@pretable/core 0.7.0 → 0.9.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.d.cts CHANGED
@@ -837,6 +837,17 @@ interface PretableCellRange {
837
837
  endRowId: string;
838
838
  startColumnId: string;
839
839
  endColumnId: string;
840
+ /**
841
+ * Dataset positions of this range's endpoints, when the grid is serving a
842
+ * window under the honesty gate — see
843
+ * {@link PretableIndexedDatasetRowSpan}. Present on every range the grid
844
+ * emits through `onSelectionChange`, and accepted back through the
845
+ * controlled `state.selection` prop so a selection that is persisted and
846
+ * restored stays countable while its rows are evicted. Omitting it on the
847
+ * way back in is safe: the engine recovers the positions by row id from
848
+ * the selection it is replacing.
849
+ */
850
+ datasetRowSpan?: PretableIndexedDatasetRowSpan;
840
851
  }
841
852
  /**
842
853
  * Cell-range selection state including the optional anchor for shift-extension.
@@ -888,10 +899,72 @@ interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId ext
888
899
  readonly rowId: TRowId;
889
900
  readonly columnId: TColumnId;
890
901
  }
902
+ /**
903
+ * Where a cell range's two endpoints sit in the DATASET — the coordinate
904
+ * system `PretableIndexedSelectionWindow` is expressed in, not snapshot
905
+ * indices, which shift under the loaded window every time it moves.
906
+ *
907
+ * Under the honesty gate this is the range's IDENTITY, not an annotation on
908
+ * it: a range named by row ids stops meaning anything once those rows are
909
+ * evicted, because an id cannot be resolved to a position without the row.
910
+ * A dataset position survives the row. So `end - start + 1` stays answerable
911
+ * with nothing loaded, and so does "is this rendered row inside it?".
912
+ *
913
+ * `start`/`end` mirror the range's own `start`/`end` endpoints and are NOT
914
+ * normalized — `start` may exceed `end` for a range dragged upwards. Count
915
+ * and containment order them; keeping the orientation is what lets a range
916
+ * with one evicted endpoint resolve the survivor live and the absentee from
917
+ * memory, instead of guessing which remembered bound belongs to which.
918
+ *
919
+ * @public
920
+ */
921
+ interface PretableIndexedDatasetRowSpan {
922
+ /** Dataset position of the range's `start` endpoint. */
923
+ readonly start: number;
924
+ /** Dataset position of the range's `end` endpoint. */
925
+ readonly end: number;
926
+ /**
927
+ * The population these positions were measured in — `resultMeta.datasetKey`
928
+ * as of the measurement. A re-sort or a filter change re-fills the same
929
+ * dataset positions with different rows, so a span carrying a different key
930
+ * than the window currently reports is not stale-but-usable, it is about a
931
+ * different table. Count and containment both refuse it rather than
932
+ * answering from it: `indexedRangeContainsCell` returns a bare boolean and
933
+ * has no `verified` channel to downgrade through, and a wrong `true` there
934
+ * paints the wrong rows.
935
+ *
936
+ * **This is load-bearing, and it fails CLOSED.** An absent key is not a
937
+ * match — it is the absence of any evidence about the population, which
938
+ * leaves the engine unable to tell a scroll from a re-sort, so it refuses.
939
+ * A grid that publishes `resultMeta.window` but no `resultMeta.datasetKey`
940
+ * therefore gets no span at all: its selections degrade to the loaded
941
+ * window, visibly, in `rowCount` and `verified`. `@pretable/react` warns
942
+ * once when it sees that combination.
943
+ *
944
+ * Local mode is a different case and is genuinely unaffected: with no
945
+ * window there are no dataset positions to record, so there is nothing a
946
+ * key could qualify.
947
+ */
948
+ readonly datasetKey?: string;
949
+ }
891
950
  /** Inclusive data-cell range; group rows can never be endpoints. @public */
