remix 3.0.0-beta.0 → 3.0.0-beta.2

package/src/ui/button/README.md

@@ -0,0 +1,44 @@
+# button
+
+`button` is the shared button styling contract for `remix/ui`. Use `Button` for ordinary action buttons, or compose flat `button.*Style` exports directly when a higher-level control needs button structure without a wrapper.
+
+## Usage
+
+```tsx
+import { Button } from 'remix/ui/button'
+import * as button from 'remix/ui/button'
+import { Glyph } from 'remix/ui/glyph'
+
+function Actions() {
+  return (
+    <div>
+      <Button startIcon={<Glyph name="add" />} tone="primary">
+        Create project
+      </Button>
+
+      <a href="/projects" mix={[button.baseStyle, button.secondaryStyle]}>
+        <span mix={button.labelStyle}>View projects</span>
+        <Glyph mix={button.iconStyle} name="chevronRight" />
+      </a>
+    </div>
+  )
+}
+```
+
+## `button.*`
+
+- `Button`: thin button wrapper for the common `base + tone + label/icon slots` case. Pass `tone`, `startIcon`, and `endIcon` when the default authored structure is enough.
+- `button.baseStyle`: base host styling plus the default `type="button"` behavior for button elements.
+- `button.primaryStyle`, `button.secondaryStyle`, `button.ghostStyle`, and `button.dangerStyle`: visual button treatments.
+- `button.labelStyle`: inline label slot with the standard button spacing.
+- `button.iconStyle`: icon slot sizing and `aria-hidden` defaults for decorative icons.
+
+## Behavior Notes
+
+- `button.baseStyle` only adds `type="button"` when the host element is a `<button>` and no explicit `type` was provided.
+- `Button` renders `children` inside `button.labelStyle` and renders `startIcon` and `endIcon` inside `button.iconStyle`.
+- Use an explicit accessible name when you render an icon-only button.
+
+## When To Use Something Else
+
+Use `button.*Style` exports directly when a control needs button structure plus extra behavior or layout, like `select`, `menu`, or `tabs`. Those controls own their own interaction mixins and should not hide that behavior behind `Button`.

package/src/ui/combobox/README.md

