@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/json-schema-editor/README.md

@@ -25,20 +25,20 @@ Multi-view editor for authoring JSON Schema documents with form, raw JSON, and d
 
 <!-- generated:props:start -->
 
-| Prop            | Type                                       | Required | Default | Description                                                                                                                |
-| --------------- | ------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`                                   | no       | —       |                                                                                                                            |
-| `draftOverride` | `"2020-12"` \| `"2019-09"` \| `"draft-07"` | no       | —       | Force a draft override regardless of $schema.                                                                              |
-| `id`            | `string`                                   | yes      | —       | Required for ARIA wiring.                                                                                                  |
-| `maxHistory`    | `number`                                   | no       | —       | Maximum history entries (default 100).                                                                                     |
-| `readonly`      | `boolean`                                  | no       | —       | Read-only mode disables all mutations.                                                                                     |
-| `schemaKey`     | `string`                                   | no       | —       | Changing this triggers a full reset (history clears).                                                                      |
-| `view`          | `"form"` \| `"json"` \| `"diff"`           | no       | —       | Active view: form / json / diff. Bindable.                                                                                 |
-| `onchange`      | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onrevert`      | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onvalidate`    | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `original`      | `(opaque)`                                 | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `schema`        | `(opaque)`                                 | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop            | Type                                       | Required | Default | Description                                                                                                                                          |
+| --------------- | ------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`         | `string`                                   | no       | —       | Additional class merged onto the `.cinder-jse` root element.                                                                                         |
+| `draftOverride` | `"2020-12"` \| `"2019-09"` \| `"draft-07"` | no       | —       | Force a draft override regardless of $schema.                                                                                                        |
+| `id`            | `string`                                   | yes      | —       | Required for ARIA wiring.                                                                                                                            |
+| `maxHistory`    | `number`                                   | no       | —       | Maximum history entries (default 100).                                                                                                               |
+| `readonly`      | `boolean`                                  | no       | —       | Read-only mode disables all mutations.                                                                                                               |
+| `schemaKey`     | `string`                                   | no       | —       | Changing this triggers a full reset (history clears).                                                                                                |
+| `view`          | `"form"` \| `"json"` \| `"diff"`           | no       | —       | Active view: form / json / diff. Bindable.                                                                                                           |
+| `onchange`      | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+| `onrevert`      | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+| `onvalidate`    | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                           |
+| `original`      | `(opaque)`                                 | no       | —       | Optional explicit baseline; defaults to the initial `schema`. Not expressible in JSON Schema; see the component types for the signature.             |
+| `schema`        | `(opaque)`                                 | yes      | —       | The schema being edited. May be a string (JSON text) or pre-parsed value. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/json-schema-editor/json-schema-editor.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic JSON Schema editor",
       "description": "Edit a flat object schema with form, JSON, and diff views.",
