@svgrid/enterprise 2.2.1 → 2.3.1

package/src/board.ts

@@ -0,0 +1,36 @@
+/**
+ * board (view) - registers the Enterprise Kanban board renderer with the grid so
+ * `<SvGrid board={...}>` renders lanes of cards instead of the table. The grid
+ * ships the `board` prop and its config types for free; the *renderer*
+ * (SvGridBoard) is Pro and plugs in through the grid's `registerBoardView` seam.
+ *
+ * Soft-gated like the rest of Enterprise: it works without a license key but the
+ * grid shows the "unlicensed" watermark + a one-time console nudge.
+ *
+ * ```ts
+ * import { setLicenseKey, enableBoardView } from '@svgrid/enterprise'
+ * setLicenseKey('YOUR-KEY')
+ * enableBoardView()
+ * // then: <SvGrid {data} {columns} board={{ groupBy: 'status' }} />
+ * ```
+ */
+import { registerBoardView } from '@svgrid/grid'
+import { isLicenseKeySet } from './license'
+import { emitUnlicensedNudge } from './watermark'
+import SvGridBoard from './SvGridBoard.svelte'
+
+let enabled = false
+
+/**
+ * Register the Enterprise Kanban board view. Idempotent - safe to call from every
+ * component that uses `board`, or once at app start. Also invoked by
+ * {@link installEnterprise} so wiring the Pro API turns the view on too.
+ */
+export function enableBoardView(): void {
+  if (enabled) return
+  enabled = true
+  registerBoardView(SvGridBoard as never)
+  if (!isLicenseKeySet()) emitUnlicensedNudge()
+}
+
+export { default as SvGridBoard } from './SvGridBoard.svelte'

package/src/export-ooxml.ts

@@ -83,6 +83,10 @@ const XML_ESCAPE: Record<string, string> = {
   "'": '&apos;',
 }
 // Control chars that are illegal in XML 1.0 (would make Excel reject the file).
