entasis 0.7.1 → 0.9.0

package/dist/components/Form/Select/select.align.d.ts

@@ -0,0 +1,55 @@
+/** Distance kept between an item-aligned panel and the viewport edges, in px. */
+export declare const SELECT_ALIGN_MARGIN = 8;
+/**
+ * Viewport measurements of an open Select, taken with the option list at its natural height and
+ * scrolled to the top. `textStart` values are the inline-start edge of the text (left in LTR,
+ * right in RTL).
+ */
+export type SelectAlignMetrics = {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    trigger: {
+        top: number;
+        height: number;
+    };
+    /** The trigger's value (or placeholder) text. */
+    valueTextStart: number;
+    panel: {
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /** The scrolling option list inside the panel. */
+    list: {
+        top: number;
+        height: number;
+    };
+    /** The option to put on the trigger: the selected one, else the first. */
+    item: {
+        top: number;
+        height: number;
+        textStart: number;
+    };
+    rtl: boolean;
+};
+export type SelectAlignment = {
+    /** Panel position, viewport coordinates. */
+    x: number;
+    y: number;
+    /** Height to cap the option list at. */
+    listHeight: number;
+    /** Scroll offset that keeps the option on the trigger. */
+    scrollTop: number;
+};
+/**
+ * Item-aligned placement, the native select's and Radix's: the panel covers the trigger with the
+ * option's middle on the trigger's middle and its text on the value text. A panel that would cross
+ * the top edge is pinned there and its list scrolled by the overflow, so the option stays on the
+ * trigger; one that would cross the bottom edge is cut short and scrolls. Only when the trigger
+ * sits so low that fewer than four rows would fit does the panel rise and give up the alignment.
+ */
+export declare function alignItemWithTrigger(m: SelectAlignMetrics): SelectAlignment;

package/dist/components/Form/Select/select.align.js

@@ -0,0 +1,41 @@
+/** Distance kept between an item-aligned panel and the viewport edges, in px. */
+export const SELECT_ALIGN_MARGIN = 8;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+/**
+ * Item-aligned placement, the native select's and Radix's: the panel covers the trigger with the
+ * option's middle on the trigger's middle and its text on the value text. A panel that would cross
+ * the top edge is pinned there and its list scrolled by the overflow, so the option stays on the
+ * trigger; one that would cross the bottom edge is cut short and scrolls. Only when the trigger
+ * sits so low that fewer than four rows would fit does the panel rise and give up the alignment.
+ */
+export function alignItemWithTrigger(m) {
+    const top = SELECT_ALIGN_MARGIN;
+    const bottom = m.viewport.height - SELECT_ALIGN_MARGIN;
+    const chromeAbove = m.list.top - m.panel.top;
+    const chromeBelow = m.panel.top + m.panel.height - (m.list.top + m.list.height);
+    const itemMiddle = m.item.top + m.item.height / 2 - m.panel.top;
+    const triggerMiddle = m.trigger.top + m.trigger.height / 2;
+    let y = triggerMiddle - itemMiddle;
+    let scrollTop = 0;
+    if (y < top) {
+        scrollTop = top - y;
+        y = top;
+    }
+    let height = Math.min(m.panel.height - scrollTop, bottom - y);
+    const minHeight = Math.min(m.panel.height, chromeAbove + chromeBelow + m.item.height * 4);
+    if (height < minHeight) {
+        height = minHeight;
+        y = Math.max(top, bottom - height);
+    }
+    const listHeight = Math.max(0, height - chromeAbove - chromeBelow);
+    scrollTop = clamp(scrollTop, 0, m.list.height - listHeight);
+    // Line the option's text up with the value's: the panel moves by the gap between them.
+    const textOffset = m.rtl ? m.panel.right - m.item.textStart : m.item.textStart - m.panel.left;
+    const x = m.rtl ? m.valueTextStart + textOffset - m.panel.width : m.valueTextStart - textOffset;
+    return {
+        x: clamp(x, SELECT_ALIGN_MARGIN, m.viewport.width - SELECT_ALIGN_MARGIN - m.panel.width),
+        y,
+        listHeight,
+        scrollTop
+    };
+}

package/dist/components/Form/Select/select.mcp.d.ts

@@ -1 +1 @@
-export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) dropdown selection field: a combobox trigger opening a listbox popover,\nwith full keyboard navigation, grouped options, and Field/Form integration.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable the trigger\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input for native form posts\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes\n- **onValidate**: (value) => string[] | boolean - Custom validation\n\n### Advanced Props\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text\n- Disabled options are skipped by the highlight\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior)\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land\n- The dropdown scrolls beyond ~240px (ScrollArea); the highlight scrolls into view on keyboard nav\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) selection field: a combobox trigger opening a listbox popover, with full\nkeyboard navigation, grouped options, and Field/Form integration. Like a native select (and\nRadix's item-aligned or Base UI's `alignItemWithTrigger` position), the listbox opens over the\ntrigger with the selected option sitting on the value.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. `false` opens a dropdown below the trigger instead, capped at ~240px\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable the trigger\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input for native form posts\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes\n- **onValidate**: (value) => string[] | boolean - Custom validation\n\n### Advanced Props\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text\n- Disabled options are skipped by the highlight\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior)\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land\n- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav\n- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";

