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

package/src/ui/accordion/README.md

@@ -2,7 +2,7 @@
 
 `Accordion` renders a disclosure set with one or more expandable items. Use it for grouped settings, FAQ sections, and dense panels where each item owns a trigger and content region.
 
-## Usage
+## Component Usage
 
 ```tsx
 import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
@@ -82,16 +82,11 @@ export function ControlledAccordion(handle: Handle) {
 }
 ```
 
-Listen for bubbling `AccordionChangeEvent` events with `onAccordionChange`.
+Listen for bubbling `AccordionChangeEvent` events with `onAccordionChange` from `remix/ui/accordion/primitives`.
 
 ```tsx
-import {
-  Accordion,
-  AccordionContent,
-  AccordionItem,
-  AccordionTrigger,
-  onAccordionChange,
-} from 'remix/ui/accordion'
+import { onAccordionChange } from 'remix/ui/accordion/primitives'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
 
 export function TrackedAccordion() {
   return (
@@ -124,7 +119,7 @@ Set `collapsible={false}` in single mode when the open item must stay open. The
 </Accordion>
 ```
 
-Use `headingLevel` to choose the heading wrapper rendered around each trigger. The default level is `3`.
+Use `headingLevel` to choose the heading element rendered around each trigger. The default level is `3`.
 
 ```tsx
 <Accordion defaultValue="shipping" headingLevel={2}>
@@ -142,16 +137,57 @@ Pass `indicator={null}` to remove the default chevron, or pass a custom node to
 <AccordionTrigger indicator={<span aria-hidden>+</span>}>Custom indicator</AccordionTrigger>
 ```
 
-## `accordion.*`
+## Primitive Usage
+
+Use the lower-level primitives when app code owns the accordion markup and styles:
+
+```tsx
+import * as accordion from 'remix/ui/accordion/primitives'
+import { contentStyle, headingStyle, itemStyle, rootStyle, triggerStyle } from './accordion.styles'
+
+export function PrimitiveAccordion() {
+  return (
+    <accordion.Context defaultValue="shipping">
+      <div mix={[rootStyle, accordion.root()]}>
+        <accordion.ItemContext value="shipping">
+          <div mix={[itemStyle, accordion.item()]}>
+            <h3 mix={headingStyle}>
+              <button mix={[triggerStyle, accordion.trigger()]} type="button">
+                Shipping
+              </button>
+            </h3>
+            <div mix={[contentStyle, accordion.content()]}>
+              Delivery windows and carrier defaults.
+            </div>
+          </div>
+        </accordion.ItemContext>
+      </div>
+    </accordion.Context>
+  )
+}
+```
+
+## `remix/ui/accordion`
 
 - `Accordion`: root component. Defaults to single-item mode and supports controlled `value`, uncontrolled `defaultValue`, `onValueChange`, `disabled`, `headingLevel`, `collapsible`, and `type="multiple"`.
 - `AccordionItem`: registers one accordion item by `value`. Pass `disabled` to prevent that item from opening or receiving keyboard focus.
 - `AccordionTrigger`: heading-wrapped button for an item. It wires `aria-expanded`, `aria-controls`, keyboard navigation, and the default chevron indicator.
 - `AccordionContent`: panel for an item. It wires the panel id, `aria-labelledby`, `aria-hidden`, inert state, and open/closed state attributes.
+- `rootStyle`, `itemStyle`, `headingStyle`, `triggerStyle`, `indicatorStyle`, `panelStyle`, and `bodyStyle`: flat style mixins used by the component markup.
+- `AccordionProps`, `AccordionSingleProps`, `AccordionMultipleProps`, `AccordionItemProps`, `AccordionTriggerProps`, and `AccordionContentProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/accordion/primitives`
+
+- `Context`: lower-level provider for custom accordion composition.
+- `ItemContext`: lower-level provider for one item value.
+- `root()`: wires the root element and bubbling change events.
+- `item()`: wires one item wrapper.
+- `trigger()`: wires the item trigger, keyboard navigation, and trigger ARIA attributes.
+- `content()`: wires the item panel id, hidden state, inert state, and open/closed state attributes.
 - `onAccordionChange(...)`: event mixin for the bubbling `AccordionChangeEvent`.
