@proteos/ui 0.31.0

package/src/components/checkbox/checkbox-group.tsx

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react'
+import {
+  CheckboxGroup as AriaCheckboxGroup,
+  type CheckboxGroupProps as AriaCheckboxGroupProps,
+  FieldError,
+  Label,
+  Text,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import { fieldErrorStyles, fieldHintStyles, fieldLabelStyles } from '../field/field'
+
+/* =========================================================================
+   CheckboxGroup — multi-choice field, the checkbox counterpart to RadioGroup.
+   Monolithic API to match it: label / description / errorMessage props on the
+   group, `<Checkbox value="…">` children. `value` is a string[] of selected
+   values (controlled via value/onChange, or defaultValue).
+   ========================================================================= */
+
+export type CheckboxGroupProps = Omit<AriaCheckboxGroupProps, 'children'> & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  /** `<Checkbox value="…">` elements. Function-as-children is not supported at the group level. */
+  children: ReactNode
+}
+
+export function CheckboxGroup({
+  label,
+  description,
+  errorMessage,
+  children,
+  className,
+  ...props
+}: CheckboxGroupProps) {
+  return (
+    <AriaCheckboxGroup
+      {...props}
+      className={(renderProps) =>
+        cn('grid gap-2', typeof className === 'function' ? className(renderProps) : className)
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+      <div className="grid gap-3">{children}</div>
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage ? <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError> : null}
+    </AriaCheckboxGroup>
+  )
+}

package/src/components/checkbox/checkbox.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Checkbox } from './checkbox'
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Components/Checkbox',
+  component: Checkbox,
+  tags: ['autodocs'],
+  args: {
+    children: 'Audit log',
+  },
+  argTypes: {
+    isDisabled: { control: { type: 'boolean' } },
+    isSelected: { control: { type: 'boolean' } },
+    isIndeterminate: { control: { type: 'boolean' } },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Checkbox>
+
+export const Playground: Story = {}
+
+export const Group: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-3">
+      <Checkbox defaultSelected>Audit log</Checkbox>
+      <Checkbox defaultSelected>Row-level permissions</Checkbox>
+      <Checkbox>Weekly architect review</Checkbox>
+    </div>
+  ),
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-3">
+      <Checkbox>Unchecked</Checkbox>
+      <Checkbox defaultSelected>Checked</Checkbox>
+      <Checkbox isIndeterminate>Indeterminate</Checkbox>
+      <Checkbox isDisabled>Disabled</Checkbox>
+      <Checkbox isDisabled defaultSelected>
+        Disabled · checked
+      </Checkbox>
+    </div>
+  ),
+}

package/src/components/checkbox/checkbox.test.tsx

@@ -0,0 +1,50 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Checkbox } from './checkbox'
+
+describe('Checkbox', () => {
+  it('renders its label', () => {
+    render(<Checkbox>Audit log</Checkbox>)
+    expect(screen.getByRole('checkbox', { name: 'Audit log' })).toBeInTheDocument()
+  })
+
+  it('toggles on click', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Checkbox onChange={onChange}>Audit log</Checkbox>)
+
+    await user.click(screen.getByRole('checkbox', { name: 'Audit log' }))
+    expect(onChange).toHaveBeenCalledWith(true)
+  })
+
+  it('toggles on keyboard Space', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Checkbox onChange={onChange}>Audit log</Checkbox>)
+
+    await user.tab()
+    expect(screen.getByRole('checkbox')).toHaveFocus()
+    await user.keyboard(' ')
+    expect(onChange).toHaveBeenCalledWith(true)
+  })
+
+  it('does not toggle when disabled', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(
+      <Checkbox onChange={onChange} isDisabled>
+        Audit log
+      </Checkbox>,
+    )
+
+    await user.click(screen.getByRole('checkbox', { name: 'Audit log' }))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('reflects a controlled checked state', () => {
+    render(<Checkbox isSelected>Row-level permissions</Checkbox>)
+    expect(screen.getByRole('checkbox', { name: 'Row-level permissions' })).toBeChecked()
+  })
+})

