@open-mercato/ui 0.6.1-develop.3276.1.1fcd145078 → 0.6.1-develop.3287.1.450f4ffb56

package/src/backend/filters/__tests__/FilteredEmptyResults.test.tsx

@@ -0,0 +1,35 @@
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback: string, vars?: Record<string, unknown>) => {
+    if (!vars) return fallback
+    return Object.entries(vars).reduce((s, [k, v]) => s.replace(new RegExp(`\\{${k}\\}`, 'g'), String(v)), fallback)
+  },
+}))
+
+import { render, screen, fireEvent } from '@testing-library/react'
+import { FilteredEmptyResults } from '../FilteredEmptyResults'
+
+describe('FilteredEmptyResults', () => {
+  it('renders title with entityNamePlural interpolated', () => {
+    render(<FilteredEmptyResults entityNamePlural="people" canRemoveLast onClearAll={() => {}} onRemoveLast={() => {}} />)
+    expect(screen.getByText(/no people match these filters/i)).toBeInTheDocument()
+  })
+
+  it('calls onClearAll on Clear button click', () => {
+    const onClearAll = jest.fn()
+    render(<FilteredEmptyResults entityNamePlural="people" canRemoveLast onClearAll={onClearAll} onRemoveLast={() => {}} />)
+    fireEvent.click(screen.getByRole('button', { name: /clear all filters/i }))
+    expect(onClearAll).toHaveBeenCalled()
+  })
+
+  it('calls onRemoveLast on Remove last click', () => {
+    const onRemoveLast = jest.fn()
+    render(<FilteredEmptyResults entityNamePlural="people" canRemoveLast onClearAll={() => {}} onRemoveLast={onRemoveLast} />)
+    fireEvent.click(screen.getByRole('button', { name: /remove last filter/i }))
+    expect(onRemoveLast).toHaveBeenCalled()
+  })
+
+  it('disables remove last when canRemoveLast=false', () => {
+    render(<FilteredEmptyResults entityNamePlural="people" canRemoveLast={false} onClearAll={() => {}} onRemoveLast={() => {}} />)
+    expect(screen.getByRole('button', { name: /remove last filter/i })).toBeDisabled()
+  })
+})

package/src/backend/filters/__tests__/QuickFilters.test.tsx

@@ -0,0 +1,34 @@
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (_key: string, fallback: string) => fallback,
+}))
+
+import { render, screen, fireEvent } from '@testing-library/react'
+import { QuickFilters, type FilterPreset } from '../QuickFilters'
+import { createEmptyTree } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+
+const presets: FilterPreset[] = [
+  { id: 'recent', labelKey: 'ui.test.recent', iconName: 'clock', build: () => createEmptyTree() },
+  { id: 'mine', labelKey: 'ui.test.mine', build: () => createEmptyTree() },
+]
+
+describe('QuickFilters', () => {
+  it('renders nothing when no presets', () => {
+    const { container } = render(<QuickFilters presets={[]} userId="u1" onApply={() => {}} />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders a chip per preset', () => {
+    render(<QuickFilters presets={presets} userId="u1" onApply={() => {}} />)
+    expect(screen.getByRole('button', { name: /ui.test.recent/i })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /ui.test.mine/i })).toBeInTheDocument()
+  })
+
+  it('calls onApply with the built tree on click and passes userId+now', () => {
+    const onApply = jest.fn()
+    const build = jest.fn(() => createEmptyTree())
+    render(<QuickFilters presets={[{ id: 'mine', labelKey: 'k', build }]} userId="u-42" onApply={onApply} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(build).toHaveBeenCalledWith(expect.objectContaining({ userId: 'u-42', now: expect.any(Date) }))
+    expect(onApply).toHaveBeenCalledTimes(1)
+  })
+})

package/src/backend/filters/__tests__/filterValidation.test.ts

