@proteos/ui 0.45.0 → 0.46.0

package/src/components/icon-picker/icon-picker.tsx

@@ -0,0 +1,336 @@
+import type { LucideIcon } from 'lucide-react'
+import { icons, Search, Shapes, X } from 'lucide-react'
+import { type ReactNode, useMemo, useRef, useState } from 'react'
+import { Input as AriaInput, Label, ListBox, ListBoxItem, Popover } from 'react-aria-components'
+
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  FieldCaret,
+  type FieldSize,
+  fieldControlStyles,
+  fieldErrorStyles,
+  fieldHintStyles,
+  fieldLabelStyles,
+  fieldTextStyles,
+} from '../field/field'
+
+/* =========================================================================
+   IconPicker — a form field for choosing a Lucide icon by name.
+
+   The value is the icon's canonical PascalCase export name ("TrendingUp"),
+   which is what the platform stores wherever an icon rides config (menu
+   items, connectors, knowledge spaces). The picker resolves loosely on the
+   way IN — kebab-case and lowercase resolve too — but always emits the
+   canonical name, so data written through it never needs the fallback path.
+
+   Built from the org's own field primitives (same chrome as Select/Input)
+   plus a RAC grid ListBox, so arrow keys move through the grid and
+   selection/focus/ARIA come from RAC rather than hand-rolled handlers.
+
+   The full set is ~1.5k icons; rendering every SVG into one popover is
+   noticeably slow, so the grid caps what it draws and tells you it did —
+   the search input is the intended way in, not scrolling.
+   ========================================================================= */
+
+/** Canonical icon names — the keys of lucide's alias-free `icons` record. */
+export type LucideIconName = keyof typeof icons
+
+const ICON_NAMES = Object.keys(icons) as LucideIconName[]
+
+/** Lookup by squashed lowercase name, so "trending-up" / "trendingup" resolve. */
+const BY_NORMALIZED = new Map<string, LucideIconName>(
+  ICON_NAMES.map((name) => [normalize(name), name]),
+)
+
+function normalize(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+/**
+ * Resolves a free-form icon name to its Lucide component, or null when it
+ * matches nothing. Null (rather than a baked-in placeholder) so each caller
+ * chooses its own fallback glyph.
+ */
+export function resolveLucideIcon(name: string | null | undefined): LucideIcon | null {
+  const canonical = resolveLucideIconName(name)
+  return canonical ? icons[canonical] : null
+}
+
+/** Same resolution, returning the canonical PascalCase name instead. */
+export function resolveLucideIconName(name: string | null | undefined): LucideIconName | null {
+  if (!name) return null
+  return BY_NORMALIZED.get(normalize(name)) ?? null
+}
+
+/** Cells drawn per batch; scrolling near the bottom appends another batch. */
+const GRID_PAGE = 120
+
+export type IconPickerProps = {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  /** Trigger text while nothing is chosen. */
+  placeholder?: string
+  /** Canonical or loose Lucide icon name; null/'' mean "no icon". */
+  value: string | null
+  /** Fires with the canonical PascalCase name, or null when cleared. */
+  onChange: (name: LucideIconName | null) => void
+  isDisabled?: boolean
+  isInvalid?: boolean
+  /** Offer a clear affordance once a value is set. Default true. */
+  allowClear?: boolean
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the trigger box. */
+  appearance?: FieldAppearance
+  /** Square, icon-only trigger (no name, no caret) for dense rows. The
+   *  popover is unchanged. Pair with `aria-label` when there's no `label`. */
+  compact?: boolean
+  /** Accessible name when no visible `label` is rendered. */
+  'aria-label'?: string
+  className?: string
+}
+
+/** Compact trigger edge — matches the height of a single-line field at that size. */
+const COMPACT_SIZE: Record<FieldSize, string> = {
+  sm: 'size-8',
+  md: 'size-[42px]',
+}
+
+export function IconPicker({
+  label,
+  description,
+  errorMessage,
+  placeholder = 'Choose an icon…',
+  value,
+  onChange,
+  isDisabled = false,
+  isInvalid = false,
+  allowClear = true,
+  size = 'md',
+  appearance,
+  compact = false,
+  'aria-label': ariaLabel,
+  className,
+}: IconPickerProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const [limit, setLimit] = useState(GRID_PAGE)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+
+  const styles = fieldControlStyles({ size, invalid: isInvalid, appearance })
+  const selectedName = resolveLucideIconName(value)
+  const SelectedIcon = selectedName ? icons[selectedName] : null
+
+  const matches = useMemo(() => {
+    const q = normalize(query)
+    return q ? ICON_NAMES.filter((name) => normalize(name).includes(q)) : ICON_NAMES
+  }, [query])
+  const visible = matches.slice(0, limit)
+  const hiddenCount = matches.length - visible.length
+
+  const open = (next: boolean) => {
+    setIsOpen(next)
+    if (!next) {
+      setQuery('')
+      setLimit(GRID_PAGE)
+    }
+  }
+
+  const search = (next: string) => {
+    setQuery(next)
+    // A new query is a new list; the old scroll depth means nothing for it.
+    setLimit(GRID_PAGE)
+  }
+
+  const onGridScroll = (element: HTMLDivElement) => {
+    if (hiddenCount === 0) return
+    const remaining = element.scrollHeight - element.scrollTop - element.clientHeight
+    if (remaining < 120) setLimit((current) => current + GRID_PAGE)
+  }
+
+  const pick = (name: LucideIconName | null) => {
+    onChange(name)
+    open(false)
+    triggerRef.current?.focus()
+  }
+
+  return (
+    <div className={cn('grid grid-cols-1 gap-1.5', className)}>
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      {compact ? (
+        <button
+          ref={triggerRef}
+          type="button"
+          aria-haspopup="dialog"
+          aria-expanded={isOpen}
+          aria-label={ariaLabel ?? (typeof label === 'string' ? label : 'Icon')}
+          title={selectedName ?? placeholder}
+          disabled={isDisabled}
+          onClick={() => open(!isOpen)}
+          data-invalid={isInvalid || undefined}
+          className={cn(
+            styles.box(),
+            'flex shrink-0 items-center justify-center cursor-pointer',
+            appearance === 'cell' ? 'size-[29px]' : COMPACT_SIZE[size],
+            'disabled:cursor-not-allowed disabled:opacity-45',
+          )}
+        >
+          {SelectedIcon ? (
+            <SelectedIcon aria-hidden className="size-4 text-ink-2" />
+          ) : (
+            <Shapes aria-hidden className="size-4 text-ink-4" />
+          )}
+        </button>
+      ) : (
+        <button
+          ref={triggerRef}
+          type="button"
+          aria-haspopup="dialog"
+          aria-expanded={isOpen}
+          aria-label={ariaLabel ?? (typeof label === 'string' ? label : 'Icon')}
+          disabled={isDisabled}
+          onClick={() => open(!isOpen)}
+          data-invalid={isInvalid || undefined}
+          className={cn(
+            // box carries no padding by contract — content is what gives a
+            // single-element control its interior (padding, font, text-size).
+            styles.box(),
+            styles.content(),
+            'flex w-full items-center gap-2 text-left cursor-pointer',
+            'disabled:cursor-not-allowed disabled:opacity-45',
+          )}
+        >
+          {SelectedIcon ? (
+            <SelectedIcon aria-hidden className="size-4 shrink-0 text-ink-2" />
+          ) : null}
+          <span className={cn('min-w-0 flex-1 truncate', selectedName ? 'text-ink' : 'text-ink-4')}>
+            {selectedName ?? placeholder}
+          </span>
+          <FieldCaret />
+        </button>
+      )}
+
+      {description ? <p className={fieldHintStyles}>{description}</p> : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <p className={fieldErrorStyles}>{errorMessage}</p>
+      ) : null}
+
+      <Popover
+        isOpen={isOpen}
+        onOpenChange={open}
+        triggerRef={triggerRef}
+        offset={6}
+        placement="bottom start"
+        className={cn(
+          'w-[316px] rounded-md border border-rule bg-surface p-2',
+          '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',
+        )}
+      >
+        <div className="flex items-center gap-1.5 pb-2">
+          <div
+            className={cn(
+              fieldControlStyles({ size: 'sm' }).box(),
+              'flex min-w-0 flex-1 items-center gap-1.5 px-2.5 py-1.5',
+              'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]',
+            )}
+          >
+            <Search aria-hidden className="size-3.5 shrink-0 text-ink-4" />
+            {/* Bare RAC input rather than the Input field: this is popover
+                furniture, not a form field — no label/description slots. */}
+            <AriaInput
+              autoFocus
+              aria-label="Search icons"
+              value={query}
+              onChange={(event) => search(event.target.value)}
+              placeholder="Search icons…"
+              className={cn(
+                'min-w-0 flex-1 bg-transparent font-sans outline-none',
+                'text-ink placeholder:text-ink-4',
+                fieldTextStyles.sm,
+              )}
+            />
+          </div>
+          {allowClear && selectedName ? (
+            <button
+              type="button"
+              onClick={() => pick(null)}
+              className={cn(
+                'flex shrink-0 items-center gap-1 rounded-[6px] px-2 py-1.5 cursor-pointer',
+                'font-sans text-[12px] text-ink-3 transition-colors',
+                'hover:bg-surface-2 hover:text-ink',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)]',
+              )}
+            >
+              <X aria-hidden className="size-3" />
+              Clear
+            </button>
+          ) : null}
+        </div>
+
+        {/* The scroll container is a wrapper rather than the ListBox itself:
+            the ListBox must keep its natural height so appended batches grow
+            it and the scrollHeight arithmetic stays meaningful. */}
+        <div
+          className="max-h-64 overflow-y-auto"
+          onScroll={(event) => onGridScroll(event.currentTarget)}
+        >
+          <ListBox
+            aria-label="Icons"
+            layout="grid"
+            selectionMode="single"
+            selectedKeys={selectedName ? new Set([selectedName]) : new Set()}
+            onSelectionChange={(keys) => {
+              if (keys === 'all') return
+              const next = [...keys][0]
+              // Re-picking the selected icon reports an empty set; keep the
+              // value — clearing has its own button.
+              if (next !== undefined) pick(next as LucideIconName)
+            }}
+            className="grid grid-cols-8 gap-0.5 outline-none"
+            renderEmptyState={() => (
+              <div className={cn('col-span-8 px-2 py-3 text-center', fieldHintStyles)}>
+                No icons match
+              </div>
+            )}
+          >
+            {visible.map((name) => {
+              const Icon = icons[name]
+              return (
+                <ListBoxItem
+                  key={name}
+                  id={name}
+                  textValue={name}
+                  // The cell's only content is an aria-hidden svg, so the name
+                  // must be explicit — it is also what the picker's tests and
+                  // any consumer's tests select on.
+                  aria-label={name}
+                  className={cn(
+                    'flex size-[34px] items-center justify-center rounded-[6px]',
+                    'cursor-pointer outline-none',
+                    'data-[hovered]:bg-surface-2 data-[focused]:bg-surface-2',
+                    'data-[focus-visible]:ring-2 data-[focus-visible]:ring-[var(--color-accent)]',
+                    'data-[selected]:bg-[color-mix(in_oklab,var(--color-accent)_12%,var(--color-surface))]',
+                    'data-[selected]:text-accent text-ink-2',
+                  )}
+                >
+                  <Icon aria-hidden className="size-4" />
+                </ListBoxItem>
+              )
+            })}
+          </ListBox>
+        </div>
+
+        {hiddenCount > 0 ? (
+          <p className={cn('px-1 pt-2', fieldHintStyles)}>
+            {hiddenCount.toLocaleString()} more — keep scrolling, or search.
+          </p>
+        ) : null}
+      </Popover>
+    </div>
+  )
+}

