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

package/dist/FOCUS_STATE_CONTRACT.md

@@ -49,3 +49,15 @@ On overlay/popover close, transient trigger state is allowed:
 ## Operational Template
 
 - Use `FOCUS_STATE_REVIEW_TEMPLATE.md` for PR/release reviews (modality matrix + component status + checklist).
+
+## Component Coverage
+
+The following components implement this contract:
+
+- **Popover** — trigger + content, restore focus on close.
+- **Dialog** — trigger + overlay/content, nested stack support.
+- **DatePicker** — segment spinbuttons, trigger, popover (calendar).
+- **TimePicker** — segment spinbuttons, trigger, popover (scrollable columns). Follows the same contract as DatePicker.
+- **Calendar** — grid cells with roving tabindex.
+- **ComboBox** — input + listbox with virtual focus.
+- **ListBox** — items with roving tabindex.

package/dist/calendar/body-cell/README.md

@@ -0,0 +1,15 @@
+# Calendar BodyCell
+
+## API reference
+
+### Calendar.BodyCell
+
+Name: `Calendar.BodyCell`  
+Description: Wrapper part for date grid cells inside `Calendar.GridBody`.
+
+| Prop           | Type                                   | Default     | Description                                                     |
+| -------------- | -------------------------------------- | ----------- | --------------------------------------------------------------- |
+| `date`         | `string`                               | `required`  | Calendar date value rendered by the cell (`YYYY-MM-DD`).        |
+| `children`     | `Snippet<[string]>`                    | `undefined` | Optional custom renderer receiving the day label text.          |
+| `class`        | `string`                               | `''`        | CSS class names for the inner gridcell element.                 |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the outer table cell (`td`). |

package/dist/calendar/grid/README.md

@@ -0,0 +1,13 @@
+# Calendar Grid
+
+## API reference
+
+### Calendar.Grid
+
+Name: `Calendar.Grid`  
+Description: Calendar month table container rendered by `Calendar.Root`.
+
+| Prop       | Type      | Default     | Description                                   |
+| ---------- | --------- | ----------- | --------------------------------------------- |
+| `children` | `Snippet` | `undefined` | Optional custom month-grid content.           |
+| `class`    | `string`  | `''`        | CSS class names for the outer grid container. |

package/dist/calendar/grid-body/README.md

@@ -0,0 +1,13 @@
+# Calendar GridBody
+
+## API reference
+
+### Calendar.GridBody
+
+Name: `Calendar.GridBody`  
+Description: TBody container for week rows in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                              |
+| ---------- | ------------------- | ----------- | -------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each day date string. |
+| `class`    | `string`            | `''`        | CSS class names for the `tbody` element.                 |

package/dist/calendar/grid-header/README.md

@@ -0,0 +1,13 @@
+# Calendar GridHeader
+
+## API reference
+
+### Calendar.GridHeader
+
+Name: `Calendar.GridHeader`  
+Description: Header row group for weekday labels in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                                      |
+| ---------- | ------------------- | ----------- | ---------------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each localized weekday label. |
+| `class`    | `string`            | `''`        | CSS class names for the `thead` element.                         |

package/dist/calendar/header-cell/README.md

@@ -0,0 +1,14 @@
+# Calendar HeaderCell
+
+## API reference
+
+### Calendar.HeaderCell
+
+Name: `Calendar.HeaderCell`  
+Description: Weekday heading cell part used inside `Calendar.GridHeader`.
+
+| Prop           | Type                                   | Default     | Description                                        |
+| -------------- | -------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `Snippet`                              | `undefined` | Optional custom header cell content.               |
+| `class`        | `string`                               | `''`        | CSS class names for the header cell element.       |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the table cell. |

package/dist/calendar/heading/README.md

@@ -0,0 +1,13 @@
+# Calendar Heading
+
+## API reference
+
+### Calendar.Heading
+
+Name: `Calendar.Heading`  
+Description: Label part that displays the currently visible calendar period.
+
+| Prop           | Type                                 | Default | Description                                             |
+| -------------- | ------------------------------------ | ------- | ------------------------------------------------------- |
+| `class`        | `string`                             | `''`    | CSS class names for the heading element (`h2`).         |
+| `...restProps` | `HTMLAttributes<HTMLHeadingElement>` | `-`     | Additional attributes forwarded to the heading element. |

package/dist/calendar/root/README.md

