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

package/dist/datepicker/segment/date-picker-segment.svelte

@@ -0,0 +1,319 @@
+<script module lang="ts">
+	const monthFormatterCache: Record<string, Intl.DateTimeFormat> = Object.create(null);
+
+	function getMonthFormatter(locale: string): Intl.DateTimeFormat {
+		let formatter = monthFormatterCache[locale];
+		if (!formatter) {
+			formatter = new Intl.DateTimeFormat(locale, {
+				month: 'long',
+				timeZone: 'UTC'
+			});
+			monthFormatterCache[locale] = formatter;
+		}
+		return formatter;
+	}
+</script>
+
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import type { DatePickerSegmentPart } from '../root/context';
+	import { useDatePickerContext } from '../root/context';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+
+	type DatePickerSegmentProps = Omit<
+		HTMLAttributes<HTMLSpanElement>,
+		| 'children'
+		| 'class'
+		| 'id'
+		| 'role'
+		| 'contenteditable'
+		| 'tabindex'
+		| 'aria-label'
+		| 'aria-labelledby'
+		| 'aria-valuemin'
+		| 'aria-valuemax'
+		| 'aria-valuenow'
+		| 'aria-valuetext'
+		| 'aria-readonly'
+		| 'aria-disabled'
+		| 'onfocus'
+		| 'onblur'
+		| 'onmousedown'
+		| 'onclick'
+		| 'onselectstart'
+		| 'onkeydown'
+	> & {
+		segment: DatePickerSegmentPart;
+		class?: string;
+	};
+
+	let { segment, class: className = '', ...restProps }: DatePickerSegmentProps = $props();
+	let isFocused = $state(false);
+	let segmentRef: HTMLSpanElement | null = $state(null);
+
+	const datePicker = useDatePickerContext();
+
+	const isEditableSegment = $derived(segment.type !== 'literal');
+	const isActive = $derived(
+		isEditableSegment && (datePicker.activeSegment === segment.type || isFocused)
+	);
+	const isFocusVisible = $derived(isFocused && datePicker.focusVisible);
+	const segmentId = $props.id();
+
+	const currentNumericValue = $derived.by(() => {
+		if (segment.type === 'literal') return undefined;
+		const segmentValue = datePicker.getSegmentValue(segment.type);
+		if (segmentValue.length === 0) return undefined;
+		const value = Number(segmentValue);
+		return Number.isFinite(value) ? value : undefined;
+	});
+
+	const valueMin = $derived.by(() => {
+		if (segment.type === 'literal') return undefined;
+		if (segment.type === 'month') return 1;
+		if (segment.type === 'day') return 1;
+		return 1;
+	});
+
+	const valueMax = $derived.by(() => {
+		if (segment.type === 'literal') return undefined;
+		if (segment.type === 'month') return 12;
+		if (segment.type === 'day') return 31;
+		return 9999;
+	});
+
+	const valueText = $derived.by(() => {
+		if (segment.type === 'literal') return segment.text;
+		if (segment.type === 'month' && currentNumericValue) {
+			const monthLabel = getMonthFormatter(datePicker.locale).format(
+				new Date(Date.UTC(2030, currentNumericValue - 1, 1))
+			);
+			return `${currentNumericValue} - ${monthLabel}`;
+		}
+		return segment.text;
+	});
+
+	const segmentLabel = $derived.by(() => {
+		if (segment.type === 'literal') return undefined;
+		return datePicker.getSegmentLabel(segment.type);
+	});
+
+	$effect(() => {
+		if (segment.type === 'literal') return;
+		const segmentType = segment.type;
+		datePicker.registerSegmentRef(segmentType, segmentRef);
+		return () => {
+			datePicker.registerSegmentRef(segmentType, null);
+		};
+	});
+
+	function handleFocus(event: FocusEvent) {
+		if (segment.type === 'literal') return;
+		if (datePicker.isDisabled) {
+			isFocused = false;
+			return;
+		}
+		isFocused = true;
+		datePicker.syncFocusWithin();
+		datePicker.setFocusVisible(shouldShowFocusVisible(event.currentTarget as HTMLElement));
+		datePicker.setActiveSegment(segment.type);
+	}
+
+	function handleBlur() {
+		if (segment.type === 'literal') return;
+		isFocused = false;
+		queueMicrotask(() => {
+			datePicker.syncFocusWithin();
+		});
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		if (segment.type === 'literal') return;
+		if (datePicker.isDisabled) {
+			event.preventDefault();
+			return;
+		}
+		trackInteractionModality(event, event.currentTarget as HTMLElement);
+		datePicker.setFocusVisible(false);
+		event.preventDefault();
+		const target = event.currentTarget as HTMLElement;
+		target.focus();
+		datePicker.setActiveSegment(segment.type);
+	}
+
+	function handleClick(event: MouseEvent) {
+		if (segment.type === 'literal') return;
+		if (datePicker.isDisabled) {
+			event.preventDefault();
+			return;
+		}
+		const target = event.currentTarget as HTMLElement;
+		target.focus();
+		datePicker.setActiveSegment(segment.type);
+	}
+
+	function handleSelectStart(event: Event) {
+		if (!segment.isPlaceholder) return;
+		event.preventDefault();
+	}
+
+	function handleKeydown(event: KeyboardEvent) {
+		if (segment.type === 'literal') return;
+		if (datePicker.isDisabled) return;
+		trackInteractionModality(event, event.currentTarget as HTMLElement);
+		datePicker.setFocusVisible(true);
+
+		if (event.key === 'ArrowRight') {
+			event.preventDefault();
+			if (!datePicker.focusNextSegment(segment.type)) {
+				datePicker.triggerRef?.focus();
+			}
+			return;
+		}
+
+		if (event.key === 'ArrowLeft') {
+			event.preventDefault();
+			datePicker.focusPreviousSegment(segment.type);
+			return;
+		}
+
+		if (event.key === 'ArrowUp') {
+			event.preventDefault();
+			datePicker.adjustSegmentValue(segment.type, 1);
+			return;
+		}
+
+		if (event.key === 'ArrowDown') {
+			event.preventDefault();
+			datePicker.adjustSegmentValue(segment.type, -1);
+			return;
+		}
+
+		if (event.key === 'PageUp') {
+			event.preventDefault();
+			const step = segment.type === 'year' ? 10 : 5;
+			datePicker.adjustSegmentValue(segment.type, step);
+			return;
+		}
+
+		if (event.key === 'PageDown') {
+			event.preventDefault();
+			const step = segment.type === 'year' ? 10 : 5;
+			datePicker.adjustSegmentValue(segment.type, -step);
+			return;
+		}
+
+		if (event.key === 'Home') {
+			event.preventDefault();
+			if (segment.type === 'month') {
+				datePicker.setSegmentValue('month', '1');
+			} else if (segment.type === 'day') {
+				datePicker.setSegmentValue('day', '1');
+			} else {
+				datePicker.setSegmentValue('year', '1');
+			}
+			return;
+		}
+
+		if (event.key === 'End') {
+			event.preventDefault();
+			if (segment.type === 'month') {
+				datePicker.setSegmentValue('month', '12');
+			} else if (segment.type === 'day') {
+				datePicker.setSegmentValue('day', '31');
+			} else {
+				datePicker.setSegmentValue('year', '9999');
+			}
+			return;
+		}
+
+		if (event.key === 'Delete' || event.key === 'Backspace') {
+			event.preventDefault();
+			const currentValue = datePicker.getSegmentValue(segment.type);
+			if (currentValue.length === 0) {
+				if (event.key === 'Backspace') {
+					datePicker.focusPreviousSegment(segment.type);
+				}
+				return;
+			}
+			datePicker.setSegmentValue(segment.type, currentValue.slice(0, -1));
+			return;
+		}
+
+		if (event.key.length === 1 && /\d/.test(event.key)) {
+			event.preventDefault();
+			const didComplete = datePicker.typeSegmentDigit(segment.type, event.key);
+			if (didComplete) {
+				datePicker.focusNextSegment(segment.type);
+			}
+			return;
+		}
+
+		if (event.key === '/' || event.key === '-' || event.key === '.') {
+			event.preventDefault();
+			const currentValue = datePicker.getSegmentValue(segment.type);
+			if (currentValue.length === 0) {
+				return;
+			}
+			datePicker.focusNextSegment(segment.type);
+			return;
+		}
+
+		if (event.key === 'Tab') {
+			return;
+		}
+
+		event.preventDefault();
+	}
+</script>
+
+{#if segment.type === 'literal'}
+	<span
+		class={className}
+		{...restProps}
+		data-placeholder={segment.isPlaceholder || undefined}
+		data-type={segment.type}
+		aria-hidden="true"
+	>
+		{segment.text}
+	</span>
+{:else}
+	<span
+		bind:this={segmentRef}
+		id={segmentId}
+		class={className}
+		{...restProps}
+		data-date-picker-segment="true"
+		data-placeholder={segment.isPlaceholder || undefined}
+		data-type={segment.type}
+		data-focused={isActive ? 'true' : undefined}
+		data-focus-visible={isFocusVisible ? 'true' : undefined}
+		role="spinbutton"
+		aria-valuetext={valueText}
+		aria-valuemin={valueMin}
+		aria-valuemax={valueMax}
+		aria-valuenow={currentNumericValue}
+		aria-label={segmentLabel}
+		aria-readonly={datePicker.isReadOnly || undefined}
+		aria-disabled={datePicker.isDisabled || undefined}
+		contenteditable={!datePicker.isDisabled && !datePicker.isReadOnly}
+		spellcheck="false"
+		enterkeyhint="next"
+		inputmode="numeric"
+		tabindex={datePicker.isDisabled ? -1 : 0}
+		style={segment.isPlaceholder
+			? 'caret-color: transparent; user-select: none;'
+			: 'caret-color: transparent;'}
+		onfocus={handleFocus}
+		onblur={handleBlur}
+		onmousedown={handleMouseDown}
+		onclick={handleClick}
+		onselectstart={handleSelectStart}
+		onkeydown={handleKeydown}
+	>
+		{segment.text}
+	</span>
+{/if}

package/dist/datepicker/segment/date-picker-segment.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { DatePickerSegmentPart } from '../root/context';
+type DatePickerSegmentProps = Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'class' | 'id' | 'role' | 'contenteditable' | 'tabindex' | 'aria-label' | 'aria-labelledby' | 'aria-valuemin' | 'aria-valuemax' | 'aria-valuenow' | 'aria-valuetext' | 'aria-readonly' | 'aria-disabled' | 'onfocus' | 'onblur' | 'onmousedown' | 'onclick' | 'onselectstart' | 'onkeydown'> & {
+    segment: DatePickerSegmentPart;
+    class?: string;
+};
+declare const DatePickerSegment: import("svelte").Component<DatePickerSegmentProps, {}, "">;
+type DatePickerSegment = ReturnType<typeof DatePickerSegment>;
+export default DatePickerSegment;

package/dist/datepicker/trigger/README.md

@@ -0,0 +1,14 @@
+# DatePicker Trigger
+
+## API reference
+
+### DatePicker.Trigger
+
+Name: `DatePicker.Trigger`  
+Description: Button part that toggles `DatePicker.Popover` and anchors positioning/focus behavior.
+
+| 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/datepicker/trigger/date-picker-trigger.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { useDatePickerContext } from '../root/context';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+
+	type DatePickerTriggerProps = Omit<
+		HTMLButtonAttributes,
+		'type' | 'children' | 'class' | 'onclick' | 'aria-haspopup' | 'aria-expanded'
+	> & {
+		children?: Snippet;
+		class?: string;
+	};
+
+	let { children, class: className = '', ...restProps }: DatePickerTriggerProps = $props();
+
+	let buttonRef: HTMLButtonElement | null = $state(null);
+	let isFocused = $state(false);
+	const datePicker = useDatePickerContext();
+
+	$effect(() => {
+		if (datePicker.isReadOnly) {
+			datePicker.setTriggerRef(null);
+			return;
+		}
+		if (buttonRef) {
+			datePicker.setTriggerRef(buttonRef);
+		}
+	});
+
+	function handleFocus() {
+		if (datePicker.isDisabled) {
+			isFocused = false;
+			return;
+		}
+		if (buttonRef) {
+			datePicker.setTriggerRef(buttonRef);
+			datePicker.setActiveSegment(null);
+			isFocused = true;
+			datePicker.syncFocusWithin();
+			datePicker.setFocusVisible(shouldShowFocusVisible(buttonRef));
+		}
+	}
+
+	function handleBlur() {
+		isFocused = false;
+		queueMicrotask(() => {
+			datePicker.syncFocusWithin();
+		});
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		if (datePicker.isDisabled || datePicker.isReadOnly) return;
+		trackInteractionModality(event, buttonRef);
+		datePicker.setFocusVisible(false);
+		event.preventDefault();
+	}
+
+	function handleClick(event: MouseEvent) {
+		if (datePicker.isDisabled || datePicker.isReadOnly) return;
+		if (event.detail > 0) {
+			trackInteractionModality(event, buttonRef);
+		}
+		if (buttonRef) {
+			datePicker.setTriggerRef(buttonRef);
+		}
+		datePicker.togglePopover('trigger-press', event);
+	}
+
+	function handleKeydown(event: KeyboardEvent) {
+		if (datePicker.isDisabled) return;
+		trackInteractionModality(event, buttonRef);
+		if (event.key === 'Enter' || event.key === ' ') {
+			datePicker.setFocusVisible(true);
+			return;
+		}
+		if (event.key !== 'ArrowLeft') return;
+		datePicker.setFocusVisible(true);
+
+		event.preventDefault();
+		datePicker.focusLastSegment();
+	}
+</script>
+
+{#if !datePicker.isReadOnly}
+	<ButtonRoot
+		bind:element={buttonRef}
+		type="button"
+		isDisabled={datePicker.isDisabled}
+		class={className}
+		aria-haspopup="dialog"
+		aria-expanded={datePicker.open}
+		data-focused={isFocused || undefined}
+		data-focus-visible={isFocused && datePicker.focusVisible ? 'true' : undefined}
+		onmousedown={handleMouseDown}
+		onfocus={handleFocus}
+		onblur={handleBlur}
+		onkeydown={handleKeydown}
+		onclick={handleClick}
+		{...restProps}
+	>
+		{#if children}
+			{@render children()}
+		{/if}
+	</ButtonRoot>
+{/if}

package/dist/datepicker/trigger/date-picker-trigger.svelte.d.ts

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

package/dist/dialog/README.md

@@ -0,0 +1,35 @@
+# Dialog
+
+## Description
+
+`Dialog` provides an accessible modal pattern with trigger, portal, overlay, and content parts. It includes nested dialog stacking so only the topmost dialog handles global close interactions.
+
+## Usage guidelines
+
+- Place all dialog parts inside `Dialog.Root`.
+- Use `Dialog.Trigger` to wire the opener button.
+- Render modal layers inside `Dialog.Portal`.
+- Use `Dialog.Overlay` and `Dialog.Content` together for standard modal behavior.
+- Use nested `Dialog.Root` instances when you need modal stacks; topmost behavior is handled internally.
+
+## Anatomy
+
+Import the component and compose its parts:
+
+```svelte
+<Dialog.Root>
+	<Dialog.Trigger>
+		<button>Open</button>
+	</Dialog.Trigger>
+	<Dialog.Portal>
+		<Dialog.Overlay />
+		<Dialog.Content>...</Dialog.Content>
+	</Dialog.Portal>
+</Dialog.Root>
+```
+
+- `Dialog.Root`
+- `Dialog.Trigger`
+- `Dialog.Portal`
+- `Dialog.Overlay`
+- `Dialog.Content`

package/dist/dialog/content/README.md

@@ -0,0 +1,16 @@
+# Dialog Content
+
+## API reference
+
+### Dialog.Content
+
+Name: `Dialog.Content`  
+Description: Modal panel part that applies focus trapping, outside-click handling, scroll lock, aria outside hiding, and topmost stack guards.
+
+| Prop                           | Type                             | Default     | Description                                                  |
+| ------------------------------ | -------------------------------- | ----------- | ------------------------------------------------------------ |
+| `children`                     | `Snippet`                        | `undefined` | Dialog body content.                                         |
+| `class`                        | `string`                         | `''`        | CSS class names for the dialog panel.                        |
+| `shouldCloseOnInteractOutside` | `boolean`                        | `true`      | Enables closing when clicking outside (topmost dialog only). |
+| `shouldCloseOnEscape`          | `boolean`                        | `true`      | Enables closing on Escape key (topmost dialog only).         |
+| `...restProps`                 | `HTMLAttributes<HTMLDivElement>` | `-`         | Additional dialog panel attributes.                          |

package/dist/dialog/content/dialog-content.svelte

@@ -45,16 +45,16 @@
 	let dialogId: symbol | null = null;
 	let dialogLevel = $state(0);
 
-	function close() {
-		dialogCtx.close();
+	function close(reason: 'escape-key' | 'outside-press' | 'imperative-action', event?: Event) {
+		dialogCtx.close(reason, event);
 	}
 
 	/**
 	 * Wrapper for close that only executes if this is the topmost dialog.
 	 */
-	function closeIfTopmost() {
+	function closeIfTopmost(event: MouseEvent) {
 		if (dialogId && isTopmostDialog(dialogId)) {
-			close();
+			close('outside-press', event);
 		}
 	}
 
@@ -63,7 +63,7 @@
 			// Only handle if this is the topmost dialog
 			if (dialogId && isTopmostDialog(dialogId)) {
 				event.preventDefault();
-				close();
+				close('escape-key', event);
 			}
 		}
 	}
@@ -71,7 +71,7 @@
 	onMount(() => {
 		if (!browser) return;
 		// Register this dialog in the stack
-		const { id, level } = pushDialog(close);
+		const { id, level } = pushDialog(() => close('imperative-action'));
 		dialogId = id;
 		dialogLevel = level;
 		// Share level with overlay via context

package/dist/dialog/index.d.ts

@@ -1,4 +1,4 @@
-import * as DialogParts from './index.parts.ts';
+import * as DialogParts from './index.parts.js';
 export declare const Dialog: typeof DialogParts;
 export default DialogParts;
 export { default as DialogRoot } from './root/dialog-root.svelte';
@@ -6,5 +6,5 @@ export { default as DialogTrigger } from './trigger/dialog-trigger.svelte';
 export { default as DialogPortal } from './portal/dialog-portal.svelte';
 export { default as DialogOverlay } from './overlay/dialog-overlay.svelte';
 export { default as DialogContent } from './content/dialog-content.svelte';
-export { getDialogContext, setDialogContext, type DialogContext } from './root/context';
-export type { DialogStateHelpers } from './root/types';
+export { getDialogContext, setDialogContext, type DialogContext } from './root/context.js';
+export type { DialogStateHelpers } from './root/types.js';

package/dist/dialog/index.js

@@ -1,6 +1,6 @@
 // Dialog component with namespace pattern
 // Usage: <Dialog.Root>, <Dialog.Trigger>, <Dialog.Portal>, <Dialog.Overlay>, <Dialog.Content>
-import * as DialogParts from './index.parts.ts';
+import * as DialogParts from './index.parts.js';
 // Named export for namespace usage: import { Dialog } from '...'
 export const Dialog = DialogParts;
 // Default export for backwards compatibility
@@ -12,4 +12,4 @@ export { default as DialogPortal } from './portal/dialog-portal.svelte';
 export { default as DialogOverlay } from './overlay/dialog-overlay.svelte';
 export { default as DialogContent } from './content/dialog-content.svelte';
 // Re-export context utilities
-export { getDialogContext, setDialogContext } from './root/context';
+export { getDialogContext, setDialogContext } from './root/context.js';

package/dist/dialog/overlay/README.md

@@ -0,0 +1,13 @@
+# Dialog Overlay
+
+## API reference
+
+### Dialog.Overlay
+
+Name: `Dialog.Overlay`  
+Description: Backdrop layer behind dialog content. Z-index is derived from dialog stack level.
+
+| Prop           | Type                             | Default | Description                      |
+| -------------- | -------------------------------- | ------- | -------------------------------- |
+| `class`        | `string`                         | `''`    | CSS class names for the overlay. |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`     | Additional overlay attributes.   |

package/dist/dialog/portal/README.md

@@ -0,0 +1,12 @@
+# Dialog Portal
+
+## API reference
+
+### Dialog.Portal
+
+Name: `Dialog.Portal`  
+Description: Portal wrapper that renders dialog layers only while `Dialog.Root` is open.
+
+| Prop       | Type      | Default     | Description                                                      |
+| ---------- | --------- | ----------- | ---------------------------------------------------------------- |
+| `children` | `Snippet` | `undefined` | Portaled content, usually `Dialog.Overlay` and `Dialog.Content`. |

package/dist/dialog/root/README.md

@@ -0,0 +1,53 @@
+# Dialog Root
+
+## API reference
+
+### Dialog.Root
+
+Name: `Dialog.Root`  
+Description: Dialog state container for open state, trigger ref, and root-level open/close/toggle actions.
+
+| Prop           | Type                            | Default     | Description                                             |
+| -------------- | ------------------------------- | ----------- | ------------------------------------------------------- |
+| `open`         | `boolean`                       | `undefined` | Controlled open state. Supports `bind:open`.            |
+| `defaultOpen`  | `boolean`                       | `false`     | Initial open state in uncontrolled mode.                |
+| `onOpenChange` | `(open: boolean) => void`       | `undefined` | Called whenever open state changes.                     |
+| `triggerRef`   | `HTMLElement \| null`           | `null`      | Trigger reference. Supports `bind:triggerRef`.          |
+| `children`     | `Snippet<[DialogStateHelpers]>` | `undefined` | Root render snippet that receives dialog state helpers. |
+
+### Context utilities
+
+Name: `context.ts` helpers  
+Description: Context APIs shared by trigger, portal, overlay, and content parts.
+
+| Prop               | Type                               | Default | Description                                     |
+| ------------------ | ---------------------------------- | ------- | ----------------------------------------------- |
+| `setDialogContext` | `(ctx: DialogContext) => void`     | `-`     | Registers dialog context.                       |
+| `getDialogContext` | `() => DialogContext \| undefined` | `-`     | Returns dialog context when available.          |
+| `DialogContext`    | `type`                             | `-`     | Context contract with dialog state and actions. |
+
+### DialogStateHelpers type
+
+Name: `DialogStateHelpers`  
+Description: Helper object passed to the `children` snippet in `Dialog.Root`.
+
+| Prop     | Type         | Default | Description         |
+| -------- | ------------ | ------- | ------------------- |
+| `close`  | `() => void` | `-`     | Closes the dialog.  |
+| `open`   | `() => void` | `-`     | Opens the dialog.   |
+| `toggle` | `() => void` | `-`     | Toggles open state. |
+| `isOpen` | `boolean`    | `-`     | Current open state. |
+
+### Stack utilities
+
+Name: `dialog-stack.ts`  
+Description: Internal global stack utilities used by `Dialog.Content` and `Dialog.Overlay` to support nested dialogs.
+
+| Prop               | Type                                                   | Default                 | Description                                            |
+| ------------------ | ------------------------------------------------------ | ----------------------- | ------------------------------------------------------ |
+| `pushDialog`       | `(close: () => void) => { id: symbol; level: number }` | `-`                     | Registers an opened dialog and returns stack id/level. |
+| `popDialog`        | `(id: symbol) => void`                                 | `-`                     | Unregisters a dialog by id.                            |
+| `isTopmostDialog`  | `(id: symbol) => boolean`                              | `-`                     | Returns whether a dialog is currently topmost.         |
+| `getOverlayZIndex` | `(level: number) => number`                            | `BASE + level * 10`     | Computes overlay z-index for a stack level.            |
+| `getContentZIndex` | `(level: number) => number`                            | `BASE + level * 10 + 1` | Computes content z-index for a stack level.            |
+| `getDialogCount`   | `() => number`                                         | `-`                     | Returns the number of currently open dialogs.          |

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

@@ -1,3 +1,4 @@
+export type DialogCloseReason = 'escape-key' | 'outside-press' | 'imperative-action' | 'none';
 /**
  * Context shared between Dialog components (Root, Trigger, Content).
  */
@@ -13,7 +14,7 @@ export type DialogContext = {
     /** Open the dialog */
     open: () => void;
     /** Close the dialog and return focus to trigger */
-    close: () => void;
+    close: (reason?: DialogCloseReason, event?: Event) => void;
     /** Called when dialog open state changes */
     onOpenChange: (open: boolean) => void;
     /** Stack level for z-index calculation (set by Content) */