-      "code": "<script lang=\"ts\">\n  import { JsonSchemaEditor } from '@lostgradient/cinder/json-schema-editor';\n  import type { JsonSchemaValue } from '@lostgradient/cinder/json-schema-editor';\n  const personSchema: JsonSchemaValue = {\n    $schema: 'https://json-schema.org/draft/2020-12/schema',\n    title: 'Person',\n    type: 'object',\n    properties: {\n      name: { type: 'string', title: 'Full name', minLength: 1 },\n      age: { type: 'integer', minimum: 0 },\n      email: { type: 'string', format: 'email' },\n    },\n    required: ['name'],\n  };\n</script>\n\n<JsonSchemaEditor id=\"basic-jse\" schema={personSchema} />\n"
+      "code": "<script lang=\"ts\">\n  import { JsonSchemaEditor } from '@lostgradient/cinder/json-schema-editor';\n  import type { JsonSchemaValue } from '@lostgradient/cinder/json-schema-editor';\n\n  const personSchema: JsonSchemaValue = {\n    $schema: 'https://json-schema.org/draft/2020-12/schema',\n    title: 'Person',\n    type: 'object',\n    properties: {\n      name: { type: 'string', title: 'Full name', minLength: 1 },\n      age: { type: 'integer', minimum: 0 },\n      email: { type: 'string', format: 'email' },\n    },\n    required: ['name'],\n  };\n</script>\n\n<JsonSchemaEditor id=\"jse\" schema={personSchema} />\n"
     },
     {
       "id": "composition",

package/src/components/json-schema-editor/json-schema-editor.types.ts

@@ -42,5 +42,6 @@ export type JsonSchemaEditorProps = {
   onchange?: (event: JsonSchemaEditorChangeEvent) => void;
   onrevert?: (event: JsonSchemaEditorRevertEvent) => void;
   onvalidate?: (result: JsonSchemaValidationResult) => void;
+  /** Additional class merged onto the `.cinder-jse` root element. */
   class?: string;
 };

package/src/components/json-viewer/README.md

@@ -16,13 +16,13 @@ Collapsible tree visualization of an arbitrary JSON value with hard depth and by
 
 <!-- generated:props:start -->
 
-| Prop           | Type       | Required | Default | Description                                                                                             |
-| -------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`   | no       | —       | Additional class names merged with `.cinder-json-viewer`.                                               |
-| `initialDepth` | `number`   | no       | —       | Initial collapse depth. Nodes deeper than this start collapsed. Default 1.                              |
-| `maxBytes`     | `number`   | no       | —       | Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).                                      |
-| `maxDepth`     | `number`   | no       | —       | Hard depth cap. Nodes deeper than this never render their children. Default 50.                         |
-| `value`        | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop           | Type       | Required | Default | Description                                                                                                                      |
+| -------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`   | no       | —       | Additional class names merged with `.cinder-json-viewer`.                                                                        |
+| `initialDepth` | `number`   | no       | —       | Initial collapse depth. Nodes deeper than this start collapsed. Default 1.                                                       |
+| `maxBytes`     | `number`   | no       | —       | Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).                                                               |
+| `maxDepth`     | `number`   | no       | —       | Hard depth cap. Nodes deeper than this never render their children. Default 50.                                                  |
+| `value`        | `(opaque)` | yes      | —       | The value to render. Any JSON-serializable structure. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/json-viewer/_json-viewer-node.svelte

@@ -34,10 +34,10 @@
     return Object.entries(value as Record<string, unknown>);
   });
 
