@lostgradient/cinder 0.3.0 → 0.4.1

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

@@ -157,8 +157,8 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    inline-size: 1.75rem;
-    min-block-size: 1.75rem;
+    inline-size: 2rem;
+    min-block-size: 2rem;
     border: 1px solid transparent;
     border-radius: var(--cinder-radius-sm);
     background: var(--cinder-surface-raised);
@@ -176,7 +176,8 @@
 
   @media (forced-colors: active) {
     .cinder-code-block .cinder-code-block__header .cinder-copy-button:focus-visible {
-      outline-color: CanvasText;
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
       box-shadow: none;
     }
   }

package/src/components/collapsible/README.md

@@ -32,7 +32,7 @@ Controlled — the parent owns the state with `bind:open`:
 
 ### State model
 
-Without `bind:open`, `open` is the initial local value and the component manages subsequent toggles; pass `open={true}` to render initially open. With `bind:open`, the parent owns the state. `onToggle` fires on every toggle with the next boolean, so one-way observers stay in sync.
+Without `bind:open`, `open` is the initial local value and the component manages subsequent toggles; pass `open={true}` to render initially open. With `bind:open`, the parent owns the state. `ontoggle` fires on every toggle with the next boolean, so one-way observers stay in sync.
 
 The `trigger` prop is either a string or a snippet receiving `{ open, disabled }`, letting the label react to state (for example, swapping "Show" and "Hide").
 
