@proteos/ui 0.31.0

package/src/components/record-filter/group-mutations.ts

@@ -0,0 +1,116 @@
+import { defaultValueFor, operatorsForType } from './operators'
+import type { FilterElement, FilterField, FilterGroup, LogicalOperator } from './types'
+
+/* =========================================================================
+   group-mutations — pure immutable helpers that produce a new `FilterGroup`
+   from the previous one + an action. The recursive popover panel composes
+   these instead of inlining `{ ...g, elements: g.elements.map(...) }`
+   spaghetti.
+
+   Invariants:
+   - Inputs are never mutated.
+   - Index parameters refer to position within the relevant sub-array
+     (`elements` for leaves, `groups` for sub-groups). The two arrays are
+     addressed independently — the renderer treats them as ordered children
+     by concatenation (leaves first, then groups).
+   ========================================================================= */
+
+export function addLeaf(group: FilterGroup, field: FilterField): FilterGroup {
+  const ops = operatorsForType(field.type)
+  const op = ops[0]
+  if (!op) return group
+  const next: FilterElement = {
+    field: field.path,
+    operator: op.id,
+    value: defaultValueFor(field.type, op.arity),
+  }
+  return { ...group, elements: [...(group.elements ?? []), next] }
+}
+
+export function addPendingLeaf(group: FilterGroup): FilterGroup {
+  const next: FilterElement = { field: '', operator: 'eq', value: '' }
+  return { ...group, elements: [...(group.elements ?? []), next] }
+}
+
+export function addSubgroup(
+  group: FilterGroup,
+  joiner: LogicalOperator = oppositeJoiner(group.logicalOperator),
+): FilterGroup {
+  const sub: FilterGroup = { logicalOperator: joiner, elements: [], groups: [] }
+  return { ...group, groups: [...(group.groups ?? []), sub] }
+}
+
+export function removeLeaf(group: FilterGroup, index: number): FilterGroup {
+  const elements = group.elements ?? []
+  return { ...group, elements: elements.filter((_, i) => i !== index) }
+}
+
+export function removeSubgroup(group: FilterGroup, index: number): FilterGroup {
+  const groups = group.groups ?? []
+  return { ...group, groups: groups.filter((_, i) => i !== index) }
+}
+
+export function updateLeaf(
+  group: FilterGroup,
+  index: number,
+  patch: Partial<FilterElement> | FilterElement,
+): FilterGroup {
+  const elements = group.elements ?? []
+  return {
+    ...group,
+    elements: elements.map((el, i) => (i === index ? { ...el, ...patch } : el)),
+  }
+}
+
+export function replaceLeaf(
+  group: FilterGroup,
+  index: number,
+  next: FilterElement,
+): FilterGroup {
+  const elements = group.elements ?? []
+  return { ...group, elements: elements.map((el, i) => (i === index ? next : el)) }
+}
+
+export function updateSubgroup(
+  group: FilterGroup,
+  index: number,
+  next: FilterGroup,
+): FilterGroup {
+  const groups = group.groups ?? []
+  return { ...group, groups: groups.map((g, i) => (i === index ? next : g)) }
+}
+
+/* Wrap an existing leaf in a new sub-group with the opposite joiner.
+   Leaves the rest of the group untouched. The leaf is moved into the new
+   sub-group's `elements`. Used by the "wrap in group" hover action. */
+export function wrapLeafInGroup(group: FilterGroup, index: number): FilterGroup {
+  const elements = group.elements ?? []
+  const leaf = elements[index]
+  if (!leaf) return group
+  const sub: FilterGroup = {
+    logicalOperator: oppositeJoiner(group.logicalOperator),
+    elements: [leaf],
+    groups: [],
+  }
+  return {
+    ...group,
+    elements: elements.filter((_, i) => i !== index),
+    groups: [...(group.groups ?? []), sub],
+  }
+}
+
+export function setJoiner(group: FilterGroup, joiner: LogicalOperator): FilterGroup {
+  return { ...group, logicalOperator: joiner }
+}
+
+/* Recursively count leaf filters in a group. Used by the chip pill badge
+   and for filter-button counts when nested groups are present. */
+export function countLeaves(group: FilterGroup): number {
+  const direct = (group.elements ?? []).length
+  const nested = (group.groups ?? []).reduce((n, g) => n + countLeaves(g), 0)
+  return direct + nested
+}
+
+function oppositeJoiner(j: LogicalOperator): LogicalOperator {
+  return j === 'and' ? 'or' : 'and'
+}

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

