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

package/dist/FOCUS_STATE_CONTRACT.md

@@ -0,0 +1,63 @@
+# Focus State Contract
+
+## Scope
+
+Focus-state contract for composed and interactive library components.
+
+## Canonical Attributes
+
+- `data-focused`: focused interactive element (real focus or logical focus for active item).
+- `data-focus-visible`: visible focus based on keyboard/screen-reader modality.
+- `data-focus-within`: any descendant inside the composed container has focus.
+
+## Serialization Rules
+
+1. Attributes are serialized as presence (`"true"`) or absence.
+2. Never serialize `"false"`.
+
+## Invariants
+
+1. On containers, `data-focus-visible` implies `data-focus-within`.
+2. On items, `data-focus-visible` implies `data-focused`.
+3. On external blur (focus leaves scope), clear container `data-focus-within` and `data-focus-visible`.
+
+## Modality
+
+- Keyboard/SR: may activate `data-focus-visible`.
+- Pointer: should not activate `data-focus-visible` by default.
+
+Canonical implementation lives in `primitives/input-modality.ts`:
+
+- `trackInteractionModality(event, target)` records input modality transitions.
+- `shouldShowFocusVisible(target)` resolves whether `data-focus-visible` should be shown.
+- `focusWithModality(target, modality)` atomically sets modality + programmatic focus restore.
+- Keep explicit `trackInteractionModality` calls in component keyboard/pointer handlers to guarantee deterministic modality updates before local focus-state logic runs.
+
+## Restore focus
+
+On overlay/popover close, transient trigger state is allowed:
+
+- `escape-key` => `data-focused=true` and `data-focus-visible=true`.
+- `outside-press` => `data-focused=true` and `data-focus-visible` absent.
+
+## Recommended Implementation
+
+- Native visual baseline: `:focus`, `:focus-visible`, `:focus-within`.
+- Use `data-*` for composed state and restore semantics.
+- Avoid overengineering: centralize minimal synchronization utilities and validate with contract tests.
+
+## 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/FOCUS_STATE_REVIEW_TEMPLATE.md

@@ -0,0 +1,70 @@
+# Focus State Review Template
+
+## Usage
+
+Template to validate focus-related changes without adding extra CI guardrails.
+Fill this out for PRs that modify interaction, keyboard navigation, overlays, or focus-based styling.
+
+## 1) Review Metadata
+
+- PR/Branch:
+- Component(s):
+- Reviewer:
+- Date:
+- Verified browsers:
+  - [ ] Chromium
+  - [ ] Firefox
+  - [ ] WebKit/Safari
+
+## 2) Minimum Modality Matrix (per component)
+
+> Mark **OK/NA/FAIL** and add a short note when failing.
+
+| Scenario                           | What to validate                                                            | Status | Note |
+| ---------------------------------- | --------------------------------------------------------------------------- | ------ | ---- |
+| Keyboard (Tab/Arrow/Home/End/Page) | `data-*` and ARIA stay in sync with logical focus                           |        |      |
+| Pointer (click/mousedown)          | do not elevate `data-focus-visible` by default                              |        |      |
+| External blur                      | transient state cleanup (`data-focus-within`, `data-focus-visible`)         |        |      |
+| Close restore (`escape-key`)       | trigger: `data-focused=true`, `data-focus-visible=true` (when applicable)   |        |      |
+| Close restore (`outside-press`)    | trigger: `data-focused=true`, `data-focus-visible` absent (when applicable) |        |      |
+| Programmatic focus                 | does not break invariants or leave stale state                              |        |      |
+
+## 3) Required Invariants
+
+- [ ] Never serialize `'false'` for `data-focused`, `data-focus-visible`, `data-focus-within`.
+- [ ] On containers: `data-focus-visible => data-focus-within`.
+- [ ] On items: `data-focus-visible => data-focused`.
+- [ ] No visible desync between real focus, logical focus, and `data-*` attributes.
+
+## 4) Component Status (living status)
+
+> Use one row per component touched or audited.
+
+| Component  | Status                            | Current coverage | Residual risk   | Owner |
+| ---------- | --------------------------------- | ---------------- | --------------- | ----- |
+| DatePicker | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Popover    | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| ListBox    | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| ComboBox   | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Dialog     | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Calendar   | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+
+## 5) PR Checklist
+
+- [ ] If focus/keyboard/overlay behavior changed, tests were added or updated.
+- [ ] Shared helper was used: `src/lib/test-utils/focus-contract.ts`.
+- [ ] Focused suites for affected components were run.
+- [ ] If the change was cross-cutting, full package test suite was run.
+
+## 6) Suggested Commands
+
+- Focused (example):
+  - `bun run test -- --run src/lib/datepicker src/lib/popover src/lib/listbox src/lib/combobox src/lib/dialog src/lib/calendar`
+- Full:
+  - `bun run test -- --run`
+
+## 7) Final Decision
+
+- Final status: [ ] Approved [ ] Approved with risk [ ] Blocked
+- Residual risk summary:
+- Follow-up actions:

