sveld 0.30.0 → 0.30.1

package/README.md

@@ -129,6 +129,7 @@ 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)
@@ -419,6 +420,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.

package/lib/ComponentParser.d.ts

@@ -520,6 +520,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.
      */