chore: use sveld to generate types, component docs

package.json

@@ -27,7 +27,6 @@
     "@tsconfig/svelte": "^1.0.10",
     "autoprefixer": "^9.8.6",
     "carbon-components-10.23": "npm:carbon-components@10.23.1",
-    "comment-parser": "^0.7.6",
     "gh-pages": "^3.1.0",
     "husky": "^4.3.0",
     "lint-staged": "^10.5.0",
@@ -39,6 +38,7 @@
     "rollup": "^2.32.1",
     "rollup-plugin-svelte": "^6.1.0",
     "rollup-plugin-terser": "^7.0.2",
+    "sveld": "^0.1.0-rc.0",
     "svelte": "^3.29.4",
     "svelte-check": "^1.1.6",
     "svelte-loader": "^2.13.6",

rollup.config.js

@@ -3,7 +3,7 @@ import pkg from "./package.json";
 import resolve from "@rollup/plugin-node-resolve";
 import commonjs from "@rollup/plugin-commonjs";
 import svelte from "rollup-plugin-svelte";
-import generateDocs from "./scripts/rollup/plugin-generate-docs";
+import sveld from "sveld";
 
 export default ["es", "umd"].map((format) => {
   const UMD = format === "umd";
@@ -22,9 +22,20 @@ export default ["es", "umd"].map((format) => {
       resolve(),
       commonjs(),
       UMD && terser(),
-
+      UMD &&
-      // TODO: replace
+        sveld({
-      // !UMD && generateDocs(),
+          markdown: true,
+          markdownOptions: {
+            onAppend: (type, document, components) => {
+              if (type === "h1")
+                document.append(
+                  "quote",
+                  `${components.size} components exported from ${pkg.name}@${pkg.version}.`
+                );
+            },
+          },
+          json: true,
+        }),
     ],
   };
 });

scripts/rollup/generate-index.js

