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

package/dist/table/sort-trigger/table-sort-trigger.svelte

@@ -0,0 +1,183 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { onDestroy, onMount } from 'svelte';
+	import { useTableCellContext, useTableColumnContext, useTableContext } from '../root/context';
+	import type { TableSortTriggerProps, TableSortTriggerRenderState } from '../types.js';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+
+	let { children }: TableSortTriggerProps = $props();
+
+	const table = useTableContext();
+	const column = useTableColumnContext();
+	const cell = useTableCellContext();
+	const sortVersion = table.sortVersion;
+
+	let wrapperRef = $state<HTMLElement | null>(null);
+	let activeTrigger = $state<HTMLElement | null>(null);
+
+	const sortDirection = $derived.by(() => {
+		void $sortVersion;
+		return table.getSortDirection(column.id);
+	});
+	const renderState = $derived.by<TableSortTriggerRenderState>(() => ({
+		sortDirection
+	}));
+
+	function getTriggerElement() {
+		if (!wrapperRef) return null;
+		return wrapperRef.querySelector<HTMLElement>('button, [role="button"]');
+	}
+
+	function syncTriggerMetadata(trigger: HTMLElement | null) {
+		if (!trigger) return;
+
+		if (trigger instanceof HTMLButtonElement && !trigger.hasAttribute('type')) {
+			trigger.type = 'button';
+		}
+
+		trigger.setAttribute('data-table-sort-trigger', 'true');
+		if (sortDirection) {
+			trigger.setAttribute('data-sorted', 'true');
+			trigger.setAttribute('data-sort-direction', sortDirection);
+		} else {
+			trigger.removeAttribute('data-sorted');
+			trigger.removeAttribute('data-sort-direction');
+		}
+	}
+
+	function refreshActiveTrigger() {
+		activeTrigger = getTriggerElement();
+		syncTriggerMetadata(activeTrigger);
+	}
+
+	$effect(() => {
+		table.registerColumnSortTrigger(column.token);
+		syncTriggerMetadata(activeTrigger);
+
+		return () => {
+			table.unregisterColumnSortTrigger(column.token);
+		};
+	});
+
+	function handleFocusIn(event: FocusEvent) {
+		const target = event.target instanceof HTMLElement ? event.target : activeTrigger;
+		table.setFocusedCell(cell.cellKey);
+		table.setFocusVisible(shouldShowFocusVisible(target ?? null));
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		const target = event.target as HTMLElement | null;
+		const trigger = target?.closest('button, [role="button"]') as HTMLElement | null;
+		if (!trigger || !wrapperRef?.contains(trigger)) return;
+
+		trackInteractionModality(event, trigger);
+		table.setFocusVisible(false);
+		event.stopPropagation();
+	}
+
+	function handleClick(event: MouseEvent) {
+		const target = event.target as HTMLElement | null;
+		const trigger = target?.closest('button, [role="button"]') as HTMLElement | null;
+		if (!trigger || !wrapperRef?.contains(trigger)) return;
+
+		activeTrigger = trigger;
+		syncTriggerMetadata(activeTrigger);
+		event.stopPropagation();
+		table.toggleSort(column.id);
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		const target = event.target as HTMLElement | null;
+		const trigger = target?.closest('button, [role="button"]') as HTMLElement | null;
+		if (!trigger || !wrapperRef?.contains(trigger)) return;
+
+		activeTrigger = trigger;
+		syncTriggerMetadata(activeTrigger);
+		trackInteractionModality(event, trigger);
+
+		if ((event.ctrlKey || event.metaKey) && event.key === 'Home') {
+			event.preventDefault();
+			event.stopPropagation();
+			table.moveToGridStart();
+			return;
+		}
+
+		if ((event.ctrlKey || event.metaKey) && event.key === 'End') {
+			event.preventDefault();
+			event.stopPropagation();
+			table.moveToGridEnd();
+			return;
+		}
+
+		switch (event.key) {
+			case 'ArrowUp':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveFocus('up', {
+					shiftKey: event.shiftKey,
+					ctrlKey: event.ctrlKey,
+					metaKey: event.metaKey,
+					altKey: event.altKey
+				});
+				return;
+			case 'ArrowDown':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveFocus('down', {
+					shiftKey: event.shiftKey,
+					ctrlKey: event.ctrlKey,
+					metaKey: event.metaKey,
+					altKey: event.altKey
+				});
+				return;
+			case 'ArrowLeft':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveFocus('left');
+				return;
+			case 'ArrowRight':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveFocus('right');
+				return;
+			case 'Home':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveToRowStart();
+				return;
+			case 'End':
+				event.preventDefault();
+				event.stopPropagation();
+				table.moveToRowEnd();
+				return;
+			case 'Enter':
+			case ' ':
+				event.stopPropagation();
+				return;
+		}
+	}
+
+	onMount(() => {
+		refreshActiveTrigger();
+		wrapperRef?.addEventListener('focusin', handleFocusIn);
+		wrapperRef?.addEventListener('mousedown', handleMouseDown);
+		wrapperRef?.addEventListener('click', handleClick);
+		wrapperRef?.addEventListener('keydown', handleKeyDown);
+	});
+
+	onDestroy(() => {
+		wrapperRef?.removeEventListener('focusin', handleFocusIn);
+		wrapperRef?.removeEventListener('mousedown', handleMouseDown);
+		wrapperRef?.removeEventListener('click', handleClick);
+		wrapperRef?.removeEventListener('keydown', handleKeyDown);
+	});
+</script>
+
+<div bind:this={wrapperRef} style="display: contents;">
+	{#if children}
+		{@render (children as Snippet<[TableSortTriggerRenderState]>)(renderState)}
+	{/if}
+</div>

package/dist/table/sort-trigger/table-sort-trigger.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { TableSortTriggerProps } from '../types.js';
+declare const TableSortTrigger: import("svelte").Component<TableSortTriggerProps, {}, "">;
+type TableSortTrigger = ReturnType<typeof TableSortTrigger>;
+export default TableSortTrigger;

package/dist/table/types.d.ts

@@ -0,0 +1,95 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { TableColumnWidth, TableContext, TableDisabledBehavior, TableRowActionHandler, TableSelectionBehavior, TableSelectionKey, TableSelectionMode, TableSortDirection, TableSortDescriptor } from './root/context.js';
+export type TableColumnProps = {
+    id: string;
+    isRowHeader?: boolean;
+    textValue?: string;
+    width?: TableColumnWidth;
+    defaultWidth?: TableColumnWidth;
+    minWidth?: number;
+    maxWidth?: number;
+    children?: Snippet;
+};
+export type TableHeaderProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+export type TableBodyProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+export type TableFooterProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+export type TableRootProps = Omit<HTMLAttributes<HTMLTableElement>, 'children'> & {
+    selectionMode?: TableSelectionMode;
+    selectionBehavior?: TableSelectionBehavior;
+    disabledBehavior?: TableDisabledBehavior;
+    disallowEmptySelection?: boolean;
+    hiddenColumns?: Iterable<string>;
+    defaultHiddenColumns?: Iterable<string>;
+    selectedKeys?: Iterable<TableSelectionKey>;
+    defaultSelectedKeys?: Iterable<TableSelectionKey>;
+    sortDescriptor?: TableSortDescriptor;
+    defaultSortDescriptor?: TableSortDescriptor;
+    columnWidths?: Map<string, TableColumnWidth>;
+    defaultColumnWidths?: Iterable<readonly [string, TableColumnWidth]>;
+    disabledKeys?: Iterable<TableSelectionKey>;
+    onRowAction?: TableRowActionHandler;
+    onSelectionChange?: (keys: Set<TableSelectionKey>) => void;
+    onSortChange?: (descriptor: TableSortDescriptor | undefined) => void;
+    onColumnWidthsChange?: (widths: Map<string, TableColumnWidth>) => void;
+    onHiddenColumnsChange?: (columnIds: string[]) => void;
+    onColumnResizeStart?: (columnId: string) => void;
+    onColumnResizeEnd?: (widths: Map<string, TableColumnWidth>) => void;
+    children?: Snippet;
+    class?: string;
+    context?: TableContext;
+    element?: HTMLTableElement;
+};
+export type TableRowProps = Omit<HTMLAttributes<HTMLTableRowElement>, 'children' | 'id'> & {
+    id?: TableSelectionKey;
+    isDisabled?: boolean;
+    textValue?: string;
+    children?: Snippet;
+    class?: string;
+};
+export type TableColumnHeaderCellProps = Omit<HTMLAttributes<HTMLTableCellElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+export type TableSortTriggerRenderState = {
+    sortDirection: TableSortDirection | undefined;
+};
+export type TableSortTriggerProps = {
+    children?: Snippet<[TableSortTriggerRenderState]> | Snippet;
+};
+export type TableColumnResizerProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    step?: number;
+    shiftStep?: number;
+    children?: Snippet;
+    class?: string;
+};
+export type TableCellProps = Omit<HTMLAttributes<HTMLTableCellElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+export type TableEmptyStateProps = {
+    children?: Snippet;
+    class?: string;
+};
+export type TableCheckboxProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class' | 'id' | 'role' | 'tabindex' | 'aria-checked' | 'aria-disabled' | 'onclick' | 'onkeydown'> & {
+    id?: string;
+    title?: string;
+    children?: Snippet;
+    class?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+};
+export type TableCheckboxIndicatorProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class'> & {
+    keepMounted?: boolean;
+    children?: Snippet;
+    class?: string;
+};