-  // The key label renders in a sibling <span> outside the <button>, so a screen
-  // reader announces the toggle without any indication of which node it belongs
-  // to. Compose a distinguishing accessible name from the key (when present) and
-  // the collection shape so sibling toggles are tellable apart.
+  // The key label renders inside the <button> so the focus ring encloses the
+  // full row label + caret. The aria-label on the button provides a distinguishing
+  // accessible name from the key (when present) and the collection shape so
+  // sibling toggles are tellable apart.
   const itemCount = $derived(entries.length);
   const collectionLabel = $derived(
     `${isArray ? 'array' : 'object'}, ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`,
@@ -57,9 +57,6 @@
 
 {#if isObject && !tooDeep}
   <span class={classNames('cinder-json-viewer__node')}>
-    {#if keyName !== undefined}
-      <span class="cinder-json-viewer__key">{keyName}:</span>
-    {/if}
     <button
       type="button"
       class="cinder-json-viewer__toggle"
@@ -67,6 +64,9 @@
       aria-label={toggleLabel}
       onclick={() => (collapsed = !collapsed)}
     >
+      {#if keyName !== undefined}
+        <span class="cinder-json-viewer__key">{keyName}:</span>
+      {/if}
       <span class="cinder-json-viewer__caret" data-cinder-collapsed={collapsed || undefined}></span>
       <span class="cinder-json-viewer__brace">
         {isArray ? '[' : '{'}

package/src/components/json-viewer/json-viewer.css

@@ -50,6 +50,12 @@
     border-radius: var(--cinder-radius-sm);
   }
 
+  @media (hover: hover) {
+    .cinder-json-viewer__toggle:hover {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
   .cinder-json-viewer__toggle:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);

package/src/components/json-viewer/json-viewer.examples.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "json-viewer",
+  "import": "@lostgradient/cinder/json-viewer",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Shallow object",
+      "description": "A flat JSON object with mixed scalar values. The default initialDepth of 1 keeps the top-level keys expanded while deeper nodes start collapsed — useful for at-a-glance inspection.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    id: 'wf_3c4fce',\n    status: 'completed',\n    exitCode: 0,\n    durationMs: 1423,\n    startedAt: '2025-05-12T15:30:00Z',\n    finishedAt: '2025-05-12T15:30:01.423Z',\n    retryCount: 0,\n    triggeredBy: 'schedule',\n  };\n</script>\n\n<JsonViewer value={payload} />\n"
+    },
+    {
+      "id": "nested",
+      "title": "Nested object and array",
+      "description": "Deeply nested objects and arrays with initialDepth={2} so the second level starts expanded. Toggle nodes to drill into child collections — each branch remembers its collapsed state independently.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    workflow: {\n      id: 'wf_3c4fce',\n      name: 'Nightly ETL',\n      steps: [\n        { name: 'extract', status: 'completed', durationMs: 312 },\n        { name: 'transform', status: 'completed', durationMs: 874 },\n        { name: 'load', status: 'completed', durationMs: 237 },\n      ],\n    },\n    metadata: {\n      triggeredBy: 'schedule',\n      region: 'us-east-1',\n      tags: ['etl', 'nightly', 'production'],\n    },\n    result: {\n      rowsProcessed: 84201,\n      rowsSkipped: 3,\n      errors: [],\n    },\n  };\n</script>\n\n<JsonViewer value={payload} initialDepth={2} />\n"
+    },
+    {
+      "id": "oversized",
+      "title": "Oversized payload fallback",
+      "description": "When the serialized payload exceeds maxBytes, JsonViewer renders a fallback instead of attempting the tree. Here maxBytes={256} triggers the cap on a ~500-byte object. Use the copy or download action in the host surface to inspect the raw JSON.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    id: 'act_9f2a1b',\n    type: 'ActivityCompleted',\n    namespace: 'default',\n    workflowId: 'wf_3c4fce',\n    runId: 'run_7d8e2c',\n    activityId: 'act_9f2a1b',\n    activityType: 'ProcessBatch',\n    result: { rowsProcessed: 84201, rowsSkipped: 3, errors: [] },\n    scheduledAt: '2025-05-12T15:30:00Z',\n    startedAt: '2025-05-12T15:30:00.312Z',\n    completedAt: '2025-05-12T15:30:01.186Z',\n    workerIdentity: 'worker@node-42.us-east-1',\n  };\n</script>\n\n<JsonViewer value={payload} maxBytes={256} />\n"
+    },
+    {
+      "id": "payload-inspector",
+      "title": "Payload inspector with copy",
+      "description": "Pairing JsonViewer with CopyButton creates an operational payload inspector. A metadata header names the source event; CopyButton copies the raw JSON to the clipboard so engineers can paste into other tools. This pattern suits fault-detail and activity-result surfaces in operator UIs.",
+      "code": "<script lang=\"ts\">\n  import { CopyButton } from '@lostgradient/cinder/copy-button';\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const eventType = 'ActivityFailed';\n  const payload = {\n    activityType: 'ProcessBatch',\n    activityId: 'act_9f2a1b',\n    workflowId: 'wf_3c4fce',\n    runId: 'run_7d8e2c',\n    failure: {\n      message: 'connection refused',\n      cause: 'redis://cache.internal:6379 unreachable after 3 retries',\n      applicationFailureInfo: {\n        type: 'NetworkError',\n        nonRetryable: false,\n      },\n    },\n    attempt: 2,\n    scheduledAt: '2025-05-12T15:30:42Z',\n    startedAt: '2025-05-12T15:30:42.811Z',\n  };\n\n  const rawJson = $derived(JSON.stringify(payload, null, 2));\n</script>\n\n<div\n  style=\"border: 1px solid var(--cinder-border); border-radius: var(--cinder-radius-md); overflow: hidden;\"\n>\n  <div\n    style=\"display: flex; align-items: center; justify-content: space-between; padding: 0.5rem 0.75rem; background-color: var(--cinder-surface-raised); border-bottom: 1px solid var(--cinder-border);\"\n  >\n    <span style=\"font-size: 0.75rem; font-weight: 600; color: var(--cinder-text-subtle);\"\n      >{eventType}</span\n    >\n    <CopyButton value={rawJson} label=\"Copy raw JSON\" iconOnly />\n  </div>\n  <div style=\"padding: 0.75rem;\">\n    <JsonViewer value={payload} initialDepth={2} />\n  </div>\n</div>\n"
+    },
+    {
+      "id": "primitives",
+      "title": "Primitive and null values",
+      "description": "Each JSON primitive type — string, number, boolean, and null — rendered inline with type-specific color coding. Useful for verifying that scalar fields survive serialization round-trips.",
+      "code": "<script lang=\"ts\">\n  import { JsonViewer } from '@lostgradient/cinder/json-viewer';\n\n  const payload = {\n    label: 'activity-result',\n    count: 42,\n    ratio: 0.9375,\n    active: true,\n    deprecated: false,\n    errorMessage: null,\n    emptyString: '',\n    negativeOffset: -7,\n  };\n</script>\n\n<JsonViewer value={payload} />\n"
+    }
+  ]
+}

package/src/components/kanban-board/README.md

@@ -28,18 +28,18 @@ Controlled multi-column board for reordering cards within and across workflow co
 
 | Prop             | Type       | Required | Default | Description                                                                                                                |
 | ---------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`          | `string`   | no       | —       |                                                                                                                            |
-| `collapsible`    | `boolean`  | no       | —       |                                                                                                                            |
-| `label`          | `string`   | no       | —       |                                                                                                                            |
-| `reorderColumns` | `boolean`  | no       | —       |                                                                                                                            |
-| `card`           | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `class`          | `string`   | no       | —       | Additional class merged onto the `.cinder-kanban-board` root element.                                                      |
+| `collapsible`    | `boolean`  | no       | —       | When true, each column renders a collapse/expand button that toggles its card list.                                        |
+| `label`          | `string`   | no       | —       | Accessible label applied to the board's `<section>` root via `aria-label`.                                                 |
+| `reorderColumns` | `boolean`  | no       | —       | When true (default), columns can be reordered by dragging or keyboard. Set to false to make column order fixed.            |
+| `card`           | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `columnActions`  | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `columnHeader`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `columns`        | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| `columns`        | `(opaque)` | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
 | `emptyColumn`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `getCardKey`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `getCardLabel`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onchange`       | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `getCardKey`     | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `getCardLabel`   | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `onchange`       | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->
 

package/src/components/kanban-board/kanban-board.types.ts

@@ -64,8 +64,12 @@ export type KanbanBoardProps<Card> = {
   columnHeader?: Snippet<[KanbanBoardColumn<Card>, KanbanBoardColumnContext<Card>]>;
   columnActions?: Snippet<[KanbanBoardColumn<Card>, KanbanBoardColumnContext<Card>]>;
   emptyColumn?: Snippet<[KanbanBoardColumn<Card>]>;
+  /** Accessible label applied to the board's `<section>` root via `aria-label`. */
   label?: string;
+  /** When true, each column renders a collapse/expand button that toggles its card list. */
   collapsible?: boolean;
+  /** When true (default), columns can be reordered by dragging or keyboard. Set to false to make column order fixed. */
   reorderColumns?: boolean;
+  /** Additional class merged onto the `.cinder-kanban-board` root element. */
   class?: string;
 };

package/src/components/kbd/README.md

@@ -16,11 +16,12 @@ A styled keyboard key element for displaying keyboard shortcuts in help text and
 
 <!-- generated:props:start -->
 
-| Prop    | Type             | Required | Default | Description                                       |
-| ------- | ---------------- | -------- | ------- | ------------------------------------------------- |
-| `class` | `string`         | no       | —       | Additional class names merged with `.cinder-kbd`. |
-| `label` | `string`         | no       | —       | Key label content.                                |
-| `size`  | `"sm"` \| `"md"` | no       | `"md"`  | Keyboard key size.                                |
+| Prop       | Type             | Required | Default | Description                                                                                   |
+| ---------- | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `class`    | `string`         | no       | —       | Additional class names merged with `.cinder-kbd`.                                             |
+| `label`    | `string`         | no       | —       | Key label content.                                                                            |
+| `size`     | `"sm"` \| `"md"` | no       | `"md"`  | Keyboard key size.                                                                            |
+| `children` | `(opaque)`       | no       | —       | Key label content. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/keyboard-shortcuts/README.md

@@ -25,12 +25,12 @@ Grouped keyboard-shortcut reference that renders key combos via Kbd with accessi
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                                                                                                |
-| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       | Additional class names merged with `.cinder-keyboard-shortcuts`.                                                           |
-| `heading`  | `string`   | no       | —       | Optional heading for the entire shortcuts panel.                                                                           |
-| `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `groups`   | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop       | Type       | Required | Default | Description                                                                                                         |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional class names merged with `.cinder-keyboard-shortcuts`.                                                    |
+| `heading`  | `string`   | no       | —       | Optional heading for the entire shortcuts panel.                                                                    |
+| `children` | `(opaque)` | no       | —       | Intro content rendered above the groups. Not expressible in JSON Schema; see the component types for the signature. |
+| `groups`   | `(opaque)` | yes      | —       | Groups of shortcuts to display. Not expressible in JSON Schema; see the component types for the signature.          |
 
 <!-- generated:props:end -->
 

package/src/components/label/README.md

@@ -16,13 +16,13 @@ Accessible form label that associates descriptive text with its input element.
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                                                                                                |
-| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `disabled` | `boolean`  | no       | —       | When true, render the label in the disabled color treatment.                                                               |
-| `for`      | `string`   | yes      | —       | The id of the form control this label labels. Sets `for` on the rendered `<label>`.                                        |
-| `required` | `boolean`  | no       | —       | When true, append a visual indicator that the field is required.                                                           |
-| `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `class`    | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop       | Type       | Required | Default | Description                                                                                                                    |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `disabled` | `boolean`  | no       | —       | When true, render the label in the disabled color treatment.                                                                   |
+| `for`      | `string`   | yes      | —       | The id of the form control this label labels. Sets `for` on the rendered `<label>`.                                            |
+| `required` | `boolean`  | no       | —       | When true, append a visual indicator that the field is required.                                                               |
+| `children` | `(opaque)` | yes      | —       | The label text or composed content. Not expressible in JSON Schema; see the component types for the signature.                 |
+| `class`    | `(opaque)` | no       | —       | Additional class names merged with `.cinder-label`. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/line-chart/README.md

@@ -26,21 +26,23 @@ Responsive SVG line chart for comparing one or more numeric series over an order
 
 <!-- generated:props:start -->
 
-| Prop                       | Type                                                                                                                   | Required | Default | Description |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| `class`                    | `string`                                                                                                               | no       | —       |             |
-| `dataTableCaption`         | `string`                                                                                                               | no       | —       |             |
-| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                                                                    | no       | —       |             |
-| `description`              | `string`                                                                                                               | no       | —       |             |
-| `height`                   | `number`                                                                                                               | no       | —       |             |
-| `hiddenSeriesIds`          | `string`[]                                                                                                             | no       | —       |             |
-| `label`                    | `string`                                                                                                               | yes      | —       |             |
-| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                                                                      | no       | —       |             |
-| `loading`                  | `boolean`                                                                                                              | no       | —       |             |
-| `maximumInteractivePoints` | `number`                                                                                                               | no       | —       |             |
-| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       |             |
-| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
-| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       |             |
+| Prop                       | Type                                                                                                                   | Required | Default | Description                                                                                                                |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`                    | `string`                                                                                                               | no       | —       | Custom class applied to the root element.                                                                                  |
+| `dataTableCaption`         | `string`                                                                                                               | no       | —       | Custom data table caption; falls back to `label`.                                                                          |
+| `dataTableVisibility`      | `"screen-reader-only"` \| `"visible"` \| `"hidden"`                                                                    | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                              |
+| `description`              | `string`                                                                                                               | no       | —       | Optional description rendered below the label.                                                                             |
+| `height`                   | `number`                                                                                                               | no       | —       | Pixel height of the chart viewport. Default `280`.                                                                         |
+| `hiddenSeriesIds`          | `string`[]                                                                                                             | no       | —       | IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`.                           |
+| `label`                    | `string`                                                                                                               | yes      | —       | Accessible label for the chart. Required for screen readers.                                                               |
+| `legendPosition`           | `"top"` \| `"bottom"` \| `"none"`                                                                                      | no       | —       | Where to render the series legend relative to the chart. Default `top`.                                                    |
+| `loading`                  | `boolean`                                                                                                              | no       | —       | Whether the chart is in a loading state. Default `false`.                                                                  |
+| `maximumInteractivePoints` | `number`                                                                                                               | no       | —       | Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`.                         |
+| `series`                   | ({ color?: `string`; data: ({ x: `string` \| `number`; y?: `number` \| `null` })[]; id: `string`; label: `string` })[] | yes      | —       | Series to render as one or more connected line paths.                                                                      |
+| `xAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       | Configuration for the x-axis label and tick count.                                                                         |
+| `yAxis`                    | { label?: `string`; tickCount?: `number` }                                                                             | no       | —       | Configuration for the y-axis label and tick count.                                                                         |
+| `empty`                    | `(opaque)`                                                                                                             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `loadingContent`           | `(opaque)`                                                                                                             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->
 

package/src/components/line-chart/line-chart.examples.json

@@ -19,6 +19,7 @@
       "id": "single-series",
       "title": "Revenue trend",
       "description": "A single-series line chart for monthly recurring revenue.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { LineChart } from '@lostgradient/cinder/line-chart';\n\n  const series = [\n    {\n      id: 'revenue',\n      label: 'Revenue',\n      data: [\n        { x: 'Jan', y: 120 },\n        { x: 'Feb', y: 148 },\n        { x: 'Mar', y: 172 },\n        { x: 'Apr', y: 196 },\n      ],\n    },\n  ];\n</script>\n\n<LineChart label=\"Monthly recurring revenue\" {series} dataTableVisibility=\"visible\" />\n"
     }
   ]

