@human-kit/svelte-components 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/table/row/README.md

@@ -0,0 +1,27 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Row
+
+## API reference
+
+### Table.Row
+
+Name: `Table.Row`
+Description: Semantic table row part used in the header, body, or footer. In body scope it reflects row focus, selection, and disabled state.
+
+| Prop         | Type               | Default     | Description                                                     |
+| ------------ | ------------------ | ----------- | --------------------------------------------------------------- |
+| `id`         | `string \| number` | `undefined` | Stable row identifier used for selection state in `Table.Body`. |
+| `isDisabled` | `boolean`          | `false`     | Marks a body row as non-selectable.                             |
+| `textValue`  | `string`           | `undefined` | Reserved for future text-based navigation features.             |
+| `class`      | `string`           | `''`        | Class names for the `tr` element.                               |
+| `children`   | `Snippet`          | `undefined` | Row cells.                                                      |
+
+### Context utilities
+
+Name: `Table.Row` row context
+Description: Publishes row registration and cell-order helpers to descendant cells.
+
+| Prop                 | Type                    | Default | Description                                          |
+| -------------------- | ----------------------- | ------- | ---------------------------------------------------- |
+| `useTableRowContext` | `() => TableRowContext` | `-`     | Reads the current row token and cell-order contract. |

package/dist/table/row/table-row.svelte

