refactor(types): rewrite component TypeScript definitions

[metonym]

This PR rewrites the TypeScript definitions from scratch.

Purpose

• account for intrinsic element attributes if $$restProps is spread to a native HTML Element (Fix IntrinsicAttributes error in TypeScript definitions #304 )
• accurately represent the shape of the library so direct imports work
• improve typings for prop default values by deferring to the Svelte compiler instead of JSDocs
• improve typings for forwarded/dispatched events
• improve typings for slots, slot props

Refactor

• adjust existing JSDoc annotations to be more concise
• remove "." from component file names to improve direct imports
• update typeof import("carbon-icons-svelte/lib/Add16").default to import("carbon-icons-svelte").CarbonIcon
• remove type annotation for id, ref props where applicable

Docs

• replace PUBLIC_API.json with COMPONENT_API.json generated from "sveld"
• enhance component API documentation by linking to component source code, labelling reactive props, describing if the component spreads $$restProps

Todo

• further improve slot prop typings (conservatively, some will fallback to any)
• some interfaces should be exported for the consumer (i.e. DataTable headers in DataTable: typings for headers and rows #364 ) (defer)
• use svelte-check to validate TS definitions in the CI

Errors

• props must extend svelte.JSX.HTMLAttributes<HTMLElementTagNameMap["div"]>; an intersection will cause errors
• components without $$restProps (or if it's ambiguous like Tag) should conservatively allow any attributes
• remove "undefined" dispatched events

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/carbon-svelte/carbon-components-svelte/iu056uky3
✅ Preview: https://carbon-components-svelte-git-rewrite-tyepscript-definitions.carbon-svelte.vercel.app

[albertms10]

Wow, nice job! 👏

Just asking… Will union types also be rewritten to TS syntax? (As do the *.d.ts output type files)

Before:

/**
 * Specify alignment of accordion item chevron icon
 * @type {"start" | "end"}
 */
export let align = "end";

After:

/** Specify alignment of accordion item chevron icon */
export let align: "start" | "end" = "end";

[metonym]

@albertms10 That's good thinking but unfortunately that would make the uncompiled Svelte components TS only.

[albertms10]

Instead of typing the generic icon prop with the Add16 icon default type, wouldn’t it be cleaner to use the typeof CarbonIcon class?—it applies to the rest of icon imports.

/**
 * Specify the icon from `carbon-icons-svelte` to render
 * @type {typeof import("carbon-icons-svelte").CarbonIcon}
 */
export let icon = undefined;

Although in this way you can’t restrict the icon size to e.g. 16… 🤔

[metonym]

Nice suggestion. The icon size should not matter.