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

package/dist/popover/root/popover-root.svelte

@@ -1,6 +1,20 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { setPopoverContext, type PopoverContext } from './context';
+	import { onDestroy } from 'svelte';
+	import {
+		setPopoverContext,
+		type PopoverCanonicalCloseReason,
+		type PopoverChangeReason,
+		type PopoverCloseReason,
+		type PopoverOpenChangeDetails,
+		type PopoverOpenReason,
+		type PopoverContext
+	} from './context';
+	import {
+		addTriggerBlurCleanup,
+		applyTriggerCloseFocusState,
+		clearTriggerFocusState
+	} from './focus-state';
 
 	/**
 	 * Popover.Root - State management wrapper for Popover components.
@@ -12,7 +26,7 @@
 		/** Initial open state for uncontrolled mode. */
 		defaultOpen?: boolean;
 		/** Callback when open state changes. */
-		onOpenChange?: (open: boolean) => void;
+		onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 		/** Reference to the trigger element. Can be set manually or via Popover.Trigger. */
 		triggerRef?: HTMLElement | null;
 		/** Children (Trigger and Content) */
@@ -26,6 +40,9 @@
 		triggerRef = $bindable<HTMLElement | null>(null),
 		children
 	}: PopoverRootProps = $props();
+	let closeReason: PopoverCanonicalCloseReason = $state('none');
+	let cleanupTriggerBlurListener: (() => void) | undefined;
+	let pendingTriggerCloseFocusFrame: number | undefined;
 
 	// Use function to capture initial value only (not reactive)
 	let isOpenInternal = $state((() => defaultOpen)());
@@ -33,39 +50,90 @@
 	const isControlled = $derived(open !== undefined);
 	const isOpen = $derived(isControlled ? open! : isOpenInternal);
 
