entasis 0.11.0 → 0.12.0

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

@@ -1,3 +1,4 @@
 export { default as Menu } from './Menu.svelte';
-export type { MenuProps, MenuItem, MenuSubmenuMode } from './menu.props.js';
+export type { MenuProps, MenuItem, MenuItemBase, MenuButtonItem, MenuOptionItem, MenuSeparatorItem, MenuSubmenuItem, MenuCheckboxItem, MenuRadioItem, MenuRadioGroupItem, MenuGroupItem, MenuFilter, MenuFilterOptions, MenuFilterMatchItem, MenuSubmenuMode } from './menu.props.js';
 export { menuTheme, setMenuTheme, useMenuTheme, type MenuTheme, type MenuThemeProps } from './menu.theme.js';
+export { menuDataAttributes, menuCssVariables, type MenuDataAttribute, type MenuCssVariable } from './menu.attributes.js';

package/dist/components/Menu/index.js

@@ -1,2 +1,3 @@
 export { default as Menu } from './Menu.svelte';
 export { menuTheme, setMenuTheme, useMenuTheme } from './menu.theme.js';
+export { menuDataAttributes, menuCssVariables } from './menu.attributes.js';

package/dist/components/Menu/menu.attributes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The styling hooks a Menu exposes. Attributes are presence attributes (set while the state
+ * holds, omitted otherwise) unless the description says they carry a value. A popup menu
+ * (PopupMenu, ContextMenu, a submenu) is a Popover panel: it also carries `data-open`,
+ * `data-closed`, `data-entering`, `data-exiting`, `data-side` and `data-align`, and the CSS
+ * variables of `menuCssVariables`.
+ */
+export declare const menuDataAttributes: {
+    readonly 'data-highlighted': "On a row: present while the keyboard or the pointer highlights it (the roving tab stop).";
+    readonly 'data-disabled': "On a row: present while it is disabled.";
+    readonly 'data-selected': "On a checkbox, radio or option row: present while it is checked or selected.";
+    readonly 'data-popup-open': "On a submenu row: present while its submenu is open.";
+    readonly 'data-popup-side': "On a submenu row: the submenu's `data-side` while it is placed.";
+    readonly 'data-open': "On a popup menu or submenu panel: present while open.";
+    readonly 'data-closed': "On a popup menu or submenu panel: present while its exit transition plays.";
+    readonly 'data-entering': "On a popup menu or submenu panel: present while the enter transition plays.";
+    readonly 'data-exiting': "On a popup menu or submenu panel: present while the exit transition plays.";
+    readonly 'data-side': "On a popup menu or submenu panel: the side of its trigger it sits on after flipping.";
+    readonly 'data-align': "On a popup menu or submenu panel: `start`, `center` or `end`.";
+    readonly 'data-size': "On the root and the list: the resolved `size`.";
+    readonly 'data-density': "On the root and the list: the resolved `density`.";
+};
+/** The name of a Menu data attribute. */
+export type MenuDataAttribute = keyof typeof menuDataAttributes;
+/**
+ * The CSS variables a placement writes on a popup menu's or submenu's positioned wrapper, inherited
+ * by the panel and its rows: the Popover set (`popoverCssVariables`). An inline Menu has none.
+ */
+export declare const menuCssVariables: {
+    readonly '--available-width': "The width in px the panel can take before it reaches the viewport edges, minus 20px.";
+    readonly '--available-height': "The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with `max-height: min(240px, var(--available-height))`.";
+    readonly '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.";
+    readonly '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.";
+    readonly '--transform-origin': "The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.";
+};
+/** The name of a Menu CSS variable. */
+export type MenuCssVariable = keyof typeof menuCssVariables;

package/dist/components/Menu/menu.attributes.js

@@ -0,0 +1,28 @@
+import { popoverCssVariables } from '../Popover/popover.attributes.js';
+/**
+ * The styling hooks a Menu exposes. Attributes are presence attributes (set while the state
+ * holds, omitted otherwise) unless the description says they carry a value. A popup menu
+ * (PopupMenu, ContextMenu, a submenu) is a Popover panel: it also carries `data-open`,
+ * `data-closed`, `data-entering`, `data-exiting`, `data-side` and `data-align`, and the CSS
+ * variables of `menuCssVariables`.
+ */
+export const menuDataAttributes = {
+    'data-highlighted': 'On a row: present while the keyboard or the pointer highlights it (the roving tab stop).',
+    'data-disabled': 'On a row: present while it is disabled.',
+    'data-selected': 'On a checkbox, radio or option row: present while it is checked or selected.',
+    'data-popup-open': 'On a submenu row: present while its submenu is open.',
+    'data-popup-side': "On a submenu row: the submenu's `data-side` while it is placed.",
+    'data-open': 'On a popup menu or submenu panel: present while open.',
+    'data-closed': 'On a popup menu or submenu panel: present while its exit transition plays.',
+    'data-entering': 'On a popup menu or submenu panel: present while the enter transition plays.',
+    'data-exiting': 'On a popup menu or submenu panel: present while the exit transition plays.',
+    'data-side': 'On a popup menu or submenu panel: the side of its trigger it sits on after flipping.',
+    'data-align': 'On a popup menu or submenu panel: `start`, `center` or `end`.',
+    'data-size': 'On the root and the list: the resolved `size`.',
+    'data-density': 'On the root and the list: the resolved `density`.'
+};
+/**
+ * The CSS variables a placement writes on a popup menu's or submenu's positioned wrapper, inherited
+ * by the panel and its rows: the Popover set (`popoverCssVariables`). An inline Menu has none.
+ */
+export const menuCssVariables = popoverCssVariables;

