sveld 0.29.0 → 0.29.1

package/README.md

@@ -129,7 +129,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)
@@ -369,18 +369,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 +685,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 +696,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 +714,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 +759,7 @@ 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.
 
 For slots with props (e.g., `let:prop`), the generated type uses a Snippet-compatible signature:
 
@@ -856,7 +863,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 +880,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 +1460,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

@@ -80,7 +80,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;
 }
 /**
@@ -308,6 +308,8 @@ export default class ComponentParser {
     private readonly restPropLocals;
     /** 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 runesPropTypeMetadataByDeclaratorStart;
     /** Component-level lexical scope shared by instance script and template */
     private readonly componentScope;
     /** Precomputed lexical scopes for nested AST nodes */
@@ -323,6 +325,7 @@ export default class ComponentParser {
     private trackPropLocalName;
     private getPropByLocalOrPublic;
     private getPropTypeByLocalOrPublic;
+    private getRunesPropTypeMetadata;
     private declareScopeBinding;
     private resolveIdentifierToReactiveProp;
     private collectPatternIdentifiers;
@@ -347,7 +350,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 +393,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 +427,7 @@ export default class ComponentParser {
      * ```
      */
     private processJSDocComment;
+    private buildRunesPropTypeMetadata;
     /**
      * Checks if a MemberExpression represents a well-known numeric constant.
      *
@@ -640,6 +645,7 @@ export default class ComponentParser {
      * ```
      */
     private addDispatchedEvent;
+    private normalizeRunesCallbackProps;
     /**
      * Parses custom types, events, slots, and other JSDoc annotations from component comments.
      *