Rework how pattern lab loads UI-kits

[JosefBredereck]

Currently, pattern lab is expecting UI-kits to have a fixed layout and file structure to be loaded correctly.

In my humble opinion, this leads to the point that community driven UI-kits are very rare and the hurdle for creating a new one is already big on the starting point.

Therefore, pattern lab has to introduce the possibility to configure entry points for UI-kits so that we only require a configuration file.
The configuration file should include:

• where is the main HTML file located.
• which static content needs to be loaded by pattern lab (images, SVGs, JSON)
• where are the JS files located
• where are the CSS files located

Moreover, we require the main HTML file to be parsable with handlebars, which is not a very great approach and could lead to further issues and could be resolved in other ways

[JosefBredereck]

I started to analyzed what currently is happening to have a more profound understanding on how to proceed and what to change.

Foremost, all UI-kits need to be configured in the patternlab-config.json where it is possible to add some configurations.

{
  "uikits": [
    {
      "name": "uikit-workshop",
      "package": "@pattern-lab/uikit-workshop",
      "outputDir": "",
      "enabled": true,
      "excludedPatternStates": [],
      "excludedTags": []
    }
  ]
}

With this config, it will enter loaduikits where we extend the config with some additional options.

The first thing that comes into view is the part where we try to resolve the UI-kit by name. This is now deprecated for over 2 years and can be removed entirely.

patternlab-node/packages/core/src/lib/loaduikits.js

Lines 43 to 47 in 6dd472f

	// For backwards compatibility, name to package calculation is:
	// 1. name -> name
	// 2. name -> uikit-name
	// 3. name -> @pattern-lab/name
	// 4. name -> @pattern-lab/uikit-name

Afterward, the config gets extended with some info from patternlab-config.

patternlab-node/packages/core/src/lib/loaduikits.js

