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

package/dist/clock/root/clock-root.svelte

@@ -0,0 +1,329 @@
+<script lang="ts">
+	import { untrack, type Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { useLocaleContextOptional } from '../../locale-provider/context';
+	import { setClockContext, type ClockContext } from './context';
+	import { resolveVisibleColumns, type ClockColumnInfo } from './resolve-visible-columns';
+	import { buildWheelOptions } from './wheel-options';
+	import ClockWheelColumn from '../wheel-column/clock-wheel-column.svelte';
+	import {
+		buildTimePartsFromDraft,
+		clampToStep,
+		createEmptyTimePickerDraft,
+		formatTimePickerValue,
+		getSegmentLabel,
+		isSegmentValueEmpty,
+		isTimeOutOfRange,
+		isValidTimePickerValue,
+		normalizeSegmentNumberInput,
+		toDraftFromTimeValue,
+		type TimePickerDraft,
+		type TimePickerEditableSegmentType,
+		type TimePickerGranularity,
+		type TimePickerHourCycle,
+		type TimePickerTimeValue
+	} from './time-utils';
+
+	type ClockRootProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+		id?: string;
+		value?: TimePickerTimeValue | null;
+		defaultValue?: TimePickerTimeValue | null;
+		onChange?: (value: TimePickerTimeValue | null) => void;
+		minValue?: TimePickerTimeValue;
+		maxValue?: TimePickerTimeValue;
+		hourCycle?: TimePickerHourCycle;
+		granularity?: TimePickerGranularity;
+		hourStep?: number;
+		minuteStep?: number;
+		secondStep?: number;
+		isDisabled?: boolean;
+		column?: Snippet<[ClockColumnInfo]>;
+		children?: Snippet;
+		class?: string;
+		'aria-label'?: string;
+	};
+
+	const generatedInstanceId = $props.id();
+
+	let {
+		id,
+		value = $bindable(),
+		defaultValue,
+		onChange,
+		minValue,
+		maxValue,
+		hourCycle,
+		granularity = 'minute',
+		hourStep = 1,
+		minuteStep = 1,
+		secondStep = 1,
+		isDisabled = false,
+		column: columnSnippet,
+		children,
+		class: className = '',
+		'aria-label': ariaLabel,
+		...restProps
+	}: ClockRootProps = $props();
+
+	function hasExplicitPositionClass(value: string): boolean {
+		return /(^|\s)(?:[\w-]+:)*(?:static|fixed|absolute|relative|sticky)(?:\s|$)/.test(value);
+	}
+
+	const resolvedClassName = $derived.by(() => {
+		const trimmed = className.trim();
+		if (trimmed.length === 0) return 'relative';
+		if (hasExplicitPositionClass(trimmed)) return trimmed;
+		return `${trimmed} relative`;
+	});
+
+	const instanceId = untrack(() => id) ?? generatedInstanceId;
+	const localeContext = useLocaleContextOptional();
+	const localeStore = localeContext?.locale;
+	const localeFromContext = $derived.by(() => {
+		if (!localeStore) return undefined;
+		return $localeStore;
+	});
+	const systemLocale = untrack(() => Intl.DateTimeFormat().resolvedOptions().locale);
+	const resolvedLocale = $derived(localeFromContext ?? systemLocale);
+	const resolvedHourCycle = $derived.by<TimePickerHourCycle>(() => {
+		if (hourCycle) return hourCycle;
+		const localeCycle = new Intl.DateTimeFormat(resolvedLocale, {
+			hour: 'numeric'
+		}).resolvedOptions().hourCycle;
+		return localeCycle === 'h11' || localeCycle === 'h12' ? 12 : 24;
+	});
+
+	const initialValueProp = untrack(() => value);
+	const initialDefaultValue = untrack(() =>
+		isValidTimePickerValue(defaultValue) ? defaultValue : null
+	);
+	const initialPropValue =
+		initialValueProp === undefined
+			? initialDefaultValue
+			: isValidTimePickerValue(initialValueProp)
+				? initialValueProp
+				: null;
+	const initialHourCycle = untrack<TimePickerHourCycle>(() => {
+		if (hourCycle) return hourCycle;
+		const localeCycle = new Intl.DateTimeFormat(resolvedLocale, {
+			hour: 'numeric'
+		}).resolvedOptions().hourCycle;
+		return localeCycle === 'h11' || localeCycle === 'h12' ? 12 : 24;
+	});
+
+	let valueInternal = $state<TimePickerTimeValue | null>(initialPropValue);
+	let lastPublishedValue = $state<TimePickerTimeValue | null>(initialPropValue);
+	let segmentDraft = $state<TimePickerDraft>(
+		initialPropValue
+			? toDraftFromTimeValue(initialPropValue, initialHourCycle)
+			: createEmptyTimePickerDraft()
+	);
+
+	if (initialValueProp === undefined) {
+		value = initialPropValue;
+	} else if (initialValueProp !== initialPropValue) {
+		value = initialPropValue;
+	}
+
+	$effect(() => {
+		const nextValue = value === undefined ? null : isValidTimePickerValue(value) ? value : null;
+		if (nextValue === lastPublishedValue) return;
+		publishCommittedValue(nextValue, false);
+		segmentDraft = nextValue
+			? toDraftFromTimeValue(nextValue, resolvedHourCycle)
+			: createEmptyTimePickerDraft();
+	});
+
+	const normalizedMinValue = $derived(isValidTimePickerValue(minValue) ? minValue : undefined);
+	const normalizedMaxValue = $derived(isValidTimePickerValue(maxValue) ? maxValue : undefined);
+
+	function publishCommittedValue(
+		nextValue: TimePickerTimeValue | null,
+		emitChange: boolean
+	): boolean {
+		const bindableValue = value === undefined ? valueInternal : value;
+		const normalizedBindableValue = isValidTimePickerValue(bindableValue) ? bindableValue : null;
+		const didInternalChange = valueInternal !== nextValue;
+		const didBindableChange = normalizedBindableValue !== nextValue;
+		if (!didInternalChange && !didBindableChange) return false;
+
+		valueInternal = nextValue;
+		lastPublishedValue = nextValue;
+		if (didBindableChange) {
+			value = nextValue;
+		}
+		if (emitChange && didInternalChange) {
+			onChange?.(nextValue);
+		}
+		return true;
+	}
+
+	function getSegmentValue(type: TimePickerEditableSegmentType): string {
+		if (type === 'hour') return segmentDraft.hour;
+		if (type === 'minute') return segmentDraft.minute;
+		if (type === 'second') return segmentDraft.second;
+		return segmentDraft.dayPeriod;
+	}
+
+	function setSegmentValue(type: TimePickerEditableSegmentType, nextValue: string) {
+		if (isDisabled) return;
+		if (type === 'dayPeriod') {
+			const normalized = nextValue.trim().toUpperCase();
+			if (normalized === '' || normalized === 'AM' || normalized === 'PM') {
+				segmentDraft.dayPeriod = normalized;
+			} else {
+				segmentDraft.dayPeriod = '';
+			}
+		} else {
+			const maxDigits = 2;
+			let normalized = normalizeSegmentNumberInput(nextValue, maxDigits);
+			if (normalized.length > 0) {
+				const numeric = Number(normalized);
+				if (type === 'hour') {
+					if (resolvedHourCycle === 12) {
+						normalized = String(clampToStep(numeric, Math.max(1, hourStep), 1, 12));
+					} else {
+						normalized = String(clampToStep(numeric, Math.max(1, hourStep), 0, 23));
+					}
+				}
+				if (type === 'minute') {
+					normalized = String(clampToStep(numeric, Math.max(1, minuteStep), 0, 59));
+				}
+				if (type === 'second') {
+					normalized = String(clampToStep(numeric, Math.max(1, secondStep), 0, 59));
+				}
+			}
+
+			if (type === 'hour') segmentDraft.hour = normalized;
+			if (type === 'minute') segmentDraft.minute = normalized;
+			if (type === 'second') segmentDraft.second = normalized;
+
+			if (resolvedHourCycle === 12 && isSegmentValueEmpty(segmentDraft.dayPeriod)) {
+				segmentDraft.dayPeriod = 'AM';
+			}
+		}
+
+		commitFromDraft();
+	}
+
+	function commitFromDraft() {
+		const nextParts = buildTimePartsFromDraft(segmentDraft, granularity, resolvedHourCycle);
+		if (!nextParts) {
+			publishCommittedValue(null, true);
+			return;
+		}
+
+		const candidateValue = formatTimePickerValue(nextParts, granularity);
+		if (isTimeOutOfRange(candidateValue, normalizedMinValue, normalizedMaxValue, granularity)) {
+			publishCommittedValue(null, true);
+			return;
+		}
+
+		publishCommittedValue(candidateValue, true);
+	}
+
+	function selectWheelValue(type: TimePickerEditableSegmentType, optionValue: string) {
+		if (isDisabled) return;
+
+		if (type === 'dayPeriod') {
+			setSegmentValue(type, optionValue.toUpperCase());
+		} else {
+			setSegmentValue(type, optionValue);
+		}
+	}
+
+	function getSelectedWheelValue(type: TimePickerEditableSegmentType): string | null {
+		const selected = getSegmentValue(type);
+		return selected.trim().length > 0 ? selected : null;
+	}
+
+	function getWheelOptions(type: TimePickerEditableSegmentType) {
+		const hasRangeBounds = normalizedMinValue !== undefined || normalizedMaxValue !== undefined;
+
+		const getCandidateFromPartial = (
+			partial: Partial<TimePickerDraft>
+		): TimePickerTimeValue | null => {
+			const candidateDraft: TimePickerDraft = {
+				hour: partial.hour ?? segmentDraft.hour,
+				minute: partial.minute ?? segmentDraft.minute,
+				second: partial.second ?? segmentDraft.second,
+				dayPeriod: partial.dayPeriod ?? segmentDraft.dayPeriod
+			};
+			const parts = buildTimePartsFromDraft(candidateDraft, granularity, resolvedHourCycle);
+			if (!parts) return null;
+			return formatTimePickerValue(parts, granularity);
+		};
+
+		return buildWheelOptions({
+			type,
+			granularity,
+			hourCycle: resolvedHourCycle,
+			hourStep,
+			minuteStep,
+			secondStep,
+			hasRangeBounds,
+			getCandidateFromPartial,
+			isOutOfRange: (candidate) =>
+				isTimeOutOfRange(candidate, normalizedMinValue, normalizedMaxValue, granularity)
+		});
+	}
+
+	function getSegmentLabelByType(type: TimePickerEditableSegmentType): string {
+		return getSegmentLabel(type, resolvedLocale);
+	}
+
+	const context: ClockContext = {
+		get id() {
+			return instanceId;
+		},
+		get locale() {
+			return resolvedLocale;
+		},
+		get isDisabled() {
+			return isDisabled;
+		},
+		get granularity() {
+			return granularity;
+		},
+		get hourCycle() {
+			return resolvedHourCycle;
+		},
+		get open() {
+			return true;
+		},
+		selectWheelValue,
+		getSelectedWheelValue,
+		getWheelOptions,
+		getSegmentLabel: getSegmentLabelByType
+	};
+
+	setClockContext(context);
+
+	const visibleColumns = $derived.by(() =>
+		resolveVisibleColumns(granularity, resolvedHourCycle, getSegmentLabelByType)
+	);
+</script>
+
+<div
+	id={instanceId}
+	class={resolvedClassName}
+	role="group"
+	aria-label={ariaLabel}
+	data-clock="true"
+	{...restProps}
+>
+	{#if columnSnippet}
+		{#each visibleColumns as col (col.type)}
+			{@render columnSnippet(col)}
+		{/each}
+		{#if children}
+			{@render children()}
+		{/if}
+	{:else if children}
+		{@render children()}
+	{:else}
+		{#each visibleColumns as col (col.type)}
+			<ClockWheelColumn type={col.type} />
+		{/each}
+	{/if}
+</div>

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

@@ -0,0 +1,25 @@
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type ClockColumnInfo } from './resolve-visible-columns';
+import { type TimePickerGranularity, type TimePickerHourCycle, type TimePickerTimeValue } from './time-utils';
+type ClockRootProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+    id?: string;
+    value?: TimePickerTimeValue | null;
+    defaultValue?: TimePickerTimeValue | null;
+    onChange?: (value: TimePickerTimeValue | null) => void;
+    minValue?: TimePickerTimeValue;
+    maxValue?: TimePickerTimeValue;
+    hourCycle?: TimePickerHourCycle;
+    granularity?: TimePickerGranularity;
+    hourStep?: number;
+    minuteStep?: number;
+    secondStep?: number;
+    isDisabled?: boolean;
+    column?: Snippet<[ClockColumnInfo]>;
+    children?: Snippet;
+    class?: string;
+    'aria-label'?: string;
+};
+declare const ClockRoot: import("svelte").Component<ClockRootProps, {}, "value">;
+type ClockRoot = ReturnType<typeof ClockRoot>;
+export default ClockRoot;

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

@@ -0,0 +1,22 @@
+import type { TimePickerEditableSegmentType, TimePickerGranularity, TimePickerHourCycle } from './time-utils';
+export type ClockContext = {
+    id: string;
+    locale: string;
+    isDisabled: boolean;
+    granularity: TimePickerGranularity;
+    hourCycle: TimePickerHourCycle;
+    /** Whether the clock is visible and should align scroll positions. */
+    open: boolean;
+    selectWheelValue: (type: TimePickerEditableSegmentType, value: string) => void;
+    getSelectedWheelValue: (type: TimePickerEditableSegmentType) => string | null;
+    getWheelOptions: (type: TimePickerEditableSegmentType) => Array<{
+        value: string;
+        label: string;
+        disabled: boolean;
+    }>;
+    getSegmentLabel: (type: TimePickerEditableSegmentType) => string;
+};
+export declare function setClockContext(context: ClockContext): void;
+export declare function getClockContext(): ClockContext | undefined;
+export declare function useClockContext(): ClockContext;
+export type { TimePickerEditableSegmentType as ClockEditableSegmentType };

package/dist/clock/root/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('clock');
+export function setClockContext(context) {
+    setContext(KEY, context);
+}
+export function getClockContext() {
+    return getContext(KEY);
+}
+export function useClockContext() {
+    const context = getClockContext();
+    if (!context) {
+        throw new Error('Clock components must be used within Clock.Root.');
+    }
+    return context;
+}

package/dist/clock/root/resolve-visible-columns.d.ts

@@ -0,0 +1,7 @@
+import type { ClockEditableSegmentType } from './context';
+import type { TimePickerGranularity, TimePickerHourCycle } from './time-utils';
+export type ClockColumnInfo = {
+    type: ClockEditableSegmentType;
+    label?: string;
+};
+export declare function resolveVisibleColumns(granularity: TimePickerGranularity, hourCycle: TimePickerHourCycle, getSegmentLabel?: (type: ClockEditableSegmentType) => string): ClockColumnInfo[];

package/dist/clock/root/resolve-visible-columns.js

@@ -0,0 +1,16 @@
+export function resolveVisibleColumns(granularity, hourCycle, getSegmentLabel) {
+    const columns = ['hour'];
+    if (granularity !== 'hour') {
+        columns.push('minute');
+    }
+    if (granularity === 'second') {
+        columns.push('second');
+    }
+    if (hourCycle === 12) {
+        columns.push('dayPeriod');
+    }
+    return columns.map((type) => ({
+        type,
+        label: getSegmentLabel?.(type)
+    }));
+}

package/dist/clock/root/time-utils.d.ts

@@ -0,0 +1,48 @@
+export type TimePickerGranularity = 'hour' | 'minute' | 'second';
+export type TimePickerHourCycle = 12 | 24;
+export type TimePickerTimeValue = string;
+export type TimePickerSegmentType = 'hour' | 'minute' | 'second' | 'dayPeriod' | 'literal';
+export type TimePickerEditableSegmentType = Exclude<TimePickerSegmentType, 'literal'>;
+export type TimePickerSegmentPart = {
+    type: TimePickerSegmentType;
+    text: string;
+    isPlaceholder: boolean;
+};
+export type TimePickerDraft = {
+    hour: string;
+    minute: string;
+    second: string;
+    dayPeriod: string;
+};
+export type TimeParts = {
+    hour: number;
+    minute: number;
+    second: number;
+};
+export declare function createEmptyTimePickerDraft(): TimePickerDraft;
+export declare function isValidTimePickerValue(value: unknown): value is TimePickerTimeValue;
+export declare function parseTimePickerValue(value: TimePickerTimeValue): TimeParts | null;
+export declare function formatTimePickerValue(parts: TimeParts, granularity: TimePickerGranularity): TimePickerTimeValue;
+export declare function toDraftFromTimeValue(value: TimePickerTimeValue, hourCycle: TimePickerHourCycle): TimePickerDraft;
+export declare function getRequiredSegments(granularity: TimePickerGranularity, hourCycle: TimePickerHourCycle): TimePickerEditableSegmentType[];
+export declare function normalizeSegmentNumberInput(value: string, maxDigits?: number): string;
+export declare function isSegmentValueEmpty(value: string | undefined): boolean;
+export declare function buildTimePartsFromDraft(draft: TimePickerDraft, granularity: TimePickerGranularity, hourCycle: TimePickerHourCycle): TimeParts | null;
+export declare function compareTimeParts(left: TimeParts, right: TimeParts): number;
+export declare function isTimeOutOfRange(value: TimePickerTimeValue, minValue: TimePickerTimeValue | undefined, maxValue: TimePickerTimeValue | undefined, granularity?: TimePickerGranularity): boolean;
+export declare function clampToStep(value: number, step: number, min: number, max: number): number;
+export declare function adjustSegmentWithStep(currentValue: string, type: Exclude<TimePickerSegmentType, 'literal' | 'dayPeriod'>, delta: number, options: {
+    hourCycle: TimePickerHourCycle;
+    hourStep: number;
+    minuteStep: number;
+    secondStep: number;
+}): string;
+export declare function buildTimePickerSegments(params: {
+    locale: string;
+    hourCycle: TimePickerHourCycle;
+    granularity: TimePickerGranularity;
+    draft: TimePickerDraft;
+    formatter?: Intl.DateTimeFormat;
+}): TimePickerSegmentPart[];
+export declare function getEditableSegmentOrder(segments: TimePickerSegmentPart[]): TimePickerEditableSegmentType[];
+export declare function getSegmentLabel(type: TimePickerEditableSegmentType, locale: string): string;