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,10 +40,16 @@ export function parseComponent(source, hooks) {
 
           let value = undefined;
           let type = undefined;
+          let kind = node.declaration.kind;
           let description = null;
 
           if (init != null) {
-            value = init.raw;
+            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,9 +116,11 @@ export function parseComponent(source, hooks) {
       if (node.name === dispatcher_name) {
         const [name, detail] = node.parent.arguments;
 
-        dispatched_events.set(name.raw, {
-          detail: detail ? source.slice(detail.start, detail.end) : undefined,
-        });
+        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" })
+      );
     },
   };
 }