@lostgradient/cinder 0.1.0 → 0.2.0

package/src/components/chat/message/tool-call-group.svelte

@@ -182,10 +182,16 @@
   /* Focus: ring travels via box-shadow, not outline, so it sits inside the
    * card's colored border instead of doubling up on top of it. */
   .tool-call-header:focus-visible {
-    /* cinder-focus-ring-owner: parent — this header self-owns its inset
-       box-shadow ring; the outline is intentionally suppressed. */
-    outline: none;
-    box-shadow: inset 0 0 0 var(--cinder-ring-width) var(--cinder-ring-color);
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width)
+      var(--_cinder-tool-call-header-ring, var(--cinder-ring-color));
+  }
+
+  @media (forced-colors: active) {
+    .tool-call-header:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+    }
   }
 
   .tool-call-icon {

package/src/components/choice-grid/README.md

@@ -0,0 +1,66 @@
+# ChoiceGrid
+
+Responsive grid of large selectable choices with roving keyboard focus, selection state, and optional correct/incorrect/pending feedback for quiz and assessment surfaces.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';
+
+  let selected = $state<string | null>(null);
+</script>
+
+<ChoiceGrid ariaLabel="Choose a difficulty" bind:value={selected}>
+  <ChoiceGrid.Item value="easy">Easy</ChoiceGrid.Item>
+  <ChoiceGrid.Item value="medium">Medium</ChoiceGrid.Item>
+  <ChoiceGrid.Item value="hard">Hard</ChoiceGrid.Item>
+</ChoiceGrid>
+```
+
+## Guidance
+
+### Use When
+
+- Presenting a small fixed set of large selectable answers where all options should stay visible (quiz or assessment surfaces).
+- Building a touch-friendly selector grid with stable cell dimensions that must not shift when feedback states are applied.
+
+### Avoid When
+
+- Selecting from a long dynamic list — use combobox or select instead.
+- Choosing one of two to five short values in a compact inline context — use segmented-control instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop             | Type                                       | Required | Default | Description                                                                                                                                                                                                                   |
+| ---------------- | ------------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ariaLabel`      | `string`                                   | no       | —       | Accessible label for the grid (required unless `ariaLabelledby` is set).                                                                                                                                                      |
+| `ariaLabelledby` | `string`                                   | no       | —       | Id of an external element that labels this grid.                                                                                                                                                                              |
+| `columns`        | `"responsive"` \| `1` \| `2` \| `3` \| `4` | no       | —       | Column layout. - `'responsive'` — `auto-fill` at a minimum cell width (default). - `1 \| 2 \| 3 \| 4` — fixed number of columns.                                                                                              |
+| `disabled`       | `boolean`                                  | no       | —       | Disables all items in the grid.                                                                                                                                                                                               |
+| `minColumnWidth` | `string`                                   | no       | —       | Minimum cell width for `columns="responsive"`. Accepts any CSS `<length>` (e.g. `"12rem"`, `"200px"`). Default: `"10rem"`.                                                                                                    |
+| `multiple`       | `boolean`                                  | no       | —       | When true the grid allows multiple simultaneous selections and reads/writes `values` instead of `value`. The ARIA role switches to `group` (items become `checkbox`); single-select uses `radiogroup` (items become `radio`). |
+| `value`          | `string` \| `null`                         | no       | —       | The currently selected value (single-select mode). Bindable. Pass `null` or omit to start with no selection.                                                                                                                  |
+| `values`         | `string`[]                                 | no       | —       | Currently selected values (multi-select mode). Bindable. Only used when `multiple` is `true` — set `multiple` explicitly to switch modes; binding `values` alone does NOT enable multi-select.                                |
+| `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.                                                                                                                       |
+
+<!-- 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/choice-grid/choice-grid-context.ts

@@ -0,0 +1,30 @@
+import { createContext } from 'svelte';
+
+import type { ChoiceGridContext } from './choice-grid.types.ts';
+
+export type { ChoiceGridContext };
+
+/**
+ * Context published by `<ChoiceGrid>` for descendant `<ChoiceGridItem>` children.
+ *
+ * All members are getter properties on the context object so reads stay
+ * reactive — when a consumer reads `context.value` inside a `$derived`,
+ * the read flows through the getter which returns a value recomputed from
+ * ChoiceGrid's `$derived` internals. Destructuring breaks reactivity;
+ * getter reads preserve it.
+ *
+ * The context is *required* — a `<ChoiceGridItem>` outside a `<ChoiceGrid>` is a
+ * programmer error. The `getChoiceGridContext` getter therefore throws
+ * (via Svelte 5's `createContext`) when no provider exists.
+ */
+
+const [getChoiceGridContextStrict, setChoiceGridContext] = createContext<ChoiceGridContext>();
+
+export { setChoiceGridContext };
+
+/**
+ * Read the enclosing `<ChoiceGrid>` context. Throws via Svelte 5's
+ * `createContext` when no provider exists — a `<ChoiceGridItem>` rendered
+ * outside a `<ChoiceGrid>` is a programmer error.
+ */
+export const getChoiceGridContext = getChoiceGridContextStrict;

package/src/components/choice-grid/choice-grid.css

@@ -0,0 +1,27 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@import '../choice-grid-item/choice-grid-item.css';
+
+@layer cinder.components {
+  /* ========================================
+   * CHOICE GRID — parent container
+   * ======================================== */
+
+  .cinder-choice-grid {
+    /* Default grid layout: responsive auto-fill. Overridden by the
+     * --cinder-choice-grid-columns inline style set from the `columns` prop. */
+    display: grid;
+    grid-template-columns: var(
+      --cinder-choice-grid-columns,
+      repeat(auto-fill, minmax(min(10rem, 100%), 1fr))
+    );
+    gap: var(--cinder-space-3);
+    inline-size: 100%;
+  }
+
+  /* Disabled grid dims every item. Individual item disabled states also apply. */
+  .cinder-choice-grid[data-cinder-disabled] {
+    opacity: 0.6;
+    pointer-events: none;
+  }
+}

package/src/components/choice-grid/choice-grid.examples.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "choice-grid",
+  "import": "@lostgradient/cinder/choice-grid",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic single-select",
+      "description": "A simple quiz question with four answer options and roving keyboard focus.",
+      "code": "<script lang=\"ts\">\n  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';\n\n  let selected = $state<string | null>(null);\n</script>\n\n<ChoiceGrid ariaLabel=\"What is the capital of France?\" bind:value={selected}>\n  <ChoiceGrid.Item value=\"london\">London</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"berlin\">Berlin</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"paris\">Paris</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"madrid\">Madrid</ChoiceGrid.Item>\n</ChoiceGrid>\n\n{#if selected}\n  <p style=\"margin-top: 1rem; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n    Selected: {selected}\n  </p>\n{/if}\n"
+    },
+    {
+      "id": "dense-layout",
+      "title": "Dense phone layout",
+      "description": "Fixed 2-column grid with compact cells — suitable for narrow mobile viewports.",
+      "code": "<script lang=\"ts\">\n  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';\n\n  let selected = $state<string | null>(null);\n</script>\n\n<div style=\"max-width: 20rem; margin: 0 auto;\">\n  <ChoiceGrid ariaLabel=\"Choose a difficulty\" bind:value={selected} columns={2}>\n    <ChoiceGrid.Item value=\"easy\">Easy</ChoiceGrid.Item>\n    <ChoiceGrid.Item value=\"medium\">Medium</ChoiceGrid.Item>\n    <ChoiceGrid.Item value=\"hard\">Hard</ChoiceGrid.Item>\n    <ChoiceGrid.Item value=\"expert\">Expert</ChoiceGrid.Item>\n  </ChoiceGrid>\n</div>\n"
+    },
+    {
+      "id": "feedback-states",
+      "title": "Feedback states",
+      "description": "Correct, incorrect, and pending states for quiz and assessment surfaces. Cell dimensions stay stable across states.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';\n  import type { ChoiceGridItemState } from '@lostgradient/cinder/choice-grid';\n\n  let selected = $state<string | null>(null);\n  let revealed = $state(false);\n\n  const correctAnswer = 'paris';\n\n  function getState(value: string): ChoiceGridItemState {\n    if (!revealed || selected === null) return 'neutral';\n    if (value === correctAnswer) return 'correct';\n    if (value === selected && value !== correctAnswer) return 'incorrect';\n    return 'neutral';\n  }\n</script>\n\n<ChoiceGrid ariaLabel=\"What is the capital of France?\" bind:value={selected}>\n  <ChoiceGrid.Item value=\"london\" state={getState('london')}>London</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"berlin\" state={getState('berlin')}>Berlin</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"paris\" state={getState('paris')}>Paris</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"madrid\" state={getState('madrid')}>Madrid</ChoiceGrid.Item>\n</ChoiceGrid>\n\n<div style=\"margin-top: 1rem; display: flex; gap: 0.5rem; flex-wrap: wrap;\">\n  <Button variant=\"secondary\" onclick={() => (revealed = !revealed)}>\n    {revealed ? 'Hide feedback' : 'Reveal answer'}\n  </Button>\n  <Button\n    variant=\"ghost\"\n    onclick={() => {\n      selected = null;\n      revealed = false;\n    }}\n  >\n    Reset\n  </Button>\n</div>\n"
+    },
+    {
+      "id": "multi-select",
+      "title": "Multi-select",
+      "description": "Toggle multiple answers simultaneously — useful for checkboxes presented as large tiles.",
+      "code": "<script lang=\"ts\">\n  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';\n\n  let selected = $state<string[]>([]);\n</script>\n\n<ChoiceGrid multiple ariaLabel=\"Which topics interest you?\" bind:values={selected} columns={2}>\n  <ChoiceGrid.Item value=\"design\">Design</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"engineering\">Engineering</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"product\">Product</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"data\">Data</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"marketing\">Marketing</ChoiceGrid.Item>\n  <ChoiceGrid.Item value=\"leadership\">Leadership</ChoiceGrid.Item>\n</ChoiceGrid>\n\n{#if selected.length > 0}\n  <p style=\"margin-top: 1rem; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n    Selected: {selected.join(', ')}\n  </p>\n{/if}\n"
+    }
+  ]
+}

package/src/components/choice-grid/choice-grid.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "value": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The currently selected value (single-select mode). Bindable.\nPass `null` or omit to start with no selection."
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Currently selected values (multi-select mode). Bindable. Only used when\n`multiple` is `true` — set `multiple` explicitly to switch modes; binding\n`values` alone does NOT enable multi-select."
+    },
+    "multiple": {
+      "type": "boolean",
+      "description": "When true the grid allows multiple simultaneous selections and reads/writes\n`values` instead of `value`. The ARIA role switches to `group` (items become\n`checkbox`); single-select uses `radiogroup` (items become `radio`)."
+    },
+    "columns": {
+      "enum": ["responsive", 1, 2, 3, 4],
+      "description": "Column layout.\n- `'responsive'` — `auto-fill` at a minimum cell width (default).\n- `1 | 2 | 3 | 4` — fixed number of columns."
+    },
+    "minColumnWidth": {
+      "type": "string",
+      "description": "Minimum cell width for `columns=\"responsive\"`. Accepts any CSS\n`<length>` (e.g. `\"12rem\"`, `\"200px\"`). Default: `\"10rem\"`."
+    },
+    "ariaLabel": {
+      "type": "string",
+      "description": "Accessible label for the grid (required unless `ariaLabelledby` is set)."
+    },
+    "ariaLabelledby": {
+      "type": "string",
+      "description": "Id of an external element that labels this grid."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disables all items in the grid."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "class",
+        "reason": "unknown-shape"
+      }
+    ]
+  }
+}

