@pretable/core 0.0.1 → 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.ts CHANGED
@@ -1,7 +1,18 @@
1
- interface LayoutSpan {
1
+ /**
2
+ * Half-open row index range — `start` inclusive, `end` exclusive — used to
3
+ * describe the visible row window in {@link PretableGridSnapshot.visibleRange}.
4
+ *
5
+ * @public
6
+ */
7
+ interface PretableRowRange {
2
8
  start: number;
3
9
  end: number;
4
10
  }
11
+ /**
12
+ * Tuning knobs for column autosize calculations.
13
+ *
14
+ * @public
15
+ */
5
16
  interface AutosizeOptions {
6
17
  maxWidthPx?: number;
7
18
  minWidthPx?: number;
@@ -9,92 +20,321 @@ interface AutosizeOptions {
9
20
  cellPaddingPx?: number;
10
21
  }
11
22
 
12
- type GridCoreRow = Record<string, unknown>;
13
- type GridCoreSortDirection = "asc" | "desc" | null;
14
- interface GridCoreColumn<TRow extends GridCoreRow = GridCoreRow> {
23
+ /**
24
+ * Base row constraint — every row is at minimum a string-keyed record.
25
+ *
26
+ * @public
27
+ */
28
+ type PretableRow = Record<string, unknown>;
29
+ /**
30
+ * Sort direction — `null` means unsorted.
31
+ *
32
+ * @public
33
+ */
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
+ }
84
+ /**
85
+ * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
86
+ *
87
+ * @public
88
+ */
89
+ interface PretableColumn<TRow extends PretableRow = PretableRow> {
15
90
  id: string;
16
91
  header?: string;
17
92
  wrap?: boolean;
18
93
  widthPx?: number;
19
- pinned?: "left";
94
+ pinned?: "left" | "right";
20
95
  sortable?: boolean;
96
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
97
+ step?: number;
21
98
  filterable?: boolean;
22
- getValue?: (row: TRow) => unknown;
99
+ type?: ColumnType;
100
+ options?: ColumnOption[];
101
+ value?: (row: TRow) => unknown;
102
+ format?: (input: PretableFormatInput<TRow>) => string;
103
+ minWidthPx?: number;
104
+ maxWidthPx?: number;
105
+ resizable?: boolean;
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;
111
+ }
112
+ /**
113
+ * Input passed to a column's `format` function.
114
+ *
115
+ * @public
116
+ */
117
+ interface PretableFormatInput<TRow extends PretableRow = PretableRow> {
118
+ value: unknown;
119
+ row: TRow;
120
+ column: PretableColumn<TRow>;
23
121
  }
24
- interface GridCoreOptions<TRow extends GridCoreRow = GridCoreRow> {
25
- columns: GridCoreColumn<TRow>[];
122
+ /**
123
+ * Options accepted by `createGrid`.
124
+ *
125
+ * @public
126
+ */
127
+ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
128
+ columns: PretableColumn<TRow>[];
26
129
  rows: TRow[];
27
130
  getRowId?: (row: TRow, index: number) => string;
28
131
  autosize?: boolean | AutosizeOptions;
29
132
  }
30
- interface GridCoreSortState {
31
- columnId: string | null;
32
- direction: GridCoreSortDirection;
133
+ /**
134
+ * One entry in the ordered sort list; index in the list = priority.
135
+ *
136
+ * @public
137
+ */
138
+ interface PretableSortEntry {
139
+ columnId: string;
140
+ direction: "asc" | "desc";
141
+ }
142
+ /**
143
+ * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
144
+ *
145
+ * @public
146
+ */
147
+ interface PretableCellAddress {
148
+ rowId: string;
149
+ columnId: string;
33
150
  }
34
- interface GridCoreSelectionState {
35
- rowIds: string[];
36
- anchorRowId: string | null;
151
+ /**
152
+ * Inclusive cell range — both bounds (start and end) are inside the selection.
153
+ *
154
+ * @public
155
+ */
156
+ interface PretableCellRange {
157
+ startRowId: string;
158
+ endRowId: string;
159
+ startColumnId: string;
160
+ endColumnId: string;
37
161
  }
38
- interface GridCoreFocusState {
162
+ /**
163
+ * Cell-range selection state including the optional anchor for shift-extension.
164
+ *
165
+ * @public
166
+ */
167
+ interface PretableSelectionState {
168
+ ranges: PretableCellRange[];
169
+ anchor: PretableCellAddress | null;
170
+ }
171
+ /**
172
+ * Currently focused cell — both fields are null when nothing is focused.
173
+ *
174
+ * @public
175
+ */
176
+ interface PretableFocusState {
39
177
  rowId: string | null;
40
178
  columnId: string | null;
41
179
  }
42
- interface GridCoreViewportState {
180
+ /**
181
+ * Viewport-level scroll + size state.
182
+ *
183
+ * @public
184
+ */
185
+ interface PretableViewportState {
43
186
  scrollTop: number;
44
187
  scrollLeft: number;
45
188
  height: number;
46
189
  width: number;
47
190
  }
48
- interface GridCoreTransaction<TRow extends GridCoreRow = GridCoreRow> {
191
+ /**
192
+ * Streaming transaction — incremental row mutations applied via `PretableGrid.applyTransaction`.
193
+ *
194
+ * @public
195
+ */
196
+ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
49
197
  add?: TRow[];
50
198
  update?: Partial<TRow>[];
51
199
  remove?: string[];
52
200
  }
53
- interface GridCoreRowModel<TRow extends GridCoreRow = GridCoreRow> {
201
+ /**
202
+ * A row currently in the visible window — includes its source-array index for stable identity.
203
+ *
204
+ * @public
205
+ */
206
+ interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
54
207
  id: string;
55
208
  row: TRow;
56
209
  sourceIndex: number;
57
210
  }
58
- interface GridCoreSnapshot<TRow extends GridCoreRow = GridCoreRow> {
59
- viewport: GridCoreViewportState;
60
- sort: GridCoreSortState;
61
- filters: Record<string, string>;
62
- selection: GridCoreSelectionState;
63
- focus: GridCoreFocusState;
211
+ /**
212
+ * Read-only state observed via `PretableGrid.getSnapshot`.
213
+ *
214
+ * @public
215
+ */
216
+ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
217
+ viewport: PretableViewportState;
218
+ sort: PretableSortEntry[];
219
+ filters: Record<string, ColumnFilter>;
220
+ selection: PretableSelectionState;
221
+ focus: PretableFocusState;
64
222
  totalRowCount: number;
65
- visibleRows: GridCoreRowModel<TRow>[];
66
- visibleRange: LayoutSpan;
223
+ visibleRows: PretableVisibleRow<TRow>[];
224
+ visibleRange: PretableRowRange;
225
+ editing: PretableEditState | null;
67
226
  }
68
- interface GridCoreStore<TRow extends GridCoreRow = GridCoreRow> {
69
- options: GridCoreOptions<TRow>;
70
- subscribe(listener: () => void): () => void;
71
- getSnapshot(): GridCoreSnapshot<TRow>;
72
- setSort(columnId: string | null, direction: GridCoreSortDirection): void;
73
- setFilter(columnId: string, value: string): void;
74
- clearFilters(): void;
75
- replaceFilters(nextFilters: Record<string, string>): void;
76
- selectRow(rowId: string | null): void;
77
- setFocus(rowId: string | null, columnId: string | null): void;
78
- moveFocus(delta: number): void;
79
- setViewport(viewport: GridCoreViewportState): void;
80
- autosizeColumns(autosizeOptions?: AutosizeOptions): void;
81
- applyTransaction(transaction: GridCoreTransaction<TRow>): void;
227
+ /**
228
+ * Direction passed to `PretableGrid.moveFocus`.
229
+ *
230
+ * @public
231
+ */
232
+ type PretableFocusDirection = "up" | "down" | "left" | "right";
233
+ /**
234
+ * Optional behavior modifiers for `PretableGrid.moveFocus`.
235
+ *
236
+ * @public
237
+ */
238
+ interface PretableMoveFocusOptions {
239
+ extend?: boolean;
240
+ jumpToEdge?: boolean;
241
+ byPage?: boolean;
82
242
  }
83
243
 
84
- type PretableRow = Record<string, unknown>;
244
+ /**
245
+ * Per-row selection state — "selected" means fully, "indeterminate" means partial.
246
+ *
247
+ * @public
248
+ */
249
+ type PretableRowSelectionTriState = "selected" | "indeterminate";
85
250
 
86
- type PretableColumn<TRow extends PretableRow = PretableRow> = GridCoreColumn<TRow>;
87
- type PretableGridOptions<TRow extends PretableRow = PretableRow> = GridCoreOptions<TRow>;
88
- type PretableTransaction<TRow extends PretableRow = PretableRow> = GridCoreTransaction<TRow>;
89
- interface PretableGrid<TRow extends PretableRow = PretableRow> extends Omit<GridCoreStore<TRow>, "options"> {
90
- kind: "pretable-grid";
91
- options: PretableGridOptions<TRow>;
92
- getSnapshot(): GridCoreSnapshot<TRow>;
93
- setSort(columnId: string | null, direction: GridCoreSortDirection): void;
251
+ /**
252
+ * Public handle returned by {@link createGrid}. Exposes every action and
253
+ * observation pretable promises to support; does not extend the internal
254
+ * engine type, so private methods cannot leak through the public surface.
255
+ *
256
+ * @public
257
+ */
258
+ interface PretableGrid<TRow extends PretableRow = PretableRow> {
259
+ /** Discriminator — distinguishes `PretableGrid` from arbitrary objects. */
260
+ readonly kind: "pretable-grid";
261
+ /** The options the grid was constructed with. */
262
+ readonly options: PretableGridOptions<TRow>;
263
+ /** Subscribe to grid mutations. Returns an unsubscribe function. */
264
+ subscribe(listener: () => void): () => void;
265
+ /** Read the current snapshot. Stable reference until the next mutation. */
266
+ getSnapshot(): PretableGridSnapshot<TRow>;
267
+ setSort(columnId: string | null, direction: PretableSortDirection): 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;
271
+ clearFilters(): void;
272
+ replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
273
+ distinctColumnValues(columnId: string): string[];
274
+ setSelection(state: PretableSelectionState): void;
275
+ selectAll(): void;
276
+ clearSelection(): void;
277
+ addRange(range: PretableCellRange): void;
278
+ extendRangeFromAnchor(addr: PretableCellAddress): void;
279
+ toggleRowSelection(rowId: string): void;
280
+ setSelectAllVisible(checked: boolean): void;
281
+ setFocus(addr: PretableCellAddress | null): void;
282
+ moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
283
+ setViewport(viewport: PretableViewportState): void;
94
284
  autosizeColumns(options?: AutosizeOptions): void;
285
+ setColumnWidth(columnId: string, width: number): void;
286
+ moveColumn(columnId: string, toIndex: number): 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;
297
+ autosizeColumn(columnId: string, options?: AutosizeOptions): void;
298
+ resetColumnLayout(): void;
299
+ mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
95
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;
96
320
  }
97
321
 
98
- declare function createGrid<TRow extends Record<string, unknown>>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
322
+ /**
323
+ * Create a pretable grid instance. Returns a {@link PretableGrid} handle
324
+ * that exposes every action and observation pretable supports.
325
+ *
326
+ * @example
327
+ * ```ts
328
+ * const grid = createGrid({
329
+ * columns: [{ id: "name" }, { id: "age" }],
330
+ * rows: [{ id: "1", name: "Ada", age: 36 }],
331
+ * });
332
+ * grid.setSort("age", "desc");
333
+ * const snapshot = grid.getSnapshot();
334
+ * ```
335
+ *
336
+ * @public
337
+ */
338
+ declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
99
339
 
100
- export { type AutosizeOptions, type PretableColumn, type GridCoreFocusState as PretableFocusState, type PretableGrid, type PretableGridOptions, type GridCoreSnapshot as PretableGridSnapshot, type PretableRow, type GridCoreSelectionState as PretableSelectionState, type GridCoreSortDirection as PretableSortDirection, type GridCoreSortState as PretableSortState, type PretableTransaction, type GridCoreViewportState as PretableViewportState, type GridCoreRowModel as 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 };