@remix-run/ui 0.1.0 → 0.1.2

package/src/components/popover/README.md

@@ -8,9 +8,9 @@ Use it for custom surfaces like filters, inspectors, and view options. Higher-le
 
 ```tsx
 import { css, on, type Handle } from 'remix/ui'
-import { Button } from '@remix-run/ui/button'
-import { Glyph } from '@remix-run/ui/glyph'
-import { popover } from '@remix-run/ui/popover'
+import { Button } from 'remix/ui/button'
+import { Glyph } from 'remix/ui/glyph'
+import { popover } from 'remix/ui/popover'
 
 export function ViewOptions(handle: Handle) {
   let open = false

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

@@ -0,0 +1,143 @@
+import { css, on, type Handle } from '@remix-run/ui'
+import { Button } from '@remix-run/ui/button'
+import { Glyph } from '@remix-run/ui/glyph'
+import * as popover from '@remix-run/ui/popover'
+import { Option, Select } from '@remix-run/ui/select'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Popover Overview
+ * @description A popover panel anchored to a trigger button, containing form controls and a close action.
+ */
+export default function Example(handle: Handle) {
+  let open = false
+
+  function closePopover() {
+    open = false
+    void handle.update()
+  }
+
+  return () => (
+    <popover.Context>
+      <div mix={buttonRowCss}>
+        <Button
+          endIcon={<Glyph name="chevronDown" />}
+          mix={[
+            popover.anchor({ placement: 'bottom' }),
+            popover.focusOnHide(),
+            on('click', () => {
+              open = !open
+              void handle.update()
+            }),
+          ]}
+          tone="secondary"
+        >
+          View options
+        </Button>
+      </div>
+
+      <div
+        mix={[
+          popover.surfaceStyle,
+          popover.surface({
+            closeOnAnchorClick: false,
+            open,
+            onHide() {
+              closePopover()
+            },
+          }),
+        ]}
+      >
+        <div mix={[popover.contentStyle, panelCss]}>
+          <div mix={fieldCss}>
+            <label for={`${handle.id}-grouping`} mix={labelCss}>
+              Grouping
+            </label>
+            <Select
+              id={`${handle.id}-grouping`}
+              defaultLabel="No grouping"
+              defaultValue="none"
+              mix={[fieldSelectCss, popover.focusOnShow()]}
+            >
+              <Option label="No grouping" value="none" />
+              <Option label="Status" value="status" />
+              <Option label="Priority" value="priority" />
+            </Select>
+          </div>
+
+          <div mix={fieldCss}>
+            <label for={`${handle.id}-ordering`} mix={labelCss}>
+              Ordering
+            </label>
+            <Select
+              id={`${handle.id}-ordering`}
+              defaultLabel="Manual"
+              defaultValue="manual"
+              mix={fieldSelectCss}
+            >
+              <Option label="Manual" value="manual" />
+              <Option label="Newest first" value="newest" />
+              <Option label="Oldest first" value="oldest" />
+            </Select>
+          </div>
+
+          <div mix={fieldCss}>
+            <label for={`${handle.id}-closed-projects`} mix={labelCss}>
+              Show closed projects
+            </label>
+            <Select
+              id={`${handle.id}-closed-projects`}
+              defaultLabel="All"
+              defaultValue="all"
+              mix={fieldSelectCss}
+            >
+              <Option label="All" value="all" />
+              <Option label="Open only" value="open" />
+              <Option label="Closed only" value="closed" />
+            </Select>
+          </div>
+
+          <div mix={actionsCss}>
+            <Button mix={on('click', closePopover)} tone="ghost">
+              Done
+            </Button>
+          </div>
+        </div>
+      </div>
+    </popover.Context>
+  )
+}
+
+const buttonRowCss = css({
+  display: 'flex',
+  justifyContent: 'flex-start',
+})
+
+const panelCss = css({
+  display: 'grid',
+  gap: theme.space.md,
+  width: '22rem',
+  padding: theme.space.lg,
+})
+
+const fieldCss = css({
+  display: 'grid',
+  gap: theme.space.px,
+})
+
+const labelCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.xs,
+  fontWeight: theme.fontWeight.semibold,
+  color: theme.colors.text.primary,
+})
+
+const fieldSelectCss = css({
+  width: '100%',
+})
+
+const actionsCss = css({
+  display: 'flex',
+  justifyContent: 'flex-end',
+  paddingTop: theme.space.xs,
+})

package/src/components/select/README.md

@@ -0,0 +1,107 @@
+# select
+
+`Select` is a button-triggered popup value picker backed by `listbox` and `popover`. Use it when the user should choose one stable string value from a finite set.
+
+## Usage
+
+```tsx
+import { Option, Select, onSelectChange } from 'remix/ui/select'
+
+export function FrameworkSelect() {
+  return (
+    <Select
+      defaultLabel="Select a framework"
+      defaultValue="remix"
+      name="framework"
+      mix={onSelectChange((event) => {
+        console.log(event.value, event.label, event.optionId)
+      })}
+    >
+      <Option label="Remix framework" value="remix">
+        Remix
+      </Option>
+      <Option disabled label="React Router framework" value="react-router">
+        React Router
+      </Option>
+      <Option label="React framework" value="react">
+        React
+      </Option>
+    </Select>
+  )
+}
+```
+
+Use `textValue` when closed-trigger typeahead should match a different string from the visible label.
+
+```tsx
+<Select defaultLabel="Select an environment">
+  <Option label="Production environment" value="production">
+    Production
+  </Option>
+  <Option label="Staging environment" textValue="beta" value="staging">
+    Staging
+  </Option>
+</Select>
+```
+
+Use the lower-level primitives when the trigger or popup structure needs to be owned by another component. Keep the same provider, trigger, popover, list, option, and hidden-input relationship.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import * as button from 'remix/ui/button'
+import * as listbox from 'remix/ui/listbox'
+import * as popover from 'remix/ui/popover'
+import * as select from 'remix/ui/select'
+
+function SelectValue(handle: Handle) {
+  let context = handle.context.get(select.Context)
+
+  return () => <span mix={button.labelStyle}>{context.displayedLabel}</span>
+}
+
+function IssueTypeSelect() {
+  return () => (
+    <select.Context defaultLabel="Select a type" name="issueType">
+      <button type="button" mix={[button.baseStyle, select.triggerStyle, select.trigger()]}>
+        <SelectValue />
+      </button>
+      <popover.Context>
+        <div mix={[popover.surfaceStyle, select.popover()]}>
+          <div mix={[popover.contentStyle, listbox.listStyle, select.list()]}>
+            <div mix={[listbox.optionStyle, select.option({ label: 'Bug', value: 'bug' })]}>
+              Bug
+            </div>
+            <div mix={[listbox.optionStyle, select.option({ label: 'Feature', value: 'feature' })]}>
+              Feature
+            </div>
+          </div>
+        </div>
+      </popover.Context>
+      <input mix={select.hiddenInput()} />
+    </select.Context>
+  )
+}
+```
+
+## `select.*`
+
+- `Select`: composed trigger, popover, listbox, option list, and optional hidden input for form participation. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and button props.
+- `Option`: option wrapper that renders the standard check glyph and label slot. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `onSelectChange(...)`: event mixin for the bubbling `SelectChangeEvent`.
+- `Context`, `trigger()`, `popover()`, `list()`, `option(...)`, and `hiddenInput()`: lower-level composition primitives.
+- `triggerStyle`: standard select trigger style.
+- `SelectChangeEvent`: event with `value`, `label`, and `optionId`.
+- `SelectProps`, `SelectContextProps`, and `SelectOptionProps`: public TypeScript props for the composed and lower-level APIs.
+
+## Behavior Notes
+
+- `defaultLabel` is displayed before selection settles. `defaultValue` selects the matching option without replacing the trigger label until a new selection commits.
+- `Option.label` is the committed display label and event label. `children` are the rendered option contents.
+- Click, `ArrowDown`, and `ArrowUp` open the popup. Focus moves into the list and Escape restores focus to the trigger through popover behavior.
+- Reopening highlights the current selected value.
+- The popup min-width syncs to the trigger width before opening.
+- Closed-trigger typeahead selects a matching option immediately and supports option `textValue`.
+- Selecting an option flashes it with `data-select-flash`, waits for the close transition and label delay, updates the displayed label, and dispatches `SelectChangeEvent`.
+- Selecting the already-selected value updates state but does not dispatch a change event.
+- `SelectChangeEvent` bubbles from the trigger when a trigger exists. It includes `value`, `label`, and `optionId`.
+- Passing `name` renders a hidden input so the selected value participates in `FormData`; disabled selects disable the trigger and hidden input.