Lines 78 to 81 in 6dd472f

	patternlab.uikits[uikitConfig.name] = {
	name: uikitConfig.name,
	package: uikitConfig.package,
	modulePath: uikitLocation,

And here is the first point where the configuration can be adjusted.
"general-header", "general-footer", "patternSection", "patternSectionSubgroup" and "viewall" must be provided from the user via patternlab-config where the file structure of the UI-kit needs to be known. The better approach would be to have the UI-kit package providing the required configuration so that all file locations are known. Pattern lab could provide a JSON Schema for that part.

Moreover, where the style guide files are located needs to be known by the user too. It would be better to configure where the JavaScript, CSS, and HTML is located directly in the UI-kits Schema. And that the files will be copied to the correct place and referenced by pattern lab automatically. In that case, the UI-kit does not need a general header or footer because pattern lab knows what to inject.

{
  "paths": {
    "source": {
      [...]
      "styleguide": "dist/"
      [...]
    }
  }
}

In Twig also, the namespace needs to be configured:

{
  "namespaces": [
    {
      "id": "uikit",
      "recursive": true,
      "paths": ["./node_modules/@pattern-lab/uikit-workshop/views-twig"]
    }
  ]
}

After all the data is loaded and the UI gets build, the different parts of pattern lab and UI-kit get put together.

patternlab-node/packages/core/src/lib/compose.js

Line 76 in 6dd472f

//re-rendering the headHTML each time allows pattern-specific data to influence the head of the pattern

At last, the UI-kit specific files will be copied into the public folder on the specified place of outputDir. Where the whole style guide gets copied as a whole folder and the different pattern lab generated files get added to the folder.

patternlab-node/packages/core/src/lib/copier.js

Line 76 in 6dd472f

copyPromises.push(

patternlab-node/packages/core/src/lib/copier.js

Line 88 in 6dd472f

// copy the styleguide

patternlab-node/packages/core/src/lib/copier.js

Line 99 in 6dd472f

// copy the favicon

At this point, the next issue occurs. When generating the pattern lab frontend, the file structure could change at some point. With the current approach, every UI-kit needs to be adjusted because the UI-kit delivers the index.html and must know where the final files will be located so that it references the correct static files.

Finally, there is another point that I could not genuinely understand for now. In the index.html file is a script tag which contains handlebars code <script type="text/x-handlebars-template" class="pl-js-panel-template-base">.
I assume that this tag will be used to render the panel inside the view all pages and in the panel viewer. At this point, I would like to investigate if it is possible to eliminate the usage of another external renderer (handlebars) when the structure of the panel is clear and a web component could be used in both instances.

[JosefBredereck]

Pattern Lab generates the file patternlab-data.js that gets consumed by pattern lab's UI-kit. Where only the following types are expected, but much more is generated and added to the file.

Maybe we can greatly reduce it to the relevant content so that every UI-kit knows which data to expect.

interface UiKitConfig {
  defaultPattern: string;
  defaultShowPatternInfo: false;
  patternExtension: string;
  defaultPatternInfoPanelCode: false;
  noIndexHtmlremoval: false;
  ishFontSize: number;
  ishMinimum: number;
  ishMaximum: number;
  ishViewportRange: {
    s: [number, number];
    m: [number, number];
    l: [number, number];
  };
  outputFileSuffixes: {
    rendered: string;
    rawTemplate: string;
    markupOnly: string;
  };
  theme: {
    color: string;
    density: string;
    layout: string;
    noViewAll: false;
    logo: {
      srcLight: string;
      srcDark: string;
      url: string;
      width: number;
      height: number;
      text: string;
    };
  };
}

// could maybe moved to config where it is located anyway
interface UikitControls {
  ishControlsHide: {
    s: boolean;
    m: boolean;
    l: boolean;
    full: boolean;
    random: boolean;
    disco: boolean;
    hay: boolean;
    mqs: boolean;
    find: boolean;
    "views-all": boolean;
    "views-annotations": boolean;
    "views-code": boolean;
    "views-new": boolean;
    "tools-all": boolean;
    "tools-docs": boolean;
  };
}

Navigation Structure Config:

interface UiKitNavPatternItem {
  patternPartial: string;
  patternName: string;
  patternState: string;
  patternPath: string;
  name: string;
  order: number;
  variantOrder: number;
}

interface UiKitNavSubGroup {
  patternSubgroupLC: string; // lowercase group name
  patternSubgroupUC: string; // upper case Group name
  patternSubgroup: string; // group raw
  patternSubgroupDash: string; // group name lower case with dashes instead of spaces
  patternSubgroupItems: UiKitNavPatternItem[];
}

interface UiKitNavItems {
  patternGroups: {
    patternGroupLC: string; // lowercase group name
    patternGroupUC: string; // upper case Group name
    patternGroup: string; // group raw
    patternGroupDash: string; // group name lower case with dashes instead of spaces
    patternGroupItems: UiKitNavSubGroup[];
  }[];
}

Paths Structure:

// group.subgroup.pattern
type UiKitPaths = Record<string, Record<string, string>>;

Plugin Structure:

interface UiKitPlugin {
  name: string;
  templates: string[];
  stylesheets: string[];
  javascripts: string[];
  onready: string;
  callback: string;
  // [...] plugin specific configs
}

Final data that gets combined into the window object.

declare global {
  interface Window {
    config: UiKitConfig;
    ishControls: UikitControls;
    navItems: UiKitNavItems;
    patternPaths: UiKitPaths; // for baisc paths resolution
    viewAllPaths: UiKitPaths; // for view all paths resolution
    plugins: UiKitPlugin[];
  }
}

[JosefBredereck]

An alternate approach to the configuration of how the data needs to be loaded and where to find it:
The UI-kit is a closed application, where pattern lab just injects the content required to preview the frontend. This includes the config above and the folder with all the patterns in it.
The only info required is, where to find the index.html to inject CSS-based configs and the pattern-lab-data.js.