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

package/dist/hooks/use-virtual-focus.svelte.js

@@ -0,0 +1,201 @@
+/**
+ * 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>
+ * ```
+ */
+import { SvelteMap } from 'svelte/reactivity';
+export function useVirtualFocus(options) {
+    const { instanceId, itemPrefix = 'combobox-item', containerRef } = options;
+    // Internal state
+    let focusedId = $state(null);
+    let itemIds = $state([]);
+    const itemLabels = new SvelteMap();
+    let pendingFocusDirection = $state(null);
+    let cachedItemOrder = $state(null);
+    /**
+     * Smart page size calculation based on number of registered items.
+     * Ensures PageUp/PageDown jump a reasonable amount regardless of list size.
+     */
+    const pageSize = $derived(itemIds.length === 0 ? 10 : Math.max(5, Math.min(10, Math.ceil(itemIds.length / 3))));
+    /**
+     * Get item IDs in DOM order.
+     * Uses cache when available, queries DOM otherwise.
+     */
+    function getItemIdsInOrder() {
+        if (cachedItemOrder !== null) {
+            return cachedItemOrder;
+        }
+        const selector = `[id^="${itemPrefix}-${instanceId}-"]`;
+        const queryRoot = containerRef?.() ?? document;
+        const itemElements = queryRoot.querySelectorAll(selector);
+        if (itemElements.length === 0) {
+            cachedItemOrder = itemIds;
+            return cachedItemOrder;
+        }
+        const orderedIds = [];
+        const prefix = `${itemPrefix}-${instanceId}-`;
+        itemElements.forEach((el) => {
+            const fullId = el.getAttribute('id');
+            if (fullId && fullId.startsWith(prefix)) {
+                const rawId = fullId.substring(prefix.length);
+                const registeredId = itemIds.find((id) => String(id) === rawId);
+                orderedIds.push(registeredId ?? rawId);
+            }
+        });
+        cachedItemOrder = orderedIds;
+        return cachedItemOrder;
+    }
+    // Navigation functions
+    function next() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length === 0)
+            return;
+        if (focusedId === null) {
+            focusedId = orderedIds[0];
+            return;
+        }
+        const currentIndex = orderedIds.indexOf(focusedId);
+        if (currentIndex === -1) {
+            focusedId = orderedIds[0];
+        }
+        else if (currentIndex < orderedIds.length - 1) {
+            focusedId = orderedIds[currentIndex + 1];
+        }
+    }
+    function previous() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length === 0)
+            return;
+        if (focusedId === null) {
+            focusedId = orderedIds[orderedIds.length - 1];
+            return;
+        }
+        const currentIndex = orderedIds.indexOf(focusedId);
+        if (currentIndex === -1) {
+            focusedId = orderedIds[orderedIds.length - 1];
+        }
+        else if (currentIndex > 0) {
+            focusedId = orderedIds[currentIndex - 1];
+        }
+    }
+    function first() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length > 0) {
+            focusedId = orderedIds[0];
+        }
+    }
+    function last() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length > 0) {
+            focusedId = orderedIds[orderedIds.length - 1];
+        }
+    }
+    function pageUp() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length === 0)
+            return;
+        const currentIndex = focusedId !== null ? orderedIds.indexOf(focusedId) : orderedIds.length - 1;
+        const newIndex = Math.max(0, currentIndex - pageSize);
+        focusedId = orderedIds[newIndex];
+    }
+    function pageDown() {
+        const orderedIds = getItemIdsInOrder();
+        if (orderedIds.length === 0)
+            return;
+        const currentIndex = focusedId !== null ? orderedIds.indexOf(focusedId) : 0;
+        const newIndex = Math.min(orderedIds.length - 1, currentIndex + pageSize);
+        focusedId = orderedIds[newIndex];
+    }
+    // Registration functions
+    function register(id, label) {
+        if (!itemIds.includes(id)) {
+            itemIds = [...itemIds, id];
+            cachedItemOrder = null; // Invalidate cache
+        }
+        itemLabels.set(id, label);
+        // Apply pending focus if this is the target item
+        if (pendingFocusDirection !== null && itemIds.length > 0) {
+            if (pendingFocusDirection === 'first' && itemIds[0] === id) {
+                focusedId = id;
+                pendingFocusDirection = null;
+            }
+            else if (pendingFocusDirection === 'last') {
+                focusedId = id;
+            }
+        }
+    }
+    function unregister(id) {
+        itemIds = itemIds.filter((i) => i !== id);
+        itemLabels.delete(id);
+        cachedItemOrder = null; // Invalidate cache
+        if (focusedId === id) {
+            focusedId = null;
+        }
+    }
+    // Control functions
+    function setFocused(id) {
+        focusedId = id;
+    }
+    function setPendingDirection(direction) {
+        pendingFocusDirection = direction;
+    }
+    function reset() {
+        focusedId = null;
+        itemIds = [];
+        itemLabels.clear();
+        cachedItemOrder = null;
+        pendingFocusDirection = null;
+    }
+    function invalidateCache() {
+        cachedItemOrder = null;
+    }
+    return {
+        get focusedId() {
+            return focusedId;
+        },
+        get itemIds() {
+            return itemIds;
+        },
+        get itemLabels() {
+            return itemLabels;
+        },
+        get pendingFocusDirection() {
+            return pendingFocusDirection;
+        },
+        next,
+        previous,
+        first,
+        last,
+        pageUp,
+        pageDown,
+        register,
+        unregister,
+        setFocused,
+        setPendingDirection,
+        reset,
+        invalidateCache
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { ComboBox } from './combobox/index.ts';
+export { Dialog } from './dialog/index.ts';
+export { ListBox } from './listbox/index.ts';
+export { Popover } from './popover/index.ts';
+export { default as Input } from './input/index.ts';
+export { default as Label } from './label/index.ts';
+export { Portal } from './portal/index.ts';
+export * from './combobox/index.ts';
+export * from './dialog/index.ts';
+export * from './listbox/index.ts';
+export * from './popover/index.ts';
+export * from './primitives/index.ts';
+export { cn } from './utils/index.ts';

package/dist/index.js

@@ -0,0 +1,19 @@
+// Main library entry point
+// Components (namespace exports)
+export { ComboBox } from './combobox/index.ts';
+export { Dialog } from './dialog/index.ts';
+export { ListBox } from './listbox/index.ts';
+export { Popover } from './popover/index.ts';
+// Simple components
+export { default as Input } from './input/index.ts';
+export { default as Label } from './label/index.ts';
+export { Portal } from './portal/index.ts';
+// Re-export named exports from components
+export * from './combobox/index.ts';
+export * from './dialog/index.ts';
+export * from './listbox/index.ts';
+export * from './popover/index.ts';
+// Primitives
+export * from './primitives/index.ts';
+// Utilities
+export { cn } from './utils/index.ts';

package/dist/input/index.d.ts

@@ -0,0 +1,3 @@
+import Input from './input.svelte';
+export { Input };
+export default Input;

package/dist/input/index.js

@@ -0,0 +1,3 @@
+import Input from './input.svelte';
+export { Input };
+export default Input;

package/dist/input/input.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import type { HTMLInputAttributes } from 'svelte/elements';
+	import type { ClassValue } from 'class-variance-authority/types';
+	import { cn } from '../utils/cn';
+
+	type InputProps = HTMLInputAttributes & {
+		class?: ClassValue;
+	};
+
+	let { class: className, ...props }: InputProps = $props();
+</script>
+
+<input
+	{...props}
+	class={cn(
+		`bg-depth-2 sunken placeholder:text-muted-foreground hover:bg-depth-1 focus:ring-border h-8 w-full rounded-xs border px-2 text-sm shadow-xs transition-all ease-out outline-none focus:ring focus:ring-offset-1 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 focus:data-[invalid=true]:ring-red-500`,
+		className
+	)}
+/>

package/dist/input/input.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import type { ClassValue } from 'class-variance-authority/types';
+type InputProps = HTMLInputAttributes & {
+    class?: ClassValue;
+};
+declare const Input: import("svelte").Component<InputProps, {}, "">;
+type Input = ReturnType<typeof Input>;
+export default Input;

package/dist/label/index.d.ts

@@ -0,0 +1,3 @@
+import Label from './label.svelte';
+export { Label };
+export default Label;

package/dist/label/index.js

@@ -0,0 +1,3 @@
+import Label from './label.svelte';
+export { Label };
+export default Label;

package/dist/label/label.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import type { HTMLLabelAttributes } from 'svelte/elements';
+	import type { ClassValue } from 'class-variance-authority/types';
+	import { cn } from '../utils/cn';
+
+	type LabelProps = HTMLLabelAttributes & {
+		class?: ClassValue;
+	};
+
+	let { class: className, children, ...props }: LabelProps = $props();
+</script>
+
+<label
+	{...props}
+	class={cn(
+		`text-sm leading-none font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70`,
+		className
+	)}
+>
+	{@render children?.()}
+</label>

package/dist/label/label.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLLabelAttributes } from 'svelte/elements';
+import type { ClassValue } from 'class-variance-authority/types';
+type LabelProps = HTMLLabelAttributes & {
+    class?: ClassValue;
+};
+declare const Label: import("svelte").Component<LabelProps, {}, "">;
+type Label = ReturnType<typeof Label>;
+export default Label;