892
951
  interface PretableIndexedCellRange<TRowId extends PretableRowId, TColumnId extends string> {
893
952
  readonly start: PretableIndexedCellAddress<TRowId, TColumnId>;
894
953
  readonly end: PretableIndexedCellAddress<TRowId, TColumnId>;
954
+ /**
955
+ * Where `start` and `end` sit in the dataset. Absent in local mode and
956
+ * outside the honesty gate, where dataset positions are meaningless and
957
+ * every endpoint is loaded anyway.
958
+ *
959
+ * Derived by the engine on every write — `setSelection` fills it in from
960
+ * the loaded snapshot, and from the positions the selection being replaced
961
+ * already remembers, so a gesture extending from an EVICTED anchor still
962
+ * produces a countable range. Reconciliation refreshes it. A consumer that
963
+ * echoes a selection back through the controlled `state` prop may
964
+ * round-trip it verbatim, but does not have to: dropping it costs nothing,
965
+ * because the engine recovers it by row id from the selection it replaces.
966
+ */
967
+ readonly datasetRowSpan?: PretableIndexedDatasetRowSpan;
895
968
  }
896
969
  /** Inclusive data-row span stored by its stable endpoint IDs. @public */
897
970
  interface PretableIndexedRowRange<TRowId extends PretableRowId> {
@@ -912,18 +985,109 @@ type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
912
985
  readonly kind: "all";
913
986
  readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
914
987
  };
988
+ /**
989
+ * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
990
+ * {@link PretableIndexedRowSelection}, which is what the engine holds.
991
+ *
992
+ * Same two cases and the same discriminant, because they describe the same
993
+ * thing; only the containers differ. The engine stores a `ReadonlySet` and an
994
+ * opaque normalized interval index, neither of which a consumer can build; this
995
+ * shape takes plain arrays and the engine indexes them at the boundary.
996
+ *
997
+ * The sparseness survives that conversion, which is the point of not flattening
998
+ * this to a list of ids:
999
+ *
1000
+ * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
1001
+ * count — it never enumerates the population, so select-all over a million
1002
+ * rows stays free.
1003
+ * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
1004
+ * span costs two ids rather than 100k.
1005
+ * - `excludedRowIds` is POINTS, not spans, matching what the engine can
1006
+ * actually store: unticking one row out of a symbolic "all" records that
1007
+ * one row. A span-shaped exclusion would read as though it could untick a
1008
+ * range, which nothing here can do.
1009
+ *
1010
+ * @public
1011
+ */
1012
+ type PretableRowSelectionState<TRowId extends PretableRowId> = {
1013
+ readonly kind: "explicit";
1014
+ readonly rowIds: readonly TRowId[];
1015
+ readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
1016
+ readonly excludedRowIds?: readonly TRowId[];
1017
+ } | {
1018
+ readonly kind: "all";
1019
+ readonly excludedRowIds?: readonly TRowId[];
1020
+ };
915
1021
  /** Data-only selection owned by the indexed UI layer. @public */
916
1022
  interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
917
1023
  readonly rows: PretableIndexedRowSelection<TRowId>;
918
1024
  readonly ranges: readonly PretableIndexedCellRange<TRowId, TColumnId>[];
919
1025
  readonly anchor: PretableIndexedCellAddress<TRowId, TColumnId> | null;
920
1026
  }
1027
+ /**
1028
+ * Loaded span, in dataset-index terms, that `reconcileIndexedSelection` uses
1029
+ * to tell an evicted row (outside `[start, start + length)`) from a deleted
1030
+ * one (inside it) — see `resultMeta.window` on `PretableResultMeta`, which
1031
+ * this mirrors with `length` standing in for `rows.length`. `@internal`
1032
+ * rather than derived from `PretableResultMeta` directly: grid-core has no
1033
+ * dependency on the react-level honesty gate that decides whether a window
1034
+ * may be trusted, so callers pass this only once that gate has passed.
1035
+ *
1036
+ * @internal
1037
+ */
1038
+ interface PretableIndexedSelectionWindow {
1039
+ readonly start: number;
1040
+ readonly length: number;
1041
+ /**
1042
+ * `resultMeta.datasetKey` for the population this window is a slice of.
1043
+ * Carried here rather than on a channel of its own because a span is only
1044
+ * meaningful paired with the population it was measured in, and the two
1045
+ * must never be able to disagree — see
1046
+ * {@link PretableIndexedDatasetRowSpan.datasetKey}.
1047
+ *
1048
+ * Absent switches spans off entirely for this window: none are recorded and
1049
+ * none are read back. That is fail-closed by design, not an oversight.
1050
+ */
1051
+ readonly datasetKey?: string;
1052
+ }
921
1053
  /** Header-checkbox state derived without visiting every visible row. @public */
