@human-kit/svelte-components 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/checkbox/root/checkbox-root.svelte

@@ -0,0 +1,361 @@
+<script lang="ts">
+	import { untrack, type Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+	import { cn } from '../../utils/cn';
+	import { setCheckboxContext, type CheckboxContext, type CheckboxState } from './context';
+
+	type CheckboxRootProps = Omit<
+		HTMLAttributes<HTMLSpanElement>,
+		| 'children'
+		| 'class'
+		| 'id'
+		| 'role'
+		| 'tabindex'
+		| 'aria-checked'
+		| 'aria-disabled'
+		| 'aria-readonly'
+		| 'aria-required'
+		| 'onclick'
+		| 'onkeydown'
+		| 'value'
+	> & {
+		id?: string;
+		name?: string;
+		value?: string;
+		isChecked?: boolean;
+		defaultChecked?: boolean;
+		isIndeterminate?: boolean;
+		defaultIndeterminate?: boolean;
+		onCheckedChange?: (checked: boolean) => void;
+		onIndeterminateChange?: (indeterminate: boolean) => void;
+		isDisabled?: boolean;
+		isReadOnly?: boolean;
+		required?: boolean;
+		children?: Snippet;
+		class?: string;
+		'aria-label'?: string;
+		'aria-labelledby'?: string;
+	};
+
+	function resolveState(isChecked: boolean, isIndeterminate: boolean): CheckboxState {
+		if (isIndeterminate) return 'indeterminate';
+		return isChecked ? 'checked' : 'unchecked';
+	}
+
+	function getNextState(currentState: CheckboxState): CheckboxState {
+		if (currentState === 'indeterminate') return 'checked';
+		if (currentState === 'checked') return 'unchecked';
+		return 'checked';
+	}
+
+	const generatedId = $props.id();
+
+	let {
+		id,
+		name,
+		value = 'on',
+		isChecked = $bindable(),
+		defaultChecked = false,
+		isIndeterminate = $bindable(),
+		defaultIndeterminate = false,
+		onCheckedChange,
+		onIndeterminateChange,
+		isDisabled = false,
+		isReadOnly = false,
+		required = false,
+		children,
+		class: className = '',
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		...restProps
+	}: CheckboxRootProps = $props();
+
+	const instanceId = untrack(() => id) ?? generatedId;
+	const inputId = instanceId;
+	const rootId = `${instanceId}-root`;
+
+	const initialChecked = untrack(() => isChecked ?? defaultChecked);
+	const initialIndeterminate = untrack(() => isIndeterminate ?? defaultIndeterminate);
+	const initialState = resolveState(initialChecked, initialIndeterminate);
+
+	let checkedInternal = $state(initialState === 'checked');
+	let indeterminateInternal = $state(initialState === 'indeterminate');
+	let pressed = $state(false);
+	let pressedKey: 'Enter' | 'Space' | null = $state(null);
+	let focused = $state(false);
+	let focusVisible = $state(false);
+	let rootRef: HTMLSpanElement | null = $state(null);
+	let inputRef: HTMLInputElement | null = $state(null);
+
+	if (untrack(() => isChecked) === undefined) {
+		isChecked = initialState === 'checked';
+	}
+
+	if (untrack(() => isIndeterminate) === undefined) {
+		isIndeterminate = initialState === 'indeterminate';
+	}
+
+	const isCheckedControlled = $derived(isChecked !== undefined);
+	const isIndeterminateControlled = $derived(isIndeterminate !== undefined);
+
+	const currentState = $derived.by(() =>
+		resolveState(
+			isCheckedControlled ? Boolean(isChecked) : checkedInternal,
+			isIndeterminateControlled ? Boolean(isIndeterminate) : indeterminateInternal
+		)
+	);
+
+	const currentChecked = $derived(currentState === 'checked');
+	const currentIndeterminate = $derived(currentState === 'indeterminate');
+	const currentUnchecked = $derived(currentState === 'unchecked');
+
+	function publishState(nextState: CheckboxState, event?: Event) {
+		const nextChecked = nextState === 'checked';
+		const nextIndeterminate = nextState === 'indeterminate';
+		const previousChecked = currentChecked;
+		const previousIndeterminate = currentIndeterminate;
+
+		if (!isCheckedControlled) {
+			checkedInternal = nextChecked;
+		}
+
+		if (!isIndeterminateControlled) {
+			indeterminateInternal = nextIndeterminate;
+		}
+
+		isChecked = nextChecked;
+		isIndeterminate = nextIndeterminate;
+
+		if (nextChecked !== previousChecked) {
+			onCheckedChange?.(nextChecked);
+		}
+
+		if (nextIndeterminate !== previousIndeterminate) {
+			onIndeterminateChange?.(nextIndeterminate);
+		}
+
+		if (event && rootRef && document.activeElement !== rootRef) {
+			rootRef.focus();
+		}
+	}
+
+	function setState(nextState: CheckboxState, event?: Event) {
+		if (isDisabled || isReadOnly) return;
+		publishState(nextState, event);
+	}
+
+	function toggle(event?: Event) {
+		setState(getNextState(currentState), event);
+	}
+
+	function requestNativeToggle(event?: Event) {
+		if (isDisabled || isReadOnly) return;
+		if (!inputRef) {
+			toggle(event);
+			return;
+		}
+
+		inputRef.click();
+	}
+
+	function handleClick(event: MouseEvent) {
+		trackInteractionModality(event, rootRef);
+
+		if (event.defaultPrevented) return;
+		if (isDisabled || isReadOnly) {
+			event.preventDefault();
+			return;
+		}
+
+		event.preventDefault();
+		requestNativeToggle(event);
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		if (event.defaultPrevented) return;
+		if (event.key !== ' ' && event.key !== 'Spacebar' && event.key !== 'Enter') return;
+
+		trackInteractionModality(event, rootRef);
+		if (focused) {
+			focusVisible = true;
+		} else {
+			focusVisible = shouldShowFocusVisible(rootRef);
+		}
+		event.preventDefault();
+
+		if (event.repeat && pressed) return;
+
+		pressed = true;
+		pressedKey = event.key === 'Enter' ? 'Enter' : 'Space';
+	}
+
+	function handleKeyUp(event: KeyboardEvent) {
+		if (event.defaultPrevented) return;
+
+		const releasedKey =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+		if (!releasedKey) return;
+
+		trackInteractionModality(event, rootRef);
+		if (focused) {
+			focusVisible = true;
+		} else {
+			focusVisible = shouldShowFocusVisible(rootRef);
+		}
+		event.preventDefault();
+
+		const shouldToggle = pressed && pressedKey === releasedKey;
+		pressed = false;
+		pressedKey = null;
+
+		if (!shouldToggle) return;
+		requestNativeToggle(event);
+	}
+
+	function handlePointerDown(event: PointerEvent | MouseEvent) {
+		trackInteractionModality(event, rootRef);
+		focusVisible = false;
+	}
+
+	function handleFocus() {
+		focused = true;
+		focusVisible = shouldShowFocusVisible(rootRef);
+	}
+
+	function handleBlur() {
+		focused = false;
+		focusVisible = false;
+		pressed = false;
+		pressedKey = null;
+	}
+
+	function handleInputChange(event: Event) {
+		const target = event.currentTarget;
+		if (!(target instanceof HTMLInputElement)) return;
+
+		const nextState = resolveState(target.checked, target.indeterminate);
+		publishState(nextState, event);
+	}
+
+	function handleInputFocus() {
+		rootRef?.focus();
+	}
+
+	function handleInputClick(event: MouseEvent) {
+		event.stopPropagation();
+	}
+
+	$effect(() => {
+		if (!inputRef) return;
+		inputRef.checked = currentChecked;
+		inputRef.indeterminate = currentIndeterminate;
+	});
+
+	setCheckboxContext({
+		get id() {
+			return rootId;
+		},
+		get inputId() {
+			return inputId;
+		},
+		get inputRef() {
+			return inputRef;
+		},
+		setInputRef(element) {
+			inputRef = element;
+		},
+		get state() {
+			return currentState;
+		},
+		get pressed() {
+			return pressed;
+		},
+		get isChecked() {
+			return currentChecked;
+		},
+		get isIndeterminate() {
+			return currentIndeterminate;
+		},
+		get isDisabled() {
+			return isDisabled;
+		},
+		get isReadOnly() {
+			return isReadOnly;
+		},
+		get required() {
+			return required;
+		},
+		get focused() {
+			return focused;
+		},
+		get focusVisible() {
+			return focusVisible;
+		},
+		toggle,
+		setState
+	} satisfies CheckboxContext);
+</script>
+
+<span
+	{...restProps}
+	bind:this={rootRef}
+	id={rootId}
+	role="checkbox"
+	tabindex={isDisabled ? undefined : 0}
+	aria-checked={currentIndeterminate ? 'mixed' : currentChecked ? 'true' : 'false'}
+	aria-disabled={isDisabled || undefined}
+	aria-readonly={isReadOnly || undefined}
+	aria-required={required || undefined}
+	aria-label={ariaLabel}
+	aria-labelledby={ariaLabelledby}
+	data-checkbox-root="true"
+	data-checked={currentChecked || undefined}
+	data-unchecked={currentUnchecked || undefined}
+	data-indeterminate={currentIndeterminate || undefined}
+	data-pressed={pressed || undefined}
+	data-disabled={isDisabled || undefined}
+	data-readonly={isReadOnly || undefined}
+	data-required={required || undefined}
+	data-focused={focused || undefined}
+	data-focus-visible={focusVisible || undefined}
+	onclick={handleClick}
+	onkeydown={handleKeyDown}
+	onkeyup={handleKeyUp}
+	onpointerdown={handlePointerDown}
+	onmousedown={handlePointerDown}
+	onfocus={handleFocus}
+	onblur={handleBlur}
+	class={cn(
+		'relative inline-flex shrink-0 items-center justify-center align-middle outline-none',
+		className
+	)}
+>
+	<input
+		bind:this={inputRef}
+		id={inputId}
+		tabindex={-1}
+		type="checkbox"
+		{name}
+		{value}
+		checked={currentChecked}
+		disabled={isDisabled}
+		{required}
+		readonly={isReadOnly}
+		aria-hidden="true"
+		data-checkbox-input="true"
+		onclick={handleInputClick}
+		onchange={handleInputChange}
+		onfocus={handleInputFocus}
+		style="position:absolute;inset:0;width:100%;height:100%;margin:0;padding:0;border:0;opacity:0;cursor:inherit;pointer-events:none;"
+	/>
+
+	{@render children?.()}
+</span>

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

@@ -0,0 +1,23 @@
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type CheckboxRootProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class' | 'id' | 'role' | 'tabindex' | 'aria-checked' | 'aria-disabled' | 'aria-readonly' | 'aria-required' | 'onclick' | 'onkeydown' | 'value'> & {
+    id?: string;
+    name?: string;
+    value?: string;
+    isChecked?: boolean;
+    defaultChecked?: boolean;
+    isIndeterminate?: boolean;
+    defaultIndeterminate?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    onIndeterminateChange?: (indeterminate: boolean) => void;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    required?: boolean;
+    children?: Snippet;
+    class?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+};
+declare const CheckboxRoot: import("svelte").Component<CheckboxRootProps, {}, "isChecked" | "isIndeterminate">;
+type CheckboxRoot = ReturnType<typeof CheckboxRoot>;
+export default CheckboxRoot;

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

