@awarebydefault/display-case 1.0.0

package/src/ui/design-system/components/controls/Select.case.tsx

@@ -0,0 +1,48 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { Select } from './Select'
+
+const grouped = [
+  { label: 'Responsive', options: ['Responsive', 'Desktop', 'Tablet'] },
+  { label: 'Devices', options: ['iPhone 14', 'iPad', 'Pixel 7'] },
+]
+
+export default defineCases(
+  'Select',
+  {
+    Playground: {
+      tweaks: {
+        value: tweak.choice(['text', 'number', 'boolean'], 'number'),
+        size: tweak.choice(['sm', 'md'], 'md'),
+        disabled: tweak.boolean(false),
+      },
+      render: (t) => (
+        <Select
+          aria-label="Field type"
+          options={['text', 'number', 'boolean']}
+          defaultValue={t.value}
+          size={t.size as 'sm' | 'md'}
+          disabled={t.disabled}
+        />
+      ),
+    },
+    Options: () => (
+      <Select
+        aria-label="Field type"
+        options={['text', 'number', 'boolean']}
+        defaultValue="number"
+      />
+    ),
+    Grouped: () => (
+      <Select aria-label="Viewport" options={grouped} defaultValue="Desktop" />
+    ),
+    Disabled: () => (
+      <Select
+        aria-label="Field type"
+        options={['text', 'number']}
+        disabled
+        defaultValue="text"
+      />
+    ),
+  },
+  { level: 'atom' },
+)

package/src/ui/design-system/components/controls/Select.css

@@ -0,0 +1,44 @@
+.dcui-select {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+.dcui-select-el {
+  appearance: none;
+  -webkit-appearance: none;
+  font-family: var(--dc-font-sans);
+  font-size: var(--dc-text-base);
+  color: var(--dc-fg);
+  background: var(--dc-surface);
+  border: 1px solid var(--dc-border);
+  border-radius: var(--dc-radius-sm);
+  padding: 0 calc(var(--dc-space-8) + 0.5rem) 0 var(--dc-space-4);
+  height: 30px;
+  cursor: pointer;
+  transition:
+    border-color var(--dc-transition-fast),
+    background var(--dc-transition-fast);
+}
+.dcui-select-el:hover {
+  background: var(--dc-hover);
+}
+.dcui-select-el:focus-visible {
+  outline: 2px solid var(--dc-focus-ring);
+  outline-offset: 1px;
+}
+.dcui-select[data-size="sm"] .dcui-select-el {
+  height: 26px;
+  font-size: var(--dc-text-sm);
+}
+.dcui-select-caret {
+  position: absolute;
+  right: var(--dc-space-4);
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-sm);
+  color: var(--dc-fg-muted);
+  pointer-events: none;
+}
+.dcui-select-el:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/src/ui/design-system/components/controls/Select.placard.md

@@ -0,0 +1,15 @@
+**Select** — a native `<select>` styled to match the chrome (mono `▾` caret); reach for it to pick one value from a fixed set of choices.
+
+```tsx
+<Select options={['text', 'number', 'boolean']} value={kind} onChange={(e) => setKind(e.target.value)} />
+<Select options={[
+  { label: 'Responsive', options: ['Full', 'Desktop'] },
+  { label: 'Devices', options: ['iPhone 14', 'iPad'] },
+]} />
+```
+
+`onChange` emits a native `<select>` event — read `event.target.value`. Accepts plain options, grouped options, or arbitrary `<option>` children.
+
+For free-form text or number entry, use `Input`.
+
+Sizes: `sm` · `md` (default). Other native `<select>` props (`value`, `disabled`, …) spread onto the element.

