@human-kit/svelte-components 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/checkbox/root/README.md

@@ -0,0 +1,47 @@
+# Checkbox Root
+
+## API reference
+
+### Checkbox.Root
+
+Name: `Checkbox.Root`  
+Description: Interactive tri-state checkbox root that owns checked, indeterminate, focus, and hidden input synchronization.
+
+| Prop                    | Type                               | Default       | Description                                                      |
+| ----------------------- | ---------------------------------- | ------------- | ---------------------------------------------------------------- |
+| `id`                    | `string`                           | `$props.id()` | Stable id used for the hidden input and derived root id.         |
+| `name`                  | `string`                           | `undefined`   | Form field name forwarded to the hidden native input.            |
+| `value`                 | `string`                           | `'on'`        | Submitted value when the checkbox is checked.                    |
+| `isChecked`             | `boolean`                          | `undefined`   | Controlled checked state. Supports `bind:isChecked`.             |
+| `defaultChecked`        | `boolean`                          | `false`       | Initial checked state in uncontrolled mode.                      |
+| `isIndeterminate`       | `boolean`                          | `undefined`   | Controlled indeterminate state. Supports `bind:isIndeterminate`. |
+| `defaultIndeterminate`  | `boolean`                          | `false`       | Initial indeterminate state in uncontrolled mode.                |
+| `onCheckedChange`       | `(checked: boolean) => void`       | `undefined`   | Called when the effective checked state changes.                 |
+| `onIndeterminateChange` | `(indeterminate: boolean) => void` | `undefined`   | Called when the effective indeterminate state changes.           |
+| `isDisabled`            | `boolean`                          | `false`       | Prevents focus and state changes.                                |
+| `isReadOnly`            | `boolean`                          | `false`       | Allows focus but blocks user-driven state changes.               |
+| `required`              | `boolean`                          | `false`       | Marks the hidden input as required and exposes `data-required`.  |
+| `children`              | `Snippet`                          | `undefined`   | Composed checkbox parts such as `Checkbox.Indicator`.            |
+| `class`                 | `string`                           | `''`          | CSS class names for the root element.                            |
+| `...restProps`          | `HTMLAttributes<HTMLSpanElement>`  | `-`           | Additional attributes forwarded to the checkbox root span.       |
+
+### Context utilities
+
+Name: `context.ts` helpers  
+Description: Internal APIs for publishing and consuming checkbox state.
+
+| Prop                 | Type                                 | Default | Description                                        |
+| -------------------- | ------------------------------------ | ------- | -------------------------------------------------- |
+| `setCheckboxContext` | `(ctx: CheckboxContext) => void`     | `-`     | Registers the checkbox context in root.            |
+| `getCheckboxContext` | `() => CheckboxContext \| undefined` | `-`     | Returns the context when available.                |
+| `useCheckboxContext` | `() => CheckboxContext`              | `-`     | Returns the context and throws outside root usage. |
+
+`CheckboxState` is the internal state union used by the root context: `'checked' | 'unchecked' | 'indeterminate'`.
+
+```svelte
+<Checkbox.Root bind:isChecked bind:isIndeterminate aria-label="Notifications">
+	<Checkbox.Indicator>
+		<CheckIcon />
+	</Checkbox.Indicator>
+</Checkbox.Root>
+```

package/dist/checkbox/root/checkbox-label-test.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import { Checkbox } from '../index.ts';
+</script>
+
+<label for="notifications">Enable notifications</label>
+<Checkbox.Root id="notifications" aria-label="Notifications">
+	<Checkbox.Indicator>
+		<span data-checkbox-icon="true">icon</span>
+	</Checkbox.Indicator>
+</Checkbox.Root>

package/dist/checkbox/root/checkbox-label-test.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CheckboxLabelTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CheckboxLabelTest = InstanceType<typeof CheckboxLabelTest>;
+export default CheckboxLabelTest;

package/dist/checkbox/root/checkbox-root.svelte

