@svgrid/grid 2.6.3 → 2.6.5

package/src/a11y.axe.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Accessibility tests that run axe-core against a REAL rendered grid.
+ *
+ * The other a11y tests in this package (`a11y.test.ts`, `a11y.contract.test.ts`)
+ * check the ARIA prop builders in isolation, against strings. Useful, but they
+ * cannot catch a violation that only exists once the component is assembled:
+ * a duplicated id, a control with no accessible name, a role nested somewhere
+ * it is not allowed. This file mounts `<SvGrid>` and audits the resulting DOM.
+ *
+ * It runs in the normal vitest suite - which means it runs in CI. The Playwright
+ * e2e suite cannot, because it depends on the private `website/` submodule.
+ *
+ * jsdom limitation, stated rather than hidden: jsdom performs no layout, so
+ * every geometry-dependent rule is meaningless here and is disabled below. The
+ * important one is `color-contrast`, which needs real painting. Contrast is a
+ * property of a theme, not of grid markup, and the guidance for verifying it
+ * against your own theme lives in docs/help/accessibility.md. What this file
+ * does cover is the structural half: roles, names, relationships, and ids.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import axe from 'axe-core'
+import SvGrid from './SvGrid.svelte'
+import {
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+} from './index'
+import type { ColumnDef } from './index'
+
+type Row = { id: string; name: string; team: string; score: number }
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+})
+
+const sortFns = {} as never
+
+const rows: Row[] = [
+  { id: 'r1', name: 'Ada Lovelace', team: 'Platform', score: 91 },
+  { id: 'r2', name: 'Grace Hopper', team: 'Compilers', score: 88 },
+  { id: 'r3', name: 'Karen Sparck Jones', team: 'Search', score: 95 },
+  { id: 'r4', name: 'Barbara Liskov', team: 'Platform', score: 93 },
+]
+
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 200 },
+  { field: 'team', header: 'Team', width: 140 },
+  { field: 'score', header: 'Score', width: 100, align: 'right' },
+]
+
+/**
+ * Rules that depend on layout or painting. jsdom gives every element zero size
+ * and no computed colour, so these produce noise rather than signal.
+ */
+const LAYOUT_DEPENDENT_RULES = [
+  'color-contrast',
+  'scrollable-region-focusable',
+  'target-size',
+]
+
+function mountGrid(extraProps: Record<string, unknown> = {}) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data: rows,
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+      },
+      containerHeight: 300,
+      virtualization: false,
+      columnVirtualization: false,
+      ...extraProps,
+    } as never,
+  })
+  return {
+    target,
+    destroy: () => {
+      unmount(app)
+      target.remove()
+    },
+  }
+}
+
+async function auditGrid(props: Record<string, unknown> = {}) {
+  const { target, destroy } = mountGrid(props)
+  try {
+    // Let the grid settle (row model + effects) before auditing.
+    await new Promise((r) => setTimeout(r, 0))
+    const results = await axe.run(target, {
+      rules: Object.fromEntries(LAYOUT_DEPENDENT_RULES.map((id) => [id, { enabled: false }])),
+    })
+    return results.violations.map((v) => ({
+      id: v.id,
+      impact: v.impact,
+      help: v.help,
+      nodes: v.nodes.map((n) => n.html).slice(0, 3),
+    }))
+  } finally {
+    destroy()
+  }
+}
+
+describe('axe audit of a rendered grid', () => {
+  it('reports no violations for a plain grid', async () => {
+    expect(await auditGrid()).toEqual([])
+  })
+
+  it('reports no violations with the filter row and global filter shown', async () => {
+    expect(
+      await auditGrid({ showColumnFilters: true, showFilterRow: true, showGlobalFilter: true }),
+    ).toEqual([])
+  })
+
+  it('reports no violations with row selection enabled', async () => {
+    expect(await auditGrid({ showRowSelection: true })).toEqual([])
+  })
+
+  it('reports no violations with pagination shown', async () => {
+    expect(await auditGrid({ showPagination: true, pageSize: 2 })).toEqual([])
+  })
+
+  it('actually audits something - the grid role is present in the tree', async () => {
+    // Guards against the audit silently passing because nothing rendered.
+    const { target, destroy } = mountGrid()
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      expect(target.querySelector('[role="grid"], table')).not.toBeNull()
+    } finally {
+      destroy()
+    }
+  })
+})
+
+describe('validation is exposed to assistive technology', () => {
+  // `validate` used to mark a bad cell with a red class and a `title` only.
+  // Both are visual: the class carries no semantics at all, and `title` is
+  // unreliably surfaced and unreachable by keyboard. A screen-reader user had
+  // no way to know the cell was rejected, which is WCAG 3.3.1.
+  const validatedCols: ColumnDef<typeof features, Row>[] = [
+    { field: 'name', header: 'Name', width: 200 },
+    {
+      field: 'score',
+      header: 'Score',
+      width: 100,
+      validate: ({ value }) => (Number(value) < 90 ? 'Score must be at least 90' : null),
+    },
+  ]
+
+  it('marks an invalid cell with aria-invalid and keeps the message', async () => {
+    const { target, destroy } = mountGrid({ columns: validatedCols })
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      const invalid = [...target.querySelectorAll('td[aria-invalid="true"]')]
+      // Grace 88 fails, Ada 91 / Karen 95 / Barbara 93 pass.
+      expect(invalid).toHaveLength(1)
+      // The reason must reach assistive tech, not just the hover tooltip:
+      // either as the accessible description (`title`) or as visually-hidden
+      // text read with the cell. Which one depends on the render path.
+      const reason =
+        invalid[0]?.getAttribute('title') ??
+        invalid[0]?.querySelector('.sv-grid-sr-only')?.textContent
+      expect(reason).toBe('Score must be at least 90')
+    } finally {
+      destroy()
+    }
+  })
+
+  it('leaves valid cells unmarked', async () => {
+    const { target, destroy } = mountGrid({ columns: validatedCols })
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      expect(target.querySelectorAll('td[aria-invalid]')).toHaveLength(1)
+    } finally {
+      destroy()
+    }
+  })
+
+  it('passes axe with an invalid cell rendered', async () => {
+    expect(await auditGrid({ columns: validatedCols })).toEqual([])
+  })
+})

