@proteos/ui 0.31.0

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

@@ -0,0 +1,155 @@
+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 { BadgeMultiSelect, type BadgeMultiSelectOption } from './badge-multi-select'
+
+const statuses: BadgeMultiSelectOption<string>[] = [
+  { id: 'in-transit', label: 'in transit', variant: 'active' },
+  { id: 'quoted', label: 'quoted' },
+  { id: 'reconciled', label: 'reconciled', variant: 'success' },
+  { id: 'past-due', label: 'past due', variant: 'warning' },
+  { id: 'exception', label: 'exception', variant: 'danger' },
+]
+
+function Harness({
+  onSelectionChange,
+  initial = new Set<string>(),
+}: {
+  onSelectionChange?: (keys: Set<string>) => void
+  initial?: Set<string>
+}) {
+  const [selected, setSelected] = useState<Set<string>>(initial)
+  return (
+    <BadgeMultiSelect<string>
+      label="Status"
+      placeholder="Any status"
+      options={statuses}
+      selectedKeys={selected}
+      onSelectionChange={(keys) => {
+        setSelected(keys)
+        onSelectionChange?.(keys)
+      }}
+    />
+  )
+}
+
+describe('BadgeMultiSelect', () => {
+  it('renders placeholder when nothing is selected', () => {
+    render(<Harness />)
+    expect(screen.getByText('Any status')).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(statuses.length)
+  })
+
+  it('selects multiple options and renders them as removable badges', 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: 'in transit' }))
+    await user.click(screen.getByRole('option', { name: 'past due' }))
+
+    const lastCall = onChange.mock.calls.at(-1)?.[0] as Set<string> | undefined
+    expect(lastCall?.has('in-transit')).toBe(true)
+    expect(lastCall?.has('past-due')).toBe(true)
+    expect(lastCall?.size).toBe(2)
+
+    // Two selections = two × remove buttons inside the trigger.
+    expect(screen.getAllByRole('button', { name: 'Remove', hidden: true })).toHaveLength(2)
+  })
+
+  it('removes a selection via the × inside the badge', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onSelectionChange={onChange} initial={new Set(['in-transit', 'reconciled'])} />)
+
+    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(['reconciled']))
+  })
+
+  it('hides selected options from the dropdown when hideSelectedOptions is set', async () => {
+    const user = userEvent.setup()
+    render(
+      <BadgeMultiSelect<string>
+        label="Status"
+        options={statuses}
+        selectedKeys={new Set<string>(['in-transit'])}
+        onSelectionChange={() => {}}
+        hideSelectedOptions
+      />,
+    )
+
+    await user.click(screen.getByRole('combobox'))
+    await screen.findByRole('listbox')
+
+    // "in transit" is already selected — it should NOT be in the listbox.
+    expect(screen.queryByRole('option', { name: 'in transit' })).not.toBeInTheDocument()
+    // The other five are still available.
+    expect(screen.getAllByRole('option')).toHaveLength(statuses.length - 1)
+  })
+
+  it('shows "All options selected" when every option is picked and hidden', async () => {
+    const user = userEvent.setup()
+    render(
+      <BadgeMultiSelect<string>
+        label="Status"
+        options={statuses}
+        selectedKeys={new Set(statuses.map((s) => s.id))}
+        onSelectionChange={() => {}}
+        hideSelectedOptions
+      />,
+    )
+
+    await user.click(screen.getByRole('combobox'))
+    // RAC's renderEmptyState renders inside the listbox; the copy landing
+    // is enough proof — we don't poke at internal listbox semantics.
+    expect(await screen.findByText('All options selected')).toBeInTheDocument()
+  })
+
+  it('does not open when disabled', async () => {
+    const user = userEvent.setup()
+    render(
+      <BadgeMultiSelect
+        label="Status"
+        options={statuses}
+        selectedKeys={new Set<string>()}
+        onSelectionChange={() => {}}
+        isDisabled
+      />,
+    )
+
+    await user.click(screen.getByRole('combobox'))
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('renders description and error slots', () => {
+    render(
+      <BadgeMultiSelect
+        label="Status"
+        description="Filter the board."
+        errorMessage="Pick at least one."
+        isInvalid
+        options={statuses}
+        selectedKeys={new Set<string>()}
+        onSelectionChange={() => {}}
+      />,
+    )
+    expect(screen.getByText('Filter the board.')).toBeInTheDocument()
+    expect(screen.getByText('Pick at least one.')).toBeInTheDocument()
+    expect(screen.getByRole('combobox')).toHaveAttribute('aria-invalid', 'true')
+  })
+})

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