package/src/components/icon-picker/index.ts

@@ -0,0 +1,2 @@
+export type { IconPickerProps, LucideIconName } from './icon-picker'
+export { IconPicker, resolveLucideIcon, resolveLucideIconName } from './icon-picker'

package/src/components/record-filter/chip-value.tsx

@@ -124,9 +124,16 @@ function ChipItem({
   }
   // Lib default: enum → Badge with variant lookup; other → truncated mono text.
   if (field.type === 'enum') {
-    const variant = field.options?.find((o) => o.value === value)?.variant
-    const label = field.options?.find((o) => o.value === value)?.label ?? value
-    return <Badge variant={variant}>{label}</Badge>
+    const option = field.options?.find((o) => o.value === value)
+    return (
+      <Badge
+        variant={option?.variant}
+        {...(option?.color ? { color: option.color } : {})}
+        {...(option?.icon ? { icon: option.icon } : {})}
+      >
+        {option?.label ?? value}
+      </Badge>
+    )
   }
   return (
     <span className={cn('font-mono text-[12px] text-ink max-w-[10rem] truncate')}>

package/src/components/record-filter/filter-value-input.tsx

@@ -270,8 +270,16 @@ function EnumSingleValue({
       selectedKey={value === '' ? null : value}
       onSelectionChange={(next) => onChange(next == null ? '' : String(next))}
       renderItem={(o) => {
-        const variant = field.options?.find((x) => x.value === o.id)?.variant
-        return <Badge variant={variant}>{o.label}</Badge>
+        const option = field.options?.find((x) => x.value === o.id)
+        return (
+          <Badge
+            variant={option?.variant}
+            {...(option?.color ? { color: option.color } : {})}
+            {...(option?.icon ? { icon: option.icon } : {})}
+          >
+            {o.label}
+          </Badge>
+        )
       }}
       {...(isDisabled !== undefined ? { isDisabled } : {})}
       {...(autoFocus ? { autoFocus: true } : {})}
@@ -300,6 +308,8 @@ function EnumMultiValue({
     id: o.value,
     label: o.label,
     ...(o.variant ? { variant: o.variant } : {}),
+    ...(o.color ? { color: o.color } : {}),
+    ...(o.icon ? { icon: o.icon } : {}),
   }))
   return (
     <BadgeMultiSelect<string>

package/src/components/record-filter/operators.ts

@@ -18,25 +18,25 @@ export const OPERATORS: ReadonlyArray<OperatorDescriptor> = [
     id: 'eq',
     label: 'is',
     arity: 1,
-    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user'],
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user', 'principal'],
   },
   {
     id: 'ne',
     label: 'is not',
     arity: 1,
-    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user'],
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user', 'principal'],
   },
   {
     id: 'in',
     label: 'is any of',
     arity: 'n',
-    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user'],
+    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user', 'principal'],
   },
   {
     id: 'not_in',
     label: 'is none of',
     arity: 'n',
-    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user'],
+    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user', 'principal'],
   },
   { id: 'contains', label: 'contains', arity: 1, types: ['string', 'array'] },
   { id: 'starts_with', label: 'starts with', arity: 1, types: ['string'] },
@@ -49,13 +49,13 @@ export const OPERATORS: ReadonlyArray<OperatorDescriptor> = [
     id: 'empty',
     label: 'is empty',
     arity: 0,
-    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'file'],
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'principal', 'file'],
   },
   {
     id: 'not_empty',
     label: 'is not empty',
     arity: 0,
-    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'file'],
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'principal', 'file'],
   },
 ]
 

