@pretable/core 0.0.14 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -549,20 +549,23 @@ var NO_OVERRIDES = /* @__PURE__ */ new Set();
549
549
  function deriveVisibleRows(input) {
550
550
  const resolvedFilters = resolveFilters(input.columns, input.filters);
551
551
  const filtered = input.rows.filter((entry) => matchesFilters(entry.row, resolvedFilters));
552
- return buildGroupedRows({
553
- rows: filtered,
554
- // Only worth carrying the pre-filter set when it can actually differ.
555
- // Equal lengths mean the filter removed nothing, so `filtered` is a copy of
556
- // `input.rows` in the same order and the two sort identically —
557
- // `buildGroupedRows` sorts whichever it folds over, so skipping here does
558
- // not change the fold order.
559
- allRows: input.aggregateFilteredRows && filtered.length !== input.rows.length ? input.rows : void 0,
560
- columns: input.columns,
561
- rowGroups: input.rowGroups ?? [],
562
- sort: input.sort,
563
- groupExpansionOverrides: input.groupExpansionOverrides ?? NO_OVERRIDES,
564
- defaultExpanded: input.groupsDefaultExpanded ?? true
565
- });
552
+ return {
553
+ rows: buildGroupedRows({
554
+ rows: filtered,
555
+ // Only worth carrying the pre-filter set when it can actually differ.
556
+ // Equal lengths mean the filter removed nothing, so `filtered` is a copy
557
+ // of `input.rows` in the same order and the two sort identically —
558
+ // `buildGroupedRows` sorts whichever it folds over, so skipping here does
559
+ // not change the fold order.
560
+ allRows: input.aggregateFilteredRows && filtered.length !== input.rows.length ? input.rows : void 0,
561
+ columns: input.columns,
562
+ rowGroups: input.rowGroups ?? [],
563
+ sort: input.sort,
564
+ groupExpansionOverrides: input.groupExpansionOverrides ?? NO_OVERRIDES,
565
+ defaultExpanded: input.groupsDefaultExpanded ?? true
566
+ }),
567
+ filteredCount: filtered.length
568
+ };
566
569
  }
567
570
  function resolveFilters(columns, filters) {
568
571
  const columnMap = new Map(columns.map((c) => [c.id, c]));
@@ -638,8 +641,22 @@ function addGroupExpansionOverride(current, groupId, limit) {
638
641
  return next;
639
642
  }
640
643
 
644
+ // ../grid-core/dist/dev-warn.js
645
+ var warned = /* @__PURE__ */ new Set();
646
+ function warnOnce(key, message) {
647
+ if (warned.has(key)) {
648
+ return;
649
+ }
650
+ warned.add(key);
651
+ console.warn(message);
652
+ }
653
+
641
654
  // ../grid-core/dist/create-grid-core.js
642
655
  var ROW_SELECT_COLUMN_ID = "__pretable_row_select__";
656
+ var NO_FILTERS = {};
657
+ var NO_SORT = [];
658
+ var SUPPLIED_TOTAL_WARN_KEY = "supplied-total-under-engine-filter";
659
+ var SUPPLIED_TOTAL_WARN_MESSAGE = '[pretable] resultMeta.total was supplied while filter authority is "engine". The engine computes the matching total locally from its own filter pass, so the supplied value is ignored \u2014 the two cannot be reconciled. Pass processing: { filter: "external" } if an upstream processor owns filtering.';
643
660
  function isDataRow(entry) {
644
661
  return entry.kind === "data";
645
662
  }
@@ -689,10 +706,14 @@ function createGridCore(inputOptions) {
689
706
  let options = groupedInput.autosize ? applyAutosize(groupedInput, typeof groupedInput.autosize === "object" ? groupedInput.autosize : void 0) : groupedInput;
690
707
  let originalColumns = groupColumnsByPin(inputOptions.columns).map((c) => ({ ...c }));
691
708
  let sourceRows = createSourceRows(options);
709
+ const filterAuthority = options.processing?.filter ?? "engine";
710
+ const sortAuthority = options.processing?.sort ?? "engine";
692
711
  const sourceRowIndex = new Map(sourceRows.map((entry) => [entry.id, entry]));
693
712
  const pinnedWidthColumnIds = /* @__PURE__ */ new Set();
694
713
  let cachedSnapshot = null;
695
- let cachedVisibleRows = null;
714
+ let suppliedTotal = null;
715
+ let datasetKey = null;
716
+ let cachedDerivation = null;
696
717
  let cachedDerivedSort = null;
697
718
  let cachedDerivedFilters = null;
698
719
  let cachedDerivedRowGroups = null;
@@ -718,6 +739,31 @@ function createGridCore(inputOptions) {
718
739
  height: 0,
719
740
  width: 0
720
741
  };
742
+ function isDatasetPivot(next) {
743
+ return typeof next === "string" && datasetKey !== null && next !== datasetKey;
744
+ }
745
+ function clearForDatasetChange() {
746
+ selection = { ranges: [], anchor: null };
747
+ focus = { rowId: null, columnId: null };
748
+ groupExpansionOverrides = /* @__PURE__ */ new Set();
749
+ editing = null;
750
+ suppliedTotal = null;
751
+ }
752
+ function applyResultMeta(meta) {
753
+ if (!meta) {
754
+ return;
755
+ }
756
+ if (typeof meta.datasetKey === "string") {
757
+ datasetKey = meta.datasetKey;
758
+ }
759
+ if (meta.total !== void 0) {
760
+ if (filterAuthority === "external") {
761
+ suppliedTotal = { ...meta.total };
762
+ } else {
763
+ warnOnce(SUPPLIED_TOTAL_WARN_KEY, SUPPLIED_TOTAL_WARN_MESSAGE);
764
+ }
765
+ }
766
+ }
721
767
  const store = {
722
768
  get options() {
723
769
  return options;
@@ -1314,7 +1360,7 @@ function createGridCore(inputOptions) {
1314
1360
  groupExpansionOverrides = /* @__PURE__ */ new Set();
1315
1361
  }
1316
1362
  if (groupingSemanticsChanged) {
1317
- cachedVisibleRows = null;
1363
+ cachedDerivation = null;
1318
1364
  reconcileFocusAfterVisibleModelChange(before);
1319
1365
  }
1320
1366
  const selectionChanged = reconcileSelectionAfterColumnModelChange(beforeColumns);
@@ -1370,11 +1416,15 @@ function createGridCore(inputOptions) {
1370
1416
  sourceRowIndex.set(id, entry);
1371
1417
  }
1372
1418
  }
1373
- cachedVisibleRows = null;
1419
+ cachedDerivation = null;
1374
1420
  reconcileFocusAfterVisibleModelChange(before);
1375
1421
  emit();
1376
1422
  },
1377
- setRows(nextRows) {
1423
+ setRows(nextRows, meta) {
1424
+ if (isDatasetPivot(meta?.datasetKey)) {
1425
+ clearForDatasetChange();
1426
+ }
1427
+ applyResultMeta(meta);
1378
1428
  const before = captureVisibleRowsForFocusReconciliation();
1379
1429
  options = { ...options, rows: nextRows };
1380
1430
  sourceRows = createSourceRows(options);
@@ -1414,10 +1464,27 @@ function createGridCore(inputOptions) {
1414
1464
  })
1415
1465
  };
1416
1466
  }
1417
- cachedVisibleRows = null;
1467
+ cachedDerivation = null;
1418
1468
  reconcileFocusAfterVisibleModelChange(before);
1419
1469
  emit();
1420
1470
  },