@@ -0,0 +1,272 @@
+import { type KeyboardEvent, type ReactNode, useEffect, useRef, useState } from 'react'
+import { type Key, Label, ListBox, ListBoxItem, Popover } from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import { Badge, type BadgeVariants } from '../badge/badge'
+import {
+  type FieldAppearance,
+  FieldCaret,
+  fieldChipPadding,
+  fieldControlStyles,
+  fieldErrorStyles,
+  fieldHintStyles,
+  fieldLabelStyles,
+  fieldMinHeight,
+  type FieldSize,
+  fieldTextStyles,
+} from '../field/field'
+
+/* =========================================================================
+   BadgeMultiSelect — a MultiSelect specialized for picking status-like
+   values. Each option is a <Badge/> — both in the dropdown and as the
+   selected pill. The × remove button lives INSIDE each selected badge
+   (no extra chip chrome), so the color coding from the Badge variant is
+   what you see, cleanly.
+   ========================================================================= */
+
+export type BadgeMultiSelectOption<T extends Key = Key> = {
+  id: T
+  /** Text shown inside the badge. Used as the accessible name too. */
+  label: string
+  /** Badge color register. Defaults to `default`. */
+  variant?: BadgeVariants['variant']
+  isDisabled?: boolean
+}
+
+export type BadgeMultiSelectProps<T extends Key = Key> = {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  placeholder?: string
+  options: ReadonlyArray<BadgeMultiSelectOption<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 from the listbox). */
+  hideSelectedOptions?: boolean
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box. */
+  appearance?: FieldAppearance
+  /** Focus the trigger on mount. Mirrors RAC's `autoFocus` prop on native
+   *  inputs; useful for keyboard chains where the trigger should take focus
+   *  when its surrounding context becomes ready. */
+  autoFocus?: boolean
+  className?: string
+}
+
+export function BadgeMultiSelect<T extends Key>({
+  label,
+  description,
+  errorMessage,
+  placeholder = 'Select…',
+  options,
+  selectedKeys,
+  onSelectionChange,
+  isDisabled = false,
+  isInvalid = false,
+  hideSelectedOptions = false,
+  size = 'md',
+  appearance,
+  autoFocus = false,
+  className,
+}: BadgeMultiSelectProps<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)]'
+  const minHeight = appearance === 'cell' ? 'min-h-[29px]' : fieldMinHeight[size]
+  const [isOpen, setIsOpen] = useState(false)
+  const triggerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (autoFocus) triggerRef.current?.focus()
+    // mount-only — autoFocus is a one-shot signal, not sustained.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const selectedSet = new Set(selectedKeys)
+  const selectedOptions = options.filter((o) => selectedSet.has(o.id))
+  const listboxOptions = hideSelectedOptions
+    ? options.filter((o) => !selectedSet.has(o.id))
+    : options
+
+  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()
+      setIsOpen(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 && setIsOpen((v) => !v)}
+        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',
+          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) => (
+            <RemovableBadge
+              key={o.id}
+              variant={o.variant}
+              onRemove={() => remove(o.id)}
+              isDisabled={isDisabled}
+            >
+              {o.label}
+            </RemovableBadge>
+          ))
+        )}
+        <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={setIsOpen}
+        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',
+        )}
+      >
+        <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)}>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',
+                'rounded-[6px] px-3 py-2',
+                'cursor-pointer outline-none select-none',
+                'data-[hovered]:bg-surface-2',
+                'data-[focused]:bg-surface-2',
+                'data-[selected]:bg-surface-3',
+                'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+              )}
+            >
+              <Badge variant={option.variant}>{option.label}</Badge>
+            </ListBoxItem>
+          ))}
+        </ListBox>
+      </Popover>
+    </div>
+  )
+}
+
+/* =========================================================================
+   Internal: a Badge with a trailing × button baked into the pill.
+   The × inherits the badge's text color via `currentColor`, so it reads
+   correctly against every variant's fill.
+   ========================================================================= */
+
+function RemovableBadge({
+  children,
+  variant,
+  onRemove,
+  isDisabled,
+}: {
+  children: ReactNode
+  variant?: BadgeVariants['variant']
+  onRemove: () => void
+  isDisabled: boolean
+}) {
+  return (
+    <Badge variant={variant}>
+      <span>{children}</span>
+      <button
+        type="button"
+        aria-label="Remove"
+        disabled={isDisabled}
+        onClick={(e) => {
+          e.stopPropagation()
+          onRemove()
+        }}
+        className={cn(
+          'inline-flex items-center justify-center shrink-0',
+          'size-3.5 rounded-full',
+          'text-current/70 hover:text-current hover:bg-current/10',
+          'outline-none cursor-pointer',
+          'focus-visible:shadow-[var(--shadow-focus)]',
+          'disabled:opacity-45 disabled:cursor-not-allowed',
+          // Pull the button flush with the right edge so the pill still feels
+          // symmetric around the leading dot.
+          '-mr-1',
+        )}
+      >
+        <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>
+    </Badge>
+  )
+}