-- `AccordionChangeEvent`: bubbling event class with `value`, `itemValue`, and `accordionType`.
-- `AccordionProps`, `AccordionSingleProps`, `AccordionMultipleProps`, `AccordionItemProps`, `AccordionTriggerProps`, and `AccordionContentProps`: public TypeScript props.
-- `rootStyle`, `itemStyle`, `triggerStyle`, `indicatorStyle`, `panelStyle`, and `bodyStyle`: flat style mixins used by the component wrappers.
+- `AccordionChangeEvent`: bubbling event with `value`, `itemValue`, and `accordionType`.
+- `AccordionType`, `AccordionValue`, `AccordionSingleValue`, `AccordionMultipleValue`, and `AccordionHeadingLevel`: public TypeScript state and configuration types.
+- `AccordionBaseContextProps`, `AccordionSingleContextProps`, `AccordionMultipleContextProps`, `AccordionContextProps`, `AccordionRootOptions`, `AccordionItemOptions`, `AccordionTriggerOptions`, and `AccordionContentOptions`: primitive prop and option types for custom composition.
 
 ## Behavior Notes
 

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

@@ -0,0 +1,202 @@
+# accordion
+
+`Accordion` renders a disclosure set with one or more expandable items. Use it for grouped settings, FAQ sections, and dense panels where each item owns a trigger and content region.
+
+## Component Usage
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function SettingsAccordion() {
+  return (
+    <Accordion defaultValue="account">
+      <AccordionItem value="account">
+        <AccordionTrigger>Account</AccordionTrigger>
+        <AccordionContent>Manage account preferences.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="billing">
+        <AccordionTrigger>Billing</AccordionTrigger>
+        <AccordionContent>Review billing details.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Use `type="multiple"` when more than one panel may stay open. `defaultValue` and `value` are arrays in multiple mode.
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function StatusAccordion() {
+  return (
+    <Accordion defaultValue={['api', 'alerts']} type="multiple">
+      <AccordionItem value="api">
+        <AccordionTrigger>API status checks</AccordionTrigger>
+        <AccordionContent>Review uptime checks and response time alerts.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem disabled value="access">
+        <AccordionTrigger>Access control sync</AccordionTrigger>
+        <AccordionContent>This disabled item cannot be opened or focused.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="alerts">
+        <AccordionTrigger>Alert routing</AccordionTrigger>
+        <AccordionContent>Confirm escalation rules and notification channels.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Control the open value when state should live in the owning component. Single mode uses `string | null`; multiple mode uses `string[]`.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function ControlledAccordion(handle: Handle) {
+  let value: string | null = 'account'
+
+  return () => (
+    <Accordion
+      value={value}
+      onValueChange={(nextValue) => {
+        value = nextValue
+        void handle.update()
+      }}
+    >
+      <AccordionItem value="account">
+        <AccordionTrigger>Account</AccordionTrigger>
+        <AccordionContent>Manage account preferences.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="billing">
+        <AccordionTrigger>Billing</AccordionTrigger>
+        <AccordionContent>Review billing details.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Listen for bubbling `AccordionChangeEvent` events with `onAccordionChange` from `remix/ui/accordion/primitives`.
+
+```tsx
+import { onAccordionChange } from 'remix/ui/accordion/primitives'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function TrackedAccordion() {
+  return (
+    <div
+      mix={[
+        onAccordionChange((event) => {
+          console.log(event.accordionType, event.itemValue, event.value)
+        }),
+      ]}
+    >
+      <Accordion>
+        <AccordionItem value="account">
+          <AccordionTrigger>Account</AccordionTrigger>
+          <AccordionContent>Manage account preferences.</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  )
+}
+```
+
+Set `collapsible={false}` in single mode when the open item must stay open. The locked-open trigger receives `aria-disabled`.
+
+```tsx
+<Accordion collapsible={false} defaultValue="account">
+  <AccordionItem value="account">
+    <AccordionTrigger>Account</AccordionTrigger>
+    <AccordionContent>Manage account preferences.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Use `headingLevel` to choose the heading element rendered around each trigger. The default level is `3`.
+
+```tsx
+<Accordion defaultValue="shipping" headingLevel={2}>
+  <AccordionItem value="shipping">
+    <AccordionTrigger>Shipping</AccordionTrigger>
+    <AccordionContent>Review shipping preferences.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Pass `indicator={null}` to remove the default chevron, or pass a custom node to replace it.
+
+```tsx
+<AccordionTrigger indicator={null}>No indicator</AccordionTrigger>
+<AccordionTrigger indicator={<span aria-hidden>+</span>}>Custom indicator</AccordionTrigger>
+```
+
+## Primitive Usage
+
+Use the lower-level primitives when app code owns the accordion markup and styles:
+
+```tsx
+import * as accordion from 'remix/ui/accordion/primitives'
+import { contentStyle, headingStyle, itemStyle, rootStyle, triggerStyle } from './accordion.styles'
+
+export function PrimitiveAccordion() {
+  return (
+    <accordion.Context defaultValue="shipping">
+      <div mix={[rootStyle, accordion.root()]}>
+        <accordion.ItemContext value="shipping">
+          <div mix={[itemStyle, accordion.item()]}>
+            <h3 mix={headingStyle}>
+              <button mix={[triggerStyle, accordion.trigger()]} type="button">
+                Shipping
+              </button>
+            </h3>
+            <div mix={[contentStyle, accordion.content()]}>
+              Delivery windows and carrier defaults.
+            </div>
+          </div>
+        </accordion.ItemContext>
+      </div>
+    </accordion.Context>
+  )
+}
+```
+
+## `remix/ui/accordion`
+
+- `Accordion`: root component. Defaults to single-item mode and supports controlled `value`, uncontrolled `defaultValue`, `onValueChange`, `disabled`, `headingLevel`, `collapsible`, and `type="multiple"`.
+- `AccordionItem`: registers one accordion item by `value`. Pass `disabled` to prevent that item from opening or receiving keyboard focus.
+- `AccordionTrigger`: heading-wrapped button for an item. It wires `aria-expanded`, `aria-controls`, keyboard navigation, and the default chevron indicator.
+- `AccordionContent`: panel for an item. It wires the panel id, `aria-labelledby`, `aria-hidden`, inert state, and open/closed state attributes.
+- `rootStyle`, `itemStyle`, `headingStyle`, `triggerStyle`, `indicatorStyle`, `panelStyle`, and `bodyStyle`: flat style mixins used by the component markup.
+- `AccordionProps`, `AccordionSingleProps`, `AccordionMultipleProps`, `AccordionItemProps`, `AccordionTriggerProps`, and `AccordionContentProps`: public TypeScript props for the composed APIs.
+
+## `remix/ui/accordion/primitives`
+
+- `Context`: lower-level provider for custom accordion composition.
+- `ItemContext`: lower-level provider for one item value.
+- `root()`: wires the root element and bubbling change events.
+- `item()`: wires one item wrapper.
+- `trigger()`: wires the item trigger, keyboard navigation, and trigger ARIA attributes.
+- `content()`: wires the item panel id, hidden state, inert state, and open/closed state attributes.
+- `onAccordionChange(...)`: event mixin for the bubbling `AccordionChangeEvent`.
+- `AccordionChangeEvent`: bubbling event with `value`, `itemValue`, and `accordionType`.
+- `AccordionType`, `AccordionValue`, `AccordionSingleValue`, `AccordionMultipleValue`, and `AccordionHeadingLevel`: public TypeScript state and configuration types.
+- `AccordionBaseContextProps`, `AccordionSingleContextProps`, `AccordionMultipleContextProps`, `AccordionContextProps`, `AccordionRootOptions`, `AccordionItemOptions`, `AccordionTriggerOptions`, and `AccordionContentOptions`: primitive prop and option types for custom composition.
+
+## Behavior Notes
+
+- Single mode stores one open value or `null`; multiple mode stores an array of open values.
+- Single accordions are collapsible by default. Set `collapsible={false}` to keep the open item locked open.
+- Root `disabled` disables every item. Item `disabled` only disables that item.
+- Arrow keys move between enabled triggers. `Home` and `End` move to the first and last enabled triggers.
+- Disabled items are skipped by keyboard navigation.
+- Trigger and panel ids are generated and linked with `aria-controls`, `aria-labelledby`, and `aria-expanded`; closed panels receive `aria-hidden` and `inert`.
+- `AccordionTrigger` renders inside an `h1`-`h6` element based on `headingLevel`.
+- Each item and trigger receives `data-state="open"` or `data-state="closed"` for styling.
+- `AccordionChangeEvent` bubbles from the root and includes `value`, `itemValue`, and `accordionType`.

package/src/ui/accordion/primitives.ts

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

package/src/ui/anchor/README.md

@@ -2,7 +2,7 @@
 
 `anchor` positions a floating element against an anchor element or viewport coordinates and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
 
-## Usage
+## Primitive Usage
 
 ```tsx
 import { anchor } from 'remix/ui/anchor'
@@ -55,7 +55,42 @@ Anchor to coordinates when the surface should open at a pointer location.
 let cleanup = anchor(popover, { x: event.clientX, y: event.clientY }, { placement: 'bottom-start' })
 ```
 
-## `anchor.*`
+Keep presentation app-owned when the anchored element is rendered by your component:
+
+```tsx
+import { anchor } from 'remix/ui/anchor'
+import { on, ref, type Handle } from 'remix/ui'
+import { panelStyle } from './floating.styles'
+
+export function AnchoredPanel(handle: Handle) {
+  let cleanup = () => {}
+  let trigger: HTMLElement | null = null
+  let panel: HTMLElement | null = null
+
+  function position() {
+    cleanup()
+    if (trigger && panel) {
+      cleanup = anchor(panel, trigger, { placement: 'bottom-start', offset: 8 })
+    }
+  }
+
+  return () => (
+    <>
+      <button
+        mix={[ref((node) => (trigger = node as HTMLElement)), on('click', position)]}
+        type="button"
+      >
+        Open
+      </button>
+      <div data-panel mix={[panelStyle, ref((node) => (panel = node as HTMLElement))]}>
+        Panel
+      </div>
+    </>
+  )
+}
+```
+
+## `remix/ui/anchor`
 
 - `anchor(floatingElement, anchorTarget, options)`: positions `floatingElement` against an element or coordinate target, starts animation-frame polling for geometry changes, and returns a cleanup function.
 - `AnchorOptions`: placement, inset, relative alignment, and offset options.

package/src/ui/breadcrumbs/README.md

@@ -2,7 +2,7 @@
 
 `Breadcrumbs` renders semantic breadcrumb navigation from a list of items. Use it when the page needs a compact path back through parent sections.
 
-## Usage
+## Component Usage
 
 ```tsx
 import { Breadcrumbs } from 'remix/ui/breadcrumbs'
@@ -32,13 +32,13 @@ Mark an earlier item as current when the page belongs to a parent section but th
 />
 ```
 
-Pass `separator` to replace the default chevron glyph.
+Pass `separator` to replace the default chevron icon.
 
 ```tsx
 <Breadcrumbs items={[{ href: '/', label: 'Home' }, { label: 'Breadcrumbs' }]} separator="/" />
 ```
 
-## `breadcrumbs.*`
+## `remix/ui/breadcrumbs`
 
 - `Breadcrumbs`: component that renders a `<nav>` with an ordered list of breadcrumb items.
 - `BreadcrumbItem`: item shape with `label`, optional `href`, and optional `current`.
@@ -52,4 +52,4 @@ Pass `separator` to replace the default chevron glyph.
 - An explicit current item wins over the last-item default.
 - Current items render as text with `aria-current="page"`, even when they include `href`.
 - Non-current items with `href` render as links; non-current items without `href` render as text.
-- The default separator is the `chevronRight` glyph. Separators render between items and are hidden from assistive technology.
+- The default separator is a chevron icon. Separators render between items and are hidden from assistive technology.

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.