entasis 0.11.0 → 0.12.0

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

@@ -0,0 +1,28 @@
+/**
+ * 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 const popoverDataAttributes = {
+    'data-open': 'On the panel: present while open.',
+    'data-closed': 'On the panel: present while its exit transition plays (a closed panel is not rendered).',
+    'data-entering': 'On the panel: present while the enter transition plays.',
+    'data-exiting': 'On the panel: present while the exit transition plays.',
+    '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.',
+    'data-align': 'On the panel: `start`, `center` or `end`, how it lines up with the trigger (absent with `data-side="none"`).',
+    'data-anchor-hidden': 'On the panel: present while the trigger is scrolled out of view; the panel is hidden meanwhile.',
+    'data-uncentered': 'On the arrow: present while the trigger is not under the middle of the panel (a shift moved the panel).',
+    '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.',
+    '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 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 const popoverCssVariables = {
+    '--available-width': 'The width in px the panel can take before it reaches the viewport edges, minus 20px.',
+    '--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))`.",
+    '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.",
+    '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.",
+    '--transform-origin': 'The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.'
+};

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

@@ -0,0 +1,19 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * Sets an attribute on an anchor for one owner: the anchor shows the value of the owner that
+ * claimed it last, and loses the attribute only when no owner claims it. Several popovers (a menu
+ * and its tooltip) can share one trigger; one closing must not strip the others' hook.
+ * Pass `null` to withdraw the owner's claim.
+ */
+export declare const claimAnchorAttribute: (anchor: HTMLElement, owner: object, name: string, value: string | null) => void;
+/** `data-popup-side` on an anchor for one owner; see `claimAnchorAttribute`. */
+export declare const claimPopupSide: (anchor: HTMLElement, owner: object, side: string | null) => void;
+/** `data-popup-open` on an anchor for one owner while its popup is open; see `claimAnchorAttribute`. */
+export declare const claimPopupOpen: (anchor: HTMLElement, owner: object, open: boolean) => void;
+/**
+ * Claims `data-popup-open` on its element while `open` holds (`{@attach popupOpenClaim(open)}`),
+ * for a trigger whose popup is not anchored to it, such as a Select button inside its field.
+ * Writing the attribute from the template instead would let a tooltip on the same element remove
+ * it when the tooltip closes.
+ */
+export declare const popupOpenClaim: (open: boolean) => Attachment<HTMLElement>;

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

@@ -0,0 +1,45 @@
+/** The owners claiming each attribute on each anchor element, in the order they last claimed. */
+const anchorAttributeClaims = new WeakMap();
+/**
+ * Sets an attribute on an anchor for one owner: the anchor shows the value of the owner that
+ * claimed it last, and loses the attribute only when no owner claims it. Several popovers (a menu
+ * and its tooltip) can share one trigger; one closing must not strip the others' hook.
+ * Pass `null` to withdraw the owner's claim.
+ */
+export const claimAnchorAttribute = (anchor, owner, name, value) => {
+    let byName = anchorAttributeClaims.get(anchor);
+    let claims = byName?.get(name);
+    if (value === null) {
+        claims?.delete(owner);
+    }
+    else {
+        if (!byName)
+            anchorAttributeClaims.set(anchor, (byName = new Map()));
+        if (!claims)
+            byName.set(name, (claims = new Map()));
+        claims.delete(owner);
+        claims.set(owner, value);
+    }
+    const current = claims && [...claims.values()].at(-1);
+    if (current !== undefined)
+        anchor.setAttribute(name, current);
+    else
+        anchor.removeAttribute(name);
+};
+/** `data-popup-side` on an anchor for one owner; see `claimAnchorAttribute`. */
+export const claimPopupSide = (anchor, owner, side) => claimAnchorAttribute(anchor, owner, 'data-popup-side', side);
+/** `data-popup-open` on an anchor for one owner while its popup is open; see `claimAnchorAttribute`. */
+export const claimPopupOpen = (anchor, owner, open) => claimAnchorAttribute(anchor, owner, 'data-popup-open', open ? '' : null);
+/**
+ * Claims `data-popup-open` on its element while `open` holds (`{@attach popupOpenClaim(open)}`),
+ * for a trigger whose popup is not anchored to it, such as a Select button inside its field.
+ * Writing the attribute from the template instead would let a tooltip on the same element remove
+ * it when the tooltip closes.
+ */
+export const popupOpenClaim = (open) => (node) => {
+    if (!open)
+        return;
+    const owner = {};
+    claimPopupOpen(node, owner, true);
+    return () => claimPopupOpen(node, owner, false);
+};

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

