build: add script to generate component index

- move typedefs for correct type parsing

scripts/rollup/generate-index.js

@@ -0,0 +1,110 @@
+const toLink = (text) => text.toLowerCase().replace(/\s+/g, "-");
+
+const toMdLink = (text) => `[${text}](#${toLink(text)})`;
+
+const formatType = (type) => `<code>${type.replace(/\|/g, "&#124;")}</code>`;
+
+const HEADER_PROPS = "| Prop name | Type | Default value |\n| :- | :- | :- |\n";
+
+/**
+ * Use library component metadata to generate component documentation in markdown format.
+ * @param {Map<string, { component: { exported_props: Map<string, any>; slots: Map<string, any>; } typedefs: {name: string; type: string;}[] }>} components
+ * @param {Map<string, string[]>} groups
+ * @param {{name: string; version: string; homepage: string;}} pkg
+ */
+export function generateIndex(components, groups, pkg) {
+  let code = `# Component Index\n\n`;
+
+  code += `> ${components.size} components exported from ${pkg.name} ${pkg.version}\n\n`;
+
+  groups.forEach((group, component_group) => {
+    if (group.length > 1) {
+      code += `- ${component_group}\n`;
+      group.forEach((component) => {
+        code += `  - ${toMdLink(component)}\n`;
+      });
+    } else {
+      code += `- ${toMdLink(component_group)}\n`;
+    }
+  });
+
+  code += "---\n";
+
+  components.forEach((component, moduleName) => {
+    const {
+      typedefs,
+      component: { exported_props, slots, forwarded_events, dispatched_events },
+    } = component;
+
+    code += `## ${moduleName}\n\n`;
+    code += `### Import path\n\n`;
+    code += `\`\`\`js\nimport { ${moduleName} } from "${pkg.name}";\n\`\`\`\n\n`;
+
+    code += "### Props\n\n";
+
+    if (exported_props.size > 0) {
+      if (typedefs.length > 0) {
+        let definitions = "";
+
+        typedefs.forEach(({ name, type }) => {
+          const typedef = type.startsWith("{")
+            ? `interface ${name} ${type}`
+            : `type ${name} = ${type};`;
+
+          definitions += `${typedef}\n\n`;
+        });
+
+        code += `\`\`\`ts\n// \`${moduleName}\` type definitions\n\n${definitions}\n\`\`\`\n\n`;
+      }
+
+      code += HEADER_PROPS;
+
+      exported_props.forEach((prop, name) => {
+        code += `| ${name}${
+          prop.kind === "const" ? " (`constant`)" : ""
+        } | ${formatType(prop.type)} | ${prop.value || "--"}|\n`;
+      });
+    } else {
+      code += "No exported props.\n\n";
+    }
+
+    code += "### Slots\n\n";
+
+    if (slots.size > 0) {
+      if (slots.get("default")) {
+        code += "- `<slot>...</slot>`\n";
+      } else {
+        slots.forEach((slot, name) => {
+          if (slot.default) return;
+          code += `- \`<slot name="${name}">...</slot>\`\n`;
+        });
+      }
+    } else {
+      code += "No slots.\n\n";
+    }
+
+    code += "### Forwarded events\n\n";
+
+    if (forwarded_events.size > 0) {
+      forwarded_events.forEach((event, name) => {
+        code += `- \`on:${name}\`\n`;
+      });
+    } else {
+      code += "No forwarded events.\n\n";
+    }
+
+    code += "### Dispatched events\n\n";
+
+    if (dispatched_events.size > 0) {
+      dispatched_events.forEach((event, name) => {
+        code += `- \`on:${name}\`\n`;
+      });
+    } else {
+      code += "No dispatched events.\n\n";
+    }
+
+    code += "---\n";
+  });
+
+  return { code };
+}

scripts/rollup/generate-types.js