package/dist/components/Form/Select/select.mcp.js

@@ -1,8 +1,10 @@
 export const selectDescription = `
 # Select Component
 
-A custom (non-native) dropdown selection field: a combobox trigger opening a listbox popover,
-with full keyboard navigation, grouped options, and Field/Form integration.
+A custom (non-native) selection field: a combobox trigger opening a listbox popover, with full
+keyboard navigation, grouped options, and Field/Form integration. Like a native select (and
+Radix's item-aligned or Base UI's \`alignItemWithTrigger\` position), the listbox opens over the
+trigger with the selected option sitting on the value.
 
 ## Basic Usage
 
@@ -42,6 +44,7 @@ Extends all Field component props plus:
 - **items**: (SelectOption | SelectOptionGroup)[] - Flat \`{ value, label, disabled? }\` options and/or \`{ label, items }\` groups
 - **placeholder**: string (default: 'Select an option') - Trigger text when no selection
 - **separators**: boolean (default: true) - Render separators between consecutive groups
+- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. \`false\` opens a dropdown below the trigger instead, capped at ~240px
 
 ### Field Props (inherited)
 - **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder
@@ -88,7 +91,8 @@ rather than repeating the placeholder.
 
 - Selection re-focuses the trigger (matches native select behavior)
 - Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land
-- The dropdown scrolls beyond ~240px (ScrollArea); the highlight scrolls into view on keyboard nav
+- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav
+- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select
 
 ## State contract
 

package/dist/components/Form/Select/select.props.d.ts

@@ -34,6 +34,14 @@ export type SelectProps = InputProps<'select'> & {
     density?: Density;
     /** Render separators between consecutive groups. */
     separators?: boolean;
+    /**
+     * Open over the trigger with the selected option (or the first, when nothing is selected) on
+     * the value, its text lined up with the value's, like a native select. A list taller than the
+     * viewport is capped and pre-scrolled to keep the option there. `false` opens a dropdown below
+     * the trigger instead.
+     * @default true
+     */
+    alignItemWithTrigger?: boolean;
     /** Native attributes applied to the combobox trigger button. */
     triggerAttrs?: SelectTriggerAttributes;
     /** Per-instance i18n overrides merged over the global catalog. */

package/dist/components/Form/Select/select.state.svelte.d.ts

@@ -8,13 +8,24 @@ interface SelectStateOptions {
     disabled: boolean | undefined;
     /** The trigger button — reactive getter bridged to `field.node`, refocused after selection. */
     triggerEl: HTMLElement | null;
+    /** Open over the trigger with the selected option on the value, like a native select. */
+    alignItemWithTrigger: boolean;
+    /** The trigger's value text, the option list root, and its scrolling viewport. */
+    valueEl: HTMLElement | null;
+    listEl: HTMLElement | null;
+    viewportEl: HTMLElement | null;
 }
 export declare class SelectState {
+    #private;
     id: string;
     items: SelectItems | undefined;
     value: string | null | undefined;
     disabled: boolean | undefined;
     triggerEl: HTMLElement | null;
+    alignItemWithTrigger: boolean;
+    valueEl: HTMLElement | null;
+    listEl: HTMLElement | null;
+    viewportEl: HTMLElement | null;
     isOpen: boolean;
     listboxId: string;
     /** All options, flattened across groups — render order. */
@@ -38,6 +49,19 @@ export declare class SelectState {
     };
     constructor(options: SelectStateOptions);
     optionId: (value: string) => string;
+    /**
+     * Popover `positionPanel`: places the open panel over the trigger with the selected option (or
+     * the first one) on the value, and sizes and scrolls the list to keep it there. `null` falls
+     * back to the dropdown below the trigger.
+     */
+    positionPanel: ({ panel, reference }: {
+        panel: HTMLElement;
+        reference: unknown;
+    }) => {
+        x: number;
+        y: number;
+        minWidth: number;
+    } | null;
     open: () => void;
     close: () => void;
     toggle: () => void;

package/dist/components/Form/Select/select.state.svelte.js

@@ -1,8 +1,28 @@
 import { bind } from '../../../utils/state.svelte.js';
 import { useListNavigation } from '../../../utils/useListNavigation.svelte.js';
+import { alignItemWithTrigger, SELECT_ALIGN_MARGIN } from './select.align.js';
+/** Inline-start edge of an element's first text: what lines up between the value and an option. */
+const textStart = (element, rtl) => {
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+        acceptNode: (node) => node.textContent?.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
+    });
+    const text = walker.nextNode();
+    let rect = element.getBoundingClientRect();
+    const range = text ? document.createRange() : null;
+    // Ranges without layout (jsdom) fall back to the element's own box.
+    if (range?.getBoundingClientRect) {
+        range.selectNodeContents(text);
+        rect = range.getBoundingClientRect();
+    }
+    return rtl ? rect.right : rect.left;
+};
 const isGroup = (entry) => Array.isArray(entry.items);
 export class SelectState {
     isOpen = $state(false);
+    // Where this open session placed the panel. Measured once: later repositioning (the panel
+    // resizing, the list scrolling) must not re-scroll the list under the pointer. A new viewport
+    // size measures again.
+    #alignment = null;
     listboxId = $derived.by(() => `${this.id}-listbox`);
     /** All options, flattened across groups — render order. */
     flatOptions = $derived.by(() => (this.items ?? []).flatMap((entry) => (isGroup(entry) ? entry.items : [entry])));
@@ -35,12 +55,100 @@ export class SelectState {
     });
     constructor(options) {
         bind(this, options);
+        // An item-aligned panel sits on the trigger, so the page holds still while it is open, as
+        // it does for a native select. Popover's body lock does not reach an app's own scroll
+        // container (a scrolling <main>), so wheel and touch scrolling are blocked outside the
+        // panel. The panel is portaled under the locked body: its own scrolling cannot chain out.
+        $effect(() => {
+            if (!this.isOpen || !this.alignItemWithTrigger)
+                return;
+            const block = (event) => {
+                const panel = document.getElementById(this.listboxId)?.closest('dialog');
+                if (event.target instanceof Node && panel?.contains(event.target))
+                    return;
+                event.preventDefault();
+            };
+            const listen = { capture: true, passive: false };
+            window.addEventListener('wheel', block, listen);
+            window.addEventListener('touchmove', block, listen);
+            return () => {
+                window.removeEventListener('wheel', block, listen);
+                window.removeEventListener('touchmove', block, listen);
+            };
+        });
     }
     // Index-based ids — sanitizing values into ids can collide ('a.b' and 'a_b' both → 'a_b').
     optionId = (value) => `${this.id}-option-${this.flatOptions.findIndex((o) => o.value === value)}`;
+    /**
+     * Popover `positionPanel`: places the open panel over the trigger with the selected option (or
+     * the first one) on the value, and sizes and scrolls the list to keep it there. `null` falls
+     * back to the dropdown below the trigger.
+     */
+    positionPanel = ({ panel, reference }) => {
+        const { valueEl, listEl, viewportEl } = this;
+        if (!this.alignItemWithTrigger || !valueEl || !listEl || !viewportEl)
+            return null;
+        if (!(reference instanceof HTMLElement))
+            return null;
+        const anchor = this.selectedOption && !this.selectedOption.disabled
+            ? this.selectedOption
+            : this.flatOptions.find((option) => !option.disabled);
+        const item = anchor && document.getElementById(this.optionId(anchor.value));
+        if (!item)
+            return null;
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        const kept = this.#alignment;
+        if (kept && kept.viewport.width === width && kept.viewport.height === height)
+            return kept.position;
+        // Measure the list at its natural height and scroll, the panel at least as wide as the
+        // trigger (what `fitTrigger` applies on the next render).
+        const trigger = reference.getBoundingClientRect();
+        const surface = panel.firstElementChild;
+        if (surface)
+            surface.style.minWidth = `${trigger.width}px`;
+        listEl.style.maxHeight = 'none';
+        viewportEl.scrollTop = 0;
+        const rtl = getComputedStyle(reference).direction === 'rtl';
+        const panelRect = panel.getBoundingClientRect();
+        const listRect = listEl.getBoundingClientRect();
+        const itemRect = item.getBoundingClientRect();
+        const placed = alignItemWithTrigger({
+            viewport: { width, height },
+            trigger: { top: trigger.top, height: trigger.height },
+            valueTextStart: textStart(valueEl, rtl),
+            panel: {
+                left: panelRect.left,
+                right: panelRect.right,
+                top: panelRect.top,
+                width: panelRect.width,
+                height: panelRect.height
+            },
+            list: { top: listRect.top, height: listRect.height },
+            item: { top: itemRect.top, height: itemRect.height, textStart: textStart(item, rtl) },
+            rtl
+        });
+        listEl.style.maxHeight = `${placed.listHeight}px`;
+        viewportEl.scrollTop = placed.scrollTop;
+        // Overhang the trigger on both sides. The text alignment fixes the start edge, so the panel
+        // widens at the end to match the start's overhang (at least 4px) and stays in the viewport.
+        const end = rtl ? placed.x + panelRect.width : placed.x;
+        const startOverhang = rtl ? end - trigger.right : trigger.left - placed.x;
+        const overhang = Math.max(4, startOverhang);
+        const minWidth = Math.max(panelRect.width, rtl ? end - (trigger.left - overhang) : trigger.right + overhang - placed.x);
+        const x = Math.min(Math.max(rtl ? end - minWidth : placed.x, SELECT_ALIGN_MARGIN), width - SELECT_ALIGN_MARGIN - minWidth);
+        // Popover applies `minWidth` through a style binding, which skips the write when the value
+        // matches the previous session's: put back what the measurement overwrote.
+        if (surface)
+            surface.style.minWidth = `${minWidth}px`;
+        const position = { x: Math.max(SELECT_ALIGN_MARGIN, x), y: placed.y, minWidth };
+        this.#alignment = { position, viewport: { width, height } };
+        return position;
+    };
     open = () => {
         if (this.disabled)
             return;
+        this.#alignment = null;
         this.isOpen = true;
         // Safari/Firefox-macOS don't focus buttons on click — grab focus explicitly so the
         // blur-to-close and trigger keydown paths work for mouse users everywhere.
@@ -51,8 +159,10 @@ export class SelectState {
         if (selected && !selected.disabled) {
             this.nav.setHighlighted(selected.value);
             // The dropdown mounts on the next flush — defer the scroll (setTimeout, not rAF:
-            // rAF stalls in hidden tabs).
+            // rAF stalls in hidden tabs). An item-aligned panel has already scrolled its list.
             setTimeout(() => {
+                if (this.#alignment)
+                    return;
                 document
                     .getElementById(this.optionId(selected.value))
                     ?.scrollIntoView({ block: 'nearest' });

package/dist/components/Popover/Popover.svelte

@@ -34,6 +34,7 @@
 		directedTransition = true,
 		lockScroll = true,
 		fitTrigger = false,
+		positionPanel,
 		inline = false,
 		mobileSheet = false,
 		mobileSheetSizeTransition = true,
@@ -87,6 +88,9 @@
 		get fitTrigger() {
 			return fitTrigger;
 		},
+		get positionPanel() {
+			return positionPanel;
+		},
 		get mobileSheet() {
 			return mobileSheet;
 		},

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- **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>`\n  - Pass button props object for default button: `trigger={{ content: \"Click Me\", color: \"primary\" }}`\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.reference} anchors the panel to the element and keeps\n     aria-haspopup / aria-expanded / aria-controls in sync on it -->\n<Popover>\n\t{#snippet trigger(popover)}\n\t\t<Button onclick={() => popover.toggle()} {@attach popover.reference}>Open</Button>\n\t{/snippet}\n\t\n\t<p>This is a popover!</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- **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\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.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' (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>`\n  - Pass button props object for default button: `trigger={{ content: \"Click Me\", color: \"primary\" }}`\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.reference} anchors the panel to the element and keeps\n     aria-haspopup / aria-expanded / aria-controls in sync on it -->\n<Popover>\n\t{#snippet trigger(popover)}\n\t\t<Button onclick={() => popover.toggle()} {@attach popover.reference}>Open</Button>\n\t{/snippet}\n\t\n\t<p>This is a popover!</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- **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\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.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";

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

@@ -29,6 +29,7 @@ The Popover component displays floating content positioned relative to a trigger
   - Determines where popover appears relative to trigger
 - **offset**: number - Distance in pixels from the reference element
 - **fitTrigger**: boolean (default: false) - Whether popover should match the width of the trigger element
+- **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

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

@@ -33,6 +33,22 @@ export type PopoverProps = WithAttachments<{
     ref?: HTMLElement | VirtualElement | null;
     /** Preferred placement relative to the reference element; supports responsive values. */
     position?: ResponsiveProps<Placement>;
+    /**
+     * Places 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 (scroll, resize, size changes), with the positioned panel wrapper and the
+     * reference element in one payload. Select uses it to open over its trigger with the selected
+     * option on the value.
+     */
+    positionPanel?: (payload: {
+        panel: HTMLElement;
+        reference: HTMLElement | VirtualElement;
+    }) => {
+        x: number;
+        y: number;
+        minWidth?: number;
+    } | null;
     /** When true, clicking the trigger toggles the popover open and closed. */
     openOnClick?: boolean;
     /** When true, hovering the trigger opens the popover after `delay`. */

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

@@ -2,7 +2,7 @@ import type { PopoverProps } from './popover.props.js';
 import { type Placement, type VirtualElement } from '@floating-ui/dom';
 import { type PopoverThemeProps } from './popover.theme.js';
 type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-interface PopoverOptions extends MakeRequired<Pick<PopoverProps, 'id' | 'size' | 'position' | 'transition' | 'onOpenChange' | 'offset' | 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'mobileSheet' | 'inline' | 'focusOnOpen' | 'haspopup'>, 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'inline'> {
+interface PopoverOptions extends MakeRequired<Pick<PopoverProps, 'id' | 'size' | 'position' | 'transition' | 'onOpenChange' | 'offset' | 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'mobileSheet' | 'inline' | 'focusOnOpen' | 'haspopup' | 'positionPanel'>, 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'inline'> {
     isOpen: boolean;
     externalRef?: HTMLElement | VirtualElement | null;
     fitTrigger: boolean;

package/dist/components/Popover/popover.state.svelte.js

@@ -142,6 +142,19 @@ export class PopoverState extends PopoverOptionsBase {
         if (this.fitTrigger) {
             this.triggerWidth = this.referenceElement.getBoundingClientRect().width;
         }
+        const custom = this.positionPanel?.({ panel: node, reference: this.referenceElement });
+        if (custom) {
+            if (custom.minWidth != null)
+                this.triggerWidth = custom.minWidth;
+            Object.assign(node.style, {
+                position: 'fixed',
+                left: `${custom.x}px`,
+                top: `${custom.y}px`,
+                visibility: ''
+            });
+            this.safeArea.updateAreas();
+            return;
+        }
         const { x, y, strategy, placement } = await computePosition(this.referenceElement, node, {
             strategy: 'fixed',
             placement: this.computedPosition,