@human-kit/svelte-components 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/datepicker/root/README.md

@@ -0,0 +1,38 @@
+# DatePicker Root
+
+## API reference
+
+### DatePicker.Root
+
+Name: `DatePicker.Root`  
+Description: State container for segmented date input, popover lifecycle, calendar selection, and validation constraints.
+
+| Prop                | Type                                           | Default     | Description                                               |
+| ------------------- | ---------------------------------------------- | ----------- | --------------------------------------------------------- |
+| `value`             | `DatePickerDateValue \| null`                  | `bindable`  | Controlled ISO date value (`YYYY-MM-DD`).                 |
+| `defaultValue`      | `DatePickerDateValue \| null`                  | `undefined` | Initial date value for uncontrolled mode.                 |
+| `onChange`          | `(value: DatePickerDateValue \| null) => void` | `undefined` | Called when committed date value changes.                 |
+| `open`              | `boolean`                                      | `bindable`  | Controlled open state for the popover panel.              |
+| `defaultOpen`       | `boolean`                                      | `false`     | Initial open state in uncontrolled mode.                  |
+| `onOpenChange`      | `(open: boolean, details) => void`             | `undefined` | Called on open-state transitions (supports cancellation). |
+| `closeOnSelect`     | `boolean`                                      | `true`      | Closes the popover after calendar selection.              |
+| `minValue`          | `DatePickerDateValue`                          | `undefined` | Optional lower bound for selectable dates.                |
+| `maxValue`          | `DatePickerDateValue`                          | `undefined` | Optional upper bound for selectable dates.                |
+| `isDateUnavailable` | `(date: DatePickerDateValue) => boolean`       | `undefined` | Optional predicate to block unavailable dates.            |
+| `isDisabled`        | `boolean`                                      | `false`     | Disables interaction and selection.                       |
+| `isReadOnly`        | `boolean`                                      | `false`     | Prevents value changes while preserving navigation.       |
+| `children`          | `Snippet`                                      | `undefined` | Composed `DatePicker` parts.                              |
+| `class`             | `string`                                       | `''`        | CSS class names for root wrapper.                         |
+| `aria-label`        | `string`                                       | `undefined` | Accessible label for the root wrapper.                    |
+
+### Context utilities
+
+Name: `setDatePickerContext` / `getDatePickerContext` / `useDatePickerContext`  
+Description: Context helpers for internal/public `DatePicker` part composition.
+
+| Prop                   | Type                                   | Default | Description                                         |
+| ---------------------- | -------------------------------------- | ------- | --------------------------------------------------- |
+| `setDatePickerContext` | `(ctx: DatePickerContext) => void`     | `-`     | Publishes root context.                             |
+| `getDatePickerContext` | `() => DatePickerContext \| undefined` | `-`     | Reads context when available.                       |
+| `useDatePickerContext` | `() => DatePickerContext`              | `-`     | Reads context and throws outside `DatePicker.Root`. |
+| `DatePickerContext`    | `type`                                 | `-`     | Shared context contract for all datepicker parts.   |

package/dist/datepicker/segment/README.md

@@ -0,0 +1,14 @@
+# DatePicker Segment
+
+## API reference
+
+### DatePicker.Segment
+
+Name: `DatePicker.Segment`  
+Description: Editable (or literal) date segment renderer used inside `DatePicker.Input`.
+
+| Prop           | Type                              | Default    | Description                                             |
+| -------------- | --------------------------------- | ---------- | ------------------------------------------------------- |
+| `segment`      | `DatePickerSegmentPart`           | `required` | Segment metadata and text payload.                      |
+| `class`        | `string`                          | `''`       | CSS class names for the segment span element.           |
+| `...restProps` | `HTMLAttributes<HTMLSpanElement>` | `-`        | Additional attributes forwarded to the segment element. |

package/dist/datepicker/trigger/README.md

@@ -0,0 +1,14 @@
+# DatePicker Trigger
+
+## API reference
+
+### DatePicker.Trigger
+
+Name: `DatePicker.Trigger`  
+Description: Button part that toggles `DatePicker.Popover` and anchors positioning/focus behavior.
+
+| Prop           | Type                   | Default     | Description                                            |
+| -------------- | ---------------------- | ----------- | ------------------------------------------------------ |
+| `children`     | `Snippet`              | `undefined` | Optional trigger content.                              |
+| `class`        | `string`               | `''`        | CSS class names for the trigger button.                |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional button attributes forwarded to the trigger. |

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { ComboBox } from './combobox/index.ts';
 export { Calendar } from './calendar/index.ts';
+export { Clock } from './clock/index.ts';
 export { DatePicker } from './datepicker/index.ts';