package/dist/listbox/index.d.ts

@@ -0,0 +1,6 @@
+export * as ListBox from './index.parts.ts';
+export { default as ListBoxRoot } from './root/listbox.svelte';
+export { default as ListBoxItem } from './item/listbox-item.svelte';
+export { useListBoxContext, createListBoxContext, type ListBoxContext } from './root/context.ts';
+import * as ListBoxParts from './index.parts.ts';
+export default ListBoxParts;

package/dist/listbox/index.js

@@ -0,0 +1,10 @@
+// Namespace export for component composition: <ListBox.Root>, <ListBox.Item>
+export * as ListBox from './index.parts.ts';
+// Direct named exports for individual imports
+export { default as ListBoxRoot } from './root/listbox.svelte';
+export { default as ListBoxItem } from './item/listbox-item.svelte';
+// Context and types
+export { useListBoxContext, createListBoxContext } from './root/context.ts';
+// Default export as namespace object
+import * as ListBoxParts from './index.parts.ts';
+export default ListBoxParts;

package/dist/listbox/index.parts.d.ts

@@ -0,0 +1,2 @@
+export { default as Root } from './root/listbox.svelte';
+export { default as Item } from './item/listbox-item.svelte';

package/dist/listbox/index.parts.js

@@ -0,0 +1,3 @@
+// Short alias exports for namespace usage: ListBox.Root, ListBox.Item
+export { default as Root } from './root/listbox.svelte';
+export { default as Item } from './item/listbox-item.svelte';

