@remix-run/ui 0.2.0 → 0.4.0

package/src/button/index.ts

@@ -0,0 +1,168 @@
+import { createMixin, css } from '@remix-run/ui'
+import type { CSSMixinDescriptor, ElementProps, MixinDescriptor } from '@remix-run/ui'
+import { renderMixinElement } from '../runtime/mixins/mixin.ts'
+
+export type ButtonSize = 'md' | 'lg'
+export type ButtonTone = 'neutral' | 'primary' | 'ghost'
+
+export interface ButtonOptions {
+  size?: ButtonSize
+  tone?: ButtonTone
+}
+
+type ButtonMixin = readonly [
+  MixinDescriptor<Element, [], ElementProps>,
+  CSSMixinDescriptor,
+  CSSMixinDescriptor,
+  CSSMixinDescriptor,
+]
+
+const buttonDefaultAttrs = createMixin<Element, [], ElementProps>((handle, hostType) => (props) => {
+  if (hostType !== 'button' || props.type !== undefined) {
+    return handle.element
+  }
+
+  return renderMixinElement(handle.element, {
+    ...props,
+    type: 'button',
+  })
+})()
+
+const baseStyle: CSSMixinDescriptor = css({
+  '--rmx-button-shadow': '0 0 0 0 rgba(0, 0, 0, 0)',
+  '--rmx-button-focus-shadow':
+    '0 0 0 1px #3573F6, var(--rmx-button-shadow), 0 0 0 4px rgba(53, 115, 246, 0.1), 0 6px 32px 4px rgba(53, 115, 246, 0.08), inset 0 0 8px 1px rgba(53, 115, 246, 0.05)',
+  appearance: 'none',
+  margin: 0,
+  boxSizing: 'border-box',
+  cursor: 'revert',
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flexDirection: 'row',
+  gap: '4px',
+  paddingBlock: 0,
+  width: 'max-content',
+  maxWidth: '100%',
+  borderRadius: '999px',
+  fontFamily: '"Inter Variable", Inter, ui-sans-serif, system-ui, sans-serif',
+  fontStyle: 'normal',
+  fontWeight: 500,
+  fontFeatureSettings: '"cv01" on, "ss01" on',
+  letterSpacing: 0,
+  whiteSpace: 'nowrap',
+  textDecoration: 'none',
+  userSelect: 'none',
+  WebkitUserSelect: 'none',
+  verticalAlign: 'top',
+  boxShadow: 'var(--rmx-button-shadow)',
+  '&:focus-visible': {
+    outline: 0,
+    boxShadow: 'var(--rmx-button-focus-shadow)',
+  },
+  '&:disabled, &[aria-disabled="true"]': {
+    cursor: 'not-allowed',
+    opacity: 0.55,
+  },
+})
+
+const mediumStyle: CSSMixinDescriptor = css({
+  height: '26px',
+  minHeight: '26px',
+  paddingInline: '12px',
+  fontSize: '12px',
+  lineHeight: '17px',
+  '--rmx-button-neutral-shadow-alpha': '0.03',
+})
+
+const largeStyle: CSSMixinDescriptor = css({
+  height: '30px',
+  minHeight: '30px',
+  paddingInline: '12px',
+  fontSize: '13px',
+  lineHeight: '20px',
+  '--rmx-button-neutral-shadow-alpha': '0.04',
+})
+
+const neutralStyle: CSSMixinDescriptor = css({
+  background: '#FCFCFC',
+  border: '1px solid rgba(0, 0, 0, 0.08)',
+  '--rmx-button-shadow':
+    '0 -2px 0 -2px rgba(0, 0, 0, 0.06), 0 0 0 1px rgba(255, 255, 255, 0.75), 0 1px 0 #FFFFFF, 0 2px 4px -1px rgb(0 0 0 / var(--rmx-button-neutral-shadow-alpha)), inset 0 2px 0 #FFFFFF, inset 0 -1px 0 rgba(0, 0, 0, 0.05)',
+  color: '#101010',
+  textShadow: '0 1px 0 #FFFFFF',
+  '&:hover:not(:disabled):not([aria-disabled="true"])': {
+    background: '#FFFFFF',
+    borderColor: 'rgba(0, 0, 0, 0.1)',
+    '--rmx-button-shadow':
+      '0 -2px 0 -2px rgba(0, 0, 0, 0.06), 0 0 0 1px rgba(255, 255, 255, 0.8), 0 1px 0 #FFFFFF, 0 3px 6px -2px rgb(0 0 0 / calc(var(--rmx-button-neutral-shadow-alpha) + 0.03)), inset 0 2px 0 #FFFFFF, inset 0 -1px 0 rgba(0, 0, 0, 0.05)',
+  },
+  '&:active:not(:disabled):not([aria-disabled="true"]), &[aria-pressed="true"]:not(:disabled):not([aria-disabled="true"])':
+    {
+      background: '#F7F7F7',
+      borderColor: 'rgba(0, 0, 0, 0.12)',
+      '--rmx-button-shadow':
+        '0 0 0 1px rgba(255, 255, 255, 0.65), inset 0 1px 2px rgba(0, 0, 0, 0.08), inset 0 -1px 0 rgba(255, 255, 255, 0.8)',
+      textShadow: 'none',
+    },
+})
+
+const primaryStyle: CSSMixinDescriptor = css({
+  background:
+    'radial-gradient(50% 50% at 50% 0%, rgba(255, 255, 255, 0.2) 0%, rgba(255, 255, 255, 0) 100%), radial-gradient(49.59% 37.11% at 50.41% 101.56%, rgba(255, 255, 255, 0.15) 0%, rgba(255, 255, 255, 0) 66.46%), #101010',
+  border: 0,
+  '--rmx-button-shadow':
+    '0 16px 16px -8px rgba(0, 0, 0, 0.1), 0 8px 8px -4px rgba(0, 0, 0, 0.1), 0 4px 4px -2px rgba(0, 0, 0, 0.1), 0 2px 2px -1px rgba(0, 0, 0, 0.1), inset 0 0 4px 2px #101010, inset 0 0 4px 2px rgba(255, 255, 255, 0.1), inset 0 0 12px -6px rgba(255, 255, 255, 0.75)',
+  color: '#FFFFFF',
+  textShadow: '0 1px 1px #000000',
+  '&:hover:not(:disabled):not([aria-disabled="true"])': {
+    background:
+      'radial-gradient(50% 50% at 50% 0%, rgba(255, 255, 255, 0.24) 0%, rgba(255, 255, 255, 0) 100%), radial-gradient(49.59% 37.11% at 50.41% 101.56%, rgba(255, 255, 255, 0.18) 0%, rgba(255, 255, 255, 0) 66.46%), #171717',
+    '--rmx-button-shadow':
+      '0 18px 18px -10px rgba(0, 0, 0, 0.14), 0 8px 8px -4px rgba(0, 0, 0, 0.12), 0 4px 4px -2px rgba(0, 0, 0, 0.1), 0 2px 2px -1px rgba(0, 0, 0, 0.1), inset 0 0 4px 2px #101010, inset 0 0 4px 2px rgba(255, 255, 255, 0.13), inset 0 0 12px -6px rgba(255, 255, 255, 0.85)',
+  },
+  '&:active:not(:disabled):not([aria-disabled="true"]), &[aria-pressed="true"]:not(:disabled):not([aria-disabled="true"])':
+    {
+      background:
+        'radial-gradient(50% 50% at 50% 0%, rgba(255, 255, 255, 0.12) 0%, rgba(255, 255, 255, 0) 100%), radial-gradient(49.59% 37.11% at 50.41% 101.56%, rgba(255, 255, 255, 0.08) 0%, rgba(255, 255, 255, 0) 66.46%), #080808',
+      '--rmx-button-shadow':
+        '0 2px 2px -1px rgba(0, 0, 0, 0.14), inset 0 0 4px 2px #050505, inset 0 1px 2px rgba(0, 0, 0, 0.45), inset 0 0 10px -6px rgba(255, 255, 255, 0.55)',
+      textShadow: '0 1px 1px #000000',
+    },
+  '&:active:not(:disabled):not([aria-disabled="true"])': {
+    transform: 'translateY(1px)',
+  },
+})
+
+const ghostStyle: CSSMixinDescriptor = css({
+  background: 'transparent',
+  border: '1px solid transparent',
+  '--rmx-button-shadow': '0 0 0 0 rgba(0, 0, 0, 0)',
+  color: '#101010',
+  textShadow: 'none',
+  '&:hover:not(:disabled):not([aria-disabled="true"])': {
+    background: 'rgba(16, 16, 16, 0.05)',
+  },
+  '&:active:not(:disabled):not([aria-disabled="true"]), &[aria-pressed="true"]:not(:disabled):not([aria-disabled="true"])':
+    {
+      background: 'rgba(16, 16, 16, 0.08)',
+    },
+})
+
+const sizeStyles = {
+  md: mediumStyle,
+  lg: largeStyle,
+} as const satisfies Record<ButtonSize, CSSMixinDescriptor>
+
+const toneStyles = {
+  neutral: neutralStyle,
+  primary: primaryStyle,
+  ghost: ghostStyle,
+} as const satisfies Record<ButtonTone, CSSMixinDescriptor>
+
+export function button(options: ButtonOptions = {}): ButtonMixin {
+  let { size = 'md', tone = 'neutral' } = options
+  return [buttonDefaultAttrs, baseStyle, sizeStyles[size], toneStyles[tone]]
+}
+
+export default button

