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

package/dist/popover/root/README.md

@@ -7,24 +7,19 @@
 Name: `Popover.Root`  
 Description: Root state container that controls open state, trigger ref, and toggle/open/close 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`                 | `undefined` | Composed trigger and content parts.            |
+- `open`: `boolean` (default: `undefined`) — Controlled open state. Supports `bind:open`.
+- `defaultOpen`: `boolean` (default: `false`) — Initial open state in uncontrolled mode.
+- `onOpenChange`: `(open: boolean, details) => void` (default: `undefined`) — Called whenever open state changes. `details` includes `reason`, optional `event`, `cancel()`, and `isCanceled`.
+- `triggerRef`: `HTMLElement | null` (default: `null`) — Trigger reference. Supports `bind:triggerRef`.
+- `children`: `Snippet` (default: `undefined`) — Composed trigger and content parts.
 
 ### Context utilities
 
 Name: `context.ts` helpers  
 Description: Context APIs used by trigger and content parts.
 
-| Prop                       | Type                                | Default             | Description                              |
-| -------------------------- | ----------------------------------- | ------------------- | ---------------------------------------- |
-| `setPopoverContext`        | `(ctx: PopoverContext) => void`     | `-`                 | Registers popover context.               |
-| `getPopoverContext`        | `() => PopoverContext \| undefined` | `-`                 | Returns popover context when available.  |
-| `PopoverContext`           | `type`                              | `-`                 | Context contract with state and actions. |
-| `PopoverTriggerContext`    | `type alias`                        | `PopoverContext`    | Backward-compatible alias.               |
-| `setPopoverTriggerContext` | `alias`                             | `setPopoverContext` | Backward-compatible alias.               |
-| `getPopoverTriggerContext` | `alias`                             | `getPopoverContext` | Backward-compatible alias.               |
+| Prop                | Type                                | Default | Description                              |
+| ------------------- | ----------------------------------- | ------- | ---------------------------------------- |
+| `setPopoverContext` | `(ctx: PopoverContext) => void`     | `-`     | Registers popover context.               |
+| `getPopoverContext` | `() => PopoverContext \| undefined` | `-`     | Returns popover context when available.  |
+| `PopoverContext`    | `type`                              | `-`     | Context contract with state and actions. |

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

@@ -1,7 +1,19 @@
+export type PopoverCanonicalCloseReason = 'escape-key' | 'outside-press' | 'focus-out' | 'close-press' | 'imperative-action' | 'none';
+export type PopoverCloseReason = PopoverCanonicalCloseReason;
+export type PopoverOpenReason = 'trigger-press' | 'imperative-action' | 'none';
+export type PopoverChangeReason = PopoverOpenReason | PopoverCloseReason;
+export type PopoverOpenChangeDetails = {
+    reason: PopoverChangeReason;
+    event?: Event;
+    cancel: () => void;
+    isCanceled: boolean;
+};
 /**
  * Context shared between Popover components (Root, Trigger, Content).
  */
 export type PopoverContext = {
+    /** Reason why popover is closing */
+    closeReason: PopoverCanonicalCloseReason;
     /** Whether the popover is open */
     isOpen: boolean;
     /** Reference to the trigger element */
@@ -9,16 +21,13 @@ export type PopoverContext = {
     /** Set the trigger ref (used by Trigger component) */
     setTriggerRef: (el: HTMLElement | null) => void;
     /** Toggle popover open state */
-    toggle: () => void;
+    toggle: (reason?: PopoverOpenReason, event?: Event) => void;
     /** Open the popover */
-    open: () => void;
+    open: (reason?: PopoverOpenReason, event?: Event) => void;
     /** Close the popover and return focus to trigger */
-    close: () => void;
+    close: (reason?: PopoverCloseReason, event?: Event) => void;
     /** Called when popover open state changes */
-    onOpenChange: (open: boolean) => void;
+    onOpenChange: (open: boolean, details: PopoverOpenChangeDetails) => void;
 };
 export declare function setPopoverContext(ctx: PopoverContext): void;
 export declare function getPopoverContext(): PopoverContext | undefined;
-export type PopoverTriggerContext = PopoverContext;
-export declare const setPopoverTriggerContext: typeof setPopoverContext;
-export declare const getPopoverTriggerContext: typeof getPopoverContext;

package/dist/popover/root/context.js

@@ -6,5 +6,3 @@ export function setPopoverContext(ctx) {
 export function getPopoverContext() {
     return getContext(POPOVER_CONTEXT_KEY);
 }
-export const setPopoverTriggerContext = setPopoverContext;
-export const getPopoverTriggerContext = getPopoverContext;

package/dist/popover/root/focus-state.d.ts

@@ -0,0 +1,4 @@
+import type { PopoverCloseReason } from './context';
+export declare function clearTriggerFocusState(trigger: HTMLElement): void;
+export declare function applyTriggerCloseFocusState(trigger: HTMLElement, reason: PopoverCloseReason, event?: Event): void;
+export declare function addTriggerBlurCleanup(trigger: HTMLElement, once?: boolean): () => void;

package/dist/popover/root/focus-state.js

@@ -0,0 +1,33 @@
+import { focusWithModality, resolveCloseInteractionModality } from '../../primitives/input-modality';
+export function clearTriggerFocusState(trigger) {
+    delete trigger.dataset.focused;
+    delete trigger.dataset.focusVisible;
+}
+export function applyTriggerCloseFocusState(trigger, reason, event) {
+    const closeModality = resolveCloseInteractionModality(reason, event);
+    focusWithModality(trigger, closeModality);
+    if (reason === 'outside-press' || reason === 'escape-key') {
+        trigger.dataset.focused = 'true';
+    }
+    else {
+        delete trigger.dataset.focused;
+    }
+    if (closeModality === 'keyboard') {
+        trigger.dataset.focusVisible = 'true';
+    }
+    else {
+        delete trigger.dataset.focusVisible;
+    }
+}
+export function addTriggerBlurCleanup(trigger, once = false) {
+    const handleBlur = () => {
+        clearTriggerFocusState(trigger);
+        if (once) {
+            trigger.removeEventListener('blur', handleBlur);
+        }
+    };
+    trigger.addEventListener('blur', handleBlur);
+    return () => {
+        trigger.removeEventListener('blur', handleBlur);
+    };
+}

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/popover-trigger-button-root-test.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import { Button } from '../../button';
+	import { Popover } from '../index';
+</script>
+
+<Popover.Root>
+	<Popover.Trigger>
+		<Button.Root>Open Button Root Popover</Button.Root>
+	</Popover.Trigger>
+
+	<Popover.Content class="popover-content">
+		<div class="popover-body">
+			<h3>Popover Title</h3>
+			<p>Popover content goes here.</p>
+		</div>
+	</Popover.Content>
+</Popover.Root>

package/dist/popover/trigger/popover-trigger-button-root-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 PopoverTriggerButtonRootTest: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type PopoverTriggerButtonRootTest = InstanceType<typeof PopoverTriggerButtonRootTest>;
+export default PopoverTriggerButtonRootTest;

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

@@ -1,7 +1,8 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLButtonAttributes } from 'svelte/elements';
-	import { getPopoverTriggerContext } from '../root/context';
+	import { ButtonRoot } from '../../button/index.js';
+	import { getPopoverContext } from '../root/context';
 
 	type PopoverTriggerButtonProps = Omit<
 		HTMLButtonAttributes,
@@ -17,7 +18,7 @@
 	let { children, class: className = '', ...restProps }: PopoverTriggerButtonProps = $props();
 
 	let buttonRef: HTMLButtonElement | null = $state(null);
-	const ctx = getPopoverTriggerContext();
+	const ctx = getPopoverContext();
 
 	$effect(() => {
 		if (buttonRef && ctx) {
@@ -25,15 +26,16 @@
 		}
 	});
 
-	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"
+	pressed={ctx?.isOpen ?? false}
 	aria-expanded={ctx?.isOpen ?? false}
 	aria-haspopup="dialog"
 	onclick={handleClick}
@@ -42,4 +44,4 @@
 	{#if children}
 		{@render children()}
 	{/if}
-</button>
+</ButtonRoot>

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

@@ -26,15 +26,28 @@
 	let wrapperRef: HTMLElement | null = $state(null);
 	let activeTrigger: HTMLElement | null = null;
 
+	function syncTriggerState(button: HTMLElement) {
+		button.setAttribute('aria-haspopup', 'dialog');
+		button.setAttribute('aria-expanded', String(popoverCtx.isOpen));
+		if (popoverCtx.isOpen) {
+			button.dataset.pressedWhenExpanded = 'true';
+			button.dataset.pressed = 'true';
+		} else {
+			delete button.dataset.pressedWhenExpanded;
+			delete button.dataset.pressed;
+		}
+	}
+
 	function setActiveTrigger(button: HTMLElement) {
 		if (activeTrigger && activeTrigger !== button) {
 			activeTrigger.setAttribute('aria-expanded', 'false');
+			delete activeTrigger.dataset.pressed;
+			delete activeTrigger.dataset.pressedWhenExpanded;
 		}
 
 		activeTrigger = button;
 		popoverCtx.setTriggerRef(button);
-		button.setAttribute('aria-haspopup', 'dialog');
-		button.setAttribute('aria-expanded', String(popoverCtx.isOpen));
+		syncTriggerState(button);
 	}
 
 	function handleClick(event: MouseEvent) {
@@ -43,7 +56,7 @@
 
 		if (button && wrapperRef?.contains(button)) {
 			setActiveTrigger(button);
-			popoverCtx.toggle();
+			popoverCtx.toggle('trigger-press', event);
 		}
 	}
 
@@ -70,8 +83,7 @@
 			if (activeTrigger !== popoverCtx.triggerRef) {
 				activeTrigger = popoverCtx.triggerRef;
 			}
-			popoverCtx.triggerRef.setAttribute('aria-haspopup', 'dialog');
-			popoverCtx.triggerRef.setAttribute('aria-expanded', String(popoverCtx.isOpen));
+			syncTriggerState(popoverCtx.triggerRef);
 		}
 	});
 </script>

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;
 };