-	function setOpen(value: boolean) {
-		if (isControlled) {
-			onOpenChange?.(value);
-		} else {
+	function setOpenWithDetails(
+		value: boolean,
+		incomingDetails: { reason: PopoverChangeReason; event?: Event }
+	) {
+		let canceled = false;
+		const details: PopoverOpenChangeDetails = {
+			reason: incomingDetails.reason,
+			event: incomingDetails.event,
+			cancel: () => {
+				canceled = true;
+			},
+			get isCanceled() {
+				return canceled;
+			}
+		};
+
+		onOpenChange?.(value, details);
+		if (details.isCanceled) return;
+
+		if (!isControlled) {
 			isOpenInternal = value;
-			onOpenChange?.(value);
 		}
-		// Sync bindable prop
+
 		open = value;
 	}
 
-	function toggle() {
-		setOpen(!isOpen);
+	function toggle(reason: PopoverOpenReason = 'trigger-press', event?: Event) {
+		setOpenWithDetails(!isOpen, { reason, event });
+	}
+
+	function openPopover(reason: PopoverOpenReason = 'imperative-action', event?: Event) {
+		closeReason = 'none';
+		setOpenWithDetails(true, { reason, event });
 	}
 
-	function openPopover() {
-		setOpen(true);
+	function clearPendingTriggerCloseFocus() {
+		if (pendingTriggerCloseFocusFrame === undefined) return;
+		cancelAnimationFrame(pendingTriggerCloseFocusFrame);
+		pendingTriggerCloseFocusFrame = undefined;
 	}
 
-	function closePopover() {
-		setOpen(false);
-		triggerRef?.focus();
+	function scheduleTriggerCloseFocus(
+		trigger: HTMLElement,
+		reason: PopoverCanonicalCloseReason,
+		event?: Event
+	) {
+		clearPendingTriggerCloseFocus();
+		pendingTriggerCloseFocusFrame = requestAnimationFrame(() => {
+			pendingTriggerCloseFocusFrame = undefined;
+			if (!trigger.isConnected) return;
+			applyTriggerCloseFocusState(trigger, reason, event);
+		});
+	}
+
+	function closePopover(reason: PopoverCloseReason = 'imperative-action', event?: Event) {
+		closeReason = reason;
+		const wasOpen = isOpen;
+		setOpenWithDetails(false, { reason, event });
+		if (!wasOpen || isOpen) return;
+		if (!triggerRef) return;
+		scheduleTriggerCloseFocus(triggerRef, reason, event);
 	}
 
 	function setTriggerRef(el: HTMLElement | null) {
+		clearPendingTriggerCloseFocus();
+		cleanupTriggerBlurListener?.();
+		cleanupTriggerBlurListener = undefined;
+		if (triggerRef && triggerRef !== el) {
+			clearTriggerFocusState(triggerRef);
+		}
 		triggerRef = el;
+		if (!triggerRef) return;
+		const currentTrigger = triggerRef;
+		cleanupTriggerBlurListener = addTriggerBlurCleanup(currentTrigger);
 	}
 
-	function handleOpenChange(newOpen: boolean) {
-		setOpen(newOpen);
+	function handleOpenChange(newOpen: boolean, details: PopoverOpenChangeDetails) {
+		setOpenWithDetails(newOpen, { reason: details.reason, event: details.event });
 	}
 
 	const ctx: PopoverContext = {
+		get closeReason() {
+			return closeReason;
+		},
 		get isOpen() {
 			return isOpen;
 		},
@@ -80,6 +148,11 @@
 	};
 
 	setPopoverContext(ctx);
+
+	onDestroy(() => {
+		clearPendingTriggerCloseFocus();
+		cleanupTriggerBlurListener?.();
+	});
 </script>
 
 {#if children}

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

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import { type PopoverOpenChangeDetails } from './context';
 /**
  * Popover.Root - State management wrapper for Popover components.
  * Provides context for Trigger and Content children.
@@ -9,7 +10,7 @@ type PopoverRootProps = {
     /** Initial open state for uncontrolled mode. */
     defaultOpen?: boolean;
     /** Callback when open state changes. */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
     /** Reference to the trigger element. Can be set manually or via Popover.Trigger. */
     triggerRef?: HTMLElement | null;
     /** Children (Trigger and Content) */

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

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import { Popover } from '../index';
+	import type { PopoverOpenChangeDetails } from './context';
 
 	type Props = {
 		open?: boolean;
@@ -7,7 +8,7 @@
 		isNonModal?: boolean;
 		shouldCloseOnInteractOutside?: boolean;
 		shouldCloseOnEscape?: boolean;
-		onOpenChange?: (open: boolean) => void;
+		onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 	};
 
 	let {

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

@@ -1,10 +1,11 @@
+import type { PopoverOpenChangeDetails } from './context';
 type Props = {
     open?: boolean;
     defaultOpen?: boolean;
     isNonModal?: boolean;
     shouldCloseOnInteractOutside?: boolean;
     shouldCloseOnEscape?: boolean;
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 };
 declare const PopoverTest: import("svelte").Component<Props, {}, "">;
 type PopoverTest = ReturnType<typeof PopoverTest>;

package/dist/popover/trigger/README.md

@@ -0,0 +1,23 @@
+# Popover Trigger
+
+## API reference
+
+### Popover.Trigger
+
+Name: `Popover.Trigger`  
+Description: Wrapper trigger part that finds a button in its children, wires it as trigger, and toggles the popover on click.
+
+| Prop       | Type      | Default     | Description                                                                    |
+| ---------- | --------- | ----------- | ------------------------------------------------------------------------------ |
+| `children` | `Snippet` | `undefined` | Child content that includes a trigger element (`button` or `[role="button"]`). |
+
+### Popover.TriggerButton
+
+Name: `Popover.TriggerButton`  
+Description: Pre-wired trigger button part for popover toggling.
+
+| Prop           | Type                   | Default     | Description                                                                |
+| -------------- | ---------------------- | ----------- | -------------------------------------------------------------------------- |
+| `children`     | `Snippet`              | `undefined` | Button content.                                                            |
+| `class`        | `string`               | `''`        | CSS class names for the button.                                            |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional native button attributes, excluding reserved trigger semantics. |

package/dist/popover/trigger/popover-trigger-button.svelte

@@ -1,20 +1,24 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { getPopoverTriggerContext } from '../root/context';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { ButtonRoot } from '../../button/index.js';
+	import { getPopoverContext } from '../root/context';
 
-	type PopoverTriggerButtonProps = {
+	type PopoverTriggerButtonProps = Omit<
+		HTMLButtonAttributes,
+		// Keep the trigger semantics stable
+		'type' | 'class' | 'children' | 'onclick' | 'aria-haspopup' | 'aria-expanded'
+	> & {
 		/** Button content */
 		children?: Snippet;
 		/** Additional class */
 		class?: string;
-		/** Any other props */
-		[key: string]: unknown;
 	};
 
 	let { children, class: className = '', ...restProps }: PopoverTriggerButtonProps = $props();
 
 	let buttonRef: HTMLButtonElement | null = $state(null);
-	const ctx = getPopoverTriggerContext();
+	const ctx = getPopoverContext();
 
 	$effect(() => {
 		if (buttonRef && ctx) {
@@ -22,13 +26,13 @@
 		}
 	});
 
-	function handleClick() {
-		ctx?.toggle();
+	function handleClick(event: MouseEvent) {
+		ctx?.toggle('trigger-press', event);
 	}
 </script>
 
-<button
-	bind:this={buttonRef}
+<ButtonRoot
+	bind:element={buttonRef}
 	class={className}
 	type="button"
 	aria-expanded={ctx?.isOpen ?? false}
@@ -39,4 +43,4 @@
 	{#if children}
 		{@render children()}
 	{/if}
-</button>
+</ButtonRoot>

package/dist/popover/trigger/popover-trigger-button.svelte.d.ts

@@ -1,11 +1,10 @@
 import type { Snippet } from 'svelte';
-type PopoverTriggerButtonProps = {
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type PopoverTriggerButtonProps = Omit<HTMLButtonAttributes, 'type' | 'class' | 'children' | 'onclick' | 'aria-haspopup' | 'aria-expanded'> & {
     /** Button content */
     children?: Snippet;
     /** Additional class */
     class?: string;
-    /** Any other props */
-    [key: string]: unknown;
 };
 declare const PopoverTriggerButton: import("svelte").Component<PopoverTriggerButtonProps, {}, "">;
 type PopoverTriggerButton = ReturnType<typeof PopoverTriggerButton>;

package/dist/popover/trigger/popover-trigger-multi-button-test.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+	import { Popover } from '../../popover';
+</script>
+
+<Popover.Root>
+	<Popover.Trigger>
+		<div>
+			<button type="button">First Popover Trigger</button>
+			<button type="button">Second Popover Trigger</button>
+		</div>
+	</Popover.Trigger>
+
+	<Popover.Content>
+		<p>Popover body</p>
+	</Popover.Content>
+</Popover.Root>

package/dist/popover/trigger/popover-trigger-multi-button-test.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const PopoverTriggerMultiButtonTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type PopoverTriggerMultiButtonTest = InstanceType<typeof PopoverTriggerMultiButtonTest>;
+export default PopoverTriggerMultiButtonTest;

package/dist/popover/trigger/popover-trigger.svelte

@@ -24,17 +24,26 @@
 	const popoverCtx = ctx;
 
 	let wrapperRef: HTMLElement | null = $state(null);
+	let activeTrigger: HTMLElement | null = null;
+
+	function setActiveTrigger(button: HTMLElement) {
+		if (activeTrigger && activeTrigger !== button) {
+			activeTrigger.setAttribute('aria-expanded', 'false');
+		}
+
+		activeTrigger = button;
+		popoverCtx.setTriggerRef(button);
+		button.setAttribute('aria-haspopup', 'dialog');
+		button.setAttribute('aria-expanded', String(popoverCtx.isOpen));
+	}
 
 	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 (!popoverCtx.triggerRef) {
-				popoverCtx.setTriggerRef(button);
-			}
-			popoverCtx.toggle();
+			setActiveTrigger(button);
+			popoverCtx.toggle('trigger-press', event);
 		}
 	}
 
@@ -43,8 +52,7 @@
 			// Find and set up the trigger button
 			const firstButton = wrapperRef.querySelector('button, [role="button"]') as HTMLElement | null;
 			if (firstButton) {
-				popoverCtx.setTriggerRef(firstButton);
-				firstButton.setAttribute('aria-haspopup', 'dialog');
+				setActiveTrigger(firstButton);
 			}
 		}
 
@@ -59,6 +67,10 @@
 
 	$effect(() => {
 		if (popoverCtx.triggerRef) {
+			if (activeTrigger !== popoverCtx.triggerRef) {
+				activeTrigger = popoverCtx.triggerRef;
+			}
+			popoverCtx.triggerRef.setAttribute('aria-haspopup', 'dialog');
 			popoverCtx.triggerRef.setAttribute('aria-expanded', String(popoverCtx.isOpen));
 		}
 	});

package/dist/portal/portal.svelte

@@ -18,6 +18,8 @@
 		if (!browser || !wrapper) return;
 
 		await tick();
+		const wrapperNode = wrapper;
+		if (!wrapperNode) return;
 
 		const targetEl = document.querySelector(target);
 		if (!targetEl) {
@@ -25,7 +27,7 @@
 			return;
 		}
 
-		targetEl.appendChild(wrapper);
+		targetEl.appendChild(wrapperNode);
 	});
 
 	onDestroy(() => {

package/dist/primitives/click-outside.d.ts

@@ -4,7 +4,7 @@
  */
 export type ClickOutsideOptions = {
     /** Callback when clicking outside. */
-    handler: () => void;
+    handler: (event: MouseEvent) => void;
     /** Whether the listener is enabled. */
     enabled?: boolean;
     /** Elements to ignore (clicks on these won't trigger). */

package/dist/primitives/click-outside.js

@@ -41,7 +41,7 @@ export function clickOutside(node, options) {
         // This prevents closing when clicking on nested popovers/dialogs
         if (isInTopLayer(target))
             return;
-        handler();
+        handler(event);
     }
     if (enabled) {
         document.addEventListener('mousedown', handleClick, true);

package/dist/primitives/floating.js

@@ -84,11 +84,15 @@ export function createFloating(anchorElement, options = {}) {
             size({
                 apply({ rects, availableWidth, availableHeight, elements, placement }) {
                     const floatingEl = elements.floating;
+                    const clampedAvailableWidth = Math.max(0, availableWidth);
+                    const clampedAvailableHeight = Math.max(0, availableHeight);
                     floatingEl.style.setProperty('--trigger-width', `${rects.reference.width}px`);
                     floatingEl.style.setProperty('--trigger-height', `${rects.reference.height}px`);
-                    floatingEl.style.setProperty('--available-width', `${availableWidth}px`);
-                    floatingEl.style.setProperty('--available-height', `${availableHeight}px`);
+                    floatingEl.style.setProperty('--available-width', `${clampedAvailableWidth}px`);
+                    floatingEl.style.setProperty('--available-height', `${clampedAvailableHeight}px`);
                     floatingEl.style.setProperty('--transform-origin', getTransformOrigin(placement));
+                    floatingEl.style.maxWidth = `${clampedAvailableWidth}px`;
+                    floatingEl.style.maxHeight = `${clampedAvailableHeight}px`;
                 }
             })
         ];
@@ -141,11 +145,15 @@ export function floating(floatingElement, options) {
         size({
             apply({ rects, availableWidth, availableHeight, elements, placement }) {
                 const floatingEl = elements.floating;
+                const clampedAvailableWidth = Math.max(0, availableWidth);
+                const clampedAvailableHeight = Math.max(0, availableHeight);
                 floatingEl.style.setProperty('--trigger-width', `${rects.reference.width}px`);
                 floatingEl.style.setProperty('--trigger-height', `${rects.reference.height}px`);
-                floatingEl.style.setProperty('--available-width', `${availableWidth}px`);
-                floatingEl.style.setProperty('--available-height', `${availableHeight}px`);
+                floatingEl.style.setProperty('--available-width', `${clampedAvailableWidth}px`);
+                floatingEl.style.setProperty('--available-height', `${clampedAvailableHeight}px`);
                 floatingEl.style.setProperty('--transform-origin', getTransformOrigin(placement));
+                floatingEl.style.maxWidth = `${clampedAvailableWidth}px`;
+                floatingEl.style.maxHeight = `${clampedAvailableHeight}px`;
             }
         })
     ];

package/dist/primitives/focus-trap.d.ts

@@ -2,6 +2,11 @@
  * Focus trap primitive.
  * Traps keyboard focus within a container element.
  */
+export type FocusTrapOptions = {
+    enabled?: boolean;
+    restoreFocus?: boolean;
+    initialFocus?: HTMLElement | string | (() => HTMLElement | null | undefined);
+};
 /**
  * Svelte action that traps focus within an element.
  *
@@ -13,7 +18,7 @@
  * </div>
  * ```
  */
-export declare function focusTrap(node: HTMLElement, enabled?: boolean): {
-    update(newEnabled: boolean): void;
+export declare function focusTrap(node: HTMLElement, options?: boolean | FocusTrapOptions): {
+    update(newOptions: boolean | FocusTrapOptions): void;
     destroy(): void;
 };

package/dist/primitives/focus-trap.js

@@ -2,6 +2,7 @@
  * Focus trap primitive.
  * Traps keyboard focus within a container element.
  */
+import { focusWithModality, getInteractionModality } from './input-modality';
 const FOCUSABLE_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
@@ -11,8 +12,29 @@ const FOCUSABLE_SELECTOR = [
     '[tabindex]:not([tabindex="-1"])',
     '[contenteditable="true"]'
 ].join(', ');
+function resolveEnabled(options) {
+    if (typeof options === 'boolean')
+        return options;
+    return options.enabled ?? true;
+}
+function resolveRestoreFocus(options) {
+    if (typeof options === 'boolean')
+        return true;
+    return options.restoreFocus ?? true;
+}
+function resolveInitialFocus(container, initialFocus) {
+    if (!initialFocus)
+        return null;
+    if (typeof initialFocus === 'function') {
+        return initialFocus() ?? null;
+    }
+    if (typeof initialFocus === 'string') {
+        return container.querySelector(initialFocus);
+    }
+    return initialFocus;
+}
 function getFocusableElements(container) {
-    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetParent !== null);
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => element.offsetParent !== null);
 }
 /**
  * Svelte action that traps focus within an element.
@@ -25,8 +47,11 @@ function getFocusableElements(container) {
  * </div>
  * ```
  */
-export function focusTrap(node, enabled = true) {
+export function focusTrap(node, options = true) {
     let previousActiveElement = null;
+    let enabled = resolveEnabled(options);
+    let restoreFocus = resolveRestoreFocus(options);
+    let initialFocus = typeof options === 'boolean' ? undefined : options.initialFocus;
     function handleKeydown(event) {
         if (event.key !== 'Tab')
             return;
@@ -49,12 +74,11 @@ export function focusTrap(node, enabled = true) {
                 event.preventDefault();
                 lastElement.focus();
             }
+            return;
         }
-        else {
-            if (document.activeElement === lastElement || document.activeElement === node) {
-                event.preventDefault();
-                firstElement.focus();
-            }
+        if (document.activeElement === lastElement || document.activeElement === node) {
+            event.preventDefault();
+            firstElement.focus();
         }
     }
     function activate() {
@@ -62,21 +86,25 @@ export function focusTrap(node, enabled = true) {
         if (!node.hasAttribute('tabindex')) {
             node.setAttribute('tabindex', '-1');
         }
-        // Focus first focusable element, or the container if none
         requestAnimationFrame(() => {
+            const initialFocusTarget = resolveInitialFocus(node, initialFocus);
+            const modality = getInteractionModality();
+            if (initialFocusTarget && initialFocusTarget.isConnected) {
+                focusWithModality(initialFocusTarget, modality);
+                return;
+            }
             const focusableElements = getFocusableElements(node);
             if (focusableElements.length > 0) {
-                focusableElements[0].focus();
-            }
-            else {
-                node.focus();
+                focusWithModality(focusableElements[0], modality);
+                return;
             }
+            focusWithModality(node, modality);
         });
         document.addEventListener('keydown', handleKeydown, true);
     }
     function deactivate() {
         document.removeEventListener('keydown', handleKeydown, true);
-        if (previousActiveElement && previousActiveElement.focus) {
+        if (restoreFocus && previousActiveElement && previousActiveElement.focus) {
             previousActiveElement.focus();
         }
     }
@@ -84,14 +112,19 @@ export function focusTrap(node, enabled = true) {
         activate();
     }
     return {
-        update(newEnabled) {
-            if (newEnabled && !enabled) {
+        update(newOptions) {
+            const nextEnabled = resolveEnabled(newOptions);
+            const nextRestoreFocus = resolveRestoreFocus(newOptions);
+            if (nextEnabled && !enabled) {
                 activate();
             }
-            else if (!newEnabled && enabled) {
+            else if (!nextEnabled && enabled) {
                 deactivate();
             }
-            enabled = newEnabled;
+            options = newOptions;
+            enabled = nextEnabled;
+            restoreFocus = nextRestoreFocus;
+            initialFocus = typeof newOptions === 'boolean' ? undefined : newOptions.initialFocus;
         },
         destroy() {
             if (enabled) {

package/dist/primitives/index.d.ts

@@ -4,3 +4,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/index.js

@@ -5,3 +5,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/input-modality.d.ts

@@ -0,0 +1,7 @@
+export type InputModality = 'keyboard' | 'pointer' | 'virtual';
+export declare function initInputModality(target?: HTMLElement | null): void;
+export declare function trackInteractionModality(event?: Event, target?: HTMLElement | null): void;
+export declare function getInteractionModality(): InputModality;
+export declare function shouldShowFocusVisible(target: HTMLElement | null): boolean;
+export declare function focusWithModality(target: HTMLElement, modality: InputModality, options?: FocusOptions): void;
+export declare function resolveCloseInteractionModality(reason: string, event?: Event): InputModality;