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

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

@@ -0,0 +1,17 @@
+export type CalendarDateValue = string;
+export declare function isValidCalendarDateValue(value: string): boolean;
+export declare function parseCalendarDate(value: CalendarDateValue): Date | null;
+export declare function formatCalendarDate(date: Date): CalendarDateValue;
+export declare function startOfMonth(date: Date): Date;
+export declare function addMonths(date: Date, amount: number): Date;
+export declare function addDays(date: Date, amount: number): Date;
+export declare function compareDates(a: Date, b: Date): number;
+export declare function getTodayUtcDate(): Date;
+export declare function getFirstDayOfWeek(locale: string): number;
+export declare function getWeekdayLabels(locale: string, firstDayOfWeek: number): string[];
+export type CalendarDayCell = {
+    date: CalendarDateValue;
+    isOutsideMonth: boolean;
+};
+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

@@ -0,0 +1,94 @@
+import { createUtcDate, formatDateOnlyValue, isValidDateOnlyValue, parseDateOnlyValue } from '../../utils/date-only';
+export function isValidCalendarDateValue(value) {
+    return isValidDateOnlyValue(value);
+}
+export function parseCalendarDate(value) {
+    return parseDateOnlyValue(value);
+}
+export function formatCalendarDate(date) {
+    return formatDateOnlyValue(date);
+}
+export function startOfMonth(date) {
+    return createUtcDate(date.getUTCFullYear(), date.getUTCMonth(), 1);
+}
+function getDaysInMonthUtc(year, monthIndex) {
+    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 createUtcDate(targetYear, normalizedMonth, targetDay);
+}
+export function addDays(date, amount) {
+    return createUtcDate(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount);
+}
+export function compareDates(a, b) {
+    const at = a.getTime();
+    const bt = b.getTime();
+    if (at < bt)
+        return -1;
+    if (at > bt)
+        return 1;
+    return 0;
+}
+export function getTodayUtcDate() {
+    const now = new Date();
+    return createUtcDate(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+}
+export function getFirstDayOfWeek(locale) {
+    try {
+        const intlLocale = new Intl.Locale(locale);
+        const weekInfo = intlLocale.weekInfo;
+        if (weekInfo?.firstDay) {
+            return weekInfo.firstDay % 7;
+        }
+    }
+    catch {
+        // ignore and fallback to sunday
+    }
+    return 0;
+}
+export function getWeekdayLabels(locale, firstDayOfWeek) {
+    const formatter = new Intl.DateTimeFormat(locale, {
+        weekday: 'short',
+        timeZone: 'UTC'
+    });
+    const sunday = new Date(Date.UTC(2024, 0, 7));
+    return Array.from({ length: 7 }, (_, index) => {
+        const dayOffset = (firstDayOfWeek + index) % 7;
+        return formatter.format(addDays(sunday, dayOffset));
+    });
+}
+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 < weekCount; weekIndex++) {
+        const week = [];
+        for (let dayIndex = 0; dayIndex < 7; dayIndex++) {
+            const date = addDays(gridStart, weekIndex * 7 + dayIndex);
+            week.push({
+                date: formatCalendarDate(date),
+                isOutsideMonth: date.getUTCMonth() !== firstOfMonth.getUTCMonth()
+            });
+        }
+        weeks.push(week);
+    }
+    return weeks;
+}
+export function formatMonthHeading(date, locale) {
+    return new Intl.DateTimeFormat(locale, {
+        month: 'long',
+        year: 'numeric',
+        timeZone: 'UTC'
+    }).format(date);
+}

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-next/calendar-trigger-next.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { useCalendarContext } from '../root/context';
+
+	type CalendarTriggerNextProps = Omit<
+		HTMLButtonAttributes,
+		'children' | 'class' | 'disabled' | 'aria-disabled'
+	> & {
+		class?: string;
+		children?: Snippet;
+	};
+
+	let { children, class: className = '', ...restProps }: CalendarTriggerNextProps = $props();
+
+	const calendar = useCalendarContext();
+	const layoutVersion = calendar.layoutVersion;
+	const isDisabled = $derived.by(() => {
+		void $layoutVersion;
+		return calendar.isDisabled;
+	});
+
+	function handleClick() {
+		if (isDisabled) return;
+		calendar.goToNextPage();
+	}
+</script>
+
+<ButtonRoot
+	type="button"
+	class={className}
+	aria-label="Next page"
+	{isDisabled}
+	onclick={handleClick}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		Next
+	{/if}
+</ButtonRoot>

