@pretable/core 0.6.2 → 0.8.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/LICENSE CHANGED
@@ -19,3 +19,22 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
21
  SOFTWARE.
22
+
23
+ ---
24
+
25
+ Acknowledgements
26
+
27
+ @chenglou/pretext — MIT, Copyright (c) Pretext contributors
28
+ https://github.com/chenglou/pretext
29
+
30
+ Pretable's text layout predictor (`@pretable-internal/text-core`, together with
31
+ the canvas-backed measurer in `@pretable/react`) follows pretext's two-phase
32
+ design: measure each segment once, cache the result by (segment, font), and then
33
+ decide line breaks with pure arithmetic over those cached widths. Before that,
34
+ pretable modelled a whole font as a single number — pixels per character — and
35
+ wrapped by character count.
36
+
37
+ This is our own implementation against a different API, written independently
38
+ rather than adapted from pretext's source, so this acknowledgement is a courtesy
39
+ rather than a licence obligation. It is recorded because the idea is the load-
40
+ bearing part and it was not ours.
package/dist/index.cjs CHANGED
@@ -917,6 +917,72 @@ function isIndexedRowSelected(selection, ref, snapshot) {
917
917
  return false;
918
918
  return semanticRowSelected(rowSelectionProgram(selection, snapshot), ref.rowId);
919
919
  }
920
+ function createIndexedRowSelection(requested, snapshot) {
921
+ let selection = createEmptyIndexedSelection();
922
+ if (requested.kind === "all") {
923
+ selection = selectAllVisibleRows(selection, snapshot);
924
+ } else {
925
+ for (const rowId of new Set(requested.rowIds)) {
926
+ selection = toggleIndexedRowSelection(selection, rowId, snapshot);
927
+ }
928
+ for (const range of requested.ranges ?? []) {
929
+ selection = selectIndexedRowRange(selection, range.startRowId, range.endRowId, snapshot);
930
+ }
931
+ }
932
+ for (const rowId of new Set(requested.excludedRowIds)) {
933
+ if (!isIndexedRowSelected(selection, dataRef(rowId), snapshot))
934
+ continue;
935
+ selection = toggleIndexedRowSelection(selection, rowId, snapshot);
936
+ }
937
+ return selection.rows;
938
+ }
939
+ function describeRowSelection(rows) {
940
+ const excluded = /* @__PURE__ */ new Set();
941
+ for (const range of rows.excludedRanges ?? []) {
942
+ excluded.add(range.startRowId);
943
+ excluded.add(range.endRowId);
944
+ }
945
+ const excludedRowIds = excluded.size === 0 ? {} : { excludedRowIds: Object.freeze([...excluded]) };
946
+ if (rows.kind === "all") {
947
+ return Object.freeze({ kind: "all", ...excludedRowIds });
948
+ }
949
+ const ranges = [...rows.ranges ?? []].map((range) => Object.freeze({ startRowId: range.startRowId, endRowId: range.endRowId }));
950
+ return Object.freeze({
951
+ kind: "explicit",
952
+ rowIds: Object.freeze([...rows.rowIds]),
953
+ ...ranges.length === 0 ? {} : { ranges: Object.freeze(ranges) },
954
+ ...excludedRowIds
955
+ });
956
+ }
957
+ function sameIndexedRowSelectionValue(left, right) {
958
+ if (left === right)
959
+ return true;
960
+ if (left.kind !== right.kind)
961
+ return false;
962
+ if (!sameRowRangeIndex(left.excludedRanges, right.excludedRanges))
963
+ return false;
964
+ if (left.kind !== "explicit" || right.kind !== "explicit")
965
+ return true;
966
+ if (left.rowIds.size !== right.rowIds.size)
967
+ return false;
968
+ for (const rowId of left.rowIds) {
969
+ if (!right.rowIds.has(rowId))
970
+ return false;
971
+ }
972
+ return sameRowRangeIndex(left.ranges, right.ranges);
973
+ }
974
+ function sameRowRangeIndex(left, right) {
975
+ if (left === right)
976
+ return true;
977
+ if ((left?.size ?? 0) !== (right?.size ?? 0))
978
+ return false;
979
+ const leftRanges = [...left ?? []];
980
+ const rightRanges = [...right ?? []];
981
+ return leftRanges.every((range, index) => {
982
+ const other = rightRanges[index];
983
+ return other !== void 0 && sameRowId(range.startRowId, other.startRowId) && sameRowId(range.endRowId, other.endRowId);
984
+ });
985
+ }
920
986
  function getIndexedSelectionSummary(selection, snapshot) {
921
987
  const visibleCount2 = snapshot.visibleDataRowCount;
922
988
  const selectedCount = projectionFor(rowSelectionProgram(selection, snapshot), snapshot).runs?.selectedCount ?? 0;
@@ -1323,6 +1389,22 @@ function createGridUiCore(options) {
1323
1389
  publish({ ...state, selection: next });
1324
1390
  });