+// XML 1.0 forbids these control characters outright, so they are stripped
+// rather than escaped - a stray \x00 from a data source would otherwise
+// produce a workbook Excel refuses to open.
+// eslint-disable-next-line no-control-regex
 const INVALID_XML = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g
 function esc(s: string): string {
   return s.replace(INVALID_XML, '').replace(/[&<>"']/g, (c) => XML_ESCAPE[c]!)

package/src/export-xls.ts

@@ -17,6 +17,9 @@ import type { RowData } from '@svgrid/grid'
 import type { SerializeOptions } from './export-serialize'
 
 // Control chars illegal in XML 1.0 - strip so a stray \x00 can't corrupt the file.
+// See export-ooxml.ts: XML 1.0 has no representation for these at all, so a
+// control character has to be dropped before it reaches the file.
+// eslint-disable-next-line no-control-regex
 const INVALID_XML = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g
 function xmlEscape(s: string): string {
   return s

package/src/export.ts

@@ -349,6 +349,9 @@ async function ensureGlobals(format: ExportFormat): Promise<void> {
   if (format === 'xlsx' && g.JSZip == null) {
     let mod: unknown
     try {
+      // Optional peer, loaded on demand. The `@ts-ignore` keeps a consumer's
+      // type-check clean when jszip isn't installed (no-op when it is).
+      // @ts-ignore - "jszip" is an optional peerDependency
       mod = await import('jszip')
     } catch {
       throw new Error(
@@ -362,7 +365,10 @@ async function ensureGlobals(format: ExportFormat): Promise<void> {
     let pdfMakeMod: unknown
     let vfsMod: unknown
     try {
+      // Optional peer, loaded on demand (keeps consumer type-checks clean when absent).
+      // @ts-ignore - "pdfmake" is an optional peerDependency
       pdfMakeMod = await import('pdfmake/build/pdfmake')
+      // @ts-ignore - "pdfmake" is an optional peerDependency
       vfsMod = await import('pdfmake/build/vfs_fonts')
     } catch {
       throw new Error(

package/src/expressions/evaluate.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { evaluatePredicate, evaluateScalar, evaluateChange } from './evaluate'
+import type { ChangeExpr, EvalContext, PredicateExpr, ScalarExpr } from './expression-types'
+
+type Row = { price: number; qty: number; name: string; region: string }
+
+const row: Row = { price: 120, qty: 3, name: 'Widget', region: 'EU' }
+const ctx = (r: Row, extra: Partial<EvalContext<Row>> = {}): EvalContext<Row> => ({ row: r, ...extra })
+
+describe('evaluateScalar', () => {
+  it('reads columns, literals and arithmetic', () => {
+    const total: ScalarExpr = { kind: 'bin', op: '*', left: { kind: 'col', id: 'price' }, right: { kind: 'col', id: 'qty' } }
+    expect(evaluateScalar(total, ctx(row))).toBe(360)
+    expect(evaluateScalar({ kind: 'lit', value: 5 }, ctx(row))).toBe(5)
+    expect(evaluateScalar({ kind: 'neg', expr: { kind: 'col', id: 'price' } }, ctx(row))).toBe(-120)
+  })
+
+  it('concatenates strings with +', () => {
+    const e: ScalarExpr = { kind: 'bin', op: '+', left: { kind: 'col', id: 'name' }, right: { kind: 'lit', value: '!' } }
+    expect(evaluateScalar(e, ctx(row))).toBe('Widget!')
+  })
+
+  it('guards divide by zero', () => {
+    const e: ScalarExpr = { kind: 'bin', op: '/', left: { kind: 'lit', value: 10 }, right: { kind: 'lit', value: 0 } }
+    expect(Number.isNaN(evaluateScalar(e, ctx(row)) as number)).toBe(true)
+  })
+
+  it('runs built-in functions', () => {
+    expect(evaluateScalar({ kind: 'func', name: 'ABS', args: [{ kind: 'lit', value: -7 }] }, ctx(row))).toBe(7)
+    expect(evaluateScalar({ kind: 'func', name: 'ROUND', args: [{ kind: 'lit', value: 3.14159 }, { kind: 'lit', value: 2 }] }, ctx(row))).toBe(3.14)
+  })
+
+  it('aggregates over the row set in scope', () => {
+    const rows: Row[] = [row, { ...row, price: 80 }, { ...row, price: 40 }]
+    const sum: ScalarExpr = { kind: 'agg', fn: 'sum', column: 'price' }
+    expect(evaluateScalar(sum, ctx(row, { rows }))).toBe(240)
+    expect(evaluateScalar({ kind: 'agg', fn: 'avg', column: 'price' }, ctx(row, { rows }))).toBe(80)
+    expect(evaluateScalar({ kind: 'agg', fn: 'count', column: 'price' }, ctx(row, { rows }))).toBe(3)
+  })
+})
+
+describe('evaluatePredicate', () => {
+  it('cmp delegates to applyExcelFilter semantics', () => {
+    const gt: PredicateExpr = { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 }
+    expect(evaluatePredicate(gt, ctx(row))).toBe(true)
+    expect(evaluatePredicate(gt, ctx({ ...row, price: 50 }))).toBe(false)
+
+    const contains: PredicateExpr = { kind: 'cmp', column: 'name', op: 'contains', value: 'idge' }
+    expect(evaluatePredicate(contains, ctx(row))).toBe(true)
+
+    const inSet: PredicateExpr = { kind: 'cmp', column: 'region', op: 'in', value: ['EU', 'US'] }
+    expect(evaluatePredicate(inSet, ctx(row))).toBe(true)
+    expect(evaluatePredicate(inSet, ctx({ ...row, region: 'APAC' }))).toBe(false)
+  })
+
+  it('combines with and/or/not', () => {
+    const expr: PredicateExpr = {
+      kind: 'and',
+      parts: [
+        { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 },
+        { kind: 'not', expr: { kind: 'cmp', column: 'region', op: 'equals', value: 'US' } },
+      ],
+    }
+    expect(evaluatePredicate(expr, ctx(row))).toBe(true)
+    expect(evaluatePredicate(expr, ctx({ ...row, region: 'US' }))).toBe(false)
+  })
+
+  it('scalarCmp compares cross-column maths', () => {
+    // price / qty >= 40  -> 120/3 = 40 -> true
+    const expr: PredicateExpr = {
+      kind: 'scalarCmp',
+      left: { kind: 'bin', op: '/', left: { kind: 'col', id: 'price' }, right: { kind: 'col', id: 'qty' } },
+      op: '>=',
+      right: { kind: 'lit', value: 40 },
+    }
+    expect(evaluatePredicate(expr, ctx(row))).toBe(true)
+    expect(evaluatePredicate(expr, ctx({ ...row, qty: 4 }))).toBe(false)
+  })
+})
+
+describe('evaluateChange', () => {
+  const change = (e: ChangeExpr, prev: Row, next: Row) => evaluateChange(e, ctx(next, { prev }))
+
+  it('detects a bare change', () => {
+    expect(change({ kind: 'changed', column: 'price' }, row, { ...row, price: 121 })).toBe(true)
+    expect(change({ kind: 'changed', column: 'price' }, row, { ...row })).toBe(false)
+  })
+
+  it('returns false with no prior snapshot', () => {
+    expect(evaluateChange({ kind: 'changed', column: 'price' }, ctx(row))).toBe(false)
+  })
+
+  it('tests absolute delta', () => {
+    const e: ChangeExpr = { kind: 'delta', column: 'price', op: '>', value: 10, abs: true }
+    expect(change(e, row, { ...row, price: 140 })).toBe(true)
+    expect(change(e, row, { ...row, price: 100 })).toBe(true) // abs of -20
+    expect(change(e, row, { ...row, price: 125 })).toBe(false)
+  })
+
+  it('tests percent change', () => {
+    const e: ChangeExpr = { kind: 'percentChange', column: 'price', op: '>', value: 5, abs: true }
+    expect(change(e, row, { ...row, price: 132 })).toBe(true) // +10%
+    expect(change(e, row, { ...row, price: 123 })).toBe(false) // +2.5%
+  })
+
+  it('detects threshold crossing', () => {
+    const above: ChangeExpr = { kind: 'crossed', column: 'price', threshold: 130, direction: 'above' }
+    expect(change(above, row, { ...row, price: 135 })).toBe(true)
+    expect(change(above, { ...row, price: 131 }, { ...row, price: 140 })).toBe(false) // already above
+  })
+})

package/src/expressions/evaluate.ts

@@ -0,0 +1,237 @@
+/**
+ * Expression evaluators - pure functions, no DOM. Predicate leaves delegate to
+ * the grid's `applyExcelFilter` so operator semantics match the filter row
+ * exactly; scalar maths and change detection are handled here.
+ */
+import { applyExcelFilter } from '@svgrid/grid/filtering'
+import type {
+  ChangeExpr,
+  ComparisonOp,
+  EvalContext,
+  ExprRow,
+  PredicateExpr,
+  ScalarExpr,
+} from './expression-types'
+
+type Scalar = number | string | boolean | null
+
+function readValue<TData>(ctx: EvalContext<TData>, row: TData, columnId: string): unknown {
+  if (ctx.getValue) return ctx.getValue(row, columnId)
+  return (row as Record<string, unknown>)?.[columnId]
+}
+
+/** Number coercion that returns NaN for blanks/non-numerics (never 0). */
+function num(v: unknown): number {
+  if (v == null || v === '') return NaN
+  if (typeof v === 'boolean') return v ? 1 : 0
+  return Number(v)
+}
+
+/** Loose value equality used by `changed` and `=` on non-numeric operands. */
+function looseEqual(a: unknown, b: unknown): boolean {
+  if (a == null && b == null) return true
+  const na = num(a)
+  const nb = num(b)
+  if (Number.isFinite(na) && Number.isFinite(nb)) return na === nb
+  return String(a ?? '') === String(b ?? '')
+}
+
+const BUILTINS: Record<string, (args: Scalar[]) => Scalar> = {
+  ABS: (a) => Math.abs(num(a[0])),
+  ROUND: (a) => {
+    const n = num(a[0])
+    const d = a.length > 1 ? num(a[1]) : 0
+    const f = 10 ** (Number.isFinite(d) ? d : 0)
+    return Math.round(n * f) / f
+  },
+  FLOOR: (a) => Math.floor(num(a[0])),
+  CEIL: (a) => Math.ceil(num(a[0])),
+  MIN: (a) => Math.min(...a.map(num)),
+  MAX: (a) => Math.max(...a.map(num)),
+  IF: (a) => (truthy(a[0] ?? null) ? (a[1] ?? null) : (a[2] ?? null)),
+  COALESCE: (a) => a.find((v) => v != null && v !== '') ?? null,
+  CONCAT: (a) => a.map((v) => (v == null ? '' : String(v))).join(''),
+  LOWER: (a) => String(a[0] ?? '').toLowerCase(),
+  UPPER: (a) => String(a[0] ?? '').toUpperCase(),
+  LEN: (a) => String(a[0] ?? '').length,
+}
+
+/** Names of the built-in scalar functions (for editor validation/autocomplete). */
+export const BUILTIN_FUNCTION_NAMES: ReadonlyArray<string> = Object.keys(BUILTINS)
+
+/** Whether `name` (any case) is a known built-in scalar function. */
+export function isBuiltinFunction(name: string): boolean {
+  return name.toUpperCase() in BUILTINS
+}
+
+function truthy(v: Scalar): boolean {
+  if (typeof v === 'boolean') return v
+  if (v == null || v === '') return false
+  const n = num(v)
+  return Number.isFinite(n) ? n !== 0 : true
+}
+
+/** Evaluate a scalar expression to a single value. */
+export function evaluateScalar<TData = ExprRow>(
+  expr: ScalarExpr,
+  ctx: EvalContext<TData>,
+): Scalar {
+  switch (expr.kind) {
+    case 'lit':
+      return expr.value
+    case 'col':
+      return (readValue(ctx, ctx.row, expr.id) ?? null) as Scalar
+    case 'neg':
+      return -num(evaluateScalar(expr.expr, ctx))
+    case 'bin': {
+      const l = evaluateScalar(expr.left, ctx)
+      const r = evaluateScalar(expr.right, ctx)
+      if (expr.op === '+') {
+        const ln = num(l)
+        const rn = num(r)
+        if (Number.isFinite(ln) && Number.isFinite(rn)) return ln + rn
+        return String(l ?? '') + String(r ?? '')
+      }
+      const a = num(l)
+      const b = num(r)
+      switch (expr.op) {
+        case '-':
+          return a - b
+        case '*':
+          return a * b
+        case '/':
+          return b === 0 ? NaN : a / b
+        case '%':
+          return b === 0 ? NaN : a % b
+        // Rules are authored at runtime, so an operator outside the union can
+        // arrive from parsed JSON. Without this the switch falls out of its
+        // case and into `case 'agg'`, reading agg fields off a binary node.
+        default:
+          return null
+      }
+    }
+    case 'agg': {
+      const rows = ctx.rows ?? [ctx.row]
+      if (expr.fn === 'count') return rows.length
+      const nums: number[] = []
+      for (const row of rows) {
+        const n = num(readValue(ctx, row, expr.column))
+        if (Number.isFinite(n)) nums.push(n)
+      }
+      if (nums.length === 0) return expr.fn === 'sum' ? 0 : null
+      switch (expr.fn) {
+        case 'sum':
+          return nums.reduce((s, n) => s + n, 0)
+        case 'avg':
+          return nums.reduce((s, n) => s + n, 0) / nums.length
+        case 'min':
+          return Math.min(...nums)
+        case 'max':
+          return Math.max(...nums)
+        // Same here: falling through to `case 'func'` would call
+        // `expr.name.toUpperCase()` on an agg node and throw.
+        default:
+          return null
+      }
+    }
+    case 'func': {
+      const name = expr.name.toUpperCase()
+      const args = expr.args.map((a) => evaluateScalar(a, ctx))
+      const fn = ctx.functions?.[name] ?? BUILTINS[name]
+      return fn ? fn(args) : null
+    }
+  }
+}
+
+function compareScalar(a: Scalar, op: ComparisonOp, b: Scalar): boolean {
+  switch (op) {
+    case '=':
+      return looseEqual(a, b)
+    case '!=':
+      return !looseEqual(a, b)
+  }
+  const na = num(a)
+  const nb = num(b)
+  const numeric = Number.isFinite(na) && Number.isFinite(nb)
+  const x: number | string = numeric ? na : String(a ?? '')
+  const y: number | string = numeric ? nb : String(b ?? '')
+  switch (op) {
+    case '>':
+      return x > y
+    case '<':
+      return x < y
+    case '>=':
+      return x >= y
+    case '<=':
+      return x <= y
+  }
+}
+
+/** Evaluate a predicate expression to a boolean for the context's row. */
+export function evaluatePredicate<TData = ExprRow>(
+  expr: PredicateExpr,
+  ctx: EvalContext<TData>,
+): boolean {
+  switch (expr.kind) {
+    case 'const':
+      return expr.value
+    case 'and':
+      return expr.parts.every((p) => evaluatePredicate(p, ctx))
+    case 'or':
+      return expr.parts.some((p) => evaluatePredicate(p, ctx))
+    case 'not':
+      return !evaluatePredicate(expr.expr, ctx)
+    case 'cmp':
+      return applyExcelFilter(
+        readValue(ctx, ctx.row, expr.column),
+        { id: expr.column, operator: expr.op, value: expr.value, valueTo: expr.valueTo },
+        { locale: ctx.locale },
+      ) as boolean
+    case 'scalarCmp':
+      return compareScalar(
+        evaluateScalar(expr.left, ctx),
+        expr.op,
+        evaluateScalar(expr.right, ctx),
+      )
+  }
+}
+
+/**
+ * Evaluate a change expression - true when the value moved between `ctx.prev`
+ * and `ctx.row` in the way the expression describes. Returns false when there
+ * is no prior snapshot (nothing has changed yet).
+ */
+export function evaluateChange<TData = ExprRow>(
+  expr: ChangeExpr,
+  ctx: EvalContext<TData>,
+): boolean {
+  if (ctx.prev == null) return false
+  const next = readValue(ctx, ctx.row, expr.column)
+  const prev = readValue(ctx, ctx.prev, expr.column)
+  switch (expr.kind) {
+    case 'changed':
+      return !looseEqual(prev, next)
+    case 'delta': {
+      const p = num(prev)
+      const n = num(next)
+      if (!Number.isFinite(p) || !Number.isFinite(n)) return false
+      const d = expr.abs ? Math.abs(n - p) : n - p
+      return compareScalar(d, expr.op, expr.value)
+    }
+    case 'percentChange': {
+      const p = num(prev)
+      const n = num(next)
+      if (!Number.isFinite(p) || !Number.isFinite(n) || p === 0) return false
+      const pc = ((n - p) / Math.abs(p)) * 100
+      return compareScalar(expr.abs ? Math.abs(pc) : pc, expr.op, expr.value)
+    }
+    case 'crossed': {
+      const p = num(prev)
+      const n = num(next)
+      if (!Number.isFinite(p) || !Number.isFinite(n)) return false
+      return expr.direction === 'above'
+        ? p < expr.threshold && n >= expr.threshold
+        : p > expr.threshold && n <= expr.threshold
+    }
+  }
+}

package/src/expressions/expression-columns.ts

@@ -0,0 +1,133 @@
+/**
+ * Column metadata for the expression layer - the small, self-contained operator
+ * catalogue the editor draws from, plus name <-> id resolution for the
+ * `[Bracketed Name]` reference syntax.
+ *
+ * The operator set mirrors the grid's own filter row (text / number / date),
+ * so an expression's operators line up with what a user already knows from the
+ * column menu. We keep a local copy rather than importing the grid's internal
+ * `filter-operators` module (which is not part of the public surface).
+ */
+import type { ExcelFilterOperator } from '@svgrid/grid'
+
+/** Coarse value type used to decide which operators a column offers. */
+export type ExprColumnType = 'text' | 'number' | 'date' | 'datetime' | 'boolean'
+
+/** A column as the expression layer sees it. */
+export type ExprColumn = {
+  /** Canonical id (the field key stored in the AST). */
+  id: string
+  /** Human label; also the token used inside `[Bracketed Name]` references. */
+  name?: string
+  type?: ExprColumnType
+}
+
+/** One operator entry: its label and which column types it applies to. */
+export type OperatorMeta = {
+  value: ExcelFilterOperator
+  label: string
+  types: ReadonlyArray<ExprColumnType>
+  /** No value input (acts on emptiness alone). */
+  valueless?: boolean
+  /** Multi-value set membership (renders a token/chip input). */
+  set?: boolean
+  /** Needs a second value (`valueTo`). */
+  range?: boolean
+}
+
+const TEXT: ExprColumnType[] = ['text']
+const NUM: ExprColumnType[] = ['number']
+const DATES: ExprColumnType[] = ['date', 'datetime']
+const ALL: ExprColumnType[] = ['text', 'number', 'date', 'datetime', 'boolean']
+
+/** The full operator catalogue, ordered as the editor should present it. */
+export const OPERATORS: ReadonlyArray<OperatorMeta> = [
+  { value: 'equals', label: 'Equals', types: ALL },
+  { value: 'notEquals', label: 'Not equals', types: ALL },
+  { value: 'contains', label: 'Contains', types: TEXT },
+  { value: 'notContains', label: 'Not contains', types: TEXT },
+  { value: 'startsWith', label: 'Starts with', types: TEXT },
+  { value: 'endsWith', label: 'Ends with', types: TEXT },
+  { value: 'regex', label: 'Matches regex', types: TEXT },
+  { value: 'greaterThan', label: 'Greater than', types: [...NUM, ...DATES] },
+  { value: 'lessThan', label: 'Less than', types: [...NUM, ...DATES] },
+  { value: 'between', label: 'Between', types: [...NUM, ...DATES], range: true },
+  { value: 'in', label: 'In', types: ['text', 'number'], set: true },
+  { value: 'notIn', label: 'Not in', types: ['text', 'number'], set: true },
+  { value: 'isBlank', label: 'Is blank', types: ALL, valueless: true },
+  { value: 'isNotBlank', label: 'Is not blank', types: ALL, valueless: true },
+]
+
+const BY_VALUE = new Map<ExcelFilterOperator, OperatorMeta>(
+  OPERATORS.map((op) => [op.value, op]),
+)
+
+/** Metadata for one operator (falls back to a plain `equals`). */
+export function operatorMeta(op: ExcelFilterOperator): OperatorMeta {
+  return BY_VALUE.get(op) ?? { value: 'equals', label: 'Equals', types: ALL }
+}
+
+/** Operators valid for a column type (defaults to the text set). */
+export function operatorsForType(type: ExprColumnType | undefined): OperatorMeta[] {
+  const t = type ?? 'text'
+  return OPERATORS.filter((op) => op.types.includes(t))
+}
+
+/** Whether an operator needs no value input. */
+export function isValueless(op: ExcelFilterOperator): boolean {
+  return operatorMeta(op).valueless === true
+}
+
+/** Whether an operator takes a multi-value token list. */
+export function isSetOperator(op: ExcelFilterOperator): boolean {
+  return operatorMeta(op).set === true
+}
+
+/** Whether an operator needs a second (`valueTo`) value. */
+export function isRangeOperator(op: ExcelFilterOperator): boolean {
+  return operatorMeta(op).range === true
+}
+
+/** Look a column up by its canonical id. */
+export function columnById(
+  columns: ReadonlyArray<ExprColumn>,
+  id: string,
+): ExprColumn | undefined {
+  return columns.find((c) => c.id === id)
+}
+
+/**
+ * Resolve a reference (as written in an expression) to a column id. A reference
+ * matches a column id first, then a column name (case-insensitive) - so both
+ * `price` and `[Unit Price]` resolve. Returns the raw ref unchanged when
+ * nothing matches, leaving `validateExpression` to flag it.
+ */
+export function resolveColumnRef(
+  columns: ReadonlyArray<ExprColumn>,
+  ref: string,
+): string {
+  if (columnById(columns, ref)) return ref
+  const lc = ref.toLowerCase()
+  const byName = columns.find((c) => (c.name ?? '').toLowerCase() === lc)
+  return byName ? byName.id : ref
+}
+
+/** The display label for a column id (its name, or the id itself). */
+export function columnLabel(
+  columns: ReadonlyArray<ExprColumn>,
+  id: string,
+): string {
+  return columnById(columns, id)?.name ?? id
+}
+
+/**
+ * How a column id should be written inside an expression: `[Name]` when the
+ * label has spaces or non-word characters, otherwise the bare id.
+ */
+export function columnRefText(
+  columns: ReadonlyArray<ExprColumn>,
+  id: string,
+): string {
+  const label = columnLabel(columns, id)
+  return /^[A-Za-z_$][\w$]*$/.test(label) ? label : `[${label}]`
+}

package/src/expressions/expression-types.ts

@@ -0,0 +1,84 @@
+/**
+ * Expression / query language - the model layer.
+ *
+ * A tiny, dependency-free expression language that end users author through the
+ * grid UI. It is the connective tissue behind the Alert Rules engine (and, in
+ * time, styled columns and calculated columns): one predicate/scalar/change
+ * model, evaluated the same way everywhere.
+ *
+ * The canonical, persisted form is a JSON AST (the types below) - no parser on
+ * the hot path. A light tokenizer/parser (`parse.ts`) is offered only for the
+ * editor's free-text mode; the structured builder writes the AST directly.
+ *
+ * Leaf comparisons delegate to the grid's own `applyExcelFilter`, so a rule's
+ * "greater than" is byte-for-byte the grid filter's "greater than".
+ */
+import type { ExcelFilterOperator } from '@svgrid/grid'
+
+/** Symbolic comparison operators used by `scalarCmp` (general value compare). */
+export type ComparisonOp = '=' | '!=' | '>' | '<' | '>=' | '<='
+
+/** Arithmetic operators for `bin` scalar nodes. */
+export type ArithmeticOp = '+' | '-' | '*' | '/' | '%'
+
+/** Column aggregate reducers (evaluated over the row set in scope). */
+export type AggFn = 'sum' | 'avg' | 'min' | 'max' | 'count'
+
+/**
+ * A scalar expression - evaluates to a single value (number / string /
+ * boolean / null) for a given row (and, for aggregates, the row set).
+ */
+export type ScalarExpr =
+  | { kind: 'col'; id: string }
+  | { kind: 'lit'; value: string | number | boolean | null }
+  | { kind: 'neg'; expr: ScalarExpr }
+  | { kind: 'bin'; op: ArithmeticOp; left: ScalarExpr; right: ScalarExpr }
+  | { kind: 'agg'; fn: AggFn; column: string }
+  | { kind: 'func'; name: string; args: ScalarExpr[] }
+
+/**
+ * A boolean (predicate) expression - the thing an alert rule / filter needs.
+ *
+ * - `cmp` maps straight onto the grid's `applyExcelFilter` (text/set/range ops).
+ * - `scalarCmp` compares two scalar expressions with a symbolic operator, so
+ *   cross-column maths (`[filled] / [target] >= 0.9`) is expressible.
+ */
+export type PredicateExpr =
+  | { kind: 'and'; parts: PredicateExpr[] }
+  | { kind: 'or'; parts: PredicateExpr[] }
+  | { kind: 'not'; expr: PredicateExpr }
+  | { kind: 'cmp'; column: string; op: ExcelFilterOperator; value?: unknown; valueTo?: unknown }
+  | { kind: 'scalarCmp'; left: ScalarExpr; op: ComparisonOp; right: ScalarExpr }
+  | { kind: 'const'; value: boolean }
+
+/**
+ * A change (observable) expression - true when a value moves between the
+ * previous and current snapshot of a row. Powers "relative change" alerts.
+ */
+export type ChangeExpr =
+  | { kind: 'changed'; column: string }
+  | { kind: 'delta'; column: string; op: ComparisonOp; value: number; abs?: boolean }
+  | { kind: 'percentChange'; column: string; op: ComparisonOp; value: number; abs?: boolean }
+  | { kind: 'crossed'; column: string; threshold: number; direction: 'above' | 'below' }
+
+/** The shape the evaluator reads rows as (a plain field bag by default). */
+export type ExprRow = Record<string, unknown>
+
+/**
+ * Everything the evaluator needs for one evaluation. `getValue` lets a caller
+ * resolve a column id to a value when it is not a plain `row[id]` field;
+ * `functions` injects extra scalar functions (e.g. delegate to HyperFormula).
+ */
+export type EvalContext<TData = ExprRow> = {
+  row: TData
+  /** Prior snapshot of the same row - required by `ChangeExpr`. */
+  prev?: TData
+  /** The row set in scope - required by aggregates. Defaults to `[row]`. */
+  rows?: ReadonlyArray<TData>
+  /** Resolve a column id to its cell value. Defaults to `row[id]`. */
+  getValue?: (row: TData, columnId: string) => unknown
+  /** BCP-47 locale(s) threaded into `applyExcelFilter` for text folding. */
+  locale?: string | ReadonlyArray<string>
+  /** Extra scalar functions by upper-case name, merged over the builtins. */
+  functions?: Record<string, (args: Array<number | string | boolean | null>) => number | string | boolean | null>
+}