package/src/ui/design-system/components/controls/Select.test.tsx

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { Select } from './Select'
+
+describe('Select', () => {
+  test('renders an aria-hidden caret beside the native control', () => {
+    const html = renderToStaticMarkup(<Select options={['a']} />)
+    expect(html).toContain('class="dcui-select"')
+    expect(html).toContain('class="dcui-select-el"')
+    expect(html).toContain('aria-hidden="true"')
+    expect(html).toContain('▾')
+  })
+
+  test('renders string options with value and label equal', () => {
+    const html = renderToStaticMarkup(<Select options={['light', 'dark']} />)
+    expect(html).toContain('<option value="light">light</option>')
+    expect(html).toContain('<option value="dark">dark</option>')
+  })
+
+  test('renders object options with a distinct value and label', () => {
+    const html = renderToStaticMarkup(
+      <Select options={[{ value: 'sm', label: 'Small' }]} />,
+    )
+    expect(html).toContain('<option value="sm">Small</option>')
+  })
+
+  test('renders grouped options as optgroups', () => {
+    const html = renderToStaticMarkup(
+      <Select
+        options={[
+          {
+            label: 'Devices',
+            options: ['iPhone', { value: 'ipad', label: 'iPad' }],
+          },
+        ]}
+      />,
+    )
+    expect(html).toContain('<optgroup label="Devices">')
+    expect(html).toContain('<option value="iPhone">iPhone</option>')
+    expect(html).toContain('<option value="ipad">iPad</option>')
+  })
+
+  test('arbitrary option children override the options prop', () => {
+    const html = renderToStaticMarkup(
+      <Select options={['ignored']}>
+        <option value="custom">Custom</option>
+      </Select>,
+    )
+    expect(html).toContain('<option value="custom">Custom</option>')
+    expect(html).not.toContain('ignored')
+  })
+
+  test('disabling propagates to the native select element', () => {
+    const html = renderToStaticMarkup(<Select options={['a']} disabled />)
+    expect(html).toContain('disabled')
+  })
+})

package/src/ui/design-system/components/controls/Select.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode, SelectHTMLAttributes } from 'react'
+
+/**
+ * Display Case — Select
+ * Native <select> styled to match the chrome, with a mono caret. Accepts plain
+ * options or grouped options (Responsive / Devices), or arbitrary <option>
+ * children.
+ */
+
+export type SelectSize = 'sm' | 'md'
+export type SelectOption = string | { value: string; label?: ReactNode }
+export interface SelectOptionGroup {
+  label: string
+  options: SelectOption[]
+}
+export type SelectItem = SelectOption | SelectOptionGroup
+
+export interface SelectProps
+  extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
+  options?: SelectItem[]
+  size?: SelectSize
+}
+
+function renderOption(o: SelectItem) {
+  if (o && typeof o === 'object' && 'options' in o) {
+    return (
+      <optgroup key={o.label} label={o.label}>
+        {o.options.map(renderOption)}
+      </optgroup>
+    )
+  }
+  const value = typeof o === 'string' ? o : o.value
+  const label = typeof o === 'string' ? o : (o.label ?? o.value)
+  return (
+    <option key={value} value={value}>
+      {label}
+    </option>
+  )
+}
+
+export function Select({
+  options = [],
+  size = 'md',
+  disabled = false,
+  children,
+  ...rest
+}: SelectProps) {
+  return (
+    <span className="dcui-select" data-size={size}>
+      <select className="dcui-select-el" disabled={disabled} {...rest}>
+        {children ?? options.map(renderOption)}
+      </select>
+      <span className="dcui-select-caret" aria-hidden="true">
+        ▾
+      </span>
+    </span>
+  )
+}

package/src/ui/design-system/components/controls/SelectMenu.case.tsx