922
1054
  interface PretableIndexedSelectionSummary {
923
1055
  readonly state: "none" | "some" | "all";
924
1056
  readonly selectedCount: number;
925
1057
  readonly visibleCount: number;
926
1058
  }
1059
+ /**
1060
+ * How many data rows the CELL-RANGE slice covers — `ranges`, the slice a
1061
+ * click/shift-click/marquee builds. Distinct from
1062
+ * {@link PretableIndexedSelectionSummary}, which counts the separate sparse
1063
+ * row-selection program behind the checkbox column; the two answer different
1064
+ * questions and neither is derived from the other.
1065
+ *
1066
+ * @public
1067
+ */
1068
+ interface PretableIndexedCellSelectionSummary {
1069
+ /**
1070
+ * Distinct data rows covered, counted by arithmetic over spans — O(ranges),
1071
+ * independent of how many rows are selected or how many are loaded.
1072
+ * Overlapping ranges are unioned, never double-counted.
1073
+ */
1074
+ readonly rowCount: number;
1075
+ /**
1076
+ * Whether every contributing range had both endpoints loaded, so
1077
+ * `rowCount` is a fact about rows that are provably still there.
1078
+ *
1079
+ * `false` means the count came wholly or partly from remembered dataset
1080
+ * positions: the rows are evicted, and a row deleted server-side while
1081
+ * evicted cannot be detected, so `rowCount` may overstate. It is still the
1082
+ * best available number — the loaded-rows-only alternative understates a
1083
+ * genuine selection by whatever fraction is evicted — but it may not be
1084
+ * presented as a proven one. Same rule as `PretableMatchingTotal`'s
1085
+ * `"exact" | "estimate"`: keep the number, qualify the claim, and let the
1086
+ * boundary that must speak a bare integer downgrade (see
1087
+ * `resolveAriaRowCount`).
1088
+ */
1089
+ readonly verified: boolean;
1090
+ }
927
1091
  /** Group and data rows share one focus path while preserving runtime identity. @public */
928
1092
  interface PretableIndexedFocusState<TRowId extends PretableRowId, TColumnId extends string> {
929
1093
  readonly ref: PretableVisibleRowRef<TRowId> | null;
@@ -974,10 +1138,31 @@ interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId,
974
1138
  readonly pageRows?: number;
975
1139
  }) => void;
976
1140
  readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
1141
+ /**
1142
+ * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1143
+ *
1144
+ * The write-side counterpart of `getState().selection.rows`. `setSelection`
1145
+ * cannot do this job: it takes the engine's own containers, which a consumer
1146
+ * has no way to construct.
1147
+ *
1148
+ * Idempotent — applying a value the slice already holds publishes nothing, so
1149
+ * a controlled caller can push on every render without looping.
1150
+ */
1151
+ readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
977
1152
  readonly toggleRowSelection: (rowId: TRowId) => void;
978
1153
  readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
979
1154
  readonly isRowSelected: (rowId: TRowId) => boolean;
980
1155
  readonly getSelectionSummary: () => PretableIndexedSelectionSummary;
1156
+ /**
1157
+ * How many data rows the CELL-RANGE slice covers, and whether that number
1158
+ * is proven. Counted by arithmetic over dataset spans, so it stays correct
1159
+ * — and O(ranges) — while most of the selection is evicted.
1160
+ *
1161
+ * A separate method from {@link getSelectionSummary} because they count
1162
+ * different slices: that one counts the sparse row-selection program the
1163
+ * checkbox column drives, this one counts `selection.ranges`.
1164
+ */
1165
+ readonly getCellSelectionSummary: () => PretableIndexedCellSelectionSummary;
981
1166
  readonly selectAllVisibleRows: () => void;
982
1167
  readonly clearSelection: () => void;
