@pretable/core 0.2.0 → 0.3.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
@@ -308,11 +308,16 @@ function resolveAggregator(spec) {
308
308
  // ../grid-core/dist/row-utils.js
309
309
  function createSourceRows(options) {
310
310
  return options.rows.map((row, index) => ({
311
- id: options.getRowId?.(row, index) ?? String(index),
311
+ id: options.getRowId(row),
312
312
  row,
313
313
  sourceIndex: index
314
314
  }));
315
315
  }
316
+ function assertGetRowId(options) {
317
+ if (typeof options.getRowId !== "function") {
318
+ throw new TypeError("pretable: `getRowId` is required. Selection, focus, edits and transactions are keyed by row id, so identity must come from the row's own data \u2014 e.g. `getRowId: (row) => row.id`. There is no positional default: one would silently re-point selection and in-flight edits at the wrong rows whenever `rows` is replaced in a different order.");
319
+ }
320
+ }
316
321
  var collator = new Intl.Collator(void 0, {
317
322
  numeric: true,
318
323
  sensitivity: "base"
@@ -698,6 +703,7 @@ function groupColumnsByPin(columns) {
698
703
  return [...left, ...unpinned, ...right];
699
704
  }
700
705
  function createGridCore(inputOptions) {
706
+ assertGetRowId(inputOptions);
701
707
  const listeners = /* @__PURE__ */ new Set();
702
708
  const groupedInput = {
703
709
  ...inputOptions,
@@ -1369,9 +1375,6 @@ function createGridCore(inputOptions) {
1369
1375
  }
1370
1376
  },
1371
1377
  applyTransaction(transaction) {
1372
- if (!options.getRowId) {
1373
- throw new Error("applyTransaction requires getRowId on PretableGridOptions");
1374
- }
1375
1378
  const getRowId = options.getRowId;
1376
1379
  const before = captureVisibleRowsForFocusReconciliation();
1377
1380
  if (transaction.remove) {
@@ -1386,7 +1389,7 @@ function createGridCore(inputOptions) {
1386
1389
  }
1387
1390
  if (transaction.update) {
1388
1391
  for (const patch of transaction.update) {
1389
- const id = getRowId(patch, -1);
1392
+ const id = getRowId(patch);
1390
1393
  const existing = sourceRowIndex.get(id);
1391
1394
  if (!existing) {
1392
1395
  continue;
@@ -1406,7 +1409,7 @@ function createGridCore(inputOptions) {
1406
1409
  }
1407
1410
  if (transaction.add) {
1408
1411
  for (const row of transaction.add) {
1409
- const id = getRowId(row, sourceRows.length);
1412
+ const id = getRowId(row);
1410
1413
  const entry = {
1411
1414
  id,
1412
1415
  row,
package/dist/index.d.cts CHANGED
@@ -244,7 +244,31 @@ interface PretableProcessingOptions {
244
244
  interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
245
245
  columns: PretableColumn<TRow>[];
246
246
  rows: TRow[];
247
- getRowId?: (row: TRow, index: number) => string;
247
+ /**
248
+ * Stable identity for a row, derived from the row's own data. **Required**,
249
+ * and deliberately not defaultable.
250
+ *
251
+ * Selection, focus, in-flight edits, group expansion and
252
+ * {@link PretableGrid.applyTransaction} are all keyed by this id, and they
253
+ * are designed to survive a wholesale row replacement. That design is only
254
+ * sound when the id travels with the row: if it were derived from array
255
+ * position instead, replacing `rows` in a different order — an external
256
+ * sort, a streaming batch, a removal — would silently re-point selection,
257
+ * focus and an open editor at whichever rows now occupy those positions. No
258
+ * error, no warning, wrong rows.
259
+ *
260
+ * The function receives only the row, so position is not in scope. Rows with
261
+ * no natural key need one synthesized when the data is loaded, not derived
262
+ * from where the row happens to sit.
263
+ *
264
+ * Ids must be unique and stable across renders for the same logical row.
265
+ *
266
+ * @example
267
+ * ```ts
268
+ * createGrid({ columns, rows, getRowId: (row) => row.id });
269
+ * ```
270
+ */
271
+ getRowId: (row: TRow) => string;
248
272
  autosize?: boolean | AutosizeOptions;
249
273
  /**
250
274
  * Who applies filtering and sorting to the loaded records. Construction-time
@@ -661,6 +685,7 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
661
685
  * const grid = createGrid({
662
686
  * columns: [{ id: "name" }, { id: "age" }],
663
687
  * rows: [{ id: "1", name: "Ada", age: 36 }],
688
+ * getRowId: (row) => row.id,
664
689
  * });
665
690
  * grid.setSort("age", "desc");
666
691
  * const snapshot = grid.getSnapshot();
package/dist/index.d.ts CHANGED
@@ -244,7 +244,31 @@ interface PretableProcessingOptions {
244
244
  interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
245
245
  columns: PretableColumn<TRow>[];
246
246
  rows: TRow[];
247
- getRowId?: (row: TRow, index: number) => string;
247
+ /**
248
+ * Stable identity for a row, derived from the row's own data. **Required**,
249
+ * and deliberately not defaultable.
250
+ *
251
+ * Selection, focus, in-flight edits, group expansion and
252
+ * {@link PretableGrid.applyTransaction} are all keyed by this id, and they
253
+ * are designed to survive a wholesale row replacement. That design is only
254
+ * sound when the id travels with the row: if it were derived from array
255
+ * position instead, replacing `rows` in a different order — an external
256
+ * sort, a streaming batch, a removal — would silently re-point selection,
257
+ * focus and an open editor at whichever rows now occupy those positions. No
258
+ * error, no warning, wrong rows.
259
+ *
260
+ * The function receives only the row, so position is not in scope. Rows with
261
+ * no natural key need one synthesized when the data is loaded, not derived
262
+ * from where the row happens to sit.
263
+ *
264
+ * Ids must be unique and stable across renders for the same logical row.
265
+ *
266
+ * @example
267
+ * ```ts
268
+ * createGrid({ columns, rows, getRowId: (row) => row.id });
269
+ * ```
270
+ */
271
+ getRowId: (row: TRow) => string;
248
272
  autosize?: boolean | AutosizeOptions;
249
273
  /**
250
274
  * Who applies filtering and sorting to the loaded records. Construction-time
@@ -661,6 +685,7 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
661
685
  * const grid = createGrid({
662
686
  * columns: [{ id: "name" }, { id: "age" }],
663
687
  * rows: [{ id: "1", name: "Ada", age: 36 }],
688
+ * getRowId: (row) => row.id,
664
689
  * });
665
690
  * grid.setSort("age", "desc");
666
691
  * const snapshot = grid.getSnapshot();
package/dist/index.mjs CHANGED
@@ -306,11 +306,16 @@ function resolveAggregator(spec) {
306
306
  // ../grid-core/dist/row-utils.js
307
307
  function createSourceRows(options) {
308
308
  return options.rows.map((row, index) => ({
309
- id: options.getRowId?.(row, index) ?? String(index),
309
+ id: options.getRowId(row),
310
310
  row,
311
311
  sourceIndex: index
312
312
  }));
313
313
  }
314
+ function assertGetRowId(options) {
315
+ if (typeof options.getRowId !== "function") {
316
+ throw new TypeError("pretable: `getRowId` is required. Selection, focus, edits and transactions are keyed by row id, so identity must come from the row's own data \u2014 e.g. `getRowId: (row) => row.id`. There is no positional default: one would silently re-point selection and in-flight edits at the wrong rows whenever `rows` is replaced in a different order.");
317
+ }
318
+ }
314
319
  var collator = new Intl.Collator(void 0, {
315
320
  numeric: true,
316
321
  sensitivity: "base"
@@ -696,6 +701,7 @@ function groupColumnsByPin(columns) {
696
701
  return [...left, ...unpinned, ...right];
697
702
  }
698
703
  function createGridCore(inputOptions) {
704
+ assertGetRowId(inputOptions);
699
705
  const listeners = /* @__PURE__ */ new Set();
700
706
  const groupedInput = {
701
707
  ...inputOptions,
@@ -1367,9 +1373,6 @@ function createGridCore(inputOptions) {
1367
1373
  }
1368
1374
  },
1369
1375
  applyTransaction(transaction) {
1370
- if (!options.getRowId) {
1371
- throw new Error("applyTransaction requires getRowId on PretableGridOptions");
1372
- }
1373
1376
  const getRowId = options.getRowId;
1374
1377
  const before = captureVisibleRowsForFocusReconciliation();
1375
1378
  if (transaction.remove) {
@@ -1384,7 +1387,7 @@ function createGridCore(inputOptions) {
1384
1387
  }
1385
1388
  if (transaction.update) {
1386
1389
  for (const patch of transaction.update) {
1387
- const id = getRowId(patch, -1);
1390
+ const id = getRowId(patch);
1388
1391
  const existing = sourceRowIndex.get(id);
1389
1392
  if (!existing) {
1390
1393
  continue;
@@ -1404,7 +1407,7 @@ function createGridCore(inputOptions) {
1404
1407
  }
1405
1408
  if (transaction.add) {
1406
1409
  for (const row of transaction.add) {
1407
- const id = getRowId(row, sourceRows.length);
1410
+ const id = getRowId(row);
1408
1411
  const entry = {
1409
1412
  id,
1410
1413
  row,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pretable/core",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Framework-agnostic grid state primitives for Pretable.",
5
5
  "license": "MIT",
6
6
  "repository": {