package/src/components/select/demos/deconstructed.demo.tsx

@@ -0,0 +1,95 @@
+import { css, type Handle } from '@remix-run/ui'
+import * as button from '@remix-run/ui/button'
+import { Glyph } from '@remix-run/ui/glyph'
+import * as listbox from '@remix-run/ui/listbox'
+import * as popover from '@remix-run/ui/popover'
+import * as select from '@remix-run/ui/select'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Select Deconstructed
+ * @description Build a fully custom select by composing the select, popover, and listbox primitives directly.
+ */
+export default function Example(handle: Handle) {
+  let label = 'Local'
+  let value = 'local'
+  let triggerId = `${handle.id}-trigger`
+
+  return () => (
+    <div
+      mix={[
+        stackCss,
+        select.onSelectChange((event) => {
+          label = event.label ?? 'Select an environment'
+          value = event.value ?? 'null'
+          void handle.update()
+        }),
+      ]}
+    >
+      <p mix={labelCss}>Environment</p>
+
+      <select.Context defaultLabel="Local" defaultValue="local" name="environment">
+        <button
+          id={triggerId}
+          type="button"
+          mix={[button.baseStyle, select.triggerStyle, select.trigger(), selectCss]}
+        >
+          <span mix={button.labelStyle}>{label}</span>
+          <Glyph mix={button.iconStyle} name="chevronVertical" />
+        </button>
+
+        <popover.Context>
+          <div mix={[popover.surfaceStyle, select.popover()]}>
+            <div
+              aria-labelledby={triggerId}
+              mix={[popover.contentStyle, listbox.listStyle, select.list()]}
+            >
+              {environmentOptions.map((option) => (
+                <div key={option.value} mix={[listbox.optionStyle, select.option(option)]}>
+                  <Glyph mix={listbox.glyphStyle} name="check" />
+                  <span mix={listbox.labelStyle}>{option.label}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+        </popover.Context>
+
+        <input mix={select.hiddenInput()} />
+      </select.Context>
+
+      <p mix={valueCss}>{`value=${value}`}</p>
+    </div>
+  )
+}
+
+const environmentOptions = [
+  { label: 'Local', value: 'local' },
+  { label: 'Staging', value: 'staging' },
+  { label: 'Production', value: 'production' },
+  { disabled: true, label: 'Archived', value: 'archived' },
+] as const
+
+const selectCss = css({
+  width: '16rem',
+})
+
+const stackCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.sm,
+  width: '100%',
+})
+
+const labelCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.xs,
+  fontWeight: theme.fontWeight.semibold,
+  color: theme.colors.text.primary,
+})
+
+const valueCss = css({
+  margin: 0,
+  fontFamily: theme.fontFamily.mono,
+  fontSize: theme.fontSize.xs,
+  color: theme.colors.text.secondary,
+})

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

