remix 3.0.0-beta.4 → 3.0.0-beta.6

package/src/ui/combobox/primitives/README.md

@@ -0,0 +1,194 @@
+# combobox
+
+`Combobox` is the input-first popup value picker for `remix/ui/combobox`.
+
+Use it when the user should type draft text, filter a popup list, and still commit one stable form value. If you just need a button-triggered picker, use `Select` instead.
+
+## Component Usage
+
+```tsx
+import { css, type Handle } from 'remix/ui'
+import { Combobox, ComboboxOption } from 'remix/ui/combobox'
+import { onComboboxChange } from 'remix/ui/combobox/primitives'
+
+let airports = [
+  {
+    label: 'Los Angeles International',
+    searchValue: ['lax', 'los angeles', 'los angeles international'],
+    value: 'LAX',
+  },
+  {
+    label: 'John F. Kennedy International',
+    searchValue: ['jfk', 'new york', 'john f. kennedy international'],
+    value: 'JFK',
+  },
+] as const
+
+export default function AirportField(handle: Handle) {
+  let value: string | null = null
+
+  return () => (
+    <div mix={root}>
+      <Combobox
+        inputId="airport"
+        mix={onComboboxChange((event) => {
+          value = event.value
+          void handle.update()
+        })}
+        name="airport"
+        placeholder="Search airports or codes"
+      >
+        {airports.map((airport) => (
+          <ComboboxOption
+            key={airport.value}
+            label={airport.label}
+            searchValue={airport.searchValue}
+            value={airport.value}
+          />
+        ))}
+      </Combobox>
+
+      <p>{`value=${value ?? 'null'}`}</p>
+    </div>
+  )
+}
+
+let root = css({
+  display: 'grid',
+  gap: '8px',
+})
+```
+
+## Primitive Usage
+
+Use the lower-level primitives when app code owns the input, popover, list, and option markup:
+
+```tsx
+import * as combobox from 'remix/ui/combobox/primitives'
+import { inputStyle, listStyle, optionStyle, popoverStyle } from './combobox.styles'
+
+let frameworks = [
+  { label: 'Remix', searchValue: ['remix', 'rmx'], value: 'remix' },
+  { label: 'React Router', value: 'react-router' },
+]
+
+export function PrimitiveCombobox() {
+  return (
+    <combobox.Context name="framework">
+      <input mix={[inputStyle, combobox.input()]} placeholder="Search frameworks" />
+      <div mix={[popoverStyle, combobox.popover()]}>
+        <div mix={[listStyle, combobox.list()]}>
+          {frameworks.map((option) => (
+            <div key={option.value} mix={[optionStyle, combobox.option(option)]}>
+              {option.label}
+            </div>
+          ))}
+        </div>
+      </div>
+      <input mix={combobox.hiddenInput()} />
+    </combobox.Context>
+  )
+}
+```
+
+## `remix/ui/combobox`
+
+### `Combobox`
+
+The convenience component.
+
+- Renders the text input, popover surface, listbox root, and hidden form input.
+- Dispatches a bubbled custom event that `onComboboxChange(...)` listens for when the committed value changes.
+- Accepts `children`, `defaultValue`, `disabled`, `inputId`, `name`, `placeholder`, and root `div` props.
+
+### `ComboboxOption`
+
+The default option row for `Combobox`.
+
+- Uses the shared listbox option visuals.
+- Accepts `label`, `value`, optional `searchValue`, and optional `disabled`.
+- Renders `children` when provided, otherwise renders `label`.
+- `searchValue` can be a string or string array for aliases like airport codes, abbreviations, or alternate labels.
+
+### Style and Prop Exports
+
+- `inputStyle`: default combobox input style.
+- `popoverStyle`: default combobox popover behavior style.
+- `ComboboxProps` and `ComboboxOptionProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/combobox/primitives`
+
+### `onComboboxChange(...)`
+
+The listener mixin from `remix/ui/combobox/primitives` for bubbled committed-value changes.
+
+The event object includes:
+
+- `event.value`: the committed value or `null`
+- `event.label`: the committed option label or `null`
+- `event.optionId`: the generated option id or `null`
+- `ComboboxChangeEvent`: the event class dispatched for committed value changes.
+
+### `combobox.Context`
+
+The lower-level coordinator from `remix/ui/combobox/primitives` for custom combobox composition.
+
+It wraps the shared `popover` and `listbox` contexts and owns the draft text, committed value, popup state, and selection timing.
+
+### `combobox.input()`
+
+Turns the host input into the combobox input.
+
+- Keeps focus on the input during list navigation and pointer selection.
+- Wires `role="combobox"`, `aria-expanded`, `aria-controls`, and `aria-activedescendant`.
+- Opens from typing, click, and arrow-key navigation.
+
+### `combobox.popover()`
+
+Turns the host into the combobox popover surface.
+
+- Uses the shared popover primitive.
+- Keeps anchor clicks inside the session so the input stays interactive while open.
+- Applies the combobox open/close reason contract used by `popoverStyle`.
+
+### `combobox.list()`
+
+Turns the host into the popup listbox root and applies the generated list id.
+
+### `combobox.option(options)`
+
+Registers one option with the combobox and listbox layers.
+
+- Accepts `label`, `value`, optional `searchValue`, and optional `disabled`.
+- Hides non-matching options from the current draft filter.
+- Prevents pointer selection from blurring the input before the click commits.
+
+### `combobox.hiddenInput()`
+
+Mirrors the committed value into a hidden input for forms.
+
+Apply it to an `<input type="hidden" />` inside the same `combobox.Context`.
+
+### Primitive Types
+
+- `ComboboxOpenStrategy`: initial active-option strategy when the popup opens.
+- `ComboboxHandle`: imperative ref for reading or updating the combobox value and draft label.
+- `ComboboxContextProps`, `ComboboxProps`, `ComboboxOptionOptions`, and `ComboboxOptionProps`: primitive prop and option types for custom composition.
+
+## Behavior Notes
+
+- Typing opens the popup in hint mode when there are matches.
+- If typing leaves no matches, the popup closes immediately without the navigation fade-out.
+- Selecting from the list flashes the option, then closes the popup and finally commits the visible input label.
+- Typing clears the committed value immediately; the hidden form value becomes empty until the user commits again.
+- Blur commits an exact `label` or `searchValue` match. A non-matching blur clears the draft text and committed value.
+- `Escape` keeps exact-match draft text but clears non-matching draft text and selection.
+- Disabled options can stay visible in filtered results, but they are skipped by keyboard navigation and selection.
+
+## When To Use Something Else
+
+Use `Select` when you want the ordinary button-triggered single-select control.
+
+Use `listbox` when you need listbox semantics without an editable text input.
+
+Use `popover` directly for custom floating panels that are not value-picking controls.

