remix 3.0.0-beta.4 → 3.0.0-beta.5

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/{dist/ui/scroll-lock.js → src/ui/menu/primitives.ts}

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

package/src/ui/popover/README.md

@@ -1,16 +1,15 @@
-# Popover
+# popover
 
 `popover` is a low-level primitive for anchored, dismissible floating panels.
 
-Use it for custom surfaces like filters, inspectors, and view options. Higher-level widgets like `menu`, `select`, and `combobox` should build on top of it instead of exposing raw `popover.*` mixins directly.
+Use it for custom surfaces like filters, inspectors, and view options. Higher-level widgets like menu, select, and combobox should build on top of it instead of exposing raw `popover.*` mixins directly.
 
-## Usage
+## Primitive Usage
 
 ```tsx
-import { css, on, type Handle } from 'remix/ui'
-import { Button } from 'remix/ui/button'
-import { Glyph } from 'remix/ui/glyph'
-import { popover } from 'remix/ui/popover'
+import { on, type Handle } from 'remix/ui'
+import * as popover from 'remix/ui/popover'
+import { panelStyle } from './popover.styles'
 
 export function ViewOptions(handle: Handle) {
   let open = false
@@ -27,21 +26,20 @@ export function ViewOptions(handle: Handle) {
 
   return () => (
     <popover.Context>
-      <Button
-        endIcon={<Glyph name="chevronDown" />}
+      <button
         mix={[
           popover.anchor({ placement: 'bottom-end' }),
           popover.focusOnHide(),
           on('click', openPopover),
         ]}
-        tone="secondary"
+        type="button"
       >
         View options
-      </Button>
+      </button>
 
       <div
         mix={[
-          popover.surfaceStyle,
+          panelStyle,
           popover.surface({
             open,
             onHide() {
@@ -50,23 +48,17 @@ export function ViewOptions(handle: Handle) {
           }),
         ]}
       >
-        <div mix={popover.contentStyle}>
-          <Button mix={[popover.focusOnShow(), on('click', closePopover)]} tone="ghost">
-            Close
-          </Button>
-          <div mix={panelBody}>Panel content</div>
-        </div>
+        <button mix={[popover.focusOnShow(), on('click', closePopover)]} type="button">
+          Close
+        </button>
+        <div>Panel content</div>
       </div>
     </popover.Context>
   )
 }
-
-let panelBody = css({
-  padding: '12px',
-})
 ```
 
-## `popover.*`
+## `remix/ui/popover`
 
 ### `popover.Context`
 
@@ -76,10 +68,6 @@ Provides shared coordination for one popover instance. Render the anchor, any fo
 
 Registers the host element as the anchor for the current popover surface.
 
-- Accepts standard `AnchorOptions`.
-- The stored anchor controls where the surface is positioned when it opens.
-- Apply it to the button or other element the surface should attach to.
-
 ### `popover.surface({ open, onHide, ... })`
 
 Turns the host into the controlled popover surface.
@@ -99,13 +87,12 @@ Registers the element that should receive focus when the popover opens.
 
 Registers the element that should receive focus again when the popover closes.
 
-### `popover.surfaceStyle`
-
-Default floating-surface presentation for popovers.
+### Primitive Types
 
-### `popover.contentStyle`
-
-Default inner scroll container for popover content.
+- `PopoverContext`: context object exposed by `popover.Context`.
+- `PopoverProps`: provider props for one popover instance.
+- `PopoverSurfaceOptions`: options accepted by `popover.surface(...)`.
+- `PopoverHideRequest`: hide request passed to `onHide`.
 
 ## Behavior Notes
 
@@ -114,9 +101,3 @@ Default inner scroll container for popover content.
 - `popover.focusOnShow()` wins on open when present.
 - `popover.focusOnHide()` is used on close by default when focus restoration is enabled.
 - `closeOnAnchorClick: false` keeps anchor clicks inside the current session, which is useful for input-driven popovers like comboboxes.
-
-## When To Use Something Else
-
-- Use `menu` for command surfaces.
-- Use `listbox` or `select` for committed value picking.
-- Use `combobox` for input-first popup selection.

package/src/ui/radio/README.md

@@ -0,0 +1,53 @@
+# radio
+
+`radio` is a style mixin for native radio inputs. It only owns radio visuals and the default `type="radio"` behavior for native `<input>` hosts.
+
+## Primitive Usage
+
+```tsx
+import radio from 'remix/ui/radio'
+
+function ShippingSpeed() {
+  return () => (
+    <fieldset>
+      <label>
+        <input defaultChecked mix={radio()} name="shipping-speed" value="standard" />
+        Standard
+      </label>
+      <label>
+        <input mix={radio({ size: 'lg' })} name="shipping-speed" value="express" />
+        Express
+      </label>
+    </fieldset>
+  )
+}
+```
+
+Compose app-owned styles around the primitive when a radio option needs local layout:
+
+```tsx
+import radio from 'remix/ui/radio'
+import { optionStyle } from './shipping.styles'
+
+function ShippingOption() {
+  return () => (
+    <label mix={optionStyle}>
+      <input mix={radio()} name="shipping-speed" value="overnight" />
+      Overnight
+    </label>
+  )
+}
+```
+
+## `remix/ui/radio`
+
+- `radio(options)`: style mixin for native radio inputs or radio-like hosts.
+- `RadioOptions`: accepts `size`.
+- `RadioSize`: `'md'` or `'lg'`. Defaults to `'md'`.
+
+## Behavior Notes
+
+- `radio()` returns a mixin descriptor, so it composes with other mixins in the host element's `mix` prop.
+- Native `<input>` hosts receive `type="radio"` unless an explicit `type` is provided.
+- Radio state is native browser behavior. The mixin also styles `aria-checked="true"` and `data-state="checked"` for custom hosts.
+- Disabled hosts use the shared disabled treatment through `disabled` or `aria-disabled="true"`.