1325
1391
  },
1392
+ setRowSelection(rows) {
1393
+ command(() => {
1394
+ let nextRows;
1395
+ try {
1396
+ nextRows = createIndexedRowSelection(rows, snapshotForInteraction());
1397
+ } catch (cause) {
1398
+ throw observationError("The supplied row selection could not be applied atomically.", cause);
1399
+ }
1400
+ if (sameIndexedRowSelectionValue(state.selection.rows, nextRows))
1401
+ return;
1402
+ publish({
1403
+ ...state,
1404
+ selection: Object.freeze({ ...state.selection, rows: nextRows })
1405
+ });
1406
+ });
1407
+ },
1326
1408
  toggleRowSelection(rowId) {
1327
1409
  command(() => {
1328
1410
  let next;
@@ -2002,9 +2084,14 @@ function validateFilterOperand(column, filter, path) {
2002
2084
  }
2003
2085
  if (!Array.isArray(value))
2004
2086
  fail("selection operand must be an array", path, column.id);
2005
- const expected = column.type === "boolean" ? "boolean" : "string";
2006
- if (value.some((entry) => typeof entry !== expected)) {
2007
- fail(`${column.type} selection must contain only ${expected} values`, path, column.id);
2087
+ if (column.type === "boolean") {
2088
+ if (value.some((entry) => typeof entry !== "boolean" && entry !== "true" && entry !== "false")) {
2089
+ fail('boolean selection must contain only boolean values or the strings "true"/"false"', path, column.id);
2090
+ }
2091
+ return;
2092
+ }
2093
+ if (value.some((entry) => typeof entry !== "string")) {
2094
+ fail(`${column.type} selection must contain only string values`, path, column.id);
2008
2095
  }
2009
2096
  }
2010
2097
  function validateQuery(query, columns) {
@@ -8390,4 +8477,5 @@ exports.PretableUnsupportedRowUpdateError = PretableUnsupportedRowUpdateError;
8390
8477
  exports.createColumnHelper = createColumnHelper2;
8391
8478
  exports.createGrid = createGrid;
8392
8479
  exports.createLocalRowModel = createLocalRowModel2;
8480
+ exports.describeRowSelection = describeRowSelection;
8393
8481
  exports.numberFormats = numberFormats;
package/dist/index.d.cts CHANGED
@@ -64,6 +64,12 @@ interface PretableColumnDefinition<TRow extends object, TId extends string, TVal
64
64
  readonly value: (row: TRow) => TValue;
65
65
  readonly compare?: (left: TValue, right: TValue) => number;
66
66
  readonly aggregate?: TAggregate;
67
+ /**
68
+ * Native number presentation. Outranked by `format` for data cells and by
69
+ * `formatAggregate` for group aggregates; derivation, editing, and every
70
+ * row-model read continue to see the raw value.
71
+ */
72
+ readonly numberFormat?: Intl.NumberFormatOptions;
67
73
  readonly format?: (input: PretableFormatInput<TRow, TValue, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
68
74
  readonly formatAggregate?: (input: PretableAggregateFormatInput<PretableAggregateOutputOf<TAggregate>, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
69
75
  readonly [columnDescriptor]: {
@@ -90,6 +96,8 @@ type PretableColumnOptions<TRow extends object, TId extends string, TValue, TTyp
90
96
  readonly header?: string;
91
97
  readonly compare?: (left: TValue, right: TValue) => number;
92
98
  readonly aggregate?: TAggregate;
99
+ /** Native number presentation; `format` outranks it for data cells. */
100
+ readonly numberFormat?: Intl.NumberFormatOptions;
93
101
  readonly format?: (input: {
94
102
  readonly value: TValue;
95
103
  readonly row: TRow;
@@ -107,6 +115,8 @@ interface PretableColumnHelper<TRow extends object> {
107
115
  readonly header?: string;
108
116
  readonly compare?: (left: TValue, right: TValue) => number;
109
117
  readonly aggregate?: TAggregate;
118
+ /** Native number presentation; `format` outranks it for data cells. */
119
+ readonly numberFormat?: Intl.NumberFormatOptions;
110
120
  readonly format?: (input: {
111
121
  readonly value: TValue;
112
122
  readonly row: TRow;
@@ -784,6 +794,20 @@ interface PretableResultMeta {
784
794
  total?: PretableMatchingTotal;
785
795
  /** Stable identity for the query/result population represented by the rows. */
786
796
  datasetKey?: string;
797
+ /**
798
+ * Where the loaded rows sit inside the population, when they are a window
799
+ * rather than a prefix. Absent means the classic prefix case.
800
+ *
801
+ * `hasMore` rather than a remaining count: a keyset cursor walks forward, so
802
+ * the extent must promise only what is fetchable. A count would invite a
803
+ * scrollbar that reaches rows the cursor cannot serve.
804
+ */
805
+ window?: {
806
+ /** Dataset index of `rows[0]`. */
807
+ readonly start: number;
808
+ /** Whether anything follows this window. NOT how much. */
809
+ readonly hasMore: boolean;
810
+ };
787
811
  }
788
812
  /**
789
813
  * One entry in the ordered sort list; index in the list = priority.
@@ -888,6 +912,39 @@ type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
888
912
  readonly kind: "all";
889
913
  readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
890
914
  };
915
+ /**
916
+ * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
917
+ * {@link PretableIndexedRowSelection}, which is what the engine holds.
918
+ *
919
+ * Same two cases and the same discriminant, because they describe the same
920
+ * thing; only the containers differ. The engine stores a `ReadonlySet` and an
921
+ * opaque normalized interval index, neither of which a consumer can build; this
922
+ * shape takes plain arrays and the engine indexes them at the boundary.
923
+ *
924
+ * The sparseness survives that conversion, which is the point of not flattening
925
+ * this to a list of ids:
926
+ *
927
+ * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
928
+ * count — it never enumerates the population, so select-all over a million
929
+ * rows stays free.
930
+ * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
931
+ * span costs two ids rather than 100k.
932
+ * - `excludedRowIds` is POINTS, not spans, matching what the engine can
933
+ * actually store: unticking one row out of a symbolic "all" records that
934
+ * one row. A span-shaped exclusion would read as though it could untick a
935
+ * range, which nothing here can do.
936
+ *
937
+ * @public
938
+ */
939
+ type PretableRowSelectionState<TRowId extends PretableRowId> = {
940
+ readonly kind: "explicit";
941
+ readonly rowIds: readonly TRowId[];
942
+ readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
943
+ readonly excludedRowIds?: readonly TRowId[];
944
+ } | {
945
+ readonly kind: "all";
946
+ readonly excludedRowIds?: readonly TRowId[];
947
+ };
891
948
  /** Data-only selection owned by the indexed UI layer. @public */
892
949
  interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
893
950
  readonly rows: PretableIndexedRowSelection<TRowId>;
@@ -950,6 +1007,17 @@ interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId,
950
1007
  readonly pageRows?: number;
951
1008
  }) => void;
952
1009
  readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
1010
+ /**
1011
+ * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1012
+ *
1013
+ * The write-side counterpart of `getState().selection.rows`. `setSelection`
1014
+ * cannot do this job: it takes the engine's own containers, which a consumer
1015
+ * has no way to construct.
1016
+ *
1017
+ * Idempotent — applying a value the slice already holds publishes nothing, so
1018
+ * a controlled caller can push on every render without looping.
1019
+ */
1020
+ readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
953
1021
  readonly toggleRowSelection: (rowId: TRowId) => void;
954
1022
  readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
955
1023
  readonly isRowSelected: (rowId: TRowId) => boolean;
@@ -983,6 +1051,17 @@ interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRo
983
1051
  readonly viewport?: PretableViewportState;
984
1052
  }
985
1053
 
1054
+ /**
1055
+ * Render the engine's row-checkbox slice as the shape a consumer can write
1056
+ * back — the inverse of {@link createIndexedRowSelection}.
1057
+ *
1058
+ * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1059
+ * 100k-row span stays its two endpoint ids; nothing here walks a population.
1060
+ *
1061
+ * @public
1062
+ */
1063
+ declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1064
+
986
1065
  /**
987
1066
  * Half-open row index range — `start` inclusive, `end` exclusive — used to
988
1067
  * describe a visible row window without materializing the rows outside it.
@@ -1121,4 +1200,4 @@ declare const numberFormats: {
1121
1200
  readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1122
1201
  };
1123
1202
 
1124
- 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 };
1203
+ 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 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 };
package/dist/index.d.ts CHANGED
@@ -64,6 +64,12 @@ interface PretableColumnDefinition<TRow extends object, TId extends string, TVal
64
64
  readonly value: (row: TRow) => TValue;
65
65
  readonly compare?: (left: TValue, right: TValue) => number;
66
66
  readonly aggregate?: TAggregate;
67
+ /**
68
+ * Native number presentation. Outranked by `format` for data cells and by
69
+ * `formatAggregate` for group aggregates; derivation, editing, and every
70
+ * row-model read continue to see the raw value.
71
+ */
72
+ readonly numberFormat?: Intl.NumberFormatOptions;
67
73
  readonly format?: (input: PretableFormatInput<TRow, TValue, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
68
74
  readonly formatAggregate?: (input: PretableAggregateFormatInput<PretableAggregateOutputOf<TAggregate>, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
69
75
  readonly [columnDescriptor]: {
@@ -90,6 +96,8 @@ type PretableColumnOptions<TRow extends object, TId extends string, TValue, TTyp
90
96
  readonly header?: string;
91
97
  readonly compare?: (left: TValue, right: TValue) => number;
92
98
  readonly aggregate?: TAggregate;
99
+ /** Native number presentation; `format` outranks it for data cells. */
100
+ readonly numberFormat?: Intl.NumberFormatOptions;
93
101
  readonly format?: (input: {
94
102
  readonly value: TValue;
95
103
  readonly row: TRow;
@@ -107,6 +115,8 @@ interface PretableColumnHelper<TRow extends object> {
107
115
  readonly header?: string;
108
116
  readonly compare?: (left: TValue, right: TValue) => number;
109
117
  readonly aggregate?: TAggregate;
118
+ /** Native number presentation; `format` outranks it for data cells. */
119
+ readonly numberFormat?: Intl.NumberFormatOptions;
110
120
  readonly format?: (input: {
111
121
  readonly value: TValue;
112
122
  readonly row: TRow;
@@ -784,6 +794,20 @@ interface PretableResultMeta {
784
794
  total?: PretableMatchingTotal;
785
795
  /** Stable identity for the query/result population represented by the rows. */
786
796
  datasetKey?: string;
797
+ /**
798
+ * Where the loaded rows sit inside the population, when they are a window
799
+ * rather than a prefix. Absent means the classic prefix case.
800
+ *
801
+ * `hasMore` rather than a remaining count: a keyset cursor walks forward, so
802
+ * the extent must promise only what is fetchable. A count would invite a
803
+ * scrollbar that reaches rows the cursor cannot serve.
804
+ */
805
+ window?: {
806
+ /** Dataset index of `rows[0]`. */
807
+ readonly start: number;
808
+ /** Whether anything follows this window. NOT how much. */
809
+ readonly hasMore: boolean;
810
+ };
787
811
  }
788
812
  /**
789
813
  * One entry in the ordered sort list; index in the list = priority.
@@ -888,6 +912,39 @@ type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
888
912
  readonly kind: "all";
889
913
  readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
890
914
  };
915
+ /**
916
+ * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
917
+ * {@link PretableIndexedRowSelection}, which is what the engine holds.
918
+ *
919
+ * Same two cases and the same discriminant, because they describe the same
920
+ * thing; only the containers differ. The engine stores a `ReadonlySet` and an
921
+ * opaque normalized interval index, neither of which a consumer can build; this
922
+ * shape takes plain arrays and the engine indexes them at the boundary.
923
+ *
924
+ * The sparseness survives that conversion, which is the point of not flattening
925
+ * this to a list of ids:
926
+ *
927
+ * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
928
+ * count — it never enumerates the population, so select-all over a million
929
+ * rows stays free.
930
+ * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
931
+ * span costs two ids rather than 100k.
932
+ * - `excludedRowIds` is POINTS, not spans, matching what the engine can
933
+ * actually store: unticking one row out of a symbolic "all" records that
934
+ * one row. A span-shaped exclusion would read as though it could untick a
935
+ * range, which nothing here can do.
936
+ *
937
+ * @public
938
+ */
939
+ type PretableRowSelectionState<TRowId extends PretableRowId> = {
940
+ readonly kind: "explicit";
941
+ readonly rowIds: readonly TRowId[];
942
+ readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
943
+ readonly excludedRowIds?: readonly TRowId[];
944
+ } | {
945
+ readonly kind: "all";
946
+ readonly excludedRowIds?: readonly TRowId[];
947
+ };
891
948
  /** Data-only selection owned by the indexed UI layer. @public */
892
949
  interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
893
950
  readonly rows: PretableIndexedRowSelection<TRowId>;
@@ -950,6 +1007,17 @@ interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId,
950
1007
  readonly pageRows?: number;
951
1008
  }) => void;
952
1009
  readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
1010
+ /**
1011
+ * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1012
+ *
1013
+ * The write-side counterpart of `getState().selection.rows`. `setSelection`
1014
+ * cannot do this job: it takes the engine's own containers, which a consumer
1015
+ * has no way to construct.
1016
+ *
1017
+ * Idempotent — applying a value the slice already holds publishes nothing, so
1018
+ * a controlled caller can push on every render without looping.
1019
+ */
1020
+ readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
953
1021
  readonly toggleRowSelection: (rowId: TRowId) => void;
954
1022
  readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
955
1023
  readonly isRowSelected: (rowId: TRowId) => boolean;
@@ -983,6 +1051,17 @@ interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRo
983
1051
  readonly viewport?: PretableViewportState;
984
1052
  }
985
1053
 
1054
+ /**
1055
+ * Render the engine's row-checkbox slice as the shape a consumer can write
1056
+ * back — the inverse of {@link createIndexedRowSelection}.
1057
+ *
1058
+ * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1059
+ * 100k-row span stays its two endpoint ids; nothing here walks a population.
1060
+ *
1061
+ * @public
1062
+ */
1063
+ declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1064
+
986
1065
  /**
987
1066
  * Half-open row index range — `start` inclusive, `end` exclusive — used to
988
1067
  * describe a visible row window without materializing the rows outside it.
@@ -1121,4 +1200,4 @@ declare const numberFormats: {
1121
1200
  readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1122
1201
  };
1123
1202
 
1124
- 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 };
1203
+ 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 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 };
package/dist/index.mjs CHANGED
@@ -915,6 +915,72 @@ function isIndexedRowSelected(selection, ref, snapshot) {
915
915
  return false;
916
916
  return semanticRowSelected(rowSelectionProgram(selection, snapshot), ref.rowId);
917
917
  }
918
+ function createIndexedRowSelection(requested, snapshot) {
919
+ let selection = createEmptyIndexedSelection();
920
+ if (requested.kind === "all") {
921
+ selection = selectAllVisibleRows(selection, snapshot);
922
+ } else {
923
+ for (const rowId of new Set(requested.rowIds)) {
924
+ selection = toggleIndexedRowSelection(selection, rowId, snapshot);
925
+ }
926
+ for (const range of requested.ranges ?? []) {
927
+ selection = selectIndexedRowRange(selection, range.startRowId, range.endRowId, snapshot);
928
+ }
929
+ }
930
+ for (const rowId of new Set(requested.excludedRowIds)) {
931
+ if (!isIndexedRowSelected(selection, dataRef(rowId), snapshot))
932
+ continue;
933
+ selection = toggleIndexedRowSelection(selection, rowId, snapshot);
934
+ }
935
+ return selection.rows;
936
+ }
937
+ function describeRowSelection(rows) {
938
+ const excluded = /* @__PURE__ */ new Set();
939
+ for (const range of rows.excludedRanges ?? []) {
940
+ excluded.add(range.startRowId);
941
+ excluded.add(range.endRowId);
942
+ }
943
+ const excludedRowIds = excluded.size === 0 ? {} : { excludedRowIds: Object.freeze([...excluded]) };
944
+ if (rows.kind === "all") {
945
+ return Object.freeze({ kind: "all", ...excludedRowIds });
946
+ }
947
+ const ranges = [...rows.ranges ?? []].map((range) => Object.freeze({ startRowId: range.startRowId, endRowId: range.endRowId }));
948
+ return Object.freeze({
949
+ kind: "explicit",
950
+ rowIds: Object.freeze([...rows.rowIds]),
951
+ ...ranges.length === 0 ? {} : { ranges: Object.freeze(ranges) },
952
+ ...excludedRowIds
953
+ });
954
+ }
955
+ function sameIndexedRowSelectionValue(left, right) {
956
+ if (left === right)
957
+ return true;
958
+ if (left.kind !== right.kind)
959
+ return false;
960
+ if (!sameRowRangeIndex(left.excludedRanges, right.excludedRanges))
961
+ return false;
962
+ if (left.kind !== "explicit" || right.kind !== "explicit")
963
+ return true;
964
+ if (left.rowIds.size !== right.rowIds.size)
965
+ return false;
966
+ for (const rowId of left.rowIds) {
967
+ if (!right.rowIds.has(rowId))
968
+ return false;
969
+ }
970
+ return sameRowRangeIndex(left.ranges, right.ranges);
971
+ }
972
+ function sameRowRangeIndex(left, right) {
973
+ if (left === right)
974
+ return true;
975
+ if ((left?.size ?? 0) !== (right?.size ?? 0))
976
+ return false;
977
+ const leftRanges = [...left ?? []];
978
+ const rightRanges = [...right ?? []];
979
+ return leftRanges.every((range, index) => {
980
+ const other = rightRanges[index];
981
+ return other !== void 0 && sameRowId(range.startRowId, other.startRowId) && sameRowId(range.endRowId, other.endRowId);
982
+ });
983
+ }
918
984
  function getIndexedSelectionSummary(selection, snapshot) {
919
985
  const visibleCount2 = snapshot.visibleDataRowCount;
920
986
  const selectedCount = projectionFor(rowSelectionProgram(selection, snapshot), snapshot).runs?.selectedCount ?? 0;
@@ -1321,6 +1387,22 @@ function createGridUiCore(options) {
1321
1387
  publish({ ...state, selection: next });
1322
1388
  });
1323
1389
  },
1390
+ setRowSelection(rows) {
1391
+ command(() => {
1392
+ let nextRows;
1393
+ try {
1394
+ nextRows = createIndexedRowSelection(rows, snapshotForInteraction());
1395
+ } catch (cause) {
1396
+ throw observationError("The supplied row selection could not be applied atomically.", cause);
1397
+ }
1398
+ if (sameIndexedRowSelectionValue(state.selection.rows, nextRows))
1399
+ return;
1400
+ publish({
1401
+ ...state,
1402
+ selection: Object.freeze({ ...state.selection, rows: nextRows })
1403
+ });
1404
+ });
1405
+ },
1324
1406
  toggleRowSelection(rowId) {
1325
1407
  command(() => {
1326
1408
  let next;
@@ -2000,9 +2082,14 @@ function validateFilterOperand(column, filter, path) {
2000
2082
  }
2001
2083
  if (!Array.isArray(value))
2002
2084
  fail("selection operand must be an array", path, column.id);
2003
- const expected = column.type === "boolean" ? "boolean" : "string";
2004
- if (value.some((entry) => typeof entry !== expected)) {
2005
- fail(`${column.type} selection must contain only ${expected} values`, path, column.id);
2085
+ if (column.type === "boolean") {
2086
+ if (value.some((entry) => typeof entry !== "boolean" && entry !== "true" && entry !== "false")) {
2087
+ fail('boolean selection must contain only boolean values or the strings "true"/"false"', path, column.id);
2088
+ }
2089
+ return;
2090
+ }
2091
+ if (value.some((entry) => typeof entry !== "string")) {
2092
+ fail(`${column.type} selection must contain only string values`, path, column.id);
2006
2093
  }
2007
2094
  }
2008
2095
  function validateQuery(query, columns) {
@@ -8377,4 +8464,4 @@ var numberFormats = {
8377
8464
  }
8378
8465
  };
8379
8466
 
8380
- export { GROUP_COLUMN_ID, PretableDisposedModelError, PretableInvalidGroupKeyError, PretableReentrantMutationError, PretableRowIdentityChangeError, PretableRowModelError, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, createColumnHelper2 as createColumnHelper, createGrid, createLocalRowModel2 as createLocalRowModel, numberFormats };
8467
+ export { GROUP_COLUMN_ID, PretableDisposedModelError, PretableInvalidGroupKeyError, PretableReentrantMutationError, PretableRowIdentityChangeError, PretableRowModelError, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, createColumnHelper2 as createColumnHelper, createGrid, createLocalRowModel2 as createLocalRowModel, describeRowSelection, numberFormats };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pretable/core",
3
- "version": "0.6.2",
3
+ "version": "0.8.0",
4
4
  "description": "Framework-agnostic grid state primitives for Pretable.",
5
5
  "license": "MIT",
6
6
  "repository": {