@@ -0,0 +1,59 @@
+<script lang="ts">
+	import { Checkbox } from '../index';
+
+	type Props = {
+		id?: string;
+		name?: string;
+		value?: string;
+		isChecked?: boolean;
+		defaultChecked?: boolean;
+		isIndeterminate?: boolean;
+		defaultIndeterminate?: boolean;
+		isDisabled?: boolean;
+		isReadOnly?: boolean;
+		required?: boolean;
+		keepMounted?: boolean;
+		onCheckedChange?: (checked: boolean) => void;
+		onIndeterminateChange?: (indeterminate: boolean) => void;
+	};
+
+	let {
+		id,
+		name,
+		value = 'newsletter',
+		isChecked = $bindable(),
+		defaultChecked = false,
+		isIndeterminate = $bindable(),
+		defaultIndeterminate = false,
+		isDisabled = false,
+		isReadOnly = false,
+		required = false,
+		keepMounted = false,
+		onCheckedChange,
+		onIndeterminateChange
+	}: Props = $props();
+</script>
+
+<Checkbox.Root
+	{id}
+	{name}
+	{value}
+	bind:isChecked
+	{defaultChecked}
+	bind:isIndeterminate
+	{defaultIndeterminate}
+	{isDisabled}
+	{isReadOnly}
+	{required}
+	{onCheckedChange}
+	{onIndeterminateChange}
+	class="inline-flex h-5 w-5 items-center justify-center"
+	aria-label="Accept terms"
+>
+	<Checkbox.Indicator {keepMounted}>
+		<span data-checkbox-icon="true">icon</span>
+	</Checkbox.Indicator>
+</Checkbox.Root>
+
+<output data-checked-state>{String(isChecked ?? false)}</output>
+<output data-indeterminate-state>{String(isIndeterminate ?? false)}</output>

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

