use svelte compiler to generate TypeScript definitions, documentation

[metonym]

This PR adds a build step that uses Rollup and the Svelte compiler to generate TypeScript definitions. The exported modules from the entry file are used to document the public API. Additional, human-readable documentation can be generated as well.

Approach

The Svelte compiler is used to extract component metadata, including exported props, slots (default and named) and events (forwarded, dispatched). Props are manually annotated using the JSDocs format and parsed using the comment-parser npm package.

The generated TS definitions file defines a base class that stubs the interface of a Svelte component (following svelte2tsx) as consumed by the Svelte LSP:

class SvelteComponent {
  $$prop_def: {};

  $$slot_def: {};

  // stub all 'on:{event}' directives
  $on(eventname: string, handler: (e: Event) => any): () => void;
}

Each component extends the base class, overriding the base properties as necessary.

Component properties have a description and default value (if applicable).

export class Accordion extends CarbonSvelteBase {
  $$prop_def: {
    /**
     * Specify alignment of accordion item chevron icon
     * @default "end"
     */
    align?: "start" | "end";

    /**
     * Set to `true` to display the skeleton state
     * @default false
     */
    skeleton?: boolean;
  };

  $$slot_def: {
    default: {};
  };
}

Carbon icons are typed using the typeof operator:

icon?: typeof import("carbon-icons-svelte/lib/Add16").default;

View the current generated definitions: types/index.d.ts

Changes

• add script to document public API by parsing component info (i.e. props/slots/events)
• generate TypeScript definitions using parsed component info
• add missing JSDocs to components (related issue Svelte Ts support: SelectItem in index.d.ts has no props defined. #227 )
• use prettier to format generated types and .svelte files
• dependencies: upgrade carbon-icons-svelte to ^10.15.0 to consume library definitions
• devDependencies: add typescript, @tsconfig/svelte, comment-parser, prettier, prettier-plugin-svelte

Todo

• collect exported components using the rollup.generate JavaScript API
• parse each exported component using the Svelte compiler
• collect exported props (parse JSDoc comments using comment-parser), slots, forwarded/dispatched events
• generate TypeScript definition file
• generate human-readable documentation for each component (props/slots/events/import path etc.)
• add script to CI/publish flow
• test manually generated types
• add an example TS-enabled project
• document library usage with TypeScript

---

Notes:

Usage of the Rollup JavaScript API could be avoided by incorporating the generate-docs.js script as a Rollup plugin.