@@ -1 +1 @@
-export declare const popoverDescription = "\n# Popover Component\n\nThe Popover component displays floating content positioned relative to a trigger element. It's ideal for tooltips, dropdown menus, and contextual information.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\t\t\n</script>\n// By default Popover comes with a button that triggers them, no need to define a callback and a $state\n<Popover trigger={{ content: \"Toggle Popover\" }}>\n\tPopover content here\n</Popover>\n```\n\n## Props\n\n### Core Props\n- **open**: boolean (bindable) - Controls popover visibility (optional when using trigger prop)\n- **defaultOpen**: boolean (default: false) - Initial state when open is not provided\n- **ref**: HTMLElement | null - Reference element to position popover against (optional when using trigger prop)\n- **id**: string - Unique identifier\n\n### Layout Props\n- **position**: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' (default: 'bottom')\n  - Determines where popover appears relative to trigger\n- **offset**: number - Distance in pixels from the reference element\n- **fitTrigger**: boolean (default: false) - Whether popover should match the width of the trigger element\n- **positionPanel**: ({ panel, reference }) => { x: number; y: number; minWidth?: number } | null - Place the panel yourself instead of floating-ui: return its viewport coordinates (the panel is `position: fixed`) and optionally a `minWidth` in px that replaces `fitTrigger`'s, or `null` to fall back to `position`. Called when the panel mounts and whenever floating-ui would reposition it. Select uses it to open over its trigger\n- **mobileSheet**: boolean (default: false) - On mobile viewports (<768px), render as a bottom sheet instead of an anchored floating panel\n- **inline**: boolean (default: false) - Render the panel in normal document flow where the component sits instead of portaling to the viewport-fixed layer: no floating-ui positioning, no scroll lock, no outside-press dismissal (Escape still closes it). Same panel classes and motion, and the trigger still toggles it. Wins over `mobileSheet`\n- **mobileSheetSizeTransition**: boolean (default: true) - Whether mobile-sheet panels animate intrinsic size changes\n\n### Event Props\n- **onOpenChange**: (open: boolean) => void - Called once for each library-requested state change\n- **onAfterOpen**: (payload: PopoverState) => void - Called after the open transition finishes\n- **onAfterClose**: (payload: PopoverState) => void - Called after the close transition finishes\n\n### Slot Props\n- **children**: Snippet<[PopoverState]> - Popover content\n- **trigger**: Snippet<[PopoverState]> | (ButtonProps & { content?: string }) | false - Trigger element\n  - Pass a snippet function for custom trigger: `{#snippet trigger(popover)}...</snippet>`. Put\n    `{@attach popover.trigger}` on any element (a card, an avatar, a Button) and it opens the\n    panel on click and from the keyboard, with the ARIA state kept in sync. Type the parameter\n    with `PopoverState` from `entasis/popover`.\n  - Pass button props object for default button: `trigger={{ content: \"Click Me\", color: \"primary\" }}`.\n    `children` (a string or a snippet) replaces `content` for a richer body; `prefix` and\n    `suffix` work as on Button.\n  - Pass `false` to disable trigger (use with external ref)\n\n### Interaction Props\n- **openOnHover**: boolean (default: false) - Open on mouse hover\n- **openOnClick**: boolean (default: true) - Open on click\n- **delay**: number (default: 100) - Delay in ms before opening on hover\n- **closeOnEscape**: boolean (default: true) - Close on Escape. Only the topmost open layer closes, so Escape inside a nested popover leaves its parent open\n- **closeOnClickOutside**: boolean (default: true) - Close on an outside press. A press dismisses this popover and every layer stacked above it, but never the layer that was pressed\n- **closeOnMouseLeave**: boolean (default: false) - Close when the pointer leaves the hover safe area. The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open.\n- **debugSafeArea**: boolean (default: false) - Show hover safe-area overlays. Trigger/panel rectangles render in blue; the prediction cone toward the panel renders in orange.\n\n### Focus & ARIA Props\n- **focusOnOpen**: 'first' | 'container' | false (default: false) - Where focus goes when the panel opens: `'first'` moves it to an `[autofocus]` / `[data-autofocus]` target or the first tabbable control, `'container'` focuses the panel itself, `false` keeps it on the trigger. Focus always returns to the trigger when the popover closes (Escape or outside press)\n- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true (default: 'dialog') - Value of `aria-haspopup` on the trigger, describing what the panel contains. `aria-expanded` and `aria-controls` are managed automatically alongside it, for the built-in Button trigger and for a snippet trigger using `{@attach popover.reference}`\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover focusOnOpen=\"first\" haspopup=\"listbox\" trigger={{ content: 'Pick one' }}>\n\t<ul role=\"listbox\"><li role=\"option\" tabindex=\"0\">First</li></ul>\n</Popover>\n```\n\n### Visual Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: Compact popover size\n  - normal: Standard popover size\n  - large: Larger popover size\n- **transition**: TransitionConfig - Custom transition animation\n- **directedTransition**: boolean (default: true) - Transition direction follows position\n\n### Behavior Props\n- **lockScroll**: boolean (default: true) - Lock body scroll when open\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<PopoverTrigger>\n\t<Trigger />\n</PopoverTrigger>\n\n<PopoverContent>\n\t<Children />\n</PopoverContent>\n```\n\n## Examples\n\n### More Examples\n\n### With a custom trigger snippet\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n</script>\n\n<!-- {@attach popover.trigger} anchors the panel to the element, toggles it on click and keeps\n     aria-haspopup / aria-expanded / aria-controls in sync on it -->\n<Popover>\n\t{#snippet trigger(popover)}\n\t\t<Button {@attach popover.trigger}>Open</Button>\n\t{/snippet}\n\t\n\t<p>This is a popover!</p>\n</Popover>\n```\n\nAny element works. One that is not a control gets `role=\"button\"`, `tabindex=\"0\"` and Enter/Space\nactivation:\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover, type PopoverState } from 'entasis/popover';\n\timport { Avatar } from 'entasis/avatar';\n</script>\n\n<Popover>\n\t{#snippet trigger(popover: PopoverState)}\n\t\t<div class=\"flex items-center gap-sm\" {@attach popover.trigger}>\n\t\t\t<Avatar name=\"Ada Lovelace\" />\n\t\t\t<span>Ada Lovelace</span>\n\t\t</div>\n\t{/snippet}\n\n\t<p>Profile details</p>\n</Popover>\n```\n\n### With button props\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{\n\t\tcontent: \"Click Me\",\n\t\tcolor: \"secondary\",\n\t\tsize: \"small\"\n\t}}\n>\n\t<p>This is a popover!</p>\n</Popover>\n```\n\n### Different Positions\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Top -->\n<Popover position=\"top\" trigger={{ content: \"Top\" }}>\n\tTop popover\n</Popover>\n\n<!-- Bottom -->\n<Popover position=\"bottom\" trigger={{ content: \"Bottom\" }}>\n\tBottom popover\n</Popover>\n\n<!-- Left -->\n<Popover position=\"left\" trigger={{ content: \"Left\" }}>\n\tLeft popover\n</Popover>\n\n<!-- Right -->\n<Popover position=\"right\" trigger={{ content: \"Right\" }}>\n\tRight popover\n</Popover>\n```\n\n### Advanced Example\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n</script>\n\n<Popover position=\"bottom-start\" trigger={{ content: \"Menu\" }}>\n\t<div class=\"flex flex-col gap-1\">\n\t\t<Button variant=\"ghost\" fullWidth>Profile</Button>\n\t\t<Button variant=\"ghost\" fullWidth>Settings</Button>\n\t\t<Button variant=\"ghost\" fullWidth>Logout</Button>\n\t</div>\n</Popover>\n```\n\n### Open on Hover\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Hover Me\" }}\n\topenOnHover\n\topenOnClick={false}\n\tdelay={200}\n>\n\tHover content\n</Popover>\n```\n\n### With Custom Offset\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Trigger\" }}\n\tposition=\"bottom\"\n\toffset={20}\n>\n\t20px away from trigger\n</Popover>\n```\n\n### Fit Trigger Width\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Click Me\" }}\n\tfitTrigger\n>\n\tPopover matches trigger width\n</Popover>\n```\n\n### Inline (static, in flow)\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Open in place, no portal: useful for docs, visual tests, or an always-visible panel -->\n<Popover inline open trigger={false}>\n\t<p>Rendered where the component sits.</p>\n</Popover>\n\n<!-- The trigger still toggles an inline panel -->\n<Popover inline trigger={{ content: 'Toggle' }}>\n\t<p>Expands below the trigger, in the flow.</p>\n</Popover>\n```\n\n### Mobile Bottom Sheet\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover\n\ttrigger={{ content: \"Open filters\" }}\n\tposition=\"bottom\"\n\tmobileSheet\n>\n\tFilters content\n</Popover>\n```\n\n### Different Sizes\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Small -->\n<Popover size=\"small\" trigger={{ content: \"Small\" }}>\n\tSmall popover\n</Popover>\n\n<!-- Large -->\n<Popover size=\"large\" trigger={{ content: \"Large\" }}>\n\tLarge popover with more content\n</Popover>\n```\n\n### Close on Mouse Leave\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Hover Me\" }}\n\topenOnHover\n\tcloseOnMouseLeave\n>\n\tCloses when you move outside the rectangle tolerance\n</Popover>\n```\n\n### With Lifecycle Hooks\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Trigger\" }}\n\tonAfterOpen={(payload) => console.log('Popover opened', payload)}\n\tonAfterClose={(payload) => console.log('Popover closed', payload)}\n>\n\tWatch the console\n</Popover>\n```\n\n### User Card Popover with External Ref\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n\timport { Avatar } from 'entasis/avatar';\n\n\tlet avatarRef = $state<HTMLElement | null>(null);\n\tlet open = $state(false);\n\tconst user = { name: 'John Doe', email: 'john@example.com' };\n</script>\n\n<button type=\"button\" bind:this={avatarRef} onclick={() => (open = !open)}>\n\t<Avatar name={user.name} />\n</button>\n\n<Popover bind:open ref={avatarRef} position=\"bottom\">\n\t<div class=\"p-4\">\n\t\t<h3>{user.name}</h3>\n\t\t<p>{user.email}</p>\n\t\t<Button fullWidth>View Profile</Button>\n\t</div>\n</Popover>\n```\n\n## State Management\n\nThe Popover component uses a `PopoverState` instance that is passed to all slot snippets. This state object provides:\n\n- **id**: string - Popover identifier\n- **size**: Size - Current popover size\n- **position**: Placement - Current popover position\n- **offset**: number - Current offset value\n- **open()**: () => void - Method to open the popover\n- **close()**: () => void - Method to close the popover\n- **toggle()**: () => void - Method to toggle the popover\n- **trigger**: attachment that makes any element the trigger (`{@attach popover.trigger}`): `reference` plus a click toggle (when `openOnClick`), and on a non-control `role=\"button\"`, `tabindex=\"0\"` and Enter/Space activation. The element's own handler wins: when it calls `open`, `close`, `toggle` or `setOpen` during the click, the default toggle stands down, so a kept `onclick={popover.toggle}` does not toggle twice\n- **reference**: attachment for a custom trigger element (`{@attach popover.reference}`); anchors the panel to it and keeps its `aria-haspopup`, `aria-expanded`, and `aria-controls` in sync, leaving clicks and keyboard to the element\n\n## Accessibility\n\n- The trigger carries `aria-haspopup` (from `haspopup`), `aria-expanded`, and `aria-controls` \u2014 automatically for the built-in Button and for a snippet trigger using `{@attach popover.trigger}` or `{@attach popover.reference}`\n- `focusOnOpen` decides where focus lands on open; focus returns to the trigger on close, whether by Escape or an outside press\n- Non-modal: Tab is not contained and the page is not made inert (use Dialog for that)\n- Escape closes only the topmost open layer; an outside press dismisses every layer stacked above the one pressed. Popovers, menus, and dialogs share one layer stack\n- Keyboard navigation support\n\n## Notes\n\n- Popover is positioned using floating-ui, except with `inline`, where the document lays the panel out\n- Automatically adjusts position to stay in viewport\n- Multiple popovers can be stacked\n- Scroll locking prevents background scroll (when enabled)\n- Transitions animate based on position direction\n\n## Theme Customization\n\nThe Popover component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Open/close transition preset, keyed by `mode` (a floating panel scales, the mobile\n  sheet slides up). Takes `in` / `out` FSO params plus a `duration` / `easing` motion token;\n  the `transition` prop wins over it\n- **popover**: Main popover container styles\n\n### Theme Type Definition\n\n```typescript\nimport type { PopoverThemeProps } from 'entasis/popover';\n\n// Example theme customization\nconst customTheme: PopoverThemeProps = {\n  popover: {\n    base: 'z-[+50] fixed bg-surface-floating text-neutral w-fit rounded-xl raised isolate h-fit',\n    size: {\n      small: 'max-w-3xs w-full p-2',\n      normal: 'max-w-xs w-full p-3',\n      large: 'max-w-sm w-full p-4'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**popover**:\n- base: Base classes applied to all popovers\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls max-width, width, and padding\n  - mode: 'floating' | 'inline' | 'mobileSheet' - Set from `inline` / `mobileSheet`; `root` positions the wrapper (fixed, in flow, or full-screen sheet)\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Popover \n  trigger={{ content: \"Click Me\" }}\n  theme={{\n    popover: {\n      base: 'rounded-xl lift-5 border-2 border-primary',\n      size: {\n        normal: 'max-w-md p-4'\n      }\n    }\n  }}\n>\n  Custom styled popover content\n</Popover>\n```\n\n**Size Customization**:\n```svelte\n<Popover \n  size=\"large\"\n  trigger={{ content: \"Large Popover\" }}\n  theme={{\n    popover: {\n      size: {\n        large: 'max-w-lg p-6'\n      }\n    }\n  }}\n>\n  Large popover with more padding\n</Popover>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setPopoverTheme } from './index.ts';\n  \n  setPopoverTheme({\n    popover: {\n      base: 'rounded-lg lift-5 backdrop-blur-sm bg-white/95',\n      size: {\n        normal: 'max-w-sm p-4'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const popoverDescription = "\n# Popover Component\n\nThe Popover component displays floating content positioned relative to a trigger element. It's ideal for tooltips, dropdown menus, and contextual information.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\t\t\n</script>\n// By default Popover comes with a button that triggers them, no need to define a callback and a $state\n<Popover trigger={{ content: \"Toggle Popover\" }}>\n\tPopover content here\n</Popover>\n```\n\n## Props\n\n### Core Props\n- **open**: boolean (bindable) - Controls popover visibility (optional when using trigger prop)\n- **defaultOpen**: boolean (default: false) - Initial state when open is not provided\n- **ref**: HTMLElement | null - Reference element to position popover against (optional when using trigger prop)\n- **id**: string - Unique identifier\n\n### Layout Props\n- **position**: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' | 'inline-start' | 'inline-end' | 'inline-start-start' | 'inline-start-end' | 'inline-end-start' | 'inline-end-end' (default: 'top'; responsive values allowed)\n  - Determines where popover appears relative to trigger. The panel flips to the opposite side when the preferred one has no room, and shifts back inside the viewport (20px from its edges)\n  - `inline-start` / `inline-end` are logical sides: left / right in a left-to-right document, right / left in a right-to-left one (the i18n direction context, else the trigger's computed `direction`). The `start` / `end` alignment of `top` and `bottom` already follows the reading direction\n- **collisionBoundary**: 'visualViewport' | 'layoutViewport' (default: 'visualViewport') - The viewport the panel is shifted back into. The visual viewport is the visible area: it shrinks under an on-screen keyboard and follows pinch-zoom. `'layoutViewport'` ignores pinch-zoom so panning a zoomed page doesn't drag the panel along; flipping and `--available-*` still use the visual viewport. ContextMenu uses `'layoutViewport'`\n- **fallbackAxisSide**: 'start' | 'end' | 'none' (default: 'none') - When the panel fits neither on its side nor the opposite one, also try the perpendicular sides: `'end'` tries bottom (or the inline end) first, `'start'` top (or the inline start). A panel placed beside its reference (left or right) tries only the side asked for, so it never jumps over the reference's own row and menu. Submenus use `'end'`, so a submenu with no room beside its menu opens below its row, sliding back into the viewport if that is still too tight\n- **anchorTo**: 'box' | 'line' (default: 'box') - What the panel anchors to when its trigger wraps across lines (a link in prose): the whole bounding box, or the line the pointer was on when the panel opened, kept while it stays open. A keyboard open takes the first line above the trigger and the last one below it\n- **offset**: number - Distance in pixels from the reference element\n- **fitTrigger**: boolean (default: false) - Whether popover should match the width of the trigger element (the trigger width snapped to the device pixel grid, also published as `--anchor-width`)\n- **positionPanel**: ({ panel, reference }) => { x: number; y: number; minWidth?: number } | null - Place the panel yourself instead of floating-ui: return its viewport coordinates (the panel is `position: fixed`) and optionally a `minWidth` in px that replaces `fitTrigger`'s, or `null` to fall back to `position`. Called when the panel mounts and whenever floating-ui would reposition it. Select uses it to open over its trigger\n- **mobileSheet**: boolean (default: false) - On mobile viewports (<768px), render as a bottom sheet instead of an anchored floating panel\n- **inline**: boolean (default: false) - Render the panel in normal document flow where the component sits instead of portaling to the viewport-fixed layer: no floating-ui positioning, no scroll lock, no outside-press dismissal (Escape still closes it). Same panel classes and motion, and the trigger still toggles it. Wins over `mobileSheet`\n- **mobileSheetSizeTransition**: boolean (default: true) - Whether mobile-sheet panels animate intrinsic size changes\n\n### Event Props\n- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before each library-requested state change, with `details.reason` (`'trigger-press'`, `'trigger-hover'`, `'outside-press'`, `'escape-key'`, `'item-press'`, `'trigger-unmount'`, `'imperative-action'`\u2026), `details.event`, `details.trigger`, `details.interaction` and `details.cancel()`. Cancelling keeps the popover as it is and leaves the event untouched (a cancelled Escape is not `defaultPrevented`). Inside the callback `open` still holds the previous state. Types from `entasis/types`\n- **onAfterOpen**: (payload: PopoverApi<Payload>) => void - Called once per open after the open transition finishes, right away when none plays (`defaultOpen`, `inline`)\n- **onAfterClose**: (payload: PopoverApi<Payload>) => void - Called once per close after the close transition finishes\n\n### Slot Props\n- **children**: Snippet<[PopoverApi<Payload>]> - Popover content. `Payload` is inferred from the type you give the snippet parameter (`PopoverApi<Person>`) and defaults to `unknown`\n- **trigger**: Snippet<[PopoverApi<Payload>]> | (ButtonProps & { content?: string }) | false - Trigger element\n  - Pass a snippet function for custom trigger: `{#snippet trigger(popover)}...</snippet>`. Put\n    `{@attach popover.trigger}` on any element (a card, an avatar, a Button) and it opens the\n    panel on click and from the keyboard, with the ARIA state kept in sync. Type the parameter\n    with `PopoverApi` from `entasis/popover`.\n  - Pass button props object for default button: `trigger={{ content: \"Click Me\", color: \"primary\" }}`.\n    `children` (a string or a snippet) replaces `content` for a richer body; `prefix` and\n    `suffix` work as on Button.\n  - Pass `false` to disable trigger (use with external ref)\n\n### Interaction Props\n- **openOnHover**: boolean (default: false) - Open on mouse hover, after `delay`. Works whether the popover started closed or open (`defaultOpen`): once closed, hovering the trigger opens it again. A hover-opened popover does not lock page scroll, and pressing its trigger pins it open instead of closing it. Touch taps and disabled triggers (`disabled`, `aria-disabled=\"true\"`, `data-disabled`) never hover-open it, a pending open needs the pointer still on the trigger when the delay ends, and a trigger that appears under a resting pointer (a menu reopened from the keyboard) waits for the pointer to move. Right after another hover popover, tooltip or hover card was open (within 400 ms), a root popover opens without the delay; submenus keep theirs\n- **openOnClick**: boolean (default: true) - Open on click\n- **delay**: number (default: 100) - Delay in ms before opening on hover; leaving the trigger before it elapses cancels the open, and so does any other open-state change meanwhile (a click that opens and closes it, Escape), so a pending hover never reopens a popover the user just closed\n- **closeOnEscape**: boolean (default: true) - Close on Escape. Only the topmost open layer closes, so Escape inside a nested popover leaves its parent open\n- **closeOnClickOutside**: boolean (default: true) - Close on an outside press. A press dismisses this popover and every layer stacked above it, but never the layer that was pressed. A press that began before the popover opened does not count, and on a touch screen only a tap does: a finger that starts scrolling the page leaves it open\n- **closeOnMouseLeave**: boolean (default: false) - Close a popover that hovering opened when the pointer leaves the hover safe area (`reason: 'trigger-hover'`). The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open. A popover opened by a press, the keyboard or code stays open.\n- **closeDelay**: number (default: 120) - Milliseconds the pointer may spend outside the hover safe area before `closeOnMouseLeave` closes the popover; a longer delay forgives a pointer that overshoots on its way to the panel\n- **debugSafeArea**: boolean (default: false) - Show hover safe-area overlays. Trigger/panel rectangles render in blue; the prediction cone toward the panel renders in orange.\n\n### Focus & ARIA Props\n- **focusOnOpen**: 'first' | 'container' | false (default: false) - Where focus goes when the panel opens: `'first'` moves it to an `[autofocus]` / `[data-autofocus]` target or the first tabbable control, `'container'` focuses the panel itself, `false` keeps it on the trigger. When the popover closes with focus inside it, focus returns to the trigger that opened it (or the control pressed inside a wrapper trigger), and after a programmatic open to the element that had focus when it opened\n- **focusOnClose**: boolean | HTMLElement | ((details) => HTMLElement | boolean | void) (default: true) - Where focus goes when the popover closes with focus inside it or after a trigger opened it. `true` returns it to the trigger (a visible focus ring after Escape or another keyboard close), else to the most recent element still on the page; `false` leaves focus alone; an element receives it; a function gets the change details and returns one of these, or nothing to restore as usual. A close because focus moved on (`'focus-out'`) never moves it\n- **label**: string - The popup's accessible name, written as `aria-label` on the `<dialog>` (on the element with the menu, listbox, tree or grid role inside a non-dialog popup unless it has a name of its own, and on the mobile sheet's dialog). A popover that holds a form or a picker is announced as a dialog: name it\n- **labelledBy**: string - The id of an element that names the popup, written as `aria-labelledby` where `label` goes\n- **modal**: boolean (default: false) - Makes a floating popover modal: Tab stays inside the panel (wrapping from the last control to the first), the rest of the page becomes `inert`, the panel opens with focus inside it (`focusOnOpen` defaults to `'first'`), the layer counts as modal for Android Back and touch dismissal, and a visually hidden Close button at the end of the panel (out of the Tab order, `reason: 'close-press'`) gives screen reader users a control that closes it. A modal popover does not open on hover, and an `inline` panel ignores it. The mobile sheet is always modal\n- **tabBridge**: boolean (default: true) - Tab on the open trigger enters the portaled panel, Tab past its last control continues after the trigger and closes the panel (`reason: 'focus-out'`), and Shift+Tab on its first control returns to the trigger; a screen reader finds the panel straight after the trigger through `aria-owns`. Applies to dialog popups opened from a trigger. Menus, listboxes and the like (`haspopup`), modal popovers, `ref`-anchored panels and panels a hover opened manage Tab themselves; set `false` for a panel that is not meant to be tabbed into (the tooltip surface does). A trigger that is a text field (a date, color or phone input) is never bridged: Tab there moves on to the next field\n- **closeOnFocusOut**: boolean (default: the value of `closeOnClickOutside`) - Close (`reason: 'focus-out'`) when focus that was inside the popover or on its trigger moves to a control outside both and outside any popup opened from them. Focus that never entered is left to outside presses, and focus that moved on is not taken back. Does not apply to menus, lists, modal popovers or a popover the pointer opened by hovering\n- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true (default: 'dialog') - Value of `aria-haspopup` on the trigger, describing what the panel contains. `aria-expanded` and `aria-controls` are managed automatically alongside it, for the built-in Button trigger and for a snippet trigger using `{@attach popover.reference}`. A `'dialog'` popup renders in a `<dialog>`; any other value renders a plain `<div>` wrapper, points `aria-controls` at the element inside with the matching role (`role=\"menu\"` for `menu` and `true`) and labels that element by the trigger (`aria-labelledby`) unless it has an `aria-label`\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover focusOnOpen=\"first\" haspopup=\"listbox\" trigger={{ content: 'Pick one' }}>\n\t<ul role=\"listbox\"><li role=\"option\" tabindex=\"0\">First</li></ul>\n</Popover>\n```\n\n### Visual Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: Compact popover size\n  - normal: Standard popover size\n  - large: Larger popover size\n- **arrow**: boolean (default: false) - Draws an arrow from a floating panel toward its trigger, inside the panel behind its content. It is placed by floating-ui's `arrow` middleware after `shift`, so it keeps pointing at the trigger when the panel slides to fit the viewport, stays 10px from the panel's corners, and writes `data-side` (the physical side it sits on) and `data-uncentered` (the trigger is not under the middle of the panel). Style it with `theme.arrow`; it takes the panel colour (`bg-surface-floating`)\n- **transition**: TransitionConfig - Custom transition animation\n- **directedTransition**: boolean (default: true) - Transition direction follows position\n\n### Behavior Props\n- **lockScroll**: boolean (default: true) - Lock page scroll while a root-level popover is open, unless hovering opened it, or a finger did and the panel is more than 20px narrower than the viewport (a touch popover the page can still scroll under stays unlocked). The lock is the `data-entasis-scroll-lock` attribute on `<html>`; `--entasis-scrollbar-width` holds the hidden scrollbar's width for fixed bars\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Styling hooks\n\nA floating panel is placed before it shows: it stays hidden until its first placement lands, and `focusOnOpen` waits for that placement too. Every placement (scroll, resize, a flip, the end of the opening transition, and the visual viewport settling after an on-screen keyboard) updates these hooks.\n\n**Data attributes** (presence attributes unless they carry a value)\n- `data-open`: On the panel: present while open.\n- `data-closed`: On the panel: present while its exit transition plays (a closed panel is not rendered).\n- `data-entering`: On the panel: present while the enter transition plays.\n- `data-exiting`: On the panel: present while the exit transition plays.\n- `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.\n- `data-align`: On the panel: `start`, `center` or `end`, how it lines up with the trigger (absent with `data-side=\"none\"`).\n- `data-anchor-hidden`: On the panel: present while the trigger is scrolled out of view; the panel is hidden meanwhile.\n- `data-uncentered`: On the arrow: present while the trigger is not under the middle of the panel (a shift moved the panel).\n- `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.\n- `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.\n\n**CSS variables** (set on the positioned wrapper, inherited by the panel and its content)\n- `--available-width`: The width in px the panel can take before it reaches the viewport edges, minus 20px.\n- `--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))`.\n- `--anchor-width`: The trigger's width in px, snapped to the device pixel grid.\n- `--anchor-height`: The trigger's height in px, snapped to the device pixel grid.\n- `--transform-origin`: The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.\n\nThe typed maps `popoverDataAttributes` and `popoverCssVariables` (from `entasis/popover`) list each name with its meaning. Select, Combobox, Menu, PopupMenu, HoverCard and Tooltip are built on Popover and carry the same panel hooks.\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Square the corner that touches the trigger, whichever side the panel lands on -->\n<Popover\n\tposition=\"bottom-start\"\n\tclass=\"data-[side=bottom]:rounded-t-none data-[side=top]:rounded-b-none\"\n\ttrigger={{ content: 'Open' }}\n>\n\tAttached panel\n</Popover>\n\n<!-- Opens on the reading direction's end side: right in English, left in Arabic -->\n<Popover position=\"inline-end\" trigger={{ content: 'Details' }}>Details</Popover>\n```\n\n## Structure\n\n```\n<PopoverTrigger>\n\t<Trigger />\n</PopoverTrigger>\n\n<PopoverContent>\n\t<Children />\n</PopoverContent>\n```\n\n## Examples\n\n### More Examples\n\n### With a custom trigger snippet\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n</script>\n\n<!-- {@attach popover.trigger} anchors the panel to the element, toggles it on click and keeps\n     aria-haspopup / aria-expanded / aria-controls in sync on it -->\n<Popover>\n\t{#snippet trigger(popover)}\n\t\t<Button {@attach popover.trigger}>Open</Button>\n\t{/snippet}\n\t\n\t<p>This is a popover!</p>\n</Popover>\n```\n\nAny element works. One that is not a control gets `role=\"button\"`, `tabindex=\"0\"` and Enter/Space\nactivation:\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover, type PopoverApi } from 'entasis/popover';\n\timport { Avatar } from 'entasis/avatar';\n</script>\n\n<Popover>\n\t{#snippet trigger(popover: PopoverApi)}\n\t\t<div class=\"flex items-center gap-sm\" {@attach popover.trigger}>\n\t\t\t<Avatar name=\"Ada Lovelace\" />\n\t\t\t<span>Ada Lovelace</span>\n\t\t</div>\n\t{/snippet}\n\n\t<p>Profile details</p>\n</Popover>\n```\n\n### One popup for many triggers\n\nA list of rows needs one Popover, not one per row. `popover.triggerFor(() => row)` is `popover.trigger` plus a payload getter: the popup moves to the trigger that was pressed (pressing another trigger while it is open moves it there and keeps it open), and `popover.payload` is that trigger's data, read live. Pass a getter, not the value, so the payload follows its source without the trigger being removed and re-attached (which would close the popover).\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover, type PopoverApi } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n\n\ttype Person = { id: number; name: string; role: string };\n\tlet { people }: { people: Person[] } = $props();\n</script>\n\n<Popover position=\"bottom\" arrow>\n\t{#snippet trigger(popover: PopoverApi<Person>)}\n\t\t{#each people as person (person.id)}\n\t\t\t<Button {@attach popover.triggerFor(() => person)}>{person.name}</Button>\n\t\t{/each}\n\t{/snippet}\n\t{#snippet children(popover: PopoverApi<Person>)}\n\t\t<strong>{popover.payload?.name}</strong>\n\t\t<p>{popover.payload?.role}</p>\n\t{/snippet}\n</Popover>\n```\n\n### Modal and named\n\n```svelte\n<Popover modal label=\"Delivery options\" trigger={{ content: 'Delivery options' }}>\n\t<fieldset>...</fieldset>\n\t<Button>Save</Button>\n</Popover>\n```\n\n### With button props\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{\n\t\tcontent: \"Click Me\",\n\t\tcolor: \"secondary\",\n\t\tsize: \"small\"\n\t}}\n>\n\t<p>This is a popover!</p>\n</Popover>\n```\n\n### Different Positions\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Top -->\n<Popover position=\"top\" trigger={{ content: \"Top\" }}>\n\tTop popover\n</Popover>\n\n<!-- Bottom -->\n<Popover position=\"bottom\" trigger={{ content: \"Bottom\" }}>\n\tBottom popover\n</Popover>\n\n<!-- Left -->\n<Popover position=\"left\" trigger={{ content: \"Left\" }}>\n\tLeft popover\n</Popover>\n\n<!-- Right -->\n<Popover position=\"right\" trigger={{ content: \"Right\" }}>\n\tRight popover\n</Popover>\n```\n\n### Advanced Example\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n</script>\n\n<Popover position=\"bottom-start\" trigger={{ content: \"Menu\" }}>\n\t<div class=\"flex flex-col gap-1\">\n\t\t<Button variant=\"ghost\" fullWidth>Profile</Button>\n\t\t<Button variant=\"ghost\" fullWidth>Settings</Button>\n\t\t<Button variant=\"ghost\" fullWidth>Logout</Button>\n\t</div>\n</Popover>\n```\n\n### Open on Hover\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Hover Me\" }}\n\topenOnHover\n\topenOnClick={false}\n\tdelay={200}\n>\n\tHover content\n</Popover>\n```\n\n### With Custom Offset\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Trigger\" }}\n\tposition=\"bottom\"\n\toffset={20}\n>\n\t20px away from trigger\n</Popover>\n```\n\n### Fit Trigger Width\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Click Me\" }}\n\tfitTrigger\n>\n\tPopover matches trigger width\n</Popover>\n```\n\n### Inline (static, in flow)\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Open in place, no portal: useful for docs, visual tests, or an always-visible panel -->\n<Popover inline open trigger={false}>\n\t<p>Rendered where the component sits.</p>\n</Popover>\n\n<!-- The trigger still toggles an inline panel -->\n<Popover inline trigger={{ content: 'Toggle' }}>\n\t<p>Expands below the trigger, in the flow.</p>\n</Popover>\n```\n\n### Mobile Bottom Sheet\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover\n\ttrigger={{ content: \"Open filters\" }}\n\tposition=\"bottom\"\n\tmobileSheet\n>\n\tFilters content\n</Popover>\n```\n\n### Different Sizes\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<!-- Small -->\n<Popover size=\"small\" trigger={{ content: \"Small\" }}>\n\tSmall popover\n</Popover>\n\n<!-- Large -->\n<Popover size=\"large\" trigger={{ content: \"Large\" }}>\n\tLarge popover with more content\n</Popover>\n```\n\n### Close on Mouse Leave\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Hover Me\" }}\n\topenOnHover\n\tcloseOnMouseLeave\n>\n\tCloses when you move outside the rectangle tolerance\n</Popover>\n```\n\n### With Lifecycle Hooks\n\n```svelte\n<script>\n\timport { Popover } from 'entasis/popover';\n</script>\n\n<Popover \n\ttrigger={{ content: \"Trigger\" }}\n\tonAfterOpen={(payload) => console.log('Popover opened', payload)}\n\tonAfterClose={(payload) => console.log('Popover closed', payload)}\n>\n\tWatch the console\n</Popover>\n```\n\n### Keep it open with onOpenChange\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover } from 'entasis/popover';\n\timport type { OpenChangeDetails } from 'entasis/types';\n\n\tlet note = $state('');\n\t// Runs before the change: an outside press or Escape keeps a popover with an unsaved note.\n\tconst keepNote = (open: boolean, details: OpenChangeDetails) => {\n\t\tconst dismissal = details.reason === 'outside-press' || details.reason === 'escape-key';\n\t\tif (!open && dismissal && note) details.cancel();\n\t};\n</script>\n\n<Popover trigger={{ content: 'Add a note' }} focusOnOpen=\"first\" onOpenChange={keepNote}>\n\t{#snippet children(popover)}\n\t\t<textarea aria-label=\"Note\" bind:value={note}></textarea>\n\t\t<button\n\t\t\ttype=\"button\"\n\t\t\tonclick={() => {\n\t\t\t\tnote = '';\n\t\t\t\tpopover.close();\n\t\t\t}}>Discard</button\n\t\t>\n\t{/snippet}\n</Popover>\n```\n\n### User Card Popover with External Ref\n\n```svelte\n<script lang=\"ts\">\n\timport { Popover } from 'entasis/popover';\n\timport { Button } from 'entasis/button';\n\timport { Avatar } from 'entasis/avatar';\n\n\tlet avatarRef = $state<HTMLElement | null>(null);\n\tlet open = $state(false);\n\tconst user = { name: 'John Doe', email: 'john@example.com' };\n</script>\n\n<button type=\"button\" bind:this={avatarRef} onclick={() => (open = !open)}>\n\t<Avatar name={user.name} />\n</button>\n\n<Popover bind:open ref={avatarRef} position=\"bottom\">\n\t<div class=\"p-4\">\n\t\t<h3>{user.name}</h3>\n\t\t<p>{user.email}</p>\n\t\t<Button fullWidth>View Profile</Button>\n\t</div>\n</Popover>\n```\n\n## State Management\n\nEvery slot snippet (`trigger`, `children`), `onAfterOpen` and `onAfterClose` receive a `PopoverApi` (`import type { PopoverApi } from './index.ts'`). It is a narrow handle: the class behind it stays internal, so its layers, focus scope and hover tracking can change without breaking you. `PopoverState` is a deprecated alias of `PopoverApi`, kept for one minor. It provides:\n\n- **id**: string - Popover identifier, which the open trigger's `aria-controls` points at\n- **isOpen**: boolean - Whether the popover is open\n- **status**: 'closed' | 'entering' | 'open' | 'exiting' - Where the panel is in its open/close lifecycle\n- **placement**: { side, align, anchorHidden } | null - Where the floating panel was last placed (the values of `data-side`, `data-align` and `data-anchor-hidden`); `null` until it is placed and once it unmounts\n- **open(details?)**, **close(details?)**, **toggle(details?)** - Request a change through `onOpenChange`. Each accepts the DOM event (`onclick={popover.toggle}`) or partial details (`{ reason, event, trigger }`); called while a trigger press dispatches, the change reports `reason: 'trigger-press'` and that trigger, otherwise `'imperative-action'`. `close` returns `false` when the change was cancelled. `toggle` on the trigger of a hover-opened popover pins it open; on another trigger of an open popover it moves the panel there\n- **setOpen(open, details?)**: boolean - The same request with an explicit state; returns `false` when `onOpenChange` cancelled it\n- **openReason**: 'hover' | 'press' | 'keyboard' | 'programmatic' | null - How the open popover was opened (`programmatic` covers `open()` from code, the `open` prop and `defaultOpen`)\n- **activeTrigger**: HTMLElement | null - The trigger that opened it: the panel anchors to it and focus returns to it\n- **triggerProps**: { haspopup, expanded, controls } - The trigger state in the library's semantic vocabulary, to spread on a Button; `trigger` and `reference` already write it as ARIA attributes\n- **payload**: Payload | undefined - The data of the trigger the panel is anchored to (see `triggerFor`)\n- **trigger**: attachment that makes any element the trigger (`{@attach popover.trigger}`): `reference` plus a click toggle (when `openOnClick`), and on a non-control `role=\"button\"`, `tabindex=\"0\"` and Enter/Space activation. The element's own handler runs first: when it calls `event.preventDefault()`, or `open`, `close`, `toggle` or `setOpen` during the click, the default toggle stands down, so a kept `onclick={popover.toggle}` does not toggle twice. Several elements may carry it: the one pressed opens the popover and anchors it\n- **triggerFor(() => payload)**: `trigger` plus a payload getter, read back as `payload` while that trigger anchors the panel\n- **reference**: attachment for a custom trigger element (`{@attach popover.reference}`); anchors the panel to it and keeps its `aria-haspopup`, `aria-expanded`, and `aria-controls` in sync, leaving clicks and keyboard to the element\n\n`usePopoverContext()` returns the enclosing popover's `PopoverApi`, or `null` outside one.\n\n## Accessibility\n\n- The trigger carries `aria-haspopup` (from `haspopup`), `aria-expanded`, and `aria-controls` \u2014 automatically for the built-in Button and for a snippet trigger using `{@attach popover.trigger}` or `{@attach popover.reference}`\n- `focusOnOpen` decides where focus lands on open; when the popover closes with focus inside it, focus returns to the trigger that opened it (after a programmatic open, to the element that had focus then)\n- Menus, listboxes, trees and grids (`haspopup` other than `'dialog'`) render a plain wrapper instead of an unnamed `<dialog>`; the trigger's `aria-controls` points at the role owner, which is labelled by the trigger\n- Non-modal: Tab is not contained and the page is not made inert (use Dialog for that)\n- Tab order for a dialog popup that a trigger opened (not a hover-opened one, a `ref` popover, a menu, listbox, tree or grid): the panel is portaled to the end of the page, so Tab on the open trigger moves into the panel's first control, Tab past its last control continues with the control after the trigger and closes the popover (`reason: 'focus-out'`), and Shift+Tab on its first control returns to the trigger. When nothing follows the trigger, Tab is left to the browser, so it cannot loop. A visually hidden `aria-owns` element after the trigger makes screen readers read the panel straight after it\n- Escape closes only the topmost open layer; an outside press dismisses every layer stacked above the one pressed. Popovers, menus, and dialogs share one layer stack\n- Keyboard navigation support\n\n## Notes\n\n- Popover is positioned using floating-ui, except with `inline`, where the document lays the panel out\n- Removing the trigger that opened it closes an open popover (reported through `onOpenChange(false, details)` with `reason: 'trigger-unmount'`), even when another trigger remains, and so does a `ref` element leaving the document; a trigger re-rendered as a new element keeps it open and re-anchors it. Unmounting the whole Popover reports nothing\n- `onAfterOpen` and `onAfterClose` fire exactly once per open and close, also when no transition plays (an `inline` or `defaultOpen` popover reports its open once mounted)\n- Automatically adjusts position to stay in viewport: flips, then shifts 20px inside the visual viewport, and places again once the visual viewport settles after an on-screen keyboard opens\n- Coordinates are rounded to the device pixel grid, and in right-to-left documents the panel stays beside its trigger with `start` alignment on the right\n- Multiple popovers can be stacked\n- A closed popover is cheap: its layer, focus scope, hover safe area, Tab bridge and scroll lock are built when it opens and released once its closing transition ends, so a page with many closed Selects, date inputs or row menus mounts without them. Only the trigger's listeners and ARIA attributes exist while it is closed\n- Scroll locking prevents background scroll (when enabled), except for a popover hovering opened and a touch-opened popover narrower than the viewport\n- Transitions animate based on position direction\n\n## Theme Customization\n\nThe Popover component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Open/close transition preset, keyed by `mode` (a floating panel scales, the mobile\n  sheet slides up). Takes `in` / `out` FSO params plus a `duration` / `easing` motion token;\n  the `transition` prop wins over it\n- **popover**: Main popover container styles\n- **arrow**: The arrow (`arrow` prop): a rotated square in the panel colour, absolutely positioned inside the panel behind its content (`-z-10`); its position is written inline by the placement\n\n### Theme Type Definition\n\n```typescript\nimport type { PopoverThemeProps } from 'entasis/popover';\n\n// Example theme customization\nconst customTheme: PopoverThemeProps = {\n  popover: {\n    base: 'z-[+50] fixed bg-surface-floating text-neutral w-fit rounded-xl raised isolate h-fit',\n    size: {\n      small: 'max-w-3xs w-full p-2',\n      normal: 'max-w-xs w-full p-3',\n      large: 'max-w-sm w-full p-4'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**popover**:\n- base: Base classes applied to all popovers\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls max-width, width, and padding\n  - mode: 'floating' | 'inline' | 'mobileSheet' - Set from `inline` / `mobileSheet`; `root` positions the wrapper (fixed, in flow, or full-screen sheet)\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Popover \n  trigger={{ content: \"Click Me\" }}\n  theme={{\n    popover: {\n      base: 'rounded-xl lift-5 border-2 border-primary',\n      size: {\n        normal: 'max-w-md p-4'\n      }\n    }\n  }}\n>\n  Custom styled popover content\n</Popover>\n```\n\n**Size Customization**:\n```svelte\n<Popover \n  size=\"large\"\n  trigger={{ content: \"Large Popover\" }}\n  theme={{\n    popover: {\n      size: {\n        large: 'max-w-lg p-6'\n      }\n    }\n  }}\n>\n  Large popover with more padding\n</Popover>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setPopoverTheme } from './index.ts';\n  \n  setPopoverTheme({\n    popover: {\n      base: 'rounded-lg lift-5 backdrop-blur-sm bg-white/95',\n      size: {\n        normal: 'max-w-sm p-4'\n      }\n    }\n  });\n</script>\n```\n";

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