@@ -0,0 +1,18 @@
+type Props = {
+    id?: string;
+    name?: string;
+    value?: string;
+    isChecked?: boolean;
+    defaultChecked?: boolean;
+    isIndeterminate?: boolean;
+    defaultIndeterminate?: boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    required?: boolean;
+    keepMounted?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    onIndeterminateChange?: (indeterminate: boolean) => void;
+};
+declare const CheckboxTest: import("svelte").Component<Props, {}, "isChecked" | "isIndeterminate">;
+type CheckboxTest = ReturnType<typeof CheckboxTest>;
+export default CheckboxTest;

package/dist/checkbox/root/context.d.ts

@@ -0,0 +1,21 @@
+export type CheckboxState = 'checked' | 'unchecked' | 'indeterminate';
+export type CheckboxContext = {
+    id: string;
+    inputId: string;
+    inputRef: HTMLInputElement | null;
+    setInputRef: (element: HTMLInputElement | null) => void;
+    state: CheckboxState;
+    pressed: boolean;
+    isChecked: boolean;
+    isIndeterminate: boolean;
+    isDisabled: boolean;
+    isReadOnly: boolean;
+    required: boolean;
+    focused: boolean;
+    focusVisible: boolean;
+    toggle: (event?: Event) => void;
+    setState: (state: CheckboxState, event?: Event) => void;
+};
+export declare function setCheckboxContext(context: CheckboxContext): void;
+export declare function getCheckboxContext(): CheckboxContext | undefined;
+export declare function useCheckboxContext(): CheckboxContext;