package/src/ui/combobox/primitives.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui/combobox/primitives'

package/src/ui/dev/refresh.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui/dev/refresh'

package/src/ui/input/README.md

@@ -0,0 +1,52 @@
+# input
+
+`input` is a style mixin for text inputs. Use `input()` directly on standalone native inputs, or compose `input.root()` with `input.field()` when the input needs inline icons or controls.
+
+## Primitive Usage
+
+```tsx
+import input from 'remix/ui/input'
+
+function ProductFilters() {
+  return () => (
+    <div>
+      <input mix={input()} placeholder="Limit" />
+
+      <div mix={input.root()}>
+        <SearchIcon />
+        <input mix={input.field()} placeholder="Search and filter products" />
+      </div>
+    </div>
+  )
+}
+```
+
+Compose app-owned styles when a field needs local layout or adornments:
+
+```tsx
+import input from 'remix/ui/input'
+import { filterFieldStyle, filterRootStyle } from './filters.styles'
+
+function SearchFilter() {
+  return () => (
+    <div mix={[filterRootStyle, input.root()]}>
+      <SearchIcon />
+      <input mix={[filterFieldStyle, input.field()]} placeholder="Search" />
+    </div>
+  )
+}
+```
+
+## `remix/ui/input`
+
+- `input(options)`: styles a standalone native input. `size` may be `'md'` or `'lg'` and defaults to `'md'`.
+- `input.root(options)`: styles a flex input frame for inline icons, buttons, and a child input.
+- `input.field()`: styles the child native input inside `input.root()`.
+- `InputOptions`: accepts `size`.
+- `InputSize`: `'md'` or `'lg'`.
+
+## Behavior Notes
+
+- `input.root()` uses child selectors to size direct SVG children as presentational icons.
+- Put the icon before or after the field to control its visual position.
+- Focus and disabled states work through the native input; the root mirrors them with `:focus-within` and `:has(input:disabled)`.

package/src/ui/input.ts

@@ -0,0 +1,3 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui/input'
+export { default } from '@remix-run/ui/input'

package/src/ui/listbox/README.md

@@ -1,14 +1,14 @@
 # listbox
 