@@ -0,0 +1,69 @@
+// packages/ui/src/backend/filters/__tests__/filterValidation.test.ts
+import { validateTreeForApply, type ValidationError } from '../filterValidation'
+import type { AdvancedFilterTree } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+import type { FilterFieldDef } from '@open-mercato/shared/lib/query/advanced-filter'
+
+const fields: FilterFieldDef[] = [
+  { key: 'name', label: 'Name', type: 'text' },
+  { key: 'created_at', label: 'Created', type: 'date' },
+  { key: 'tags', label: 'Tags', type: 'tags' },
+  { key: 'status', label: 'Status', type: 'select' },
+]
+
+function tree(...children: any[]): AdvancedFilterTree {
+  return { root: { id: 'r', type: 'group', combinator: 'and', children } }
+}
+
+describe('validateTreeForApply', () => {
+  it('returns ok for empty tree', () => {
+    expect(validateTreeForApply(tree(), fields)).toEqual({ ok: true })
+  })
+
+  it('flags rule with empty value on value-required op', () => {
+    const t = tree({ id: 'a', type: 'rule', field: 'name', operator: 'contains', value: '' })
+    const r = validateTreeForApply(t, fields)
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.errors[0].ruleId).toBe('a')
+  })
+
+  it('passes valueless operator without value', () => {
+    const t = tree({ id: 'a', type: 'rule', field: 'name', operator: 'is_empty', value: undefined })
+    expect(validateTreeForApply(t, fields)).toEqual({ ok: true })
+  })
+
+  it('flags multi-value op with empty array', () => {
+    const t = tree({ id: 'a', type: 'rule', field: 'tags', operator: 'has_any_of', value: [] })
+    const r = validateTreeForApply(t, fields)
+    expect(r.ok).toBe(false)
+  })
+
+  it('flags between op with one endpoint missing', () => {
+    const t = tree({ id: 'a', type: 'rule', field: 'created_at', operator: 'between', value: ['2026-01-01', ''] })
+    const r = validateTreeForApply(t, fields)
+    expect(r.ok).toBe(false)
+  })
+
+  it('walks nested groups and reports errors from sub-groups', () => {
+    const t = tree(
+      { id: 'a', type: 'rule', field: 'name', operator: 'contains', value: 'okay' },
+      { id: 'g1', type: 'group', combinator: 'or', children: [
+        { id: 'b', type: 'rule', field: 'name', operator: 'contains', value: '' },
+      ] },
+    )
+    const r = validateTreeForApply(t, fields)
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.errors.map(e => e.ruleId)).toEqual(['b'])
+  })
+
+  it('allows non-blank one-character substring text operators', () => {
+    const t = tree({ id: 'a', type: 'rule', field: 'name', operator: 'contains', value: 'a' })
+    expect(validateTreeForApply(t, fields)).toEqual({ ok: true })
+  })
+
+  it('allows all non-blank substring operators regardless of length', () => {
+    for (const op of ['contains', 'does_not_contain', 'starts_with', 'ends_with'] as const) {
+      const short = tree({ id: 'a', type: 'rule', field: 'name', operator: op, value: 'ab' })
+      expect(validateTreeForApply(short, fields)).toEqual({ ok: true })
+    }
+  })
+})

package/src/backend/filters/__tests__/treeReducer.test.ts

