sveld 0.29.1 → 0.30.1

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             |     ✓     |
@@ -127,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)
@@ -156,6 +159,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 +216,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 +314,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 +368,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
@@ -404,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.
@@ -761,6 +859,8 @@ For Svelte 5 compatibility, `sveld` automatically generates optional snippet pro
 
 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:
 
 ```ts

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.
  *
@@ -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,10 +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 runesPropTypeMetadataByDeclaratorStart;
+    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 */
@@ -325,7 +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;
@@ -489,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.
      */
@@ -499,6 +535,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.