@svgrid/enterprise 1.0.1

package/src/index.ts

@@ -0,0 +1,88 @@
+export {
+  setLicenseKey,
+  clearLicenseKey,
+  getLicenseKey,
+  isLicenseKeySet,
+  hasValidLicense,
+  assertProLicensed,
+} from './license'
+
+export {
+  exportGrid,
+  type ExportFormat,
+  type ExportOptions,
+  type ExportColumn,
+  type ExportCellStyle,
+  type ExportStyles,
+  type ExportHeaderFooterLine,
+  type ExportSheet,
+} from './export'
+export { printGrid, type PrintOptions } from './print'
+export {
+  importData,
+  type ImportFormat,
+  type ImportFieldType,
+  type ImportOptions,
+  type ImportResult,
+  type ImportColumnMap,
+  type ImportColumnTypes,
+  type ImportRowError,
+  type ImportValidator,
+} from './import'
+export { installPro, type ProGridApi, type ProAIApi, type ProPivotApi } from './install'
+export {
+  createStagedEditing,
+  type StagedChange,
+  type StagedEditingApi,
+  type StagedEditingEvent,
+} from './staged-editing'
+export { dismissUnlicensedNudge } from './watermark'
+export {
+  showUpgradePrompt,
+  dismissUpgradePrompt,
+  type ProFeatureLabel,
+} from './upgrade-prompt'
+
+export {
+  createPivotModel,
+  pivotAggregators,
+  filterCollapsedPivotRows,
+  type PivotAggregator,
+  type PivotAggregatorId,
+  type PivotConfig,
+  type PivotResult,
+  type PivotRow,
+  type PivotRowKind,
+  type PivotValueConfig,
+} from './pivot'
+
+export {
+  // Provider plumbing
+  setAIProvider,
+  getAIProvider,
+  hasAIProvider,
+  mockAIProvider,
+  type AIProvider,
+  type AIRequest,
+  type AITask,
+  // Filter
+  aiFilter,
+  type AIFilterOptions,
+  type AIFilterResult,
+  type AIFilterClause,
+  type AISortClause,
+  // Smart fill
+  aiSmartFill,
+  type AISmartFillOptions,
+  type AISmartFillResult,
+  type AISmartFillExample,
+  // Summarize
+  aiSummarize,
+  type AISummarizeOptions,
+  type AISummarizeTarget,
+  type AISummary,
+  // Classify
+  aiClassify,
+  type AIClassifyOptions,
+  type AIClassifyResult,
+} from './ai'

package/src/install.ts

