@proteos/ui 0.31.0

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

@@ -0,0 +1,196 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { RecordFilterButton } from './record-filter-button'
+import { RecordFilterChips } from './record-filter-chips'
+import type { FilterField, FilterGroup } from './types'
+
+/* =========================================================================
+   Composite story for the RecordFilter family. Mirrors the design's
+   Customer entity so the visual matches the prototype.
+   ========================================================================= */
+
+const customerFields: FilterField[] = [
+  { path: 'name', shortLabel: 'Name', label: 'Name', type: 'string' },
+  {
+    path: 'email',
+    shortLabel: 'Email',
+    label: 'Email',
+    type: 'string',
+    inputType: 'email',
+  },
+  {
+    path: 'tier',
+    shortLabel: 'Tier',
+    label: 'Tier',
+    type: 'enum',
+    options: [
+      { value: 'free', label: 'Free' },
+      { value: 'starter', label: 'Starter', variant: 'neutral' },
+      { value: 'growth', label: 'Growth', variant: 'active' },
+      { value: 'enterprise', label: 'Enterprise', variant: 'success' },
+    ],
+  },
+  {
+    path: 'status',
+    shortLabel: 'Status',
+    label: 'Status',
+    type: 'enum',
+    options: [
+      { value: 'active', label: 'Active', variant: 'success' },
+      { value: 'trialing', label: 'Trialing', variant: 'active' },
+      { value: 'churned', label: 'Churned', variant: 'danger' },
+      { value: 'paused', label: 'Paused', variant: 'warning' },
+    ],
+  },
+  { path: 'mrr', shortLabel: 'MRR', label: 'MRR', type: 'number' },
+  { path: 'seats', shortLabel: 'Seats', label: 'Seats', type: 'integer' },
+  { path: 'isVerified', shortLabel: 'Verified', label: 'Verified', type: 'boolean' },
+  { path: 'signedUpAt', shortLabel: 'Signed up', label: 'Signed up', type: 'datetime' },
+  { path: 'tags', shortLabel: 'Tags', label: 'Tags', type: 'array' },
+  {
+    path: 'owner.name',
+    shortLabel: 'Name',
+    parentLabel: 'Owner',
+    label: 'Owner / Name',
+    type: 'string',
+  },
+  {
+    path: 'owner.email',
+    shortLabel: 'Email',
+    parentLabel: 'Owner',
+    label: 'Owner / Email',
+    type: 'string',
+    inputType: 'email',
+  },
+  {
+    path: 'address.country',
+    shortLabel: 'Country',
+    parentLabel: 'Address',
+    label: 'Address / Country',
+    type: 'enum',
+    options: [
+      { value: 'us', label: 'United States' },
+      { value: 'ca', label: 'Canada' },
+      { value: 'uk', label: 'United Kingdom' },
+      { value: 'de', label: 'Germany' },
+      { value: 'fr', label: 'France' },
+      { value: 'jp', label: 'Japan' },
+    ],
+  },
+]
+
+const meta: Meta = {
+  title: 'Components/RecordFilter',
+  decorators: [
+    (Story) => (
+      <div className="p-12 min-h-[60vh]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj
+
+export const ToolbarComposition: Story = {
+  render: () => {
+    const [filter, setFilter] = useState<FilterGroup>({
+      logicalOperator: 'and',
+      elements: [
+        { field: 'status', operator: 'in', value: ['active', 'trialing'] },
+        { field: 'mrr', operator: 'gt', value: '1000' },
+      ],
+    })
+    return (
+      <div className="flex flex-col gap-4 max-w-[1100px]">
+        <div className="flex items-end justify-between gap-4">
+          <div className="flex-1 min-w-0">
+            <RecordFilterChips fields={customerFields} filter={filter} onChange={setFilter} />
+          </div>
+          <div className="flex items-center gap-2 shrink-0">
+            <RecordFilterButton
+              entityLabel="Customer"
+              fields={customerFields}
+              filter={filter}
+              onChange={setFilter}
+            />
+            <button
+              type="button"
+              className="inline-flex items-center gap-1.5 px-3 py-2 rounded-md border border-rule bg-surface font-mono text-[12px] text-ink-2 hover:border-ink-4"
+            >
+              + New customer
+            </button>
+          </div>
+        </div>
+        <div className="rounded-lg border border-rule bg-surface p-4 text-[12px] font-mono text-ink-3">
+          (table renders here — wire up `filter` to your records query)
+        </div>
+        <pre className="rounded-md border border-rule bg-surface-2 p-3 text-[11px] font-mono text-ink-3 overflow-auto">
+          {JSON.stringify(filter, null, 2)}
+        </pre>
+      </div>
+    )
+  },
+}
+
+export const Empty: Story = {
+  render: () => {
+    const [filter, setFilter] = useState<FilterGroup>({ logicalOperator: 'and', elements: [] })
+    return (
+      <div className="flex items-center gap-2">
+        <RecordFilterButton
+          entityLabel="Customer"
+          fields={customerFields}
+          filter={filter}
+          onChange={setFilter}
+        />
+      </div>
+    )
+  },
+}
+
+/* tier ∈ {growth, enterprise} AND status = active AND (mrr > 1000 OR owner.team = ae)
+   — direct port of the example the design's chat transcript ends on. */
+export const WithNestedGroups: Story = {
+  render: () => {
+    const [filter, setFilter] = useState<FilterGroup>({
+      logicalOperator: 'and',
+      elements: [
+        { field: 'tier', operator: 'in', value: ['growth', 'enterprise'] },
+        { field: 'status', operator: 'eq', value: 'active' },
+      ],
+      groups: [
+        {
+          logicalOperator: 'or',
+          elements: [
+            { field: 'mrr', operator: 'gt', value: '1000' },
+            { field: 'owner.email', operator: 'contains', value: 'ae@' },
+          ],
+        },
+      ],
+    })
+    return (
+      <div className="flex flex-col gap-4 max-w-[1100px]">
+        <div className="flex items-end justify-between gap-4">
+          <div className="flex-1 min-w-0">
+            <RecordFilterChips fields={customerFields} filter={filter} onChange={setFilter} />
+          </div>
+          <div className="flex items-center gap-2 shrink-0">
+            <RecordFilterButton
+              entityLabel="Customer"
+              fields={customerFields}
+              filter={filter}
+              onChange={setFilter}
+              isComplexEnabled
+            />
+          </div>
+        </div>
+        <pre className="rounded-md border border-rule bg-surface-2 p-3 text-[11px] font-mono text-ink-3 overflow-auto">
+          {JSON.stringify(filter, null, 2)}
+        </pre>
+      </div>
+    )
+  },
+}

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

@@ -0,0 +1,437 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { RecordFilterBuilderPanel } from './record-filter-builder-panel'
+import { RecordFilterButton } from './record-filter-button'
+import { RecordFilterChips } from './record-filter-chips'
+import { __resetShowDetailsStores } from './show-details-store'
+import type { FilterField, FilterGroup } from './types'
+
+const fields: FilterField[] = [
+  { path: 'name', shortLabel: 'Name', label: 'Name', type: 'string' },
+  { path: 'mrr', shortLabel: 'MRR', label: 'MRR', type: 'number' },
+  {
+    path: 'status',
+    shortLabel: 'Status',
+    label: 'Status',
+    type: 'enum',
+    options: [
+      { value: 'active', label: 'Active', variant: 'success' },
+      { value: 'churned', label: 'Churned', variant: 'danger' },
+    ],
+  },
+]
+
+function Harness({ initial, storageKey }: { initial?: FilterGroup; storageKey?: string }) {
+  const [filter, setFilter] = useState<FilterGroup>(
+    initial ?? { logicalOperator: 'and', elements: [] },
+  )
+  return (
+    <div>
+      <RecordFilterChips
+        fields={fields}
+        filter={filter}
+        onChange={setFilter}
+        {...(storageKey ? { storageKey } : {})}
+      />
+      <RecordFilterButton
+        entityLabel="Customer"
+        fields={fields}
+        filter={filter}
+        onChange={setFilter}
+        {...(storageKey ? { storageKey } : {})}
+      />
+    </div>
+  )
+}
+
+beforeEach(() => {
+  __resetShowDetailsStores()
+})
+
+afterEach(() => {
+  __resetShowDetailsStores()
+})
+
+describe('RecordFilter', () => {
+  it('renders the Filter button only when collapsed', () => {
+    // Default collapsed state: the Filter button owns UI; no chip row.
+    const { unmount } = render(<Harness storageKey="rf.test.empty" />)
+    expect(screen.getByRole('button', { name: /^Filter$/ })).toBeInTheDocument()
+    unmount()
+
+    // Pre-expand via localStorage → chips take over, Filter button hides.
+    window.localStorage.setItem('rf.test.empty.expanded', '1')
+    render(<Harness storageKey="rf.test.empty.expanded" />)
+    expect(screen.queryByRole('button', { name: /^Filter$/ })).not.toBeInTheDocument()
+    // The +Add inline pill is the entry point in expanded-empty state.
+    expect(screen.getByRole('button', { name: /Add filter/i })).toBeInTheDocument()
+  })
+
+  it('renders chips for active filters and hides the Filter button when expanded', () => {
+    // Expanded is no longer the default — opt in explicitly.
+    window.localStorage.setItem('rf.test.expanded', '1')
+    render(
+      <Harness
+        storageKey="rf.test.expanded"
+        initial={{
+          logicalOperator: 'and',
+          elements: [
+            { field: 'status', operator: 'eq', value: 'active' },
+            { field: 'mrr', operator: 'gt', value: '500' },
+          ],
+        }}
+      />,
+    )
+    // Two chips visible.
+    expect(screen.getByLabelText(/Edit filter 1: Status/)).toBeInTheDocument()
+    expect(screen.getByLabelText(/Edit filter 2: MRR/)).toBeInTheDocument()
+    // Filter button hidden because expanded with active filters.
+    expect(screen.queryByRole('button', { name: /^Filter$/i })).not.toBeInTheDocument()
+    // The collapse toggle is visible.
+    expect(screen.getByRole('button', { name: /Collapse/i })).toBeInTheDocument()
+  })
+
+  it('toggles between collapsed and expanded', async () => {
+    const user = userEvent.setup()
+    // Start expanded so the Collapse toggle is present to click.
+    window.localStorage.setItem('rf.test.toggle', '1')
+    render(
+      <Harness
+        storageKey="rf.test.toggle"
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'status', operator: 'eq', value: 'active' }],
+        }}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /Collapse/i }))
+
+    // Now collapsed — Filter button visible (with count badge), chips hidden.
+    expect(screen.queryByLabelText(/Edit filter/)).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /Filter/i })).toBeInTheDocument()
+    // Count badge "1" somewhere inside the button.
+    expect(screen.getByText('1')).toBeInTheDocument()
+  })
+
+  it('removes a filter via the chip × button', async () => {
+    const user = userEvent.setup()
+    window.localStorage.setItem('rf.test.remove', '1')
+    render(
+      <Harness
+        storageKey="rf.test.remove"
+        initial={{
+          logicalOperator: 'and',
+          elements: [
+            { field: 'status', operator: 'eq', value: 'active' },
+            { field: 'mrr', operator: 'gt', value: '500' },
+          ],
+        }}
+      />,
+    )
+
+    const removes = screen.getAllByRole('button', { name: 'Remove filter' })
+    expect(removes).toHaveLength(2)
+    if (!removes[0]) throw new Error('expected first remove button')
+    await user.click(removes[0])
+
+    expect(screen.queryByLabelText(/Edit filter 1: Status/)).not.toBeInTheDocument()
+    expect(screen.getByLabelText(/Edit filter 1: MRR/)).toBeInTheDocument()
+  })
+
+  it('toggles AND <-> OR via the joiner pill between chips', async () => {
+    const user = userEvent.setup()
+    window.localStorage.setItem('rf.test.joiner', '1')
+    render(
+      <Harness
+        storageKey="rf.test.joiner"
+        initial={{
+          logicalOperator: 'and',
+          elements: [
+            { field: 'status', operator: 'eq', value: 'active' },
+            { field: 'mrr', operator: 'gt', value: '500' },
+          ],
+        }}
+      />,
+    )
+
+    const andPill = screen.getByRole('button', { name: 'AND' })
+    await user.click(andPill)
+    expect(screen.getByRole('button', { name: 'OR' })).toBeInTheDocument()
+  })
+})
+
+/* =========================================================================
+   Keyboard-first creation — RecordFilterBuilderPanel.
+   ========================================================================= */
+
+function PanelHarness({
+  initial,
+  onClose = () => {},
+}: {
+  initial?: FilterGroup
+  onClose?: () => void
+}) {
+  const [filter, setFilter] = useState<FilterGroup>(
+    initial ?? { logicalOperator: 'and', elements: [] },
+  )
+  return (
+    <RecordFilterBuilderPanel
+      fields={fields}
+      filter={filter}
+      onChange={setFilter}
+      onClose={onClose}
+    />
+  )
+}
+
+describe('RecordFilterBuilderPanel — keyboard creation', () => {
+  it('auto-adds a pending row on mount when elements is empty', () => {
+    const onChange = vi.fn()
+    render(
+      <RecordFilterBuilderPanel
+        fields={fields}
+        filter={{ logicalOperator: 'and', elements: [] }}
+        onChange={onChange}
+        onClose={() => {}}
+      />,
+    )
+    // First and only call appends a single pending element with field=''.
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onChange).toHaveBeenCalledWith({
+      logicalOperator: 'and',
+      elements: [{ field: '', operator: 'eq', value: '' }],
+    })
+  })
+
+  it('does not auto-add a pending row when elements is non-empty', () => {
+    const onChange = vi.fn()
+    render(
+      <RecordFilterBuilderPanel
+        fields={fields}
+        filter={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+        }}
+        onChange={onChange}
+        onClose={() => {}}
+      />,
+    )
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('Enter inside a plain value Input adds a new pending row', async () => {
+    const user = userEvent.setup()
+    render(
+      <PanelHarness
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'tonio' }],
+        }}
+      />,
+    )
+
+    // The string row's value cell is a plain <input>. Find it and focus it.
+    const valueInput = screen.getByLabelText('Name')
+    await user.click(valueInput)
+    await user.keyboard('{Enter}')
+
+    // After commit + add new pending row, two rows should exist: the
+    // original plus a fresh pending one. Probe for the second row's
+    // AttributePicker placeholder ("Find attribute…") — there's at least
+    // one in the DOM either way (the original row also has one), but with
+    // a pending row added there should be one *empty* attribute combobox.
+    const placeholders = screen.getAllByPlaceholderText('Find attribute…')
+    // Original row has one (showing the picked field as input value); the
+    // pending row adds another. Total = 2.
+    expect(placeholders).toHaveLength(2)
+  })
+
+  it('Cmd+Enter on the panel calls onClose', async () => {
+    const user = userEvent.setup()
+    const onClose = vi.fn()
+    render(
+      <PanelHarness
+        onClose={onClose}
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'tonio' }],
+        }}
+      />,
+    )
+
+    // Focus any control inside the panel and fire Cmd+Enter.
+    const valueInput = screen.getByLabelText('Name')
+    await user.click(valueInput)
+    await user.keyboard('{Meta>}{Enter}{/Meta}')
+
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+})
+
+/* =========================================================================
+   Nested groups — opt-in via `isComplexEnabled`.
+   ========================================================================= */
+
+function NestedHarness({
+  initial,
+  isComplexEnabled,
+}: {
+  initial?: FilterGroup
+  isComplexEnabled: boolean
+}) {
+  const [filter, setFilter] = useState<FilterGroup>(
+    initial ?? { logicalOperator: 'and', elements: [] },
+  )
+  return (
+    <RecordFilterBuilderPanel
+      fields={fields}
+      filter={filter}
+      onChange={setFilter}
+      onClose={() => {}}
+      isComplexEnabled={isComplexEnabled}
+    />
+  )
+}
+
+describe('RecordFilterBuilderPanel — nested groups', () => {
+  it('hides the Add group button when isComplexEnabled is false', () => {
+    render(
+      <RecordFilterBuilderPanel
+        fields={fields}
+        filter={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+        }}
+        onChange={() => {}}
+        onClose={() => {}}
+      />,
+    )
+    expect(screen.queryByRole('button', { name: /Add group/i })).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /Add filter/i })).toBeInTheDocument()
+  })
+
+  it('shows Add group, "Wrap in group" hover icon, and the GROUP eyebrow when enabled', async () => {
+    const user = userEvent.setup()
+    render(
+      <NestedHarness
+        isComplexEnabled
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+        }}
+      />,
+    )
+
+    expect(screen.getByRole('button', { name: /Wrap in group/i })).toBeInTheDocument()
+    const addGroup = screen.getByRole('button', { name: /Add group/i })
+    await user.click(addGroup)
+
+    // After clicking Add group: a Group eyebrow appears + the new sub-group's
+    // "Empty group" prompt appears in the body.
+    expect(screen.getByText(/^Group$/)).toBeInTheDocument()
+    expect(screen.getByText(/Empty group/i)).toBeInTheDocument()
+  })
+
+  it('Wrap in group moves the leaf into a new sub-group with the opposite joiner', async () => {
+    const user = userEvent.setup()
+    const onFilter = vi.fn<(f: FilterGroup) => void>()
+    render(
+      <ProbePanel
+        onFilter={onFilter}
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+        }}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /Wrap in group/i }))
+
+    expect(onFilter).toHaveBeenCalled()
+    const next = onFilter.mock.calls.at(-1)?.[0]
+    expect(next?.elements).toHaveLength(0)
+    expect(next?.groups).toHaveLength(1)
+    expect(next?.groups?.[0]?.logicalOperator).toBe('or')
+    expect(next?.groups?.[0]?.elements?.[0]?.field).toBe('name')
+  })
+
+  it('Removing a nested group via the group × leaves elements untouched', async () => {
+    const user = userEvent.setup()
+    const onFilter = vi.fn<(f: FilterGroup) => void>()
+    render(
+      <ProbePanel
+        onFilter={onFilter}
+        initial={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+          groups: [
+            {
+              logicalOperator: 'or',
+              elements: [{ field: 'mrr', operator: 'gt', value: '1000' }],
+            },
+          ],
+        }}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /Remove group/i }))
+
+    const next = onFilter.mock.calls.at(-1)?.[0]
+    expect(next?.groups ?? []).toHaveLength(0)
+    expect(next?.elements).toHaveLength(1)
+  })
+})
+
+function ProbePanel({
+  initial,
+  onFilter,
+}: {
+  initial: FilterGroup
+  onFilter: (f: FilterGroup) => void
+}) {
+  const [filter, setFilter] = useState<FilterGroup>(initial)
+  return (
+    <RecordFilterBuilderPanel
+      fields={fields}
+      filter={filter}
+      onChange={(next) => {
+        setFilter(next)
+        onFilter(next)
+      }}
+      onClose={() => {}}
+      isComplexEnabled
+    />
+  )
+}
+
+describe('RecordFilterChips — nested groups', () => {
+  it('renders a read-only group pill for each sub-group', () => {
+    // Chips only render when expanded; the store now defaults to collapsed.
+    window.localStorage.setItem('rf.showDetails', '1')
+    render(
+      <RecordFilterChips
+        fields={fields}
+        filter={{
+          logicalOperator: 'and',
+          elements: [{ field: 'name', operator: 'eq', value: 'x' }],
+          groups: [
+            {
+              logicalOperator: 'or',
+              elements: [
+                { field: 'mrr', operator: 'gt', value: '1000' },
+                { field: 'status', operator: 'eq', value: 'active' },
+              ],
+            },
+          ],
+        }}
+        onChange={() => {}}
+      />,
+    )
+    expect(screen.getByText(/or group/i)).toBeInTheDocument()
+    expect(screen.getByText(/· 2/)).toBeInTheDocument()
+  })
+})