package/src/components/line-chart/line-chart.types.ts

@@ -27,17 +27,30 @@ export type LineChartSchemaSeries = {
 };
 
 export type LineChartSchemaProps = {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Configuration for the x-axis label and tick count. */
   xAxis?: ChartAxisSchemaConfiguration;
+  /** Configuration for the y-axis label and tick count. */
   yAxis?: ChartAxisSchemaConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
   legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
   hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
   maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
   class?: string;
+  /** Series to render as one or more connected line paths. */
   series: LineChartSchemaSeries[];
 };

package/src/components/link/README.md

@@ -33,8 +33,8 @@ Inline text link with consistent focus ring and underline behavior.
 | `href`      | `string`                            | no       | —           | The URL the link points to. Optional ONLY because a `disabled` link renders a `<span>` with no href. For any enabled (non-disabled) link you must provide it — an `<a>` without `href` is not keyboard-focusable and is not exposed as a link to assistive technology, so an enabled Link without `href` is a bug, not a feature. |
 | `rel`       | `string` \| `null`                  | no       | —           | Forwarded to the rendered `<a>`. `"noopener noreferrer"` is merged in whenever the link opens in a new tab — `external` is true OR the resolved target is `"_blank"` (case-insensitive) — and the whole value is de-duplicated case-insensitively.                                                                                |
 | `underline` | `"always"` \| `"hover"` \| `"none"` | no       | `"hover"`   | Controls text-decoration behavior. - `'always'` — underline is always visible. - `'hover'` — underline appears on hover and focus (default). - `'none'` — underline is never shown.                                                                                                                                               |