package/dist/calendar/trigger-next/calendar-trigger-next.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type CalendarTriggerNextProps = Omit<HTMLButtonAttributes, 'children' | 'class' | 'disabled' | 'aria-disabled'> & {
+    class?: string;
+    children?: Snippet;
+};
+declare const CalendarTriggerNext: import("svelte").Component<CalendarTriggerNextProps, {}, "">;
+type CalendarTriggerNext = ReturnType<typeof CalendarTriggerNext>;
+export default CalendarTriggerNext;

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/calendar/trigger-previous/calendar-trigger-previous.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { useCalendarContext } from '../root/context';
+
+	type CalendarTriggerPreviousProps = Omit<
+		HTMLButtonAttributes,
+		'children' | 'class' | 'disabled' | 'aria-disabled'
+	> & {
+		class?: string;
+		children?: Snippet;
+	};
+
+	let { children, class: className = '', ...restProps }: CalendarTriggerPreviousProps = $props();
+
+	const calendar = useCalendarContext();
+	const layoutVersion = calendar.layoutVersion;
+	const isDisabled = $derived.by(() => {
+		void $layoutVersion;
+		return calendar.isDisabled;
+	});
+
+	function handleClick() {
+		if (isDisabled) return;
+		calendar.goToPreviousPage();
+	}
+</script>
+
+<ButtonRoot
+	type="button"
+	class={className}
+	aria-label="Previous page"
+	{isDisabled}
+	onclick={handleClick}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		Prev
+	{/if}
+</ButtonRoot>

package/dist/calendar/trigger-previous/calendar-trigger-previous.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type CalendarTriggerPreviousProps = Omit<HTMLButtonAttributes, 'children' | 'class' | 'disabled' | 'aria-disabled'> & {
+    class?: string;
+    children?: Snippet;
+};
+declare const CalendarTriggerPrevious: import("svelte").Component<CalendarTriggerPreviousProps, {}, "">;
+type CalendarTriggerPrevious = ReturnType<typeof CalendarTriggerPrevious>;
+export default CalendarTriggerPrevious;

package/dist/checkbox/README.md

@@ -0,0 +1,53 @@
+# Checkbox
+
+## Description
+
+`Checkbox` is a composable tri-state checkbox with separate checked and indeterminate bindings, hidden input form support, and headless indicator rendering.
+
+## Anatomy
+
+- `Checkbox.Root`
+- `Checkbox.Indicator`
+
+```svelte
+<Checkbox.Root aria-label="Accept terms">
+	<Checkbox.Indicator>
+		<CheckIcon />
+	</Checkbox.Indicator>
+</Checkbox.Root>
+```
+
+## Usage guidelines
+
+- Use `isChecked` / `defaultChecked` for the checked state and `isIndeterminate` / `defaultIndeterminate` for the mixed state.
+- `isIndeterminate` takes precedence over `isChecked`. When both are `true`, the checkbox is exposed as indeterminate.
+- Use `value` only for form submission through the hidden native input; it does not represent the visual state.
+- Wrap the checkbox in a native `<label>` for the simplest accessible labeling pattern.
+
+## API reference
+
+- `Checkbox.Root`
+  - `isChecked?: boolean`
+  - `defaultChecked?: boolean`
+  - `isIndeterminate?: boolean`
+  - `defaultIndeterminate?: boolean`
+  - `onCheckedChange?: (checked: boolean) => void`
+  - `onIndeterminateChange?: (indeterminate: boolean) => void`
+  - `isDisabled?: boolean`
+  - `isReadOnly?: boolean`
+  - `name?: string`
+  - `value?: string`
+  - `required?: boolean`
+- `Checkbox.Indicator`
+  - `keepMounted?: boolean`
+
+## Accessibility
+
+- `Checkbox.Root` exposes `role="checkbox"` with `aria-checked="true" | "false" | "mixed"`.
+- Press `Space` to toggle the checkbox.
+- `isReadOnly` keeps the checkbox focusable while preventing state changes.
+
+## Notes
+
+- The first user toggle from the indeterminate state resolves to checked.
+- A hidden checkbox input is kept in sync for form integration and `label[for]` support.

package/dist/checkbox/TODO.md