package/src/ui/radio.ts

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

package/src/ui/select/README.md

@@ -2,10 +2,11 @@
 
 `Select` is a button-triggered popup value picker backed by `listbox` and `popover`. Use it when the user should choose one stable string value from a finite set.
 
-## Usage
+## Component Usage
 
 ```tsx
-import { Option, Select, onSelectChange } from 'remix/ui/select'
+import { Option, Select } from 'remix/ui/select'
+import { onSelectChange } from 'remix/ui/select/primitives'
 
 export function FrameworkSelect() {
   return (
@@ -44,34 +45,34 @@ Use `textValue` when closed-trigger typeahead should match a different string fr
 </Select>
 ```
 
+## Primitive Usage
+
 Use the lower-level primitives when the trigger or popup structure needs to be owned by another component. Keep the same provider, trigger, popover, list, option, and hidden-input relationship.
 
 ```tsx
 import type { Handle } from 'remix/ui'
-import * as button from 'remix/ui/button'
-import * as listbox from 'remix/ui/listbox'
 import * as popover from 'remix/ui/popover'
-import * as select from 'remix/ui/select'
+import { triggerStyle } from 'remix/ui/select'
+import * as select from 'remix/ui/select/primitives'
+import { listStyle, optionStyle, surfaceStyle } from './select.styles'
 
 function SelectValue(handle: Handle) {
   let context = handle.context.get(select.Context)
 
-  return () => <span mix={button.labelStyle}>{context.displayedLabel}</span>
+  return () => <span>{context.displayedLabel}</span>
 }
 
 function IssueTypeSelect() {
   return () => (
-    <select.Context defaultLabel="Select a type" name="issueType">
-      <button type="button" mix={[button.baseStyle, select.triggerStyle, select.trigger()]}>
+    <select.Context defaultLabel="Select a type" labelSwapDelayMs={100} name="issueType">
+      <button type="button" mix={[triggerStyle, select.trigger()]}>
         <SelectValue />
       </button>
       <popover.Context>
-        <div mix={[popover.surfaceStyle, select.popover()]}>
-          <div mix={[popover.contentStyle, listbox.listStyle, select.list()]}>
-            <div mix={[listbox.optionStyle, select.option({ label: 'Bug', value: 'bug' })]}>
-              Bug
-            </div>
-            <div mix={[listbox.optionStyle, select.option({ label: 'Feature', value: 'feature' })]}>
+        <div mix={[surfaceStyle, select.popover()]}>
+          <div mix={[listStyle, select.list()]}>
+            <div mix={[optionStyle, select.option({ label: 'Bug', value: 'bug' })]}>Bug</div>
+            <div mix={[optionStyle, select.option({ label: 'Feature', value: 'feature' })]}>
               Feature
             </div>
           </div>
@@ -83,15 +84,24 @@ function IssueTypeSelect() {
 }
 ```
 
-## `select.*`
+## `remix/ui/select`
 
 - `Select`: composed trigger, popover, listbox, option list, and optional hidden input for form participation. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and button props.
-- `Option`: option wrapper that renders the standard check glyph and label slot. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `Option`: option component that renders the standard check indicator and label slot. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `triggerStyle`: standard select trigger style for custom trigger composition.
+- `SelectProps` and `SelectOptionProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/select/primitives`
+
+- `Context`: lower-level provider for custom composition. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and primitive-only `labelSwapDelayMs`; the label-swap delay defaults to `75` milliseconds.
+- `trigger()`: wires the trigger button, open behavior, closed-trigger typeahead, and trigger ARIA attributes.
+- `popover()`: wires the popover surface and keeps its min-width synced to the trigger before open.
+- `list()`: wires the listbox root used inside the popover.
+- `option(...)`: registers one selectable option. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `hiddenInput()`: mirrors the selected value into a hidden input for form participation.
 - `onSelectChange(...)`: event mixin for the bubbling `SelectChangeEvent`.
-- `Context`, `trigger()`, `popover()`, `list()`, `option(...)`, and `hiddenInput()`: lower-level composition primitives.
-- `triggerStyle`: standard select trigger style.
 - `SelectChangeEvent`: event with `value`, `label`, and `optionId`.