-| `children`  | `(opaque)`                          | no       | —           | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                        |
-| `target`    | `(opaque)`                          | no       | —           | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                           |
+| `children`  | `(opaque)`                          | yes      | —           | The link text or composed content. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                           |
+| `target`    | `(opaque)`                          | no       | —           | Forwarded to the rendered `<a>`. `external` supplies `"_blank"` only when no target is given. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/load-more/README.md

@@ -28,19 +28,19 @@ Sentinel-based infinite-scroll trigger with an always-visible button fallback an
 
 <!-- generated:props:start -->
 
-| Prop               | Type       | Required | Default | Description                                                                                                                |
-| ------------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `buttonLabel`      | `string`   | no       | —       | Visible label for the load-more button.                                                                                    |
-| `class`            | `string`   | no       | —       | Custom class merged with `.cinder-load-more`.                                                                              |
-| `endOfListMessage` | `string`   | no       | —       | Politely announced when the end of the list is reached.                                                                    |
-| `hasMore`          | `boolean`  | no       | —       | Whether more items are available. Bindable.                                                                                |
-| `loading`          | `boolean`  | no       | —       | Whether a load is in progress. Bindable.                                                                                   |
-| `maxRetries`       | `number`   | no       | —       | Maximum consecutive sentinel-triggered requests before auto-loading pauses.                                                |
-| `retryLabel`       | `string`   | no       | —       | Visible label for the retry button after a load error.                                                                     |
-| `rootMargin`       | `string`   | no       | —       | rootMargin passed to IntersectionObserver. Captured at attachment time.                                                    |
-| `onError`          | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onLoadMore`       | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `root`             | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop               | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                     |
+| ------------------ | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `buttonLabel`      | `string`   | no       | —       | Visible label for the load-more button.                                                                                                                                                                                                                                                                         |
+| `class`            | `string`   | no       | —       | Custom class merged with `.cinder-load-more`.                                                                                                                                                                                                                                                                   |
+| `endOfListMessage` | `string`   | no       | —       | Politely announced when the end of the list is reached.                                                                                                                                                                                                                                                         |
+| `hasMore`          | `boolean`  | no       | —       | Whether more items are available. Bindable.                                                                                                                                                                                                                                                                     |
+| `loading`          | `boolean`  | no       | —       | Whether a load is in progress. Bindable.                                                                                                                                                                                                                                                                        |
+| `maxRetries`       | `number`   | no       | —       | Maximum consecutive sentinel-triggered requests before auto-loading pauses.                                                                                                                                                                                                                                     |
+| `retryLabel`       | `string`   | no       | —       | Visible label for the retry button after a load error.                                                                                                                                                                                                                                                          |
+| `rootMargin`       | `string`   | no       | —       | rootMargin passed to IntersectionObserver. Captured at attachment time.                                                                                                                                                                                                                                         |
+| `onError`          | `(opaque)` | no       | —       | Notified when onLoadMore throws or rejects. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                          |
+| `onLoadMore`       | `(opaque)` | no       | —       | Called when the next page should be loaded. Caller flips `loading` and `hasMore`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                    |
+| `root`             | `(opaque)` | no       | —       | Scroll container the sentinel is observed within. Pass the scrollable ancestor element when the list scrolls inside a container rather than the viewport. `null`/omitted observes against the viewport. Captured at attachment time. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/markdown-editor/README.md

@@ -39,17 +39,17 @@ Rich Markdown editing surface bundling a Milkdown-powered ProseMirror editor, to
 | `showToolbar`           | `boolean`                 | no       | —       | Show formatting toolbar (DEP-37)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `snapshotMode`          | `boolean`                 | no       | —       | Snapshot mode for visual regression testing. When `true`: - Applies `caret-color: transparent` and `user-select: none` to the editor root via a `data-snapshot-mode` attribute, producing a stable visual state (no blinking cursor, no selection highlights). - Blurs any focused element inside the component on mount so the initial screenshot does not capture a focused ring or active caret. This is a purely visual / CSS concern. It does NOT affect editability, ProseMirror state, or any prop controlled by `readonly` / `mode`. |
 | `value`                 | `string`                  | no       | —       | Current markdown content (two-way bindable)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `onchange`              | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onCommentShortcut`     | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onmodechange`          | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onReady`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `onSelectionChange`     | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `placeholderCompletion` | `(opaque)`                | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `placeholderDecoration` | `(opaque)`                | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `plugins`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbar`               | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbarActions`        | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `toolbarLeading`        | `(opaque)`                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `onchange`              | `(opaque)`                | no       | —       | Called when content changes Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `onCommentShortcut`     | `(opaque)`                | no       | —       | Called when comment shortcut (Ctrl-Alt-c) is pressed (DEP-47) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `onmodechange`          | `(opaque)`                | no       | —       | Called when editor mode changes Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `onReady`               | `(opaque)`                | no       | —       | Called when the editor is ready (Milkdown initialized) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `onSelectionChange`     | `(opaque)`                | no       | —       | Called when selection changes (stub for DEP-39) Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `placeholderCompletion` | `(opaque)`                | no       | —       | Placeholder completion configuration (DEP-583). When provided, enables inline suggestion menu for {{…}} tokens in WYSIWYG mode. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                   |
