@proteos/ui 0.31.0

package/src/components/multi-select/multi-select.stories.tsx

@@ -0,0 +1,211 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { MultiSelect, type MultiSelectOption } from './multi-select'
+
+const meta: Meta<typeof MultiSelect> = {
+  title: 'Components/MultiSelect',
+  component: MultiSelect,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="w-[440px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof MultiSelect>
+
+/* ===== example data ======================================================= */
+
+// Plain text options — the chip and listbox row both render the string.
+const plainCarriers: MultiSelectOption<string>[] = [
+  { id: 'blue-ridge', label: 'Blue Ridge' },
+  { id: 'north-star', label: 'North Star' },
+  { id: 'sunline', label: 'Sunline' },
+  { id: 'cascade', label: 'Cascade' },
+  { id: 'atlantic', label: 'Atlantic' },
+  { id: 'pioneer', label: 'Pioneer' },
+]
+
+// Options with a small decoration alongside the label — shows that
+// `content` can be anything, not just a Badge.
+const carriersWithMeta: MultiSelectOption<string>[] = [
+  {
+    id: 'blue-ridge',
+    label: 'Blue Ridge',
+    content: (
+      <span className="inline-flex items-center gap-2">
+        <span>Blue Ridge</span>
+        <span className="font-mono text-[11px] text-ink-4">FTL · 42 trucks</span>
+      </span>
+    ),
+  },
+  {
+    id: 'north-star',
+    label: 'North Star',
+    content: (
+      <span className="inline-flex items-center gap-2">
+        <span>North Star</span>
+        <span className="font-mono text-[11px] text-ink-4">LTL · 118 trucks</span>
+      </span>
+    ),
+  },
+  {
+    id: 'sunline',
+    label: 'Sunline',
+    content: (
+      <span className="inline-flex items-center gap-2">
+        <span>Sunline</span>
+        <span className="font-mono text-[11px] text-ink-4">FTL · 24 trucks</span>
+      </span>
+    ),
+  },
+]
+
+/* ===== stories ============================================================ */
+
+/** Plain text options — the default. Each chip shows the option's label. */
+export const PlainText: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set(['blue-ridge', 'sunline']))
+    return (
+      <MultiSelect
+        label="Carriers"
+        placeholder="Pick carriers"
+        description="Click to add, × to remove."
+        options={plainCarriers}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+/** `hideSelectedOptions` — already-selected items disappear from the
+ *  dropdown. Removal happens only via the chip × in the trigger. */
+export const HideSelected: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set(['blue-ridge']))
+    return (
+      <MultiSelect
+        label="Carriers"
+        placeholder="Pick carriers"
+        description="Selected carriers are hidden from the menu — remove them via × above."
+        options={plainCarriers}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+        hideSelectedOptions
+      />
+    )
+  },
+}
+
+/** Mix a label with small meta on the right — shows that `content` is just
+ *  ReactNode, no constraints on structure. */
+export const WithInlineMeta: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set(['blue-ridge']))
+    return (
+      <MultiSelect
+        label="Carriers"
+        placeholder="Pick carriers"
+        options={carriersWithMeta}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+/** Empty state — no selection yet, trigger shows only the placeholder. */
+export const Empty: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set())
+    return (
+      <MultiSelect
+        label="Carriers"
+        placeholder="Pick one or more carriers"
+        options={plainCarriers}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+      />
+    )
+  },
+}
+
+export const Invalid: Story = {
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set())
+    return (
+      <MultiSelect
+        label="Carriers"
+        placeholder="Pick carriers"
+        options={plainCarriers}
+        selectedKeys={selected}
+        onSelectionChange={setSelected}
+        isInvalid
+        errorMessage="Pick at least one carrier to dispatch."
+      />
+    )
+  },
+}
+
+export const Disabled: Story = {
+  render: () => (
+    <MultiSelect
+      label="Carriers"
+      placeholder="Pick carriers"
+      options={plainCarriers}
+      selectedKeys={new Set(['blue-ridge', 'sunline'])}
+      onSelectionChange={() => {}}
+      isDisabled
+    />
+  ),
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [a, setA] = useState<Set<string>>(new Set())
+    const [b, setB] = useState<Set<string>>(new Set(['blue-ridge', 'sunline']))
+    return (
+      <div className="grid gap-5 w-[440px]">
+        <MultiSelect
+          label="Rest"
+          placeholder="Pick carriers"
+          options={plainCarriers}
+          selectedKeys={a}
+          onSelectionChange={setA}
+        />
+        <MultiSelect
+          label="With text chips"
+          placeholder="Pick carriers"
+          options={plainCarriers}
+          selectedKeys={b}
+          onSelectionChange={setB}
+        />
+        <MultiSelect
+          label="Invalid"
+          placeholder="Pick carriers"
+          options={plainCarriers}
+          selectedKeys={new Set<string>()}
+          onSelectionChange={() => {}}
+          isInvalid
+          errorMessage="Pick at least one."
+        />
+        <MultiSelect
+          label="Disabled"
+          placeholder="Pick carriers"
+          options={plainCarriers}
+          selectedKeys={new Set(['blue-ridge'])}
+          onSelectionChange={() => {}}
+          isDisabled
+        />
+      </div>
+    )
+  },
+}