package/src/components/record-filter/show-details-store.ts

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react'
+
+/* =========================================================================
+   showDetails persistence — a tiny pub/sub on top of localStorage so the
+   FilterButton (collapsed) and the FilterChips (expanded) stay in sync
+   regardless of where they're mounted in the page. Keyed by a configurable
+   storage key so multiple filter UIs can coexist.
+   ========================================================================= */
+
+type Listener = (next: boolean) => void
+
+const stores = new Map<string, Set<Listener>>()
+
+function listeners(key: string): Set<Listener> {
+  let set = stores.get(key)
+  if (!set) {
+    set = new Set()
+    stores.set(key, set)
+  }
+  return set
+}
+
+function read(key: string): boolean {
+  if (typeof window === 'undefined') return false
+  try {
+    // Default collapsed: only an explicit '1' expands. Unset / '0' → collapsed.
+    return window.localStorage.getItem(key) === '1'
+  } catch {
+    return false
+  }
+}
+
+function write(key: string, next: boolean) {
+  if (typeof window !== 'undefined') {
+    try {
+      window.localStorage.setItem(key, next ? '1' : '0')
+    } catch {
+      /* ignore quota / privacy-mode errors */
+    }
+  }
+  for (const fn of listeners(key)) fn(next)
+}
+
+export function useShowDetails(storageKey = 'rf.showDetails') {
+  const [value, setValue] = useState<boolean>(() => read(storageKey))
+
+  useEffect(() => {
+    const fn: Listener = (next) => setValue(next)
+    listeners(storageKey).add(fn)
+    setValue(read(storageKey))
+    return () => {
+      listeners(storageKey).delete(fn)
+    }
+  }, [storageKey])
+
+  const toggle = () => write(storageKey, !read(storageKey))
+  const set = (next: boolean) => write(storageKey, next)
+
+  return [value, toggle, set] as const
+}
+
+/** Test-only escape hatch — clears all listeners and storage values. */
+export function __resetShowDetailsStores() {
+  stores.clear()
+  if (typeof window !== 'undefined') {
+    try {
+      window.localStorage.clear()
+    } catch {
+      /* ignore */
+    }
+  }
+}