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

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

@@ -3,6 +3,11 @@
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { useListBoxContext } from '../root/context';
 	import { onMount, onDestroy } from 'svelte';
+	import {
+		focusWithModality,
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
 
 	/**
 	 * Props for the ListBox.Item component.
@@ -26,14 +31,20 @@
 		disableFocusHandling?: boolean;
 		/** Override the focused state. When provided, this value is used instead of internal focus tracking. */
 		isFocusedOverride?: boolean;
+		/** Override the focus-visible presentation state. */
+		isFocusVisibleOverride?: 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;
+		/** Callback when pointer hover should move logical focus to this item. */
+		onItemHoverStart?: (id: string | number, 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;
+		/** Override the visual pressed state. When provided, this value is used instead of internal press tracking. */
+		pressed?: boolean;
 	};
 
 	let {
@@ -46,10 +57,13 @@
 		customId,
 		disableFocusHandling = false,
 		isFocusedOverride,
+		isFocusVisibleOverride,
 		onItemSelect,
 		onResolvedTextValue,
+		onItemHoverStart,
 		scrollOnFocus = false,
 		isParentDisabled = false,
+		pressed: pressedOverride,
 		...restProps
 	}: ListBoxItemProps = $props();
 
@@ -58,7 +72,12 @@
 	let elementRef: HTMLElement;
 	let isSelected = $state(false);
 	let isFocused = $state(false);
+	let isFocusVisible = $state(false);
+	let listFocusVisible = $state(false);
 	let isHovered = $state(false);
+	let isPressed = $state(false);
+	let pressedKey: 'Enter' | 'Space' | null = $state(null);
+	let suppressNextFocusVisible = $state(false);
 
 	// Focus: use override if provided, otherwise use internal state
 	const isFocusedComputed = $derived(
@@ -67,12 +86,28 @@
 	const isDisabledComputed = $derived(
 		disabled || listboxCtx.disabledIds.has(id) || isParentDisabled
 	);
+	const isPressedComputed = $derived(
+		pressedOverride !== undefined
+			? Boolean(pressedOverride) && !isDisabledComputed
+			: isPressed && !isDisabledComputed
+	);
+	const isFocusVisibleComputed = $derived(
+		isFocusVisibleOverride !== undefined ? isFocusVisibleOverride : isFocusVisible
+	);
+	const isActiveFocusVisible = $derived(
+		isFocusVisibleOverride !== undefined
+			? isFocusVisibleComputed
+			: isFocusedComputed && listFocusVisible
+	);
+	const showFocusVisible = $derived(isActiveFocusVisible && !isHovered);
+	const showHovered = $derived(isHovered && !isActiveFocusVisible);
 
 	// ID: use custom if provided, otherwise generate
 	const uniqueId = $derived(customId ?? `listbox-item-${id}`);
 
 	let unsubscribeSelection: (() => void) | null = null;
 	let unsubscribeFocus: (() => void) | null = null;
+	let unsubscribeFocusVisible: (() => void) | null = null;
 
 	function getResolvedTextValue() {
 		return textValue || elementRef?.textContent?.trim() || String(id);
@@ -94,6 +129,9 @@
 			unsubscribeFocus = listboxCtx.subscribeToFocus(id, (focused) => {
 				isFocused = focused;
 			});
+			unsubscribeFocusVisible = listboxCtx.subscribeToFocusVisible((visible) => {
+				listFocusVisible = visible;
+			});
 			listboxCtx.keyboardNav.updateItems();
 		}
 	});
@@ -102,58 +140,265 @@
 		listboxCtx.unregisterItem(id);
 		unsubscribeSelection?.();
 		unsubscribeFocus?.();