package/dist/checkbox/root/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const CHECKBOX_CONTEXT_KEY = Symbol('checkbox');
+export function setCheckboxContext(context) {
+    setContext(CHECKBOX_CONTEXT_KEY, context);
+}
+export function getCheckboxContext() {
+    return getContext(CHECKBOX_CONTEXT_KEY);
+}
+export function useCheckboxContext() {
+    const context = getCheckboxContext();
+    if (!context) {
+        throw new Error('Checkbox components must be used within Checkbox.Root.');
+    }
+    return context;
+}

package/dist/clock/README.md

@@ -0,0 +1,75 @@
+# Clock
+
+## Description
+
+`Clock` provides a standalone wheel-based time picker with spinbutton columns for hour, minute, second, and day-period selection. It can be used independently or composed inside `TimePicker` via `TimePicker.Clock`.
+
+## Anatomy
+
+- `Clock.Root`
+- `Clock.Axis`
+- `Clock.WheelColumn`
+- `Clock.WheelItem`
+
+```svelte
+<Clock.Root value="14:30" granularity="minute" hourCycle={24} class="flex gap-2">
+	{#snippet column(col)}
+		<Clock.WheelColumn type={col.type} class="h-44 w-16">
+			{#snippet children(option)}
+				<Clock.WheelItem type={col.type} {option} class="..." />
+			{/snippet}
+		</Clock.WheelColumn>
+	{/snippet}
+	<Clock.Axis class="rounded-md ring-1 ring-inset" />
+</Clock.Root>
+```
+
+Default columns are rendered automatically when no `column` snippet is provided:
+
+```svelte
+<Clock.Root value="09:00" granularity="minute" hourCycle={24} />
+```
+
+## Root API
+
+- `value?: string | null` (`HH:mm` or `HH:mm:ss`)
+- `defaultValue?: string | null` (`HH:mm` or `HH:mm:ss`)
+- `onChange?: (value: string | null) => void`
+- `minValue?: string`
+- `maxValue?: string`
+- `hourCycle?: 12 | 24` (defaults to locale)
+- `granularity?: 'hour' | 'minute' | 'second'` (defaults to `'minute'`)
+- `hourStep?: number`
+- `minuteStep?: number`
+- `secondStep?: number`
+- `isDisabled?: boolean`
+- `column?: Snippet<[ClockColumnInfo]>` — custom per-column rendering
+- `children?: Snippet` — arbitrary children. When `column` is used, children render after columns (useful for overlays like `Clock.Axis`).
+- `class?: string`
+- `aria-label?: string`
+
+Visible columns are resolved automatically in stable order: `hour → minute? → second? → dayPeriod?`.
+
+## Wheel API
+
+- `Clock.Axis` renders a root-level visual overlay (for example, a central selection band) across all columns.
+- `Clock.WheelColumn` renders one wheel (`role="spinbutton"`) for one editable segment (`hour`, `minute`, `second`, or `dayPeriod`).
+- `Clock.WheelItem` is headless: it renders one item (`data-wheel-item`) with state attributes (`data-selected`, `data-disabled`, `data-centered`) and leaves all visual styling to consumers.
+- `ClockColumnInfo` shape:
+  - `type: 'hour' | 'minute' | 'second' | 'dayPeriod'`
+  - `label?: string`
+
+## Accessibility
+
+- Each wheel column exposes `role="spinbutton"` with `aria-valuenow`, `aria-valuetext`, `aria-valuemin`, and `aria-valuemax`.
+- `ArrowUp/ArrowDown`: change value by one step.
+- `ArrowLeft/ArrowRight`: move focus between columns.
+- `Home/End`: jump to first/last value in the column.
+
+## Notes
+
+- Locale is read from `LocaleProvider` when available.
+- Internally, values are normalized to 24-hour representation; 12-hour rendering only affects UI segments.
+- `granularity='hour'` emits `HH:00` values.
+- Min/max comparisons do not support midnight-wrapping ranges.
+- Wheel selection commits immediately on snap.

