sveld 0.30.0 → 0.30.2

package/README.md

@@ -129,9 +129,11 @@ export default class Button extends SvelteComponentTyped<
 - [Available Options](#available-options)
 - [API Reference](#api-reference)
   - [@type](#type)
+  - [@default](#default)
   - [@typedef](#typedef)
   - [@callback](#callback)
   - [@slot / @snippet](#slot--snippet)
+    - [Extra JSDoc tags before `@slot`](#extra-jsdoc-tags-before-slot)
     - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
   - [@event](#event)
   - [Context API](#context-api)
@@ -419,6 +421,88 @@ For runes components with multiple destructured props, place JSDoc on the indivi
 </script>
 ```
 
+### `@default`
+
+By default, `sveld` infers the `@default` value from the prop's initializer and includes it in the generated TypeScript definitions:
+
+```svelte
+<script>
+  export let open = false;
+</script>
+```
+
+```ts
+/**
+ * @default false
+ */
+open?: boolean;
+```
+
+Use the `@default` tag to explicitly document the default value. When an explicit `@default` annotation is provided, `sveld` uses it instead of the inferred value, avoiding duplicate `@default` tags in the output.
+
+This is useful when the initializer references a variable or expression that is not meaningful to consumers:
+
+```svelte
+<script>
+  const defaultFilter = () => true;
+
+  /**
+   * @default () => true
+   * @type {(item: string, value: string) => boolean}
+   */
+  export let shouldFilter = defaultFilter;
+</script>
+```
+
+```ts
+/**
+ * @default () => true
+ */
+shouldFilter?: (item: string, value: string) => boolean;
+```
+
+#### Identifier resolution
+
+When a prop's initializer is a variable reference, `sveld` resolves it to the actual value automatically:
+
+```svelte
+<script>
+  const DEFAULT_SIZE = "md";
+
+  /** @type {"sm" | "md" | "lg"} */
+  export let size = DEFAULT_SIZE;
+</script>
+```
+
+```ts
+/**
+ * @default "md"
+ */
+size?: "sm" | "md" | "lg";
+```
+
+Chained references are also resolved:
+
+```svelte
+<script>
+  const ACTUAL_VALUE = 42;
+  const ALIAS = ACTUAL_VALUE;
+
+  export let count = ALIAS;
+</script>
+```
+
+```ts
+/**
+ * @default 42
+ */
+count?: number;
+```
+
+Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value. If the identifier cannot be resolved (e.g., it is imported from another module), the variable name is used as-is.
+
+When an explicit `@default` annotation is provided, it always takes precedence over the resolved value.
+
 ### `@typedef`
 
 The `@typedef` tag can be used to define a common type that is used multiple times within a component. All typedefs defined in a component will be exported from the generated TypeScript definition file.
@@ -704,7 +788,7 @@ When `@returns` is omitted, the return type defaults to `void`. When no `@param`
 
 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.
+Descriptions are optional for every slot, including the default slot: use prose lines in the same `/** */` block above `@slot` / `@snippet`, and/or an inline description on the `@slot` line for named slots.
 
 **Signature:**
 
@@ -770,6 +854,32 @@ Omit the `slot-name` to type the default slot.
 </p>
 ```
 
+#### Extra JSDoc tags before `@slot`
+
+Tags such as `@example`, `@deprecated`, `@see`, or `@since` that appear **after** the prose description and **before** the `@slot` / `@snippet` line are carried into generated `.d.ts` files: the emitted JSDoc above each slot’s snippet prop (and the traditional `SlotDefs` shape) contains the description, then those tags in source order. The same entries are available on each slot in JSON output as `tags: [{ "name", "body" }, ...]`.
+
+Put `@slot` / `@snippet` last in the block (`description` → optional extra tags → slot tag). Tags placed after `@slot` / `@snippet` in the same comment are not tied to that slot. Unknown tag names are passed through as-is (no allowlist). Markdown docs do not render slot descriptions or these tags yet; use TypeScript hover or JSON for that metadata.
+
+**Example (default slot with `@example` and `@deprecated`):**
+
+````svelte
+<script>
+  /**
+   * Spread `props` onto a custom element.
+   * @example
+   * ```svelte
+   * <Item let:props>
+   *   <a {...props} href="/">Home</a>
+   * </Item>
+   * ```
+   * @deprecated Prefer the `link` snippet.
+   * @slot {{ props?: { class: string } }}
+   */
+</script>
+
+<slot props={{ class: "bx--link" }} />
+````
+
 #### Svelte 5 Snippet Compatibility
 
 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.

package/lib/ComponentParser.d.ts

@@ -92,6 +92,14 @@ interface ComponentSlot {
     slot_props?: string;
     /** Description extracted from JSDoc `@slot` or `@snippet` tags */
     description?: string;
+    /**
+     * JSDoc tags that appeared after the prose description and before `@slot` / `@snippet`
+     * (e.g. `@example`, `@deprecated`), in source order.
+     */
+    tags?: Array<{
+        name: string;
+        body: string;
+    }>;
 }
 /**
  * Event that is forwarded from a child component or element.
@@ -520,6 +528,11 @@ export default class ComponentParser {
      * ```
      */
     private processInitializer;
+    /**
+     * Look up a local variable's initializer AST node by name.
+     * Returns the init node if found, or undefined.
+     */
+    private resolveLocalVarInitializer;
     /**
      * Unwraps `$bindable(...)` calls so defaults are documented as their underlying values.
      */