sveld 0.32.1 → 0.32.3

package/README.md

@@ -849,6 +849,80 @@ export type ComponentProps = {
 
 > **Note:** The inline syntax `@typedef {{ name: string }} User` continues to work for backwards compatibility.
 
+#### Discriminated unions
+
+A `@typedef` can be a union of object literals, optionally mixed with primitive members. `sveld` emits these as `export type X = ...` aliases (not `interface`), so the discriminant narrows correctly on the consumer side.
+
+**Signature:**
+
+```js
+/**
+ * @typedef {A | B | C} TypeName
+ */
+```
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * @typedef {{ kind: "success"; value: string } | { kind: "error"; error: Error }} Result
+   * @typedef {{ ok: true; data: number } | { ok: false; reason: string } | "pending"} Status
+   */
+
+  /** @type {Result} */
+  export let result = { kind: "success", value: "ok" };
+
+  /** @type {Status} */
+  export let status = "pending";
+</script>
+```
+
+Output:
+
+```ts
+export type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };
+
+export type Status = { ok: true; data: number } | { ok: false; reason: string } | "pending";
+
+export type ComponentProps = {
+  /** @default { kind: "success", value: "ok" } */
+  result?: Result;
+  /** @default "pending" */
+  status?: Status;
+};
+```
+
+Consumers can then narrow on the discriminant:
+
+```ts
+function describe(r: Result) {
+  switch (r.kind) {
+    case "success":
+      return r.value;
+    case "error":
+      return r.error.message;
+  }
+}
+```
+
+The same pattern works inline via `@type`, which is useful when the union is only used for a single prop:
+
+```js
+/** @type {{ kind: "success"; value: string } | { kind: "error"; error: Error }} */
+export let result = { kind: "success", value: "ok" };
+```
+
+In `<script lang="ts">` components, write the type alias directly — `sveld` preserves it in the emitted `.d.ts`:
+
+```svelte
+<script lang="ts">
+  type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };
+
+  let { result = { kind: "success", value: "ok" } }: { result?: Result } = $props();
+</script>
+```
+
 ### `@callback`
 
 The `@callback` tag defines a function type using `@param` and `@returns` tags, following the [TypeScript JSDoc `@callback` specification](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated TypeScript definition file.
@@ -1410,6 +1484,41 @@ export default class Component extends SvelteComponentTyped<
 > {}
 ```
 
+#### Discriminated unions in event details
+
+When the event detail is a union (or any non-object shape), use `@type` to declare it directly. An explicit `@type` takes precedence over `@property` tags, so the union is preserved verbatim in the emitted `.d.ts` rather than being flattened into independent property unions. The special form `@type {object}` is the only exception — it signals that the shape should be built from the `@property` tags (as shown above).
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * @event sort
+   * @type {{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }}
+   * Dispatched when a sortable column header would change the active sort.
+   */
+
+  import { createEventDispatcher } from "svelte";
+
+  const dispatch = createEventDispatcher();
+</script>
+```
+
+Output:
+
+```ts
+export default class Component extends SvelteComponentTyped<
+  ComponentProps,
+  {
+    /** Dispatched when a sortable column header would change the active sort. */
+    sort: CustomEvent<{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }>;
+  },
+  Record<string, never>
+> {}
+```
+
+Any free-text prose after the tags is attached to the event description, not to a property doc.
+
 ### Context API
 
 `sveld` automatically generates TypeScript definitions for Svelte's `setContext`/`getContext` API by extracting types from JSDoc annotations on the context values.