@@ -0,0 +1,51 @@
+import { css } from '@remix-run/ui'
+import { Option, Select } from '@remix-run/ui/select'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Select Overview
+ * @description A styled select control with a searchable dropdown and accessible label.
+ */
+export default function Example() {
+  return () => (
+    <div mix={stackCss}>
+      <label for="fruit-select" mix={labelCss}>
+        Choose a fruit
+      </label>
+      <Select
+        id="fruit-select"
+        defaultLabel="Banana"
+        defaultValue="banana"
+        name="fruit"
+        mix={selectCss}
+      >
+        <Option label="Apple" value="apple" />
+        <Option label="Apricot" value="apricot" />
+        <Option label="Banana" value="banana" />
+        <Option label="Blackberry" value="blackberry" />
+        <Option label="Blackcurrant" value="blackcurrant" />
+        <Option label="Blueberry" value="blueberry" />
+        <Option label="Boysenberry" value="boysenberry" />
+        <Option label="Cantaloupe" value="cantaloupe" />
+      </Select>
+    </div>
+  )
+}
+
+const selectCss = css({
+  width: '16rem',
+})
+
+const stackCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.sm,
+  width: '100%',
+})
+
+const labelCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.xs,
+  fontWeight: theme.fontWeight.semibold,
+  color: theme.colors.text.primary,
+})