package/src/components/record-filter/record-filter.stories.tsx

@@ -40,7 +40,7 @@ const customerFields: FilterField[] = [
       { value: 'active', label: 'Active', variant: 'success' },
       { value: 'trialing', label: 'Trialing', variant: 'active' },
       { value: 'churned', label: 'Churned', variant: 'danger' },
-      { value: 'paused', label: 'Paused', variant: 'warning' },
+      { value: 'paused', label: 'Paused', icon: 'CirclePause', color: '#e0a030' },
     ],
   },
   { path: 'mrr', shortLabel: 'MRR', label: 'MRR', type: 'number' },

package/src/components/record-filter/types.ts

@@ -25,6 +25,10 @@ export type FilterFieldOption = {
   label: string
   /** Badge color register, used when this option is rendered as a pill. */
   variant?: BadgeVariants['variant']
+  /** `#rrggbb` tint — overrides `variant` when the option renders as a pill. */
+  color?: string
+  /** Lucide icon name shown in place of the pill's dot. */
+  icon?: string
 }
 
 export type FilterField = {

package/src/components/table/table.stories.tsx

@@ -3,7 +3,6 @@ import { useState } from 'react'
 
 import { Badge } from '../badge'
 import {
-  SortableHeaderCell,
   type SortDirection,
   Table,
   TableBody,
@@ -179,36 +178,36 @@ export const Sortable: Story = {
     return (
       <Table aria-label="Shipments — sortable">
         <TableHeader sticky>
-          <SortableHeaderCell
+          <TableHeaderCell
             width={COLUMN_WIDTHS.id}
             sortDirection={dirFor('id')}
-            onPress={() => onSort('id')}
+            onSortToggle={() => onSort('id')}
           >
             Shipment
-          </SortableHeaderCell>
-          <SortableHeaderCell
+          </TableHeaderCell>
+          <TableHeaderCell
             width={COLUMN_WIDTHS.lane}
             sortDirection={dirFor('lane')}
-            onPress={() => onSort('lane')}
+            onSortToggle={() => onSort('lane')}
           >
             Lane
-          </SortableHeaderCell>
-          <SortableHeaderCell
+          </TableHeaderCell>
+          <TableHeaderCell
             width={COLUMN_WIDTHS.carrier}
             sortDirection={dirFor('carrier')}
-            onPress={() => onSort('carrier')}
+            onSortToggle={() => onSort('carrier')}
           >
             Carrier
-          </SortableHeaderCell>
+          </TableHeaderCell>
           <TableHeaderCell width={COLUMN_WIDTHS.status}>Status</TableHeaderCell>
-          <SortableHeaderCell
+          <TableHeaderCell
             width={COLUMN_WIDTHS.rate}
             align="right"
             sortDirection={dirFor('rate')}
-            onPress={() => onSort('rate')}
+            onSortToggle={() => onSort('rate')}
           >
             Rate
-          </SortableHeaderCell>
+          </TableHeaderCell>
           <TableHeaderSpacer />
         </TableHeader>
         <TableBody>

package/src/components/toast/index.ts

@@ -0,0 +1,9 @@
+export type {
+  ToastContent,
+  ToastOptions,
+  ToastQueue,
+  ToastRegionProps,
+  ToastVariant,
+  ToastVariants,
+} from './toast'
+export { createToastQueue, ToastRegion, toastStyles } from './toast'

package/src/components/toast/toast.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Button } from '@/components/button/button'
+
+import { createToastQueue, ToastRegion } from './toast'
+
+const queue = createToastQueue()
+
+const meta: Meta<typeof ToastRegion> = {
+  title: 'Components/Toast',
+  component: ToastRegion,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof ToastRegion>
+
+export const Basic: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button
+        variant="secondary"
+        onPress={() => queue.add({ title: 'Saved', variant: 'info' }, { timeout: 4000 })}
+      >
+        Info
+      </Button>
+      <Button
+        variant="secondary"
+        onPress={() =>
+          queue.add(
+            {
+              title: 'Workflow finished',
+              description: 'sync-hubspot succeeded in 0:12',
+              variant: 'success',
+            },
+            { timeout: 5000 },
+          )
+        }
+      >
+        Success
+      </Button>
+      <Button
+        variant="secondary"
+        onPress={() =>
+          queue.add({
+            title: 'Workflow failed',
+            description: 'node "Create deal": hubspot returned 429 rate_limited',
+            variant: 'danger',
+          })
+        }
+      >
+        Danger (sticky)
+      </Button>
+      <ToastRegion queue={queue} />
+    </div>
+  ),
+}

package/src/components/toast/toast.test.tsx

@@ -0,0 +1,34 @@
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+
+import { createToastQueue, ToastRegion } from './toast'
+
+describe('Toast', () => {
+  it('renders nothing until a toast is queued, then shows title + description', () => {
+    const queue = createToastQueue()
+    render(<ToastRegion queue={queue} />)
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument()
+
+    act(() => {
+      queue.add({
+        title: 'Workflow finished',
+        description: 'sync-hubspot succeeded',
+        variant: 'success',
+      })
+    })
+    expect(screen.getByText('Workflow finished')).toBeInTheDocument()
+    expect(screen.getByText('sync-hubspot succeeded')).toBeInTheDocument()
+  })
+
+  it('dismisses via the close button', async () => {
+    const queue = createToastQueue()
+    render(<ToastRegion queue={queue} />)
+    act(() => {
+      queue.add({ title: 'Hello' })
+    })
+    const user = userEvent.setup()
+    await user.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(screen.queryByText('Hello')).not.toBeInTheDocument()
+  })
+})