package/src/components/checkbox/checkbox.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from 'react'
+import {
+  Checkbox as AriaCheckbox,
+  type CheckboxProps as AriaCheckboxProps,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+
+export type CheckboxProps = Omit<AriaCheckboxProps, 'children'> & {
+  children?: ReactNode
+}
+
+export function Checkbox({ children, className, ...props }: CheckboxProps) {
+  return (
+    <AriaCheckbox
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'group inline-flex items-center gap-2.5 cursor-pointer',
+          'font-sans text-[14px] text-ink-2 select-none',
+          'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {(renderProps) => (
+        <>
+          <span
+            aria-hidden
+            className={cn(
+              'relative inline-flex items-center justify-center shrink-0',
+              'size-[18px] rounded-[4px] border bg-surface',
+              'border-ink-4',
+              'transition-[background-color,border-color,box-shadow] duration-150',
+              // hovered
+              'group-data-[hovered]:border-ink',
+              // checked / indeterminate — fill with ink
+              'group-data-[selected]:bg-ink group-data-[selected]:border-ink',
+              'group-data-[indeterminate]:bg-ink group-data-[indeterminate]:border-ink',
+              // focus ring on the box
+              'group-data-[focus-visible]:shadow-[var(--shadow-focus)]',
+            )}
+          >
+            {renderProps.isIndeterminate ? (
+              <span className="block h-px w-2.5 bg-surface" />
+            ) : (
+              <svg
+                viewBox="0 0 12 12"
+                className={cn(
+                  'size-3 text-surface transition-opacity duration-150',
+                  renderProps.isSelected ? 'opacity-100' : 'opacity-0',
+                )}
+                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>
+          {children}
+        </>
+      )}
+    </AriaCheckbox>
+  )
+}

package/src/components/checkbox/index.ts

@@ -0,0 +1,4 @@
+export type { CheckboxProps } from './checkbox'
+export { Checkbox } from './checkbox'
+export type { CheckboxGroupProps } from './checkbox-group'
+export { CheckboxGroup } from './checkbox-group'

package/src/components/combobox/combobox.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Combobox } from './combobox'
+
+const carriers = [
+  { id: 'blue-ridge', label: 'Blue Ridge', description: 'FTL · 42 trucks' },
+  { id: 'north-star', label: 'North Star', description: 'LTL · 118 trucks' },
+  { id: 'sunline', label: 'Sunline', description: 'FTL · 24 trucks' },
+  { id: 'cascade', label: 'Cascade', description: 'Reefer · 56 trucks' },
+  { id: 'atlantic', label: 'Atlantic', description: 'Intermodal · 81 trucks' },
+  { id: 'pioneer', label: 'Pioneer', description: 'FTL · 17 trucks' },
+  { id: 'meridian', label: 'Meridian', description: 'LTL · 93 trucks' },
+  { id: 'heartland', label: 'Heartland', description: 'FTL · 211 trucks' },
+]
+
+const meta: Meta<typeof Combobox> = {
+  title: 'Components/Combobox',
+  component: Combobox,
+  tags: ['autodocs'],
+  args: {
+    label: 'Carrier',
+    placeholder: 'Search carriers…',
+    options: carriers,
+  },
+  argTypes: {
+    isDisabled: { control: { type: 'boolean' } },
+    isInvalid: { control: { type: 'boolean' } },
+    allowsCustomValue: { control: { type: 'boolean' } },
+    menuTrigger: {
+      control: { type: 'inline-radio' },
+      options: ['input', 'focus', 'manual'],
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[440px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof Combobox>
+
+export const Playground: Story = {}
+
+export const WithDescription: Story = {
+  args: {
+    description: 'Type to filter the list, or open the menu to browse.',
+  },
+}
+
+export const OpensOnFocus: Story = {
+  args: {
+    menuTrigger: 'focus',
+    description: 'Tab into the field — the menu opens immediately.',
+  },
+}
+
+export const AllowsCustomValue: Story = {
+  args: {
+    allowsCustomValue: true,
+    description: 'Pick an existing carrier, or type a new one. Useful for tag-style entry.',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    isInvalid: true,
+    errorMessage: 'Pick a carrier before dispatching.',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    isDisabled: true,
+    defaultSelectedKey: 'blue-ridge',
+  },
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-5 w-[440px]">
+      <Combobox label="Rest" options={carriers} />
+      <Combobox label="Selected" options={carriers} defaultSelectedKey="north-star" />
+      <Combobox
+        label="Invalid"
+        options={carriers}
+        isInvalid
+        errorMessage="Pick a carrier before dispatching."
+      />
+      <Combobox label="Disabled" options={carriers} defaultSelectedKey="cascade" isDisabled />
+    </div>
+  ),
+}

package/src/components/combobox/combobox.test.tsx

@@ -0,0 +1,123 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { Combobox } from './combobox'
+
+const carriers = [
+  { id: 'blue-ridge', label: 'Blue Ridge' },
+  { id: 'north-star', label: 'North Star' },
+  { id: 'sunline', label: 'Sunline' },
+  { id: 'cascade', label: 'Cascade' },
+  { id: 'atlantic', label: 'Atlantic' },
+] as const
+
+describe('Combobox', () => {
+  it('renders a labelled combobox input', () => {
+    render(<Combobox label="Carrier" options={[...carriers]} />)
+    expect(screen.getByRole('combobox', { name: 'Carrier' })).toBeInTheDocument()
+  })
+
+  it('filters options as the user types', async () => {
+    const user = userEvent.setup()
+    render(<Combobox label="Carrier" options={[...carriers]} />)
+
+    // Open the menu via the trigger button (deterministic in jsdom),
+    // then type into the input to filter the now-visible list.
+    await user.click(screen.getByRole('button'))
+    await screen.findByRole('listbox')
+
+    const input = screen.getByRole('combobox', { name: 'Carrier' })
+    await user.click(input)
+    await user.keyboard('su')
+
+    expect(await screen.findByRole('option', { name: 'Sunline' })).toBeInTheDocument()
+    expect(screen.queryByRole('option', { name: 'Blue Ridge' })).not.toBeInTheDocument()
+  })
+
+  it('fires onSelectionChange when an option is picked', async () => {
+    const user = userEvent.setup()
+    const onSelectionChange = vi.fn()
+    render(
+      <Combobox label="Carrier" options={[...carriers]} onSelectionChange={onSelectionChange} />,
+    )
+
+    await user.click(screen.getByRole('button'))
+    await user.click(await screen.findByRole('option', { name: 'North Star' }))
+    expect(onSelectionChange).toHaveBeenCalledWith('north-star')
+  })
+
+  it('opens the listbox via the trigger button', async () => {
+    const user = userEvent.setup()
+    render(<Combobox label="Carrier" options={[...carriers]} />)
+
+    const trigger = screen.getByRole('button')
+    await user.click(trigger)
+
+    expect(await screen.findByRole('listbox')).toBeInTheDocument()
+    expect(screen.getAllByRole('option')).toHaveLength(carriers.length)
+  })
+
+  it('shows the empty-state message when no option matches', async () => {
+    const user = userEvent.setup()
+    render(<Combobox label="Carrier" options={[...carriers]} emptyMessage="No carriers match" />)
+
+    await user.click(screen.getByRole('button'))
+    await screen.findByRole('listbox')
+
+    const input = screen.getByRole('combobox', { name: 'Carrier' })
+    await user.click(input)
+    await user.keyboard('zzzz')
+
+    expect(await screen.findByText('No carriers match')).toBeInTheDocument()
+  })
+
+  it('renders the error message when invalid', () => {
+    render(
+      <Combobox label="Carrier" options={[...carriers]} isInvalid errorMessage="Pick a carrier" />,
+    )
+    expect(screen.getByText('Pick a carrier')).toBeInTheDocument()
+  })
+
+  it('disables the input when isDisabled is set', () => {
+    render(<Combobox label="Carrier" options={[...carriers]} isDisabled />)
+    expect(screen.getByRole('combobox', { name: 'Carrier' })).toBeDisabled()
+  })
+
+  it('renders a per-option trailing slot whose clicks do not select the row', async () => {
+    const user = userEvent.setup()
+    const onTrailing = vi.fn()
+    const onSelectionChange = vi.fn()
+    render(
+      <Combobox
+        label="Carrier"
+        onSelectionChange={onSelectionChange}
+        options={[
+          {
+            id: 'blue-ridge',
+            label: 'Blue Ridge',
+            trailing: (
+              <button type="button" aria-label="Peek Blue Ridge" onClick={onTrailing}>
+                ↗
+              </button>
+            ),
+          },
+          { id: 'north-star', label: 'North Star' },
+        ]}
+      />,
+    )
+
+    // Before the popover opens, the trigger is the only button in the DOM.
+    await user.click(screen.getByRole('button'))
+    // The peek button should be in the DOM (CSS hides it until hover/focus,
+    // which jsdom can't simulate; presence is what we assert here).
+    const peek = await screen.findByRole('button', { name: 'Peek Blue Ridge' })
+
+    // userEvent's full pointer-event sequence gets tangled with RAC's
+    // listbox press handling in jsdom; a direct synthetic click on the
+    // trailing button is enough to verify the wiring + propagation guard.
+    fireEvent.click(peek)
+    expect(onTrailing).toHaveBeenCalledTimes(1)
+    expect(onSelectionChange).not.toHaveBeenCalled()
+  })
+})

package/src/components/combobox/combobox.tsx

@@ -0,0 +1,239 @@
+import { type ReactNode, useContext } from 'react'
+import {
+  ComboBox as AriaComboBox,
+  type ComboBoxProps as AriaComboBoxProps,
+  ComboBoxStateContext,
+  Button as AriaComboButton,
+  Input as AriaInput,
+  FieldError,
+  type Key,
+  Label,
+  ListBox,
+  ListBoxItem,
+  type ListBoxItemProps,
+  Popover,
+  Text,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  FieldCaret,
+  fieldControlStyles,
+  fieldErrorStyles,
+  type FieldSize,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+
+export type ComboboxOption<T extends Key = Key> = {
+  id: T
+  label: string
+  description?: ReactNode
+  isDisabled?: boolean
+  /**
+   * Per-row action UI rendered at the trailing edge of the option. Hidden
+   * by default; revealed when the row is hovered or keyboard-focused. The
+   * slot intercepts `pointerdown` / `click` propagation so interactions
+   * inside it don't trigger option selection — put a real `<button>` /
+   * `<Link>` here and it Just Works.
+   */
+  trailing?: ReactNode
+}
+
+export type ComboboxProps<T extends Key = Key> = Omit<
+  AriaComboBoxProps<never>,
+  'children' | 'items' | 'defaultItems'
+> & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  placeholder?: string
+  options: ReadonlyArray<ComboboxOption<T>>
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box. */
+  appearance?: FieldAppearance
+  /** Visual override for the trigger input wrapper only. */
+  inputWrapperClassName?: string
+  /** Visual override for the inner `<input>` (size, padding, font). */
+  inputClassName?: string
+  /** Empty-state message shown in the popover when no options match. */
+  emptyMessage?: ReactNode
+}
+
+export function Combobox<T extends Key>({
+  label,
+  description,
+  errorMessage,
+  placeholder = 'Type to search…',
+  options,
+  size,
+  appearance,
+  inputWrapperClassName,
+  inputClassName,
+  emptyMessage = 'No matches',
+  className,
+  // Default to keeping the popover open on an empty filter so the
+  // `emptyMessage` slot actually renders. Callers can opt out.
+  allowsEmptyCollection = true,
+  ...props
+}: ComboboxProps<T>) {
+  const styles = fieldControlStyles({ size, appearance })
+  // In cell mode the wrapper's own focus-within halo must go too — only the
+  // accent border remains on focus.
+  const focusWithin =
+    appearance === 'cell'
+      ? 'focus-within:border-accent focus-within:shadow-none'
+      : 'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]'
+  return (
+    <AriaComboBox
+      {...props}
+      allowsEmptyCollection={allowsEmptyCollection}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      <div
+        className={cn(
+          // Box chrome on the wrapper; the inner <input> carries the padding
+          // + font so the chevron button sits inside the same border + ring.
+          styles.box(),
+          'flex items-center gap-1 pr-2',
+          focusWithin,
+          inputWrapperClassName,
+        )}
+      >
+        <AriaInput
+          placeholder={placeholder}
+          className={cn(
+            'flex-1 min-w-0 bg-transparent outline-none',
+            styles.content(),
+            inputClassName,
+          )}
+        />
+        <AriaComboButton
+          className={cn(
+            'shrink-0 flex items-center justify-center',
+            'size-7 rounded-pill',
+            'text-ink-3 hover:text-ink outline-none cursor-pointer',
+          )}
+        >
+          <FieldCaret />
+        </AriaComboButton>
+      </div>
+
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+
+      <Popover
+        offset={6}
+        className={cn(
+          'min-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',
+        )}
+      >
+        <ListBox
+          className="outline-none max-h-72 overflow-auto"
+          renderEmptyState={() => (
+            <div className={cn('px-3 py-2', fieldHintStyles)}>{emptyMessage}</div>
+          )}
+        >
+          {options.map((option) => (
+            <ComboboxItem
+              key={option.id}
+              id={option.id}
+              textValue={option.label}
+              {...(option.isDisabled ? { isDisabled: true } : {})}
+            >
+              <span className="truncate">{option.label}</span>
+              {option.description ? (
+                <span className="ml-3 shrink-0 font-mono text-[11.5px] text-ink-4">
+                  {option.description}
+                </span>
+              ) : null}
+              {option.trailing ? <TrailingSlot>{option.trailing}</TrailingSlot> : null}
+            </ComboboxItem>
+          ))}
+        </ListBox>
+      </Popover>
+    </AriaComboBox>
+  )
+}
+
+/**
+ * Wraps the per-option trailing UI so that:
+ * - The full pointer→click sequence is intercepted (so RAC's listbox
+ *   press handling on the surrounding ListBoxItem can never claim it
+ *   and select the row).
+ * - On click, after the consumer's own handler runs (bubble order:
+ *   inner element → this wrapper), the combobox popover closes.
+ *   The trailing action is by nature "do something with this option" —
+ *   e.g. open a peek panel — which always takes the user away from the
+ *   field, so leaving the popover open underneath would be a UX bug.
+ */
+function TrailingSlot({ children }: { children: ReactNode }) {
+  const state = useContext(ComboBoxStateContext)
+  return (
+    <span
+      className={cn(
+        'ml-auto pl-2 shrink-0 inline-flex items-center',
+        // Hidden by default; revealed when the row is hovered or
+        // keyboard-focused. `group/combobox-item` is set on ComboboxItem.
+        'hidden',
+        'group-data-[hovered]/combobox-item:inline-flex',
+        'group-data-[focused]/combobox-item:inline-flex',
+        'focus-within:inline-flex',
+      )}
+      // Block the full press lifecycle: `pointerdown` prevents usePress
+      // from arming on the option, the rest cover the test-env mousedown
+      // path and any third-party handlers.
+      onPointerDown={(e) => e.stopPropagation()}
+      onPointerUp={(e) => e.stopPropagation()}
+      onMouseDown={(e) => e.stopPropagation()}
+      onMouseUp={(e) => e.stopPropagation()}
+      onClick={(e) => {
+        e.stopPropagation()
+        // Bubble order means the consumer's onClick already ran; now
+        // close the popover so the trailing action's target UI (e.g. a
+        // peek modal) isn't sitting on top of an open dropdown.
+        state?.close()
+      }}
+    >
+      {children}
+    </span>
+  )
+}
+
+function ComboboxItem(props: ListBoxItemProps) {
+  return (
+    <ListBoxItem
+      {...props}
+      className={cn(
+        // `group/combobox-item` exposes hover/focus state to the trailing
+        // slot so it can reveal itself only when the row is engaged.
+        'group/combobox-item',
+        'flex items-center justify-between gap-3',
+        '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',
+      )}
+    />
+  )
+}

package/src/components/combobox/index.ts

@@ -0,0 +1,2 @@
+export type { ComboboxOption, ComboboxProps } from './combobox'
+export { Combobox } from './combobox'