package/src/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/checkbox/index.ts

@@ -0,0 +1,162 @@
+import { createMixin, css } from '@remix-run/ui'
+import type { CSSMixinDescriptor, ElementProps, MixinDescriptor } from '@remix-run/ui'
+import { renderMixinElement } from '../runtime/mixins/mixin.ts'
+import { controlFocusShadow } from '../shared/focus-styles.ts'
+
+export type CheckboxSize = 'md' | 'lg'
+export type CheckboxState = 'checked' | 'mixed' | 'unchecked'
+
+export interface CheckboxOptions {
+  size?: CheckboxSize
+  state?: CheckboxState
+}
+
+type CheckboxMixin = readonly [
+  MixinDescriptor<Element, [state?: CheckboxState], ElementProps>,
+  CSSMixinDescriptor,
+  CSSMixinDescriptor,
+]
+
+const checkedSelector = '&:checked, &[aria-checked="true"], &[data-state="checked"]'
+const mixedSelector =
+  '&:indeterminate, &[indeterminate], &[aria-checked="mixed"], &[data-state="mixed"]'
+const checkedMarkSelector =
+  '&:checked::before, &[aria-checked="true"]::before, &[data-state="checked"]::before'
+const mixedMarkSelector =
+  '&:indeterminate::before, &[indeterminate]::before, &[aria-checked="mixed"]::before, &[data-state="mixed"]::before'
+const enabledSelector = ':not(:disabled):not([aria-disabled="true"])'
+const checkedActiveSelector =
+  '&:checked:active:not(:disabled):not([aria-disabled="true"]), &[aria-checked="true"]:active:not(:disabled):not([aria-disabled="true"]), &[data-state="checked"]:active:not(:disabled):not([aria-disabled="true"])'
+const mixedActiveSelector =
+  '&:indeterminate:active:not(:disabled):not([aria-disabled="true"]), &[indeterminate]:active:not(:disabled):not([aria-disabled="true"]), &[aria-checked="mixed"]:active:not(:disabled):not([aria-disabled="true"]), &[data-state="mixed"]:active:not(:disabled):not([aria-disabled="true"])'
+const checkIconUrl =
+  "url(\"data:image/svg+xml,%3Csvg width='12' height='12' viewBox='0 0 12 12' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cg filter='url(%23filter0_d_2_2264)'%3E%3Cpath d='M2.75 5.76562L5.10156 8.25L9.23438 1.75' stroke='white' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3Cpath d='M2.75 5.76562L5.10156 8.25L9.23438 1.75' stroke='url(%23paint0_linear_2_2264)' stroke-opacity='0.1' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/g%3E%3Cdefs%3E%3Cfilter id='filter0_d_2_2264' x='0' y='0' width='11.9845' height='12' filterUnits='userSpaceOnUse' color-interpolation-filters='sRGB'%3E%3CfeFlood flood-opacity='0' result='BackgroundImageFix'/%3E%3CfeColorMatrix in='SourceAlpha' type='matrix' values='0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0' result='hardAlpha'/%3E%3CfeOffset dy='1'/%3E%3CfeGaussianBlur stdDeviation='1'/%3E%3CfeComposite in2='hardAlpha' operator='out'/%3E%3CfeColorMatrix type='matrix' values='0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.4 0'/%3E%3CfeBlend mode='overlay' in2='BackgroundImageFix' result='effect1_dropShadow_2_2264'/%3E%3CfeBlend mode='normal' in='SourceGraphic' in2='effect1_dropShadow_2_2264' result='shape'/%3E%3C/filter%3E%3ClinearGradient id='paint0_linear_2_2264' x1='5.99219' y1='1.75' x2='5.99219' y2='8.25' gradientUnits='userSpaceOnUse'%3E%3Cstop offset='0.25' stop-color='%233573F6' stop-opacity='0'/%3E%3Cstop offset='1' stop-color='%233573F6'/%3E%3C/linearGradient%3E%3C/defs%3E%3C/svg%3E\")"
+
+const checkboxAriaChecked = {
+  checked: 'true',
+  mixed: 'mixed',
+  unchecked: 'false',
+} as const satisfies Record<CheckboxState, 'true' | 'mixed' | 'false'>
+
+const checkboxDefaultAttrs = createMixin<Element, [state?: CheckboxState], ElementProps>(
+  (handle, hostType) => (state, props) => {
+    let stateProps =
+      state === undefined
+        ? props
+        : {
+            ...props,
+            'aria-checked': props['aria-checked'] ?? checkboxAriaChecked[state],
+            'data-state': props['data-state'] ?? state,
+          }
+
+    if (hostType !== 'input' || stateProps.type !== undefined) {
+      return state === undefined ? handle.element : renderMixinElement(handle.element, stateProps)
+    }
+
+    return renderMixinElement(handle.element, {
+      ...stateProps,
+      type: 'checkbox',
+    })
+  },
+)
+
+const baseStyle: CSSMixinDescriptor = css({
+  appearance: 'none',
+  WebkitAppearance: 'none',
+  margin: 0,
+  boxSizing: 'border-box',
+  position: 'relative',
+  display: 'inline-grid',
+  placeItems: 'center',
+  width: 'var(--rmx-checkbox-size)',
+  height: 'var(--rmx-checkbox-size)',
+  minWidth: 'var(--rmx-checkbox-size)',
+  minHeight: 'var(--rmx-checkbox-size)',
+  padding: 0,
+  border: 0,
+  borderRadius: 'var(--rmx-checkbox-radius)',
+  background: '#FFFFFF',
+  boxShadow:
+    '0 2px 2px -1px rgba(0, 0, 0, 0.05), 0 3px 4px -1.5px rgba(0, 0, 0, 0.05), 0 4px 8px -2px rgba(0, 0, 0, 0.05), 0 5px 16px -2.5px rgba(0, 0, 0, 0.05), 0 0 0 1px rgba(0, 0, 0, 0.12)',
+  color: '#FFFFFF',
+  verticalAlign: 'middle',
+  flex: 'none',
+  '&::before': {
+    content: '""',
+    position: 'absolute',
+    opacity: 0,
+    pointerEvents: 'none',
+  },
+  '&:disabled, &[aria-disabled="true"]': {
+    opacity: 0.55,
+  },
+  [`${checkedSelector}, ${mixedSelector}`]: {
+    background:
+      'linear-gradient(180deg, rgba(0, 0, 0, 0) 24.52%, rgba(0, 0, 0, 0.1) 100%), #3573F6',
+    backgroundBlendMode: 'overlay, normal',
+    borderRadius: 'var(--rmx-checkbox-active-radius)',
+    boxShadow:
+      '0 1px 1px -0.5px rgba(9, 68, 190, 0.12), 0 2px 2px -1px rgba(9, 68, 190, 0.12), 0 4px 4px -2px rgba(9, 68, 190, 0.12), 0 8px 8px -4px rgba(9, 68, 190, 0.12), 0 2px 8px rgba(53, 115, 246, 0.4), inset 0 0 3px 1px rgba(0, 0, 0, 0.1)',
+  },
+  [checkedMarkSelector]: {
+    opacity: 1,
+    left: '50%',
+    top: '50%',
+    width: 'var(--rmx-checkbox-check-size)',
+    height: 'var(--rmx-checkbox-check-size)',
+    background: `${checkIconUrl} center / contain no-repeat`,
+    transform: 'translate(-50%, calc(-50% + var(--rmx-checkbox-check-y)))',
+  },
+  [mixedMarkSelector]: {
+    opacity: 1,
+    left: '50%',
+    top: '50%',
+    width: 'var(--rmx-checkbox-mixed-width)',
+    height: 'var(--rmx-checkbox-mixed-height)',
+    border: 0,
+    borderRadius: '999px',
+    background: 'currentColor',
+    filter: 'drop-shadow(0 1px 2px rgba(0, 0, 0, 0.4))',
+    transform: 'translate(-50%, -50%)',
+  },
+  [`&:active${enabledSelector}`]: {
+    boxShadow:
+      '0 1px 1px -0.5px rgba(0, 0, 0, 0.06), 0 0 0 1px rgba(0, 0, 0, 0.14), inset 0 1px 2px rgba(0, 0, 0, 0.08)',
+  },
+  [`${checkedActiveSelector}, ${mixedActiveSelector}`]: {
+    boxShadow:
+      '0 1px 1px -0.5px rgba(9, 68, 190, 0.1), 0 2px 2px -1px rgba(9, 68, 190, 0.1), 0 4px 4px -2px rgba(9, 68, 190, 0.1), 0 6px 8px -4px rgba(9, 68, 190, 0.1), 0 2px 6px rgba(53, 115, 246, 0.32), inset 0 1px 2px rgba(0, 0, 0, 0.3), inset 0 0 3px 1px rgba(0, 0, 0, 0.12)',
+  },
+  '&:focus-visible': {
+    outline: 0,
+    boxShadow: controlFocusShadow,
+  },
+})
+
+const sizeStyles = {
+  md: css({
+    '--rmx-checkbox-size': '16px',
+    '--rmx-checkbox-radius': '4px',
+    '--rmx-checkbox-active-radius': '5px',
+    '--rmx-checkbox-check-size': '12px',
+    '--rmx-checkbox-check-y': '1px',
+    '--rmx-checkbox-mixed-width': '7px',
+    '--rmx-checkbox-mixed-height': '2px',
+  }),
+  lg: css({
+    '--rmx-checkbox-size': '20px',
+    '--rmx-checkbox-radius': '5px',
+    '--rmx-checkbox-active-radius': '6px',
+    '--rmx-checkbox-check-size': '15px',
+    '--rmx-checkbox-check-y': '1.25px',
+    '--rmx-checkbox-mixed-width': '9px',
+    '--rmx-checkbox-mixed-height': '2.25px',
+  }),
+} as const satisfies Record<CheckboxSize, CSSMixinDescriptor>
+
+export function checkbox(options: CheckboxOptions = {}): CheckboxMixin {
+  let { size = 'md', state } = options
+  return [checkboxDefaultAttrs(state), baseStyle, sizeStyles[size]]
+}
+
+export default checkbox