@@ -0,0 +1,58 @@
+export { AttributePicker, type AttributePickerProps } from './attribute-picker'
+export {
+  ChipValue,
+  type ChipValueItemRenderer,
+  type ChipValueProps,
+  formatValue,
+  RenderChipItemProvider,
+  useRenderChipItem,
+} from './chip-value'
+export {
+  FilterRow,
+  type FilterRowProps,
+  rebaseRowOnFieldChange,
+  rebaseRowOnOperatorChange,
+} from './filter-row'
+export {
+  addLeaf as addFilterLeaf,
+  addPendingLeaf,
+  addSubgroup,
+  countLeaves,
+  removeLeaf,
+  removeSubgroup,
+  replaceLeaf,
+  setJoiner,
+  updateLeaf,
+  updateSubgroup,
+  wrapLeafInGroup,
+} from './group-mutations'
+export {
+  FilterValueInput,
+  type FilterValueInputProps,
+  type FilterValueInputRenderer,
+  RenderValueInputProvider,
+  useRenderValueInput,
+} from './filter-value-input'
+export { OperatorPicker, type OperatorPickerProps } from './operator-picker'
+export { arityOf, defaultValueFor, OPERATORS, operatorById, operatorsForType } from './operators'
+export {
+  RecordFilterBuilderPanel,
+  type RecordFilterBuilderPanelProps,
+} from './record-filter-builder-panel'
+export { RecordFilterEditor, type RecordFilterEditorProps } from './record-filter-editor'
+export { RecordFilterButton, type RecordFilterButtonProps } from './record-filter-button'
+export { RecordFilterChips, type RecordFilterChipsProps } from './record-filter-chips'
+export { useShowDetails } from './show-details-store'
+export type {
+  ComparisonOperator,
+  FilterElement,
+  FilterField,
+  FilterFieldOption,
+  FilterFieldRelation,
+  FilterFieldType,
+  FilterGroup,
+  FilterValue,
+  LogicalOperator,
+  OperatorArity,
+  OperatorDescriptor,
+} from './types'

package/src/components/record-filter/nested-group.tsx

