entasis 0.10.2 → 0.12.0

package/dist/components/Overlay/overlay.attributes.js

@@ -0,0 +1,14 @@
+/**
+ * The styling hooks an Overlay exposes. Attributes are presence attributes (`''` while the state
+ * holds, omitted otherwise) unless the description says they carry a value.
+ */
+export const overlayDataAttributes = {
+    'data-open': 'On the root: present while open (shown, or ready to show on hover or focus).',
+    'data-closed': 'On the root: present while closed, including during the exit transition.',
+    'data-entering': 'On the root: present while the opening transition plays.',
+    'data-exiting': 'On the root: present while the closing transition plays.',
+    'data-show-on': 'On the root: `always`, `hover` or `focus`, the resolved `showOn`.',
+    'data-position': 'On the root: the resolved `position`.',
+    'data-entasis-overlay': 'On the root: always present; marks the overlay inside its container.',
+    'data-overlay-content': 'On the content panel: always present.'
+};

package/dist/components/Overlay/overlay.mcp.d.ts

@@ -1 +1 @@
-export declare const overlayDescription = "\n# Overlay Component\n\nOverlay layers concise content and actions over bounded media or another visual surface. Place it as the direct first child of a container; the component automatically establishes that parent as its positioning context, so no attachment or wrapper component is required.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Overlay } from 'entasis/overlay';\n</script>\n\n<div class=\"aspect-video overflow-hidden rounded-lg\">\n\t<Overlay\n\t\ttitle=\"Design system foundations\"\n\t\tdescription=\"A practical tour of tokens, primitives, and composition.\"\n\t\tactions={[{ content: 'Open gallery', color: 'neutral', variant: 'soft' }]}\n\t/>\n\t<img src=\"/cover.jpg\" alt=\"Coastal landscape\" class=\"size-full object-cover\" />\n</div>\n```\n\n## Props\n\n- **position**: 'fill' | 'top' | 'bottom' (default: 'fill') - Places the content vertically. Fill uses a surface-wide dark scrim; top and bottom use content-sized black-to-transparent gradients.\n- **align**: 'start' | 'center' | 'end' (default: 'center') - Horizontal content and text alignment.\n- **showOn**: 'always' | 'hover' | 'focus' (default: 'always') - Reveal condition. Hover also reveals for focus-within so actions remain keyboard accessible.\n- **open**: boolean (default: true) - Enables or hides the overlay while preserving its reveal transition.\n- **defaultOpen**: boolean (default: true) - Initial state when open is not provided.\n- **onOpenChange**: (open: boolean) => void - Reserved for library-requested state changes.\n- **onAfterOpen**: () => void - Called after the open transition finishes.\n- **onAfterClose**: () => void - Called after the close transition finishes.\n- **scrim**: boolean (default: true) - Toggles the dark fill or directional gradient.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Scales padding, gaps, and typography.\n- **actions**: OverlayAction[] - Button props plus a content string, rendered as a wrapping action row.\n- **ref**: HTMLDivElement | null - Bindable root reference.\n- **class**: string - Additional root classes.\n- **theme**: OverlayThemeProps - Theme overrides.\n\n## Slots\n\n- **title**: Main overlay heading.\n- **description**: Supporting text.\n- **content**: Additional body content between the description and actions.\n- **children**: Fully custom composition replacing title, description, content, and actions.\n\nAll named content slots accept a string or snippet.\n\n## Placement\n\nThe overlay must be the direct first child of the surface it covers:\n\n```svelte\n<div class=\"overflow-hidden rounded-lg\">\n\t<Overlay position=\"bottom\" title=\"Golden hour\" />\n\t<img src=\"/photo.jpg\" alt=\"Golden hour over a valley\" />\n</div>\n```\n\nThe parent receives a zero-specificity relative positioning context and isolated stacking context through CSS `:has()`. An explicit parent positioning utility or inline style still takes precedence.\n\nTop and bottom content enters from its corresponding edge while the scrim fades in place. Fill content only fades. Motion is disabled when the user requests reduced motion.\n\n## Reveal on Hover or Focus\n\n```svelte\n<div class=\"aspect-video overflow-hidden rounded-lg\">\n\t<Overlay\n\t\tshowOn=\"hover\"\n\t\tposition=\"bottom\"\n\t\ttitle=\"Mountain archive\"\n\t\tactions={[{ content: 'View collection', color: 'neutral', variant: 'soft' }]}\n\t/>\n\t<img src=\"/mountain.jpg\" alt=\"Snow-covered mountain\" />\n</div>\n```\n\n## Accessibility\n\n- The overlay is semantically neutral; supplied buttons and links keep their native semantics.\n- Hover-revealed content also appears when focus enters the surface or its actions.\n- Setting open to false makes the overlay inert and hides it from assistive technology.\n- Images and video beneath the overlay still require their own accessible labels or alternatives.\n\n## Theme Parts\n\n- **root**: Absolute overlay, reveal state, vertical placement, and clipping.\n- **scrim**: Fill or directional gradient.\n- **content**: Padding and horizontal alignment.\n- **header**: Title and description stack.\n- **title**: Heading typography.\n- **description**: Supporting text.\n- **body**: Additional content slot.\n- **actions**: Button row.\n";
+export declare const overlayDescription = "\n# Overlay Component\n\nOverlay layers concise content and actions over bounded media or another visual surface. Place it as the direct first child of a container; the component automatically establishes that parent as its positioning context, so no attachment or wrapper component is required.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Overlay } from 'entasis/overlay';\n</script>\n\n<div class=\"aspect-video overflow-hidden rounded-lg\">\n\t<Overlay\n\t\ttitle=\"Design system foundations\"\n\t\tdescription=\"A practical tour of tokens, primitives, and composition.\"\n\t\tactions={[{ content: 'Open gallery', color: 'neutral', variant: 'soft' }]}\n\t/>\n\t<img src=\"/cover.jpg\" alt=\"Coastal landscape\" class=\"size-full object-cover\" />\n</div>\n```\n\n## Props\n\n- **position**: 'fill' | 'top' | 'bottom' (default: 'fill') - Places the content vertically. Fill uses a surface-wide dark scrim; top and bottom use content-sized black-to-transparent gradients.\n- **align**: 'start' | 'center' | 'end' (default: 'center') - Horizontal content and text alignment.\n- **showOn**: 'always' | 'hover' | 'focus' (default: 'always') - Reveal condition. Hover also reveals for focus-within so actions remain keyboard accessible.\n- **open**: boolean (default: true) - Enables or hides the overlay while preserving its reveal transition.\n- **defaultOpen**: boolean (default: true) - Initial state when open is not provided.\n- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Reserved for the shared disclosure contract; Overlay has no control of its own that opens or closes it, so it never calls this.\n- **onAfterOpen**: () => void - Called once per open after the reveal animation settles, including for an overlay open at creation.\n- **onAfterClose**: () => void - Called once per close after the hide animation settles.\n- **scrim**: boolean (default: true) - Toggles the dark fill or directional gradient.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Scales padding, gaps, and typography.\n- **actions**: OverlayAction[] - Button props plus a content string, rendered as a wrapping action row.\n- **ref**: HTMLDivElement | null - Bindable root reference.\n- **class**: string - Additional root classes.\n- **theme**: OverlayThemeProps - Theme overrides.\n\n## Slots\n\n- **title**: Main overlay heading.\n- **description**: Supporting text.\n- **content**: Additional body content between the description and actions.\n- **children**: Fully custom composition replacing title, description, content, and actions.\n\nAll named content slots accept a string or snippet.\n\n## Placement\n\nThe overlay must be the direct first child of the surface it covers:\n\n```svelte\n<div class=\"overflow-hidden rounded-lg\">\n\t<Overlay position=\"bottom\" title=\"Golden hour\" />\n\t<img src=\"/photo.jpg\" alt=\"Golden hour over a valley\" />\n</div>\n```\n\nThe parent receives a zero-specificity relative positioning context and isolated stacking context through CSS `:has()`. An explicit parent positioning utility or inline style still takes precedence.\n\nTop and bottom content enters from its corresponding edge while the scrim fades in place. Fill content only fades. Motion is disabled when the user requests reduced motion.\n\n## Reveal on Hover or Focus\n\n```svelte\n<div class=\"aspect-video overflow-hidden rounded-lg\">\n\t<Overlay\n\t\tshowOn=\"hover\"\n\t\tposition=\"bottom\"\n\t\ttitle=\"Mountain archive\"\n\t\tactions={[{ content: 'View collection', color: 'neutral', variant: 'soft' }]}\n\t/>\n\t<img src=\"/mountain.jpg\" alt=\"Snow-covered mountain\" />\n</div>\n```\n\n## Styling hooks\n\n`data-open` is a presence attribute: a closed overlay carries `data-closed` and no `data-open` (before 0.12.0 it carried `data-open=\"false\"`). Select an open overlay with `[data-open]` or Tailwind's `data-open:` variant.\n\nAttributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.\n\n**Data attributes**\n- `data-open`: On the root: present while open (shown, or ready to show on hover or focus).\n- `data-closed`: On the root: present while closed, including during the exit transition.\n- `data-entering`: On the root: present while the opening transition plays.\n- `data-exiting`: On the root: present while the closing transition plays.\n- `data-show-on`: On the root: `always`, `hover` or `focus`, the resolved `showOn`.\n- `data-position`: On the root: the resolved `position`.\n- `data-entasis-overlay`: On the root: always present; marks the overlay inside its container.\n- `data-overlay-content`: On the content panel: always present.\n\nThe typed map `overlayDataAttributes` (from `entasis/overlay`) lists each name with its meaning.\n\n## Accessibility\n\n- The overlay is semantically neutral; supplied buttons and links keep their native semantics.\n- Hover-revealed content also appears when focus enters the surface or its actions.\n- Setting open to false makes the overlay inert and hides it from assistive technology.\n- Images and video beneath the overlay still require their own accessible labels or alternatives.\n\n## Theme Parts\n\n- **root**: Absolute overlay, reveal state, vertical placement, and clipping.\n- **scrim**: Fill or directional gradient.\n- **content**: Padding and horizontal alignment.\n- **header**: Title and description stack.\n- **title**: Heading typography.\n- **description**: Supporting text.\n- **body**: Additional content slot.\n- **actions**: Button row.\n";

