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

package/dist/timepicker/popover/README.md

@@ -0,0 +1,20 @@
+# TimePicker Popover
+
+## API reference
+
+### TimePicker.Popover
+
+Name: `TimePicker.Popover`  
+Description: Popover content wrapper integrated with `TimePicker.Root` controlled open state and trigger reference.
+
+| Prop           | Type                                     | Default         | Description                                                      |
+| -------------- | ---------------------------------------- | --------------- | ---------------------------------------------------------------- |
+| `aria-label`   | `string`                                 | `'Time picker'` | Accessible name for the popover dialog content.                  |
+| `initialFocus` | `() => HTMLElement \| null \| undefined` | `first wheel`   | Optional initial focus resolver for popover open.                |
+| `class`        | `string`                                 | `''`            | CSS class names applied to popover content.                      |
+| `...restProps` | `ComponentProps<typeof Popover.Content>` | `-`             | Forwarded popover content props, excluding root-controlled keys. |
+
+### Notes
+
+Name: Root-controlled props  
+Description: `open`, `triggerRef`, `onOpenChange`, and `id` are controlled by `TimePicker.Root` and ignored when passed to this part.

package/dist/timepicker/popover/time-picker-popover-unsafe-props-test.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import TimePicker from '../index';
+
+	let value = $state<string | null>('14:30');
+	let open = $state(true);
+</script>
+
+<TimePicker.Root bind:value bind:open>
+	<TimePicker.Input aria-label="Time input">
+		{#snippet children(segment)}
+			<TimePicker.Segment {segment} />
+		{/snippet}
+	</TimePicker.Input>
+	<TimePicker.Trigger>Open time picker</TimePicker.Trigger>
+	<TimePicker.Popover>
+		<TimePicker.Clock class="flex">
+			{#snippet column(col)}
+				<TimePicker.WheelColumn type={col.type} class="h-44" />
+			{/snippet}
+		</TimePicker.Clock>
+	</TimePicker.Popover>
+</TimePicker.Root>

package/dist/timepicker/popover/time-picker-popover-unsafe-props-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const TimePickerPopoverUnsafePropsTest: import("svelte").Component<Record<string, never>, {}, "">;
+type TimePickerPopoverUnsafePropsTest = ReturnType<typeof TimePickerPopoverUnsafePropsTest>;
+export default TimePickerPopoverUnsafePropsTest;

package/dist/timepicker/popover/time-picker-popover.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+	import type { ComponentProps } from 'svelte';
+	import { useTimePickerContext } from '../root/context';
+	import { Popover } from '../../popover';
+	import type { PopoverOpenChangeDetails } from '../../popover/root/context';
+	import { composeEventHandlers, sanitizeTimePickerProps } from '../internal/strict-props';
+	import { trackInteractionModality } from '../../primitives/input-modality';
+
+	type ForbiddenPopoverProp = 'open' | 'triggerRef' | 'onOpenChange' | 'id';
+	type TimePickerPopoverProps = Omit<ComponentProps<typeof Popover.Content>, ForbiddenPopoverProp>;
+
+	const forbiddenPopoverProps: ForbiddenPopoverProp[] = [
+		'open',
+		'triggerRef',
+		'onOpenChange',
+		'id'
+	];
+
+	let {
+		class: className = '',
+		children,
+		'aria-label': ariaLabel = 'Time picker',
+		initialFocus,
+		onmousedown: onMouseDownExternal,
+		onkeydowncapture: onKeydownCaptureExternal,
+		...unsafeRestProps
+	}: TimePickerPopoverProps = $props();
+
+	const timePicker = useTimePickerContext();
+	const dialogId = `${timePicker.id}-popover`;
+	const restProps = $derived.by(
+		() =>
+			sanitizeTimePickerProps(
+				'Popover',
+				unsafeRestProps as Record<string, unknown>,
+				forbiddenPopoverProps
+			) as Omit<ComponentProps<typeof Popover.Content>, ForbiddenPopoverProp>
+	);
+
+	const resolvedInitialFocus = $derived.by(() => {
+		if (typeof initialFocus === 'function') {
+			return () => initialFocus() ?? resolveInitialWheelFocus();
+		}
+		if (initialFocus !== undefined) {
+			return initialFocus;
+		}
+		return resolveInitialWheelFocus;
+	});
+
+	function resolveInitialWheelFocus(): HTMLElement | null {
+		const dialog = document.getElementById(dialogId);
+		const firstSpinbutton = dialog?.querySelector<HTMLElement>('[role="spinbutton"]');
+		return firstSpinbutton ?? null;
+	}
+
+	function handleOpenChange(nextOpen: boolean, details: PopoverOpenChangeDetails) {
+		timePicker.onOpenChange(nextOpen, details);
+	}
+
+	function handlePointerDown(event: MouseEvent) {
+		trackInteractionModality(event);
+	}
+
+	function handleKeydown(event: KeyboardEvent) {
+		trackInteractionModality(event);
+	}
+</script>
+
+<Popover.Root
+	open={timePicker.open}
+	triggerRef={timePicker.triggerRef}
+	onOpenChange={handleOpenChange}
+>
+	<Popover.Content
+		id={dialogId}
+		class={className}
+		aria-label={ariaLabel}
+		onmousedown={composeEventHandlers(handlePointerDown, onMouseDownExternal ?? undefined)}
+		onkeydowncapture={composeEventHandlers(handleKeydown, onKeydownCaptureExternal ?? undefined, {
+			skipExternalOnDefaultPrevented: true
+		})}
+		initialFocus={resolvedInitialFocus}
+		{...restProps}
+	>
+		{#if children}
+			{@render children()}
+		{/if}
+	</Popover.Content>
+</Popover.Root>

package/dist/timepicker/popover/time-picker-popover.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentProps } from 'svelte';
+import { Popover } from '../../popover';
+type ForbiddenPopoverProp = 'open' | 'triggerRef' | 'onOpenChange' | 'id';
+type TimePickerPopoverProps = Omit<ComponentProps<typeof Popover.Content>, ForbiddenPopoverProp>;
+declare const TimePickerPopover: import("svelte").Component<TimePickerPopoverProps, {}, "">;
+type TimePickerPopover = ReturnType<typeof TimePickerPopover>;
+export default TimePickerPopover;

package/dist/timepicker/root/README.md

@@ -0,0 +1,42 @@
+# TimePicker Root
+
+## API reference
+
+### TimePicker.Root
+
+Name: `TimePicker.Root`  
+Description: State container for segmented time input, popover lifecycle, wheel selection, and value validation.
+
+| Prop           | Type                               | Default     | Description                                                  |
+| -------------- | ---------------------------------- | ----------- | ------------------------------------------------------------ |
+| `value`        | `string \| null`                   | `bindable`  | Controlled time value (`HH:mm` or `HH:mm:ss`).               |
+| `defaultValue` | `string \| null`                   | `undefined` | Initial value for uncontrolled mode.                         |
+| `onChange`     | `(value: string \| null) => void`  | `undefined` | Called when committed value changes.                         |
+| `open`         | `boolean`                          | `bindable`  | Controlled open state for popover panel.                     |
+| `defaultOpen`  | `boolean`                          | `false`     | Initial open state in uncontrolled mode.                     |
+| `onOpenChange` | `(open: boolean, details) => void` | `undefined` | Called on open-state transitions (supports cancellation).    |
+| `hourCycle`    | `12 \| 24`                         | `locale`    | Hour cycle used for rendering and parsing.                   |
+| `granularity`  | `'hour' \| 'minute' \| 'second'`   | `'minute'`  | Controls visible segments and wheel columns.                 |
+| `hourStep`     | `number`                           | `1`         | Hour increment for segment and wheel interactions.           |
+| `minuteStep`   | `number`                           | `1`         | Minute increment for segment and wheel interactions.         |
+| `secondStep`   | `number`                           | `1`         | Second increment for segment and wheel interactions.         |
+| `minValue`     | `string`                           | `undefined` | Optional lower bound for valid values.                       |
+| `maxValue`     | `string`                           | `undefined` | Optional upper bound for valid values.                       |
+| `isDisabled`   | `boolean`                          | `false`     | Disables user interaction.                                   |
+| `isReadOnly`   | `boolean`                          | `false`     | Prevents value changes while keeping focus/navigation.       |
+| `isRequired`   | `boolean`                          | `false`     | Propagates required state to input accessibility attributes. |
+| `children`     | `Snippet`                          | `undefined` | Composed `TimePicker` parts.                                 |
+| `class`        | `string`                           | `''`        | CSS class names for the root element.                        |
+| `aria-label`   | `string`                           | `undefined` | Accessible label for the root wrapper.                       |
+
+### Context utilities
+
+Name: `setTimePickerContext` / `getTimePickerContext` / `useTimePickerContext`  
+Description: Context helpers for internal/public part composition.
+
+| Prop                   | Type                                   | Default | Description                                         |
+| ---------------------- | -------------------------------------- | ------- | --------------------------------------------------- |
+| `setTimePickerContext` | `(ctx: TimePickerContext) => void`     | `-`     | Publishes root context.                             |
+| `getTimePickerContext` | `() => TimePickerContext \| undefined` | `-`     | Reads context when available.                       |
+| `useTimePickerContext` | `() => TimePickerContext`              | `-`     | Reads context and throws outside `TimePicker.Root`. |
+| `TimePickerContext`    | `type`                                 | `-`     | Full context contract used by all child parts.      |

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

@@ -0,0 +1,51 @@
+import type { TimePickerEditableSegmentType, TimePickerGranularity, TimePickerHourCycle, TimePickerSegmentPart, TimePickerSegmentType, TimePickerTimeValue } from './time-utils';
+import type { PopoverChangeReason, PopoverOpenChangeDetails } from '../../popover/root/context';
+export type TimePickerOpenChangeReason = PopoverChangeReason;
+export type TimePickerOpenChangeDetails = PopoverOpenChangeDetails;
+export type TimePickerContext = {
+    id: string;
+    isDisabled: boolean;
+    isReadOnly: boolean;
+    isRequired: boolean;
+    granularity: TimePickerGranularity;
+    hourCycle: TimePickerHourCycle;
+    open: boolean;
+    focusVisible: boolean;
+    focusWithin: boolean;
+    isInvalidDraft: boolean;
+    value: TimePickerTimeValue | null;
+    locale: string;
+    triggerRef: HTMLElement | null;
+    activeSegment: Exclude<TimePickerSegmentType, 'literal'> | null;
+    setTriggerRef: (element: HTMLElement | null) => void;
+    setFocusVisible: (visible: boolean) => void;
+    syncFocusWithin: () => void;
+    setActiveSegment: (segment: Exclude<TimePickerSegmentType, 'literal'> | null) => void;
+    openPopover: (reason?: TimePickerOpenChangeReason, event?: Event) => void;
+    closePopover: (reason?: TimePickerOpenChangeReason, event?: Event) => void;
+    togglePopover: (reason?: TimePickerOpenChangeReason, event?: Event) => void;
+    onOpenChange: (open: boolean, details: TimePickerOpenChangeDetails) => void;
+    setValue: (nextValue: TimePickerTimeValue | null) => void;
+    getSegments: () => TimePickerSegmentPart[];
+    getSegmentValue: (type: Exclude<TimePickerSegmentType, 'literal'>) => string;
+    setSegmentValue: (type: Exclude<TimePickerSegmentType, 'literal'>, nextValue: string) => void;
+    typeSegmentDigit: (type: Exclude<TimePickerSegmentType, 'literal'>, digit: string) => boolean;
+    adjustSegmentValue: (type: Exclude<TimePickerSegmentType, 'literal'>, step: number) => void;
+    getSegmentLabel: (type: TimePickerEditableSegmentType) => string;
+    registerSegmentRef: (type: TimePickerEditableSegmentType, element: HTMLElement | null) => void;
+    focusNextPlaceholderOrLastSegment: () => boolean;
+    focusNextSegment: (type: TimePickerEditableSegmentType) => boolean;
+    focusPreviousSegment: (type: TimePickerEditableSegmentType) => boolean;
+    focusLastSegment: () => boolean;
+    selectWheelValue: (type: TimePickerEditableSegmentType, value: string) => void;
+    getSelectedWheelValue: (type: TimePickerEditableSegmentType) => string | null;
+    getWheelOptions: (type: TimePickerEditableSegmentType) => Array<{
+        value: string;
+        label: string;
+        disabled: boolean;
+    }>;
+};
+export declare function setTimePickerContext(context: TimePickerContext): void;
+export declare function getTimePickerContext(): TimePickerContext | undefined;
+export declare function useTimePickerContext(): TimePickerContext;
+export type { TimePickerSegmentPart, TimePickerSegmentType, TimePickerEditableSegmentType };

package/dist/timepicker/root/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('time-picker');
+export function setTimePickerContext(context) {
+    setContext(KEY, context);
+}
+export function getTimePickerContext() {
+    return getContext(KEY);
+}
+export function useTimePickerContext() {
+    const context = getTimePickerContext();
+    if (!context) {
+        throw new Error('TimePicker components must be used within TimePicker.Root.');
+    }
+    return context;
+}

package/dist/timepicker/root/time-picker-12h-test.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { LocaleProvider } from '../../locale-provider';
+	import TimePicker from '../index';
+
+	let value = $state<string | null>('14:30');
+</script>
+
+<LocaleProvider locale="en-US">
+	<TimePicker.Root bind:value hourCycle={12}>
+		<TimePicker.Input aria-label="Time input">
+			{#snippet children(segment)}
+				<TimePicker.Segment {segment} />
+			{/snippet}
+		</TimePicker.Input>
+		<TimePicker.Trigger>Open time picker</TimePicker.Trigger>
+		<TimePicker.Popover>
+			<TimePicker.Clock />
+		</TimePicker.Popover>
+	</TimePicker.Root>
+</LocaleProvider>
+
+<p data-testid="bind-value">{value}</p>

package/dist/timepicker/root/time-picker-12h-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const TimePicker12hTest: import("svelte").Component<Record<string, never>, {}, "">;
+type TimePicker12hTest = ReturnType<typeof TimePicker12hTest>;
+export default TimePicker12hTest;

package/dist/timepicker/root/time-picker-bindable-test.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import TimePicker from '../index';
+
+	let value = $state<string | null | undefined>('14:30');
+	let open = $state(false);
+</script>
+
+<TimePicker.Root bind:value bind:open hourCycle={24}>
+	<TimePicker.Input aria-label="Time input">
+		{#snippet children(segment)}
+			<TimePicker.Segment {segment} />
+		{/snippet}
+	</TimePicker.Input>
+	<TimePicker.Trigger>Open time picker</TimePicker.Trigger>
+	<TimePicker.Popover>
+		<TimePicker.Clock />
+	</TimePicker.Popover>
+</TimePicker.Root>
+
+<p data-testid="bind-value">{value}</p>
+<p data-testid="bind-open">{String(open)}</p>
+<button type="button" data-testid="clear-undefined" onclick={() => (value = undefined)}
+	>Clear undefined</button
+>
+<button type="button" data-testid="clear-null" onclick={() => (value = null)}>Clear null</button>

package/dist/timepicker/root/time-picker-bindable-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const TimePickerBindableTest: import("svelte").Component<Record<string, never>, {}, "">;
+type TimePickerBindableTest = ReturnType<typeof TimePickerBindableTest>;
+export default TimePickerBindableTest;

package/dist/timepicker/root/time-picker-empty-test.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+	import TimePicker from '../index';
+
+	let value = $state<string | null>(null);
+</script>
+
+<TimePicker.Root bind:value hourCycle={24}>
+	<TimePicker.Input aria-label="Time input">
+		{#snippet children(segment)}
+			<TimePicker.Segment {segment} />
+		{/snippet}
+	</TimePicker.Input>
+	<TimePicker.Trigger>Open time picker</TimePicker.Trigger>
+	<TimePicker.Popover>
+		<TimePicker.Clock />
+	</TimePicker.Popover>
+</TimePicker.Root>
+
+<p data-testid="bind-value">{value}</p>
+<button type="button" data-testid="outside-button">Outside</button>

package/dist/timepicker/root/time-picker-empty-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const TimePickerEmptyTest: import("svelte").Component<Record<string, never>, {}, "">;
+type TimePickerEmptyTest = ReturnType<typeof TimePickerEmptyTest>;
+export default TimePickerEmptyTest;