sveld 0.30.3 → 0.32.0

package/README.md

@@ -127,6 +127,7 @@ export default class Button extends SvelteComponentTyped<
   - [CLI](#cli)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
+- [JSON Output](#json-output)
 - [API Reference](#api-reference)
   - [@type](#type)
   - [@default](#default)
@@ -139,6 +140,7 @@ export default class Button extends SvelteComponentTyped<
   - [Context API](#context-api)
   - [@restProps](#restprops)
   - [@extendProps](#extendprops)
+  - [@template](#template)
   - [@generics](#generics)
   - [@component comments](#component-comments)
   - [Accessor Props](#accessor-props)
@@ -332,6 +334,121 @@ sveld({
 })
 ```
 
+## JSON Output
+
+When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
+component API.
+
+The public JSON Schema for the combined output is hosted on GitHub ([path to file](https://github.com/carbon-design-system/sveld/blob/main/schema/component-api.schema.json), [raw URL](https://raw.githubusercontent.com/carbon-design-system/sveld/main/schema/component-api.schema.json)). Use it to document or validate
+generated `COMPONENT_API.json` files. The schema describes the emitted metadata contract; optional fields may be absent when
+the parser does not have a stable source for that metadata.
+
+```ts
+interface ComponentApiJson {
+  schemaVersion: 1;
+  generator: {
+    name: string;
+    version: string;
+    svelteVersion: string;
+  };
+  total: number;
+  components: ComponentDocApi[];
+}
+
+interface SourceRange {
+  start: SourcePosition;
+  end: SourcePosition;
+}
+
+interface SourcePosition {
+  line: number;
+  column: number;
+}
+
+interface ComponentDocApi {
+  moduleName: string;
+  filePath: string;
+  source?: SourceRange;
+  syntaxMode: "legacy" | "runes";
+  scriptLanguage?: "js" | "ts";
+  props: ComponentProp[];
+  moduleExports: ComponentProp[];
+  slots: ComponentSlot[];
+  events: ComponentEvent[];
+  typedefs: TypeDef[];
+  generics: null | [name: string, type: string];
+  rest_props?: RestProps;
+  extends?: { interface: string; import: string };
+  componentComment?: string;
+  componentCommentSource?: SourceRange;
+  contexts?: ComponentContext[];
+}
+
+interface ComponentProp {
+  name: string;
+  localName?: string;
+  kind: "let" | "const" | "function";
+  constant: boolean;
+  type?: string;
+  typeSource?: "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
+  value?: string;
+  defaultValue?: {
+    raw: string;
+    kind: "literal" | "array" | "object" | "expression" | "function" | "unknown";
+    value?: unknown;
+  };
+  description?: string;
+  params?: Array<{ name: string; type: string; description?: string; optional?: boolean }>;
+  returnType?: string;
+  isFunction: boolean;
+  isFunctionDeclaration: boolean;
+  isRequired: boolean;
+  reactive: boolean;
+  binding?: "readonly" | "writable";
+  bindable?: true;
+  source?: SourceRange;
+}
+
+interface ComponentSlot {
+  name?: string | null;
+  default: boolean;
+  fallback?: string;
+  slot_props?: string;
+  description?: string;
+  tags?: Array<{ name: string; body: string }>;
+  source?: SourceRange;
+}
+
+type ComponentEvent =
+  | {
+      type: "forwarded";
+      name: string;
+      element: string;
+      description?: string;
+      detail?: string;
+      source?: SourceRange;
+    }
+  | {
+      type: "dispatched";
+      name: string;
+      detail?: string;
+      description?: string;
+      source?: SourceRange;
+    };
+```
+
+`source` fields are optional and are included only when the Svelte or JavaScript AST provides stable positions. They do not
+include source text or raw character offsets.
+
+Note that `SourcePosition.line` is 1-based and `SourcePosition.column` is 0-based.
+
+Prop metadata is additive and preserves the older public fields:
+
+- `name` is always the public prop name. For runes `$props()` aliases such as `let { class: className } = $props()`, `localName` is emitted only when the local binding differs.
+- `typeSource` identifies the conservative source of the emitted `type`: TypeScript annotation, JSDoc, initializer/default inference, other parser inference, or unknown fallback.
+- `value` remains the raw default expression string. `defaultValue` adds structured metadata with the same raw expression, a coarse `kind`, and a parsed `value` only for JSON-safe literals, arrays, and plain objects. `sveld` does not evaluate arbitrary code.
+- `bindable: true` is emitted only for props explicitly declared with Svelte 5 `$bindable(...)`. Missing `bindable` should be treated as false.
+
 ## API Reference
 
 ### `reactive`
@@ -349,6 +466,38 @@ Local variables or parameters that shadow a prop name do not count as writes to
 
 `reactive: false` means `sveld` found no such evidence. It does not imply that parent-side `bind:` usage is impossible.
 
+### `binding`
+
+The optional `binding` field in generated JSON is explicit documentation metadata for a prop's intended `bind:` contract. It is separate from `reactive`, and it is never inferred from internal writes or `$bindable()`.
+
+Use `@bindable readonly` for component-owned or output-style bindings where the consumer binds to the current value emitted by the component:
+
+```svelte
+<script>
+  /**
+   * Bind to the current value emitted by the component.
+   * @bindable readonly
+   */
+  export let size = undefined;
+</script>
+```
+
+Use `@bindable writable` for two-way or shared state bindings where either the consumer or component may control the value:
+
+```svelte
+<script>
+  /**
+   * Bind to state controlled by either the consumer or component.
+   * @bindable writable
+   */
+  export let open = false;
+</script>
+```
+
+Generated JSON includes `"binding": "readonly"` or `"binding": "writable"` for annotated props. Unannotated props omit the field.
+
+This is documentation metadata only. Generated `.svelte.d.ts` prop types are unchanged because TypeScript cannot reliably express Svelte component binding direction.
+
 For stable output, generated `events` arrays are emitted in deterministic sorted order.
 
 ### `@type`
@@ -1544,24 +1693,22 @@ export const secondary = true;
 import Button from "./Button.svelte";
 ```
 
-### `@generics`
+### `@template`
 
-Currently, to define generics for a Svelte component, you must use [`generics` attribute](https://github.com/dummdidumm/rfcs/blob/bfb14dc56a70ec6ddafebf2242b8e1500e06a032/text/ts-typing-props-slots-events.md#generics) on the script tag. Note that this feature is [experimental](https://svelte.dev/docs/typescript#experimental-advanced-typings) and may change in the future.
-
-However, the `generics` attribute only works if using `lang="ts"`; the language server will produce an error if `generics` is used without specifying `lang="ts"`.
+Svelte supports defining generics via the [`generics` attribute](https://svelte.dev/docs/svelte/typescript) on the script tag, but this requires `lang="ts"`.
 
 ```svelte
-<!-- This causes an error because `lang="ts"` must be used. -->
-<script generics="Row extends DataTableRow = any"></script>
+<!-- Requires lang="ts" -->
+<script lang="ts" generics="Row extends DataTableRow = any"></script>
 ```
 
-Because `sveld` is designed to support JavaScript-only usage as a baseline, the API design to specify generics uses a custom JSDoc tag `@generics`.
+Because `sveld` is designed to support JavaScript-only usage as a baseline, the API design to specify generics uses the standard JSDoc `@template` tag. The `@generics` tag is also supported as an alias.
 
-**Signature:**
+**Signature:** Uses standard [JSDoc `@template` syntax](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template):
 
 ```js
 /**
- * @generics {GenericParameter} GenericName
+ * @template {Constraint} [Name=Default]
  */
 ```
 
@@ -1569,7 +1716,7 @@ Because `sveld` is designed to support JavaScript-only usage as a baseline, the
 
 ```js
 /**
- * @generics {Row extends DataTableRow = any} Row
+ * @template {DataTableRow} [Row=DataTableRow]
  */
 ```
 
@@ -1624,13 +1771,12 @@ Because `sveld` is designed to support JavaScript-only usage as a baseline, the
 The generated TypeScript definition will resemble the following:
 
 ```ts
-// Props type includes the full constraint, enabling indexed access types like Row["id"]
-export type ComponentProps<Row extends DataTableRow = any> = {
+export type ComponentProps<Row extends DataTableRow = DataTableRow> = {
   rows?: ReadonlyArray<Row>;
 };
 
 export default class Component<
-  Row extends DataTableRow = any,
+  Row extends DataTableRow = DataTableRow,
 > extends SvelteComponentTyped<
   ComponentProps<Row>,
   Record<string, any>,
@@ -1638,24 +1784,57 @@ export default class Component<
 > {}
 ```
 
-For a parameter list, the name should be comma-separated but not include spaces.
+For multiple generics, use separate `@template` tags:
 
 ```js
 /**
- * @generics {Param1, Param2} Name1,Name2
+ * @template {DataTableRow} [Row=DataTableRow]
+ * @template {DataTableRow} [Header=DataTableRow]
  */
 ```
 
 ```ts
-export type ComponentProps<Param1, Param2> = { ... };
+export type ComponentProps<
+  Row extends DataTableRow = DataTableRow,
+  Header extends DataTableRow = DataTableRow,
+> = { ... };
 
-export default class Component<Param1, Param2> extends SvelteComponentTyped<
-  ComponentProps<Name1, Name2>,
+export default class Component<
+  Row extends DataTableRow = DataTableRow,
+  Header extends DataTableRow = DataTableRow,
+> extends SvelteComponentTyped<
+  ComponentProps<Row, Header>,
   Record<string, any>,
   Record<string, any>
 > {}
 ```
 
+### `@generics`
+
+As an alternative to `@template`, sveld also supports a custom `@generics` tag. Unlike `@template`, which is [officially supported by JSDoc/TypeScript](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template), `@generics` is sveld-specific. However, its syntax can be more readable since the full constraint is written inline:
+
+```js
+/**
+ * @generics {Row extends DataTableRow = DataTableRow} Row
+ */
+```
+
+This is equivalent to:
+
+```js
+/**
+ * @template {DataTableRow} [Row=DataTableRow]
+ */
+```
+
+For multiple generics, use a single `@generics` tag with comma-separated names:
+
+```js
+/**
+ * @generics {Row extends DataTableRow = DataTableRow, Header extends DataTableRow = DataTableRow} Row,Header
+ */
+```
+
 ### `@component` comments
 
 The Svelte Language Server supports component-level comments through the following syntax: `<!-- @component [comment] -->`.