+		unsubscribeFocusVisible?.();
 	});
 
 	// Scroll into view when focused (if enabled)
 	$effect(() => {
-		if (scrollOnFocus && isFocusedComputed && elementRef) {
+		if (scrollOnFocus && isFocusedComputed && isFocusVisibleComputed && elementRef) {
 			requestAnimationFrame(() => {
 				elementRef?.scrollIntoView({ block: 'nearest' });
 			});
 		}
 	});
 
+	$effect(() => {
+		if (!isDisabledComputed) return;
+		clearPressedState();
+		isHovered = false;
+		isFocusVisible = false;
+	});
+
+	$effect(() => {
+		if (!isFocusedComputed) {
+			if (pressedKey !== null) {
+				clearPressedState();
+			}
+			return;
+		}
+
+		if (listFocusVisible || isFocusVisibleComputed) {
+			isHovered = false;
+		}
+	});
+
+	function clearPressedState() {
+		isPressed = false;
+		pressedKey = null;
+	}
+
+	function applyPointerFocusState() {
+		suppressNextFocusVisible = true;
+		listboxCtx.setFocusVisible(false);
+		listboxCtx.setFocusedId(id);
+		listboxCtx.keyboardNav.setCurrentId(id);
+		if (elementRef) {
+			focusWithModality(elementRef, 'pointer');
+		}
+	}
+
+	function transferHoverFocus() {
+		const label = getResolvedTextValue();
+		if (onItemHoverStart) {
+			onItemHoverStart(id, label);
+		} else if (!disableFocusHandling) {
+			applyPointerFocusState();
+			requestAnimationFrame(() => {
+				if (isHovered && !isDisabledComputed) {
+					applyPointerFocusState();
+				}
+			});
+		}
+	}
+
 	function handleClick() {
 		if (isDisabledComputed) return;
 
 		const label = getResolvedTextValue();
 
+		if (!disableFocusHandling && elementRef) {
+			suppressNextFocusVisible = true;
+			isFocusVisible = false;
+			listboxCtx.setFocusVisible(false);
+			listboxCtx.setFocusedId(id);
+			listboxCtx.keyboardNav.setCurrentId(id);
+			focusWithModality(elementRef, 'pointer');
+		}
+
 		// Use custom select handler if provided, otherwise use listbox default
 		if (onItemSelect) {
 			onItemSelect(id, label);
 		} else {
 			listboxCtx.select(id);
-			listboxCtx.setFocusedId(id);
+		}
+
+		if (!disableFocusHandling) {
+			listboxCtx.keyboardNav.setCurrentId(id);
 		}
 	}
 
 	function handleFocus() {
+		if (isDisabledComputed) return;
+		isFocusVisible = suppressNextFocusVisible ? false : shouldShowFocusVisible(elementRef);
+		suppressNextFocusVisible = false;
+		if (isFocusVisible) {
+			isHovered = false;
+		}
 		if (!disableFocusHandling) {
+			listboxCtx.setFocusVisible(isFocusVisible);
 			listboxCtx.setFocusedId(id);
 		}
 	}
 
-	function handleBlur() {}
+	function handleBlur() {
+		isFocusVisible = false;
+		if (!disableFocusHandling && listboxCtx.isFocused(id)) {
+			listboxCtx.setFocusVisible(false);
+			listboxCtx.setFocusedId(null);
+		}
+	}
+
+	function handlePointerDown(event: PointerEvent) {
+		trackInteractionModality(event, elementRef);
+		isFocusVisible = false;
+		if (!disableFocusHandling) {
+			listboxCtx.setFocusVisible(false);
+		}
 
-	function handleMouseEnter() {
+		if (isDisabledComputed) {
+			event.preventDefault();
+			clearPressedState();
+			return;
+		}
+
+		if (event.button !== 0) return;
+		isPressed = true;
+		pressedKey = null;
+	}
+
+	function handlePointerUp(event: PointerEvent) {
+		if (event.button !== 0) return;
+		isPressed = false;
+		pressedKey = null;
+	}
+
+	function handlePointerCancel() {
+		clearPressedState();
+	}
+
+	function handlePointerEnter(event: PointerEvent) {
+		if (isDisabledComputed) return;
+
+		trackInteractionModality(event, elementRef);
+		if (!disableFocusHandling) {
+			listboxCtx.setFocusVisible(false);
+		}
+		transferHoverFocus();
+
+		if ((event.buttons & 1) === 1 && pressedKey === null) {
+			isPressed = true;
+		}
+	}
+
+	function handlePointerLeave() {
+		if (pressedKey === null) {
+			isPressed = false;
+		}
+	}
+
+	function handleMouseEnter(event: MouseEvent) {
 		if (!isDisabledComputed) {
+			trackInteractionModality(event, elementRef);
 			isHovered = true;
+			isFocusVisible = false;
+			if (!disableFocusHandling) {
+				listboxCtx.setFocusVisible(false);
+				transferHoverFocus();
+			}
 		}
 	}
 
 	function handleMouseLeave() {
 		isHovered = false;
+		if (pressedKey === null) {
+			isPressed = false;
+		}
 	}
 
 	// Keyboard is handled by parent container
-	function handleKeydown() {}
+	function handleKeydown(event: KeyboardEvent) {
+		trackInteractionModality(event, elementRef);
+		if (isFocusedComputed) {
+			isHovered = false;
+			isFocusVisible = true;
+			if (!disableFocusHandling) {
+				listboxCtx.setFocusVisible(true);
+			}
+		}
+
+		const key =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+
+		if (!key) return;
+
+		if (isDisabledComputed) {
+			event.preventDefault();
+			clearPressedState();
+			return;
+		}
+
+		if (event.repeat && isPressed && pressedKey === key) return;
+
+		isPressed = true;
+		pressedKey = key;
+	}
+
+	function handleKeyup(event: KeyboardEvent) {
+		const key =
+			event.key === 'Enter'
+				? 'Enter'
+				: event.key === ' ' || event.key === 'Spacebar'
+					? 'Space'
+					: null;
+
+		if (!key) return;
+
+		if (isDisabledComputed) {
+			event.preventDefault();
+			clearPressedState();
+			return;
+		}
+
+		if (pressedKey === key) {
+			clearPressedState();
+		}
+	}
+
 	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, elementRef);
+		isFocusVisible = false;
+		if (!disableFocusHandling) {
+			listboxCtx.setFocusVisible(false);
+		}
+
 		// Prevent focus stealing when used in ComboBox (disableFocusHandling=true)
 		// This keeps the focus on the input while allowing click selection
+		if (isDisabledComputed) {
+			event.preventDefault();
+			clearPressedState();
+			return;
+		}
+
+		if (event.button === 0) {
+			isPressed = true;
+			pressedKey = null;
+		}
+
 		if (disableFocusHandling) {
 			event.preventDefault();
 		}
 	}