@@ -0,0 +1,114 @@
+import type { RowData, TableFeatures, SvGridApi } from '@svgrid/grid'
+import { exportGrid, type ExportOptions } from './export'
+import { printGrid, type PrintOptions } from './print'
+import { importData, type ImportOptions, type ImportResult } from './import'
+import { isLicenseKeySet } from './license'
+import { emitUnlicensedNudge } from './watermark'
+import {
+  aiFilter, aiSmartFill, aiSummarize, aiClassify,
+  type AIFilterOptions, type AIFilterResult,
+  type AISmartFillOptions, type AISmartFillResult,
+  type AISummarizeOptions, type AISummary,
+  type AIClassifyOptions, type AIClassifyResult,
+} from './ai'
+import {
+  createPivotModel,
+  type PivotConfig,
+  type PivotResult,
+} from './pivot'
+
+export type ProAIApi<TData extends RowData> = {
+  /** Natural-language -> filter + sort plan (and optionally apply it). */
+  filter(query: string, opts?: AIFilterOptions): Promise<AIFilterResult>
+  /** Propose values for empty cells based on a few worked examples. */
+  smartFill<TValue = unknown>(opts: AISmartFillOptions): Promise<AISmartFillResult<TValue>>
+  /** One-paragraph + bullets summary of a row, selection, group, or the whole view. */
+  summarize(opts: AISummarizeOptions): Promise<AISummary>
+  /** Classify free-text cells into one of a known set of labels. */
+  classify(opts: AIClassifyOptions): Promise<AIClassifyResult>
+  // TData is referenced so the type stays bound to the row shape even
+  // though the helpers all read through `api.getData()`. Lets callers
+  // get correct inference downstream without explicit generics.
+  readonly _rowType?: TData
+}
+
+export type ProPivotApi<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = {
+  /**
+   * Build a pivot row/column model from the grid's current data. Returns
+   * `{ rows, columns }` you can feed to a separate `<SvGrid>` instance
+   * (the typical pattern - the source grid stays unmodified). Pure: no
+   * mutation, no DOM access.
+   */
+  build(config: PivotConfig<TData>): PivotResult<TFeatures>
+  /**
+   * Build a pivot from an arbitrary array (not necessarily the grid's
+   * data). Useful for previewing a designer's config against a sample
+   * before committing.
+   */
+  buildFrom<TIn extends RowData>(
+    data: ReadonlyArray<TIn>,
+    config: PivotConfig<TIn>,
+  ): PivotResult<TFeatures>
+}
+
+export type ProGridApi<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = SvGridApi<TFeatures, TData> & {
+  /** Export the current visible rows to the chosen format. */
+  exportData(opts: ExportOptions<TData>): Promise<void>
+  /** Open a printable view of the current visible rows in a new window. */
+  print(opts?: PrintOptions<TData>): Promise<void>
+  /** Read an Excel / CSV / TSV / JSON file (or inline text) into typed
+   *  rows. Caller decides whether to commit into the grid or preview
+   *  the parsed result first via the returned `ImportResult`. */
+  importData(opts: ImportOptions<TData>): Promise<ImportResult<TData>>
+  /** AI helpers (Pro). All calls route through a consumer-registered
+   *  AIProvider via setAIProvider(); no model client is bundled. */
+  ai: ProAIApi<TData>
+  /** Pivot table builder (Pro). Pure - returns `{ rows, columns }` you
+   *  hand to a separate `<SvGrid>` instance. */
+  pivot: ProPivotApi<TFeatures, TData>
+}
+
+/**
+ * Augment a SvGridApi instance with Pro methods (`exportData`, `print`,
+ * `ai.*`). Mutates and returns the same object so existing references
+ * keep working.
+ *
+ * If no license key has been set, the Pro methods still function but the
+ * grid shows a small "unlicensed" watermark linking to jqwidgets.com and
+ * the console emits a one-time nudge. Revoked or malformed keys throw on
+ * first call.
+ */
+export function installPro<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>): ProGridApi<TFeatures, TData> {
+  const pro = api as ProGridApi<TFeatures, TData>
+  pro.exportData = (opts) => exportGrid(pro, opts)
+  pro.print = (opts) => printGrid(pro, opts)
+  pro.importData = (opts) => importData(pro, opts)
+  pro.ai = {
+    filter: (query, opts) => aiFilter(pro, query, opts),
+    smartFill: (opts) => aiSmartFill(pro, opts),
+    summarize: (opts) => aiSummarize(pro, opts),
+    classify: (opts) => aiClassify(pro, opts),
+  }
+  pro.pivot = {
+    build: (config) =>
+      createPivotModel<TFeatures, TData>(pro.getData(), config),
+    buildFrom: <TIn extends RowData>(data: ReadonlyArray<TIn>, config: PivotConfig<TIn>) =>
+      // PivotConfig is variance-strict in TIn; the runtime call only needs
+      // the row shape to match config.rows / config.cols field names, which
+      // the caller-side generic enforces.
+      createPivotModel<TFeatures, TIn>(data, config),
+  }
+  // Surface the soft-gate state at install time so the watermark appears
+  // alongside the grid, not just after the user clicks Export.
+  if (!isLicenseKeySet()) emitUnlicensedNudge()
+  return pro
+}