1471
+ setResultMeta(meta) {
1472
+ const pivot = isDatasetPivot(meta.datasetKey);
1473
+ const nextKey = typeof meta.datasetKey === "string" ? meta.datasetKey : datasetKey;
1474
+ const nextTotal = meta.total !== void 0 && filterAuthority === "external" ? { ...meta.total } : pivot ? null : suppliedTotal;
1475
+ if (meta.total !== void 0 && filterAuthority !== "external") {
1476
+ warnOnce(SUPPLIED_TOTAL_WARN_KEY, SUPPLIED_TOTAL_WARN_MESSAGE);
1477
+ }
1478
+ if (nextKey === datasetKey && matchingTotalsEqual(nextTotal, suppliedTotal)) {
1479
+ return;
1480
+ }
1481
+ if (pivot) {
1482
+ clearForDatasetChange();
1483
+ }
1484
+ datasetKey = nextKey;
1485
+ suppliedTotal = nextTotal;
1486
+ emit();
1487
+ },
1421
1488
  setRowGroups(columnIds) {
1422
1489
  const next = sanitizeRowGroups(columnIds, options.columns);
1423
1490
  if (stringListsEqual(rowGroups, next)) {
@@ -1716,20 +1783,28 @@ function createGridCore(inputOptions) {
1716
1783
  return cachedSnapshot;
1717
1784
  }
1718
1785
  const aggregateFilteredRows = options.aggregateFilteredRows ?? false;
1719
- const derivedIsFresh = cachedVisibleRows !== null && cachedDerivedSort === sort && cachedDerivedFilters === filters && cachedDerivedRowGroups === rowGroups && cachedDerivedOverrides === groupExpansionOverrides && cachedDerivedDefaultExpanded === groupsDefaultExpanded && cachedDerivedAggregateFiltered === aggregateFilteredRows;
1720
- const visibleRows = derivedIsFresh ? cachedVisibleRows : preserveAggregateIdentity(deriveVisibleRows({
1721
- columns: options.columns,
1722
- filters,
1723
- rows: sourceRows,
1724
- sort,
1725
- rowGroups,
1726
- groupExpansionOverrides,
1727
- groupsDefaultExpanded,
1728
- aggregateFilteredRows
1729
- }));
1730
- cachedVisibleRows = visibleRows;
1731
- cachedDerivedSort = sort;
1732
- cachedDerivedFilters = filters;
1786
+ const derivedFilters = filterAuthority === "external" ? NO_FILTERS : filters;
1787
+ const derivedSort = sortAuthority === "external" ? NO_SORT : sort;
1788
+ const derivedIsFresh = cachedDerivation !== null && cachedDerivedSort === derivedSort && cachedDerivedFilters === derivedFilters && cachedDerivedRowGroups === rowGroups && cachedDerivedOverrides === groupExpansionOverrides && cachedDerivedDefaultExpanded === groupsDefaultExpanded && cachedDerivedAggregateFiltered === aggregateFilteredRows;
1789
+ if (!derivedIsFresh) {
1790
+ const derived = deriveVisibleRows({
1791
+ columns: options.columns,
1792
+ filters: derivedFilters,
1793
+ rows: sourceRows,
1794
+ sort: derivedSort,
1795
+ rowGroups,
1796
+ groupExpansionOverrides,
1797
+ groupsDefaultExpanded,
1798
+ aggregateFilteredRows
1799
+ });
1800
+ cachedDerivation = {
1801
+ rows: preserveAggregateIdentity(derived.rows),
1802
+ filteredCount: derived.filteredCount
1803
+ };
1804
+ }
1805
+ const { rows: visibleRows, filteredCount } = cachedDerivation;
1806
+ cachedDerivedSort = derivedSort;
1807
+ cachedDerivedFilters = derivedFilters;
1733
1808
  cachedDerivedRowGroups = rowGroups;
1734
1809
  cachedDerivedOverrides = groupExpansionOverrides;
1735
1810
  cachedDerivedDefaultExpanded = groupsDefaultExpanded;
@@ -1743,7 +1818,9 @@ function createGridCore(inputOptions) {
1743
1818
  anchor: selection.anchor ? { ...selection.anchor } : null
1744
1819
  },
1745
1820
  focus,
1746
- totalRowCount: sourceRows.length,
1821
+ loadedRowCount: sourceRows.length,
1822
+ matchingTotal: filterAuthority === "external" ? suppliedTotal ? { ...suppliedTotal } : { kind: "unknown" } : { kind: "exact", count: filteredCount },
1823
+ datasetKey,
1747
1824
  visibleRows,
1748
1825
  visibleRange: {
1749
1826
  start: 0,
@@ -1888,6 +1965,18 @@ function filtersEqual(a, b) {
1888
1965
  }
1889
1966
  return true;
1890
1967
  }
1968
+ function matchingTotalsEqual(a, b) {
1969
+ if (a === b) {
1970
+ return true;
1971
+ }
1972
+ if (a === null || b === null) {
1973
+ return false;
1974
+ }
1975
+ if (a.kind === "unknown" || b.kind === "unknown") {
1976
+ return a.kind === "unknown" && b.kind === "unknown" && a.atLeast === b.atLeast;
1977
+ }
1978
+ return a.kind === b.kind && a.count === b.count;
1979
+ }
1891
1980
 
1892
1981
  // src/create-grid.ts
1893
1982
  function createGrid(options) {
@@ -1931,6 +2020,7 @@ function createGrid(options) {
1931
2020
  mergeColumnsFromProps: engine.mergeColumnsFromProps,
1932
2021
  applyTransaction: engine.applyTransaction,
1933
2022
  setRows: engine.setRows,
2023
+ setResultMeta: engine.setResultMeta,
1934
2024
  beginEdit: engine.beginEdit,
1935
2025
  setEditDraft: engine.setEditDraft,
1936
2026
  markEditing: engine.markEditing,
package/dist/index.d.cts CHANGED
@@ -129,6 +129,14 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
129
129
  /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
130
130
  step?: number;
131
131
  filterable?: boolean;
132
+ /**
133
+ * Restrict the filter menu to the operators the processor can honor. Omitted
134
+ * = the full per-type set (today's behavior). Load-bearing under external
135
+ * filter authority: an unpruned menu offers operators the server will ignore.
136
+ *
137
+ * @experimental
138
+ */
139
+ filterOperators?: FilterOperator[];
132
140
  type?: ColumnType;
133
141
  /**
134
142
  * Horizontal alignment of this column's cells and header label. Defaults to
@@ -189,6 +197,44 @@ interface PretableAggregateFormatInput<TRow extends PretableRow = PretableRow> {
189
197
  value: unknown;
190
198
  column: PretableColumn<TRow>;
191
199
  group: PretableGroupRow;
200
+ /**
201
+ * `"loaded"` when the aggregate folded a window onto a larger population, so
202
+ * a sum over 200 loaded rows is never presentable as a population sum. Local
203
+ * mode always passes `"all"`.
204
+ *
205
+ * @experimental
206
+ */
207
+ scope: "all" | "loaded";
208
+ }
209
+ /**
210
+ * Who applies an operation to the loaded records: the engine's derivation
211
+ * pipeline, or an external processor upstream of `setRows` (a server, a worker,
212
+ * a wasm index — the engine does not know or care).
213
+ *
214
+ * @experimental
215
+ * @public
216
+ */
217
+ type PretableProcessingAuthority = "engine" | "external";
218
+ /**
219
+ * Per-operation processing authority. Construction-time: flipping authority is
220
+ * a dataset pivot, so it takes a new grid rather than a mutator.
221
+ *
222
+ * @experimental
223
+ * @public
224
+ */
225
+ interface PretableProcessingOptions {
226
+ /**
227
+ * `"external"`: filter state is displayed (funnel indicators, menu contents,
228
+ * `snapshot.filters`) but never applied to the loaded records. Default
229
+ * `"engine"`.
230
+ */
231
+ filter?: PretableProcessingAuthority;
232
+ /**
233
+ * `"external"`: sort state is displayed (header arrows, priority badges,
234
+ * `snapshot.sort`) but the model order is the supplied record order. Default
235
+ * `"engine"`.
236
+ */
237
+ sort?: PretableProcessingAuthority;
192
238
  }
193
239
  /**
194
240
  * Options accepted by `createGrid`.
@@ -200,6 +246,13 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
200
246
  rows: TRow[];
201
247
  getRowId?: (row: TRow, index: number) => string;
202
248
  autosize?: boolean | AutosizeOptions;
249
+ /**
250
+ * Who applies filtering and sorting to the loaded records. Construction-time
251
+ * only.
252
+ *
253
+ * @experimental
254
+ */
255
+ processing?: PretableProcessingOptions;
203
256
  /**
204
257
  * Fold group aggregates over rows the active filter hides. Default `false`,
205
258
  * so a group total always equals the sum of the rows visible beneath it.
@@ -384,6 +437,52 @@ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
384
437
  * @public
385
438
  */
386
439
  type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
440
+ /**
441
+ * How many records match the fulfilled query — loaded or not. Three kinds
442
+ * because real backends have three answers: SQL gives an exact count,
443
+ * sampling engines give an estimate, and Elasticsearch gives
444
+ * `{ relation: "gte", value: 10000 }`.
445
+ *
446
+ * @experimental
447
+ * @public
448
+ */
449
+ type PretableMatchingTotal = {
450
+ kind: "exact";
451
+ count: number;
452
+ } | {
453
+ kind: "estimate";
454
+ count: number;
455
+ } | {
456
+ kind: "unknown";
457
+ atLeast?: number;
458
+ };
459
+ /**
460
+ * Metadata about the result set the loaded records came from. Supplied
461
+ * alongside `setRows`, or on its own via `setResultMeta`.
462
+ *
463
+ * **Contiguous-from-head contract.** The loaded records must be a prefix of the
464
+ * result set in result order. That is what makes loaded model index `i` equal
465
+ * dataset position `i`, which is what lets the renderer publish global
466
+ * `aria-rowindex` values. Windowed or noncontiguous loading is not
467
+ * representable here and downgrades the ARIA counts.
468
+ *
469
+ * @experimental
470
+ * @public
471
+ */
472
+ interface PretableResultMeta {
473
+ /** Matching total for the result set the loaded records came from. */
474
+ total?: PretableMatchingTotal;
475
+ /**
476
+ * Dataset identity. When this key CHANGES between calls the loaded records
477
+ * answer a different question: the engine clears selection, focus,
478
+ * group-expansion overrides, any in-flight edit, and the previously supplied
479
+ * `total` — pass the new one alongside the key, or the grid reports `unknown`
480
+ * until it arrives. A stable (or omitted) key preserves all of them — the
481
+ * existing streaming guarantees. The first key supplied is an assignment,
482
+ * not a change.
483
+ */
484
+ datasetKey?: string;
485
+ }
387
486
  /**
388
487
  * Read-only state observed via `PretableGrid.getSnapshot`.
389
488
  *
@@ -395,7 +494,23 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
395
494
  filters: Record<string, ColumnFilter>;
396
495
  selection: PretableSelectionState;
397
496
  focus: PretableFocusState;
398
- totalRowCount: number;
497
+ /** Count of loaded source records — not the matching population. */
498
+ loadedRowCount: number;
499
+ /**
500
+ * Engine filter authority: computed locally and always exact (post-filter,
501
+ * pre-grouping). External filter authority: the last supplied
502
+ * `resultMeta.total`, else `{ kind: "unknown" }`.
503
+ *
504
+ * @experimental
505
+ */
506
+ matchingTotal: PretableMatchingTotal;
507
+ /**
508
+ * The last supplied dataset identity; `null` before any. Local mode never
509
+ * changes it.
510
+ *
511
+ * @experimental
512
+ */
513
+ datasetKey: string | null;
399
514
  visibleRows: PretableVisibleRow<TRow>[];
400
515
  visibleRange: PretableRowRange;
401
516
  editing: PretableEditState | null;
@@ -459,6 +574,14 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
459
574
  setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
460
575
  clearFilters(): void;
461
576
  replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
577
+ /**
578
+ * The distinct values a column takes across the LOADED records — never a
579
+ * claim about the matching population. Under external filter authority the
580
+ * loaded records are a window onto the result set, so this list can omit
581
+ * values the user would need to filter for; declare `column.options` to give
582
+ * an enum filter its full universe. The surface dev-warns when a funnel menu
583
+ * falls back to this list in that mode.
584
+ */
462
585
  distinctColumnValues(columnId: string): string[];
463
586
  setSelection(state: PretableSelectionState): void;
464
587
  selectAll(): void;
@@ -507,7 +630,14 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
507
630
  * references whose rows are no longer present. Suited to high-frequency
508
631
  * updates where row identities are stable.
509
632
  */
510
- setRows(rows: TRow[]): void;
633
+ setRows(rows: TRow[], meta?: PretableResultMeta): void;
634
+ /**
635
+ * Update result metadata without a rows replacement — a late-arriving exact
636
+ * count, say. Avoids forcing a fake rows-identity change.
637
+ *
638
+ * @experimental
639
+ */
640
+ setResultMeta(meta: PretableResultMeta): void;
511
641
  beginEdit(addr: PretableCellAddress, opts?: {
512
642
  draft?: unknown;
513
643
  status?: "checking" | "editing";
@@ -540,4 +670,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
540
670
  */
541
671
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
542
672
 
543
- export { type AutosizeOptions, type ColumnAlign, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupColumnOptions, type PretableGroupRow, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
673
+ export { type AutosizeOptions, type ColumnAlign, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupColumnOptions, type PretableGroupRow, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableResultMeta, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
package/dist/index.d.ts CHANGED
@@ -129,6 +129,14 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
129
129
  /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
130
130
  step?: number;
131
131
  filterable?: boolean;
132
+ /**
133
+ * Restrict the filter menu to the operators the processor can honor. Omitted
134
+ * = the full per-type set (today's behavior). Load-bearing under external
135
+ * filter authority: an unpruned menu offers operators the server will ignore.
136
+ *
137
+ * @experimental
138
+ */
139
+ filterOperators?: FilterOperator[];
132
140
  type?: ColumnType;
133
141
  /**
134
142
  * Horizontal alignment of this column's cells and header label. Defaults to
@@ -189,6 +197,44 @@ interface PretableAggregateFormatInput<TRow extends PretableRow = PretableRow> {
189
197
  value: unknown;
190
198
  column: PretableColumn<TRow>;
191
199
  group: PretableGroupRow;
200
+ /**
201
+ * `"loaded"` when the aggregate folded a window onto a larger population, so
202
+ * a sum over 200 loaded rows is never presentable as a population sum. Local
203
+ * mode always passes `"all"`.
204
+ *
205
+ * @experimental
206
+ */
207
+ scope: "all" | "loaded";
208
+ }
209
+ /**
210
+ * Who applies an operation to the loaded records: the engine's derivation
211
+ * pipeline, or an external processor upstream of `setRows` (a server, a worker,
212
+ * a wasm index — the engine does not know or care).
213
+ *
214
+ * @experimental
215
+ * @public
216
+ */
217
+ type PretableProcessingAuthority = "engine" | "external";
218
+ /**
219
+ * Per-operation processing authority. Construction-time: flipping authority is
220
+ * a dataset pivot, so it takes a new grid rather than a mutator.
221
+ *
222
+ * @experimental
223
+ * @public
224
+ */
225
+ interface PretableProcessingOptions {
226
+ /**
227
+ * `"external"`: filter state is displayed (funnel indicators, menu contents,
228
+ * `snapshot.filters`) but never applied to the loaded records. Default
229
+ * `"engine"`.
230
+ */
231
+ filter?: PretableProcessingAuthority;
232
+ /**
233
+ * `"external"`: sort state is displayed (header arrows, priority badges,
234
+ * `snapshot.sort`) but the model order is the supplied record order. Default
235
+ * `"engine"`.
236
+ */
237
+ sort?: PretableProcessingAuthority;
192
238
  }
193
239
  /**
194
240
  * Options accepted by `createGrid`.
@@ -200,6 +246,13 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
200
246
  rows: TRow[];
201
247
  getRowId?: (row: TRow, index: number) => string;
202
248
  autosize?: boolean | AutosizeOptions;
249
+ /**
250
+ * Who applies filtering and sorting to the loaded records. Construction-time
251
+ * only.
252
+ *
253
+ * @experimental
254
+ */
255
+ processing?: PretableProcessingOptions;
203
256
  /**
204
257
  * Fold group aggregates over rows the active filter hides. Default `false`,
205
258
  * so a group total always equals the sum of the rows visible beneath it.
@@ -384,6 +437,52 @@ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
384
437
  * @public
385
438
  */
386
439
  type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
440
+ /**
441
+ * How many records match the fulfilled query — loaded or not. Three kinds
442
+ * because real backends have three answers: SQL gives an exact count,
443
+ * sampling engines give an estimate, and Elasticsearch gives
444
+ * `{ relation: "gte", value: 10000 }`.
445
+ *
446
+ * @experimental
447
+ * @public
448
+ */
449
+ type PretableMatchingTotal = {
450
+ kind: "exact";
451
+ count: number;
452
+ } | {
453
+ kind: "estimate";
454
+ count: number;
455
+ } | {
456
+ kind: "unknown";
457
+ atLeast?: number;
458
+ };
459
+ /**
460
+ * Metadata about the result set the loaded records came from. Supplied
461
+ * alongside `setRows`, or on its own via `setResultMeta`.
462
+ *
463
+ * **Contiguous-from-head contract.** The loaded records must be a prefix of the
464
+ * result set in result order. That is what makes loaded model index `i` equal
465
+ * dataset position `i`, which is what lets the renderer publish global
466
+ * `aria-rowindex` values. Windowed or noncontiguous loading is not
467
+ * representable here and downgrades the ARIA counts.
468
+ *
469
+ * @experimental
470
+ * @public
471
+ */
472
+ interface PretableResultMeta {
473
+ /** Matching total for the result set the loaded records came from. */
474
+ total?: PretableMatchingTotal;
475
+ /**
476
+ * Dataset identity. When this key CHANGES between calls the loaded records
477
+ * answer a different question: the engine clears selection, focus,
478
+ * group-expansion overrides, any in-flight edit, and the previously supplied
479
+ * `total` — pass the new one alongside the key, or the grid reports `unknown`
480
+ * until it arrives. A stable (or omitted) key preserves all of them — the
481
+ * existing streaming guarantees. The first key supplied is an assignment,
482
+ * not a change.
483
+ */
484
+ datasetKey?: string;
485
+ }
387
486
  /**
388
487
  * Read-only state observed via `PretableGrid.getSnapshot`.
389
488
  *
@@ -395,7 +494,23 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
395
494
  filters: Record<string, ColumnFilter>;
396
495
  selection: PretableSelectionState;
397
496
  focus: PretableFocusState;
398
- totalRowCount: number;
497
+ /** Count of loaded source records — not the matching population. */
498
+ loadedRowCount: number;
499
+ /**
500
+ * Engine filter authority: computed locally and always exact (post-filter,
501
+ * pre-grouping). External filter authority: the last supplied
502
+ * `resultMeta.total`, else `{ kind: "unknown" }`.
503
+ *
504
+ * @experimental
505
+ */
506
+ matchingTotal: PretableMatchingTotal;
507
+ /**
508
+ * The last supplied dataset identity; `null` before any. Local mode never
509
+ * changes it.
510
+ *
511
+ * @experimental
512
+ */
513
+ datasetKey: string | null;
399
514
  visibleRows: PretableVisibleRow<TRow>[];
400
515
  visibleRange: PretableRowRange;
401
516
  editing: PretableEditState | null;
@@ -459,6 +574,14 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
459
574
  setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
460
575
  clearFilters(): void;
461
576
  replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
577
+ /**
578
+ * The distinct values a column takes across the LOADED records — never a
579
+ * claim about the matching population. Under external filter authority the
580
+ * loaded records are a window onto the result set, so this list can omit
581
+ * values the user would need to filter for; declare `column.options` to give
582
+ * an enum filter its full universe. The surface dev-warns when a funnel menu
583
+ * falls back to this list in that mode.
584
+ */
462
585
  distinctColumnValues(columnId: string): string[];
463
586
  setSelection(state: PretableSelectionState): void;
464
587
  selectAll(): void;
@@ -507,7 +630,14 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
507
630
  * references whose rows are no longer present. Suited to high-frequency
508
631
  * updates where row identities are stable.
509
632
  */
510
- setRows(rows: TRow[]): void;
633
+ setRows(rows: TRow[], meta?: PretableResultMeta): void;
634
+ /**
635
+ * Update result metadata without a rows replacement — a late-arriving exact
636
+ * count, say. Avoids forcing a fake rows-identity change.
637
+ *
638
+ * @experimental
639
+ */
640
+ setResultMeta(meta: PretableResultMeta): void;
511
641
  beginEdit(addr: PretableCellAddress, opts?: {
512
642
  draft?: unknown;
513
643
  status?: "checking" | "editing";
@@ -540,4 +670,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
540
670
  */
541
671
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
542
672
 
543
- export { type AutosizeOptions, type ColumnAlign, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupColumnOptions, type PretableGroupRow, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
673
+ export { type AutosizeOptions, type ColumnAlign, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupColumnOptions, type PretableGroupRow, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableResultMeta, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
package/dist/index.mjs CHANGED
@@ -547,20 +547,23 @@ var NO_OVERRIDES = /* @__PURE__ */ new Set();
547
547
  function deriveVisibleRows(input) {
548
548
  const resolvedFilters = resolveFilters(input.columns, input.filters);
549
549
  const filtered = input.rows.filter((entry) => matchesFilters(entry.row, resolvedFilters));
550
- return buildGroupedRows({
551
- rows: filtered,
552
- // Only worth carrying the pre-filter set when it can actually differ.
553
- // Equal lengths mean the filter removed nothing, so `filtered` is a copy of
554
- // `input.rows` in the same order and the two sort identically —
555
- // `buildGroupedRows` sorts whichever it folds over, so skipping here does
556
- // not change the fold order.
557
- allRows: input.aggregateFilteredRows && filtered.length !== input.rows.length ? input.rows : void 0,
558
- columns: input.columns,
559
- rowGroups: input.rowGroups ?? [],
560
- sort: input.sort,
561
- groupExpansionOverrides: input.groupExpansionOverrides ?? NO_OVERRIDES,
562
- defaultExpanded: input.groupsDefaultExpanded ?? true
563
- });
550
+ return {
551
+ rows: buildGroupedRows({
552
+ rows: filtered,
553
+ // Only worth carrying the pre-filter set when it can actually differ.
554
+ // Equal lengths mean the filter removed nothing, so `filtered` is a copy
555
+ // of `input.rows` in the same order and the two sort identically —
556
+ // `buildGroupedRows` sorts whichever it folds over, so skipping here does
557
+ // not change the fold order.
558
+ allRows: input.aggregateFilteredRows && filtered.length !== input.rows.length ? input.rows : void 0,
559
+ columns: input.columns,
560
+ rowGroups: input.rowGroups ?? [],
561
+ sort: input.sort,
562
+ groupExpansionOverrides: input.groupExpansionOverrides ?? NO_OVERRIDES,
563
+ defaultExpanded: input.groupsDefaultExpanded ?? true
564
+ }),
565
+ filteredCount: filtered.length
566
+ };
564
567
  }
565
568
  function resolveFilters(columns, filters) {
566
569
  const columnMap = new Map(columns.map((c) => [c.id, c]));
@@ -636,8 +639,22 @@ function addGroupExpansionOverride(current, groupId, limit) {
636
639
  return next;
637
640
  }
638
641
 
642
+ // ../grid-core/dist/dev-warn.js
643
+ var warned = /* @__PURE__ */ new Set();
644
+ function warnOnce(key, message) {
645
+ if (warned.has(key)) {
646
+ return;
647
+ }
648
+ warned.add(key);
649
+ console.warn(message);
650
+ }
651
+
639
652
  // ../grid-core/dist/create-grid-core.js
640
653
  var ROW_SELECT_COLUMN_ID = "__pretable_row_select__";
654
+ var NO_FILTERS = {};
655
+ var NO_SORT = [];
656
+ var SUPPLIED_TOTAL_WARN_KEY = "supplied-total-under-engine-filter";
657
+ var SUPPLIED_TOTAL_WARN_MESSAGE = '[pretable] resultMeta.total was supplied while filter authority is "engine". The engine computes the matching total locally from its own filter pass, so the supplied value is ignored \u2014 the two cannot be reconciled. Pass processing: { filter: "external" } if an upstream processor owns filtering.';
641
658
  function isDataRow(entry) {
642
659
  return entry.kind === "data";
643
660
  }
@@ -687,10 +704,14 @@ function createGridCore(inputOptions) {
687
704
  let options = groupedInput.autosize ? applyAutosize(groupedInput, typeof groupedInput.autosize === "object" ? groupedInput.autosize : void 0) : groupedInput;
688
705
  let originalColumns = groupColumnsByPin(inputOptions.columns).map((c) => ({ ...c }));
689
706
  let sourceRows = createSourceRows(options);
707
+ const filterAuthority = options.processing?.filter ?? "engine";
708
+ const sortAuthority = options.processing?.sort ?? "engine";
690
709
  const sourceRowIndex = new Map(sourceRows.map((entry) => [entry.id, entry]));
691
710
  const pinnedWidthColumnIds = /* @__PURE__ */ new Set();
692
711
  let cachedSnapshot = null;
693
- let cachedVisibleRows = null;
712
+ let suppliedTotal = null;
713
+ let datasetKey = null;
714
+ let cachedDerivation = null;
694
715
  let cachedDerivedSort = null;
695
716
  let cachedDerivedFilters = null;
696
717
  let cachedDerivedRowGroups = null;
@@ -716,6 +737,31 @@ function createGridCore(inputOptions) {
716
737
  height: 0,
717
738
  width: 0
718
739
  };
740
+ function isDatasetPivot(next) {
741
+ return typeof next === "string" && datasetKey !== null && next !== datasetKey;
742
+ }
743
+ function clearForDatasetChange() {
744
+ selection = { ranges: [], anchor: null };
745
+ focus = { rowId: null, columnId: null };
746
+ groupExpansionOverrides = /* @__PURE__ */ new Set();
747
+ editing = null;
748
+ suppliedTotal = null;
749
+ }
750
+ function applyResultMeta(meta) {
751
+ if (!meta) {
752
+ return;
753
+ }
754
+ if (typeof meta.datasetKey === "string") {
755
+ datasetKey = meta.datasetKey;
756
+ }
757
+ if (meta.total !== void 0) {
758
+ if (filterAuthority === "external") {
759
+ suppliedTotal = { ...meta.total };
760
+ } else {
761
+ warnOnce(SUPPLIED_TOTAL_WARN_KEY, SUPPLIED_TOTAL_WARN_MESSAGE);
762
+ }
763
+ }
764
+ }
719
765
  const store = {
720
766
  get options() {
721
767
  return options;
@@ -1312,7 +1358,7 @@ function createGridCore(inputOptions) {
1312
1358
  groupExpansionOverrides = /* @__PURE__ */ new Set();
1313
1359
  }
1314
1360
  if (groupingSemanticsChanged) {
1315
- cachedVisibleRows = null;
1361
+ cachedDerivation = null;
1316
1362
  reconcileFocusAfterVisibleModelChange(before);
1317
1363
  }
1318
1364
  const selectionChanged = reconcileSelectionAfterColumnModelChange(beforeColumns);
@@ -1368,11 +1414,15 @@ function createGridCore(inputOptions) {
1368
1414
  sourceRowIndex.set(id, entry);
1369
1415
  }
1370
1416
  }
1371
- cachedVisibleRows = null;
1417
+ cachedDerivation = null;
1372
1418
  reconcileFocusAfterVisibleModelChange(before);
1373
1419
  emit();
1374
1420
  },
1375
- setRows(nextRows) {
1421
+ setRows(nextRows, meta) {
1422
+ if (isDatasetPivot(meta?.datasetKey)) {
1423
+ clearForDatasetChange();
1424
+ }
1425
+ applyResultMeta(meta);
1376
1426
  const before = captureVisibleRowsForFocusReconciliation();
1377
1427
  options = { ...options, rows: nextRows };
1378
1428
  sourceRows = createSourceRows(options);
@@ -1412,10 +1462,27 @@ function createGridCore(inputOptions) {
1412
1462
  })
1413
1463
  };
1414
1464
  }
1415
- cachedVisibleRows = null;
1465
+ cachedDerivation = null;
1416
1466
  reconcileFocusAfterVisibleModelChange(before);
1417
1467
  emit();
1418
1468
  },
1469
+ setResultMeta(meta) {
1470
+ const pivot = isDatasetPivot(meta.datasetKey);
1471
+ const nextKey = typeof meta.datasetKey === "string" ? meta.datasetKey : datasetKey;
1472
+ const nextTotal = meta.total !== void 0 && filterAuthority === "external" ? { ...meta.total } : pivot ? null : suppliedTotal;
1473
+ if (meta.total !== void 0 && filterAuthority !== "external") {
1474
+ warnOnce(SUPPLIED_TOTAL_WARN_KEY, SUPPLIED_TOTAL_WARN_MESSAGE);
1475
+ }
1476
+ if (nextKey === datasetKey && matchingTotalsEqual(nextTotal, suppliedTotal)) {
1477
+ return;
1478
+ }
1479
+ if (pivot) {
1480
+ clearForDatasetChange();
1481
+ }
1482
+ datasetKey = nextKey;
1483
+ suppliedTotal = nextTotal;
1484
+ emit();
1485
+ },
1419
1486
  setRowGroups(columnIds) {
1420
1487
  const next = sanitizeRowGroups(columnIds, options.columns);
1421
1488
  if (stringListsEqual(rowGroups, next)) {
@@ -1714,20 +1781,28 @@ function createGridCore(inputOptions) {
1714
1781
  return cachedSnapshot;
1715
1782
  }
1716
1783
  const aggregateFilteredRows = options.aggregateFilteredRows ?? false;
1717
- const derivedIsFresh = cachedVisibleRows !== null && cachedDerivedSort === sort && cachedDerivedFilters === filters && cachedDerivedRowGroups === rowGroups && cachedDerivedOverrides === groupExpansionOverrides && cachedDerivedDefaultExpanded === groupsDefaultExpanded && cachedDerivedAggregateFiltered === aggregateFilteredRows;
1718
- const visibleRows = derivedIsFresh ? cachedVisibleRows : preserveAggregateIdentity(deriveVisibleRows({
1719
- columns: options.columns,
1720
- filters,
1721
- rows: sourceRows,
1722
- sort,
1723
- rowGroups,
1724
- groupExpansionOverrides,
1725
- groupsDefaultExpanded,
1726
- aggregateFilteredRows
1727
- }));
1728
- cachedVisibleRows = visibleRows;
1729
- cachedDerivedSort = sort;
1730
- cachedDerivedFilters = filters;
1784
+ const derivedFilters = filterAuthority === "external" ? NO_FILTERS : filters;
1785
+ const derivedSort = sortAuthority === "external" ? NO_SORT : sort;
1786
+ const derivedIsFresh = cachedDerivation !== null && cachedDerivedSort === derivedSort && cachedDerivedFilters === derivedFilters && cachedDerivedRowGroups === rowGroups && cachedDerivedOverrides === groupExpansionOverrides && cachedDerivedDefaultExpanded === groupsDefaultExpanded && cachedDerivedAggregateFiltered === aggregateFilteredRows;
1787
+ if (!derivedIsFresh) {
1788
+ const derived = deriveVisibleRows({
1789
+ columns: options.columns,
1790
+ filters: derivedFilters,
1791
+ rows: sourceRows,
1792
+ sort: derivedSort,
1793
+ rowGroups,
1794
+ groupExpansionOverrides,
1795
+ groupsDefaultExpanded,
1796
+ aggregateFilteredRows
1797
+ });
1798
+ cachedDerivation = {
1799
+ rows: preserveAggregateIdentity(derived.rows),
1800
+ filteredCount: derived.filteredCount
1801
+ };
1802
+ }
1803
+ const { rows: visibleRows, filteredCount } = cachedDerivation;
1804
+ cachedDerivedSort = derivedSort;
1805
+ cachedDerivedFilters = derivedFilters;
1731
1806
  cachedDerivedRowGroups = rowGroups;
1732
1807
  cachedDerivedOverrides = groupExpansionOverrides;
1733
1808
  cachedDerivedDefaultExpanded = groupsDefaultExpanded;
@@ -1741,7 +1816,9 @@ function createGridCore(inputOptions) {
1741
1816
  anchor: selection.anchor ? { ...selection.anchor } : null
1742
1817
  },
1743
1818
  focus,
1744
- totalRowCount: sourceRows.length,
1819
+ loadedRowCount: sourceRows.length,
1820
+ matchingTotal: filterAuthority === "external" ? suppliedTotal ? { ...suppliedTotal } : { kind: "unknown" } : { kind: "exact", count: filteredCount },
1821
+ datasetKey,
1745
1822
  visibleRows,
1746
1823
  visibleRange: {
1747
1824
  start: 0,
@@ -1886,6 +1963,18 @@ function filtersEqual(a, b) {
1886
1963
  }
1887
1964
  return true;
1888
1965
  }
1966
+ function matchingTotalsEqual(a, b) {
1967
+ if (a === b) {
1968
+ return true;
1969
+ }
1970
+ if (a === null || b === null) {
1971
+ return false;
1972
+ }
1973
+ if (a.kind === "unknown" || b.kind === "unknown") {
1974
+ return a.kind === "unknown" && b.kind === "unknown" && a.atLeast === b.atLeast;
1975
+ }
1976
+ return a.kind === b.kind && a.count === b.count;
1977
+ }
1889
1978
 
1890
1979
  // src/create-grid.ts
1891
1980
  function createGrid(options) {
@@ -1929,6 +2018,7 @@ function createGrid(options) {
1929
2018
  mergeColumnsFromProps: engine.mergeColumnsFromProps,
1930
2019
  applyTransaction: engine.applyTransaction,
1931
2020
  setRows: engine.setRows,
2021
+ setResultMeta: engine.setResultMeta,
1932
2022
  beginEdit: engine.beginEdit,
1933
2023
  setEditDraft: engine.setEditDraft,
1934
2024
  markEditing: engine.markEditing,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pretable/core",
3
- "version": "0.0.14",
3
+ "version": "0.1.0",
4
4
  "description": "Framework-agnostic grid state primitives for Pretable.",
5
5
  "license": "MIT",
6
6
  "repository": {