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

package/dist/combobox/root/combobox.svelte

@@ -3,11 +3,16 @@
 	import { setComboBoxContext, type ComboBoxContext } from './context';
 	import type { ListBoxContext } from '../../listbox/root/context';
 	import { useVirtualFocus } from '../../hooks/use-virtual-focus.svelte';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
 
 	type ComboBoxProps<T> = {
 		/** Stable ID used to generate internal ARIA IDs (recommended for SSR). */
 		id?: string;
 		isDisabled?: boolean;
+		isPending?: boolean;
 		isReadOnly?: boolean;
 		/** Selected value(s). Single value for single mode, array for multiple mode. Can be bound with bind:value */
 		value?: string | number | (string | number)[];
@@ -43,6 +48,7 @@
 	let {
 		id: rootId,
 		isDisabled = false,
+		isPending = false,
 		isReadOnly = false,
 		value = $bindable(),
 		defaultValue,
@@ -98,6 +104,9 @@
 
 	// Virtual focus for tag navigation in multiple mode
 	let focusedTagId: string | number | null = $state(null);
+	let focusWithin = $state(false);
+	let focusVisible = $state(false);
+	let popoverPointerDownPending = $state(false);
 
 	// Flag to control whether inputValue should be used for filtering
 	// When false, all items are shown regardless of inputValue
@@ -188,6 +197,7 @@
 		// In multiple mode, selections are managed via tags, not input
 		if (selectionMode === 'single' && val.trim() === '' && currentSelection.size > 0) {
 			const emptySelection = new Set<string | number>();
+			selectedInternal = emptySelection;
 			if (isSelectionControlled) {
 				onChange?.(toExternalValue(emptySelection));
 			} else {
@@ -236,6 +246,7 @@
 			}
 		}
 
+		selectedInternal = newSelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(newSelection));
 		} else {
@@ -257,6 +268,7 @@
 		// Remove from persistent labels
 		selectedLabels.delete(id);
 
+		selectedInternal = newSelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(newSelection));
 		} else {
@@ -274,6 +286,7 @@
 	function clearSelection() {
 		const emptySelection = new Set<string | number>();
 
+		selectedInternal = emptySelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(emptySelection));
 		} else {
@@ -335,6 +348,34 @@
 		}
 	}
 
