@freighttech/ui 0.13.18

package/src/backend/dynamic-table/__tests__/abbreviationsSubscription.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The abbreviation registry's CHANGE NOTIFICATION.
+ *
+ * Why this is worth its own test file: the dictionary is fetched once at app
+ * boot, which routinely resolves AFTER a grid has already painted every cell
+ * with the long names. Registration therefore has to do two things — fill the
+ * registry, and tell somebody — and only the first of those is obvious. A
+ * regression here is silent and looks exactly like "the abbreviations feature
+ * doesn't work": cells keep showing "Port Gdańsk" until the user happens to
+ * sort or page, and nothing errors.
+ */
+
+import {
+  ABBREV_FACILITY,
+  abbreviate,
+  abbreviationsVersion,
+  contractorToAbbreviation,
+  facilityToAbbreviation,
+  registerAbbreviations,
+  registerAbbreviationSeed,
+  resetAbbreviations,
+  subscribeAbbreviations,
+} from '../utils/abbreviations'
+
+const NS = 'test-namespace'
+
+afterEach(() => {
+  resetAbbreviations()
+})
+
+describe('subscribeAbbreviations', () => {
+  it('notifies subscribers when a runtime dictionary is registered', () => {
+    const seen: number[] = []
+    const stop = subscribeAbbreviations(() => seen.push(abbreviationsVersion()))
+
+    registerAbbreviations(NS, [{ match: ['Port Gdansk'], short: 'GDN' }])
+
+    expect(seen).toHaveLength(1)
+    stop()
+  })
+
+  it('notifies on seed registration too — a seed changes what cells render', () => {
+    const listener = jest.fn()
+    const stop = subscribeAbbreviations(listener)
+
+    registerAbbreviationSeed(NS, [{ match: ['Baltic Hub'], short: 'BHCT' }])
+
+    expect(listener).toHaveBeenCalledTimes(1)
+    stop()
+  })
+
+  it('bumps the version monotonically so memo dependencies actually change', () => {
+    const before = abbreviationsVersion()
+    registerAbbreviations(NS, [{ match: ['a'], short: 'A' }])
+    const mid = abbreviationsVersion()
+    registerAbbreviations(NS, [{ match: ['b'], short: 'B' }])
+
+    expect(mid).toBeGreaterThan(before)
+    expect(abbreviationsVersion()).toBeGreaterThan(mid)
+  })
+
+  it('stops notifying after unsubscribe', () => {
+    const listener = jest.fn()
+    const stop = subscribeAbbreviations(listener)
+    stop()
+
+    registerAbbreviations(NS, [{ match: ['a'], short: 'A' }])
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('a throwing subscriber does not prevent the others being told', () => {
+    // One broken consumer must not cost every OTHER grid on the page its
+    // dictionary — the failure would be invisible and asymmetric.
+    const good = jest.fn()
+    const stopBad = subscribeAbbreviations(() => {
+      throw new Error('subscriber blew up')
+    })
+    const stopGood = subscribeAbbreviations(good)
+
+    expect(() => registerAbbreviations(NS, [{ match: ['a'], short: 'A' }])).not.toThrow()
+    expect(good).toHaveBeenCalledTimes(1)
+
+    stopBad()
+    stopGood()
+  })
+
+  it('registration invalidates cached MISSES, not just cached hits', () => {
+    // The common case by far: the grid rendered and asked for a value before
+    // the dictionary arrived, so the registry cached `null` for it. If that
+    // negative result survived registration the cell would never fold.
+    expect(abbreviate(NS, 'Port Gdansk')).toBeNull()
+
+    registerAbbreviations(NS, [{ match: ['Port Gdansk'], short: 'GDN' }])
+
+    expect(abbreviate(NS, 'Port Gdansk')).toBe('GDN')
+  })
+})
+
+describe('the boot payload adapters', () => {
+  it('facilityToAbbreviation prefers the curated short name over code and locode', () => {
+    expect(
+      facilityToAbbreviation({ name: 'Baltic Hub', shortName: 'BHCT', code: 'DCT', locode: 'PLGDN' })?.short,
+    ).toBe('BHCT')
+  })
+
+  it('falls back to the code, then the locode', () => {
+    expect(facilityToAbbreviation({ name: 'X', code: 'BCT', locode: 'PLGDY' })?.short).toBe('BCT')
+    expect(facilityToAbbreviation({ name: 'X', locode: 'PLGDY' })?.short).toBe('PLGDY')
+  })
+
+  it('skips a facility with nothing to abbreviate to rather than guessing', () => {
+    expect(facilityToAbbreviation({ name: 'Some Unnamed Depot' })).toBeNull()
+  })
+
+  // Found in the browser against the live table: 1738 facilities whose
+  // `short_name` is null and whose `code` is a generated geohash key. The
+  // original precedence preferred `code`, which rendered "Port Gdańsk" as
+  // "N031E031-04…" — longer than the LOCODE and truncated in an 84px column.
+  it('rejects a machine-generated code and falls through to the LOCODE', () => {
+    expect(
+      facilityToAbbreviation({ name: 'Aalborg Container Terminal', code: 'N057E010-02981', locode: 'DKAAL' })?.short,
+    ).toBe('DKAAL')
+    expect(
+      facilityToAbbreviation({ name: 'Some Depot', code: 'ADDR-1BF4-9C3E', locode: 'PLGDN' })?.short,
+    ).toBe('PLGDN')
+  })
+
+  it('still prefers a genuine short trade code over the LOCODE', () => {
+    expect(facilityToAbbreviation({ name: 'Baltic CT', code: 'BCT', locode: 'PLGDY' })?.short).toBe('BCT')
+  })
+
+  it('emits no entry at all when every candidate is an internal id', () => {
+    // The full name is the honest rendering — never a truncated machine key.
+    expect(facilityToAbbreviation({ name: 'Nowhere Terminal', code: 'ADDR-1BF4-9C3E' })).toBeNull()
+  })
+
+  it('never length-checks a CURATED short name — staff intent wins', () => {
+    expect(
+      facilityToAbbreviation({ name: 'X', shortName: 'Gdansk North Quay', code: 'BCT' })?.short,
+    ).toBe('Gdansk North Quay')
+  })
+
+  it('contractorToAbbreviation derives nothing — it only delivers a curated short name', () => {
+    expect(contractorToAbbreviation({ name: 'Maersk Polska Sp. z o.o.', shortName: 'MAERSK' })?.short).toBe('MAERSK')
+    // No short name → no entry, so the grid keeps the full legal name. A second
+    // derivation scheme here would drift from the one staff maintain.
+    expect(contractorToAbbreviation({ name: 'Maersk Polska Sp. z o.o.' })).toBeNull()
+    // Identical short and full is not an abbreviation; shipping it would only
+    // add a registry entry that resolves to the value it replaced.
+    expect(contractorToAbbreviation({ name: 'DHL', shortName: 'DHL' })).toBeNull()
+  })
+})
+
+describe('the shipped seed keeps a fresh deployment readable', () => {
+  it('folds the Polish terminals INF names out loud, diacritics and all', () => {
+    expect(abbreviate(ABBREV_FACILITY, 'Port Gdańsk')).toBe('GDN')
+    expect(abbreviate(ABBREV_FACILITY, 'port gdansk')).toBe('GDN')
+    expect(abbreviate(ABBREV_FACILITY, 'Baltic Hub')).toBe('BHCT')
+    expect(abbreviate(ABBREV_FACILITY, 'DCT Gdańsk')).toBe('BHCT')
+  })
+
+  it('a database registration outranks the seed', () => {
+    registerAbbreviations(ABBREV_FACILITY, [{ match: ['Port Gdansk'], short: 'GDA' }])
+    expect(abbreviate(ABBREV_FACILITY, 'Port Gdańsk')).toBe('GDA')
+  })
+
+  it('leaves an uncurated value alone rather than inventing one', () => {
+    expect(abbreviate(ABBREV_FACILITY, 'Some Regional Depot')).toBeNull()
+  })
+})

package/src/backend/dynamic-table/__tests__/aggregate.spec.test.ts

@@ -0,0 +1,224 @@
+import {
+  parseAggregateSpec,
+  buildAggregateWhere,
+  buildAggregateSelect,
+  mapAggregateRow,
+  tenancyFromRouteContext,
+  aggregateKey,
+  AggregateSpecError,
+  AggregateScopeError,
+  MAX_AGGREGATE_ENTRIES,
+} from '../server/aggregate'
+
+// The route's public column key -> ORM property. This IS the allow-list.
+const fieldMap: Record<string, string> = {
+  grossAmount: 'grossAmount',
+  netAmount: 'netAmount',
+  id: 'id',
+  issuedAt: 'issuedAt',
+}
+
+describe('parseAggregateSpec', () => {
+  it('parses a well-formed spec', () => {
+    expect(parseAggregateSpec('grossAmount:sum,netAmount:avg,id:count', fieldMap)).toEqual([
+      { field: 'grossAmount', fn: 'sum', property: 'grossAmount' },
+      { field: 'netAmount', fn: 'avg', property: 'netAmount' },
+      { field: 'id', fn: 'count', property: 'id' },
+    ])
+  })
+
+  it('accepts every widened function', () => {
+    const spec = ['sum', 'avg', 'min', 'max', 'count', 'countDistinct']
+      .map((fn) => `grossAmount:${fn}`)
+      .join(',')
+    expect(parseAggregateSpec(spec, fieldMap)).toHaveLength(6)
+  })
+
+  it('treats absent / empty as "no aggregate requested"', () => {
+    expect(parseAggregateSpec(undefined, fieldMap)).toEqual([])
+    expect(parseAggregateSpec(null, fieldMap)).toEqual([])
+    expect(parseAggregateSpec('   ', fieldMap)).toEqual([])
+  })
+
+  it('de-duplicates identical field:fn pairs', () => {
+    expect(parseAggregateSpec('grossAmount:sum,grossAmount:sum', fieldMap)).toHaveLength(1)
+  })
+
+  // ── Rejection: an unknown field must never reach SQL ──
+  it('rejects a field that is not on the route allow-list', () => {
+    expect(() => parseAggregateSpec('secretSalary:sum', fieldMap)).toThrow(AggregateSpecError)
+  })
+
+  it('rejects an SQL-injection attempt outright', () => {
+    expect(() => parseAggregateSpec('x);DROP TABLE invoices;--:sum', fieldMap)).toThrow(
+      AggregateSpecError,
+    )
+    expect(() => parseAggregateSpec('grossAmount:sum);DROP TABLE t;--', fieldMap)).toThrow(
+      AggregateSpecError,
+    )
+  })
+
+  it('rejects an unknown function', () => {
+    expect(() => parseAggregateSpec('grossAmount:median', fieldMap)).toThrow(AggregateSpecError)
+  })
+
+  it('rejects malformed entries', () => {
+    expect(() => parseAggregateSpec('grossAmount', fieldMap)).toThrow(AggregateSpecError)
+    expect(() => parseAggregateSpec(':sum', fieldMap)).toThrow(AggregateSpecError)
+    expect(() => parseAggregateSpec('grossAmount:', fieldMap)).toThrow(AggregateSpecError)
+  })
+
+  it('rejects an over-long spec and too many entries', () => {
+    expect(() => parseAggregateSpec('a'.repeat(501), fieldMap)).toThrow(AggregateSpecError)
+    const many = Array.from({ length: MAX_AGGREGATE_ENTRIES + 1 }, (_, i) => `f${i}:sum`).join(',')
+    expect(() => parseAggregateSpec(many, fieldMap)).toThrow(AggregateSpecError)
+  })
+
+  it('does not treat inherited Object properties as allow-listed fields', () => {
+    expect(() => parseAggregateSpec('constructor:sum', fieldMap)).toThrow(AggregateSpecError)
+    expect(() => parseAggregateSpec('toString:count', fieldMap)).toThrow(AggregateSpecError)
+  })
+})
+
+describe('buildAggregateWhere — tenant isolation', () => {
+  const rowWhere = { deletedAt: null, status: 'open', $and: [{ grossAmount: { $gt: 10 } }] }
+
+  it('keeps the row query WHERE and re-asserts org (a SET) + tenant', () => {
+    const merged = buildAggregateWhere(rowWhere, {
+      organizationIds: ['org-1', 'org-2'],
+      tenantId: 'tenant-1',
+    })
+    expect(merged.status).toBe('open')
+    expect(merged.$and).toEqual(rowWhere.$and)
+    expect(merged.organizationId).toEqual({ $in: ['org-1', 'org-2'] })
+    expect(merged.tenantId).toBe('tenant-1')
+    expect(merged.deletedAt).toBeNull()
+  })
+
+  it('does not mutate the caller’s WHERE object', () => {
+    const original = { ...rowWhere }
+    buildAggregateWhere(rowWhere, { organizationIds: ['org-1'], tenantId: 't' })
+    expect(rowWhere).toEqual(original)
+  })
+
+  it('REFUSES to build an aggregate with no organization scope', () => {
+    expect(() => buildAggregateWhere(rowWhere, { organizationIds: [], tenantId: 't' })).toThrow(
+      AggregateScopeError,
+    )
+  })
+
+  it('REFUSES to build an aggregate with no tenant', () => {
+    expect(() =>
+      buildAggregateWhere(rowWhere, { organizationIds: ['org-1'], tenantId: null }),
+    ).toThrow(AggregateScopeError)
+  })
+
+  it('lets a genuinely unscoped entity opt out explicitly', () => {
+    const merged = buildAggregateWhere(rowWhere, {
+      organizationIds: [],
+      orgField: null,
+      tenantField: null,
+      softDeleteField: null,
+    })
+    expect(merged.organizationId).toBeUndefined()
+    expect(merged.tenantId).toBeUndefined()
+  })
+
+  it('honours custom scope field names', () => {
+    const merged = buildAggregateWhere(
+      {},
+      { orgField: 'orgId', organizationIds: ['o'], tenantField: 'tid', tenantId: 't' },
+    )
+    expect(merged.orgId).toEqual({ $in: ['o'] })
+    expect(merged.tid).toBe('t')
+  })
+})
+
+describe('tenancyFromRouteContext', () => {
+  it('carries the whole organization SET, not a single id', () => {
+    const tenancy = tenancyFromRouteContext(
+      { tenantId: 'tenant-9', allowedOrgIds: new Set(['a', 'b', 'c']) },
+      {},
+    )
+    expect(tenancy.organizationIds.sort()).toEqual(['a', 'b', 'c'])
+    expect(tenancy.tenantId).toBe('tenant-9')
+  })
+})
+
+describe('buildAggregateSelect', () => {
+  const columnOf = (property: string) =>
+    ({ grossAmount: 'gross_amount', netAmount: 'net_amount', id: 'id' })[property]
+
+  it('emits parameterless, quoted, generated-alias expressions plus a row count', () => {
+    const plan = buildAggregateSelect(
+      [
+        { field: 'grossAmount', fn: 'sum', property: 'grossAmount' },
+        { field: 'id', fn: 'countDistinct', property: 'id' },
+      ],
+      columnOf,
+      'dta',
+    )
+    expect(plan.expressions).toEqual([
+      'sum("dta"."gross_amount") as "agg_0"',
+      'count(distinct "dta"."id") as "agg_1"',
+      'count(*) as "agg_total"',
+    ])
+    expect(plan.aliasToKey).toEqual({ agg_0: 'grossAmount:sum', agg_1: 'id:countDistinct' })
+  })
+
+  it('rejects a column name that is not a plain identifier', () => {
+    expect(() =>
+      buildAggregateSelect(
+        [{ field: 'x', fn: 'sum', property: 'x' }],
+        () => 'gross"; drop table t; --',
+        'dta',
+      ),
+    ).toThrow(AggregateSpecError)
+  })
+
+  it('rejects an unmapped property rather than guessing a column', () => {
+    expect(() =>
+      buildAggregateSelect([{ field: 'x', fn: 'sum', property: 'x' }], () => undefined, 'dta'),
+    ).toThrow(AggregateSpecError)
+  })
+
+  it('rejects an unsafe table alias', () => {
+    expect(() =>
+      buildAggregateSelect([{ field: 'id', fn: 'count', property: 'id' }], columnOf, 'a"b'),
+    ).toThrow(AggregateSpecError)
+  })
+})
+
+describe('mapAggregateRow', () => {
+  const plan = buildAggregateSelect(
+    [
+      { field: 'grossAmount', fn: 'sum', property: 'grossAmount' },
+      { field: 'id', fn: 'count', property: 'id' },
+      { field: 'netAmount', fn: 'min', property: 'netAmount' },
+    ],
+    (p) => ({ grossAmount: 'gross_amount', id: 'id', netAmount: 'net_amount' })[p],
+    'dta',
+  )
+
+  it('coerces the STRING values pg actually returns', () => {
+    // numeric -> "18400.0000", int8 -> "7". Un-coerced these render as 0,00.
+    const result = mapAggregateRow(
+      { agg_0: '18400.0000', agg_1: '7', agg_2: null, agg_total: '1240' },
+      plan,
+    )
+    expect(result.values[aggregateKey('grossAmount', 'sum')]).toBe(18400)
+    expect(result.values[aggregateKey('id', 'count')]).toBe(7)
+    expect(result.values[aggregateKey('netAmount', 'min')]).toBeNull()
+    expect(result.total).toBe(1240)
+  })
+
+  it('is always dataset-scoped — that is the entire point of the server aggregate', () => {
+    expect(mapAggregateRow({ agg_total: '0' }, plan).scope).toBe('dataset')
+  })
+
+  it('survives an empty result row', () => {
+    const result = mapAggregateRow(null, plan)
+    expect(result.total).toBe(0)
+    expect(result.values[aggregateKey('grossAmount', 'sum')]).toBeNull()
+  })
+})

package/src/backend/dynamic-table/__tests__/aggregateDimension.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * HEDGE-147 — a `sum` must never add amounts in different currencies together.
+ *
+ * The defect these tests pin: the "By counterparty (sum)" view on
+ * `/backend/invoicing` rendered `TOTAL · ALL 4 MATCHING ROWS · 15 750,00` for
+ * 6 150 PLN + 1 200 EUR − 200 EUR + 8 600 USD. One unlabelled number, on the
+ * only summary line an accountant closes the month from, and nothing on screen
+ * disqualified it.
+ *
+ * The mechanism is `AggregationRule.dimension`: the aggregate is partitioned by
+ * a column (here `currencyCode`) and rendered as one labelled line per slice.
+ */
+import { render } from '@testing-library/react'
+import { computeAggregates } from '../hooks/useGrouping'
+import { formatAggregate, AGGREGATE_UNLABELLED_DIMENSION } from '../utils/formatAggregate'
+import { parseAggregateSpec, AggregateSpecError } from '../server/aggregate'
+import type { ColumnDef } from '../types/index'
+import type { AggregationRule } from '../types/grouping'
+
+const amountCol: ColumnDef = { data: 'grossAmount', type: 'numeric' }
+const columnsByField = new Map<string, ColumnDef>([
+  ['grossAmount', amountCol],
+  ['currencyCode', { data: 'currencyCode' }],
+])
+
+/** The exact dataset from the HEDGE-109 walkthrough that produced 15 750,00. */
+const ROWS = [
+  { grossAmount: '6150.00', currencyCode: 'PLN' },
+  { grossAmount: '1200.00', currencyCode: 'EUR' },
+  { grossAmount: '-200.00', currencyCode: 'EUR' },
+  { grossAmount: '8600.00', currencyCode: 'USD' },
+]
+const ALL = ROWS.map((_, i) => i)
+
+const rule = (over: Partial<AggregationRule> = {}): AggregationRule => ({
+  id: 'agg-grossAmount',
+  field: 'grossAmount',
+  fn: 'sum',
+  ...over,
+})
+
+describe('computeAggregates — dimensioned rules', () => {
+  it('still produces the plain scalar when no dimension is set (unchanged behaviour)', () => {
+    const out = computeAggregates(ROWS, ALL, [rule()], columnsByField)
+    expect(out.values.grossAmount).toBe(15750)
+    expect(out.breakdowns.grossAmount).toBeUndefined()
+  })
+
+  it('splits the sum per currency instead of adding PLN + EUR + USD together', () => {
+    const out = computeAggregates(ROWS, ALL, [rule({ dimension: 'currencyCode' })], columnsByField)
+    expect(out.breakdowns.grossAmount).toEqual([
+      { key: 'PLN', value: 6150 },
+      { key: 'EUR', value: 1000 }, // 1200 + (-200) — netted WITHIN the currency
+      { key: 'USD', value: 8600 },
+    ])
+  })
+
+  it('never lets two currencies land in one slice', () => {
+    const { breakdowns } = computeAggregates(
+      ROWS,
+      ALL,
+      [rule({ dimension: 'currencyCode' })],
+      columnsByField,
+    )
+    const keys = breakdowns.grossAmount.map((e) => e.key)
+    expect(new Set(keys).size).toBe(keys.length)
+    expect(keys.sort()).toEqual(['EUR', 'PLN', 'USD'])
+  })
+
+  it('buckets rows with no currency under the empty key rather than dropping them', () => {
+    const rows = [...ROWS, { grossAmount: '5.00', currencyCode: null }]
+    const { breakdowns } = computeAggregates(
+      rows,
+      rows.map((_, i) => i),
+      [rule({ dimension: 'currencyCode' })],
+      columnsByField,
+    )
+    expect(breakdowns.grossAmount).toContainEqual({ key: '', value: 5 })
+  })
+})
+
+describe('formatAggregate — dimensioned rendering', () => {
+  const renderNode = (node: React.ReactNode) => render(<>{node}</>).container.textContent ?? ''
+
+  it('prints one labelled line per currency, never a single combined figure', () => {
+    const { breakdowns } = computeAggregates(
+      ROWS,
+      ALL,
+      [rule({ dimension: 'currencyCode' })],
+      columnsByField,
+    )
+    const text = renderNode(
+      formatAggregate(15750, amountCol, 'en-US', 'sum', breakdowns.grossAmount),
+    )
+    expect(text).toContain('8,600.00')
+    expect(text).toContain('USD')
+    expect(text).toContain('6,150.00')
+    expect(text).toContain('PLN')
+    expect(text).toContain('1,000.00')
+    expect(text).toContain('EUR')
+    // THE REGRESSION GUARD: the cross-currency total must not be on screen.
+    expect(text).not.toContain('15,750')
+  })
+
+  it('orders slices by magnitude so the dominant figure reads first', () => {
+    const { breakdowns } = computeAggregates(
+      ROWS,
+      ALL,
+      [rule({ dimension: 'currencyCode' })],
+      columnsByField,
+    )
+    const text = renderNode(formatAggregate(0, amountCol, 'en-US', 'sum', breakdowns.grossAmount))
+    expect(text.indexOf('8,600.00')).toBeLessThan(text.indexOf('6,150.00'))
+    expect(text.indexOf('6,150.00')).toBeLessThan(text.indexOf('1,000.00'))
+  })
+
+  it('labels a SINGLE-currency breakdown too — an unlabelled number is the defect', () => {
+    const text = renderNode(
+      formatAggregate(6150, amountCol, 'en-US', 'sum', [{ key: 'PLN', value: 6150 }]),
+    )
+    expect(text).toBe('6,150.00 PLN')
+  })
+
+  it('labels the empty dimension rather than printing a bare number', () => {
+    const text = renderNode(formatAggregate(5, amountCol, 'en-US', 'sum', [{ key: '', value: 5 }]))
+    expect(text).toContain(AGGREGATE_UNLABELLED_DIMENSION)
+  })
+
+  it('a breakdown overrides even a column summaryRenderer', () => {
+    // `summaryRenderer` takes a bare number and so cannot know the currency —
+    // deferring to it would reintroduce the unlabelled total.
+    const text = renderNode(
+      formatAggregate(15750, { ...amountCol, summaryRenderer: (v) => `TOTAL ${v}` }, 'en-US', 'sum', [
+        { key: 'PLN', value: 6150 },
+        { key: 'USD', value: 8600 },
+      ]),
+    )
+    expect(text).not.toContain('15750')
+    expect(text).toContain('PLN')
+    expect(text).toContain('USD')
+  })
+
+  it('falls back to the scalar path when there is no breakdown (unchanged behaviour)', () => {
+    expect(formatAggregate(14145, amountCol, 'en-US', 'sum')).toBe('14,145.00')
+    expect(formatAggregate(14145, amountCol, 'en-US', 'sum', [])).toBe('14,145.00')
+  })
+})
+
+describe('parseAggregateSpec — the dimension is allow-listed like any other field', () => {
+  const fieldMap = {
+    grossAmount: 'grossAmount',
+    netAmount: 'netAmount',
+    currencyCode: 'currencyCode',
+  }
+
+  it('parses the two-part form exactly as before', () => {
+    expect(parseAggregateSpec('grossAmount:sum', fieldMap)).toEqual([
+      { field: 'grossAmount', fn: 'sum', property: 'grossAmount' },
+    ])
+  })
+
+  it('parses the three-part form and resolves the dimension property', () => {
+    expect(parseAggregateSpec('grossAmount:sum:currencyCode', fieldMap)).toEqual([
+      {
+        field: 'grossAmount',
+        fn: 'sum',
+        property: 'grossAmount',
+        dimension: 'currencyCode',
+        dimensionProperty: 'currencyCode',
+      },
+    ])
+  })
+
+  it('refuses a dimension that is not on the allow-list — it reaches SQL as GROUP BY', () => {
+    expect(() => parseAggregateSpec('grossAmount:sum:evil', fieldMap)).toThrow(AggregateSpecError)
+    expect(() => parseAggregateSpec('grossAmount:sum:"; drop table--', fieldMap)).toThrow(
+      AggregateSpecError,
+    )
+  })
+
+  it('refuses an empty dimension rather than silently ignoring it', () => {
+    expect(() => parseAggregateSpec('grossAmount:sum:', fieldMap)).toThrow(AggregateSpecError)
+  })
+
+  it('handles a mixed spec of dimensioned and plain entries', () => {
+    const out = parseAggregateSpec('grossAmount:sum:currencyCode,netAmount:avg', fieldMap)
+    expect(out).toHaveLength(2)
+    expect(out[0].dimension).toBe('currencyCode')
+    expect(out[1].dimension).toBeUndefined()
+  })
+})

package/src/backend/dynamic-table/__tests__/anchoredPosition.test.ts

@@ -0,0 +1,88 @@
+import { computeAnchoredPosition } from '../utils/anchoredPosition';
+
+/**
+ * Pins the placement contract shared by ColumnFilterPopover, SelectMenu and
+ * PerspectiveTabMenu.
+ *
+ * The headline case is the one measured on the real transport list: a column
+ * header near the TOP of a short viewport used to flip its popover upward and
+ * land at `top: -156`, hiding the search box, "Select all" and the first two
+ * options above the window edge.
+ */
+
+const VIEWPORT = { width: 1920, height: 1080 };
+/** A column header on the transport list: 24px tall, sticky near the top. */
+const HEADER = { top: 213, bottom: 237, left: 567, right: 700 };
+
+describe('computeAnchoredPosition', () => {
+  it('opens below when there is room', () => {
+    const p = computeAnchoredPosition(HEADER, VIEWPORT, { width: 268, preferredHeight: 360 });
+    expect(p.flipAbove).toBe(false);
+    expect(p.top).toBe(HEADER.bottom + 4);
+    expect(p.maxHeight).toBe(360);
+  });
+
+  it('REGRESSION: never flips a top-anchored panel off the top of a short viewport', () => {
+    // 560px tall — the viewport the bug was reproduced at. The old code flipped
+    // here because `rect.bottom + 360 > 560`, then translateY(-100%) pushed the
+    // panel to -156.
+    const p = computeAnchoredPosition(HEADER, { width: 1920, height: 560 }, {
+      width: 268,
+      preferredHeight: 360,
+      minHeight: 200,
+    });
+
+    expect(p.flipAbove).toBe(false); // above has only 205px; below has 315px
+    // The panel shrinks instead of moving, and still ends inside the viewport.
+    expect(p.maxHeight).toBeLessThan(360);
+    expect(p.top + p.maxHeight).toBeLessThanOrEqual(560);
+    expect(p.top).toBeGreaterThan(0);
+  });
+
+  it('flips above only when above is genuinely roomier, and then fits', () => {
+    // A trigger low on the page: 900px down a 1080px viewport.
+    const low = { top: 900, bottom: 924, left: 400, right: 560 };
+    const p = computeAnchoredPosition(low, VIEWPORT, { width: 268, preferredHeight: 360 });
+
+    expect(p.flipAbove).toBe(true);
+    expect(p.top).toBe(low.top - 4);
+    // The caller applies translateY(-100%); capping maxHeight at the space
+    // above is what makes that safe. Rendered top = top - maxHeight >= 0.
+    expect(p.top - p.maxHeight).toBeGreaterThanOrEqual(0);
+  });
+
+  it('clamps a right-edge anchor back inside the viewport', () => {
+    // The Configure View drawer sits against the right edge; its selects do too.
+    const nearRight = { top: 300, bottom: 328, left: 1850, right: 1910 };
+    const p = computeAnchoredPosition(nearRight, VIEWPORT, { width: 268, preferredHeight: 280 });
+
+    expect(p.left + 268).toBeLessThanOrEqual(VIEWPORT.width);
+    expect(p.left).toBe(1920 - 268 - 8);
+  });
+
+  it('pins to the left margin rather than hanging off the right', () => {
+    const p = computeAnchoredPosition(HEADER, { width: 200, height: 1080 }, {
+      width: 268, // wider than the viewport itself
+      preferredHeight: 280,
+    });
+    expect(p.left).toBe(8);
+  });
+
+  it('honours align:end for right-aligned panels', () => {
+    const p = computeAnchoredPosition(HEADER, VIEWPORT, {
+      width: 268,
+      preferredHeight: 280,
+      align: 'end',
+    });
+    expect(p.left).toBe(HEADER.right - 268);
+  });
+
+  it('never collapses below minHeight, even with no room either way', () => {
+    const p = computeAnchoredPosition(
+      { top: 100, bottom: 130, left: 10, right: 100 },
+      { width: 1920, height: 160 },
+      { width: 268, preferredHeight: 360, minHeight: 120 },
+    );
+    expect(p.maxHeight).toBe(120);
+  });
+});