package/src/components/select/select.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   attrs,
   createElement,
@@ -8,6 +6,7 @@ import {
   on,
   ref,
   type CSSMixinDescriptor,
+  type Dispatched,
   type ElementProps,
   type Handle,
   type MixinHandle,
@@ -28,7 +27,10 @@ import type { AnchorOptions } from '../anchor/anchor.ts'
 const SELECT_CHANGE_EVENT = 'rmx:select-change' as const
 const LABEL_SWAP_DELAY_MS = 75
 
-type SelectChangeHandler = (event: SelectChangeEvent, signal: AbortSignal) => void | Promise<void>
+type SelectChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<SelectChangeEvent, target>,
+  signal: AbortSignal,
+) => void | Promise<void>
 
 declare global {
   interface HTMLElementEventMap {
@@ -74,12 +76,7 @@ export interface SelectProps extends Omit<Props<'button'>, 'children' | 'name'>
 
 export type SelectOptionProps = Props<'div'> & Omit<listbox.ListboxOption, 'id'>
 
-enum State {
-  Initializing = 'initializing',
-  Closed = 'closed',
-  Open = 'open',
-  Selecting = 'selecting',
-}
+type State = 'initializing' | 'closed' | 'open' | 'selecting'
 
 type PendingChange = {
   label: string | null
@@ -115,7 +112,7 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
   let surfaceRef: HTMLElement | undefined
   let popoverContextRef: popover.PopoverContext | undefined
 
-  let state: State = State.Initializing
+  let state: State = 'initializing'
 
   let value: listbox.ListboxValue = null
   let activeValue: listbox.ListboxValue = null
@@ -128,14 +125,14 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
   let listId = `${handle.id}-list`
 
   function open() {
-    if (state !== State.Closed || handle.props.disabled) return
-    state = State.Open
+    if (state !== 'closed' || handle.props.disabled) return
+    state = 'open'
     activeValue = value
     handle.update()
   }
 
   function syncPopoverMinWidth() {
-    if (state !== State.Open || !surfaceRef || !triggerRef) {
+    if (state !== 'open' || !surfaceRef || !triggerRef) {
       return
     }
 
@@ -165,8 +162,8 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
   }
 
   function close() {
-    if (state !== State.Open) return
-    state = State.Closed
+    if (state !== 'open') return
+    state = 'closed'
     handle.update()
   }
 
@@ -215,22 +212,22 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
     nextValue: listbox.ListboxValue,
     option: listbox.ListboxOption | undefined,
   ) {
-    if (state !== State.Open) return
+    if (state !== 'open') return
     pendingChange = getPendingChange(nextValue, option)
     setSelectedOption(nextValue, option)
     handle.update()
   }
 
   async function settleSelectedOption() {
-    if (state !== State.Open) return
+    if (state !== 'open') return
 
     let change = pendingChange
     pendingChange = null
-    state = State.Selecting
+    state = 'selecting'
 
     if (!surfaceRef) {
       displayedLabel = selectedLabel
-      state = State.Closed
+      state = 'closed'
       let signal = await handle.update()
       if (signal.aborted) return
       dispatchChange(change)
@@ -241,14 +238,14 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
     await wait(LABEL_SWAP_DELAY_MS) // UX delay label swap for clear value change
     if (handle.signal.aborted) return
     displayedLabel = selectedLabel
-    state = State.Closed
+    state = 'closed'
     let signal = await handle.update()
     if (signal.aborted) return
     dispatchChange(change)
   }
 
   function selectTypeaheadMatch(text: string) {
-    if (state !== State.Closed || handle.props.disabled) return
+    if (state !== 'closed' || handle.props.disabled) return
 
     let option = listboxRef?.matchSearchText(text, value)
     if (!option) return
@@ -266,7 +263,7 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
     nextActiveValue: listbox.ListboxValue,
     option: listbox.ListboxOption | undefined,
   ) {
-    if (state !== State.Open) return
+    if (state !== 'open') return
     activeValue = nextActiveValue
     activeId = option?.id
     handle.update()
@@ -286,11 +283,11 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
     },
 
     get isExpanded() {
-      return state === State.Open || state === State.Selecting
+      return state === 'open' || state === 'selecting'
     },
 
     get isOpen() {
-      return state === State.Open
+      return state === 'open'
     },
 
     get listId() {
@@ -356,11 +353,11 @@ function SelectProvider(handle: Handle<SelectContextProps, SelectContextValue>)
   })
 
   return () => {
-    if (state === State.Initializing) {
+    if (state === 'initializing') {
       selectedLabel = displayedLabel = handle.props.defaultLabel
       value = handle.props.defaultValue ?? null
       activeValue = value
-      state = State.Closed
+      state = 'closed'
 
       handle.queueTask(() => {
         if (selectedId || !surfaceRef) {
@@ -532,8 +529,11 @@ const select = {
   trigger,
 } as const
 
-export function onSelectChange(handler: SelectChangeHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof SELECT_CHANGE_EVENT>(SELECT_CHANGE_EVENT, handler, captureBoolean)
+export function onSelectChange<target extends HTMLElement>(
+  handler: SelectChangeHandler<target>,
+  captureBoolean?: boolean,
+) {
+  return on(SELECT_CHANGE_EVENT, handler, captureBoolean)
 }
 
 function SelectLabel(handle: Handle) {

package/src/components/tabs/tabs.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   attrs,
   css,
@@ -7,6 +5,7 @@ import {
   createMixin,
   on,
   type CSSMixinDescriptor,
+  type Dispatched,
   type ElementProps,
   type Handle,
   type MixinHandle,
@@ -18,7 +17,10 @@ import { theme } from '../../theme/theme.ts'
 
 const TABS_CHANGE_EVENT = 'rmx:tabs-change' as const
 
-type TabsChangeHandler = (event: TabsChangeEvent, signal: AbortSignal) => void | Promise<void>
+type TabsChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<TabsChangeEvent, target>,
+  signal: AbortSignal,
+) => void | Promise<void>
 
 const tabsListCss: CSSMixinDescriptor = css({
   display: 'inline-flex',
@@ -446,8 +448,11 @@ export const trigger = triggerMixin
 
 const tabs = { Context, list, panel, trigger } as const
 
-export function onTabsChange(handler: TabsChangeHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof TABS_CHANGE_EVENT>(TABS_CHANGE_EVENT, handler, captureBoolean)
+export function onTabsChange<target extends HTMLElement>(
+  handler: TabsChangeHandler<target>,
+  captureBoolean?: boolean,
+) {
+  return on(TABS_CHANGE_EVENT, handler, captureBoolean)
 }
 
 export function Tabs(handle: Handle<TabsProps>) {

package/src/index.ts

@@ -58,8 +58,8 @@ export type {
 } from './runtime/mixins/mixin.ts'
 export { TypedEventTarget } from './runtime/typed-event-target.ts'
 export { addEventListeners } from './runtime/event-listeners.ts'
+export type { Dispatched } from './runtime/event-listeners.ts'
 export { on } from './runtime/mixins/on-mixin.ts'
-export type { Dispatched } from './runtime/mixins/on-mixin.ts'
 export { link } from './runtime/mixins/link-mixin.ts'
 export { ref } from './runtime/mixins/ref-mixin.ts'
 export type { RefCallback } from './runtime/mixins/ref-mixin.ts'