@@ -0,0 +1,189 @@
+/** @jest-environment node */
+import {
+  treeReducer,
+  canAddRule,
+  canAddGroup,
+} from '../treeReducer'
+import type { AdvancedFilterTree } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+
+const seed: AdvancedFilterTree = {
+  root: {
+    id: 'r', type: 'group', combinator: 'and',
+    children: [{ id: 'a', type: 'rule', field: 'display_name', operator: 'contains', value: 'Daniel' }],
+  },
+}
+
+describe('treeReducer', () => {
+  it('addRule appends a rule to the target group', () => {
+    const next = treeReducer(seed, { type: 'addRule', groupId: 'r' })
+    expect(next.root.children).toHaveLength(2)
+    expect(next.root.children[1].type).toBe('rule')
+  })
+
+  it('addGroup appends a nested group with one empty rule', () => {
+    const next = treeReducer(seed, { type: 'addGroup', groupId: 'r' })
+    const last = next.root.children[next.root.children.length - 1]
+    expect(last.type).toBe('group')
+    if (last.type === 'group') {
+      expect(last.combinator).toBe('and')
+      expect(last.children).toHaveLength(1)
+      expect(last.children[0].type).toBe('rule')
+    }
+  })
+
+  it('removeNode removes by id', () => {
+    const next = treeReducer(seed, { type: 'removeNode', nodeId: 'a' })
+    expect(next.root.children).toHaveLength(0)
+  })
+
+  it('updateRule patches field/op/value', () => {
+    const next = treeReducer(seed, { type: 'updateRule', ruleId: 'a', updates: { value: 'Naomi' } })
+    expect((next.root.children[0] as any).value).toBe('Naomi')
+  })
+
+  it('updateGroupCombinator flips and|or', () => {
+    const next = treeReducer(seed, { type: 'updateGroupCombinator', groupId: 'r', combinator: 'or' })
+    expect(next.root.combinator).toBe('or')
+  })
+
+  it('addRule rejected when group has 15 children', () => {
+    const big: AdvancedFilterTree = {
+      root: {
+        id: 'r', type: 'group', combinator: 'and',
+        children: Array.from({ length: 15 }, (_, i) => ({
+          id: `r${i}`, type: 'rule' as const, field: 'f', operator: 'is' as const, value: 'x',
+        })),
+      },
+    }
+    const next = treeReducer(big, { type: 'addRule', groupId: 'r' })
+    expect(next).toBe(big) // rejected; identity preserved
+  })
+
+  it('addGroup rejected at level 3', () => {
+    const t: AdvancedFilterTree = {
+      root: {
+        id: 'r', type: 'group', combinator: 'and', children: [
+          {
+            id: 'g2', type: 'group', combinator: 'and', children: [
+              {
+                id: 'g3', type: 'group', combinator: 'and', children: [
+                  { id: 'rr', type: 'rule', field: 'f', operator: 'is', value: 'x' },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    }
+    const next = treeReducer(t, { type: 'addGroup', groupId: 'g3' })
+    expect(next).toBe(t)
+  })
+
+  it('addRule rejected at total cap', () => {
+    // 50 rules across 4 sub-groups (15+15+15+5), each under width cap
+    const mk = (prefix: string, n: number) =>
+      Array.from({ length: n }, (_, i) => ({
+        id: `${prefix}${i}`, type: 'rule' as const, field: 'f', operator: 'is' as const, value: 'x',
+      }))
+    const t: AdvancedFilterTree = {
+      root: {
+        id: 'r', type: 'group', combinator: 'and', children: [
+          { id: 'a', type: 'group', combinator: 'and', children: mk('a', 15) },
+          { id: 'b', type: 'group', combinator: 'and', children: mk('b', 15) },
+          { id: 'c', type: 'group', combinator: 'and', children: mk('c', 15) },
+          { id: 'd', type: 'group', combinator: 'and', children: mk('d', 5) },
+        ],
+      },
+    }
+    const next = treeReducer(t, { type: 'addRule', groupId: 'a' })
+    expect(next).toBe(t)
+  })
+})
+
+describe('canAddRule / canAddGroup', () => {
+  it('canAddGroup returns false at level 3', () => {
+    const t: AdvancedFilterTree = {
+      root: {
+        id: 'r', type: 'group', combinator: 'and', children: [
+          {
+            id: 'g2', type: 'group', combinator: 'and', children: [
+              { id: 'g3', type: 'group', combinator: 'and', children: [] },
+            ],
+          },
+        ],
+      },
+    }
+    expect(canAddGroup(t, 'g3')).toBe(false)
+    expect(canAddGroup(t, 'g2')).toBe(true) // adding into g2 produces a level-3 group
+    expect(canAddGroup(t, 'r')).toBe(true)
+  })
+
+  it('canAddRule returns false at width cap', () => {
+    const t: AdvancedFilterTree = {
+      root: {
+        id: 'r', type: 'group', combinator: 'and',
+        children: Array.from({ length: 15 }, (_, i) => ({
+          id: `r${i}`, type: 'rule' as const, field: 'f', operator: 'is' as const, value: 'x',
+        })),
+      },
+    }
+    expect(canAddRule(t, 'r')).toBe(false)
+  })
+})
+
+describe('treeReducer — reorderChildren', () => {
+  it('swaps two children inside the same group', () => {
+    const tree: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [
+      { id: 'a', type: 'rule', field: 'name', operator: 'contains', value: 'X' } as any,
+      { id: 'b', type: 'rule', field: 'name', operator: 'contains', value: 'Y' } as any,
+      { id: 'c', type: 'rule', field: 'name', operator: 'contains', value: 'Z' } as any,
+    ] } }
+    const out = treeReducer(tree, { type: 'reorderChildren', groupId: 'r', fromIdx: 0, toIdx: 2 })
+    expect(out.root.children.map((c: any) => c.id)).toEqual(['b', 'c', 'a'])
+  })
+  it('no-op when group not found', () => {
+    const tree: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [] } }
+    expect(treeReducer(tree, { type: 'reorderChildren', groupId: 'missing', fromIdx: 0, toIdx: 1 })).toBe(tree)
+  })
+})
+
+describe('treeReducer — removeLast', () => {
+  it('removes the rule with the highest addedAt', () => {
+    const tree: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [
+      { id: 'a', type: 'rule', field: 'name', operator: 'contains', value: 'X', addedAt: 1 } as any,
+      { id: 'b', type: 'rule', field: 'name', operator: 'contains', value: 'Y', addedAt: 3 } as any,
+      { id: 'c', type: 'rule', field: 'name', operator: 'contains', value: 'Z', addedAt: 2 } as any,
+    ] } }
+    const out = treeReducer(tree, { type: 'removeLast' })
+    expect(out.root.children.map((c: any) => c.id)).toEqual(['a', 'c'])
+  })
+  it('no-op when no node has addedAt', () => {
+    const tree: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [] } }
+    expect(treeReducer(tree, { type: 'removeLast' })).toBe(tree)
+  })
+})
+
+describe('treeReducer — replaceRoot', () => {
+  it('overwrites the root group', () => {
+    const tree: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [] } }
+    const newRoot = { id: 'r2', type: 'group' as const, combinator: 'or' as const, children: [] }
+    const out = treeReducer(tree, { type: 'replaceRoot', root: newRoot })
+    expect(out.root.id).toBe('r2')
+    expect(out.root.combinator).toBe('or')
+  })
+})
+
+describe('treeReducer — addedAt stamping', () => {
+  it('stamps addedAt on addRule', () => {
+    const before: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [] } }
+    const after = treeReducer(before, { type: 'addRule', groupId: 'r' })
+    const inserted = after.root.children[0] as any
+    expect(typeof inserted.addedAt).toBe('number')
+  })
+  it('stamps addedAt on addGroup', () => {
+    const before: AdvancedFilterTree = { root: { id: 'r', type: 'group', combinator: 'and', children: [] } }
+    const after = treeReducer(before, { type: 'addGroup', groupId: 'r' })
+    const inserted = after.root.children[0] as any
+    expect(typeof inserted.addedAt).toBe('number')
+  })
+})