+	function syncFocusWithin() {
+		focusWithin =
+			!!wrapperRef && !!document.activeElement && wrapperRef.contains(document.activeElement);
+		if (!focusWithin) {
+			focusVisible = false;
+			// Clean up stale data-focused/data-focus-visible that Popover.Root's
+			// focus-state module may have set imperatively on the wrapper (the
+			// wrapper is briefly used as triggerRef before the input overrides it).
+			if (wrapperRef) {
+				delete wrapperRef.dataset.focused;
+				delete wrapperRef.dataset.focusVisible;
+			}
+		}
+	}
+
+	function handleFocusIn(event: FocusEvent) {
+		focusWithin = true;
+		focusVisible = shouldShowFocusVisible(event.target as HTMLElement | null);
+	}
+
+	function handleFocusOut() {
+		queueMicrotask(syncFocusWithin);
+	}
+
+	function setFocusVisibleState(visible: boolean) {
+		focusVisible = visible && focusWithin;
+	}
+
 	// Use navigation hook methods for keyboard navigation
 	function selectFocusedItem() {
 		if (navigation.focusedId !== null) {
@@ -346,9 +387,26 @@
 	/**
 	 * Handle input blur or escape - restore selection label or clear if no selection
 	 */
-	function handleInputBlur() {
+	function consumePopoverPointerDown() {
+		if (!popoverPointerDownPending) return false;
+		popoverPointerDownPending = false;
+		return true;
+	}
+
+	function handleInputBlur(event?: FocusEvent) {
 		// Clear tag virtual focus
 		focusedTagId = null;
+
+		const nextFocusedElement = event?.relatedTarget;
+		const isMovingFocusWithinCombobox =
+			nextFocusedElement instanceof Node &&
+			((wrapperRef?.contains(nextFocusedElement) ?? false) ||
+				(listboxRef?.contains(nextFocusedElement) ?? false));
+
+		if (isMovingFocusWithinCombobox || consumePopoverPointerDown()) {
+			return;
+		}
+
 		// Close popover first to prevent flash of options when clearing input
 		closePopover();
 
@@ -385,6 +443,7 @@
 
 	function handleKeydown(event: KeyboardEvent) {
 		if (isDisabled) return;
+		trackInteractionModality(event, event.target as HTMLElement | null);
 
 		// Handle tag virtual focus navigation in multiple mode
 		if (focusedTagId !== null && selectionMode === 'multiple') {
@@ -559,6 +618,8 @@
 					event.stopImmediatePropagation();
 				}
 				handleInputBlur();
+				// Escape is a keyboard-only path, so focus-visible remains enabled for the input.
+				focusVisible = true;
 				event.preventDefault();
 				break;
 			case 'Backspace':
@@ -604,6 +665,9 @@
 		get isDisabled() {
 			return isDisabled;
 		},
+		get isPending() {
+			return isPending;
+		},
 		get isReadOnly() {
 			return isReadOnly;
 		},
@@ -668,12 +732,17 @@
 		unregisterItem: navigation.unregister,
 		handleKeydown,
 		handleInputBlur,
+		setFocusVisible: setFocusVisibleState,
 		get focusedTagId() {
 			return focusedTagId;
 		},
 		setFocusedTagId: (id: string | number | null) => {
 			focusedTagId = id;
-		}
+		},
+		markPopoverPointerDown: () => {
+			popoverPointerDownPending = true;
+		},
+		consumePopoverPointerDown
 	};
 
 	setComboBoxContext(ctx);
@@ -684,11 +753,18 @@
 	role="group"
 	aria-label={ariaLabel}
 	aria-labelledby={ariaLabelledby}
+	aria-busy={isPending ? 'true' : undefined}
 	class={className}
 	data-combobox
+	data-focused={focusWithin || undefined}
 	data-disabled={isDisabled || undefined}
+	data-pending={isPending || undefined}
 	data-readonly={isReadOnly || undefined}
+	data-focus-within={focusWithin || undefined}
+	data-focus-visible={focusVisible || undefined}
 	use:setWrapperAsTrigger
+	onfocusin={handleFocusIn}
+	onfocusout={handleFocusOut}
 >
 	{#if children}
 		{@render children()}

package/dist/combobox/root/combobox.svelte.d.ts

@@ -3,6 +3,7 @@ type ComboBoxProps<T> = {
     /** Stable ID used to generate internal ARIA IDs (recommended for SSR). */
     id?: string;
     isDisabled?: boolean;
+    isPending?: boolean;
     isReadOnly?: boolean;
     /** Selected value(s). Single value for single mode, array for multiple mode. Can be bound with bind:value */
     value?: string | number | (string | number)[];

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

@@ -20,6 +20,8 @@ export type ComboBoxContext<T extends object = object> = {
     selectedValue: Set<string | number>;
     /** Whether the combobox is disabled */
     isDisabled: boolean;
+    /** Whether the combobox is pending async work */
+    isPending: boolean;
     /** Whether the combobox is read-only */
     isReadOnly: boolean;
     /** Selection mode */
@@ -79,11 +81,17 @@ export type ComboBoxContext<T extends object = object> = {
     /** Handle keyboard events (arrow navigation, enter, escape) */
     handleKeydown: (event: KeyboardEvent) => void;
     /** Handle input blur - restore selection or deselect if empty */
-    handleInputBlur: () => void;
+    handleInputBlur: (event?: FocusEvent) => void;
+    /** Update root-level focus-visible state based on current modality. */
+    setFocusVisible: (visible: boolean) => void;
     /** Currently focused tag ID (virtual focus for tag navigation) */
     focusedTagId: string | number | null;
     /** Set focused tag ID (virtual focus for tag navigation) */
     setFocusedTagId: (id: string | number | null) => void;
+    /** Mark that the next input blur was caused by pointer interaction inside the popover. */
+    markPopoverPointerDown: () => void;
+    /** Consume the pending popover-pointer marker. */
+    consumePopoverPointerDown: () => boolean;
 };
 export declare function setComboBoxContext<T extends object = object>(ctx: ComboBoxContext<T>): void;
 export declare function getComboBoxContext<T extends object = object>(): ComboBoxContext<T> | undefined;

package/dist/combobox/tag/README.md

@@ -0,0 +1,37 @@
+# ComboBox Tag
+
+## API reference
+
+### ComboBox.Tag
+
+Name: `ComboBox.Tag`  
+Description: Visual token representing one selected value in multiple selection mode.
+
+| Prop           | Type                              | Default     | Description                          |
+| -------------- | --------------------------------- | ----------- | ------------------------------------ |
+| `children`     | `Snippet`                         | `required`  | Tag content.                         |
+| `class`        | `string`                          | `undefined` | CSS class names for the tag element. |
+| `...restProps` | `HTMLAttributes<HTMLSpanElement>` | `-`         | Additional span attributes.          |
+
+### TagContextProvider (utility)
+
+Name: `TagContextProvider`  
+Description: Internal provider used by `ComboBox.Tags` to expose `id`, `label`, `remove`, and `disabled` to tag sub-parts.
+
+| Prop       | Type               | Default    | Description                             |
+| ---------- | ------------------ | ---------- | --------------------------------------- |
+| `id`       | `string \| number` | `required` | Selected item id.                       |
+| `label`    | `string`           | `required` | Selected item label.                    |
+| `remove`   | `() => void`       | `required` | Removes the selected item.              |
+| `disabled` | `boolean`          | `required` | Disabled state propagated to tag parts. |
+| `children` | `Snippet`          | `required` | Wrapped tag subtree.                    |
+
+### Tag context exports
+
+Name: `TAG_CONTEXT_KEY` / `TagContext`  
+Description: Shared context key and type consumed by `ComboBox.Tag` and `ComboBox.TagRemove`.
+
+| Prop              | Type     | Default                      | Description                                        |
+| ----------------- | -------- | ---------------------------- | -------------------------------------------------- |
+| `TAG_CONTEXT_KEY` | `symbol` | `Symbol.for('combobox-tag')` | Global context key for tag state.                  |
+| `TagContext`      | `type`   | `-`                          | Type with `id`, `label`, `remove`, and `disabled`. |

package/dist/combobox/tag-remove/README.md

@@ -0,0 +1,14 @@
+# ComboBox Tag Remove
+
+## API reference
+
+### ComboBox.TagRemove
+
+Name: `ComboBox.TagRemove`  
+Description: Remove action button for a selected tag.
+
+| Prop           | Type                   | Default     | Description                                                     |
+| -------------- | ---------------------- | ----------- | --------------------------------------------------------------- |
+| `children`     | `Snippet`              | `X icon`    | Custom button content.                                          |
+| `class`        | `string`               | `undefined` | CSS class names for the remove button.                          |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional button attributes, excluding reserved trigger props. |

package/dist/combobox/tag-remove/combobox-tag-remove.svelte

@@ -2,6 +2,7 @@
 	import type { Snippet } from 'svelte';
 	import type { HTMLButtonAttributes } from 'svelte/elements';
 	import { getContext } from 'svelte';
+	import { ButtonRoot } from '../../button/index.js';
 	import { cn } from '../../utils/cn';
 	import { TAG_CONTEXT_KEY, type TagContext } from '../tag/combobox-tag.svelte';
 
@@ -27,7 +28,7 @@
 </script>
 
 {#if !tagCtx.disabled}
-	<button
+	<ButtonRoot
 		type="button"
 		onclick={handleClick}
 		aria-label={`Remove ${tagCtx.label}`}
@@ -49,5 +50,5 @@
 				/>
 			</svg>
 		{/if}
-	</button>
+	</ButtonRoot>
 {/if}

package/dist/combobox/tags/README.md

@@ -0,0 +1,23 @@
+# ComboBox Tags
+
+## API reference
+
+### ComboBox.Tags
+
+Name: `ComboBox.Tags`  
+Description: Container that renders selected values as tags in multiple mode.
+
+| Prop       | Type                           | Default    | Description                                                                       |
+| ---------- | ------------------------------ | ---------- | --------------------------------------------------------------------------------- |
+| `children` | `Snippet<[{ item: TagItem }]>` | `required` | Render function that receives each selected item as `{ item: { value, label } }`. |
+| `class`    | `string`                       | `''`       | CSS class names for the tags container.                                           |
+
+### TagItem type
+
+Name: `TagItem`  
+Description: Item shape provided to `ComboBox.Tags` render snippet.
+
+| Prop    | Type               | Default    | Description                           |
+| ------- | ------------------ | ---------- | ------------------------------------- |
+| `value` | `string \| number` | `required` | Selected value id.                    |
+| `label` | `string`           | `required` | Display label for the selected value. |

package/dist/combobox/trigger/README.md

@@ -0,0 +1,21 @@
+# ComboBox Trigger
+
+## API reference
+
+### ComboBox.Trigger
+
+Name: `ComboBox.Trigger`  
+Description: Optional trigger button that toggles the combobox popover without stealing focus from the input.
+
+| Prop           | Type                   | Default     | Description                                                     |
+| -------------- | ---------------------- | ----------- | --------------------------------------------------------------- |
+| `class`        | `string`               | `undefined` | CSS class names for the trigger element.                        |
+| `children`     | `Snippet`              | `undefined` | Custom trigger content. If omitted, a chevron icon is rendered. |
+| `tabindex`     | `number`               | `-1`        | Tab index applied to the trigger button.                        |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional native button attributes.                            |
+
+## Notes
+
+- `ComboBox.Trigger` reflects the root pending state through `data-pending`.
+- While the combobox is disabled, read-only, or pending, the trigger becomes non-interactive.
+- `ComboBox.Button` remains available as a compatibility alias.

package/dist/combobox/trigger/combobox-trigger.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { useComboBoxContext } from '../root/context';
+
+	type ComboBoxTriggerProps = HTMLButtonAttributes & {
+		class?: string;
+		children?: Snippet;
+	};
+
+	let { class: className, children, tabindex = -1, ...restProps }: ComboBoxTriggerProps = $props();
+
+	const ctx = useComboBoxContext();
+	const isTriggerDisabled = $derived(ctx.isDisabled || ctx.isReadOnly || ctx.isPending);
+
+	function handleMouseDown(event: MouseEvent) {
+		event.preventDefault();
+		if (!isTriggerDisabled) {
+			ctx.toggle();
+		}
+	}
+</script>
+
+<ButtonRoot
+	type="button"
+	{tabindex}
+	aria-label={ctx.isOpen ? 'Close menu' : 'Open menu'}
+	aria-expanded={ctx.isOpen}
+	aria-controls={`combobox-listbox-${ctx.instanceId}`}
+	isDisabled={ctx.isDisabled || ctx.isReadOnly}
+	isPending={ctx.isPending}
+	pressed={ctx.isOpen}
+	onmousedown={handleMouseDown}
+	class={className}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			width="16"
+			height="16"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="2"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			class="transition-transform {ctx.isOpen ? 'rotate-180' : ''}"
+		>
+			<path d="m6 9 6 6 6-6" />
+		</svg>
+	{/if}
+</ButtonRoot>

package/dist/combobox/trigger/combobox-trigger.svelte.d.ts

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

package/dist/datepicker/README.md

@@ -0,0 +1,100 @@
+# DatePicker
+
+## Description
+
+`DatePicker` composes a segmented date input with a calendar popover for selecting dates.
+
+## Anatomy
+
+- `DatePicker.Root`
+- `DatePicker.Input`
+- `DatePicker.Segment`
+- `DatePicker.Trigger`
+- `DatePicker.Popover`
+- `DatePicker.Calendar`
+- `DatePicker.TriggerPrevious`
+- `DatePicker.Heading`
+- `DatePicker.TriggerNext`
+- `DatePicker.Grid`
+- `DatePicker.GridHeader`
+- `DatePicker.HeaderCell`
+- `DatePicker.GridBody`
+- `DatePicker.BodyCell`
+
+```svelte
+<DatePicker.Root>
+	<DatePicker.Input aria-label="Date input">
+		{#snippet children(segment)}
+			<DatePicker.Segment {segment} />
+		{/snippet}
+	</DatePicker.Input>
+	<DatePicker.Trigger />
+
+	<DatePicker.Popover>
+		<DatePicker.Calendar>
+			<div>
+				<DatePicker.TriggerPrevious />
+				<DatePicker.Heading />
+				<DatePicker.TriggerNext />
+			</div>
+			<DatePicker.Grid>
+				<DatePicker.GridHeader />
+				<DatePicker.GridBody />
+			</DatePicker.Grid>
+		</DatePicker.Calendar>
+	</DatePicker.Popover>
+</DatePicker.Root>
+```
+
+## Root API
+
+- `value?: string | null` (`YYYY-MM-DD`)
+- `defaultValue?: string | null` (`YYYY-MM-DD`)
+- `onChange?: (value: string | null) => void`
+- `isDisabled?: boolean`
+- `isReadOnly?: boolean`
+- `minValue?: string` (`YYYY-MM-DD`)
+- `maxValue?: string` (`YYYY-MM-DD`)
+- `isDateUnavailable?: (date: string) => boolean`
+- `open?: boolean`
+- `defaultOpen?: boolean`
+- `onOpenChange?: (open: boolean, details: { reason, event?, cancel(), isCanceled }) => void`
+- `closeOnSelect?: boolean`
+- Null-first empty contract: when `value` and `defaultValue` are omitted, the empty state is `null`.
+- `DatePicker.Input` exposes `aria-invalid` and `data-invalid` when the current segment draft is not committeable.
+
+## Popover API
+
+- `DatePicker.Popover` forwards `Popover.Content` props (for example `placement`, `offset`, `shouldFlip`, `boundaryElement`, `isNonModal`, and close behavior props).
+- The following are controlled internally by `DatePicker` and are not accepted on `DatePicker.Popover`: `open`, `triggerRef`, `onOpenChange`, `id`.
+- Defaults:
+  - `placement` defaults to `bottom-start`.
+  - `aria-label` defaults to `Calendar`.
+  - `initialFocus` defaults to focusing the current active day cell in the calendar grid.
+
+## Calendar API
+
+- `DatePicker.Calendar` forwards `Calendar.Root` props except those controlled by `DatePicker.Root`.
+- The following are controlled internally by `DatePicker` and are not accepted on `DatePicker.Calendar`: `selectionMode`, `value`, `defaultValue`, `onChange`, `isDisabled`, `isReadOnly`, `isDateUnavailable`.
+
+## Notes
+
+- Locale is read from `LocaleProvider` when available.
+- Segment accessible names are resolved automatically from the active locale.
+- During segment editing, the committed value is set to `null` when the draft is incomplete, invalid, out-of-range, or unavailable.
+- Current MVP focuses on date-only values.
+
+## UX Decisions
+
+- **No Date Auto-Correction:** When users manually type dates out of the configured bounds (`minValue`/`maxValue`) or dates that are unavailable, the DatePicker **does not auto-correct** the typed value. Instead, it exposes `aria-invalid="true"` and `data-invalid` on the input, allowing the user to see what they typed incorrectly. The underlying committed value is kept as `null` until a valid date is completed. Auto-correcting input without explicit user consent is an inaccessible anti-pattern.
+- **Navigable Disabled Dates:** When using the Calendar, disabled dates remain focusable via keyboard navigation. This ensures ARIA Grid spatial navigation parity so that screen readers can consistently announce all calendar cells and report them as "disabled", rather than skipping over them and disorienting the user.
+
+## Focus behavior decisions
+
+- DatePicker aligns with the shared modality primitive (`primitives/input-modality.ts`) for `keyboard`, `pointer`, and `virtual` interactions.
+- `data-focus-visible` is modality-driven; `data-focused` and `data-focus-within` continue to represent real DOM focus state.
+- Trigger focus restore after calendar close is modality-aware:
+  - keyboard close paths keep visible focus,
+  - pointer outside close restores focus without visible focus.
+- The component keeps explicit `trackInteractionModality(...)` calls in local handlers to ensure deterministic modality updates before local focus-state logic runs.
+- Cross-component focus contract and invariants are documented in `FOCUS_STATE_CONTRACT.md`.

package/dist/datepicker/TODO.md

@@ -0,0 +1,28 @@
+# DatePicker TODO
+
+## Goal
+
+Track DatePicker work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [M][P0][Area: Context][Owner: Unassigned][Target: Done] Complete core context wiring.
+- [x] [M][P0][Area: State][Owner: Unassigned][Target: Done] Implement root state and value handling.
+- [x] [M][P0][Area: Parsing][Owner: Unassigned][Target: Done] Integrate segment parser and formatter.
+- [x] [M][P0][Area: Input][Owner: Unassigned][Target: Done] Deliver baseline segmented input rendering.
+- [x] [M][P0][Area: Composition][Owner: Unassigned][Target: Done] Integrate calendar popover behavior.
+- [x] [M][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Implement keyboard navigation baseline.
+- [x] [M][P0][Area: Validation][Owner: Unassigned][Target: Done] Implement min/max and unavailable date validation baseline.
+- [x] [M][P0][Area: API][Owner: Unassigned][Target: Done] Ship public exports and baseline docs/tests.
+- [x] [M][P0][Area: Forms][Owner: Unassigned][Target: Done] Support rich object values and hidden input synchronization.
+- [x] [M][P0][Area: Focus][Owner: Unassigned][Target: Done] Unify focus-visible behavior with shared modality semantics.
+- [x] [S][P1][Area: Focus][Owner: Unassigned][Target: Done] Remove DatePicker-local modality tracking in favor of shared primitive.
+- [x] [S][P1][Area: Documentation][Owner: Unassigned][Target: Done] Document focus contract updates and DatePicker rationale.
+- [ ] [S][P1][Area: Calendar][Owner: Unassigned][Target: TBD] Add multi-month calendar display.
+- [ ] [S][P1][Area: Accessibility][Owner: Unassigned][Target: TBD] Run deep accessibility audit (SR + keyboard edge cases).
+- [ ] [C][P2][Area: Time][Owner: Unassigned][Target: TBD] Add time selection integration.
+- [ ] [C][P2][Area: API][Owner: Unassigned][Target: TBD] Decide and implement date-range mode strategy.
+- [ ] [C][P2][Area: Input][Owner: Unassigned][Target: TBD] Add input mask helper utilities.
+- [ ] [C][P2][Area: Mobile][Owner: Unassigned][Target: TBD] Add mobile-optimized interaction pass.
+- [ ] [C][P2][Area: UX][Owner: Unassigned][Target: TBD] Add preset shortcuts (today, next week, custom).
+- [ ] [C][P2][Area: Performance][Owner: Unassigned][Target: TBD] Add segment update micro-benchmarks and optimizations.

package/dist/datepicker/calendar/README.md

@@ -0,0 +1,19 @@
+# DatePicker Calendar
+
+## API reference
+
+### DatePicker.Calendar
+
+Name: `DatePicker.Calendar`  
+Description: Calendar composition part connected to `DatePicker.Root` selected date and navigation state.
+
+| Prop           | Type                                                                                                                                                            | Default     | Description                                            |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------ |
+| `children`     | `Snippet`                                                                                                                                                       | `undefined` | Optional custom calendar content.                      |
+| `class`        | `string`                                                                                                                                                        | `''`        | CSS class names for the calendar wrapper.              |
+| `...restProps` | `Omit<ComponentProps<typeof Calendar.Root>, 'selectionMode' \| 'value' \| 'defaultValue' \| 'onChange' \| 'isDisabled' \| 'isReadOnly' \| 'isDateUnavailable'>` | `-`         | Additional calendar root props forwarded by this part. |
+
+### Notes
+
+Name: Root-controlled calendar props  
+Description: `selectionMode`, `value`, `defaultValue`, `onChange`, `isDisabled`, `isReadOnly`, and `isDateUnavailable` are controlled by `DatePicker.Root` and ignored when passed to this part.

package/dist/datepicker/calendar/date-picker-calendar-unsafe-props-test.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+	import DatePicker from '../index';
+
+	let unsafeOnChangeCalls = $state(0);
+	let selectedValue = $state<string | null>('');
+
+	const unsafeCalendarProps: Record<string, unknown> = {
+		selectionMode: 'range',
+		value: { start: '2026-02-01', end: '2026-02-05' },
+		defaultValue: '2026-02-20',
+		onChange: () => {
+			unsafeOnChangeCalls += 1;
+		},
+		isDisabled: true,
+		isReadOnly: true,
+		isDateUnavailable: () => true
+	};
+</script>
+
+<DatePicker.Root
+	defaultValue="2026-02-10"
+	defaultOpen={true}
+	onChange={(nextValue) => {
+		selectedValue = nextValue;
+	}}
+>
+	<DatePicker.Input class="date-picker-input" aria-label="Date input">
+		{#snippet children(segment)}
+			<DatePicker.Segment class="date-picker-segment" {segment} />
+		{/snippet}
+	</DatePicker.Input>
+	<DatePicker.Trigger class="date-picker-trigger">Open calendar</DatePicker.Trigger>
+
+	<DatePicker.Popover class="date-picker-popover">
+		<DatePicker.Calendar class="date-picker-calendar" {...unsafeCalendarProps}>
+			<div class="flex items-center justify-between gap-2 p-2">
+				<DatePicker.TriggerPrevious />
+				<DatePicker.Heading />
+				<DatePicker.TriggerNext />
+			</div>
+			<DatePicker.Grid>
+				<DatePicker.GridHeader>
+					{#snippet children(dayLabel: string)}
+						<DatePicker.HeaderCell>
+							{dayLabel}
+						</DatePicker.HeaderCell>
+					{/snippet}
+				</DatePicker.GridHeader>
+				<DatePicker.GridBody>
+					{#snippet children(date: string)}
+						<DatePicker.BodyCell {date} />
+					{/snippet}
+				</DatePicker.GridBody>
+			</DatePicker.Grid>
+		</DatePicker.Calendar>
+	</DatePicker.Popover>
+</DatePicker.Root>
+
+<p data-testid="unsafe-on-change-calls">{unsafeOnChangeCalls}</p>
+<p data-testid="selected-value">{selectedValue}</p>

package/dist/datepicker/calendar/date-picker-calendar-unsafe-props-test.svelte.d.ts

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