docs(readme): restored readme auto-generation

ci/docs_generate.ts

@@ -0,0 +1,118 @@
+/**
+ * Docs: https://github.com/open-wc/custom-elements-manifest/tree/master/packages/to-markdown
+ */
+import fs from 'fs';
+import { customElementsManifestToMarkdown } from '@custom-elements-manifest/to-markdown';
+import MagicString from 'magic-string';
+
+const manifestFilePath = './dist/custom-elements.json';
+const tempFolderPath = './dist/docs';
+const componentsFolder = './src/components';
+const inheritedFromColumnIndex = 6;
+const attributeColumnIndex = 2;
+
+// List of components for which the 'toKebabCase' naming convention is not followed
+const componentsNameMapping: { [key: string]: string } = {
+  SbbOptGroup: 'sbb-optgroup',
+};
+
+function toKebabCase(value: string): string {
+  return value.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * Add the 'attribute' column.
+ * Removes the 'Inherited from' column.
+ * Replace 'Fields' title with 'Properties'
+ */
+function updateFieldsTable(newDocs: MagicString, sections: RegExpMatchArray[]): void {
+  const fieldsSectionIndex = sections.findIndex((sect) => sect.groups!.name === 'Fields');
+  const startIndex = sections[fieldsSectionIndex]?.index;
+  const endIndex = sections[fieldsSectionIndex + 1]?.index;
+  if (fieldsSectionIndex === -1) {
+    return;
+  }
+
+  // Create a matrix 'table[row][column]' structure for the fields table
+  const fieldsSection = newDocs.original.substring(startIndex!, endIndex);
+  const tableRows = Array.from(fieldsSection.matchAll(/^\|.*\|$/gm))
+    .map((match) => match[0])
+    .map((row) => row.split(/(?<!\\)\|/g)); // Split by not escaped '|'
+
+  // Remove the 'Inherited from' column
+  tableRows.forEach((row) => row.splice(inheritedFromColumnIndex, 1));
+
+  // Add the 'attribute' column
+  for (let i = 0; i < tableRows.length; i++) {
+    let attributeColumn: string;
+    if (i === 0) {
+      attributeColumn = tableRows[0][1].replace('Name', 'Attribute');
+    } else {
+      attributeColumn = toKebabCase(tableRows[i][1]);
+    }
+    tableRows[i].splice(attributeColumnIndex, 0, attributeColumn);
+  }
+
+  const fieldsTable = tableRows.map((cols) => cols.join('|')).join('\n');
+  newDocs.update(
+    startIndex!,
+    endIndex ?? newDocs.original.length,
+    `## Properties \n\n${fieldsTable}\n\n`,
+  );
+}
+
+function updateComponentReadme(name: string, docs: string): void {
+  const compFolder = componentsNameMapping[name] ?? toKebabCase(name);
+  const path = `${componentsFolder}/${compFolder}/readme.md`;
+  if (!fs.existsSync(path)) {
+    console.error(`Component ${name} has no readme file, please create it following the template`);
+  }
+  const newReadme = new MagicString(fs.readFileSync(path, 'utf8'));
+  let newDocs = new MagicString(docs);
+
+  // Remove the details section and commit the change
+  const detailsSectionStart = newDocs.original.match(/<details>/)?.index;
+  newDocs.remove(detailsSectionStart!, newDocs.original.length);
+  newDocs = new MagicString(newDocs.toString());
+
+  const sections = Array.from(newDocs.original.matchAll(/## (?<name>.+)/g));
+
+  // Change the generated doc here
+  newDocs.prepend('<!-- Auto Generated Below --> \n \n');
+
+  // Remove the title
+  newDocs.replace(/^# class: `.*`\n/m, '');
+
+  updateFieldsTable(newDocs, sections);
+
+  // Replace the generated doc in the readme
+  const generatedStartIndex =
+    newReadme.original.match('<!-- Auto Generated Below -->')?.index ?? newReadme.original.length;
+  newReadme.update(generatedStartIndex, newReadme.length(), newDocs.toString());
+  fs.writeFileSync(path, newReadme.toString());
+}
+
+const manifest = JSON.parse(fs.readFileSync(manifestFilePath, 'utf-8'));
+const markdown: string = customElementsManifestToMarkdown(manifest, {
+  headingOffset: -1, // Default heading is '###'
+  private: 'details', // We use 'details' cause it's the only way to remove 'protected' members from the tables
+  omitDeclarations: ['exports'],
+  omitSections: ['super-class', 'css-properties', 'css-parts', 'main-heading', 'static-fields'],
+});
+
+if (!fs.existsSync(tempFolderPath)) {
+  fs.mkdirSync(tempFolderPath, { recursive: true });
+}
+fs.writeFileSync(`${tempFolderPath}/components.md`, markdown);
+
+// Split the generated file into the single readme of each component
+const matches = Array.from(markdown.matchAll(/^# class: `(?<name>.*)`$/gm));
+
+for (let i = 0; i < matches.length; i++) {
+  const startIndex = matches[i].index!;
+  const endIndex = matches[i + 1]?.index ?? markdown.length;
+  const compName = matches[i].groups!.name;
+
+  updateComponentReadme(compName, markdown.substring(startIndex, endIndex));
+}
+console.log('Docs generated successufly');

custom-elements-manifest.config.js

@@ -1,9 +1,9 @@
 /**
- * Docs: https://custom-elements-manifest.open-wc.org/analyzer
+ * Docs: https://custom-elements-manifest.open-wc.org/analyzer/getting-started/
  */
 export default {
-  litElement: true,
-  globs: ['src/**/sbb-*.ts'],
+  litelement: true,
+  globs: ['src/**/sbb-*.(ts|tsx)'],
   exclude: ['src/**/*.spec.ts', 'src/**/*.e2e.ts', 'src/**/*.stories.tsx'],
   outdir: 'dist',
   dependencies: false,

package.json

@@ -33,11 +33,12 @@
     "build:storybook": "storybook build --quiet",
     "build:chromatic-stories": "tsx ci/chromatic-stories-generator.ts",
     "build": "npm-run-all --sequential build:components build:storybook",
-    "docs": "npm-run-all --sequential docs:manifest",
+    "docs": "npm-run-all --sequential docs:manifest docs:to-md",
     "docs:manifest": "custom-elements-manifest analyze",
+    "docs:to-md": "tsx ci/docs_generate.ts",
     "format": "prettier \"**/*\" --write --ignore-unknown",
     "generate": "tsx convenience/generate-component/index.mts",
-    "integrity": "yarn format",
+    "integrity": "npm-run-all format docs",
     "lint": "npm-run-all --sequential lint:*",
     "lint:ts": "eslint \"**/*.{ts,tsx}\"",
     "lint:js": "eslint \"**/*.js\"",

src/components/sbb-accordion/readme.md

@@ -41,25 +41,20 @@ In the following example, all the `sbb-expansion-panel-header` would be wrapped
 </sbb-accordion>
 ```
 
-<!-- Auto Generated Below -->
+<!-- Auto Generated Below --> 
+
 
+## Properties 
 
-## Properties
-
-| Property           | Attribute           | Description                                                                 | Type                                     | Default     |
-| ------------------ | ------------------- | --------------------------------------------------------------------------- | ---------------------------------------- | ----------- |
-| `disableAnimation` | `disable-animation` | Whether the animation should be disabled.                                   | `boolean`                                | `false`     |
-| `multi`            | `multi`             | Whether more than one sbb-expansion-panel can be open at the same time.     | `boolean`                                | `false`     |
-| `titleLevel`       | `title-level`       | The heading level for the sbb-expansion-panel-headers within the component. | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"` | `undefined` |
-
+| Name               | Attribute               | Privacy | Type                 | Default | Description                                                                 |
+| ------------------ | ------------------ | ------- | -------------------- | ------- | --------------------------------------------------------------------------- |
+| `titleLevel`       | `title-level`       | public  | `TitleLevel \| null` |         | The heading level for the sbb-expansion-panel-headers within the component. |
+| `disableAnimation` | `disable-animation` | public  | `boolean`            | `false` | Whether the animation should be disabled.                                   |
+| `multi`            | `multi`            | public  | `boolean`            |         | Whether more than one sbb-expansion-panel can be open at the same time.     |
 
 ## Slots
 
-| Slot        | Description                                      |
-| ----------- | ------------------------------------------------ |
-| `"unnamed"` | Use this to add one or more sbb-expansion-panel. |
-
-
-----------------------------------------------
-
+| Name      | Description                                      |
+| --------- | ------------------------------------------------ |
+| `unnamed` | Use this to add one or more sbb-expansion-panel. |
 

src/components/sbb-action-group/readme.md

@@ -113,27 +113,22 @@ The values for `align-group` and `align-self` for the various allocations are as
 |                0-0-3                |   stretch   |   Link: 'end'  |
 |                0-0-2                |   stretch   |        /       |
 
-<!-- Auto Generated Below -->
+<!-- Auto Generated Below --> 
+
 
+## Properties 
 
-## Properties
-
-| Property         | Attribute         | Description                                                                                                     | Type                                                                       | Default        |
-| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------- |
-| `alignGroup`     | `align-group`     | Set the slotted `<sbb-action-group>` children's alignment.                                                      | `"center" \| "end" \| "start" \| "stretch"`                                | `'start'`      |
-| `buttonSize`     | `button-size`     | Size of the nested sbb-button instances. This will overwrite the size attribute of nested sbb-button instances. | `"l" \| "m"`                                                               | `'l'`          |
-| `horizontalFrom` | `horizontal-from` | Overrides the behaviour of `orientation` property.                                                              | `"large" \| "medium" \| "micro" \| "small" \| "ultra" \| "wide" \| "zero"` | `'medium'`     |
-| `linkSize`       | `link-size`       | Size of the nested sbb-link instances. This will overwrite the size attribute of nested sbb-link instances.     | `"m" \| "s" \| "xs"`                                                       | `'m'`          |
-| `orientation`    | `orientation`     | Indicates the orientation of the components inside the `<sbb-action-group>`.                                    | `"horizontal" \| "vertical"`                                               | `'horizontal'` |
-
+| Name             | Attribute             | Privacy | Type                                        | Default        | Description                                                                                                         |
+| ---------------- | ---------------- | ------- | ------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `alignGroup`     | `align-group`     | public  | `'start' \| 'center' \| 'stretch' \| 'end'` | `'start'`      | Set the slotted \`\<sbb-action-group>\` children's alignment.                                                       |
+| `horizontalFrom` | `horizontal-from` | public  | `SbbHorizontalFrom \| undefined`            | `'medium'`     | Overrides the behaviour of \`orientation\` property.                                                                |
+| `orientation`    | `orientation`    | public  | `SbbOrientation`                            | `'horizontal'` | Indicates the orientation of the components inside the \`\<sbb-action-group>\`.                                     |
+| `buttonSize`     | `button-size`     | public  | `SbbButtonSize \| undefined`                | `'l'`          | Size of the nested sbb-button instances. This will overwrite the size attribute of nested&#xA;sbb-button instances. |
+| `linkSize`       | `link-size`       | public  | `SbbLinkSize \| undefined`                  | `'m'`          | Size of the nested sbb-link instances. This will overwrite the size attribute of nested&#xA;sbb-link instances.     |
 
 ## Slots
 
-| Slot        | Description                                      |
-| ----------- | ------------------------------------------------ |
-| `"unnamed"` | Slot to render the content inside the container. |
-
-
-----------------------------------------------
-
+| Name      | Description                                      |
+| --------- | ------------------------------------------------ |
+| `unnamed` | Slot to render the content inside the container. |
 

src/components/sbb-alert-group/readme.md

@@ -39,34 +39,21 @@ and therefore interrupts screen reader flow, to immediately read out the alert c
 
 **Note that with role `alert`, in some combinations of screen readers and browsers not every part of the alert is fully read.**
 
-<!-- Auto Generated Below -->
+<!-- Auto Generated Below --> 
+
 
+## Properties 
 
-## Properties
-
-| Property                  | Attribute                   | Description                                                                                                                                                                               | Type                                     | Default     |
-| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------- |
-| `accessibilityTitle`      | `accessibility-title`       | Title for this alert group which is only visible for screen reader users.                                                                                                                 | `string`                                 | `undefined` |
-| `accessibilityTitleLevel` | `accessibility-title-level` | Level of the accessibility title, will be rendered as heading tag (e.g. h2). Defaults to level 2.                                                                                         | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"` | `'2'`       |
-| `role`                    | `role`                      | The role attribute defines how to announce alerts to the user.  'status': sets aria-live to polite and aria-atomic to true. 'alert': sets aria-live to assertive and aria-atomic to true. | `string`                                 | `'status'`  |
-
-
-## Events
-
-| Event               | Description                                 | Type                               |
-| ------------------- | ------------------------------------------- | ---------------------------------- |
-| `did-dismiss-alert` | Emits when an alert was removed from DOM.   | `CustomEvent<HTMLSbbAlertElement>` |
-| `empty`             | Emits when `sbb-alert-group` becomes empty. | `CustomEvent<void>`                |
-
+| Name                      | Attribute                      | Privacy | Type                            | Default    | Description                                                                                                                                                                                           |
+| ------------------------- | ------------------------- | ------- | ------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `role`                    | `role`                    | public  | `'alert' \| 'status' \| string` | `'status'` | The role attribute defines how to announce alerts to the user.&#xA;&#xA;'status': sets aria-live to polite and aria-atomic to true.&#xA;'alert': sets aria-live to assertive and aria-atomic to true. |
+| `accessibilityTitle`      | `accessibility-title`      | public  | `string`                        |            | Title for this alert group which is only visible for screen reader users.                                                                                                                             |
+| `accessibilityTitleLevel` | `accessibility-title-level` | public  | `TitleLevel`                    | `'2'`      | Level of the accessibility title, will be rendered as heading tag (e.g. h2). Defaults to level 2.                                                                                                     |
 
 ## Slots
 
-| Slot                    | Description                                                                   |
-| ----------------------- | ----------------------------------------------------------------------------- |
-| `"accessibility-title"` | title for this sbb-alert-group which is only visible for screen reader users. |
-| `"unnamed"`             | content slot, should be filled with `sbb-alert` items.                        |
-
-
-----------------------------------------------
-
+| Name                  | Description                                                                   |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `unnamed`             | content slot, should be filled with \`sbb-alert\` items.                      |
+| `accessibility-title` | title for this sbb-alert-group which is only visible for screen reader users. |