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

package/dist/dialog/overlay/dialog-overlay.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * Dialog.Overlay - The backdrop overlay behind the dialog.
+ * Must be used inside a Dialog.Portal.
+ */
+type DialogOverlayProps = {
+    /** CSS class for the overlay. */
+    class?: string;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'class'>;
+declare const DialogOverlay: import("svelte").Component<DialogOverlayProps, {}, "">;
+type DialogOverlay = ReturnType<typeof DialogOverlay>;
+export default DialogOverlay;

package/dist/dialog/portal/dialog-portal.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { Portal } from '../../portal';
+	import { getDialogContext } from '../root/context';
+
+	/**
+	 * Dialog.Portal - Renders children into a portal when dialog is open.
+	 * Must be used inside a Dialog.Root.
+	 */
+	type DialogPortalProps = {
+		/** Content to render in portal (Overlay and Content) */
+		children?: Snippet;
+	};
+
+	let { children }: DialogPortalProps = $props();
+
+	const ctx = getDialogContext();
+
+	if (!ctx) {
+		throw new Error('Dialog.Portal must be used inside a Dialog.Root');
+	}
+
+	const dialogCtx = ctx;
+</script>
+
+{#if dialogCtx.isOpen}
+	<Portal>
+		{#if children}
+			{@render children()}
+		{/if}
+	</Portal>
+{/if}

package/dist/dialog/portal/dialog-portal.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+/**
+ * Dialog.Portal - Renders children into a portal when dialog is open.
+ * Must be used inside a Dialog.Root.
+ */
+type DialogPortalProps = {
+    /** Content to render in portal (Overlay and Content) */
+    children?: Snippet;
+};
+declare const DialogPortal: import("svelte").Component<DialogPortalProps, {}, "">;
+type DialogPortal = ReturnType<typeof DialogPortal>;
+export default DialogPortal;

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

@@ -0,0 +1,25 @@
+/**
+ * Context shared between Dialog components (Root, Trigger, Content).
+ */
+export type DialogContext = {
+    /** Whether the dialog is open */
+    isOpen: boolean;
+    /** Reference to the trigger element */
+    triggerRef: HTMLElement | null;
+    /** Set the trigger ref (used by Trigger component) */
+    setTriggerRef: (el: HTMLElement | null) => void;
+    /** Toggle dialog open state */
+    toggle: () => void;
+    /** Open the dialog */
+    open: () => void;
+    /** Close the dialog and return focus to trigger */
+    close: () => void;
+    /** Called when dialog open state changes */
+    onOpenChange: (open: boolean) => void;
+    /** Stack level for z-index calculation (set by Content) */
+    stackLevel: number;
+    /** Set the stack level (used by Content component) */
+    setStackLevel: (level: number) => void;
+};
+export declare function setDialogContext(ctx: DialogContext): void;
+export declare function getDialogContext(): DialogContext | undefined;

package/dist/dialog/root/context.js

@@ -0,0 +1,8 @@
+import { setContext, getContext } from 'svelte';
+const DIALOG_CONTEXT_KEY = Symbol('dialog');
+export function setDialogContext(ctx) {
+    setContext(DIALOG_CONTEXT_KEY, ctx);
+}
+export function getDialogContext() {
+    return getContext(DIALOG_CONTEXT_KEY);
+}

package/dist/dialog/root/dialog-root.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { setDialogContext, type DialogContext } from './context';
+	import type { DialogStateHelpers } from './types';
+
+	/**
+	 * Dialog.Root - State management wrapper for Dialog components.
+	 * Provides context for Trigger and Content children.
+	 */
+	type DialogRootProps = {
+		/** Controlled open state. */
+		open?: boolean;
+		/** Initial open state for uncontrolled mode. */
+		defaultOpen?: boolean;
+		/** Callback when open state changes. */
+		onOpenChange?: (open: boolean) => void;
+		/** Reference to the trigger element. Can be set manually or via Dialog.Trigger. */
+		triggerRef?: HTMLElement | null;
+		/** Children snippet receives state helpers: { close, open, toggle, isOpen } */
+		children?: Snippet<[DialogStateHelpers]>;
+	};
+
+	let {
+		open: openProp = $bindable(),
+		defaultOpen = false,
+		onOpenChange,
+		triggerRef = $bindable<HTMLElement | null>(null),
+		children
+	}: DialogRootProps = $props();
+
+	// Use function to capture initial value only (not reactive)
+	let isOpenInternal = $state((() => defaultOpen)());
+
+	// Stack level for z-index calculation
+	let stackLevel = $state(0);
+
+	const isControlled = $derived(openProp !== undefined);
+	const isOpen = $derived(isControlled ? openProp! : isOpenInternal);
+
+	function setOpen(value: boolean) {
+		if (isControlled) {
+			onOpenChange?.(value);
+		} else {
+			isOpenInternal = value;
+			onOpenChange?.(value);
+		}
+		// Sync bindable prop
+		openProp = value;
+	}
+
+	function toggle() {
+		setOpen(!isOpen);
+	}
+
+	function openDialog() {
+		setOpen(true);
+	}
+
+	function closeDialog() {
+		setOpen(false);
+		triggerRef?.focus();
+	}
+
+	function setTriggerRef(el: HTMLElement | null) {
+		triggerRef = el;
+	}
+
+	function handleOpenChange(newOpen: boolean) {
+		setOpen(newOpen);
+	}
+
+	function setStackLevel(level: number) {
+		stackLevel = level;
+	}
+
+	const ctx: DialogContext = {
+		get isOpen() {
+			return isOpen;
+		},
+		get triggerRef() {
+			return triggerRef ?? null;
+		},
+		get stackLevel() {
+			return stackLevel;
+		},
+		setTriggerRef,
+		setStackLevel,
+		toggle,
+		open: openDialog,
+		close: closeDialog,
+		onOpenChange: handleOpenChange
+	};
+
+	setDialogContext(ctx);
+</script>
+
+{#if children}
+	{@render children({ close: closeDialog, open: openDialog, toggle, isOpen })}
+{/if}

package/dist/dialog/root/dialog-root.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+import type { DialogStateHelpers } from './types';
+/**
+ * Dialog.Root - State management wrapper for Dialog components.
+ * Provides context for Trigger and Content children.
+ */
+type DialogRootProps = {
+    /** Controlled open state. */
+    open?: boolean;
+    /** Initial open state for uncontrolled mode. */
+    defaultOpen?: boolean;
+    /** Callback when open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Reference to the trigger element. Can be set manually or via Dialog.Trigger. */
+    triggerRef?: HTMLElement | null;
+    /** Children snippet receives state helpers: { close, open, toggle, isOpen } */
+    children?: Snippet<[DialogStateHelpers]>;
+};
+declare const DialogRoot: import("svelte").Component<DialogRootProps, {}, "open" | "triggerRef">;
+type DialogRoot = ReturnType<typeof DialogRoot>;
+export default DialogRoot;

package/dist/dialog/root/dialog-stack.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Global dialog stack for managing nested dialogs.
+ * Only the topmost dialog should respond to Escape and click-outside events.
+ */
+/**
+ * Register a dialog when it opens.
+ * Returns the dialog ID and level for z-index calculation.
+ */
+export declare function pushDialog(close: () => void): {
+    id: symbol;
+    level: number;
+};
+/**
+ * Unregister a dialog when it closes.
+ */
+export declare function popDialog(id: symbol): void;
+/**
+ * Check if this dialog is the topmost (should handle events).
+ */
+export declare function isTopmostDialog(id: symbol): boolean;
+/**
+ * Get the z-index for the overlay based on dialog level.
+ */
+export declare function getOverlayZIndex(level: number): number;
+/**
+ * Get the z-index for the content based on dialog level.
+ */
+export declare function getContentZIndex(level: number): number;
+/**
+ * Get the number of open dialogs.
+ */
+export declare function getDialogCount(): number;

package/dist/dialog/root/dialog-stack.js

@@ -0,0 +1,55 @@
+/**
+ * Global dialog stack for managing nested dialogs.
+ * Only the topmost dialog should respond to Escape and click-outside events.
+ */
+const dialogStack = [];
+/**
+ * Base z-index for dialogs. Each nested dialog increments by 10.
+ */
+const BASE_Z_INDEX = 9990;
+const Z_INDEX_INCREMENT = 10;
+/**
+ * Register a dialog when it opens.
+ * Returns the dialog ID and level for z-index calculation.
+ */
+export function pushDialog(close) {
+    const id = Symbol('dialog');
+    const level = dialogStack.length;
+    dialogStack.push({ id, close, level });
+    return { id, level };
+}
+/**
+ * Unregister a dialog when it closes.
+ */
+export function popDialog(id) {
+    const index = dialogStack.findIndex((entry) => entry.id === id);
+    if (index !== -1) {
+        dialogStack.splice(index, 1);
+    }
+}
+/**
+ * Check if this dialog is the topmost (should handle events).
+ */
+export function isTopmostDialog(id) {
+    if (dialogStack.length === 0)
+        return false;
+    return dialogStack[dialogStack.length - 1].id === id;
+}
+/**
+ * Get the z-index for the overlay based on dialog level.
+ */
+export function getOverlayZIndex(level) {
+    return BASE_Z_INDEX + level * Z_INDEX_INCREMENT;
+}
+/**
+ * Get the z-index for the content based on dialog level.
+ */
+export function getContentZIndex(level) {
+    return BASE_Z_INDEX + level * Z_INDEX_INCREMENT + 1;
+}
+/**
+ * Get the number of open dialogs.
+ */
+export function getDialogCount() {
+    return dialogStack.length;
+}

package/dist/dialog/root/dialog-test.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import { Dialog } from '../index';
+
+	type Props = {
+		open?: boolean;
+		defaultOpen?: boolean;
+		shouldCloseOnInteractOutside?: boolean;
+		shouldCloseOnEscape?: boolean;
+		onOpenChange?: (open: boolean) => void;
+	};
+
+	let {
+		open,
+		defaultOpen = false,
+		shouldCloseOnInteractOutside = true,
+		shouldCloseOnEscape = true,
+		onOpenChange
+	}: Props = $props();
+</script>
+
+<Dialog.Root {open} {defaultOpen} {onOpenChange}>
+	{#snippet children({ close })}
+		<Dialog.Trigger>
+			<button type="button">Open Dialog</button>
+		</Dialog.Trigger>
+
+		<Dialog.Portal>
+			<Dialog.Overlay data-testid="dialog-overlay" />
+			<Dialog.Content class="dialog-content" {shouldCloseOnInteractOutside} {shouldCloseOnEscape}>
+				<div class="dialog-body">
+					<h3>Dialog Title</h3>
+					<p>Dialog content goes here.</p>
+					<button type="button" class="close-btn" onclick={close}>Close</button>
+				</div>
+			</Dialog.Content>
+		</Dialog.Portal>
+	{/snippet}
+</Dialog.Root>

package/dist/dialog/root/dialog-test.svelte.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    open?: boolean;
+    defaultOpen?: boolean;
+    shouldCloseOnInteractOutside?: boolean;
+    shouldCloseOnEscape?: boolean;
+    onOpenChange?: (open: boolean) => void;
+};
+declare const DialogTest: import("svelte").Component<Props, {}, "">;
+type DialogTest = ReturnType<typeof DialogTest>;
+export default DialogTest;

package/dist/dialog/root/dialog-with-combobox-test.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import { Dialog } from '../index';
+	import { ComboBox } from '../../combobox';
+
+	type Props = {
+		comboboxAutofocus?: boolean;
+		comboboxTrigger?: 'focus' | 'input' | 'press';
+	};
+
+	let { comboboxAutofocus = false, comboboxTrigger = 'press' }: Props = $props();
+
+	const countries = [
+		{ id: 'ar', name: 'Argentina' },
+		{ id: 'br', name: 'Brazil' },
+		{ id: 'ca', name: 'Canada' }
+	];
+
+	let selectedCountry = $state<string | number | undefined>();
+</script>
+
+<Dialog.Root>
+	{#snippet children({ close })}
+		<Dialog.Trigger>
+			<button type="button" data-testid="dialog-trigger">Open Dialog</button>
+		</Dialog.Trigger>
+
+		<Dialog.Portal>
+			<Dialog.Overlay />
+			<Dialog.Content class="dialog-content">
+				<h3>Select a Country</h3>
+				<ComboBox.Root trigger={comboboxTrigger} bind:value={selectedCountry}>
+					<div class="flex gap-1">
+						<ComboBox.Input
+							placeholder="Search countries..."
+							autofocus={comboboxAutofocus}
+							data-testid="combobox-input"
+						/>
+						<ComboBox.Button data-testid="combobox-button" />
+					</div>
+					<ComboBox.Popover>
+						<ComboBox.List emptyPlaceholder="No countries found">
+							{#each countries as country (country.id)}
+								<ComboBox.Item
+									id={country.id}
+									textValue={country.name}
+									data-testid="combobox-item-{country.id}"
+								>
+									{country.name}
+								</ComboBox.Item>
+							{/each}
+						</ComboBox.List>
+					</ComboBox.Popover>
+				</ComboBox.Root>
+				<div style="margin-top: 16px;">
+					<button type="button" onclick={close} data-testid="close-button">Close</button>
+				</div>
+				<div data-testid="selected-value">{selectedCountry ?? ''}</div>
+			</Dialog.Content>
+		</Dialog.Portal>
+	{/snippet}
+</Dialog.Root>

package/dist/dialog/root/dialog-with-combobox-test.svelte.d.ts

@@ -0,0 +1,7 @@
+type Props = {
+    comboboxAutofocus?: boolean;
+    comboboxTrigger?: 'focus' | 'input' | 'press';
+};
+declare const DialogWithComboboxTest: import("svelte").Component<Props, {}, "">;
+type DialogWithComboboxTest = ReturnType<typeof DialogWithComboboxTest>;
+export default DialogWithComboboxTest;

package/dist/dialog/root/nested-dialog-test.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import { Dialog } from '../index';
+
+	type Props = {
+		onDialog1Close?: () => void;
+		onDialog2Close?: () => void;
+		onDialog3Close?: () => void;
+	};
+
+	let { onDialog1Close, onDialog2Close, onDialog3Close }: Props = $props();
+</script>
+
+<!-- Level 1 Dialog -->
+<Dialog.Root onOpenChange={(open) => !open && onDialog1Close?.()}>
+	{#snippet children({ close })}
+		<Dialog.Trigger>
+			<button type="button" data-testid="trigger-1">Open Dialog 1</button>
+		</Dialog.Trigger>
+
+		<Dialog.Portal>
+			<Dialog.Overlay data-testid="overlay-1" />
+			<Dialog.Content data-testid="content-1" class="dialog-1">
+				<h3>Dialog 1</h3>
+				<button type="button" data-testid="close-1" onclick={close}>Close 1</button>
+
+				<!-- Level 2 Dialog (Nested) -->
+				<Dialog.Root onOpenChange={(open) => !open && onDialog2Close?.()}>
+					{#snippet children({ close: close2 })}
+						<Dialog.Trigger>
+							<button type="button" data-testid="trigger-2">Open Dialog 2</button>
+						</Dialog.Trigger>
+
+						<Dialog.Portal>
+							<Dialog.Overlay data-testid="overlay-2" />
+							<Dialog.Content data-testid="content-2" class="dialog-2">
+								<h3>Dialog 2</h3>
+								<button type="button" data-testid="close-2" onclick={close2}>Close 2</button>
+
+								<!-- Level 3 Dialog (Double Nested) -->
+								<Dialog.Root onOpenChange={(open) => !open && onDialog3Close?.()}>
+									{#snippet children({ close: close3 })}
+										<Dialog.Trigger>
+											<button type="button" data-testid="trigger-3">Open Dialog 3</button>
+										</Dialog.Trigger>
+
+										<Dialog.Portal>
+											<Dialog.Overlay data-testid="overlay-3" />
+											<Dialog.Content data-testid="content-3" class="dialog-3">
+												<h3>Dialog 3</h3>
+												<button type="button" data-testid="close-3" onclick={close3}>Close 3</button
+												>
+											</Dialog.Content>
+										</Dialog.Portal>
+									{/snippet}
+								</Dialog.Root>
+							</Dialog.Content>
+						</Dialog.Portal>
+					{/snippet}
+				</Dialog.Root>
+			</Dialog.Content>
+		</Dialog.Portal>
+	{/snippet}
+</Dialog.Root>

package/dist/dialog/root/nested-dialog-test.svelte.d.ts

@@ -0,0 +1,8 @@
+type Props = {
+    onDialog1Close?: () => void;
+    onDialog2Close?: () => void;
+    onDialog3Close?: () => void;
+};
+declare const NestedDialogTest: import("svelte").Component<Props, {}, "">;
+type NestedDialogTest = ReturnType<typeof NestedDialogTest>;
+export default NestedDialogTest;

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

@@ -0,0 +1,10 @@
+export type DialogStateHelpers = {
+    /** Close the dialog */
+    close: () => void;
+    /** Open the dialog */
+    open: () => void;
+    /** Toggle the dialog open state */
+    toggle: () => void;
+    /** Whether the dialog is currently open */
+    isOpen: boolean;
+};

package/dist/dialog/root/types.js

@@ -0,0 +1 @@
+export {};

package/dist/dialog/trigger/dialog-trigger.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { onMount, onDestroy } from 'svelte';
+	import { getDialogContext } from '../root/context';
+
+	/**
+	 * Dialog.Trigger - Wrapper that auto-wires a trigger element.
+	 * Must be used inside a Dialog.Root.
+	 */
+	type DialogTriggerProps = {
+		/** Children (trigger button) */
+		children?: Snippet;
+	};
+
+	let { children }: DialogTriggerProps = $props();
+
+	const ctx = getDialogContext();
+
+	if (!ctx) {
+		throw new Error('Dialog.Trigger must be used inside a Dialog.Root');
+	}
+
+	// After the throw, TypeScript knows ctx is defined
+	const dialogCtx = ctx;
+
+	let wrapperRef: HTMLElement | null = $state(null);
+
+	function handleClick(event: MouseEvent) {
+		const target = event.target as HTMLElement;
+		const button = target.closest('button, [role="button"]') as HTMLElement | null;
+
+		if (button && wrapperRef?.contains(button)) {
+			// Set trigger ref if not already set
+			if (!dialogCtx.triggerRef) {
+				dialogCtx.setTriggerRef(button);
+			}
+			dialogCtx.toggle();
+		}
+	}
+
+	onMount(() => {
+		if (wrapperRef) {
+			// Find and set up the trigger button
+			const firstButton = wrapperRef.querySelector('button, [role="button"]') as HTMLElement | null;
+			if (firstButton) {
+				dialogCtx.setTriggerRef(firstButton);
+				firstButton.setAttribute('aria-haspopup', 'dialog');
+			}
+		}
+
+		// Add click listener imperatively to avoid a11y linter warnings
+		// Buttons inside handle keyboard events natively (Enter/Space trigger click)
+		wrapperRef?.addEventListener('click', handleClick);
+	});
+
+	onDestroy(() => {
+		wrapperRef?.removeEventListener('click', handleClick);
+	});
+
+	$effect(() => {
+		if (dialogCtx.triggerRef) {
+			dialogCtx.triggerRef.setAttribute('aria-expanded', String(dialogCtx.isOpen));
+		}
+	});
+</script>
+
+<div bind:this={wrapperRef} style="display: contents;">
+	{#if children}
+		{@render children()}
+	{/if}
+</div>

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

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+/**
+ * Dialog.Trigger - Wrapper that auto-wires a trigger element.
+ * Must be used inside a Dialog.Root.
+ */
+type DialogTriggerProps = {
+    /** Children (trigger button) */
+    children?: Snippet;
+};
+declare const DialogTrigger: import("svelte").Component<DialogTriggerProps, {}, "">;
+type DialogTrigger = ReturnType<typeof DialogTrigger>;
+export default DialogTrigger;

package/dist/hooks/use-virtual-focus.svelte.d.ts

@@ -0,0 +1,55 @@
+/**
+ * useVirtualFocus - A reusable hook for virtual focus navigation.
+ *
+ * Implements the aria-activedescendant pattern for keyboard navigation
+ * in composite widgets like ComboBox, Menu, Select, TreeView, etc.
+ *
+ * Features:
+ * - Virtual focus state (focusedId)
+ * - Item registration/unregistration
+ * - Navigation (next, previous, first, last, pageUp, pageDown)
+ * - DOM order caching for performance
+ * - Scoped queries via containerRef
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useVirtualFocus } from './use-virtual-focus.svelte';
+ *
+ *   const nav = useVirtualFocus({
+ *     instanceId: 'my-list',
+ *     containerRef: () => listboxElement
+ *   });
+ *
+ *   // Use nav.focusedId, nav.next(), nav.register(), etc.
+ *   // PageSize is calculated automatically based on item count
+ * </script>
+ * ```
+ */
+export type VirtualFocusOptions = {
+    /** Unique ID prefix for item identification */
+    instanceId: string;
+    /** Prefix for item IDs in the DOM (default: 'combobox-item') */
+    itemPrefix?: string;
+    /** Reference to container element for scoped DOM queries */
+    containerRef?: () => HTMLElement | null;
+};
+export type VirtualFocusReturn = {
+    readonly focusedId: string | number | null;
+    readonly itemIds: (string | number)[];
+    readonly itemLabels: Map<string | number, string>;
+    readonly pendingFocusDirection: 'first' | 'last' | null;
+    next: () => void;
+    previous: () => void;
+    first: () => void;
+    last: () => void;
+    pageUp: () => void;
+    pageDown: () => void;
+    register: (id: string | number, label: string) => void;
+    unregister: (id: string | number) => void;
+    setFocused: (id: string | number | null) => void;
+    setPendingDirection: (direction: 'first' | 'last' | null) => void;
+    reset: () => void;
+    invalidateCache: () => void;
+};
+export declare function useVirtualFocus(options: VirtualFocusOptions): VirtualFocusReturn;