@remix-run/ui 0.1.1 → 0.2.0

package/src/components/popover/popover.ts

@@ -4,7 +4,9 @@ import {
   css,
   on,
   type CSSMixinDescriptor,
+  type ElementProps,
   type Handle,
+  type MixinFactory,
   type RemixNode,
 } from '@remix-run/ui'
 import { anchor as positionAnchor, type AnchorOptions } from '../anchor/anchor.ts'
@@ -75,7 +77,7 @@ const popoverSurfaceCss: CSSMixinDescriptor = css({
 export const contentStyle = popoverContentCss
 export const surfaceStyle = [popoverSurfaceCss, popoverSurfaceTransitionCss] as const
 
-function PopoverProvider(handle: Handle<PopoverProps, PopoverContext>) {
+function PopoverProvider(handle: Handle<PopoverProps, PopoverContext>): () => RemixNode {
   handle.context.set({
     hideFocusTarget: null,
     showFocusTarget: null,
@@ -99,7 +101,10 @@ export interface PopoverHideRequest {
   target?: Node | null
 }
 
-const anchorMixin = createMixin<HTMLElement, [options: AnchorOptions]>((handle) => {
+const anchorMixin: MixinFactory<HTMLElement, [options: AnchorOptions], ElementProps> = createMixin<
+  HTMLElement,
+  [options: AnchorOptions]
+>((handle) => {
   let context = handle.context.get(PopoverProvider)
   return (options) => {
     handle.queueTask((node) => {
@@ -108,91 +113,97 @@ const anchorMixin = createMixin<HTMLElement, [options: AnchorOptions]>((handle)
   }
 })
 
-const surfaceMixin = createMixin<HTMLElement, [options: PopoverSurfaceOptions]>((handle) => {
-  let openProp = false
-  let cleanupAnchor = () => {}
-  let unlockScroll = () => {}
-  let context = handle.context.get(PopoverProvider)
-
-  handle.queueTask((node, signal) => {
-    context.surface = node
-
-    signal.addEventListener('abort', () => {
-      if (context.surface === node) {
-        context.surface = null
-      }
-    })
-  })
+const surfaceMixin: MixinFactory<HTMLElement, [options: PopoverSurfaceOptions], ElementProps> =
+  createMixin<HTMLElement, [options: PopoverSurfaceOptions]>((handle) => {
+    let openProp = false
+    let cleanupAnchor = () => {}
+    let unlockScroll = () => {}
+    let context = handle.context.get(PopoverProvider)
 
-  return (options) => {
-    let wasOpen = openProp
-    openProp = options.open
-
-    handle.queueTask(async (node) => {
-      if (openProp && !wasOpen) {
-        node.showPopover()
-      } else if (!openProp && wasOpen) {
-        node.hidePopover()
-      }
-    })
+    handle.queueTask((node, signal) => {
+      context.surface = node
 
-    return [
-      attrs({ popover: 'manual' }),
-
-      on('beforetoggle', (event) => {
-        if (event.newState === 'open') {
-          cleanupAnchor = positionAnchor(
-            event.currentTarget,
-            context.anchor!.node,
-            context.anchor!.options,
-          )
-          unlockScroll = lockScroll()
-        } else if (event.newState === 'closed') {
-          cleanupAnchor()
-          unlockScroll()
+      signal.addEventListener('abort', () => {
+        if (context.surface === node) {
+          context.surface = null
         }
-      }),
+      })
+    })
 
-      on('toggle', async (event) => {
-        if (event.newState === 'open') {
-          context.showFocusTarget?.focus()
-        } else if (event.newState === 'closed' && options.restoreFocusOnHide !== false) {
-          context.hideFocusTarget?.focus()
-        }
-      }),
+    return (options) => {
+      let wasOpen = openProp
+      openProp = options.open
 
-      on('keydown', (event) => {
-        if (event.key === 'Escape') {
-          event.preventDefault()
-          options.onHide({ reason: 'escape-key' })
+      handle.queueTask(async (node) => {
+        if (openProp && !wasOpen) {
+          node.showPopover()
+        } else if (!openProp && wasOpen) {
+          node.hidePopover()
         }
-      }),
-
-      onOutsideClick(
-        openProp,
-        (target) => {
-          options.onHide({ reason: 'outside-click', target })
-        },
-        (target) => options.closeOnAnchorClick === false && !!context.anchor?.node.contains(target),
-        options.stopOutsideClickPropagation ?? true,
-      ),
-    ]
-  }
-})
-
-const focusOnShowMixin = createMixin<HTMLElement, []>((handle) => {
-  handle.addEventListener('insert', (event) => {
-    let context = handle.context.get(PopoverProvider)
-    context.showFocusTarget = event.node
+      })
+
+      return [
+        attrs({ popover: 'manual' }),
+
+        on('beforetoggle', (event) => {
+          if (event.newState === 'open') {
+            cleanupAnchor = positionAnchor(
+              event.currentTarget,
+              context.anchor!.node,
+              context.anchor!.options,
+            )
+            unlockScroll = lockScroll()
+          } else if (event.newState === 'closed') {
+            cleanupAnchor()
+            unlockScroll()
+          }
+        }),
+
+        on('toggle', async (event) => {
+          if (event.newState === 'open') {
+            context.showFocusTarget?.focus()
+          } else if (event.newState === 'closed' && options.restoreFocusOnHide !== false) {
+            context.hideFocusTarget?.focus()
+          }
+        }),
+
+        on('keydown', (event) => {
+          if (event.key === 'Escape') {
+            event.preventDefault()
+            options.onHide({ reason: 'escape-key' })
+          }
+        }),
+
+        onOutsideClick(
+          openProp,
+          (target) => {
+            options.onHide({ reason: 'outside-click', target })
+          },
+          (target) =>
+            options.closeOnAnchorClick === false && !!context.anchor?.node.contains(target),
+          options.stopOutsideClickPropagation ?? true,
+        ),
+      ]
+    }
   })
-})
 
-const focusOnHideMixin = createMixin<HTMLElement, []>((handle) => {
-  handle.addEventListener('insert', (event) => {
-    let context = handle.context.get(PopoverProvider)
-    context.hideFocusTarget = event.node
-  })
-})
+const focusOnShowMixin: MixinFactory<HTMLElement, [], ElementProps> = createMixin<HTMLElement, []>(
+  (handle) => {
+    handle.addEventListener('insert', (event) => {
+      let context = handle.context.get(PopoverProvider)
+      context.showFocusTarget = event.node
+    })
+  },
+)
+
+const focusOnHideMixin: MixinFactory<HTMLElement, [], ElementProps> = createMixin<HTMLElement, []>(
+  (handle) => {
+    handle.addEventListener('insert', (event) => {
+      let context = handle.context.get(PopoverProvider)
+      context.hideFocusTarget = event.node
+    })
+  },
+)
 
 export const Context = PopoverProvider
 export const anchor = anchorMixin

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,
+})