package/dist/table/types.js

@@ -0,0 +1 @@
+export {};

package/dist/table/utils/handle-body-keydown.d.ts

@@ -0,0 +1,13 @@
+import type { TableContext } from '../root/context';
+type TableBodyKeydownOptions = {
+    event: KeyboardEvent;
+    table: Pick<TableContext, 'selectionMode' | 'selectAllRows' | 'moveToGridStart' | 'moveToGridEnd' | 'moveFocus'>;
+    focusTarget: HTMLElement | null | undefined;
+    isDisabled: boolean;
+    onHome: () => void;
+    onEnd: () => void;
+    onEnter: () => void;
+    onSpace: () => void;
+};
+export declare function handleTableBodyKeydown({ event, table, focusTarget, isDisabled, onHome, onEnd, onEnter, onSpace }: TableBodyKeydownOptions): void;
+export {};

package/dist/table/utils/handle-body-keydown.js

@@ -0,0 +1,67 @@
+import { trackInteractionModality } from '../../primitives/input-modality';
+function getInteraction(event) {
+    return {
+        shiftKey: event.shiftKey,
+        ctrlKey: event.ctrlKey,
+        metaKey: event.metaKey,
+        altKey: event.altKey
+    };
+}
+export function handleTableBodyKeydown({ event, table, focusTarget, isDisabled, onHome, onEnd, onEnter, onSpace }) {
+    trackInteractionModality(event, focusTarget ?? null);
+    if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
+        if (table.selectionMode === 'multiple') {
+            event.preventDefault();
+            table.selectAllRows();
+        }
+        return;
+    }
+    if ((event.ctrlKey || event.metaKey) && event.key === 'Home') {
+        event.preventDefault();
+        table.moveToGridStart();
+        return;
+    }
+    if ((event.ctrlKey || event.metaKey) && event.key === 'End') {
+        event.preventDefault();
+        table.moveToGridEnd();
+        return;
+    }
+    switch (event.key) {
+        case 'ArrowUp':
+            event.preventDefault();
+            table.moveFocus('up', getInteraction(event));
+            return;
+        case 'ArrowDown':
+            event.preventDefault();
+            table.moveFocus('down', getInteraction(event));
+            return;
+        case 'ArrowLeft':
+            event.preventDefault();
+            table.moveFocus('left');
+            return;
+        case 'ArrowRight':
+            event.preventDefault();
+            table.moveFocus('right');
+            return;
+        case 'Home':
+            event.preventDefault();
+            onHome();
+            return;
+        case 'End':
+            event.preventDefault();
+            onEnd();
+            return;
+        case 'Enter':
+            event.preventDefault();
+            if (event.repeat || isDisabled)
+                return;
+            onEnter();
+            return;
+        case ' ':
+            event.preventDefault();
+            if (event.repeat || isDisabled)
+                return;
+            onSpace();
+            return;
+    }
+}

package/dist/table/utils/visually-hidden-style.d.ts

@@ -0,0 +1 @@
+export declare const visuallyHiddenStyle = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;";

package/dist/table/utils/visually-hidden-style.js

@@ -0,0 +1 @@
+export const visuallyHiddenStyle = 'position:fixed;top:0;left:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';

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.