@@ -0,0 +1,386 @@
+<script lang="ts">
+	import { untrack, type Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+	import { cn } from '../../utils/cn';
+	import { setCheckboxContext, type CheckboxContext, type CheckboxState } from './context';
+
+	type CheckboxRootProps = Omit<
+		HTMLAttributes<HTMLSpanElement>,
+		| 'children'
+		| 'class'
+		| 'id'
+		| 'role'
+		| 'aria-checked'
+		| 'aria-disabled'
+		| 'aria-readonly'
+		| 'aria-required'
+		| 'onclick'
+		| 'onkeydown'
+		| 'value'
+	> & {
+		id?: string;
+		element?: HTMLSpanElement | null;
+		name?: string;
+		value?: string;
+		isChecked?: boolean;
+		defaultChecked?: boolean;
+		isIndeterminate?: boolean;
+		defaultIndeterminate?: boolean;
+		onCheckedChange?: (checked: boolean) => void;
+		onIndeterminateChange?: (indeterminate: boolean) => void;
+		isDisabled?: boolean;
+		isReadOnly?: boolean;
+		required?: boolean;
+		children?: Snippet;
+		class?: string;
+		'aria-label'?: string;
+		'aria-labelledby'?: string;
+		tabindex?: number;
+		onclick?: HTMLAttributes<HTMLSpanElement>['onclick'];
+		onkeydown?: HTMLAttributes<HTMLSpanElement>['onkeydown'];
+		onfocus?: HTMLAttributes<HTMLSpanElement>['onfocus'];
+		onmousedown?: HTMLAttributes<HTMLSpanElement>['onmousedown'];
+	};
+
+	function composeEventHandlers<TEvent extends Event>(
+		internalHandler: ((event: TEvent) => void) | undefined,
+		externalHandler: ((event: TEvent) => void) | undefined
+	): (event: TEvent) => void {
+		return (event: TEvent) => {
+			internalHandler?.(event);
+			externalHandler?.(event);
+		};
+	}
+
+	function resolveState(isChecked: boolean, isIndeterminate: boolean): CheckboxState {
+		if (isIndeterminate) return 'indeterminate';
+		return isChecked ? 'checked' : 'unchecked';
+	}
+
+	function getNextState(currentState: CheckboxState): CheckboxState {
+		if (currentState === 'indeterminate') return 'checked';
+		if (currentState === 'checked') return 'unchecked';
+		return 'checked';
+	}
+
+	const generatedId = $props.id();
+
+	let {
+		id,
+		element = $bindable(),
+		name,
+		value = 'on',
+		isChecked = $bindable(),
+		defaultChecked = false,
+		isIndeterminate = $bindable(),
+		defaultIndeterminate = false,
+		onCheckedChange,
+		onIndeterminateChange,
+		isDisabled = false,
+		isReadOnly = false,
+		required = false,
+		children,
+		class: className = '',
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		tabindex,
+		onclick: onClickExternal,
+		onkeydown: onKeyDownExternal,
+		onfocus: onFocusExternal,
+		onmousedown: onMouseDownExternal,
+		...restProps
+	}: CheckboxRootProps = $props();
+
+	const instanceId = untrack(() => id) ?? generatedId;
+	const inputId = instanceId;
+	const rootId = `${instanceId}-root`;
+
+	const initialChecked = untrack(() => isChecked ?? defaultChecked);
+	const initialIndeterminate = untrack(() => isIndeterminate ?? defaultIndeterminate);
+	const initialState = resolveState(initialChecked, initialIndeterminate);
+
+	let checkedInternal = $state(initialState === 'checked');
+	let indeterminateInternal = $state(initialState === 'indeterminate');
+	let pressed = $state(false);
+	let pressedKey: 'Enter' | 'Space' | null = $state(null);
+	let focused = $state(false);
+	let focusVisible = $state(false);
+	let rootRef: HTMLSpanElement | null = $state(null);
+	let inputRef: HTMLInputElement | null = $state(null);
+
+	$effect(() => {
+		element = rootRef;
+	});
+
+	if (untrack(() => isChecked) === undefined) {
+		isChecked = initialState === 'checked';
+	}
+
+	if (untrack(() => isIndeterminate) === undefined) {
+		isIndeterminate = initialState === 'indeterminate';
+	}
+
+	const isCheckedControlled = $derived(isChecked !== undefined);
+	const isIndeterminateControlled = $derived(isIndeterminate !== undefined);
+
+	const currentState = $derived.by(() =>
+		resolveState(
+			isCheckedControlled ? Boolean(isChecked) : checkedInternal,
+			isIndeterminateControlled ? Boolean(isIndeterminate) : indeterminateInternal
+		)
+	);
+
+	const currentChecked = $derived(currentState === 'checked');
+	const currentIndeterminate = $derived(currentState === 'indeterminate');
+	const currentUnchecked = $derived(currentState === 'unchecked');
+
+	function publishState(nextState: CheckboxState, event?: Event) {
+		const nextChecked = nextState === 'checked';
+		const nextIndeterminate = nextState === 'indeterminate';
+		const previousChecked = currentChecked;
+		const previousIndeterminate = currentIndeterminate;
+
+		if (!isCheckedControlled) {
+			checkedInternal = nextChecked;
+		}
+
+		if (!isIndeterminateControlled) {
+			indeterminateInternal = nextIndeterminate;
+		}
+
+		isChecked = nextChecked;
+		isIndeterminate = nextIndeterminate;
+
+		if (nextChecked !== previousChecked) {
+			onCheckedChange?.(nextChecked);
+		}
+
+		if (nextIndeterminate !== previousIndeterminate) {
+			onIndeterminateChange?.(nextIndeterminate);
+		}
+
+		if (event && rootRef && document.activeElement !== rootRef) {
+			rootRef.focus();
+		}
+	}
+
+	function setState(nextState: CheckboxState, event?: Event) {
+		if (isDisabled || isReadOnly) return;
+		publishState(nextState, event);
+	}
+
+	function toggle(event?: Event) {
+		setState(getNextState(currentState), event);
+	}
+
+	function requestNativeToggle(event?: Event) {
+		if (isDisabled || isReadOnly) return;
+		if (!inputRef) {
+			toggle(event);
+			return;
+		}
+
+		inputRef.click();
+	}
+
+	function handleClick(event: MouseEvent) {
+		trackInteractionModality(event, rootRef);
+
+		if (event.defaultPrevented) return;
+		if (isDisabled || isReadOnly) {
+			event.preventDefault();
+			return;
+		}
+
+		event.preventDefault();
+		requestNativeToggle(event);
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		if (event.defaultPrevented) return;
+		if (event.key !== ' ' && event.key !== 'Spacebar' && event.key !== 'Enter') return;
+
+		trackInteractionModality(event, rootRef);
+		if (focused) {
+			focusVisible = true;
+		} else {
+			focusVisible = shouldShowFocusVisible(rootRef);
+		}
+		event.preventDefault();
+
+		if (event.repeat && pressed) return;
+
+		pressed = true;
+		pressedKey = event.key === 'Enter' ? 'Enter' : 'Space';
+	}
+
+	function handleKeyUp(event: KeyboardEvent) {
+		if (event.defaultPrevented) return;
+
+		const releasedKey =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+		if (!releasedKey) return;
+
+		trackInteractionModality(event, rootRef);
+		if (focused) {
+			focusVisible = true;
+		} else {
+			focusVisible = shouldShowFocusVisible(rootRef);
+		}
+		event.preventDefault();
+
+		const shouldToggle = pressed && pressedKey === releasedKey;
+		pressed = false;
+		pressedKey = null;
+
+		if (!shouldToggle) return;
+		requestNativeToggle(event);
+	}
+
+	function handlePointerDown(event: PointerEvent | MouseEvent) {
+		trackInteractionModality(event, rootRef);
+		focusVisible = false;
+	}
+
+	function handleFocus() {
+		focused = true;
+		focusVisible = shouldShowFocusVisible(rootRef);
+	}
+
+	function handleBlur() {
+		focused = false;
+		focusVisible = false;
+		pressed = false;
+		pressedKey = null;
+	}
+
+	function handleInputChange(event: Event) {
+		const target = event.currentTarget;
+		if (!(target instanceof HTMLInputElement)) return;
+
+		const nextState = resolveState(target.checked, target.indeterminate);
+		publishState(nextState, event);
+	}
+
+	function handleInputFocus() {
+		rootRef?.focus();
+	}
+
+	function handleInputClick(event: MouseEvent) {
+		event.stopPropagation();
+	}
+
+	$effect(() => {
+		if (!inputRef) return;
+		inputRef.checked = currentChecked;
+		inputRef.indeterminate = currentIndeterminate;
+	});
+
+	setCheckboxContext({
+		get id() {
+			return rootId;
+		},
+		get inputId() {
+			return inputId;
+		},
+		get inputRef() {
+			return inputRef;
+		},
+		setInputRef(element) {
+			inputRef = element;
+		},
+		get state() {
+			return currentState;
+		},
+		get pressed() {
+			return pressed;
+		},
+		get isChecked() {
+			return currentChecked;
+		},
+		get isIndeterminate() {
+			return currentIndeterminate;
+		},
+		get isDisabled() {
+			return isDisabled;
+		},
+		get isReadOnly() {
+			return isReadOnly;
+		},
+		get required() {
+			return required;
+		},
+		get focused() {
+			return focused;
+		},
+		get focusVisible() {
+			return focusVisible;
+		},
+		toggle,
+		setState
+	} satisfies CheckboxContext);
+</script>
+
+<span
+	{...restProps}
+	bind:this={rootRef}
+	id={rootId}
+	role="checkbox"
+	tabindex={isDisabled ? undefined : (tabindex ?? 0)}
+	aria-checked={currentIndeterminate ? 'mixed' : currentChecked ? 'true' : 'false'}
+	aria-disabled={isDisabled || undefined}
+	aria-readonly={isReadOnly || undefined}
+	aria-required={required || undefined}
+	aria-label={ariaLabel}
+	aria-labelledby={ariaLabelledby}
+	data-checkbox-root="true"
+	data-checked={currentChecked || undefined}
+	data-unchecked={currentUnchecked || undefined}
+	data-indeterminate={currentIndeterminate || undefined}
+	data-pressed={pressed || undefined}
+	data-disabled={isDisabled || undefined}
+	data-readonly={isReadOnly || undefined}
+	data-required={required || undefined}
+	data-focused={focused || undefined}
+	data-focus-visible={focusVisible || undefined}
+	onclick={composeEventHandlers(onClickExternal ?? undefined, handleClick)}
+	onkeydown={composeEventHandlers(handleKeyDown, onKeyDownExternal ?? undefined)}
+	onkeyup={handleKeyUp}
+	onpointerdown={handlePointerDown}
+	onmousedown={composeEventHandlers(onMouseDownExternal ?? undefined, handlePointerDown)}
+	onfocus={composeEventHandlers(handleFocus, onFocusExternal ?? undefined)}
+	onblur={handleBlur}
+	class={cn(
+		'relative inline-flex shrink-0 items-center justify-center align-middle outline-none',
+		className
+	)}
+>
+	<input
+		bind:this={inputRef}
+		id={inputId}
+		tabindex={-1}
+		type="checkbox"
+		{name}
+		{value}
+		checked={currentChecked}
+		disabled={isDisabled}
+		{required}
+		readonly={isReadOnly}
+		aria-hidden="true"
+		data-checkbox-input="true"
+		onclick={handleInputClick}
+		onchange={handleInputChange}
+		onfocus={handleInputFocus}
+		style="position:absolute;inset:0;width:100%;height:100%;margin:0;padding:0;border:0;opacity:0;cursor:inherit;pointer-events:none;"
+	/>
+
+	{@render children?.()}
+</span>

package/dist/checkbox/root/checkbox-root.svelte.d.ts

@@ -0,0 +1,29 @@
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type CheckboxRootProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class' | 'id' | 'role' | 'aria-checked' | 'aria-disabled' | 'aria-readonly' | 'aria-required' | 'onclick' | 'onkeydown' | 'value'> & {
+    id?: string;
+    element?: HTMLSpanElement | null;
+    name?: string;
+    value?: string;
+    isChecked?: boolean;
+    defaultChecked?: boolean;
+    isIndeterminate?: boolean;
+    defaultIndeterminate?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    onIndeterminateChange?: (indeterminate: boolean) => void;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    required?: boolean;
+    children?: Snippet;
+    class?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    tabindex?: number;
+    onclick?: HTMLAttributes<HTMLSpanElement>['onclick'];
+    onkeydown?: HTMLAttributes<HTMLSpanElement>['onkeydown'];
+    onfocus?: HTMLAttributes<HTMLSpanElement>['onfocus'];
+    onmousedown?: HTMLAttributes<HTMLSpanElement>['onmousedown'];
+};
+declare const CheckboxRoot: import("svelte").Component<CheckboxRootProps, {}, "element" | "isChecked" | "isIndeterminate">;
+type CheckboxRoot = ReturnType<typeof CheckboxRoot>;
+export default CheckboxRoot;