983
1168
  readonly beginEdit: <TColumnId extends ColumnIdOf<TColumns>>(input: {
@@ -1005,8 +1190,31 @@ interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRo
1005
1190
  readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1006
1191
  readonly columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[];
1007
1192
  readonly viewport?: PretableViewportState;
1193
+ /**
1194
+ * @internal Late-bound getter for the loaded span (dataset-index terms)
1195
+ * behind the same honesty gate as `aria-rowindex` and the scroll-extent
1196
+ * spacers — see `WindowSpacers`/`getWindowSpacers` in `@pretable/react`'s
1197
+ * `pretable-model.ts`, which this mirrors and is fed by. Read fresh on
1198
+ * every row-model revision (never cached) so `reconcileIndexedSelection`
1199
+ * can tell an evicted row from a deleted one — see
1200
+ * {@link PretableIndexedSelectionWindow}. Undefined, or a getter that
1201
+ * returns null, reproduces pre-eviction behavior exactly: every absent
1202
+ * row is treated as deleted.
1203
+ */
1204
+ readonly getSelectionWindow?: () => PretableIndexedSelectionWindow | null;
1008
1205
  }
1009
1206
 
1207
+ /**
1208
+ * Render the engine's row-checkbox slice as the shape a consumer can write
1209
+ * back — the inverse of {@link createIndexedRowSelection}.
1210
+ *
1211
+ * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1212
+ * 100k-row span stays its two endpoint ids; nothing here walks a population.
1213
+ *
1214
+ * @public
1215
+ */
1216
+ declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1217
+
1010
1218
  /**
1011
1219
  * Half-open row index range — `start` inclusive, `end` exclusive — used to
1012
1220
  * describe a visible row window without materializing the rows outside it.
@@ -1145,4 +1353,4 @@ declare const numberFormats: {
1145
1353
  readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1146
1354
  };
1147
1355
 
1148
- export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, numberFormats };
1356
+ export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedCellSelectionSummary, type PretableIndexedDatasetRowSpan, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowSelectionState, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, describeRowSelection, numberFormats, type PretableIndexedSelectionWindow as ɵPretableIndexedSelectionWindow };
package/dist/index.d.ts CHANGED
@@ -837,6 +837,17 @@ interface PretableCellRange {
837
837
  endRowId: string;
838
838
  startColumnId: string;
839
839
  endColumnId: string;
840
+ /**
841
+ * Dataset positions of this range's endpoints, when the grid is serving a
842
+ * window under the honesty gate — see
843
+ * {@link PretableIndexedDatasetRowSpan}. Present on every range the grid
844
+ * emits through `onSelectionChange`, and accepted back through the
845
+ * controlled `state.selection` prop so a selection that is persisted and
846
+ * restored stays countable while its rows are evicted. Omitting it on the
847
+ * way back in is safe: the engine recovers the positions by row id from
848
+ * the selection it is replacing.
849
+ */
850
+ datasetRowSpan?: PretableIndexedDatasetRowSpan;
840
851
  }