@@ -0,0 +1,24 @@
+# Calendar Root
+
+## API reference
+
+### Calendar.Root
+
+Name: `Calendar.Root`  
+Description: Root state container for date grid rendering, navigation, selection, and locale-aware formatting.
+
+| Prop                | Type                                                       | Default     | Description                                                         |
+| ------------------- | ---------------------------------------------------------- | ----------- | ------------------------------------------------------------------- |
+| `selectionMode`     | `'single' \| 'range'`                                      | `'single'`  | Selection behavior and value shape.                                 |
+| `value`             | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `bindable`  | Controlled selected value (single date or `{ start, end }`).        |
+| `defaultValue`      | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `undefined` | Initial value for uncontrolled mode.                                |
+| `onChange`          | `(value: CalendarDateValue \| CalendarRangeValue) => void` | `undefined` | Called when selection changes.                                      |
+| `visibleMonths`     | `number`                                                   | `1`         | Number of month grids rendered simultaneously.                      |
+| `showOutsideDays`   | `boolean`                                                  | `false`     | Whether days outside the visible month remain rendered/interactive. |
+| `isDateUnavailable` | `(date: string) => boolean`                                | `undefined` | Marks specific dates as unavailable.                                |
+| `isDisabled`        | `boolean`                                                  | `false`     | Disables interaction and navigation.                                |
+| `isReadOnly`        | `boolean`                                                  | `false`     | Keeps navigation while preventing selection updates.                |
+| `children`          | `Snippet`                                                  | `undefined` | Composed `Calendar` parts.                                          |
+| `class`             | `string`                                                   | `''`        | CSS class names for the root wrapper.                               |
+| `id`                | `string`                                                   | `undefined` | Optional root id.                                                   |
+| `aria-label`        | `string`                                                   | `undefined` | Accessible label for the root wrapper.                              |

package/dist/calendar/trigger-next/README.md

@@ -0,0 +1,14 @@
+# Calendar TriggerNext
+
+## API reference
+
+### Calendar.TriggerNext
+
+Name: `Calendar.TriggerNext`  
+Description: Button part that advances the visible calendar period.
+
+| 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/calendar/trigger-previous/README.md

@@ -0,0 +1,14 @@
+# Calendar TriggerPrevious
+
+## API reference
+
+### Calendar.TriggerPrevious
+
+Name: `Calendar.TriggerPrevious`  
+Description: Button part that moves the visible calendar period backward.
+
+| 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/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.

package/dist/clock/axis/README.md