@@ -0,0 +1,16 @@
+# Checkbox TODO
+
+## Goal
+
+Track Checkbox work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [S][P0][Area: Architecture][Owner: Unassigned][Target: Done] Create base `root` and `indicator` parts with namespace exports.
+- [x] [S][P0][Area: State][Owner: Unassigned][Target: Done] Implement checked, unchecked, and indeterminate state transitions.
+- [x] [S][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Add checkbox semantics, keyboard toggle, and readonly behavior.
+- [x] [S][P0][Area: Forms][Owner: Unassigned][Target: Done] Sync a hidden native input for form submission and label targeting.
+- [x] [S][P0][Area: Testing][Owner: Unassigned][Target: Done] Add baseline tests for root and indicator behavior.
+- [ ] [S][P1][Area: API][Owner: Unassigned][Target: TBD] Add optional `nativeButton` rendering mode for sibling-label patterns.
+- [ ] [S][P1][Area: Forms][Owner: Unassigned][Target: TBD] Support unchecked submission values and form reset synchronization.
+- [ ] [C][P2][Area: Animation][Owner: Unassigned][Target: TBD] Add indicator presence data for enter and exit animations.

package/dist/checkbox/index.d.ts

@@ -0,0 +1,6 @@
+export * as Checkbox from './index.parts.js';
+export { default as CheckboxRoot } from './root/checkbox-root.svelte';
+export { default as CheckboxIndicator } from './indicator/checkbox-indicator.svelte';
+export { getCheckboxContext, setCheckboxContext, useCheckboxContext, type CheckboxContext, type CheckboxState } from './root/context.js';
+import * as CheckboxParts from './index.parts.js';
+export default CheckboxParts;

package/dist/checkbox/index.js

@@ -0,0 +1,6 @@
+export * as Checkbox from './index.parts.js';
+export { default as CheckboxRoot } from './root/checkbox-root.svelte';
+export { default as CheckboxIndicator } from './indicator/checkbox-indicator.svelte';
+export { getCheckboxContext, setCheckboxContext, useCheckboxContext } from './root/context.js';
+import * as CheckboxParts from './index.parts.js';
+export default CheckboxParts;

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

@@ -0,0 +1,2 @@
+export { default as Root } from './root/checkbox-root.svelte';
+export { default as Indicator } from './indicator/checkbox-indicator.svelte';

package/dist/checkbox/index.parts.js

@@ -0,0 +1,2 @@
+export { default as Root } from './root/checkbox-root.svelte';
+export { default as Indicator } from './indicator/checkbox-indicator.svelte';

package/dist/checkbox/indicator/README.md

@@ -0,0 +1,23 @@
+# Checkbox Indicator
+
+## API reference
+
+### Checkbox.Indicator
+
+Name: `Checkbox.Indicator`  
+Description: Headless presence wrapper for checkbox indicator content. It renders when the checkbox is checked or indeterminate.
+
+| Prop           | Type                              | Default     | Description                                                              |
+| -------------- | --------------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `keepMounted`  | `boolean`                         | `false`     | Keeps the indicator mounted while hidden when the checkbox is unchecked. |
+| `children`     | `Snippet`                         | `undefined` | Rendered indicator content, such as a check or dash icon.                |
+| `class`        | `string`                          | `''`        | CSS class names for the indicator wrapper.                               |
+| `...restProps` | `HTMLAttributes<HTMLSpanElement>` | `-`         | Additional attributes forwarded to the indicator span.                   |
+
+```svelte
+<Checkbox.Root aria-label="Select row">
+	<Checkbox.Indicator>
+		<CheckIcon />
+	</Checkbox.Indicator>
+</Checkbox.Root>
+```

package/dist/checkbox/indicator/checkbox-indicator.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import type { Snippet } from 'svelte';
+	import { cn } from '../../utils/cn';
+	import { useCheckboxContext } from '../root/context';
+
+	type CheckboxIndicatorProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class'> & {
+		keepMounted?: boolean;
+		children?: Snippet;
+		class?: string;
+	};
+
+	let {
+		keepMounted = false,
+		children,
+		class: className = '',
+		...restProps
+	}: CheckboxIndicatorProps = $props();
+
+	const checkbox = useCheckboxContext();
+	const visible = $derived(checkbox.state !== 'unchecked');
+</script>
+
+{#if keepMounted || visible}
+	<span
+		{...restProps}
+		data-checkbox-indicator="true"
+		data-checked={checkbox.isChecked || undefined}
+		data-unchecked={checkbox.state === 'unchecked' || undefined}
+		data-indeterminate={checkbox.isIndeterminate || undefined}
+		data-pressed={checkbox.pressed || undefined}
+		data-disabled={checkbox.isDisabled || undefined}
+		data-readonly={checkbox.isReadOnly || undefined}
+		data-required={checkbox.required || undefined}
+		data-focused={checkbox.focused || undefined}
+		data-focus-visible={checkbox.focusVisible || undefined}
+		hidden={keepMounted && !visible}
+		aria-hidden={keepMounted && !visible ? 'true' : undefined}
+		class={cn('contents', className)}
+	>
+		{@render children?.()}
+	</span>
+{/if}

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

@@ -0,0 +1,10 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Snippet } from 'svelte';
+type CheckboxIndicatorProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class'> & {
+    keepMounted?: boolean;
+    children?: Snippet;
+    class?: string;
+};
+declare const CheckboxIndicator: import("svelte").Component<CheckboxIndicatorProps, {}, "">;
+type CheckboxIndicator = ReturnType<typeof CheckboxIndicator>;
+export default CheckboxIndicator;