package/dist/listbox/item/listbox-item.svelte

@@ -0,0 +1,186 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { useListBoxContext } from '../root/context';
+	import { onMount, onDestroy } from 'svelte';
+
+	/**
+	 * Props for the ListBox.Item component.
+	 */
+	type ListBoxItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'id' | 'children'> & {
+		/** Unique identifier for this item. Used for selection tracking. */
+		id: string | number;
+		/** Text value for typeahead search. If not provided, extracted from content. */
+		textValue?: string;
+		/** Whether this item is disabled and non-selectable. */
+		disabled?: boolean;
+		/** CSS class to apply to the item element. */
+		class?: string;
+		/** Content to render inside the item. */
+		children?: Snippet;
+
+		// Override props for composition (e.g., ComboBox.Item wrapping ListBox.Item)
+		/** Override the generated ID. Useful for components with custom ID requirements. */
+		customId?: string;
+		/** Disable real DOM focus handling. When true, no tabindex is set and focus events are skipped. */
+		disableFocusHandling?: boolean;
+		/** Override the focused state. When provided, this value is used instead of internal focus tracking. */
+		isFocusedOverride?: boolean;
+		/** Override the select behavior. When provided, called instead of default listbox selection. */
+		onItemSelect?: (id: string | number, label: string) => void;
+		/** Callback with resolved text value when mounted (from prop or rendered content). */
+		onResolvedTextValue?: (label: string) => void;
+		/** Whether to scroll this item into view when focused. Useful for virtual focus patterns. */
+		scrollOnFocus?: boolean;
+		/** Additional disabled state from parent. */
+		isParentDisabled?: boolean;
+	};
+
+	let {
+		id,
+		textValue,
+		disabled = false,
+		class: className = '',
+		children,
+		// Override props
+		customId,
+		disableFocusHandling = false,
+		isFocusedOverride,
+		onItemSelect,
+		onResolvedTextValue,
+		scrollOnFocus = false,
+		isParentDisabled = false,
+		...restProps
+	}: ListBoxItemProps = $props();
+
+	const listboxCtx = useListBoxContext();
+
+	let elementRef: HTMLElement;
+	let isSelected = $state(false);
+	let isFocused = $state(false);
+	let isHovered = $state(false);
+
+	// Focus: use override if provided, otherwise use internal state
+	const isFocusedComputed = $derived(
+		isFocusedOverride !== undefined ? isFocusedOverride : isFocused
+	);
+	const isDisabledComputed = $derived(
+		disabled || listboxCtx.disabledIds.has(id) || isParentDisabled
+	);
+
+	// ID: use custom if provided, otherwise generate
+	const uniqueId = $derived(customId ?? `listbox-item-${id}`);
+
+	let unsubscribeSelection: (() => void) | null = null;
+	let unsubscribeFocus: (() => void) | null = null;
+
+	function getResolvedTextValue() {
+		return textValue || elementRef?.textContent?.trim() || String(id);
+	}
+
+	onMount(() => {
+		const computedTextValue = getResolvedTextValue();
+
+		// Register with ListBox context for selection state
+		listboxCtx.registerItem(id, computedTextValue, elementRef);
+		onResolvedTextValue?.(computedTextValue);
+
+		unsubscribeSelection = listboxCtx.subscribeToItem(id, (selected) => {
+			isSelected = selected;
+		});
+
+		// Only subscribe to ListBox focus if focus handling is enabled
+		if (!disableFocusHandling) {
+			unsubscribeFocus = listboxCtx.subscribeToFocus(id, (focused) => {
+				isFocused = focused;
+			});
+			listboxCtx.keyboardNav.updateItems();
+		}
+	});
+
+	onDestroy(() => {
+		listboxCtx.unregisterItem(id);
+		unsubscribeSelection?.();
+		unsubscribeFocus?.();
+	});
+
+	// Scroll into view when focused (if enabled)
+	$effect(() => {
+		if (scrollOnFocus && isFocusedComputed && elementRef) {
+			requestAnimationFrame(() => {
+				elementRef?.scrollIntoView({ block: 'nearest' });
+			});
+		}
+	});
+
+	function handleClick() {
+		if (isDisabledComputed) return;
+
+		const label = getResolvedTextValue();
+
+		// Use custom select handler if provided, otherwise use listbox default
+		if (onItemSelect) {
+			onItemSelect(id, label);
+		} else {
+			listboxCtx.select(id);
+			listboxCtx.setFocusedId(id);
+		}
+	}
+
+	function handleFocus() {
+		if (!disableFocusHandling) {
+			listboxCtx.setFocusedId(id);
+		}
+	}
+
+	function handleBlur() {}
+
+	function handleMouseEnter() {
+		if (!isDisabledComputed) {
+			isHovered = true;
+		}
+	}
+
+	function handleMouseLeave() {
+		isHovered = false;
+	}
+
+	// Keyboard is handled by parent container
+	function handleKeydown() {}
+	function handleMouseDown(event: MouseEvent) {
+		// Prevent focus stealing when used in ComboBox (disableFocusHandling=true)
+		// This keeps the focus on the input while allowing click selection
+		if (disableFocusHandling) {
+			event.preventDefault();
+		}
+	}
+</script>
+
+<div
+	bind:this={elementRef}
+	role="option"
+	id={uniqueId}
+	class={className}
+	tabindex={disableFocusHandling ? undefined : isFocusedComputed ? 0 : -1}
+	aria-selected={isSelected}
+	aria-disabled={isDisabledComputed || undefined}
+	data-navigation-item={!disableFocusHandling || undefined}
+	data-item-id={id}
+	data-item-id-type={typeof id === 'number' ? 'number' : 'string'}
+	data-selected={isSelected || undefined}
+	data-disabled={isDisabledComputed || undefined}
+	data-focused={isFocusedComputed || undefined}
+	data-hovered={isHovered || undefined}
+	onmousedown={handleMouseDown}
+	onclick={handleClick}
+	onkeydown={handleKeydown}
+	onfocus={handleFocus}
+	onblur={handleBlur}
+	onmouseenter={handleMouseEnter}
+	onmouseleave={handleMouseLeave}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{/if}
+</div>

