@freighttech/ui 0.13.18

package/src/backend/dynamic-table/server/dateWindows.ts

@@ -0,0 +1,201 @@
+/**
+ * Date-window resolution for DynamicTable filter operators — ONE implementation,
+ * shared by every list route regardless of how it applies filters.
+ *
+ * ## Why this file exists (workshop item A14)
+ *
+ * There are two kinds of list route in this repo:
+ *
+ *  - **DB-backed** routes push filters into SQL through {@link parseFilterRow}
+ *    (`filterParser.ts`). Those understood the now-relative operators.
+ *  - **In-memory** routes (the folders Files list, the Transport list) denormalise
+ *    rows first and match with their own `applyColumnFilters`. Those did **not**.
+ *    Their parser dropped any rule whose right-hand side was empty, and every
+ *    preset (`is_today`, `is_tomorrow`, `is_this_week`, `is_next_week`,
+ *    `is_overdue`) is deliberately value-less — so picking "tomorrow" on ETD
+ *    silently returned the **entire unfiltered table**. `is_in_next` /
+ *    `is_in_last` survived the drop but fell through to a substring match, so
+ *    "next 7 days" matched every row whose ISO timestamp contained a "7".
+ *
+ * Both were invisible: a filter that changes nothing looks like "no shipments
+ * match today", not like a bug. Resolving the operator to a concrete
+ * `[from, to]` window here, once, means the preset and the explicit
+ * `is_between` range are the *same mechanism* on every list — which is the
+ * requirement: one operator whose window happens to be computed, the other
+ * whose window is typed.
+ *
+ * All arithmetic is local-time (matching how operators read a calendar) and
+ * day-bounded, so a row stored at `2026-06-12 14:30` matches `is_today` on
+ * 2026-06-12.
+ */
+
+export type RelativeUnit = 'days' | 'weeks' | 'months'
+
+/**
+ * A resolved filter window. `from` is always an inclusive lower bound.
+ * `to` is inclusive unless {@link DateWindow.toExclusive} is set — `is_overdue`
+ * is "strictly before the start of today", which is not expressible as an
+ * inclusive end-of-day bound without an off-by-one-millisecond fudge.
+ * Either side may be `null`, meaning unbounded.
+ */
+export type DateWindow = {
+  from: Date | null
+  to: Date | null
+  toExclusive?: boolean
+}
+
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+
+/** Parse `YYYY-MM-DD` into a local Date at the start of that day. */
+export function parseIsoDay(value: unknown): Date | null {
+  if (typeof value !== 'string' || !ISO_DATE_RE.test(value)) return null
+  const [y, m, d] = value.split('-').map(Number)
+  const date = new Date(y, m - 1, d, 0, 0, 0, 0)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+export function startOfDay(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate(), 0, 0, 0, 0)
+}
+
+export function endOfDay(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate(), 23, 59, 59, 999)
+}
+
+/**
+ * Add `n` units to `base` (n may be negative). Days/weeks are plain day
+ * arithmetic; months are calendar months with an end-of-month clamp so the
+ * result is always a real date instead of a JS Date overflow:
+ *   May 31 minus 1 month -> Apr 30   (not May 1)
+ *   Jan 31 plus 1 month  -> Feb 28/29 (not Mar 2/3)
+ */
+export function addUnit(base: Date, n: number, unit: RelativeUnit): Date {
+  if (unit === 'weeks') {
+    return new Date(base.getFullYear(), base.getMonth(), base.getDate() + n * 7)
+  }
+  if (unit === 'months') {
+    const targetFirst = new Date(base.getFullYear(), base.getMonth() + n, 1)
+    const daysInTarget = new Date(targetFirst.getFullYear(), targetFirst.getMonth() + 1, 0).getDate()
+    return new Date(targetFirst.getFullYear(), targetFirst.getMonth(), Math.min(base.getDate(), daysInTarget))
+  }
+  return new Date(base.getFullYear(), base.getMonth(), base.getDate() + n)
+}
+
+/** Coerce a stored relative unit value, defaulting to days. */
+export function parseUnit(value: unknown): RelativeUnit {
+  return value === 'weeks' || value === 'months' ? value : 'days'
+}
+
+/** ISO weekday: Monday = 1 … Sunday = 7. */
+function isoWeekday(date: Date): number {
+  const wd = date.getDay()
+  return wd === 0 ? 7 : wd
+}
+
+/** Monday 00:00 of the ISO week containing `date`. */
+export function startOfWeek(date: Date): Date {
+  return startOfDay(addUnit(date, 1 - isoWeekday(date), 'days'))
+}
+
+/** Sunday 23:59 of the ISO week containing `date`. */
+export function endOfWeek(date: Date): Date {
+  return endOfDay(addUnit(date, 7 - isoWeekday(date), 'days'))
+}
+
+/**
+ * Coerce a stored relative count to a positive integer, or null if invalid.
+ * Uses `Number` (not `parseInt`) so fractional/garbage input like "1.5" or
+ * "5abc" is rejected outright rather than silently truncated.
+ */
+export function parsePositiveInt(value: unknown): number | null {
+  const n = typeof value === 'number' ? value : Number(String(value ?? '').trim())
+  return Number.isInteger(n) && n >= 1 ? n : null
+}
+
+/**
+ * Every operator that resolves to a `[from, to]` window.
+ *
+ * `is_between` is in this list ON PURPOSE. Agnieszka works date-first on an
+ * explicit range ("szybciej mi jest operować na zakresie dat") and declined
+ * more presets; Klaudiusz lives on "tomorrow". Both mechanisms must coexist in
+ * the same operator list, and the cheapest way to guarantee they never diverge
+ * is for them to produce the same shape.
+ */
+export const DATE_WINDOW_OPERATORS = [
+  'is_between',
+  'is_in_next',
+  'is_in_last',
+  'is_overdue',
+  'is_today',
+  'is_tomorrow',
+  'is_this_week',
+  'is_next_week',
+] as const
+
+export type DateWindowOperator = (typeof DATE_WINDOW_OPERATORS)[number]
+
+const WINDOW_OPERATOR_SET: ReadonlySet<string> = new Set<string>(DATE_WINDOW_OPERATORS)
+
+export function isDateWindowOperator(operator: string): operator is DateWindowOperator {
+  return WINDOW_OPERATOR_SET.has(operator)
+}
+
+/**
+ * Resolve a window operator + its stored `values` into a concrete
+ * `[from, to]` range, anchored to `now`.
+ *
+ * Returns `null` when the rule cannot produce a window — an unknown operator,
+ * an `is_between` with neither end filled, or an `is_in_next` whose count is
+ * missing or not a positive integer. A `null` return means "drop this rule",
+ * never "match nothing".
+ *
+ * `now` is injected (and re-read per request by callers) so a saved
+ * perspective holding `is_tomorrow` keeps meaning *tomorrow*, not the day
+ * after it was saved.
+ */
+export function resolveDateWindow(
+  operator: string,
+  values: readonly unknown[],
+  now: Date = new Date(),
+): DateWindow | null {
+  switch (operator) {
+    case 'is_between': {
+      // Explicit range from the two FilterDatePickers — values = [from, to].
+      // A half-open range (only one end filled) is still a useful filter, so
+      // the missing side is left unbounded rather than dropping the rule.
+      const from = parseIsoDay(values[0])
+      const to = parseIsoDay(values[1])
+      if (!from && !to) return null
+      return { from: from ? startOfDay(from) : null, to: to ? endOfDay(to) : null }
+    }
+    case 'is_in_next': {
+      // Moving window anchored to today: [start of today, end of today + N units].
+      const count = parsePositiveInt(values[0])
+      if (count === null) return null
+      return { from: startOfDay(now), to: endOfDay(addUnit(now, count, parseUnit(values[1]))) }
+    }
+    case 'is_in_last': {
+      const count = parsePositiveInt(values[0])
+      if (count === null) return null
+      return { from: startOfDay(addUnit(now, -count, parseUnit(values[1]))), to: endOfDay(now) }
+    }
+    case 'is_overdue':
+      // Strictly before today — a date that has already passed.
+      return { from: null, to: startOfDay(now), toExclusive: true }
+    case 'is_today':
+      return { from: startOfDay(now), to: endOfDay(now) }
+    case 'is_tomorrow': {
+      const t = addUnit(now, 1, 'days')
+      return { from: startOfDay(t), to: endOfDay(t) }
+    }
+    case 'is_this_week':
+      // Today through the end of the current ISO week (upcoming, not past days).
+      return { from: startOfDay(now), to: endOfWeek(now) }
+    case 'is_next_week': {
+      const nextWeek = addUnit(now, 7, 'days')
+      return { from: startOfWeek(nextWeek), to: endOfWeek(nextWeek) }
+    }
+    default:
+      return null
+  }
+}