+
+	function handleMouseUp(event: MouseEvent) {
+		if (event.button !== 0) return;
+		if (pressedKey === null) {
+			clearPressedState();
+		}
+	}
 </script>
 
 <div
@@ -170,10 +415,19 @@
 	data-selected={isSelected || undefined}
 	data-disabled={isDisabledComputed || undefined}
 	data-focused={isFocusedComputed || undefined}
-	data-hovered={isHovered || undefined}
+	data-focus-visible={showFocusVisible || undefined}
+	data-hovered={showHovered || undefined}
+	data-pressed={isPressedComputed || undefined}
+	onpointerdown={handlePointerDown}
+	onpointerup={handlePointerUp}
+	onpointercancel={handlePointerCancel}
+	onpointerenter={handlePointerEnter}
+	onpointerleave={handlePointerLeave}
 	onmousedown={handleMouseDown}
+	onmouseup={handleMouseUp}
 	onclick={handleClick}
 	onkeydown={handleKeydown}
+	onkeyup={handleKeyup}
 	onfocus={handleFocus}
 	onblur={handleBlur}
 	onmouseenter={handleMouseEnter}

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

@@ -20,14 +20,20 @@ type ListBoxItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'id' | 'children'>
     disableFocusHandling?: boolean;
     /** Override the focused state. When provided, this value is used instead of internal focus tracking. */
     isFocusedOverride?: boolean;
+    /** Override the focus-visible presentation state. */
+    isFocusVisibleOverride?: 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;
+    /** Callback when pointer hover should move logical focus to this item. */
+    onItemHoverStart?: (id: string | number, 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;
+    /** Override the visual pressed state. When provided, this value is used instead of internal press tracking. */
+    pressed?: boolean;
 };
 declare const ListboxItem: import("svelte").Component<ListBoxItemProps, {}, "">;
 type ListboxItem = ReturnType<typeof ListboxItem>;

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