package/dist/components/Menu/menu.filter.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { useNavigation } from '../../utils/useNavigation.svelte.js';
+import type { MenuFilter, MenuFilterOptions, MenuItem } from './menu.props.js';
+type Navigation = ReturnType<typeof useNavigation>;
+/** Where the search text of one menu level lives, and how a change of it is reported. */
+export type MenuSearchOptions = {
+    /** The `filter` prop. */
+    filter: () => MenuFilter | undefined;
+    /** The controlled `search` text, `undefined` when the menu is uncontrolled. */
+    search: () => string | undefined;
+    /** Writes back to a bound `search`. */
+    write: (next: string) => void;
+    defaultSearch: () => string | undefined;
+    onSearchChange: () => ((search: string) => void) | undefined;
+};
+/**
+ * The search state of a filterable menu: the field's text (controlled or not), the options of the
+ * filter, and the rows left for that text. Call during component initialisation.
+ */
+export declare const useMenuSearch: (opts: MenuSearchOptions) => {
+    /** Whether the menu has a search field. */
+    readonly enabled: boolean;
+    readonly options: MenuFilterOptions | undefined;
+    readonly search: string;
+    /** Edits the text; `onSearchChange` runs once per edit that changes it. */
+    set(next: string): void;
+    /** The rows that match the text, or all of them without a field. */
+    visible(items: readonly MenuItem[]): MenuItem[];
+};
+/** The attribute a row reports its value in, for the highlight callback. */
+export declare const HIGHLIGHT_VALUE_ATTRIBUTE = "data-menu-value";
+/**
+ * Reports the highlighted row of a menu list: its element, or `null` when none is. The list marks
+ * the row `data-highlighted` itself, whether the keyboard, the pointer or a filter moved it.
+ * Returns the cleanup.
+ */
+export declare const watchHighlight: (list: HTMLElement, report: (row: HTMLElement | null) => void) => () => void;
+/** The value a highlighted row reports: its `data-menu-value`, else its text. */
+export declare const rowValue: (row: HTMLElement | null) => string | undefined;
+/**
+ * The key handler of a menu's search field. Focus stays in the field, so ArrowUp and ArrowDown
+ * only move the highlight (`virtualFocus`), Enter presses the highlighted row, and ArrowRight at
+ * the end of the text opens a highlighted submenu while ArrowLeft at its start leaves this level.
+ */
+export declare const createSearchKeys: (options: {
+    navigation: Navigation;
+    list: () => HTMLElement | null;
+    /** Whether text direction is right-to-left, which swaps ArrowLeft and ArrowRight. */
+    rtl: () => boolean;
+    /** Leaves this menu level; returns whether there was one to leave. */
+    leave: () => boolean;
+}) => (event: KeyboardEvent) => void;
+export {};

package/dist/components/Menu/menu.filter.svelte.js

@@ -0,0 +1,143 @@
+import { createBindableValue } from '../../utils/state.svelte.js';
+import { filterMenuItems } from './menuTree.js';
+/**
+ * The search state of a filterable menu: the field's text (controlled or not), the options of the
+ * filter, and the rows left for that text. Call during component initialisation.
+ */
+export const useMenuSearch = (opts) => {
+    const state = createBindableValue(opts.search, opts.write, () => opts.defaultSearch() ?? '');
+    const config = $derived.by(() => {
+        const filter = opts.filter();
+        if (filter === undefined || filter === false)
+            return null;
+        return filter === true ? {} : filter;
+    });
+    return {
+        /** Whether the menu has a search field. */
+        get enabled() {
+            return config !== null;
+        },
+        get options() {
+            return config ?? undefined;
+        },
+        get search() {
+            return state.value;
+        },
+        /** Edits the text; `onSearchChange` runs once per edit that changes it. */
+        set(next) {
+            if (next === state.value)
+                return;
+            state.value = next;
+            opts.onSearchChange()?.(next);
+        },
+        /** The rows that match the text, or all of them without a field. */
+        visible(items) {
+            return config === null ? [...items] : filterMenuItems(items, state.value, config);
+        }
+    };
+};
+// The caret rests at the start or end of the field with nothing selected, so an arrow pointing past
+// that edge has no text left to move through. Shift+arrow extends a selection instead.
+const isCaretAtEdge = (field, edge, shift) => {
+    if (shift)
+        return false;
+    const { selectionStart, selectionEnd, value } = field;
+    if (selectionStart === null || selectionEnd === null || selectionStart !== selectionEnd) {
+        return false;
+    }
+    return edge === 'start' ? selectionStart === 0 : selectionEnd === value.length;
+};
+/** The attribute a row reports its value in, for the highlight callback. */
+export const HIGHLIGHT_VALUE_ATTRIBUTE = 'data-menu-value';
+/**
+ * Reports the highlighted row of a menu list: its element, or `null` when none is. The list marks
+ * the row `data-highlighted` itself, whether the keyboard, the pointer or a filter moved it.
+ * Returns the cleanup.
+ */
+export const watchHighlight = (list, report) => {
+    let last;
+    const read = () => {
+        const row = list.querySelector('[data-highlighted="true"]');
+        if (row === last)
+            return;
+        last = row;
+        report(row);
+    };
+    const observer = new MutationObserver(read);
+    observer.observe(list, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['data-highlighted']
+    });
+    read();
+    return () => observer.disconnect();
+};
+/** The value a highlighted row reports: its `data-menu-value`, else its text. */
+export const rowValue = (row) => {
+    if (!row)
+        return undefined;
+    return row.getAttribute(HIGHLIGHT_VALUE_ATTRIBUTE) ?? row.textContent?.trim() ?? undefined;
+};
+/**
+ * The key handler of a menu's search field. Focus stays in the field, so ArrowUp and ArrowDown
+ * only move the highlight (`virtualFocus`), Enter presses the highlighted row, and ArrowRight at
+ * the end of the text opens a highlighted submenu while ArrowLeft at its start leaves this level.
+ */
+export const createSearchKeys = (options) => {
+    const highlighted = () => options.list()?.querySelector('[data-highlighted="true"]') ?? null;
+    /** Moves the highlight one row up or down, wrapping, over rows that can take it. */
+    const move = (direction) => {
+        const { navigation } = options;
+        const count = options.list()?.querySelectorAll('[role^="menuitem"]').length ?? 0;
+        if (count === 0)
+            return;
+        const current = navigation.focusedIndex;
+        let index = current === null || current < 0 ? (direction === 1 ? -1 : count) : current;
+        for (let step = 0; step < count; step += 1) {
+            index = (index + direction + count) % count;
+            navigation.focusItem(index);
+            if (navigation.focusedIndex === index)
+                return;
+        }
+    };
+    return (event) => {
+        if (event.defaultPrevented || event.isComposing)
+            return;
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const field = event.currentTarget;
+        switch (event.key) {
+            case 'ArrowDown':
+            case 'ArrowUp':
+                event.preventDefault();
+                move(event.key === 'ArrowDown' ? 1 : -1);
+                return;
+            case 'Enter': {
+                const row = highlighted();
+                if (!row || row.getAttribute('aria-disabled') === 'true' || row.matches(':disabled'))
+                    return;
+                event.preventDefault();
+                row.click();
+                return;
+            }
+            case 'ArrowLeft':
+            case 'ArrowRight': {
+                const forward = (event.key === 'ArrowRight') !== options.rtl();
+                if (forward) {
+                    if (!isCaretAtEdge(field, 'end', event.shiftKey))
+                        return;
+                    const row = highlighted();
+                    if (typeof row?.onNext === 'function' && row.onNext() !== false)
+                        event.preventDefault();
+                    return;
+                }
+                if (!isCaretAtEdge(field, 'start', event.shiftKey))
+                    return;
+                if (options.leave())
+                    event.preventDefault();
+                return;
+            }
+        }
+    };
+};

package/dist/components/Menu/menu.mcp.d.ts

