entasis 0.11.0 → 0.12.0

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

@@ -1,7 +1,7 @@
 export const menuDescription = `
 # Menu Component
 
-The 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.
+The 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.
 
 ## Basic Usage
 
@@ -41,8 +41,9 @@ The Menu component is a flexible container that renders an array of menu items i
 ### Core Props
 - **items**: MenuItem[] (required)
   - Array of menu items to render
-  - Each item must have a \`type\` field: 'button', 'option', or 'separator'
+  - Each item must have a \`type\` field: 'button', 'option', 'separator', 'submenu', 'checkbox', 'radio-group' or 'group'
   - Items are spread with their respective component props
+  - 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\`
 
 - **class**: string - Additional CSS classes for the menu container
 
@@ -54,9 +55,19 @@ The Menu component is a flexible container that renders an array of menu items i
 
 All 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.
 
-- **header**: Snippet - Optional header content rendered at the top of the menu
+- **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
 
-- **footer**: Snippet - Optional footer content rendered at the bottom of the menu
+- **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
+
+- **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
+
+- **filter**: boolean | { placeholder?, label?, match? } (default: false) - Adds a search field above the rows. See Filterable menus
+
+- **search** / **defaultSearch** / **onSearchChange**: the text of the search field (bindable \`search\`, initial \`defaultSearch\`, \`onSearchChange(search)\` once per edit)
+
+- **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
+
+- **empty**: Snippet - Shown in place of the rows when the search matches none of them (default: "No results found.")
 
 - **theme**: MenuThemeProps - Custom theme overrides
   - menu: Theme for the container (gap spacing, layout)
@@ -72,7 +83,7 @@ All three axes (\`density\`, \`size\`, \`color\`) are inherited by submenus: a s
 
 ## MenuItem Types
 
-The Menu accepts a discriminated union of four item types:
+The Menu accepts a discriminated union of seven item types:
 
 ### Button Item
 \`\`\`typescript
@@ -98,6 +109,29 @@ const optionItem = {
 } satisfies MenuItem;
 \`\`\`
 
+\`textValue\` sets the text type-ahead matches when the visible text should not count, for
+example a row that starts with a keyboard shortcut:
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const copyItem = {
+	type: 'option',
+	title: '⌘C  Copy',
+	textValue: 'Copy'
+} satisfies MenuItem;
+\`\`\`
+
+\`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"\`:
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const zoomIn = {
+	type: 'option',
+	title: 'Zoom in',
+	closeOnClick: false
+} satisfies MenuItem;
+\`\`\`
+
 ### Separator Item
 \`\`\`typescript
 import type { MenuItem } from './index.ts';
@@ -125,21 +159,75 @@ const submenuItem = {
 } satisfies MenuItem;
 \`\`\`
 
+### Checkbox Item
+A 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.
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const wordWrap = {
+	type: 'checkbox',
+	title: 'Word wrap',
+	defaultValue: true,
+	onValueChange: (next) => console.log(next)
+} satisfies MenuItem;
+\`\`\`
+
+### Radio Group Item
+Radio 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).
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const sortBy = {
+	type: 'radio-group',
+	label: 'Sort by',
+	defaultValue: 'name',
+	onValueChange: (value) => console.log(value),
+	items: [
+		{ value: 'name', title: 'Name' },
+		{ value: 'date', title: 'Date modified' }
+	]
+} satisfies MenuItem;
+\`\`\`
+
+An option that passes \`selected\` still renders a \`menuitemradio\` for single-choice lists that keep their value elsewhere.
+
+### Group Item
+Rows 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.
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const recent = {
+	type: 'group',
+	label: 'Recent',
+	items: [
+		{ type: 'option', title: 'notes.md' },
+		{ type: 'option', title: 'todo.md' }
+	]
+} satisfies MenuItem;
+\`\`\`
+
 ## Structure
 
 The menu follows this DOM structure:
 \`\`\`
 <Menu>
-	<div role="menu">
-		<!-- Items rendered based on type -->
-		<Button />
-		<MenuOption />
-		<Separator />
-		<!-- ... -->
+	<div>                       <!-- first element: class, data attributes -->
+		<!-- header snippet -->
+		<div role="menu">
+			<!-- Items rendered based on type -->
+			<Button />
+			<MenuOption />
+			<div role="group">...</div>
+			<Separator />
+			<!-- ... -->
+		</div>
+		<!-- footer snippet -->
 	</div>
 </Menu>
 \`\`\`
 
+With \`filter\` the search field sits between the header and the \`role="menu"\` element, and the empty message (a \`role="status"\` region) after it.
+
 ## Examples
 
 ### Simple Menu
@@ -446,6 +534,83 @@ The menu follows this DOM structure:
 </Menu>
 \`\`\`
 
+### Checkbox Items and Radio Groups
+\`\`\`svelte
+<script lang="ts">
+	import { Menu, type MenuItem } from './index.ts';
+
+	let minimap = $state(true);
+	let sort = $state('name');
+
+	const items: MenuItem[] = $derived([
+		{
+			type: 'checkbox',
+			title: 'Minimap',
+			value: minimap,
+			onValueChange: (next) => (minimap = next)
+		},
+		{ type: 'checkbox', title: 'Word wrap', defaultValue: false },
+		{ type: 'separator' },
+		{
+			type: 'radio-group',
+			label: 'Sort by',
+			value: sort,
+			onValueChange: (next) => (sort = next),
+			items: [
+				{ value: 'name', title: 'Name' },
+				{ value: 'date', title: 'Date modified' },
+				{ value: 'size', title: 'Size' }
+			]
+		}
+	]);
+</script>
+
+<Menu {items} />
+\`\`\`
+
+### Filterable Menu
+A 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.
+\`\`\`svelte
+<script lang="ts">
+	import { PopupMenu } from '../PopupMenu/index.ts';
+	import type { MenuItem } from './index.ts';
+
+	const items: MenuItem[] = [
+		{ type: 'option', title: 'Open file' },
+		{ type: 'option', title: 'Open folder' },
+		{ type: 'option', title: 'Open recent' },
+		{ type: 'option', title: 'Save' },
+		{ type: 'option', title: 'Save as' }
+	];
+</script>
+
+<PopupMenu
+	trigger={{ content: 'Commands' }}
+	menu={{
+		items,
+		filter: { placeholder: 'Find a command' },
+		onSearchChange: (search) => console.log(search),
+		onHighlightChange: (value) => console.log(value)
+	}}
+/>
+\`\`\`
+
+A submenu takes its own \`filter\` (a "Move to..." picker); it opens on its search field:
+\`\`\`typescript
+import type { MenuItem } from './index.ts';
+
+const moveTo = {
+	type: 'submenu',
+	title: 'Move to',
+	filter: { placeholder: 'Pick a folder' },
+	menu: [
+		{ type: 'option', title: 'Inbox' },
+		{ type: 'option', title: 'Archive' },
+		{ type: 'option', title: 'Projects' }
+	]
+} satisfies MenuItem;
+\`\`\`
+
 ### Mixed Size Items
 \`\`\`svelte
 <script lang="ts">
@@ -472,12 +637,48 @@ The menu follows this DOM structure:
 <Menu {items} density="comfortable" />
 \`\`\`
 
+## Styling hooks
+
+Rows 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]\`).
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`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\`.
+
+**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)
+- \`--available-width\`: The width in px the panel can take before it reaches the viewport edges, minus 20px.
+- \`--available-height\`: The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with \`max-height: min(240px, var(--available-height))\`.
+- \`--anchor-width\`: The trigger's width in px, snapped to the device pixel grid.
+- \`--anchor-height\`: The trigger's height in px, snapped to the device pixel grid.
+- \`--transform-origin\`: The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.
+
+The typed maps \`menuDataAttributes\` and \`menuCssVariables\` (from \`entasis/menu\`) list each name with its meaning.
+
 ## Accessibility
 
 - Automatically sets \`role="menu"\` on the container
-- 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
-- ArrowUp / ArrowDown move the highlight, Home / End jump, Enter or Space activates, ArrowRight opens a submenu and ArrowLeft closes it (mirrored in RTL)
-- Type-ahead: typing letters moves the highlight to the next item whose label starts with the typed text
+- 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
+- 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
+- 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
+- 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
+- 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
+- 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
+- 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
+- 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
+- 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
 - Supports keyboard navigation through child components
 - MenuOption and Button items handle interactive states
 
@@ -496,16 +697,20 @@ This allows for consistent styling across all menu items while maintaining flexi
 
 Submenu items automatically:
 - Add a caret-right icon as suffix (unless custom suffix provided)
-- Open submenus positioned to the right (right-start)
+- 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\`)
+- Fall back below their row when neither side of the menu has room (\`fallbackAxisSide: 'end'\`), instead of covering the menu
 - Support hover and click triggers (configurable)
 - Manage submenu state internally using PopupMenu
 - Support nested submenus (submenus within submenus)
 
 Default submenu behavior:
 - Opens on hover (after 100ms delay)
-- Opens on click
+- Opens on click. A keyboard open (ArrowRight, Enter, Space) focuses the submenu's first row, a pointer click the submenu itself
+- 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
+- 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
 - Closes when the pointer leaves the submenu prediction cone and rectangle tolerance
-- Does not close when clicking items inside (allows multi-interaction)
+- 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
+- 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' } }\`
 
 ## Notes
 
@@ -523,6 +728,11 @@ The Menu component uses a theme object that can be customized using the \`theme\
 
 The theme object contains the following parts:
 - **root**: Main menu container styles
+- **list**: The \`role="menu"\` element (density gap)
+- **group** / **groupLabel**: A \`role="group"\` and its label
+- **search** / **searchIcon** / **searchInput**: The search field of a filterable menu
+- **empty**: The message shown when a search matches nothing
+- **header** / **footer**: The header and footer slots
 - **button**: Theme forwarded to Button items (optional)
 - **option**: Theme forwarded to MenuOption items (optional)
 - **separator**: Theme forwarded to Separator items (optional)

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

@@ -0,0 +1,5 @@
+/**
+ * Whether the page runs on an Apple platform (macOS, iOS, iPadOS), where VoiceOver reads the
+ * state of a submenu trigger again when focus moves into its submenu.
+ */
+export declare const isApplePlatform: () => boolean;

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

@@ -0,0 +1,11 @@
+/**
+ * Whether the page runs on an Apple platform (macOS, iOS, iPadOS), where VoiceOver reads the
+ * state of a submenu trigger again when focus moves into its submenu.
+ */
+export const isApplePlatform = () => {
+    if (typeof navigator === 'undefined')
+        return false;
+    const nav = navigator;
+    const platform = nav.userAgentData?.platform || nav.platform || nav.userAgent || '';
+    return /Mac|iPhone|iPad|iPod/i.test(platform);
+};

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

@@ -4,8 +4,24 @@ import type { WithAttachments } from '../../types/props.js';
 import type { ButtonProps } from '../Button/button.props.js';
 import type { MenuOptionProps } from '../MenuOption/menuOption.props.js';
 import type { SeparatorProps } from '../Separator/separator.props.js';
+import type { Slot } from '../Slot/slot.js';
 import type { MenuThemeProps } from './menu.theme.js';
 export type MenuSubmenuMode = 'auto' | 'popover' | 'stack';
+/** Fields every menu item accepts. */
+export type MenuItemBase = {
+    /**
+     * Identity of the row. A row keeps its DOM node (and with it focus, the tab stop and hover
+     * state) while items before it are inserted, removed or reordered, as long as its key stays the
+     * same. Left out, the key comes from the row's visible text, `href` or `textValue`, so rows
+     * built from plain strings need none. Give rows whose text is a snippet or repeats a key.
+     */
+    key?: string | number;
+    /**
+     * Identifies the row in `onHighlightChange` and in a filter's `match`. Left out, the row's
+     * `textValue`, or its text when that is a string, stands for it.
+     */
+    value?: string;
+};
 export type SubMenuItemProps = Omit<MenuOptionProps, 'onclick' | 'onpointerenter' | 'onpointerleave'> & {
     /**
      * Array of submenu items.
@@ -36,28 +52,142 @@ export type SubMenuItemProps = Omit<MenuOptionProps, 'onclick' | 'onpointerenter
      * @default false
      */
     debugSafeArea?: boolean;
+    /**
+     * Adds a search field above the submenu's rows (a "Move to..." picker). `true` uses the
+     * defaults; an object tunes the field. See `MenuProps.filter`.
+     */
+    filter?: MenuFilter;
+    /**
+     * Called with the `value` of the highlighted row of the submenu, `undefined` when none is.
+     */
+    onHighlightChange?: (value: string | undefined) => void;
 };
-export type MenuItem = ({
+/** What a menu's search field matches against, and how it looks. */
+export type MenuFilterOptions = {
+    /** Placeholder of the search field. Defaults to the catalog's search placeholder. */
+    placeholder?: string;
+    /** Accessible name of the search field. Defaults to the placeholder. */
+    label?: string;
+    /**
+     * Decides whether a row stays visible for the search text. Defaults to a case- and
+     * accent-insensitive substring match against the row's `textValue`, `value` or text.
+     */
+    match?: (item: MenuFilterMatchItem, search: string) => boolean;
+};
+/** A row as a filter's `match` sees it. */
+export type MenuFilterMatchItem = {
+    /** The row's `value`, else its `textValue`, else its text when that is a string. */
+    value: string | undefined;
+    /** The text the row shows or is matched on. */
+    text: string;
+    /** The row's own item. */
+    item: MenuItem;
+};
+/** `true` shows a search field with the defaults; an object tunes it. */
+export type MenuFilter = boolean | MenuFilterOptions;
+/**
+ * A row that closes the menu when pressed unless `closeOnClick` is `false`. Applies to buttons
+ * and options; a checkbox item or a radio group keeps the menu open by default.
+ */
+export type MenuCloseOnClick = {
+    /**
+     * Whether pressing the row closes the menu it sits in.
+     * @default true
+     */
+    closeOnClick?: boolean;
+};
+export type MenuButtonItem = {
     type: 'button';
-} & ButtonProps) | ({
+} & MenuItemBase & MenuCloseOnClick & ButtonProps;
+export type MenuOptionItem = {
     type: 'option';
-} & MenuOptionProps) | ({
+} & MenuItemBase & Omit<MenuOptionProps, 'closeOnClick'> & MenuCloseOnClick;
+export type MenuSeparatorItem = {
     type: 'separator';
-} & SeparatorProps) | ({
+} & Pick<MenuItemBase, 'key'> & SeparatorProps;
+export type MenuSubmenuItem = {
     type: 'submenu';
-} & MenuOptionProps & SubMenuItemProps);
+} & MenuItemBase & MenuOptionProps & SubMenuItemProps;
+/**
+ * A row with a checked state. The check indicator stays mounted and animates out when the row is
+ * unchecked. A press toggles it and keeps the menu open unless `closeOnClick` is `true`.
+ */
+export type MenuCheckboxItem = {
+    type: 'checkbox';
+} & Pick<MenuItemBase, 'key'> & Omit<MenuOptionProps, 'selected' | 'role' | 'closeOnClick'> & {
+    /** Checked state. Pass it with `onValueChange` to control the row. */
+    value?: boolean;
+    /** Initial checked state when `value` is not passed. @default false */
+    defaultValue?: boolean;
+    /** Called once with the new checked state after a press that changes it. */
+    onValueChange?: (value: boolean) => void;
+    /**
+     * Whether pressing the row closes the menu.
+     * @default false
+     */
+    closeOnClick?: boolean;
+};
+/** One radio of a `radio-group` item. */
+export type MenuRadioItem = Omit<MenuOptionProps, 'selected' | 'role' | 'closeOnClick'> & Pick<MenuItemBase, 'key'> & Pick<MenuCloseOnClick, 'closeOnClick'> & {
+    /** The value the group takes when this radio is chosen. Unique within the group. */
+    value: string;
+};
+/**
+ * Radio rows that share one value, inside a labelled `role="group"`. A press chooses the radio
+ * and keeps the menu open unless `closeOnClick` is `true`; choosing the checked radio changes
+ * nothing.
+ */
+export type MenuRadioGroupItem = {
+    type: 'radio-group';
+    key?: string | number;
+    /** Label of the group. It names the group for assistive technology and is hidden from the tree otherwise. */
+    label?: Slot;
+    /** Checked value. Pass it with `onValueChange` to control the group. */
+    value?: string;
+    /** Initial checked value when `value` is not passed. */
+    defaultValue?: string;
+    /** Called once with the chosen value after a press that changes it. */
+    onValueChange?: (value: string) => void;
+    /**
+     * Whether choosing a radio closes the menu. A radio's own `closeOnClick` wins.
+     * @default false
+     */
+    closeOnClick?: boolean;
+    /** Disables every radio of the group. */
+    disabled?: boolean;
+    /** The radios. */
+    items: MenuRadioItem[];
+};
+/** Rows under a label, inside a `role="group"` named by it. */
+export type MenuGroupItem = {
+    type: 'group';
+    key?: string | number;
+    /** Label of the group. It names the group for assistive technology and is hidden from the tree otherwise. */
+    label?: Slot;
+    /** The rows of the group. */
+    items: MenuItem[];
+};
+export type MenuItem = MenuButtonItem | MenuOptionItem | MenuSeparatorItem | MenuSubmenuItem | MenuCheckboxItem | MenuRadioGroupItem | MenuGroupItem;
 export type MenuProps = WithAttachments<{
     /**
      * Focus first item on mount.
+     * - `true`: the first item.
+     * - `'last'`: the last item.
+     * - `'container'`: the menu itself, with no item highlighted.
+     *
+     * Left out, a PopupMenu decides from how it opened: a keyboard open highlights the first item
+     * (the last one for ArrowUp), a pointer open focuses the menu, and a hover open leaves focus
+     * where it is.
      * @default false
      */
-    focusOnMount?: boolean | 'container';
+    focusOnMount?: boolean | 'container' | 'last';
     /**
      * The class name of the menu container. First element that the component outputs in the DOM.
      */
     class?: string;
     /**
-     * Array of menu items to render (Button, MenuOption, or Separator).
+     * Array of menu items to render (Button, MenuOption, Separator, submenu, checkbox, radio
+     * group or group).
      */
     items: MenuItem[];
     /**
@@ -92,11 +222,44 @@ export type MenuProps = WithAttachments<{
      */
     submenuMode?: MenuSubmenuMode;
     /**
-     * Optional header content rendered at the top of the menu.
+     * Optional header content rendered at the top of the menu, outside the `role="menu"` element
+     * (links and fields in it are not menu items).
      */
     header?: Snippet;
     /**
-     * Optional footer content rendered at the bottom of the menu.
+     * Optional footer content rendered at the bottom of the menu, outside the `role="menu"`
+     * element (links and buttons in it are not menu items).
      */
     footer?: Snippet;
+    /**
+     * Adds a search field above the rows. Typing narrows the rows (and drops groups left empty);
+     * focus stays in the field while ArrowUp and ArrowDown highlight rows, and Enter presses the
+     * highlighted one. `true` uses the defaults; an object tunes the placeholder, the label and
+     * the match.
+     * @default false
+     */
+    filter?: MenuFilter;
+    /**
+     * The search text. Pass it with `onSearchChange` to control the field.
+     */
+    search?: string;
+    /**
+     * Initial search text when `search` is not passed.
+     * @default ''
+     */
+    defaultSearch?: string;
+    /**
+     * Called once per edit of the search field with the new text.
+     */
+    onSearchChange?: (search: string) => void;
+    /**
+     * Called when the highlighted row changes (by keyboard, by hover or by filtering), with that
+     * row's `value` (its `textValue`, or its text when that is a string) and `undefined` when no
+     * row is highlighted.
+     */
+    onHighlightChange?: (value: string | undefined) => void;
+    /**
+     * Shown in place of the rows when the search matches none of them.
+     */
+    empty?: Snippet;
 }>;