package/src/license.ts

@@ -0,0 +1,90 @@
+// Polite license gate. Not crypto - anyone with devtools can extract the key
+// from a deployed bundle. The point is to make commercial use require a
+// transaction, not to defeat reverse engineering.
+//
+// Behavior matrix:
+//
+//   currentKey state                  -> result
+//   ────────────────────────────────────────────────────────────────────
+//   null (no key set)                 -> soft-gate: watermark + console.log,
+//                                        feature still runs
+//   does not start with "SVPRO-"      -> throws (programmer error)
+//   in REVOKED_KEYS                   -> throws (revoked / leaked / expired)
+//   starts with "SVPRO-DEV" or
+//     "SVPRO-EVAL"                    -> works; one-time console.info notice
+//   any other "SVPRO-..."             -> works silently (paid production)
+
+import { REVOKED_KEYS } from './revoked'
+import { emitUnlicensedNudge } from './watermark'
+import { showUpgradePrompt, type ProFeatureLabel } from './upgrade-prompt'
+
+const VALID_PREFIX = 'SVPRO-'
+let currentKey: string | null = null
+let noticedDev = false
+
+export function setLicenseKey(key: string): void {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('@svgrid/enterprise: setLicenseKey() requires a non-empty string')
+  }
+  currentKey = key
+  noticedDev = false
+}
+
+export function clearLicenseKey(): void {
+  currentKey = null
+  noticedDev = false
+}
+
+export function getLicenseKey(): string | null {
+  return currentKey
+}
+
+/** True if a key is set at all (regardless of validity). */
+export function isLicenseKeySet(): boolean {
+  return currentKey != null
+}
+
+/**
+ * True if the current key passes every check: present, valid prefix, not
+ * revoked. Use this from callers that want to branch on license status
+ * (e.g. UI that hides Pro-only options when unlicensed).
+ */
+export function hasValidLicense(): boolean {
+  if (currentKey == null) return false
+  if (!currentKey.startsWith(VALID_PREFIX)) return false
+  if (REVOKED_KEYS.has(currentKey)) return false
+  return true
+}
+
+export function assertProLicensed(feature?: ProFeatureLabel): void {
+  if (currentKey == null) {
+    // Soft-gate: the feature still runs, but the user gets a watermark +
+    // a one-time console.log nudge directing them to pricing, plus a
+    // contextual moment-of-intent upgrade card naming the feature they
+    // just reached for.
+    emitUnlicensedNudge()
+    showUpgradePrompt(feature)
+    return
+  }
+  if (!currentKey.startsWith(VALID_PREFIX)) {
+    throw new Error(
+      '@svgrid/enterprise: invalid license key format (expected "SVPRO-..." prefix).',
+    )
+  }
+  if (REVOKED_KEYS.has(currentKey)) {
+    throw new Error(
+      '@svgrid/enterprise: this license key has been revoked. ' +
+        'Contact sales@jqwidgets.com for a replacement.',
+    )
+  }
+  if (
+    !noticedDev &&
+    (currentKey.startsWith('SVPRO-DEV') || currentKey.startsWith('SVPRO-EVAL'))
+  ) {
+    // eslint-disable-next-line no-console
+    console.info(
+      '@svgrid/enterprise: using a development / evaluation license. Not for production use.',
+    )
+    noticedDev = true
+  }
+}

package/src/pdfmake-shims.d.ts

@@ -0,0 +1,22 @@
+// Ambient declarations for pdfmake submodules we lazy-import. pdfmake
+// itself ships no .d.ts files and there is no @types/pdfmake on npm that
+// covers `build/*`. Kept as a separate script-style .d.ts (no top-level
+// import/export) so it functions as an ambient declaration, not a module
+// augmentation. Pulled into export.ts via a triple-slash reference so
+// consumers of @svgrid/enterprise pick the declarations up automatically.
+
+declare module 'pdfmake/build/pdfmake' {
+  const pdfMake: {
+    vfs?: Record<string, string>
+    createPdf(definition: unknown): {
+      download(filename: string): void
+      getBlob(callback: (blob: Blob) => void): void
+    }
+  }
+  export default pdfMake
+}
+
+declare module 'pdfmake/build/vfs_fonts' {
+  const vfsFonts: unknown
+  export default vfsFonts
+}