package/src/advanced-filter.svelte.ts

@@ -0,0 +1,59 @@
+/**
+ * Registration seam for the advanced filter (a `@svgrid/enterprise` feature).
+ *
+ * The grid owns the state and the pipeline slot; enterprise owns the compiler.
+ * Same shape as `pivot-view.svelte.ts`: a module-level `$state` holder with a
+ * register / get / has triple, so the free package carries no commercial code.
+ */
+import type { GridPredicateExpr } from './filtering/predicate-expr'
+
+/** What the engine needs in order to compile an expression into a predicate. */
+export type AdvancedFilterCompileContext<TRow> = {
+  /**
+   * Resolve a column id to its cell value for a row. The grid passes the same
+   * accessor the column-menu filter stage uses, so a `cmp` on a `fieldFn` or
+   * value-getter column resolves identically in both.
+   */
+  getValue: (row: TRow, columnId: string) => unknown
+  /** Locale for text folding, matching the column filters. */
+  locale?: string | ReadonlyArray<string>
+  /**
+   * The rows entering this stage. Aggregates (`SUM(amount) > 1000`) are folded
+   * over exactly these, once, so they see the rows the user is currently
+   * looking at rather than the raw dataset.
+   */
+  rows: ReadonlyArray<TRow>
+}
+
+/** A compiled expression: cheap to call once per row. */
+export type CompiledRowPredicate<TRow> = (row: TRow) => boolean
+
+/**
+ * Compile an expression to a row predicate.
+ *
+ * Returns `null` when the expression cannot be compiled (an unknown node kind,
+ * an unresolvable column). Must never throw: the grid treats both `null` and a
+ * thrown error as "do not filter", because a half-applied filter silently
+ * showing the wrong rows is worse than an unapplied one.
+ */
+export type AdvancedFilterEngine = <TRow>(
+  expr: GridPredicateExpr,
+  ctx: AdvancedFilterCompileContext<TRow>,
+) => CompiledRowPredicate<TRow> | null
+
+let engine = $state<AdvancedFilterEngine | null>(null)
+
+/** Register the engine. Enterprise calls this from `enableAdvancedFilter()`. */
+export function registerAdvancedFilterEngine(fn: AdvancedFilterEngine | null): void {
+  engine = fn
+}
+
+/** The registered engine, or null when enterprise is not installed. */
+export function getAdvancedFilterEngine(): AdvancedFilterEngine | null {
+  return engine
+}
+
+/** Whether an advanced-filter engine has been registered. */
+export function hasAdvancedFilterEngine(): boolean {
+  return engine != null
+}

package/src/build-api.ts

@@ -25,6 +25,7 @@ import {
   getColumnAlign,
   columnDefMatchesId,
 } from "./cell-values";