package/src/backend/dynamic-table/server/filterParser.ts

@@ -0,0 +1,132 @@
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import {
+  endOfDay,
+  parseIsoDay,
+  resolveDateWindow,
+  startOfDay,
+} from './dateWindows'
+
+export interface DynamicTableFilterRow {
+  field: string
+  operator: string
+  values: unknown[]
+}
+
+/**
+ * Parse a single DynamicTable FilterRow into a MikroORM Where clause.
+ * Returns null if the row cannot be parsed (unknown field, missing value, etc.)
+ *
+ * Date semantics: when an operator is date-typed (`is_before` / `is_after` /
+ * `is_on_or_before` / `is_on_or_after` / `is_between`) or when `equals` is
+ * given an ISO `YYYY-MM-DD` value, the parser converts the right-hand side
+ * into Date objects and uses day-bounded ranges so timestamp columns compare
+ * correctly. The on/between/equals operators expand to a [start-of-day,
+ * end-of-day] window so a row stored as `2026-05-11 14:30` matches a filter
+ * for `equals 2026-05-11`.
+ */
+export function parseFilterRow(
+  row: DynamicTableFilterRow,
+  fieldMap: Record<string, string>,
+  now: Date = new Date()
+): Record<string, unknown> | null {
+  const field = fieldMap[row.field]
+  if (!field) return null
+
+  const val = row.values[0]
+  const hasValue = val !== undefined && val !== null && val !== ''
+  const hasValues = Array.isArray(row.values) && row.values.length > 0
+
+  switch (row.operator) {
+    case 'is_any_of':
+      if (!hasValues) return null
+      return { [field]: { $in: row.values } }
+    case 'is_not_any_of':
+      if (!hasValues) return null
+      return { [field]: { $nin: row.values } }
+    case 'contains':
+      if (!hasValue) return null
+      return { [field]: { $ilike: `%${escapeLikePattern(String(val))}%` } }
+    case 'is_empty':
+      return { [field]: { $eq: null } }
+    case 'is_not_empty':
+      return { [field]: { $ne: null } }
+    case 'equals': {
+      if (!hasValue) return null
+      // Same-day equality for ISO date values; exact-match otherwise.
+      const day = parseIsoDay(val)
+      if (day) return { [field]: { $gte: startOfDay(day), $lte: endOfDay(day) } }
+      return { [field]: { $eq: val } }
+    }
+    case 'not_equals':
+      if (!hasValue) return null
+      return { [field]: { $ne: val } }
+    case 'is_true':
+      return { [field]: { $eq: true } }
+    case 'is_false':
+      return { [field]: { $eq: false } }
+    case 'greater_than':
+      if (!hasValue) return null
+      return { [field]: { $gt: val } }
+    case 'less_than':
+      if (!hasValue) return null
+      return { [field]: { $lt: val } }
+    case 'is_before': {
+      if (!hasValue) return null
+      const day = parseIsoDay(val)
+      // Strictly before the picked day starts.
+      return { [field]: { $lt: day ?? val } }
+    }
+    case 'is_after': {
+      if (!hasValue) return null
+      const day = parseIsoDay(val)
+      // Strictly after the picked day ends.
+      return { [field]: { $gt: day ? endOfDay(day) : val } }
+    }
+    case 'is_on_or_before': {
+      if (!hasValue) return null
+      const day = parseIsoDay(val)
+      // Anywhere on the picked day or earlier.
+      return { [field]: { $lte: day ? endOfDay(day) : val } }
+    }
+    case 'is_on_or_after': {
+      if (!hasValue) return null
+      const day = parseIsoDay(val)
+      return { [field]: { $gte: day ? startOfDay(day) : val } }
+    }
+    // ── Windowed date operators ───────────────────────────────────────────────
+    // `is_between` (explicit range) and every now-relative preset / moving
+    // window resolve through ONE shared resolver, so the DB-backed lists and
+    // the in-memory lists can never drift apart on what "tomorrow" means.
+    case 'is_between':
+    case 'is_in_next':
+    case 'is_in_last':
+    case 'is_overdue':
+    case 'is_today':
+    case 'is_tomorrow':
+    case 'is_this_week':
+    case 'is_next_week': {
+      const window = resolveDateWindow(row.operator, row.values, now)
+      if (!window) return null
+      const range: Record<string, Date> = {}
+      if (window.from) range.$gte = window.from
+      if (window.to) range[window.toExclusive ? '$lt' : '$lte'] = window.to
+      return { [field]: range }
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * Convert an array of DynamicTable FilterRows into MikroORM Where clauses.
+ * Filters out rows that cannot be parsed (unknown field, missing value, etc.)
+ */
+export function parseDynamicTableFilters(
+  filterRows: DynamicTableFilterRow[],
+  fieldMap: Record<string, string>,
+  now: Date = new Date()
+): Record<string, unknown>[] {
+  return filterRows
+    .map((row) => parseFilterRow(row, fieldMap, now))
+    .filter((f): f is Record<string, unknown> => f !== null)
+}

package/src/backend/dynamic-table/server/filterSuggestions.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared primitive for DynamicTable filter-value suggestions.
+ *
+ * Why this exists instead of `/api/entities/filter-suggestions`:
+ *
+ *  1. The generic endpoint SAMPLES rather than aggregating — it pulls
+ *     `pageSize: limit * 2` rows and de-duplicates whatever came back. On a
+ *     skewed column that hides most values: on production, `invoice.source`
+ *     returned a single suggestion while the table actually holds three
+ *     (finance 8,499 / document 675 / ksef 66), because the first 100 rows were
+ *     all `finance`.
+ *  2. It resolves fields off the entity's own table, so any column the list
+ *     denormalises (a joined contractor name, a container number living on a
+ *     child unit) yields `[]` — and it fails *silently*, so the picker just
+ *     looks empty rather than erroring.
+ *
+ * `distinctColumnValues` runs a real `SELECT DISTINCT` against a named
+ * table/column, always constrained by the caller's scope, so every list can
+ * offer the same suggestion behaviour regardless of where its data lives.
+ */
+
+/** Postgres identifier: letters, digits, underscore; not starting with a digit. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/i
+
+function assertIdentifier(kind: 'table' | 'column', value: string): string {
+  if (!IDENTIFIER.test(value)) {
+    throw new Error(`Unsafe ${kind} identifier for filter suggestions: ${JSON.stringify(value)}`)
+  }
+  return `"${value}"`
+}
+
+export interface DistinctColumnValuesOptions {
+  /** MikroORM EntityManager (uses its underlying connection). */
+  em: { getConnection: () => { execute: (sql: string, params?: unknown[]) => Promise<unknown> } }
+  /** Physical table name. Caller-controlled — never user input. */
+  table: string
+  /**
+   * Physical column(s) to aggregate. Caller-controlled — never user input.
+   * Pass several when one grid column is fed by more than one DB column: the
+   * invoice list's "counterparty" is `seller_name` for incoming invoices and
+   * `buyer_name` for outgoing ones, so both have to be offered.
+   */
+  column: string | string[]
+  /**
+   * Scope predicate as physical column → value. `null` means `IS NULL` (used
+   * for `deleted_at`), an array becomes `IN (...)`. Values are parameterised.
+   */
+  scope?: Record<string, string | string[] | null | undefined>
+  /** Optional case-insensitive substring the value must contain. */
+  query?: string
+  /** Max suggestions returned. Defaults to 50, hard-capped at 200. */
+  limit?: number
+  /**
+   * Optional join, for columns that live on a related table
+   * (e.g. suggesting a contractor name for a folder list).
+   */
+  join?: { table: string; on: string; foreign: string }
+}
+
+/**
+ * Distinct, non-empty, alphabetically ordered values for one column.
+ *
+ * Returns `[]` rather than throwing when the table is unreachable — a missing
+ * suggestion list must never take down the list page that requested it.
+ */
+export async function distinctColumnValues(opts: DistinctColumnValuesOptions): Promise<string[]> {
+  const limit = Math.min(Math.max(opts.limit ?? 50, 1), 200)
+  const base = assertIdentifier('table', opts.table)
+  const columns = (Array.isArray(opts.column) ? opts.column : [opts.column])
+    .map((c) => assertIdentifier('column', c))
+  if (columns.length === 0) return []
+
+  const params: unknown[] = []
+  const where: string[] = []
+  let from = `${base} AS t`
+  let prefix = 't'
+
+  if (opts.join) {
+    const jt = assertIdentifier('table', opts.join.table)
+    const on = assertIdentifier('column', opts.join.on)
+    const foreign = assertIdentifier('column', opts.join.foreign)
+    from = `${base} AS t INNER JOIN ${jt} AS j ON j.${foreign} = t.${on}`
+    prefix = 'j'
+  }
+
+  // One grid column, possibly several DB columns: unnest keeps the scope
+  // predicate (and its bound parameters) written exactly once.
+  const target = columns.length === 1
+    ? `${prefix}.${columns[0]}`
+    : `unnest(ARRAY[${columns.map((c) => `${prefix}.${c}::text`).join(', ')}])`
+
+  for (const [rawColumn, value] of Object.entries(opts.scope ?? {})) {
+    if (value === undefined) continue
+    const scoped = `t.${assertIdentifier('column', rawColumn)}`
+    if (value === null) {
+      where.push(`${scoped} IS NULL`)
+    } else if (Array.isArray(value)) {
+      // An empty allow-list means "no rows in scope" — not "no constraint".
+      if (value.length === 0) return []
+      const holes = value.map((entry) => {
+        params.push(entry)
+        return '?'
+      })
+      where.push(`${scoped} IN (${holes.join(', ')})`)
+    } else {
+      params.push(value)
+      where.push(`${scoped} = ?`)
+    }
+  }
+
+  // `unnest` is a set-returning function and cannot sit in WHERE, so the
+  // multi-column form selects into a subquery and filters the flattened value
+  // outside it. Scope predicates stay inside either way — they must be applied
+  // before the columns are flattened, and their parameters bind first.
+  const needle = (opts.query ?? '').trim()
+  const scopeWhere = where.length > 0 ? `WHERE ${where.join(' AND ')} ` : ''
+
+  const outer: string[] = ['value IS NOT NULL', "btrim(value) <> ''"]
+  let sql: string
+  if (columns.length === 1) {
+    if (needle) params.push(`%${needle}%`)
+    const outerSql = [...outer, ...(needle ? ['value ILIKE ?'] : [])].join(' AND ')
+    sql =
+      `SELECT DISTINCT value FROM (SELECT ${target}::text AS value FROM ${from} ${scopeWhere}) s ` +
+      `WHERE ${outerSql} ORDER BY value ASC LIMIT ?`
+  } else {
+    if (needle) params.push(`%${needle}%`)
+    const outerSql = [...outer, ...(needle ? ['value ILIKE ?'] : [])].join(' AND ')
+    sql =
+      `SELECT DISTINCT value FROM (SELECT ${target} AS value FROM ${from} ${scopeWhere}) s ` +
+      `WHERE ${outerSql} ORDER BY value ASC LIMIT ?`
+  }
+  params.push(limit)
+
+  try {
+    const rows = (await opts.em.getConnection().execute(sql, params)) as Array<{ value: string }>
+    return Array.isArray(rows) ? rows.map((r) => r.value).filter(Boolean) : []
+  } catch (err) {
+    // A missing suggestion list must never take down the list page, so this
+    // still degrades to []. But it does NOT swallow the reason: a broken query
+    // here is indistinguishable from "this column has no values", and that cost
+    // a full release cycle once already — every endpoint answered 200 with an
+    // empty list and looked correctly wired.
+    console.error(
+      `[filter-suggestions] query failed for ${opts.table}.${opts.column}:`,
+      err instanceof Error ? err.message : err,
+    )
+    return []
+  }
+}

package/src/backend/dynamic-table/server/index.ts

@@ -0,0 +1,47 @@
+export { makeDynamicTableRoute } from './makeDynamicTableRoute'
+export type {
+  DynamicTableRouteConfig,
+  DynamicTableRouteOrmConfig,
+  DynamicTableRouteCtx,
+  DynamicTableRouteMethodMetadata,
+  DynamicTableRouteUpdateConfig,
+  DynamicTableRouteCreateConfig,
+  DynamicTableRouteDeleteConfig,
+} from './makeDynamicTableRoute'
+
+export {
+  parseFilterRow,
+  parseDynamicTableFilters,
+} from './filterParser'
+export type { DynamicTableFilterRow } from './filterParser'
+
+export {
+  DATE_WINDOW_OPERATORS,
+  isDateWindowOperator,
+  resolveDateWindow,
+} from './dateWindows'
+export type { DateWindow, DateWindowOperator } from './dateWindows'
+
+export { distinctColumnValues } from './filterSuggestions'
+export type { DistinctColumnValuesOptions } from './filterSuggestions'
+
+export {
+  MAX_AGGREGATE_ENTRIES,
+  MAX_AGGREGATE_PARAM_LENGTH,
+  AggregateSpecError,
+  AggregateScopeError,
+  aggregateKey,
+  buildAggregateSelect,
+  buildAggregateWhere,
+  makeColumnResolver,
+  mapAggregateRow,
+  parseAggregateSpec,
+  runAggregate,
+  tenancyFromRouteContext,
+} from './aggregate'
+export type {
+  AggregateEntry,
+  AggregateSelectPlan,
+  AggregateTenancy,
+  RunAggregateOptions,
+} from './aggregate'