sveld 0.31.0 → 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)
@@ -333,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`
@@ -350,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`