package/src/components/badge-multi-select/index.ts

@@ -0,0 +1,2 @@
+export type { BadgeMultiSelectOption, BadgeMultiSelectProps } from './badge-multi-select'
+export { BadgeMultiSelect } from './badge-multi-select'

package/src/components/breadcrumbs/breadcrumbs.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Breadcrumbs } from './breadcrumbs'
+
+const meta: Meta<typeof Breadcrumbs> = {
+  title: 'Components/Breadcrumbs',
+  component: Breadcrumbs,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof Breadcrumbs>
+
+export const Playground: Story = {
+  args: {
+    items: [
+      { id: 1, label: 'Operations', href: '/operations' },
+      { id: 2, label: 'Shipments', href: '/operations/shipments' },
+      { id: 3, label: 'Open' },
+    ],
+  },
+}
+
+export const TwoLevels: Story = {
+  args: {
+    items: [
+      { id: 1, label: 'Workspace', href: '/' },
+      { id: 2, label: 'Home' },
+    ],
+  },
+}
+
+export const WithChevronSeparator: Story = {
+  args: {
+    separator: '›',
+    items: [
+      { id: 1, label: 'Finance', href: '/finance' },
+      { id: 2, label: 'Reconciliation', href: '/finance/reconciliation' },
+      { id: 3, label: 'Disputes' },
+    ],
+  },
+}

package/src/components/breadcrumbs/breadcrumbs.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react'
+import {
+  Breadcrumb as AriaBreadcrumb,
+  Breadcrumbs as AriaBreadcrumbs,
+  type BreadcrumbsProps as AriaBreadcrumbsProps,
+  Link as AriaLink,
+} from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Breadcrumbs — RAC Breadcrumbs/Breadcrumb under the hood. Last item is
+   rendered as a non-link span with `aria-current="page"`; everything before
+   it is a RAC Link with hover + focus-visible chrome.
+   ========================================================================= */
+
+export type BreadcrumbItem = {
+  /** Stable key for the row. */
+  id: string | number
+  /** Display label. */
+  label: ReactNode
+  /** Optional href. Omit (or leave the last item without one) to render the
+   *  current page as plain text. */
+  href?: string
+}
+
+export type BreadcrumbsProps = Omit<AriaBreadcrumbsProps<never>, 'children' | 'items'> & {
+  items: ReadonlyArray<BreadcrumbItem>
+  /** Glyph between crumbs. Default `/`. */
+  separator?: ReactNode
+}
+
+export function Breadcrumbs({ items, separator = '/', className, ...props }: BreadcrumbsProps) {
+  return (
+    <AriaBreadcrumbs
+      {...props}
+      className={cn(
+        'flex items-center gap-2',
+        'font-mono text-[12px] text-ink-3',
+        // RAC renders Breadcrumbs as <ol> — neutralise list defaults.
+        'list-none m-0 p-0',
+        className,
+      )}
+    >
+      {items.map((item, i) => {
+        const isLast = i === items.length - 1
+        return (
+          <AriaBreadcrumb
+            key={item.id}
+            className="flex items-center gap-2"
+            // The last crumb is the current page. Hides the trailing
+            // separator and skips the link affordance.
+            data-current={isLast || undefined}
+          >
+            {item.href !== undefined && !isLast ? (
+              <AriaLink
+                href={item.href}
+                className={cn(
+                  'rounded-sm outline-none cursor-pointer',
+                  'transition-colors duration-150',
+                  'hover:text-ink',
+                  'data-[hovered]:text-ink',
+                  'data-[focus-visible]:shadow-[var(--shadow-focus)]',
+                )}
+              >
+                {item.label}
+              </AriaLink>
+            ) : (
+              <span
+                className={cn(isLast && 'text-ink font-semibold')}
+                aria-current={isLast ? 'page' : undefined}
+              >
+                {item.label}
+              </span>
+            )}
+            {!isLast ? (
+              <span aria-hidden className="text-ink-4 select-none">
+                {separator}
+              </span>
+            ) : null}
+          </AriaBreadcrumb>
+        )
+      })}
+    </AriaBreadcrumbs>
+  )
+}

package/src/components/breadcrumbs/index.ts

@@ -0,0 +1,2 @@
+export type { BreadcrumbItem, BreadcrumbsProps } from './breadcrumbs'
+export { Breadcrumbs } from './breadcrumbs'