@@ -0,0 +1,321 @@
+<script lang="ts">
+	import { onDestroy } from 'svelte';
+	import { SvelteMap } from 'svelte/reactivity';
+	import { writable } from 'svelte/store';
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import {
+		setTableRowContext,
+		useTableContext,
+		useTableSectionContext,
+		type TableSelectionKey
+	} from '../root/context';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+
+	type TableRowProps = Omit<HTMLAttributes<HTMLTableRowElement>, 'children' | 'id'> & {
+		id?: TableSelectionKey;
+		isDisabled?: boolean;
+		textValue?: string;
+		children?: Snippet;
+		class?: string;
+	};
+
+	let {
+		id,
+		isDisabled = false,
+		children,
+		class: className = '',
+		...restProps
+	}: TableRowProps = $props();
+
+	const table = useTableContext();
+	const section = useTableSectionContext();
+	const rowToken = table.createInstanceToken('row');
+	const cellOrder: string[] = [];
+	const cellElements = new SvelteMap<string, () => HTMLElement | undefined>();
+	const cellOrderVersion = writable(0);
+
+	let rowElement = $state<HTMLTableRowElement | undefined>(undefined);
+	let childListObserver: MutationObserver | null = null;
+
+	function notifyCellOrderChange() {
+		cellIndexCache = null;
+		cellOrderVersion.update((value) => value + 1);
+	}
+
+	function registerCellToken(token: string, getElement?: () => HTMLElement | undefined) {
+		if (!cellOrder.includes(token)) {
+			cellOrder.push(token);
+			notifyCellOrderChange();
+		}
+		if (getElement) {
+			cellElements.set(token, getElement);
+		}
+	}
+
+	function unregisterCellToken(token: string) {
+		cellElements.delete(token);
+		const index = cellOrder.indexOf(token);
+		if (index >= 0) {
+			cellOrder.splice(index, 1);
+			notifyCellOrderChange();
+		}
+	}
+
+	let cellIndexCache: Map<string, number> | null = null;
+
+	function buildCellIndexCache(): Map<string, number> {
+		if (cellIndexCache) return cellIndexCache;
+		// eslint-disable-next-line svelte/prefer-svelte-reactivity -- plain cache, not reactive state
+		const cache = new Map<string, number>();
+		if (rowElement) {
+			const directCells = rowElement.children;
+			// eslint-disable-next-line svelte/prefer-svelte-reactivity -- plain cache, not reactive state
+			const elementToIndex = new Map<HTMLElement, number>();
+			for (let i = 0; i < directCells.length; i += 1) {
+				const child = directCells[i];
+				if (child instanceof HTMLElement) {
+					elementToIndex.set(child, i);
+				}
+			}
+			for (const registeredToken of cellOrder) {
+				const element = cellElements.get(registeredToken)?.();
+				if (element) {
+					const idx = elementToIndex.get(element);
+					if (idx !== undefined) {
+						cache.set(registeredToken, idx);
+					}
+				}
+			}
+		}
+		cellIndexCache = cache;
+		return cache;
+	}
+
+	function getCellIndex(token: string) {
+		const cache = buildCellIndexCache();
+		const cached = cache.get(token);
+		if (cached !== undefined) return cached;
+		return cellOrder.indexOf(token);
+	}
+
+	setTableRowContext({
+		rowToken,
+		section: section.section,
+		get rowId() {
+			return id;
+		},
+		get isDisabled() {
+			return isDisabled;
+		},
+		cellOrderVersion,
+		registerCellToken,
+		unregisterCellToken,
+		getCellIndex
+	});
+
+	function syncRowRegistration() {
+		table.registerRow({
+			token: rowToken,
+			section: section.section,
+			id,
+			disabled: isDisabled,
+			element: rowElement
+		});
+	}
+
+	syncRowRegistration();
+
+	$effect(() => {
+		syncRowRegistration();
+	});
+
+	let pendingCellOrderNotify = false;
+
+	function scheduleCellOrderNotify() {
+		if (!pendingCellOrderNotify) {
+			pendingCellOrderNotify = true;
+			queueMicrotask(() => {
+				pendingCellOrderNotify = false;
+				cellIndexCache = null;
+				notifyCellOrderChange();
+			});
+		}
+	}
+
+	$effect(() => {
+		childListObserver?.disconnect();
+		childListObserver = null;
+
+		if (!rowElement) {
+			return;
+		}
+
+		const observer = new MutationObserver(() => {
+			scheduleCellOrderNotify();
+		});
+		observer.observe(rowElement, { childList: true });
+		childListObserver = observer;
+
+		return () => {
+			observer.disconnect();
+			if (childListObserver === observer) {
+				childListObserver = null;
+			}
+		};
+	});
+
+	onDestroy(() => {
+		childListObserver?.disconnect();
+		table.unregisterRow(rowToken);
+	});
+
+	const selectionVersion = table.selectionVersion;
+	const focusVersion = table.focusVersion;
+	const isSelected = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowSelected(id) : false;
+	});
+	const isFocusWithin = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? table.isRowFocused(rowToken) : false;
+	});
+	const isFocused = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? table.isRowFocusTarget(rowToken) : false;
+	});
+	const isFocusVisible = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? isFocused && table.focusVisible : false;
+	});
+	const isFocusVisibleWithin = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? isFocusWithin && table.focusVisible : false;
+	});
+	const isAriaDisabled = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowDisabled(id, isDisabled) : isDisabled;
+	});
+
+	function handleFocus() {
+		if (section.section !== 'body') return;
+		if (isAriaDisabled) return;
+		if (!table.isRowTabStop(rowToken)) return;
+		table.setFocusedRow(rowToken, table.getRowFocusEdge(rowToken) ?? 'start');
+		table.setFocusVisible(shouldShowFocusVisible(rowElement ?? null));
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, rowElement ?? null);
+		table.setFocusVisible(false);
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		if (section.section !== 'body') return;
+		if (event.target !== rowElement) return;
+		trackInteractionModality(event, rowElement ?? 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', {
+					shiftKey: event.shiftKey,
+					ctrlKey: event.ctrlKey,
+					metaKey: event.metaKey,
+					altKey: event.altKey
+				});
+				return;
+			case 'ArrowDown':
+				event.preventDefault();
+				table.moveFocus('down', {
+					shiftKey: event.shiftKey,
+					ctrlKey: event.ctrlKey,
+					metaKey: event.metaKey,
+					altKey: event.altKey
+				});
+				return;
+			case 'ArrowLeft':
+				event.preventDefault();
+				table.moveFocus('left');
+				return;
+			case 'ArrowRight':
+				event.preventDefault();
+				table.moveFocus('right');
+				return;
+			case 'Home':
+				event.preventDefault();
+				table.moveToBodyRowStart();
+				return;
+			case 'End':
+				event.preventDefault();
+				table.moveToBodyRowEnd();
+				return;
+			case 'Enter':
+			case ' ':
+				event.preventDefault();
+				if (event.repeat) return;
+				if (!isAriaDisabled) {
+					table.pressRow(id, {
+						shiftKey: event.shiftKey,
+						ctrlKey: event.ctrlKey,
+						metaKey: event.metaKey,
+						altKey: event.altKey
+					});
+				}
+				return;
+		}
+	}
+</script>
+
+<tr
+	bind:this={rowElement}
+	class={className}
+	tabindex={section.section === 'body'
+		? !isAriaDisabled
+			? table.isRowTabStop(rowToken)
+				? 0
+				: -1
+			: undefined
+		: undefined}
+	data-focused={isFocused ? 'true' : undefined}
+	data-focus-visible={isFocusVisible ? 'true' : undefined}
+	data-focus-within={isFocusWithin ? 'true' : undefined}
+	data-focus-visible-within={isFocusVisibleWithin ? 'true' : undefined}
+	data-selected={isSelected ? 'true' : undefined}
+	data-disabled={isAriaDisabled || undefined}
+	aria-selected={section.section === 'body' && table.selectionMode !== 'none'
+		? isSelected
+		: undefined}
+	aria-disabled={section.section === 'body' && isAriaDisabled ? true : undefined}
+	onfocus={handleFocus}
+	onmousedown={handleMouseDown}
+	onkeydown={handleKeyDown}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{/if}
+</tr>

package/dist/table/row/table-row.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type TableSelectionKey } from '../root/context';
+type TableRowProps = Omit<HTMLAttributes<HTMLTableRowElement>, 'children' | 'id'> & {
+    id?: TableSelectionKey;
+    isDisabled?: boolean;
+    textValue?: string;
+    children?: Snippet;
+    class?: string;
+};
+declare const TableRow: import("svelte").Component<TableRowProps, {}, "">;
+type TableRow = ReturnType<typeof TableRow>;
+export default TableRow;

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.