@pretable/core 0.0.2 → 0.0.3

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
@@ -32,6 +32,55 @@ type PretableRow = Record<string, unknown>;
32
32
  * @public
33
33
  */
34
34
  type PretableSortDirection = "asc" | "desc" | null;
35
+ /**
36
+ * Phase of an in-progress cell edit.
37
+ *
38
+ * @public
39
+ */
40
+ type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
41
+ /**
42
+ * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
43
+ * `formatEditValue`).
44
+ *
45
+ * @public
46
+ */
47
+ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
48
+ rowId: string;
49
+ columnId: string;
50
+ row: TRow;
51
+ column: PretableColumn<TRow>;
52
+ value: unknown;
53
+ }
54
+ /**
55
+ * In-progress cell edit observed via `PretableGrid.getSnapshot().editing`.
56
+ * `error` carries the validation message (status `"editing"`) or the commit
57
+ * failure message (status `"error"`).
58
+ *
59
+ * @public
60
+ */
61
+ interface PretableEditState {
62
+ rowId: string;
63
+ columnId: string;
64
+ draft: unknown;
65
+ status: PretableEditStatus;
66
+ error?: string;
67
+ }
68
+ /** @public */
69
+ type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
70
+ /** @public */
71
+ type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
72
+ /** @public */
73
+ type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
74
+ /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
75
+ interface ColumnFilter {
76
+ operator: FilterOperator;
77
+ value?: FilterValue;
78
+ }
79
+ /** @public */
80
+ interface ColumnOption {
81
+ value: string;
82
+ label?: string;
83
+ }
35
84
  /**
36
85
  * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
37
86
  *
@@ -42,15 +91,23 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
42
91
  header?: string;
43
92
  wrap?: boolean;
44
93
  widthPx?: number;
45
- pinned?: "left";
94
+ pinned?: "left" | "right";
46
95
  sortable?: boolean;
96
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
97
+ step?: number;
47
98
  filterable?: boolean;
99
+ type?: ColumnType;
100
+ options?: ColumnOption[];
48
101
  value?: (row: TRow) => unknown;
49
102
  format?: (input: PretableFormatInput<TRow>) => string;
50
103
  minWidthPx?: number;
51
104
  maxWidthPx?: number;
52
105
  resizable?: boolean;
53
106
  reorderable?: boolean;
107
+ editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
+ validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
+ parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
110
+ formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
54
111
  }
55
112
  /**
56
113
  * Input passed to a column's `format` function.
@@ -74,13 +131,13 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
74
131
  autosize?: boolean | AutosizeOptions;
75
132
  }
76
133
  /**
77
- * Active sort. `columnId` is null when no column is sorted.
134
+ * One entry in the ordered sort list; index in the list = priority.
78
135
  *
79
136
  * @public
80
137
  */
81
- interface PretableSortState {
82
- columnId: string | null;
83
- direction: PretableSortDirection;
138
+ interface PretableSortEntry {
139
+ columnId: string;
140
+ direction: "asc" | "desc";
84
141
  }
85
142
  /**
86
143
  * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
@@ -158,13 +215,14 @@ interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
158
215
  */
159
216
  interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
160
217
  viewport: PretableViewportState;
161
- sort: PretableSortState;
162
- filters: Record<string, string>;
218
+ sort: PretableSortEntry[];
219
+ filters: Record<string, ColumnFilter>;
163
220
  selection: PretableSelectionState;
164
221
  focus: PretableFocusState;
165
222
  totalRowCount: number;
166
223
  visibleRows: PretableVisibleRow<TRow>[];
167
224
  visibleRange: PretableRowRange;
225
+ editing: PretableEditState | null;
168
226
  }
169
227
  /**
170
228
  * Direction passed to `PretableGrid.moveFocus`.
@@ -207,9 +265,12 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
207
265
  /** Read the current snapshot. Stable reference until the next mutation. */
208
266
  getSnapshot(): PretableGridSnapshot<TRow>;
209
267
  setSort(columnId: string | null, direction: PretableSortDirection): void;