@@ -0,0 +1,138 @@
+import { cn } from '../../lib/cn'
+import { SegmentedControl } from '../segmented-control/segmented-control'
+import { GroupBody } from './group-body'
+import type { FilterField, FilterGroup, LogicalOperator } from './types'
+
+/* =========================================================================
+   NestedGroup — non-root group rendered as a bordered, indented panel.
+   Layout:
+
+     [WHERE/AND/OR  ] [ ┌─ Group · AND/OR ───────────── × ┐ ]
+                       [   FilterRow                       ]
+                       [   FilterRow                       ]
+                       [   + Add filter   + Add group      ]
+                       [ └────────────────────────────────┘ ]
+
+   The left gutter aligns with sibling FilterRows so the joiner ("AND" /
+   "OR" or the leading "WHERE") sits in the same column. The bordered panel
+   carries the group's own AND/OR header + remove button; its body recurses
+   into another `GroupBody`.
+   ========================================================================= */
+
+export type NestedGroupProps = {
+  /** Sibling index inside the parent group's combined children list (leaves
+   *  first, groups last). Drives the joiner label. */
+  index: number
+  /** Parent group's logical operator — that's what joins this sub-group to
+   *  its siblings. */
+  joiner: LogicalOperator
+  group: FilterGroup
+  fields: ReadonlyArray<FilterField>
+  fieldsByPath: Record<string, FilterField>
+  onChange: (next: FilterGroup) => void
+  onRemove: () => void
+  showFieldIcons: boolean
+  showJoinerToggle: boolean
+  isComplexEnabled: boolean
+}
+
+export function NestedGroup({
+  index,
+  joiner,
+  group,
+  fields,
+  fieldsByPath,
+  onChange,
+  onRemove,
+  showFieldIcons,
+  showJoinerToggle,
+  isComplexEnabled,
+}: NestedGroupProps) {
+  const elementCount = (group.elements?.length ?? 0) + (group.groups?.length ?? 0)
+  const showJoinerSegment = showJoinerToggle && elementCount >= 2
+
+  return (
+    <div className="flex items-stretch gap-2 px-1.5">
+      {/* Joiner gutter — same width as a FilterRow's gutter so siblings line
+          up vertically. `px-1.5` matches FilterRow's horizontal padding so
+          the gutter labels and the group-panel left edge align with sibling
+          rows. `pt-2` aligns the label with the group header text. */}
+      <span className="w-12 shrink-0 inline-flex justify-end pr-1 pt-2">
+        <span
+          className={cn(
+            'font-mono text-[10.5px] tracking-[0.08em]',
+            index === 0 ? 'text-ink-4' : 'text-accent-ink',
+          )}
+        >
+          {index === 0 ? 'WHERE' : joiner.toUpperCase()}
+        </span>
+      </span>
+
+      <div
+        className={cn(
+          'flex-1 min-w-0 rounded-sm border border-rule',
+          'bg-[color-mix(in_oklab,var(--color-surface-2)_60%,var(--color-surface))]',
+        )}
+      >
+        {/* Group header — eyebrow + AND/OR + remove */}
+        <div className="flex items-center justify-between px-2.5 py-1.5 border-b border-rule">
+          <div className="flex items-center gap-2">
+            <span className="font-mono text-[10px] uppercase tracking-[0.08em] text-ink-4">
+              Group
+            </span>
+            {showJoinerSegment ? (
+              <SegmentedControl<LogicalOperator>
+                aria-label="Group joiner"
+                options={[
+                  { id: 'and', label: 'AND' },
+                  { id: 'or', label: 'OR' },
+                ]}
+                value={group.logicalOperator}
+                onChange={(next) => onChange({ ...group, logicalOperator: next })}
+              />
+            ) : (
+              <span className="font-mono text-[10.5px] tracking-[0.08em] text-ink-3 uppercase">
+                {group.logicalOperator}
+              </span>
+            )}
+          </div>
+          <button
+            type="button"
+            onClick={onRemove}
+            aria-label="Remove group"
+            className={cn(
+              'size-6 inline-flex items-center justify-center rounded-sm',
+              'text-ink-4 hover:text-danger hover:bg-surface cursor-pointer outline-none',
+            )}
+          >
+            <svg
+              aria-hidden
+              viewBox="0 0 14 14"
+              className="size-3.5"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.4"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M3 4h8M5 4V3a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1v1M4.5 4l.5 7a1 1 0 0 0 1 1h3a1 1 0 0 0 1-1l.5-7" />
+            </svg>
+          </button>
+        </div>
+
+        <div className="px-1.5 py-1.5">
+          <GroupBody
+            group={group}
+            fields={fields}
+            fieldsByPath={fieldsByPath}
+            onChange={onChange}
+            isRoot={false}
+            isComplexEnabled={isComplexEnabled}
+            showFieldIcons={showFieldIcons}
+            showJoinerToggle={showJoinerToggle}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/record-filter/operator-picker.tsx

@@ -0,0 +1,62 @@
+import { cn } from '../../lib/cn'
+import type { FieldSize } from '../field/field'
+import { Select, type SelectOption } from '../select/select'
+import { operatorsForType } from './operators'
+import type { ComparisonOperator, FilterFieldType } from './types'
+
+/* =========================================================================
+   OperatorPicker — small dropdown of operators valid for the given field
+   type. Wraps lib `Select` and inherits its compact `sm` chrome so it lines
+   up byte-for-byte with the AttributePicker beside it.
+   ========================================================================= */
+
+export type OperatorPickerProps = {
+  fieldType: FilterFieldType
+  value: ComparisonOperator
+  onChange: (next: ComparisonOperator) => void
+  isDisabled?: boolean
+  /** Auto-focus the trigger on mount. Used by the chip mini-editor so focus
+   *  lands on the operator (the field is already chosen, the operator is the
+   *  natural next thing to tweak). */
+  autoFocus?: boolean
+  /** Field size. Defaults to `sm` to match the filter row. */
+  size?: FieldSize
+  /** Visual override for the trigger wrapper (sizing). */
+  className?: string
+  /** Per-field allowlist override (LUM-34). When provided, picks operators
+   *  from this list instead of `operatorsForType(fieldType)`. */
+  operators?: ReadonlyArray<ComparisonOperator>
+}
+
+export function OperatorPicker({
+  fieldType,
+  value,
+  onChange,
+  isDisabled,
+  autoFocus,
+  size = 'sm',
+  className,
+  operators,
+}: OperatorPickerProps) {
+  const allForType = operatorsForType(fieldType)
+  const ops = operators ? allForType.filter((op) => operators.includes(op.id)) : allForType
+  const options: SelectOption<ComparisonOperator>[] = ops.map((op) => ({
+    id: op.id,
+    label: op.label,
+  }))
+
+  return (
+    <Select<ComparisonOperator>
+      aria-label="Operator"
+      options={options}
+      selectedKey={value}
+      onSelectionChange={(next) => onChange(next as ComparisonOperator)}
+      size={size}
+      {...(isDisabled !== undefined ? { isDisabled } : {})}
+      {...(autoFocus ? { autoFocus: true } : {})}
+      className={cn('w-full', className)}
+      // `min-w-0` lets the trigger shrink so its <SelectValue> can truncate.
+      triggerClassName="min-w-0"
+    />
+  )
+}

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

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+
+import { arityOf, defaultValueFor, OPERATORS, operatorById, operatorsForType } from './operators'
+
+describe('operatorsForType', () => {
+  it('includes eq/ne for every primitive type', () => {
+    for (const t of ['string', 'number', 'integer', 'datetime', 'enum', 'boolean'] as const) {
+      const ops = operatorsForType(t).map((o) => o.id)
+      expect(ops).toContain('eq')
+      expect(ops).toContain('ne')
+    }
+  })
+
+  it('only allows starts_with / ends_with on strings', () => {
+    for (const op of ['starts_with', 'ends_with'] as const) {
+      const types = OPERATORS.find((o) => o.id === op)?.types ?? []
+      expect(types).toEqual(['string'])
+    }
+  })
+
+  it('allows in / not_in on strings, numbers, and enums (not datetime/boolean/array)', () => {
+    for (const op of ['in', 'not_in'] as const) {
+      const types = new Set(OPERATORS.find((o) => o.id === op)?.types ?? [])
+      expect(types.has('string')).toBe(true)
+      expect(types.has('number')).toBe(true)
+      expect(types.has('integer')).toBe(true)
+      expect(types.has('enum')).toBe(true)
+      expect(types.has('datetime')).toBe(false)
+      expect(types.has('boolean')).toBe(false)
+      expect(types.has('array')).toBe(false)
+    }
+  })
+
+  it('only allows gte/lte on datetime', () => {
+    for (const op of ['gte', 'lte'] as const) {
+      const types = OPERATORS.find((o) => o.id === op)?.types ?? []
+      expect(types).toEqual(['datetime'])
+    }
+  })
+
+  it('allows contains/empty/not_empty on arrays', () => {
+    const arrayOps = operatorsForType('array').map((o) => o.id)
+    expect(arrayOps).toContain('contains')
+    expect(arrayOps).toContain('empty')
+    expect(arrayOps).toContain('not_empty')
+    // No magnitude/text-shape operators on arrays.
+    expect(arrayOps).not.toContain('gt')
+    expect(arrayOps).not.toContain('starts_with')
+  })
+
+  it('allows identity operators on user, not text/numeric shapes', () => {
+    const userOps = operatorsForType('user').map((o) => o.id)
+    expect(userOps).toEqual(
+      expect.arrayContaining(['eq', 'ne', 'in', 'not_in', 'empty', 'not_empty']),
+    )
+    expect(userOps).not.toContain('contains')
+    expect(userOps).not.toContain('starts_with')
+    expect(userOps).not.toContain('gt')
+  })
+
+  it('overrides labels per field type where natural', () => {
+    const numberEq = operatorsForType('number').find((o) => o.id === 'eq')
+    expect(numberEq?.label).toBe('equals')
+
+    const datetimeGt = operatorsForType('datetime').find((o) => o.id === 'gt')
+    expect(datetimeGt?.label).toBe('is after')
+  })
+})
+
+describe('arityOf', () => {
+  it('returns 0 for empty/not_empty', () => {
+    expect(arityOf('empty')).toBe(0)
+    expect(arityOf('not_empty')).toBe(0)
+  })
+  it("returns 'n' for in/not_in", () => {
+    expect(arityOf('in')).toBe('n')
+    expect(arityOf('not_in')).toBe('n')
+  })
+  it('returns 1 for the rest', () => {
+    expect(arityOf('eq')).toBe(1)
+    expect(arityOf('contains')).toBe(1)
+    expect(arityOf('gt')).toBe(1)
+  })
+})
+
+describe('defaultValueFor', () => {
+  it('returns null for arity 0', () => {
+    expect(defaultValueFor('string', 0)).toBeNull()
+  })
+  it("returns [] for arity 'n'", () => {
+    expect(defaultValueFor('enum', 'n')).toEqual([])
+  })
+  it('returns true for boolean fields, empty string otherwise', () => {
+    expect(defaultValueFor('boolean', 1)).toBe(true)
+    expect(defaultValueFor('string', 1)).toBe('')
+    expect(defaultValueFor('number', 1)).toBe('')
+  })
+})
+
+describe('operatorById', () => {
+  it('finds known operators', () => {
+    expect(operatorById('eq')?.label).toBe('is')
+    expect(operatorById('contains')?.arity).toBe(1)
+  })
+})

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

@@ -0,0 +1,97 @@
+import type {
+  ComparisonOperator,
+  FilterFieldType,
+  FilterValue,
+  OperatorArity,
+  OperatorDescriptor,
+} from './types'
+
+/* =========================================================================
+   Operator catalogue — single source of truth for which operators apply
+   to which field types and how many values each takes. Mirrors the
+   backend enum at `core-model/comparison-operator.go` and the design's
+   `OPERATORS` table.
+   ========================================================================= */
+
+export const OPERATORS: ReadonlyArray<OperatorDescriptor> = [
+  {
+    id: 'eq',
+    label: 'is',
+    arity: 1,
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user'],
+  },
+  {
+    id: 'ne',
+    label: 'is not',
+    arity: 1,
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'relation', 'user'],
+  },
+  {
+    id: 'in',
+    label: 'is any of',
+    arity: 'n',
+    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user'],
+  },
+  {
+    id: 'not_in',
+    label: 'is none of',
+    arity: 'n',
+    types: ['string', 'number', 'integer', 'currency', 'enum', 'relation', 'user'],
+  },
+  { id: 'contains', label: 'contains', arity: 1, types: ['string', 'array'] },
+  { id: 'starts_with', label: 'starts with', arity: 1, types: ['string'] },
+  { id: 'ends_with', label: 'ends with', arity: 1, types: ['string'] },
+  { id: 'gt', label: 'is greater than', arity: 1, types: ['number', 'integer', 'currency', 'datetime'] },
+  { id: 'gte', label: 'is on or after', arity: 1, types: ['datetime'] },
+  { id: 'lt', label: 'is less than', arity: 1, types: ['number', 'integer', 'currency', 'datetime'] },
+  { id: 'lte', label: 'is on or before', arity: 1, types: ['datetime'] },
+  {
+    id: 'empty',
+    label: 'is empty',
+    arity: 0,
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'file'],
+  },
+  {
+    id: 'not_empty',
+    label: 'is not empty',
+    arity: 0,
+    types: ['string', 'number', 'integer', 'currency', 'datetime', 'enum', 'boolean', 'array', 'relation', 'user', 'file'],
+  },
+]
+
+const OP_LABEL_OVERRIDES: Partial<
+  Record<FilterFieldType, Partial<Record<ComparisonOperator, string>>>
+> = {
+  number: { gt: 'is greater than', lt: 'is less than', eq: 'equals', ne: 'does not equal' },
+  integer: { gt: 'is greater than', lt: 'is less than', eq: 'equals', ne: 'does not equal' },
+  currency: { gt: 'is greater than', lt: 'is less than', eq: 'equals', ne: 'does not equal' },
+  datetime: { eq: 'is on', ne: 'is not on', gt: 'is after', lt: 'is before' },
+  array: { contains: 'contains', empty: 'is empty', not_empty: 'is not empty' },
+  boolean: { eq: 'is', ne: 'is not' },
+}
+
+export function operatorsForType(type: FilterFieldType): ReadonlyArray<OperatorDescriptor> {
+  return OPERATORS.filter((op) => op.types.includes(type)).map((op) => {
+    const override = OP_LABEL_OVERRIDES[type]?.[op.id]
+    return override ? { ...op, label: override } : op
+  })
+}
+
+export function operatorById(id: ComparisonOperator): OperatorDescriptor | undefined {
+  return OPERATORS.find((o) => o.id === id)
+}
+
+export function arityOf(operator: ComparisonOperator): OperatorArity {
+  return operatorById(operator)?.arity ?? 1
+}
+
+/* =========================================================================
+   Default value for a fresh row, given the field type and the chosen
+   operator's arity. Keeps the value shape consistent with `FilterValue`.
+   ========================================================================= */
+export function defaultValueFor(type: FilterFieldType, arity: OperatorArity): FilterValue {
+  if (arity === 0) return null
+  if (arity === 'n') return []
+  if (type === 'boolean') return true
+  return ''
+}