+export { TimePicker } from './timepicker/index.ts';
 export { Dialog } from './dialog/index.ts';
 export { ListBox } from './listbox/index.ts';
 export { Popover } from './popover/index.ts';
@@ -11,10 +13,13 @@ export { Portal } from './portal/index.ts';
 export * from './locale-provider/index.ts';
 export * from './combobox/index.ts';
 export * from './calendar/index.ts';
+export * from './clock/index.ts';
 export * from './datepicker/index.ts';
+export * from './timepicker/index.ts';
 export * from './dialog/index.ts';
 export * from './listbox/index.ts';
 export * from './popover/index.ts';
 export * from './primitives/index.ts';
 export { cn } from './utils/index.ts';
 export * from './utils/index.ts';
+export * from './utils/index.ts';

package/dist/index.js

@@ -2,7 +2,9 @@
 // Components (namespace exports)
 export { ComboBox } from './combobox/index.ts';
 export { Calendar } from './calendar/index.ts';
+export { Clock } from './clock/index.ts';
 export { DatePicker } from './datepicker/index.ts';
+export { TimePicker } from './timepicker/index.ts';
 export { Dialog } from './dialog/index.ts';
 export { ListBox } from './listbox/index.ts';
 export { Popover } from './popover/index.ts';
@@ -15,7 +17,9 @@ export * from './locale-provider/index.ts';
 // Re-export named exports from components
 export * from './combobox/index.ts';
 export * from './calendar/index.ts';
+export * from './clock/index.ts';
 export * from './datepicker/index.ts';
+export * from './timepicker/index.ts';
 export * from './dialog/index.ts';
 export * from './listbox/index.ts';
 export * from './popover/index.ts';
@@ -24,3 +28,4 @@ export * from './primitives/index.ts';
 // Utilities
 export { cn } from './utils/index.ts';
 export * from './utils/index.ts';
+export * from './utils/index.ts';

package/dist/primitives/focus-trap.js

@@ -2,6 +2,7 @@
  * Focus trap primitive.
  * Traps keyboard focus within a container element.
  */
+import { focusWithModality, getInteractionModality } from './input-modality';
 const FOCUSABLE_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