package/dist/checkbox/root/checkbox-test.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+	import { Checkbox } from '../index';
+
+	type Props = {
+		id?: string;
+		name?: string;
+		value?: string;
+		isChecked?: boolean;
+		defaultChecked?: boolean;
+		isIndeterminate?: boolean;
+		defaultIndeterminate?: boolean;
+		isDisabled?: boolean;
+		isReadOnly?: boolean;
+		required?: boolean;
+		keepMounted?: boolean;
+		onCheckedChange?: (checked: boolean) => void;
+		onIndeterminateChange?: (indeterminate: boolean) => void;
+	};
+
+	let {
+		id,
+		name,
+		value = 'newsletter',
+		isChecked = $bindable(),
+		defaultChecked = false,
+		isIndeterminate = $bindable(),
+		defaultIndeterminate = false,
+		isDisabled = false,
+		isReadOnly = false,
+		required = false,
+		keepMounted = false,
+		onCheckedChange,
+		onIndeterminateChange
+	}: Props = $props();
+</script>
+
+<Checkbox.Root
+	{id}
+	{name}
+	{value}
+	bind:isChecked
+	{defaultChecked}
+	bind:isIndeterminate
+	{defaultIndeterminate}
+	{isDisabled}
+	{isReadOnly}
+	{required}
+	{onCheckedChange}
+	{onIndeterminateChange}
+	class="inline-flex h-5 w-5 items-center justify-center"
+	aria-label="Accept terms"
+>
+	<Checkbox.Indicator {keepMounted}>
+		<span data-checkbox-icon="true">icon</span>
+	</Checkbox.Indicator>
+</Checkbox.Root>
+
+<output data-checked-state>{String(isChecked ?? false)}</output>
+<output data-indeterminate-state>{String(isIndeterminate ?? false)}</output>

