@lumiose/ui 0.0.0-stage → 0.1.1

package/docs/llms.txt

@@ -0,0 +1,53 @@
+# Lumiose UI
+
+> `@lumiose/ui`: accessible, unstyled UI primitives built on native elements (`<dialog>`, popover, invoker commands, CSS anchor positioning), server-rendered without hydration. Style them with your own CSS or the optional default theme.
+
+These docs ship in `@lumiose/ui` and match the installed version: `node_modules/@lumiose/ui/docs`.
+In a project that depends on it, `lumiose docs ui` prints the index and `lumiose docs dialog` a
+component's page; the Lumiose MCP server's `ui_components` tool lists every component's parts,
+props, events and styling hooks. The Lumiose docs: `node_modules/lumiose/docs/llms.txt`.
+
+## Overview
+
+- [UI components](README.md): `@lumiose/ui`: accessible, unstyled UI primitives built on native elements (`<dialog>`, popover, invoker commands, CSS anchor positioning), server-rendered without hydration. Style them with your own CSS or the optional default theme.
+- [Installation](installation.md): Add `@lumiose/ui` to a Lumiose app and import its stylesheets, and the default theme if you want its look. The components then render in server HTML, without an island, and a page loads only the small scripts of the components it renders.
+- [Theming](theming.md): `@lumiose/ui` is unstyled: its stylesheets hold only what the components need to work. The optional default theme gives them a look, light and dark, through `--lu-` custom properties you can change; or style the parts with your own CSS.
+
+## Components
+
+- [Accordion](accordion.md): A stack of items whose triggers show and hide their panels, after the WAI-ARIA accordion pattern: each item is a native `<details>`, one open at a time through the browser's exclusive group (`name`) or several, so it works in server HTML with no JavaScript and find-in-page opens the item it lands in. `<lu-accordion>`, a 1 kB light-DOM element, adds the arrow keys and Base UI's animation hooks. `bind:value` (or `value` and `onValueChange`) keeps a signal in sync.
+- [Autocomplete](autocomplete.md): A text input with suggestions, for text that may be anything (a search, a tag, an address): the WAI-ARIA combobox pattern with list autocomplete, after Base UI's Autocomplete. Unlike a Combobox, the text is the value: the input has the name and submits what is typed, and choosing a suggestion only fills it in. It runs on the Combobox's element (`<lu-combobox free>`, 5.0 kB) and parts, on server-rendered pages and in islands; `bind:value` keeps a signal in sync. Filtering, inline completion, groups, an empty state and a status.
+- [Avatar](avatar.md): A person's picture with a fallback, such as their initials, after Base UI's Avatar: the image loads in the server HTML and shows once it has loaded, the fallback shows until then, after an optional delay, and when the image fails. Both sit in one cell, so neither moves the other. A 0.5 kB script follows the image's loading status; without JavaScript an avatar with an image shows the image alone.
+- [Button](button.md): A native `<button>`, after Base UI's Button. It is `type="button"` unless you say otherwise, so it submits a form only when asked to. Disabled it leaves the tab order; with `focusableWhenDisabled` it stays focusable as `aria-disabled="true"` (a loading state keeps focus where it was) and a tiny script cancels its clicks.
+- [Checkbox](checkbox.md): A native `<input type="checkbox">`, after Base UI's Checkbox: Space and a label click toggle it, the form submits its value when checked, reset and `required` work, in server HTML and without JavaScript. `indeterminate`, `readOnly`, the parent checkbox of a Checkbox Group and `bind:checked` come on top, with a 1.0 kB script shared with Radio Group and Switch.
+- [Checkbox Group](checkbox-group.md): A group of checkboxes with one value, the list of the checked ones, after Base UI's CheckboxGroup: a native `<fieldset>` whose checkboxes share a name, so the form submits each checked value and a disabled group disables them all, without JavaScript. A parent checkbox checks them all and shows checked, mixed or unchecked as they are; `bind:value` keeps a signal in sync.
+- [Collapsible](collapsible.md): A panel that its trigger shows and hides: a native `<details>` whose `<summary>` is the trigger, so it works in server HTML with no JavaScript, keeps the browser's keyboard handling, and opens when find-in-page or a link lands inside it. A 0.7 kB script adds Base UI's animation hooks. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+- [Combobox](combobox.md): A text input that filters a list of options, for picking one value or several from many: the WAI-ARIA combobox pattern with list autocomplete, after Base UI's Combobox. The input shows the option's label and the form gets its value. `<lu-combobox>`, a 5.4 kB form-associated light-DOM element, runs it on server-rendered pages and in islands; `bind:value` and `bind:open` keep signals in sync. Groups, an empty state, a status, a clear button, multiple values with chips, validation and async options.
+- [Context Menu](context-menu.md): A menu opened at the pointer by a right-click in its trigger area, a long press on a touch screen, or Shift+F10 and the ContextMenu key: Menu's popup and items, with Menu's keys, typeahead, submenus and dismissal. A 0.6 kB script on top of Menu's (4.6 kB together) opens it; without JavaScript the browser shows its own menu. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+- [Dialog](dialog.md): A modal dialog, or an alert dialog that needs an answer: a native `<dialog>` opened and closed by invoker commands, so it works in server HTML with no JavaScript, and a 1.5 kB script closes the native element's gaps where JavaScript runs. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+- [Drawer](drawer.md): A panel that slides in from an edge of the window and that a swipe toward that edge closes: a Dialog (a native modal `<dialog>` opened by an invoker command, so it works in server HTML with no JavaScript) against the edge its `swipeDirection` names. A 1 kB script adds the swipe, with the close buttons, Escape and a click on the backdrop as its alternatives. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+- [Field](field.md): A form field: a label, a native control, a description and its errors, wired with `for`, `aria-describedby` and `aria-invalid`, after Base UI's Field. Validation is the browser's constraint validation (`required`, `type`, `pattern`, `minlength`…); a 1.7 kB script shows it in the field's Error parts at the right time, instead of the browser's bubble, and focuses the first invalid field on submit. A Form's server errors render in the HTML, so they work without JavaScript. In an island, `validate` adds checks of your own, async ones included, and `Field.Validity` renders from the field's validity.
+- [Fieldset](fieldset.md): A group of related fields with a caption: a native `<fieldset>` and `<legend>`, after Base UI's Fieldset. The browser names the group by its legend and disables every control inside a disabled fieldset, with no JavaScript and no CSS of its own. The legend also names a Checkbox Group or a Radio Group.
+- [Form](form.md): A native `<form>` that hands its fields the server's errors, after Base UI's Form. Pass the data a form action gives `fail()` as `errors`, and each Field shows the message for its `name`, in the HTML the server renders back (no JavaScript needed) or, with `submit()`, in an island. Submission, validation and the first invalid field's focus are the platform's and Field's.
+- [Input](input.md): A native `<input>`, after Base UI's Input: every type, constraint and autofill the browser has, plus `onValueChange` and `bind:value`. Inside a Field (as `Field.Control`) it takes the field's id, name and ARIA references. No script, no CSS of its own.
+- [Menu](menu.md): A menu of commands, links, checkbox and radio items and submenus, opened by a button: the trigger's `popovertarget` opens it and CSS anchor positioning places it, so it works in server HTML with no JavaScript, and a 4.0 kB script adds the APG Menu Button keyboard contract where JavaScript runs. `bind:open`, `bind:checked` and `bind:value` keep signals in sync in islands.
+- [Menubar](menubar.md): A bar of menus, such as an app's File, Edit and View, after Base UI's Menubar and the WAI-ARIA menubar pattern: `Menu.Root`s inside `<lu-menubar role="menubar">`, whose triggers are the bar's items. Menu's popups, items, submenus and dismissal; the bar is one tab stop, the arrow keys move between its items and between open menus, and once a menu is open, hovering another item opens its menu instead. A 0.7 kB script on top of Menu's (4.7 kB together); without JavaScript each trigger opens its menu.
+- [Meter](meter.md): A measurement within a known range (storage used, a password's strength, a rating), after Base UI's Meter: a native `<meter>` (with its value, range and `aria-valuetext`), labelled, with the value as text (a percentage of the range by default, or your `Intl.NumberFormat` options). No script.
+- [Navigation Menu](navigation-menu.md): A site's navigation whose items open panels of links, after Base UI's NavigationMenu and the WAI-ARIA disclosure navigation pattern: a `<nav>` landmark around a list, each trigger opening its content through `popovertarget` (a native popover placed under it by CSS anchor positioning), so the links work and the panels open on a click, one at a time, in server HTML with no JavaScript. A 3.5 kB script adds hover intent, the arrow keys, closing when focus leaves and the direction a panel comes in from. `bind:value` (or `value` and `onValueChange`) keeps the open item in a signal.
+- [Number Field](number-field.md): A number input with buttons to step it, after Base UI's NumberField and the APG spinbutton. Without `format` it is a native `<input type="number">`, which steps, validates and submits without JavaScript; with `format` (`Intl.NumberFormat` options: a currency, a percentage, grouping) it shows the formatted number, reads what is typed back in the same locale, and a hidden input submits the number. `<lu-number-field>`'s 2.6 kB script adds Page Up and Page Down, Home and End, press-and-hold buttons, a scrub area, the wheel when asked, and commit-time clamping. `bind:value` keeps a signal in sync.
+- [OTP Field](otp-field.md): A one-time code input, after Base UI's OTPField: one native `<input>` shown as one slot per character. SMS autofill (`autocomplete="one-time-code"`), paste, Backspace, the arrow keys, `maxlength`, `pattern`, `required` and the form's value are the platform's, without JavaScript too, and assistive technology meets one labelled text field. `<lu-otp-field>`'s 1.5 kB script lays the input over the slots, keeps the code to the allowed characters, and reports completion. `bind:value` keeps a signal in sync.
+- [Popover](popover.md): A popup anchored to its trigger: a native `popover` opened and closed by the trigger's `popovertarget`, placed with CSS anchor positioning, so it works in server HTML with no JavaScript. A 3.3 kB script moves focus into it and back, dismisses it as Base UI does (not on a right-click), keeps `aria-expanded` current and places it in browsers without anchor positioning. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands. A trigger can open it on hover (`openOnHover`), and a `modal` popover is a modal `<dialog>` that makes the page behind it inert.
+- [Preview Card](preview-card.md): A card that previews a link's destination while the pointer or keyboard focus rests on the link, after Base UI's PreviewCard. The trigger is the link itself, which works as a link without JavaScript; the card is a manual popover placed with Popover's placement and opened with its hover timing by a 2.8 kB script. It is hoverable, persistent and dismissible (WCAG 1.4.13). `bind:open` keeps a signal in sync.
+- [Progress](progress.md): A task's progress, after Base UI's Progress: a native `<progress>` (the progress bar for assistive technology, with its value and `aria-valuetext`), labelled, with the value as text (a percentage by default, or your `Intl.NumberFormat` options). With no value it is indeterminate. No script.
+- [Radio](radio-group.md): A group of radios with one value, after Base UI's RadioGroup and Radio: native radios in a `<fieldset role="radiogroup">`. The browser gives the group one tab stop, arrow keys that move and select (skipping disabled radios), `required`, submission and reset, in server HTML and without JavaScript; a legend names the group. `bind:value` keeps a signal in sync.
+- [Scroll Area](scroll-area.md): A scrolling region with custom scrollbars laid over native scrolling, after Base UI's ScrollArea. The viewport scrolls natively (the wheel, touch, the keyboard, find-in-page), is focusable while it overflows, and traps nothing; without JavaScript its native scrollbars show. `<lu-scroll-area>`'s 1.6 kB script hides them and draws its own, which show on hover, while scrolling and while focused, take a thumb drag and a track press, and expose the overflow as data attributes and CSS variables.
+- [Select](select.md): A native `<select>` for picking one value from a list: it works with no JavaScript, submits with its form and keeps the platform's keyboard, typeahead and mobile pickers. Where the browser has customizable select (`appearance: base-select`, Chrome 135, Safari 26), `Select.Trigger` and `Select.Value` shape the button, the picker is styleable and options may hold more than text; elsewhere it is the classic select. No script; `bind:value` keeps a signal in sync in islands.
+- [Separator](separator.md): A native `<hr>` between groups of content, after Base UI's Separator: announced as a separator, horizontal by default, or vertical between the items of a row with `aria-orientation="vertical"`. No script.
+- [Slider](slider.md): A value picked within a range by dragging or with the keys, or a range with two thumbs, after Base UI's Slider. Each thumb is a native `<input type="range">`, so it drags, takes the arrow keys, Home and End, follows the text direction and submits with its form, in server HTML and without JavaScript. `<lu-slider>` adds Page Up and Page Down, keeps a range's thumbs in order, moves the nearest thumb on a press on the track and keeps the value text current. `bind:value` keeps a signal in sync.
+- [Switch](switch.md): On or off, for a setting: a native `<input type="checkbox" role="switch">`, after Base UI's Switch. Space and a label click toggle it, the form submits its value when on, `required` and reset work, in server HTML and without JavaScript, and assistive technology announces a switch. `bind:checked` keeps a signal in sync.
+- [Tabs](tabs.md): A tab list and the panel of the selected tab, after the WAI-ARIA tabs pattern: the server HTML holds the whole state (roles, `aria-selected`, the roving tab stop, the hidden panels), and `<lu-tabs>`, a 1.2 kB light-DOM element, adds the arrow keys and the selection. Manual or automatic activation, horizontal or vertical, right-to-left aware, with an optional indicator that slides to the selected tab; `bind:value` (or `value` and `onValueChange`) keeps a signal in sync.
+- [Toast](toast.md): Short notices in a region of their own, after Base UI's toast: server HTML renders them (a form action's result), and islands add, update and close them through a toast manager. `<lu-toast-viewport>`, a 2.6 kB light-DOM element, puts them in the top layer, times them (pausing on hover and focus), limits how many show, closes them on a swipe, Escape or their close button, focuses the region on F6, and makes screen readers announce them.
+- [Toggle](toggle.md): A two-state button (bold, mute, pin), after Base UI's Toggle: a native `<button type="button" aria-pressed>`. Its label stays the same; `aria-pressed` tells pressed from not. On its own the component presses it, in an island, and `bind:pressed` keeps a signal in sync; inside a Toggle Group the group presses it, on server pages too.
+- [Toggle Group](toggle-group.md): A set of Toggles with one value, after Base UI's ToggleGroup: text alignment (one pressed at a time) or text style (several). `<lu-toggle-group role="group">` presses its toggles and gives the group one tab stop that the arrow keys, Home and End move, following the orientation and the direction, on server pages and in islands. `bind:value` keeps a signal in sync.
+- [Toolbar](toolbar.md): A set of controls with one tab stop, after Base UI's Toolbar and the APG toolbar pattern: `<lu-toolbar role="toolbar">` moves focus between its items with the arrow keys, Home and End, following the orientation and the text direction. Its items are native: buttons that stay focusable when disabled, links, inputs, and the toggles of a Toggle Group inside it. In the server HTML every item is a tab stop, so each is reachable without JavaScript; a 1.1 kB script makes them one tab stop and moves it.
+- [Tooltip](tooltip.md): A short tip next to its trigger, on hover or keyboard focus: a native `popover="hint"` with `role="tooltip"`, placed with CSS anchor positioning. The trigger is described by the tip in server HTML, so screen readers announce it without hovering; a 2.0 kB script opens and closes it as Base UI's tooltip does. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.