@@ -33,7 +34,7 @@ function resolveInitialFocus(container, initialFocus) {
     return initialFocus;
 }
 function getFocusableElements(container) {
-    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetParent !== null);
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => element.offsetParent !== null);
 }
 /**
  * Svelte action that traps focus within an element.
@@ -73,12 +74,11 @@ export function focusTrap(node, options = true) {
                 event.preventDefault();
                 lastElement.focus();
             }
+            return;
         }
-        else {
-            if (document.activeElement === lastElement || document.activeElement === node) {
-                event.preventDefault();
-                firstElement.focus();
-            }
+        if (document.activeElement === lastElement || document.activeElement === node) {
+            event.preventDefault();
+            firstElement.focus();
         }
     }
     function activate() {
@@ -86,20 +86,19 @@ export function focusTrap(node, options = true) {
         if (!node.hasAttribute('tabindex')) {
             node.setAttribute('tabindex', '-1');
         }
-        // Focus first focusable element, or the container if none
         requestAnimationFrame(() => {
             const initialFocusTarget = resolveInitialFocus(node, initialFocus);
+            const modality = getInteractionModality();
             if (initialFocusTarget && initialFocusTarget.isConnected) {
-                initialFocusTarget.focus();
+                focusWithModality(initialFocusTarget, modality);
                 return;
             }
             const focusableElements = getFocusableElements(node);
             if (focusableElements.length > 0) {
-                focusableElements[0].focus();
-            }
-            else {
-                node.focus();
+                focusWithModality(focusableElements[0], modality);
+                return;
             }
+            focusWithModality(node, modality);
         });
         document.addEventListener('keydown', handleKeydown, true);
     }

package/dist/primitives/input-modality.js

@@ -95,7 +95,16 @@ export function focusWithModality(target, modality, options) {
     forcedFocusTarget = target;
     forcedFocusModality = modality;
     currentModality = modality;
-    target.focus(options);
+    if (modality === 'pointer') {
+        const pointerFocusOptions = {
+            ...(options ?? {}),
+            focusVisible: false
+        };
+        target.focus(pointerFocusOptions);
+    }
+    else {
+        target.focus(options);
+    }
     queueMicrotask(() => {
         if (forcedFocusTarget !== target)
             return;

package/dist/timepicker/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,254 @@
+# TimePicker Implementation Plan
+
+## Scope
+
+Implement all open items from `TODO.md` in one delivery, prioritizing correctness and stability first, then accessibility/performance, and finally coverage hardening.
+
+## Goals
+
+- Fix state/event correctness regressions first.
+- Keep wheel interaction fluid while improving robustness.
+- Add missing accessibility semantics without introducing noisy behavior.
+- Apply low-risk performance improvements.
+- Expand tests to protect the full wheel pipeline.
+
+## Phase 1 — Correctness (P0/P1 behavior)
+
+### 1a) Allow external clearing via `value = undefined`
+
+**Files**
+
+- `root/time-picker-root.svelte`
+
+**Changes**
+
+- Remove the `if (value === undefined) return;` early-return in the `$effect` that observes `value`.
+- When `value` becomes `undefined`, treat it as an explicit clear: reset `segmentDraft` to empty, set `valueInternal = null`, and publish `null` via `publishCommittedValue`.
+
+**Risk**
+
+- Controlled/uncontrolled sync regressions — initial mount with `value={undefined}` must not trigger a spurious publish.
+
+**Validation**
+
+- `bun run test -- --run src/lib/timepicker/root/time-picker-root.test.ts`
+
+### 1b) Publish `null` when all segments are cleared
+
+**Files**
+
+- `root/time-picker-root.svelte`
+
+**Changes**
+
+- In `commitFromDraft`, when `buildTimePartsFromDraft` returns `null` **and** `hasAnyRequiredValue` is `false` (every segment is empty), call `publishCommittedValue(null)` instead of doing a silent return.
+- This ensures `bind:value` transitions from a valid time to `null` when the user backspaces every segment.
+
+**Risk**
+
+- Must avoid re-publishing `null` on every keystroke while segments are partially filled — the `hasAnyRequiredValue === true` path already handles that correctly.
+
+**Validation**
+
+- `bun run test -- --run src/lib/timepicker/root/time-picker-root.test.ts`
+
+### 2) Event forwarding consistency
+
+**Files**
+
+- `input/time-picker-input.svelte`
+- `trigger/time-picker-trigger.svelte`
+  **Changes**
+
+- Compose external/internal handlers consistently.
+
+- User handlers accidentally suppress internal logic.
+
+- `bun run test -- --run src/lib/timepicker/input/time-picker-input.test.ts src/lib/timepicker/trigger/time-picker-trigger.test.ts`
+
+- Add safety restoration to current draft value when drift is detected.
+
+**Policy**
+
+- Implement guard + restore strategy aligned with TODO note.
+  **Risk**
+
+- IME/paste edge cases and cross-browser input events.
+  **Validation**
+
+- `bun run test -- --run src/lib/timepicker/segment/time-picker-segment.test.ts`
+
+**Files**
+
+- `segment/time-picker-segment.svelte`
+
+- Use explicit 12h boundaries (`1`/`12`) instead of relying on clamping side effects.
+
+- Segment keyboard tests in same run as above.
+
+---
+
+## Phase 2 — Wheel stability and interaction quality
+
+### 5) Wheel settle behavior and anchor sync
+
+**Files**
+**Changes**
+
+- Increase scroll debounce fallback from 64ms to 120ms. The debounce only fires in browsers without native `scrollend` support, so higher values do not affect perceived latency. 120ms is conservative enough to avoid interrupting touch momentum on iOS Safari.
+  **Risk**
+
+- Async timing loops (`scroll`, `scrollend`, debounce). The silent flag must be cleared reliably (on `scrollend` or animation completion).
+  **Validation**
+
+- `bun run test -- --run src/lib/clock/wheel-column/clock-wheel-column.test.ts src/lib/clock/panel/clock-panel.test.ts`
+
+### 6) ResizeObserver loop mitigation
+
+**Files**
+
+- `../clock/wheel-column/clock-wheel-column.svelte`
+- Batch measurement updates through `requestAnimationFrame` to reduce observer-loop warnings.
+
+**Validation**
+
+- Re-run wheel and root tests:
+- `bun run test -- --run src/lib/clock/wheel-column/clock-wheel-column.test.ts src/lib/timepicker/root/time-picker-root.test.ts`
+
+## Phase 3 — Accessibility and API surface
+
+### 7) Wheel announcements and semantics
+
+- `../clock/wheel-column/clock-wheel-column.svelte`
+
+**Changes**
+
+- Add `aria-roledescription` on wheel spinbutton.
+
+**Risk**
+
+- Over-announcement/noise for SR users.
+
+### 8) `isRequired` propagation
+
+**Files**
+
+- `root/time-picker-root.svelte`
+- `root/context.ts`
+- `input/time-picker-input.svelte`
+- `README.md`
+
+- Add `isRequired` to root API and context.
+- Expose `aria-required` on input group.
+- Document API addition.
+
+- Input/root tests + typecheck.
+
+- `../clock/wheel-item/clock-wheel-item.svelte`
+
+**Changes**
+
+- Remove default visual inline styles (opacity, cursor, font-weight, etc.) entirely. The component becomes fully headless — consumers style via `data-selected`, `data-disabled`, `data-centered` attributes.
+- This aligns WheelItem with the rest of the library where components ship zero visual opinions.
+  **Risk**
+
+- Technically breaking for anyone relying on the default inline styles. Acceptable at current maturity — the component is new and the old styles were inconsistent (all dropped when `class` was passed).
+
+## Phase 4 — Performance and code cleanup
+
+### 10) Formatter and locale caching
+
+- `root/time-picker-root.svelte`
+- `root/time-utils.ts`
+  **Changes**
+
+- Cache `Intl.DateTimeFormat` by `locale` + `hourCycle` + `granularity`.
+- Cache system-locale fallback once per component lifetime.
+
+**Files**
+
+**Changes**
+
+- Skip disabled candidate computation when no min/max is set.
+
+### 12) Low-risk code quality cleanups
+
+**Files**
+
+- `root/time-utils.ts`
+- `root/time-picker-root.svelte`
+
+**Changes**
+
+- Remove unreachable min>max branch in `isTimeOutOfRange`.
+- Replace meaningless ternary `type === 'hour' ? 2 : 2` with constant.
+
+**Validation**
+
+## Phase 5 — Test hardening
+
+### 13) Wheel test matrix expansion
+
+**Add coverage for**
+
+- Open alignment and external value sync.
+- Focus contract (`data-focus-within`, `data-focus-visible`).
+- Min/max disabled behavior.
+
+### 14) End-to-end wheel integration test
+
+**Files**
+
+- `root/time-picker-root.test.ts` and/or `wheel-column/time-picker-wheel-column.test.ts`
+
+**Flow to cover**
+
+- Wheel interaction → snap → `selectWheelValue` → root commit → segment UI + bound value sync.
+
+### 15) Segment paste/IME resilience tests
+
+**Files**
+
+- `segment/time-picker-segment.test.ts`
+
+**Cases**
+
+- Paste attempts do not corrupt draft.
+- Input DOM restores to draft when mutation bypass happens.
+
+---
+
+## Execution Order (Single PR)
+
+1. Phase 1
+2. Phase 2
+3. Phase 3
+4. Phase 4
+5. Phase 5
+
+This order minimizes risk: behavior correctness first, wheel timing second, API/accessibility third, refactors fourth, broad tests last.
+
+## Verification Checklist
+
+### Targeted runs after each phase
+
+- `bun run test -- --run src/lib/timepicker/root/time-picker-root.test.ts`
+- `bun run test -- --run src/lib/timepicker/input/time-picker-input.test.ts src/lib/timepicker/trigger/time-picker-trigger.test.ts`
+- `bun run test -- --run src/lib/timepicker/segment/time-picker-segment.test.ts`
+- `bun run test -- --run src/lib/clock/wheel-column/clock-wheel-column.test.ts src/lib/clock/panel/clock-panel.test.ts`
+- `bun run test -- --run src/lib/timepicker/root/time-utils.test.ts`
+
+### Final gate
+
+- `bun run typecheck`
+- `bun run test -- --run`
+- `bun run lint`
+- `bun run build`
+- `bunx changeset` — generate changeset file (CI requires it for `packages/svelte/src/**` changes)
+
+## Notes
+
+- Debounce increase (64→120ms) is safe because it only acts as a fallback for browsers without `scrollend`. Modern browsers use `scrollend` as the primary settle signal.
+- Preserve existing public APIs except where TODO explicitly requests additions (`isRequired`) or removals (WheelItem default styles).
+- Phase 5 tests must be written against the corrected behavior from Phases 1-4, not against the current (buggy) behavior.
+- Update docs/tests together with behavior changes to keep CI stable.

package/dist/timepicker/README.md

@@ -0,0 +1,97 @@
+# TimePicker
+
+## Description
+
+`TimePicker` composes a segmented time input with a popover containing wheel-based spinbutton columns.
+
+## Anatomy
+
+- `TimePicker.Root`
+- `TimePicker.Input`
+- `TimePicker.Segment`
+- `TimePicker.Trigger`
+- `TimePicker.Popover`
+- `TimePicker.Clock`
+- `TimePicker.WheelColumn`
+- `TimePicker.WheelItem`
+
+```svelte
+<TimePicker.Root>
+	<TimePicker.Input aria-label="Time input">
+		{#snippet children(segment)}
+			<TimePicker.Segment {segment} />
+		{/snippet}
+	</TimePicker.Input>
+	<TimePicker.Trigger />
+
+	<TimePicker.Popover>
+		<TimePicker.Clock />
+	</TimePicker.Popover>
+</TimePicker.Root>
+```
+
+```svelte
+<TimePicker.Popover>
+	<TimePicker.Clock class="flex gap-2">
+		{#snippet column(col)}
+			<TimePicker.WheelColumn type={col.type} class="h-44 rounded-md">
+				{#snippet children(option)}
+					<TimePicker.WheelItem type={col.type} {option} class="..." />
+				{/snippet}
+			</TimePicker.WheelColumn>
+		{/snippet}
+	</TimePicker.Clock>
+</TimePicker.Popover>
+```
+
+## 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`
+- `granularity?: 'hour' | 'minute' | 'second'`
+- `hourStep?: number`
+- `minuteStep?: number`
+- `secondStep?: number`
+- `isDisabled?: boolean`
+- `isReadOnly?: boolean`
+- `isRequired?: boolean`
+- `open?: boolean`
+- `defaultOpen?: boolean`
+- `onOpenChange?: (open: boolean, details: { reason, event?, cancel(), isCanceled }) => void`
+- Null-first empty contract: when `value` and `defaultValue` are omitted, the empty state is `null`.
+- `TimePicker.Input` exposes `aria-invalid` and `data-invalid` when the current segment draft is not committeable.
+
+## Popover API
+
+- `TimePicker.Popover` forwards `Popover.Content` props (for example `placement`, `offset`, `shouldFlip`, `boundaryElement`, `isNonModal`, and close behavior props).
+- The following are controlled internally by `TimePicker` and are not accepted on `TimePicker.Popover`: `open`, `triggerRef`, `onOpenChange`, `id`.
+- Defaults:
+  - `placement` defaults to `bottom`.
+  - `aria-label` defaults to `Time picker`.
+  - `initialFocus` defaults to the first wheel column (`role="spinbutton"`).
+
+## Wheel API
+
+- `TimePicker.WheelColumn` renders one wheel (`role="spinbutton"`) for one editable segment (`hour`, `minute`, `second`, or `dayPeriod`).
+- `TimePicker.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.
+
+## Clock API
+
+- `TimePicker.Clock` resolves visible wheel columns from root state (`granularity`, `hourCycle`) in stable order: `hour → minute? → second? → dayPeriod?`.
+- `class?: string` uses default layout (`flex gap-2`) when omitted.
+- `column?: Snippet<[ClockColumnInfo]>` allows custom per-column rendering.
+- `ClockColumnInfo` shape:
+  - `type: 'hour' | 'minute' | 'second' | 'dayPeriod'`
+  - `label?: string`
+
+## 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 (`minValue > maxValue` is treated as out-of-range).
+- Wheel selection commits immediately on snap; popover close is controlled by standard popover interactions (escape, outside press, programmatic close).

package/dist/timepicker/TODO.md

@@ -0,0 +1,86 @@
+# TimePicker TODO
+
+## Goal
+
+Track TimePicker work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [M][P0][Area: Parsing][Owner: Unassigned][Target: TBD] Make time parsing strict so invalid strings like "1.5:30" or ":30" are rejected. _(Already implemented via `isValidTimePickerValue` regex. `parseTimePickerValue` now returns `null` for invalid input.)_
+- [x] [S][P0][Area: Validation][Owner: Unassigned][Target: TBD] Guard 12h draft conversion against invalid hour values outside 1-12. _(Already implemented in `buildTimePartsFromDraft`.)_
+- [x] [M][P0][Area: Input][Owner: Unassigned][Target: TBD] Apply step clamping on typed values when segment edit is confirmed. _(Already implemented in `setSegmentValue` via `clampToStep`.)_
+- [x] [S][P0][Area: Formatting][Owner: Unassigned][Target: TBD] Force "HH:00" output for hour granularity regardless of leftover minutes. _(Already implemented in `formatTimePickerValue`.)_
+- [x] [S][P0][Area: Validation][Owner: Unassigned][Target: TBD] Treat missing dayPeriod as invalid in 12h draft-to-24h conversion. _(Already implemented in `buildTimePartsFromDraft`.)_
+- [x] [M][P1][Area: Locale][Owner: Unassigned][Target: TBD] Build segment order and literals from Intl formatToParts instead of hardcoded templates. _(Already implemented in `buildTimePickerSegments`.)_
+- [x] [S][P1][Area: Validation][Owner: Unassigned][Target: TBD] Compare min/max using the active granularity to avoid false out-of-range states. _(Fixed: `isTimeOutOfRange` now accepts `granularity` and truncates before comparison.)_
+- [x] [S][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Ensure time picker columns and options expose complete listbox/option ARIA contract. _(Already implemented in column/column-cell components.)_
+- [x] [S][P1][Area: Composition][Owner: Unassigned][Target: TBD] Wire selection-close behavior so `shouldCloseOnSelect` controls whether column selection closes popover when draft is complete. _(Implemented in `selectColumnOption`; default is `false`.)_
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: TBD] Verify dayPeriod segment uses 0-1 ARIA bounds and localized value text. _(Fixed: segment now uses `timePicker.hourCycle` for correct `aria-valuemin`/`aria-valuemax`.)_
+- [x] [S][P2][Area: Testing][Owner: Unassigned][Target: TBD] Ensure segment data attributes are consistent for styling and test selectors. _(Already implemented: `data-time-picker-segment="true"`.)_
+- [x] [M][P2][Area: Testing][Owner: Unassigned][Target: TBD] Expand unit coverage for parsing, format output, 12h conversion, clamping, and draft evaluation pipeline. _(Added 47 unit tests in `time-utils.test.ts`.)_
+- [x] [S][P2][Area: Documentation][Owner: Unassigned][Target: TBD] Add TimePicker references to focus contract documentation. _(Added component coverage section to `FOCUS_STATE_CONTRACT.md`.)_
+
+## Active
+
+### Bugs
+
+- [x] [M][P0][Area: State][Owner: Unassigned][Target: TBD] Permitir que el componente se limpie a undefined/null externamente. En `time-picker-root.svelte`, la observación de Svelte 5 ($effect sobre value) hace un early return con `if (value === undefined) return;`. Esto impide que se limpie la hora si el developer resetea el form manualmente enviando value = undefined. **Fix:** Quitar el early return por `undefined` y despachar la asignación nula para vaciar el TimePicker de forma controlada.
+
+- [x] [S][P0][Area: State][Owner: Unassigned][Target: TBD] Arreglar deshidratación al vaciar todos los segmentos (`commitFromDraft`). Al borrar backspace tras backspace, si el usuario vacía el _último_ segmento, la variable `hasAnyRequiredValue` rompe el flujo dando `false` lo que dispara un early return ocultando el borrado de `publishCommittedValue`. **Fix:** Quitar o condicionar el early return condicionado de hasAnyRequiredValue para que el componente notifique a los bindings de que la hora quedó completamente `null`.
+
+- [x] [M][P0][Area: Events][Owner: Unassigned][Target: TBD] Reparar Event Forwarding y omisiones en componentes internos. Actualmente los wrappers tragan eventos porque fallan en reingeniar el event payload natural de Svelte 5.
+  1. `Input`: Extrae variables pero no usa `composeEventHandlers`. Los onkey/onfocus externos mueren ahogados.
+  2. `Trigger`: Esparce `...restProps` **después** de sus eventos atados a Svelte 5, lo que cancela las rutinas internas si el usuario pasa `<Trigger onmousedown>`
+     **Fix:** Extraer las declaraciones conflictivas de `$props()` y usar `composeEventHandlers` en línea para todas en vez de pisarlas u omitirlas.
+
+- [x] [M][P0][Area: Input][Owner: Unassigned][Target: TBD] Guard segment `contenteditable` against paste, IME composition, and drag-drop. The `<span contenteditable>` in `time-picker-segment.svelte` has no `onbeforeinput`, `onpaste`, or `oncompositionend` handler. Ctrl+V, IME input, or drag-drop can modify the DOM directly without going through `typeSegmentDigit` / `setSegmentValue`, creating drift between the visible text and the internal `segmentDraft`. **Fix:** Add `onbeforeinput={(e) => e.preventDefault()}` to block all non-keyboard mutations. Alternatively, add an `oninput` handler that immediately restores the span's `textContent` to the current draft value as a safety net.
+
+- [x] [M][P0][Area: Wheel][Owner: Unassigned][Target: TBD] Increase scroll debounce timeout in `use-wheel-scroll.svelte.ts` from 64ms to ~120-150ms. On touch devices with momentum scrolling (especially iOS Safari), gaps between `scroll` events during deceleration can exceed 64ms, causing premature snap that interrupts the user's inertia. Since browsers that support `scrollend` use it as the primary settle signal and the debounce only acts as a safety net, a higher value does not affect perceived latency. **File:** `hooks/use-wheel-scroll.svelte.ts` line ~215.
+
+- [x] [M][P0][Area: Wheel][Owner: Unassigned][Target: TBD] Sync `lastCenteredIndex` when value changes externally while popover is open. `lastCenteredIndex` in `time-picker-wheel-column.svelte` is a plain `let` used as anchor for `moveBy()`. If the root value changes via `bind:value` while the popover is open, `lastCenteredIndex` still points to the old index. A subsequent `ArrowDown` jumps from the stale position instead of the current one. **Fix:** Add a `$effect` that observes `selectedValue` + `timePicker.open`: when both are truthy and `selectedIndex` changes, update `lastCenteredIndex = selectedIndex` and optionally scroll to it.
+
+- [x] [S][P1][Area: Wheel][Owner: Unassigned][Target: TBD] Suppress unnecessary re-snap chain after `scrollToIndex('smooth')` when value is already committed. When `handleCenterRequest` (click on WheelItem) eagerly commits the value then calls `scrollToIndex(i, 'smooth')`, the ensuing scroll events trigger debounce → `snapToCenter` → `animateSnapTo` for micro-alignment → more scroll events. The chain is usually idempotent but can cause micro-jitter. **Fix:** Add a `silent` parameter to `scrollToIndex` that suppresses `snapToCenter` for the duration of that smooth scroll. Use it only for clicks where the commit already happened, NOT for corrective disabled-skip (which must snap and commit).
+
+### Accesibilidad
+
+- [x] [S][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Add `aria-live` region to announce wheel value changes for screen readers. When the user scrolls a `WheelColumn`, `aria-valuenow` / `aria-valuetext` update, but screen readers don't automatically announce `aria-valuenow` changes on a `spinbutton`. **Fix:** Add a visually-hidden `<span role="status" aria-live="polite" class="sr-only">{valueText}</span>` inside each `WheelColumn` that updates when the selected value changes. This announces the new value after each snap.
+
+- [x] [S][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Fix `Home`/`End` in segment to use correct boundary values for 12h mode. In `time-picker-segment.svelte`, `Home` sends `setSegmentValue('hour', '0')` and `End` sends `'23'` regardless of `hourCycle`. In 12h mode the valid range is 1-12. This currently works by accident (clamping corrects it), but the intent is wrong and fragile. **Fix:** Use `timePicker.hourCycle` to determine boundaries: `Home` → `hourCycle === 12 ? '1' : '0'`, `End` → `hourCycle === 12 ? '12' : '23'`.
+
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: TBD] Add `aria-roledescription` to `WheelColumn`. A generic `role="spinbutton"` doesn't communicate that the widget is a wheel/picker. Adding `aria-roledescription="wheel picker"` (or a localized equivalent) would improve the experience for screen reader users. Apply to the root `<div role="spinbutton">` in `time-picker-wheel-column.svelte`.
+
+- [x] [S][P2][Area: Accessibility][Owner: Unassigned][Target: TBD] Add `isRequired` prop to Root and propagate `aria-required` to the Input group. There's currently no way to indicate the field is required for form validation. The prop should flow from Root → context → `time-picker-input.svelte` as `aria-required` on the `role="group"` element.
+
+### Performance
+
+- [x] [M][P1][Area: Performance][Owner: Unassigned][Target: TBD] Cache `Intl.DateTimeFormat` instance across segment draft changes. `buildTimePickerSegments` in `time-utils.ts` creates a `new Intl.DateTimeFormat(locale, formatOptions)` on every call. This function is invoked from a `$derived` that depends on `segmentDraft`, so every keystroke recreates the formatter. The formatter only depends on `locale`, `hourCycle`, and `granularity`. **Fix:** In `time-picker-root.svelte`, derive the formatter once from those 3 variables and pass it to `buildTimePickerSegments` as a parameter.
+
+- [x] [S][P2][Area: Performance][Owner: Unassigned][Target: TBD] Short-circuit disabled computation in `getWheelOptions` when no min/max range is set. `getWheelOptions` runs `buildTimePartsFromDraft` + `isTimeOutOfRange` for every option in every column (~122 iterations for minute granularity). When `normalizedMinValue` and `normalizedMaxValue` are both `undefined`, all options are always enabled. **Fix:** Add an early check: `if (!normalizedMinValue && !normalizedMaxValue)` → skip disabled computation and return `disabled: false` for all.
+
+- [x] [S][P2][Area: Performance][Owner: Unassigned][Target: TBD] Cache system locale so `Intl.DateTimeFormat().resolvedOptions().locale` isn't called on every `$derived` reevaluation. In `time-picker-root.svelte`, `resolvedLocale` falls back to `Intl.DateTimeFormat().resolvedOptions().locale` when no context locale is provided. This creates a new formatter on each reevaluation. The system locale doesn't change during the component's lifetime. **Fix:** Capture it once with `untrack` at initialization and store in a constant.
+
+### Arquitectura / Robustez
+
+- [x] [S][P2][Area: Wheel][Owner: Unassigned][Target: TBD] Batch `ResizeObserver` callbacks with `requestAnimationFrame` to avoid layout thrashing. The `ResizeObserver` in `time-picker-wheel-column.svelte` calls `syncMeasurements()` which updates `$state` variables (`itemHeight`, `spacerHeight`). This triggers Svelte re-render → layout shift → observer fires again, producing `ResizeObserver loop completed with undelivered notifications` warnings in tests. **Fix:** Wrap the observer callback: `resizeObserver = new ResizeObserver(() => { requestAnimationFrame(() => syncMeasurements()); });`
+
+- [x] [S][P2][Area: Wheel][Owner: Unassigned][Target: TBD] Make `WheelItem` default visual style consistent with headless pattern. `time-picker-wheel-item.svelte` applies inline styles (opacity, cursor, font-weight, etc.) by default but drops ALL of them if the consumer passes `class`. This all-or-nothing behavior is inconsistent with the rest of the library (fully headless). **Fix:** Either remove default visual styles entirely (consumer styles via `data-selected`, `data-disabled` attributes — headless), or separate structural styles (always applied) from decorative styles (opt-out via prop). Preferred: go fully headless for consistency.
+
+- [x] [S][P3][Area: Code Quality][Owner: Unassigned][Target: TBD] Remove dead code in `isTimeOutOfRange`. The `if (minValue && maxValue) { ... if (min > max) return true }` block at the end is unreachable — if `min > max`, any value `v` is already rejected by the individual `v < min` or `v > max` checks above. Remove to reduce reader confusion. **File:** `root/time-utils.ts` lines ~219-228.
+
+- [x] [S][P3][Area: Code Quality][Owner: Unassigned][Target: TBD] Fix meaningless ternary in `setSegmentValue`. `const maxDigits = type === 'hour' ? 2 : 2;` — both branches are `2`. Was likely a draft for differentiating types. Replace with `const maxDigits = 2;`. **File:** `root/time-picker-root.svelte` line ~280.
+
+### Testing
+
+- [x] [C][P1][Area: Testing][Owner: Unassigned][Target: TBD] Expand `WheelColumn` test coverage. Current: 4 tests (render, aria values, cross-column nav, spacers). Missing critical scenarios: (a) ArrowUp/Down keyboard changes value, (b) disabled item skip on scroll, (c) PageUp/PageDown/Home/End navigation, (d) scroll-to-selected on popover open, (e) external value change syncs wheel position, (f) full focus contract (`data-focus-within`, `data-focus-visible`), (g) behavior with `minValue`/`maxValue` producing disabled options.
+
+- [x] [M][P1][Area: Testing][Owner: Unassigned][Target: TBD] Add integration test for wheel → root → segment sync. No test verifies the full flow: user scrolls wheel → snap detects centered item → `selectWheelValue` called → `commitFromDraft` runs → segment text updates → `bind:value` reflects new time. This is the core happy-path of the wheel and should be covered.
+
+- [x] [S][P2][Area: Testing][Owner: Unassigned][Target: TBD] Add test for contenteditable paste/IME resilience in segment. Verify that pasting text into a segment does not corrupt `segmentDraft` and that the visible text is restored to the draft value. Important because `contenteditable` is inherently fragile.
+
+## Notes
+
+TimePicker locale is sourced from LocaleProvider, not from a root locale prop.
+
+### Review context (2026-03-02)
+
+The wheel architecture (`WheelColumn` / `WheelItem` / `use-wheel-scroll`) replaced the original column-based `listbox`/`option` architecture. The wheel uses JS-driven snapping (no CSS `scroll-snap-type`) with a 120ms ease-out animation. Selection occurs when scroll settles and the centered item is committed. Disabled items are auto-skipped. `shouldCloseOnSelect` was removed — popover closes only via Escape, click outside, or programmatically.

package/dist/timepicker/clock/README.md

@@ -0,0 +1,14 @@
+# TimePicker Clock
+
+## API reference
+
+### TimePicker.Clock
+
+Name: `TimePicker.Clock`  
+Description: Clock panel composition part that resolves visible wheel columns from `TimePicker.Root` state.
+
+| Prop           | Type                             | Default                      | Description                                             |
+| -------------- | -------------------------------- | ---------------------------- | ------------------------------------------------------- |
+| `column`       | `Snippet<[ClockColumnInfo]>`     | `undefined`                  | Optional custom per-column renderer.                    |
+| `class`        | `string`                         | `'flex items-stretch gap-2'` | CSS class names for the clock container.                |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`                          | Additional attributes forwarded to the clock container. |