@@ -8,7 +8,7 @@ export function generateTypes(components, pkg) {
     // Type definitions for ${pkg.name} ${pkg.version}
     // Project: ${pkg.homepage}
 
-    class SvelteComponent {
+    export class CarbonSvelteComponent {
       $$prop_def: {};
 
       $$slot_def: {};
@@ -35,6 +35,10 @@ export function generateTypes(components, pkg) {
         $$prop_def += "* " + line + "\n";
       });
 
+      if (prop.kind === "const") {
+        $$prop_def += "* @constant\n";
+      }
+
       if (prop.value !== undefined) {
         $$prop_def += "* @default " + prop.value + "\n";
       }
@@ -67,7 +71,7 @@ export function generateTypes(components, pkg) {
     });
 
     code += `
-      export class ${moduleName} extends SvelteComponent {
+      export class ${moduleName} extends CarbonSvelteComponent {
         ${!!$$prop_def ? "$$prop_def: {" + $$prop_def + "}\n" : ""}
         
         ${!!$$slot_def ? "$$slot_def: {" + $$slot_def + "}\n" : ""}

scripts/rollup/parse-component.js

@@ -40,11 +40,17 @@ export function parseComponent(source, hooks) {
 
           let value = undefined;
           let type = undefined;
+          let kind = node.declaration.kind;
           let description = null;
 
           if (init != null) {
+            if (init.type === "ObjectExpression") {
+              value = source.slice(init.start, init.end).replace(/\n/g, " ");
+              type = value;
+            } else {
               value = init.raw;
             }
+          }
 
           const general_comments = commentParser(source);
 
@@ -60,14 +66,15 @@ export function parseComponent(source, hooks) {
             );
 
             description = comment[0].description;
-            type = comment[0].tags[0].type;
+
+            type = comment[0].tags[comment[0].tags.length - 1].type;
           } else {
             throw Error(
               `[${hooks.component}] property \`${id.name}\` should be annotated.`
             );
           }
 
-          exported_props.set(id.name, { value, type, description });
+          exported_props.set(id.name, { kind, value, type, description });
           break;
         case "Slot":
           let slot_name = null;
@@ -82,10 +89,17 @@ export function parseComponent(source, hooks) {
             }
           });
 
+          let default_value = "";
+
+          node.children.forEach((child) => {
+            default_value += `${source.slice(child.start, child.end)}\n`;
+          });
+
           slots.set(slot_name == null ? "default" : slot_name, {
             attributes: node.attributes,
             children: node.children,
             default: slot_name == null,
+            default_value,
           });
           break;
         case "EventHandler":
@@ -102,10 +116,12 @@ export function parseComponent(source, hooks) {
       if (node.name === dispatcher_name) {
         const [name, detail] = node.parent.arguments;
 
-        dispatched_events.set(name.raw, {
+        if (name.value !== undefined) {
+          dispatched_events.set(name.value, {
             detail: detail ? source.slice(detail.start, detail.end) : undefined,
           });
         }
+      }
     });
   }
 

scripts/rollup/plugin-generate-docs.js

@@ -4,6 +4,7 @@ import pkg from "../../package.json";
 import { format } from "prettier";
 import { parseComponent } from "./parse-component";
 import { generateTypes } from "./generate-types";
