@proteos/ui 0.46.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/ui",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "license": "FSL-1.1-Apache-2.0",
   "description": "Proteos React component library (React Aria Components + Tailwind v4).",
   "repository": {
@@ -55,7 +55,8 @@
     "tailwind-merge": "^3.5.0",
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.2.4",
-    "@proteos/sdk": "0.46.0"
+    "thinking-orbs": "^0.3.1",
+    "@proteos/sdk": "0.48.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

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

@@ -9,6 +9,7 @@ import {
   MessageCircle,
   MessagesSquare,
   Mic,
+  Phone,
   Send,
   Video,
 } from 'lucide-react'
@@ -41,6 +42,7 @@ const CHANNEL_ICONS: Readonly<Record<string, LucideIcon>> = {
   'teams-meeting': Video,
   'webex-meeting': Video,
   adhoc: AudioLines,
+  phone: Phone,
 }
 
 /** The channel's glyph component. Unknown channels get the generic one. */

package/src/components/checkbox/checkbox.tsx

@@ -16,7 +16,14 @@ export function Checkbox({ children, className, ...props }: CheckboxProps) {
       {...props}
       className={(renderProps) =>
         cn(
-          'group inline-flex items-center gap-2.5 cursor-pointer',
+          // `relative` so RAC's visually-hidden <input> — which is absolutely
+          // positioned and is the element that actually receives focus — is
+          // laid out against THIS checkbox. Without a positioned ancestor here
+          // it resolves against a far-away container, ends up outside any
+          // scroll clipping, and focusing it makes the browser scroll a
+          // container the user cannot scroll back (the roles permission
+          // matrix, where toggling a row threw the page off-screen).
+          'group relative 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,

package/src/components/data-table/data-table.test.tsx

@@ -0,0 +1,112 @@
+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 { DataTable, type InfiniteQueryLike } from './data-table'
+
+type Row = { id: string; name: string }
+
+const ROWS: Row[] = [
+  { id: 'r-1', name: 'Alpha' },
+  { id: 'r-2', name: 'Beta' },
+  { id: 'r-3', name: 'Gamma' },
+]
+
+function query(rows: Row[]): InfiniteQueryLike<Row> {
+  return {
+    data: { pages: [{ data: rows, meta: { items_total: rows.length } }] },
+    isLoading: false,
+    isFetchingNextPage: false,
+    hasNextPage: false,
+    error: null,
+    fetchNextPage: vi.fn(),
+  }
+}
+
+const columns = [{ id: 'name', accessorKey: 'name', header: 'Name', size: 160 }]
+
+function Harness({ onChange }: { onChange?: (ids: Set<string>) => void }) {
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+  return (
+    <DataTable<Row>
+      query={query(ROWS)}
+      columns={columns}
+      ariaLabel="Records"
+      selectionMode="multiple"
+      selectedIds={selected}
+      onSelectionChange={(ids) => {
+        setSelected(ids)
+        onChange?.(ids)
+      }}
+    />
+  )
+}
+
+// The body is virtualized against a real scroll box, which jsdom cannot
+// measure (every rect is 0×0, so the virtualizer yields no items and no row
+// ever renders). Swap the virtualizer for a pass-through that emits every
+// row — the windowing itself is TanStack's to test, not ours.
+vi.mock('@tanstack/react-virtual', () => ({
+  useVirtualizer: ({ count, estimateSize }: { count: number; estimateSize: () => number }) => {
+    const size = estimateSize()
+    return {
+      getTotalSize: () => count * size,
+      getVirtualItems: () =>
+        Array.from({ length: count }, (_unused, index) => ({
+          index,
+          key: index,
+          start: index * size,
+          size,
+        })),
+    }
+  },
+}))
+
+describe('DataTable selection', () => {
+  it('renders no checkboxes when selection is off', () => {
+    render(<DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" />)
+    expect(screen.queryByRole('checkbox')).toBeNull()
+  })
+
+  it('select-all toggles every loaded row, then clears', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onChange={onChange} />)
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select all rows' }))
+    expect(onChange).toHaveBeenLastCalledWith(new Set(['r-1', 'r-2', 'r-3']))
+
+    await user.click(screen.getByRole('checkbox', { name: 'Deselect all rows' }))
+    expect(onChange).toHaveBeenLastCalledWith(new Set())
+  })
+
+  it('selecting one row leaves select-all indeterminate', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select row 1' }))
+
+    const selectAll = screen.getByRole('checkbox', { name: 'Select all rows' })
+    expect(selectAll).toBePartiallyChecked()
+  })
+
+  it('does not open a row when its checkbox is clicked', async () => {
+    const user = userEvent.setup()
+    const onRowClick = vi.fn()
+    render(
+      <DataTable<Row>
+        query={query(ROWS)}
+        columns={columns}
+        ariaLabel="Records"
+        selectionMode="multiple"
+        selectedIds={new Set()}
+        onSelectionChange={vi.fn()}
+        onRowClick={onRowClick}
+      />,
+    )
+
+    await user.click(screen.getByRole('checkbox', { name: 'Select row 1' }))
+    expect(onRowClick).not.toHaveBeenCalled()
+  })
+})

package/src/components/data-table/data-table.tsx

@@ -24,6 +24,7 @@ import {
 } from 'react'
 
 import { cn } from '../../lib/cn'
+import { Checkbox } from '../checkbox'
 import {
   isColumnDragData,
   type SortDirection,
@@ -138,6 +139,20 @@ export type DataTableProps<TRow> = {
    * at slot='end'. Sits inside the scrollable area below the rows.
    */
   bodyAfter?: ReactNode
+  /**
+   * Row selection. `none` (default) renders no checkbox column; `multiple`
+   * prepends a sticky leading checkbox column and turns the header checkbox
+   * into a tri-state select-all.
+   *
+   * Selection is CONTROLLED — the owner holds the ids because it is the one
+   * that acts on them (running a batch action, clearing after a save). The
+   * header checkbox covers the rows currently LOADED: an infinite list can't
+   * honestly claim to select rows it has never fetched, so "select everything
+   * matching the filter" belongs to the owner's toolbar, not here.
+   */
+  selectionMode?: 'none' | 'multiple'
+  selectedIds?: Set<string>
+  onSelectionChange?: (ids: Set<string>) => void
   /**
    * Draw vertical gridlines between body cells. The header always has them;
    * the body opts in (e.g. inline-edit mode wants the full Excel-style grid).
@@ -148,6 +163,9 @@ export type DataTableProps<TRow> = {
 
 const DEFAULT_ROW_HEIGHT = 32
 
+/** Column id of the leading checkbox column added by `selectionMode`. */
+export const SELECTION_COLUMN_ID = '__select__' 
+
 export function DataTable<TRow>({
   query,
   columns,
@@ -172,6 +190,9 @@ export function DataTable<TRow>({
   extraRows,
   bodyBefore,
   bodyAfter,
+  selectionMode = 'none',
+  selectedIds,
+  onSelectionChange,
   columnBorders = false,
 }: DataTableProps<TRow>) {
   const rows = useMemo<TRow[]>(() => {
@@ -183,21 +204,124 @@ export function DataTable<TRow>({
     return [...startExtras, ...dataRows, ...endExtras]
   }, [query.data, extraRows])
 
+  const resolveRowId = useMemo(
+    () =>
+      getRowId ??
+      ((row: TRow, index: number) => {
+        const r = row as Record<string, unknown>
+        if (typeof r.id === 'string' || typeof r.id === 'number') return String(r.id)
+        if (typeof r.slug === 'string') return r.slug
+        return String(index)
+      }),
+    [getRowId],
+  )
+
+  const selectionEnabled = selectionMode === 'multiple'
+  const selected = useMemo(() => selectedIds ?? new Set<string>(), [selectedIds])
+  // Ids of the rows currently LOADED — what the header checkbox operates on.
+  const loadedIds = useMemo(
+    () => (selectionEnabled ? rows.map((row, index) => resolveRowId(row, index)) : []),
+    [selectionEnabled, rows, resolveRowId],
+  )
+  // Anchor for shift-click range selection, in loaded-row index space.
+  const lastToggledIndexRef = useRef<number | null>(null)
+
+  const toggleRow = (id: string, index: number, isRange: boolean) => {
+    if (!onSelectionChange) return
+    const next = new Set(selected)
+    const anchor = lastToggledIndexRef.current
+    if (isRange && anchor !== null) {
+      const [from, to] = anchor <= index ? [anchor, index] : [index, anchor]
+      // A range drag always ADDS — matching how file managers and mail
+      // clients behave; use individual clicks to take rows back out.
+      for (let i = from; i <= to; i += 1) {
+        const rangeId = loadedIds[i]
+        if (rangeId !== undefined) next.add(rangeId)
+      }
+    } else if (next.has(id)) {
+      next.delete(id)
+    } else {
+      next.add(id)
+    }
+    lastToggledIndexRef.current = index
+    onSelectionChange(next)
+  }
+
+  const loadedSelectedCount = loadedIds.reduce((count, id) => count + (selected.has(id) ? 1 : 0), 0)
+  const allLoadedSelected = loadedIds.length > 0 && loadedSelectedCount === loadedIds.length
+
+  const toggleAllLoaded = () => {
+    if (!onSelectionChange) return
+    const next = new Set(selected)
+    if (allLoadedSelected) {
+      for (const id of loadedIds) next.delete(id)
+    } else {
+      for (const id of loadedIds) next.add(id)
+    }
+    lastToggledIndexRef.current = null
+    onSelectionChange(next)
+  }
+
+  // RAC's Checkbox onChange carries no modifier keys, so the shift state is
+  // captured on the preceding pointer event.
+  const rangeModifierRef = useRef(false)
+
+  const selectionColumn = useMemo<ColumnDef<TRow>>(
+    () => ({
+      id: SELECTION_COLUMN_ID,
+      size: 36,
+      enableSorting: false,
+      meta: { align: 'center', sticky: 'left', cellClassName: 'px-0 justify-center' },
+      header: () => (
+        <span className="inline-flex items-center justify-center w-full">
+          <Checkbox
+            aria-label={allLoadedSelected ? 'Deselect all rows' : 'Select all rows'}
+            isSelected={allLoadedSelected}
+            isIndeterminate={loadedSelectedCount > 0 && !allLoadedSelected}
+            isDisabled={loadedIds.length === 0}
+            onChange={toggleAllLoaded}
+          />
+        </span>
+      ),
+      cell: ({ row }) => (
+        // Stop the click here: selecting a row must never also open it.
+        <span
+          className="inline-flex items-center justify-center w-full"
+          onClick={(event) => event.stopPropagation()}
+          onKeyDown={(event) => {
+            event.stopPropagation()
+            rangeModifierRef.current = event.shiftKey
+          }}
+          onPointerDownCapture={(event) => {
+            rangeModifierRef.current = event.shiftKey
+          }}
+          role="presentation"
+        >
+          <Checkbox
+            aria-label={`Select row ${row.index + 1}`}
+            isSelected={selected.has(row.id)}
+            onChange={() => toggleRow(row.id, row.index, rangeModifierRef.current)}
+          />
+        </span>
+      ),
+    }),
+    // biome-ignore lint/correctness/useExhaustiveDependencies: handlers read the latest selection via closure recreated on these inputs
+    [selected, loadedIds, allLoadedSelected, loadedSelectedCount],
+  )
+
+  const tableColumns = useMemo(
+    () => (selectionEnabled ? [selectionColumn, ...columns] : columns),
+    [selectionEnabled, selectionColumn, columns],
+  )
+
   const table = useReactTable({
     data: rows,
-    columns,
+    columns: tableColumns,
     state: { sorting: sorting ?? [] },
     ...(onSortingChange ? { onSortingChange } : {}),
     manualSorting: true,
     getCoreRowModel: getCoreRowModel(),
-    getRowId: getRowId
-      ? (row, index) => getRowId(row, index)
-      : (row, index) => {
-          const r = row as Record<string, unknown>
-          if (typeof r.id === 'string' || typeof r.id === 'number') return String(r.id)
-          if (typeof r.slug === 'string') return r.slug
-          return String(index)
-        },
+    getRowId: (row, index) => resolveRowId(row, index),
   })
 
   const tableRows = table.getRowModel().rows
@@ -243,8 +367,8 @@ export function DataTable<TRow>({
   })
 
   const totalColumnWidth = useMemo(
-    () => columns.reduce((sum, c) => sum + (c.size ?? 140), 0),
-    [columns],
+    () => tableColumns.reduce((sum, c) => sum + (c.size ?? 140), 0),
+    [tableColumns],
   )
 
   // Single global pragmatic-dnd monitor for column reorder. We mirror the

package/src/components/data-table/index.ts

@@ -7,7 +7,7 @@ export type {
 } from './cells'
 export { BooleanCell, DateCell, DateTimeCell, LinkCell, TruncateCell } from './cells'
 export type { DataTableProps, InfiniteQueryLike } from './data-table'
-export { DataTable } from './data-table'
+export { DataTable, SELECTION_COLUMN_ID } from './data-table'
 
 export type { ActionsColumnOptions } from './make-actions-column'
 export { makeActionsColumn } from './make-actions-column'

package/src/components/orb/index.ts

@@ -0,0 +1,2 @@
+export type { OrbProps, OrbSizeToken } from './orb'
+export { Orb } from './orb'

package/src/components/orb/orb.stories.tsx

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { Orb } from './orb'
+
+const meta: Meta<typeof Orb> = {
+  title: 'Components/Orb',
+  component: Orb,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof Orb>
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Orb size="xs" label="Agent working" />
+      <Orb size="sm" label="Agent working" />
+      <Orb size="md" label="Agent working" />
+      <Orb size="lg" label="Agent working" />
+      <span className="text-[13px] text-ink-3">Agent is composing…</span>
+    </div>
+  ),
+}

package/src/components/orb/orb.tsx

@@ -0,0 +1,57 @@
+import { type OrbState, type OrbTheme, ThinkingOrb } from 'thinking-orbs'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Orb — the "agent is working" indicator, backed by the `thinking-orbs`
+   package (https://orbs.jakubantalik.com): a canvas-rendered dotted orb
+   (state: solving), monochrome ink that auto-resolves against `data-theme`
+   / OS scheme, with a reduced-motion static frame built in.
+
+   The package ships two hand-tuned designs — 20px (inline) and 64px
+   (avatar). `sm` and `lg` render them at native size; `xs` gently
+   downscales the 20px design, `md` downscales the 64px one (downscaling
+   stays crisp — the canvas buffer is the larger design).
+
+   Purely decorative by default — pass `label` to expose it as an img with
+   an accessible name (e.g. "Agent working").
+   ========================================================================= */
+
+export type OrbSizeToken = 'xs' | 'sm' | 'md' | 'lg'
+
+/** CSS box per token. sm/lg match the native designs exactly (no scaling). */
+const SIZE_PX: Record<OrbSizeToken, number> = { xs: 12, sm: 20, md: 40, lg: 64 }
+
+/** Which native design each token rides. */
+const DESIGN: Record<OrbSizeToken, 20 | 64> = { xs: 20, sm: 20, md: 64, lg: 64 }
+
+export interface OrbProps {
+  /** xs 12 · sm 20 (native inline) · md 40 · lg 64 (native avatar). Default `sm`. */
+  size?: OrbSizeToken
+  /** Animation state; defaults to `solving` (the working indicator). */
+  state?: OrbState
+  /** Speed multiplier (1 = tuned speed); e.g. 0.2 for a slow idle shimmer. */
+  speed?: number
+  /** Pin the ink instead of auto-detecting — `dark` renders light dots (for
+   *  a dark chip like the launcher's black circle). */
+  theme?: OrbTheme
+  className?: string
+  /** Accessible name; omitting it hides the orb from assistive tech. */
+  label?: string
+}
+
+export function Orb({ size = 'sm', state = 'solving', speed, theme, className, label }: OrbProps) {
+  const px = SIZE_PX[size]
+  const design = DESIGN[size]
+  return (
+    <ThinkingOrb
+      state={state}
+      size={design}
+      {...(speed !== undefined ? { speed } : {})}
+      {...(theme !== undefined ? { theme } : {})}
+      className={cn('inline-block shrink-0', className)}
+      {...(px !== design ? { style: { width: px, height: px } } : {})}
+      {...(label ? { 'aria-label': label } : { 'aria-hidden': true })}
+    />
+  )
+}

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

@@ -124,7 +124,7 @@ function ChipItem({
   }
   // Lib default: enum → Badge with variant lookup; other → truncated mono text.
   if (field.type === 'enum') {
-    const option = field.options?.find((o) => o.value === value)
+    const option = findEnumOption(field, value)
     return (
       <Badge
         variant={option?.variant}
@@ -146,6 +146,13 @@ function Em({ children }: { children: string }) {
   return <span className="font-mono text-[12px] text-ink-4">{children}</span>
 }
 
+/** The declared option for an enum value, if the field carries one. Central so
+ *  the badge, the multi-value summary and the single-value summary agree on
+ *  what a stored value is called. */
+function findEnumOption(field: FilterField, value: string) {
+  return field.options?.find((option) => option.value === value)
+}
+
 export function formatValue(
   field: FilterField,
   operator: ComparisonOperator,
@@ -161,7 +168,7 @@ export function formatValue(
         : []
     if (arr.length === 0) return '—'
     if (field.type === 'enum') {
-      const labels = arr.map((v) => field.options?.find((x) => x.value === v)?.label ?? v)
+      const labels = arr.map((v) => findEnumOption(field, v)?.label ?? v)
       return labels.length <= 2
         ? labels.join(', ')
         : `${labels[0]}, ${labels[1]} +${labels.length - 2}`
@@ -170,6 +177,14 @@ export function formatValue(
   }
   if (field.type === 'boolean') return value === true || value === 'true' ? 'true' : 'false'
   if (value === '' || value == null) return '—'
+  // An enum stores a system value ("technical_decider") and displays its
+  // declared label ("Technical Decider"). The multi-value branch above and the
+  // badge below already do this; a single value read as the raw slug, so the
+  // same filter said "is technical_decider" or "is any of Technical Decider"
+  // depending only on the operator.
+  if (field.type === 'enum') {
+    return findEnumOption(field, String(value))?.label ?? String(value)
+  }
   if (field.type === 'number' || field.type === 'integer') {
     const n = Number(value)
     return Number.isFinite(n) ? n.toLocaleString() : String(value)

package/src/components/record-filter/field-label.ts

@@ -0,0 +1,29 @@
+/* =========================================================================
+   Field-label composition — how a nested or related field reads in the
+   picker, the chips rail and the operator row.
+
+   A `FilterField` path is hierarchical: an object leaf (`address.city`) and
+   a field reached through a relation (`company_id.name`) both render as a
+   breadcrumb. The separator lives here because BOTH sides compose it — the
+   consumer builds `FilterField.label` from an entity, and the chips rail
+   builds its own breadcrumb from `parentLabel` — and a mismatch between the
+   two shows up as one chip reading "Company · Name" next to another reading
+   "Company / Name".
+   ========================================================================= */
+
+/**
+ * U+00B7 MIDDLE DOT, spaced. The same separator the app already uses for
+ * breadcrumb-ish text ("Segment · SaaS decision makers"), and quieter than a
+ * slash at the small type sizes these labels render at — the eye reads the
+ * words, not the punctuation.
+ */
+export const FIELD_LABEL_SEPARATOR = ' · '
+
+/**
+ * Joins breadcrumb parts with {@link FIELD_LABEL_SEPARATOR}, skipping empties
+ * so a field with no parent renders as its own label rather than with a
+ * leading separator.
+ */
+export function joinFieldLabel(...parts: ReadonlyArray<string | undefined | null>): string {
+  return parts.filter((part): part is string => !!part && part.length > 0).join(FIELD_LABEL_SEPARATOR)
+}

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

@@ -1,4 +1,5 @@
 export { AttributePicker, type AttributePickerProps } from './attribute-picker'
+export { FIELD_LABEL_SEPARATOR, joinFieldLabel } from './field-label'
 export {
   ChipValue,
   type ChipValueItemRenderer,

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

@@ -14,6 +14,7 @@ import { OperatorPicker } from './operator-picker'
 import { operatorById, operatorsForType } from './operators'
 import { useShowDetails } from './show-details-store'
 import { AttributeTypeIcon } from '../attribute-type-icon'
+import { FIELD_LABEL_SEPARATOR } from './field-label'
 import type { ComparisonOperator, FilterField, FilterGroup, FilterValue } from './types'
 
 /* =========================================================================
@@ -370,7 +371,12 @@ function Chip({
           </span>
         ) : null}
         <span className="font-sans text-[12.5px] text-ink-2">
-          {field.parentLabel ? <span className="text-ink-4">{field.parentLabel} / </span> : null}
+          {field.parentLabel ? (
+            <span className="text-ink-4">
+              {field.parentLabel}
+              {FIELD_LABEL_SEPARATOR}
+            </span>
+          ) : null}
           <span className="text-ink">{field.shortLabel}</span>
         </span>
         <span className="font-mono text-[11px] text-ink-3">{op?.label}</span>

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

@@ -52,14 +52,14 @@ const customerFields: FilterField[] = [
     path: 'owner.name',
     shortLabel: 'Name',
     parentLabel: 'Owner',
-    label: 'Owner / Name',
+    label: 'Owner · Name',
     type: 'string',
   },
   {
     path: 'owner.email',
     shortLabel: 'Email',
     parentLabel: 'Owner',
-    label: 'Owner / Email',
+    label: 'Owner · Email',
     type: 'string',
     inputType: 'email',
   },
@@ -67,7 +67,7 @@ const customerFields: FilterField[] = [
     path: 'address.country',
     shortLabel: 'Country',
     parentLabel: 'Address',
-    label: 'Address / Country',
+    label: 'Address · Country',
     type: 'enum',
     options: [
       { value: 'us', label: 'United States' },