package/dist/checkbox/root/checkbox-test.svelte.d.ts

@@ -0,0 +1,18 @@
+type Props = {
+    id?: string;
+    name?: string;
+    value?: string;
+    isChecked?: boolean;
+    defaultChecked?: boolean;
+    isIndeterminate?: boolean;
+    defaultIndeterminate?: boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    required?: boolean;
+    keepMounted?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    onIndeterminateChange?: (indeterminate: boolean) => void;
+};
+declare const CheckboxTest: import("svelte").Component<Props, {}, "isChecked" | "isIndeterminate">;
+type CheckboxTest = ReturnType<typeof CheckboxTest>;
+export default CheckboxTest;

package/dist/checkbox/root/context.d.ts

@@ -0,0 +1,21 @@
+export type CheckboxState = 'checked' | 'unchecked' | 'indeterminate';
+export type CheckboxContext = {
+    id: string;
+    inputId: string;
+    inputRef: HTMLInputElement | null;
+    setInputRef: (element: HTMLInputElement | null) => void;
+    state: CheckboxState;
+    pressed: boolean;
+    isChecked: boolean;
+    isIndeterminate: boolean;
+    isDisabled: boolean;
+    isReadOnly: boolean;
+    required: boolean;
+    focused: boolean;
+    focusVisible: boolean;
+    toggle: (event?: Event) => void;
+    setState: (state: CheckboxState, event?: Event) => void;
+};
+export declare function setCheckboxContext(context: CheckboxContext): void;
+export declare function getCheckboxContext(): CheckboxContext | undefined;
+export declare function useCheckboxContext(): CheckboxContext;