+| `placeholderDecoration` | `(opaque)`                | no       | —       | Placeholder decoration configuration (DEP-583). When provided, decorates invalid {{…}} tokens with CSS class and data attributes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                 |
+| `plugins`               | `(opaque)`                | no       | —       | Additional Milkdown plugins to load. Used for comment anchoring (DEP-39), decorations, and other extensions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                      |
+| `toolbar`               | `(opaque)`                | no       | —       | Custom toolbar content. When provided, replaces default toolbar. Receives ToolbarContext for building custom toolbar UI. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                          |
+| `toolbarActions`        | `(opaque)`                | no       | —       | Additional toolbar actions (appended to default toolbar). Use this for adding buttons without replacing the entire toolbar. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                       |
+| `toolbarLeading`        | `(opaque)`                | no       | —       | Leading toolbar content (prepended before default toolbar items). Useful for adding undo/redo or other leading actions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                           |
 
 <!-- generated:props:end -->
 

package/src/components/markdown-editor/markdown-editor.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic markdown editor",
       "description": "A Milkdown-backed editor with toolbar and source mode toggle.",
-      "code": "<script lang=\"ts\">\n  import { MarkdownEditor } from '@lostgradient/cinder/markdown-editor';\n  let value = $state(`# Release notes\n\nThis editor supports **rich markdown editing**, toolbar actions, and a source mode.\n\n- Write in markdown\n- Switch between rendered and source modes\n- Keep the value bindable`);\n</script>\n\n<div style=\"display: grid; gap: 0.75rem;\">\n  <MarkdownEditor id=\"playground-markdown-editor\" bind:value showToolbar showModeToggle />\n  <p style=\"margin: 0; color: var(--cinder-text-muted);\">\n    Characters: {value.length}\n  </p>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { MarkdownEditor } from '@lostgradient/cinder/markdown-editor';\n\n  let value = $state(`# Release notes\n\nThis editor supports **rich markdown editing**, toolbar actions, and a source mode.\n\n- Write in markdown\n- Switch between rendered and source modes\n- Keep the value bindable`);\n</script>\n\n<div style=\"display: grid; gap: 0.75rem;\">\n  <MarkdownEditor id=\"editor\" bind:value showToolbar showModeToggle />\n  <p style=\"margin: 0; color: var(--cinder-text-muted);\">\n    Characters: {value.length}\n  </p>\n</div>\n"
     }
   ]
 }