package/src/{components/combobox → 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/combobox/index.tsx

@@ -0,0 +1,112 @@
+import { createElement, css } from '@remix-run/ui'
+import type { CSSMixinDescriptor, Handle, Props, RemixNode } from '@remix-run/ui'
+
+import * as combobox from '@remix-run/ui/combobox/primitives'
+import type { SearchValue } from '../shared/typeahead.ts'
+import { CheckIcon } from '../shared/icons.tsx'
+import {
+  listboxIndicatorStyle,
+  listboxLabelStyle,
+  listboxListStyle,
+  listboxOptionStyle,
+  popoverSurfaceStyle,
+} from '../shared/listbox-popover-styles.ts'
+import { componentStyleValues as styles } from '../shared/style-values.ts'
+
+export interface ComboboxProps extends Omit<Props<'div'>, 'children'> {
+  children?: RemixNode
+  defaultValue?: string | null
+  disabled?: boolean
+  inputId?: string
+  name?: string
+  placeholder?: string
+}
+
+export interface ComboboxOptionProps extends Omit<Props<'div'>, 'children'> {
+  children?: RemixNode
+  disabled?: boolean
+  label: string
+  searchValue?: SearchValue
+  value: string
+}
+
+const comboboxPopoverCss: CSSMixinDescriptor = css({
+  opacity: 0,
+  '&:popover-open': {
+    opacity: 1,
+  },
+  '&:not(:popover-open)': {
+    pointerEvents: 'none',
+  },
+  '&[data-show-reason="nav"]:not(:popover-open)': {
+    transition: 'opacity 180ms ease-in, overlay 180ms ease-in, display 180ms ease-in',
+    transitionBehavior: 'allow-discrete',
+  },
+  '&[data-show-reason="hint"]:not(:popover-open)': {
+    transition: 'none',
+    transitionBehavior: 'normal',
+  },
+})
+
+const comboboxInputCss: CSSMixinDescriptor = css({
+  minHeight: styles.control.height.sm,
+  width: '100%',
+  paddingInline: styles.space.sm,
+  border: `0.5px solid ${styles.colors.border.default}`,
+  borderRadius: styles.radius.md,
+  backgroundColor: styles.surface.lvl0,
+  color: styles.colors.text.primary,
+  fontFamily: styles.fontFamily.sans,
+  fontSize: styles.fontSize.sm,
+  lineHeight: styles.lineHeight.normal,
+  boxShadow: 'inset 0 1px 0 rgb(255 255 255 / 0.7)',
+  '&:focus-visible': {
+    outline: `2px solid ${styles.colors.focus.ring}`,
+    outlineOffset: styles.space.none,
+  },
+  '&[data-surface-visible="true"][aria-activedescendant]:focus-visible': {
+    outline: 'none',
+  },
+})
+
+export const inputStyle = comboboxInputCss
+export const popoverStyle = comboboxPopoverCss
+
+export function Combobox(handle: Handle<ComboboxProps>): () => RemixNode {
+  return () => {
+    let { children, defaultValue, disabled, inputId, name, placeholder, ...divProps } = handle.props
+
+    return (
+      <combobox.Context defaultValue={defaultValue} disabled={disabled} name={name}>
+        <div {...divProps}>
+          <input
+            defaultValue={defaultValue ?? undefined}
+            id={inputId}
+            mix={[inputStyle, combobox.input()]}
+            placeholder={placeholder}
+          />
+          <div mix={[popoverSurfaceStyle, popoverStyle, combobox.popover()]}>
+            <div mix={[listboxListStyle, combobox.list()]}>{children}</div>
+          </div>
+          {name && <input mix={combobox.hiddenInput()} />}
+        </div>
+      </combobox.Context>
+    )
+  }
+}
+
+export function ComboboxOption(handle: Handle<ComboboxOptionProps>): () => RemixNode {
+  return () => {
+    let { children, disabled, label, mix, searchValue, value, ...divProps } = handle.props
+
+    return (
+      <div
+        {...divProps}
+        mix={[listboxOptionStyle, combobox.option({ disabled, label, searchValue, value }), mix]}
+      >
+        <CheckIcon mix={listboxIndicatorStyle} />
+        <span mix={listboxLabelStyle}>{children ?? label}</span>
+      </div>
+    )
+  }
+}