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

package/dist/popover/content/README.md

@@ -23,3 +23,14 @@ Description: Floating panel rendered in a portal. Supports context mode (`Popove
 | `triggerRef`                   | `HTMLElement \| null`            | `null`      | Trigger reference in standalone mode.                                          |
 | `onOpenChange`                 | `(open: boolean) => void`        | `undefined` | Open-state callback in standalone mode.                                        |
 | `...restProps`                 | `HTMLAttributes<HTMLDivElement>` | `-`         | Additional panel attributes.                                                   |
+
+## Styling state
+
+`Popover.Content` exposes RAC-style data attributes that can drive CSS or Tailwind animation utilities:
+
+- `data-state="open" | "closed"`
+- `data-entering`
+- `data-exiting`
+- `data-placement="top" | "right" | "bottom" | "left"`
+
+Exit animations keep the panel mounted until the element's own CSS transition or animation finishes. If no motion is defined, the panel unmounts immediately.

package/dist/popover/content/popover-content-controlled-close-test.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import { Popover } from '../index';
+
+	let open = $state(false);
+</script>
+
+<Popover.Root bind:open>
+	<Popover.Trigger>
+		<button type="button">Open Popover</button>
+	</Popover.Trigger>
+
+	<Popover.Content class="popover-content presence-animation">
+		<div class="popover-body">
+			<h3>Popover Title</h3>
+			<p>Popover content goes here.</p>
+			<button type="button" class="apply-btn" onclick={() => (open = false)}>Apply</button>
+		</div>
+	</Popover.Content>
+</Popover.Root>
+
+<style>
+	:global(.presence-animation) {
+		opacity: 1;
+		transition: opacity 0.2s linear;
+	}
+
+	:global(.presence-animation[data-exiting]) {
+		opacity: 0;
+	}
+</style>

package/dist/popover/content/popover-content-controlled-close-test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const PopoverContentControlledCloseTest: import("svelte").Component<Record<string, never>, {}, "">;
+type PopoverContentControlledCloseTest = ReturnType<typeof PopoverContentControlledCloseTest>;
+export default PopoverContentControlledCloseTest;

package/dist/popover/content/popover-content-standalone-test.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+	import { Popover } from '../index';
+	import type { PopoverOpenChangeDetails } from '../root/context';
+
+	type Props = {
+		preventClose?: boolean;
+	};
+
+	let { preventClose = true }: Props = $props();
+
+	let open = $state(true);
+	let triggerRef = $state<HTMLElement | null>(null);
+
+	function handleOpenChange(nextOpen: boolean, details: PopoverOpenChangeDetails) {
+		if (!nextOpen && preventClose) {
+			details.cancel();
+		}
+		if (!details.isCanceled) {
+			open = nextOpen;
+		}
+	}
+</script>
+
+<button bind:this={triggerRef} type="button">Standalone Trigger</button>
+
+<Popover.Content {open} {triggerRef} onOpenChange={handleOpenChange}>
+	<div>Standalone content</div>
+</Popover.Content>

package/dist/popover/content/popover-content-standalone-test.svelte.d.ts

@@ -0,0 +1,6 @@
+type Props = {
+    preventClose?: boolean;
+};
+declare const PopoverContentStandaloneTest: import("svelte").Component<Props, {}, "">;
+type PopoverContentStandaloneTest = ReturnType<typeof PopoverContentStandaloneTest>;
+export default PopoverContentStandaloneTest;

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

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import { Popover } from '../index';
+	import type { PopoverOpenChangeDetails } from '../root/context';
 
 	type Props = {
 		open?: boolean;
@@ -8,7 +9,8 @@
 		shouldCloseOnInteractOutside?: boolean;
 		shouldCloseOnEscape?: boolean;
 		shouldCloseOnBlur?: boolean;
-		onOpenChange?: (open: boolean) => void;
+		class?: string;
+		onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 	};
 
 	let {
@@ -18,6 +20,7 @@
 		shouldCloseOnInteractOutside = true,
 		shouldCloseOnEscape = true,
 		shouldCloseOnBlur,
+		class: className = '',
 		onOpenChange
 	}: Props = $props();
 </script>
@@ -28,7 +31,7 @@
 	</Popover.Trigger>
 
 	<Popover.Content
-		class="popover-content"
+		class={`popover-content ${className}`.trim()}
 		{isNonModal}
 		{shouldCloseOnInteractOutside}
 		{shouldCloseOnEscape}
@@ -41,3 +44,30 @@
 		</div>
 	</Popover.Content>
 </Popover.Root>
+
+<style>
+	:global(.presence-animation) {
+		opacity: 1;
+		transition: opacity 0.2s linear;
+	}
+
+	:global(.presence-animation[data-entering]) {
+		animation: popover-enter 0.2s linear;
+	}
+
+	:global(.presence-animation[data-exiting]) {
+		opacity: 0;
+	}
+
+	@keyframes popover-enter {
+		from {
+			opacity: 0;
+			transform: scale(0.96);
+		}
+
+		to {
+			opacity: 1;
+			transform: scale(1);
+		}
+	}
+</style>

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

@@ -1,3 +1,4 @@
+import type { PopoverOpenChangeDetails } from '../root/context';
 type Props = {
     open?: boolean;
     defaultOpen?: boolean;
@@ -5,7 +6,8 @@ type Props = {
     shouldCloseOnInteractOutside?: boolean;
     shouldCloseOnEscape?: boolean;
     shouldCloseOnBlur?: boolean;
-    onOpenChange?: (open: boolean) => void;
+    class?: string;
+    onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 };
 declare const PopoverContentTest: import("svelte").Component<Props, {}, "">;
 type PopoverContentTest = ReturnType<typeof PopoverContentTest>;

package/dist/popover/content/popover-content.svelte

@@ -4,12 +4,21 @@
 	import { onMount, onDestroy } from 'svelte';
 	import { browser } from '$app/environment';
 	import { floating, type ExtendedPlacement } from '../../primitives/floating';
-	import { focusTrap } from '../../primitives/focus-trap';
+	import { focusTrap, type FocusTrapOptions } from '../../primitives/focus-trap';
 	import { scrollLock } from '../../primitives/scroll-lock';
 	import { clickOutside } from '../../primitives/click-outside';
 	import { ariaHideOutside } from '../../primitives/aria-hide-outside';
 	import { Portal } from '../../portal';
-	import { getPopoverContext } from '../root/context';
+	import {
+		getPopoverContext,
+		type PopoverOpenChangeDetails,
+		type PopoverCloseReason
+	} from '../root/context';
+	import {
+		addTriggerBlurCleanup,
+		applyTriggerCloseFocusState,
+		clearTriggerFocusState
+	} from '../root/focus-state';
 
 	/**
 	 * Popover.Content - The floating content panel.
@@ -36,17 +45,19 @@
 		shouldCloseOnEscape?: boolean;
 		/** Whether losing focus (blur) should close the popover. Defaults to true for non-modal popovers. */
 		shouldCloseOnBlur?: boolean;
+		/** Element or selector to focus first when modal trap activates. */
+		initialFocus?: FocusTrapOptions['initialFocus'];
 		// Standalone mode props (used when not inside Popover.Root)
 		/** Controlled open state (standalone mode). */
 		open?: boolean;
 		/** Reference to the trigger element (standalone mode). */
 		triggerRef?: HTMLElement | null;
 		/** Callback when open state changes (standalone mode). */
-		onOpenChange?: (open: boolean) => void;
+		onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 	} & Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'>;
 
 	let {
-		offset = 8,
+		offset = 4,
 		placement = 'bottom',
 		shouldFlip = true,
 		boundaryElement = null,
@@ -56,6 +67,7 @@
 		shouldCloseOnInteractOutside = true,
 		shouldCloseOnEscape = true,
 		shouldCloseOnBlur,
+		initialFocus,
 		// Standalone mode props
 		open: openProp,
 		triggerRef: triggerRefProp = null,
@@ -73,28 +85,204 @@
 	const shouldCloseOnBlurResolved = $derived(shouldCloseOnBlur ?? isNonModal);
 
 	let popoverRef: HTMLElement | undefined = $state();
+	let cleanupStandaloneTriggerBlurListener: (() => void) | undefined;
+	let pendingStandaloneTriggerCloseFocusFrame: number | undefined;
+	let trackedStandaloneTrigger: HTMLElement | null = null;
+	let isMounted = $state(false);
+	let isEntering = $state(false);
+	let isExiting = $state(false);
+	let resolvedPlacement = $state<'top' | 'right' | 'bottom' | 'left'>('bottom');
+	let motionTimeout: number | undefined;
+	let pendingMotionFrame: number | undefined;
+	let cleanupMotionListeners: (() => void) | undefined;
+	let motionId = 0;
+	let previousOpen = $state(false);
+	let closeHandledInternally = false;
 
-	function close() {
-		if (isStandalone) {
-			onOpenChangeProp?.(false);
-			triggerRefProp?.focus();
-		} else {
-			ctx!.close();
+	function parseTimeList(value: string) {
+		return value
+			.split(',')
+			.map((entry) => entry.trim())
+			.filter(Boolean)
+			.map((entry) => {
+				if (entry.endsWith('ms')) return Number.parseFloat(entry);
+				if (entry.endsWith('s')) return Number.parseFloat(entry) * 1000;
+				return Number.parseFloat(entry) || 0;
+			});
+	}
+
+	function getMaxTime(duration: string, delay: string) {
+		const durations = parseTimeList(duration);
+		const delays = parseTimeList(delay);
+		const length = Math.max(durations.length, delays.length);
+
+		let maxTime = 0;
+		for (let index = 0; index < length; index += 1) {
+			const total =
+				(durations[index] ?? durations[durations.length - 1] ?? 0) +
+				(delays[index] ?? delays[delays.length - 1] ?? 0);
+			maxTime = Math.max(maxTime, total);
 		}
+
+		return maxTime;
+	}
+
+	function getMotionTime(element: HTMLElement) {
+		const styles = getComputedStyle(element);
+		const transitionTime = getMaxTime(styles.transitionDuration, styles.transitionDelay);
+		const animationTime = getMaxTime(styles.animationDuration, styles.animationDelay);
+		return Math.max(transitionTime, animationTime);
+	}
+
+	function resolvePlacementSide(value: string) {
+		const side = value.split(/[-\s]/)[0];
+		return side === 'top' || side === 'right' || side === 'left' ? side : 'bottom';
 	}
 
-	function handleOpenChange(value: boolean) {
+	function clearMotionTracking() {
+		if (pendingMotionFrame !== undefined) {
+			cancelAnimationFrame(pendingMotionFrame);
+			pendingMotionFrame = undefined;
+		}
+
+		if (motionTimeout !== undefined) {
+			clearTimeout(motionTimeout);
+			motionTimeout = undefined;
+		}
+
+		cleanupMotionListeners?.();
+		cleanupMotionListeners = undefined;
+	}
+
+	function finishEnter(id: number) {
+		if (id !== motionId) return;
+		clearMotionTracking();
+		isEntering = false;
+	}
+
+	function finishExit(id: number) {
+		if (id !== motionId) return;
+		clearMotionTracking();
+		isExiting = false;
+		isMounted = false;
+	}
+
+	function trackMotion(phase: 'enter' | 'exit', element: HTMLElement) {
+		clearMotionTracking();
+		const id = ++motionId;
+
+		pendingMotionFrame = requestAnimationFrame(() => {
+			pendingMotionFrame = undefined;
+			if (id !== motionId || !element.isConnected) return;
+
+			const totalMotionTime = getMotionTime(element);
+			const complete = phase === 'enter' ? () => finishEnter(id) : () => finishExit(id);
+
+			if (totalMotionTime <= 0) {
+				complete();
+				return;
+			}
+
+			const handleMotionEnd = (event: Event) => {
+				if (event.target !== element) return;
+				complete();
+			};
+
+			element.addEventListener('animationend', handleMotionEnd);
+			element.addEventListener('transitionend', handleMotionEnd);
+			cleanupMotionListeners = () => {
+				element.removeEventListener('animationend', handleMotionEnd);
+				element.removeEventListener('transitionend', handleMotionEnd);
+			};
+
+			motionTimeout = window.setTimeout(() => {
+				complete();
+			}, totalMotionTime + 50);
+		});
+	}
+
+	function clearPendingStandaloneTriggerCloseFocus() {
+		if (pendingStandaloneTriggerCloseFocusFrame === undefined) return;
+		cancelAnimationFrame(pendingStandaloneTriggerCloseFocusFrame);
+		pendingStandaloneTriggerCloseFocusFrame = undefined;
+	}
+
+	function clearStandaloneTriggerTracking() {
+		clearPendingStandaloneTriggerCloseFocus();
+		cleanupStandaloneTriggerBlurListener?.();
+		cleanupStandaloneTriggerBlurListener = undefined;
+	}
+
+	function applyStandaloneTriggerCloseState(
+		trigger: HTMLElement,
+		reason: PopoverCloseReason,
+		event?: Event
+	) {
+		clearStandaloneTriggerTracking();
+		pendingStandaloneTriggerCloseFocusFrame = requestAnimationFrame(() => {
+			pendingStandaloneTriggerCloseFocusFrame = undefined;
+			if (!trigger.isConnected) return;
+			applyTriggerCloseFocusState(trigger, reason, event);
+
+			const cleanupTriggerBlur = addTriggerBlurCleanup(trigger, true);
+			const handleDocumentFocusIn = (focusEvent: FocusEvent) => {
+				const target = focusEvent.target;
+				if (target === trigger) return;
+				if (target instanceof Node && trigger.contains(target)) return;
+				clearTriggerFocusState(trigger);
+				document.removeEventListener('focusin', handleDocumentFocusIn);
+			};
+
+			document.addEventListener('focusin', handleDocumentFocusIn);
+			cleanupStandaloneTriggerBlurListener = () => {
+				cleanupTriggerBlur();
+				document.removeEventListener('focusin', handleDocumentFocusIn);
+			};
+		});
+	}
+
+	function releaseFocusedDescendantBeforeHide() {
+		if (!browser || !popoverRef || !triggerRef) return;
+
+		const activeElement = document.activeElement;
+		if (!(activeElement instanceof HTMLElement)) return;
+		if (activeElement === triggerRef || triggerRef.contains(activeElement)) return;
+		if (activeElement !== popoverRef && !popoverRef.contains(activeElement)) return;
+
+		activeElement.blur();
+	}
+
+	function close(reason: PopoverCloseReason = 'imperative-action', event?: Event) {
+		closeHandledInternally = true;
+		releaseFocusedDescendantBeforeHide();
+
 		if (isStandalone) {
-			onOpenChangeProp?.(value);
+			let canceled = false;
+			const details: PopoverOpenChangeDetails = {
+				reason,
+				event,
+				cancel: () => {
+					canceled = true;
+				},
+				get isCanceled() {
+					return canceled;
+				}
+			};
+
+			onOpenChangeProp?.(false, details);
+			if (details.isCanceled) return;
+			if (triggerRefProp) {
+				applyStandaloneTriggerCloseState(triggerRefProp, reason, event);
+			}
 		} else {
-			ctx!.onOpenChange(value);
+			ctx!.close(reason, event);
 		}
 	}
 
 	function handleKeydown(event: KeyboardEvent) {
 		if (event.key === 'Escape' && isOpen && shouldCloseOnEscape) {
 			event.preventDefault();
-			close();
+			close('escape-key', event);
 		}
 	}
 
@@ -107,7 +295,7 @@
 		const focusInTrigger = triggerRef?.contains(target) || target === triggerRef;
 
 		if (!focusInPopover && !focusInTrigger) {
-			handleOpenChange(false);
+			close('focus-out', event);
 		}
 	}
 
@@ -121,10 +309,28 @@
 
 		// Only close on external scroll
 		if (!isInsidePopover && !isInsideTrigger) {
-			close();
+			close('outside-press', event);
 		}
 	}
 
+	$effect(() => {
+		if (!isStandalone) {
+			if (trackedStandaloneTrigger) {
+				clearTriggerFocusState(trackedStandaloneTrigger);
+			}
+			trackedStandaloneTrigger = null;
+			clearStandaloneTriggerTracking();
+			return;
+		}
+
+		if (trackedStandaloneTrigger && trackedStandaloneTrigger !== triggerRefProp) {
+			clearTriggerFocusState(trackedStandaloneTrigger);
+			clearStandaloneTriggerTracking();
+		}
+
+		trackedStandaloneTrigger = triggerRefProp;
+	});
+
 	onMount(() => {
 		if (!browser) return;
 		document.addEventListener('keydown', handleKeydown);
@@ -134,28 +340,113 @@
 
 	onDestroy(() => {
 		if (!browser) return;
+		if (trackedStandaloneTrigger) {
+			clearTriggerFocusState(trackedStandaloneTrigger);
+		}
+		clearMotionTracking();
+		clearStandaloneTriggerTracking();
 		document.removeEventListener('keydown', handleKeydown);
 		document.removeEventListener('focusin', handleDocumentFocusIn);
 		document.removeEventListener('scroll', handleScroll, true);
 	});
+
+	$effect(() => {
+		const wasOpen = previousOpen;
+		previousOpen = isOpen;
+
+		if (isOpen) {
+			closeHandledInternally = false;
+			return;
+		}
+
+		if (!wasOpen) {
+			closeHandledInternally = false;
+			return;
+		}
+
+		if (closeHandledInternally) {
+			closeHandledInternally = false;
+			return;
+		}
+
+		releaseFocusedDescendantBeforeHide();
+	});
+
+	$effect(() => {
+		if (isOpen) {
+			const shouldAnimateIn = !isMounted || isExiting;
+			isMounted = true;
+			isExiting = false;
+			if (shouldAnimateIn) {
+				isEntering = true;
+			}
+			return;
+		}
+
+		if (!isMounted) {
+			isEntering = false;
+			isExiting = false;
+			return;
+		}
+
+		isEntering = false;
+		isExiting = true;
+	});
+
+	$effect(() => {
+		if (!isMounted || !popoverRef) {
+			clearMotionTracking();
+			return;
+		}
+
+		if (isEntering) {
+			trackMotion('enter', popoverRef);
+			return;
+		}
+
+		if (isExiting) {
+			trackMotion('exit', popoverRef);
+			return;
+		}
+
+		clearMotionTracking();
+	});
 </script>
 
-{#if isOpen}
+{#if isMounted}
 	<Portal>
 		<div
 			bind:this={popoverRef}
 			class={className}
 			role="dialog"
-			aria-modal={isModal}
-			use:floating={{ anchor: triggerRef, offset, placement, shouldFlip, boundaryElement }}
+			aria-modal={isOpen ? isModal : undefined}
+			aria-hidden={isOpen ? undefined : 'true'}
+			inert={!isOpen}
+			data-state={isOpen ? 'open' : 'closed'}
+			data-entering={isEntering || undefined}
+			data-exiting={isExiting || undefined}
+			data-placement={resolvedPlacement}
+			use:floating={{
+				anchor: triggerRef,
+				offset,
+				placement,
+				shouldFlip,
+				boundaryElement,
+				onPositionUpdate: (_, __, finalPlacement) => {
+					resolvedPlacement = resolvePlacementSide(finalPlacement);
+				}
+			}}
 			use:clickOutside={{
-				handler: close,
-				enabled: shouldCloseOnInteractOutside,
+				handler: (event) => {
+					event.preventDefault();
+					close('outside-press', event);
+				},
+				enabled: isOpen && shouldCloseOnInteractOutside,
 				ignore: [triggerRef]
 			}}
-			use:focusTrap={isModal}
-			use:scrollLock={isModal}
-			use:ariaHideOutside={isModal}
+			use:focusTrap={{ enabled: isOpen && isModal, restoreFocus: false, initialFocus }}
+			use:scrollLock={isOpen && isModal}
+			use:ariaHideOutside={isOpen && isModal}
 			style="position: fixed; z-index: 9999;"
 			{...restProps}
 		>

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

@@ -1,6 +1,8 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type ExtendedPlacement } from '../../primitives/floating';
+import { type FocusTrapOptions } from '../../primitives/focus-trap';
+import { type PopoverOpenChangeDetails } from '../root/context';
 /**
  * Popover.Content - The floating content panel.
  * Can be used inside Popover.Root (reads context) or standalone (props required).
@@ -26,12 +28,14 @@ type PopoverContentProps = {
     shouldCloseOnEscape?: boolean;
     /** Whether losing focus (blur) should close the popover. Defaults to true for non-modal popovers. */
     shouldCloseOnBlur?: boolean;
+    /** Element or selector to focus first when modal trap activates. */
+    initialFocus?: FocusTrapOptions['initialFocus'];
     /** Controlled open state (standalone mode). */
     open?: boolean;
     /** Reference to the trigger element (standalone mode). */
     triggerRef?: HTMLElement | null;
     /** Callback when open state changes (standalone mode). */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: (open: boolean, details: PopoverOpenChangeDetails) => void;
 } & Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'>;
 declare const PopoverContent: import("svelte").Component<PopoverContentProps, {}, "">;
 type PopoverContent = ReturnType<typeof PopoverContent>;

package/dist/popover/index.d.ts

@@ -1,8 +1,8 @@
-export * as Popover from './index.parts.ts';
+export * as Popover from './index.parts.js';
 export { default as PopoverRoot } from './root/popover-root.svelte';
 export { default as PopoverContent } from './content/popover-content.svelte';
 export { default as PopoverTrigger } from './trigger/popover-trigger.svelte';
 export { default as PopoverTriggerButton } from './trigger/popover-trigger-button.svelte';
-export { getPopoverContext, setPopoverContext, type PopoverContext, getPopoverTriggerContext, setPopoverTriggerContext, type PopoverTriggerContext } from './root/context.ts';
-import * as PopoverParts from './index.parts.ts';
+export { getPopoverContext, setPopoverContext, type PopoverContext, type PopoverCanonicalCloseReason, type PopoverCloseReason, type PopoverOpenReason, type PopoverChangeReason, type PopoverOpenChangeDetails } from './root/context.js';
+import * as PopoverParts from './index.parts.js';
 export default PopoverParts;

package/dist/popover/index.js

@@ -1,14 +1,12 @@
 // Namespace export for component composition: <Popover.Root>, <Popover.Trigger>, etc.
-export * as Popover from './index.parts.ts';
+export * as Popover from './index.parts.js';
 // Direct named exports for individual imports
 export { default as PopoverRoot } from './root/popover-root.svelte';
 export { default as PopoverContent } from './content/popover-content.svelte';
 export { default as PopoverTrigger } from './trigger/popover-trigger.svelte';
 export { default as PopoverTriggerButton } from './trigger/popover-trigger-button.svelte';
 // Context and types
-export { getPopoverContext, setPopoverContext, 
-// Legacy aliases
-getPopoverTriggerContext, setPopoverTriggerContext } from './root/context.ts';
+export { getPopoverContext, setPopoverContext } from './root/context.js';
 // Default export as namespace object
-import * as PopoverParts from './index.parts.ts';
+import * as PopoverParts from './index.parts.js';
 export default PopoverParts;