+import { hasAdvancedFilterEngine } from "./advanced-filter.svelte";
 
 export function createGridApi<
   TFeatures extends TableFeatures = TableFeatures,
@@ -369,13 +370,33 @@ export function createGridApi<
         // See `setFilter` for why the read-modify-write is untracked.
         untrack(() => {
           // Wipe every filter surface in one go: column-menu, filter-row, set
-          // filters, and the global search box.
+          // filters, the global search box, and the advanced filter. This
+          // promises "every filter surface", so leaving the advanced one set
+          // would strand rows nobody can see a cause for.
           ctx.filterMenuValues = {};
           ctx.filterRowValues = {};
           ctx.valueFilters = {};
           if (ctx.globalFilter !== "") ctx.globalFilter = "";
+          if (ctx.advancedFilter !== null) ctx.advancedFilter = null;
         });
       },
+      setAdvancedFilter(expr) {
+        // See `setFilter` for why the write is untracked.
+        untrack(() => {
+          ctx.advancedFilter = expr ?? null;
+        });
+      },
+      getAdvancedFilter() {
+        return ctx.advancedFilter ?? null;
+      },
+      clearAdvancedFilter() {
+        untrack(() => {
+          ctx.advancedFilter = null;
+        });
+      },
+      isAdvancedFilterActive() {
+        return ctx.advancedFilter != null && hasAdvancedFilterEngine();
+      },
       getFilters() {
         // Return a defensive copy so callers can't mutate internal state.
         const out: Record<
@@ -397,9 +418,14 @@ export function createGridApi<
         // `allRows` is the final, post-filter, post-sort, post-group,
         // post-pagination list - exactly what the body renders. Skip group
         // header rows (they wrap an aggregate, not a TData row).
+        //
+        // `isGroupRow` rather than a `subRows.length` test: a TREE parent also
+        // has subRows, but it is a real data row that renders its own cells, so
+        // dropping it here silently truncated every tree read - including the
+        // enterprise export, whose default row source is this method.
         const out: TData[] = [];
         for (const row of ctx.allRows) {
-          if (row.subRows && row.subRows.length > 0) continue;
+          if (isGroupRow(row)) continue;
           out.push(row.original as TData);
         }
         return out;
@@ -428,6 +454,10 @@ export function createGridApi<
           // editorType-based default the body uses.
           format: c.columnDef.format,
           align: getColumnAlign(c),
+          // The column's declared value type. Lets a filter or expression UI
+          // offer the right operators (numeric ranges vs text matching) without
+          // re-walking the columnDef tree.
+          editorType: (c.columnDef as { editorType?: string }).editorType,
         });
         // Visible columns first, in their current visual order...
         const out = ctx.allColumns.map((c: any) => describe(c, true));
@@ -721,6 +751,11 @@ export function createGridApi<
               Array.from(set),
             ]),
           ),