@@ -1 +1 @@
-export declare const menuDescription = "\n# Menu Component\n\nThe Menu component is a flexible container that renders an array of menu items including Buttons, MenuOptions, and Separators. It provides theme forwarding capabilities and manages vertical layout with configurable spacing.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { Menu, type MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile', prefix: userIcon },\n\t\t{ type: 'option', title: 'Settings', prefix: gearIcon },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Logout', color: 'danger', variant: 'ghost' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n\n<!-- With optional header and footer -->\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"px-2 pb-2 border-b mb-2\">\n\t\t\t<h3>Menu Title</h3>\n\t\t</div>\n\t{/snippet}\n\t{#snippet footer()}\n\t\t<div class=\"px-2 pt-2 border-t mt-2\">\n\t\t\t<p class=\"text-xs\">Footer content</p>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n## Props\n\n### Core Props\n- **items**: MenuItem[] (required)\n  - Array of menu items to render\n  - Each item must have a `type` field: 'button', 'option', or 'separator'\n  - Items are spread with their respective component props\n\n- **class**: string - Additional CSS classes for the menu container\n\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density: controls the gap between rows and is forwarded to every MenuOption row (option, submenu trigger, back control); a per-item `density` wins. Items of type 'button' render a Button, which has no density axis and is unaffected.\n\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Type/icon scale of every MenuOption row; a per-item `size` wins. Items of type 'button' are unaffected.\n\n- **color**: Colors - Role every MenuOption row follows unless the item names its own `color`. Left undefined, each row keeps the MenuOption default.\n\nAll three axes (`density`, `size`, `color`) are inherited by submenus: a submenu is the same menu one level down and opens on the axes its parent was given.\n\n- **header**: Snippet - Optional header content rendered at the top of the menu\n\n- **footer**: Snippet - Optional footer content rendered at the bottom of the menu\n\n- **theme**: MenuThemeProps - Custom theme overrides\n  - menu: Theme for the container (gap spacing, layout)\n  - button: Theme forwarded to Button components\n  - option: Theme forwarded to MenuOption components\n  - separator: Theme forwarded to Separator components\n  - submenu: Theme forwarded to submenu MenuOption triggers\n\n- **submenuMode**: 'auto' | 'popover' | 'stack' (default: 'auto')\n  - auto: floating submenus normally, stacked views inside mobile-sheet popovers\n  - popover: always open submenus as nested PopupMenu instances\n  - stack: navigate to submenu views inside the same menu surface\n\n## MenuItem Types\n\nThe Menu accepts a discriminated union of four item types:\n\n### Button Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst buttonItem = {\n\ttype: 'button',\n\tchildren: 'Log out',\n\tvariant: 'ghost',\n\tcolor: 'danger'\n} satisfies MenuItem;\n```\n\n### MenuOption Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst optionItem = {\n\ttype: 'option',\n\ttitle: 'Profile',\n\tdescription: 'Manage your account',\n\thref: '/profile'\n} satisfies MenuItem;\n```\n\n### Separator Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst separatorItem = {\n\ttype: 'separator',\n\tcolor: 'neutral',\n\tdecorative: true\n} satisfies MenuItem;\n```\n\n### Submenu Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst submenuItem = {\n\ttype: 'submenu',\n\ttitle: 'Settings',\n\tmenu: [\n\t\t{ type: 'option', title: 'General' },\n\t\t{ type: 'option', title: 'Privacy' }\n\t],\n\topenOnHover: true,\n\tdelay: 100\n} satisfies MenuItem;\n```\n\n## Structure\n\nThe menu follows this DOM structure:\n```\n<Menu>\n\t<div role=\"menu\">\n\t\t<!-- Items rendered based on type -->\n\t\t<Button />\n\t\t<MenuOption />\n\t\t<Separator />\n\t\t<!-- ... -->\n\t</div>\n</Menu>\n```\n\n## Examples\n\n### Simple Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { fileIcon } from 'entasis/icons/file';\n\timport { folderIcon } from 'entasis/icons/folder';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File', prefix: fileIcon },\n\t\t{ type: 'option', title: 'Open...', prefix: folderIcon },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Exit', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Buttons\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'button', children: 'Save', variant: 'solid', color: 'primary' },\n\t\t{ type: 'button', children: 'Cancel', variant: 'ghost' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Descriptions\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { starIcon } from 'entasis/icons/star';\n\timport { checkIcon } from 'entasis/icons/check';\n\timport { buildingIcon } from 'entasis/icons/building';\n\n\tconst items = [\n\t\t{ \n\t\t\ttype: 'option',\n\t\t\ttitle: 'Pro Plan',\n\t\t\tdescription: 'For growing teams',\n\t\t\tprefix: starIcon,\n\t\t\tsuffix: checkIcon\n\t\t},\n\t\t{ \n\t\t\ttype: 'option',\n\t\t\ttitle: 'Enterprise',\n\t\t\tdescription: 'For large organizations',\n\t\t\tprefix: buildingIcon\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Event Handlers\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tfunction handleProfile() {\n\t\tconsole.log('Profile clicked');\n\t}\n\t\n\tfunction handleLogout() {\n\t\tconsole.log('Logout clicked');\n\t}\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile', onclick: handleProfile },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Logout', onclick: handleLogout, color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Custom Theme\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst customTheme = {\n\t\troot: {\n\t\t\tbase: 'gap-3' // More spacing between items\n\t\t},\n\t\toption: {\n\t\t\troot: {\n\t\t\t\tbase: 'px-4 py-3'\n\t\t\t}\n\t\t}\n\t};\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{ type: 'option', title: 'Option 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} theme={customTheme} />\n```\n\n### Menu with Links\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Dashboard', href: '/dashboard' },\n\t\t{ type: 'option', title: 'Profile', href: '/profile' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'External Link', href: 'https://example.com', target: '_blank' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { gearIcon } from 'entasis/icons/gear';\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Dashboard' },\n\t\t{ type: 'option', title: 'Profile' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\tprefix: gearIcon,\n\t\t\ttitle: 'Settings',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'General' },\n\t\t\t\t{ type: 'option', title: 'Privacy' },\n\t\t\t\t{ type: 'option', title: 'Security' }\n\t\t\t]\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Stacked Submenus\n```svelte\n<Menu {items} submenuMode=\"stack\" />\n```\n\n### Nested Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Recent Files',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'document.txt' },\n\t\t\t\t{ type: 'option', title: 'project.js' },\n\t\t\t\t{\n\t\t\t\t\ttype: 'submenu',\n\t\t\t\t\ttitle: 'More',\n\t\t\t\t\tmenu: [\n\t\t\t\t\t\t{ type: 'option', title: 'file1.txt' },\n\t\t\t\t\t\t{ type: 'option', title: 'file2.txt' }\n\t\t\t\t\t]\n\t\t\t\t}\n\t\t\t]\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Save' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Submenu with Custom Trigger Behavior\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Click Only',\n\t\t\topenOnHover: false,\n\t\t\topenOnClick: true,\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Hover with Delay',\n\t\t\topenOnHover: true,\n\t\t\tdelay: 500,\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Header\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile' },\n\t\t{ type: 'option', title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"border-b pb-2 mb-2\">\n\t\t\t<h3 class=\"text-sm font-semibold px-2\">User Menu</h3>\n\t\t\t<p class=\"text-xs text-gray-500 px-2\">Manage your account</p>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Menu with Footer\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Item 1' },\n\t\t{ type: 'option', title: 'Item 2' },\n\t\t{ type: 'option', title: 'Item 3' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet footer()}\n\t\t<div class=\"border-t pt-2 mt-2\">\n\t\t\t<div class=\"text-xs text-gray-500 px-2\">Version 1.0.0</div>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Menu with Header and Footer\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\n\tconst items = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"border-b pb-2 mb-2\">\n\t\t\t<div class=\"flex items-center gap-2 px-2\">\n\t\t\t\t<div class=\"w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white\">\n\t\t\t\t\tJD\n\t\t\t\t</div>\n\t\t\t\t<div>\n\t\t\t\t\t<div class=\"text-sm font-semibold\">John Doe</div>\n\t\t\t\t\t<div class=\"text-xs text-gray-500\">john@example.com</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</div>\n\t{/snippet}\n\t{#snippet footer()}\n\t\t<div class=\"border-t pt-2 mt-2\">\n\t\t\t<div class=\"text-xs text-gray-500 px-2 text-center\">\n\t\t\t\t<a href=\"/privacy\">Privacy</a> \u00B7 <a href=\"/terms\">Terms</a>\n\t\t\t</div>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Mixed Size Items\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Small Option', size: 'small' },\n\t\t{ type: 'option', title: 'Normal Option', size: 'normal' },\n\t\t{ type: 'option', title: 'Large Option', size: 'large' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Large Button', size: 'large', variant: 'solid' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Density\n```svelte\n<!-- density tightens/loosens the row gap and every option row's paddings.\n     Button items are unaffected (Button has no density axis). -->\n<Menu {items} density=\"compact\" />\n<Menu {items} density=\"normal\" />\n<Menu {items} density=\"comfortable\" />\n```\n\n## Accessibility\n\n- Automatically sets `role=\"menu\"` on the container\n- Option items render `role=\"menuitem\"`; an option that passes `selected` (true or false) renders `role=\"menuitemradio\"` with `aria-checked`, so a check-marked choice is announced as checked rather than as a plain command\n- ArrowUp / ArrowDown move the highlight, Home / End jump, Enter or Space activates, ArrowRight opens a submenu and ArrowLeft closes it (mirrored in RTL)\n- Type-ahead: typing letters moves the highlight to the next item whose label starts with the typed text\n- Supports keyboard navigation through child components\n- MenuOption and Button items handle interactive states\n\n## Theme Forwarding\n\nThe Menu component forwards theme props to its child components:\n- `theme.menu` - Applied to the container (gap, layout)\n- `theme.button` - Forwarded to all Button items\n- `theme.option` - Forwarded to all MenuOption items\n- `theme.separator` - Forwarded to all Separator items\n- `theme.submenu` - Forwarded to submenu MenuOption triggers\n\nThis allows for consistent styling across all menu items while maintaining flexibility for individual customization.\n\n## Submenu Behavior\n\nSubmenu items automatically:\n- Add a caret-right icon as suffix (unless custom suffix provided)\n- Open submenus positioned to the right (right-start)\n- Support hover and click triggers (configurable)\n- Manage submenu state internally using PopupMenu\n- Support nested submenus (submenus within submenus)\n\nDefault submenu behavior:\n- Opens on hover (after 100ms delay)\n- Opens on click\n- Closes when the pointer leaves the submenu prediction cone and rectangle tolerance\n- Does not close when clicking items inside (allows multi-interaction)\n\n## Notes\n\n- The Menu component is a controlled component that renders based on the items array\n- Items are distinguished by their `type` property using TypeScript discriminated unions\n- Each item type spreads its respective component props for full flexibility\n- The menu container uses minimal styling, focusing on vertical layout and spacing\n- Theme forwarding allows global styling of all items of a specific type\n\n## Theme Customization\n\nThe Menu 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- **root**: Main menu container styles\n- **button**: Theme forwarded to Button items (optional)\n- **option**: Theme forwarded to MenuOption items (optional)\n- **separator**: Theme forwarded to Separator items (optional)\n- **submenu**: Theme forwarded to submenu MenuOption triggers (optional)\n\n### Theme Type Definition\n\n```typescript\nimport type { MenuThemeProps } from 'entasis/menu';\nimport type { ButtonThemeProps } from 'entasis/button';\nimport type { MenuOptionThemeProps } from 'entasis/menu-option';\nimport type { SeparatorThemeProps } from 'entasis/separator';\n\n// Example theme customization\nconst customTheme: MenuThemeProps = {\n  root: {\n    base: 'flex flex-col w-full',\n    density: {\n      compact: 'gap-0',\n      normal: 'gap-0.5',\n      comfortable: 'gap-1'\n    }\n  },\n  button: {\n    root: {\n      base: 'w-full justify-start'\n    }\n  },\n  option: {\n    root: {\n      density: {\n        normal: 'px-3 py-2'\n      }\n    }\n  },\n  separator: {\n    root: {\n      base: 'my-2'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes for menu container\n- Variants:\n  - density: 'compact' | 'normal' | 'comfortable' - Spacing between menu items\n\n**button** (optional):\n- Forwards theme to all Button items in the menu\n- See Button component theme documentation for available variants\n\n**option** (optional):\n- Forwards theme to all MenuOption items in the menu\n- See MenuOption component theme documentation for available variants\n\n**separator** (optional):\n- Forwards theme to all Separator items in the menu\n- See Separator component theme documentation for available variants\n\n**submenu** (optional):\n- Forwards theme to submenu MenuOption triggers\n- See MenuOption component theme documentation for available variants\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Menu\n  items={menuItems}\n  theme={{\n    root: {\n      density: {\n        normal: 'gap-2'\n      }\n    }\n  }}\n/>\n```\n\n**Theme Forwarding to Child Components**:\n```svelte\n<Menu\n  items={menuItems}\n  theme={{\n    root: {\n      density: {\n        comfortable: 'gap-3'\n      }\n    },\n    option: {\n      root: {\n        density: {\n          normal: 'px-4 py-3 min-h-10'\n        },\n        color: {\n          primary: 'text-blue-600 highlight:bg-blue-50'\n        }\n      }\n    },\n    separator: {\n      root: {\n        base: 'my-3',\n\t\tcolor: {\n\t\t\tneutral: 'before:border-gray-200 after:border-gray-200'\n\t\t}\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setMenuTheme } from './index.ts';\n  import { setMenuOptionTheme } from '../MenuOption/index.ts';\n  \n  // The global menu theme covers the container parts (root, header, footer).\n  // Option rows are themed globally through MenuOption's own setter.\n  setMenuTheme({\n    root: {\n      density: {\n        normal: 'gap-2'\n      }\n    }\n  });\n  setMenuOptionTheme({\n    root: {\n      base: 'rounded-lg',\n      density: {\n        normal: 'px-3 py-2'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const menuDescription = "\n# Menu Component\n\nThe Menu component is a flexible container that renders an array of menu items: Buttons, MenuOptions, Separators, submenus, checkbox items, radio groups and labelled groups. It provides theme forwarding capabilities and manages vertical layout with configurable spacing.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { Menu, type MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile', prefix: userIcon },\n\t\t{ type: 'option', title: 'Settings', prefix: gearIcon },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Logout', color: 'danger', variant: 'ghost' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n\n<!-- With optional header and footer -->\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"px-2 pb-2 border-b mb-2\">\n\t\t\t<h3>Menu Title</h3>\n\t\t</div>\n\t{/snippet}\n\t{#snippet footer()}\n\t\t<div class=\"px-2 pt-2 border-t mt-2\">\n\t\t\t<p class=\"text-xs\">Footer content</p>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n## Props\n\n### Core Props\n- **items**: MenuItem[] (required)\n  - Array of menu items to render\n  - Each item must have a `type` field: 'button', 'option', 'separator', 'submenu', 'checkbox', 'radio-group' or 'group'\n  - Items are spread with their respective component props\n  - Every item accepts a `key`. A row keeps its DOM node, and with it focus, the Tab stop and hover state, while rows before it are inserted, removed or reordered, as long as its key stays the same. Without a `key` the identity comes from the row's plain-text title or children, its `href` or its `textValue`, so a menu built from strings needs none. A row whose text changes when it is pressed (Mute becoming Unmute) keeps its node too, as it takes over the key of the row that disappeared in the same place. Give rows whose title is a snippet, or whose text repeats, an explicit `key`\n\n- **class**: string - Additional CSS classes for the menu container\n\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density: controls the gap between rows and is forwarded to every MenuOption row (option, submenu trigger, back control); a per-item `density` wins. Items of type 'button' render a Button, which has no density axis and is unaffected.\n\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Type/icon scale of every MenuOption row; a per-item `size` wins. Items of type 'button' are unaffected.\n\n- **color**: Colors - Role every MenuOption row follows unless the item names its own `color`. Left undefined, each row keeps the MenuOption default.\n\nAll three axes (`density`, `size`, `color`) are inherited by submenus: a submenu is the same menu one level down and opens on the axes its parent was given.\n\n- **header**: Snippet - Optional header content rendered at the top of the menu, outside the `role=\"menu\"` element: a field or a link in it is not a menu item\n\n- **footer**: Snippet - Optional footer content rendered at the bottom of the menu, outside the `role=\"menu\"` element: links and buttons in it are not menu items. A PopupMenu still closes when a button or link in the footer is pressed\n\n- **focusOnMount**: boolean | 'container' | 'last' - Which part takes focus when the menu mounts: `true` the first row, `'last'` the last row, `'container'` the menu itself. A PopupMenu decides from how it opened when this is left out: a keyboard open (Enter, Space, ArrowDown, Shift+F10) highlights the first row, ArrowUp the last, a pointer open focuses the menu itself, and a hover open leaves focus where it is\n\n- **filter**: boolean | { placeholder?, label?, match? } (default: false) - Adds a search field above the rows. See Filterable menus\n\n- **search** / **defaultSearch** / **onSearchChange**: the text of the search field (bindable `search`, initial `defaultSearch`, `onSearchChange(search)` once per edit)\n\n- **onHighlightChange**: (value: string | undefined) => void - Called when the highlighted row changes (keyboard, pointer or filter), with that row's `value` (its `textValue`, or its text when that is a string); `undefined` when no row is highlighted\n\n- **empty**: Snippet - Shown in place of the rows when the search matches none of them (default: \"No results found.\")\n\n- **theme**: MenuThemeProps - Custom theme overrides\n  - menu: Theme for the container (gap spacing, layout)\n  - button: Theme forwarded to Button components\n  - option: Theme forwarded to MenuOption components\n  - separator: Theme forwarded to Separator components\n  - submenu: Theme forwarded to submenu MenuOption triggers\n\n- **submenuMode**: 'auto' | 'popover' | 'stack' (default: 'auto')\n  - auto: floating submenus normally, stacked views inside mobile-sheet popovers\n  - popover: always open submenus as nested PopupMenu instances\n  - stack: navigate to submenu views inside the same menu surface\n\n## MenuItem Types\n\nThe Menu accepts a discriminated union of seven item types:\n\n### Button Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst buttonItem = {\n\ttype: 'button',\n\tchildren: 'Log out',\n\tvariant: 'ghost',\n\tcolor: 'danger'\n} satisfies MenuItem;\n```\n\n### MenuOption Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst optionItem = {\n\ttype: 'option',\n\ttitle: 'Profile',\n\tdescription: 'Manage your account',\n\thref: '/profile'\n} satisfies MenuItem;\n```\n\n`textValue` sets the text type-ahead matches when the visible text should not count, for\nexample a row that starts with a keyboard shortcut:\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst copyItem = {\n\ttype: 'option',\n\ttitle: '\u2318C  Copy',\n\ttextValue: 'Copy'\n} satisfies MenuItem;\n```\n\n`closeOnClick` (default true) says whether pressing a button or option closes the PopupMenu it sits in; `false` marks the row `data-menu-keep-open=\"true\"`:\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst zoomIn = {\n\ttype: 'option',\n\ttitle: 'Zoom in',\n\tcloseOnClick: false\n} satisfies MenuItem;\n```\n\n### Separator Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst separatorItem = {\n\ttype: 'separator',\n\tcolor: 'neutral',\n\tdecorative: true\n} satisfies MenuItem;\n```\n\n### Submenu Item\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst submenuItem = {\n\ttype: 'submenu',\n\ttitle: 'Settings',\n\tmenu: [\n\t\t{ type: 'option', title: 'General' },\n\t\t{ type: 'option', title: 'Privacy' }\n\t],\n\topenOnHover: true,\n\tdelay: 100\n} satisfies MenuItem;\n```\n\n### Checkbox Item\nA row with a checked state. It is a `menuitemcheckbox` with `aria-checked`, takes `value`, `defaultValue` and `onValueChange` like the other editable components, and keeps the menu open unless `closeOnClick: true`. The check indicator stays mounted and fades out when the row is unchecked. A consumer `onclick` runs first and `preventDefault()` there refuses the toggle.\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst wordWrap = {\n\ttype: 'checkbox',\n\ttitle: 'Word wrap',\n\tdefaultValue: true,\n\tonValueChange: (next) => console.log(next)\n} satisfies MenuItem;\n```\n\n### Radio Group Item\nRadio rows that share one value, inside a `role=\"group\"` named by `label`. Each radio is a `menuitemradio`. Choosing the checked radio changes nothing; `onValueChange` reports the chosen value once. The group keeps the menu open unless `closeOnClick: true` (a radio's own `closeOnClick` wins).\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst sortBy = {\n\ttype: 'radio-group',\n\tlabel: 'Sort by',\n\tdefaultValue: 'name',\n\tonValueChange: (value) => console.log(value),\n\titems: [\n\t\t{ value: 'name', title: 'Name' },\n\t\t{ value: 'date', title: 'Date modified' }\n\t]\n} satisfies MenuItem;\n```\n\nAn option that passes `selected` still renders a `menuitemradio` for single-choice lists that keep their value elsewhere.\n\n### Group Item\nRows under a label, inside a `role=\"group\"` that the label names. The visible label is hidden from the accessibility tree, so it is not read twice. Arrow keys and type-ahead cross group boundaries.\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst recent = {\n\ttype: 'group',\n\tlabel: 'Recent',\n\titems: [\n\t\t{ type: 'option', title: 'notes.md' },\n\t\t{ type: 'option', title: 'todo.md' }\n\t]\n} satisfies MenuItem;\n```\n\n## Structure\n\nThe menu follows this DOM structure:\n```\n<Menu>\n\t<div>                       <!-- first element: class, data attributes -->\n\t\t<!-- header snippet -->\n\t\t<div role=\"menu\">\n\t\t\t<!-- Items rendered based on type -->\n\t\t\t<Button />\n\t\t\t<MenuOption />\n\t\t\t<div role=\"group\">...</div>\n\t\t\t<Separator />\n\t\t\t<!-- ... -->\n\t\t</div>\n\t\t<!-- footer snippet -->\n\t</div>\n</Menu>\n```\n\nWith `filter` the search field sits between the header and the `role=\"menu\"` element, and the empty message (a `role=\"status\"` region) after it.\n\n## Examples\n\n### Simple Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { fileIcon } from 'entasis/icons/file';\n\timport { folderIcon } from 'entasis/icons/folder';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File', prefix: fileIcon },\n\t\t{ type: 'option', title: 'Open...', prefix: folderIcon },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Exit', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Buttons\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'button', children: 'Save', variant: 'solid', color: 'primary' },\n\t\t{ type: 'button', children: 'Cancel', variant: 'ghost' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Descriptions\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { starIcon } from 'entasis/icons/star';\n\timport { checkIcon } from 'entasis/icons/check';\n\timport { buildingIcon } from 'entasis/icons/building';\n\n\tconst items = [\n\t\t{ \n\t\t\ttype: 'option',\n\t\t\ttitle: 'Pro Plan',\n\t\t\tdescription: 'For growing teams',\n\t\t\tprefix: starIcon,\n\t\t\tsuffix: checkIcon\n\t\t},\n\t\t{ \n\t\t\ttype: 'option',\n\t\t\ttitle: 'Enterprise',\n\t\t\tdescription: 'For large organizations',\n\t\t\tprefix: buildingIcon\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Event Handlers\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tfunction handleProfile() {\n\t\tconsole.log('Profile clicked');\n\t}\n\t\n\tfunction handleLogout() {\n\t\tconsole.log('Logout clicked');\n\t}\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile', onclick: handleProfile },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Logout', onclick: handleLogout, color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Custom Theme\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst customTheme = {\n\t\troot: {\n\t\t\tbase: 'gap-3' // More spacing between items\n\t\t},\n\t\toption: {\n\t\t\troot: {\n\t\t\t\tbase: 'px-4 py-3'\n\t\t\t}\n\t\t}\n\t};\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{ type: 'option', title: 'Option 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} theme={customTheme} />\n```\n\n### Menu with Links\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Dashboard', href: '/dashboard' },\n\t\t{ type: 'option', title: 'Profile', href: '/profile' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'External Link', href: 'https://example.com', target: '_blank' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { gearIcon } from 'entasis/icons/gear';\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Dashboard' },\n\t\t{ type: 'option', title: 'Profile' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\tprefix: gearIcon,\n\t\t\ttitle: 'Settings',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'General' },\n\t\t\t\t{ type: 'option', title: 'Privacy' },\n\t\t\t\t{ type: 'option', title: 'Security' }\n\t\t\t]\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Stacked Submenus\n```svelte\n<Menu {items} submenuMode=\"stack\" />\n```\n\n### Nested Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Recent Files',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'document.txt' },\n\t\t\t\t{ type: 'option', title: 'project.js' },\n\t\t\t\t{\n\t\t\t\t\ttype: 'submenu',\n\t\t\t\t\ttitle: 'More',\n\t\t\t\t\tmenu: [\n\t\t\t\t\t\t{ type: 'option', title: 'file1.txt' },\n\t\t\t\t\t\t{ type: 'option', title: 'file2.txt' }\n\t\t\t\t\t]\n\t\t\t\t}\n\t\t\t]\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Save' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Submenu with Custom Trigger Behavior\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Click Only',\n\t\t\topenOnHover: false,\n\t\t\topenOnClick: true,\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'Hover with Delay',\n\t\t\topenOnHover: true,\n\t\t\tdelay: 500,\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Menu with Header\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Profile' },\n\t\t{ type: 'option', title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"border-b pb-2 mb-2\">\n\t\t\t<h3 class=\"text-sm font-semibold px-2\">User Menu</h3>\n\t\t\t<p class=\"text-xs text-gray-500 px-2\">Manage your account</p>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Menu with Footer\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Item 1' },\n\t\t{ type: 'option', title: 'Item 2' },\n\t\t{ type: 'option', title: 'Item 3' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet footer()}\n\t\t<div class=\"border-t pt-2 mt-2\">\n\t\t\t<div class=\"text-xs text-gray-500 px-2\">Version 1.0.0</div>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Menu with Header and Footer\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\n\tconst items = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items}>\n\t{#snippet header()}\n\t\t<div class=\"border-b pb-2 mb-2\">\n\t\t\t<div class=\"flex items-center gap-2 px-2\">\n\t\t\t\t<div class=\"w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white\">\n\t\t\t\t\tJD\n\t\t\t\t</div>\n\t\t\t\t<div>\n\t\t\t\t\t<div class=\"text-sm font-semibold\">John Doe</div>\n\t\t\t\t\t<div class=\"text-xs text-gray-500\">john@example.com</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</div>\n\t{/snippet}\n\t{#snippet footer()}\n\t\t<div class=\"border-t pt-2 mt-2\">\n\t\t\t<div class=\"text-xs text-gray-500 px-2 text-center\">\n\t\t\t\t<a href=\"/privacy\">Privacy</a> \u00B7 <a href=\"/terms\">Terms</a>\n\t\t\t</div>\n\t\t</div>\n\t{/snippet}\n</Menu>\n```\n\n### Checkbox Items and Radio Groups\n```svelte\n<script lang=\"ts\">\n\timport { Menu, type MenuItem } from 'entasis/menu';\n\n\tlet minimap = $state(true);\n\tlet sort = $state('name');\n\n\tconst items: MenuItem[] = $derived([\n\t\t{\n\t\t\ttype: 'checkbox',\n\t\t\ttitle: 'Minimap',\n\t\t\tvalue: minimap,\n\t\t\tonValueChange: (next) => (minimap = next)\n\t\t},\n\t\t{ type: 'checkbox', title: 'Word wrap', defaultValue: false },\n\t\t{ type: 'separator' },\n\t\t{\n\t\t\ttype: 'radio-group',\n\t\t\tlabel: 'Sort by',\n\t\t\tvalue: sort,\n\t\t\tonValueChange: (next) => (sort = next),\n\t\t\titems: [\n\t\t\t\t{ value: 'name', title: 'Name' },\n\t\t\t\t{ value: 'date', title: 'Date modified' },\n\t\t\t\t{ value: 'size', title: 'Size' }\n\t\t\t]\n\t\t}\n\t]);\n</script>\n\n<Menu {items} />\n```\n\n### Filterable Menu\nA search field above the rows. Typing narrows them (case and accent insensitive, over the row's `textValue`, or its text, and its `value`); a group whose rows all drop out goes too, and separators are dropped while searching. Focus stays in the field: ArrowDown and ArrowUp highlight rows (wrapping), the first match is highlighted as you type, and Enter presses the highlighted row. ArrowRight at the end of the text opens a highlighted submenu, ArrowLeft at the start leaves a submenu. A row whose title is a snippet needs a `textValue` to be found.\n```svelte\n<script lang=\"ts\">\n\timport { PopupMenu } from 'entasis/popup-menu';\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items: MenuItem[] = [\n\t\t{ type: 'option', title: 'Open file' },\n\t\t{ type: 'option', title: 'Open folder' },\n\t\t{ type: 'option', title: 'Open recent' },\n\t\t{ type: 'option', title: 'Save' },\n\t\t{ type: 'option', title: 'Save as' }\n\t];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Commands' }}\n\tmenu={{\n\t\titems,\n\t\tfilter: { placeholder: 'Find a command' },\n\t\tonSearchChange: (search) => console.log(search),\n\t\tonHighlightChange: (value) => console.log(value)\n\t}}\n/>\n```\n\nA submenu takes its own `filter` (a \"Move to...\" picker); it opens on its search field:\n```typescript\nimport type { MenuItem } from 'entasis/menu';\n\nconst moveTo = {\n\ttype: 'submenu',\n\ttitle: 'Move to',\n\tfilter: { placeholder: 'Pick a folder' },\n\tmenu: [\n\t\t{ type: 'option', title: 'Inbox' },\n\t\t{ type: 'option', title: 'Archive' },\n\t\t{ type: 'option', title: 'Projects' }\n\t]\n} satisfies MenuItem;\n```\n\n### Mixed Size Items\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Small Option', size: 'small' },\n\t\t{ type: 'option', title: 'Normal Option', size: 'normal' },\n\t\t{ type: 'option', title: 'Large Option', size: 'large' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Large Button', size: 'large', variant: 'solid' }\n\t] satisfies MenuItem[];\n</script>\n\n<Menu {items} />\n```\n\n### Density\n```svelte\n<!-- density tightens/loosens the row gap and every option row's paddings.\n     Button items are unaffected (Button has no density axis). -->\n<Menu {items} density=\"compact\" />\n<Menu {items} density=\"normal\" />\n<Menu {items} density=\"comfortable\" />\n```\n\n## Styling hooks\n\nRows carry their state as attributes, so `data-highlighted:`, `data-disabled:` and `data-selected:` variants style them without a theme override. `data-highlighted` and `data-selected` are written as `\"true\"`; match them by presence (`[data-highlighted]`).\n\nAttributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.\n\n**Data attributes**\n- `data-highlighted`: On a row: present while the keyboard or the pointer highlights it (the roving tab stop).\n- `data-disabled`: On a row: present while it is disabled.\n- `data-selected`: On a checkbox, radio or option row: present while it is checked or selected.\n- `data-popup-open`: On a submenu row: present while its submenu is open.\n- `data-popup-side`: On a submenu row: the submenu's `data-side` while it is placed.\n- `data-open`: On a popup menu or submenu panel: present while open.\n- `data-closed`: On a popup menu or submenu panel: present while its exit transition plays.\n- `data-entering`: On a popup menu or submenu panel: present while the enter transition plays.\n- `data-exiting`: On a popup menu or submenu panel: present while the exit transition plays.\n- `data-side`: On a popup menu or submenu panel: the side of its trigger it sits on after flipping.\n- `data-align`: On a popup menu or submenu panel: `start`, `center` or `end`.\n- `data-size`: On the root and the list: the resolved `size`.\n- `data-density`: On the root and the list: the resolved `density`.\n\n**CSS variables** (set on a popup menu's or submenu's positioned wrapper and inherited by the panel and its rows; an inline Menu has none)\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 `menuDataAttributes` and `menuCssVariables` (from `entasis/menu`) list each name with its meaning.\n\n## Accessibility\n\n- Automatically sets `role=\"menu\"` on the container\n- Option items render `role=\"menuitem\"`; checkbox items render `menuitemcheckbox` and radio items `menuitemradio`, each with `aria-checked`; an option that passes `selected` (true or false) renders `role=\"menuitemradio\"` too, so a check-marked choice is announced as checked rather than as a plain command\n- Groups and radio groups render `role=\"group\"` named (`aria-labelledby`) by their label, which is hidden from the accessibility tree. The header, footer and search field sit outside the `role=\"menu\"` element\n- ArrowUp / ArrowDown move the highlight, Home / End jump, Enter or Space activates, ArrowRight opens a submenu and ArrowLeft closes it; both are mirrored in right-to-left text, in an inline Menu as in a PopupMenu. A panel opened from a right-to-left trigger carries `dir=\"rtl\"` itself, because it is portaled out of the trigger's subtree\n- Tab inside a PopupMenu, ContextMenu or MenuBar menu closes every level and lets the browser carry on from the trigger, so focus lands on the control after it; Shift+Tab closes the menu and stays on the trigger. A field or link in the header or footer keeps Tab until the last one. Focus moving back to a row of the parent menu (a screen reader's cursor, a click) closes the submenus open beside it, so the arrow keys work there again\n- Type-ahead: typing letters moves the highlight to the next item whose label starts with the typed text. An option or submenu item's `textValue` replaces its visible text for matching (useful when the title is a snippet or the row shows a shortcut); disabled and hidden items are passed over for the next match, and the typed text starts over when focus leaves the menu\n- Disabled items and items hidden with CSS are skipped by the arrow keys, Home and End. The single Tab stop stays on the focused row element and follows the row that takes its place when the focused row is removed. Rows are keyed by identity (see `key`), so inserting, removing or reordering rows around the focused one leaves focus and the Tab stop on the same row\n- Hovering a row highlights it without moving focus. While nothing on the page has focus, the arrow keys and Home / End move focus into the hovered menu; keys typed in a text field, a button or another popup stay there, and Enter or Space never activate the hovered row. A submenu row is the exception: it still opens its submenu after the hover `delay`, but a submenu the pointer opened does not take focus, so typing in a field elsewhere carries on\n- Once focus is inside the menu, keys act on the focused row, not on the row under the pointer. When the menu panel itself has focus (a popup menu opened with the pointer), they act on the highlighted row that `aria-activedescendant` names, so Enter activates the row under the pointer\n- Arrow, Home, End, Enter and Space pressed with Alt, Ctrl or Meta are left to the browser (Alt+ArrowLeft stays Back), including in menus opened from a MenuBar; Shift does not count as a modifier\n- Supports keyboard navigation through child components\n- MenuOption and Button items handle interactive states\n\n## Theme Forwarding\n\nThe Menu component forwards theme props to its child components:\n- `theme.menu` - Applied to the container (gap, layout)\n- `theme.button` - Forwarded to all Button items\n- `theme.option` - Forwarded to all MenuOption items\n- `theme.separator` - Forwarded to all Separator items\n- `theme.submenu` - Forwarded to submenu MenuOption triggers\n\nThis allows for consistent styling across all menu items while maintaining flexibility for individual customization.\n\n## Submenu Behavior\n\nSubmenu items automatically:\n- Add a caret-right icon as suffix (unless custom suffix provided)\n- Open submenus beside their row on the reading direction's end side (`inline-end-start`: right in a left-to-right document, left in a right-to-left one); below `md` they drop below the row (`bottom-start`)\n- Fall back below their row when neither side of the menu has room (`fallbackAxisSide: 'end'`), instead of covering the menu\n- Support hover and click triggers (configurable)\n- Manage submenu state internally using PopupMenu\n- Support nested submenus (submenus within submenus)\n\nDefault submenu behavior:\n- Opens on hover (after 100ms delay)\n- Opens on click. A keyboard open (ArrowRight, Enter, Space) focuses the submenu's first row, a pointer click the submenu itself\n- A second press on an open submenu's row closes it when it came from the keyboard or assistive technology, or follows a click; a mouse click on a submenu the pointer opened keeps it open\n- On Apple platforms an open submenu's row omits `aria-expanded` (keeping `aria-haspopup` and `aria-controls`), because VoiceOver reads the trigger's state again when focus moves into the submenu\n- Closes when the pointer leaves the submenu prediction cone and rectangle tolerance\n- Closes when an item inside is chosen. Inside a PopupMenu, ContextMenu or MenuBar the submenu belongs to that menu: choosing an item at any depth closes every level at once, following the menu's closeOnItemClick. In an inline Menu, choosing an item closes the submenu and focus returns to its row\n- An item (or an ancestor) with `data-menu-keep-open=\"true\"` keeps every level open, for multi-select options: `{ type: 'option', title: 'Bold', attrs: { 'data-menu-keep-open': 'true' } }`\n\n## Notes\n\n- The Menu component is a controlled component that renders based on the items array\n- Items are distinguished by their `type` property using TypeScript discriminated unions\n- Each item type spreads its respective component props for full flexibility\n- The menu container uses minimal styling, focusing on vertical layout and spacing\n- Theme forwarding allows global styling of all items of a specific type\n\n## Theme Customization\n\nThe Menu 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- **root**: Main menu container styles\n- **list**: The `role=\"menu\"` element (density gap)\n- **group** / **groupLabel**: A `role=\"group\"` and its label\n- **search** / **searchIcon** / **searchInput**: The search field of a filterable menu\n- **empty**: The message shown when a search matches nothing\n- **header** / **footer**: The header and footer slots\n- **button**: Theme forwarded to Button items (optional)\n- **option**: Theme forwarded to MenuOption items (optional)\n- **separator**: Theme forwarded to Separator items (optional)\n- **submenu**: Theme forwarded to submenu MenuOption triggers (optional)\n\n### Theme Type Definition\n\n```typescript\nimport type { MenuThemeProps } from 'entasis/menu';\nimport type { ButtonThemeProps } from 'entasis/button';\nimport type { MenuOptionThemeProps } from 'entasis/menu-option';\nimport type { SeparatorThemeProps } from 'entasis/separator';\n\n// Example theme customization\nconst customTheme: MenuThemeProps = {\n  root: {\n    base: 'flex flex-col w-full',\n    density: {\n      compact: 'gap-0',\n      normal: 'gap-0.5',\n      comfortable: 'gap-1'\n    }\n  },\n  button: {\n    root: {\n      base: 'w-full justify-start'\n    }\n  },\n  option: {\n    root: {\n      density: {\n        normal: 'px-3 py-2'\n      }\n    }\n  },\n  separator: {\n    root: {\n      base: 'my-2'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes for menu container\n- Variants:\n  - density: 'compact' | 'normal' | 'comfortable' - Spacing between menu items\n\n**button** (optional):\n- Forwards theme to all Button items in the menu\n- See Button component theme documentation for available variants\n\n**option** (optional):\n- Forwards theme to all MenuOption items in the menu\n- See MenuOption component theme documentation for available variants\n\n**separator** (optional):\n- Forwards theme to all Separator items in the menu\n- See Separator component theme documentation for available variants\n\n**submenu** (optional):\n- Forwards theme to submenu MenuOption triggers\n- See MenuOption component theme documentation for available variants\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Menu\n  items={menuItems}\n  theme={{\n    root: {\n      density: {\n        normal: 'gap-2'\n      }\n    }\n  }}\n/>\n```\n\n**Theme Forwarding to Child Components**:\n```svelte\n<Menu\n  items={menuItems}\n  theme={{\n    root: {\n      density: {\n        comfortable: 'gap-3'\n      }\n    },\n    option: {\n      root: {\n        density: {\n          normal: 'px-4 py-3 min-h-10'\n        },\n        color: {\n          primary: 'text-blue-600 highlight:bg-blue-50'\n        }\n      }\n    },\n    separator: {\n      root: {\n        base: 'my-3',\n\t\tcolor: {\n\t\t\tneutral: 'before:border-gray-200 after:border-gray-200'\n\t\t}\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setMenuTheme } from './index.ts';\n  import { setMenuOptionTheme } from '../MenuOption/index.ts';\n  \n  // The global menu theme covers the container parts (root, header, footer).\n  // Option rows are themed globally through MenuOption's own setter.\n  setMenuTheme({\n    root: {\n      density: {\n        normal: 'gap-2'\n      }\n    }\n  });\n  setMenuOptionTheme({\n    root: {\n      base: 'rounded-lg',\n      density: {\n        normal: 'px-3 py-2'\n      }\n    }\n  });\n</script>\n```\n";