841
852
  /**
842
853
  * Cell-range selection state including the optional anchor for shift-extension.
@@ -888,10 +899,72 @@ interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId ext
888
899
  readonly rowId: TRowId;
889
900
  readonly columnId: TColumnId;
890
901
  }
902
+ /**
903
+ * Where a cell range's two endpoints sit in the DATASET — the coordinate
904
+ * system `PretableIndexedSelectionWindow` is expressed in, not snapshot
905
+ * indices, which shift under the loaded window every time it moves.
906
+ *
907
+ * Under the honesty gate this is the range's IDENTITY, not an annotation on
908
+ * it: a range named by row ids stops meaning anything once those rows are
909
+ * evicted, because an id cannot be resolved to a position without the row.
910
+ * A dataset position survives the row. So `end - start + 1` stays answerable
911
+ * with nothing loaded, and so does "is this rendered row inside it?".
912
+ *
913
+ * `start`/`end` mirror the range's own `start`/`end` endpoints and are NOT
914
+ * normalized — `start` may exceed `end` for a range dragged upwards. Count
915
+ * and containment order them; keeping the orientation is what lets a range
916
+ * with one evicted endpoint resolve the survivor live and the absentee from
917
+ * memory, instead of guessing which remembered bound belongs to which.
918
+ *
919
+ * @public
920
+ */
921
+ interface PretableIndexedDatasetRowSpan {
922
+ /** Dataset position of the range's `start` endpoint. */
923
+ readonly start: number;
924
+ /** Dataset position of the range's `end` endpoint. */
925
+ readonly end: number;
926
+ /**
927
+ * The population these positions were measured in — `resultMeta.datasetKey`
928
+ * as of the measurement. A re-sort or a filter change re-fills the same
929
+ * dataset positions with different rows, so a span carrying a different key
930
+ * than the window currently reports is not stale-but-usable, it is about a
931
+ * different table. Count and containment both refuse it rather than
932
+ * answering from it: `indexedRangeContainsCell` returns a bare boolean and
933
+ * has no `verified` channel to downgrade through, and a wrong `true` there
934
+ * paints the wrong rows.
935
+ *
936
+ * **This is load-bearing, and it fails CLOSED.** An absent key is not a
937
+ * match — it is the absence of any evidence about the population, which
938
+ * leaves the engine unable to tell a scroll from a re-sort, so it refuses.
939
+ * A grid that publishes `resultMeta.window` but no `resultMeta.datasetKey`
940
+ * therefore gets no span at all: its selections degrade to the loaded
941
+ * window, visibly, in `rowCount` and `verified`. `@pretable/react` warns
942
+ * once when it sees that combination.
943
+ *
944
+ * Local mode is a different case and is genuinely unaffected: with no
945
+ * window there are no dataset positions to record, so there is nothing a
946
+ * key could qualify.
947
+ */
948
+ readonly datasetKey?: string;
949
+ }
891
950
  /** Inclusive data-cell range; group rows can never be endpoints. @public */
892
951
  interface PretableIndexedCellRange<TRowId extends PretableRowId, TColumnId extends string> {
893
952
  readonly start: PretableIndexedCellAddress<TRowId, TColumnId>;
894
953
  readonly end: PretableIndexedCellAddress<TRowId, TColumnId>;
954
+ /**
955
+ * Where `start` and `end` sit in the dataset. Absent in local mode and
956
+ * outside the honesty gate, where dataset positions are meaningless and
957
+ * every endpoint is loaded anyway.
958
+ *
959
+ * Derived by the engine on every write — `setSelection` fills it in from
960
+ * the loaded snapshot, and from the positions the selection being replaced
961
+ * already remembers, so a gesture extending from an EVICTED anchor still
962
+ * produces a countable range. Reconciliation refreshes it. A consumer that
963
+ * echoes a selection back through the controlled `state` prop may
964
+ * round-trip it verbatim, but does not have to: dropping it costs nothing,
965
+ * because the engine recovers it by row id from the selection it replaces.
966
+ */
967
+ readonly datasetRowSpan?: PretableIndexedDatasetRowSpan;
895
968
  }
896
969
  /** Inclusive data-row span stored by its stable endpoint IDs. @public */
897
970
  interface PretableIndexedRowRange<TRowId extends PretableRowId> {
@@ -912,18 +985,109 @@ type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
912
985
  readonly kind: "all";
913
986
  readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
914
987
  };
988
+ /**
989
+ * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
990
+ * {@link PretableIndexedRowSelection}, which is what the engine holds.
991
+ *
992
+ * Same two cases and the same discriminant, because they describe the same
993
+ * thing; only the containers differ. The engine stores a `ReadonlySet` and an
994
+ * opaque normalized interval index, neither of which a consumer can build; this
995
+ * shape takes plain arrays and the engine indexes them at the boundary.
996
+ *
997
+ * The sparseness survives that conversion, which is the point of not flattening
998
+ * this to a list of ids:
999
+ *
1000
+ * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
1001
+ * count — it never enumerates the population, so select-all over a million
1002
+ * rows stays free.
1003
+ * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
1004
+ * span costs two ids rather than 100k.
1005
+ * - `excludedRowIds` is POINTS, not spans, matching what the engine can
1006
+ * actually store: unticking one row out of a symbolic "all" records that
1007
+ * one row. A span-shaped exclusion would read as though it could untick a
1008
+ * range, which nothing here can do.
1009
+ *
1010
+ * @public
1011
+ */
1012
+ type PretableRowSelectionState<TRowId extends PretableRowId> = {
1013
+ readonly kind: "explicit";
1014
+ readonly rowIds: readonly TRowId[];
1015
+ readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
1016
+ readonly excludedRowIds?: readonly TRowId[];
1017
+ } | {
1018
+ readonly kind: "all";
1019
+ readonly excludedRowIds?: readonly TRowId[];
1020
+ };
915
1021
  /** Data-only selection owned by the indexed UI layer. @public */
