sveld 0.36.10 → 0.36.11

package/README.md

@@ -141,18 +141,28 @@ export default class Button extends SvelteComponentTyped<
 - [JSON Output](#json-output)
 - [Custom Elements Manifest](#custom-elements-manifest)
   - [Consuming the manifest](#consuming-the-manifest)
+- [Custom Writers](#custom-writers)
+  - [The `OutputWriter` contract](#the-outputwriter-contract)
+  - [Registering a writer](#registering-a-writer)
+  - [Running it via the plugin](#running-it-via-the-plugin)
+  - [Worked example: a minimal `llms.txt` writer](#worked-example-a-minimal-llmstxt-writer)
 - [API Reference](#api-reference)
   - [reactive](#reactive)
   - [binding](#binding)
   - [@type](#type)
   - [@default](#default)
   - [@typedef](#typedef)
+  - [@property](#property)
   - [@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)
   - [@deprecated](#deprecated)
+  - [@since](#since)
+  - [@see](#see)
+  - [@link](#link)
+  - [@example](#example)
   - [Context API](#context-api)
   - [@restProps](#restprops)
   - [@extendProps](#extendprops)
@@ -708,14 +718,22 @@ The `svelte` condition lets bundlers that understand it (Vite, Rollup, webpack v
 - **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
 - **`documentExports`** (boolean, optional): Include consts, functions, and types from the entry barrel in JSON (`exports`) and Markdown ("Exports"). Off by default. See [Documenting Entry Exports](#documenting-entry-exports).
 - **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
-- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `format`.
+- **`typesOptions`** (object, optional): Options for TypeScript definition generation.
+  - **`outDir`** (string, optional, default: `"types"`): Output directory for generated `.d.ts` files, relative to the project root.
+  - **`preamble`** (string, optional, default: `""`): Raw text prepended to the top of the generated `index.d.ts` barrel file, before the `export * from "./..."` lines. Useful for license headers or lint-disable comments. See [`typesOptions.preamble`](#typesoptionspreamble) below.
   - **`format`** (`"class"` | `"component"`, optional, default: `"class"`): `.d.ts` output shape. `"class"` extends `SvelteComponentTyped`; `"component"` emits the Svelte 5 `Component` type. Also available as `--types-format`. See [`.d.ts` output format](#dts-output-format-typesoptionsformat).
 - **`json`** (boolean, optional): Generate component documentation in JSON format.
 - **`jsonOptions`** (object, optional): Options for JSON output.
+  - **`outFile`** (string, optional, default: `"COMPONENT_API.json"`): Path (relative to the project root) for the single combined JSON document. Ignored when `outDir` is set.
+  - **`outDir`** (string, optional): Emit one JSON file per component (`<ComponentName>.api.json`) into this directory instead of a single combined file. See [`jsonOptions.outDir`](#jsonoptionsoutdir).
 - **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
 - **`markdownOptions`** (object, optional): Options for Markdown output.
+  - **`outFile`** (string, optional, default: `"COMPONENT_INDEX.md"`): Path (relative to the project root) for the generated Markdown file.
+  - **`write`** (boolean, optional, default: `true`): Set to `false` to render the Markdown document without writing it to disk.
+  - **`onAppend`** (function, optional): Callback invoked every time a heading, quote, paragraph, divider, or raw block is appended to the document. Lets you inject extra content, e.g. a summary line under the title. See [`markdownOptions.onAppend`](#markdownoptionsonappend) below.
 - **`customElements`** (boolean, optional): Generate a [Custom Elements Manifest](#custom-elements-manifest) (`custom-elements.json`). Also available as the `--custom-elements` CLI flag.
-- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output, including `outFile`.
+- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output.
+  - **`outFile`** (string, optional, default: `"custom-elements.json"`): Path (relative to the project root) for the generated manifest file.
 - **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when `.svelte` source changes during `vite dev` / `vite build --watch`. Only the changed component and the components that depend on it via [`@extendProps`](#extendprops) / `@extends` are re-parsed, rather than rebuilding every component. Without this option, the plugin only runs during `vite build`.
 - **`failFast`** (boolean, optional, default: `false`): Abort the entire run when a single component fails to parse. By default, parse failures are collected as diagnostics (and reported to `stderr`) so the remaining components still emit their output. Also available as the `--fail-fast` CLI flag.
 - **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. Also available as `--resolve-types` (`--resolveTypes` remains as a deprecated alias). See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
@@ -738,6 +756,56 @@ sveld({
 })
 ```
 
+#### `typesOptions.preamble`
+
+Use `typesOptions.preamble` to prepend raw text to the generated `types/index.d.ts` barrel file — for example, a license header that should ship with every published `.d.ts` file.
+
+```js
+sveld({
+  types: true,
+  typesOptions: {
+    preamble: "// Copyright (c) 2026 Acme Inc. All rights reserved.\n\n",
+  },
+});
+```
+
+```ts
+// types/index.d.ts
+// Copyright (c) 2026 Acme Inc. All rights reserved.
+
+export { default as Button } from "./Button.svelte";
+```
+
+`preamble` only affects the barrel file (`index.d.ts`); per-component `.d.ts` files are untouched.
+
+#### `markdownOptions.onAppend`
+
+`markdownOptions.onAppend` fires on every heading, quote, paragraph, divider, and raw block written to the Markdown document, and receives the block's `type`, the in-progress `WriterMarkdown` document, and the full component map. Use it to inject extra content, e.g. a summary line under the `h1` title.
+
+```js
+import pkg from "./package.json" with { type: "json" };
+
+sveld({
+  markdown: true,
+  markdownOptions: {
+    onAppend: (type, document, components) => {
+      if (type === "h1") {
+        document.append(
+          "quote",
+          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
+        );
+      }
+    },
+  },
+});
+```
+
+```md
+# Component Index
+
+> 1 components exported from sveld-scratch@1.0.0.
+```
+
 ## Documenting Entry Exports
 
 Most entry barrels re-export more than `.svelte` components. Set `documentExports: true` to add consts, functions, and types to the JSON and Markdown output.
@@ -931,6 +999,139 @@ With that in place:
 - [Storybook](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#extracting-argtypes) for web components reads the manifest to auto-generate `argTypes` (controls, docs tables) for `customElement`-compiled components, once you point it at the file (e.g. `setCustomElementsManifest` from `@storybook/web-components`, or `customElements: "custom-elements.json"` in `.storybook/main.js`).
 - Any other tool built against the [Custom Elements Manifest spec](https://github.com/webcomponents/custom-elements-manifest) (API viewers, doc generators, linters) can read the file directly without sveld-specific integration.
 
+## Custom Writers
+
+`json`, `markdown`, `types`, and `custom-elements` are all built on the same
+extensibility point: a small writer registry that third parties can use to
+add new output formats without a core PR. This is a stable, public part of
+sveld's API — the four built-in writers register through it in
+`src/writer/built-in-writers.ts`, there is no separate "internal" path.
+
+### The `OutputWriter` contract
+
+```ts
+interface OutputWriter<TOptions = unknown> {
+  name: string;
+  /** Which component set this writer expects. @default "exported" */
+  componentSet?: "exported" | "all";
+  write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
+}
+```
+
+- **`name`** is how the plugin's `additionalWriters` option (and anything else
+  that calls `getWriter`) looks the writer up. Pick something that won't
+  collide with `types` / `json` / `markdown` / `custom-elements` or another
+  third-party writer.
+- **`componentSet`** picks which map `write` receives:
+  - `"exported"` (the default) — components reachable from the entry barrel,
+    keyed by `moduleName`. This is what `json` / `markdown` /
+    `custom-elements` use.
+  - `"all"` — every `--glob`-discovered `.svelte` file, keyed by resolved
+    `filePath` instead of `moduleName` (two files in different directories
+    can share a basename). This is what `types` uses.
+- **`write`** receives a `ComponentDocs` (`Map<string, ComponentDocApi>`) —
+  the same `ComponentDocApi` shape documented in [JSON Output](#json-output).
+  Don't iterate the raw map yourself; call `buildComponentApiDocument(components, { entryExports })`
+  (also exported from `sveld`) to get the sorted, `diagnostics`-stripped,
+  schema-versioned document the built-in writers build from. It's memoized
+  per `components` map, so calling it more than once in one run is free.
+
+### Registering a writer
+
+```ts
+import { registerWriter } from "sveld";
+
+registerWriter({
+  name: "my-format",
+  write(components, options) {
+    // ...
+  },
+});
+```
+
+`registerWriter` is a side effect — call it once, before the plugin or CLI
+runs, e.g. at the top of `vite.config.ts` or `sveld.config.ts`, or in a file
+either of those imports.
+
+### Running it via the plugin
+
+```ts
+// vite.config.ts
+import sveld from "sveld";
+import "./writers/my-format"; // calls registerWriter as a side effect
+
+export default {
+  plugins: [
+    sveld({
+      additionalWriters: {
+        "my-format": { outFile: "MY_FORMAT.txt" },
+      },
+    }),
+  ],
+};
+```
+
+`additionalWriters` is keyed by the writer's registered `name`; the value is
+whatever options object that writer's `write` expects. An unknown name logs a
+warning and is skipped rather than failing the build. Registered writers run
+alongside whichever built-in outputs (`types` / `json` / `markdown` /
+`customElements`) are also enabled, and the same option is available from the
+programmatic Node API and from `sveld.config.ts` (`additionalWriters` lives on
+the options shared by all three entry points).
+
+### Worked example: a minimal `llms.txt` writer
+
+A plain-text, one-file-per-library summary — the kind of thing
+[llms.txt](https://llmstxt.org)-aware tools look for — is a good demo because
+it needs nothing beyond `ComponentApiDocument`.
+
+```ts
+// writers/llms-writer.ts
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildComponentApiDocument, registerWriter } from "sveld";
+
+interface LlmsWriterOptions {
+  outFile?: string;
+}
+
+registerWriter<LlmsWriterOptions>({
+  name: "llms-demo",
+  componentSet: "exported",
+  write(components, options = {}) {
+    const document = buildComponentApiDocument(components);
+
+    const sections = document.components.map((component) => {
+      const props = component.props.map((prop) => `${prop.name}: ${prop.type ?? "unknown"}`).join(", ");
+      return `## ${component.moduleName}\n\nProps: ${props || "none"}`;
+    });
+
+    const rendered = ["# My Library", "", "> Auto-generated component reference.", "", ...sections].join("\n\n");
+
+    writeFileSync(join(process.cwd(), options.outFile ?? "llms.txt"), rendered);
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import sveld from "sveld";
+import "./writers/llms-writer";
+
+export default {
+  plugins: [
+    sveld({
+      additionalWriters: {
+        "llms-demo": { outFile: "llms.txt" },
+      },
+    }),
+  ],
+};
+```
+
+Running a build now produces an `llms.txt` alongside the usual output, with
+one section per exported component.
+
 ## API Reference
 
 ### `reactive`
@@ -1299,7 +1500,7 @@ The `@typedef` tag defines a shared type used multiple times in a component. All
 
 #### Using `@property` for complex typedefs
 
-For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE.
+For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE. See the [`@property`](#property) reference for the tag's valid contexts.
 
 **Signature:**
 
@@ -1696,6 +1897,35 @@ function render(value: unknown, props: ComponentProps) {
 }
 ```
 
+### `@property`
+
+`@property` documents one field of an object. `sveld` only reads it in two places: directly inside a `@typedef {object}` block, and directly inside an `@event` block (after an explicit `@type {object}`, or with no `@type` at all — `sveld` builds the detail type from the collected `@property` entries). It has no effect anywhere else.
+
+**Valid contexts:**
+
+| Context | Behavior |
+| :- | :- |
+| After `@typedef {object} Name`, in the same comment block | Builds `Name`'s fields. See [Using `@property` for complex typedefs](#using-property-for-complex-typedefs). |
+| After `@event eventname`, in the same comment block | Builds the event's detail type. See [Using `@property` for complex event details](#using-property-for-complex-event-details). |
+| A plain prop with no `@typedef`/`@type {object}` | Not structured. Folded into the prop's description as literal text (`@property name - description`). |
+| Before a `@slot` / `@snippet` line | Dropped entirely — no structured output, and unlike other unrecognized tags in that position, it is not folded into the slot's description either. |
+| Inside `@callback` | Not read. Use `@param` for callback parameters instead. |
+
+**Signature:**
+
+```js
+/**
+ * @typedef {object} TypeName
+ * @property {Type} propertyName - Property description
+ *
+ * @event eventname
+ * @type {object}
+ * @property {Type} propertyName - Property description
+ */
+```
+
+Both forms support the same modifiers as typedef properties elsewhere in this doc: optional properties (`[name]`), default values (`[name=value]`), and nested/discriminated-union shapes. See the linked sections above for full signatures and worked examples with generated output.
+
 ### `@callback`
 
 The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.
@@ -2083,7 +2313,7 @@ export default class Component extends SvelteComponentTyped<
 
 #### Using `@property` for complex event details
 
-For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description.
+For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description. See the [`@property`](#property) reference for the tag's valid contexts.
 
 This is the idiomatic way to describe each field of an event detail. An inline object literal such as `@event {{ items: string[]; added: string[] }} change` types the payload but cannot carry per-field descriptions, since a nested block comment would terminate the host JSDoc. Declare the detail with `@type {object}` and `@property` instead to document every field.
 
@@ -2358,6 +2588,174 @@ label?: string;
 { "name": "label", "deprecated": "Use the `text` prop instead." }
 ```
 
+### `@since`
+
+`@since` records the version a prop, event, or slot was introduced. `sveld` does not validate or parse the version text — whatever follows the tag is copied through as-is.
+
+**Valid contexts:**
+
+- **Prop / module export** — captured as a structured tag: JSON adds a `tags: [{ "name": "since", "body": "..." }]` array on the prop (kept separate from `description`), and the generated `.d.ts` emits `@since ...` as its own JSDoc line above `@default`. **Not rendered in the Markdown table** — the Markdown props/events renderers only read `description`, not `tags` (only the slots renderer does; see [extra tags before `@slot`](#extra-jsdoc-tags-before-slot)).
+- **`@event`** — same structured behavior as props, but only when `@since` is placed **after** the `@event` line in the same comment block (matching the [`@deprecated`](#deprecated) rule for events). Placed before `@event`, it is silently dropped.
+- **`@slot` / `@snippet`** — placed before the `@slot`/`@snippet` line, alongside the description. Fully surfaced in JSON, `.d.ts`, *and* the Markdown table. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported.** A `@since` before `@typedef` produces no output anywhere; it is silently dropped.
+- **`@component` comments** — passed through verbatim as part of the raw HTML comment text. See [@component comments](#component-comments).
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * A width prop.
+   * @since 1.2.0
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * A width prop.
+   * @since 1.2.0
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+Output (JSON, relevant slice):
+
+```json
+{ "name": "width", "description": "A width prop.", "tags": [{ "name": "since", "body": "1.2.0" }] }
+```
+
+The Markdown table for the same prop shows only `A width prop.` in the Description column — `@since` does not appear there.
+
+### `@see`
+
+`@see` adds a reference link or citation. Like `@since`, `sveld` does not resolve or validate the target — it is free text.
+
+**Valid contexts:**
+
+- **Prop / module export** — `@see` is *not* one of the small set of tags `sveld` structures specially, so it is folded verbatim into the prop's `description` as an extra line (`@see ...`) rather than getting its own `tags` entry. Because it lives in `description`, it *does* show up everywhere `description` is used: JSON, `.d.ts`, and the Markdown table.
+- **`@event`** — **not supported in either position** (before or after `@event`). A `@see` tag near an `@event` block is silently dropped in both JSON and `.d.ts`.
+- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`, alongside the description: fully supported in JSON, `.d.ts`, and Markdown, same as `@since`. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported.** Dropped silently, same as `@since`.
+- **`@component` comments** — passed through verbatim, same as `@since`.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * A width prop.
+   * @see https://example.com/width-docs
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * A width prop.
+   * @see https://example.com/width-docs
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+Output (Markdown props table Description column):
+
+```
+A width prop.<br />@see https://example.com/width-docs
+```
+
+### `@link`
+
+`{@link target}` (optionally `{@link target|display text}`) is an inline JSDoc tag used inside prose, not a block-level tag like the others on this page. `sveld`'s comment parser only treats a *line* as starting a new tag when it begins with `@` — `{@link ...}` always starts with `{`, so it's never intercepted. It is always literal text.
+
+**Valid contexts:** anywhere free-form description text is read — prop and module export descriptions, event descriptions, slot descriptions, typedef descriptions, `@component` HTML comments, and `@example` bodies. In every case `sveld` copies it through unchanged, with no link resolution or target validation, into JSON `description`, `.d.ts` JSDoc, and Markdown.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * The element's width in pixels. See {@link https://example.com/width|width docs}.
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * The element's width in pixels. See {@link https://example.com/width|width docs}.
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+The same literal string appears unchanged in JSON `description` and in the Markdown table's Description column.
+
+### `@example`
+
+`@example` has two related uses: as a plain JSDoc tag whose body is copied into generated output, and — with `checkExamples: true` — as input to sveld's compile-checker for plain TS/JS example code. This section covers the tag itself; see [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples) for the type-checking feature.
+
+`@example` shares its underlying mechanism with `@since` (both are in the small set of tags `sveld` treats as structured "IDE passthrough" tags), so the valid contexts are the same:
+
+- **Prop / module export (including functions)** — structured `tags` entry in JSON, its own `@example` block in `.d.ts`. **Not rendered in the Markdown table**, same gap as `@since`.
+- **`@event`** — only when placed **after** the `@event` line in the same block, same rule as `@since`.
+- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`: fully supported in JSON, `.d.ts`, and Markdown. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported**, dropped silently, same as `@since`.
+- **`@component` comments** — passed through verbatim; this is already how the [`@component` comments](#component-comments) example on this page uses `@example`.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * Formats a value.
+   * @param {string} value
+   * @returns {string}
+   * @example
+   * ```js
+   * formatValue("ok");
+   * ```
+   */
+  export function formatValue(value) {
+    return value;
+  }
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+/**
+ * Formats a value.
+ * @example
+ *  ```js
+ *  formatValue("ok");
+ *  ```
+ */
+formatValue: (value: string) => string;
+```
+
+`@param`/`@returns` are consumed into the function's type signature rather than kept as separate JSDoc lines. The Markdown table shows only `Formats a value.` in the Description column — the `@example` block does not appear there.
+
 ### Context API
 
 `sveld` generates TypeScript definitions for Svelte's `setContext`/`getContext` by extracting types from JSDoc on context values.