package/dist/button/README.md

@@ -0,0 +1,48 @@
+# Button
+
+## Description
+
+`Button` is a headless native button with RAC-aligned pending semantics, pressed-state exposure, and modality-aware focus data attributes.
+
+## Anatomy
+
+- `Button.Root`
+
+```svelte
+<Button.Root>
+	{#snippet children({ isPending, isPressed })}
+		{#if isPending}
+			<SavingSpinner />
+		{:else}
+			<span class:is-pressed={isPressed}>Save</span>
+		{/if}
+	{/snippet}
+</Button.Root>
+```
+
+## Usage guidelines
+
+- Use native button props such as `type`, `name`, `value`, and form attributes directly on `Button.Root`.
+- Use `isPending` to keep the button focusable while blocking activation and hover state.
+- Style interaction states with `data-hovered`, `data-pressed`, `data-focused`, `data-focus-visible`, `data-disabled`, and `data-pending`.
+
+## API reference
+
+`Button.Root` supports:
+
+- `isPending?: boolean`
+- `isDisabled?: boolean`
+- `children?: Snippet<[ButtonRenderState]> | Snippet`
+- `type?: 'button' | 'submit' | 'reset'`
+- `...restProps: HTMLButtonAttributes`
+
+## Accessibility
+
+- `Button.Root` renders a native `<button>`.
+- `isPending` applies `aria-disabled="true"`, preserves focusability, blocks press behavior, and announces the pending state through an internal polite live region.
+- `data-focus-visible` follows the shared modality contract and is only exposed for keyboard or virtual focus.
+
+## Notes
+
+- When `type="submit"` and `isPending` is true, the rendered button type switches to `button` to prevent implicit and explicit form submission.
+- Pending does not serialize `data-disabled`; it is represented by `data-pending`.

package/dist/button/TODO.md