package/dist/clock/axis/README.md

@@ -0,0 +1,24 @@
+# Clock Axis
+
+## API reference
+
+### Clock.Axis
+
+Name: `Clock.Axis`  
+Description: Visual overlay band for `Clock.Root`; it is presentational (`aria-hidden`) and does not manage selection.
+
+| Prop           | Type                             | Default     | Description                                          |
+| -------------- | -------------------------------- | ----------- | ---------------------------------------------------- |
+| `height`       | `number`                         | `undefined` | Optional overlay height in pixels.                   |
+| `class`        | `string`                         | `''`        | CSS class names for the overlay element.             |
+| `style`        | `string`                         | `''`        | Inline styles merged with the optional height style. |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`         | Additional attributes forwarded to the overlay div.  |
+
+### Context utilities
+
+Name: `useClockContext`  
+Description: Ensures `Clock.Axis` is used within `Clock.Root`.
+
+| Prop              | Type                 | Default | Description                                      |
+| ----------------- | -------------------- | ------- | ------------------------------------------------ |
+| `useClockContext` | `() => ClockContext` | `-`     | Returns context and throws outside `Clock.Root`. |

package/dist/clock/axis/clock-axis.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { useClockContext } from '../root/context';
+
+	type ClockAxisProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+		class?: string;
+		height?: number;
+	};
+
+	let {
+		class: className = '',
+		height,
+		style: styleProp = '',
+		...restProps
+	}: ClockAxisProps = $props();
+
+	const resolvedStyle = $derived.by(() => {
+		const base = styleProp?.trim() ?? '';
+		if (height === undefined || !Number.isFinite(height) || height <= 0) {
+			return base.length > 0 ? base : undefined;
+		}
+		const axisHeight = `height:${height}px`;
+		if (base.length === 0) return axisHeight;
+		const withSemicolon = /;\s*$/.test(base) ? base : `${base};`;
+		return `${withSemicolon}${axisHeight}`;
+	});
+
+	useClockContext();
+</script>
+
+<div
+	aria-hidden="true"
+	data-clock-axis
+	class={`pointer-events-none absolute top-1/2 left-0 w-full -translate-y-1/2 ${className}`}
+	style={resolvedStyle}
+	{...restProps}
+></div>

package/dist/clock/axis/clock-axis.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLAttributes } from 'svelte/elements';
+type ClockAxisProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+    class?: string;
+    height?: number;
+};
+declare const ClockAxis: import("svelte").Component<ClockAxisProps, {}, "">;
+type ClockAxis = ReturnType<typeof ClockAxis>;
+export default ClockAxis;

package/dist/clock/hooks/use-wheel-scroll.svelte.d.ts

@@ -0,0 +1,16 @@
+export type WheelScrollBehavior = 'smooth' | 'instant';
+export type WheelScrollApi = {
+    scrollToIndex: (index: number, behavior?: WheelScrollBehavior, options?: {
+        silent?: boolean;
+    }) => void;
+    destroy: () => void;
+};
+/**
+ * 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 declare function useWheelScroll(container: HTMLElement, onSnap: (centeredIndex: number) => number | null | void): WheelScrollApi;