@lostgradient/cinder 0.3.0 → 0.4.0

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

@@ -0,0 +1,60 @@
+# TimeField
+
+Standalone time-of-day input with optional timezone selection.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import TimeField from '@lostgradient/cinder/time-field';
+
+  let time = $state('09:30');
+</script>
+
+<TimeField id="reminder-time" label="Reminder time" bind:value={time} />
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop               | Type                                       | Required | Default | Description                                                                                                                        |
+| ------------------ | ------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `aria-describedby` | `string`                                   | no       | —       |                                                                                                                                    |
+| `aria-invalid`     | `false` \| `true` \| `"true"` \| `"false"` | no       | —       |                                                                                                                                    |
+| `aria-label`       | `string`                                   | no       | —       |                                                                                                                                    |
+| `aria-labelledby`  | `string`                                   | no       | —       |                                                                                                                                    |
+| `class`            | `string`                                   | no       | —       |                                                                                                                                    |
+| `defaultValue`     | `string`                                   | no       | —       |                                                                                                                                    |
+| `description`      | `string`                                   | no       | —       |                                                                                                                                    |
+| `disabled`         | `boolean`                                  | no       | —       |                                                                                                                                    |
+| `error`            | `string`                                   | no       | —       |                                                                                                                                    |
+| `granularity`      | `"minute"` \| `"second"`                   | no       | —       |                                                                                                                                    |
+| `id`               | `string`                                   | yes      | —       |                                                                                                                                    |
+| `label`            | `string`                                   | no       | —       |                                                                                                                                    |
+| `name`             | `string`                                   | no       | —       |                                                                                                                                    |
+| `readonly`         | `boolean`                                  | no       | —       |                                                                                                                                    |
+| `required`         | `boolean`                                  | no       | —       |                                                                                                                                    |
+| `timezone`         | `string`                                   | no       | —       |                                                                                                                                    |
+| `timezoneName`     | `string`                                   | no       | —       |                                                                                                                                    |
+| `timezones`        | `string`[]                                 | no       | —       |                                                                                                                                    |
+| `value`            | `string`                                   | no       | —       |                                                                                                                                    |
+| `onchange`         | `(opaque)`                                 | no       | —       | Called when the user commits a time or timezone change. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/time-field/index.ts

@@ -0,0 +1,6 @@
+import './time-field.css';
+import TimeField from './time-field.svelte';
+
+export default TimeField;
+export type { TimeFieldChange, TimeFieldGranularity, TimeFieldProps } from './time-field.types.ts';
+export { TimeField };

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

@@ -0,0 +1,60 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-time-field {
+    display: grid;
+    gap: var(--cinder-space-2);
+    color: var(--cinder-text);
+  }
+
+  .cinder-time-field__label {
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-semibold);
+  }
+
+  .cinder-time-field__controls {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--cinder-space-2);
+    align-items: center;
+  }
+
+  .cinder-time-field__input,
+  .cinder-time-field__timezone {
+    min-height: 2.25rem;
+    padding-block: var(--cinder-space-2);
+    padding-inline: var(--cinder-space-3);
+    color: var(--cinder-text);
+    background: var(--cinder-surface);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+  }
+
+  .cinder-time-field__input:focus-visible,
+  .cinder-time-field__timezone:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-time-field__input:focus-visible,
+    .cinder-time-field__timezone:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
+  .cinder-time-field__description,
+  .cinder-time-field__error {
+    margin: 0;
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-time-field__description {
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-time-field__error {
+    color: var(--cinder-danger);
+  }
+}

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

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "time-field",
+  "import": "@lostgradient/cinder/time-field",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic time field",
+      "description": "Standalone time input with optional timezone selection.",
+      "code": "<script lang=\"ts\">\n  import { TimeField } from '@lostgradient/cinder/time-field';\n\n  let time = $state('09:30');\n  let timezone = $state<string | undefined>('America/Denver');\n</script>\n\n<TimeField\n  id=\"time-field\"\n  label=\"Reminder time\"\n  bind:value={time}\n  bind:timezone\n  timezones={['America/Denver', 'UTC']}\n  description=\"Stored as a canonical 24-hour time string.\"\n/>\n\n<p style=\"margin-block: 0; color: var(--cinder-text-muted);\">\n  Value: {time}\n  {timezone}\n</p>\n"
+    }
+  ]
+}