package/docs/menu.md

@@ -0,0 +1,365 @@
+# Menu
+
+> A menu of commands, links, checkbox and radio items and submenus, opened by a button: the trigger's `popovertarget` opens it and CSS anchor positioning places it, so it works in server HTML with no JavaScript, and a 4.0 kB script adds the APG Menu Button keyboard contract where JavaScript runs. `bind:open`, `bind:checked` and `bind:value` keep signals in sync in islands.
+
+```ts
+import { Menu } from "@lumiose/ui"; // or "@lumiose/ui/menu"
+import "@lumiose/ui/menu.css"; // places the popup next to its trigger and stacks the items
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Menu.Root>
+  <Menu.Trigger />
+  <Menu.Popup>
+    <Menu.Item />
+    <Menu.LinkItem />
+    <Menu.CheckboxItem />
+    <Menu.Separator />
+    <Menu.Group>
+      <Menu.GroupLabel />
+      <Menu.Item />
+    </Menu.Group>
+    <Menu.RadioGroup>
+      <Menu.GroupLabel />
+      <Menu.RadioItem />
+    </Menu.RadioGroup>
+    <Menu.SubmenuRoot>
+      <Menu.SubmenuTrigger />
+      <Menu.Popup>…</Menu.Popup>
+    </Menu.SubmenuRoot>
+  </Menu.Popup>
+</Menu.Root>
+```
+
+| Part             | Renders                                                                                                                                              |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`           | `<lu-menu>`, an element with no box (`display: contents`) that holds the menu's state and adds the keyboard contract.                                |
+| `Trigger`        | `<button type="button" popovertarget="…" aria-haspopup="menu">`; `aria-expanded` follows the menu once the script runs.                              |
+| `Popup`          | `<div role="menu" popover="auto" tabindex="-1" data-side="…" data-align="…">`, labelled by its trigger; `popover="manual"` once the script opens it. |
+| `Item`           | `<button type="button" role="menuitem">`: a command.                                                                                                 |
+| `LinkItem`       | `<a role="menuitem">`: a link.                                                                                                                       |
+| `CheckboxItem`   | `<button type="button" role="menuitemcheckbox" aria-checked="…">`                                                                                    |
+| `Separator`      | `<div role="separator">`                                                                                                                             |
+| `Group`          | `<div role="group">`, labelled by its `GroupLabel`.                                                                                                  |
+| `GroupLabel`     | `<div role="presentation">`, which names its `Group` or `RadioGroup`.                                                                                |
+| `RadioGroup`     | `<div role="group">` of radio items, one of them checked.                                                                                            |
+| `RadioItem`      | `<button type="button" role="menuitemradio" value="…" aria-checked="…">`                                                                             |
+| `SubmenuRoot`    | `<lu-menu>` for a submenu, inside a `Popup`.                                                                                                         |
+| `SubmenuTrigger` | `<button type="button" role="menuitem" popovertarget="…" aria-haspopup="menu">`: an item of the parent menu.                                         |
+
+The trigger and the popup sit inside `Root`; a submenu's trigger and popup sit inside its
+`SubmenuRoot`, which sits in the parent's `Popup`, as deep as you like. Items, groups and separators
+go inside a `Popup`, radio items inside a `RadioGroup`.
+
+## API
+
+### Menu.Root
+
+| Prop           | Type                      | Default |                                                                                                                                              |
+| -------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Opens or closes the menu when it changes, in the browser. Server HTML always starts closed: a popover opens only from its trigger or script. |
+| `onOpenChange` | `(open: boolean) => void` |         | Called after the menu opens or closes, whatever did it: the trigger, a key, a click outside, an item that ran, `open`.                       |
+| `bind:open`    | `Signal<boolean>`         |         | Stands in for `open` and `onOpenChange`: the signal opens and closes the menu, and follows it.                                               |
+
+Without `open`, `onOpenChange` or `bind:open` the menu keeps its own state. A menu opened from the
+server HTML before its island hydrated stays open, and `onOpenChange(true)` tells the signal.
+`Menu.SubmenuRoot` takes the same props, for its submenu.
+
+### Menu.Popup
+
+| Prop          | Type                                                                       | Default                                 |                                                                      |
+| ------------- | -------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- |
+| `side`        | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"`, `"inline-end"` in a submenu | The trigger's side the popup goes on. It flips when it does not fit. |
+| `align`       | `"start" \| "center" \| "end"`                                             | `"start"`                               | How the popup aligns with the trigger along that side.               |
+| `sideOffset`  | `number`                                                                   |                                         | The gap between the trigger and the popup, in CSS pixels.            |
+| `alignOffset` | `number`                                                                   |                                         | A shift along the side, away from the aligned edge, in CSS pixels.   |
+
+### Menu.Item
+
+| Prop           | Type                          | Default |                                                                                                             |
+| -------------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `onClick`      | `(event: MouseEvent) => void` |         | Runs the command, on a click, Enter or Space. The menu has closed and focus is back on the trigger by then. |
+| `disabled`     | `boolean`                     | `false` | Unavailable (`aria-disabled`): the arrows and typeahead still reach it, but it does not run.                |
+| `label`        | `string`                      |         | The text typeahead matches, when the item's text content is not it.                                         |
+| `closeOnClick` | `boolean`                     | `true`  | Whether running the item closes the menu.                                                                   |
+
+### Menu.LinkItem
+
+| Prop           | Type      | Default |                                                                                                                                                                              |
+| -------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `href`         | `string`  |         | Where the link goes. A Ctrl, Cmd or Shift click, or a link with `download`, leaves the menu open.                                                                            |
+| `label`        | `string`  |         | The text typeahead matches.                                                                                                                                                  |
+| `closeOnClick` | `boolean` | `true`  | Whether following the link closes the menu. Base UI keeps it open by default; here it closes, like the other items, since a layout's menu outlives a client-side navigation. |
+
+### Menu.CheckboxItem
+
+| Prop              | Type                         | Default |                                                                              |
+| ----------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `checked`         | `boolean`                    |         | Checks or unchecks the item when it changes. Pair it with `onCheckedChange`. |
+| `defaultChecked`  | `boolean`                    | `false` | Whether it starts checked when `checked` is left out.                        |
+| `onCheckedChange` | `(checked: boolean) => void` |         | Called after a click, Enter or Space checks or unchecks it.                  |
+| `bind:checked`    | `Signal<boolean>`            |         | Stands in for `checked` and `onCheckedChange`.                               |
+| `disabled`        | `boolean`                    | `false` | Unavailable: it can be highlighted, but it does not toggle.                  |
+| `label`           | `string`                     |         | The text typeahead matches.                                                  |
+| `closeOnClick`    | `boolean`                    | `false` | Whether toggling it closes the menu.                                         |
+
+### Menu.RadioGroup
+
+| Prop            | Type                      | Default |                                                                                        |
+| --------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------- |
+| `value`         | `string`                  |         | Checks the radio item with this `value` when it changes. Pair it with `onValueChange`. |
+| `defaultValue`  | `string`                  |         | The radio item checked at first when `value` is left out.                              |
+| `onValueChange` | `(value: string) => void` |         | Called with the `value` of the radio item a click, Enter or Space checks.              |
+| `bind:value`    | `Signal<string>`          |         | Stands in for `value` and `onValueChange`.                                             |
+
+### Menu.RadioItem
+
+| Prop           | Type      | Default |                                                            |
+| -------------- | --------- | ------- | ---------------------------------------------------------- |
+| `value`        | `string`  |         | Required: the value its group takes when it is checked.    |
+| `disabled`     | `boolean` | `false` | Unavailable: it can be highlighted, but it is not checked. |
+| `label`        | `string`  |         | The text typeahead matches.                                |
+| `closeOnClick` | `boolean` | `false` | Whether checking it closes the menu.                       |
+
+### Menu.SubmenuTrigger
+
+| Prop       | Type      | Default |                                                                    |
+| ---------- | --------- | ------- | ------------------------------------------------------------------ |
+| `disabled` | `boolean` | `false` | Unavailable: it can be highlighted, but its submenu does not open. |
+| `label`    | `string`  |         | The text typeahead matches in the parent menu.                     |
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through. Your props override the defaults (`type`, `tabindex`,
+`aria-labelledby`, `data-side`, `data-align`). A `Trigger`'s (or `SubmenuTrigger`'s) `id` names it,
+and the popup points at it; the `Popup` keeps its own `id`, which the trigger points at (see
+[Ids](README.md#ids)); the roles, `popovertarget` and the anchor stay the parts' own. Your `style` is kept, after the anchor's.
+
+- **`Trigger`**: `aria-expanded` is left to the browser in server HTML, where `popovertarget`
+  implies it, and set by the script once it runs. Disable it with the native `disabled`.
+- **`Group`** and **`RadioGroup`**: `aria-labelledby` points at their `GroupLabel` while one
+  renders; without one, give the group an `aria-label`.
+- **`Separator`**: a horizontal rule between items; `aria-orientation` passes through.
+
+**Differences from Base UI's Menu.** No `Portal`, `Positioner`, `Backdrop` or `Arrow`: the top
+layer and anchor positioning replace them, and the placement props go on `Popup`. The menu is not
+modal: the page keeps scrolling (the popup follows its trigger), and a press outside closes the
+menu and reaches what it lands on. Items render buttons, so they run with Enter and Space without
+the script. There are no indicator parts: style `[aria-checked="true"]`. Submenus open on hover
+after 100 ms, which no prop changes, and the root trigger does not open on hover.
+
+## Example
+
+A menu in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Menu } from "@lumiose/ui";
+
+export function ProjectMenu() {
+  return (
+    <Menu.Root>
+      <Menu.Trigger class="lu-button">Project</Menu.Trigger>
+      <Menu.Popup class="lu-menu">
+        <Menu.LinkItem href="/settings">Settings</Menu.LinkItem>
+        <Menu.LinkItem href="/members">Members</Menu.LinkItem>
+        <Menu.Separator />
+        <Menu.SubmenuRoot>
+          <Menu.SubmenuTrigger>Export</Menu.SubmenuTrigger>
+          <Menu.Popup class="lu-menu">
+            <Menu.LinkItem href="/export.csv" download>
+              CSV
+            </Menu.LinkItem>
+            <Menu.LinkItem href="/export.json" download>
+              JSON
+            </Menu.LinkItem>
+          </Menu.Popup>
+        </Menu.SubmenuRoot>
+      </Menu.Popup>
+    </Menu.Root>
+  );
+}
+```
+
+In an island, with a command, a checkbox item and a radio group bound to signals, and a status
+line that follows them. `bind:checked={wrap}` is short for `checked={wrap()}` plus
+`onCheckedChange={(next) => wrap.set(next)}`, and `bind:value` likewise.
+
+```tsx check
+import { Menu } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function EditorMenu() {
+  const formatted = signal(0);
+  const wrap = signal(true);
+  const indent = signal("spaces");
+  return (
+    <>
+      <Menu.Root>
+        <Menu.Trigger class="lu-button">View</Menu.Trigger>
+        <Menu.Popup class="lu-menu" align="end">
+          <Menu.Item onClick={() => formatted.set(formatted() + 1)}>Format document</Menu.Item>
+          <Menu.Item disabled>Fold all</Menu.Item>
+          <Menu.Separator />
+          <Menu.CheckboxItem bind:checked={wrap}>Wrap lines</Menu.CheckboxItem>
+          <Menu.RadioGroup bind:value={indent}>
+            <Menu.GroupLabel>Indent with</Menu.GroupLabel>
+            <Menu.RadioItem value="spaces">Spaces</Menu.RadioItem>
+            <Menu.RadioItem value="tabs">Tabs</Menu.RadioItem>
+          </Menu.RadioGroup>
+        </Menu.Popup>
+      </Menu.Root>
+      <p>
+        Formatted {formatted()} times, lines {wrap() ? "wrap" : "do not wrap"}, indent with{" "}
+        {indent()}.
+      </p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-menu` on every `Popup`, submenus included, and `lu-button` on
+the trigger. `lu-menu` styles the surface, the items (highlighted, disabled, focus ring), the
+checkbox and radio marks, the arrow of a submenu trigger, the separators and the group labels, and
+fades the popup in and out. Its colours come from the theme's `--lu-` properties
+([UI components](README.md#the-default-theme)), and it sets a 4px gap with `--lu-side-offset`.
+
+**With your own CSS**, style the parts through `class` and their state:
+
+- the popup: `:popover-open`, `data-side` and `data-align` (where it was asked to go);
+- the trigger and a submenu trigger: `[aria-expanded="true"]` while their menu is open;
+- items: `[data-highlighted]` on the item that has focus (by keyboard or pointer),
+  `:focus-visible`, `[aria-disabled="true"]`, and `[aria-checked="true"]` on checkbox and radio
+  items;
+- `[role="separator"]`, `[role="group"]` and a group label's `[role="presentation"]`.
+
+A starting point:
+
+```css
+.menu {
+  min-inline-size: 10rem;
+  padding: 0.25rem;
+  border: 1px solid #d4d4d8;
+  border-radius: 0.5rem;
+  box-shadow: 0 10px 30px -10px rgb(0 0 0 / 0.35);
+  --lu-side-offset: 4px;
+}
+.menu [role^="menuitem"] {
+  padding: 0.375rem 0.5rem;
+  border: 0;
+  border-radius: 0.25rem;
+  background: none;
+  font: inherit;
+}
+.menu [role^="menuitem"][data-highlighted] {
+  background: #f4f4f5;
+}
+.menu [role^="menuitem"][aria-disabled="true"] {
+  opacity: 0.5;
+}
+.menu [aria-checked="true"]::before {
+  content: "✓" / "";
+}
+```
+
+`@lumiose/ui/menu.css` holds what the menu needs to work, in the `lu.core` layer: `lu-menu` has
+no box, and the popup and its groups lay the items out in a column (`display: grid`, items
+`display: flex`). It imports the placement rules Menu shares with Popover and Tooltip: with CSS
+anchor positioning, a popup sits on its `data-side` and `data-align`, keeps the gaps of
+`--lu-side-offset` and `--lu-align-offset`, flips when it does not fit (a submenu tries the other
+side, then the other alignment, then below and above its trigger), shrinks to the room beside its
+trigger and scrolls when it fits nowhere (the focused item stays in view), and hides while its
+trigger is scrolled out of view (`data-anchor-hidden`, where the script runs). The `sideOffset` and `alignOffset` props set those two properties on the
+popup.
+
+## Keyboard and focus
+
+The [WAI-ARIA Menu Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/), with
+Base UI's behaviour where the pattern leaves a choice:
+
+| Key                       | Does                                                                                                                                   |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter, Space              | On the trigger: opens the menu on its first item. On an item: runs it (a link item too), or checks it. On a submenu trigger: opens it. |
+| Arrow Down, Arrow Up      | On the trigger: opens the menu on its first item, or on its last. In the menu: the next or previous item, looping.                     |
+| Home, End                 | The first or last item.                                                                                                                |
+| Arrow Right (Left in RTL) | On a submenu trigger, or the trigger of a menu in a vertical Toolbar or Menubar: opens it on its first item.                           |
+| Arrow Left (Right in RTL) | In a submenu: closes it, back on its trigger.                                                                                          |
+| A character               | The next item whose text starts with it; characters typed within 750 ms add up, and Space among them is text.                          |
+| Escape                    | Closes one level: the submenu on top, or the menu. Focus goes back to its trigger.                                                     |
+| Tab, Shift+Tab            | Close the whole menu. Tab moves on from the trigger; Shift+Tab stays on it.                                                            |
+
+- **On open**, focus moves to the first item that can run (Arrow Up: the last one). Opened by a
+  pointer, the popup itself takes focus and no item is highlighted until a key or the pointer
+  picks one.
+- **On close**, focus returns to the trigger without scrolling the page, after Escape, Tab, an
+  item that ran or a click outside on nothing focusable; a click on a button or a field outside
+  leaves focus there.
+- **Running an item** closes the whole menu and returns focus before the item's `onClick` runs,
+  so a handler that opens a dialog gets focus back on the trigger when it closes. Checkbox and
+  radio items stay open.
+- **Disabled items** (`aria-disabled`) stay in the arrow order and typeahead, as the pattern
+  asks, but do not run.
+- **The pointer** highlights the item under it, and leaving the items clears the highlight. A
+  mouse press on the trigger opens the menu at once: releasing it on an item runs the item, and
+  releasing it outside closes the menu. A submenu opens after the pointer rests 100 ms on its
+  trigger, and stays open while the pointer heads for it across other items.
+- **A click outside** closes the whole menu, submenus included, and a click in a menu closes the
+  submenus open from it. A right-click, a middle click or a second finger outside leaves the menu
+  open, as in Base UI.
+
+## Without JavaScript, and the client script
+
+The trigger opens the popup with `popovertarget`, and Escape or a click outside closes it: a menu
+in a server-rendered page opens before any script loads, and with none. Tab then moves through the
+items in order, and links work; commands, which run JavaScript, need it anyway. Escape in a
+submenu closes it, but the browser leaves focus on the page rather than on the submenu's trigger:
+Tab starts over from the top (the script returns focus to the trigger). `open`, `onOpenChange` and
+the `bind:` props need the component to run in the browser, in an island.
+
+The keyboard contract comes from a small script: a page that renders a `Menu` loads it once, as a
+4.0 kB (brotli) module without the Lumiose runtime, and islands bundle it. It defines `lu-menu`,
+which upgrades every menu on the page in place, and adds what the native popover lacks: focus on
+open and its return on close, the arrows, Home, End and typeahead, Escape one level at a time, Tab,
+submenus, checkbox and radio items, disabled items, `data-highlighted`, and the pointer behaviour
+above. It also takes over dismissal, with the model Menu shares with [Popover](popover.md) and
+[Combobox](combobox.md): the popup becomes a manual popover when the script opens it, and the
+script closes it on a click outside (main button only), on Escape, on a close request such as the
+Android back gesture, and when another popup opens outside it. Until it loads (or without JavaScript) the menu behaves as a
+native `popover="auto"` of buttons, which any click outside closes.
+
+The element is also an API of its own, for scripts and other frameworks:
+
+- `open`: a property; setting it to `true` or `false` opens or closes the menu.
+- `openchange`: an event (not bubbling, like `toggle`) with `detail.open`, after the menu opens or
+  closes.
+- `checkedchange`: a bubbling event that checkbox and radio items fire with `detail.checked` when
+  a click, Enter or Space checks or unchecks them.
+
+## Browser support
+
+- **Popovers and `popovertarget`**: Chrome and Edge 114, Firefox 125, Safari 17.
+- **CSS anchor positioning** places the popup: Chrome and Edge 125, Firefox 147, Safari 26
+  (partly; 27 fully). Elsewhere the client script places the popup with the same sides,
+  alignment, offsets and flips; without JavaScript it shows where the browser shows any popover,
+  in the middle of the viewport, and still works.
+- **`showPopover({ source })`**, which ties a popup the script opens to its trigger: Chrome 137,
+  Firefox 144, Safari 26. Older browsers open it the same way.
+- **`CloseWatcher`**, for the Android back gesture on a menu opened by a click, a tap or a key:
+  Chrome 126, Firefox 149. Escape is handled on its own in every browser, one layer at a time.
+- **Exit animations** that keep the popup in the top layer while it fades (`overlay`) are
+  Chromium-only.
+
+## Related
+
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Dialog](dialog.md): a menu item can open one; focus returns to the menu's trigger when it
+  closes.
+- [Islands](https://itsjavi.com/lumiose/docs/concepts/islands/): running a component in the
+  browser, for `open`, `onOpenChange` and the `bind:` props.
+- [JSX](https://itsjavi.com/lumiose/docs/concepts/jsx/): `bind:`, native events with `on:` and
+  `ref`.

package/docs/menubar.md

@@ -0,0 +1,186 @@
+# Menubar
+
+> A bar of menus, such as an app's File, Edit and View, after Base UI's Menubar and the WAI-ARIA menubar pattern: `Menu.Root`s inside `<lu-menubar role="menubar">`, whose triggers are the bar's items. Menu's popups, items, submenus and dismissal; the bar is one tab stop, the arrow keys move between its items and between open menus, and once a menu is open, hovering another item opens its menu instead. A 0.7 kB script on top of Menu's (4.7 kB together); without JavaScript each trigger opens its menu.
+
+```ts
+import { Menu, Menubar } from "@lumiose/ui"; // or "@lumiose/ui/menu" and "@lumiose/ui/menubar"
+import "@lumiose/ui/menubar.css"; // Menu's layout, and the bar's row (or column)
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Menubar>
+  <Menu.Root>
+    <Menu.Trigger />
+    <Menu.Popup>
+      <Menu.Item />
+      <Menu.SubmenuRoot>
+        <Menu.SubmenuTrigger />
+        <Menu.Popup>…</Menu.Popup>
+      </Menu.SubmenuRoot>
+    </Menu.Popup>
+  </Menu.Root>
+  <Menu.Root>…</Menu.Root>
+</Menubar>
+```
+
+| Part                       | Renders                                                                                                               |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `Menubar`                  | `<lu-menubar role="menubar" aria-orientation="…" data-orientation="…">`: a row of the menus (a column when vertical). |
+| `Menu.Root` inside it      | Menu's `<lu-menu>`, with `role="none"`.                                                                               |
+| `Menu.Trigger` inside it   | Menu's `<button popovertarget="…">`, with `role="menuitem"`: an item of the bar.                                      |
+| `Menu.Popup` and the items | As in [Menu](menu.md#anatomy).                                                                                        |
+
+A menubar's items are the triggers of its menus, each inside its `<lu-menu role="none">`, as in
+the APG example. Give the bar an `aria-label`.
+
+## API
+
+### Menubar
+
+| Prop          | Type                         | Default        |                                                                                                                                                     |
+| ------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Which way the items run. Vertical: Arrow Up and Down move between them, the arrow that points at a popup opens it, and popups go at the inline end. |
+| `loopFocus`   | `boolean`                    | `true`         | Whether the arrows wrap from the last item to the first and back.                                                                                   |
+
+Every other prop passes through to `<lu-menubar>`: `class`, `style`, `aria-label`, `data-*`.
+
+### The menus
+
+Each `Menu.Root` keeps [Menu's props](menu.md#api): `open`, `onOpenChange` and `bind:open` per
+menu, and its items' `bind:checked` and `bind:value`. `disabled` on a `Menu.Trigger` takes the menu
+out of the bar: no focus, no opening.
+
+**Differences from Base UI's Menubar.** No `modal` (the page stays scrollable and usable while a
+menu is open) and no `disabled` on the bar: disable each trigger instead. No `render`.
+
+## Example
+
+An editor's menus in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Menu, Menubar } from "@lumiose/ui";
+
+export function EditorMenus() {
+  return (
+    <Menubar aria-label="Editor" class="lu-menubar">
+      <Menu.Root>
+        <Menu.Trigger>File</Menu.Trigger>
+        <Menu.Popup class="lu-menu">
+          <Menu.Item>New file</Menu.Item>
+          <Menu.Item>Open…</Menu.Item>
+          <Menu.SubmenuRoot>
+            <Menu.SubmenuTrigger>Share</Menu.SubmenuTrigger>
+            <Menu.Popup class="lu-menu">
+              <Menu.Item>Email</Menu.Item>
+              <Menu.Item>Copy link</Menu.Item>
+            </Menu.Popup>
+          </Menu.SubmenuRoot>
+        </Menu.Popup>
+      </Menu.Root>
+      <Menu.Root>
+        <Menu.Trigger>Edit</Menu.Trigger>
+        <Menu.Popup class="lu-menu">
+          <Menu.Item>Undo</Menu.Item>
+          <Menu.Item>Redo</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Menu.Root>
+        <Menu.Trigger>View</Menu.Trigger>
+        <Menu.Popup class="lu-menu">
+          <Menu.RadioGroup defaultValue="100">
+            <Menu.GroupLabel>Zoom</Menu.GroupLabel>
+            <Menu.RadioItem value="75">75%</Menu.RadioItem>
+            <Menu.RadioItem value="100">100%</Menu.RadioItem>
+          </Menu.RadioGroup>
+        </Menu.Popup>
+      </Menu.Root>
+    </Menubar>
+  );
+}
+```
+
+In an island, a checkbox item bound to a signal and an item that writes a status line:
+
+```tsx check
+import { Menu, Menubar } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function DocumentMenus() {
+  const wrap = signal(false);
+  const status = signal("Not saved yet");
+  return (
+    <>
+      <Menubar aria-label="Document" class="lu-menubar">
+        <Menu.Root>
+          <Menu.Trigger>File</Menu.Trigger>
+          <Menu.Popup class="lu-menu">
+            <Menu.Item onClick={() => status.set("Saved")}>Save</Menu.Item>
+          </Menu.Popup>
+        </Menu.Root>
+        <Menu.Root>
+          <Menu.Trigger>Edit</Menu.Trigger>
+          <Menu.Popup class="lu-menu">
+            <Menu.CheckboxItem bind:checked={wrap}>Word wrap</Menu.CheckboxItem>
+          </Menu.Popup>
+        </Menu.Root>
+      </Menubar>
+      <p>
+        {status()}; word wrap is {wrap() ? "on" : "off"}
+      </p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-menubar` on `Menubar` and `lu-menu` on each `Menu.Popup`: a
+bordered bar of the triggers, the one whose menu is open filled, with a focus ring.
+
+**With your own CSS**, style the bar through `class` and `[data-orientation]`, the items as
+`lu-menubar > lu-menu > [role="menuitem"]` with `[aria-expanded="true"]` for the open one, and
+`[data-has-submenu-open]` on the bar while a menu is open. The popups and items are
+[Menu's](menu.md#styling).
+
+`@lumiose/ui/menubar.css` holds Menu's rules and, in the `lu.core` layer, makes `<lu-menubar>` a
+flex row (a column when vertical); each `<lu-menu>` adds no box.
+
+## Keyboard and focus
+
+| Key                            | Does                                                                                                                             |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Tab, Shift+Tab                 | Enter and leave the bar, which is one tab stop: the item focused last (the first, if that one goes, is disabled or hidden).      |
+| Arrow Right, Arrow Left        | On an item: the next or previous item (Down and Up when vertical; swapped right to left). An open menu follows to the next item. |
+| Home, End                      | The first or last item.                                                                                                          |
+| A letter                       | The next item whose label starts with it.                                                                                        |
+| Arrow Down, Enter, Space       | Open the item's menu on its first item (Arrow Up: the last one). Vertical: the arrow that points at the popup opens it.          |
+| Arrow Right, Arrow Left (menu) | On an item that opens no submenu: close the menu and open the next or previous one. Vertical: the arrow pointing back closes it. |
+| Escape                         | Closes the menu (a submenu first) and returns to its item.                                                                       |
+
+- **The pointer**: a click opens or closes a menu; once one is open, hovering another item opens
+  its menu instead. Inside a menu, Menu's rules apply: hover highlights, submenus open on hover.
+- **Focus** returns to the item when its menu closes, as in Menu. Disabled triggers are skipped.
+
+## Without JavaScript, and the client script
+
+Each trigger opens its menu through `popovertarget`, and the browser light-dismisses it: without
+JavaScript every trigger is a tab stop, and the menus open with Enter, Space or a click.
+
+A page that renders a `Menubar` loads Menu's script and a 0.7 kB (brotli) one of its own, 4.7 kB
+together, without the Lumiose runtime; islands bundle them. The menubar's script makes the bar one
+tab stop once the page has loaded, and adds the arrow keys between items and menus and the hover
+switching. Each menu stays Menu's: its keys, items, submenus and dismissal.
+
+## Browser support
+
+As for [Menu](menu.md#browser-support): popovers everywhere current, CSS anchor positioning in
+Chrome, Edge, Firefox 147 and Safari 26 (elsewhere the script places the popups).
+
+## Related
+
+- [Menu](menu.md): one menu, opened by a button.
+- [Navigation Menu](navigation-menu.md): site navigation with panels of links.
+- [UI components](README.md): the approach, styling and the other components.