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

package/dist/popover/trigger/popover-trigger.svelte

@@ -43,7 +43,7 @@
 
 		if (button && wrapperRef?.contains(button)) {
 			setActiveTrigger(button);
-			popoverCtx.toggle();
+			popoverCtx.toggle('trigger-press', event);
 		}
 	}
 

package/dist/portal/portal.svelte

@@ -18,6 +18,8 @@
 		if (!browser || !wrapper) return;
 
 		await tick();
+		const wrapperNode = wrapper;
+		if (!wrapperNode) return;
 
 		const targetEl = document.querySelector(target);
 		if (!targetEl) {
@@ -25,7 +27,7 @@
 			return;
 		}
 
-		targetEl.appendChild(wrapper);
+		targetEl.appendChild(wrapperNode);
 	});
 
 	onDestroy(() => {

package/dist/primitives/click-outside.d.ts

@@ -4,7 +4,7 @@
  */
 export type ClickOutsideOptions = {
     /** Callback when clicking outside. */
-    handler: () => void;
+    handler: (event: MouseEvent) => void;
     /** Whether the listener is enabled. */
     enabled?: boolean;
     /** Elements to ignore (clicks on these won't trigger). */

package/dist/primitives/click-outside.js

@@ -41,7 +41,7 @@ export function clickOutside(node, options) {
         // This prevents closing when clicking on nested popovers/dialogs
         if (isInTopLayer(target))
             return;
-        handler();
+        handler(event);
     }
     if (enabled) {
         document.addEventListener('mousedown', handleClick, true);

package/dist/primitives/focus-trap.d.ts

@@ -2,6 +2,11 @@
  * Focus trap primitive.
  * Traps keyboard focus within a container element.
  */
+export type FocusTrapOptions = {
+    enabled?: boolean;
+    restoreFocus?: boolean;
+    initialFocus?: HTMLElement | string | (() => HTMLElement | null | undefined);
+};
 /**
  * Svelte action that traps focus within an element.
  *
@@ -13,7 +18,7 @@
  * </div>
  * ```
  */
-export declare function focusTrap(node: HTMLElement, enabled?: boolean): {
-    update(newEnabled: boolean): void;
+export declare function focusTrap(node: HTMLElement, options?: boolean | FocusTrapOptions): {
+    update(newOptions: boolean | FocusTrapOptions): void;
     destroy(): void;
 };

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])',
@@ -11,8 +12,29 @@ const FOCUSABLE_SELECTOR = [
     '[tabindex]:not([tabindex="-1"])',
     '[contenteditable="true"]'
 ].join(', ');
+function resolveEnabled(options) {
+    if (typeof options === 'boolean')
+        return options;
+    return options.enabled ?? true;
+}
+function resolveRestoreFocus(options) {
+    if (typeof options === 'boolean')
+        return true;
+    return options.restoreFocus ?? true;
+}
+function resolveInitialFocus(container, initialFocus) {
+    if (!initialFocus)
+        return null;
+    if (typeof initialFocus === 'function') {
+        return initialFocus() ?? null;
+    }
+    if (typeof initialFocus === 'string') {
+        return container.querySelector(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.
@@ -25,8 +47,11 @@ function getFocusableElements(container) {
  * </div>
  * ```
  */
-export function focusTrap(node, enabled = true) {
+export function focusTrap(node, options = true) {
     let previousActiveElement = null;
+    let enabled = resolveEnabled(options);
+    let restoreFocus = resolveRestoreFocus(options);
+    let initialFocus = typeof options === 'boolean' ? undefined : options.initialFocus;
     function handleKeydown(event) {
         if (event.key !== 'Tab')
             return;
@@ -49,12 +74,11 @@ export function focusTrap(node, enabled = 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() {
@@ -62,21 +86,25 @@ export function focusTrap(node, enabled = 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) {
+                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);
     }
     function deactivate() {
         document.removeEventListener('keydown', handleKeydown, true);
-        if (previousActiveElement && previousActiveElement.focus) {
+        if (restoreFocus && previousActiveElement && previousActiveElement.focus) {
             previousActiveElement.focus();
         }
     }
@@ -84,14 +112,19 @@ export function focusTrap(node, enabled = true) {
         activate();
     }
     return {
-        update(newEnabled) {
-            if (newEnabled && !enabled) {
+        update(newOptions) {
+            const nextEnabled = resolveEnabled(newOptions);
+            const nextRestoreFocus = resolveRestoreFocus(newOptions);
+            if (nextEnabled && !enabled) {
                 activate();
             }
-            else if (!newEnabled && enabled) {
+            else if (!nextEnabled && enabled) {
                 deactivate();
             }
-            enabled = newEnabled;
+            options = newOptions;
+            enabled = nextEnabled;
+            restoreFocus = nextRestoreFocus;
+            initialFocus = typeof newOptions === 'boolean' ? undefined : newOptions.initialFocus;
         },
         destroy() {
             if (enabled) {

package/dist/primitives/index.d.ts

@@ -4,3 +4,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/index.js

@@ -5,3 +5,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/input-modality.d.ts

@@ -0,0 +1,7 @@
+export type InputModality = 'keyboard' | 'pointer' | 'virtual';
+export declare function initInputModality(target?: HTMLElement | null): void;
+export declare function trackInteractionModality(event?: Event, target?: HTMLElement | null): void;
+export declare function getInteractionModality(): InputModality;
+export declare function shouldShowFocusVisible(target: HTMLElement | null): boolean;
+export declare function focusWithModality(target: HTMLElement, modality: InputModality, options?: FocusOptions): void;
+export declare function resolveCloseInteractionModality(reason: string, event?: Event): InputModality;

package/dist/primitives/input-modality.js

@@ -0,0 +1,125 @@
+let currentModality = 'virtual';
+const listenedWindows = new WeakSet();
+let forcedFocusTarget = null;
+let forcedFocusModality = null;
+function isModifierOnlyKey(event) {
+    return (event.key === 'Shift' || event.key === 'Control' || event.key === 'Alt' || event.key === 'Meta');
+}
+function isKeyboardModalityKey(event) {
+    if (event.ctrlKey || event.metaKey || event.altKey)
+        return false;
+    if (isModifierOnlyKey(event))
+        return false;
+    return true;
+}
+function ensureWindowListeners(win) {
+    if (!win)
+        return;
+    if (listenedWindows.has(win))
+        return;
+    const onKeyDown = (event) => {
+        if (!isKeyboardModalityKey(event))
+            return;
+        currentModality = 'keyboard';
+    };
+    const onPointerDown = () => {
+        currentModality = 'pointer';
+    };
+    const onFocusIn = () => {
+        if (currentModality === 'pointer' || currentModality === 'keyboard')
+            return;
+        currentModality = 'virtual';
+    };
+    win.addEventListener('keydown', onKeyDown, true);
+    win.addEventListener('pointerdown', onPointerDown, true);
+    win.addEventListener('mousedown', onPointerDown, true);
+    win.addEventListener('focusin', onFocusIn, true);
+    listenedWindows.add(win);
+}
+export function initInputModality(target) {
+    const ownerWindow = target?.ownerDocument?.defaultView;
+    if (ownerWindow) {
+        ensureWindowListeners(ownerWindow);
+        return;
+    }
+    if (typeof window !== 'undefined') {
+        ensureWindowListeners(window);
+    }
+}
+function inferModalityFromEvent(event) {
+    if (!event)
+        return undefined;
+    if (event instanceof KeyboardEvent) {
+        return isKeyboardModalityKey(event) ? 'keyboard' : undefined;
+    }
+    if (event instanceof MouseEvent && event.type === 'click' && event.detail === 0) {
+        return 'keyboard';
+    }
+    if (event instanceof PointerEvent || event instanceof MouseEvent) {
+        return 'pointer';
+    }
+    return undefined;
+}
+function resolveModalityForTarget(target) {
+    if (target && forcedFocusTarget === target && forcedFocusModality) {
+        const modality = forcedFocusModality;
+        forcedFocusTarget = null;
+        forcedFocusModality = null;
+        return modality;
+    }
+    return currentModality;
+}
+export function trackInteractionModality(event, target) {
+    initInputModality(target);
+    const inferred = inferModalityFromEvent(event);
+    if (inferred) {
+        currentModality = inferred;
+    }
+}
+export function getInteractionModality() {
+    return currentModality;
+}
+export function shouldShowFocusVisible(target) {
+    if (!target)
+        return false;
+    const modality = resolveModalityForTarget(target);
+    if (modality === 'pointer')
+        return false;
+    return target.matches(':focus-visible');
+}
+export function focusWithModality(target, modality, options) {
+    initInputModality(target);
+    // The forced target/modality pair is a synchronous safety net so a focus handler that runs
+    // immediately after target.focus() can resolve the intended modality without racing async timing.
+    // If it is consumed later, currentModality still preserves the same modality as fallback.
+    forcedFocusTarget = target;
+    forcedFocusModality = modality;
+    currentModality = modality;
+    if (modality === 'pointer') {
+        const pointerFocusOptions = {
+            ...(options ?? {}),
+            focusVisible: false
+        };
+        target.focus(pointerFocusOptions);
+    }
+    else {
+        target.focus(options);
+    }
+    queueMicrotask(() => {
+        if (forcedFocusTarget !== target)
+            return;
+        forcedFocusTarget = null;
+        forcedFocusModality = null;
+    });
+}
+export function resolveCloseInteractionModality(reason, event) {
+    if (reason === 'escape-key')
+        return 'keyboard';
+    if (event instanceof KeyboardEvent)
+        return 'keyboard';
+    if (event instanceof PointerEvent || event instanceof MouseEvent)
+        return 'pointer';
+    if (reason === 'outside-press')
+        return 'pointer';
+    return 'virtual';
+}

package/dist/test-utils/focus-contract.d.ts

@@ -0,0 +1,3 @@
+export declare function expectFocusVisibleImpliesFocusWithin(root: HTMLElement | null): void;
+export declare function expectFocusVisibleImpliesFocused(node: HTMLElement | null): void;
+export declare function expectNoFalseFocusAttributes(scope?: ParentNode): void;

package/dist/test-utils/focus-contract.js

@@ -0,0 +1,26 @@
+import { expect } from 'vitest';
+export function expectFocusVisibleImpliesFocusWithin(root) {
+    expect(root).toBeTruthy();
+    const focusVisible = root?.getAttribute('data-focus-visible');
+    const focusWithin = root?.getAttribute('data-focus-within');
+    if (focusVisible === 'true') {
+        expect(focusWithin).toBe('true');
+    }
+}
+export function expectFocusVisibleImpliesFocused(node) {
+    expect(node).toBeTruthy();
+    const focusVisible = node?.getAttribute('data-focus-visible');
+    const focused = node?.getAttribute('data-focused');
+    if (focusVisible === 'true') {
+        expect(focused).toBe('true');
+    }
+}
+export function expectNoFalseFocusAttributes(scope = document) {
+    const focusAttrs = ['data-focused', 'data-focus-visible', 'data-focus-within'];
+    for (const attr of focusAttrs) {
+        const nodes = Array.from(scope.querySelectorAll(`[${attr}]`));
+        for (const node of nodes) {
+            expect(node.getAttribute(attr)).not.toBe('false');
+        }
+    }
+}

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.