@@ -57,7 +57,7 @@ For multiple coordinated sections where opening one may close others, use [`Acco
 | `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. |
+| `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/collapsible/collapsible.svelte

@@ -27,7 +27,7 @@
     trigger,
     children,
     open = $bindable(false),
-    onToggle,
+    ontoggle,
     disabled = false,
     idBase,
     class: className,
@@ -49,7 +49,7 @@
     if (disabled) return;
     const next = !open;
     open = next;
-    onToggle?.(next);
+    ontoggle?.(next);
   }
 </script>
 

package/src/components/collapsible/collapsible.types.ts

@@ -4,7 +4,10 @@ import type { HTMLAttributes } from 'svelte/elements';
 /** State passed to a trigger snippet so labels can react to open/disabled. */
 export type CollapsibleTriggerState = { open: boolean; disabled: boolean };
 
-export type CollapsibleProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+export type CollapsibleProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'ontoggle'
+> & {
   /** Trigger label: a plain string, or a snippet receiving `{ open, disabled }`. */
   trigger: string | Snippet<[CollapsibleTriggerState]>;
   /** Panel content shown when open. */
@@ -16,7 +19,7 @@ export type CollapsibleProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'c
    */
   open?: boolean;
   /** Fired on every successful toggle with the next open state. Not called while disabled. */
-  onToggle?: (open: boolean) => void;
+  ontoggle?: (open: boolean) => void;
   /**
    * When true, the trigger cannot be toggled.
    * @default false

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

@@ -60,24 +60,24 @@ Moving the component across forms at runtime is not supported in v1.
 
 <!-- generated:props:start -->
 
-| Prop             | Type                                      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                 |
-| ---------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `alpha`          | `boolean`                                 | no       | —       | Accept and emit alpha when the parsed value has partial alpha. When `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed but alpha is stripped on emit.                                                                                                                                                                   |
-| `ariaLabel`      | `string`                                  | no       | —       | Accessible label applied directly to the inner `<input>` when no `FormField` wraps it.                                                                                                                                                                                                                                                      |
-| `ariaLabelledby` | `string`                                  | no       | —       | Id of an external element that labels the inner `<input>`.                                                                                                                                                                                                                                                                                  |
-| `class`          | `string`                                  | no       | —       | Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`).                                                                                                                                                                                                                                                          |
-| `defaultValue`   | `string`                                  | no       | —       | Initial value when uncontrolled. Accepts any allowed `formats` input.                                                                                                                                                                                                                                                                       |
-| `disabled`       | `boolean`                                 | no       | —       | Disable the input.                                                                                                                                                                                                                                                                                                                          |
-| `enterBehavior`  | `"commit-then-submit"` \| `"commit-only"` | no       | —       | Commit-on-Enter behavior. Default `'commit-then-submit'`: - `'commit-then-submit'`: Enter commits the value, then lets the form's native submission proceed via `requestSubmit`. - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing form submission (useful in dialogs / multi-field flows where Enter must not submit). |
-| `errorMessage`   | `string`                                  | no       | —       | Override the default parse-failure error message.                                                                                                                                                                                                                                                                                           |
-| `formats`        | (`"hex"` \| `"rgb"` \| `"hsl"`)[]         | no       | —       | Accepted _input_ formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex.                                                                                                                                                                                                                                                        |
-| `id`             | `string`                                  | yes      | —       | Inner `<input>` id. Required (mirrors Input).                                                                                                                                                                                                                                                                                               |
-| `name`           | `string`                                  | no       | —       | Form field name. When set, the hidden mirror input contributes the current committed hex value to native form submission.                                                                                                                                                                                                                   |
-| `placeholder`    | `string`                                  | no       | —       | Placeholder text for the inner `<input>`.                                                                                                                                                                                                                                                                                                   |
-| `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       | —       | 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.                                                                                                   |
+| Prop              | Type                                      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                 |
+| ----------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alpha`           | `boolean`                                 | no       | —       | Accept and emit alpha when the parsed value has partial alpha. When `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed but alpha is stripped on emit.                                                                                                                                                                   |
+| `aria-label`      | `string`                                  | no       | —       | Accessible label applied directly to the inner `<input>` when no `FormField` wraps it.                                                                                                                                                                                                                                                      |
+| `aria-labelledby` | `string`                                  | no       | —       | Id of an external element that labels the inner `<input>`.                                                                                                                                                                                                                                                                                  |
+| `class`           | `string`                                  | no       | —       | Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`).                                                                                                                                                                                                                                                          |
+| `defaultValue`    | `string`                                  | no       | —       | Initial value when uncontrolled. Accepts any allowed `formats` input.                                                                                                                                                                                                                                                                       |
+| `disabled`        | `boolean`                                 | no       | —       | Disable the input.                                                                                                                                                                                                                                                                                                                          |
+| `enterBehavior`   | `"commit-then-submit"` \| `"commit-only"` | no       | —       | Commit-on-Enter behavior. Default `'commit-then-submit'`: - `'commit-then-submit'`: Enter commits the value, then lets the form's native submission proceed via `requestSubmit`. - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing form submission (useful in dialogs / multi-field flows where Enter must not submit). |
+| `errorMessage`    | `string`                                  | no       | —       | Override the default parse-failure error message.                                                                                                                                                                                                                                                                                           |
+| `formats`         | (`"hex"` \| `"rgb"` \| `"hsl"`)[]         | no       | —       | Accepted _input_ formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex.                                                                                                                                                                                                                                                        |
+| `id`              | `string`                                  | yes      | —       | Inner `<input>` id. Required (mirrors Input).                                                                                                                                                                                                                                                                                               |
+| `name`            | `string`                                  | no       | —       | Form field name. When set, the hidden mirror input contributes the current committed hex value to native form submission.                                                                                                                                                                                                                   |
+| `placeholder`     | `string`                                  | no       | —       | Placeholder text for the inner `<input>`.                                                                                                                                                                                                                                                                                                   |
+| `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       | —       | 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.svelte

@@ -36,8 +36,8 @@
     readonly = false,
     name,
     placeholder,
-    ariaLabel,
-    ariaLabelledby,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
     errorMessage,
     enterBehavior = 'commit-then-submit',
     onchange,

package/src/components/color-field/color-field.types.ts

@@ -35,9 +35,9 @@ export type ColorFieldProps = {
   /** Placeholder text for the inner `<input>`. */
   placeholder?: string;
   /** Accessible label applied directly to the inner `<input>` when no `FormField` wraps it. */
-  ariaLabel?: string;
+  'aria-label'?: string;
   /** Id of an external element that labels the inner `<input>`. */
-  ariaLabelledby?: string;
+  'aria-labelledby'?: string;
   /** Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`). */
   class?: string;
   /** Override the default parse-failure error message. */

package/src/components/color-swatch-picker/color-swatch-picker.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "color-swatch-picker",
+  "import": "@lostgradient/cinder/color-swatch-picker",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic color swatch picker",
+      "description": "Keyboard-navigable preset palette constrained to brand colors.",
+      "code": "<script lang=\"ts\">\n  import { ColorSwatchPicker } from '@lostgradient/cinder/color-swatch-picker';\n\n  const palette = [\n    { color: '#ef4444', name: 'Red' },\n    { color: '#f97316', name: 'Orange' },\n    { color: '#eab308', name: 'Yellow' },\n    { color: '#22c55e', name: 'Green' },\n    { color: '#3b82f6', name: 'Blue' },\n    { color: '#8b5cf6', name: 'Violet' },\n  ];\n\n  let selected = $state('#3b82f6');\n</script>\n\n<ColorSwatchPicker\n  colors={palette}\n  value={selected}\n  label=\"Accent color\"\n  onchange={(color) => (selected = color)}\n/>\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Selected: {selected}</p>\n"
+    }
+  ]
+}

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