package/src/components/choice-grid/choice-grid.schema.ts

@@ -0,0 +1,70 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      anyOf: [
+        {
+          type: 'string',
+        },
+        {
+          type: 'null',
+        },
+      ],
+      description:
+        'The currently selected value (single-select mode). Bindable.\nPass `null` or omit to start with no selection.',
+    },
+    values: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      description:
+        'Currently selected values (multi-select mode). Bindable. Only used when\n`multiple` is `true` — set `multiple` explicitly to switch modes; binding\n`values` alone does NOT enable multi-select.',
+    },
+    multiple: {
+      type: 'boolean',
+      description:
+        'When true the grid allows multiple simultaneous selections and reads/writes\n`values` instead of `value`. The ARIA role switches to `group` (items become\n`checkbox`); single-select uses `radiogroup` (items become `radio`).',
+    },
+    columns: {
+      enum: ['responsive', 1, 2, 3, 4],
+      description:
+        "Column layout.\n- `'responsive'` — `auto-fill` at a minimum cell width (default).\n- `1 | 2 | 3 | 4` — fixed number of columns.",
+    },
+    minColumnWidth: {
+      type: 'string',
+      description:
+        'Minimum cell width for `columns="responsive"`. Accepts any CSS\n`<length>` (e.g. `"12rem"`, `"200px"`). Default: `"10rem"`.',
+    },
+    ariaLabel: {
+      type: 'string',
+      description: 'Accessible label for the grid (required unless `ariaLabelledby` is set).',
+    },
+    ariaLabelledby: {
+      type: 'string',
+      description: 'Id of an external element that labels this grid.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disables all items in the grid.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'class',
+        reason: 'unknown-shape',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/choice-grid/choice-grid.svelte

@@ -0,0 +1,272 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status alpha
+   * @purpose Responsive grid of large selectable choices with roving keyboard focus, selection state, and optional correct/incorrect/pending feedback for quiz and assessment surfaces.
+   * @tag form
+   * @tag selection
+   * @tag quiz
+   * @tag assessment
+   * @useWhen Presenting a small fixed set of large selectable answers where all options should stay visible (quiz or assessment surfaces).
+   * @useWhen Building a touch-friendly selector grid with stable cell dimensions that must not shift when feedback states are applied.
+   * @avoidWhen Selecting from a long dynamic list — use combobox or select instead.
+   * @avoidWhen Choosing one of two to five short values in a compact inline context — use segmented-control instead.
+   * @related choice-grid-item, segmented-control, radio-group, checkbox-group
+   */
+  export type {
+    ChoiceGridColumns,
+    ChoiceGridContext,
+    ChoiceGridItemState,
+    ChoiceGridProps,
+  } from './choice-grid.types.ts';
+</script>
+
+<script lang="ts">
+  import type { ChoiceGridProps } from './choice-grid.types.ts';
+  import { setChoiceGridContext } from './choice-grid-context.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import { createSingleSelection, createMultiSelection } from '../../_internal/collection.ts';
+  import { handleRovingKeydown } from '../../utilities/roving-tabindex.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
+
+  let {
+    value = $bindable(null),
+    values = $bindable([]),
+    multiple = false,
+    columns = 'responsive',
+    minColumnWidth = '10rem',
+    ariaLabel,
+    ariaLabelledby,
+    disabled = false,
+    class: className,
+    children,
+    ...rest
+  }: ChoiceGridProps = $props();
+
+  // Registry of items keyed by value. Insertion order determines navigation
+  // order (linear roving through the visual grid). `disabled` is tracked so both
+  // the roving-tabindex computation and arrow-key navigation skip disabled items.
+  type RegisteredItem = { element: HTMLElement; disabled: boolean };
+  const items: Map<string, RegisteredItem> = new Map();
+  let version = $state(0);
+
+  const singleSelection = $derived(
+    createSingleSelection(
+      () => value ?? null,
+      (next) => {
+        value = next;
+      },
+    ),
+  );
+
+  const multiSelection = $derived(
+    createMultiSelection(
+      () => values,
+      (next) => {
+        values = next;
+      },
+    ),
+  );
+
+  function isSelected(candidate: string): boolean {
+    if (multiple) {
+      return multiSelection.isSelected(candidate);
+    }
+    return singleSelection.isSelected(candidate);
+  }
+
+  function select(candidate: string): void {
+    // Refuse to activate when the grid is disabled OR the specific item is
+    // disabled — items forward keydown unconditionally (so navigation isn't
+    // trapped), which means Space/Enter can reach here for a disabled item.
+    if (isItemDisabled(candidate)) return;
+    if (multiple) {
+      multiSelection.toggle(candidate);
+    } else {
+      singleSelection.select(candidate);
+    }
+  }
+
+  function isItemDisabled(candidate: string): boolean {
+    if (disabled) return true;
+    return items.get(candidate)?.disabled ?? false;
+  }
+
+  // Item values ordered by their RENDERED DOM position, not Map-insertion order.
+  // Reordering keyed `{#each}` children reorders the DOM without re-registering,
+  // so roving navigation and the default tabindex target must follow the visual
+  // order — otherwise focus moves along the wrong sequence.
+  function orderedKeys(): string[] {
+    return [...items.entries()]
+      .sort(([, a], [, b]) => {
+        const position = a.element.compareDocumentPosition(b.element);
+        if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+        if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+        return 0;
+      })
+      .map(([key]) => key);
+  }
+
+  // The single ENABLED value that should hold `tabindex="0"`. Disabled items are
+  // never focusable: prefer the (enabled) selected value, else the first enabled
+  // registered item. Returns null when every item is disabled.
+  const focusableValue = $derived.by(() => {
+    void version;
+    void value;
+    void values;
+    const ordered = orderedKeys();
+    if (ordered.length === 0) return null;
+
+    if (!multiple && value !== null && value !== undefined) {
+      if (items.has(value) && !isItemDisabled(value)) return value;
+    }
+    if (multiple && values.length > 0) {
+      for (const selected of values) {
+        if (items.has(selected) && !isItemDisabled(selected)) return selected;
+      }
+    }
+    // First enabled item in DOM order.
+    for (const key of ordered) {
+      if (!isItemDisabled(key)) return key;
+    }
+    return null;
+  });
+
+  function isFocusable(candidate: string): boolean {
+    // Subscribe to reactive inputs so this stays current inside $derived.
+    void version;
+    void value;
+    void values;
+    return focusableValue === candidate;
+  }
+
+  function register(itemValue: string, element: HTMLElement, itemDisabled: boolean): void {
+    items.set(itemValue, { element, disabled: itemDisabled });
+    version += 1;
+  }
+
+  function setItemDisabled(itemValue: string, itemDisabled: boolean): void {
+    const existing = items.get(itemValue);
+    if (existing && existing.disabled !== itemDisabled) {
+      items.set(itemValue, { element: existing.element, disabled: itemDisabled });
+      version += 1;
+    }
+  }
+
+  function unregister(itemValue: string): void {
+    if (items.delete(itemValue)) {
+      version += 1;
+    }
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    const keys = orderedKeys();
+    const currentIndex = keys.findIndex((key) => {
+      const entry = items.get(key);
+      return entry?.element === event.currentTarget || entry?.element === event.target;
+    });
+
+    if (currentIndex === -1) return;
+
+    // Space/Enter: activate the currently focused item.
+    if (event.key === ' ' || event.key === 'Enter') {
+      event.preventDefault();
+      const focusedValue = keys[currentIndex];
+      if (focusedValue !== undefined) {
+        select(focusedValue);
+      }
+      return;
+    }
+
+    // Arrow keys: LINEAR roving through the visual grid in DOM order (the
+    // responsive column count is layout-dependent, so v1 uses linear roving
+    // rather than measured 2D movement). Disabled items are skipped.
+    const nextIndex = handleRovingKeydown(event, currentIndex, keys.length, {
+      horizontal: true,
+      vertical: true,
+      isDisabled: (index) => {
+        const key = keys[index];
+        return key === undefined ? true : isItemDisabled(key);
+      },
+    });
+
+    if (nextIndex === null || nextIndex === currentIndex) return;
+    event.preventDefault();
+
+    const nextValue = keys[nextIndex];
+    if (nextValue === undefined) return;
+    items.get(nextValue)?.element.focus();
+
+    // WAI-ARIA radiogroup pattern: arrow navigation also moves the selection in
+    // single-select mode. Multi-select (checkbox semantics) only moves focus —
+    // selection toggles on Space/Enter/click.
+    if (!multiple) {
+      select(nextValue);
+    }
+  }
+
+  setChoiceGridContext({
+    get value() {
+      return value ?? null;
+    },
+    get multiple() {
+      return multiple;
+    },
+    get disabled() {
+      return disabled;
+    },
+    isSelected,
+    select,
+    register,
+    setItemDisabled,
+    unregister,
+    isFocusable,
+    handleKeydown,
+  });
+
+  // Empty strings are normalized to `undefined` so `aria-label=""` does not
+  // suppress the accessible-name fallback and leave the group unnamed.
+  const resolvedAriaLabel = $derived(ariaLabel?.trim() ? ariaLabel : undefined);
+  const resolvedAriaLabelledby = $derived(ariaLabelledby?.trim() ? ariaLabelledby : undefined);
+
+  // Dev-time guardrails for the two easy-to-miss API contracts.
+  $effect(() => {
+    if (values.length > 0 && !multiple) {
+      devWarn(
+        'ChoiceGrid: `values` was provided without `multiple`. Binding `values` does not enable multi-select — set `multiple` explicitly. The grid is operating in single-select mode and ignoring `values`.',
+      );
+    }
+    // Check the resolved (non-empty) names so `ariaLabel=""` / `ariaLabelledby=""`
+    // still warn — an empty string leaves the control unnamed.
+    if (!resolvedAriaLabel && !resolvedAriaLabelledby) {
+      devWarn(
+        'ChoiceGrid: no `ariaLabel` or `ariaLabelledby` provided. The radiogroup/group has no accessible name — pass one.',
+      );
+    }
+  });
+
+  // Grid template columns CSS.
+  const gridTemplateColumns = $derived(
+    columns === 'responsive'
+      ? `repeat(auto-fill, minmax(min(${minColumnWidth}, 100%), 1fr))`
+      : `repeat(${columns}, 1fr)`,
+  );
+
+  // ARIA role: radiogroup for single-select, group for multi-select.
+  const role = $derived(multiple ? 'group' : 'radiogroup');
+</script>
+
+<div
+  {...rest}
+  {role}
+  class={classNames('cinder-choice-grid', className)}
+  aria-label={resolvedAriaLabel}
+  aria-labelledby={resolvedAriaLabelledby}
+  aria-disabled={disabled || undefined}
+  data-cinder-multiple={multiple || undefined}
+  data-cinder-disabled={disabled || undefined}
+  style:--cinder-choice-grid-columns={gridTemplateColumns}
+>
+  {@render children()}
+</div>