@remix-run/ui 0.1.0 → 0.1.2

package/src/components/button/README.md

@@ -1,13 +1,13 @@
 # button
 
-`button` is the shared button styling contract for `@remix-run/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 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-run/ui/button'
-import * as button from '@remix-run/ui/button'
-import { Glyph } from '@remix-run/ui/glyph'
+import { Button } from 'remix/ui/button'
+import * as button from 'remix/ui/button'
+import { Glyph } from 'remix/ui/glyph'
 
 function Actions() {
   return (

package/src/components/button/button.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import { attrs, createElement, createMixin, css } from '@remix-run/ui'
 import type { CSSMixinDescriptor, ElementProps, Handle, Props, RemixNode } from '@remix-run/ui'
 
@@ -93,12 +91,61 @@ const buttonDefaultsMixin = createMixin<Element, [], ElementProps>(
 
 const buttonDefaultsCss = buttonDefaultsMixin()
 
+/**
+ * Base button styling with the default `type="button"` behavior for `<button>`
+ * hosts. Compose with a tone style (e.g. {@link primaryStyle}) when applying
+ * button styling without using the {@link Button} component.
+ *
+ * @category mixin
+ */
 export const baseStyle = [buttonDefaultsCss, buttonBaseStyleCss] as const
+
+/**
+ * Icon slot sizing and `aria-hidden` defaults for decorative icons rendered
+ * inside a button.
+ *
+ * @category mixin
+ */
 export const iconStyle = [buttonIconAttrsCss, buttonIconCss] as const
+
+/**
+ * Inline label slot with the standard button label spacing.
+ *
+ * @category mixin
+ */
 export const labelStyle = buttonLabelCss
+
+/**
+ * Primary visual treatment for buttons. Combine with {@link baseStyle} when
+ * styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
 export const primaryStyle = createButtonCss(theme.colors.action.primary)
+
+/**
+ * Secondary visual treatment for buttons. Combine with {@link baseStyle} when
+ * styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
 export const secondaryStyle = createButtonCss(theme.colors.action.secondary)
+
+/**
+ * Ghost visual treatment for buttons — transparent background with a hover
+ * surface. Combine with {@link baseStyle} when styling a non-`Button` host
+ * element.
+ *
+ * @category mixin
+ */
 export const ghostStyle = ghostButtonToneCss
+
+/**
+ * Danger visual treatment for destructive actions. Combine with
+ * {@link baseStyle} when styling a non-`Button` host element.
+ *
+ * @category mixin
+ */
 export const dangerStyle = createButtonCss(theme.colors.action.danger)
 
 const toneStyleByTone = {
@@ -108,15 +155,54 @@ const toneStyleByTone = {
   danger: dangerStyle,
 } as const
 
+/**
+ * Visual treatment supported by {@link Button} — `'primary'`, `'secondary'`,
+ * `'ghost'`, or `'danger'`.
+ */
 export type ButtonTone = keyof typeof toneStyleByTone
 
+/**
+ * Props accepted by the {@link Button} component.
+ *
+ * Extends the native `<button>` element props with optional icon slots and a
+ * tone variant
+ */
 export type ButtonProps = Omit<Props<'button'>, 'children'> & {
+  /**
+   * Content rendered inside the button's label slot.
+   */
   readonly children?: RemixNode
+  /**
+   * Decorative icon rendered after the label, inside the icon slot.
+   */
   readonly endIcon?: RemixNode
+  /**
+   * Decorative icon rendered before the label, inside the icon slot.
+   */
   readonly startIcon?: RemixNode
+  /**
+   * Visual treatment to apply to the button (default `'secondary'`).
+   */
   readonly tone?: ButtonTone
 }
 
+/**
+ * Renders a `<button>` with `baseStyle` and the resolved tone style, along with
+ * optional start and end icons.
+ *
+ * @param handle Component handle providing the runtime API and the resolved {@link ButtonProps}.
+ * @returns A render function for the button element.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from '@remix-run/ui/button'
+ * import { Glyph } from '@remix-run/ui/glyph'
+ *
+ * <Button startIcon={<Glyph name="add" />} tone="primary">
+ *   Create project
+ * </Button>
+ * ```
+ */
 export function Button(handle: Handle<ButtonProps>) {
   return () => {
     let { children, endIcon, mix, startIcon, tone = 'secondary', ...buttonProps } = handle.props

package/src/components/button/demos/aliases.demo.tsx

@@ -0,0 +1,27 @@
+import { Button } from '@remix-run/ui/button'
+import { css } from '@remix-run/ui'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Button Component
+ * @description The Button component wraps the low-level style primitives and accepts a tone prop for quick theming.
+ * @order 2
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <Button tone="primary" type="submit">
+        Save
+      </Button>
+      <Button tone="secondary">Secondary</Button>
+      <Button tone="ghost">Ghost</Button>
+      <Button tone="danger">Delete</Button>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})

package/src/components/button/demos/basic.demo.tsx

@@ -0,0 +1,30 @@
+import { css } from '@remix-run/ui'
+import * as button from '@remix-run/ui/button'
+import { Glyph } from '@remix-run/ui/glyph'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Basic Button
+ * @description The default button contract supports both ordinary actions and link-shaped navigation.
+ * @order 1
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <button type="submit" mix={[button.baseStyle, button.primaryStyle]}>
+        <Glyph mix={button.iconStyle} name="add" />
+        <span mix={button.labelStyle}>Publish</span>
+      </button>
+      <a href="/api/remix/ui/button/overview/" mix={[button.baseStyle, button.secondaryStyle]}>
+        <span mix={button.labelStyle}>View button docs</span>
+        <Glyph mix={button.iconStyle} name="chevronRight" />
+      </a>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})

package/src/components/button/demos/states.demo.tsx

@@ -0,0 +1,52 @@
+import * as button from '@remix-run/ui/button'
+import { css } from '@remix-run/ui'
+import { Glyph } from '@remix-run/ui/glyph'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Button States
+ * @description Buttons support normal, disabled, and busy (loading) states using aria attributes.
+ * @order 3
+ */
+export default function Example() {
+  return () => (
+    <div mix={buttonRowCss}>
+      <button mix={[button.baseStyle, button.primaryStyle]}>
+        <Glyph mix={button.iconStyle} name="add" />
+        <span mix={button.labelStyle}>New issue</span>
+      </button>
+
+      <button mix={[button.baseStyle, button.ghostStyle]}>
+        <span mix={button.labelStyle}>Open</span>
+        <Glyph mix={button.iconStyle} name="chevronRight" />
+      </button>
+
+      <button disabled mix={[button.baseStyle, button.secondaryStyle]}>
+        <span mix={button.labelStyle}>Disabled</span>
+      </button>
+
+      <button aria-busy="true" mix={[button.baseStyle, button.secondaryStyle]}>
+        <Glyph mix={[button.iconStyle, spinnerGlyphCss, spinCss]} name="spinner" />
+        <span mix={button.labelStyle}>Saving</span>
+      </button>
+    </div>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.space.sm,
+})
+
+const spinnerGlyphCss = css({
+  opacity: 0.72,
+})
+
+const spinCss = css({
+  '@keyframes demo-button-spin': {
+    from: { transform: 'rotate(0deg)' },
+    to: { transform: 'rotate(360deg)' },
+  },
+  animation: 'demo-button-spin 1s linear infinite',
+})

package/src/components/combobox/combobox.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   attrs,
   css,
@@ -8,6 +6,7 @@ import {
   on,
   ref,
   type CSSMixinDescriptor,
+  type Dispatched,
   type ElementProps,
   type Handle,
   type MixinHandle,
@@ -26,8 +25,8 @@ import { wait } from '../../utils/wait.ts'
 const COMBOBOX_CHANGE_EVENT = 'rmx:combobox-change' as const
 const INPUT_COMMIT_DELAY_MS = 50
 
-type ComboboxChangeHandler = (
-  event: ComboboxChangeEvent,
+type ComboboxChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<ComboboxChangeEvent, target>,
   signal: AbortSignal,
 ) => void | Promise<void>
 
@@ -966,12 +965,11 @@ const combobox = {
   popover: popoverMixin,
 } as const
 
-export function onComboboxChange(handler: ComboboxChangeHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof COMBOBOX_CHANGE_EVENT>(
-    COMBOBOX_CHANGE_EVENT,
-    handler,
-    captureBoolean,
-  )
+export function onComboboxChange<target extends HTMLElement>(
+  handler: ComboboxChangeHandler<target>,
+  captureBoolean?: boolean,
+) {
+  return on(COMBOBOX_CHANGE_EVENT, handler, captureBoolean)
 }
 
 export function Combobox(handle: Handle<ComboboxProps>) {

package/src/components/combobox/demos/overview.demo.tsx

@@ -0,0 +1,199 @@
+import { css, type Handle } from '@remix-run/ui'
+import { Combobox, ComboboxOption, onComboboxChange } from '@remix-run/ui/combobox'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Combobox Overview
+ * @description A searchable combobox with keyboard navigation. Try typing airport names or codes like ord, lax, or jfk.
+ */
+export default function Example(handle: Handle) {
+  let value: string | null = null
+
+  return () => (
+    <div mix={stackCss}>
+      <div mix={fieldCss}>
+        <label for="airport-combobox" mix={labelCss}>
+          Airport
+        </label>
+
+        <Combobox
+          inputId="airport-combobox"
+          mix={[
+            comboboxCss,
+            onComboboxChange((event) => {
+              value = event.value
+              void handle.update()
+            }),
+          ]}
+          name="airport"
+          placeholder="Search airports or codes"
+        >
+          {airportOptions.map((airport) => (
+            <ComboboxOption
+              key={airport.value}
+              disabled={airport.disabled}
+              label={airport.label}
+              searchValue={airport.searchValue}
+              value={airport.value}
+            />
+          ))}
+        </Combobox>
+
+        <div mix={helpCss}>
+          Try typing `san`, `wash`, or airport codes like `ord`, `lax`, or `jfk`, then use ArrowDown
+          and Enter.
+        </div>
+      </div>
+
+      <p mix={valueCss}>{`value=${value ?? 'null'}`}</p>
+    </div>
+  )
+}
+
+type AirportOption = {
+  disabled?: boolean
+  label: string
+  searchValue: string[]
+  value: string
+}
+
+const airportOptions: AirportOption[] = [
+  {
+    label: 'Hartsfield-Jackson Atlanta International',
+    searchValue: ['atl', 'atlanta', 'hartsfield-jackson atlanta international'],
+    value: 'ATL',
+  },
+  {
+    label: 'Austin-Bergstrom International',
+    searchValue: ['aus', 'austin', 'austin-bergstrom international'],
+    value: 'AUS',
+  },
+  {
+    label: 'Boston Logan International',
+    searchValue: ['bos', 'boston', 'boston logan international'],
+    value: 'BOS',
+  },
+  {
+    label: 'Baltimore/Washington International',
+    searchValue: ['bwi', 'baltimore', 'washington', 'baltimore/washington international'],
+    value: 'BWI',
+  },
+  {
+    label: 'Ronald Reagan Washington National',
+    searchValue: ['dca', 'reagan', 'washington', 'ronald reagan washington national'],
+    value: 'DCA',
+  },
+  {
+    label: 'Denver International',
+    searchValue: ['den', 'denver', 'denver international'],
+    value: 'DEN',
+  },
+  {
+    label: 'Dallas/Fort Worth International',
+    searchValue: ['dfw', 'dallas', 'fort worth', 'dallas/fort worth international'],
+    value: 'DFW',
+  },
+  {
+    label: 'Newark Liberty International',
+    searchValue: ['ewr', 'newark', 'newark liberty international'],
+    value: 'EWR',
+  },
+  {
+    label: 'Daniel K. Inouye International',
+    searchValue: ['hnl', 'honolulu', 'daniel k. inouye international'],
+    value: 'HNL',
+  },
+  {
+    label: 'Washington Dulles International',
+    searchValue: ['iad', 'dulles', 'washington', 'washington dulles international'],
+    value: 'IAD',
+  },
+  {
+    label: 'John F. Kennedy International',
+    searchValue: ['jfk', 'kennedy', 'new york', 'john f. kennedy international'],
+    value: 'JFK',
+  },
+  {
+    label: 'Harry Reid International',
+    searchValue: ['las', 'las vegas', 'harry reid international'],
+    value: 'LAS',
+  },
+  {
+    label: 'Los Angeles International',
+    searchValue: ['lax', 'los angeles', 'los angeles international'],
+    value: 'LAX',
+  },
+  {
+    label: 'Orlando International',
+    searchValue: ['mco', 'orlando', 'orlando international'],
+    value: 'MCO',
+  },
+  {
+    label: 'Miami International',
+    searchValue: ['mia', 'miami', 'miami international'],
+    value: 'MIA',
+  },
+  {
+    label: "Chicago O'Hare International",
+    searchValue: ['ord', 'ohare', 'chicago', "chicago o'hare international"],
+    value: 'ORD',
+  },
+  {
+    label: 'Portland International',
+    searchValue: ['pdx', 'portland', 'portland international'],
+    value: 'PDX',
+  },
+  {
+    label: 'San Diego International',
+    searchValue: ['san', 'san diego', 'san diego international'],
+    value: 'SAN',
+  },
+  {
+    label: 'San Francisco International',
+    searchValue: ['sfo', 'san francisco', 'san francisco international'],
+    value: 'SFO',
+  },
+  {
+    disabled: true,
+    label: 'San Jose Mineta International',
+    searchValue: ['sjc', 'san jose', 'san jose mineta international'],
+    value: 'SJC',
+  },
+]
+
+const comboboxCss = css({
+  width: '16rem',
+})
+
+const stackCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.sm,
+  width: '100%',
+})
+
+const fieldCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.xs,
+})
+
+const labelCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.xs,
+  fontWeight: theme.fontWeight.semibold,
+  color: theme.colors.text.primary,
+})
+
+const helpCss = css({
+  fontSize: theme.fontSize.xs,
+  lineHeight: theme.lineHeight.relaxed,
+  color: theme.colors.text.secondary,
+})
+
+const valueCss = css({
+  margin: 0,
+  fontFamily: theme.fontFamily.mono,
+  fontSize: theme.fontSize.xs,
+  color: theme.colors.text.secondary,
+})

package/src/components/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/components/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.