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

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

@@ -2,6 +2,7 @@ import type { CalendarSelectionMode, CalendarValue } from './context';
 type Props = {
     selectionMode?: CalendarSelectionMode;
     visibleMonths?: number;
+    showOutsideDays?: boolean;
     isDisabled?: boolean;
     isReadOnly?: boolean;
     defaultValue?: CalendarValue;

package/dist/calendar/root/calendar-root.svelte

@@ -34,6 +34,7 @@
 	type CalendarRootProps = {
 		selectionMode?: CalendarSelectionMode;
 		visibleMonths?: number;
+		showOutsideDays?: boolean;
 		isDateUnavailable?: (date: string) => boolean;
 		isDisabled?: boolean;
 		isReadOnly?: boolean;
@@ -62,6 +63,7 @@
 	let {
 		selectionMode = 'single',
 		visibleMonths = 1,
+		showOutsideDays = false,
 		isDateUnavailable,
 		isDisabled = false,
 		isReadOnly = false,
@@ -100,6 +102,7 @@
 		return {
 			selectionMode,
 			visibleMonths,
+			showOutsideDays,
 			locale: resolvedLocale,
 			isDateUnavailable,
 			isDisabled,

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

@@ -4,6 +4,7 @@ import { type CalendarDateValue } from './date-utils';
 type CalendarRootProps = {
     selectionMode?: CalendarSelectionMode;
     visibleMonths?: number;
+    showOutsideDays?: boolean;
     isDateUnavailable?: (date: string) => boolean;
     isDisabled?: boolean;
     isReadOnly?: boolean;

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

@@ -16,6 +16,7 @@ export type CalendarMonth = {
 export type CreateCalendarContextOptions<TSelectionMode extends CalendarSelectionMode = CalendarSelectionMode> = {
     selectionMode?: TSelectionMode;
     visibleMonths?: number;
+    showOutsideDays?: boolean;
     locale?: string;
     isDisabled?: boolean;
     isReadOnly?: boolean;
@@ -31,12 +32,14 @@ export type CalendarContext = {
     selectionMode: CalendarSelectionMode;
     firstDayOfWeek: number;
     visibleMonths: number;
+    showOutsideDays: boolean;
     isDisabled: boolean;
     isReadOnly: boolean;
     months: CalendarMonth[];
     selectedValue: CalendarDateValue | undefined;
     rangeValue: CalendarRangeValue | undefined;
     focusedValue: CalendarDateValue;
+    focusVisible: boolean;
     weekdayLabels: string[];
     headingLabel: string;
     isSelected: (date: CalendarDateValue) => boolean;
@@ -47,6 +50,7 @@ export type CalendarContext = {
     isDateDisabled: (date: CalendarDateValue) => boolean;
     isOutsideVisibleRange: (date: CalendarDateValue, monthIndex: number) => boolean;
     setFocusedValue: (date: CalendarDateValue) => void;
+    setFocusVisible: (visible: boolean) => void;
     setHoveredValue: (date: CalendarDateValue | undefined) => void;
     selectDate: (date: CalendarDateValue) => void;
     goToNextPage: () => void;

package/dist/calendar/root/context.js

@@ -2,9 +2,8 @@ import { getContext, setContext } from 'svelte';
 import { writable } from 'svelte/store';
 import { addDays, addMonths, buildMonthGrid, compareDates, formatCalendarDate, formatMonthHeading, getFirstDayOfWeek, getTodayUtcDate, getWeekdayLabels, isValidCalendarDateValue, parseCalendarDate, startOfMonth } from './date-utils';
 const KEY = Symbol('calendar');
-const MAX_FOCUS_SEARCH_DAYS = 370;
 export function createCalendarContext(options) {
-    let { selectionMode = 'single', visibleMonths = 1, locale = Intl.DateTimeFormat().resolvedOptions().locale, isDisabled = false, isReadOnly = false, isDateUnavailable, onChange } = options;
+    let { selectionMode = 'single', visibleMonths = 1, showOutsideDays = false, locale = Intl.DateTimeFormat().resolvedOptions().locale, isDisabled = false, isReadOnly = false, isDateUnavailable, onChange } = options;
     const { value, defaultValue } = options;
     function isRangeValue(valueToCheck) {
         if (!valueToCheck || typeof valueToCheck === 'string')
@@ -85,6 +84,7 @@ export function createCalendarContext(options) {
         initialRangeSelected?.end ??
         initialRangeSelected?.start ??
         fallbackToday;
+    let currentFocusVisible = false;
     let currentVisibleMonth = startOfMonth(parseCalendarDate(currentFocused) ?? getTodayUtcDate());
     let cachedMonths = [];
     let hasCachedMonths = false;
@@ -93,6 +93,7 @@ export function createCalendarContext(options) {
     let pendingRangePathCacheStart;
     let previousUnavailableFn = isDateUnavailable;
     let previousVisibleMonths = visibleMonths;
+    let previousShowOutsideDays = showOutsideDays;
     let previousLocale = locale;
     let cachedFirstDayOfWeek = getFirstDayOfWeek(locale);
     const layoutVersion = writable(0);
@@ -133,16 +134,19 @@ export function createCalendarContext(options) {
         let shouldNotifySelection = false;
         const nextSelectionMode = next.selectionMode ?? 'single';
         const nextVisibleMonths = Math.max(1, next.visibleMonths ?? 1);
+        const nextShowOutsideDays = next.showOutsideDays ?? false;
         const nextLocale = next.locale ?? Intl.DateTimeFormat().resolvedOptions().locale;
         const nextUnavailableFn = next.isDateUnavailable;
         if (nextUnavailableFn !== previousUnavailableFn ||
             nextVisibleMonths !== previousVisibleMonths ||
+            nextShowOutsideDays !== previousShowOutsideDays ||
             nextLocale !== previousLocale) {
             clearUnavailableCache();
             shouldNotifyLayout = true;
         }
         previousUnavailableFn = nextUnavailableFn;
         previousVisibleMonths = nextVisibleMonths;
+        previousShowOutsideDays = nextShowOutsideDays;
         previousLocale = nextLocale;
         if (selectionMode !== nextSelectionMode) {
             selectionMode = nextSelectionMode;
@@ -157,6 +161,7 @@ export function createCalendarContext(options) {
             shouldNotifyLayout = true;
         }
         visibleMonths = nextVisibleMonths;
+        showOutsideDays = nextShowOutsideDays;
         locale = nextLocale;
         cachedFirstDayOfWeek = getFirstDayOfWeek(locale);
         if (isDisabled !== (next.isDisabled ?? false) || isReadOnly !== (next.isReadOnly ?? false)) {
@@ -312,7 +317,7 @@ export function createCalendarContext(options) {
                 monthIndex,
                 monthStart,
                 heading: formatMonthHeading(monthStart, locale),
-                weeks: buildMonthGrid(monthStart, firstDayOfWeek)
+                weeks: buildMonthGrid(monthStart, firstDayOfWeek, showOutsideDays)
             };
         });
         hasCachedMonths = true;
@@ -359,7 +364,7 @@ export function createCalendarContext(options) {
         return result;
     }
     function isDateDisabled(date) {
-        if (isDisabled || isUnavailable(date))
+        if (isDisabled)
             return true;
         if (selectionMode === 'range' && currentRangeStart && !currentRangeEnd) {
             return !isPendingRangePathSelectable(date);
@@ -386,6 +391,12 @@ export function createCalendarContext(options) {
         }
         notifySelection();
     }
+    function setFocusVisible(visible) {
+        if (currentFocusVisible === visible)
+            return;
+        currentFocusVisible = visible;
+        notifySelection();
+    }
     function setHoveredValue(date) {
         if (selectionMode !== 'range')
             return;
@@ -514,7 +525,7 @@ export function createCalendarContext(options) {
             return undefined;
         const next = addDays(parsed, amount);
         const nextValue = formatCalendarDate(next);
-        const focusableValue = findFocusableDate(nextValue, amount);
+        const focusableValue = findFocusableDate(nextValue);
         if (!focusableValue)
             return undefined;
         setFocusedValue(focusableValue);
@@ -526,8 +537,7 @@ export function createCalendarContext(options) {
             return undefined;
         const next = addMonths(parsed, amount);
         const nextValue = formatCalendarDate(next);
-        const dayStep = amount >= 0 ? 1 : -1;
-        const focusableValue = findFocusableDate(nextValue, dayStep);
+        const focusableValue = findFocusableDate(nextValue);
         if (!focusableValue) {
             if (selectionMode === 'range' && currentRangeStart && !currentRangeEnd) {
                 return moveToMonthEdge(baseDate, amount >= 0 ? 'end' : 'start');
@@ -545,33 +555,19 @@ export function createCalendarContext(options) {
         const monthEnd = addDays(addMonths(monthStart, 1), -1);
         const targetDate = edge === 'start' ? monthStart : monthEnd;
         const nextValue = formatCalendarDate(targetDate);
-        const dayStep = edge === 'start' ? 1 : -1;
-        const focusableValue = findFocusableDate(nextValue, dayStep);
+        const focusableValue = findFocusableDate(nextValue);
         if (!focusableValue)
             return undefined;
         setFocusedValue(focusableValue);
         return focusableValue;
     }
-    function findFocusableDate(targetDate, dayStep) {
+    function findFocusableDate(targetDate) {
         if (isDisabled)
             return undefined;
-        if (!isDateDisabled(targetDate))
-            return targetDate;
-        if (dayStep === 0)
-            return undefined;
-        let current = parseCalendarDate(targetDate);
-        if (!current)
-            return undefined;
-        for (let index = 0; index < MAX_FOCUS_SEARCH_DAYS; index++) {
-            current = addDays(current, dayStep > 0 ? 1 : -1);
-            const candidate = formatCalendarDate(current);
-            if (!isDateDisabled(candidate)) {
-                return candidate;
-            }
-        }
-        return undefined;
+        return targetDate;
     }
     function handleCellKeydown(event, date) {
+        setFocusVisible(true);
         const keyDate = isValidCalendarDateValue(currentFocused) ? currentFocused : date;
         let movedDate;
         function extendRangeWithKeyboard(nextDate) {
@@ -668,6 +664,9 @@ export function createCalendarContext(options) {
         get visibleMonths() {
             return visibleMonths;
         },
+        get showOutsideDays() {
+            return showOutsideDays;
+        },
         get isDisabled() {
             return isDisabled;
         },
@@ -686,6 +685,9 @@ export function createCalendarContext(options) {
         get focusedValue() {
             return currentFocused;
         },
+        get focusVisible() {
+            return currentFocusVisible;
+        },
         get weekdayLabels() {
             return getWeekdayLabels(locale, cachedFirstDayOfWeek);
         },
@@ -700,6 +702,7 @@ export function createCalendarContext(options) {
         isDateDisabled,
         isOutsideVisibleRange,
         setFocusedValue,
+        setFocusVisible,
         setHoveredValue,
         selectDate,
         goToNextPage,

package/dist/calendar/root/date-utils.d.ts

@@ -13,5 +13,5 @@ export type CalendarDayCell = {
     date: CalendarDateValue;
     isOutsideMonth: boolean;
 };
-export declare function buildMonthGrid(monthStart: Date, firstDayOfWeek: number): CalendarDayCell[][];
+export declare function buildMonthGrid(monthStart: Date, firstDayOfWeek: number, showOutsideDays?: boolean): CalendarDayCell[][];
 export declare function formatMonthHeading(date: Date, locale: string): string;

package/dist/calendar/root/date-utils.js

@@ -1,43 +1,28 @@
-const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+import { createUtcDate, formatDateOnlyValue, isValidDateOnlyValue, parseDateOnlyValue } from '../../utils/date-only';
 export function isValidCalendarDateValue(value) {
-    const match = DATE_RE.exec(value);
-    if (!match)
-        return false;
-    const year = Number(match[1]);
-    const month = Number(match[2]);
-    const day = Number(match[3]);
-    if (month < 1 || month > 12 || day < 1 || day > 31)
-        return false;
-    const date = new Date(Date.UTC(year, month - 1, day));
-    return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
+    return isValidDateOnlyValue(value);
 }
 export function parseCalendarDate(value) {
-    if (!isValidCalendarDateValue(value))
-        return null;
-    const [year, month, day] = value.split('-').map(Number);
-    return new Date(Date.UTC(year, month - 1, day));
+    return parseDateOnlyValue(value);
 }
 export function formatCalendarDate(date) {
-    const year = date.getUTCFullYear();
-    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
-    const day = String(date.getUTCDate()).padStart(2, '0');
-    return `${year}-${month}-${day}`;
+    return formatDateOnlyValue(date);
 }
 export function startOfMonth(date) {
-    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1));
+    return createUtcDate(date.getUTCFullYear(), date.getUTCMonth(), 1);
 }
 function getDaysInMonthUtc(year, monthIndex) {
-    return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+    return createUtcDate(year, monthIndex + 1, 0).getUTCDate();
 }
 export function addMonths(date, amount) {
     const targetMonth = date.getUTCMonth() + amount;
     const targetYear = date.getUTCFullYear() + Math.floor(targetMonth / 12);
     const normalizedMonth = ((targetMonth % 12) + 12) % 12;
     const targetDay = Math.min(date.getUTCDate(), getDaysInMonthUtc(targetYear, normalizedMonth));
-    return new Date(Date.UTC(targetYear, normalizedMonth, targetDay));
+    return createUtcDate(targetYear, normalizedMonth, targetDay);
 }
 export function addDays(date, amount) {
-    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount));
+    return createUtcDate(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount);
 }
 export function compareDates(a, b) {
     const at = a.getTime();
@@ -50,7 +35,7 @@ export function compareDates(a, b) {
 }
 export function getTodayUtcDate() {
     const now = new Date();
-    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    return createUtcDate(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
 }
 export function getFirstDayOfWeek(locale) {
     try {
@@ -76,13 +61,18 @@ export function getWeekdayLabels(locale, firstDayOfWeek) {
         return formatter.format(addDays(sunday, dayOffset));
     });
 }
-export function buildMonthGrid(monthStart, firstDayOfWeek) {
+export function buildMonthGrid(monthStart, firstDayOfWeek, showOutsideDays = true) {
     const firstOfMonth = startOfMonth(monthStart);
     const firstWeekday = firstOfMonth.getUTCDay();
     const startOffset = (firstWeekday - firstDayOfWeek + 7) % 7;
     const gridStart = addDays(firstOfMonth, -startOffset);
+    const lastOfMonth = addDays(addMonths(firstOfMonth, 1), -1);
+    const lastWeekday = lastOfMonth.getUTCDay();
+    const endOffset = (firstDayOfWeek + 6 - lastWeekday + 7) % 7;
+    const visibleDays = startOffset + lastOfMonth.getUTCDate() + endOffset;
+    const weekCount = showOutsideDays ? 6 : Math.max(1, Math.ceil(visibleDays / 7));
     const weeks = [];
-    for (let weekIndex = 0; weekIndex < 6; weekIndex++) {
+    for (let weekIndex = 0; weekIndex < weekCount; weekIndex++) {
         const week = [];
         for (let dayIndex = 0; dayIndex < 7; dayIndex++) {
             const date = addDays(gridStart, weekIndex * 7 + dayIndex);

package/dist/calendar/trigger-next/README.md

@@ -0,0 +1,14 @@
+# Calendar TriggerNext
+
+## API reference
+
+### Calendar.TriggerNext
+
+Name: `Calendar.TriggerNext`  
+Description: Button part that advances the visible calendar period.
+
+| Prop           | Type                   | Default     | Description                                            |
+| -------------- | ---------------------- | ----------- | ------------------------------------------------------ |
+| `children`     | `Snippet`              | `undefined` | Optional trigger content.                              |
+| `class`        | `string`               | `''`        | CSS class names for the trigger button.                |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional button attributes forwarded to the trigger. |

package/dist/calendar/trigger-previous/README.md

@@ -0,0 +1,14 @@
+# Calendar TriggerPrevious
+
+## API reference
+
+### Calendar.TriggerPrevious
+
+Name: `Calendar.TriggerPrevious`  
+Description: Button part that moves the visible calendar period backward.
+
+| Prop           | Type                   | Default     | Description                                            |
+| -------------- | ---------------------- | ----------- | ------------------------------------------------------ |
+| `children`     | `Snippet`              | `undefined` | Optional trigger content.                              |
+| `class`        | `string`               | `''`        | CSS class names for the trigger button.                |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional button attributes forwarded to the trigger. |

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;