sveld 0.29.0 → 0.30.0

package/README.md

@@ -11,6 +11,8 @@ The purpose of this project is to make third party Svelte component libraries co
 
 `sveld` uses the Svelte 5 compiler to parse `.svelte` files. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …), and Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).
 
+For `lang="ts"` components, `sveld` preserves source-level prop type annotations when possible instead of requiring JSDoc as the primary source of truth. This includes legacy `export let` props, typed `$props()` destructuring, typed whole-object `$props()` captures, local `interface`/`type` declarations, and imported type references in emitted `.d.ts` files.
+
 | Syntax mode          | Supported |
 | :------------------- | :-------: |
 | Svelte 3             |     ✓     |
@@ -129,7 +131,7 @@ export default class Button extends SvelteComponentTyped<
   - [@type](#type)
   - [@typedef](#typedef)
   - [@callback](#callback)
-  - [@slot](#slot)
+  - [@slot / @snippet](#slot--snippet)
     - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
   - [@event](#event)
   - [Context API](#context-api)
@@ -156,6 +158,15 @@ Extracted metadata include:
 
 This library adopts a progressively enhanced approach. Any property type that cannot be inferred (e.g., "hello" is a string) falls back to "any" to minimize incorrectly typed properties or signatures. To mitigate this, the library author can add JSDoc annotations to specify types that cannot be reliably inferred. This represents a progressively enhanced approach because JSDocs are comments that can be ignored by the compiler.
 
+When both TypeScript syntax and JSDoc are present, `sveld` resolves prop types in this order:
+
+1. explicit TypeScript annotation
+2. explicit JSDoc annotation
+3. initializer inference
+4. `any`
+
+`sveld` intentionally stays AST-only. It preserves imported and local type text in generated `.d.ts` output, but it does not perform project-wide semantic resolution with the TypeScript compiler. That means opaque imported whole-object `$props()` types can be preserved in declarations without being fully expanded into JSON metadata.
+
 ## Usage
 
 ### Installation
@@ -204,13 +215,15 @@ sveld({
 When building the library, TypeScript definitions are emitted to the `types` folder by default.
 
 Customize the output folder using the `typesOptions.outDir` option.
+Use `typesOptions.printWidth` to control Prettier wrapping for generated `.d.ts` files. The default is `80`.
 
 The following example emits the output to the `dist` folder:
 
 ```diff
 sveld({
 +  typesOptions: {
-+    outDir: 'dist'
++    outDir: 'dist',
++    printWidth: 80
 +  }
 })
 ```
@@ -300,7 +313,7 @@ TypeScript definitions are outputted to the `types` folder by default. Don't for
 - **`entry`** (string, optional): Specify the entry point to uncompiled Svelte source. If not provided, sveld will use the `"svelte"` field from `package.json`.
 - **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
 - **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
-- **`typesOptions`** (object, optional): Options for TypeScript definition generation.
+- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `printWidth`.
 - **`json`** (boolean, optional): Generate component documentation in JSON format.
 - **`jsonOptions`** (object, optional): Options for JSON output.
 - **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
@@ -354,6 +367,8 @@ export let id = `ccs-${Math.random().toString(36)}`;
 
 Use the `@type` tag to explicitly document the type. In the following example, the `kind` property has an enumerated (enum) type.
 
+For `lang="ts"` components, prefer native TypeScript annotations when they are already present. `@type` remains useful for JavaScript components, for overriding inferred types, and for cases where the AST cannot recover a more precise type.
+
 **Signature:**
 
 ```js
@@ -369,18 +384,23 @@ Use the `@type` tag to explicitly document the type. In the following example, t
 
 ```svelte
 <script>
-  /**
-   * Specify the kind of button
-   * @type {"primary" | "secondary" | "tertiary"}
-   */
-  /**
-   * Specify the Carbon icon to render
-   * @type {typeof import("carbon-icons-svelte").CarbonIcon}
-   */
-  let { kind = "primary", renderIcon = Close20 } = $props();
+  let {
+    /**
+     * Specify the kind of button
+     * @type {"primary" | "secondary" | "tertiary"}
+     */
+    kind = "primary",
+    /**
+     * Specify the Carbon icon to render
+     * @type {typeof import("carbon-icons-svelte").CarbonIcon}
+     */
+    renderIcon = Close20,
+  } = $props();
 </script>
 ```
 
+For runes components with multiple destructured props, place JSDoc on the individual property you want to document. A declaration-level JSDoc block is only used as a fallback when the destructure exposes a single public prop.
+
 **Svelte 3, 4, 5 (non-Runes):**
 
 ```svelte
@@ -680,9 +700,9 @@ Callbacks can be combined with `@typedef` in the same comment block:
 
 When `@returns` is omitted, the return type defaults to `void`. When no `@param` tags are present, the callback is typed as a no-argument function.
 
-### `@slot`
+### `@slot` / `@snippet`
 
-Use the `@slot` tag for typing component slots. Note that `@slot` is a non-standard JSDoc tag.
+Use the `@slot` tag for typing component slots. For Svelte 5 runes components, `@snippet` is also supported as an alias. Both are non-standard JSDoc tags.
 
 Descriptions are optional for named slots. Currently, the default slot cannot have a description.
 
@@ -691,12 +711,14 @@ Descriptions are optional for named slots. Currently, the default slot cannot ha
 ```js
 /**
  * @slot {Type} slot-name [slot description]
+ * @snippet {Type} snippet-name [snippet description]
  */
 
 Omit the `slot-name` to type the default slot.
 
 /**
  * @slot {Type}
+ * @snippet {Type}
  */
 ```
 
@@ -707,9 +729,9 @@ Omit the `slot-name` to type the default slot.
 ```svelte
 <script>
   /**
-   * @slot {{ prop: number; doubled: number; }}
-   * @slot {{}} title
-   * @slot {{ prop: number }} body - Customize the paragraph text.
+   * @snippet {{ prop: number; doubled: number; }}
+   * @snippet {{}} title
+   * @snippet {{ prop: number }} body - Customize the paragraph text.
    */
 
   let { prop = 0, children, title, body } = $props();
@@ -752,7 +774,9 @@ Omit the `slot-name` to type the default slot.
 
 For Svelte 5 compatibility, `sveld` automatically generates optional snippet props for all slots. This allows consumers to use either the traditional slot syntax or Svelte 5's `{#snippet}` syntax.
 
-When parsing runes components, `sveld` also maps `{@render ...}` calls back into the same slot metadata used for traditional `<slot>` declarations.
+When parsing runes components, `sveld` maps `{@render ...}` calls back into the same slot metadata used for traditional `<slot>` declarations. Reserved snippet props such as `children`, along with named snippet props discovered from `{@render ...}`, are represented through `slots` metadata and generated snippet prop types rather than duplicated in the `props` output.
+
+Positional snippet calls such as `{@render row?.(item, index)}` are preserved as typed props when the prop itself has an explicit type like `Snippet<[Item, number]>`. They are not converted into synthetic slot metadata.
 
 For slots with props (e.g., `let:prop`), the generated type uses a Snippet-compatible signature:
 
@@ -856,7 +880,7 @@ export default class DataTable<Row> extends SvelteComponentTyped<
 
 Use the `@event` tag to type dispatched events. An event name is required and a description optional.
 
-In Svelte 5 runes components, callback props such as `onclick` are treated as component props, not events. The `events` output remains reserved for dispatched events and legacy forwarded events.
+In Svelte 5 runes components, callback props such as `onclick` are treated as component props, not events. The `events` output remains reserved for real dispatched events and legacy forwarded events. If a runes component documents `@event foo` and exposes a matching callback prop like `onfoo` without actually dispatching or forwarding `foo`, `sveld` aliases that documentation onto the callback prop instead of synthesizing an emitted event.
 
 Use `null` as the value if no event detail is provided.
 
@@ -873,6 +897,20 @@ Use `null` as the value if no event detail is provided.
 
 **Svelte 5 Runes:**
 
+```svelte
+<script>
+  /**
+   * Fired when a value is saved.
+   * @event {{ id: string }} save
+   */
+  let { onsave } = $props();
+</script>
+
+<button onclick={() => onsave?.({ id: "1" })}>Save</button>
+```
+
+**Svelte 5 Runes with dispatched events:**
+
 ```svelte
 <script>
   /**
@@ -1439,8 +1477,13 @@ Because `sveld` is designed to support JavaScript-only usage as a baseline, the
    * @generics {Row extends DataTableRow = DataTableRow} Row
    */
 
-  /** @type {ReadonlyArray<DataTableHeader<Row>>} */
-  let { headers = [], rows = [], children } = $props();
+  let {
+    /** @type {ReadonlyArray<DataTableHeader<Row>>} */
+    headers = [],
+    /** @type {ReadonlyArray<Row>} */
+    rows = [],
+    children,
+  } = $props();
 </script>
 
 {@render children?.({ headers, rows })}

package/lib/ComponentParser.d.ts

@@ -1,3 +1,13 @@
+export interface ParsedComponentTypeScriptMetadata {
+    canonicalPropsType?: string;
+    canonicalPropNames: string[];
+    localTypeDeclarations: string[];
+    typeImportStatements: string[];
+}
+export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
+export declare function getParsedComponentTypeScriptMetadata(component: {
+    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
+}): ParsedComponentTypeScriptMetadata | undefined;
 /**
  * Diagnostic information for component parsing.
  *
@@ -80,7 +90,7 @@ interface ComponentSlot {
     fallback?: string;
     /** TypeScript type definition for slot props (e.g., "{ title: string }") */
     slot_props?: string;
-    /** Description extracted from JSDoc `@slot` tags */
+    /** Description extracted from JSDoc `@slot` or `@snippet` tags */
     description?: string;
 }
 /**
@@ -258,6 +268,8 @@ export interface ParsedComponent {
     componentComment?: string;
     /** Contexts created with `setContext` in the component */
     contexts?: ComponentContext[];
+    /** Internal writer-only TypeScript metadata. Not serialized to JSON. */
+    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }
 export default class ComponentParser {
     /** Parser configuration options (e.g., verbose logging) */
@@ -306,8 +318,20 @@ export default class ComponentParser {
     private readonly propLocalToPublicName;
     /** Tracks `$props()` bindings that are used as spread/rest props */
     private readonly restPropLocals;
+    /** Tracks identifier bindings that capture the entire `$props()` object */
+    private readonly wholePropsLocals;
     /** Tracks prop locals that are used as snippet/render props */
     private readonly snippetPropLocals;
+    /** Per-declarator type metadata extracted from modern AST `$props()` annotations */
+    private readonly runesPropsDeclarationMetadataByDeclaratorStart;
+    /** Explicit TypeScript prop annotations for legacy `export let` declarations keyed by local name */
+    private readonly explicitPropTypesByName;
+    /** Type-only imports keyed by their local binding names */
+    private readonly typeImportBindingsByLocalName;
+    /** Local interface/type declarations keyed by type name */
+    private readonly localTypeDeclarationsByName;
+    /** Typed `$props()` declarations discovered in source order */
+    private readonly typedRunesPropsDeclarations;
     /** Component-level lexical scope shared by instance script and template */
     private readonly componentScope;
     /** Precomputed lexical scopes for nested AST nodes */
@@ -323,6 +347,16 @@ export default class ComponentParser {
     private trackPropLocalName;
     private getPropByLocalOrPublic;
     private getPropTypeByLocalOrPublic;
+    private getExplicitPropType;
+    private getRunesPropsDeclarationMetadata;
+    private getRunesPropTypeMetadata;
+    private getTypeReferenceName;
+    private getTypeDependencyName;
+    private getTypeAnnotationText;
+    private collectReferencedTypeDependencies;
+    private buildTypeImportStatements;
+    private buildTypeScriptMetadata;
+    private buildRunesPropTypeMetadataMap;
     private declareScopeBinding;
     private resolveIdentifierToReactiveProp;
     private collectPatternIdentifiers;
@@ -347,7 +381,7 @@ export default class ComponentParser {
      * Extracts and categorizes JSDoc tags from a parsed comment.
      *
      * Separates tags into type, param, returns, and additional categories while
-     * excluding tags that are handled separately (extends, restProps, slot, event, typedef).
+     * excluding tags that are handled separately (extends, restProps, slot/snippet, event, typedef).
      *
      * @param parsed - The parsed comment result from comment-parser
      * @returns An object containing categorized tags and the comment description
@@ -390,6 +424,7 @@ export default class ComponentParser {
     private static findJSDocComment;
     private findAdjacentJSDocComment;
     private processNodeJSDoc;
+    private processLeadingCommentsJSDoc;
     /**
      * Processes JSDoc comments from leadingComments and extracts structured information.
      *
@@ -423,6 +458,7 @@ export default class ComponentParser {
      * ```
      */
     private processJSDocComment;
+    private buildRunesPropTypeMetadata;
     /**
      * Checks if a MemberExpression represents a well-known numeric constant.
      *
@@ -494,6 +530,7 @@ export default class ComponentParser {
     private parseRunesPropsDeclaration;
     private inferSlotPropValueFromExpression;
     private buildSlotPropsFromObjectExpression;
+    private resolveRenderTagPropReference;
     private extractRenderTagInfo;
     /**
      * Adds or merges a component prop to the props map.
@@ -640,6 +677,7 @@ export default class ComponentParser {
      * ```
      */
     private addDispatchedEvent;
+    private normalizeRunesCallbackProps;
     /**
      * Parses custom types, events, slots, and other JSDoc annotations from component comments.
      *