package/dist/components/Overlay/overlay.mcp.js

@@ -27,9 +27,9 @@ Overlay layers concise content and actions over bounded media or another visual
 - **showOn**: 'always' | 'hover' | 'focus' (default: 'always') - Reveal condition. Hover also reveals for focus-within so actions remain keyboard accessible.
 - **open**: boolean (default: true) - Enables or hides the overlay while preserving its reveal transition.
 - **defaultOpen**: boolean (default: true) - Initial state when open is not provided.
-- **onOpenChange**: (open: boolean) => void - Reserved for library-requested state changes.
-- **onAfterOpen**: () => void - Called after the open transition finishes.
-- **onAfterClose**: () => void - Called after the close transition finishes.
+- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Reserved for the shared disclosure contract; Overlay has no control of its own that opens or closes it, so it never calls this.
+- **onAfterOpen**: () => void - Called once per open after the reveal animation settles, including for an overlay open at creation.
+- **onAfterClose**: () => void - Called once per close after the hide animation settles.
 - **scrim**: boolean (default: true) - Toggles the dark fill or directional gradient.
 - **size**: 'small' | 'normal' | 'large' (default: 'normal') - Scales padding, gaps, and typography.
 - **actions**: OverlayAction[] - Button props plus a content string, rendered as a wrapping action row.
