@lostgradient/cinder 0.1.1 → 0.3.0

package/src/components/code-block/code-block.examples.json

@@ -9,6 +9,12 @@
       "description": "Multi-line preformatted code.",
       "code": "<script lang=\"ts\">\n  import { CodeBlock } from '@lostgradient/cinder/code-block';\n  const code = `function greet(name: string): string {\n  return \\`Hello, \\${name}!\\`;\n}\n\nconst message = greet('world');`;\n</script>\n\n<CodeBlock {code} />\n"
     },
+    {
+      "id": "delayed-highlighting",
+      "title": "Delayed highlighting",
+      "description": "Colorization can resolve after first paint while the code block keeps its dimensions.",
+      "code": "<script lang=\"ts\">\n  import { CodeBlock } from '@lostgradient/cinder';\n\n  const code = `SELECT id, name, created_at, email_address, account_status, last_seen_at, billing_plan, feature_flags\nFROM users\nWHERE active = true\nORDER BY created_at DESC\nLIMIT 10;`;\n\n  const highlightedHtml = `<pre class=\"shiki\" style=\"background-color:#fff;color:#24292e\"><code>${escapeHtml(\n    code,\n  )}</code></pre>`;\n\n  type LayoutHighlighterWindow = Window & {\n    cinderCodeBlockLayoutHighlighterReady?: boolean;\n    resolveCinderCodeBlockLayoutHighlight?: () => void;\n  };\n\n  if (typeof window !== 'undefined') {\n    (window as LayoutHighlighterWindow).cinderCodeBlockLayoutHighlighterReady = false;\n  }\n\n  function escapeHtml(value: string): string {\n    return value\n      .replaceAll('&', '&amp;')\n      .replaceAll('<', '&lt;')\n      .replaceAll('>', '&gt;')\n      .replaceAll('\"', '&quot;')\n      .replaceAll(\"'\", '&#39;');\n  }\n\n  function highlighter(): Promise<string> {\n    return new Promise((resolve) => {\n      if (typeof window === 'undefined') return;\n      const target = window as LayoutHighlighterWindow;\n      target.resolveCinderCodeBlockLayoutHighlight = () => resolve(highlightedHtml);\n      target.cinderCodeBlockLayoutHighlighterReady = true;\n    });\n  }\n</script>\n\n<CodeBlock {code} language=\"sql\" {highlighter} />\n"
+    },
     {
       "id": "with-language",
       "title": "With language label and copy",

package/src/components/code-block/code-block.svelte

@@ -36,9 +36,10 @@
   // Two-phase render contract: the server (and the first client paint) emits
   // the plain `<pre><code>` fallback because `$effect` never runs during SSR.
   // The effect below — client-only by definition — enhances the block to the
-  // highlighted HTML once the highlighter resolves. Keeping the Shiki boundary
-  // a dynamic import inside this effect is what keeps Shiki out of the SSR
-  // bundle and the consumer's entry chunk.
+  // highlighted HTML once the highlighter resolves. The outer viewport stays
+  // mounted across both phases so syntax colorization cannot move surrounding
+  // layout. Keeping the Shiki boundary a dynamic import inside this effect is
+  // what keeps Shiki out of the SSR bundle and the consumer's entry chunk.
   $effect(() => {
     // `highlight={false}` is an absolute off switch: it disables ALL
     // highlighting — including an explicit `highlighter` prop — and triggers
@@ -109,38 +110,32 @@
       {/if}
     </header>
   {/if}
-  <!-- The svelte:boundary catches errors thrown during render of {@html highlighted}
-       (e.g. a malformed HTML string that breaks Svelte's reconciliation). Sync/async
-       errors from the highlighter ITSELF are caught above; this is the secondary net. -->
-  <!-- `{@html}` reconciliation across string→string transitions strands the
-       previous DOM nodes when they're emitted as direct children of an
-       `{#if}` branch (Svelte 5: the prior nodes share the same parent and
-       no anchor scopes them). Wrap the `{@html}` output in a stable
-       container `<div>` so the previous render is contained inside an
-       element Svelte can replace in place. -->
-  <svelte:boundary>
-    {#if highlighted !== null}
-      <!-- tabindex="0" makes this scroll container keyboard-reachable so
-           keyboard-only users can scroll long highlighted code snippets
-           (WCAG 2.1 SC 2.1.1; axe scrollable-region-focusable). The div
-           owns overflow-x: auto in CSS; the inner shiki <pre> is clipped
-           so there is exactly one focusable scroll region. No role="region":
-           a landmark per code block would flood landmark navigation with
-           identically-named "Code" regions on docs pages with many snippets —
-           tabindex alone satisfies the keyboard-scroll requirement. -->
-      <div class="cinder-code-block__highlighted" tabindex="0">
-        {@html highlighted}
-      </div>
-    {:else}
-      <!-- tabindex="0" makes the plain-code scroll container keyboard-reachable. -->
-      <pre class="cinder-code-block__pre" tabindex="0"><code class="cinder-code-block__code"
-          >{code}</code
-        ></pre>
-    {/if}
-    {#snippet failed()}
-      <pre class="cinder-code-block__pre" tabindex="0"><code class="cinder-code-block__code"
-          >{code}</code
-        ></pre>
-    {/snippet}
-  </svelte:boundary>
+  <!-- One stable, focusable scroll viewport is shared by plain, highlighted,
+       and fallback states. Keep tabindex unconditional so overflowing snippets
+       are keyboard-scrollable before measurement. -->
+  <div class="cinder-code-block__viewport" tabindex="0">
+    <!-- The svelte:boundary catches errors thrown during render of {@html highlighted}
+         (e.g. a malformed HTML string that breaks Svelte's reconciliation). Sync/async
+         errors from the highlighter ITSELF are caught above; this is the secondary net. -->
+    <!-- `{@html}` reconciliation across string→string transitions strands the
+         previous DOM nodes when they're emitted as direct children of an
+         `{#if}` branch (Svelte 5: the prior nodes share the same parent and
+         no anchor scopes them). Wrap the `{@html}` output in a stable
+         container `<div>` so the previous render is contained inside an
+         element Svelte can replace in place. -->
+    <svelte:boundary>
+      {#if highlighted !== null}
+        <div class="cinder-code-block__highlighted">
+          {@html highlighted}
+        </div>
+      {:else}
+        <pre class="cinder-code-block__pre"><code class="cinder-code-block__code">{code}</code
+          ></pre>
+      {/if}
+      {#snippet failed()}
+        <pre class="cinder-code-block__pre"><code class="cinder-code-block__code">{code}</code
+          ></pre>
+      {/snippet}
+    </svelte:boundary>
+  </div>
 </div>

package/src/components/code-block/code-block.types.ts

@@ -9,11 +9,12 @@ import type { Highlighter } from '../../utilities/highlighter.ts';
  * Syntax highlighting is automatic: when `language` is set, CodeBlock
  * lazy-loads the bundled `@lostgradient/cinder/highlighters/shiki` adapter on the client and
  * enhances the block once it resolves. The server (and the first client paint)
- * always emits the plain `<pre><code>` fallback — highlighting is a two-phase,
- * client-only enhancement, so there is a brief flash before the highlighted
- * HTML swaps in. Pass `highlight={false}` to keep `language` semantics (the
- * header label) with zero highlighting and zero Shiki import. Pass a custom
- * `highlighter` to override the bundled default per instance.
+ * always emits the plain `<pre><code>` fallback. Highlighting is a two-phase,
+ * client-only enhancement: colorization may appear after first paint, but the
+ * stable viewport keeps the block's layout from moving. Pass
+ * `highlight={false}` to keep `language` semantics (the header label) with
+ * zero highlighting and zero Shiki import. Pass a custom `highlighter` to
+ * override the bundled default per instance.
  */
 export type CodeBlockProps = {
   /** The code to render. */
@@ -26,7 +27,9 @@ export type CodeBlockProps = {
    * `highlight={false}` is an absolute off switch: it disables ALL
    * highlighting — including an explicit `highlighter` prop — and triggers no
    * Shiki import. The block renders the escaped plain `<pre><code>` fallback
-   * while keeping the `language` header label.
+   * while keeping the `language` header label. When highlighting is enabled,
+   * client-side colorization may appear after first paint, but the block keeps
+   * stable layout metrics.
    */
   highlight?: boolean;
   /**

package/src/components/collapsible/README.md

@@ -49,13 +49,15 @@ For multiple coordinated sections where opening one may close others, use [`Acco
 
 <!-- generated:props:start -->
 
-| Prop       | Type      | Required | Default | Description                                                                         |
-| ---------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------- |
-| `class`    | `string`  | no       | —       | Additional classes merged onto the root element.                                    |
-| `disabled` | `boolean` | no       | `false` | When true, the trigger cannot be toggled.                                           |
-| `idBase`   | `string`  | no       | —       | Base used to derive the trigger and panel ARIA ids. Auto-generated when omitted.    |
-| `open`     | `boolean` | no       | `false` | Bindable open state. Without binding, the initial value the component then manages. |
-| `trigger`  | `string`  | yes      | —       | Trigger label text. (The snippet form is template-only; see the type above.)        |
+| Prop       | Type       | Required | Default | Description                                                                                                                                                      |
+| ---------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional classes merged onto the root element.                                                                                                                 |
+| `disabled` | `boolean`  | no       | `false` | When true, the trigger cannot be toggled.                                                                                                                        |
+| `idBase`   | `string`   | no       | —       | Base used to derive the trigger and panel ARIA ids. Auto-generated when omitted.                                                                                 |
+| `open`     | `boolean`  | no       | `false` | Bindable open state. Without binding, the initial value the component then manages.                                                                              |
+| `trigger`  | `string`   | yes      | —       | Trigger label text. (The snippet form is template-only; see the type above.)                                                                                     |
+| `children` | `(opaque)` | yes      | —       | Panel content shown when open. Not expressible in JSON Schema; see the component types for the signature.                                                        |
+| `onToggle` | `(opaque)` | no       | —       | Fired on every successful toggle with the next open state. Not called while disabled. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/color-field/README.md

@@ -77,7 +77,7 @@ Moving the component across forms at runtime is not supported in v1.
 | `readonly`       | `boolean`                                 | no       | —       | Render the inner `<input>` as read-only.                                                                                                                                                                                                                                                                                                    |
 | `required`       | `boolean`                                 | no       | —       | Mark the input as required for form submission and a11y.                                                                                                                                                                                                                                                                                    |
 | `value`          | `string`                                  | no       | —       | Controlled value as a hex string. One-way: parent sets, child reads. Not bindable — use `onchange` to observe commits. Accepts any color string the configured `formats` allow when set externally.                                                                                                                                         |
-| `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.                                                                                                                                                                                                                  |
+| `onchange`       | `(opaque)`                                | no       | —       | Fires on successful blur-time commit when the canonical hex actually changes. Value callback by repo convention — not forwarded to the inner native `<input>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                   |
 
 <!-- generated:props:end -->
 

package/src/components/color-field/color-field.css

@@ -36,20 +36,17 @@
 
   .cinder-color-field__swatch[data-cinder-alpha]:not([data-cinder-empty]) {
     /* structural-pattern: transparency checkerboard so partially-transparent
-     * swatches stay visible — a fixed light/neutral grid signalling "see-through",
-     * not a themeable surface. Raw values declared once here with markers. */
-    --_cinder-color-field-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-field-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
-    background-color: var(--_cinder-color-field-checker-base);
+     * swatches stay visible while following the shared checker tokens. */
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(
         var(--cinder-color-field-swatch, transparent),
         var(--cinder-color-field-swatch, transparent)
       ),
-      linear-gradient(45deg, var(--_cinder-color-field-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-field-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-field-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-field-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       6px 6px,

package/src/components/color-field/color-field.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic color field",
       "description": "An uncontrolled color field that accepts hex, rgb(), and hsl() strings and normalizes them to hex on commit.",
-      "code": "<script lang=\"ts\">\n  import { ColorField } from '@lostgradient/cinder/color-field';\n\n  let committed = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; max-width: 20rem;\">\n  <label for=\"color-field-basic\" style=\"font-size: 0.875rem; font-weight: 500;\">\n    Brand color\n  </label>\n  <ColorField\n    id=\"color-field-basic\"\n    defaultValue=\"#3b82f6\"\n    onchange={(value) => {\n      committed = value;\n    }}\n  />\n  {#if committed}\n    <p style=\"font-size: 0.75rem; color: var(--cinder-text-muted);\">Committed: {committed}</p>\n  {/if}\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { ColorField } from '@lostgradient/cinder/color-field';\n\n  let committed = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; max-width: 20rem;\">\n  <label for=\"field\" style=\"font-size: 0.875rem; font-weight: 500;\"> Brand color </label>\n  <ColorField\n    id=\"field\"\n    defaultValue=\"#3b82f6\"\n    onchange={(value) => {\n      committed = value;\n    }}\n  />\n  {#if committed}\n    <p style=\"font-size: 0.75rem; color: var(--cinder-text-muted);\">Committed: {committed}</p>\n  {/if}\n</div>\n"
     },
     {
       "id": "states",

package/src/components/color-picker/README.md

@@ -26,8 +26,8 @@ Full-featured input for selecting a color via hue, saturation, lightness, and he
 | `name`         | `string`   | no       | —       | Form field name. When set, a hidden input mirrors the current value for form submission.                                                                                                                                   |
 | `swatches`     | `string`[] | no       | —       | Optional palette of preset colors rendered below the picker.                                                                                                                                                               |
 | `value`        | `string`   | no       | —       | Bindable value. Reading the value yields a hex string (`#rrggbb`, or `#rrggbbaa` when `alpha` is true). Setting the value accepts hex, `rgb()`, `rgba()`, `hsl()`, or `hsla()` input; invalid input is normalized to `''`. |
-| `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.                                                                                                 |
-| `oninput`      | `(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       | —       | Fired on commit (pointer up, swatch click, slider key). Not expressible in JSON Schema; see the component types for the signature.                                                                                         |
+| `oninput`      | `(opaque)` | no       | —       | Fired on every intermediate update (drag, slider key, swatch click). Not expressible in JSON Schema; see the component types for the signature.                                                                            |
 
 <!-- generated:props:end -->
 

package/src/components/color-picker/color-picker.css

@@ -13,12 +13,21 @@
     width: 100%;
     max-width: 280px;
 
-    /* structural-pattern: the transparency checkerboard (shown behind alpha
-     * channels by the alpha slider and the preview chip) is a fixed light/neutral
-     * grid that signals "see-through", not a themeable surface. Declared once here
-     * and reused by both checkerboards below so the raw values have a single home. */
-    --_cinder-color-picker-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-picker-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
+    /* structural-pattern: the thumb sits over arbitrary picked colors, so the
+     * white ring and dark edge stay fixed; dark chrome gets one extra outer ring. */
+    --_cinder-color-picker-thumb-border: #fff; /* cinder-allow-raw-color: structural-pattern — thumb contrast ring over arbitrary picked color */
+    /* prettier-ignore */
+    --_cinder-color-picker-thumb-shadow-edge: rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — thumb outline over arbitrary picked color */
+    --_cinder-color-picker-thumb-shadow-support-light: transparent;
+    /* prettier-ignore */
+    --_cinder-color-picker-thumb-shadow-support-dark: rgba(255, 255, 255, 0.65); /* cinder-allow-raw-color: structural-pattern — thumb outline over dark chrome */
+    --_cinder-color-picker-thumb-shadow-support: light-dark(
+      var(--_cinder-color-picker-thumb-shadow-support-light),
+      var(--_cinder-color-picker-thumb-shadow-support-dark)
+    );
+    --_cinder-color-picker-thumb-shadow:
+      0 0 0 1px var(--_cinder-color-picker-thumb-shadow-edge),
+      0 0 0 2px var(--_cinder-color-picker-thumb-shadow-support);
   }
 
   .cinder-color-picker[data-cinder-disabled] {
@@ -62,12 +71,11 @@
     width: 14px;
     height: 14px;
     /* structural-pattern: the draggable thumb sits over the user's chosen color,
-     * so its white ring + dark outline are fixed contrast devices (visible on any
-     * hue), not themeable chrome. */
-    border: 2px solid #fff; /* cinder-allow-raw-color: structural-pattern — thumb contrast ring over arbitrary picked color */
+     * so its white ring + contrast outline are hue-agnostic devices. */
+    border: 2px solid var(--_cinder-color-picker-thumb-border);
     border-radius: 50%;
     transform: translate(-50%, -50%);
-    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — thumb dark outline for contrast on light hues */
+    box-shadow: var(--_cinder-color-picker-thumb-shadow);
     pointer-events: none;
   }
 
@@ -92,13 +100,13 @@
   }
 
   .cinder-color-picker__alpha {
-    background-color: var(--_cinder-color-picker-checker-base);
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(to right, transparent, var(--cinder-color-picker-base, currentColor)),
-      linear-gradient(45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,
@@ -126,13 +134,12 @@
     width: 14px;
     height: 14px;
     /* structural-pattern: slider thumb sits over the hue rail / alpha
-     * checkerboard, so its white ring + dark outline are fixed contrast devices,
-     * not themeable chrome (same rationale as the gradient handle). */
-    border: 2px solid #fff; /* cinder-allow-raw-color: structural-pattern — slider thumb contrast ring */
+     * checkerboard, so its ring + outline follow the gradient handle. */
+    border: 2px solid var(--_cinder-color-picker-thumb-border);
     border-radius: 50%;
     background: transparent;
     transform: translate(-50%, -50%);
-    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — slider thumb dark outline */
+    box-shadow: var(--_cinder-color-picker-thumb-shadow);
     pointer-events: none;
   }
 
@@ -154,16 +161,16 @@
   }
 
   .cinder-color-picker__preview[data-cinder-alpha] {
-    background-color: var(--_cinder-color-picker-checker-base);
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(
         var(--cinder-color-picker-preview, transparent),
         var(--cinder-color-picker-preview, transparent)
       ),
-      linear-gradient(45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,

package/src/components/color-swatch-picker/README.md

@@ -16,19 +16,19 @@ Presents a fixed palette of color swatches for constrained color selection.
 
 <!-- generated:props:start -->
 
-| Prop           | Type                                           | Required | Default | Description                                                                                                                                                                                                       |
-| -------------- | ---------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                                       | no       | —       | Additional classes merged into the listbox `<ul>`.                                                                                                                                                                |
-| `defaultValue` | `string`                                       | no       | —       | Initial selected color for uncontrolled use. Ignored when `value` is set.                                                                                                                                         |
-| `disabled`     | `boolean`                                      | no       | —       | Disables the entire listbox. Keyboard activation and clicks are ignored.                                                                                                                                          |
-| `label`        | `string`                                       | yes      | —       | Accessible name for the listbox. Required — `role="listbox"` needs a label so screen readers can announce the control's purpose.                                                                                  |
-| `layout`       | `"grid"` \| `"stack"`                          | no       | —       | Layout direction. Default `'grid'`. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo. |
-| `shape`        | `"circle"` \| `"square"`                       | no       | —       | Visual shape of each swatch. Default `'circle'`.                                                                                                                                                                  |
-| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Swatch dimension token. Default `'md'`.                                                                                                                                                                           |
-| `value`        | `string`                                       | no       | —       | Controlled selected color. When provided, the parent owns the state.                                                                                                                                              |
-| `colors`       | `(opaque)`                                     | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                           |
-| `indicator`    | `(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.                                                                                        |
+| Prop           | Type                                           | Required | Default | Description                                                                                                                                                                                                                        |
+| -------------- | ---------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                                       | no       | —       | Additional classes merged into the listbox `<ul>`.                                                                                                                                                                                 |
+| `defaultValue` | `string`                                       | no       | —       | Initial selected color for uncontrolled use. Ignored when `value` is set.                                                                                                                                                          |
+| `disabled`     | `boolean`                                      | no       | —       | Disables the entire listbox. Keyboard activation and clicks are ignored.                                                                                                                                                           |
+| `label`        | `string`                                       | yes      | —       | Accessible name for the listbox. Required — `role="listbox"` needs a label so screen readers can announce the control's purpose.                                                                                                   |
+| `layout`       | `"grid"` \| `"stack"`                          | no       | —       | Layout direction. Default `'grid'`. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo.                  |
+| `shape`        | `"circle"` \| `"square"`                       | no       | —       | Visual shape of each swatch. Default `'circle'`.                                                                                                                                                                                   |
+| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Swatch dimension token. Default `'md'`.                                                                                                                                                                                            |
+| `value`        | `string`                                       | no       | —       | Controlled selected color. When provided, the parent owns the state.                                                                                                                                                               |
+| `colors`       | `(opaque)`                                     | yes      | —       | Palette to render. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                      |
+| `indicator`    | `(opaque)`                                     | no       | —       | Snippet that replaces the default check-icon indicator on the selected swatch. Receives the active swatch and the computed contrast color for the icon. Not expressible in JSON Schema; see the component types for the signature. |
+| `onchange`     | `(opaque)`                                     | no       | —       | Fired when the selected swatch changes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                 |
 
 <!-- generated:props:end -->
 

package/src/components/color-swatch-picker/color-swatch-picker.css

@@ -71,17 +71,14 @@
 
   .cinder-color-swatch-picker__swatch[data-cinder-alpha] {
     /* structural-pattern: transparency checkerboard beneath the color layer — a
-     * fixed light/neutral grid signalling "see-through", not a themeable surface.
-     * Raw values declared once here with markers. */
-    --_cinder-color-swatch-picker-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-swatch-picker-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
-    background-color: var(--_cinder-color-swatch-picker-checker-base);
+     * shared grid signalling "see-through" in both light and dark chrome. */
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(var(--swatch-color), var(--swatch-color)),
-      linear-gradient(45deg, var(--_cinder-color-swatch-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-swatch-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-swatch-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-swatch-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,

package/src/components/combobox/README.md

@@ -28,9 +28,9 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
 | `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
 | `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
-| `filter`            | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                             |
-| `options`           | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                |
-| `value`             | `(opaque)` | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                               |
+| `filter`            | `(opaque)` | no       | —       | Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label. Not expressible in JSON Schema; see the component types for the signature.     |
+| `options`           | `(opaque)` | yes      | —       | Full set of options to filter. The sole inference source for T. Not expressible in JSON Schema; see the component types for the signature.                                                                                             |
+| `value`             | `(opaque)` | no       | —       | Currently selected value. Bindable. `''` when nothing is selected. Not expressible in JSON Schema; see the component types for the signature.                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/combobox/combobox.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic combobox",
       "description": "Type to filter; the list is filtered with a case-insensitive substring match.",
-      "code": "<script lang=\"ts\">\n  import { Combobox } from '@lostgradient/cinder/combobox';\n  const fruits = [\n    { value: 'apple', label: 'Apple' },\n    { value: 'apricot', label: 'Apricot' },\n    { value: 'banana', label: 'Banana' },\n    { value: 'blackberry', label: 'Blackberry' },\n    { value: 'cherry', label: 'Cherry' },\n    { value: 'grape', label: 'Grape' },\n    { value: 'mango', label: 'Mango' },\n    { value: 'peach', label: 'Peach' },\n    { value: 'pineapple', label: 'Pineapple' },\n    { value: 'raspberry', label: 'Raspberry' },\n  ];\n\n  let selected = $state('');\n</script>\n\n<Combobox\n  id=\"combobox-fruit\"\n  label=\"Favorite fruit\"\n  placeholder=\"Start typing…\"\n  options={fruits}\n  bind:value={selected}\n/>\n"
+      "code": "<script lang=\"ts\">\n  import { Combobox } from '@lostgradient/cinder/combobox';\n\n  const fruits = [\n    { value: 'apple', label: 'Apple' },\n    { value: 'apricot', label: 'Apricot' },\n    { value: 'banana', label: 'Banana' },\n    { value: 'blackberry', label: 'Blackberry' },\n    { value: 'cherry', label: 'Cherry' },\n    { value: 'grape', label: 'Grape' },\n    { value: 'mango', label: 'Mango' },\n    { value: 'peach', label: 'Peach' },\n    { value: 'pineapple', label: 'Pineapple' },\n    { value: 'raspberry', label: 'Raspberry' },\n  ];\n\n  let selected = $state('');\n</script>\n\n<Combobox\n  id=\"fruit\"\n  label=\"Favorite fruit\"\n  placeholder=\"Start typing…\"\n  options={fruits}\n  bind:value={selected}\n/>\n"
     },
     {
       "id": "disabled",

package/src/components/combobox/combobox.svelte

@@ -25,6 +25,7 @@
     describeId,
     errorId as buildErrorId,
   } from '../../_internal/field-control.ts';
+  import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
 
@@ -75,6 +76,7 @@
   let activeIndex = $state(-1);
   let inputElement = $state<HTMLInputElement | null>(null);
   let listboxElement = $state<HTMLElement | null>(null);
+  let committedLabel = $state('');
 
   // Reset active index whenever the filtered set changes so we don't point
   // at a stale option.
@@ -92,14 +94,57 @@
       // Clearing the value (deselect/reset) must also clear the visible text;
       // otherwise the input keeps showing the previously selected option's label.
       if (untrack(() => inputValue)) inputValue = '';
+      committedLabel = '';
       return;
     }
     const matched = options.find((option) => option.value === value);
-    if (matched && untrack(() => inputValue) !== matched.label) {
-      inputValue = matched.label;
+    if (matched) {
+      // `committedLabel` tracks the committed `value`'s label and must stay in
+      // sync whenever a match exists — even when `inputValue` already shows that
+      // label. Gating it behind the `inputValue !== matched.label` check left
+      // `committedLabel` stale (''), so a later Escape restored to empty text.
+      committedLabel = matched.label;
+      if (untrack(() => inputValue) !== matched.label) {
+        inputValue = matched.label;
+      }
     }
   });
 
+  // Escape ownership.
+  //
+  // The combobox is the single Escape owner for the whole time it is open. The
+  // option Popover is told `closeOnEscape={false}`, so it never registers its
+  // own escape-stack handler — otherwise, while options are visible, the
+  // Popover's handler would sit on top of the shared LIFO stack and shadow this
+  // one. With the Popover opting out, this combobox's handler is the top-most
+  // Escape consumer for the entire open session, including the empty-filter gap
+  // (`open && filteredOptions.length === 0`) where the Popover is unmounted.
+  //
+  // That matters most when the combobox is nested inside a Modal/Sheet: the
+  // shared escape stack's window listener is capture-phase and invokes ONLY its
+  // top handler, so this combobox consumes Escape and `preventDefault()`s it
+  // before the parent overlay ever sees the key — Escape dismisses just the
+  // combobox, never the enclosing overlay.
+  function handleEscape(event?: KeyboardEvent): void {
+    const wasOpen = open;
+    open = false;
+    // Restore the committed label whenever the live text drifted from it.
+    if (inputValue !== committedLabel) {
+      inputValue = committedLabel;
+      if (inputElement) inputElement.value = committedLabel;
+    }
+    // Swallow the key if the combobox actually consumed this Escape (it was
+    // open) so the same keystroke doesn't also dismiss an enclosing overlay or
+    // trigger a page-level default.
+    if (wasOpen) event?.preventDefault();
+  }
+
+  $effect(() => {
+    if (!open) return;
+    const releaseEscape = pushEscapeHandler(handleEscape);
+    return releaseEscape;
+  });
+
   const activeOptionId = $derived(
     activeIndex >= 0 && activeIndex < filteredOptions.length
       ? `${id}-option-${activeIndex}`
@@ -124,12 +169,20 @@
     const next = event.relatedTarget as Node | null;
     if (next && listboxElement?.contains(next)) return;
     open = false;
+    // Restore the committed label if the live text drifted from it. Leaving the
+    // field on a stale edit (without selecting an option) would desync the
+    // visible text from the unchanged `value` — the same mismatch Escape fixes.
+    if (inputValue !== committedLabel) {
+      inputValue = committedLabel;
+      if (inputElement) inputElement.value = committedLabel;
+    }
   }
 
   function selectOption(option: ComboboxOption<T>) {
     if (option.disabled) return;
     value = option.value;
     inputValue = option.label;
+    committedLabel = option.label;
     open = false;
   }
 
@@ -159,10 +212,14 @@
         selectOption(option);
       }
     } else if (event.key === 'Escape') {
-      if (open) {
-        event.preventDefault();
-        open = false;
-      }
+      // Fallback path. In a real browser the capture-phase escape-stack listener
+      // (installed by the $effect's pushEscapeHandler) runs first and has
+      // already closed + restored + preventDefault'd; `defaultPrevented` is true
+      // here and we bail. This branch only does real work when the stack
+      // listener never ran — SSR/no-window environments where `window` is
+      // absent so `pushEscapeHandler` installed nothing.
+      if (event.defaultPrevented) return;
+      handleEscape(event);
     }
   }
 </script>
@@ -208,6 +265,7 @@
       role="listbox"
       focusManagement="preserve"
       wireTriggerAria={false}
+      closeOnEscape={false}
       widthMode="match-anchor"
       class="cinder-combobox__panel"
     >

package/src/components/command-item/README.md

@@ -16,17 +16,17 @@ Individual selectable row within a command palette or dropdown command list.
 
 <!-- generated:props:start -->
 
-| Prop            | Type                   | Required | Default | Description                                                                                                                |
-| --------------- | ---------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                  |
-| `description`   | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                        |
-| `disabled`      | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                      |
-| `selectionMode` | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                         |
-| `value`         | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                 |
-| `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. |
-| `leading`       | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onselect`      | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `trailing`      | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop            | Type                   | Required | Default | Description                                                                                                                               |
+| --------------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`         | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                                 |
+| `description`   | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                                       |
+| `disabled`      | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                                     |
+| `selectionMode` | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                                        |
+| `value`         | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                                |
+| `children`      | `(opaque)`             | yes      | —       | Main label content. Not expressible in JSON Schema; see the component types for the signature.                                            |
+| `leading`       | `(opaque)`             | no       | —       | Leading content (icon, avatar). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature.     |
+| `onselect`      | `(opaque)`             | no       | —       | Invoked when the item is activated inside CommandPalette. Not expressible in JSON Schema; see the component types for the signature.      |
+| `trailing`      | `(opaque)`             | no       | —       | Trailing content (kbd hint, badge). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->