package/src/components/multi-select/multi-select.test.tsx

@@ -0,0 +1,151 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { MultiSelect, type MultiSelectOption } from './multi-select'
+
+const carriers: MultiSelectOption<string>[] = [
+  { id: 'blue-ridge', label: 'Blue Ridge' },
+  { id: 'north-star', label: 'North Star' },
+  { id: 'sunline', label: 'Sunline' },
+  { id: 'cascade', label: 'Cascade' },
+]
+
+function Harness({
+  onSelectionChange,
+  initial = new Set<string>(),
+}: {
+  onSelectionChange?: (keys: Set<string>) => void
+  initial?: Set<string>
+}) {
+  const [selected, setSelected] = useState<Set<string>>(initial)
+  return (
+    <MultiSelect<string>
+      label="Carriers"
+      placeholder="Pick carriers"
+      options={carriers}
+      selectedKeys={selected}
+      onSelectionChange={(keys) => {
+        setSelected(keys)
+        onSelectionChange?.(keys)
+      }}
+    />
+  )
+}
+
+describe('MultiSelect', () => {
+  it('renders the trigger with a placeholder when nothing is selected', () => {
+    render(<Harness />)
+    expect(screen.getByText('Pick carriers')).toBeInTheDocument()
+    expect(screen.getByRole('combobox')).toBeInTheDocument()
+  })
+
+  it('opens the listbox on trigger click', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('combobox'))
+    expect(await screen.findByRole('listbox')).toBeInTheDocument()
+    expect(screen.getAllByRole('option')).toHaveLength(carriers.length)
+  })
+
+  it('selects multiple options and renders them as chips', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onSelectionChange={onChange} />)
+
+    await user.click(screen.getByRole('combobox'))
+    await user.click(screen.getByRole('option', { name: 'Blue Ridge' }))
+    await user.click(screen.getByRole('option', { name: 'Sunline' }))
+
+    // Both selections make it back to the consumer. Checking membership
+    // explicitly avoids Set-equality quirks from structural matchers.
+    const lastCall = onChange.mock.calls.at(-1)?.[0] as Set<string> | undefined
+    expect(lastCall?.has('blue-ridge')).toBe(true)
+    expect(lastCall?.has('sunline')).toBe(true)
+    expect(lastCall?.size).toBe(2)
+
+    // Two chips = two × remove buttons. RAC's popover aria-hides the
+    // trigger's ancestors while open, so we include hidden matches to see
+    // the chips inside the trigger div.
+    expect(screen.getAllByRole('button', { name: 'Remove', hidden: true })).toHaveLength(2)
+  })
+
+  it('removes a selection via the chip × button', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onSelectionChange={onChange} initial={new Set(['blue-ridge', 'north-star'])} />)
+
+    // Two chips, two × buttons. Click the first to remove Blue Ridge.
+    const [firstRemove, ...rest] = screen.getAllByRole('button', { name: 'Remove' })
+    expect(rest).toHaveLength(1)
+    if (!firstRemove) throw new Error('expected a remove button')
+    await user.click(firstRemove)
+
+    expect(onChange).toHaveBeenCalledWith(new Set(['north-star']))
+  })
+
+  it('opens via keyboard (ArrowDown / Enter / Space)', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.tab()
+    expect(screen.getByRole('combobox')).toHaveFocus()
+    await user.keyboard('{ArrowDown}')
+    expect(await screen.findByRole('listbox')).toBeInTheDocument()
+  })
+
+  it('does not open when disabled', async () => {
+    const user = userEvent.setup()
+    render(
+      <MultiSelect
+        label="Carriers"
+        options={carriers}
+        selectedKeys={new Set<string>()}
+        onSelectionChange={() => {}}
+        isDisabled
+      />,
+    )
+
+    await user.click(screen.getByRole('combobox'))
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('hides selected options from the dropdown when hideSelectedOptions is set', async () => {
+    const user = userEvent.setup()
+    render(
+      <MultiSelect<string>
+        label="Carriers"
+        options={carriers}
+        selectedKeys={new Set<string>(['blue-ridge'])}
+        onSelectionChange={() => {}}
+        hideSelectedOptions
+      />,
+    )
+
+    await user.click(screen.getByRole('combobox'))
+    await screen.findByRole('listbox')
+
+    expect(screen.queryByRole('option', { name: 'Blue Ridge' })).not.toBeInTheDocument()
+    expect(screen.getAllByRole('option')).toHaveLength(carriers.length - 1)
+  })
+
+  it('renders description and error message slots', () => {
+    render(
+      <MultiSelect
+        label="Carriers"
+        description="Pick one or more."
+        errorMessage="Required."
+        isInvalid
+        options={carriers}
+        selectedKeys={new Set<string>()}
+        onSelectionChange={() => {}}
+      />,
+    )
+
+    expect(screen.getByText('Pick one or more.')).toBeInTheDocument()
+    expect(screen.getByText('Required.')).toBeInTheDocument()
+    expect(screen.getByRole('combobox')).toHaveAttribute('aria-invalid', 'true')
+  })
+})