916
1022
  interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
917
1023
  readonly rows: PretableIndexedRowSelection<TRowId>;
918
1024
  readonly ranges: readonly PretableIndexedCellRange<TRowId, TColumnId>[];
919
1025
  readonly anchor: PretableIndexedCellAddress<TRowId, TColumnId> | null;
920
1026
  }
1027
+ /**
1028
+ * Loaded span, in dataset-index terms, that `reconcileIndexedSelection` uses
1029
+ * to tell an evicted row (outside `[start, start + length)`) from a deleted
1030
+ * one (inside it) — see `resultMeta.window` on `PretableResultMeta`, which
1031
+ * this mirrors with `length` standing in for `rows.length`. `@internal`
1032
+ * rather than derived from `PretableResultMeta` directly: grid-core has no
1033
+ * dependency on the react-level honesty gate that decides whether a window
1034
+ * may be trusted, so callers pass this only once that gate has passed.
1035
+ *
1036
+ * @internal
1037
+ */
1038
+ interface PretableIndexedSelectionWindow {
1039
+ readonly start: number;
1040
+ readonly length: number;
1041
+ /**
1042
+ * `resultMeta.datasetKey` for the population this window is a slice of.
1043
+ * Carried here rather than on a channel of its own because a span is only
1044
+ * meaningful paired with the population it was measured in, and the two
1045
+ * must never be able to disagree — see
1046
+ * {@link PretableIndexedDatasetRowSpan.datasetKey}.
1047
+ *
1048
+ * Absent switches spans off entirely for this window: none are recorded and
1049
+ * none are read back. That is fail-closed by design, not an oversight.
1050
+ */
1051
+ readonly datasetKey?: string;
1052
+ }
921
1053
  /** Header-checkbox state derived without visiting every visible row. @public */
922
1054
  interface PretableIndexedSelectionSummary {
923
1055
  readonly state: "none" | "some" | "all";
924
1056
  readonly selectedCount: number;
925
1057
  readonly visibleCount: number;
926
1058
  }
1059
+ /**
1060
+ * How many data rows the CELL-RANGE slice covers — `ranges`, the slice a
1061
+ * click/shift-click/marquee builds. Distinct from
1062
+ * {@link PretableIndexedSelectionSummary}, which counts the separate sparse
1063
+ * row-selection program behind the checkbox column; the two answer different
1064
+ * questions and neither is derived from the other.
1065
+ *
1066
+ * @public
1067
+ */
1068
+ interface PretableIndexedCellSelectionSummary {
1069
+ /**
1070
+ * Distinct data rows covered, counted by arithmetic over spans — O(ranges),
1071
+ * independent of how many rows are selected or how many are loaded.
1072
+ * Overlapping ranges are unioned, never double-counted.
1073
+ */
1074
+ readonly rowCount: number;
1075
+ /**
1076
+ * Whether every contributing range had both endpoints loaded, so
1077
+ * `rowCount` is a fact about rows that are provably still there.
1078
+ *
1079
+ * `false` means the count came wholly or partly from remembered dataset
1080
+ * positions: the rows are evicted, and a row deleted server-side while
1081
+ * evicted cannot be detected, so `rowCount` may overstate. It is still the
1082
+ * best available number — the loaded-rows-only alternative understates a
1083
+ * genuine selection by whatever fraction is evicted — but it may not be
1084
+ * presented as a proven one. Same rule as `PretableMatchingTotal`'s
1085
+ * `"exact" | "estimate"`: keep the number, qualify the claim, and let the
1086
+ * boundary that must speak a bare integer downgrade (see
1087
+ * `resolveAriaRowCount`).
1088
+ */
1089
+ readonly verified: boolean;
1090
+ }
927
1091
  /** Group and data rows share one focus path while preserving runtime identity. @public */