-- `SelectProps`, `SelectContextProps`, and `SelectOptionProps`: public TypeScript props for the composed and lower-level APIs.
+- `SelectContextProps`, `SelectProps`, and `SelectOptionProps`: primitive prop types for custom composition.
 
 ## Behavior Notes
 

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

@@ -0,0 +1,117 @@
+# select
+
+`Select` is a button-triggered popup value picker backed by `listbox` and `popover`. Use it when the user should choose one stable string value from a finite set.
+
+## Component Usage
+
+```tsx
+import { Option, Select } from 'remix/ui/select'
+import { onSelectChange } from 'remix/ui/select/primitives'
+
+export function FrameworkSelect() {
+  return (
+    <Select
+      defaultLabel="Select a framework"
+      defaultValue="remix"
+      name="framework"
+      mix={onSelectChange((event) => {
+        console.log(event.value, event.label, event.optionId)
+      })}
+    >
+      <Option label="Remix framework" value="remix">
+        Remix
+      </Option>
+      <Option disabled label="React Router framework" value="react-router">
+        React Router
+      </Option>
+      <Option label="React framework" value="react">
+        React
+      </Option>
+    </Select>
+  )
+}
+```
+
+Use `textValue` when closed-trigger typeahead should match a different string from the visible label.
+
+```tsx
+<Select defaultLabel="Select an environment">
+  <Option label="Production environment" value="production">
+    Production
+  </Option>
+  <Option label="Staging environment" textValue="beta" value="staging">
+    Staging
+  </Option>
+</Select>
+```
+
+## Primitive Usage
+
+Use the lower-level primitives when the trigger or popup structure needs to be owned by another component. Keep the same provider, trigger, popover, list, option, and hidden-input relationship.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import * as popover from 'remix/ui/popover'
+import { triggerStyle } from 'remix/ui/select'
+import * as select from 'remix/ui/select/primitives'
+import { listStyle, optionStyle, surfaceStyle } from './select.styles'
+
+function SelectValue(handle: Handle) {
+  let context = handle.context.get(select.Context)
+
+  return () => <span>{context.displayedLabel}</span>
+}
+
+function IssueTypeSelect() {
+  return () => (
+    <select.Context defaultLabel="Select a type" labelSwapDelayMs={100} name="issueType">
+      <button type="button" mix={[triggerStyle, select.trigger()]}>
+        <SelectValue />
+      </button>
+      <popover.Context>
+        <div mix={[surfaceStyle, select.popover()]}>
+          <div mix={[listStyle, select.list()]}>
+            <div mix={[optionStyle, select.option({ label: 'Bug', value: 'bug' })]}>Bug</div>
+            <div mix={[optionStyle, select.option({ label: 'Feature', value: 'feature' })]}>
+              Feature
+            </div>
+          </div>
+        </div>
+      </popover.Context>
+      <input mix={select.hiddenInput()} />
+    </select.Context>
+  )
+}
+```
+
+## `remix/ui/select`
+
+- `Select`: composed trigger, popover, listbox, option list, and optional hidden input for form participation. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and button props.
+- `Option`: option component that renders the standard check indicator and label slot. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `triggerStyle`: standard select trigger style for custom trigger composition.
+- `SelectProps` and `SelectOptionProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/select/primitives`
+
+- `Context`: lower-level provider for custom composition. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and primitive-only `labelSwapDelayMs`; the label-swap delay defaults to `75` milliseconds.
+- `trigger()`: wires the trigger button, open behavior, closed-trigger typeahead, and trigger ARIA attributes.
+- `popover()`: wires the popover surface and keeps its min-width synced to the trigger before open.
+- `list()`: wires the listbox root used inside the popover.
+- `option(...)`: registers one selectable option. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `hiddenInput()`: mirrors the selected value into a hidden input for form participation.
+- `onSelectChange(...)`: event mixin for the bubbling `SelectChangeEvent`.
+- `SelectChangeEvent`: event with `value`, `label`, and `optionId`.
+- `SelectContextProps`, `SelectProps`, and `SelectOptionProps`: primitive prop types for custom composition.
+
+## Behavior Notes
+
+- `defaultLabel` is displayed before selection settles. `defaultValue` selects the matching option without replacing the trigger label until a new selection commits.
+- `Option.label` is the committed display label and event label. `children` are the rendered option contents.
+- Click, `ArrowDown`, and `ArrowUp` open the popup. Focus moves into the list and Escape restores focus to the trigger through popover behavior.
+- Reopening highlights the current selected value.
+- The popup min-width syncs to the trigger width before opening.
+- Closed-trigger typeahead selects a matching option immediately and supports option `textValue`.
+- Selecting an option flashes it with `data-select-flash`, waits for the close transition and label delay, updates the displayed label, and dispatches `SelectChangeEvent`.
+- Selecting the already-selected value updates state but does not dispatch a change event.
+- `SelectChangeEvent` bubbles from the trigger when a trigger exists. It includes `value`, `label`, and `optionId`.
+- Passing `name` renders a hidden input so the selected value participates in `FormData`; disabled selects disable the trigger and hidden input.

package/src/ui/select/primitives.ts

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