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

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);
+            }
+        }
+    };
+}

package/dist/clock/index.d.ts

@@ -0,0 +1,10 @@
+export * as Clock from './index.parts.ts';
+export { default as ClockRoot } from './root/clock-root.svelte';
+export { default as ClockAxis } from './axis/clock-axis.svelte';
+export { default as ClockWheelColumn } from './wheel-column/clock-wheel-column.svelte';
+export { default as ClockWheelItem } from './wheel-item/clock-wheel-item.svelte';
+export { getClockContext, setClockContext, useClockContext, type ClockContext, type ClockEditableSegmentType } from './root/context.ts';
+export { type TimePickerGranularity as ClockGranularity, type TimePickerHourCycle as ClockHourCycle, type TimePickerTimeValue as ClockTimeValue } from './root/time-utils';
+export { type ClockColumnInfo } from './root/resolve-visible-columns';
+import * as ClockParts from './index.parts.ts';
+export default ClockParts;

package/dist/clock/index.js

@@ -0,0 +1,10 @@
+export * as Clock from './index.parts.ts';
+export { default as ClockRoot } from './root/clock-root.svelte';
+export { default as ClockAxis } from './axis/clock-axis.svelte';
+export { default as ClockWheelColumn } from './wheel-column/clock-wheel-column.svelte';
+export { default as ClockWheelItem } from './wheel-item/clock-wheel-item.svelte';
+export { getClockContext, setClockContext, useClockContext } from './root/context.ts';
+export {} from './root/time-utils';
+export {} from './root/resolve-visible-columns';
+import * as ClockParts from './index.parts.ts';
+export default ClockParts;

package/dist/clock/index.parts.d.ts

@@ -0,0 +1,4 @@
+export { default as Root } from './root/clock-root.svelte';
+export { default as Axis } from './axis/clock-axis.svelte';
+export { default as WheelColumn } from './wheel-column/clock-wheel-column.svelte';
+export { default as WheelItem } from './wheel-item/clock-wheel-item.svelte';

package/dist/clock/index.parts.js

@@ -0,0 +1,4 @@
+export { default as Root } from './root/clock-root.svelte';
+export { default as Axis } from './axis/clock-axis.svelte';
+export { default as WheelColumn } from './wheel-column/clock-wheel-column.svelte';
+export { default as WheelItem } from './wheel-item/clock-wheel-item.svelte';

package/dist/clock/root/README.md

@@ -0,0 +1,38 @@
+# Clock Root
+
+## API reference
+
+### Clock.Root
+
+Name: `Clock.Root`  
+Description: Standalone wheel-based time state container that resolves visible columns and publishes selection context for child parts.
+
+| Prop           | Type                              | Default     | Description                                                |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------- |
+| `value`        | `string \| null`                  | `bindable`  | Controlled time value (`HH:mm` or `HH:mm:ss`).             |
+| `defaultValue` | `string \| null`                  | `undefined` | Initial value for uncontrolled usage.                      |
+| `onChange`     | `(value: string \| null) => void` | `undefined` | Called when a committed wheel selection changes the value. |
+| `hourCycle`    | `12 \| 24`                        | `locale`    | Hour cycle used for rendering and validation.              |
+| `granularity`  | `'hour' \| 'minute' \| 'second'`  | `'minute'`  | Controls visible wheel columns and emitted precision.      |
+| `hourStep`     | `number`                          | `1`         | Hour increment used by wheel and keyboard navigation.      |
+| `minuteStep`   | `number`                          | `1`         | Minute increment used by wheel and keyboard navigation.    |
+| `secondStep`   | `number`                          | `1`         | Second increment used by wheel and keyboard navigation.    |
+| `minValue`     | `string`                          | `undefined` | Optional lower bound for selectable values.                |
+| `maxValue`     | `string`                          | `undefined` | Optional upper bound for selectable values.                |
+| `isDisabled`   | `boolean`                         | `false`     | Disables wheel interaction and value updates.              |
+| `column`       | `Snippet<[ClockColumnInfo]>`      | `undefined` | Optional custom renderer for each resolved column.         |
+| `children`     | `Snippet`                         | `undefined` | Optional additional content rendered inside the root.      |
+| `class`        | `string`                          | `''`        | CSS class names for the root element.                      |
+| `aria-label`   | `string`                          | `undefined` | Accessible label for the root group.                       |
+
+### Context utilities
+
+Name: `setClockContext` / `getClockContext` / `useClockContext`  
+Description: Context helpers used by `Clock.Axis`, `Clock.WheelColumn`, and other clock parts.
+
+| Prop              | Type                              | Default | Description                                              |
+| ----------------- | --------------------------------- | ------- | -------------------------------------------------------- |
+| `setClockContext` | `(ctx: ClockContext) => void`     | `-`     | Publishes clock context from root.                       |
+| `getClockContext` | `() => ClockContext \| undefined` | `-`     | Reads clock context when available.                      |
+| `useClockContext` | `() => ClockContext`              | `-`     | Reads context and throws outside `Clock.Root`.           |
+| `ClockContext`    | `type`                            | `-`     | Shared contract for state, labels, and wheel operations. |

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

@@ -0,0 +1,62 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import * as Clock from '../index.parts';
+	import type { ClockColumnInfo } from './resolve-visible-columns';
+
+	type Props = {
+		defaultValue?: string | null;
+		hourCycle?: 12 | 24;
+		granularity?: 'hour' | 'minute' | 'second';
+		minValue?: string;
+		maxValue?: string;
+		isDisabled?: boolean;
+		useSnippet?: boolean;
+		showAxis?: boolean;
+		axisHeight?: number;
+	};
+
+	let {
+		defaultValue = '14:30',
+		hourCycle = 24,
+		granularity = 'minute',
+		minValue,
+		maxValue,
+		isDisabled = false,
+		useSnippet = false,
+		showAxis = false,
+		axisHeight
+	}: Props = $props();
+
+	let value = $state<string | null>(untrack(() => defaultValue ?? null));
+</script>
+
+{#if useSnippet}
+	<Clock.Root
+		bind:value
+		{hourCycle}
+		{granularity}
+		{minValue}
+		{maxValue}
+		{isDisabled}
+		class="flex gap-2"
+	>
+		{#snippet column(col: ClockColumnInfo)}
+			<div data-testid="clock-column" data-type={col.type}>{col.label}</div>
+		{/snippet}
+		{#if showAxis}
+			<Clock.Axis data-testid="clock-axis" height={axisHeight} />
+		{/if}
+	</Clock.Root>
+{:else}
+	<Clock.Root
+		bind:value
+		{hourCycle}
+		{granularity}
+		{minValue}
+		{maxValue}
+		{isDisabled}
+		class="flex gap-2"
+	/>
+{/if}
+
+<p data-testid="clock-value">{value}</p>

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

@@ -0,0 +1,14 @@
+type Props = {
+    defaultValue?: string | null;
+    hourCycle?: 12 | 24;
+    granularity?: 'hour' | 'minute' | 'second';
+    minValue?: string;
+    maxValue?: string;
+    isDisabled?: boolean;
+    useSnippet?: boolean;
+    showAxis?: boolean;
+    axisHeight?: number;
+};
+declare const ClockRootTest: import("svelte").Component<Props, {}, "">;
+type ClockRootTest = ReturnType<typeof ClockRootTest>;
+export default ClockRootTest;