sveld 0.25.12 → 0.26.0

package/README.md

@@ -8,11 +8,7 @@
 
 The purpose of this project is to make third party Svelte component libraries compatible with the Svelte Language Server and TypeScript with minimal effort required by the author. For example, TypeScript definitions may be used during development via intelligent code completion in Integrated Development Environments (IDE) like VSCode.
 
-[Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata:
-
-- [TypeScript definitions](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/types): Component TypeScript definitions
-- [Component Index](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/COMPONENT_INDEX.md): Markdown file documenting component props, slots, and events
-- [Component API](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/docs/src/COMPONENT_API.json): Component API metadata in JSON format
+[Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata.
 
 **Note:** `sveld` supports Svelte 3, 4, and 5, but does not support Svelte 5-specific syntax or runes-only usage. Components must use traditional Svelte syntax (e.g., `export let` for props, not `$props()`).
 
@@ -116,7 +112,7 @@ export default class Button extends SvelteComponentTyped<
 - [Approach](#approach)
 - [Usage](#usage)
   - [Installation](#installation)
-  - [Rollup](#rollup)
+  - [Vite](#vite)
   - [Node.js](#nodejs)
   - [CLI](#cli)
   - [Publishing to NPM](#publishing-to-npm)
@@ -129,7 +125,7 @@ export default class Button extends SvelteComponentTyped<
   - [@event](#event)
   - [Context API](#context-api)
   - [@restProps](#restprops)
-  - [@extends](#extends)
+  - [@extendProps](#extendprops)
   - [@generics](#generics)
   - [@component comments](#component-comments)
   - [Accessor Props](#accessor-props)
@@ -171,26 +167,23 @@ bun i -D sveld
 yarn add -D sveld
 ```
 
-### Rollup
+### Vite
 
-Import and add `sveld` as a plugin to your `rollup.config.js`.
+Import and add `sveld` as a plugin to your `vite.config.ts`. The plugin only runs during `vite build` (not the dev server).
 
-```js
-// rollup.config.js
-import svelte from "rollup-plugin-svelte";
-import resolve from "@rollup/plugin-node-resolve";
+```ts
+// vite.config.ts
+import { svelte } from "@sveltejs/vite-plugin-svelte";
 import sveld from "sveld";
+import { defineConfig } from "vite";
 
-export default {
-  input: "src/index.js",
-  output: {
-    format: "es",
-    file: "lib/index.mjs",
-  },
-  plugins: [svelte(), resolve(), sveld()],
-};
+export default defineConfig({
+  plugins: [svelte(), sveld()],
+});
 ```
 
+Since Vite uses Rollup for production builds, `sveld` also works in Rollup configurations.
+
 By default, `sveld` will use the `"svelte"` field from your `package.json` to determine the entry point. You can override this by specifying an explicit `entry` option:
 
 ```js
@@ -213,16 +206,6 @@ sveld({
 })
 ```
 
-The [tests/e2e](tests/e2e) folder contains example set-ups:
-
-- [single-export](tests/e2e/single-export): library that exports one component
-- [single-export-default-only](tests/e2e/single-export-default-only): library that exports one component using the concise `export { default } ...` syntax
-- [multi-export](tests/e2e/multi-export): multi-component library without JSDoc annotations (types are inferred)
-- [multi-export-typed](tests/e2e/multi-export-typed): multi-component library with JSDoc annotations
-- [multi-export-typed-ts-only](tests/e2e/multi-export-typed-ts-only): multi-component library that only generates TS definitions
-- [glob](tests/e2e/glob): library that uses the glob strategy to collect/analyze \*.svelte files
-- [carbon](tests/e2e/carbon): full `carbon-components-svelte` example
-
 ### CLI
 
 The CLI uses the `"svelte"` field from your `package.json` as the entry point:
@@ -303,7 +286,7 @@ TypeScript definitions are outputted to the `types` folder by default. Don't for
 
 ## Available Options
 
-### Rollup Plugin Options
+### Plugin Options
 
 - **`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.
@@ -1003,22 +986,24 @@ Example:
 {/if}
 ```
 
-### `@extends`
+### `@extendProps`
+
+In some cases, a component may be based on another component. The `@extendProps` tag can be used to extend generated component props.
 
-In some cases, a component may be based on another component. The `@extends` tag can be used to extend generated component props.
+> **Note:** `@extends` is supported as an alias but `@extendProps` is preferred to avoid conflicts with standard JSDoc `@extends` (used for class inheritance).
 
 Signature:
 
 ```js
 /**
- * @extends {<relative path to component>} ComponentProps
+ * @extendProps {<relative path to component>} ComponentProps
  */
 ```
 
 Example:
 
 ```js
-/** @extends {"./Button.svelte"} ButtonProps */
+/** @extendProps {"./Button.svelte"} ButtonProps */
 
 export const secondary = true;
 

package/lib/ComponentParser.d.ts

@@ -167,6 +167,8 @@ interface ComponentElement {
      * ```
      */
     thisValue?: string;
+    /** Inline or block description from the `@restProps` JSDoc tag */
+    description?: string;
 }
 type RestProps = undefined | ComponentInlineElement | ComponentElement;
 /**
@@ -510,6 +512,23 @@ export default class ComponentParser {
      * ```
      */
     private aliasType;
+    /**
+     * Extracts a property's type from an object type string.
+     *
+     * Parses type strings like `{ value: string; other: number }` and returns
+     * the type for the requested property name. Handles nested braces, generics,
+     * and optional properties.
+     *
+     * @returns The property type string, or undefined if not found
+     */
+    private extractPropertyType;
+    /**
+     * Resolves the type of a MemberExpression (e.g., `obj.value`) by looking up
+     * the object's type annotation and extracting the property type.
+     *
+     * @returns The resolved type string, or undefined if it cannot be resolved
+     */
+    private resolveMemberExpressionType;
     /**
      * Adds or merges a slot definition to the slots map.
      *

package/lib/ComponentParser.js

@@ -32,6 +32,8 @@ const VAR_DECLARATION_REGEX = /(?:const|let|function)\s+(\w+)\s*[=(]/;
  * ```
  */
 const DESCRIPTION_DASH_PREFIX_REGEX = /^-\s*/;
+/** Matches a single word character (letter, digit, or underscore). Used for dotted prop access validation. */
+const WORD_CHAR_REGEX = /\w/;
 /**
  * Extracts description text after the last dash from JSDoc comments.
  *
@@ -256,6 +258,7 @@ class ComponentParser {
             "returns",
             "return",
             "extends",
+            "extendProps",
             "restProps",
             "slot",
             "event",
@@ -732,6 +735,77 @@ class ComponentParser {
             return "any";
         return type.trim();
     }
+    /**
+     * Extracts a property's type from an object type string.
+     *
+     * Parses type strings like `{ value: string; other: number }` and returns
+     * the type for the requested property name. Handles nested braces, generics,
+     * and optional properties.
+     *
+     * @returns The property type string, or undefined if not found
+     */
+    extractPropertyType(typeStr, propName) {
+        const trimmed = typeStr.trim();
+        if (!trimmed.startsWith("{") || !trimmed.endsWith("}"))
+            return undefined;
+        const inner = trimmed.slice(1, -1);
+        const segments = [];
+        let depth = 0;
+        let current = "";
+        for (const char of inner) {
+            if (char === "{" || char === "<" || char === "(" || char === "[") {
+                depth++;
+                current += char;
+            }
+            else if (char === "}" || char === ">" || char === ")" || char === "]") {
+                depth--;
+                current += char;
+            }
+            else if ((char === ";" || char === ",") && depth === 0) {
+                segments.push(current.trim());
+                current = "";
+            }
+            else {
+                current += char;
+            }
+        }
+        if (current.trim())
+            segments.push(current.trim());
+        for (const segment of segments) {
+            if (!segment.startsWith(propName))
+                continue;
+            const afterName = segment.slice(propName.length);
+            if (afterName.length > 0 && WORD_CHAR_REGEX.test(afterName[0]))
+                continue;
+            let rest = afterName.trimStart();
+            if (rest.startsWith("?"))
+                rest = rest.slice(1).trimStart();
+            if (rest.startsWith(":")) {
+                return rest.slice(1).trim();
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolves the type of a MemberExpression (e.g., `obj.value`) by looking up
+     * the object's type annotation and extracting the property type.
+     *
+     * @returns The resolved type string, or undefined if it cannot be resolved
+     */
+    resolveMemberExpressionType(expr) {
+        const memberExpr = expr;
+        if (memberExpr.computed || memberExpr.object?.type !== "Identifier" || memberExpr.property?.type !== "Identifier") {
+            return undefined;
+        }
+        const objName = memberExpr.object.name;
+        const propName = memberExpr.property.name;
+        if (!objName || !propName)
+            return undefined;
+        const objType = this.props.get(objName)?.type ?? this.findVariableTypeAndDescription(objName)?.type;
+        if (!objType)
+            return undefined;
+        return this.extractPropertyType(objType, propName);
+    }
     /**
      * Adds or merges a slot definition to the slots map.
      *
@@ -1116,6 +1190,7 @@ class ComponentParser {
                 const precedingDescription = getPrecedingDescription(tagSource);
                 switch (tag) {
                     case "extends":
+                    case "extendProps":
                         this.extends = {
                             interface: name,
                             import: type,
@@ -1123,14 +1198,31 @@ class ComponentParser {
                         if (isFirstTag)
                             isFirstTag = false;
                         break;
-                    case "restProps":
+                    case "restProps": {
+                        /**
+                         * Prefer inline description (e.g., "@restProps {type} description" or "@restProps {type} - description"),
+                         * fall back to preceding line description, then fall back to the
+                         * comment block description (only for first tag if not already used).
+                         *
+                         * Note: comment-parser treats the first word after the type as "name" and the rest as "description",
+                         * so we combine them to form the full inline description for @restProps.
+                         */
+                        const rawInlineDesc = name ? (description ? `${name} ${description}` : name) : description;
+                        const inlineRestPropsDesc = cleanDescription(rawInlineDesc);
+                        let restPropsDesc = inlineRestPropsDesc || precedingDescription;
+                        if (!restPropsDesc && isFirstTag && !commentDescriptionUsed && commentDescription) {
+                            restPropsDesc = commentDescription;
+                            commentDescriptionUsed = true;
+                        }
                         this.rest_props = {
                             type: "Element",
                             name: type,
+                            description: restPropsDesc || undefined,
                         };
                         if (isFirstTag)
                             isFirstTag = false;
                         break;
+                    }
                     case "slot": {
                         /**
                          * Prefer inline description (e.g., "@slot name - description"),
@@ -2298,14 +2390,14 @@ class ComponentParser {
                                 if (expression.type === "Literal" && "value" in expression) {
                                     slot_prop_value.value = String(expression.value);
                                 }
+                                else if (expression.type === "MemberExpression") {
+                                    slot_prop_value.value = this.resolveMemberExpressionType(expression);
+                                }
                                 else if (expression.type !== "Identifier") {
                                     if (start !== undefined && end !== undefined) {
                                         if (expression.type === "ObjectExpression" || expression.type === "TemplateLiteral") {
                                             slot_prop_value.value = this.sourceAtPos(start + 1, end - 1);
                                         }
-                                        else {
-                                            slot_prop_value.value = this.sourceAtPos(start, end);
-                                        }
                                     }
                                 }
                             }

package/lib/cli.js

@@ -8,7 +8,7 @@ const plugin_node_resolve_1 = __importDefault(require("@rollup/plugin-node-resol
 const rollup_1 = require("rollup");
 const rollup_plugin_svelte_1 = __importDefault(require("rollup-plugin-svelte"));
 const get_svelte_entry_1 = require("./get-svelte-entry");
-const rollup_plugin_1 = require("./rollup-plugin");
+const plugin_1 = require("./plugin");
 /**
  * Command-line interface for sveld.
  *
@@ -43,6 +43,6 @@ async function cli(process) {
         plugins: [(0, rollup_plugin_svelte_1.default)(), (0, plugin_node_resolve_1.default)()],
     });
     await rollup_bundle.generate({});
-    const result = await (0, rollup_plugin_1.generateBundle)(input, options?.glob === true);
-    (0, rollup_plugin_1.writeOutput)(result, options, input);
+    const result = await (0, plugin_1.generateBundle)(input, options?.glob === true);
+    (0, plugin_1.writeOutput)(result, options, input);
 }

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { default as ComponentParser } from "./ComponentParser";
 export { cli } from "./cli";
-export { default } from "./rollup-plugin";
+export { default } from "./plugin";
 export { sveld } from "./sveld";

package/lib/index.js

@@ -8,7 +8,7 @@ var ComponentParser_1 = require("./ComponentParser");
 Object.defineProperty(exports, "ComponentParser", { enumerable: true, get: function () { return __importDefault(ComponentParser_1).default; } });
 var cli_1 = require("./cli");
 Object.defineProperty(exports, "cli", { enumerable: true, get: function () { return cli_1.cli; } });
-var rollup_plugin_1 = require("./rollup-plugin");
-Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(rollup_plugin_1).default; } });
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(plugin_1).default; } });
 var sveld_1 = require("./sveld");
 Object.defineProperty(exports, "sveld", { enumerable: true, get: function () { return sveld_1.sveld; } });

package/lib/{rollup-plugin.d.ts → plugin.d.ts}

@@ -23,12 +23,15 @@ export interface ComponentDocApi extends ParsedComponent {
     moduleName: string;
 }
 export type ComponentDocs = Map<ComponentModuleName, ComponentDocApi>;
-export default function pluginSveld(opts?: PluginSveldOptions): {
+interface SveldPlugin {
     name: string;
+    apply?: "build" | "serve";
+    enforce?: "pre" | "post";
     buildStart(): void;
     generateBundle(): Promise<void>;
     writeBundle(): void;
-};
+}
+export default function pluginSveld(opts?: PluginSveldOptions): SveldPlugin;
 interface GenerateBundleResult {
     exports: ParsedExports;
     components: ComponentDocs;

package/lib/{rollup-plugin.js → plugin.js}

@@ -25,7 +25,9 @@ function pluginSveld(opts) {
     let result;
     let input;
     return {
-        name: "plugin-sveld",
+        name: "vite-plugin-sveld",
+        apply: "build",
+        enforce: "post",
         buildStart() {
             input = (0, get_svelte_entry_1.getSvelteEntry)(opts?.entry);
         },

package/lib/sveld.d.ts

@@ -1,4 +1,4 @@
-import { type PluginSveldOptions } from "./rollup-plugin";
+import { type PluginSveldOptions } from "./plugin";
 interface SveldOptions extends PluginSveldOptions {
     /**
      * Specify the input to the uncompiled Svelte source.

package/lib/sveld.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sveld = sveld;
 const get_svelte_entry_1 = require("./get-svelte-entry");
-const rollup_plugin_1 = require("./rollup-plugin");
+const plugin_1 = require("./plugin");
 /**
  * Main entry point for programmatic sveld usage.
  *
@@ -28,6 +28,6 @@ async function sveld(opts) {
     const input = (0, get_svelte_entry_1.getSvelteEntry)(opts?.input);
     if (input === null)
         return;
-    const result = await (0, rollup_plugin_1.generateBundle)(input, opts?.glob === true);
-    (0, rollup_plugin_1.writeOutput)(result, opts || {}, input);
+    const result = await (0, plugin_1.generateBundle)(input, opts?.glob === true);
+    (0, plugin_1.writeOutput)(result, opts || {}, input);
 }

package/lib/writer/markdown-render-utils.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDocs } from "../rollup-plugin";
+import type { ComponentDocs } from "../plugin";
 import type { AppendType } from "./MarkdownWriterBase";
 /**
  * Interface for markdown documents that can be used for rendering.

package/lib/writer/writer-json.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDocs } from "../rollup-plugin";
+import type { ComponentDocs } from "../plugin";
 export interface WriteJsonOptions {
     input: string;
     inputDir: string;

package/lib/writer/writer-markdown-core.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDocs } from "../rollup-plugin";
+import type { ComponentDocs } from "../plugin";
 import { type AppendType, MarkdownWriterBaseImpl } from "./MarkdownWriterBase";
 export type { AppendType };
 type OnAppend = (type: AppendType, document: BrowserWriterMarkdown) => void;

package/lib/writer/writer-markdown.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDocs } from "../rollup-plugin";
+import type { ComponentDocs } from "../plugin";
 import WriterMarkdown, { type AppendType } from "./WriterMarkdown";
 export interface WriteMarkdownOptions {
     write?: boolean;

package/lib/writer/writer-ts-definitions-core.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDocApi } from "../rollup-plugin";
+import type { ComponentDocApi } from "../plugin";
 export declare function formatTsProps(props?: string): string;
 export declare function getTypeDefs(def: Pick<ComponentDocApi, "typedefs">): string;
 /**

package/lib/writer/writer-ts-definitions-core.js

@@ -301,6 +301,15 @@ function genPropDef(def) {
          * Template literal is required for TypeScript's template literal type syntax.
          */
         const dataAttributes = "[key: `data-${string}`]: any;";
+        /**
+         * Generate JSDoc comment for $RestProps if description is provided.
+         * Use multiline format when description contains newlines.
+         */
+        const restPropsComment = def.rest_props.description
+            ? def.rest_props.description.includes("\n")
+                ? `${formatMultiLineComment(def.rest_props.description)}\n    `
+                : `${formatSingleLineComment(def.rest_props.description)}\n    `
+            : "";
         /**
          * When both `@extends` and `@restProps` are present, merge all three type sources:
          * 1. Rest props from element types (SvelteHTMLElements)
@@ -309,7 +318,7 @@ function genPropDef(def) {
          */
         if (def.extends !== undefined) {
             prop_def = `
-    ${extend_tag_map ? `type $RestProps = ${extend_tag_map};\n` : ""}
+    ${restPropsComment}${extend_tag_map ? `type $RestProps = ${extend_tag_map};\n` : ""}
     type $Props${genericsName} = {
       ${props}
 
@@ -321,7 +330,7 @@ function genPropDef(def) {
         }
         else {
             prop_def = `
-    ${extend_tag_map ? `type $RestProps = ${extend_tag_map};\n` : ""}
+    ${restPropsComment}${extend_tag_map ? `type $RestProps = ${extend_tag_map};\n` : ""}
     type $Props${genericsName} = {
       ${props}
 

package/lib/writer/writer-ts-definitions.d.ts

@@ -1,5 +1,5 @@
 import type { ParsedExports } from "../parse-exports";
-import type { ComponentDocs } from "../rollup-plugin";
+import type { ComponentDocs } from "../plugin";
 /**
  * Re-export browser-compatible functions from core module.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.25.12",
+  "version": "0.26.0",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions for your Svelte components.",
   "main": "./lib/index.js",
@@ -37,7 +37,9 @@
     "docgen",
     "typescript",
     "definitions",
-    "JSDocs"
+    "JSDocs",
+    "vite",
+    "vite-plugin"
   ],
   "maintainers": [
     "Eric Liu (https://github.com/metonym)"