package/dist/listbox/item/listbox-item.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * Props for the ListBox.Item component.
+ */
+type ListBoxItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'id' | 'children'> & {
+    /** Unique identifier for this item. Used for selection tracking. */
+    id: string | number;
+    /** Text value for typeahead search. If not provided, extracted from content. */
+    textValue?: string;
+    /** Whether this item is disabled and non-selectable. */
+    disabled?: boolean;
+    /** CSS class to apply to the item element. */
+    class?: string;
+    /** Content to render inside the item. */
+    children?: Snippet;
+    /** Override the generated ID. Useful for components with custom ID requirements. */
+    customId?: string;
+    /** Disable real DOM focus handling. When true, no tabindex is set and focus events are skipped. */
+    disableFocusHandling?: boolean;
+    /** Override the focused state. When provided, this value is used instead of internal focus tracking. */
+    isFocusedOverride?: boolean;
+    /** Override the select behavior. When provided, called instead of default listbox selection. */
+    onItemSelect?: (id: string | number, label: string) => void;
+    /** Callback with resolved text value when mounted (from prop or rendered content). */
+    onResolvedTextValue?: (label: string) => void;
+    /** Whether to scroll this item into view when focused. Useful for virtual focus patterns. */
+    scrollOnFocus?: boolean;
+    /** Additional disabled state from parent. */
+    isParentDisabled?: boolean;
+};
+declare const ListboxItem: import("svelte").Component<ListBoxItemProps, {}, "">;
+type ListboxItem = ReturnType<typeof ListboxItem>;
+export default ListboxItem;

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