package/src/components/multi-select/multi-select.tsx

@@ -0,0 +1,339 @@
+import { type KeyboardEvent, type ReactNode, useRef, useState } from 'react'
+import { type Key, Label, ListBox, ListBoxItem, Popover } from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  FieldCaret,
+  type FieldSize,
+  fieldChipPadding,
+  fieldControlStyles,
+  fieldErrorStyles,
+  fieldHintStyles,
+  fieldLabelStyles,
+  fieldMinHeight,
+  fieldTextStyles,
+} from '../field/field'
+
+/* =========================================================================
+   MultiSelect — pick many from a list. Trigger shows selected items as
+   removable chips; popover hosts a multi-select ListBox.
+
+   Each option accepts a `content: ReactNode` so consumers can render plain
+   text, a Badge, an icon + label, or anything else — and the same content
+   is reused inside the selected chip.
+   ========================================================================= */
+
+export type MultiSelectOption<T extends Key = Key> = {
+  id: T
+  /** Plain-text label — used as the option's accessible name and fallback
+   *  when `content` isn't provided. */
+  label: string
+  /** Optional rich render. Applied to BOTH the listbox row and the selected
+   *  chip (wrapped by the chip's × button). Falls back to `label`. */
+  content?: ReactNode
+  isDisabled?: boolean
+}
+
+export type MultiSelectProps<T extends Key = Key> = {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  placeholder?: string
+  options: ReadonlyArray<MultiSelectOption<T>>
+  /** Controlled selection. Pass a `Set<T>` or any `Iterable<T>`. */
+  selectedKeys: Iterable<T>
+  onSelectionChange: (keys: Set<T>) => void
+  isDisabled?: boolean
+  isInvalid?: boolean
+  /** Hide already-selected options from the dropdown. Removal then only
+   *  happens via the chip × in the trigger. Default `false` (selected
+   *  options stay visible and can be toggled off from the listbox). */
+  hideSelectedOptions?: boolean
+  /** Render a search input at the top of the popover that filters options
+   *  by label (case-insensitive substring). Default `false`. */
+  isSearchable?: boolean
+  /** Fires as the search text changes — lets consumers drive a server-side
+   *  directory search alongside the local filter. */
+  onSearchChange?: (needle: string) => void
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box. */
+  appearance?: FieldAppearance
+  className?: string
+}
+
+export function MultiSelect<T extends Key>({
+  label,
+  description,
+  errorMessage,
+  placeholder = 'Select…',
+  options,
+  selectedKeys,
+  onSelectionChange,
+  isDisabled = false,
+  isInvalid = false,
+  hideSelectedOptions = false,
+  isSearchable = false,
+  onSearchChange,
+  size = 'md',
+  appearance,
+  className,
+}: MultiSelectProps<T>) {
+  const styles = fieldControlStyles({ size, invalid: isInvalid, appearance })
+  const focusWithin =
+    appearance === 'cell'
+      ? 'focus-within:border-accent focus-within:shadow-none'
+      : 'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]'
+  // Cell mode sits under the table row so the border reads clean instead of
+  // merging with the row gridline.
+  const minHeight = appearance === 'cell' ? 'min-h-[29px]' : fieldMinHeight[size]
+  const [isOpen, setIsOpen] = useState(false)
+  const [search, setSearch] = useState('')
+  const triggerRef = useRef<HTMLDivElement>(null)
+
+  const selectedSet = new Set(selectedKeys)
+  const selectedOptions = options.filter((o) => selectedSet.has(o.id))
+  const needle = search.trim().toLowerCase()
+  const listboxOptions = (
+    hideSelectedOptions ? options.filter((o) => !selectedSet.has(o.id)) : options
+  ).filter((o) => needle === '' || o.label.toLowerCase().includes(needle))
+
+  const updateSearch = (next: string) => {
+    setSearch(next)
+    onSearchChange?.(next)
+  }
+  const openPopover = (open: boolean) => {
+    setIsOpen(open)
+    if (!open && search !== '') updateSearch('')
+  }
+
+  const remove = (id: T) => {
+    const next = new Set(selectedSet)
+    next.delete(id)
+    onSelectionChange(next)
+  }
+
+  const onTriggerKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (isDisabled) return
+    if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
+      e.preventDefault()
+      openPopover(true)
+    }
+  }
+
+  return (
+    <div className={cn('grid grid-cols-1 gap-1.5', className)}>
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      <div
+        ref={triggerRef}
+        role="combobox"
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+        aria-disabled={isDisabled || undefined}
+        aria-invalid={isInvalid || undefined}
+        tabIndex={isDisabled ? -1 : 0}
+        onClick={() => !isDisabled && openPopover(!isOpen)}
+        onKeyDown={onTriggerKeyDown}
+        data-invalid={isInvalid || undefined}
+        data-disabled={isDisabled || undefined}
+        className={cn(
+          styles.box(),
+          'flex flex-wrap items-center gap-1.5 cursor-pointer',
+          minHeight,
+          fieldChipPadding[size],
+          'pr-2',
+          // Let focus-within light up the ring on both the trigger and any
+          // chip's remove button without any extra JS.
+          focusWithin,
+        )}
+      >
+        {selectedOptions.length === 0 ? (
+          // No vertical padding — wrapper's p-1.5 + min-h-[size] govern the
+          // overall height so it matches the Input/Select trigger at the same
+          // size.
+          <span className={cn('text-ink-4 font-sans px-1', fieldTextStyles[size])}>
+            {placeholder}
+          </span>
+        ) : (
+          selectedOptions.map((o) => (
+            <Chip key={o.id} onRemove={() => remove(o.id)} isDisabled={isDisabled}>
+              {o.content ?? o.label}
+            </Chip>
+          ))
+        )}
+        <span className="ml-auto pr-1">
+          <FieldCaret />
+        </span>
+      </div>
+
+      {description ? <p className={fieldHintStyles}>{description}</p> : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <p className={fieldErrorStyles}>{errorMessage}</p>
+      ) : null}
+
+      <Popover
+        isOpen={isOpen}
+        onOpenChange={openPopover}
+        triggerRef={triggerRef}
+        offset={6}
+        placement="bottom start"
+        className={cn(
+          'w-[var(--trigger-width)]',
+          'rounded-md border border-rule bg-surface p-1',
+          'shadow-[var(--shadow-raised)]',
+          'entering:animate-in entering:fade-in-0 entering:slide-in-from-top-1',
+          'exiting:animate-out exiting:fade-out-0 exiting:slide-out-to-top-1',
+        )}
+      >
+        {isSearchable ? (
+          <div className="border-b border-rule-2 px-1 pb-1 mb-1">
+            <input
+              // biome-ignore lint/a11y/noAutofocus: the popover just opened by explicit user action — focus belongs in its search box.
+              autoFocus
+              value={search}
+              onChange={(e) => updateSearch(e.target.value)}
+              placeholder="Search…"
+              aria-label="Search options"
+              className={cn(
+                'w-full bg-transparent outline-none rounded-[6px] px-2 py-1.5',
+                'font-sans text-[13px] text-ink placeholder:text-ink-4',
+              )}
+            />
+          </div>
+        ) : null}
+        <ListBox
+          aria-label={typeof label === 'string' ? label : 'Options'}
+          selectionMode="multiple"
+          selectedKeys={selectedSet}
+          onSelectionChange={(keys) => {
+            if (keys === 'all') {
+              onSelectionChange(new Set(options.map((o) => o.id)))
+              return
+            }
+            onSelectionChange(keys as Set<T>)
+          }}
+          className="outline-none max-h-72 overflow-auto"
+          renderEmptyState={() => (
+            <div className={cn('px-3 py-2', fieldHintStyles)}>
+              {needle !== '' ? 'No matches' : 'All options selected'}
+            </div>
+          )}
+        >
+          {listboxOptions.map((option) => (
+            <ListBoxItem
+              key={option.id}
+              id={option.id}
+              textValue={option.label}
+              {...(option.isDisabled ? { isDisabled: true } : {})}
+              className={cn(
+                'group flex items-center gap-2.5',
+                'rounded-[6px] px-3 py-2 text-[14px] text-ink-2',
+                'cursor-pointer outline-none select-none',
+                'data-[hovered]:bg-surface-2 data-[hovered]:text-ink',
+                'data-[focused]:bg-surface-2 data-[focused]:text-ink',
+                'data-[selected]:bg-surface-3 data-[selected]:text-ink',
+                'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+              )}
+            >
+              <Checkmark />
+              <span className="flex-1 truncate">{option.content ?? option.label}</span>
+            </ListBoxItem>
+          ))}
+        </ListBox>
+      </Popover>
+    </div>
+  )
+}
+
+/* =========================================================================
+   Internal: selected chip with × remove button.
+   Minimal chrome (sand bg, hairline border, rounded-6) so that rich content
+   like a <Badge/> still reads cleanly inside it.
+   ========================================================================= */
+
+function Chip({
+  children,
+  onRemove,
+  isDisabled,
+}: {
+  children: ReactNode
+  onRemove: () => void
+  isDisabled: boolean
+}) {
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1.5',
+        'pl-2 pr-1 py-0.5 rounded-[6px]',
+        'bg-surface-2 border border-rule',
+        'font-sans text-[13px] text-ink',
+      )}
+    >
+      <span className="inline-flex items-center">{children}</span>
+      <button
+        type="button"
+        aria-label="Remove"
+        disabled={isDisabled}
+        onClick={(e) => {
+          // Keep the click from bubbling to the trigger div (which would
+          // toggle the popover open/closed).
+          e.stopPropagation()
+          onRemove()
+        }}
+        className={cn(
+          'inline-flex items-center justify-center shrink-0',
+          'size-4 rounded-[3px]',
+          'text-ink-3 hover:text-ink hover:bg-surface-3 cursor-pointer',
+          'outline-none focus-visible:shadow-[var(--shadow-focus)]',
+          'disabled:opacity-45 disabled:cursor-not-allowed',
+        )}
+      >
+        <svg aria-hidden viewBox="0 0 10 10" className="size-2.5" fill="none">
+          <path
+            d="M2 2l6 6M8 2l-6 6"
+            stroke="currentColor"
+            strokeWidth="1.4"
+            strokeLinecap="round"
+          />
+        </svg>
+      </button>
+    </span>
+  )
+}
+
+/* =========================================================================
+   Internal: empty box → indigo tick when the row is selected.
+   ========================================================================= */
+
+function Checkmark() {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'relative inline-flex items-center justify-center shrink-0',
+        'size-[16px] rounded-[3px] border border-ink-4 bg-surface',
+        'transition-[background-color,border-color] duration-150',
+        'group-data-[selected]:bg-ink group-data-[selected]:border-ink',
+      )}
+    >
+      <svg
+        viewBox="0 0 12 12"
+        className={cn(
+          'size-3 text-surface transition-opacity duration-150',
+          'opacity-0 group-data-[selected]:opacity-100',
+        )}
+        aria-hidden
+      >
+        <path
+          d="M2.5 6.25 5 8.75 9.5 3.75"
+          stroke="currentColor"
+          strokeWidth="1.6"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          fill="none"
+        />
+      </svg>
+    </span>
+  )
+}