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

package/dist/FOCUS_STATE_CONTRACT.md

@@ -49,3 +49,15 @@ On overlay/popover close, transient trigger state is allowed:
 ## Operational Template
 
 - Use `FOCUS_STATE_REVIEW_TEMPLATE.md` for PR/release reviews (modality matrix + component status + checklist).
+
+## Component Coverage
+
+The following components implement this contract:
+
+- **Popover** — trigger + content, restore focus on close.
+- **Dialog** — trigger + overlay/content, nested stack support.
+- **DatePicker** — segment spinbuttons, trigger, popover (calendar).
+- **TimePicker** — segment spinbuttons, trigger, popover (scrollable columns). Follows the same contract as DatePicker.
+- **Calendar** — grid cells with roving tabindex.
+- **ComboBox** — input + listbox with virtual focus.
+- **ListBox** — items with roving tabindex.

package/dist/calendar/body-cell/README.md

@@ -0,0 +1,15 @@
+# Calendar BodyCell
+
+## API reference
+
+### Calendar.BodyCell
+
+Name: `Calendar.BodyCell`  
+Description: Wrapper part for date grid cells inside `Calendar.GridBody`.
+
+| Prop           | Type                                   | Default     | Description                                                     |
+| -------------- | -------------------------------------- | ----------- | --------------------------------------------------------------- |
+| `date`         | `string`                               | `required`  | Calendar date value rendered by the cell (`YYYY-MM-DD`).        |
+| `children`     | `Snippet<[string]>`                    | `undefined` | Optional custom renderer receiving the day label text.          |
+| `class`        | `string`                               | `''`        | CSS class names for the inner gridcell element.                 |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the outer table cell (`td`). |

package/dist/calendar/grid/README.md

@@ -0,0 +1,13 @@
+# Calendar Grid
+
+## API reference
+
+### Calendar.Grid
+
+Name: `Calendar.Grid`  
+Description: Calendar month table container rendered by `Calendar.Root`.
+
+| Prop       | Type      | Default     | Description                                   |
+| ---------- | --------- | ----------- | --------------------------------------------- |
+| `children` | `Snippet` | `undefined` | Optional custom month-grid content.           |
+| `class`    | `string`  | `''`        | CSS class names for the outer grid container. |

package/dist/calendar/grid-body/README.md

@@ -0,0 +1,13 @@
+# Calendar GridBody
+
+## API reference
+
+### Calendar.GridBody
+
+Name: `Calendar.GridBody`  
+Description: TBody container for week rows in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                              |
+| ---------- | ------------------- | ----------- | -------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each day date string. |
+| `class`    | `string`            | `''`        | CSS class names for the `tbody` element.                 |

package/dist/calendar/grid-header/README.md

@@ -0,0 +1,13 @@
+# Calendar GridHeader
+
+## API reference
+
+### Calendar.GridHeader
+
+Name: `Calendar.GridHeader`  
+Description: Header row group for weekday labels in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                                      |
+| ---------- | ------------------- | ----------- | ---------------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each localized weekday label. |
+| `class`    | `string`            | `''`        | CSS class names for the `thead` element.                         |

package/dist/calendar/header-cell/README.md

@@ -0,0 +1,14 @@
+# Calendar HeaderCell
+
+## API reference
+
+### Calendar.HeaderCell
+
+Name: `Calendar.HeaderCell`  
+Description: Weekday heading cell part used inside `Calendar.GridHeader`.
+
+| Prop           | Type                                   | Default     | Description                                        |
+| -------------- | -------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `Snippet`                              | `undefined` | Optional custom header cell content.               |
+| `class`        | `string`                               | `''`        | CSS class names for the header cell element.       |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the table cell. |

package/dist/calendar/heading/README.md

@@ -0,0 +1,13 @@
+# Calendar Heading
+
+## API reference
+
+### Calendar.Heading
+
+Name: `Calendar.Heading`  
+Description: Label part that displays the currently visible calendar period.
+
+| Prop           | Type                                 | Default | Description                                             |
+| -------------- | ------------------------------------ | ------- | ------------------------------------------------------- |
+| `class`        | `string`                             | `''`    | CSS class names for the heading element (`h2`).         |
+| `...restProps` | `HTMLAttributes<HTMLHeadingElement>` | `-`     | Additional attributes forwarded to the heading element. |

package/dist/calendar/root/README.md

@@ -0,0 +1,24 @@
+# Calendar Root
+
+## API reference
+
+### Calendar.Root
+
+Name: `Calendar.Root`  
+Description: Root state container for date grid rendering, navigation, selection, and locale-aware formatting.
+
+| Prop                | Type                                                       | Default     | Description                                                         |
+| ------------------- | ---------------------------------------------------------- | ----------- | ------------------------------------------------------------------- |
+| `selectionMode`     | `'single' \| 'range'`                                      | `'single'`  | Selection behavior and value shape.                                 |
+| `value`             | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `bindable`  | Controlled selected value (single date or `{ start, end }`).        |
+| `defaultValue`      | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `undefined` | Initial value for uncontrolled mode.                                |
+| `onChange`          | `(value: CalendarDateValue \| CalendarRangeValue) => void` | `undefined` | Called when selection changes.                                      |
+| `visibleMonths`     | `number`                                                   | `1`         | Number of month grids rendered simultaneously.                      |
+| `showOutsideDays`   | `boolean`                                                  | `false`     | Whether days outside the visible month remain rendered/interactive. |
+| `isDateUnavailable` | `(date: string) => boolean`                                | `undefined` | Marks specific dates as unavailable.                                |
+| `isDisabled`        | `boolean`                                                  | `false`     | Disables interaction and navigation.                                |
+| `isReadOnly`        | `boolean`                                                  | `false`     | Keeps navigation while preventing selection updates.                |
+| `children`          | `Snippet`                                                  | `undefined` | Composed `Calendar` parts.                                          |
+| `class`             | `string`                                                   | `''`        | CSS class names for the root wrapper.                               |
+| `id`                | `string`                                                   | `undefined` | Optional root id.                                                   |
+| `aria-label`        | `string`                                                   | `undefined` | Accessible label for the root wrapper.                              |

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/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.ts';
+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.ts';
+import * as CheckboxParts from './index.parts.ts';
+export default CheckboxParts;

package/dist/checkbox/index.js

@@ -0,0 +1,6 @@
+export * as Checkbox from './index.parts.ts';
+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.ts';
+import * as CheckboxParts from './index.parts.ts';
+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;