@@ -25,44 +25,55 @@ The Popover component displays floating content positioned relative to a trigger
 - **id**: string - Unique identifier
 
 ### Layout Props
-- **position**: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' (default: 'bottom')
-  - Determines where popover appears relative to trigger
+- **position**: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' | 'inline-start' | 'inline-end' | 'inline-start-start' | 'inline-start-end' | 'inline-end-start' | 'inline-end-end' (default: 'top'; responsive values allowed)
+  - Determines where popover appears relative to trigger. The panel flips to the opposite side when the preferred one has no room, and shifts back inside the viewport (20px from its edges)
+  - \`inline-start\` / \`inline-end\` are logical sides: left / right in a left-to-right document, right / left in a right-to-left one (the i18n direction context, else the trigger's computed \`direction\`). The \`start\` / \`end\` alignment of \`top\` and \`bottom\` already follows the reading direction
+- **collisionBoundary**: 'visualViewport' | 'layoutViewport' (default: 'visualViewport') - The viewport the panel is shifted back into. The visual viewport is the visible area: it shrinks under an on-screen keyboard and follows pinch-zoom. \`'layoutViewport'\` ignores pinch-zoom so panning a zoomed page doesn't drag the panel along; flipping and \`--available-*\` still use the visual viewport. ContextMenu uses \`'layoutViewport'\`
+- **fallbackAxisSide**: 'start' | 'end' | 'none' (default: 'none') - When the panel fits neither on its side nor the opposite one, also try the perpendicular sides: \`'end'\` tries bottom (or the inline end) first, \`'start'\` top (or the inline start). A panel placed beside its reference (left or right) tries only the side asked for, so it never jumps over the reference's own row and menu. Submenus use \`'end'\`, so a submenu with no room beside its menu opens below its row, sliding back into the viewport if that is still too tight
+- **anchorTo**: 'box' | 'line' (default: 'box') - What the panel anchors to when its trigger wraps across lines (a link in prose): the whole bounding box, or the line the pointer was on when the panel opened, kept while it stays open. A keyboard open takes the first line above the trigger and the last one below it
 - **offset**: number - Distance in pixels from the reference element
-- **fitTrigger**: boolean (default: false) - Whether popover should match the width of the trigger element
+- **fitTrigger**: boolean (default: false) - Whether popover should match the width of the trigger element (the trigger width snapped to the device pixel grid, also published as \`--anchor-width\`)
 - **positionPanel**: ({ panel, reference }) => { x: number; y: number; minWidth?: number } | null - Place the panel yourself instead of floating-ui: return its viewport coordinates (the panel is \`position: fixed\`) and optionally a \`minWidth\` in px that replaces \`fitTrigger\`'s, or \`null\` to fall back to \`position\`. Called when the panel mounts and whenever floating-ui would reposition it. Select uses it to open over its trigger
 - **mobileSheet**: boolean (default: false) - On mobile viewports (<768px), render as a bottom sheet instead of an anchored floating panel
 - **inline**: boolean (default: false) - Render the panel in normal document flow where the component sits instead of portaling to the viewport-fixed layer: no floating-ui positioning, no scroll lock, no outside-press dismissal (Escape still closes it). Same panel classes and motion, and the trigger still toggles it. Wins over \`mobileSheet\`
 - **mobileSheetSizeTransition**: boolean (default: true) - Whether mobile-sheet panels animate intrinsic size changes
 
 ### Event Props
-- **onOpenChange**: (open: boolean) => void - Called once for each library-requested state change
-- **onAfterOpen**: (payload: PopoverState) => void - Called after the open transition finishes
-- **onAfterClose**: (payload: PopoverState) => void - Called after the close transition finishes
+- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before each library-requested state change, with \`details.reason\` (\`'trigger-press'\`, \`'trigger-hover'\`, \`'outside-press'\`, \`'escape-key'\`, \`'item-press'\`, \`'trigger-unmount'\`, \`'imperative-action'\`…), \`details.event\`, \`details.trigger\`, \`details.interaction\` and \`details.cancel()\`. Cancelling keeps the popover as it is and leaves the event untouched (a cancelled Escape is not \`defaultPrevented\`). Inside the callback \`open\` still holds the previous state. Types from \`entasis/types\`
+- **onAfterOpen**: (payload: PopoverApi<Payload>) => void - Called once per open after the open transition finishes, right away when none plays (\`defaultOpen\`, \`inline\`)
+- **onAfterClose**: (payload: PopoverApi<Payload>) => void - Called once per close after the close transition finishes
 
 ### Slot Props
-- **children**: Snippet<[PopoverState]> - Popover content
-- **trigger**: Snippet<[PopoverState]> | (ButtonProps & { content?: string }) | false - Trigger element
+- **children**: Snippet<[PopoverApi<Payload>]> - Popover content. \`Payload\` is inferred from the type you give the snippet parameter (\`PopoverApi<Person>\`) and defaults to \`unknown\`
+- **trigger**: Snippet<[PopoverApi<Payload>]> | (ButtonProps & { content?: string }) | false - Trigger element
   - Pass a snippet function for custom trigger: \`{#snippet trigger(popover)}...</snippet>\`. Put
     \`{@attach popover.trigger}\` on any element (a card, an avatar, a Button) and it opens the
     panel on click and from the keyboard, with the ARIA state kept in sync. Type the parameter
-    with \`PopoverState\` from \`entasis/popover\`.
+    with \`PopoverApi\` from \`entasis/popover\`.
   - Pass button props object for default button: \`trigger={{ content: "Click Me", color: "primary" }}\`.
     \`children\` (a string or a snippet) replaces \`content\` for a richer body; \`prefix\` and
     \`suffix\` work as on Button.
   - Pass \`false\` to disable trigger (use with external ref)
 
 ### Interaction Props
-- **openOnHover**: boolean (default: false) - Open on mouse hover
+- **openOnHover**: boolean (default: false) - Open on mouse hover, after \`delay\`. Works whether the popover started closed or open (\`defaultOpen\`): once closed, hovering the trigger opens it again. A hover-opened popover does not lock page scroll, and pressing its trigger pins it open instead of closing it. Touch taps and disabled triggers (\`disabled\`, \`aria-disabled="true"\`, \`data-disabled\`) never hover-open it, a pending open needs the pointer still on the trigger when the delay ends, and a trigger that appears under a resting pointer (a menu reopened from the keyboard) waits for the pointer to move. Right after another hover popover, tooltip or hover card was open (within 400 ms), a root popover opens without the delay; submenus keep theirs
 - **openOnClick**: boolean (default: true) - Open on click
-- **delay**: number (default: 100) - Delay in ms before opening on hover
+- **delay**: number (default: 100) - Delay in ms before opening on hover; leaving the trigger before it elapses cancels the open, and so does any other open-state change meanwhile (a click that opens and closes it, Escape), so a pending hover never reopens a popover the user just closed
 - **closeOnEscape**: boolean (default: true) - Close on Escape. Only the topmost open layer closes, so Escape inside a nested popover leaves its parent open
-- **closeOnClickOutside**: boolean (default: true) - Close on an outside press. A press dismisses this popover and every layer stacked above it, but never the layer that was pressed
-- **closeOnMouseLeave**: boolean (default: false) - Close when the pointer leaves the hover safe area. The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open.
+- **closeOnClickOutside**: boolean (default: true) - Close on an outside press. A press dismisses this popover and every layer stacked above it, but never the layer that was pressed. A press that began before the popover opened does not count, and on a touch screen only a tap does: a finger that starts scrolling the page leaves it open
+- **closeOnMouseLeave**: boolean (default: false) - Close a popover that hovering opened when the pointer leaves the hover safe area (\`reason: 'trigger-hover'\`). The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open. A popover opened by a press, the keyboard or code stays open.
+- **closeDelay**: number (default: 120) - Milliseconds the pointer may spend outside the hover safe area before \`closeOnMouseLeave\` closes the popover; a longer delay forgives a pointer that overshoots on its way to the panel
 - **debugSafeArea**: boolean (default: false) - Show hover safe-area overlays. Trigger/panel rectangles render in blue; the prediction cone toward the panel renders in orange.
 
 ### Focus & ARIA Props
-- **focusOnOpen**: 'first' | 'container' | false (default: false) - Where focus goes when the panel opens: \`'first'\` moves it to an \`[autofocus]\` / \`[data-autofocus]\` target or the first tabbable control, \`'container'\` focuses the panel itself, \`false\` keeps it on the trigger. Focus always returns to the trigger when the popover closes (Escape or outside press)
-- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true (default: 'dialog') - Value of \`aria-haspopup\` on the trigger, describing what the panel contains. \`aria-expanded\` and \`aria-controls\` are managed automatically alongside it, for the built-in Button trigger and for a snippet trigger using \`{@attach popover.reference}\`
+- **focusOnOpen**: 'first' | 'container' | false (default: false) - Where focus goes when the panel opens: \`'first'\` moves it to an \`[autofocus]\` / \`[data-autofocus]\` target or the first tabbable control, \`'container'\` focuses the panel itself, \`false\` keeps it on the trigger. When the popover closes with focus inside it, focus returns to the trigger that opened it (or the control pressed inside a wrapper trigger), and after a programmatic open to the element that had focus when it opened
+- **focusOnClose**: boolean | HTMLElement | ((details) => HTMLElement | boolean | void) (default: true) - Where focus goes when the popover closes with focus inside it or after a trigger opened it. \`true\` returns it to the trigger (a visible focus ring after Escape or another keyboard close), else to the most recent element still on the page; \`false\` leaves focus alone; an element receives it; a function gets the change details and returns one of these, or nothing to restore as usual. A close because focus moved on (\`'focus-out'\`) never moves it
+- **label**: string - The popup's accessible name, written as \`aria-label\` on the \`<dialog>\` (on the element with the menu, listbox, tree or grid role inside a non-dialog popup unless it has a name of its own, and on the mobile sheet's dialog). A popover that holds a form or a picker is announced as a dialog: name it
+- **labelledBy**: string - The id of an element that names the popup, written as \`aria-labelledby\` where \`label\` goes
+- **modal**: boolean (default: false) - Makes a floating popover modal: Tab stays inside the panel (wrapping from the last control to the first), the rest of the page becomes \`inert\`, the panel opens with focus inside it (\`focusOnOpen\` defaults to \`'first'\`), the layer counts as modal for Android Back and touch dismissal, and a visually hidden Close button at the end of the panel (out of the Tab order, \`reason: 'close-press'\`) gives screen reader users a control that closes it. A modal popover does not open on hover, and an \`inline\` panel ignores it. The mobile sheet is always modal
+- **tabBridge**: boolean (default: true) - Tab on the open trigger enters the portaled panel, Tab past its last control continues after the trigger and closes the panel (\`reason: 'focus-out'\`), and Shift+Tab on its first control returns to the trigger; a screen reader finds the panel straight after the trigger through \`aria-owns\`. Applies to dialog popups opened from a trigger. Menus, listboxes and the like (\`haspopup\`), modal popovers, \`ref\`-anchored panels and panels a hover opened manage Tab themselves; set \`false\` for a panel that is not meant to be tabbed into (the tooltip surface does). A trigger that is a text field (a date, color or phone input) is never bridged: Tab there moves on to the next field
+- **closeOnFocusOut**: boolean (default: the value of \`closeOnClickOutside\`) - Close (\`reason: 'focus-out'\`) when focus that was inside the popover or on its trigger moves to a control outside both and outside any popup opened from them. Focus that never entered is left to outside presses, and focus that moved on is not taken back. Does not apply to menus, lists, modal popovers or a popover the pointer opened by hovering
+- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true (default: 'dialog') - Value of \`aria-haspopup\` on the trigger, describing what the panel contains. \`aria-expanded\` and \`aria-controls\` are managed automatically alongside it, for the built-in Button trigger and for a snippet trigger using \`{@attach popover.reference}\`. A \`'dialog'\` popup renders in a \`<dialog>\`; any other value renders a plain \`<div>\` wrapper, points \`aria-controls\` at the element inside with the matching role (\`role="menu"\` for \`menu\` and \`true\`) and labels that element by the trigger (\`aria-labelledby\`) unless it has an \`aria-label\`
 
 \`\`\`svelte
 <script>
@@ -79,16 +90,60 @@ The Popover component displays floating content positioned relative to a trigger
   - small: Compact popover size
   - normal: Standard popover size
   - large: Larger popover size
+- **arrow**: boolean (default: false) - Draws an arrow from a floating panel toward its trigger, inside the panel behind its content. It is placed by floating-ui's \`arrow\` middleware after \`shift\`, so it keeps pointing at the trigger when the panel slides to fit the viewport, stays 10px from the panel's corners, and writes \`data-side\` (the physical side it sits on) and \`data-uncentered\` (the trigger is not under the middle of the panel). Style it with \`theme.arrow\`; it takes the panel colour (\`bg-surface-floating\`)
 - **transition**: TransitionConfig - Custom transition animation
 - **directedTransition**: boolean (default: true) - Transition direction follows position
 
 ### Behavior Props
-- **lockScroll**: boolean (default: true) - Lock body scroll when open
+- **lockScroll**: boolean (default: true) - Lock page scroll while a root-level popover is open, unless hovering opened it, or a finger did and the panel is more than 20px narrower than the viewport (a touch popover the page can still scroll under stays unlocked). The lock is the \`data-entasis-scroll-lock\` attribute on \`<html>\`; \`--entasis-scrollbar-width\` holds the hidden scrollbar's width for fixed bars
 
 ### Styling Props
 - **class**: string - Additional CSS classes
 - **theme**: ComponentTheme - Custom theme overrides
 
+## Styling hooks
+
+A floating panel is placed before it shows: it stays hidden until its first placement lands, and \`focusOnOpen\` waits for that placement too. Every placement (scroll, resize, a flip, the end of the opening transition, and the visual viewport settling after an on-screen keyboard) updates these hooks.
+
+**Data attributes** (presence attributes unless they carry a value)
+- \`data-open\`: On the panel: present while open.
+- \`data-closed\`: On the panel: present while its exit transition plays (a closed panel is not rendered).
+- \`data-entering\`: On the panel: present while the enter transition plays.
+- \`data-exiting\`: On the panel: present while the exit transition plays.
+- \`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.
+- \`data-align\`: On the panel: \`start\`, \`center\` or \`end\`, how it lines up with the trigger (absent with \`data-side="none"\`).
+- \`data-anchor-hidden\`: On the panel: present while the trigger is scrolled out of view; the panel is hidden meanwhile.
+- \`data-uncentered\`: On the arrow: present while the trigger is not under the middle of the panel (a shift moved the panel).
+- \`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.
+- \`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.
+
+**CSS variables** (set on the positioned wrapper, inherited by the panel and its content)
+- \`--available-width\`: The width in px the panel can take before it reaches the viewport edges, minus 20px.
+- \`--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))\`.
+- \`--anchor-width\`: The trigger's width in px, snapped to the device pixel grid.
+- \`--anchor-height\`: The trigger's height in px, snapped to the device pixel grid.
+- \`--transform-origin\`: The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.
+
+The typed maps \`popoverDataAttributes\` and \`popoverCssVariables\` (from \`entasis/popover\`) list each name with its meaning. Select, Combobox, Menu, PopupMenu, HoverCard and Tooltip are built on Popover and carry the same panel hooks.
+
+\`\`\`svelte
+<script>
+	import { Popover } from './index.ts';
+</script>
+
+<!-- Square the corner that touches the trigger, whichever side the panel lands on -->
+<Popover
+	position="bottom-start"
+	class="data-[side=bottom]:rounded-t-none data-[side=top]:rounded-b-none"
+	trigger={{ content: 'Open' }}
+>
+	Attached panel
+</Popover>
+
+<!-- Opens on the reading direction's end side: right in English, left in Arabic -->
+<Popover position="inline-end" trigger={{ content: 'Details' }}>Details</Popover>
+\`\`\`
+
 ## Structure
 
 \`\`\`
@@ -128,12 +183,12 @@ activation:
 
 \`\`\`svelte
 <script lang="ts">
-	import { Popover, type PopoverState } from './index.ts';
+	import { Popover, type PopoverApi } from './index.ts';
 	import { Avatar } from '../Avatar/index.ts';
 </script>
 
 <Popover>
-	{#snippet trigger(popover: PopoverState)}
+	{#snippet trigger(popover: PopoverApi)}
 		<div class="flex items-center gap-sm" {@attach popover.trigger}>
 			<Avatar name="Ada Lovelace" />
 			<span>Ada Lovelace</span>
@@ -144,6 +199,41 @@ activation:
 </Popover>
 \`\`\`
 
+### One popup for many triggers
+
+A list of rows needs one Popover, not one per row. \`popover.triggerFor(() => row)\` is \`popover.trigger\` plus a payload getter: the popup moves to the trigger that was pressed (pressing another trigger while it is open moves it there and keeps it open), and \`popover.payload\` is that trigger's data, read live. Pass a getter, not the value, so the payload follows its source without the trigger being removed and re-attached (which would close the popover).
+
+\`\`\`svelte
+<script lang="ts">
+	import { Popover, type PopoverApi } from './index.ts';
+	import { Button } from '../Button/index.ts';
+
+	type Person = { id: number; name: string; role: string };
+	let { people }: { people: Person[] } = $props();
+</script>
+
+<Popover position="bottom" arrow>
+	{#snippet trigger(popover: PopoverApi<Person>)}
+		{#each people as person (person.id)}
+			<Button {@attach popover.triggerFor(() => person)}>{person.name}</Button>
+		{/each}
+	{/snippet}
+	{#snippet children(popover: PopoverApi<Person>)}
+		<strong>{popover.payload?.name}</strong>
+		<p>{popover.payload?.role}</p>
+	{/snippet}
+</Popover>
+\`\`\`
+
+### Modal and named
+
+\`\`\`svelte
+<Popover modal label="Delivery options" trigger={{ content: 'Delivery options' }}>
+	<fieldset>...</fieldset>
+	<Button>Save</Button>
+</Popover>
+\`\`\`
+
 ### With button props
 \`\`\`svelte
 <script>
@@ -338,6 +428,35 @@ activation:
 </Popover>
 \`\`\`
 
+### Keep it open with onOpenChange
+
+\`\`\`svelte
+<script lang="ts">
+	import { Popover } from './index.ts';
+	import type { OpenChangeDetails } from '../../types/index.ts';
+
+	let note = $state('');
+	// Runs before the change: an outside press or Escape keeps a popover with an unsaved note.
+	const keepNote = (open: boolean, details: OpenChangeDetails) => {
+		const dismissal = details.reason === 'outside-press' || details.reason === 'escape-key';
+		if (!open && dismissal && note) details.cancel();
+	};
+</script>
+
+<Popover trigger={{ content: 'Add a note' }} focusOnOpen="first" onOpenChange={keepNote}>
+	{#snippet children(popover)}
+		<textarea aria-label="Note" bind:value={note}></textarea>
+		<button
+			type="button"
+			onclick={() => {
+				note = '';
+				popover.close();
+			}}>Discard</button
+		>
+	{/snippet}
+</Popover>
+\`\`\`
+
 ### User Card Popover with External Ref
 
 \`\`\`svelte
@@ -366,32 +485,44 @@ activation:
 
 ## State Management
 
-The Popover component uses a \`PopoverState\` instance that is passed to all slot snippets. This state object provides:
-
-- **id**: string - Popover identifier
-- **size**: Size - Current popover size
-- **position**: Placement - Current popover position
-- **offset**: number - Current offset value
-- **open()**: () => void - Method to open the popover
-- **close()**: () => void - Method to close the popover
-- **toggle()**: () => void - Method to toggle the popover
-- **trigger**: attachment that makes any element the trigger (\`{@attach popover.trigger}\`): \`reference\` plus a click toggle (when \`openOnClick\`), and on a non-control \`role="button"\`, \`tabindex="0"\` and Enter/Space activation. The element's own handler wins: when it calls \`open\`, \`close\`, \`toggle\` or \`setOpen\` during the click, the default toggle stands down, so a kept \`onclick={popover.toggle}\` does not toggle twice
+Every slot snippet (\`trigger\`, \`children\`), \`onAfterOpen\` and \`onAfterClose\` receive a \`PopoverApi\` (\`import type { PopoverApi } from './index.ts'\`). It is a narrow handle: the class behind it stays internal, so its layers, focus scope and hover tracking can change without breaking you. \`PopoverState\` is a deprecated alias of \`PopoverApi\`, kept for one minor. It provides:
+
+- **id**: string - Popover identifier, which the open trigger's \`aria-controls\` points at
+- **isOpen**: boolean - Whether the popover is open
+- **status**: 'closed' | 'entering' | 'open' | 'exiting' - Where the panel is in its open/close lifecycle
+- **placement**: { side, align, anchorHidden } | null - Where the floating panel was last placed (the values of \`data-side\`, \`data-align\` and \`data-anchor-hidden\`); \`null\` until it is placed and once it unmounts
+- **open(details?)**, **close(details?)**, **toggle(details?)** - Request a change through \`onOpenChange\`. Each accepts the DOM event (\`onclick={popover.toggle}\`) or partial details (\`{ reason, event, trigger }\`); called while a trigger press dispatches, the change reports \`reason: 'trigger-press'\` and that trigger, otherwise \`'imperative-action'\`. \`close\` returns \`false\` when the change was cancelled. \`toggle\` on the trigger of a hover-opened popover pins it open; on another trigger of an open popover it moves the panel there
+- **setOpen(open, details?)**: boolean - The same request with an explicit state; returns \`false\` when \`onOpenChange\` cancelled it
+- **openReason**: 'hover' | 'press' | 'keyboard' | 'programmatic' | null - How the open popover was opened (\`programmatic\` covers \`open()\` from code, the \`open\` prop and \`defaultOpen\`)
+- **activeTrigger**: HTMLElement | null - The trigger that opened it: the panel anchors to it and focus returns to it
+- **triggerProps**: { haspopup, expanded, controls } - The trigger state in the library's semantic vocabulary, to spread on a Button; \`trigger\` and \`reference\` already write it as ARIA attributes
+- **payload**: Payload | undefined - The data of the trigger the panel is anchored to (see \`triggerFor\`)
+- **trigger**: attachment that makes any element the trigger (\`{@attach popover.trigger}\`): \`reference\` plus a click toggle (when \`openOnClick\`), and on a non-control \`role="button"\`, \`tabindex="0"\` and Enter/Space activation. The element's own handler runs first: when it calls \`event.preventDefault()\`, or \`open\`, \`close\`, \`toggle\` or \`setOpen\` during the click, the default toggle stands down, so a kept \`onclick={popover.toggle}\` does not toggle twice. Several elements may carry it: the one pressed opens the popover and anchors it
+- **triggerFor(() => payload)**: \`trigger\` plus a payload getter, read back as \`payload\` while that trigger anchors the panel
 - **reference**: attachment for a custom trigger element (\`{@attach popover.reference}\`); anchors the panel to it and keeps its \`aria-haspopup\`, \`aria-expanded\`, and \`aria-controls\` in sync, leaving clicks and keyboard to the element
 
+\`usePopoverContext()\` returns the enclosing popover's \`PopoverApi\`, or \`null\` outside one.
+
 ## Accessibility
 
 - The trigger carries \`aria-haspopup\` (from \`haspopup\`), \`aria-expanded\`, and \`aria-controls\` — automatically for the built-in Button and for a snippet trigger using \`{@attach popover.trigger}\` or \`{@attach popover.reference}\`
-- \`focusOnOpen\` decides where focus lands on open; focus returns to the trigger on close, whether by Escape or an outside press
+- \`focusOnOpen\` decides where focus lands on open; when the popover closes with focus inside it, focus returns to the trigger that opened it (after a programmatic open, to the element that had focus then)
+- Menus, listboxes, trees and grids (\`haspopup\` other than \`'dialog'\`) render a plain wrapper instead of an unnamed \`<dialog>\`; the trigger's \`aria-controls\` points at the role owner, which is labelled by the trigger
 - Non-modal: Tab is not contained and the page is not made inert (use Dialog for that)
+- Tab order for a dialog popup that a trigger opened (not a hover-opened one, a \`ref\` popover, a menu, listbox, tree or grid): the panel is portaled to the end of the page, so Tab on the open trigger moves into the panel's first control, Tab past its last control continues with the control after the trigger and closes the popover (\`reason: 'focus-out'\`), and Shift+Tab on its first control returns to the trigger. When nothing follows the trigger, Tab is left to the browser, so it cannot loop. A visually hidden \`aria-owns\` element after the trigger makes screen readers read the panel straight after it
 - Escape closes only the topmost open layer; an outside press dismisses every layer stacked above the one pressed. Popovers, menus, and dialogs share one layer stack
 - Keyboard navigation support
 
 ## Notes
 
 - Popover is positioned using floating-ui, except with \`inline\`, where the document lays the panel out
-- Automatically adjusts position to stay in viewport
+- Removing the trigger that opened it closes an open popover (reported through \`onOpenChange(false, details)\` with \`reason: 'trigger-unmount'\`), even when another trigger remains, and so does a \`ref\` element leaving the document; a trigger re-rendered as a new element keeps it open and re-anchors it. Unmounting the whole Popover reports nothing
+- \`onAfterOpen\` and \`onAfterClose\` fire exactly once per open and close, also when no transition plays (an \`inline\` or \`defaultOpen\` popover reports its open once mounted)
+- Automatically adjusts position to stay in viewport: flips, then shifts 20px inside the visual viewport, and places again once the visual viewport settles after an on-screen keyboard opens
+- Coordinates are rounded to the device pixel grid, and in right-to-left documents the panel stays beside its trigger with \`start\` alignment on the right
 - Multiple popovers can be stacked
-- Scroll locking prevents background scroll (when enabled)
+- A closed popover is cheap: its layer, focus scope, hover safe area, Tab bridge and scroll lock are built when it opens and released once its closing transition ends, so a page with many closed Selects, date inputs or row menus mounts without them. Only the trigger's listeners and ARIA attributes exist while it is closed
+- Scroll locking prevents background scroll (when enabled), except for a popover hovering opened and a touch-opened popover narrower than the viewport
 - Transitions animate based on position direction
 
 ## Theme Customization
@@ -405,6 +536,7 @@ The theme object contains the following parts:
   sheet slides up). Takes \`in\` / \`out\` FSO params plus a \`duration\` / \`easing\` motion token;
   the \`transition\` prop wins over it
 - **popover**: Main popover container styles
+- **arrow**: The arrow (\`arrow\` prop): a rotated square in the panel colour, absolutely positioned inside the panel behind its content (\`-z-10\`); its position is written inline by the placement
 
 ### Theme Type Definition