@@ -75,6 +75,24 @@ Top and bottom content enters from its corresponding edge while the scrim fades
 </div>
 \`\`\`
 
+## Styling hooks
+
+\`data-open\` is a presence attribute: a closed overlay carries \`data-closed\` and no \`data-open\` (before 0.12.0 it carried \`data-open="false"\`). Select an open overlay with \`[data-open]\` or Tailwind's \`data-open:\` variant.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-open\`: On the root: present while open (shown, or ready to show on hover or focus).
+- \`data-closed\`: On the root: present while closed, including during the exit transition.
+- \`data-entering\`: On the root: present while the opening transition plays.
+- \`data-exiting\`: On the root: present while the closing transition plays.
+- \`data-show-on\`: On the root: \`always\`, \`hover\` or \`focus\`, the resolved \`showOn\`.
+- \`data-position\`: On the root: the resolved \`position\`.
+- \`data-entasis-overlay\`: On the root: always present; marks the overlay inside its container.
+- \`data-overlay-content\`: On the content panel: always present.
+
+The typed map \`overlayDataAttributes\` (from \`entasis/overlay\`) lists each name with its meaning.
+
 ## Accessibility
 
 - The overlay is semantically neutral; supplied buttons and links keep their native semantics.

package/dist/components/Overlay/overlay.props.d.ts

@@ -4,6 +4,7 @@ import type { Sizes } from '../../types/theme.js';
 import type { Snippet } from 'svelte';
 import type { ButtonProps } from '../Button/index.js';
 import type { OverlayThemeProps } from './overlay.theme.js';
+import type { OpenChangeHandler } from '../../utils/openChange.js';
 export type OverlayPosition = 'fill' | 'top' | 'bottom';
 export type OverlayAlign = 'start' | 'center' | 'end';
 export type OverlayShowOn = 'always' | 'hover' | 'focus';
@@ -26,11 +27,14 @@ export type OverlayProps = WithAttachments<WithSlot<{
     open?: boolean;
     /** Initial open state when `open` is not provided. */
     defaultOpen?: boolean;
-    /** Called once when the library requests an open-state change. */
-    onOpenChange?: (open: boolean) => void;
-    /** Called after the open transition finishes. */
+    /**
+     * Reserved for the shared disclosure contract: Overlay has no control of its own that
+     * opens or closes it, so it never calls this. The parent owns `open`.
+     */
+    onOpenChange?: OpenChangeHandler;
+    /** Called once per open, after the reveal animation settles (an overlay open at creation included). */
     onAfterOpen?: () => void;
-    /** Called after the close transition finishes. */
+    /** Called once per close, after the hide animation settles. */
     onAfterClose?: () => void;
     /** Renders the dark fill or directional gradient behind the content. */
     scrim?: boolean;

package/dist/components/Popover/Popover.svelte

@@ -1,15 +1,19 @@
-<script lang="ts">
+<script lang="ts" generics="Payload = unknown">
 	import { createBindableValue } from '../../utils/state.svelte.js';
 	import { getPopoverDialogTheme } from './popover.dialog.theme.js';
 	import type { PopoverProps } from './popover.props.js';
 	import { usePopoverTheme } from './popover.theme.js';
 	import { PopoverState } from './popover.state.svelte.js';
+	import PopoverSession from './PopoverSession.svelte';
 	import Button from '../Button/Button.svelte';
 	import Dialog from '../Dialog/Dialog.svelte';
 	import { fso } from '../../transitions/transition.js';
 	import { portal } from '../../attachments/portal.js';
 	import { transitionSize } from '../../attachments/transitionSize.js';
+	import { composeHandlers } from '../../utils/handlers.js';
 	import type { Attachment } from 'svelte/attachments';
+	import { SAFE_AREA_CLOSE_DELAY } from '../../utils/safeArea.svelte.js';
+	import { useI18n } from '../../i18n/context.svelte.js';
 
 	let {
 		id: customId,
@@ -27,6 +31,7 @@
 		openOnHover = false,
 		openOnClick = true,
 		delay = 100,
+		closeDelay = SAFE_AREA_CLOSE_DELAY,
 		closeOnEscape = true,
 		closeOnClickOutside = true,
 		closeOnMouseLeave = false,
@@ -35,16 +40,26 @@
 		lockScroll = true,
 		fitTrigger = false,
 		positionPanel,
+		collisionBoundary = 'visualViewport',
+		fallbackAxisSide = 'none',
+		anchorTo = 'box',
 		inline = false,
 		mobileSheet = false,
 		mobileSheetSizeTransition = true,
-		focusOnOpen = false,
+		focusOnOpen,
+		focusOnClose,
 		haspopup = 'dialog',
+		label,
+		labelledBy,
+		modal = false,
+		tabBridge = true,
+		closeOnFocusOut,
+		arrow = false,
 		class: className,
 		trigger,
 		theme,
 		...attachments
-	}: PopoverProps = $props();
+	}: PopoverProps<Payload> = $props();
 	const openState = createBindableValue(
 		() => open,
 		(next) => {
@@ -54,7 +69,8 @@
 	);
 
 	const id = $props.id();
-	const popover = new PopoverState({
+	const t = $derived(useI18n());
+	const popover = new PopoverState<Payload>({
 		get id() {
 			return customId || id;
 		},
@@ -67,6 +83,12 @@
 		get onOpenChange() {
 			return onOpenChange;
 		},
+		get onAfterOpen() {
+			return onAfterOpen;
+		},
+		get onAfterClose() {
+			return onAfterClose;
+		},
 		get size() {
 			return size;
 		},
@@ -91,6 +113,15 @@
 		get positionPanel() {
 			return positionPanel;
 		},
+		get collisionBoundary() {
+			return collisionBoundary;
+		},
+		get fallbackAxisSide() {
+			return fallbackAxisSide;
+		},
+		get anchorTo() {
+			return anchorTo;
+		},
 		get mobileSheet() {
 			return mobileSheet;
 		},
@@ -118,15 +149,39 @@
 		get delay() {
 			return delay;
 		},
+		get closeDelay() {
+			return closeDelay;
+		},
 		get openOnClick() {
 			return openOnClick;
 		},
 		get focusOnOpen() {
 			return focusOnOpen;
 		},
+		get focusOnClose() {
+			return focusOnClose;
+		},
 		get haspopup() {
 			return haspopup;
 		},
+		get label() {
+			return label;
+		},
+		get labelledBy() {
+			return labelledBy;
+		},
+		get modal() {
+			return modal;
+		},
+		get tabBridge() {
+			return tabBridge;
+		},
+		get closeOnFocusOut() {
+			return closeOnFocusOut;
+		},
+		get arrow() {
+			return arrow;
+		},
 		get motion() {
 			return theme?.motion;
 		}
@@ -138,7 +193,8 @@
 
 	const classes = $derived(usePopoverTheme(theme));
 
-	const in_out = fso();
+	// Wrapped so the lifecycle knows when the panel's transition plays (and when none does).
+	const panelTransition = popover.lifecycle.transition(fso());
 
 	// An inline panel needs no reference element: it renders where the component sits.
 	const visible = $derived(
@@ -149,6 +205,18 @@
 	// Floating panels portal to the body layer; inline ones stay in normal document flow.
 	const maybePortal: Attachment<HTMLElement> = $derived(inline ? () => {} : portal());
 
+	// The sheet's Dialog has no title to name it by: the sheet's content names the dialog around it.
+	const nameSheet: Attachment<HTMLElement> = (node) => {
+		const dialog = node.closest('[role="dialog"]');
+		if (!dialog || (!label && !labelledBy)) return;
+		if (label) dialog.setAttribute('aria-label', label);
+		if (labelledBy) dialog.setAttribute('aria-labelledby', labelledBy);
+		return () => {
+			dialog.removeAttribute('aria-label');
+			dialog.removeAttribute('aria-labelledby');
+		};
+	};
+
 	const mobileSheetDialogTheme = $derived(
 		getPopoverDialogTheme(
 			classes.popover({
@@ -162,6 +230,56 @@
 
 {#snippet emptyCloseButton()}{/snippet}
 
+<!-- First in the template: what only an open popover needs (its layer, focus scope, safe area)
+     exists before the panel below reads it, and stays until the closing transition ends. -->
+{#if popover.sessionActive}
+	<PopoverSession {popover} />
+{/if}
+
+<!-- The panel is a child of the wrapper, so it is never re-parented mid-transition (which would
+     break the intro). It carries the visuals, transform-origin, and animation. -->
+{#snippet floatingPanel()}
+	<div
+		{@attach popover.panel}
+		{...popover.panelAttributes}
+		class={classes.popover({
+			size: popover.computedSize,
+			mode: popover.computedMode,
+			arrow: arrow && popover.computedMode === 'floating',
+			className
+		})}
+		style:transform-origin={popover.transformOrigin}
+		style:min-width={popover.triggerWidth != null ? `${popover.triggerWidth}px` : undefined}
+		style:width={popover.triggerWidth != null ? 'max-content' : undefined}
+		style:max-width={popover.triggerWidth != null
+			? `max(${FIT_TRIGGER_CAP[popover.computedSize]}, ${popover.triggerWidth}px)`
+			: undefined}
+		in:panelTransition={popover.computedTransition.in}
+		out:panelTransition={popover.computedTransition.out}
+		onintroend={popover.lifecycle.introEnd}
+		onoutroend={popover.lifecycle.outroEnd}
+	>
+		{#if arrow && popover.computedMode === 'floating'}
+			<div {@attach popover.arrowRef} aria-hidden="true" class={classes.arrow()}></div>
+		{/if}
+		{@render children?.(popover)}
+		{#if popover.isModal && (closeOnEscape || closeOnClickOutside)}
+			<!-- The page behind a modal panel is inert and its Escape and outside press are no use to
+			     a screen reader's virtual cursor: a Close button at the end of the panel is. Out of
+			     the Tab order, which the panel's own controls own. -->
+			<button
+				type="button"
+				class="sr-only"
+				tabindex="-1"
+				data-autofocus-skip
+				onclick={(event) => popover.close({ reason: 'close-press', event })}
+			>
+				{t.close}
+			</button>
+		{/if}
+	</div>
+{/snippet}
+
 <!-- Trigger first: an inline panel then follows it in the document flow. Floating and
      mobile-sheet panels portal out, so source order does not reach them. -->
 {#if trigger}
@@ -172,16 +290,21 @@
 		<Button
 			{...buttonProps}
 			{...popover.triggerProps}
-			onclick={(event) => {
-				onclick?.(event);
-				if (openOnClick) popover.toggle();
-			}}
+			onclick={composeHandlers(onclick, (event) => {
+				if (openOnClick) popover.toggle(event);
+			})}
 			children={children ?? content}
 			{@attach popover.reference}
 		/>
 	{/if}
 {/if}
 
+<!-- A screen reader reads a portaled panel straight after its trigger when the trigger's
+     container owns it; the span is out of the layout and names no content of its own. -->
+{#if trigger && typeof trigger !== 'boolean' && popover.tabBridgeActive}
+	<span class="sr-only" aria-owns={popover.id}></span>
+{/if}
+
 {#if popover.isMobileSheet}
 	<Dialog
 		id={popover.id}
@@ -192,66 +315,54 @@
 		{transition}
 		{closeOnEscape}
 		{closeOnClickOutside}
+		{focusOnClose}
 		closable={closeOnEscape || closeOnClickOutside}
 		swipeToDismiss={closeOnClickOutside}
 		thumb={false}
 		closeButton={emptyCloseButton}
 		theme={mobileSheetDialogTheme}
-		onOpenChange={(nextOpen) => popover.setOpen(nextOpen)}
-		onAfterOpen={() => {
-			popover.hasTransitioned = true;
-			onAfterOpen?.(popover);
-		}}
-		onAfterClose={() => {
-			popover.hasTransitioned = false;
-			onAfterClose?.(popover);
-		}}
+		onOpenChange={(nextOpen, details) => popover.setOpen(nextOpen, details)}
+		onAfterOpen={popover.lifecycle.introEnd}
+		onAfterClose={popover.lifecycle.outroEnd}
 	>
-		<div {@attach transitionSize({ isActive: () => mobileSheetSizeTransition })} {...attachments}>
+		<div
+			{@attach transitionSize({ isActive: () => mobileSheetSizeTransition })}
+			{@attach nameSheet}
+			{...attachments}
+		>
 			{@render children?.(popover)}
 		</div>
 	</Dialog>
-{:else if visible}
+{:else if visible && popover.isDialogPopup}
+	<!-- Dialog content sits in a <dialog>; a menu, listbox, tree or grid gets a plain wrapper
+	     (below), so assistive technology does not announce an unnamed dialog around it. Two
+	     branches of this one chain rather than a dynamic element: a nested block would stop the
+	     panel's local transitions from playing. -->
 	<dialog
 		{@attach maybePortal}
 		{@attach popover.dialog}
 		open={true}
 		id={popover.id}
 		class={classes.root({ mode: popover.computedMode })}
+		aria-label={label}
+		aria-labelledby={labelledBy}
+		aria-modal={popover.isModal ? 'true' : undefined}
 		style:visibility={inline ? undefined : 'hidden'}
-		style:z-index={inline ? undefined : popover.layer.zIndex}
+		style:z-index={inline ? undefined : popover.layer?.zIndex}
 		{...attachments}
 	>
-		<!-- The panel is a child of the wrapper, so it is never re-parented mid-transition
-		     (which would break the intro). It carries the visuals, transform-origin, and animation. -->
-		<div
-			{@attach popover.panel}
-			class={classes.popover({
-				size: popover.computedSize,
-				mode: popover.computedMode,
-				className
-			})}
-			style:transform-origin={popover.transformOrigin}
-			style:min-width={popover.triggerWidth != null ? `${popover.triggerWidth}px` : undefined}
-			style:width={popover.triggerWidth != null ? 'max-content' : undefined}
-			style:max-width={popover.triggerWidth != null
-				? `max(${FIT_TRIGGER_CAP[popover.computedSize]}, ${popover.triggerWidth}px)`
-				: undefined}
-			in:in_out={popover.computedTransition.in}
-			out:in_out={popover.computedTransition.out}
-			onintroend={() => {
-				popover.hasTransitioned = true;
-				onAfterOpen?.(popover);
-			}}
-			onoutrostart={() => {
-				popover.hasTransitioned = false;
-			}}
-			onoutroend={() => {
-				popover.focusScope.restore();
-				onAfterClose?.(popover);
-			}}
-		>
-			{@render children?.(popover)}
-		</div>
+		{@render floatingPanel()}
 	</dialog>
+{:else if visible}
+	<div
+		{@attach maybePortal}
+		{@attach popover.dialog}
+		id={popover.id}
+		class={classes.root({ mode: popover.computedMode })}
+		style:visibility={inline ? undefined : 'hidden'}
+		style:z-index={inline ? undefined : popover.layer?.zIndex}
+		{...attachments}
+	>
+		{@render floatingPanel()}
+	</div>
 {/if}

package/dist/components/Popover/Popover.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { PopoverProps } from './popover.props.js';
-declare const Popover: import("svelte").Component<PopoverProps, {}, "open">;
-type Popover = ReturnType<typeof Popover>;
+declare function $$render<Payload = unknown>(): {
+    props: PopoverProps<Payload>;
+    exports: {};
+    bindings: "open";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Payload = unknown> {
+    props(): ReturnType<typeof $$render<Payload>>['props'];
+    events(): ReturnType<typeof $$render<Payload>>['events'];
+    slots(): ReturnType<typeof $$render<Payload>>['slots'];
+    bindings(): "open";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Payload = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Payload>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Payload>['props']>, ReturnType<__sveltets_Render<Payload>['events']>, ReturnType<__sveltets_Render<Payload>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Payload>['bindings']>;
+    } & ReturnType<__sveltets_Render<Payload>['exports']>;
+    <Payload = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<Payload>['props']> & {}): ReturnType<__sveltets_Render<Payload>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Popover: $$IsomorphicComponent;
+type Popover<Payload = unknown> = InstanceType<typeof Popover<Payload>>;
 export default Popover;

package/dist/components/Popover/PopoverSession.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	// Renders nothing. Popover mounts it while the popover is open or closing, so the open-only
+	// machinery (layer, focus scope, safe area, Tab bridge, scroll lock) is built on open and torn
+	// down once the closing transition ends; a closed popover pays for none of it.
+	import type { PopoverState } from './popover.state.svelte.js';
+
+	let { popover }: { popover: Pick<PopoverState, 'openSession'> } = $props();
+
+	// Once, at initialisation: the session belongs to this mount, never to a later `popover`.
+	// svelte-ignore state_referenced_locally
+	popover.openSession();
+</script>

package/dist/components/Popover/PopoverSession.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { PopoverState } from './popover.state.svelte.js';
+type $$ComponentProps = {
+    popover: Pick<PopoverState, 'openSession'>;
+};
+declare const PopoverSession: import("svelte").Component<$$ComponentProps, {}, "">;
+type PopoverSession = ReturnType<typeof PopoverSession>;
+export default PopoverSession;

package/dist/components/Popover/index.d.ts

@@ -1,4 +1,12 @@
+import type { PopoverApi } from './popover.api.js';
 export { default as Popover } from './Popover.svelte';
-export type { PopoverProps } from './popover.props.js';
+export type { PopoverOpenReason, PopoverPlacement, PopoverProps, PopoverSide } from './popover.props.js';
+export type { PopoverApi } from './popover.api.js';
+export type { FocusOnClose } from '../../utils/useFocusScope.svelte.js';
 export { popoverTheme, setPopoverTheme, usePopoverTheme, type PopoverTheme, type PopoverThemeProps } from './popover.theme.js';
-export { usePopoverContext, type PopoverState } from './popover.state.svelte.js';
+export type { PopoverPlacementState } from './popover.state.svelte.js';
+/** @deprecated Renamed `PopoverApi`, the narrow popover snippets receive; kept for one minor. */
+export type PopoverState<Payload = unknown> = PopoverApi<Payload>;
+/** The nearest enclosing popover, or `null` outside one. */
+export declare const usePopoverContext: () => PopoverApi | null;
+export { popoverDataAttributes, popoverCssVariables, type PopoverDataAttribute, type PopoverCssVariable } from './popover.attributes.js';

package/dist/components/Popover/index.js

@@ -1,3 +1,6 @@
+import { usePopoverContext as usePopoverStateContext } from './popover.state.svelte.js';
 export { default as Popover } from './Popover.svelte';
 export { popoverTheme, setPopoverTheme, usePopoverTheme } from './popover.theme.js';
-export { usePopoverContext } from './popover.state.svelte.js';
+/** The nearest enclosing popover, or `null` outside one. */
+export const usePopoverContext = usePopoverStateContext;
+export { popoverDataAttributes, popoverCssVariables } from './popover.attributes.js';

package/dist/components/Popover/popover.api.d.ts

@@ -0,0 +1,83 @@
+import type { Attachment } from 'svelte/attachments';
+import type { OpenTransitionStatus } from '../../utils/stateAttributes.js';
+import type { PopupTriggerProps } from '../../utils/trigger.js';
+import type { PopoverOpenReason, PopoverProps } from './popover.props.js';
+import type { PopoverOpenChangeInput, PopoverPlacementState } from './popover.state.svelte.js';
+/**
+ * The popover handed to the `trigger` and `children` snippets, `onAfterOpen` and `onAfterClose`:
+ * its open state, the requests that change it, and the attachments that make an element its
+ * trigger. Type a snippet parameter `PopoverApi<Row>` to read `payload` as a `Row`.
+ */
+export interface PopoverApi<Payload = unknown> {
+    /** The popover id, which the open trigger's `aria-controls` points at. */
+    readonly id: string;
+    /** Whether the popover is open. */
+    readonly isOpen: boolean;
+    /**
+     * Where the panel is in its open/close lifecycle: `closed`, `entering`, `open` or `exiting`
+     * (the values behind `data-entering` and `data-exiting`).
+     */
+    readonly status: OpenTransitionStatus;
+    /**
+     * How the open popover was opened: `hover`, `press`, `keyboard`, or `programmatic` (`open()`
+     * from code, the `open` prop, `defaultOpen`). `null` once closed.
+     */
+    readonly openReason: PopoverOpenReason | null;
+    /** The trigger that opened the popover, while it is open; `null` after a programmatic open. */
+    readonly activeTrigger: HTMLElement | null;
+    /**
+     * Where the floating panel was last placed: its side, alignment, and whether its anchor is
+     * scrolled out of view (the values of `data-side`, `data-align` and `data-anchor-hidden`).
+     * `null` until the first placement lands and once the panel unmounts.
+     */
+    readonly placement: PopoverPlacementState | null;
+    /**
+     * Trigger state in the library's semantic vocabulary (`haspopup`, `expanded`, `controls`), to
+     * spread on a Button. `trigger` and `reference` already write it as ARIA attributes.
+     */
+    readonly triggerProps: PopupTriggerProps;
+    /**
+     * The payload of the trigger the panel is anchored to (see `triggerFor`); `undefined` for a
+     * trigger made without one.
+     */
+    readonly payload: Payload | undefined;
+    /** Requests opening through `onOpenChange`. */
+    readonly open: (input?: PopoverOpenChangeInput) => void;
+    /** Requests closing through `onOpenChange`; returns `false` when it was cancelled. */
+    readonly close: (input?: PopoverOpenChangeInput) => boolean;
+    /**
+     * Requests the other state. A press on the trigger of a hover-opened popover pins it open; on
+     * another trigger of an open popover it moves the panel there.
+     */
+    readonly toggle: (input?: PopoverOpenChangeInput) => void;
+    /** Requests an explicit state; returns `false` when `onOpenChange` cancelled it. */
+    readonly setOpen: (open: boolean, input?: PopoverOpenChangeInput) => boolean;
+    /**
+     * Makes any element a complete trigger (`{@attach popover.trigger}`): it anchors the panel,
+     * toggles it on click when `openOnClick` allows, keeps `aria-haspopup`, `aria-expanded` and
+     * `aria-controls` in sync, and gives a non-control `role="button"`, `tabindex="0"` and
+     * Enter/Space activation. The element's own handler runs first.
+     */
+    readonly trigger: Attachment<HTMLElement>;
+    /**
+     * Anchors the panel to an element and keeps its ARIA state in sync, leaving clicks and keys to
+     * the element (`{@attach popover.reference}`).
+     */
+    readonly reference: Attachment<HTMLElement>;
+    /**
+     * `trigger` plus a payload getter, read back as `payload` while this trigger anchors the panel:
+     * `{@attach popover.triggerFor(() => row)}`.
+     */
+    readonly triggerFor: (payload: () => Payload) => Attachment<HTMLElement>;
+    /** @deprecated Read `status === 'open'`; kept for one minor. */
+    readonly hasTransitioned: boolean;
+    /** @deprecated Read the `size` prop you passed; kept for one minor. */
+    readonly size?: PopoverProps<Payload>['size'];
+    /**
+     * @deprecated Read the `position` prop you passed, or `placement` for where the panel landed;
+     * kept for one minor.
+     */
+    readonly position?: PopoverProps<Payload>['position'];
+    /** @deprecated Read the `offset` prop you passed; kept for one minor. */
+    readonly offset?: PopoverProps<Payload>['offset'];
+}

package/dist/components/Popover/popover.api.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Popover/popover.attributes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The styling hooks a Popover exposes. Attributes are presence attributes (`''` while the state
+ * holds, omitted otherwise) unless the description says they carry a value. Components built on
+ * Popover (Select, Combobox, Menu, HoverCard, Tooltip) inherit them.
+ */
+export declare const popoverDataAttributes: {
+    readonly 'data-open': "On the panel: present while open.";
+    readonly 'data-closed': "On the panel: present while its exit transition plays (a closed panel is not rendered).";
+    readonly 'data-entering': "On the panel: present while the enter transition plays.";
+    readonly 'data-exiting': "On the panel: present while the exit transition plays.";
+    readonly 'data-side': "On the panel: the side of the trigger it sits on after flipping, `top`, `right`, `bottom` or `left`; `inline-start` / `inline-end` when a logical side was requested; `none` when `positionPanel` placed it. On the arrow: the physical side of the panel it sits on.";
+    readonly 'data-align': "On the panel: `start`, `center` or `end`, how it lines up with the trigger (absent with `data-side=\"none\"`).";
+    readonly 'data-anchor-hidden': "On the panel: present while the trigger is scrolled out of view; the panel is hidden meanwhile.";
+    readonly 'data-uncentered': "On the arrow: present while the trigger is not under the middle of the panel (a shift moved the panel).";
+    readonly 'data-popup-open': "On the element the panel is anchored to (the trigger that opened it, or the `ref` element): present while the popover is open.";
+    readonly 'data-popup-side': "On the element the panel is anchored to: the panel's `data-side` while it is placed, so a theme can flatten the corner the panel attaches to.";
+};
+/** The name of a Popover data attribute. */
+export type PopoverDataAttribute = keyof typeof popoverDataAttributes;
+/**
+ * The CSS variables a placement writes on the positioned wrapper, inherited by the panel and its
+ * content. A floating panel only; an inline panel and the mobile sheet have none.
+ */
+export declare const popoverCssVariables: {
+    readonly '--available-width': "The width in px the panel can take before it reaches the viewport edges, minus 20px.";
+    readonly '--available-height': "The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with `max-height: min(240px, var(--available-height))`.";
+    readonly '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.";
+    readonly '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.";
+    readonly '--transform-origin': "The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.";
+};
+/** The name of a Popover CSS variable. */
+export type PopoverCssVariable = keyof typeof popoverCssVariables;