package/dist/checkbox/root/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const CHECKBOX_CONTEXT_KEY = Symbol('checkbox');
+export function setCheckboxContext(context) {
+    setContext(CHECKBOX_CONTEXT_KEY, context);
+}
+export function getCheckboxContext() {
+    return getContext(CHECKBOX_CONTEXT_KEY);
+}
+export function useCheckboxContext() {
+    const context = getCheckboxContext();
+    if (!context) {
+        throw new Error('Checkbox components must be used within Checkbox.Root.');
+    }
+    return context;
+}

package/dist/clock/README.md

@@ -0,0 +1,75 @@
+# Clock
+
+## Description
+
+`Clock` provides a standalone wheel-based time picker with spinbutton columns for hour, minute, second, and day-period selection. It can be used independently or composed inside `TimePicker` via `TimePicker.Clock`.
+
+## Anatomy
+
+- `Clock.Root`
+- `Clock.Axis`
+- `Clock.WheelColumn`
+- `Clock.WheelItem`
+
+```svelte
+<Clock.Root value="14:30" granularity="minute" hourCycle={24} class="flex gap-2">
+	{#snippet column(col)}
+		<Clock.WheelColumn type={col.type} class="h-44 w-16">
+			{#snippet children(option)}
+				<Clock.WheelItem type={col.type} {option} class="..." />
+			{/snippet}
+		</Clock.WheelColumn>
+	{/snippet}
+	<Clock.Axis class="rounded-md ring-1 ring-inset" />
+</Clock.Root>
+```
+
+Default columns are rendered automatically when no `column` snippet is provided:
+
+```svelte
+<Clock.Root value="09:00" granularity="minute" hourCycle={24} />
+```
+
+## Root API
+
+- `value?: string | null` (`HH:mm` or `HH:mm:ss`)
+- `defaultValue?: string | null` (`HH:mm` or `HH:mm:ss`)
+- `onChange?: (value: string | null) => void`
+- `minValue?: string`
+- `maxValue?: string`
+- `hourCycle?: 12 | 24` (defaults to locale)
+- `granularity?: 'hour' | 'minute' | 'second'` (defaults to `'minute'`)
+- `hourStep?: number`
+- `minuteStep?: number`
+- `secondStep?: number`
+- `isDisabled?: boolean`
+- `column?: Snippet<[ClockColumnInfo]>` — custom per-column rendering
+- `children?: Snippet` — arbitrary children. When `column` is used, children render after columns (useful for overlays like `Clock.Axis`).
+- `class?: string`
+- `aria-label?: string`
+
+Visible columns are resolved automatically in stable order: `hour → minute? → second? → dayPeriod?`.
+
+## Wheel API
+
+- `Clock.Axis` renders a root-level visual overlay (for example, a central selection band) across all columns.
+- `Clock.WheelColumn` renders one wheel (`role="spinbutton"`) for one editable segment (`hour`, `minute`, `second`, or `dayPeriod`).
+- `Clock.WheelItem` is headless: it renders one item (`data-wheel-item`) with state attributes (`data-selected`, `data-disabled`, `data-centered`) and leaves all visual styling to consumers.
+- `ClockColumnInfo` shape:
+  - `type: 'hour' | 'minute' | 'second' | 'dayPeriod'`
+  - `label?: string`
+
+## Accessibility
+
+- Each wheel column exposes `role="spinbutton"` with `aria-valuenow`, `aria-valuetext`, `aria-valuemin`, and `aria-valuemax`.
+- `ArrowUp/ArrowDown`: change value by one step.
+- `ArrowLeft/ArrowRight`: move focus between columns.
+- `Home/End`: jump to first/last value in the column.
+
+## Notes
+
+- Locale is read from `LocaleProvider` when available.
+- Internally, values are normalized to 24-hour representation; 12-hour rendering only affects UI segments.
+- `granularity='hour'` emits `HH:00` values.
+- Min/max comparisons do not support midnight-wrapping ranges.
+- Wheel selection commits immediately on snap.