@@ -0,0 +1,73 @@
+import { type KeyboardNavigationReturn } from '../../primitives/keyboard-navigation';
+/**
+ * Context object shared between ListBox and ListBox.Item components.
+ * Provides state management and actions for selection and focus.
+ */
+export type ListBoxContext = {
+    /** Current selection mode. */
+    selectionMode: 'single' | 'multiple';
+    /** Current selection behavior. */
+    selectionBehavior: 'toggle' | 'replace';
+    /** Set of disabled item IDs. */
+    disabledIds: Set<string | number>;
+    /** Returns a copy of the currently selected keys. */
+    getSelectedKeys: () => Set<string | number>;
+    /** Returns the currently focused item ID. */
+    getFocusedId: () => string | number | null;
+    /** Checks if an item is selected. */
+    isSelected: (id: string | number) => boolean;
+    /** Checks if an item is disabled. */
+    isDisabled: (id: string | number) => boolean;
+    /** Checks if an item is focused. */
+    isFocused: (id: string | number) => boolean;
+    /** Keyboard navigation controller from the shared primitive. */
+    keyboardNav: KeyboardNavigationReturn;
+    /** Map of registered items with their metadata. */
+    items: Map<string | number, {
+        textValue?: string;
+        element?: HTMLElement;
+    }>;
+    /** Registers an item in the listbox. */
+    registerItem: (id: string | number, textValue?: string, element?: HTMLElement) => void;
+    /** Unregisters an item from the listbox. */
+    unregisterItem: (id: string | number) => void;
+    /** Returns all registered item IDs. */
+    getItemIds: () => (string | number)[];
+    /** Returns the current item count. */
+    getItemCount: () => number;
+    /** Subscribes to item count changes. Returns unsubscribe function. */
+    subscribeToItemCount: (callback: (count: number) => void) => () => void;
+    /** Selects or toggles an item based on current mode and behavior. */
+    select: (id: string | number) => void;
+    /** Selects all enabled items (only works in multiple mode). */
+    selectAll: () => void;
+    /** Sets the selection programmatically (for controlled mode). */
+    setSelection: (selection: Set<string | number>) => void;
+    /** Sets the focused item ID. */
+    setFocusedId: (id: string | number | null) => void;
+    /** Subscribes to selection changes for a specific item. Returns unsubscribe function. */
+    subscribeToItem: (id: string | number, callback: (selected: boolean) => void) => () => void;
+    /** Subscribes to focus changes for a specific item. Returns unsubscribe function. */
+    subscribeToFocus: (id: string | number, callback: (focused: boolean) => void) => () => void;
+    /** Returns the next item ID respecting loop setting, or null if at end. */
+    getNextItemId: (currentId: string | number | null) => string | number | null;
+    /** Returns the previous item ID respecting loop setting, or null if at start. */
+    getPreviousItemId: (currentId: string | number | null) => string | number | null;
+};
+/**
+ * Options for creating a ListBox context.
+ */
+export type CreateListBoxContextOptions = {
+    /** Selection mode: 'single' or 'multiple'. Default: 'single'. */
+    selectionMode?: 'single' | 'multiple';
+    /** Selection behavior: 'toggle' or 'replace'. Default: 'toggle'. */
+    selectionBehavior?: 'toggle' | 'replace';
+    /** Initial set of disabled item IDs. */
+    disabledIds?: Iterable<string | number>;
+    /** Initial selection for uncontrolled mode. */
+    initialSelection?: Set<string | number>;
+    /** Callback fired when selection changes. */
+    onSelectionChange?: (selection: Set<string | number>) => void;
+};
+export declare function createListBoxContext(options?: CreateListBoxContextOptions): ListBoxContext;
+export declare function useListBoxContext(): ListBoxContext;