@@ -0,0 +1,13 @@
+# Button TODO
+
+## Goal
+
+Track Button work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [S][P0][Area: Architecture][Owner: Unassigned][Target: Done] Create base `root` part with namespace exports.
+- [x] [S][P0][Area: Interaction][Owner: Unassigned][Target: Done] Implement native press, hover, focus, and focus-visible state exposure.
+- [x] [S][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Match RAC-style pending semantics with `aria-disabled`, live announcement, and submit suppression.
+- [x] [S][P0][Area: Testing][Owner: Unassigned][Target: Done] Add baseline tests for press, pending, disabled, focus, and form behavior.
+- [ ] [S][P1][Area: API][Owner: Unassigned][Target: TBD] Evaluate whether to expose a dedicated `pendingLabel` override if consumers need localized announcement text without custom child content.

package/dist/button/index.d.ts

@@ -0,0 +1,5 @@
+export * as Button from './index.parts.js';
+export { default as ButtonRoot } from './root/button-root.svelte';
+export type { ButtonRenderState } from './root/button-root.svelte';
+import * as ButtonParts from './index.parts.js';
+export default ButtonParts;

package/dist/button/index.js

@@ -0,0 +1,4 @@
+export * as Button from './index.parts.js';
+export { default as ButtonRoot } from './root/button-root.svelte';
+import * as ButtonParts from './index.parts.js';
+export default ButtonParts;

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

@@ -0,0 +1 @@
+export { default as Root } from './root/button-root.svelte';

package/dist/button/index.parts.js

@@ -0,0 +1 @@
+export { default as Root } from './root/button-root.svelte';

package/dist/button/root/README.md

@@ -0,0 +1,43 @@
+# Button Root
+
+## API reference
+
+### Button.Root
+
+Name: `Button.Root`  
+Description: Native button root with pressed, hovered, focused, focus-visible, disabled, and pending render state.
+
+| Prop           | Type                                      | Default       | Description                                                                                          |
+| -------------- | ----------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
+| `id`           | `string`                                  | `$props.id()` | Stable id for the native button and pending announcement labelling.                                  |
+| `type`         | `'button' \| 'submit' \| 'reset'`         | `'button'`    | Native button type. While pending, `submit` is rendered as `button`.                                 |
+| `isPending`    | `boolean`                                 | `false`       | Keeps the button focusable while disabling press and hover behavior.                                 |
+| `isDisabled`   | `boolean`                                 | `false`       | Disables the native button.                                                                          |
+| `children`     | `Snippet<[ButtonRenderState]> \| Snippet` | `undefined`   | Optional renderer receiving the current interaction state.                                           |
+| `class`        | `string`                                  | `''`          | CSS class names applied to the button element.                                                       |
+| `...restProps` | `HTMLButtonAttributes`                    | `-`           | Additional native button attributes forwarded to the element, excluding reserved disabled semantics. |
+
+### Types
+
+Name: `ButtonRenderState`  
+Description: Render-state payload available to the `children` snippet.
+
+| Prop             | Type      | Default | Description                                                           |
+| ---------------- | --------- | ------- | --------------------------------------------------------------------- |
+| `isHovered`      | `boolean` | `false` | Whether the button is currently hovered by a mouse.                   |
+| `isPressed`      | `boolean` | `false` | Whether the button is currently being pressed. Cleared while pending. |
+| `isFocused`      | `boolean` | `false` | Whether the button currently holds DOM focus.                         |
+| `isFocusVisible` | `boolean` | `false` | Whether focus is visibly keyboard or virtual driven.                  |
+| `isDisabled`     | `boolean` | `false` | Whether the button is disabled.                                       |
+| `isPending`      | `boolean` | `false` | Whether the button is pending.                                        |
+
+```svelte
+<Button.Root type="submit" isPending={saving} aria-label="Save changes">
+	{#snippet children({ isPending, isPressed })}
+		<span class:opacity-0={isPending}>Save</span>
+		{#if isPending}
+			<ProgressCircle aria-label="Saving" isIndeterminate />
+		{/if}
+	{/snippet}
+</Button.Root>
+```

package/dist/button/root/button-root.svelte

@@ -0,0 +1,362 @@
+<script lang="ts">
+	import { untrack, type Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+	import { cn } from '../../utils/cn';
+
+	export type ButtonRenderState = {
+		isHovered: boolean;
+		isPressed: boolean;
+		isFocused: boolean;
+		isFocusVisible: boolean;
+		isDisabled: boolean;
+		isPending: boolean;
+	};
+
+	type ButtonRootProps = Omit<
+		HTMLButtonAttributes,
+		'children' | 'class' | 'disabled' | 'aria-disabled'
+	> & {
+		children?: Snippet<[ButtonRenderState]> | Snippet;
+		class?: string;
+		isPending?: boolean;
+		isDisabled?: boolean;
+		element?: HTMLButtonElement | null;
+		pressed?: boolean;
+	};
+
+	function composeEventHandlers<TEvent extends Event>(
+		internalHandler: ((event: TEvent) => void) | undefined,
+		externalHandler: ((event: TEvent) => void) | undefined,
+		options?: { skipExternalOnDefaultPrevented?: boolean }
+	): (event: TEvent) => void {
+		return (event: TEvent) => {
+			let preventDefaultCalled = false;
+			const originalPreventDefault = event.preventDefault.bind(event);
+			event.preventDefault = () => {
+				preventDefaultCalled = true;
+				originalPreventDefault();
+			};
+
+			internalHandler?.(event);
+			event.preventDefault = originalPreventDefault;
+
+			if (
+				options?.skipExternalOnDefaultPrevented &&
+				(event.defaultPrevented || preventDefaultCalled)
+			) {
+				return;
+			}
+
+			externalHandler?.(event);
+		};
+	}
+
+	const generatedId = $props.id();
+
+	let {
+		id,
+		type = 'button',
+		children,
+		class: className = '',
+		isPending = false,
+		isDisabled = false,
+		element = $bindable<HTMLButtonElement | null>(null),
+		pressed: pressedOverride,
+		onclick: onClickExternal,
+		onfocus: onFocusExternal,
+		onblur: onBlurExternal,
+		onkeydown: onKeyDownExternal,
+		onkeyup: onKeyUpExternal,
+		onpointerdown: onPointerDownExternal,
+		onpointerup: onPointerUpExternal,
+		onpointercancel: onPointerCancelExternal,
+		onpointerenter: onPointerEnterExternal,
+		onpointerleave: onPointerLeaveExternal,
+		onmousedown: onMouseDownExternal,
+		onmouseup: onMouseUpExternal,
+		onmouseenter: onMouseEnterExternal,
+		onmouseleave: onMouseLeaveExternal,
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		...restProps
+	}: ButtonRootProps = $props();
+
+	const resolvedId = untrack(() => id) ?? generatedId;
+
+	let buttonRef: HTMLButtonElement | null = $state(null);
+	let hovered = $state(false);
+	let pressed = $state(false);
+	let focused = $state(false);
+	let focusVisible = $state(false);
+	let pressedKey: 'Enter' | 'Space' | null = $state(null);
+
+	const renderedType = $derived(type === 'submit' && isPending ? 'button' : type);
+	const renderedPressed = $derived(
+		pressedOverride !== undefined ? Boolean(pressedOverride) && !isPending : pressed && !isPending
+	);
+	const renderState = $derived.by<ButtonRenderState>(() => ({
+		isHovered: hovered,
+		isPressed: renderedPressed,
+		isFocused: focused,
+		isFocusVisible: focusVisible,
+		isDisabled,
+		isPending
+	}));
+	const pendingAnnouncement = $derived.by(() =>
+		isPending ? `${resolveButtonLabel() || 'Button'}, pending` : ''
+	);
+
+	function resolveReferencedLabel(ids: string | null | undefined): string {
+		if (!ids || !buttonRef) return '';
+		const ownerDocument = buttonRef.ownerDocument;
+		return ids
+			.split(/\s+/)
+			.map((token) => ownerDocument.getElementById(token)?.textContent?.trim() ?? '')
+			.filter(Boolean)
+			.join(' ')
+			.trim();
+	}
+
+	function resolveButtonLabel(): string {
+		const directLabel = ariaLabel?.trim();
+		if (directLabel) return directLabel;
+
+		const labelledByLabel = resolveReferencedLabel(ariaLabelledby);
+		if (labelledByLabel) return labelledByLabel;
+
+		if (!buttonRef) return '';
+
+		const liveRegion = buttonRef.querySelector('[data-button-live-region="true"]');
+		return Array.from(buttonRef.childNodes)
+			.filter((node) => node !== liveRegion)
+			.map((node) => node.textContent?.trim() ?? '')
+			.filter(Boolean)
+			.join(' ')
+			.trim();
+	}
+
+	function clearInteractionState() {
+		hovered = false;
+		pressed = false;
+		pressedKey = null;
+	}
+
+	$effect(() => {
+		element = buttonRef;
+	});
+
+	$effect(() => {
+		if (!isPending && !isDisabled) return;
+		clearInteractionState();
+		if (isDisabled) {
+			focusVisible = false;
+		}
+	});
+
+	function handlePointerDown(event: PointerEvent) {
+		trackInteractionModality(event, buttonRef);
+		focusVisible = false;
+
+		if (isDisabled || isPending) {
+			event.preventDefault();
+			clearInteractionState();
+			return;
+		}
+
+		if (event.button !== 0) return;
+		pressed = true;
+		pressedKey = null;
+	}
+
+	function handlePointerUp(event: PointerEvent) {
+		if (event.button !== 0) return;
+		pressed = false;
+		pressedKey = null;
+	}
+
+	function handlePointerCancel() {
+		pressed = false;
+		pressedKey = null;
+	}
+
+	function handlePointerEnter(event: PointerEvent) {
+		if (isDisabled || isPending) return;
+
+		if ((event.buttons & 1) === 1 && pressedKey === null) {
+			pressed = true;
+		}
+	}
+
+	function handlePointerLeave() {
+		if (pressedKey === null) {
+			pressed = false;
+		}
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, buttonRef);
+		focusVisible = false;
+
+		if (isDisabled || isPending) {
+			event.preventDefault();
+			clearInteractionState();
+			return;
+		}
+
+		if (event.button !== 0) return;
+		pressed = true;
+		pressedKey = null;
+	}
+
+	function handleMouseUp(event: MouseEvent) {
+		if (event.button !== 0) return;
+		if (pressedKey === null) {
+			pressed = false;
+		}
+	}
+
+	function handleMouseEnter() {
+		if (isDisabled || isPending) {
+			hovered = false;
+			return;
+		}
+
+		hovered = true;
+	}
+
+	function handleMouseLeave() {
+		hovered = false;
+	}
+
+	function handleFocus() {
+		focused = true;
+		focusVisible = shouldShowFocusVisible(buttonRef);
+	}
+
+	function handleBlur() {
+		focused = false;
+		focusVisible = false;
+		clearInteractionState();
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		const key =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+
+		if (!key) return;
+
+		trackInteractionModality(event, buttonRef);
+		focusVisible = focused ? true : shouldShowFocusVisible(buttonRef);
+
+		if (isDisabled || isPending) {
+			event.preventDefault();
+			clearInteractionState();
+			return;
+		}
+
+		if (event.repeat && pressed && pressedKey === key) return;
+
+		pressed = true;
+		pressedKey = key;
+	}
+
+	function handleKeyUp(event: KeyboardEvent) {
+		const key =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+
+		if (!key) return;
+
+		trackInteractionModality(event, buttonRef);
+		focusVisible = focused ? true : shouldShowFocusVisible(buttonRef);
+
+		if (isDisabled || isPending) {
+			event.preventDefault();
+			clearInteractionState();
+			return;
+		}
+
+		if (pressedKey === key) {
+			pressed = false;
+			pressedKey = null;
+		}
+	}
+
+	function handleClick(event: MouseEvent) {
+		if (event.detail > 0) {
+			trackInteractionModality(event, buttonRef);
+		}
+
+		if (isPending) {
+			event.preventDefault();
+			clearInteractionState();
+		}
+	}
+</script>
+
+<button
+	{...restProps}
+	bind:this={buttonRef}
+	id={resolvedId}
+	type={renderedType}
+	disabled={isDisabled}
+	aria-label={ariaLabel}
+	aria-labelledby={ariaLabelledby}
+	aria-disabled={isPending ? 'true' : undefined}
+	data-button-root="true"
+	data-disabled={isDisabled || undefined}
+	data-pending={isPending || undefined}
+	data-hovered={hovered || undefined}
+	data-pressed={renderedPressed || undefined}
+	data-focused={focused || undefined}
+	data-focus-visible={focusVisible || undefined}
+	class={cn('outline-none', className)}
+	onclick={composeEventHandlers(handleClick, onClickExternal ?? undefined, {
+		skipExternalOnDefaultPrevented: true
+	})}
+	onfocus={composeEventHandlers(handleFocus, onFocusExternal ?? undefined)}
+	onblur={composeEventHandlers(handleBlur, onBlurExternal ?? undefined)}
+	onkeydown={composeEventHandlers(handleKeyDown, onKeyDownExternal ?? undefined, {
+		skipExternalOnDefaultPrevented: true
+	})}
+	onkeyup={composeEventHandlers(handleKeyUp, onKeyUpExternal ?? undefined, {
+		skipExternalOnDefaultPrevented: true
+	})}
+	onpointerdown={composeEventHandlers(handlePointerDown, onPointerDownExternal ?? undefined, {
+		skipExternalOnDefaultPrevented: true
+	})}
+	onpointerup={composeEventHandlers(handlePointerUp, onPointerUpExternal ?? undefined)}
+	onpointercancel={composeEventHandlers(handlePointerCancel, onPointerCancelExternal ?? undefined)}
+	onpointerenter={composeEventHandlers(handlePointerEnter, onPointerEnterExternal ?? undefined)}
+	onpointerleave={composeEventHandlers(handlePointerLeave, onPointerLeaveExternal ?? undefined)}
+	onmousedown={composeEventHandlers(handleMouseDown, onMouseDownExternal ?? undefined, {
+		skipExternalOnDefaultPrevented: true
+	})}
+	onmouseup={composeEventHandlers(handleMouseUp, onMouseUpExternal ?? undefined)}
+	onmouseenter={composeEventHandlers(handleMouseEnter, onMouseEnterExternal ?? undefined)}
+	onmouseleave={composeEventHandlers(handleMouseLeave, onMouseLeaveExternal ?? undefined)}
+>
+	{#if children}
+		{@render (children as Snippet<[ButtonRenderState]>)(renderState)}
+	{/if}
+
+	<span
+		data-button-live-region="true"
+		role="status"
+		aria-live="polite"
+		aria-atomic="true"
+		style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;"
+		>{pendingAnnouncement}</span
+	>
+</button>

package/dist/button/root/button-root.svelte.d.ts

@@ -0,0 +1,21 @@
+import { type Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+export type ButtonRenderState = {
+    isHovered: boolean;
+    isPressed: boolean;
+    isFocused: boolean;
+    isFocusVisible: boolean;
+    isDisabled: boolean;
+    isPending: boolean;
+};
+type ButtonRootProps = Omit<HTMLButtonAttributes, 'children' | 'class' | 'disabled' | 'aria-disabled'> & {
+    children?: Snippet<[ButtonRenderState]> | Snippet;
+    class?: string;
+    isPending?: boolean;
+    isDisabled?: boolean;
+    element?: HTMLButtonElement | null;
+    pressed?: boolean;
+};
+declare const ButtonRoot: import("svelte").Component<ButtonRootProps, {}, "element">;
+type ButtonRoot = ReturnType<typeof ButtonRoot>;
+export default ButtonRoot;