package/src/backend/filters/filterValidation.ts

@@ -0,0 +1,61 @@
+// packages/ui/src/backend/filters/filterValidation.ts
+import type { AdvancedFilterTree, FilterRule, FilterGroup } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+import type { FilterFieldDef } from '@open-mercato/shared/lib/query/advanced-filter'
+import { isValuelessOperator } from '@open-mercato/shared/lib/query/advanced-filter'
+
+export type ValidationError = {
+  ruleId: string
+  messageKey: string
+  message: string
+}
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; errors: ValidationError[] }
+
+const MULTI_VALUE_OPS = new Set(['is_any_of', 'is_none_of', 'has_any_of', 'has_all_of', 'has_none_of'])
+
+function isBlank(value: unknown): boolean {
+  if (value == null) return true
+  if (typeof value === 'string') return value.trim().length === 0
+  return false
+}
+
+function validateRule(rule: FilterRule): ValidationError | null {
+  if (isValuelessOperator(rule.operator)) return null
+  const op = rule.operator
+  if (op === 'between') {
+    if (!Array.isArray(rule.value) || rule.value.length !== 2 || isBlank(rule.value[0]) || isBlank(rule.value[1])) {
+      return { ruleId: rule.id, messageKey: 'ui.advancedFilter.error.betweenIncomplete', message: 'Pick both endpoints' }
+    }
+    return null
+  }
+  if (MULTI_VALUE_OPS.has(op)) {
+    if (!Array.isArray(rule.value) || rule.value.length === 0) {
+      return { ruleId: rule.id, messageKey: 'ui.advancedFilter.error.missingValue', message: 'Pick at least one value' }
+    }
+    return null
+  }
+  if (isBlank(rule.value)) {
+    return { ruleId: rule.id, messageKey: 'ui.advancedFilter.error.missingValue', message: 'Pick a value to apply this filter' }
+  }
+  return null
+}
+
+function walkGroup(group: FilterGroup, acc: ValidationError[]): void {
+  for (const child of group.children) {
+    if (child.type === 'rule') {
+      const err = validateRule(child)
+      if (err) acc.push(err)
+    } else {
+      walkGroup(child, acc)
+    }
+  }
+}
+
+export function validateTreeForApply(tree: AdvancedFilterTree, fields: FilterFieldDef[]): ValidationResult {
+  void fields
+  const errors: ValidationError[] = []
+  walkGroup(tree.root, errors)
+  return errors.length === 0 ? { ok: true } : { ok: false, errors }
+}