@@ -0,0 +1,24 @@
+# Clock Axis
+
+## API reference
+
+### Clock.Axis
+
+Name: `Clock.Axis`  
+Description: Visual overlay band for `Clock.Root`; it is presentational (`aria-hidden`) and does not manage selection.
+
+| Prop           | Type                             | Default     | Description                                          |
+| -------------- | -------------------------------- | ----------- | ---------------------------------------------------- |
+| `height`       | `number`                         | `undefined` | Optional overlay height in pixels.                   |
+| `class`        | `string`                         | `''`        | CSS class names for the overlay element.             |
+| `style`        | `string`                         | `''`        | Inline styles merged with the optional height style. |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`         | Additional attributes forwarded to the overlay div.  |
+
+### Context utilities
+
+Name: `useClockContext`  
+Description: Ensures `Clock.Axis` is used within `Clock.Root`.
+
+| Prop              | Type                 | Default | Description                                      |
+| ----------------- | -------------------- | ------- | ------------------------------------------------ |
+| `useClockContext` | `() => ClockContext` | `-`     | Returns context and throws outside `Clock.Root`. |

package/dist/clock/axis/clock-axis.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { useClockContext } from '../root/context';
+
+	type ClockAxisProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+		class?: string;
+		height?: number;
+	};
+
+	let {
+		class: className = '',
+		height,
+		style: styleProp = '',
+		...restProps
+	}: ClockAxisProps = $props();
+
+	const resolvedStyle = $derived.by(() => {
+		const base = styleProp?.trim() ?? '';
+		if (height === undefined || !Number.isFinite(height) || height <= 0) {
+			return base.length > 0 ? base : undefined;
+		}
+		const axisHeight = `height:${height}px`;
+		if (base.length === 0) return axisHeight;
+		const withSemicolon = /;\s*$/.test(base) ? base : `${base};`;
+		return `${withSemicolon}${axisHeight}`;
+	});
+
+	useClockContext();
+</script>
+
+<div
+	aria-hidden="true"
+	data-clock-axis
+	class={`pointer-events-none absolute top-1/2 left-0 w-full -translate-y-1/2 ${className}`}
+	style={resolvedStyle}
+	{...restProps}
+></div>

package/dist/clock/axis/clock-axis.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLAttributes } from 'svelte/elements';
+type ClockAxisProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+    class?: string;
+    height?: number;
+};
+declare const ClockAxis: import("svelte").Component<ClockAxisProps, {}, "">;
+type ClockAxis = ReturnType<typeof ClockAxis>;
+export default ClockAxis;

package/dist/clock/hooks/use-wheel-scroll.svelte.d.ts

@@ -0,0 +1,16 @@
+export type WheelScrollBehavior = 'smooth' | 'instant';
+export type WheelScrollApi = {
+    scrollToIndex: (index: number, behavior?: WheelScrollBehavior, options?: {
+        silent?: boolean;
+    }) => void;
+    destroy: () => void;
+};
+/**
+ * Manages scroll-based item selection for a wheel column.
+ *
+ * All snapping is handled in JavaScript (no CSS `scroll-snap-type`).
+ * After scrolling settles (either short inactivity in `scroll` events
+ * or browser `scrollend`), we find the nearest centered item and run
+ * a fast 120 ms ease-out animation to align it.
+ */
+export declare function useWheelScroll(container: HTMLElement, onSnap: (centeredIndex: number) => number | null | void): WheelScrollApi;

package/dist/clock/hooks/use-wheel-scroll.svelte.js

@@ -0,0 +1,336 @@
+/**
+ * Manages scroll-based item selection for a wheel column.
+ *
+ * All snapping is handled in JavaScript (no CSS `scroll-snap-type`).
+ * After scrolling settles (either short inactivity in `scroll` events
+ * or browser `scrollend`), we find the nearest centered item and run
+ * a fast 120 ms ease-out animation to align it.
+ */
+export function useWheelScroll(container, onSnap) {
+    let scrollEndTimer = null;
+    let silentScrollTimer = null;
+    let snapRafId = null;
+    let releaseSnapRafId = null;
+    let instantReleaseRafId = null;
+    let isSnapping = false;
+    let isSilentScroll = false;
+    let isPointerInteracting = false;
+    let hasPendingPointerReleaseSnap = false;
+    const supportsScrollEnd = 'onscrollend' in window;
+    const supportsPointerEvents = 'onpointerdown' in window;
+    const wheelDebugWindow = window;
+    let lastScrollAt = 0;
+    let gestureStartAt = 0;
+    let scrollEventsInGesture = 0;
+    let currentGestureId = 0;
+    function isDebugEnabled() {
+        return (wheelDebugWindow.__HK_CLOCK_WHEEL_DEBUG__ === true || container.dataset.wheelDebug === 'true');
+    }
+    function debugLog(event, details) {
+        if (!isDebugEnabled())
+            return;
+        const timestamp = Number(performance.now().toFixed(1));
+        console.info('[Clock.WheelDebug]', {
+            event,
+            t: timestamp,
+            gestureId: currentGestureId,
+            supportsScrollEnd,
+            ...details
+        });
+    }
+    function clearSilentScroll() {
+        isSilentScroll = false;
+        if (silentScrollTimer) {
+            clearTimeout(silentScrollTimer);
+            silentScrollTimer = null;
+        }
+    }
+    function startSilentScrollWindow() {
+        isSilentScroll = true;
+        if (silentScrollTimer) {
+            clearTimeout(silentScrollTimer);
+        }
+        silentScrollTimer = setTimeout(() => {
+            clearSilentScroll();
+        }, 600);
+    }
+    function getItemElements() {
+        const taggedItems = Array.from(container.querySelectorAll('[data-wheel-item]'));
+        if (taggedItems.length > 0)
+            return taggedItems;
+        return Array.from(container.children).filter((child) => {
+            if (!(child instanceof HTMLElement))
+                return false;
+            if (child.matches('[data-wheel-spacer], [data-wheel-highlight], [role="status"], .sr-only')) {
+                return false;
+            }
+            return true;
+        });
+    }
+    function getCenteredIndex() {
+        const items = getItemElements();
+        if (items.length === 0)
+            return -1;
+        const centerLine = container.scrollTop + container.clientHeight / 2;
+        let closestIndex = -1;
+        let closestDistance = Number.POSITIVE_INFINITY;
+        for (let index = 0; index < items.length; index += 1) {
+            const item = items[index];
+            const itemCenter = item.offsetTop + item.offsetHeight / 2;
+            const distance = Math.abs(itemCenter - centerLine);
+            if (distance < closestDistance) {
+                closestDistance = distance;
+                closestIndex = index;
+            }
+        }
+        return closestIndex;
+    }
+    /* ── snap animation ─────────────────────────────────────────────── */
+    function cancelSnap() {
+        if (snapRafId !== null) {
+            cancelAnimationFrame(snapRafId);
+            snapRafId = null;
+        }
+        if (releaseSnapRafId !== null) {
+            cancelAnimationFrame(releaseSnapRafId);
+            releaseSnapRafId = null;
+        }
+        if (instantReleaseRafId !== null) {
+            cancelAnimationFrame(instantReleaseRafId);
+            instantReleaseRafId = null;
+        }
+        isSnapping = false;
+    }
+    /**
+     * Run a 120 ms ease-out-cubic animation from the current scrollTop to
+     * `target`.  During the animation `isSnapping` is true so incoming
+     * scroll / scrollend events are ignored.
+     */
+    function animateSnapTo(target) {
+        cancelSnap();
+        const start = container.scrollTop;
+        const distance = target - start;
+        if (Math.abs(distance) < 1)
+            return;
+        isSnapping = true;
+        const duration = 120;
+        const t0 = performance.now();
+        debugLog('snap-animation-start', {
+            start: Number(start.toFixed(2)),
+            target: Number(target.toFixed(2)),
+            distance: Number(distance.toFixed(2)),
+            durationMs: duration
+        });
+        function frame(now) {
+            const elapsed = now - t0;
+            const t = Math.min(elapsed / duration, 1);
+            const eased = 1 - (1 - t) ** 3; // ease-out cubic
+            container.scrollTop = start + distance * eased;
+            if (t < 1) {
+                snapRafId = requestAnimationFrame(frame);
+            }
+            else {
+                snapRafId = null;
+                debugLog('snap-animation-end', {
+                    elapsedMs: Number((performance.now() - t0).toFixed(1)),
+                    finalScrollTop: Number(container.scrollTop.toFixed(2))
+                });
+                // Keep the flag only until next frame so trailing animation
+                // events are ignored without creating a visible dead-zone.
+                releaseSnapRafId = requestAnimationFrame(() => {
+                    releaseSnapRafId = null;
+                    isSnapping = false;
+                });
+            }
+        }
+        snapRafId = requestAnimationFrame(frame);
+    }
+    /* ── scroll settle ──────────────────────────────────────────────── */
+    /**
+     * Called when the user's scroll gesture has finished.
+     * 1. Identify the closest item to the viewport centre.
+     * 2. Emit `onSnap` so the consumer can update the selected value.
+     * 3. Animate to perfectly centre the item (120 ms).
+     */
+    function snapToCenter(source) {
+        if (isSnapping || isSilentScroll)
+            return;
+        const now = performance.now();
+        const idleBeforeSnapMs = lastScrollAt > 0 ? now - lastScrollAt : null;
+        debugLog('snap-evaluate', {
+            source,
+            idleBeforeSnapMs: idleBeforeSnapMs === null ? null : Number(idleBeforeSnapMs.toFixed(1)),
+            scrollEventsInGesture
+        });
+        const centeredIndex = getCenteredIndex();
+        if (centeredIndex < 0)
+            return;
+        const resolvedIndex = onSnap(centeredIndex);
+        const snapIndex = typeof resolvedIndex === 'number' ? resolvedIndex : centeredIndex;
+        if (!Number.isInteger(snapIndex) || snapIndex < 0)
+            return;
+        const items = getItemElements();
+        const target = items[snapIndex];
+        if (!target)
+            return;
+        const idealScrollTop = target.offsetTop - (container.clientHeight - target.offsetHeight) / 2;
+        const clamped = Math.max(0, idealScrollTop);
+        const diff = Math.abs(container.scrollTop - clamped);
+        debugLog('snap-target', {
+            centeredIndex,
+            snapIndex,
+            diffPx: Number(diff.toFixed(2)),
+            currentScrollTop: Number(container.scrollTop.toFixed(2)),
+            targetScrollTop: Number(clamped.toFixed(2))
+        });
+        scrollEventsInGesture = 0;
+        if (diff >= 2) {
+            animateSnapTo(clamped);
+        }
+    }
+    /* ── event wiring ───────────────────────────────────────────────── */
+    function clearScrollEndTimer() {
+        if (scrollEndTimer) {
+            clearTimeout(scrollEndTimer);
+            scrollEndTimer = null;
+        }
+    }
+    function handleScroll() {
+        const now = performance.now();
+        if (scrollEventsInGesture === 0) {
+            currentGestureId += 1;
+            gestureStartAt = now;
+            debugLog('gesture-start', {
+                scrollTop: Number(container.scrollTop.toFixed(2))
+            });
+        }
+        scrollEventsInGesture += 1;
+        lastScrollAt = now;
+        if (isSnapping) {
+            debugLog('scroll-ignored-while-snapping');
+            return;
+        }
+        if (isSilentScroll) {
+            debugLog('scroll-ignored-while-silent-scroll');
+            return;
+        }
+        if (isPointerInteracting) {
+            hasPendingPointerReleaseSnap = true;
+            clearScrollEndTimer();
+            debugLog('scroll-deferred-until-pointer-release');
+            return;
+        }
+        // Always debounce by scroll inactivity so we don't rely solely on
+        // potentially late `scrollend` dispatch.
+        clearScrollEndTimer();
+        scrollEndTimer = setTimeout(() => snapToCenter(supportsScrollEnd ? 'inactivity-timeout' : 'fallback-timeout'), 120);
+    }
+    function handleScrollEnd() {
+        const now = performance.now();
+        if (isSnapping) {
+            debugLog('scrollend-ignored-while-snapping');
+            return;
+        }
+        if (isSilentScroll) {
+            debugLog('scrollend-ignored-while-silent-scroll');
+            clearSilentScroll();
+            return;
+        }
+        debugLog('scrollend-received', {
+            sinceLastScrollMs: lastScrollAt > 0 ? Number((now - lastScrollAt).toFixed(1)) : null,
+            gestureDurationMs: gestureStartAt > 0 ? Number((now - gestureStartAt).toFixed(1)) : null,
+            scrollEventsInGesture
+        });
+        clearScrollEndTimer();
+        snapToCenter('scrollend');
+    }
+    function handlePointerDown(event) {
+        if ('pointerType' in event && event.pointerType === 'mouse' && event.button !== 0) {
+            return;
+        }
+        if (!('pointerType' in event) && event.button !== 0) {
+            return;
+        }
+        isPointerInteracting = true;
+        hasPendingPointerReleaseSnap = false;
+    }
+    function handlePointerRelease() {
+        if (!isPointerInteracting)
+            return;
+        isPointerInteracting = false;
+        if (hasPendingPointerReleaseSnap) {
+            hasPendingPointerReleaseSnap = false;
+            clearScrollEndTimer();
+            snapToCenter('pointer-release');
+        }
+    }
+    container.addEventListener('scroll', handleScroll, { passive: true });
+    if (supportsPointerEvents) {
+        container.addEventListener('pointerdown', handlePointerDown, {
+            passive: true
+        });
+        window.addEventListener('pointerup', handlePointerRelease, { passive: true });
+        window.addEventListener('pointercancel', handlePointerRelease, { passive: true });
+    }
+    else {
+        container.addEventListener('mousedown', handlePointerDown);
+        window.addEventListener('mouseup', handlePointerRelease);
+    }
+    if (supportsScrollEnd) {
+        container.addEventListener('scrollend', handleScrollEnd);
+    }
+    /* ── public API ─────────────────────────────────────────────────── */
+    function scrollToIndex(index, behavior = 'smooth', options) {
+        cancelSnap();
+        clearScrollEndTimer();
+        const shouldUseSilentScroll = options?.silent === true && behavior === 'smooth';
+        if (shouldUseSilentScroll) {
+            startSilentScrollWindow();
+        }
+        else {
+            clearSilentScroll();
+        }
+        const items = getItemElements();
+        if (index < 0 || index >= items.length)
+            return;
+        const target = items[index];
+        const idealScrollTop = target.offsetTop - (container.clientHeight - target.offsetHeight) / 2;
+        if (behavior === 'instant') {
+            // Direct assignment – no animation.  Suppress the ensuing scrollend
+            // so it doesn't trigger an unnecessary snapToCenter cycle.
+            isSnapping = true;
+            container.scrollTop = Math.max(0, idealScrollTop);
+            instantReleaseRafId = requestAnimationFrame(() => {
+                instantReleaseRafId = null;
+                isSnapping = false;
+            });
+        }
+        else {
+            container.scrollTo({
+                top: Math.max(0, idealScrollTop),
+                behavior: 'smooth'
+            });
+        }
+    }
+    return {
+        scrollToIndex,
+        destroy: () => {
+            cancelSnap();
+            clearScrollEndTimer();
+            clearSilentScroll();
+            container.removeEventListener('scroll', handleScroll);
+            if (supportsPointerEvents) {
+                container.removeEventListener('pointerdown', handlePointerDown);
+                window.removeEventListener('pointerup', handlePointerRelease);
+                window.removeEventListener('pointercancel', handlePointerRelease);
+            }
+            else {
+                container.removeEventListener('mousedown', handlePointerDown);
+                window.removeEventListener('mouseup', handlePointerRelease);
+            }
+            if (supportsScrollEnd) {
+                container.removeEventListener('scrollend', handleScrollEnd);
+            }
+        }
+    };
+}