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

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,11 @@
 
 	// 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);
+	let shouldCloseOnEscapeState = $state(true);
+	let shouldCloseOnBlurState = $state(true);
 
 	// Flag to control whether inputValue should be used for filtering
 	// When false, all items are shown regardless of inputValue
@@ -188,6 +199,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 {
@@ -199,17 +211,26 @@
 		}
 	}
 
+	function syncInputValue(val: string, options?: { notifyInputChange?: boolean }) {
+		inputValueInternal = val;
+		inputValue = val;
+
+		if (options?.notifyInputChange ?? true) {
+			onInputChange?.(val);
+		}
+	}
+
 	function selectItem(id: string | number, label: string) {
 		let newSelection: Set<string | number>;
 
 		if (selectionMode === 'single') {
 			newSelection = new Set([id]);
+			shouldFilter = false;
 			// Save the label persistently for restore on blur/escape
 			selectedLabel = label;
-			// Update input directly without triggering deselection
-			inputValueInternal = label;
-			inputValue = label;
-			onInputChange?.(label);
+			// Keep the selected label visible in the input without re-triggering
+			// external filtering during the popover close animation.
+			syncInputValue(label, { notifyInputChange: false });
 			if (effectiveCloseOnSelect) {
 				closePopover(true); // Close and keep focus on input
 			}
@@ -236,6 +257,7 @@
 			}
 		}
 
+		selectedInternal = newSelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(newSelection));
 		} else {
@@ -257,6 +279,7 @@
 		// Remove from persistent labels
 		selectedLabels.delete(id);
 
+		selectedInternal = newSelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(newSelection));
 		} else {
@@ -274,6 +297,7 @@
 	function clearSelection() {
 		const emptySelection = new Set<string | number>();
 
+		selectedInternal = emptySelection;
 		if (isSelectionControlled) {
 			onChange?.(toExternalValue(emptySelection));
 		} else {
@@ -303,6 +327,8 @@
 					onInputChange?.('');
 				}
 				// Otherwise user typed, keep their filter
+			} else {
+				shouldFilter = true;
 			}
 			setIsOpen(true);
 			// Auto-focus the selected item when opening with a selection
@@ -318,8 +344,6 @@
 		setIsOpen(false);
 		// Reset navigation state
 		navigation.reset();
-		// Re-enable filtering for next open
-		shouldFilter = true;
 		// Only refocus input when explicitly requested (e.g., after selection)
 		// Never refocus in focus mode to prevent re-opening
 		if (refocusInput && trigger !== 'focus') {
@@ -335,9 +359,40 @@
 		}
 	}
 
+	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) {
+			if (listboxCtxRef?.isDisabled(navigation.focusedId)) {
+				return;
+			}
 			const label = navigation.itemLabels.get(navigation.focusedId) ?? String(navigation.focusedId);
 			selectItem(navigation.focusedId, label);
 		}
@@ -346,9 +401,29 @@
 	/**
 	 * 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;
+		}
+
+		if (!shouldCloseOnBlurState) {
+			return;
+		}
 		// Close popover first to prevent flash of options when clearing input
 		closePopover();
 
@@ -376,15 +451,14 @@
 		if (currentSelection.size > 0 && selectedLabel) {
 			if (selectedLabel !== currentInputValue) {
 				// Restore the selected label
-				inputValueInternal = selectedLabel;
-				inputValue = selectedLabel;
-				onInputChange?.(selectedLabel);
+				syncInputValue(selectedLabel, { notifyInputChange: false });
 			}
 		}
 	}
 
 	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') {
@@ -552,14 +626,16 @@
 				}
 				break;
 			case 'Escape':
-				if (currentIsOpen) {
+				if (currentIsOpen && shouldCloseOnEscapeState) {
 					closePopover(true); // Keep focus on input after Escape
 					// Stop propagation so parent dialogs don't also close
 					event.stopPropagation();
 					event.stopImmediatePropagation();
+					handleInputBlur();
+					// Escape is a keyboard-only path, so focus-visible remains enabled for the input.
+					focusVisible = true;
+					event.preventDefault();
 				}
-				handleInputBlur();
-				event.preventDefault();
 				break;
 			case 'Backspace':
 				// In multiple mode, remove last tag when input is empty
@@ -604,6 +680,18 @@
 		get isDisabled() {
 			return isDisabled;
 		},
+		get isPending() {
+			return isPending;
+		},
+		get isFocusVisible() {
+			return focusVisible;
+		},
+		get shouldCloseOnEscape() {
+			return shouldCloseOnEscapeState;
+		},
+		get shouldCloseOnBlur() {
+			return shouldCloseOnBlurState;
+		},
 		get isReadOnly() {
 			return isReadOnly;
 		},
@@ -668,11 +756,22 @@
 		unregisterItem: navigation.unregister,
 		handleKeydown,
 		handleInputBlur,
+		setFocusVisible: setFocusVisibleState,
 		get focusedTagId() {
 			return focusedTagId;
 		},
 		setFocusedTagId: (id: string | number | null) => {
 			focusedTagId = id;
+		},
+		markPopoverPointerDown: () => {
+			popoverPointerDownPending = true;
+		},
+		consumePopoverPointerDown,
+		setShouldCloseOnEscape: (value: boolean) => {
+			shouldCloseOnEscapeState = value;
+		},
+		setShouldCloseOnBlur: (value: boolean) => {
+			shouldCloseOnBlurState = value;
 		}
 	};
 
@@ -684,11 +783,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,10 @@ 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 focus should currently be presented as keyboard-visible */
+    isFocusVisible: boolean;
     /** Whether the combobox is read-only */
     isReadOnly: boolean;
     /** Selection mode */
@@ -79,11 +83,25 @@ 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;
+    /** Whether Escape should close the popover. */
+    shouldCloseOnEscape: boolean;
+    /** Whether blur should close the popover. */
+    shouldCloseOnBlur: boolean;
+    /** Update whether Escape should close the popover. */
+    setShouldCloseOnEscape: (value: boolean) => void;
+    /** Update whether blur should close the popover. */
+    setShouldCloseOnBlur: (value: boolean) => void;
 };
 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-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/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;