210
- setFilter(columnId: string, value: string): void;
268
+ /** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
269
+ replaceSort(entries: PretableSortEntry[]): void;
270
+ setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
211
271
  clearFilters(): void;
212
- replaceFilters(nextFilters: Record<string, string>): void;
272
+ replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
273
+ distinctColumnValues(columnId: string): string[];
213
274
  setSelection(state: PretableSelectionState): void;
214
275
  selectAll(): void;
215
276
  clearSelection(): void;
@@ -223,11 +284,39 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
223
284
  autosizeColumns(options?: AutosizeOptions): void;
224
285
  setColumnWidth(columnId: string, width: number): void;
225
286
  moveColumn(columnId: string, toIndex: number): void;
226
- setColumnPinned(columnId: string, pinned: "left" | null): void;
287
+ /**
288
+ * Set the relative order of the columns. Ids that do not match a column are
289
+ * ignored, and columns absent from `ids` keep their current relative order at
290
+ * the end. Pin state is never read from `ids` nor changed: the result is
291
+ * regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
292
+ * that interleaves pinned and unpinned columns is normalised rather than
293
+ * honoured literally.
294
+ */
295
+ setColumnOrder(ids: readonly string[]): void;
296
+ setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
227
297
  autosizeColumn(columnId: string, options?: AutosizeOptions): void;
228
298
  resetColumnLayout(): void;
229
299
  mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
230
300
  applyTransaction(transaction: PretableTransaction<TRow>): void;
301
+ /**
302
+ * Replace the full row set in place. Unlike recreating the grid, this
303
+ * preserves selection and focus (both keyed by row id), dropping only the
304
+ * references whose rows are no longer present. Suited to high-frequency
305
+ * updates where row identities are stable.
306
+ */
307
+ setRows(rows: TRow[]): void;
308
+ beginEdit(addr: PretableCellAddress, opts?: {
309
+ draft?: unknown;
310
+ status?: "checking" | "editing";
311
+ }): void;
312
+ setEditDraft(value: unknown): void;
313
+ markEditing(): void;
314
+ markEditValidating(): void;
315
+ markEditSaving(): void;
316
+ markEditInvalid(message: string): void;
317
+ markEditError(message: string): void;
318
+ commitEditSucceeded(): void;
319
+ cancelEdit(): void;
231
320
  }
232
321
 
233
322
  /**
@@ -248,4 +337,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
248
337
  */
249
338
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
250
339
 
251
- export { type AutosizeOptions, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortState, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
340
+ export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
package/dist/index.d.ts CHANGED
@@ -32,6 +32,55 @@ type PretableRow = Record<string, unknown>;
32
32
  * @public
33
33
  */
34
34
  type PretableSortDirection = "asc" | "desc" | null;
35
+ /**
36
+ * Phase of an in-progress cell edit.
37
+ *
38
+ * @public
39
+ */
40
+ type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
41
+ /**
42
+ * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
43
+ * `formatEditValue`).
44
+ *
45
+ * @public
46
+ */
47
+ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
48
+ rowId: string;
49
+ columnId: string;
50
+ row: TRow;
51
+ column: PretableColumn<TRow>;
52
+ value: unknown;
53
+ }
54
+ /**
55
+ * In-progress cell edit observed via `PretableGrid.getSnapshot().editing`.
56
+ * `error` carries the validation message (status `"editing"`) or the commit
57
+ * failure message (status `"error"`).
58
+ *
59
+ * @public
60
+ */
61
+ interface PretableEditState {
62
+ rowId: string;
63
+ columnId: string;
64
+ draft: unknown;
65
+ status: PretableEditStatus;
66
+ error?: string;
67
+ }
68
+ /** @public */
69
+ type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
70
+ /** @public */
71
+ type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
72
+ /** @public */
73
+ type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
74
+ /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
75
+ interface ColumnFilter {
76
+ operator: FilterOperator;
77
+ value?: FilterValue;
78
+ }
79
+ /** @public */
80
+ interface ColumnOption {
81
+ value: string;
82
+ label?: string;
83
+ }
35
84
  /**
36
85
  * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
37
86
  *
@@ -42,15 +91,23 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
42
91
  header?: string;
43
92
  wrap?: boolean;
44
93
  widthPx?: number;
45
- pinned?: "left";
94
+ pinned?: "left" | "right";
46
95
  sortable?: boolean;
96
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
97
+ step?: number;
47
98
  filterable?: boolean;
99
+ type?: ColumnType;
100
+ options?: ColumnOption[];
48
101
  value?: (row: TRow) => unknown;
49
102
  format?: (input: PretableFormatInput<TRow>) => string;
50
103
  minWidthPx?: number;
51
104
  maxWidthPx?: number;
52
105
  resizable?: boolean;
53
106
  reorderable?: boolean;
107
+ editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
+ validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
+ parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
110
+ formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
54
111
  }
55
112
  /**
56
113
  * Input passed to a column's `format` function.
@@ -74,13 +131,13 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
74
131
  autosize?: boolean | AutosizeOptions;
75
132
  }
76
133
  /**
77
- * Active sort. `columnId` is null when no column is sorted.
134
+ * One entry in the ordered sort list; index in the list = priority.
78
135
  *
79
136
  * @public
80
137
  */
