@svgrid/grid 2.6.3 → 2.6.4

package/src/filter-operators.ts

@@ -1,157 +1,160 @@
-// Filter-operator catalogue + the pure helpers that pick which operators
-// apply to a column and how they're labelled. Fully static - no grid state -
-// so it lives outside the controller.
-import type { Column, RowData } from "./index";
-import type { FilterOperator, FilterOption } from "./SvGrid.types";
-
-export const filterOperatorOptions: Array<FilterOption> = [
-  { value: "contains", label: "Contains", iconName: "op-contains" },
-  { value: "notContains", label: "Not contains", iconName: "op-notContains" },
-  { value: "equals", label: "Equals", iconName: "op-equals" },
-  { value: "notEquals", label: "Not equals", iconName: "op-notEquals" },
-  { value: "startsWith", label: "Starts with", iconName: "op-startsWith" },
-  { value: "endsWith", label: "Ends with", iconName: "op-endsWith" },
-  { value: "regex", label: "Regex", iconName: "op-regex" },
-  { value: "in", label: "In", iconName: "op-in" },
-  { value: "notIn", label: "Not in", iconName: "op-notIn" },
-  { value: "greaterThan", label: "Greater than", iconName: "op-greaterThan" },
-  { value: "lessThan", label: "Less than", iconName: "op-lessThan" },
-  { value: "between", label: "Between", iconName: "op-between" },
-  { value: "isBlank", label: "Blank", iconName: "op-isBlank" },
-  { value: "isNotBlank", label: "Not blank", iconName: "op-isNotBlank" },
-];
-/** 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"];
-/** Operators that need no value input - they act on emptiness alone. */
-export const VALUELESS_OPERATORS: ReadonlyArray<FilterOperator> = [
-  "isBlank",
-  "isNotBlank",
-];
-/** Which operators make sense for each column editor type. */
-export const TEXT_OPERATORS: Array<FilterOperator> = [
-  "contains",
-  "notContains",
-  "equals",
-  "notEquals",
-  "startsWith",
-  "endsWith",
-  "regex",
-  "in",
-  "notIn",
-  "isBlank",
-  "isNotBlank",
-];
-export const NUMBER_OPERATORS: Array<FilterOperator> = [
-  "equals",
-  "notEquals",
-  "greaterThan",
-  "lessThan",
-  "between",
-  "in",
-  "notIn",
-  "isBlank",
-  "isNotBlank",
-];
-export const DATE_OPERATORS: Array<FilterOperator> = [
-  "equals",
-  "notEquals",
-  "lessThan",
-  "greaterThan",
-  "between",
-  "isBlank",
-  "isNotBlank",
-];
-export const CHECKBOX_OPERATORS: Array<FilterOperator> = [
-  "equals",
-  "isBlank",
-  "isNotBlank",
-];
-export const fallbackOperatorOption: FilterOption = {
-  value: "contains",
-  label: "Contains",
-  iconName: "op-contains",
-};
-
-export function operatorOption(value: FilterOperator): FilterOption {
-  return (
-    filterOperatorOptions.find((option) => option.value === value) ??
-    fallbackOperatorOption
-  );
-}
-
-/** Returns the operators that make sense for the given column's data type. */
-export function operatorsForColumn<TData extends RowData>(
-  column: Column<TData> | undefined,
-): Array<FilterOption> {
-  const editorType = column?.columnDef.editorType ?? "text";
-  const ids =
-    editorType === "number"
-      ? NUMBER_OPERATORS
-      : editorType === "date" || editorType === "datetime"
-        ? DATE_OPERATORS
-        : editorType === "checkbox"
-          ? CHECKBOX_OPERATORS
-          : TEXT_OPERATORS;
-  return ids
-    .map((id) => filterOperatorOptions.find((option) => option.value === id))
-    .filter((option): option is FilterOption => Boolean(option));
-}
-
-/** Default operator for a column (first one valid for its type). */
-export function defaultOperatorFor<TData extends RowData>(
-  column: Column<TData> | undefined,
-): FilterOperator {
-  return operatorsForColumn(column)[0]?.value ?? "contains";
-}
-
-/** Date columns get friendlier labels for "less / greater than". */
-export function operatorLabelFor<TData extends RowData>(
-  option: FilterOption,
-  column: Column<TData> | undefined,
-): string {
-  const editorType = column?.columnDef.editorType;
-  if (editorType === "date" || editorType === "datetime") {
-    if (option.value === "lessThan") return "Before";
-    if (option.value === "greaterThan") return "After";
-  }
-  return option.label;
-}
-
-/** GridMessages key for each operator's label (see grid-messages.ts). */
-const OPERATOR_MESSAGE_KEY: Record<FilterOperator, string> = {
-  contains: "opContains",
-  notContains: "opNotContains",
-  equals: "opEquals",
-  notEquals: "opNotEquals",
-  startsWith: "opStartsWith",
-  endsWith: "opEndsWith",
-  regex: "opRegex",
-  in: "opIn",
-  notIn: "opNotIn",
-  greaterThan: "opGreaterThan",
-  lessThan: "opLessThan",
-  between: "opBetween",
-  isBlank: "opIsBlank",
-  isNotBlank: "opIsNotBlank",
-};
-
-/**
- * Localized operator label: honors date `Before`/`After` relabels, then the
- * `localeText` override for the operator, falling back to the English
- * `option.label`. `messages` is a loose string map to avoid a type cycle.
- */
-export function localizeOperatorLabel<TData extends RowData>(
-  option: FilterOption,
-  column: Column<TData> | undefined,
-  messages?: Record<string, string> | null,
-): string {
-  const editorType = column?.columnDef.editorType;
-  if (editorType === "date" || editorType === "datetime") {
-    if (option.value === "lessThan") return messages?.opBefore || "Before";
-    if (option.value === "greaterThan") return messages?.opAfter || "After";
-  }
-  const key = OPERATOR_MESSAGE_KEY[option.value];
-  return (key && messages?.[key]) || option.label;
-}
+// Filter-operator catalogue + the pure helpers that pick which operators
+// apply to a column and how they're labelled. Fully static - no grid state -
+// 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" },
+  { value: "notContains", label: "Not contains", iconName: "op-notContains" },
+  { value: "equals", label: "Equals", iconName: "op-equals" },
+  { value: "notEquals", label: "Not equals", iconName: "op-notEquals" },
+  { value: "startsWith", label: "Starts with", iconName: "op-startsWith" },
+  { value: "endsWith", label: "Ends with", iconName: "op-endsWith" },
+  { value: "regex", label: "Regex", iconName: "op-regex" },
+  { value: "in", label: "In", iconName: "op-in" },
+  { value: "notIn", label: "Not in", iconName: "op-notIn" },
+  { value: "greaterThan", label: "Greater than", iconName: "op-greaterThan" },
+  { value: "lessThan", label: "Less than", iconName: "op-lessThan" },
+  { value: "between", label: "Between", iconName: "op-between" },
+  { value: "isBlank", label: "Blank", iconName: "op-isBlank" },
+  { value: "isNotBlank", label: "Not blank", iconName: "op-isNotBlank" },
+];
+/** 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. 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> =
+  VALUELESS_OPERATOR_IDS;
+/** Which operators make sense for each column editor type. */
+export const TEXT_OPERATORS: Array<FilterOperator> = [
+  "contains",
+  "notContains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+  "regex",
+  "in",
+  "notIn",
+  "isBlank",
+  "isNotBlank",
+];
+export const NUMBER_OPERATORS: Array<FilterOperator> = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "lessThan",
+  "between",
+  "in",
+  "notIn",
+  "isBlank",
+  "isNotBlank",
+];
+export const DATE_OPERATORS: Array<FilterOperator> = [
+  "equals",
+  "notEquals",
+  "lessThan",
+  "greaterThan",
+  "between",
+  "isBlank",
+  "isNotBlank",
+];
+export const CHECKBOX_OPERATORS: Array<FilterOperator> = [
+  "equals",
+  "isBlank",
+  "isNotBlank",
+];
+export const fallbackOperatorOption: FilterOption = {
+  value: "contains",
+  label: "Contains",
+  iconName: "op-contains",
+};
+
+export function operatorOption(value: FilterOperator): FilterOption {
+  return (
+    filterOperatorOptions.find((option) => option.value === value) ??
+    fallbackOperatorOption
+  );
+}
+
+/** Returns the operators that make sense for the given column's data type. */
+export function operatorsForColumn<TData extends RowData>(
+  column: Column<TData> | undefined,
+): Array<FilterOption> {
+  const editorType = column?.columnDef.editorType ?? "text";
+  const ids =
+    editorType === "number"
+      ? NUMBER_OPERATORS
+      : editorType === "date" || editorType === "datetime"
+        ? DATE_OPERATORS
+        : editorType === "checkbox"
+          ? CHECKBOX_OPERATORS
+          : TEXT_OPERATORS;
+  return ids
+    .map((id) => filterOperatorOptions.find((option) => option.value === id))
+    .filter((option): option is FilterOption => Boolean(option));
+}
+
+/** Default operator for a column (first one valid for its type). */
+export function defaultOperatorFor<TData extends RowData>(
+  column: Column<TData> | undefined,
+): FilterOperator {
+  return operatorsForColumn(column)[0]?.value ?? "contains";
+}
+
+/** Date columns get friendlier labels for "less / greater than". */
+export function operatorLabelFor<TData extends RowData>(
+  option: FilterOption,
+  column: Column<TData> | undefined,
+): string {
+  const editorType = column?.columnDef.editorType;
+  if (editorType === "date" || editorType === "datetime") {
+    if (option.value === "lessThan") return "Before";
+    if (option.value === "greaterThan") return "After";
+  }
+  return option.label;
+}
+
+/** GridMessages key for each operator's label (see grid-messages.ts). */
+const OPERATOR_MESSAGE_KEY: Record<FilterOperator, string> = {
+  contains: "opContains",
+  notContains: "opNotContains",
+  equals: "opEquals",
+  notEquals: "opNotEquals",
+  startsWith: "opStartsWith",
+  endsWith: "opEndsWith",
+  regex: "opRegex",
+  in: "opIn",
+  notIn: "opNotIn",
+  greaterThan: "opGreaterThan",
+  lessThan: "opLessThan",
+  between: "opBetween",
+  isBlank: "opIsBlank",
+  isNotBlank: "opIsNotBlank",
+};
+
+/**
+ * Localized operator label: honors date `Before`/`After` relabels, then the
+ * `localeText` override for the operator, falling back to the English
+ * `option.label`. `messages` is a loose string map to avoid a type cycle.
+ */
+export function localizeOperatorLabel<TData extends RowData>(
+  option: FilterOption,
+  column: Column<TData> | undefined,
+  messages?: Record<string, string> | null,
+): string {
+  const editorType = column?.columnDef.editorType;
+  if (editorType === "date" || editorType === "datetime") {
+    if (option.value === "lessThan") return messages?.opBefore || "Before";
+    if (option.value === "greaterThan") return messages?.opAfter || "After";
+  }
+  const key = OPERATOR_MESSAGE_KEY[option.value];
+  return (key && messages?.[key]) || option.label;
+}

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
+}

package/src/flex-render.ts

@@ -1,3 +1,3 @@
-/// <reference types="svelte" />
-
-export { default as FlexRender } from './FlexRender.svelte'
+/// <reference types="svelte" />
+
+export { default as FlexRender } from './FlexRender.svelte'