remix 3.0.0-beta.3 → 3.0.0-beta.5

package/src/ui/button/README.md

@@ -1,44 +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.
+`button` is a style mixin for pill-shaped action controls. It owns only button-like visual styling and the default `type="button"` behavior for native `<button>` hosts.
 
-## Usage
+## Primitive Usage
 
 ```tsx
-import { Button } from 'remix/ui/button'
-import * as button from 'remix/ui/button'
-import { Glyph } from 'remix/ui/glyph'
+import button from 'remix/ui/button'
 
 function Actions() {
-  return (
+  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>
+      <button mix={button()}>Edit order</button>
+      <button mix={button({ size: 'lg', tone: 'primary' })}>Add product</button>
+      <button mix={button({ tone: 'ghost' })}>Cancel</button>
     </div>
   )
 }
 ```
 
-## `button.*`
+Compose app-owned styles around the primitive when a control needs local layout or state styling:
 
-- `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.
+```tsx
+import button from 'remix/ui/button'
+import { toolbarButtonStyle } from './toolbar.styles'
 
-## Behavior Notes
+function ToolbarAction() {
+  return () => <button mix={[toolbarButtonStyle, button({ tone: 'ghost' })]}>Archive</button>
+}
+```
+
+## `remix/ui/button`
 
-- `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.
+- `button(options)`: style mixin for native buttons or button-like hosts.
+- `ButtonOptions`: accepts `size` and `tone`.
+- `ButtonSize`: `'md'` or `'lg'`. Defaults to `'md'`.
+- `ButtonTone`: `'neutral'`, `'primary'`, or `'ghost'`. Defaults to `'neutral'`.
 
-## When To Use Something Else
+## Behavior Notes
 
-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`.
+- `button()` returns a mixin descriptor, so it composes with other mixins in the host element's `mix` prop.
+- Native `<button>` hosts receive `type="button"` unless an explicit `type` is provided.
+- Non-button hosts receive styling only.
+- Disabled hosts use the shared disabled treatment through `disabled` or `aria-disabled="true"`.

package/src/ui/button.ts

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

package/src/ui/checkbox/README.md

@@ -0,0 +1,59 @@
+# checkbox
+
+`checkbox` is a style mixin for native checkbox inputs. It only owns checkbox visuals, an optional visual state, and the default `type="checkbox"` behavior for native `<input>` hosts.
+
+## Usage
+
+```tsx
+import checkbox from 'remix/ui/checkbox'
+
+function VisibilityToggle() {
+  return () => (
+    <label>
+      <input defaultChecked mix={checkbox()} name="visibility" value="archived" />
+      Show archived items
+    </label>
+  )
+}
+```
+
+Use `size: 'lg'` when the surrounding UI needs a larger visual control:
+
+```tsx
+<input mix={checkbox({ size: 'lg' })} />
+```
+
+For mixed state, app code owns the checkbox state and the native `indeterminate` property:
+
+```tsx
+import checkbox from 'remix/ui/checkbox'
+
+function PermissionParent() {
+  let state: 'checked' | 'mixed' | 'unchecked' = 'mixed'
+
+  return () => (
+    <input
+      checked={state === 'checked'}
+      indeterminate={state === 'mixed'}
+      mix={checkbox({ state })}
+    />
+  )
+}
+```
+
+## `remix/ui/checkbox`
+
+- `checkbox(options)`: style mixin for native checkbox inputs or checkbox-like hosts.
+- `CheckboxOptions`: accepts `size` and `state`.
+- `CheckboxSize`: `'md'` or `'lg'`. Defaults to `'md'`.
+- `CheckboxState`: `'checked'`, `'mixed'`, or `'unchecked'`.
+
+## Behavior Notes
+
+- `checkbox()` returns a mixin descriptor, so it composes with other mixins in the host element's `mix` prop.
+- Native `<input>` hosts receive `type="checkbox"` unless an explicit `type` is provided.
+- Native input state is browser-owned through `checked`, `defaultChecked`, and user interaction.
+- The optional `state` option adds `aria-checked` and `data-state` for app-owned mixed state or custom hosts.
+- Checked styles apply through `:checked`, `aria-checked="true"`, or `data-state="checked"`.
+- Mixed styles apply through `:indeterminate`, `indeterminate`, `aria-checked="mixed"`, or `data-state="mixed"`.
+- Disabled hosts use the shared disabled treatment through `disabled` or `aria-disabled="true"`.

package/src/ui/checkbox.ts

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

package/src/ui/combobox/README.md

@@ -1,14 +1,15 @@
-# Combobox
+# combobox
 
-`Combobox` is the input-first popup value picker for `remix/ui`.
+`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.
 
-## Usage
+## Component Usage
 
 ```tsx
 import { css, type Handle } from 'remix/ui'
-import { Combobox, ComboboxOption, onComboboxChange } from 'remix/ui/combobox'
+import { Combobox, ComboboxOption } from 'remix/ui/combobox'
+import { onComboboxChange } from 'remix/ui/combobox/primitives'
 
 let airports = [
   {
@@ -58,7 +59,39 @@ let root = css({
 })
 ```
 
-## Public API
+## 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`
 
@@ -66,7 +99,7 @@ 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`.
+- Accepts `children`, `defaultValue`, `disabled`, `inputId`, `name`, `placeholder`, and root `div` props.
 
 ### `ComboboxOption`
 
@@ -74,21 +107,31 @@ 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 for bubbled committed-value changes.
+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 for custom combobox composition.
+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.
 
@@ -106,7 +149,7 @@ 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`.
+- Applies the combobox open/close reason contract used by `popoverStyle`.
 
 ### `combobox.list()`
 
@@ -126,6 +169,12 @@ 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.

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/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.