package/src/components/time-field/time-field.svelte

@@ -0,0 +1,277 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status stable
+   * @purpose Standalone time-of-day field that collects a canonical time string with optional timezone selection.
+   * @tag form
+   * @tag time
+   * @tag internationalization
+   * @useWhen Collecting a time of day without a date, such as a reminder time or office-hours boundary.
+   * @useWhen Pairing a time value with an optional timezone while keeping a canonical `HH:mm` or `HH:mm:ss` value.
+   * @avoidWhen Collecting a full date range — use date-range-field instead.
+   * @related date-range-field, number-input
+   */
+  export type {
+    TimeFieldChange,
+    TimeFieldGranularity,
+    TimeFieldProps,
+  } from './time-field.types.ts';
+</script>
+
+<script lang="ts">
+  import { untrack } from 'svelte';
+
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
+  import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+  import { parseTimeString, serializeTimeParts } from '../../_internal/time-parts.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { TimeFieldProps } from './time-field.types.ts';
+
+  let {
+    id,
+    value = $bindable<string | undefined>(undefined),
+    defaultValue = '',
+    granularity = 'minute',
+    timezones,
+    timezone = $bindable<string | undefined>(undefined),
+    timezoneName,
+    label,
+    description,
+    error,
+    disabled = false,
+    readonly = false,
+    required = false,
+    name,
+    class: className,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': consumerDescribedBy,
+    'aria-invalid': consumerAriaInvalid,
+    onchange,
+    ...rest
+  }: TimeFieldProps = $props();
+
+  const formField = getFormFieldContext();
+  const includeSeconds = $derived(granularity === 'second');
+  const inputStep = $derived(includeSeconds ? 1 : 60);
+  let inputMirrorValue = $state<string | undefined>(undefined);
+  let inputMirrorSourceValue = $state<string | undefined>(undefined);
+  const submittedValue = $derived(canonicalTimeValue(inputMirrorValue ?? value));
+  let resetTimezoneBaseline = $state<string | undefined>(undefined);
+  let skipTimezoneBaselineUpdate = false;
+
+  untrack(() => {
+    if (value === undefined) value = canonicalTimeValue(defaultValue);
+    if (timezone === undefined && timezones && timezones.length > 0) timezone = timezones[0];
+    resetTimezoneBaseline = timezone;
+  });
+
+  $effect(() => {
+    if (!timezones || timezones.length === 0) {
+      return;
+    }
+    if (timezone === undefined || !timezones.includes(timezone)) {
+      timezone = timezones[0];
+    }
+  });
+
+  $effect(() => {
+    if (skipTimezoneBaselineUpdate) {
+      skipTimezoneBaselineUpdate = false;
+      return;
+    }
+    resetTimezoneBaseline = timezone;
+  });
+
+  $effect(() => {
+    if (inputMirrorValue === undefined) return;
+    if (inputMirrorSourceValue === value) return;
+    inputMirrorValue = undefined;
+    inputMirrorSourceValue = undefined;
+  });
+
+  $effect(() => {
+    if (value === undefined) return;
+    const nextValue = canonicalTimeValue(value);
+    if (value === nextValue) return;
+    inputMirrorValue = undefined;
+    inputMirrorSourceValue = undefined;
+    value = nextValue;
+  });
+
+  const generatedId = $props.id();
+  const field = $derived(
+    resolveFieldControl({
+      id: formField?.controlId ?? id,
+      generatedId,
+      context: formField,
+      localIdNamespace: 'time-field',
+      hasDescription: !!description,
+      hasError: !!error,
+      consumerDescribedBy,
+      consumerInvalid: consumerAriaInvalid,
+      required: required ? true : undefined,
+      disabled: disabled ? true : undefined,
+    }),
+  );
+  const inputId = $derived(field.id);
+  const labelId = $derived(label ? `${inputId}-label` : formField?.labelId);
+  const timezoneLabelId = $derived(`${inputId}-timezone-label`);
+  const descriptionId = $derived(field.ownDescriptionId);
+  const errorId = $derived(field.ownErrorId);
+  const describedBy = $derived(field.describedBy);
+  const invalid = $derived(field.ariaInvalid);
+  const resolvedDisabled = $derived(field.disabled);
+  const resolvedRequired = $derived(field.required);
+  const inputAriaLabel = $derived(
+    label || formField?.labelId ? undefined : normalizeAriaText(ariaLabel),
+  );
+  const inputAriaLabelledBy = $derived(
+    label ? undefined : (normalizeAriaText(ariaLabelledBy) ?? formField?.labelId),
+  );
+  const timezoneAriaLabelledBy = $derived(
+    labelId
+      ? `${labelId} ${timezoneLabelId}`
+      : inputAriaLabelledBy
+        ? `${inputAriaLabelledBy} ${timezoneLabelId}`
+        : undefined,
+  );
+  const timezoneAriaLabel = $derived(
+    timezoneAriaLabelledBy ? undefined : inputAriaLabel ? `${inputAriaLabel} timezone` : 'Timezone',
+  );
+  const resolvedTimezoneName = $derived(
+    timezone !== undefined ? (timezoneName ?? (name ? `${name}-timezone` : undefined)) : undefined,
+  );
+
+  function emit(nextValue: string, nextTimezone = timezone): void {
+    onchange?.({ value: nextValue, timezone: nextTimezone });
+  }
+
+  function normalizeAriaText(text: string | undefined | null): string | undefined {
+    return typeof text === 'string' && text.trim().length > 0 ? text : undefined;
+  }
+
+  function resetTimezoneFor(options: readonly string[] | undefined): string | undefined {
+    if (!options || options.length === 0) return resetTimezoneBaseline;
+    return resetTimezoneBaseline && options.includes(resetTimezoneBaseline)
+      ? resetTimezoneBaseline
+      : options[0];
+  }
+
+  function canonicalTimeValue(nextValue: string | undefined): string {
+    if (!nextValue) return '';
+    const parsed = parseTimeString(nextValue);
+    return parsed ? serializeTimeParts(parsed, includeSeconds) : '';
+  }
+
+  function handleInputChange(event: Event): void {
+    if (resolvedDisabled || readonly) return;
+    const target = event.currentTarget as HTMLInputElement;
+    const nextValue = canonicalTimeValue(target.value);
+    inputMirrorValue = undefined;
+    inputMirrorSourceValue = undefined;
+    value = nextValue;
+    emit(nextValue);
+  }
+
+  function handleInput(event: Event): void {
+    if (resolvedDisabled || readonly) return;
+    inputMirrorSourceValue = value;
+    inputMirrorValue = (event.currentTarget as HTMLInputElement).value;
+  }
+
+  function handleTimezoneChange(event: Event): void {
+    if (resolvedDisabled || readonly) return;
+    const target = event.currentTarget as HTMLSelectElement;
+    skipTimezoneBaselineUpdate = true;
+    timezone = target.value;
+    const nextValue = canonicalTimeValue(value);
+    inputMirrorValue = undefined;
+    inputMirrorSourceValue = undefined;
+    value = nextValue;
+    emit(nextValue, timezone);
+  }
+
+  $effect(() => {
+    const input = document.getElementById(inputId);
+    const form = input instanceof HTMLInputElement ? input.form : null;
+    if (!form) return;
+    const resetValue = canonicalTimeValue(defaultValue);
+    const resetTimezone = resetTimezoneFor(timezones);
+
+    const handleReset = () => {
+      if (resolvedDisabled) return;
+      inputMirrorValue = undefined;
+      inputMirrorSourceValue = undefined;
+      value = resetValue;
+      timezone = resetTimezone;
+    };
+
+    form.addEventListener('reset', handleReset);
+    return () => form.removeEventListener('reset', handleReset);
+  });
+</script>
+
+<div {...rest} class={classNames('cinder-time-field', className)}>
+  {#if label}
+    <label id={labelId} class="cinder-time-field__label" for={inputId}>{label}</label>
+  {/if}
+
+  <div class="cinder-time-field__controls">
+    <input
+      id={inputId}
+      class="cinder-time-field__input"
+      type="time"
+      step={inputStep}
+      value={inputMirrorValue ?? value ?? ''}
+      disabled={resolvedDisabled}
+      {readonly}
+      required={resolvedRequired}
+      aria-label={inputAriaLabel}
+      aria-labelledby={inputAriaLabelledBy}
+      aria-describedby={describedBy}
+      aria-invalid={invalid}
+      oninput={handleInput}
+      onchange={handleInputChange}
+    />
+
+    {#if name}
+      <input type="hidden" {name} value={submittedValue} disabled={resolvedDisabled} />
+    {/if}
+
+    {#if timezones && timezones.length > 0}
+      <span id={timezoneLabelId} class="cinder-sr-only">timezone</span>
+      <select
+        class="cinder-time-field__timezone"
+        aria-label={timezoneAriaLabel}
+        aria-labelledby={timezoneAriaLabelledBy}
+        aria-describedby={describedBy}
+        value={timezone}
+        disabled={resolvedDisabled || readonly}
+        onchange={handleTimezoneChange}
+      >
+        {#each timezones as option (option)}
+          <option value={option}>{option}</option>
+        {/each}
+      </select>
+    {/if}
+
+    {#if resolvedTimezoneName}
+      <input
+        type="hidden"
+        name={resolvedTimezoneName}
+        value={timezone}
+        disabled={resolvedDisabled}
+      />
+    {/if}
+  </div>
+
+  {#if description}
+    <p id={descriptionId} class="cinder-time-field__description">{description}</p>
+  {/if}
+
+  {#if error}
+    <p id={errorId} class="cinder-time-field__error" aria-live="polite">{error}</p>
+  {/if}
+</div>

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

@@ -0,0 +1,70 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type TimeFieldGranularity = 'minute' | 'second';
+
+export type TimeFieldChange = {
+  /** Canonical 24-hour time string (`HH:mm` or `HH:mm:ss`), or an empty string. */
+  value: string;
+  /** Selected timezone identifier when a timezone select is rendered. */
+  timezone: string | undefined;
+};
+
+export type TimeFieldProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'onchange'
+> & {
+  /** Stable id used to associate the label, input, description, and error. Required. */
+  id: string;
+  /** Bindable canonical 24-hour time string (`HH:mm` or `HH:mm:ss`). */
+  value?: string;
+  /** Initial canonical time string used when the component is not controlled. */
+  defaultValue?: string;
+  /** Time precision. Defaults to minute precision. */
+  granularity?: TimeFieldGranularity;
+  /** Optional timezone select values, such as `America/Denver` or `UTC`. */
+  timezones?: readonly string[];
+  /** Bindable selected timezone. Defaults to the first timezone when provided. */
+  timezone?: string | undefined;
+  /** Name for the timezone value in native form submission. Defaults to `${name}-timezone`. */
+  timezoneName?: string;
+  /** Visible label text rendered above the input. */
+  label?: string;
+  /** Helper text rendered below the control. */
+  description?: string;
+  /** Validation error message. */
+  error?: string;
+  /** Disable all controls. */
+  disabled?: boolean;
+  /** Prevent editing while keeping the submitted value. */
+  readonly?: boolean;
+  /** Mark the time input as required. */
+  required?: boolean;
+  /** Name for form submission. */
+  name?: string;
+  /** Additional CSS classes applied to the root. */
+  class?: string;
+  /** Called when the user commits a time or timezone change. */
+  onchange?: (detail: TimeFieldChange) => void;
+};
+
+export interface TimeFieldSchemaProps {
+  id: string;
+  value?: string;
+  defaultValue?: string;
+  granularity?: TimeFieldGranularity;
+  timezones?: readonly string[];
+  timezone?: string | undefined;
+  timezoneName?: string;
+  label?: string;
+  description?: string;
+  error?: string;
+  disabled?: boolean;
+  readonly?: boolean;
+  required?: boolean;
+  name?: string;
+  class?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  'aria-invalid'?: boolean | 'true' | 'false';
+}

package/src/components/toggle/README.md

@@ -16,17 +16,18 @@ On/off switch input for binary settings, presented as a sliding pill control.
 
 <!-- generated:props:start -->
 
-| Prop        | Type      | Required | Default | Description                                                                                                                                                                                                        |
-| ----------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `checked`   | `boolean` | no       | —       | Whether the toggle is currently checked. Bindable — defaults to false.                                                                                                                                             |
-| `class`     | `string`  | no       | —       | Additional class names merged with `.cinder-toggle` on the switch button.                                                                                                                                          |
-| `disabled`  | `boolean` | no       | —       | Prevents interaction when true. Sets `disabled` attribute.                                                                                                                                                         |
-| `form`      | `string`  | no       | —       | Associates the hidden checkbox with a form by id, matching the native `form` attribute. Lets the toggle submit with a form it is not nested in. Ignored when `name` is unset.                                      |
-| `hideLabel` | `boolean` | no       | —       | Visually hide the rendered label while keeping it as the accessible name. Use for icon-only or inline contexts.                                                                                                    |
-| `id`        | `string`  | yes      | —       | Native id placed on the `<button>`; the rendered label uses `aria-labelledby` to name it (label id is derived as `${id}-label`).                                                                                   |
-| `label`     | `string`  | yes      | —       | Visible label text. Always the accessible name, even when `hideLabel` is set. Required.                                                                                                                            |
-| `name`      | `string`  | no       | —       | Form field name. When set, a hidden checkbox mirrors `checked` so the toggle participates in native form submission. Omit for purely client-side toggles (no hidden input is rendered, so there is zero overhead). |
-| `value`     | `string`  | no       | —       | Value submitted for the hidden checkbox when `checked` and `name` is set. Mirrors native checkbox semantics: the pair `name=value` is sent only while checked. Defaults to `'on'`. Ignored when `name` is unset.   |
+| Prop            | Type       | Required | Default | Description                                                                                                                                                                                                        |
+| --------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `checked`       | `boolean`  | no       | —       | Whether the toggle is currently checked. Bindable — defaults to false.                                                                                                                                             |
+| `class`         | `string`   | no       | —       | Additional class names merged with `.cinder-toggle` on the switch button.                                                                                                                                          |
+| `disabled`      | `boolean`  | no       | —       | Prevents interaction when true. Sets `disabled` attribute.                                                                                                                                                         |
+| `form`          | `string`   | no       | —       | Associates the hidden checkbox with a form by id, matching the native `form` attribute. Lets the toggle submit with a form it is not nested in. Ignored when `name` is unset.                                      |
+| `hideLabel`     | `boolean`  | no       | —       | Visually hide the rendered label while keeping it as the accessible name. Use for icon-only or inline contexts.                                                                                                    |
+| `id`            | `string`   | yes      | —       | Native id placed on the `<button>`; the rendered label uses `aria-labelledby` to name it (label id is derived as `${id}-label`).                                                                                   |
+| `label`         | `string`   | yes      | —       | Visible label text. Always the accessible name, even when `hideLabel` is set. Required.                                                                                                                            |
+| `name`          | `string`   | no       | —       | Form field name. When set, a hidden checkbox mirrors `checked` so the toggle participates in native form submission. Omit for purely client-side toggles (no hidden input is rendered, so there is zero overhead). |
+| `value`         | `string`   | no       | —       | Value submitted for the hidden checkbox when `checked` and `name` is set. Mirrors native checkbox semantics: the pair `name=value` is sent only while checked. Defaults to `'on'`. Ignored when `name` is unset.   |
+| `onValueChange` | `(opaque)` | no       | —       | Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. Not expressible in JSON Schema; see the component types for the signature.                    |
 
 <!-- generated:props:end -->
 

package/src/components/toggle/toggle.svelte

@@ -16,13 +16,16 @@
 
 <script lang="ts">
   import type { ToggleProps } from './toggle.types.ts';
+  import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { commitValue } from '../../utilities/value-change.ts';
 
   let {
     id,
     checked = $bindable(false),
+    onValueChange,
     label,
-    disabled = false,
+    disabled,
     hideLabel = false,
     name,
     value = 'on',
@@ -30,11 +33,21 @@
     class: customClassName,
   }: ToggleProps = $props();
 
+  // A switch implies an immediate-effect setting, so Toggle deliberately does
+  // NOT take on `required`/`error` validation semantics — a deferred boolean in
+  // a submit form should use Checkbox instead (see the module docstring). It
+  // does, however, inherit `disabled` from a wrapping FormField so a disabled
+  // field group greys out the switch alongside its peers.
+  const context = getFormFieldContext();
+  const resolvedDisabled = $derived(disabled ?? context?.disabled ?? false);
+
   const labelId = $derived(`${id}-label`);
 
   function toggle(): void {
-    if (!disabled) {
-      checked = !checked;
+    if (!resolvedDisabled) {
+      commitValue(!checked, onValueChange, (next) => {
+        checked = next;
+      });
     }
   }
 </script>
@@ -46,7 +59,7 @@
     role="switch"
     aria-checked={checked}
     aria-labelledby={labelId}
-    {disabled}
+    disabled={resolvedDisabled}
     onclick={toggle}
     class={classNames('cinder-toggle', customClassName)}
     data-cinder-checked={checked ? '' : undefined}
@@ -65,7 +78,7 @@
       disabled — only `disabled` excludes a control from the form data set.
       Rendered only when `name` is set, so a client-side-only toggle pays nothing.
     -->
-    <input type="checkbox" hidden {name} {value} {form} {disabled} bind:checked />
+    <input type="checkbox" hidden {name} {value} {form} disabled={resolvedDisabled} bind:checked />
   {/if}
   <!--
     The label is a <span> (not a <label for>) named via aria-labelledby. A native
@@ -80,7 +93,7 @@
     class="cinder-toggle-field__label"
     role="presentation"
     data-hidden={hideLabel || undefined}
-    data-disabled={disabled || undefined}
+    data-disabled={resolvedDisabled || undefined}
     onclick={toggle}
   >
     {label}

package/src/components/toggle/toggle.types.ts

@@ -18,6 +18,8 @@ export type ToggleProps = {
   id: string;
   /** Whether the toggle is currently checked. Bindable — defaults to false. */
   checked?: boolean;
+  /** Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. */
+  onValueChange?: (next: boolean) => boolean | void;
   /** Visible label text. Always the accessible name, even when `hideLabel` is set. Required. */
   label: string;
   /** Prevents interaction when true. Sets `disabled` attribute. */

package/src/components/transfer-list/README.md

@@ -31,7 +31,7 @@ from an available pool to a selected set.
 | `leftLabel`  | `string`                                                  | no       | `"Available"` | Accessible and visible label for the left list.                                                                                                 |
 | `rightLabel` | `string`                                                  | no       | `"Selected"`  | Accessible and visible label for the right list.                                                                                                |
 | `value`      | `string`[]                                                | no       | —             | Unique IDs currently assigned to the right-side selected list. Supports `bind:value`. Unknown IDs are ignored and dropped on the next transfer. |
-| `onChange`   | `(opaque)`                                                | no       | —             | Called with the next right-side value after a transfer. Not expressible in JSON Schema; see the component types for the signature.              |
+| `onchange`   | `(opaque)`                                                | no       | —             | Called with the next right-side value after a transfer. Not expressible in JSON Schema; see the component types for the signature.              |
 
 <!-- generated:props:end -->
 

package/src/components/transfer-list/transfer-list.css

@@ -42,6 +42,17 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-transfer-list__list:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* Negative offset because __list has overflow:auto — a positive offset
+         would be clipped by the scrolling container and the ring can disappear.
+         An inset ring always paints inside the box regardless of overflow. */
+      outline-offset: calc(-1 * var(--cinder-ring-width));
+      box-shadow: none;
+    }
+  }
+
   .cinder-transfer-list__option {
     padding: var(--cinder-space-2) var(--cinder-space-3);
     border-radius: var(--cinder-radius-sm);
@@ -101,6 +112,17 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-transfer-list__control:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* 3px separates the outline from ButtonBorder (which renders in forced-colors
+         on all bordered controls and shares the ButtonText color family in HCM);
+         at 2px the ring and border can visually merge. */
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   @container cinder-transfer-list (max-width: 42rem) {
     .cinder-transfer-list__layout {
       grid-template-columns: minmax(0, 1fr);