@duro-app/ui 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.24.0"
+    "@duro-app/tokens": "^0.25.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ButtonGroup/ButtonGroup.meta.ts

@@ -14,8 +14,16 @@ export const meta: ComponentMeta = {
     'Navigation items — use Inline or SideNav',
   ],
   relatedTo: [
-    {component: 'Inline', relationship: 'Inline is a general-purpose horizontal layout; ButtonGroup adds role="group" and disabled support'},
-    {component: 'ActionBar', relationship: 'ActionBar is a floating bulk-selection toolbar; ButtonGroup is a static grouping'},
+    {
+      component: 'Inline',
+      relationship:
+        'Inline is a general-purpose horizontal layout; ButtonGroup adds role="group" and disabled support',
+    },
+    {
+      component: 'ActionBar',
+      relationship:
+        'ActionBar is a floating bulk-selection toolbar; ButtonGroup is a static grouping',
+    },
   ],
   example: `<ButtonGroup align="end" gap="sm">
   <Button variant="secondary">Cancel</Button>

package/src/components/CheckboxGroup/CheckboxGroup.meta.ts

@@ -13,7 +13,10 @@ export const meta: ComponentMeta = {
     'Many options (10+) — consider a filterable list or Select with multi-select',
   ],
   relatedTo: [
-    {component: 'RadioGroup', relationship: 'RadioGroup for single-select; CheckboxGroup for multi-select'},
+    {
+      component: 'RadioGroup',
+      relationship: 'RadioGroup for single-select; CheckboxGroup for multi-select',
+    },
     {component: 'Checkbox', relationship: 'CheckboxGroup.Item wraps Checkbox internally'},
     {component: 'ToggleGroup', relationship: 'ToggleGroup for toolbar-style multi-select'},
   ],

package/src/components/CheckboxGroup/CheckboxGroup.tsx

@@ -46,9 +46,7 @@ function Root({
   const onToggle = useCallback(
     (itemValue: string, checked: boolean) => {
       if (disabled) return
-      const next = checked
-        ? [...value, itemValue]
-        : value.filter((v) => v !== itemValue)
+      const next = checked ? [...value, itemValue] : value.filter((v) => v !== itemValue)
       setValue(next)
     },
     [disabled, value, setValue],
@@ -88,12 +86,7 @@ function Item({value, disabled: itemDisabled = false, children}: ItemProps) {
   )
 
   return (
-    <Checkbox
-      value={value}
-      checked={isChecked}
-      disabled={isDisabled}
-      onChange={handleChange}
-    >
+    <Checkbox value={value} checked={isChecked} disabled={isDisabled} onChange={handleChange}>
       {children}
     </Checkbox>
   )

package/src/components/Combobox/Combobox.meta.ts

@@ -0,0 +1,35 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Searchable dropdown for selecting a value from a filterable list. Combines a text input with a popup listbox. Compound component — Root is required.',
+  whenToUse: [
+    'Large option lists where users benefit from typing to filter (e.g. country, city, user picker)',
+    'Autocomplete or typeahead scenarios',
+    'Table column filters with known categorical values',
+  ],
+  whenNotToUse: [
+    'Small lists (fewer than 7 options) — use Select instead',
+    'Free-form text entry — use Input',
+    'Multiple selections — use CheckboxGroup or ToggleGroup',
+  ],
+  anatomy: {
+    required: ['Root', 'Input', 'Popup', 'Item'],
+    optional: ['Empty'],
+  },
+  relatedTo: [
+    {component: 'Select', relationship: 'Select for short lists without search; Combobox for long filterable lists'},
+    {component: 'Input', relationship: 'Input for free-form text; Combobox for constrained selection'},
+    {component: 'Menu', relationship: 'Menu triggers actions; Combobox picks a value'},
+  ],
+  example: `<Combobox.Root name="country" defaultValue="us" initialLabels={{us: 'United States'}}>
+  <Combobox.Input placeholder="Search countries…" />
+  <Combobox.Popup>
+    <Combobox.Item value="us">United States</Combobox.Item>
+    <Combobox.Item value="gb">United Kingdom</Combobox.Item>
+    <Combobox.Item value="fr">France</Combobox.Item>
+    <Combobox.Item value="de">Germany</Combobox.Item>
+    <Combobox.Empty>No countries found</Combobox.Empty>
+  </Combobox.Popup>
+</Combobox.Root>`,
+}

package/src/components/Combobox/Combobox.stories.tsx

@@ -0,0 +1,119 @@
+import {useState} from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {Combobox} from './Combobox'
+
+const meta: Meta = {
+  title: 'Components/Combobox',
+}
+
+export default meta
+type Story = StoryObj
+
+const fruits = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape', 'Honeydew']
+
+export const Default: Story = {
+  render: () => (
+    <Combobox.Root>
+      <Combobox.Input placeholder="Search fruit...">
+        <Combobox.Trigger />
+      </Combobox.Input>
+      <Combobox.Popup>
+        {fruits.map((fruit) => (
+          <Combobox.Item key={fruit} value={fruit.toLowerCase()}>
+            <Combobox.ItemText>{fruit}</Combobox.ItemText>
+          </Combobox.Item>
+        ))}
+        <Combobox.Empty>No fruits found</Combobox.Empty>
+      </Combobox.Popup>
+    </Combobox.Root>
+  ),
+  play: async ({canvas}) => {
+    const input = canvas.getByRole('combobox')
+    await expect(input).toBeInTheDocument()
+    await expect(input).toHaveAttribute('aria-expanded', 'false')
+  },
+}
+
+export const WithDefaultValue: Story = {
+  render: () => (
+    <Combobox.Root defaultValue="cherry" initialLabels={{cherry: 'Cherry'}}>
+      <Combobox.Input placeholder="Search fruit...">
+        <Combobox.Trigger />
+      </Combobox.Input>
+      <Combobox.Popup>
+        {fruits.map((fruit) => (
+          <Combobox.Item key={fruit} value={fruit.toLowerCase()}>
+            <Combobox.ItemText>{fruit}</Combobox.ItemText>
+          </Combobox.Item>
+        ))}
+        <Combobox.Empty>No fruits found</Combobox.Empty>
+      </Combobox.Popup>
+    </Combobox.Root>
+  ),
+  play: async ({canvas}) => {
+    const input = canvas.getByRole('combobox')
+    await expect(input).toHaveValue('Cherry')
+  },
+}
+
+function ControlledDemo() {
+  const [value, setValue] = useState<string | null>(null)
+
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
+      <Combobox.Root value={value} onValueChange={setValue}>
+        <Combobox.Input placeholder="Pick a role...">
+          <Combobox.Trigger />
+        </Combobox.Input>
+        <Combobox.Popup>
+          <Combobox.Item value="admin"><Combobox.ItemText>Admin</Combobox.ItemText></Combobox.Item>
+          <Combobox.Item value="editor"><Combobox.ItemText>Editor</Combobox.ItemText></Combobox.Item>
+          <Combobox.Item value="viewer"><Combobox.ItemText>Viewer</Combobox.ItemText></Combobox.Item>
+          <Combobox.Item value="moderator"><Combobox.ItemText>Moderator</Combobox.ItemText></Combobox.Item>
+          <Combobox.Item value="analyst"><Combobox.ItemText>Analyst</Combobox.ItemText></Combobox.Item>
+          <Combobox.Empty>No roles found</Combobox.Empty>
+        </Combobox.Popup>
+      </Combobox.Root>
+      <span style={{fontSize: 14, color: '#888'}}>
+        Selected: {value ?? 'none'}
+      </span>
+    </div>
+  )
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledDemo />,
+  play: async ({canvas}) => {
+    await expect(canvas.getByText('Selected: none')).toBeInTheDocument()
+  },
+}
+
+export const ManyItems: Story = {
+  render: () => {
+    const countries = [
+      'Argentina', 'Australia', 'Austria', 'Belgium', 'Brazil', 'Canada',
+      'Chile', 'China', 'Colombia', 'Denmark', 'Egypt', 'Finland',
+      'France', 'Germany', 'Greece', 'India', 'Indonesia', 'Ireland',
+      'Italy', 'Japan', 'Kenya', 'Mexico', 'Netherlands', 'New Zealand',
+      'Norway', 'Peru', 'Poland', 'Portugal', 'South Korea', 'Spain',
+      'Sweden', 'Switzerland', 'Thailand', 'Turkey', 'United Kingdom', 'United States',
+    ]
+
+    return (
+      <Combobox.Root>
+        <Combobox.Input placeholder="Search country...">
+          <Combobox.Trigger />
+        </Combobox.Input>
+        <Combobox.Popup>
+          {countries.map((country) => (
+            <Combobox.Item key={country} value={country.toLowerCase()}>
+              <Combobox.ItemText>{country}</Combobox.ItemText>
+            </Combobox.Item>
+          ))}
+          <Combobox.Empty>No countries found</Combobox.Empty>
+        </Combobox.Popup>
+      </Combobox.Root>
+    )
+  },
+}

package/src/components/Combobox/Combobox.tsx

@@ -0,0 +1,247 @@
+import {type ReactNode, useRef, useId, useEffect, useState} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {ComboboxContext, useCombobox} from './ComboboxContext'
+import {useComboboxRoot} from './useComboboxRoot'
+
+// --- Root ---
+interface RootProps {
+  name?: string
+  defaultValue?: string
+  value?: string
+  onValueChange?: (value: string | null) => void
+  inputValue?: string
+  onInputChange?: (value: string) => void
+  initialLabels?: Record<string, string>
+  children: ReactNode
+}
+
+function Root({
+  name,
+  defaultValue,
+  value,
+  onValueChange,
+  inputValue,
+  onInputChange,
+  initialLabels,
+  children,
+}: RootProps) {
+  const {ctx, rootRef} = useComboboxRoot({
+    defaultValue,
+    value,
+    onValueChange,
+    inputValue,
+    onInputChange,
+    initialLabels,
+  })
+
+  return (
+    <ComboboxContext.Provider value={ctx}>
+      <html.div ref={rootRef} style={styles.root}>
+        {name && <html.input type="hidden" name={name} value={ctx.value ?? ''} />}
+        {children}
+      </html.div>
+    </ComboboxContext.Provider>
+  )
+}
+
+// --- Input ---
+function Input({placeholder, children}: {placeholder?: string; children?: ReactNode}) {
+  const {
+    open,
+    openPopup,
+    close,
+    inputValue,
+    setInputValue,
+    listboxId,
+    highlightedId,
+    inputRef,
+  } = useCombobox()
+  const localRef = useRef<HTMLInputElement>(null)
+  const [focused, setFocused] = useState(false)
+
+  useEffect(() => {
+    inputRef.current = localRef.current
+  })
+
+  return (
+    <html.div style={[styles.inputWrapper, focused && styles.inputWrapperFocused]}>
+      <html.input
+        ref={localRef}
+        type="text"
+        role={'combobox' as 'listbox'}
+        value={inputValue}
+        placeholder={placeholder}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-controls={open ? listboxId : undefined}
+        aria-activedescendant={highlightedId ?? undefined}
+        aria-autocomplete={'list' as 'none'}
+        autoComplete="off"
+        style={styles.input}
+        onFocus={() => {
+          setFocused(true)
+          openPopup()
+        }}
+        onBlur={() => {
+          setFocused(false)
+          // Delay close to allow item click to register
+          setTimeout(close, 150)
+        }}
+        onChange={(e: any) => {
+          setInputValue(e.target.value)
+          if (!open) openPopup()
+        }}
+      />
+      {children}
+    </html.div>
+  )
+}
+
+// --- Trigger ---
+function Trigger({children}: {children?: ReactNode}) {
+  const {open, openPopup, close, inputRef} = useCombobox()
+
+  return (
+    <html.button
+      type="button"
+      tabIndex={-1}
+      aria-label={open ? 'Close' : 'Open'}
+      onClick={() => {
+        if (open) {
+          close()
+        } else {
+          openPopup()
+        }
+        inputRef.current?.focus()
+      }}
+      style={styles.trigger}
+    >
+      {children ?? (
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M6 9l6 6 6-6" />
+        </svg>
+      )}
+    </html.button>
+  )
+}
+
+// --- Popup ---
+function Popup({children}: {children: ReactNode}) {
+  const {open, listboxId} = useCombobox()
+
+  if (!open) return null
+
+  return (
+    <html.div
+      id={listboxId}
+      role="listbox"
+      style={styles.popup}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+// --- Item ---
+interface ItemProps {
+  value: string
+  children: ReactNode
+}
+
+function Item({value: itemValue, children}: ItemProps) {
+  const {
+    value: selectedValue,
+    setValue,
+    inputValue,
+    labels,
+    registerLabel,
+    highlightedId,
+    setHighlightedId,
+    registerItem,
+  } = useCombobox()
+  const id = useId()
+  const ref = useRef<HTMLDivElement>(null)
+  const isSelected = selectedValue === itemValue
+  const isHighlighted = highlightedId === id
+
+  // Filter: check if this item matches the input
+  const label = labels[itemValue] ?? itemValue
+  const query = inputValue.toLowerCase()
+  const isVisible = !query || label.toLowerCase().includes(query)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const text = el.textContent
+    if (text) registerLabel(itemValue, text)
+  }, [itemValue, registerLabel])
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    return registerItem(id, itemValue, el)
+  }, [id, itemValue, registerItem])
+
+  if (!isVisible) return null
+
+  return (
+    <html.div
+      ref={ref}
+      id={id}
+      role="option"
+      aria-selected={isSelected}
+      onClick={() => setValue(itemValue)}
+      onPointerEnter={() => setHighlightedId(id)}
+      style={[
+        styles.item,
+        isSelected && styles.itemSelected,
+        isHighlighted && styles.itemHighlighted,
+      ]}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+// --- ItemText ---
+function ItemText({children}: {children: ReactNode}) {
+  return <html.span>{children}</html.span>
+}
+
+// --- Empty ---
+function Empty({children}: {children: ReactNode}) {
+  const {open, inputValue, labels} = useCombobox()
+
+  if (!open) return null
+
+  // Check if any items are visible
+  const query = inputValue.toLowerCase()
+  const hasVisibleItems = query
+    ? Object.values(labels).some((label) => label.toLowerCase().includes(query))
+    : true
+
+  if (hasVisibleItems) return null
+
+  return <html.div style={styles.empty}>{children}</html.div>
+}
+
+export const Combobox = {
+  Root,
+  Input,
+  Trigger,
+  Popup,
+  Item,
+  ItemText,
+  Empty,
+}

package/src/components/Combobox/ComboboxContext.ts

@@ -0,0 +1,26 @@
+import {createContext, useContext} from 'react'
+
+export interface ComboboxContextValue {
+  open: boolean
+  openPopup: () => void
+  close: () => void
+  value: string | null
+  setValue: (value: string) => void
+  inputValue: string
+  setInputValue: (value: string) => void
+  labels: Record<string, string>
+  registerLabel: (value: string, label: string) => void
+  listboxId: string
+  highlightedId: string | null
+  setHighlightedId: (id: string | null) => void
+  registerItem: (id: string, value: string, element: HTMLElement) => () => void
+  inputRef: React.RefObject<HTMLInputElement | null>
+}
+
+export const ComboboxContext = createContext<ComboboxContextValue | null>(null)
+
+export function useCombobox() {
+  const ctx = useContext(ComboboxContext)
+  if (!ctx) throw new Error('Combobox compound components must be used within Combobox.Root')
+  return ctx
+}

package/src/components/Combobox/styles.css.ts

@@ -0,0 +1,119 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+
+export const styles = css.create({
+  root: {
+    position: 'relative',
+    display: 'inline-flex',
+  },
+  inputWrapper: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.xs,
+    backgroundColor: colors.bgCard,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: {
+      default: colors.border,
+      ':hover': colors.accent,
+    },
+    borderRadius: radii.sm,
+    transitionProperty: 'border-color',
+    transitionDuration: '150ms',
+  },
+  inputWrapperFocused: {
+    borderColor: colors.accent,
+  },
+  input: {
+    flex: 1,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+    outline: 'none',
+    minWidth: 0,
+  },
+  trigger: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.xs,
+    paddingRight: spacing.xs,
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+    color: colors.textMuted,
+    cursor: 'pointer',
+  },
+  backdrop: {
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: 49,
+  },
+  popup: {
+    position: 'absolute',
+    top: '100%',
+    left: 0,
+    right: 0,
+    marginTop: spacing.xs,
+    backgroundColor: colors.bgCard,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    boxShadow: shadows.md,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    maxHeight: 200,
+    overflowY: 'auto',
+    zIndex: 50,
+  },
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontSize: typography.fontSizeSm,
+    fontFamily: typography.fontFamily,
+    color: colors.text,
+    cursor: 'pointer',
+    backgroundColor: 'transparent',
+    transitionProperty: 'background-color',
+    transitionDuration: '150ms',
+  },
+  itemSelected: {
+    color: colors.accent,
+    fontWeight: typography.fontWeightMedium,
+  },
+  itemHighlighted: {
+    backgroundColor: colors.bgCardHover,
+  },
+  itemHidden: {
+    display: 'none',
+  },
+  empty: {
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontSize: typography.fontSizeSm,
+    color: colors.textMuted,
+  },
+  hidden: {
+    display: 'none',
+  },
+})