package/src/pivot.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Unit tests for the Pro pivot module: createPivotModel,
+ * filterCollapsedPivotRows, and pivotAggregators.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  createPivotModel,
+  filterCollapsedPivotRows,
+  pivotAggregators,
+  type PivotRow,
+} from './pivot'
+
+type Sale = {
+  region: 'AMER' | 'EMEA' | 'APAC'
+  salesPerson: string
+  quarter: '2026 Q1' | '2026 Q2'
+  amount: number
+  units: number
+}
+
+const facts: Sale[] = [
+  { region: 'AMER', salesPerson: 'Ada',   quarter: '2026 Q1', amount: 100, units: 1 },
+  { region: 'AMER', salesPerson: 'Ada',   quarter: '2026 Q2', amount: 200, units: 2 },
+  { region: 'AMER', salesPerson: 'Linus', quarter: '2026 Q1', amount: 300, units: 3 },
+  { region: 'AMER', salesPerson: 'Linus', quarter: '2026 Q2', amount:  50, units: 1 },
+  { region: 'EMEA', salesPerson: 'Tim',   quarter: '2026 Q1', amount: 400, units: 4 },
+  { region: 'EMEA', salesPerson: 'Tim',   quarter: '2026 Q2', amount: 100, units: 5 },
+]
+
+describe('createPivotModel - shape of the result', () => {
+  it('emits rows for each row-axis level plus a grand-total row', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    // 2 regions × (1 group + N leaves) + grand total = AMER + Ada + Linus + EMEA + Tim + Grand
+    expect(r.rows.length).toBe(6)
+    expect(r.rows.map((row) => row.__pivotKind)).toEqual([
+      'group', 'leaf', 'leaf', 'group', 'leaf', 'grandTotal',
+    ])
+    expect(r.rows.map((row) => row.__pivotLabel)).toEqual([
+      'AMER', 'Ada', 'Linus', 'EMEA', 'Tim', 'Grand total',
+    ])
+  })
+
+  it('marks group rows as expandable and leaf rows as not', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const exp = r.rows.map((row) => row.__pivotExpandable)
+    expect(exp).toEqual([true, false, false, true, false, false])
+  })
+
+  it('points each row.__pivotParentId at its row-axis parent', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const byId = new Map(r.rows.map((row) => [row.__pivotId, row]))
+    const ada = r.rows.find((row) => row.__pivotLabel === 'Ada')!
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    expect(ada.__pivotParentId).toBe(amer.__pivotId)
+    expect(amer.__pivotParentId).toBeNull()
+    expect(byId.get(ada.__pivotParentId!)).toBe(amer)
+  })
+})
+
+describe('createPivotModel - aggregated values', () => {
+  it('computes sum per (row-leaf × col-leaf) cell', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const ada = r.rows.find((row) => row.__pivotLabel === 'Ada')!
+    const q1Col = r.columns
+      .flatMap((c: any) => (c.columns ? c.columns : [c]))
+      .find((c: any) => c.id?.startsWith('pv__') && c.header === 'amount (sum)')
+    expect(q1Col).toBeDefined()
+    // Ada's Q1 sum is 100; Q2 sum is 200. Both leaves exist as separate ids.
+    const q1Id = Object.keys(ada).find((k) => k.startsWith('pv__2026') && k.includes('Q1'))!
+    const q2Id = Object.keys(ada).find((k) => k.startsWith('pv__2026') && k.includes('Q2'))!
+    expect(ada[q1Id]).toBe(100)
+    expect(ada[q2Id]).toBe(200)
+  })
+
+  it('emits a group row with the subtotal across all children', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    const q1Id = Object.keys(amer).find((k) => k.startsWith('pv__2026') && k.includes('Q1'))!
+    // AMER Q1 = Ada (100) + Linus (300) = 400
+    expect(amer[q1Id]).toBe(400)
+  })
+
+  it('emits a grand-total row that sums every fact', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const grand = r.rows.find((row) => row.__pivotKind === 'grandTotal')!
+    const q1Id = Object.keys(grand).find((k) => k.startsWith('pv__2026') && k.includes('Q1'))!
+    // Q1 total: 100 + 300 + 400 = 800
+    expect(grand[q1Id]).toBe(800)
+  })
+
+  it('supports multiple measures (one column per measure × col-axis path)', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region'],
+      cols: ['quarter'],
+      values: [
+        { field: 'amount', agg: 'sum' },
+        { field: 'units',  agg: 'sum' },
+      ],
+    })
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    const amountKeys = Object.keys(amer).filter((k) => k.startsWith('pv__') && k.endsWith('__m0'))
+    const unitsKeys  = Object.keys(amer).filter((k) => k.startsWith('pv__') && k.endsWith('__m1'))
+    // 2 col-axis values (Q1, Q2) + 1 grand-total column = 3 keys per measure
+    expect(amountKeys.length).toBe(3)
+    expect(unitsKeys.length).toBe(3)
+  })
+
+  it('honours a custom aggregator function', () => {
+    // Weighted average via custom function
+    const r = createPivotModel(facts, {
+      rows: ['region'],
+      cols: [],
+      values: [
+        {
+          field: 'amount', label: 'weighted', agg: (vs) => {
+            const ns = vs.map(Number).filter((n) => !Number.isNaN(n))
+            if (ns.length === 0) return 0
+            return ns.reduce((a, b) => a + b, 0) / ns.length
+          },
+        },
+      ],
+    })
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    const k = Object.keys(amer).find((k) => k.startsWith('pv__'))!
+    // AMER amounts: 100, 200, 300, 50 -> avg = 162.5
+    expect(amer[k]).toBeCloseTo(162.5, 5)
+  })
+})
+
+describe('createPivotModel - configuration toggles', () => {
+  it('omits the grand-total row when grandTotalRow=false', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region'],
+      cols: [],
+      values: [{ field: 'amount', agg: 'sum' }],
+      grandTotalRow: false,
+    })
+    expect(r.rows.find((row) => row.__pivotKind === 'grandTotal')).toBeUndefined()
+  })
+
+  it('omits row subtotals when rowSubtotals=false', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+      rowSubtotals: false,
+    })
+    // Only leaves + grand total - no `group` rows.
+    expect(r.rows.filter((row) => row.__pivotKind === 'group')).toEqual([])
+  })
+
+  it('honours a custom rowSort comparator', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region'],
+      cols: [],
+      values: [{ field: 'amount', agg: 'sum' }],
+      rowSort: (a, b) => String(b).localeCompare(String(a)), // reverse-alpha
+    })
+    const regionLabels = r.rows
+      .filter((row) => row.__pivotKind === 'leaf')
+      .map((row) => row.__pivotLabel)
+    expect(regionLabels).toEqual(['EMEA', 'AMER'])
+  })
+})
+
+describe('pivotAggregators - built-ins', () => {
+  it('exposes sum / avg / min / max / count / countDistinct / first / last', () => {
+    expect(Object.keys(pivotAggregators).sort()).toEqual([
+      'avg', 'count', 'countDistinct', 'first', 'last', 'max', 'min', 'sum',
+    ])
+  })
+
+  it('sum + avg coerce non-numeric values to NaN and drop them', () => {
+    expect(pivotAggregators.sum([10, 20, 'oops', null, 30])).toBe(60)
+    expect(pivotAggregators.avg([10, 20, 30])).toBe(20)
+  })
+
+  it('avg returns null for empty inputs (vs. 0, to distinguish from a real 0)', () => {
+    expect(pivotAggregators.avg([])).toBeNull()
+  })
+
+  it('countDistinct deduplicates by strict equality', () => {
+    expect(pivotAggregators.countDistinct(['a', 'a', 'b', 'b', 'c'])).toBe(3)
+  })
+
+  it('first/last pick the corresponding entries', () => {
+    expect(pivotAggregators.first(['x', 'y', 'z'])).toBe('x')
+    expect(pivotAggregators.last(['x', 'y', 'z'])).toBe('z')
+  })
+})
+
+describe('filterCollapsedPivotRows', () => {
+  function pivot() {
+    return createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+  }
+
+  it('returns every row when expanded is `true`', () => {
+    const r = pivot()
+    const out = filterCollapsedPivotRows(r.rows, true)
+    expect(out.length).toBe(r.rows.length)
+  })
+
+  it('hides leaves under collapsed groups (empty expansion set)', () => {
+    const r = pivot()
+    const out = filterCollapsedPivotRows(r.rows, [])
+    // Only top-level groups + grand-total stay; no leaves
+    expect(out.map((row) => row.__pivotLabel)).toEqual(['AMER', 'EMEA', 'Grand total'])
+  })
+
+  it('shows leaves of the one expanded group', () => {
+    const r = pivot()
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    const out = filterCollapsedPivotRows(r.rows, [amer.__pivotId])
+    expect(out.map((row) => row.__pivotLabel)).toEqual([
+      'AMER', 'Ada', 'Linus', 'EMEA', 'Grand total',
+    ])
+  })
+
+  it('accepts a Set as well as an array', () => {
+    const r = pivot()
+    const amer = r.rows.find((row) => row.__pivotLabel === 'AMER')!
+    const out = filterCollapsedPivotRows(r.rows, new Set([amer.__pivotId]))
+    expect(out.find((row) => row.__pivotLabel === 'Ada')).toBeDefined()
+    expect(out.find((row) => row.__pivotLabel === 'Tim')).toBeUndefined()
+  })
+
+  it('does not mutate the input array', () => {
+    const r = pivot()
+    const original = r.rows.slice()
+    filterCollapsedPivotRows(r.rows, [])
+    expect(r.rows).toEqual(original)
+  })
+
+  it('always keeps rows with a null parentId visible (grand total, top groups)', () => {
+    const r = pivot()
+    const out = filterCollapsedPivotRows(r.rows, [])
+    const visibleKinds = out.map((row) => row.__pivotKind)
+    expect(visibleKinds).toContain('grandTotal')
+    expect(visibleKinds.filter((k) => k === 'group').length).toBe(2)
+  })
+})
+
+describe('createPivotModel - tracking via pivotId', () => {
+  it('produces stable pivotIds for the same source data + config', () => {
+    const a = createPivotModel(facts, {
+      rows: ['region'],
+      cols: [],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const b = createPivotModel(facts, {
+      rows: ['region'],
+      cols: [],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    expect(a.rows.map((r) => r.__pivotId)).toEqual(b.rows.map((r) => r.__pivotId))
+  })
+
+  it('every row.__pivotId is unique within one pivot', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const ids = r.rows.map((row) => row.__pivotId)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('every row.__pivotParentId resolves to another row (or null)', () => {
+    const r = createPivotModel(facts, {
+      rows: ['region', 'salesPerson'],
+      cols: ['quarter'],
+      values: [{ field: 'amount', agg: 'sum' }],
+    })
+    const ids = new Set(r.rows.map((row) => row.__pivotId))
+    for (const row of r.rows) {
+      if (row.__pivotParentId === null) continue
+      expect(ids.has(row.__pivotParentId)).toBe(true)
+    }
+  })
+})