@@ -0,0 +1,145 @@
+# Combobox
+
+`Combobox` is the input-first popup value picker for `remix/ui`.
+
+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.
+
+## Usage
+
+```tsx
+import { css, type Handle } from 'remix/ui'
+import { Combobox, ComboboxOption, onComboboxChange } from 'remix/ui/combobox'
+
+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',
+})
+```
+
+## Public API
+
+### `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 `defaultValue`, `disabled`, `inputId`, `name`, and `placeholder`.
+
+### `ComboboxOption`
+
+The default option row for `Combobox`.
+
+- Uses the shared listbox option visuals.
+- Accepts `label`, `value`, optional `searchValue`, and optional `disabled`.
+- `searchValue` can be a string or string array for aliases like airport codes, abbreviations, or alternate labels.
+
+### `onComboboxChange(...)`
+
+The listener mixin 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`
+
+### `combobox.Context`
+
+The lower-level coordinator 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 `combobox.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`.
+
+## 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/glyph/README.md

@@ -0,0 +1,72 @@
+# glyph
+
+`Glyph` renders references into a shared SVG sprite sheet. Render a glyph sheet once, then render individual `Glyph` instances by name.
+
+## Usage
+
+```tsx
+import { Glyph } from 'remix/ui/glyph'
+import { RMX_01_GLYPHS } from 'remix/ui/theme'
+
+function Layout() {
+  return (
+    <html>
+      <body>
+        <RMX_01_GLYPHS />
+        <button aria-label="Delete">
+          <Glyph name="trash" />
+        </button>
+      </body>
+    </html>
+  )
+}
+```
+
+Most glyphs are decorative because the surrounding control supplies the accessible name. `Glyph` sets `aria-hidden` by default in that case.
+
+```tsx
+<button aria-label="Search">
+  <Glyph name="search" />
+</button>
+```
+
+Give the glyph its own label only when the SVG itself is the accessible element.
+
+```tsx
+<Glyph aria-label="Search" name="search" viewBox="0 0 20 20" width="24" />
+```
+
+Use `createGlyphSheet` when a theme or app provides its own complete glyph set. The generated sheet exposes the stable symbol ids and the original values for reuse.
+
+```tsx
+import { createGlyphSheet, type GlyphValues } from 'remix/ui/glyph'
+
+declare const glyphValues: GlyphValues
+
+export const AppGlyphs = createGlyphSheet(glyphValues)
+
+AppGlyphs.ids.trash
+AppGlyphs.values.trash
+```
+
+## `glyph.*`
+
+- `Glyph`: renders an `<svg>` with a `<use>` element that points at the package-owned symbol id for `name`.
+- `createGlyphSheet(values)`: creates a hidden SVG sprite sheet component from a complete glyph value set.
+- `GlyphName`: typed union of supported glyph names.
+- `GlyphProps`: props accepted by `Glyph`.
+- `GlyphSheetProps`: props accepted by generated glyph sheet components.
+- `GlyphSymbol`: SVG symbol value accepted by glyph value maps.
+- `GlyphValues`: object shape expected by `createGlyphSheet`.
+- `GlyphSheetComponent`: generated sprite sheet component with `ids` and `values` attached.
+
+The built-in glyph names are `add`, `alert`, `check`, `chevronDown`, `chevronVertical`, `chevronUp`, `chevronRight`, `close`, `copy`, `edit`, `expand`, `info`, `menu`, `open`, `search`, `spinner`, and `trash`.
+
+## Behavior Notes
+
+- Render the glyph sheet once before rendering glyph instances that reference it.
+- `createGlyphSheet` renders a hidden zero-size SVG and clones each provided `<symbol>` with the stable package id.
+- `Glyph` is `aria-hidden` by default when no accessible label or labelled-by relationship is provided.
+- Labeled glyphs keep their accessible label and do not force `aria-hidden`.
+- Host SVG props such as `viewBox`, `width`, `mix`, and `aria-label` are preserved.
+- `createGlyphSheet` throws if a provided glyph value is not a `<symbol>` element.

package/src/ui/listbox/README.md

@@ -0,0 +1,115 @@
+# 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.
+
+## 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'
+
+function FrameworkListbox(handle: Handle) {
+  let value: ListboxValue = 'remix'
+  let activeValue: ListboxValue = 'remix'
+
+  return () => (
+    <listbox.Context
+      value={value}
+      activeValue={activeValue}
+      onSelect={(nextValue) => {
+        value = nextValue
+        void handle.update()
+      }}
+      onHighlight={(nextValue) => {
+        activeValue = nextValue
+        void handle.update()
+      }}
+    >
+      <div aria-label="Frameworks" tabIndex={0} mix={[listbox.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>
+        ))}
+      </div>
+    </listbox.Context>
+  )
+}
+
+let frameworks = [
+  { label: 'Remix', value: 'remix' },
+  { disabled: true, label: 'React Router', value: 'react-router' },
+  { label: 'React', value: 'react' },
+  { label: 'Preact', value: 'preact' },
+]
+```
+
+Use `textValue` when the visible label is not the best string for typeahead search.
+
+```tsx
+<div
+  mix={[
+    listbox.option({
+      label: 'Staging',
+      textValue: 'beta',
+      value: 'staging',
+    }),
+  ]}
+>
+  Staging
+</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.*`
+
+- `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`.
+- `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.
+
+## Behavior Notes
+
+- 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

@@ -0,0 +1,96 @@
+# 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.
+
+## Usage
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { Menu, MenuItem, Submenu, onMenuSelect } from 'remix/ui/menu'
+import { separatorStyle } from 'remix/ui/separator'
+
+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>
+  )
+}
+```
+
+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>
+```
+
+## `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.
+- `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.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`, `MenuItemOptions`, and `SubmenuProps`: public TypeScript props and option types.
+
+## Behavior Notes
+
+- Click opens the root menu and focuses the list; clicking the trigger again closes it and restores focus.
+- `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/popover/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+## 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'
+
+export function ViewOptions(handle: Handle) {
+  let open = false
+
+  function openPopover() {
+    open = true
+    void handle.update()
+  }
+
+  function closePopover() {
+    open = false
+    void handle.update()
+  }
+
+  return () => (
+    <popover.Context>
+      <Button
+        endIcon={<Glyph name="chevronDown" />}
+        mix={[
+          popover.anchor({ placement: 'bottom-end' }),
+          popover.focusOnHide(),
+          on('click', openPopover),
+        ]}
+        tone="secondary"
+      >
+        View options
+      </Button>
+
+      <div
+        mix={[
+          popover.surfaceStyle,
+          popover.surface({
+            open,
+            onHide() {
+              closePopover()
+            },
+          }),
+        ]}
+      >
+        <div mix={popover.contentStyle}>
+          <Button mix={[popover.focusOnShow(), on('click', closePopover)]} tone="ghost">
+            Close
+          </Button>
+          <div mix={panelBody}>Panel content</div>
+        </div>
+      </div>
+    </popover.Context>
+  )
+}
+
+let panelBody = css({
+  padding: '12px',
+})
+```
+
+## `popover.*`
+
+### `popover.Context`
+
+Provides shared coordination for one popover instance. Render the anchor, any focus targets, and the surface inside the same context.
+
+### `popover.anchor(options)`
+
+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.
+
+- Wires `popover="manual"` and native `showPopover()` / `hidePopover()` behavior.
+- Calls `onHide` for `Escape` and outside clicks with a `PopoverHideRequest`.
+- Restores focus to the registered hide target unless `restoreFocusOnHide: false`.
+- Accepts `closeOnAnchorClick: false` when the anchor must stay interactive while open.
+
+Apply this to the actual floating root, not a nested child.
+
+### `popover.focusOnShow()`
+
+Registers the element that should receive focus when the popover opens.
+
+### `popover.focusOnHide()`
+
+Registers the element that should receive focus again when the popover closes.
+
+### `popover.surfaceStyle`
+
+Default floating-surface presentation for popovers.
+
+### `popover.contentStyle`
+
+Default inner scroll container for popover content.
+
+## Behavior Notes
+
+- Opening anchors the surface to the registered anchor and locks page scrolling until close.
+- `onHide` receives `{ reason: 'escape-key' | 'outside-click', target? }`.
+- `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/scroll-lock/README.md

@@ -0,0 +1,33 @@
+# scroll-lock
+
+`scroll-lock` locks document scrolling while a floating or modal surface is open. Use `lockScroll` directly for imperative flows or `lockScrollOnToggle` for popover-style elements that emit `beforetoggle`.
+
+## Usage
+
+```tsx
+import { lockScroll, lockScrollOnToggle } from 'remix/ui/scroll-lock'
+
+function DialogSurface() {
+  return <div popover="auto" mix={lockScrollOnToggle()} />
+}
+
+function openModal() {
+  let unlock = lockScroll()
+
+  // Later, when the modal closes:
+  unlock()
+}
+```
+
+## API
+
+- `lockScroll(document?)`: locks the target document and returns an idempotent unlock function.
+- `lockScrollOnToggle()`: mixin that locks on `beforetoggle` open, unlocks on close, and releases the lock when the host unmounts.
+
+## Behavior Notes
+
+- The lock stores and restores the document element's inline `overflow` and `scrollbarGutter`.
+- Scroll position is restored when the last active lock is released.
+- Multiple locks are reference-counted, so the document stays locked until every unlock function has run.
+- When a scrollbar is present and computed `scrollbar-gutter` is `auto`, the document reserves a stable gutter while locked.
+- `lockScrollOnToggle` uses the host element's owner document.