@@ -20,6 +20,8 @@ export type ListBoxContext = {
     isDisabled: (id: string | number) => boolean;
     /** Checks if an item is focused. */
     isFocused: (id: string | number) => boolean;
+    /** Whether keyboard focus-visible should be shown for the currently focused item. */
+    getFocusVisible: () => boolean;
     /** Keyboard navigation controller from the shared primitive. */
     keyboardNav: KeyboardNavigationReturn;
     /** Map of registered items with their metadata. */
@@ -45,10 +47,14 @@ export type ListBoxContext = {
     setSelection: (selection: Set<string | number>) => void;
     /** Sets the focused item ID. */
     setFocusedId: (id: string | number | null) => void;
+    /** Sets whether the focused item should render keyboard focus-visible. */
+    setFocusVisible: (visible: boolean) => 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;
+    /** Subscribes to focus-visible state changes. Returns unsubscribe function. */
+    subscribeToFocusVisible: (callback: (visible: 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. */

package/dist/listbox/root/context.js

@@ -53,30 +53,30 @@ export function createListBoxContext(options = {}) {
     }
     let focusedId = null;
     const focusCallbacks = new Map();
+    let focusVisible = false;
+    const focusVisibleCallbacks = new Set();
     function getFocusedId() {
         return focusedId;
     }
     function isFocused(id) {
         return focusedId === id || String(focusedId) === String(id);
     }
-    function notifyFocus(id, focused) {
-        const callbacks = focusCallbacks.get(id);
-        if (callbacks) {
-            callbacks.forEach((cb) => cb(focused));
-        }
+    function getFocusVisible() {
+        return focusVisible;
     }
     function setFocusedId(newId) {
-        if (focusedId === newId)
-            return;
-        const previousId = focusedId;
         focusedId = newId;
-        if (previousId !== null) {
-            notifyFocus(previousId, false);
-        }
-        if (newId !== null) {
-            notifyFocus(newId, true);
+        for (const [id, callbacks] of focusCallbacks) {
+            const focused = newId !== null && (id === newId || String(id) === String(newId));
+            callbacks.forEach((callback) => callback(focused));
         }
     }
+    function setFocusVisible(visible) {
+        if (focusVisible === visible)
+            return;
+        focusVisible = visible;
+        focusVisibleCallbacks.forEach((callback) => callback(visible));
+    }
     function subscribeToFocus(id, callback) {
         if (!focusCallbacks.has(id)) {
             focusCallbacks.set(id, new Set());
@@ -93,6 +93,13 @@ export function createListBoxContext(options = {}) {
             }
         };
     }
+    function subscribeToFocusVisible(callback) {
+        focusVisibleCallbacks.add(callback);
+        callback(focusVisible);
+        return () => {
+            focusVisibleCallbacks.delete(callback);
+        };
+    }
     function subscribeToItem(id, callback) {
         if (!itemCallbacks.has(id)) {
             itemCallbacks.set(id, new Set());
@@ -221,6 +228,7 @@ export function createListBoxContext(options = {}) {
         isSelected,
         isDisabled,
         isFocused,
+        getFocusVisible,
         keyboardNav,
         items,
         registerItem,
@@ -232,8 +240,10 @@ export function createListBoxContext(options = {}) {
         selectAll,
         setSelection,
         setFocusedId,
+        setFocusVisible,
         subscribeToItem,
         subscribeToFocus,
+        subscribeToFocusVisible,
         getNextItemId,
         getPreviousItemId
     };

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

@@ -5,9 +5,17 @@
 		selectionMode?: 'single' | 'multiple';
 		selectionBehavior?: 'toggle' | 'replace';
 		disabledIds?: Iterable<string | number>;
+		pressedIds?: Iterable<string | number>;
 	};
 
-	let { selectionMode = 'single', selectionBehavior = 'toggle', disabledIds }: Props = $props();
+	let {
+		selectionMode = 'single',
+		selectionBehavior = 'toggle',
+		disabledIds,
+		pressedIds
+	}: Props = $props();
+
+	const pressedIdSet = $derived(new Set(pressedIds ?? []));
 
 	const fruits = [
 		{ id: 'apple', name: 'Apple' },
@@ -20,7 +28,11 @@
 
 <ListBox.Root {selectionMode} {selectionBehavior} {disabledIds} aria-label="Fruits list">
 	{#each fruits as fruit (fruit.id)}
-		<ListBox.Item id={fruit.id} textValue={fruit.name}>
+		<ListBox.Item
+			id={fruit.id}
+			textValue={fruit.name}
+			pressed={pressedIdSet.has(fruit.id) ? true : undefined}
+		>
 			{fruit.name}
 		</ListBox.Item>
 	{/each}

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

@@ -2,6 +2,7 @@ type Props = {
     selectionMode?: 'single' | 'multiple';
     selectionBehavior?: 'toggle' | 'replace';
     disabledIds?: Iterable<string | number>;
+    pressedIds?: Iterable<string | number>;
 };
 declare const ListboxTest: import("svelte").Component<Props, {}, "">;
 type ListboxTest = ReturnType<typeof ListboxTest>;

package/dist/listbox/root/listbox.svelte

@@ -1,6 +1,8 @@
 <script lang="ts" generics="T extends object = object">
 	import type { Snippet } from 'svelte';
+	import { onMount } from 'svelte';
 	import { createListBoxContext, type ListBoxContext } from './context';
+	import { trackInteractionModality } from '../../primitives/input-modality';
 
 	/**
 	 * Props for the ListBox component.
@@ -31,6 +33,8 @@
 		'aria-label'?: string;
 		/** Callback fired when the selection changes. */
 		onChange?: (value: Set<string | number>) => void;
+		/** Disable DOM focus handling on the root container for virtual-focus compositions. */
+		disableFocusHandling?: boolean;
 	};
 
 	let {
@@ -46,6 +50,7 @@
 		id,
 		'aria-label': ariaLabel,
 		onChange,
+		disableFocusHandling = false,
 		context = $bindable(),
 		element = $bindable()
 	}: ListBoxProps & { context?: ListBoxContext; element?: HTMLElement } = $props();
@@ -114,6 +119,43 @@
 
 	const itemsArray = $derived(items ? Array.from(items) : []);
 	const hasItems = $derived(itemsArray.length > 0 || itemCount > 0);
+	let hasMounted = $state(false);
+
+	let focusWithin = $state(false);
+
+	onMount(() => {
+		hasMounted = true;
+	});
+
+	function syncFocusWithin() {
+		focusWithin =
+			!!listboxElement &&
+			!!document.activeElement &&
+			listboxElement.contains(document.activeElement);
+	}
+
+	function handleFocusIn() {
+		focusWithin = true;
+	}
+
+	function handleFocusOut() {
+		queueMicrotask(syncFocusWithin);
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, event.target as HTMLElement | null);
+		ctx.setFocusVisible(false);
+		if (disableFocusHandling) {
+			event.preventDefault();
+		}
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		trackInteractionModality(event, event.target as HTMLElement | null);
+		if (focusWithin) {
+			ctx.setFocusVisible(true);
+		}
+	}
 </script>
 
 <div
@@ -123,8 +165,13 @@
 	aria-multiselectable={selectionMode === 'multiple'}
 	aria-label={ariaLabel}
 	class={className}
-	tabindex="0"
+	tabindex={disableFocusHandling ? undefined : 0}
+	data-focus-within={focusWithin || undefined}
 	use:keyboardAction
+	onfocusin={handleFocusIn}
+	onfocusout={handleFocusOut}
+	onmousedown={handleMouseDown}
+	onkeydown={handleKeyDown}
 >
 	{#if items && children}
 		{#each itemsArray as item (item)}
@@ -134,7 +181,7 @@
 		{@render (children as Snippet)()}
 	{/if}
 
-	{#if !hasItems && itemCount === 0}
+	{#if hasMounted && !hasItems && itemCount === 0}
 		{#if typeof emptyPlaceholder === 'string'}
 			<div role="option" aria-selected="false" aria-disabled="true" data-empty-placeholder>
 				{emptyPlaceholder}

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

@@ -26,12 +26,14 @@ declare function $$render<T extends object = object>(): {
         'aria-label'?: string;
         /** Callback fired when the selection changes. */
         onChange?: (value: Set<string | number>) => void;
+        /** Disable DOM focus handling on the root container for virtual-focus compositions. */
+        disableFocusHandling?: boolean;
     } & {
         context?: ListBoxContext;
         element?: HTMLElement;
     };
     exports: {};
-    bindings: "value" | "context" | "element";
+    bindings: "value" | "element" | "context";
     slots: {};
     events: {};
 };
@@ -39,7 +41,7 @@ declare class __sveltets_Render<T extends object = object> {
     props(): ReturnType<typeof $$render<T>>['props'];
     events(): ReturnType<typeof $$render<T>>['events'];
     slots(): ReturnType<typeof $$render<T>>['slots'];
-    bindings(): "value" | "context" | "element";
+    bindings(): "value" | "element" | "context";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/popover/README.md

@@ -12,6 +12,16 @@
 - Use `Popover.Content` inside `Popover.Root`, or in standalone mode with `open`, `triggerRef`, and `onOpenChange`.
 - Configure `isNonModal`, `shouldCloseOnInteractOutside`, and `shouldCloseOnBlur` to match your interaction model.
 
+## onOpenChange details
+
+`Popover.Root` and standalone `Popover.Content` use:
+
+- `onOpenChange(open, details)`
+- `details.reason`: `trigger-press | imperative-action | none | escape-key | outside-press | focus-out | close-press`
+- `details.event?`: native event that triggered the change when available
+- `details.cancel()`: prevents the open-state transition
+- `details.isCanceled`: reflects cancellation state inside the callback
+
 ## Anatomy
 
 Import the component and compose its parts: