@remix-run/ui 0.1.1 → 0.2.0

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

@@ -31,7 +31,7 @@ export function createGlyphSheet(values: GlyphValues): GlyphSheetComponent {
     >,
   )
 
-  function GlyphSheet(handle: Handle<GlyphSheetProps>) {
+  function GlyphSheet(handle: Handle<GlyphSheetProps>): () => RemixElement {
     return () => {
       let { style, ...svgProps } = handle.props
       let hiddenStyle = {
@@ -70,7 +70,7 @@ export function createGlyphSheet(values: GlyphValues): GlyphSheetComponent {
   })
 }
 
-export function Glyph(handle: Handle<GlyphProps>) {
+export function Glyph(handle: Handle<GlyphProps>): () => RemixElement {
   return () => {
     let { fill, name, ...svgProps } = handle.props
     let glyphId = glyphContract[name].id

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.

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

@@ -0,0 +1,101 @@
+import { css, on, type Handle } from '@remix-run/ui'
+import { Glyph } from '@remix-run/ui/glyph'
+import * as listbox from '@remix-run/ui/listbox'
+import type { ListboxValue } from '@remix-run/ui/listbox'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Listbox Overview
+ * @description A keyboard-navigable listbox with selection, highlighting, and an optional flash-selection animation.
+ */
+export default function Example(handle: Handle) {
+  let value: ListboxValue = options[0]!.value
+  let activeValue: ListboxValue = options[0]!.value
+  let flashSelection = false
+
+  return () => {
+    return (
+      <div mix={stackCss}>
+        <listbox.Context
+          value={value}
+          activeValue={activeValue}
+          flashSelection={flashSelection}
+          onSelect={(nextValue) => {
+            value = nextValue
+            handle.update()
+          }}
+          onHighlight={(nextActiveValue) => {
+            activeValue = nextActiveValue
+            handle.update()
+          }}
+        >
+          <div tabIndex={0} mix={[listbox.listStyle, listbox.list(), containerCss]}>
+            {options.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>
+        <div mix={controlsCss}>
+          <label mix={checkboxLabelCss}>
+            <input
+              type="checkbox"
+              defaultChecked={flashSelection}
+              mix={on('change', (event) => {
+                flashSelection = event.currentTarget.checked
+                handle.update()
+              })}
+            />{' '}
+            Flash selection
+          </label>
+          <p mix={valueCss}>{`value=${value ?? 'null'}`}</p>
+        </div>
+      </div>
+    )
+  }
+}
+
+const options = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+  { label: 'Date', value: 'date' },
+  { label: 'Elderberry', value: 'elderberry' },
+  { label: 'Fig', value: 'fig' },
+  { label: 'Grape', value: 'grape' },
+] as const
+
+const containerCss = css({
+  borderColor: theme.colors.border.subtle,
+  padding: theme.space.xs,
+  borderRadius: theme.radius.lg,
+  borderStyle: 'solid',
+})
+
+const stackCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.md,
+  width: '100%',
+})
+
+const controlsCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.xs,
+})
+
+const checkboxLabelCss = css({
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.normal,
+  color: theme.colors.text.secondary,
+})
+
+const valueCss = css({
+  margin: 0,
+  fontFamily: theme.fontFamily.mono,
+  fontSize: theme.fontSize.xs,
+  color: theme.colors.text.secondary,
+})