928
1092
  interface PretableIndexedFocusState<TRowId extends PretableRowId, TColumnId extends string> {
929
1093
  readonly ref: PretableVisibleRowRef<TRowId> | null;
@@ -974,10 +1138,31 @@ interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId,
974
1138
  readonly pageRows?: number;
975
1139
  }) => void;
976
1140
  readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
1141
+ /**
1142
+ * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1143
+ *
1144
+ * The write-side counterpart of `getState().selection.rows`. `setSelection`
1145
+ * cannot do this job: it takes the engine's own containers, which a consumer
1146
+ * has no way to construct.
1147
+ *
1148
+ * Idempotent — applying a value the slice already holds publishes nothing, so
1149
+ * a controlled caller can push on every render without looping.
1150
+ */
1151
+ readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
977
1152
  readonly toggleRowSelection: (rowId: TRowId) => void;
978
1153
  readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
979
1154
  readonly isRowSelected: (rowId: TRowId) => boolean;
980
1155
  readonly getSelectionSummary: () => PretableIndexedSelectionSummary;
1156
+ /**
1157
+ * How many data rows the CELL-RANGE slice covers, and whether that number
1158
+ * is proven. Counted by arithmetic over dataset spans, so it stays correct
1159
+ * — and O(ranges) — while most of the selection is evicted.
1160
+ *
1161
+ * A separate method from {@link getSelectionSummary} because they count
1162
+ * different slices: that one counts the sparse row-selection program the
1163
+ * checkbox column drives, this one counts `selection.ranges`.
1164
+ */
1165
+ readonly getCellSelectionSummary: () => PretableIndexedCellSelectionSummary;
981
1166
  readonly selectAllVisibleRows: () => void;
982
1167
  readonly clearSelection: () => void;
983
1168
  readonly beginEdit: <TColumnId extends ColumnIdOf<TColumns>>(input: {
@@ -1005,8 +1190,31 @@ interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRo
1005
1190
  readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1006
1191
  readonly columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[];
1007
1192
  readonly viewport?: PretableViewportState;
1193
+ /**
1194
+ * @internal Late-bound getter for the loaded span (dataset-index terms)
1195
+ * behind the same honesty gate as `aria-rowindex` and the scroll-extent
1196
+ * spacers — see `WindowSpacers`/`getWindowSpacers` in `@pretable/react`'s
1197
+ * `pretable-model.ts`, which this mirrors and is fed by. Read fresh on
1198
+ * every row-model revision (never cached) so `reconcileIndexedSelection`
1199
+ * can tell an evicted row from a deleted one — see
1200
+ * {@link PretableIndexedSelectionWindow}. Undefined, or a getter that
1201
+ * returns null, reproduces pre-eviction behavior exactly: every absent
1202
+ * row is treated as deleted.
1203
+ */
1204
+ readonly getSelectionWindow?: () => PretableIndexedSelectionWindow | null;
1008
1205
  }
1009
1206
 
1207
+ /**
1208
+ * Render the engine's row-checkbox slice as the shape a consumer can write
1209
+ * back — the inverse of {@link createIndexedRowSelection}.
1210
+ *
1211
+ * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1212
+ * 100k-row span stays its two endpoint ids; nothing here walks a population.
1213
+ *
1214
+ * @public
1215
+ */
1216
+ declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1217
+
1010
1218
  /**
1011
1219
  * Half-open row index range — `start` inclusive, `end` exclusive — used to
1012
1220
  * describe a visible row window without materializing the rows outside it.
@@ -1145,4 +1353,4 @@ declare const numberFormats: {
1145
1353
  readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1146
1354
  };
1147
1355
 
1148
- export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, numberFormats };
1356
+ export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedCellSelectionSummary, type PretableIndexedDatasetRowSpan, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowSelectionState, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, describeRowSelection, numberFormats, type PretableIndexedSelectionWindow as ɵPretableIndexedSelectionWindow };