@@ -0,0 +1,100 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { useState } from 'react'
+import { SelectMenu, type SelectMenuOption } from './SelectMenu'
+
+const FRUITS = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']
+
+// Disabled options stand in as non-interactive group headers (the chrome's
+// screen-size picker uses this for its Responsive / Devices groups).
+const GROUPED: SelectMenuOption[] = [
+  { value: '__responsive', label: 'Responsive', disabled: true },
+  { value: 'full', label: 'Full' },
+  { value: 'desktop', label: 'Desktop' },
+  { value: '__devices', label: 'Devices', disabled: true },
+  { value: 'ipad', label: 'iPad' },
+  { value: 'iphone', label: 'iPhone' },
+]
+
+// SelectMenu is controlled, so each specimen owns its selected value. The open
+// menu is an out-of-flow popup, so the specimen reserves height for it — the
+// stage hugs a component's natural box and would otherwise clip the menu (same
+// reason the floating TweaksPanel specimen reserves a sized surface).
+function Demo({
+  options,
+  initial,
+  size,
+  disabled,
+}: {
+  options: SelectMenuOption[]
+  initial: string
+  size?: 'sm' | 'md'
+  disabled?: boolean
+}) {
+  const [value, setValue] = useState(initial)
+  return (
+    <div
+      style={{
+        width: '14rem',
+        minHeight: '12rem',
+        display: 'flex',
+        alignItems: 'flex-start',
+      }}>
+      <SelectMenu
+        aria-label="Demo select"
+        options={options}
+        value={value}
+        onChange={setValue}
+        size={size}
+        disabled={disabled}
+      />
+    </div>
+  )
+}
+
+export default defineCases(
+  'SelectMenu',
+  {
+    Playground: {
+      tweaks: {
+        // The values to choose between — edit the comma-separated list to change
+        // the menu's options live.
+        options: tweak.text('Apple, Banana, Cherry, Date, Elderberry'),
+        // The selected value (any of the options above); you can also open the
+        // menu and pick in the stage.
+        value: tweak.text('Cherry'),
+        size: tweak.choice(['sm', 'md'], 'md'),
+        disabled: tweak.boolean(false),
+      },
+      // Re-seed when the options or starting value change; size/disabled flow in
+      // as props (no remount, so an in-stage pick survives toggling them).
+      render: (t) => {
+        const options = (t.options as string)
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+        return (
+          <Demo
+            key={`${t.options}|${t.value}`}
+            options={options}
+            initial={t.value as string}
+            size={t.size as 'sm' | 'md'}
+            disabled={t.disabled}
+          />
+        )
+      },
+    },
+    // Distinct `key` per case: the browse chrome swaps cases in place, so an
+    // unkeyed <Demo> would keep the previous case's selected value (and `Grouped`
+    // uses a different option set entirely) — see docs/writing-cases.md.
+    Default: () => <Demo key="default" options={FRUITS} initial="Cherry" />,
+    Small: () => (
+      <Demo key="small" options={FRUITS} initial="Apple" size="sm" />
+    ),
+    Disabled: () => (
+      <Demo key="disabled" options={FRUITS} initial="Banana" disabled />
+    ),
+    // Open the menu in the stage to see the group headers.
+    Grouped: () => <Demo key="grouped" options={GROUPED} initial="desktop" />,
+  },
+  { level: 'atom' },
+)

package/src/ui/design-system/components/controls/SelectMenu.css