package/src/components/masonry/README.md

@@ -0,0 +1,49 @@
+# Masonry
+
+Masonry renders a pure CSS waterfall layout with balanced variable-height
+columns. It uses CSS columns, so DOM and screen-reader order remain
+top-to-bottom through each column rather than left-to-right across visual rows.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Masonry } from '@lostgradient/cinder/masonry';
+</script>
+
+<Masonry columns="3" gap="var(--cinder-space-4)">
+  <article>Short card</article>
+  <article>Much taller card content</article>
+  <article>Medium card</article>
+</Masonry>
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop       | Type       | Required | Default | Description                                                                                  |
+| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
+| `as`       | `string`   | no       | —       | Rendered HTML tag.                                                                           |
+| `class`    | `string`   | no       | —       | Custom class merged with `.cinder-masonry`.                                                  |
+| `columns`  | `string`   | no       | —       | CSS column count value.                                                                      |
+| `gap`      | `string`   | no       | —       | Gap between columns and between direct children.                                             |
+| `children` | `(opaque)` | yes      | —       | Masonry contents. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/masonry/index.ts

@@ -0,0 +1,6 @@
+import './masonry.css';
+import Masonry from './masonry.svelte';
+
+export default Masonry;
+export type { MasonryProps } from './masonry.types.ts';
+export { Masonry };