@svgrid/grid 2.6.3 → 2.6.5

package/src/grid-messages.ts

@@ -39,6 +39,17 @@ export type GridMessages = {
   total: string
   rowsSuffix: string
   rowSuffix: string
+  // Screen-reader announcements. Unlike the labels above these are whole
+  // sentences, so they take `{placeholders}` - a translator needs to control
+  // word order, which assembling atoms in English order does not allow.
+  announceFilterResults: string
+  announceNoMatches: string
+  announceFiltersCleared: string
+  announceRowsSelected: string
+  announceSelectionCleared: string
+  // Advanced-filter toolbar chip
+  advancedFilterActive: string
+  advancedFilterClear: string
   // Filter operator labels (mirror filterOperatorOptions ids)
   opContains: string
   opNotContains: string
@@ -97,6 +108,13 @@ export const defaultGridMessages: GridMessages = {
   total: 'Total',
   rowsSuffix: 'rows',
   rowSuffix: 'row',
+  announceFilterResults: '{visible} of {total} rows match the current filters',
+  announceNoMatches: 'No rows match the current filters',
+  announceFiltersCleared: 'Filters cleared, showing all {total} rows',
+  announceRowsSelected: '{count} rows selected',
+  announceSelectionCleared: 'Selection cleared',
+  advancedFilterActive: 'Advanced filter',
+  advancedFilterClear: 'Clear advanced filter',
   menuCopy: 'Copy',
   menuCut: 'Cut',
   menuPaste: 'Paste',

package/src/index.ts

@@ -709,6 +709,34 @@ export {
   type ExcelFilterOperator,
   type ExcelFilterOptions,
 } from './filtering/excel-filters'
+export {
+  ALL_FILTER_OPERATORS,
+  SET_OPERATOR_IDS,
+  VALUELESS_OPERATOR_IDS,
+  RANGE_OPERATOR_IDS,
+  isSetOperator,
+  isValuelessOperator,
+  isRangeOperator,
+  type FilterValueType,
+} from './filtering/filter-operator-catalogue'
+export { applyRowPredicate } from './filtering/row-predicate'
+export type {
+  GridPredicateExpr,
+  GridScalarExpr,
+  GridComparisonOp,
+  GridArithmeticOp,
+  GridAggFn,
+} from './filtering/predicate-expr'
+// Advanced-filter seam: enterprise registers the compiler, the grid owns the
+// state and the pipeline slot.
+export {
+  registerAdvancedFilterEngine,
+  getAdvancedFilterEngine,
+  hasAdvancedFilterEngine,
+  type AdvancedFilterEngine,
+  type AdvancedFilterCompileContext,
+  type CompiledRowPredicate,
+} from './advanced-filter.svelte'
 export {
   getGridCellDomId,
   getGridCellA11yProps,

package/src/server-data-source.test.ts

@@ -287,3 +287,97 @@ describe('createServerDataSource optimistic mutations', () => {
     expect(src.getRows).toHaveBeenCalledTimes(2)
   })
 })
+
+describe('advanced-filter expression contract', () => {
+  const EXPR = { kind: 'cmp', column: 'id', op: 'greaterThan', value: '5' } as never
+
+  /** A source that reports whether it honoured the expression. */
+  function exprSource(ack: boolean | undefined) {
+    const seen: unknown[] = []
+    const source: ServerDataSource<Row> = {
+      async getRows(req) {
+        seen.push(req.filterModel.expression)
+        return {
+          rows: [{ id: 1 }],
+          rowCount: 1,
+          ...(ack === undefined ? {} : { appliedExpression: ack }),
+        }
+      },
+    }
+    return { source, seen }
+  }
+
+  it('forwards the expression to the source', async () => {
+    const { source, seen } = exprSource(true)
+    const ctl = createServerDataSource(source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    expect(seen.at(-1)).toEqual(EXPR)
+  })
+
+  it('is satisfied when the source acknowledges applying it', async () => {
+    const ctl = createServerDataSource(exprSource(true).source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    expect(ctl.getState().expressionUnapplied).toBe(false)
+  })
+
+  it('flags an unapplied expression when the ack is missing', async () => {
+    const ctl = createServerDataSource(exprSource(undefined).source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    // The rows look perfectly normal, which is exactly why this has to be
+    // surfaced rather than inferred by the user.
+    expect(ctl.getState().expressionUnapplied).toBe(true)
+  })
+
+  it('flags it when the source explicitly declines', async () => {
+    const ctl = createServerDataSource(exprSource(false).source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    expect(ctl.getState().expressionUnapplied).toBe(true)
+  })
+
+  it('does NOT client-filter the loaded page as a fallback', async () => {
+    const ctl = createServerDataSource(exprSource(undefined).source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    // id 1 fails `id > 5`. Filtering here would turn "1 of 1,000,000 match"
+    // into a confident lie and make paging incoherent, so the row survives and
+    // the flag carries the truth instead.
+    expect(ctl.getState().rows).toEqual([{ id: 1 }])
+  })
+
+  it('warns once, not on every fetch', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const ctl = createServerDataSource(exprSource(undefined).source, { pageSize: 10, onChange: () => {} })
+      ctl.setFilter({ expression: EXPR })
+      await flush()
+      ctl.refresh()
+      await flush()
+      ctl.refresh()
+      await flush()
+      expect(warn).toHaveBeenCalledTimes(1)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('stays clear when no expression is in play', async () => {
+    const ctl = createServerDataSource(exprSource(undefined).source, { pageSize: 10, onChange: () => {} })
+    ctl.refresh()
+    await flush()
+    expect(ctl.getState().expressionUnapplied).toBe(false)
+  })
+
+  it('clears the flag once the expression is removed', async () => {
+    const ctl = createServerDataSource(exprSource(undefined).source, { pageSize: 10, onChange: () => {} })
+    ctl.setFilter({ expression: EXPR })
+    await flush()
+    expect(ctl.getState().expressionUnapplied).toBe(true)
+    ctl.setFilter({})
+    await flush()
+    expect(ctl.getState().expressionUnapplied).toBe(false)
+  })
+})

package/src/server-data-source.ts

@@ -15,6 +15,8 @@
  * non-optimistic for now - the grid reflects a change only after the
  * follow-up re-fetch of the current page lands.
  */
+import type { GridPredicateExpr } from './filtering/predicate-expr'
+
 export type ServerSortModel = Array<{ id: string; desc: boolean }>
 
 export type ServerFilterModel = {
@@ -29,6 +31,24 @@ export type ServerFilterModel = {
     string,
     { operator: string; value: string; valueTo?: string; selectedValues?: string[] }
   >
+  /**
+   * Advanced-filter predicate (Pro), as a JSON AST. Expresses what `columns`
+   * cannot: OR across columns, nesting, negation, two conditions on one
+   * column, cross-column comparison, and aggregates.
+   *
+   * CONTRACT - all or nothing. A backend that receives this MUST either:
+   *
+   *   (a) translate the WHOLE expression into its query, make `rowCount`
+   *       reflect it, and set `appliedExpression: true` on the result; or
+   *   (b) apply none of it and leave `appliedExpression` unset.
+   *
+   * Partial application is a contract violation, not a degraded mode: it
+   * returns a SUPERSET of the requested rows while the UI says the filter is
+   * on. That is strictly worse than not filtering, because nothing about the
+   * result looks wrong. When the ack is missing the grid says so rather than
+   * filtering the loaded page itself - see `ServerState.expressionUnapplied`.
+   */
+  expression?: GridPredicateExpr
 }
 
 /** A value column to roll up per group. */
@@ -144,6 +164,12 @@ export type ServerResult<TData> = {
   rows: ReadonlyArray<TData>
   /** Total row count after filtering (for the pager). */
   rowCount: number
+  /**
+   * Set `true` ONLY when `filterModel.expression` was applied in full. Leave it
+   * unset if you ignored the expression; the grid then warns rather than
+   * pretending the filter ran. See the contract on `ServerFilterModel.expression`.
+   */
+  appliedExpression?: boolean
 }
 
 export type ServerDataSource<TData> = {
@@ -171,6 +197,15 @@ export type ServerState<TData> = {
   pageCount: number
   sortModel: ServerSortModel
   filterModel: ServerFilterModel
+  /**
+   * True when an advanced-filter expression was sent but the source did not
+   * acknowledge applying it - so `rows` is unfiltered and the UI should say so.
+   * Surface this rather than hiding it: the rows look perfectly normal.
+   *
+   * Optional so existing code that builds a `ServerState` literal keeps
+   * compiling; the controller always sets it.
+   */
+  expressionUnapplied?: boolean
 }
 
 export type ServerController<TData> = {
@@ -232,12 +267,16 @@ export function createServerDataSource<TData>(
     pageCount: 1,
     sortModel: [],
     filterModel: {},
+    expressionUnapplied: false,
   }
 
   // Monotonic request id: only the latest fetch is allowed to land, so a slow
   // response for an old sort/filter can't clobber a newer one.
   let requestSeq = 0
   let disposed = false
+  // Once per controller: a misconfigured backend would otherwise log on every
+  // page, scroll and filter change.
+  let warnedExpressionUnapplied = false
 
   const emit = () => {
     state.pageCount = Math.max(1, Math.ceil(state.total / state.pageSize))
@@ -267,6 +306,23 @@ export function createServerDataSource<TData>(
       if (disposed || id !== requestSeq) return // stale
       state.rows = result.rows
       state.total = result.rowCount
+      // An expression was sent but the backend did not acknowledge applying it,
+      // so these rows are a SUPERSET of what was asked for. Say so instead of
+      // filtering the loaded page here: filtering one page would turn
+      // "3 of 1,000,000 match" into a confident lie and make paging incoherent,
+      // since page 2 would re-filter a different slice.
+      state.expressionUnapplied =
+        state.filterModel.expression != null && result.appliedExpression !== true
+      if (state.expressionUnapplied && !warnedExpressionUnapplied) {
+        warnedExpressionUnapplied = true
+        console.warn(
+          '[svgrid] The data source was sent filterModel.expression but did not ' +
+            'return `appliedExpression: true`, so the advanced filter is NOT applied ' +
+            'and the rows shown are unfiltered. Apply the whole expression and ' +
+            'acknowledge it, or clear the advanced filter. ' +
+            'See https://svgrid.com/docs/help/server/server-filtering',
+        )
+      }
       state.loading = false
       emit()
     } catch (err) {

package/src/svgrid-wrapper.types.ts

@@ -4,6 +4,7 @@
 import type { FilterOperator, Props } from './SvGrid.types'
 import type { GridExportOptions, GridClipboardOptions } from './export-format'
 import type { ChartSpec, ChartType } from './chart'
+import type { GridPredicateExpr } from './filtering/predicate-expr'
 
 // Aliased to the core union rather than restated: the API surfaces below hand
 // back whatever the grid actually filtered with, so a hand-maintained subset
@@ -33,6 +34,13 @@ export type SvGridViewState = {
   >
   /** Facet (Excel-style value checklist) selections, keyed by column id. */
   facetFilters: Record<string, string[]>
+  /**
+   * Advanced-filter expression (Pro). OPTIONAL, and omitted entirely when no
+   * advanced filter is set - so views saved before this feature existed, and
+   * views from grids that never use it, round-trip byte-identical. An explicit
+   * `null` clears the filter on `setState`.
+   */
+  advancedFilter?: GridPredicateExpr | null
   /** Built-in chart panel state (present only when `charting` is on): the
    *  ACTIVE chart, for back-compat + spread-and-tweak. */
   chart?: {
@@ -250,10 +258,25 @@ export type SvGridApi<
    */
   refreshEditorOptions(columnId?: string): void
   /**
-   * Clear every active column filter (menu, filter-row, set-list, and global).
-   * Resets the grid to "no filtering" in a single call.
+   * Clear every active column filter (menu, filter-row, set-list, global, and
+   * the advanced filter). Resets the grid to "no filtering" in a single call.
    */
   clearAllFilters(): void
+  /**
+   * Set the advanced-filter expression (Pro). `null` clears it. Composed with
+   * AND after the global, column and facet filters.
+   *
+   * Rows are only removed once `@svgrid/enterprise`'s `enableAdvancedFilter()`
+   * has registered a compiler. Without it the expression is stored but nothing
+   * is filtered - use `isAdvancedFilterActive()` to tell the two apart.
+   */
+  setAdvancedFilter(expr: GridPredicateExpr | null): void
+  /** The current advanced-filter expression, or `null`. */
+  getAdvancedFilter(): GridPredicateExpr | null
+  /** Clear the advanced filter, leaving other filter surfaces untouched. */
+  clearAdvancedFilter(): void
+  /** Whether an expression is set AND an engine is registered to run it. */
+  isAdvancedFilterActive(): boolean
   /**
    * Read the active column-menu filters as a snapshot. Keyed by column id.
    * Returns an empty object when nothing is filtered. `valueTo` is only
@@ -265,9 +288,15 @@ export type SvGridApi<
   >
 
   /**
-   * Snapshot of the rows the grid is actually displaying right now -
-   * after filtering, sorting, grouping, and pagination have been applied.
-   * Use this when you need to export the visible result set (e.g. CSV).
+   * Snapshot of the DATA rows the grid is displaying right now - after
+   * filtering, sorting, grouping and pagination. Use this when you need the
+   * visible result set (e.g. to export it as CSV).
+   *
+   * Group banner rows are not included: the return type is `TData`, and a
+   * banner is not one of your rows. That matters while grouping is on, because
+   * with every group collapsed this returns an EMPTY array even though the
+   * grid visibly shows a banner per group. Count banners from `getState()`
+   * rather than from the length of this.
    */
   getDisplayedRows(): ReadonlyArray<TData>
 
@@ -290,6 +319,9 @@ export type SvGridApi<
     format?: CellFormatConfig
     /** Effective horizontal alignment ('left' | 'center' | 'right'). */
     align?: 'left' | 'center' | 'right'
+    /** The column's declared `editorType`, when set. Lets a filter or
+     *  expression UI offer type-appropriate operators. */
+    editorType?: string
   }>
 
   // ----- Free data export (CSV / TSV / JSON + clipboard) -----