@@ -0,0 +1,72 @@
+.dcui-selectmenu {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+/* The trigger borrows the native Select's chrome (.dcui-select-el) so the two
+   read identically, then layers in flex for the value + ellipsis. */
+.dcui-selectmenu-trigger {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  user-select: none;
+}
+.dcui-selectmenu-value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dcui-selectmenu-trigger[aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.dcui-selectmenu-list {
+  position: fixed;
+  z-index: 60;
+  margin: 0;
+  padding: var(--dc-space-2);
+  list-style: none;
+  background: var(--dc-surface);
+  border: 1px solid var(--dc-border);
+  border-radius: var(--dc-radius-md);
+  box-shadow: var(--dc-shadow-overlay);
+  overflow-y: auto;
+  min-width: max-content;
+}
+.dcui-selectmenu-option {
+  display: flex;
+  align-items: center;
+  gap: var(--dc-space-3);
+  padding: var(--dc-space-2) var(--dc-space-4);
+  border-radius: var(--dc-radius-sm);
+  font-family: var(--dc-font-sans);
+  font-size: var(--dc-text-sm);
+  color: var(--dc-fg);
+  cursor: pointer;
+  white-space: nowrap;
+}
+/* Active (keyboard or hover) — the single moving highlight. */
+.dcui-selectmenu-option[data-active="true"] {
+  background: var(--dc-hover);
+}
+/* A disabled option is a non-interactive group header (mono, uppercase, quiet)
+   — never highlighted, never the check column's concern. */
+.dcui-selectmenu-option[aria-disabled="true"] {
+  cursor: default;
+  color: var(--dc-fg-subtle);
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+.dcui-selectmenu-option[aria-disabled="true"][data-active="true"] {
+  background: none;
+}
+.dcui-selectmenu-check {
+  flex: 0 0 auto;
+  width: 1em;
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  color: var(--dc-fg-muted);
+}

package/src/ui/design-system/components/controls/SelectMenu.placard.md

@@ -0,0 +1,18 @@
+**SelectMenu** — an accessible custom single-select (WAI-ARIA "select-only combobox"): a styled trigger that opens a popup listbox. Looks like `Select`, but commits the picked value **instantly** with no native OS popup — reach for it when the choice drives a live view that must update the moment an option is clicked.
+
+```tsx
+<SelectMenu
+  aria-label="variant"
+  options={['primary', 'ghost', 'bare']}
+  value={variant}
+  onChange={setVariant}
+/>
+```
+
+Controlled only: pass `value` and an `onChange(value: string)` (the value, **not** an event — unlike `Select`). `options` are plain strings or `{ value, label }` for a display label that differs from the stored value.
+
+Why it exists: a native `<select>` on macOS defers its `change` event until the OS dropdown finishes dismissing, which visibly lags any live-updating preview. `SelectMenu` avoids that. Prefer the simpler **`Select`** (native) when there's no live binding, or when you need `<optgroup>` grouping (SelectMenu is flat).
+
+Accessibility: focus stays on the `role="combobox"` trigger; the active option is tracked via `aria-activedescendant`. Full keyboard parity with a native select — ↑/↓ move, Home/End jump, type-ahead matches by label, Enter/Space commit, Esc cancels, Tab commits then moves on. The popup portals to `document.body`, so an `overflow`-clipping or `position: fixed` ancestor won't trap it.
+
+Sizes: `sm` · `md` (default). `disabled` skips interaction and drops it from the tab order.

package/src/ui/design-system/components/controls/SelectMenu.test.tsx

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { SelectMenu } from './SelectMenu'
+
+// The popup listbox is portaled to document.body and only mounts while open;
+// SSR renders the closed trigger, so these assert the combobox's resting state.
+const noop = () => {}
+
+describe('SelectMenu', () => {
+  test('renders a closed combobox trigger with the listbox wiring', () => {
+    const html = renderToStaticMarkup(
+      <SelectMenu
+        options={['light', 'dark']}
+        value="light"
+        onChange={noop}
+        aria-label="Theme"
+      />,
+    )
+    expect(html).toContain('role="combobox"')
+    expect(html).toContain('aria-haspopup="listbox"')
+    expect(html).toContain('aria-expanded="false"')
+    expect(html).toContain('aria-label="Theme"')
+  })
+
+  test('shows the selected option label in the trigger', () => {
+    const html = renderToStaticMarkup(
+      <SelectMenu
+        options={[{ value: 'dark', label: 'Dark mode' }, 'light']}
+        value="dark"
+        onChange={noop}
+      />,
+    )
+    expect(html).toContain('Dark mode')
+  })
+
+  test('does not render the popup listbox while closed', () => {
+    const html = renderToStaticMarkup(
+      <SelectMenu options={['a', 'b']} value="a" onChange={noop} />,
+    )
+    expect(html).not.toContain('role="listbox"')
+    expect(html).not.toContain('role="option"')
+  })
+
+  test('an unknown value falls back to the first selectable option label', () => {
+    const html = renderToStaticMarkup(
+      <SelectMenu
+        options={[
+          { value: 'h', label: 'Group', disabled: true },
+          { value: 'one', label: 'First' },
+        ]}
+        value="nope"
+        onChange={noop}
+      />,
+    )
+    // The disabled header is skipped, so the first real option leads.
+    expect(html).toContain('First')
+  })
+
+  test('a disabled menu is taken out of the tab order and marked aria-disabled', () => {
+    const html = renderToStaticMarkup(
+      <SelectMenu options={['a']} value="a" onChange={noop} disabled />,
+    )
+    expect(html).toContain('aria-disabled="true"')
+    expect(html).toContain('tabindex="-1"')
+  })
+})