+          // Emitted only when set. `attachAutoSavedView` diffs
+          // JSON.stringify(getState()) on a timer, so adding an always-present
+          // key would change every existing snapshot and force one spurious
+          // save in every app on upgrade.
+          ...(ctx.advancedFilter ? { advancedFilter: ctx.advancedFilter } : {}),
           ...(ctx.chartingEnabled
             ? {
                 chart: {
@@ -777,6 +812,12 @@ export function createGridApi<
             next[k] = new Set(arr);
           ctx.valueFilters = next;
         }
+        // `in` rather than a truthiness check, so an explicit null clears while
+        // an absent key leaves the current filter alone (the documented
+        // "only the keys present are applied" contract).
+        if ("advancedFilter" in state) {
+          ctx.advancedFilter = state.advancedFilter ?? null;
+        }
         if ((state.chart || state.charts) && ctx.chartingEnabled) {
           if (Array.isArray(state.charts) && state.charts.length) {
             ctx.applyChartsState(state.charts, state.chartActive);

package/src/filter-operators.ts

@@ -3,6 +3,10 @@
 // so it lives outside the controller.
 import type { Column, RowData } from "./index";
 import type { FilterOperator, FilterOption } from "./SvGrid.types";
+import {
+  SET_OPERATOR_IDS,
+  VALUELESS_OPERATOR_IDS,
+} from "./filtering/filter-operator-catalogue";
 
 export const filterOperatorOptions: Array<FilterOption> = [
   { value: "contains", label: "Contains", iconName: "op-contains" },
@@ -22,13 +26,12 @@ export const filterOperatorOptions: Array<FilterOption> = [
 ];
 /** Operators whose predicate is a set-membership test over a token list.
  *  The filter row renders a multi-value chip input for these instead of a
- *  single text box. */
-export const SET_OPERATORS: ReadonlyArray<FilterOperator> = ["in", "notIn"];
+ *  single text box. Sourced from the shared catalogue so the grid and the
+ *  expression editor cannot disagree about which control to render. */
+export const SET_OPERATORS: ReadonlyArray<FilterOperator> = SET_OPERATOR_IDS;
 /** Operators that need no value input - they act on emptiness alone. */
-export const VALUELESS_OPERATORS: ReadonlyArray<FilterOperator> = [
-  "isBlank",
-  "isNotBlank",
-];
+export const VALUELESS_OPERATORS: ReadonlyArray<FilterOperator> =
+  VALUELESS_OPERATOR_IDS;
 /** Which operators make sense for each column editor type. */
 export const TEXT_OPERATORS: Array<FilterOperator> = [
   "contains",

package/src/filtering/excel-filters.ts

@@ -159,6 +159,21 @@ function scanInTokens(value: unknown): { tokens: string[]; trailing: string } {
   return { tokens, trailing: take() }
 }
 
+// Re-exported here so consumers can reach the catalogue through the
+// `@svgrid/grid/filtering` subpath. Importing it from the package root would
+// pull in SvGrid.svelte, which is a runtime cost (and a bundler hazard) for
+// anything that only wants operator semantics.
+export {
+  ALL_FILTER_OPERATORS,
+  SET_OPERATOR_IDS,
+  VALUELESS_OPERATOR_IDS,
+  RANGE_OPERATOR_IDS,
+  isSetOperator,
+  isValuelessOperator,
+  isRangeOperator,
+  type FilterValueType,
+} from './filter-operator-catalogue.js'
+
 /** A filter with its needle-side work already done. Call per row. */
 export type CompiledExcelFilter = (cellValue: unknown) => boolean
 

package/src/filtering/filter-operator-catalogue.ts

@@ -0,0 +1,74 @@
+/**
+ * The canonical filter-operator catalogue: which operators exist, and the
+ * semantics every surface must agree on.
+ *
+ * Deliberately narrow. Two things live here:
+ *
+ *   1. `ALL_FILTER_OPERATORS` - the operator identity list, so a new operator
+ *      cannot be added to one surface and silently missed by another.
+ *   2. The input-shape predicates - whether an operator takes no value, a
+ *      token list, or a second value. Get these wrong and a filter UI renders
+ *      the wrong control, so they cannot be allowed to diverge.
+ *
+ * What deliberately does NOT live here: labels, ordering, and which operators
+ * a given column type offers. Those are presentation choices that legitimately
+ * differ per surface - the grid's filter menu leads with "Contains" for text
+ * while the expression editor leads with "Equals", and both are right for
+ * their context.
+ *
+ * Zero imports beyond the operator union, so any package can consume this
+ * without pulling in the grid's type graph.
+ */
+import type { ExcelFilterOperator } from './excel-filters.js'
+
+/** Coarse value type used to decide which operators a column offers. */
+export type FilterValueType = 'text' | 'number' | 'date' | 'datetime' | 'boolean'
+
+/**
+ * Every filter operator, in the grid's filter-menu order. Any surface that
+ * presents operators should be able to account for all of these.
+ */
+export const ALL_FILTER_OPERATORS: ReadonlyArray<ExcelFilterOperator> = [
+  'contains',
+  'notContains',
+  'equals',
+  'notEquals',
+  'startsWith',
+  'endsWith',
+  'regex',
+  'in',
+  'notIn',
+  'greaterThan',
+  'lessThan',
+  'between',
+  'isBlank',
+  'isNotBlank',
+]
+
+/** Operators whose predicate is a set-membership test over a token list.
+ *  A filter UI renders a multi-value chip input for these. */
+export const SET_OPERATOR_IDS: ReadonlyArray<ExcelFilterOperator> = ['in', 'notIn']
+
+/** Operators that need no value input - they act on emptiness alone. */
+export const VALUELESS_OPERATOR_IDS: ReadonlyArray<ExcelFilterOperator> = [
+  'isBlank',
+  'isNotBlank',
+]
+
+/** Operators that need a second value (`valueTo`). */
+export const RANGE_OPERATOR_IDS: ReadonlyArray<ExcelFilterOperator> = ['between']
+
+/** Whether an operator takes a multi-value token list. */
+export function isSetOperator(op: ExcelFilterOperator): boolean {
+  return SET_OPERATOR_IDS.includes(op)
+}
+
+/** Whether an operator needs no value input. */
+export function isValuelessOperator(op: ExcelFilterOperator): boolean {
+  return VALUELESS_OPERATOR_IDS.includes(op)
+}
+
+/** Whether an operator needs a second (`valueTo`) value. */
+export function isRangeOperator(op: ExcelFilterOperator): boolean {
+  return RANGE_OPERATOR_IDS.includes(op)
+}

package/src/filtering/node-entry.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * `@svgrid/grid/filtering` is one of the few entry points consumed by RAW NODE
+ * rather than by a bundler: @svgrid/enterprise's Studio bundle keeps
+ * `@svgrid/grid` external, so the published dist is imported by Node's own ESM
+ * resolver at runtime.
+ *
+ * Node ESM does not guess extensions. The rest of the package can use
+ * extensionless relative imports because a bundler resolves them; anything
+ * reachable from this entry cannot. `import './x'` works in Vite and throws
+ * ERR_MODULE_NOT_FOUND under Node.
+ *
+ * This was not hypothetical. Splitting the operator catalogue out of
+ * `excel-filters.ts` gave that file its first relative import and broke every
+ * generated Studio app at startup. Only `pnpm verify:app` caught it, after the
+ * change was committed.
+ *
+ * The rule enforced here is deliberately blunt - EVERY relative specifier in
+ * this folder ends in `.js`, type-only ones included. Type imports are erased
+ * and would be safe either way, but exempting them means parsing TypeScript to
+ * decide which is which, and a subtle parser in a guard test is how the guard
+ * silently stops guarding. TypeScript resolves `./excel-filters.js` to
+ * `excel-filters.ts` regardless, so the strict rule costs nothing.
+ */
+
+const DIR = import.meta.dirname
+
+/** Every relative module specifier in the file, however it is imported. */
+function relativeSpecifiers(source: string): string[] {
+  const out: string[] = []
+  // Covers `from './x'`, bare `import './x'`, and dynamic `import('./x')`.
+  const re = /(?:from|import)\s*\(?\s*['"](\.[^'"]*)['"]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(source))) out.push(m[1]!)
+  return out
+}
+
+const files = readdirSync(DIR).filter(
+  (f) => f.endsWith('.ts') && !f.endsWith('.test.ts'),
+)
+
+describe('the /filtering entry stays resolvable by raw Node', () => {
+  it('finds the source files to check', () => {
+    // Guards against the directory read silently matching nothing, which would
+    // turn every case below into a vacuous pass.
+    expect(files.length).toBeGreaterThan(0)
+    expect(files).toContain('excel-filters.ts')
+  })
+
+  it.each(files)('%s gives every relative import a .js extension', (file) => {
+    const offenders = relativeSpecifiers(readFileSync(join(DIR, file), 'utf8')).filter(
+      (spec) => !spec.endsWith('.js'),
+    )
+    expect(
+      offenders,
+      `${file} imports ${offenders.join(', ')} without a .js extension. ` +
+        'Node cannot resolve that in the published dist, which breaks every ' +
+        'generated Studio app at startup. Add .js to the specifier.',
+    ).toEqual([])
+  })
+
+  it('detects a missing extension', () => {
+    // The guard has to be able to fail. Without this the regex could stop
+    // matching and every case above would pass for the wrong reason.
+    expect(relativeSpecifiers(`export { a } from './some-module'`)).toEqual([
+      './some-module',
+    ])
+    expect(relativeSpecifiers(`import './side-effect'`)).toEqual(['./side-effect'])
+    expect(relativeSpecifiers(`const m = await import('./lazy')`)).toEqual(['./lazy'])
+    expect(relativeSpecifiers(`import { a } from './ok.js'`)).toEqual(['./ok.js'])
+  })
+})

package/src/filtering/predicate-expr.ts

@@ -0,0 +1,50 @@
+/**
+ * The advanced-filter expression shape, as the free grid sees it.
+ *
+ * This is a structural mirror of `@svgrid/enterprise`'s `PredicateExpr`. It is
+ * written here, in MIT code, against the grid's own operator union - the same
+ * arrangement `GridPivotConfig` uses so the free package can type a commercial
+ * feature's payload without depending on the commercial package.
+ *
+ * The two definitions must stay assignable in both directions. A bidirectional
+ * assignability test in `@svgrid/enterprise` fails `pnpm test:types` the moment
+ * either side drifts, so this is a checked mirror rather than a hopeful one.
+ *
+ * The grid never interprets these nodes. It hands the whole expression to the
+ * engine registered via `registerAdvancedFilterEngine`, which compiles it. That
+ * keeps the evaluator, the parser and the editor commercial.
+ */
+import type { ExcelFilterOperator } from './excel-filters.js'
+
+/** Comparison operators available to a cross-column (`scalarCmp`) node. */
+export type GridComparisonOp = '=' | '!=' | '>' | '<' | '>=' | '<='
+
+/** Arithmetic operators available inside a scalar expression. */
+export type GridArithmeticOp = '+' | '-' | '*' | '/' | '%'
+
+/** Aggregate functions available inside a scalar expression. */
+export type GridAggFn = 'sum' | 'avg' | 'min' | 'max' | 'count'
+
+/** A value-producing expression: a column, a literal, or maths over them. */
+export type GridScalarExpr =
+  | { kind: 'col'; id: string }
+  | { kind: 'lit'; value: string | number | boolean | null }
+  | { kind: 'neg'; expr: GridScalarExpr }
+  | { kind: 'bin'; op: GridArithmeticOp; left: GridScalarExpr; right: GridScalarExpr }
+  | { kind: 'agg'; fn: GridAggFn; column: string }
+  | { kind: 'func'; name: string; args: GridScalarExpr[] }
+
+/**
+ * A boolean expression over a row.
+ *
+ * `cmp` is deliberately isomorphic to one column-menu filter condition: its
+ * `op` is the same `ExcelFilterOperator` the filter row uses, so a simple
+ * advanced filter and a column filter mean exactly the same thing.
+ */
+export type GridPredicateExpr =
+  | { kind: 'and'; parts: GridPredicateExpr[] }
+  | { kind: 'or'; parts: GridPredicateExpr[] }
+  | { kind: 'not'; expr: GridPredicateExpr }
+  | { kind: 'cmp'; column: string; op: ExcelFilterOperator; value?: unknown; valueTo?: unknown }
+  | { kind: 'scalarCmp'; left: GridScalarExpr; op: GridComparisonOp; right: GridScalarExpr }
+  | { kind: 'const'; value: boolean }

package/src/filtering/row-predicate.ts

@@ -0,0 +1,57 @@
+/**
+ * Apply a row predicate across a depth-ordered row list, keeping group banners
+ * consistent with what survives beneath them.
+ *
+ * The row list interleaves group banners with their descendants, banner first.
+ * A predicate written by a user is about DATA, so it is only tested against
+ * leaf rows; a banner then survives only if something under it did. Testing a
+ * banner directly would drop whole groups because its cells are aggregates, not
+ * row values.
+ *
+ * Note the existing column-filter and facet stages do test banners directly.
+ * That is a separate pre-existing inconsistency; this helper is written to be
+ * reusable if those are ever brought in line, but changing them is deliberately
+ * not bundled into the advanced filter.
+ */
+
+/** Apply `keep` to leaf rows, dropping banners left with no surviving child. */
+export function applyRowPredicate<TRow>(
+  rows: ReadonlyArray<TRow>,
+  keep: (row: TRow) => boolean,
+  isGroup: (row: TRow) => boolean,
+): TRow[] {
+  // Fast path: no grouping in play, so every row is a leaf.
+  let hasGroup = false
+  for (const row of rows) {
+    if (isGroup(row)) {
+      hasGroup = true
+      break
+    }
+  }
+  if (!hasGroup) return rows.filter(keep)
+
+  // One reverse pass. `survivorsBelow` counts leaves kept since we last closed
+  // out a banner, so a banner is kept when anything after it survived.
+  const keepFlags = new Array<boolean>(rows.length).fill(false)
+  let survivorsSinceBanner = 0
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const row = rows[i]!
+    if (isGroup(row)) {
+      if (survivorsSinceBanner > 0) {
+        keepFlags[i] = true
+        // The banner itself counts as surviving content for any banner above
+        // it, so nested groups keep their ancestors.
+        survivorsSinceBanner = 1
+      } else {
+        keepFlags[i] = false
+      }
+    } else if (keep(row)) {
+      keepFlags[i] = true
+      survivorsSinceBanner += 1
+    }
+  }
+
+  const out: TRow[] = []
+  for (let i = 0; i < rows.length; i += 1) if (keepFlags[i]) out.push(rows[i]!)
+  return out
+}