+import { generateIndex } from "./generate-index";
 
 /**
  * Rollup plugin to generate library TypeScript definitions and documentation.
@@ -59,9 +60,13 @@ function pluginGenerateDocs() {
     },
     writeBundle() {
       const { code: types } = generateTypes(components, pkg);
-      const definitions = format(types, { parser: "typescript" });
+      fs.writeFileSync(pkg.types, format(types, { parser: "typescript" }));
 
-      fs.writeFileSync(pkg.types, definitions);
+      const { code: index } = generateIndex(components, groups, pkg);
+      fs.writeFileSync(
+        "./COMPONENT_INDEX.md",
+        format(index, { parser: "markdown" })
+      );
     },
   };
 }

src/ComboBox/ComboBox.svelte

@@ -1,8 +1,4 @@
 <script>
-  /**
-   * @typedef {{ id: string; text: string; }} ComboBoxItem
-   */
-
   /**
    * Set the combobox items
    * @type {ComboBoxItem[]} [items=[]]
@@ -111,6 +107,10 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {{ id: string; text: string; }} ComboBoxItem
+   */
+
   import { createEventDispatcher, afterUpdate } from "svelte";
   import WarningFilled16 from "carbon-icons-svelte/lib/WarningFilled16";
   import {

src/Dropdown/Dropdown.svelte

@@ -1,10 +1,4 @@
 <script>
-  /**
-   * @typedef {string} DropdownItemId
-   * @typedef {string} DropdownItemText
-   * @typedef {{ id: DropdownItemId; text: DropdownItemText; }} DropdownItem
-   */
-
   /**
    * Set the dropdown items
    * @type {DropdownItem[]} [items=[]]
@@ -113,6 +107,12 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {string} DropdownItemId
+   * @typedef {string} DropdownItemText
+   * @typedef {{ id: DropdownItemId; text: DropdownItemText; }} DropdownItem
+   */
+
   import { setContext } from "svelte";
   import WarningFilled16 from "carbon-icons-svelte/lib/WarningFilled16";
   import {

src/FileUploader/FileUploaderDropContainer.svelte

@@ -1,8 +1,4 @@
 <script>
-  /**
-   * @typedef {string[]} Files
-   */
-
   /**
    * Specify the accepted file types
    * @type {string[]} [accept=[]]
@@ -64,6 +60,10 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {string[]} Files
+   */
+
   import { createEventDispatcher } from "svelte";
 
   const dispatch = createEventDispatcher();

src/Grid/Column.svelte

@@ -30,12 +30,6 @@
    */
   export let aspectRatio = undefined;
 
-  /**
-   * @typedef {boolean | number} ColumnSize
-   * @typedef {{span?: ColumnSize; offset: number;}} ColumnSizeDescriptor
-   * @typedef {ColumnSize | ColumnSizeDescriptor} ColumnBreakpoint
-   */
-
   /**
    * Set the small breakpoint
    * @type {ColumnBreakpoint} [sm]
@@ -66,6 +60,12 @@
    */
   export let max = undefined;
 
+  /**
+   * @typedef {boolean | number} ColumnSize
+   * @typedef {{span?: ColumnSize; offset: number;}} ColumnSizeDescriptor
+   * @typedef {ColumnSize | ColumnSizeDescriptor} ColumnBreakpoint
+   */
+
   /**
    * Column breakpoints
    * @constant

src/ListBox/ListBoxField.svelte

@@ -17,10 +17,6 @@
    */
   export let tabindex = "-1";
 
-  /**
-   * @typedef {"close" | "open"} ListBoxFieldTranslationId
-   */
-
   /**
    * Default translation ids
    * @constant
@@ -46,6 +42,10 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {"close" | "open"} ListBoxFieldTranslationId
+   */
+
   import { getContext } from "svelte";
 
   const defaultTranslations = {

src/ListBox/ListBoxMenuIcon.svelte

@@ -12,16 +12,16 @@
    */
   export const translationIds = { close: "close", open: "open" };
 
-  /**
-   * @typedef {"close" | "open"} ListBoxMenuIconTranslationId
-   */
-
   /**
    * Override the default translation ids
    * @type {(id: ListBoxMenuIconTranslationId) => string} [translateWithId = (id) => string]
    */
   export let translateWithId = (id) => defaultTranslations[id];
 
+  /**
+   * @typedef {"close" | "open"} ListBoxMenuIconTranslationId
+   */
+
   import ChevronDown16 from "carbon-icons-svelte/lib/ChevronDown16";
 
   const defaultTranslations = {

src/ListBox/ListBoxSelection.svelte

@@ -11,10 +11,6 @@
    */
   export let disabled = false;
 
-  /**
-   * @typedef {"clearAll" | "clearSelection"} ListBoxSelectionTranslationId
-   */
-
   /**
    * Default translation ids
    * @constant
@@ -37,6 +33,10 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {"clearAll" | "clearSelection"} ListBoxSelectionTranslationId
+   */
+
   import { createEventDispatcher, getContext } from "svelte";
   import Close16 from "carbon-icons-svelte/lib/Close16";
 

src/NumberInput/NumberInput.svelte

@@ -95,10 +95,6 @@
    */
   export let hideLabel = false;
 
-  /**
-   * @typedef {"increment" | "decrement"} NumberInputTranslationId
-   */
-
   /**
    * Override the default translation ids
    * @type {(id: NumberInputTranslationId) => string} [translateWithId = (id: NumberInputTranslationId) => string]
@@ -133,6 +129,10 @@
    */
   export let ref = null;
 
+  /**
+   * @typedef {"increment" | "decrement"} NumberInputTranslationId
+   */
+
   import { createEventDispatcher, afterUpdate } from "svelte";
   import CaretDownGlyph from "carbon-icons-svelte/lib/CaretDownGlyph";
   import CaretUpGlyph from "carbon-icons-svelte/lib/CaretUpGlyph";