@@ -15,7 +15,7 @@
 </script>
 
 <script lang="ts">
-  import type { ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
+  import type { ColorSwatch, ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
   import { tick, untrack } from 'svelte';
 
   import { classNames } from '../../utilities/class-names.ts';
@@ -43,6 +43,31 @@
   let internalValue = $state(untrack(() => defaultValue) ?? '');
   const selected = $derived(value ?? internalValue);
 
+  // Deduplicate swatches by color (first occurrence wins) so the keyed {#each}
+  // never receives duplicate keys and Svelte cannot throw each_key_duplicate.
+  // A dev warning is emitted when duplicates are found so the data author can fix
+  // their input, but the component continues to render the deduplicated list.
+  const renderableColors = $derived.by(() => {
+    const seen = new Set<string>();
+    const result: ColorSwatch[] = [];
+    let hasDuplicates = false;
+    for (const swatch of colors) {
+      if (seen.has(swatch.color)) {
+        hasDuplicates = true;
+      } else {
+        seen.add(swatch.color);
+        result.push(swatch);
+      }
+    }
+    if (hasDuplicates) {
+      devWarn(
+        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
+          'Only the first matching swatch will be shown as selected. Duplicates were removed.',
+      );
+    }
+    return result;
+  });
+
   // Track focus index driven by user interaction. null = derive from selection.
   let userFocusIndex = $state<number | null>(null);
 
@@ -53,25 +78,25 @@
   });
 
   const effectiveFocusIndex = $derived.by(() => {
-    if (colors.length === 0) return -1;
+    if (renderableColors.length === 0) return -1;
 
     // 1. User-driven focus if it points to a valid, non-item-disabled option.
     if (
       userFocusIndex !== null &&
-      userFocusIndex < colors.length &&
-      !colors[userFocusIndex]?.disabled
+      userFocusIndex < renderableColors.length &&
+      !renderableColors[userFocusIndex]?.disabled
     ) {
       return userFocusIndex;
     }
 
     // 2. Currently selected swatch if it exists and is not item-disabled.
-    const selectedIndex = colors.findIndex((s) => s.color === selected);
-    if (selectedIndex !== -1 && !colors[selectedIndex]?.disabled) {
+    const selectedIndex = renderableColors.findIndex((s) => s.color === selected);
+    if (selectedIndex !== -1 && !renderableColors[selectedIndex]?.disabled) {
       return selectedIndex;
     }
 
     // 3. First non-item-disabled option.
-    const firstEnabled = colors.findIndex((s) => !s.disabled);
+    const firstEnabled = renderableColors.findIndex((s) => !s.disabled);
     if (firstEnabled !== -1) return firstEnabled;
 
     // 4. First option in DOM order (ensures the control always has a tab stop).
@@ -82,19 +107,19 @@
   let liRefs: (HTMLLIElement | null)[] = $state([]);
 
   // Index of the first swatch (by DOM order) matching `selected` — for aria-selected.
-  const selectedIndex = $derived(colors.findIndex((s) => s.color === selected));
+  const selectedIndex = $derived(renderableColors.findIndex((s) => s.color === selected));
 
   function isItemDisabledForRoving(index: number): boolean {
-    return colors[index]?.disabled === true;
+    return renderableColors[index]?.disabled === true;
   }
 
   function isInteractive(index: number): boolean {
-    return !disabled && !colors[index]?.disabled;
+    return !disabled && !renderableColors[index]?.disabled;
   }
 
   function selectSwatch(index: number): void {
     if (!isInteractive(index)) return;
-    const swatch = colors[index];
+    const swatch = renderableColors[index];
     if (!swatch) return;
     internalValue = swatch.color;
     onchange?.(swatch.color);
@@ -112,7 +137,7 @@
       return;
     }
 
-    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, colors.length, {
+    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, renderableColors.length, {
       vertical: true,
       horizontal: layout === 'grid',
       isDisabled: isItemDisabledForRoving,
@@ -133,17 +158,6 @@
     userFocusIndex = index;
     selectSwatch(index);
   }
-
-  // Warn in dev mode when duplicate colors appear in the palette.
-  $effect(() => {
-    const colorValues = colors.map((c) => c.color);
-    if (new Set(colorValues).size !== colorValues.length) {
-      devWarn(
-        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
-          'Only the first matching swatch will be shown as selected.',
-      );
-    }
-  });
 </script>
 
 <ul
@@ -157,7 +171,7 @@
   data-cinder-layout={layout}
   onkeydown={handleKeydown}
 >
-  {#each colors as swatch, index (swatch.color + index)}
+  {#each renderableColors as swatch, index (swatch.color)}
     {@const isSelected = index === selectedIndex}
     {@const isDisabled = swatch.disabled === true}
     {@const contrastColor = pickContrastColor(swatch.color)}

package/src/components/combobox/README.md

@@ -21,13 +21,15 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `aria-describedby`  | `string`   | no       | —       | External element id(s) to compose into `aria-describedby`. Composed after the component-generated description and error ids, matching the field-control contract in Select. Useful for tooltip ids, counter ids, or any external hint. |
 | `class`             | `string`   | no       | —       | Additional class names merged with `.cinder-combobox`.                                                                                                                                                                                 |
 | `description`       | `string`   | no       | —       | Helper text displayed below the input; wired via aria-describedby.                                                                                                                                                                     |
-| `disabled`          | `boolean`  | no       | —       | Disables the combobox.                                                                                                                                                                                                                 |
+| `disabled`          | `boolean`  | no       | —       | Disables the combobox. Inherited from a wrapping FormField when unset.                                                                                                                                                                 |
 | `error`             | `string`   | no       | —       | Validation error message; sets aria-invalid="true".                                                                                                                                                                                    |
 | `id`                | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                                                                                                    |
 | `inputValue`        | `string`   | no       | —       | Free-text input value (the text the user has typed). Bindable.                                                                                                                                                                         |
 | `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
 | `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
+| `name`              | `string`   | no       | —       | Native form field name. Renders a hidden input carrying the selected value.                                                                                                                                                            |
 | `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
+| `required`          | `boolean`  | no       | —       | Marks the field required: renders the required marker on the label and sets `aria-required` on the input. Inherited from a wrapping FormField when unset.                                                                              |
 | `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.                                                                                          |

package/src/components/combobox/combobox.svelte

@@ -19,12 +19,8 @@
   import type { ComboboxOption, ComboboxProps } from './combobox.types.ts';
   import { untrack } from 'svelte';
 
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
+  import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
@@ -32,6 +28,7 @@
   let {
     id,
     value = $bindable(''),
+    name,
     inputValue = $bindable(''),
     options,
     label,
@@ -39,17 +36,38 @@
     filter,
     description,
     error,
-    disabled = false,
+    disabled,
+    required,
     maxVisibleOptions = 200,
     class: className,
     'aria-describedby': consumerDescribedBy,
   }: ComboboxProps<T> = $props();
 
+  const context = getFormFieldContext();
+  const field = $derived(
+    resolveFieldControl({
+      id,
+      generatedId: id,
+      context,
+      hasDescription: !!description,
+      hasError: !!error,
+      localIdNamespace: 'combobox',
+      consumerDescribedBy,
+      required,
+      disabled,
+    }),
+  );
+  const resolvedDisabled = $derived(field.disabled);
+  const resolvedRequired = $derived(field.required);
+  const describedBy = $derived(field.describedBy);
+
   const listboxId = $derived(`${id}-listbox`);
-  const descriptionId = $derived(describeId(id, !!description));
-  // errId only included in aria-describedby when error is active.
-  const errId = $derived(buildErrorId(id, !!error));
-  const describedBy = $derived(composeDescribedBy(descriptionId, errId, consumerDescribedBy));
+  const descriptionId = $derived(field.ownDescriptionId);
+  // Stable id for the always-in-DOM error live region when no error is active.
+  // Mirrors Select: avoids colliding with a wrapping FormField's error id.
+  const stableLocalErrorId = $derived(
+    context?.errorId === `${field.id}-error` ? `${field.id}-combobox-error` : `${field.id}-error`,
+  );
 
   const defaultFilter = (option: ComboboxOption<T>, query: string): boolean => {
     if (!query) return true;
@@ -75,8 +93,12 @@
   let open = $state(false);
   let activeIndex = $state(-1);
   let inputElement = $state<HTMLInputElement | null>(null);
+  let hiddenInputElement = $state<HTMLInputElement | null>(null);
   let listboxElement = $state<HTMLElement | null>(null);
   let committedLabel = $state('');
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+  const initialValue = untrack(() => value);
+  const initialInputValue = untrack(() => inputValue);
 
   // Reset active index whenever the filtered set changes so we don't point
   // at a stale option.
@@ -125,7 +147,7 @@
   // 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 {
+  function handleEscape(event: KeyboardEvent | undefined = undefined): void {
     const wasOpen = open;
     open = false;
     // Restore the committed label whenever the live text drifted from it.
@@ -159,7 +181,7 @@
   }
 
   function handleFocus() {
-    if (!disabled) open = true;
+    if (!resolvedDisabled) open = true;
   }
 
   function handleBlur(event: FocusEvent) {
@@ -186,6 +208,45 @@
     open = false;
   }
 
+  function resetToInitialValue(event: Event): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (event.defaultPrevented) return;
+      value = initialValue;
+      const matched = options.find((option) => option.value === initialValue);
+      const nextInputValue = matched?.label ?? initialInputValue;
+      inputValue = nextInputValue;
+      committedLabel = matched?.label ?? '';
+      open = false;
+      activeIndex = -1;
+      if (inputElement) inputElement.value = nextInputValue;
+      if (hiddenInputElement) hiddenInputElement.value = initialValue;
+    }, 0);
+  }
+
+  $effect(() => {
+    const input = hiddenInputElement;
+    if (input === null) return;
+    const form = input.form;
+    form?.addEventListener('reset', resetToInitialValue);
+    return () => {
+      form?.removeEventListener('reset', resetToInitialValue);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
+  $effect(() => {
+    inputElement?.setCustomValidity(
+      (resolvedRequired && !value) || inputValue !== committedLabel
+        ? 'Please select an option.'
+        : '',
+    );
+  });
+
   function handleKeydown(event: KeyboardEvent) {
     if (event.key === 'ArrowDown') {
       event.preventDefault();
@@ -226,8 +287,11 @@
 
 <div class={classNames('cinder-combobox', className)}>
   {#if label}
-    <label for={id} class="cinder-combobox__label" data-disabled={disabled || undefined}>
+    <label for={id} class="cinder-combobox__label" data-disabled={resolvedDisabled || undefined}>
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 
@@ -241,14 +305,16 @@
       autocomplete="off"
       autocorrect="off"
       spellcheck="false"
-      {disabled}
+      disabled={resolvedDisabled}
+      required={resolvedRequired}
       {placeholder}
       value={inputValue}
       aria-autocomplete="list"
       aria-expanded={open}
       aria-controls={listboxId}
       aria-activedescendant={activeOptionId}
-      aria-invalid={ariaInvalid(!!error)}
+      aria-invalid={field.ariaInvalid}
+      aria-required={resolvedRequired || undefined}
       aria-describedby={describedBy}
       oninput={handleInput}
       onfocus={handleFocus}
@@ -257,6 +323,16 @@
     />
   </div>
 
+  {#if name}
+    <input
+      bind:this={hiddenInputElement}
+      type="hidden"
+      {name}
+      {value}
+      disabled={resolvedDisabled}
+    />
+  {/if}
+
   {#if open && filteredOptions.length > 0}
     <Popover
       bind:open
@@ -325,7 +401,7 @@
 
   <!-- Always in DOM for the same reason — live region must pre-exist before text is injected. -->
   <p
-    id="{id}-error"
+    id={field.ownErrorId ?? stableLocalErrorId}
     class="cinder-combobox__error"
     aria-live="polite"
     data-cinder-error={!!error || undefined}

package/src/components/combobox/combobox.types.ts

@@ -38,6 +38,8 @@ export type ComboboxProps<T extends string = string> = {
   id: string;
   /** Currently selected value. Bindable. `''` when nothing is selected. */
   value?: NoInfer<T> | '';
+  /** Native form field name. Renders a hidden input carrying the selected value. */
+  name?: string | undefined;
   /** Free-text input value (the text the user has typed). Bindable. */
   inputValue?: string;
   /** Full set of options to filter. The sole inference source for T. */
@@ -56,8 +58,14 @@ export type ComboboxProps<T extends string = string> = {
   description?: string;
   /** Validation error message; sets aria-invalid="true". */
   error?: string;
-  /** Disables the combobox. */
+  /** Disables the combobox. Inherited from a wrapping FormField when unset. */
   disabled?: boolean;
+  /**
+   * Marks the field required: renders the required marker on the label and
+   * sets `aria-required` on the input. Inherited from a wrapping FormField
+   * when unset.
+   */
+  required?: boolean;
   /** Hard cap on visible filtered options. Default 200. */
   maxVisibleOptions?: number;
   /**

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

@@ -16,17 +16,19 @@ 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)`             | 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. |
+| Prop               | Type                   | Required | Default | Description                                                                                                                               |
+| ------------------ | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessibleLabel`  | `string`               | no       | —       | Accessible name for the option when the rendered row contains secondary text or rich content.                                             |
+| `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.                                                                     |
+| `keyboardShortcut` | `string`               | no       | —       | Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`.                                                                     |
+| `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 -->
 

package/src/components/command-item/command-item.css

@@ -29,6 +29,16 @@
   .cinder-command-item[data-cinder-active] {
     background: var(--cinder-accent);
     color: var(--cinder-accent-contrast);
+    /* Keyboard-cursor ring for WCAG 1.4.11 (non-text contrast, ≥3:1). The ring
+       sits ON the accent fill, so it must contrast against --cinder-accent — NOT
+       against a neutral surface. --cinder-ring-color is engineered for ~4.5:1
+       against near-white surfaces and collapses to ~1.1–1.3:1 on the accent fill
+       (invisible), which is why the shared _floating-surface.css ring works there
+       (it sits on a neutral hover surface) but cannot be reused here verbatim.
+       --cinder-accent-contrast is the only token already proven to clear AA on the
+       accent fill (it is the text color on this fill; check-token-contrast.test.ts
+       gates it), giving ~6.5:1 (light) / ~7.8:1 (dark) for the ring. */
+    box-shadow: inset 0 0 0 1px var(--cinder-accent-contrast);
   }
 
   @media (forced-colors: active) {