package/src/backend/filters/treeReducer.ts

@@ -0,0 +1,201 @@
+import {
+  type AdvancedFilterTree,
+  type FilterRule,
+  type FilterGroup,
+  type FilterCombinator,
+  validateTreeLimits,
+  TREE_LIMITS,
+} from '@open-mercato/shared/lib/query/advanced-filter-tree'
+import type { FilterOperator } from '@open-mercato/shared/lib/query/advanced-filter'
+
+export type TreeAction =
+  | { type: 'addRule'; groupId: string; defaultField?: string; defaultOperator?: FilterOperator }
+  | { type: 'addGroup'; groupId: string; defaultField?: string; defaultOperator?: FilterOperator }
+  | { type: 'removeNode'; nodeId: string }
+  | { type: 'updateRule'; ruleId: string; updates: Partial<Pick<FilterRule, 'field' | 'operator' | 'value'>> }
+  | { type: 'updateGroupCombinator'; groupId: string; combinator: FilterCombinator }
+  | { type: 'reorderChildren'; groupId: string; fromIdx: number; toIdx: number }
+  | { type: 'removeLast' }
+  | { type: 'replaceRoot'; root: FilterGroup }
+
+// Pure monotonic counter for tracking insert order within a session.
+// MUST NOT be mixed with wall-clock time — that leaks load timing into tests
+// (fixture ordering depended on `Date.now()` resolution across runs).
+// Runtime-only — never serialized.
+let addedAtCounter = 0
+function nextAddedAt(): number {
+  addedAtCounter += 1
+  return addedAtCounter
+}
+
+function emptyRule(defaultField?: string, defaultOperator?: FilterOperator): FilterRule {
+  return {
+    id: crypto.randomUUID(),
+    type: 'rule',
+    field: defaultField ?? '',
+    operator: defaultOperator ?? 'contains',
+    value: '',
+    addedAt: nextAddedAt(),
+  }
+}
+
+function emptyGroup(defaultField?: string, defaultOperator?: FilterOperator): FilterGroup {
+  return {
+    id: crypto.randomUUID(),
+    type: 'group',
+    combinator: 'and',
+    children: [emptyRule(defaultField, defaultOperator)],
+    addedAt: nextAddedAt(),
+  }
+}
+
+type WithAddedAt = { addedAt?: number }
+
+function findMaxAddedAtNode(
+  group: FilterGroup,
+): { parent: FilterGroup; idx: number; addedAt: number } | null {
+  let best: { parent: FilterGroup; idx: number; addedAt: number } | null = null
+  function walk(g: FilterGroup) {
+    g.children.forEach((c, idx) => {
+      const a = (c as unknown as WithAddedAt).addedAt
+      if (typeof a === 'number') {
+        if (!best || a > best.addedAt) best = { parent: g, idx, addedAt: a }
+      }
+      if (c.type === 'group') walk(c)
+    })
+  }
+  walk(group)
+  return best
+}
+
+function findGroupAndDepth(root: FilterGroup, id: string, depth = 1): { group: FilterGroup; depth: number } | null {
+  if (root.id === id) return { group: root, depth }
+  for (const child of root.children) {
+    if (child.type === 'group') {
+      const r = findGroupAndDepth(child, id, depth + 1)
+      if (r) return r
+    }
+  }
+  return null
+}
+
+function countRules(group: FilterGroup): number {
+  let n = 0
+  for (const c of group.children) {
+    if (c.type === 'rule') n += 1
+    else n += countRules(c)
+  }
+  return n
+}
+
+export function treeReducer(state: AdvancedFilterTree, action: TreeAction): AdvancedFilterTree {
+  // replaceRoot bypasses cloning/walking — it overwrites the entire root.
+  if (action.type === 'replaceRoot') {
+    const next: AdvancedFilterTree = { root: action.root }
+    const v = validateTreeLimits(next)
+    return v.ok ? next : state
+  }
+
+  // Deep clone so React detects state change. The tree is JSON-safe so JSON
+  // round-tripping is sufficient; the Jest jsdom env doesn't expose
+  // `structuredClone`, so avoid relying on it.
+  const next: AdvancedFilterTree = JSON.parse(JSON.stringify(state))
+
+  if (action.type === 'removeLast') {
+    const found = findMaxAddedAtNode(next.root)
+    if (!found) return state
+    found.parent.children.splice(found.idx, 1)
+    const v = validateTreeLimits(next)
+    return v.ok ? next : state
+  }
+
+  let mutated = false
+
+  function apply(group: FilterGroup): boolean {
+    switch (action.type) {
+      case 'addRule':
+        if (group.id === action.groupId) {
+          group.children.push(emptyRule(action.defaultField, action.defaultOperator))
+          return true
+        }
+        break
+      case 'addGroup':
+        if (group.id === action.groupId) {
+          group.children.push(emptyGroup(action.defaultField, action.defaultOperator))
+          return true
+        }
+        break
+      case 'updateGroupCombinator':
+        if (group.id === action.groupId) {
+          group.combinator = action.combinator
+          return true
+        }
+        break
+      case 'removeNode': {
+        const idx = group.children.findIndex((c) => c.id === action.nodeId)
+        if (idx >= 0) {
+          group.children.splice(idx, 1)
+          return true
+        }
+        break
+      }
+      case 'updateRule':
+        for (const c of group.children) {
+          if (c.type === 'rule' && c.id === action.ruleId) {
+            Object.assign(c, action.updates)
+            return true
+          }
+        }
+        break
+      case 'reorderChildren':
+        if (group.id === action.groupId) {
+          const arr = group.children
+          if (
+            action.fromIdx >= 0 &&
+            action.fromIdx < arr.length &&
+            action.toIdx >= 0 &&
+            action.toIdx < arr.length &&
+            action.fromIdx !== action.toIdx
+          ) {
+            const [moved] = arr.splice(action.fromIdx, 1)
+            arr.splice(action.toIdx, 0, moved)
+            return true
+          }
+        }
+        break
+    }
+    for (const c of group.children) {
+      if (c.type === 'group' && apply(c)) return true
+    }
+    return false
+  }
+
+  mutated = apply(next.root)
+  if (!mutated) return state
+
+  const v = validateTreeLimits(next)
+  if (!v.ok) return state // reject by returning original (caller can show a tooltip)
+  return next
+}
+
+export function canAddRule(tree: AdvancedFilterTree, groupId: string): boolean {
+  const found = findGroupAndDepth(tree.root, groupId)
+  if (!found) return false
+  if (found.group.children.length >= TREE_LIMITS.maxChildrenPerGroup) return false
+  if (countRules(tree.root) >= TREE_LIMITS.maxTotalRules) return false
+  return true
+}
+
+export function canAddGroup(tree: AdvancedFilterTree, groupId: string): boolean {
+  const found = findGroupAndDepth(tree.root, groupId)
+  if (!found) return false
+  if (found.group.children.length >= TREE_LIMITS.maxChildrenPerGroup) return false
+  if (found.depth >= TREE_LIMITS.maxGroupLevel) return false
+  if (countRules(tree.root) >= TREE_LIMITS.maxTotalRules) return false
+  return true
+}
+
+export function getGroupDepth(tree: AdvancedFilterTree, groupId: string): number | null {
+  const found = findGroupAndDepth(tree.root, groupId)
+  return found?.depth ?? null
+}