@@ -1,117 +0,0 @@
-const toLink = (text) => text.toLowerCase().replace(/\s+/g, "-");
-
-const toMdLink = (text) => `[${text}](#${toLink(text)})`;
-
-const formatType = (type) => `<code>${type.replace(/\|/g, "&#124;")}</code>`;
-
-const escapeHtml = (text) => text.replace(/\</g, "&lt;").replace(/\>/g, "&gt;");
-
-const HEADER_PROPS =
-  "| Prop name | Type | Default value | Description |\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.sort().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 ? "`" + prop.value + "`" : "--"
-        } | ${escapeHtml(prop.description).replace(/\n/g, ". ")}. |\n`;
-      });
-    } else {
-      code += "No exported props.\n\n";
-    }
-
-    code += "### Slots\n\n";
-
-    if (slots.size > 0) {
-      if (slots.get("default")) {
-        code += "- **default**: `<div>...</div>`\n";
-      }
-
-      slots.forEach((slot, name) => {
-        if (slot.default) return;
-        code += `- **"${name}"**: \`<div name="${name}" ${slot.attributes
-          .map((attr) => `let:${attr.name}`)
-          .join(" ")}>...</div>\`\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-public-api.js

@@ -1,29 +0,0 @@
-/**
- * Use library component metadata to generate component documentation in JSON 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 generatePublicAPI(components, groups, pkg) {
-  const code = {
-    version: pkg.version,
-    components: {},
-  };
-
-  components.forEach((component, moduleName) => {
-    const props = Array.from(component.component.exported_props);
-    const slots = Array.from(component.component.slots);
-    const forwarded_events = Array.from(component.component.forwarded_events);
-    const dispatched_events = Array.from(component.component.dispatched_events);
-
-    code.components[moduleName] = {
-      moduleName,
-      props,
-      slots,
-      forwarded_events,
-      dispatched_events,
-    };
-  });
-
-  return { code };
-}

scripts/rollup/generate-types.js

@@ -1,82 +0,0 @@
-/**
- * Use library component metadata to generate TypeScript definitions.
- * @param {Map<string, { component: { exported_props: Map<string, any>; slots: Map<string, any>; } typedefs: {name: string; type: string;}[] }>} components
- * @param {{name: string; version: string; homepage: string;}} pkg
- */
-export function generateTypes(components, pkg) {
-  let code = `
-    // Type definitions for ${pkg.name} ${pkg.version}
-    // Project: ${pkg.homepage}
-
-    export class CarbonSvelteComponent {
-      $$prop_def: {};
-
-      $$slot_def: {};
-
-      // stub all \`on:{eventname}\` directives
-      $on(eventname: string, handler: (e: Event) => any): () => void;
-    }\n\n`;
-
-  components.forEach((component, moduleName) => {
-    let $$prop_def = "";
-    let $$slot_def = "";
-
-    component.typedefs.forEach(({ name, type }) => {
-      const typedef = type.startsWith("{")
-        ? `interface ${name} ${type}`
-        : `type ${name} = ${type};`;
-      code += typedef + "\n\n";
-    });
-
-    component.component.exported_props.forEach((prop, name) => {
-      $$prop_def += "/**\n";
-
-      prop.description.split("\n").forEach((line) => {
-        $$prop_def += "* " + line + "\n";
-      });
-
-      if (prop.kind === "const") {
-        $$prop_def += "* @constant\n";
-      }
-
-      if (prop.value !== undefined) {
-        $$prop_def += "* @default " + prop.value + "\n";
-      }
-
-      $$prop_def += "*/\n";
-
-      let value = "undefined";
-
-      if (prop.type) {
-        value = prop.type;
-      }
-
-      $$prop_def += name + "?: " + value + ";" + "\n\n";
-    });
-
-    component.component.slots.forEach((slot, slot_name) => {
-      let value = "";
-
-      slot.attributes.forEach((attribute) => {
-        if (attribute.name !== "name") {
-          value += attribute.name + ": any;";
-        }
-      });
-
-      if (slot.default) {
-        $$slot_def += "default: {" + value + "};" + "\n";
-      } else {
-        $$slot_def += JSON.stringify(slot_name) + ": {" + value + "};" + "\n";
-      }
-    });
-
-    code += `
-      export class ${moduleName} extends CarbonSvelteComponent {
-        ${!!$$prop_def ? "$$prop_def: {" + $$prop_def + "}\n" : ""}
-        
-        ${!!$$slot_def ? "$$slot_def: {" + $$slot_def + "}\n" : ""}
-      }\n\n`;
-  });
-
-  return { code };
-}

scripts/rollup/parse-component.js

@@ -1,137 +0,0 @@
-import { parse, walk } from "svelte/compiler";
-import commentParser from "comment-parser";
-
-/**
- * Parse Svelte component for metadata using the Svelte compiler
- * @param {string} source - raw Svelte component code
- * @param {{ component: string; onTypeDef: (tag: { type: "typedef"; tag: string; name: string; }) => void;}} hooks
- */
-export function parseComponent(source, hooks) {
-  const exported_props = new Map();
-  const slots = new Map();
-  const forwarded_events = new Map();
-  const dispatched_events = new Map();
-
-  let hasDispatchedEvents = false;
-  let dispatcher_name = null;
-  let callee = [];
-
-  walk(parse(source), {
-    enter(node, parent, prop) {
-      switch (node.type) {
-        case "CallExpression":
-          if (hasDispatchedEvents) {
-            if (node.callee.name === "createEventDispatcher") {
-              dispatcher_name = parent.id.name;
-            }
-          }
-          break;
-        case "Identifier":
-          if (node.name === "createEventDispatcher") {
-            hasDispatchedEvents = true;
-          }
-
-          if (prop === "callee") {
-            callee.push({ name: node.name, parent });
-          }
-          break;
-        case "ExportNamedDeclaration":
-          const { id, init } = node.declaration.declarations[0];
-
-          let value = undefined;
-          let type = undefined;
-          let kind = node.declaration.kind;
-          let description = null;
-
-          if (init != null) {
-            if (
-              init.type === "ObjectExpression" ||
-              init.type === "ArrayExpression"
-            ) {
-              value = source.slice(init.start, init.end).replace(/\n/g, " ");
-              type = value;
-            } else {
-              value = init.raw;
-            }
-          }
-
-          const general_comments = commentParser(source);
-
-          general_comments.forEach((comment) => {
-            comment.tags.forEach((tag) => {
-              if (tag.tag === "typedef") hooks.onTypeDef(tag);
-            });
-          });
-
-          if (node.leadingComments) {
-            const comment = commentParser(
-              "/*" + node.leadingComments[0].value + "*/"
-            );
-
-            description = comment[0].description;
-
-            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, { kind, value, type, description });
-          break;
-        case "Slot":
-          let slot_name = null;
-
-          const slot_attributes = [];
-
-          node.attributes.forEach((attribute) => {
-            if (attribute.name === "name") {
-              slot_name = attribute.value[0].raw;
-            } else {
-              slot_attributes.push(attribute);
-            }
-          });
-
-          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":
-          if (node.expression == null) {
-            forwarded_events.set(node.name, node);
-          }
-          break;
-      }
-    },
-  });
-
-  if (hasDispatchedEvents) {
-    callee.forEach((node) => {
-      if (node.name === dispatcher_name) {
-        const [name, detail] = node.parent.arguments;
-
-        if (name.value !== undefined) {
-          dispatched_events.set(name.value, {
-            detail: detail ? source.slice(detail.start, detail.end) : undefined,
-          });
-        }
-      }
-    });
-  }
-
-  return {
-    exported_props,
-    slots,
-    forwarded_events,
-    dispatched_events,
-  };
-}

scripts/rollup/plugin-generate-docs.js

@@ -1,84 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { promisify } from "util";
-import pkg from "../../package.json";
-import { format } from "prettier";
-import { parseComponent } from "./parse-component";
-import { generateTypes } from "./generate-types";
-import { generateIndex } from "./generate-index";
-import { generatePublicAPI } from "./generate-public-api";
-
-const writeFile = promisify(fs.writeFile);
-
-/**
- * Rollup plugin to generate library TypeScript definitions and documentation.
- */
-function pluginGenerateDocs() {
-  const groups = new Map();
-  const components = new Map();
-
-  return {
-    name: "generate-docs",
-    async generateBundle(options, bundle) {
-      for (const filename in bundle) {
-        const chunkOrAsset = bundle[filename];
-
-        if (chunkOrAsset.type !== "asset" && chunkOrAsset.isEntry) {
-          chunkOrAsset.exports.forEach((exportee) => {
-            components.set(exportee, {});
-          });
-
-          const shared_types = new Set();
-
-          Object.keys(chunkOrAsset.modules)
-            .sort()
-            .forEach(async (filename) => {
-              const { dir, ext, name } = path.parse(filename);
-              const moduleName = name.replace(/\./g, "");
-
-              if (ext === ".svelte" && components.has(moduleName)) {
-                const group = dir.split("src/").pop().split("/")[0];
-
-                if (groups.has(group)) {
-                  groups.set(group, [...groups.get(group), moduleName]);
-                } else {
-                  groups.set(group, [moduleName]);
-                }
-
-                const typedefs = [];
-                const source = fs.readFileSync(filename, "utf-8");
-                const component = parseComponent(source, {
-                  component: moduleName,
-                  onTypeDef: (tag) => {
-                    if (shared_types.has(tag.name)) return;
-                    shared_types.add(tag.name);
-                    typedefs.push(tag);
-                  },
-                });
-
-                components.set(moduleName, { typedefs, component });
-              }
-            });
-        }
-      }
-    },
-    async writeBundle() {
-      const { code: types } = generateTypes(components, pkg);
-      await writeFile(pkg.types, format(types, { parser: "typescript" }));
-
-      const { code: index } = generateIndex(components, groups, pkg);
-      await writeFile(
-        "./COMPONENT_INDEX.md",
-        format(index, { parser: "markdown" })
-      );
-
-      const { code: json } = generatePublicAPI(components, groups, pkg);
-      await writeFile(
-        "./docs/src/PUBLIC_API.json",
-        JSON.stringify(json, null, 2)
-      );
-    },
-  };
-}
-
-export default pluginGenerateDocs;

src/Accordion/AccordionItem.svelte

@@ -39,7 +39,7 @@
   class:bx--accordion__item--active="{open}"
   class:bx--accordion__item--disabled="{disabled}"
   {...$$restProps}
-  class="bx--accordion__item--${animation} {$$restProps.class}"
+  class="bx--accordion__item--{animation} {$$restProps.class}"
   on:animationend
   on:animationend="{() => {
     animation = undefined;

src/Button/Button.svelte

@@ -1,4 +1,8 @@
 <script>
+  /**
+   * @slot {{ props?: { role: "button"; type?: string; tabindex: string; disabled: boolean; href?: string; class: string; [key: string]: any; } }}
+   */
+
   /**
    * Specify the kind of button
    * @type {"primary" | "secondary" | "tertiary" | "ghost" | "danger" | "danger-tertiary" | "danger-ghost"}

src/Grid/Row.svelte

@@ -1,6 +1,6 @@
 <script>
   /**
-   * @slot {{ props?: { class: string; } }}
+   * @slot {{ props?: { class: string; [key: string]: any; } }}
    */
 
   /**

types/Button/Button.d.ts

@@ -86,7 +86,17 @@ export interface ButtonProps {
 export default class Button {
   $$prop_def: ButtonProps;
   $$slot_def: {
-    default: { props: undefined };
+    default: {
+      props?: {
+        role: "button";
+        type?: string;
+        tabindex: string;
+        disabled: boolean;
+        href?: string;
+        class: string;
+        [key: string]: any;
+      };
+    };
   };
 
   $on(eventname: "click", cb: (event: WindowEventMap["click"]) => void): () => void;

types/Grid/Row.d.ts

@@ -42,7 +42,7 @@ export interface RowProps {
 export default class Row {
   $$prop_def: RowProps;
   $$slot_def: {
-    default: { props?: { class: string } };
+    default: { props?: { class: string; [key: string]: any } };
   };
 
   $on(eventname: string, cb: (event: Event) => void): () => void;

yarn.lock

@@ -291,6 +291,11 @@ asynckit@^0.4.0:
   resolved "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz#c79ed97f7f34cb8f2ba1bc9790bcc366474b4b79"
   integrity sha1-x57Zf380y48robyXkLzDZkdLS3k=
 
+at-least-node@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz#602cd4b46e844ad4effc92a8011a3c46e0238dc2"
+  integrity sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==
+
 autoprefixer@^9.8.6:
   version "9.8.6"
   resolved "https://registry.npmjs.org/autoprefixer/-/autoprefixer-9.8.6.tgz#3b73594ca1bf9266320c5acf1588d74dea74210f"
@@ -972,6 +977,16 @@ fs-extra@^8.1.0:
     jsonfile "^4.0.0"
     universalify "^0.1.0"
 
+fs-extra@^9.0.1:
+  version "9.0.1"
+  resolved "https://registry.npmjs.org/fs-extra/-/fs-extra-9.0.1.tgz#910da0062437ba4c39fedd863f1675ccfefcb9fc"
+  integrity sha512-h2iAoN838FqAFJY2/qVpzFXy+EBxfVE220PalAqQLDVsFOHLJrZvut5puAbCdNv6WJk+B8ihI+k0c7JK5erwqQ==
+  dependencies:
+    at-least-node "^1.0.0"
+    graceful-fs "^4.2.0"
+    jsonfile "^6.0.1"
+    universalify "^1.0.0"
+
 fs.realpath@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f"
@@ -1432,6 +1447,15 @@ jsonfile@^4.0.0:
   optionalDependencies:
     graceful-fs "^4.1.6"
 
+jsonfile@^6.0.1:
+  version "6.1.0"
+  resolved "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz#bc55b2634793c679ec6403094eb13698a6ec0aae"
+  integrity sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==
+  dependencies:
+    universalify "^2.0.0"
+  optionalDependencies:
+    graceful-fs "^4.1.6"
+
 jsprim@^1.2.2:
   version "1.4.1"
   resolved "https://registry.npmjs.org/jsprim/-/jsprim-1.4.1.tgz#313e66bc1e5cc06e438bc1b7499c2e5c56acb6a2"
@@ -2704,6 +2728,15 @@ supports-color@^7.0.0, supports-color@^7.1.0:
   dependencies:
     has-flag "^4.0.0"
 
+sveld@^0.1.0-rc.0:
+  version "0.1.0-rc.0"
+  resolved "https://registry.npmjs.org/sveld/-/sveld-0.1.0-rc.0.tgz#3296df459116984f299bdd50bc8745e3cd48e66a"
+  integrity sha512-z4SkRD8cVCOlsdd7UTMDRuG2TNDRHSGN201Fok/aTPoT0PjuXI4lcUJqGbJdxX4KBebenj8ph7y/UV8G0FqA0A==
+  dependencies:
+    comment-parser "^0.7.6"
+    fs-extra "^9.0.1"
+    prettier "^2.1.2"
+
 svelte-check@^1.1.6:
   version "1.1.6"
   resolved "https://registry.npmjs.org/svelte-check/-/svelte-check-1.1.6.tgz#705fea71a757511f47894cdfa1ffab6e5c5cab4d"
@@ -2835,6 +2868,16 @@ universalify@^0.1.0:
   resolved "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz#b646f69be3942dabcecc9d6639c80dc105efaa66"
   integrity sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==
 
+universalify@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.npmjs.org/universalify/-/universalify-1.0.0.tgz#b61a1da173e8435b2fe3c67d29b9adf8594bd16d"
+  integrity sha512-rb6X1W158d7pRQBg5gkR8uPaSfiids68LTJQYOtEUhoJUWBdaQHsuT/EUduxXYxcrt4r5PJ4fuHW1MHT6p0qug==
+
+universalify@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz#75a4984efedc4b08975c5aeb73f530d02df25717"
+  integrity sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==
+
 uri-js@^4.2.2:
   version "4.2.2"
   resolved "https://registry.npmjs.org/uri-js/-/uri-js-4.2.2.tgz#94c540e1ff772956e2299507c010aea6c8838eb0"