-`listbox` is a headless option-list primitive for controlled selection and highlighting. Use it under components like `select` and `combobox`, or directly when you need custom listbox markup.
+`listbox` is a headless option-list primitive for controlled selection and highlighting. Use it under components like select and combobox, or directly when you need custom listbox markup.
 
-## Usage
+## Primitive Usage
 
 ```tsx
 import type { Handle } from 'remix/ui'
-import { Glyph } from 'remix/ui/glyph'
 import * as listbox from 'remix/ui/listbox'
 import type { ListboxValue } from 'remix/ui/listbox'
+import { listStyle, optionStyle } from './listbox.styles'
 
 function FrameworkListbox(handle: Handle) {
   let value: ListboxValue = 'remix'
@@ -27,11 +27,10 @@ function FrameworkListbox(handle: Handle) {
         void handle.update()
       }}
     >
-      <div aria-label="Frameworks" tabIndex={0} mix={[listbox.listStyle, listbox.list()]}>
+      <div aria-label="Frameworks" tabIndex={0} mix={[listStyle, listbox.list()]}>
         {frameworks.map((option) => (
-          <div key={option.value} mix={[listbox.optionStyle, listbox.option(option)]}>
-            <Glyph mix={listbox.glyphStyle} name="check" />
-            <span mix={listbox.labelStyle}>{option.label}</span>
+          <div key={option.value} mix={[optionStyle, listbox.option(option)]}>
+            {option.label}
           </div>
         ))}
       </div>
@@ -52,6 +51,7 @@ Use `textValue` when the visible label is not the best string for typeahead sear
 ```tsx
 <div
   mix={[
+    optionStyle,
     listbox.option({
       label: 'Staging',
       textValue: 'beta',
@@ -63,42 +63,13 @@ Use `textValue` when the visible label is not the best string for typeahead sear
 </div>
 ```
 
-Use `ref` when a parent component needs imperative coordination with the current option registry.
-
-```tsx
-import type { ListboxRef } from 'remix/ui/listbox'
-
-let listboxRef: ListboxRef | undefined
-
-function selectLastOption() {
-  listboxRef?.navigateLast()
-  void listboxRef?.selectActive()
-}
-
-;<listbox.Context
-  value={value}
-  activeValue={activeValue}
-  ref={(ref) => {
-    listboxRef = ref
-  }}
-  onSelect={(nextValue) => {
-    value = nextValue
-  }}
-  onHighlight={(nextActiveValue) => {
-    activeValue = nextActiveValue
-  }}
->
-  {/* listbox markup */}
-</listbox.Context>
-```
-
-## `listbox.*`
+## `remix/ui/listbox`
 
 - `listbox.Context`: provider for controlled `value` and `activeValue`, option registration, selection, highlighting, optional ref access, `flashSelection`, `selectionFlashAttribute`, and `onSelectSettled`.
 - `listbox.list()`: mixin that wires `role="listbox"`, default `tabIndex={-1}`, keyboard navigation, focus scrolling, and typeahead highlighting.
 - `listbox.option(options)`: mixin that registers an option with required `label` and `value`, optional `disabled` and `textValue`, and wires `role="option"`, id, selected, disabled, highlighted, mouse, and click behavior.
-- `listStyle`, `optionStyle`, `glyphStyle`, and `labelStyle`: flat style mixins for standard listbox presentation.
 - `ListboxValue`: selected or active value, represented as `string | null`.
+- `ListboxContext` and `ListboxProviderProps`: provider context and prop types for controlled listboxes.
 - `ListboxOption`: option input shape with `label`, `value`, optional `disabled`, and optional `textValue`.
 - `ListboxRegisteredOption`: registered option metadata passed to callbacks and refs.
 - `ListboxRef`: live ref object exposing active/selected options, option navigation, search matching, scrolling, and selection helpers.
@@ -108,8 +79,5 @@ function selectLastOption() {
 - Selection and highlighting are controlled. `onSelect` and `onHighlight` notify the parent, but DOM state updates after the parent rerenders with new values.
 - Disabled options are skipped by keyboard navigation, typeahead, mouse movement, and click selection.
 - Arrow keys wrap through enabled options. `Home` and `End` move to enabled boundaries. `Enter` and Space select the active option.
-- Mouse movement highlights enabled options. `mouseleave` clears the highlight when leaving the active option.
-- `Tab` is prevented and highlights the first enabled option.
 - Typeahead highlights the next matching enabled option without selecting it and supports `textValue`.
-- Focus and keyboard navigation scroll the active option into view with nearest-edge alignment.
 - `flashSelection` applies `selectionFlashAttribute` for 60ms, delays `onSelectSettled`, and ignores new highlight/select interactions until the flash completes.

package/src/ui/menu/README.md

@@ -2,12 +2,13 @@
 
 `Menu` renders a button-triggered menu with keyboard navigation, checked items, selection events, and nested submenus. Use it for action menus and command groups.
 
-## Usage
+## Component Usage
 
 ```tsx
 import type { Handle } from 'remix/ui'
-import { Menu, MenuItem, Submenu, onMenuSelect } from 'remix/ui/menu'
-import { separatorStyle } from 'remix/ui/separator'
+import { css } from 'remix/ui'
+import { Menu, MenuItem, Submenu } from 'remix/ui/menu'
+import { onMenuSelect } from 'remix/ui/menu/primitives'
 
 export function ViewMenu(handle: Handle) {
   let wordWrap = false
@@ -50,6 +51,12 @@ export function ViewMenu(handle: Handle) {
     </Menu>
   )
 }
+
+let separatorStyle = css({
+  border: 0,
+  borderBlockStart: '1px solid #e5e7eb',
+  marginBlock: '4px',
+})
 ```
 
 Use `label` or `searchValue` when the rendered item content is not the text that should be used for event labels or typeahead.
@@ -71,8 +78,8 @@ Use `menuLabel` when the menu surface needs a different accessible label from th
 Use `menu.contextTrigger()` with `menu.Context` and `MenuList` when a menu should open at the right-click location of an element.
 
 ```tsx
-import * as menu from 'remix/ui/menu'
 import { MenuItem, MenuList } from 'remix/ui/menu'
+import * as menu from 'remix/ui/menu/primitives'
 
 export function FileContextMenu(handle: Handle) {
   return () => (
@@ -89,20 +96,54 @@ export function FileContextMenu(handle: Handle) {
 }
 ```
 
-Attach `onMenuSelect(...)` to `MenuList` or a shared ancestor when using lower-level context menu composition.
+Attach `onMenuSelect(...)` from `remix/ui/menu/primitives` to `MenuList` or a shared ancestor when using lower-level context menu composition.
+
+## Primitive Usage
+
+Use only the lower-level primitives when app code owns the trigger, surface, and item markup:
+
+```tsx
+import * as menu from 'remix/ui/menu/primitives'
+import { itemStyle, listStyle, popoverStyle, triggerStyle } from './menu.styles'
+
+export function PrimitiveMenu() {
+  return (
+    <menu.Context label="Project actions">
+      <button mix={[triggerStyle, menu.trigger()]} type="button">
+        Actions
+      </button>
+      <div mix={[popoverStyle, menu.popover()]}>
+        <div mix={[listStyle, menu.list()]}>
+          <div mix={[itemStyle, menu.item({ name: 'rename' })]}>Rename</div>
+          <div mix={[itemStyle, menu.item({ disabled: true, name: 'archive' })]}>Archive</div>
+        </div>
+      </div>
+    </menu.Context>
+  )
+}
+```
 
-## `menu.*`
+## `remix/ui/menu`
 
 - `Menu`: composed trigger, popover, and list component for the common menu case.
-- `MenuItem`: menu item wrapper. Supports regular, checkbox, and radio item roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
-- `Submenu`: nested menu wrapper with its own trigger and child menu surface.
-- `MenuList`: lower-level list wrapper for custom composition.
+- `MenuItem`: menu item component. Supports regular, checkbox, and radio item roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `Submenu`: nested menu component with its own trigger and child menu surface.
+- `MenuList`: lower-level styled list component for custom composition inside `menu.Context`.
+- `buttonStyle`, `popoverStyle`, `listStyle`, `itemStyle`, `itemSlotStyle`, `itemLabelStyle`, `itemIndicatorStyle`, and `triggerIndicatorStyle`: flat style mixins used by the component markup.
+- `MenuProps`, `MenuItemProps`, `MenuListProps`, and `SubmenuProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/menu/primitives`
+
+- `Context`: lower-level provider for custom menu composition.
+- `trigger()`: wires a button-style trigger to open the root menu.
+- `contextTrigger()`: opens the root menu from a `contextmenu` event at pointer coordinates, or from keyboard context-menu shortcuts.
+- `popover()`: wires the menu popover surface.
+- `list()`: wires the menu list root, focus handling, keyboard navigation, and typeahead.
+- `item(...)`: registers one menu item. Supports regular, checkbox, and radio roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `submenuTrigger(...)`: registers a menu item that opens a child menu.
 - `onMenuSelect(...)`: event mixin for the bubbling `MenuSelectEvent`.
-- `MenuSelectEvent`: bubbling event class whose `item` describes the selected item.
-- `MenuSelectItem`: selected item shape with `checked`, `id`, `label`, `name`, `type`, and `value`.
-- `menu.Context`, `menu.trigger()`, `menu.contextTrigger()`, `menu.popover()`, `menu.list()`, `menu.item(...)`, and `menu.submenuTrigger(...)`: lower-level composition primitives.
-- `buttonStyle`, `popoverStyle`, `listStyle`, `itemStyle`, `itemSlotStyle`, `itemLabelStyle`, `itemGlyphStyle`, and `triggerGlyphStyle`: flat style mixins used by the wrappers.
-- `MenuProps`, `MenuItemProps`, `MenuListProps`, `MenuProviderProps`, `MenuTriggerOptions`, `MenuContextTriggerOptions`, `MenuItemOptions`, and `SubmenuProps`: public TypeScript props and option types.
+- `MenuSelectEvent`: bubbling event whose `item` describes the selected item.
+- `MenuSelectItem`, `MenuProviderProps`, `MenuTriggerOptions`, `MenuContextTriggerOptions`, `MenuItemOptions`, and `SubmenuTriggerOptions`: public TypeScript event, prop, and option types for the primitives.
 
 ## Behavior Notes
 

package/src/ui/menu/primitives/README.md

@@ -0,0 +1,161 @@
+# menu
+
+`Menu` renders a button-triggered menu with keyboard navigation, checked items, selection events, and nested submenus. Use it for action menus and command groups.
+
+## Component Usage
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { css } from 'remix/ui'
+import { Menu, MenuItem, Submenu } from 'remix/ui/menu'
+import { onMenuSelect } from 'remix/ui/menu/primitives'
+
+export function ViewMenu(handle: Handle) {
+  let wordWrap = false
+  let density = 'comfortable'
+
+  return () => (
+    <Menu
+      label="View"
+      mix={onMenuSelect((event) => {
+        if (event.item.name === 'wordWrap') {
+          wordWrap = event.item.checked ?? false
+        } else if (event.item.name === 'density' && event.item.value) {
+          density = event.item.value
+        }
+
+        void handle.update()
+      })}
+    >
+      <MenuItem checked={wordWrap} name="wordWrap" type="checkbox">
+        Word wrap
+      </MenuItem>
+      <MenuItem disabled name="minimap">
+        Minimap
+      </MenuItem>
+      <hr mix={separatorStyle} />
+      <MenuItem checked={density === 'compact'} name="density" type="radio" value="compact">
+        Compact
+      </MenuItem>
+      <MenuItem checked={density === 'comfortable'} name="density" type="radio" value="comfortable">
+        Comfortable
+      </MenuItem>
+      <Submenu label="Zoom">
+        <MenuItem name="zoomIn" value="zoom-in">
+          Zoom in
+        </MenuItem>
+        <MenuItem name="zoomOut" value="zoom-out">
+          Zoom out
+        </MenuItem>
+      </Submenu>
+    </Menu>
+  )
+}
+
+let separatorStyle = css({
+  border: 0,
+  borderBlockStart: '1px solid #e5e7eb',
+  marginBlock: '4px',
+})
+```
+
+Use `label` or `searchValue` when the rendered item content is not the text that should be used for event labels or typeahead.
+
+```tsx
+<MenuItem label="Open command palette" name="commandPalette" searchValue="palette">
+  Command palette
+</MenuItem>
+```
+
+Use `menuLabel` when the menu surface needs a different accessible label from the visible trigger.
+
+```tsx
+<Menu label="..." menuLabel="Project actions">
+  <MenuItem name="rename">Rename project</MenuItem>
+</Menu>
+```
+
+Use `menu.contextTrigger()` with `menu.Context` and `MenuList` when a menu should open at the right-click location of an element.
+
+```tsx
+import { MenuItem, MenuList } from 'remix/ui/menu'
+import * as menu from 'remix/ui/menu/primitives'
+
+export function FileContextMenu(handle: Handle) {
+  return () => (
+    <menu.Context label="File actions">
+      <div mix={menu.contextTrigger()} tabIndex={0}>
+        File.txt
+      </div>
+      <MenuList>
+        <MenuItem name="rename">Rename</MenuItem>
+        <MenuItem name="delete">Delete</MenuItem>
+      </MenuList>
+    </menu.Context>
+  )
+}
+```
+
+Attach `onMenuSelect(...)` from `remix/ui/menu/primitives` to `MenuList` or a shared ancestor when using lower-level context menu composition.
+
+## Primitive Usage
+
+Use only the lower-level primitives when app code owns the trigger, surface, and item markup:
+
+```tsx
+import * as menu from 'remix/ui/menu/primitives'
+import { itemStyle, listStyle, popoverStyle, triggerStyle } from './menu.styles'
+
+export function PrimitiveMenu() {
+  return (
+    <menu.Context label="Project actions">
+      <button mix={[triggerStyle, menu.trigger()]} type="button">
+        Actions
+      </button>
+      <div mix={[popoverStyle, menu.popover()]}>
+        <div mix={[listStyle, menu.list()]}>
+          <div mix={[itemStyle, menu.item({ name: 'rename' })]}>Rename</div>
+          <div mix={[itemStyle, menu.item({ disabled: true, name: 'archive' })]}>Archive</div>
+        </div>
+      </div>
+    </menu.Context>
+  )
+}
+```
+
+## `remix/ui/menu`
+
+- `Menu`: composed trigger, popover, and list component for the common menu case.
+- `MenuItem`: menu item component. Supports regular, checkbox, and radio item roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `Submenu`: nested menu component with its own trigger and child menu surface.
+- `MenuList`: lower-level styled list component for custom composition inside `menu.Context`.
+- `buttonStyle`, `popoverStyle`, `listStyle`, `itemStyle`, `itemSlotStyle`, `itemLabelStyle`, `itemIndicatorStyle`, and `triggerIndicatorStyle`: flat style mixins used by the component markup.
+- `MenuProps`, `MenuItemProps`, `MenuListProps`, and `SubmenuProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/menu/primitives`
+
+- `Context`: lower-level provider for custom menu composition.
+- `trigger()`: wires a button-style trigger to open the root menu.
+- `contextTrigger()`: opens the root menu from a `contextmenu` event at pointer coordinates, or from keyboard context-menu shortcuts.
+- `popover()`: wires the menu popover surface.
+- `list()`: wires the menu list root, focus handling, keyboard navigation, and typeahead.
+- `item(...)`: registers one menu item. Supports regular, checkbox, and radio roles through `type`, `checked`, `name`, `value`, `label`, `disabled`, and `searchValue`.
+- `submenuTrigger(...)`: registers a menu item that opens a child menu.
+- `onMenuSelect(...)`: event mixin for the bubbling `MenuSelectEvent`.
+- `MenuSelectEvent`: bubbling event whose `item` describes the selected item.
+- `MenuSelectItem`, `MenuProviderProps`, `MenuTriggerOptions`, `MenuContextTriggerOptions`, `MenuItemOptions`, and `SubmenuTriggerOptions`: public TypeScript event, prop, and option types for the primitives.
+
+## Behavior Notes
+
+- Click opens the root menu and focuses the list; clicking the trigger again closes it and restores focus.
+- `menu.contextTrigger()` opens the root menu from a `contextmenu` event at the pointer coordinates and supports keyboard opening with the Context Menu key or Shift+F10.
+- `ArrowDown` opens from the trigger at the first enabled item. `ArrowUp` opens at the last enabled item. Enter and Space open the menu with focus on the list.
+- Keyboard navigation skips disabled items and does not wrap past the first or last enabled item.
+- `Home` and `End` move to the first and last enabled item. Enter and Space activate the highlighted item.
+- Printable keys use typeahead. Typeahead matches `searchValue` when provided and otherwise uses the item label.
+- Submenus open with `ArrowRight`, close with `ArrowLeft`, and are anchored to the submenu trigger with `right-start` placement.
+- Pointer movement highlights enabled items. Submenus open after a short focus/pointer delay and use hover aim so they stay open while moving toward the child surface.
+- Selecting a regular item flashes that item. Selecting a checkbox or radio item flashes the committed checked state.
+- Selection dispatches one bubbled `MenuSelectEvent`, closes the full menu tree, and restores focus to the root trigger.
+- The composed `Menu` re-dispatches selection from its trigger so handlers on the `Menu` button and shared ancestors see the event once.
+- `menuLabel`, `Submenu.menuLabel`, and `Submenu.listProps` let composed menus label and customize menu surfaces separately from trigger content.

package/src/ui/menu/primitives.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/ui/menu/primitives'