package/dist/checkbox/root/README.md

@@ -0,0 +1,47 @@
+# Checkbox Root
+
+## API reference
+
+### Checkbox.Root
+
+Name: `Checkbox.Root`  
+Description: Interactive tri-state checkbox root that owns checked, indeterminate, focus, and hidden input synchronization.
+
+| Prop                    | Type                               | Default       | Description                                                      |
+| ----------------------- | ---------------------------------- | ------------- | ---------------------------------------------------------------- |
+| `id`                    | `string`                           | `$props.id()` | Stable id used for the hidden input and derived root id.         |
+| `name`                  | `string`                           | `undefined`   | Form field name forwarded to the hidden native input.            |
+| `value`                 | `string`                           | `'on'`        | Submitted value when the checkbox is checked.                    |
+| `isChecked`             | `boolean`                          | `undefined`   | Controlled checked state. Supports `bind:isChecked`.             |
+| `defaultChecked`        | `boolean`                          | `false`       | Initial checked state in uncontrolled mode.                      |
+| `isIndeterminate`       | `boolean`                          | `undefined`   | Controlled indeterminate state. Supports `bind:isIndeterminate`. |
+| `defaultIndeterminate`  | `boolean`                          | `false`       | Initial indeterminate state in uncontrolled mode.                |
+| `onCheckedChange`       | `(checked: boolean) => void`       | `undefined`   | Called when the effective checked state changes.                 |
+| `onIndeterminateChange` | `(indeterminate: boolean) => void` | `undefined`   | Called when the effective indeterminate state changes.           |
+| `isDisabled`            | `boolean`                          | `false`       | Prevents focus and state changes.                                |
+| `isReadOnly`            | `boolean`                          | `false`       | Allows focus but blocks user-driven state changes.               |
+| `required`              | `boolean`                          | `false`       | Marks the hidden input as required and exposes `data-required`.  |
+| `children`              | `Snippet`                          | `undefined`   | Composed checkbox parts such as `Checkbox.Indicator`.            |
+| `class`                 | `string`                           | `''`          | CSS class names for the root element.                            |
+| `...restProps`          | `HTMLAttributes<HTMLSpanElement>`  | `-`           | Additional attributes forwarded to the checkbox root span.       |
+
+### Context utilities
+
+Name: `context.ts` helpers  
+Description: Internal APIs for publishing and consuming checkbox state.
+
+| Prop                 | Type                                 | Default | Description                                        |
+| -------------------- | ------------------------------------ | ------- | -------------------------------------------------- |
+| `setCheckboxContext` | `(ctx: CheckboxContext) => void`     | `-`     | Registers the checkbox context in root.            |
+| `getCheckboxContext` | `() => CheckboxContext \| undefined` | `-`     | Returns the context when available.                |
+| `useCheckboxContext` | `() => CheckboxContext`              | `-`     | Returns the context and throws outside root usage. |
+
+`CheckboxState` is the internal state union used by the root context: `'checked' | 'unchecked' | 'indeterminate'`.
+
+```svelte
+<Checkbox.Root bind:isChecked bind:isIndeterminate aria-label="Notifications">
+	<Checkbox.Indicator>
+		<CheckIcon />
+	</Checkbox.Indicator>
+</Checkbox.Root>
+```

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

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import { Checkbox } from '../index.ts';
+</script>
+
+<label for="notifications">Enable notifications</label>
+<Checkbox.Root id="notifications" aria-label="Notifications">
+	<Checkbox.Indicator>
+		<span data-checkbox-icon="true">icon</span>
+	</Checkbox.Indicator>
+</Checkbox.Root>

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

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CheckboxLabelTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CheckboxLabelTest = InstanceType<typeof CheckboxLabelTest>;
+export default CheckboxLabelTest;