81
- interface PretableSortState {
82
- columnId: string | null;
83
- direction: PretableSortDirection;
138
+ interface PretableSortEntry {
139
+ columnId: string;
140
+ direction: "asc" | "desc";
84
141
  }
85
142
  /**
86
143
  * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
@@ -158,13 +215,14 @@ interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
158
215
  */
159
216
  interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
160
217
  viewport: PretableViewportState;
161
- sort: PretableSortState;
162
- filters: Record<string, string>;
218
+ sort: PretableSortEntry[];
219
+ filters: Record<string, ColumnFilter>;
163
220
  selection: PretableSelectionState;
164
221
  focus: PretableFocusState;
165
222
  totalRowCount: number;
166
223
  visibleRows: PretableVisibleRow<TRow>[];
167
224
  visibleRange: PretableRowRange;
225
+ editing: PretableEditState | null;
168
226
  }
169
227
  /**
170
228
  * Direction passed to `PretableGrid.moveFocus`.
@@ -207,9 +265,12 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
207
265
  /** Read the current snapshot. Stable reference until the next mutation. */
208
266
  getSnapshot(): PretableGridSnapshot<TRow>;
209
267
  setSort(columnId: string | null, direction: PretableSortDirection): void;
210
- setFilter(columnId: string, value: string): void;
268
+ /** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
269
+ replaceSort(entries: PretableSortEntry[]): void;
270
+ setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
211
271
  clearFilters(): void;
212
- replaceFilters(nextFilters: Record<string, string>): void;
272
+ replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
273
+ distinctColumnValues(columnId: string): string[];
213
274
  setSelection(state: PretableSelectionState): void;
214
275
  selectAll(): void;
215
276
  clearSelection(): void;
@@ -223,11 +284,39 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
223
284
  autosizeColumns(options?: AutosizeOptions): void;
224
285
  setColumnWidth(columnId: string, width: number): void;
225
286
  moveColumn(columnId: string, toIndex: number): void;
226
- setColumnPinned(columnId: string, pinned: "left" | null): void;
287
+ /**
288
+ * Set the relative order of the columns. Ids that do not match a column are
289
+ * ignored, and columns absent from `ids` keep their current relative order at
290
+ * the end. Pin state is never read from `ids` nor changed: the result is
291
+ * regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
292
+ * that interleaves pinned and unpinned columns is normalised rather than
293
+ * honoured literally.
294
+ */
295
+ setColumnOrder(ids: readonly string[]): void;
296
+ setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
227
297
  autosizeColumn(columnId: string, options?: AutosizeOptions): void;
228
298
  resetColumnLayout(): void;
229
299
  mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
230
300
  applyTransaction(transaction: PretableTransaction<TRow>): void;
301
+ /**
302
+ * Replace the full row set in place. Unlike recreating the grid, this
303
+ * preserves selection and focus (both keyed by row id), dropping only the
304
+ * references whose rows are no longer present. Suited to high-frequency
305
+ * updates where row identities are stable.
306
+ */
307
+ setRows(rows: TRow[]): void;
308
+ beginEdit(addr: PretableCellAddress, opts?: {
309
+ draft?: unknown;
310
+ status?: "checking" | "editing";
311
+ }): void;
312
+ setEditDraft(value: unknown): void;
313
+ markEditing(): void;
314
+ markEditValidating(): void;
315
+ markEditSaving(): void;
316
+ markEditInvalid(message: string): void;
317
+ markEditError(message: string): void;
318
+ commitEditSucceeded(): void;
319
+ cancelEdit(): void;
231
320
  }
232
321
 
233
322
  /**
@@ -248,4 +337,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
248
337
  */
249
338
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
250
339
 
251
- export { type AutosizeOptions, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortState, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
340
+ export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };