@orkestrel/scaffold 0.0.119 → 0.0.120
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/bin/main.js +15 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +27 -26
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +136 -136
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/manifest.json +39 -464
- package/dist/src/core/index.cjs +162 -177
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +151 -166
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +25 -25
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -50
- package/dist/src/server/index.d.ts +50 -50
- package/dist/src/server/index.js +26 -26
- package/dist/src/server/index.js.map +1 -1
- package/package.json +9 -9
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Table
|
|
2
2
|
|
|
3
|
-
> The environment-agnostic tabular document: a `
|
|
3
|
+
> The environment-agnostic tabular document: a `GridSchema` declaring the columns, a `Grid`
|
|
4
4
|
> holding the rows given against it, and one lens of sort, filter, and page deciding which of them
|
|
5
5
|
> the view shows.
|
|
6
6
|
|
|
7
|
-
The core renders nothing and names no host type. **A
|
|
7
|
+
The core renders nothing and names no host type. **A table, a report,
|
|
8
8
|
a terminal listing, and a CSV export are the same abstraction.** They all hold a set of records,
|
|
9
9
|
order them, narrow them, and show a stretch of them. What differs is who draws the result, and
|
|
10
10
|
drawing belongs to each host. The browser face binds native table elements to that same document.
|
|
@@ -15,8 +15,8 @@ second copy of an answer can go stale. A write validates all of itself before an
|
|
|
15
15
|
announces itself after it has.
|
|
16
16
|
|
|
17
17
|
The core refuses rather than throws. Every guard returns `false` off-shape rather than throwing,
|
|
18
|
-
every parser returns `undefined` on refusal, and every row the
|
|
19
|
-
copy.
|
|
18
|
+
every parser returns `undefined` on refusal, and every row the grid hands back is a frozen owned
|
|
19
|
+
copy. Grid-owned refusals raise `GridError`, and each one names a caller mistake.
|
|
20
20
|
|
|
21
21
|
## Surface
|
|
22
22
|
|
|
@@ -26,19 +26,19 @@ subclasses. They validate declared members and refuse transparent proxies and un
|
|
|
26
26
|
The core surface is exported from `@orkestrel/table` ([`src/core`](../src/core)); the native binding
|
|
27
27
|
surface comes from `@orkestrel/table/browser` ([`src/browser`](../src/browser)). The manager
|
|
28
28
|
classes and the key-set shell they compose are the module's internal declarations: they stay out
|
|
29
|
-
of the barrel, so no consumer can construct one, and each constructor takes the
|
|
30
|
-
and closures over state `
|
|
29
|
+
of the barrel, so no consumer can construct one, and each constructor takes the grid's emitter
|
|
30
|
+
and closures over state `Grid` keeps private, which is why they are internal rather than
|
|
31
31
|
published. Every other declaration is reachable from the barrel, so a consumer holds the
|
|
32
32
|
mechanisms the package uses on itself.
|
|
33
33
|
|
|
34
|
-
### Open a
|
|
34
|
+
### Open a grid
|
|
35
35
|
|
|
36
|
-
Open a
|
|
36
|
+
Open a grid, narrow it, order it, and read the rows to draw:
|
|
37
37
|
|
|
38
38
|
```ts
|
|
39
|
-
import {
|
|
39
|
+
import { createGrid } from '@orkestrel/table'
|
|
40
40
|
|
|
41
|
-
const
|
|
41
|
+
const grid = createGrid(
|
|
42
42
|
{
|
|
43
43
|
label: 'People',
|
|
44
44
|
key: 'id',
|
|
@@ -58,36 +58,36 @@ const table = createTable(
|
|
|
58
58
|
},
|
|
59
59
|
)
|
|
60
60
|
|
|
61
|
-
|
|
62
|
-
|
|
61
|
+
grid.filter.set({ column: 'name', operator: 'contains', text: 'a' })
|
|
62
|
+
grid.sort.set({ column: 'age', direction: 'descending' })
|
|
63
63
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
64
|
+
grid.count // 3 — every name holds a lowercase 'a'
|
|
65
|
+
grid.pagination.count // 2 — two pages of two
|
|
66
|
+
grid.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest first
|
|
67
67
|
```
|
|
68
68
|
|
|
69
69
|
### Native binding
|
|
70
70
|
|
|
71
71
|
These declarations belong to the browser entry.
|
|
72
72
|
|
|
73
|
-
| Name | Kind | Signature
|
|
74
|
-
| ----------------------- | --------- |
|
|
75
|
-
| `TableBinding` | class | `new (element: HTMLTableElement, document:
|
|
76
|
-
| `TableBindingInterface` | interface | `{ element, document, destroyed, emitter, refresh(), destroy() }`
|
|
77
|
-
| `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe?, on?, error? }`
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `TableBindingEventMap` | type | `{ readonly sort: readonly [event: CustomEvent<readonly
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `TableBindingErrorCode` | type | `'STRUCTURE'`
|
|
85
|
-
| `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError`
|
|
86
|
-
| `isTableBindingError` | function | `(value: unknown) => value is TableBindingError`
|
|
87
|
-
| `createTableBinding` | function | `(element: HTMLTableElement, document:
|
|
88
|
-
| `readTable` | function | `(element: HTMLTableElement) =>
|
|
89
|
-
| `readTableSchema` | function | `(element: HTMLTableElement) =>
|
|
90
|
-
| `readTableRows` | function | `(schema:
|
|
73
|
+
| Name | Kind | Signature | Summary |
|
|
74
|
+
| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `TableBinding` | class | `new (element: HTMLTableElement, document: GridInterface, options?: TableBindingOptions) => TableBindingInterface` | Retains keyed native rows while projecting every core grid manager. |
|
|
76
|
+
| `TableBindingInterface` | interface | `{ element, document, destroyed, emitter, refresh(), destroy() }` | Binds native table elements to a borrowed core document. |
|
|
77
|
+
| `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe?, on?, error? }` | Configures row ownership, detail presentation, scoped controls, and event listeners. |
|
|
78
|
+
| `GridRange` | interface | `{ first, last, count, page, pages, limit }` | Describes the displayed page within the filtered rows. |
|
|
79
|
+
| `GridSortDescription` | interface | `{ column, direction, priority, count }` | Describes a column's direction and one-based priority among active sort orders. |
|
|
80
|
+
| `GridExpansion` | interface | `{ key, expanded }` | Proposes one row's next expansion state in a cancelable expand request. |
|
|
81
|
+
| `TableBindingEventMap` | type | `{ readonly sort: readonly [event: CustomEvent<readonly GridOrder[]>]; readonly expand: readonly [event: CustomEvent<readonly GridExpansion[]>]; readonly render: readonly []; readonly error: readonly [error: unknown]; }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
|
|
82
|
+
| `GridRenderHandler` | type | `(element: HTMLTableRowElement, row: GridRow) => void` | Patches the contents of a retained row without moving or replacing that row. |
|
|
83
|
+
| `GridProjection` | interface | `{ schema, rows }` | Holds a validated native table projection for constructing a core document. |
|
|
84
|
+
| `TableBindingErrorCode` | type | `'STRUCTURE'` | Names a native binding failure at its structure, rendering, or lifecycle boundary. |
|
|
85
|
+
| `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError` | Represents a native table binding failure with a machine-readable code. |
|
|
86
|
+
| `isTableBindingError` | function | `(value: unknown) => value is TableBindingError` | Checks whether a caught value is a native table binding error. |
|
|
87
|
+
| `createTableBinding` | function | `(element: HTMLTableElement, document: GridInterface, options?: TableBindingOptions) => TableBindingInterface` | Creates a native table binding with one retained row owner. |
|
|
88
|
+
| `readTable` | function | `(element: HTMLTableElement) => GridProjection` | Reads declared header metadata and explicit row keys into a validated core projection. |
|
|
89
|
+
| `readTableSchema` | function | `(element: HTMLTableElement) => GridSchema` | Reads and validates explicit native header metadata. |
|
|
90
|
+
| `readTableRows` | function | `(schema: GridSchema, elements: readonly HTMLTableRowElement[]) => readonly GridRow[]` | Reads explicit keys and declared direct cells against a core schema. |
|
|
91
91
|
|
|
92
92
|
### Enhance authored rows
|
|
93
93
|
|
|
@@ -100,7 +100,7 @@ choice array as JSON in data-table-choices. Nested tables supply no headers or c
|
|
|
100
100
|
This browser example constructs the document before binding it.
|
|
101
101
|
|
|
102
102
|
```ts
|
|
103
|
-
import {
|
|
103
|
+
import { createGrid } from '@orkestrel/table'
|
|
104
104
|
import { createTableBinding, readTable } from '@orkestrel/table/browser'
|
|
105
105
|
|
|
106
106
|
const element = document.createElement('table')
|
|
@@ -109,14 +109,14 @@ element.innerHTML =
|
|
|
109
109
|
'<caption>People</caption><thead><tr><th data-table-column="id" data-table-cell="text">Reference</th><th data-table-column="name" data-table-cell="text"><button data-table-sort="name">Name</button></th></tr></thead><tbody><tr data-table-key="ash"><td data-table-column="name">Ash</td></tr><tr data-table-key="cedar"><td data-table-column="name">Cedar</td></tr></tbody>'
|
|
110
110
|
document.body.append(element)
|
|
111
111
|
const projection = readTable(element)
|
|
112
|
-
const
|
|
113
|
-
const binding = createTableBinding(element,
|
|
114
|
-
|
|
112
|
+
const grid = createGrid(projection.schema, { rows: projection.rows })
|
|
113
|
+
const binding = createTableBinding(element, grid)
|
|
114
|
+
grid.filter.set({ column: 'name', operator: 'contains', text: 'Ash' })
|
|
115
115
|
binding.refresh()
|
|
116
116
|
element.tBodies[0]?.rows.length // 1
|
|
117
117
|
binding.destroy()
|
|
118
118
|
element.tBodies[0]?.rows.length // 2: restored in core store order
|
|
119
|
-
|
|
119
|
+
grid.destroyed // false
|
|
120
120
|
element.remove()
|
|
121
121
|
```
|
|
122
122
|
|
|
@@ -174,7 +174,7 @@ numbered page window; presentation classes belong to the host.
|
|
|
174
174
|
This scoped binding example customizes wording while retaining native control labels.
|
|
175
175
|
|
|
176
176
|
```ts
|
|
177
|
-
import {
|
|
177
|
+
import { createGrid } from '@orkestrel/table'
|
|
178
178
|
import { createTableBinding, readTable } from '@orkestrel/table/browser'
|
|
179
179
|
|
|
180
180
|
const scope = document.createElement('section')
|
|
@@ -184,8 +184,8 @@ document.body.append(scope)
|
|
|
184
184
|
const element = scope.querySelector('table')
|
|
185
185
|
if (element === null) throw new Error('Missing account table')
|
|
186
186
|
const projection = readTable(element)
|
|
187
|
-
const
|
|
188
|
-
const binding = createTableBinding(element,
|
|
187
|
+
const grid = createGrid(projection.schema, { rows: projection.rows, limit: 1 })
|
|
188
|
+
const binding = createTableBinding(element, grid, {
|
|
189
189
|
scope,
|
|
190
190
|
describe: {
|
|
191
191
|
range: ({ first, last, count }) => `${first}–${last} of ${count} accounts`,
|
|
@@ -198,7 +198,7 @@ const binding = createTableBinding(element, table, {
|
|
|
198
198
|
})
|
|
199
199
|
// Keep the binding while the page is mounted; release it before removing the scope.
|
|
200
200
|
binding.destroy()
|
|
201
|
-
|
|
201
|
+
grid.destroy()
|
|
202
202
|
scope.remove()
|
|
203
203
|
```
|
|
204
204
|
|
|
@@ -222,7 +222,7 @@ import {
|
|
|
222
222
|
readTableRows,
|
|
223
223
|
readTableSchema,
|
|
224
224
|
} from '@orkestrel/table/browser'
|
|
225
|
-
import {
|
|
225
|
+
import { createGrid, matchesGridRow } from '@orkestrel/table'
|
|
226
226
|
|
|
227
227
|
const element = document.createElement('table')
|
|
228
228
|
element.setAttribute('data-table-key', 'id')
|
|
@@ -230,10 +230,10 @@ element.innerHTML =
|
|
|
230
230
|
'<thead><tr><th data-table-column="id" data-table-cell="text">Reference</th></tr></thead><tbody></tbody>'
|
|
231
231
|
const schema = readTableSchema(element)
|
|
232
232
|
const rows = readTableRows(schema, []) // []
|
|
233
|
-
const
|
|
234
|
-
const binding = new TableBinding(element,
|
|
233
|
+
const grid = createGrid(schema, { rows })
|
|
234
|
+
const binding = new TableBinding(element, grid)
|
|
235
235
|
binding.destroy()
|
|
236
|
-
|
|
236
|
+
matchesGridRow({ id: 'ash' }, { id: 'ash' }) // true
|
|
237
237
|
isTableBindingError(new TableBindingError('STRUCTURE', 'Missing identity')) // true
|
|
238
238
|
```
|
|
239
239
|
|
|
@@ -242,9 +242,9 @@ isTableBindingError(new TableBindingError('STRUCTURE', 'Missing identity')) // t
|
|
|
242
242
|
Replacement removes omitted optional cells while preserving the identity and its manager state.
|
|
243
243
|
|
|
244
244
|
```ts
|
|
245
|
-
import {
|
|
245
|
+
import { createGrid } from '@orkestrel/table'
|
|
246
246
|
|
|
247
|
-
const
|
|
247
|
+
const grid = createGrid(
|
|
248
248
|
{
|
|
249
249
|
key: 'id',
|
|
250
250
|
columns: [
|
|
@@ -254,31 +254,29 @@ const table = createTable(
|
|
|
254
254
|
},
|
|
255
255
|
{ rows: [{ id: 'ash', name: 'Ash' }] },
|
|
256
256
|
)
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
257
|
+
grid.selection.select('ash')
|
|
258
|
+
grid.rows.replace({ id: 'ash' }) // true
|
|
259
|
+
grid.rows.row('ash') // { id: 'ash' }
|
|
260
|
+
grid.selection.keys.has('ash') // true
|
|
261
261
|
```
|
|
262
262
|
|
|
263
263
|
### Row equality
|
|
264
264
|
|
|
265
265
|
This helper belongs to the core entry.
|
|
266
266
|
|
|
267
|
-
| Name
|
|
268
|
-
|
|
|
269
|
-
| `
|
|
267
|
+
| Name | Kind | Signature | Summary |
|
|
268
|
+
| ---------------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
269
|
+
| `matchesGridRow` | function | `(left: GridRow \| undefined, right: GridRow) => boolean` | Compares complete row values independently of their snapshot identities. |
|
|
270
270
|
|
|
271
271
|
### Rows, cells, and columns
|
|
272
272
|
|
|
273
|
-
The document itself — what a
|
|
274
|
-
|
|
275
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
273
|
+
The document itself — what a grid declares and what one row of it holds. All data, no behavior.
|
|
276
274
|
|
|
277
275
|
| Name | Kind | Signature | Summary |
|
|
278
276
|
| -------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
279
|
-
| `
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
277
|
+
| `GridKey` | type | `string` | Represents a row's identity — a `string`, carried in the cell the schema's `key` names. |
|
|
278
|
+
| `GridCell` | type | `string \| number \| boolean` | Represents every value a cell can hold — a `string`, a `number`, or a `boolean`. |
|
|
279
|
+
| `GridRow` | type | `Readonly<Record<string, GridCell>>` | Represents one row, keyed by column. A column nobody has filled has no key here. |
|
|
282
280
|
| `ColumnCell` | type | `'text' \| 'number' \| 'flag' \| 'choice'` | Names what a column's cells hold — the discriminant that fixes the column's options, its comparison, and the filters that apply to it. |
|
|
283
281
|
| `ColumnChoice` | interface | `{ value, label, help? }` | Represents one value a `choice` column offers — `value` is stored, `label` is read, and `help` explains. |
|
|
284
282
|
| `ColumnBase` | interface | `{ key, label?, help?, hidden?, meta? }` | Describes what every column carries, whatever its cells hold — the name a row's cell uses, the text a reader sees, whether a host draws the column, and the metadata a host attaches to it. |
|
|
@@ -286,177 +284,165 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
286
284
|
| `NumberColumn` | interface | `{ cell }` | Represents a column of numbers, compared by magnitude. |
|
|
287
285
|
| `FlagColumn` | interface | `{ cell }` | Represents a column of yes-or-no answers, compared false before true. |
|
|
288
286
|
| `ChoiceColumn` | interface | `{ cell, choices }` | Represents a column drawn from a declared list, compared by the order that list declares. It requires `choices`. |
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
287
|
+
| `GridColumn` | type | `TextColumn \| NumberColumn \| FlagColumn \| ChoiceColumn` | Represents any column a schema can declare — the union discriminated on `cell`. |
|
|
288
|
+
| `GridSchema` | interface | `{ name?, label?, help?, key, columns }` | Holds everything a grid declares about itself — how the grid is described, which column carries row identity, and the columns it declares, in the order it declares them. |
|
|
291
289
|
|
|
292
290
|
### The lens
|
|
293
291
|
|
|
294
|
-
The axes a
|
|
295
|
-
|
|
296
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
292
|
+
The axes a grid reads its rows through, and the slots that replace what a column's cell fixes.
|
|
297
293
|
|
|
298
|
-
| Name | Kind | Signature
|
|
299
|
-
| ---------------- | --------- |
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `FilterOperator` | type | `'contains' \| 'between' \| 'equals'`
|
|
304
|
-
| `ContainsFilter` | interface | `{ column, operator, text }`
|
|
305
|
-
| `BetweenFilter` | interface | `{ column, operator, minimum, maximum }`
|
|
306
|
-
| `EqualsFilter` | interface | `{ column, operator, value }`
|
|
307
|
-
| `
|
|
308
|
-
| `CellComparator` | type | `(left:
|
|
309
|
-
| `CellMatcher` | type | `(cell:
|
|
294
|
+
| Name | Kind | Signature | Summary |
|
|
295
|
+
| ---------------- | --------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
296
|
+
| `GridTerm` | interface | `{ column }` | Represents one entry of a lens list — the `column` it names. A sort term and a filter each hold one, which is why the two share a list engine. |
|
|
297
|
+
| `GridDirection` | type | `'ascending' \| 'descending'` | Names which way a column sorts. A column nobody has sorted carries no term at all. |
|
|
298
|
+
| `GridOrder` | interface | `{ column, direction }` | Represents one column's place in the sort — the `column` and its `direction`. The list is read left to right. |
|
|
299
|
+
| `FilterOperator` | type | `'contains' \| 'between' \| 'equals'` | Names how a filter tests a cell — the operator each filter carries. |
|
|
300
|
+
| `ContainsFilter` | interface | `{ column, operator, text }` | Keeps the rows whose cell holds this `text` somewhere inside it. |
|
|
301
|
+
| `BetweenFilter` | interface | `{ column, operator, minimum, maximum }` | Keeps the rows whose cell falls between `minimum` and `maximum`, both included, compared the way the column compares. |
|
|
302
|
+
| `EqualsFilter` | interface | `{ column, operator, value }` | Keeps the rows whose cell holds exactly this `value`. |
|
|
303
|
+
| `GridFilter` | type | `ContainsFilter \| BetweenFilter \| EqualsFilter` | Represents any filter a grid can hold — the union discriminated on `operator`. |
|
|
304
|
+
| `CellComparator` | type | `(left: GridCell \| undefined, right: GridCell \| undefined) => number` | Compares two cells of one column, replacing what its `cell` fixes. Always describes ascending order; direction is applied afterwards. |
|
|
305
|
+
| `CellMatcher` | type | `(cell: GridCell \| undefined, filter: GridFilter) => boolean` | Tests one column's cell against a filter, replacing what its `cell` fixes. Receives every filter the grid holds against that column. |
|
|
310
306
|
|
|
311
|
-
### The
|
|
307
|
+
### The grid
|
|
312
308
|
|
|
313
309
|
The entity, its managers, its factory, its contract, and the error it raises.
|
|
314
310
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
|
318
|
-
|
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `
|
|
330
|
-
| `
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
`TableInterface`'s readonly data members stay here, in its `Shape` cell, rather than in
|
|
311
|
+
| Name | Kind | Signature | Summary |
|
|
312
|
+
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
313
|
+
| `Grid` | class | `new (schema: GridSchema, options?: GridOptions) => GridInterface` | Holds a schema, its rows, and the lens through which they are read, implementing `GridInterface` exactly. |
|
|
314
|
+
| `GridInterface` | interface | `{ emitter, schema, rows, sort, filter, selection, expansion, pagination, view, count, destroyed, clear(), destroy() }` | Represents a grid: what it declares, the rows it holds, and the lens it reads them through. |
|
|
315
|
+
| `createGrid` | function | `(schema: GridSchema, options?: GridOptions) => GridInterface` | Opens a grid against a schema. The schema is copied, and the copy is what the grid declares. |
|
|
316
|
+
| `GridOptions` | interface | `{ on?, error?, rows?, comparators?, matchers?, limit? }` | Describes how to open a grid — the listeners wired at construction and where a throw from one goes, the rows seeded into it, the per-column comparison and test replacements, and the page size. |
|
|
317
|
+
| `GridEventMap` | type | `{ readonly write: readonly [key: GridKey]; readonly remove: readonly [key: GridKey]; readonly sort: readonly [orders: readonly GridOrder[]]; readonly filter: readonly [filters: readonly GridFilter[]]; readonly select: readonly [keys: ReadonlySet<GridKey>]; readonly expand: readonly [keys: ReadonlySet<GridKey>]; readonly paginate: readonly [page: number]; readonly clear: readonly []; }` | Lists everything a grid announces, mapping each event to the payload its listeners receive. |
|
|
318
|
+
| `RowManagerInterface` | interface | `{ row(), rows(), add(), update(), replace(), move(), remove() }` | Manages the rows a grid holds, in the order it holds them. |
|
|
319
|
+
| `SortManagerInterface` | interface | `{ order(), orders(), set(), remove() }` | Manages the order a grid reads its rows in. |
|
|
320
|
+
| `FilterManagerInterface` | interface | `{ filter(), filters(), set(), remove() }` | Manages which rows a grid keeps. |
|
|
321
|
+
| `SelectionManagerInterface` | interface | `{ keys, select(), clear(), toggle() }` | Manages the rows somebody has picked. |
|
|
322
|
+
| `ExpansionManagerInterface` | interface | `{ keys, expand(), clear(), toggle() }` | Manages the rows somebody has opened up. |
|
|
323
|
+
| `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), resize() }` | Manages which stretch of the filtered rows the view shows. |
|
|
324
|
+
| `GridError` | class | `new (code: GridErrorCode, message: string, context?: JSONRecord) => GridError` | Represents an error raised by the grid domain — a machine-readable `code` and optional structured `context`. |
|
|
325
|
+
| `GridErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'` | Names the reason a `GridError` carries — the machine-readable code a `catch` branches on. |
|
|
326
|
+
| `isGridError` | function | `(input: unknown) => input is GridError` | Determines whether a caught value is a grid error, so a `catch` branches on `code` without an assertion. |
|
|
327
|
+
|
|
328
|
+
`GridInterface`'s readonly data members stay here, in its `Signature` cell, rather than in
|
|
335
329
|
`## Methods`, and each manager's own readonly members sit in that manager's cell. Every
|
|
336
330
|
call-signature member is documented under [Methods](#methods).
|
|
337
331
|
|
|
338
332
|
The members spelled `count` answer different questions, because each is the lone tally of the
|
|
339
|
-
entity it belongs to. `
|
|
340
|
-
`
|
|
333
|
+
entity it belongs to. `grid.count` is **rows** — how many the filter admits, before the page narrows them.
|
|
334
|
+
`grid.pagination.count` is **pages** — how many the admitted rows fill.
|
|
341
335
|
|
|
342
|
-
Each manager class is constructed by `
|
|
343
|
-
construct one. Its constructor takes the
|
|
344
|
-
owning
|
|
345
|
-
and its interface is the published contract. A consumer writing its own
|
|
336
|
+
Each manager class is constructed by `Grid` and stays out of the barrel, so no consumer can
|
|
337
|
+
construct one. Its constructor takes the grid's emitter and a set of closures over state the
|
|
338
|
+
owning grid keeps private, which is what keeps every store single-owned, so the class is internal
|
|
339
|
+
and its interface is the published contract. A consumer writing its own grid composes `Grid`, or writes
|
|
346
340
|
its own managers against the manager interfaces and reads these classes as the working reference.
|
|
347
341
|
|
|
348
342
|
### Constants
|
|
349
343
|
|
|
350
|
-
The cell registry and the
|
|
351
|
-
under a consumer.
|
|
344
|
+
The cell registry and the column budget. The registry is frozen, so a shared list cannot be
|
|
345
|
+
rewritten under a consumer. The other schema budgets are `@orkestrel/contract` exports; § Budgets
|
|
346
|
+
lists them.
|
|
352
347
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
|
356
|
-
|
|
|
357
|
-
| `COLUMN_CELLS` | const | `readonly ColumnCell[]` | Lists every column cell, in the order declared by the public contract. |
|
|
358
|
-
| `COLUMN_LIMIT` | const | `256` | Names the maximum number of columns one schema may declare: 256. |
|
|
359
|
-
| `CHOICE_LIMIT` | const | `1024` | Names the maximum number of choices one `choice` column may offer: 1024. |
|
|
360
|
-
| `NAME_LIMIT` | const | `128` | Names the maximum length of a schema name or column key: 128 UTF-16 code units. |
|
|
361
|
-
| `STRING_LIMIT` | const | `65536` | Names the maximum length of any single retained string: 65536 UTF-16 code units. |
|
|
362
|
-
| `TEXT_LIMIT` | const | `1048576` | Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units. |
|
|
363
|
-
| `NODE_LIMIT` | const | `16384` | Names the maximum total number of records, arrays, and leaves one schema retains: 16384. |
|
|
348
|
+
| Name | Kind | Signature | Summary |
|
|
349
|
+
| -------------- | ----- | ----------------------- | ---------------------------------------------------------------------- |
|
|
350
|
+
| `COLUMN_CELLS` | const | `readonly ColumnCell[]` | Lists every column cell, in the order declared by the public contract. |
|
|
351
|
+
| `COLUMN_LIMIT` | const | `256` | Names the maximum number of columns one schema may declare: 256. |
|
|
364
352
|
|
|
365
353
|
### Guards
|
|
366
354
|
|
|
367
355
|
Total `is*` guards over unknown input. None throws, none coerces, and each returns `false` for
|
|
368
356
|
anything off-shape — including an unexpected prototype, a symbol key, or a cyclic value.
|
|
369
357
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
|
373
|
-
|
|
|
374
|
-
| `
|
|
375
|
-
| `
|
|
376
|
-
| `
|
|
377
|
-
| `
|
|
378
|
-
| `
|
|
379
|
-
| `isStructuralTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value has the exact shape of a `TableSchema` — the shape alone, with no domain check. |
|
|
380
|
-
| `isTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value is a `TableSchema` a table can be opened against — the exact shape, and an audit that finds nothing. |
|
|
358
|
+
| Name | Kind | Signature | Summary |
|
|
359
|
+
| ------------------------ | -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
360
|
+
| `isGridCell` | function | `(input: unknown) => input is GridCell` | Determines whether an unknown value has a grid cell shape — a string, a finite number, or a boolean. |
|
|
361
|
+
| `isGridRow` | function | `(input: unknown) => input is GridRow` | Determines whether an unknown value is a record whose every own key is a string and every value a `GridCell`. |
|
|
362
|
+
| `isColumnCell` | function | `(input: unknown) => input is ColumnCell` | Determines whether an unknown value is a declared column cell. |
|
|
363
|
+
| `isColumnChoice` | function | `(input: unknown) => input is ColumnChoice` | Determines whether an unknown value is one exact `ColumnChoice` record; an unknown member refuses it. |
|
|
364
|
+
| `isGridColumn` | function | `(input: unknown) => input is GridColumn` | Determines whether an unknown value is one exact discriminated `GridColumn`, checked against its cell's own options. |
|
|
365
|
+
| `isStructuralGridSchema` | function | `(input: unknown) => input is GridSchema` | Determines whether an unknown value has the exact shape of a `GridSchema` — the shape alone, with no domain check. |
|
|
366
|
+
| `isGridSchema` | function | `(input: unknown) => input is GridSchema` | Determines whether an unknown value is a `GridSchema` a grid can be opened against — the exact shape, and an audit that finds nothing. |
|
|
381
367
|
|
|
382
368
|
The schema guards answer about a schema, and which one to reach for is which question you are asking.
|
|
383
|
-
`
|
|
384
|
-
and nothing else there. `
|
|
369
|
+
`isStructuralGridSchema` asks whether the shape is exact: every declared member present and typed,
|
|
370
|
+
and nothing else there. `isGridSchema` asks that and then asks `auditGrid`, so it refuses a
|
|
385
371
|
schema-shaped value carrying a domain fault or a budget breach — a `key` naming no declared column,
|
|
386
372
|
a column key declared twice, a `choice` column offering nothing. It is the guard the parsers read.
|
|
387
|
-
The `
|
|
373
|
+
The `Grid` constructor asks in a different order. It guards the value it was handed, owns a copy
|
|
388
374
|
of it, then guards and audits that copy and keeps that same object. Its `SCHEMA` message carries
|
|
389
375
|
the audit diagnostics when the owned copy reaches the audit, and names
|
|
390
|
-
`The schema is not a
|
|
376
|
+
`The schema is not a grid schema` when the copy fails the guard the handed value passed. It also
|
|
391
377
|
names `column "<key>" has metadata that cannot be owned` when the column's `meta` answers the
|
|
392
|
-
guard's read and the clone's read differently, the message `
|
|
378
|
+
guard's read and the clone's read differently, the message `cloneGridSchema` raises and the
|
|
393
379
|
constructor rethrows unchanged.
|
|
394
380
|
|
|
395
|
-
`
|
|
381
|
+
`isGridSchema`, the constructor, and `parseGrid` agree on every schema whose reads are stable,
|
|
396
382
|
which is every schema made of ordinary declared data. They part where a foreign object answers a
|
|
397
383
|
property read with something other than the value a clone of it holds — a `meta` behind a `get`
|
|
398
|
-
trap is the shipped case. `
|
|
384
|
+
trap is the shipped case. `isGridSchema` admits such a schema, because it reads it once and the
|
|
399
385
|
read answers. The constructor refuses it, because it guards the copy it owns rather than the object
|
|
400
|
-
it read, and `
|
|
386
|
+
it read, and `parseGrid` refuses it too, because it re-guards its own projection. Reach for the
|
|
401
387
|
structural guard where you mean to run the audit yourself and read its diagnostics.
|
|
402
388
|
|
|
403
389
|
### Helpers
|
|
404
390
|
|
|
405
|
-
The pure leaves the
|
|
391
|
+
The pure leaves the grid composes: the column lookup, the identity read, the key-set engine, the
|
|
406
392
|
lens-list operations, the cell gate, the comparison, the filter tests, the row passes, the
|
|
407
|
-
audit, and the wire projections. `computeKeys`, `matchesTerms`, `
|
|
408
|
-
propagate exceptions from supplied callbacks; `
|
|
393
|
+
audit, and the wire projections. `computeKeys`, `matchesTerms`, `filterGridRows`, and `sortGridRows`
|
|
394
|
+
propagate exceptions from supplied callbacks; `serializeGrid` raises `SCHEMA` for a `meta` no clone
|
|
409
395
|
can own. The other helpers are total over ordinary declared inputs, subject to the core's
|
|
410
396
|
reflection-failure boundary described later.
|
|
411
397
|
|
|
412
|
-
| Name | Kind | Signature
|
|
413
|
-
| ---------------- | -------- |
|
|
414
|
-
| `extractColumn` | function | `(schema:
|
|
415
|
-
| `
|
|
416
|
-
| `computeKeys` | function | `(known: readonly
|
|
417
|
-
| `mergeTerms` | function | `<Term extends
|
|
418
|
-
| `removeTerms` | function | `<Term extends
|
|
419
|
-
| `matchesTerms` | function | `<Term extends
|
|
420
|
-
| `matchesCell` | function | `(column:
|
|
421
|
-
| `compareCells` | function | `(column:
|
|
422
|
-
| `admitsFilter` | function | `(column:
|
|
423
|
-
| `matchesFilter` | function | `(column:
|
|
424
|
-
| `
|
|
425
|
-
| `
|
|
426
|
-
| `
|
|
427
|
-
| `
|
|
428
|
-
| `serializeRows` | function | `(schema:
|
|
398
|
+
| Name | Kind | Signature | Summary |
|
|
399
|
+
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
400
|
+
| `extractColumn` | function | `(schema: GridSchema, key: string) => GridColumn \| undefined` | Finds one column by key; `undefined` when the schema declares no such column. |
|
|
401
|
+
| `extractGridKey` | function | `(schema: GridSchema, row: GridRow) => GridKey \| undefined` | Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a string. |
|
|
402
|
+
| `computeKeys` | function | `(known: readonly GridKey[], current: ReadonlySet<GridKey>, input: GridKey \| readonly GridKey[] \| undefined, include: (included: boolean) => boolean) => ReadonlySet<GridKey> \| undefined` | Computes one atomic 0/1/N membership change over the keys a caller may address — the engine selection and expansion share. |
|
|
403
|
+
| `mergeTerms` | function | `<Term extends GridTerm>(current: readonly Term[], requested: readonly Term[]) => readonly Term[]` | Merges lens terms into a column-keyed list, replacing the entry that names the same column — the `set` write. |
|
|
404
|
+
| `removeTerms` | function | `<Term extends GridTerm>(current: readonly Term[], columns: readonly string[]) => readonly Term[]` | Removes every lens term naming one of the given columns — the drop `sort.remove` and `filter.remove` share. |
|
|
405
|
+
| `matchesTerms` | function | `<Term extends GridTerm>(left: readonly Term[], right: readonly Term[], equal: (left: Term, right: Term) => boolean) => boolean` | Checks whether two lens lists hold the same terms in the same order, with the supplied test deciding the operands. |
|
|
406
|
+
| `matchesCell` | function | `(column: GridColumn, value: unknown) => value is GridCell` | Checks whether one column can hold a value — the shape gate every write and every seed passes through. |
|
|
407
|
+
| `compareCells` | function | `(column: GridColumn, left: GridCell \| undefined, right: GridCell \| undefined) => number` | Compares two of one column's cells the way its `cell` fixes, describing ascending order. |
|
|
408
|
+
| `admitsFilter` | function | `(column: GridColumn, filter: GridFilter) => boolean` | Checks whether one column admits a filter and every operand it carries — the gate `filter.set` and `matchesFilter` share. |
|
|
409
|
+
| `matchesFilter` | function | `(column: GridColumn, cell: GridCell \| undefined, filter: GridFilter) => boolean` | Tests one of a column's cells against one filter the way its `cell` fixes. |
|
|
410
|
+
| `filterGridRows` | function | `(schema: GridSchema, rows: readonly GridRow[], filters: readonly GridFilter[], matchers?: Readonly<Record<string, CellMatcher>>) => readonly GridRow[]` | Keeps the rows every filter accepts, in the order given; a supplied `CellMatcher` replaces the default per column. |
|
|
411
|
+
| `sortGridRows` | function | `(schema: GridSchema, rows: readonly GridRow[], orders: readonly GridOrder[], comparators?: Readonly<Record<string, CellComparator>>) => readonly GridRow[]` | Orders rows by the terms given, stably; a supplied `CellComparator` replaces the default per column. |
|
|
412
|
+
| `auditGrid` | function | `(schema: GridSchema) => readonly string[]` | Audits a structurally valid schema for domain faults and budget breaches, returning human diagnostics. |
|
|
413
|
+
| `serializeGrid` | function | `(schema: GridSchema) => JSONRecord` | Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA` for a `meta` it cannot own. |
|
|
414
|
+
| `serializeRows` | function | `(schema: GridSchema, rows: readonly GridRow[]) => readonly JSONRecord[]` | Projects rows into JSON with each row's cells in the schema's column order, dropping every absent cell. |
|
|
429
415
|
|
|
430
416
|
### Cloners
|
|
431
417
|
|
|
432
|
-
Owned frozen snapshots. The
|
|
433
|
-
admission, so a later edit to the object a caller passed changes nothing inside the
|
|
434
|
-
row the
|
|
418
|
+
Owned frozen snapshots. The grid takes one of the schema at construction and one of every row at
|
|
419
|
+
admission, so a later edit to the object a caller passed changes nothing inside the grid, and no
|
|
420
|
+
row the grid hands back is a live internal reference.
|
|
435
421
|
|
|
436
|
-
| Name
|
|
437
|
-
|
|
|
438
|
-
| `cloneRow`
|
|
439
|
-
| `
|
|
422
|
+
| Name | Kind | Signature | Summary |
|
|
423
|
+
| ----------------- | -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
424
|
+
| `cloneRow` | function | `(row: GridRow) => GridRow` | Clones one row into an owned frozen snapshot. |
|
|
425
|
+
| `cloneGridSchema` | function | `(schema: GridSchema) => GridSchema` | Clones a whole schema into an owned frozen snapshot, freezing every nested column, choice list, choice, and `meta`; raises `SCHEMA` for a `meta` it cannot own. |
|
|
440
426
|
|
|
441
427
|
`cloneRow` cannot fail for an ordinary row record, subject to the core's reflection-failure boundary
|
|
442
|
-
described later. `
|
|
428
|
+
described later. `cloneGridSchema` can also fail when a column's `meta` holds something no clone can own, such as a
|
|
443
429
|
record that refers back to itself. `meta` is typed as JSON and a cycle satisfies that type, so the
|
|
444
|
-
refusal is a `
|
|
445
|
-
it for a schema whose reads are stable, because `
|
|
430
|
+
refusal is a `GridError` coded `SCHEMA` rather than a silent partial copy. `createGrid` never reaches
|
|
431
|
+
it for a schema whose reads are stable, because `isGridColumn` admits only bounded, exactly ownable
|
|
446
432
|
JSON there and refuses such a schema first; a `meta` that answers the guard's read with ownable JSON
|
|
447
433
|
and the clone's read with something no clone can own reaches it, and it refuses
|
|
448
434
|
with `column "<key>" has metadata that cannot be owned`. This is the door a caller cloning or
|
|
449
|
-
serializing a schema on its own meets, and `
|
|
435
|
+
serializing a schema on its own meets, and `serializeGrid` refuses the same value the same way.
|
|
450
436
|
|
|
451
437
|
### Parsers
|
|
452
438
|
|
|
453
439
|
The wire boundary. Each returns `undefined` on refusal rather than throwing, and each returns an
|
|
454
440
|
owned value rather than the caller's.
|
|
455
441
|
|
|
456
|
-
| Name
|
|
457
|
-
|
|
|
458
|
-
| `
|
|
459
|
-
| `parseRows`
|
|
442
|
+
| Name | Kind | Signature | Summary |
|
|
443
|
+
| ----------- | -------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
444
|
+
| `parseGrid` | function | `(input: unknown) => GridSchema \| undefined` | Parses unknown wire data into an owned, structurally valid, semantically sound grid schema. |
|
|
445
|
+
| `parseRows` | function | `(schema: GridSchema, input: unknown) => readonly GridRow[] \| undefined` | Parses unknown wire data into owned rows against one grid schema, coercing a numeric string and `'true'` / `'false'`. |
|
|
460
446
|
|
|
461
447
|
**Reflection failures.** A TypeScript shape does not guarantee that reflection succeeds. An ordinary
|
|
462
448
|
helper or cloner may propagate a throw from a proxy trap or accessor. Guards and parsers contain that
|
|
@@ -491,7 +477,7 @@ const name: TextColumn = { cell: 'text', key: 'name', label: 'Name' }
|
|
|
491
477
|
```
|
|
492
478
|
|
|
493
479
|
`contains` is the operator a filter bar reaches for, and it compares **case-sensitively**. Case
|
|
494
|
-
folding is a locale decision this package cannot make for a host, so a
|
|
480
|
+
folding is a locale decision this package cannot make for a host, so a grid that wants it supplies
|
|
495
481
|
a `CellMatcher` for that column. The same is true of collation: `text` compares with the language's
|
|
496
482
|
own string order, not a locale-aware collator.
|
|
497
483
|
|
|
@@ -506,7 +492,7 @@ const age: NumberColumn = { cell: 'number', key: 'age', label: 'Age' }
|
|
|
506
492
|
```
|
|
507
493
|
|
|
508
494
|
A cell must be a finite number. `NaN` and either infinity are values a column cannot hold, so a
|
|
509
|
-
write carrying one raises `
|
|
495
|
+
write carrying one raises `GridError` coded `CELL`.
|
|
510
496
|
|
|
511
497
|
### flag
|
|
512
498
|
|
|
@@ -520,7 +506,7 @@ const active: FlagColumn = { cell: 'flag', key: 'active', label: 'Active' }
|
|
|
520
506
|
|
|
521
507
|
`flag` takes `equals` and nothing else. `contains` has no meaning against a boolean and `between`
|
|
522
508
|
carries bounds it could not order usefully, so a filter carrying either against a `flag` column
|
|
523
|
-
raises `
|
|
509
|
+
raises `GridError` coded `CELL`.
|
|
524
510
|
|
|
525
511
|
### choice
|
|
526
512
|
|
|
@@ -609,7 +595,7 @@ needs the check adds it at its own door.
|
|
|
609
595
|
|
|
610
596
|
### meta
|
|
611
597
|
|
|
612
|
-
`ColumnBase.meta` is a bounded JSON carrier for whatever the schema declines to model. The
|
|
598
|
+
`ColumnBase.meta` is a bounded JSON carrier for whatever the schema declines to model. The grid
|
|
613
599
|
never reads it, no comparison sees it, no filter tests it, and it round-trips verbatim key for key.
|
|
614
600
|
This package defines no key in it, so every key belongs to the host: an alignment, a number format,
|
|
615
601
|
a pixel width, an icon name.
|
|
@@ -626,9 +612,9 @@ question before it writes needs the same answer. `extractColumn` finds the colum
|
|
|
626
612
|
|
|
627
613
|
```ts
|
|
628
614
|
import { extractColumn, matchesCell } from '@orkestrel/table'
|
|
629
|
-
import type {
|
|
615
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
630
616
|
|
|
631
|
-
const schema:
|
|
617
|
+
const schema: GridSchema = {
|
|
632
618
|
key: 'id',
|
|
633
619
|
columns: [
|
|
634
620
|
{ cell: 'text', key: 'id' },
|
|
@@ -651,13 +637,13 @@ naming a column the schema does not declare has nothing to be measured against.
|
|
|
651
637
|
|
|
652
638
|
### Overriding a column
|
|
653
639
|
|
|
654
|
-
`
|
|
640
|
+
`GridOptions.comparators` and `GridOptions.matchers` are keyed by column key, and each entry
|
|
655
641
|
replaces — for that column alone — the comparison or the test its `cell` fixes. They are the reason
|
|
656
|
-
no function belongs in the schema: behavior is supplied where the
|
|
642
|
+
no function belongs in the schema: behavior is supplied where the grid is opened, and the schema
|
|
657
643
|
stays data that crosses a wire whole.
|
|
658
644
|
|
|
659
645
|
```ts
|
|
660
|
-
import {
|
|
646
|
+
import { createGrid } from '@orkestrel/table'
|
|
661
647
|
import type { CellComparator, CellMatcher } from '@orkestrel/table'
|
|
662
648
|
|
|
663
649
|
const natural: CellComparator = (left, right) =>
|
|
@@ -669,7 +655,7 @@ const loose: CellMatcher = (cell, filter) =>
|
|
|
669
655
|
.toLowerCase()
|
|
670
656
|
.includes(filter.text.toLowerCase())
|
|
671
657
|
|
|
672
|
-
const
|
|
658
|
+
const grid = createGrid(
|
|
673
659
|
{
|
|
674
660
|
key: 'id',
|
|
675
661
|
columns: [
|
|
@@ -684,36 +670,36 @@ const table = createTable(
|
|
|
684
670
|
},
|
|
685
671
|
)
|
|
686
672
|
|
|
687
|
-
|
|
688
|
-
|
|
673
|
+
grid.filter.set({ column: 'name', operator: 'contains', text: 'ADA' })
|
|
674
|
+
grid.count // 1 — the matcher folded the case; the default would not have
|
|
689
675
|
```
|
|
690
676
|
|
|
691
677
|
An override receives `undefined` for a row carrying no cell there, so it decides absence for itself.
|
|
692
|
-
A comparator always describes ascending order and `
|
|
678
|
+
A comparator always describes ascending order and `GridDirection` is applied afterwards, so one
|
|
693
679
|
comparator serves either direction. An override for a column the schema does not declare is never
|
|
694
680
|
consulted and is not an error: the schema decides which columns exist, and the option only says how
|
|
695
681
|
one of them behaves.
|
|
696
682
|
|
|
697
683
|
## Identity
|
|
698
684
|
|
|
699
|
-
Every row carries its own identity, in the cell named by `
|
|
685
|
+
Every row carries its own identity, in the cell named by `GridSchema.key`, as a non-empty string.
|
|
700
686
|
|
|
701
|
-
`key` is **required**. It must name a declared column, and the
|
|
687
|
+
`key` is **required**. It must name a declared column, and the grid refuses a row whose cell there
|
|
702
688
|
is missing, empty, or not a string. There is no default column, no positional fallback, and no key
|
|
703
689
|
generation: an index is a position, and a position is not an identity — the moment a sort moves a
|
|
704
690
|
row, a position that named it names somebody else.
|
|
705
691
|
|
|
706
692
|
That is a deliberate divergence from `@orkestrel/database`, whose `DEFAULT_PRIMARY` assumes `id`
|
|
707
|
-
when a
|
|
708
|
-
key, so assuming the usual name saves a declaration and costs nothing. A
|
|
693
|
+
when a grid declares no primary column. A database row arrives from a store that already gave it a
|
|
694
|
+
key, so assuming the usual name saves a declaration and costs nothing. A grid's rows arrive from a
|
|
709
695
|
caller who may have joined, projected, or invented them in the browser, so the same assumption picks
|
|
710
696
|
a column that may not exist, or picks one that exists and is not unique. Declaring the key is one
|
|
711
697
|
line, and it is the line every refusal described later is measured against.
|
|
712
698
|
|
|
713
699
|
```ts
|
|
714
|
-
import {
|
|
700
|
+
import { createGrid, isGridError } from '@orkestrel/table'
|
|
715
701
|
|
|
716
|
-
const
|
|
702
|
+
const grid = createGrid({
|
|
717
703
|
key: 'id',
|
|
718
704
|
columns: [
|
|
719
705
|
{ cell: 'text', key: 'id' },
|
|
@@ -721,44 +707,44 @@ const table = createTable({
|
|
|
721
707
|
],
|
|
722
708
|
})
|
|
723
709
|
|
|
724
|
-
|
|
710
|
+
grid.rows.add({ id: '7', name: 'Ada' })
|
|
725
711
|
|
|
726
712
|
try {
|
|
727
|
-
|
|
713
|
+
grid.rows.add({ id: '7', name: 'Grace' })
|
|
728
714
|
} catch (error) {
|
|
729
|
-
if (
|
|
715
|
+
if (isGridError(error)) error.code // 'KEY' — already taken
|
|
730
716
|
}
|
|
731
717
|
|
|
732
718
|
try {
|
|
733
|
-
|
|
719
|
+
grid.rows.add({ name: 'Alan' })
|
|
734
720
|
} catch (error) {
|
|
735
|
-
if (
|
|
721
|
+
if (isGridError(error)) error.code // 'KEY' — no identity at all
|
|
736
722
|
}
|
|
737
723
|
|
|
738
|
-
|
|
724
|
+
grid.rows.rows().length // 1 — a refused write changed nothing
|
|
739
725
|
```
|
|
740
726
|
|
|
741
727
|
These rules follow from it, and each one is a refusal rather than a repair:
|
|
742
728
|
|
|
743
|
-
- **A key is unique.** `add` raises `KEY` for a key the
|
|
729
|
+
- **A key is unique.** `add` raises `KEY` for a key the grid already holds, and for a key repeated
|
|
744
730
|
inside one batch. Every row in the batch is checked before any is admitted, so one duplicate
|
|
745
731
|
admits none of them.
|
|
746
732
|
- **A key cannot move.** `update` merges: the cells given replace the cells held and the cells left
|
|
747
733
|
out stay as they are. A row is found by the key it carries, so writing a different key writes a
|
|
748
734
|
different row — or writes nothing, if that row does not exist.
|
|
749
|
-
- **A row is owned.** The
|
|
750
|
-
is no longer the row the
|
|
735
|
+
- **A row is owned.** The grid clones and freezes a row at admission, so the object a caller keeps
|
|
736
|
+
is no longer the row the grid holds, and `row()` and `rows()` hand back frozen copies rather than
|
|
751
737
|
internal references.
|
|
752
738
|
- **Selection and expansion hold keys.** Never rows, never positions. A pick survives a sort, a
|
|
753
|
-
filter, and a page turn, and a row that leaves the
|
|
739
|
+
filter, and a page turn, and a row that leaves the grid takes its key out of both sets with it.
|
|
754
740
|
|
|
755
741
|
`update` is where that second rule is felt. It merges, so a call carries only the cells it means to
|
|
756
742
|
change, and the row it writes is the one carrying the key it names — never a rename.
|
|
757
743
|
|
|
758
744
|
```ts
|
|
759
|
-
import {
|
|
745
|
+
import { createGrid } from '@orkestrel/table'
|
|
760
746
|
|
|
761
|
-
const
|
|
747
|
+
const grid = createGrid(
|
|
762
748
|
{
|
|
763
749
|
key: 'id',
|
|
764
750
|
columns: [
|
|
@@ -770,24 +756,24 @@ const table = createTable(
|
|
|
770
756
|
{ rows: [{ id: '1', name: 'Ada', age: 36 }] },
|
|
771
757
|
)
|
|
772
758
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
759
|
+
grid.rows.update({ id: '1', age: 37 }) // true
|
|
760
|
+
grid.rows.row('1') // { id: '1', name: 'Ada', age: 37 } — `name` was left out and stayed
|
|
761
|
+
grid.rows.update({ id: '9', name: 'Nobody' }) // false — no row carries that key
|
|
762
|
+
grid.rows.rows().length // 1 — a different key is a different row, so nothing was added
|
|
777
763
|
```
|
|
778
764
|
|
|
779
|
-
`
|
|
765
|
+
`extractGridKey` is the read those rules are built on, and it is exported because a host doing the same
|
|
780
766
|
check before it calls needs the same answer.
|
|
781
767
|
|
|
782
768
|
```ts
|
|
783
|
-
import {
|
|
784
|
-
import type {
|
|
769
|
+
import { extractGridKey } from '@orkestrel/table'
|
|
770
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
785
771
|
|
|
786
|
-
const schema:
|
|
772
|
+
const schema: GridSchema = { key: 'id', columns: [{ cell: 'text', key: 'id' }] }
|
|
787
773
|
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
774
|
+
extractGridKey(schema, { id: '7' }) // '7'
|
|
775
|
+
extractGridKey(schema, { id: '' }) // undefined — empty is not an identity
|
|
776
|
+
extractGridKey(schema, { name: 'Ada' }) // undefined — no key cell at all
|
|
791
777
|
```
|
|
792
778
|
|
|
793
779
|
## The lens
|
|
@@ -799,15 +785,15 @@ before sorting pages the wrong rows onto every page.
|
|
|
799
785
|
|
|
800
786
|
### Sorting
|
|
801
787
|
|
|
802
|
-
The
|
|
788
|
+
The grid holds at most one term per column and applies them in the order they were set. The first
|
|
803
789
|
term decides, and each later term breaks the tie the terms before it left. Rows no term separates
|
|
804
|
-
keep the order the
|
|
790
|
+
keep the order the grid holds them in, so the sort is stable and the row store's own order is the
|
|
805
791
|
final tiebreak.
|
|
806
792
|
|
|
807
793
|
```ts
|
|
808
|
-
import {
|
|
794
|
+
import { createGrid } from '@orkestrel/table'
|
|
809
795
|
|
|
810
|
-
const
|
|
796
|
+
const grid = createGrid(
|
|
811
797
|
{
|
|
812
798
|
key: 'id',
|
|
813
799
|
columns: [
|
|
@@ -825,13 +811,13 @@ const table = createTable(
|
|
|
825
811
|
},
|
|
826
812
|
)
|
|
827
813
|
|
|
828
|
-
|
|
814
|
+
grid.sort.set([
|
|
829
815
|
{ column: 'team', direction: 'ascending' },
|
|
830
816
|
{ column: 'age', direction: 'descending' },
|
|
831
817
|
])
|
|
832
818
|
|
|
833
|
-
|
|
834
|
-
|
|
819
|
+
grid.view.map((row) => row.id) // ['1', '3', '2'] — team first, age breaking the tie
|
|
820
|
+
grid.sort.order('age') // { column: 'age', direction: 'descending' }
|
|
835
821
|
```
|
|
836
822
|
|
|
837
823
|
There is no cycling verb. Which direction a heading offers next is the host's decision, so a host
|
|
@@ -847,9 +833,9 @@ holding a lens of its own gets the same list arithmetic without writing it again
|
|
|
847
833
|
|
|
848
834
|
```ts
|
|
849
835
|
import { matchesTerms, mergeTerms, removeTerms } from '@orkestrel/table'
|
|
850
|
-
import type {
|
|
836
|
+
import type { GridOrder } from '@orkestrel/table'
|
|
851
837
|
|
|
852
|
-
const current: readonly
|
|
838
|
+
const current: readonly GridOrder[] = [
|
|
853
839
|
{ column: 'team', direction: 'ascending' },
|
|
854
840
|
{ column: 'age', direction: 'descending' },
|
|
855
841
|
]
|
|
@@ -860,14 +846,14 @@ matchesTerms(next, current, (order, other) => order.direction === other.directio
|
|
|
860
846
|
removeTerms(next, ['team']).map((order) => order.column) // ['age']
|
|
861
847
|
```
|
|
862
848
|
|
|
863
|
-
`
|
|
849
|
+
`sortGridRows` is the same pass without a grid, for a caller that has rows and terms and no entity. It
|
|
864
850
|
sorts a copy, so the list handed to it never moves.
|
|
865
851
|
|
|
866
852
|
```ts
|
|
867
|
-
import {
|
|
868
|
-
import type {
|
|
853
|
+
import { sortGridRows } from '@orkestrel/table'
|
|
854
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
869
855
|
|
|
870
|
-
const schema:
|
|
856
|
+
const schema: GridSchema = {
|
|
871
857
|
key: 'id',
|
|
872
858
|
columns: [
|
|
873
859
|
{ cell: 'text', key: 'id' },
|
|
@@ -876,26 +862,26 @@ const schema: TableSchema = {
|
|
|
876
862
|
}
|
|
877
863
|
const rows = [{ id: '1', age: 40 }, { id: '2' }, { id: '3', age: 30 }]
|
|
878
864
|
|
|
879
|
-
|
|
865
|
+
sortGridRows(schema, rows, [{ column: 'age', direction: 'ascending' }]).map((row) => row.id)
|
|
880
866
|
// ['2', '3', '1'] — an absent cell sorts before every present one
|
|
881
|
-
|
|
867
|
+
sortGridRows(schema, rows, []).map((row) => row.id) // ['1', '2', '3'] — no term, no movement
|
|
882
868
|
rows.map((row) => row.id) // ['1', '2', '3'] — the input is untouched
|
|
883
869
|
```
|
|
884
870
|
|
|
885
871
|
### Filtering
|
|
886
872
|
|
|
887
|
-
The
|
|
873
|
+
The grid holds at most one filter per column and keeps every row all of them accept. Composition is
|
|
888
874
|
**and** in this version: there is no either-or, and no nesting.
|
|
889
875
|
|
|
890
876
|
A filter names a column and carries only the operands its operator uses, so a `between` missing a
|
|
891
|
-
bound cannot be written down. An operator the column's cell does not admit raises `
|
|
877
|
+
bound cannot be written down. An operator the column's cell does not admit raises `GridError` coded
|
|
892
878
|
`CELL`, and an operand the column cannot hold raises the same — a `contains` against a `number`
|
|
893
879
|
column and a `between` whose bounds are the wrong shape are both refusals, not empty results.
|
|
894
880
|
|
|
895
881
|
```ts
|
|
896
|
-
import {
|
|
882
|
+
import { createGrid, isGridError } from '@orkestrel/table'
|
|
897
883
|
|
|
898
|
-
const
|
|
884
|
+
const grid = createGrid(
|
|
899
885
|
{
|
|
900
886
|
key: 'id',
|
|
901
887
|
columns: [
|
|
@@ -912,18 +898,18 @@ const table = createTable(
|
|
|
912
898
|
},
|
|
913
899
|
)
|
|
914
900
|
|
|
915
|
-
|
|
901
|
+
grid.filter.set([
|
|
916
902
|
{ column: 'name', operator: 'contains', text: 'a' },
|
|
917
903
|
{ column: 'age', operator: 'between', minimum: 40, maximum: 50 },
|
|
918
904
|
])
|
|
919
905
|
|
|
920
|
-
|
|
921
|
-
|
|
906
|
+
grid.count // 1 — both filters, and only Grace satisfies both
|
|
907
|
+
grid.view.map((row) => row.name) // ['Grace']
|
|
922
908
|
|
|
923
909
|
try {
|
|
924
|
-
|
|
910
|
+
grid.filter.set({ column: 'age', operator: 'contains', text: '4' })
|
|
925
911
|
} catch (error) {
|
|
926
|
-
if (
|
|
912
|
+
if (isGridError(error)) error.code // 'CELL' — `contains` has no meaning against a number
|
|
927
913
|
}
|
|
928
914
|
```
|
|
929
915
|
|
|
@@ -945,13 +931,13 @@ admitsFilter(age, { column: 'age', operator: 'equals', value: '36' }) // false
|
|
|
945
931
|
admitsFilter(age, { column: 'name', operator: 'equals', value: 36 }) // false — the filter names another column
|
|
946
932
|
```
|
|
947
933
|
|
|
948
|
-
`
|
|
934
|
+
`filterGridRows` is the same pass without a grid, and it keeps the order it was given.
|
|
949
935
|
|
|
950
936
|
```ts
|
|
951
|
-
import {
|
|
952
|
-
import type {
|
|
937
|
+
import { filterGridRows } from '@orkestrel/table'
|
|
938
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
953
939
|
|
|
954
|
-
const schema:
|
|
940
|
+
const schema: GridSchema = {
|
|
955
941
|
key: 'id',
|
|
956
942
|
columns: [
|
|
957
943
|
{ cell: 'text', key: 'id' },
|
|
@@ -964,23 +950,23 @@ const rows = [
|
|
|
964
950
|
{ id: '3', name: 'Bob' },
|
|
965
951
|
]
|
|
966
952
|
|
|
967
|
-
const lower =
|
|
968
|
-
const upper =
|
|
953
|
+
const lower = filterGridRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'a' }])
|
|
954
|
+
const upper = filterGridRows(schema, rows, [{ column: 'name', operator: 'contains', text: 'A' }])
|
|
969
955
|
|
|
970
956
|
lower.map((row) => row.name) // ['Ada', 'Grace']
|
|
971
957
|
upper.map((row) => row.name) // ['Ada'] — `contains` is case-sensitive
|
|
972
|
-
|
|
958
|
+
filterGridRows(schema, rows, []).length // 3 — no filter refuses nothing
|
|
973
959
|
```
|
|
974
960
|
|
|
975
961
|
### Pagination
|
|
976
962
|
|
|
977
963
|
`page` is the state, counted from one. `offset` and `count` are worked out from it and from the rows
|
|
978
|
-
the filter admits, so nothing here can drift out of step with what the
|
|
964
|
+
the filter admits, so nothing here can drift out of step with what the grid holds.
|
|
979
965
|
|
|
980
|
-
- `limit` is how many rows a page holds, or `undefined` when the
|
|
966
|
+
- `limit` is how many rows a page holds, or `undefined` when the grid is not paged. An unpaged grid
|
|
981
967
|
reports `page` 1, `offset` 0, and `count` 1, and its `view` is every row the filter admits.
|
|
982
968
|
- `offset` counts the rows skipped, from zero, which is exactly what a database query asks for.
|
|
983
|
-
- `count` is `max(1, ceil(rows / limit))`, so a paged
|
|
969
|
+
- `count` is `max(1, ceil(rows / limit))`, so a paged grid whose filter admits no rows still
|
|
984
970
|
reports one page, and that page's `view` is empty. There is no page zero, and a host drawing
|
|
985
971
|
"page 1 of 1" over an empty list needs no separate case for it.
|
|
986
972
|
- A page beyond the last one clamps to the last one. Narrowing the filter therefore moves the page
|
|
@@ -989,22 +975,22 @@ the filter admits, so nothing here can drift out of step with what the table hol
|
|
|
989
975
|
falls. Resizing is a change of magnification, not a jump to the top.
|
|
990
976
|
|
|
991
977
|
```ts
|
|
992
|
-
import {
|
|
978
|
+
import { createGrid } from '@orkestrel/table'
|
|
993
979
|
|
|
994
|
-
const
|
|
980
|
+
const grid = createGrid(
|
|
995
981
|
{ key: 'id', columns: [{ cell: 'text', key: 'id' }] },
|
|
996
982
|
{ rows: [{ id: '1' }, { id: '2' }, { id: '3' }, { id: '4' }, { id: '5' }], limit: 2 },
|
|
997
983
|
)
|
|
998
984
|
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
985
|
+
grid.pagination.count // 3 — five rows, two to a page
|
|
986
|
+
grid.pagination.move(9)
|
|
987
|
+
grid.pagination.page // 3 — clamped to the last page
|
|
988
|
+
grid.pagination.offset // 4
|
|
989
|
+
grid.view.map((row) => row.id) // ['5']
|
|
1004
990
|
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
991
|
+
grid.pagination.resize()
|
|
992
|
+
grid.pagination.limit // undefined — not paged
|
|
993
|
+
grid.view.length // 5
|
|
1008
994
|
```
|
|
1009
995
|
|
|
1010
996
|
This vocabulary is deliberately the one `@orkestrel/database` and `@orkestrel/relation` already use:
|
|
@@ -1016,53 +1002,53 @@ is in the words, so each side agrees without depending on the other.
|
|
|
1016
1002
|
|
|
1017
1003
|
### Selection and expansion
|
|
1018
1004
|
|
|
1019
|
-
Selection and expansion hold `
|
|
1005
|
+
Selection and expansion hold `GridKey` sets and nothing else, and each offers the same verbs:
|
|
1020
1006
|
`select` and `expand` add, `clear` removes, and `toggle` turns one row around. Each takes no argument to mean
|
|
1021
1007
|
every row, one key to mean one row, and a key list to mean those rows, and a list is checked in full
|
|
1022
1008
|
before any of it moves.
|
|
1023
1009
|
|
|
1024
|
-
Selecting with no argument picks **every row the
|
|
1010
|
+
Selecting with no argument picks **every row the grid holds** — not every visible one. A host
|
|
1025
1011
|
offering a header checkbox that picks the page hands that page's keys over instead, which is one
|
|
1026
1012
|
line over `view` and keeps the ambiguity where the host can see it.
|
|
1027
1013
|
|
|
1028
1014
|
```ts
|
|
1029
|
-
import {
|
|
1015
|
+
import { createGrid } from '@orkestrel/table'
|
|
1030
1016
|
|
|
1031
|
-
const
|
|
1017
|
+
const grid = createGrid(
|
|
1032
1018
|
{ key: 'id', columns: [{ cell: 'text', key: 'id' }] },
|
|
1033
1019
|
{ rows: [{ id: '1' }, { id: '2' }, { id: '3' }] },
|
|
1034
1020
|
)
|
|
1035
1021
|
|
|
1036
|
-
|
|
1037
|
-
|
|
1022
|
+
grid.selection.select(grid.view.map((row) => String(row.id))) // the page, not the grid
|
|
1023
|
+
grid.selection.keys.size // 3
|
|
1038
1024
|
|
|
1039
|
-
|
|
1040
|
-
|
|
1025
|
+
grid.selection.toggle('2')
|
|
1026
|
+
grid.selection.keys.has('2') // false
|
|
1041
1027
|
|
|
1042
|
-
|
|
1043
|
-
|
|
1028
|
+
grid.rows.remove('1')
|
|
1029
|
+
grid.selection.keys.has('1') // false — a row that leaves takes its key with it
|
|
1044
1030
|
```
|
|
1045
1031
|
|
|
1046
1032
|
What an opened row shows beside it is the host's to draw. Expansion says which rows are open and
|
|
1047
1033
|
stops there.
|
|
1048
1034
|
|
|
1049
1035
|
```ts
|
|
1050
|
-
import {
|
|
1036
|
+
import { createGrid } from '@orkestrel/table'
|
|
1051
1037
|
|
|
1052
|
-
const
|
|
1038
|
+
const grid = createGrid(
|
|
1053
1039
|
{ key: 'id', columns: [{ cell: 'text', key: 'id' }] },
|
|
1054
1040
|
{ rows: [{ id: '1' }, { id: '2' }, { id: '3' }] },
|
|
1055
1041
|
)
|
|
1056
1042
|
|
|
1057
|
-
|
|
1058
|
-
|
|
1043
|
+
grid.expansion.expand() // no argument — every row the grid holds
|
|
1044
|
+
grid.expansion.keys.size // 3
|
|
1059
1045
|
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1046
|
+
grid.expansion.clear('2')
|
|
1047
|
+
grid.expansion.expand(['2', '9']) // false — '9' names no row, so neither one opened
|
|
1048
|
+
grid.expansion.keys.has('2') // false
|
|
1063
1049
|
|
|
1064
|
-
|
|
1065
|
-
|
|
1050
|
+
grid.expansion.toggle('2')
|
|
1051
|
+
grid.expansion.keys.size // 3
|
|
1066
1052
|
```
|
|
1067
1053
|
|
|
1068
1054
|
The selection and the expansion manager are the same algorithm over their own key set, so it is
|
|
@@ -1079,10 +1065,10 @@ atomicity without writing it again.
|
|
|
1079
1065
|
|
|
1080
1066
|
```ts
|
|
1081
1067
|
import { computeKeys } from '@orkestrel/table'
|
|
1082
|
-
import type {
|
|
1068
|
+
import type { GridKey } from '@orkestrel/table'
|
|
1083
1069
|
|
|
1084
|
-
const known: readonly
|
|
1085
|
-
const picked: ReadonlySet<
|
|
1070
|
+
const known: readonly GridKey[] = ['1', '2', '3']
|
|
1071
|
+
const picked: ReadonlySet<GridKey> = new Set(['1'])
|
|
1086
1072
|
|
|
1087
1073
|
computeKeys(known, picked, '2', () => true)?.size // 2 — '2' joins '1'
|
|
1088
1074
|
computeKeys(known, picked, '9', () => true) // undefined — '9' is not a key the caller may address
|
|
@@ -1092,67 +1078,67 @@ computeKeys(known, picked, undefined, (included) => !included)?.size // 2 — ev
|
|
|
1092
1078
|
|
|
1093
1079
|
## Lifecycle and state
|
|
1094
1080
|
|
|
1095
|
-
A
|
|
1081
|
+
A grid is a live projection, not a document that settles. It has no terminal success state, no
|
|
1096
1082
|
submit, and no result: rows arrive and leave for as long as the host holds it, and every read
|
|
1097
1083
|
answers from what it holds at that moment.
|
|
1098
1084
|
|
|
1099
1085
|
The verbs that end things end different things.
|
|
1100
1086
|
|
|
1101
|
-
- **`clear` resets, and the
|
|
1102
|
-
expansion, and the page all reset to how the
|
|
1103
|
-
A cleared
|
|
1104
|
-
- **`destroy` tears down, and the
|
|
1105
|
-
did. Afterwards every write raises `
|
|
1106
|
-
what the
|
|
1087
|
+
- **`clear` resets, and the grid stays open.** Every row goes, and sort, filter, selection,
|
|
1088
|
+
expansion, and the page all reset to how the grid opened. The schema and the options do not move.
|
|
1089
|
+
A cleared grid takes rows again immediately.
|
|
1090
|
+
- **`destroy` tears down, and the grid stays readable.** Calling it twice does what calling it once
|
|
1091
|
+
did. Afterwards every write raises `GridError` coded `DESTROYED`, while every getter still answers
|
|
1092
|
+
what the grid last held — so a host can read its way out of teardown without catching anything.
|
|
1107
1093
|
|
|
1108
|
-
`destroyed` is the readable fact, and it exists so a host handed a `
|
|
1094
|
+
`destroyed` is the readable fact, and it exists so a host handed a `GridInterface` it did not
|
|
1109
1095
|
construct does not have to use an exception as control flow.
|
|
1110
1096
|
|
|
1111
1097
|
```ts
|
|
1112
|
-
import {
|
|
1098
|
+
import { createGrid, isGridError } from '@orkestrel/table'
|
|
1113
1099
|
|
|
1114
|
-
const
|
|
1100
|
+
const grid = createGrid(
|
|
1115
1101
|
{ key: 'id', columns: [{ cell: 'text', key: 'id' }] },
|
|
1116
1102
|
{ rows: [{ id: '1' }, { id: '2' }] },
|
|
1117
1103
|
)
|
|
1118
1104
|
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1105
|
+
grid.clear()
|
|
1106
|
+
grid.count // 0
|
|
1107
|
+
grid.rows.add({ id: '3' }) // a cleared grid is still open
|
|
1122
1108
|
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1109
|
+
grid.destroy()
|
|
1110
|
+
grid.destroy() // idempotent
|
|
1111
|
+
grid.destroyed // true
|
|
1112
|
+
grid.count // 1 — every getter still answers
|
|
1127
1113
|
|
|
1128
1114
|
try {
|
|
1129
|
-
|
|
1115
|
+
grid.rows.add({ id: '4' })
|
|
1130
1116
|
} catch (error) {
|
|
1131
|
-
if (
|
|
1117
|
+
if (isGridError(error)) error.code // 'DESTROYED'
|
|
1132
1118
|
}
|
|
1133
1119
|
```
|
|
1134
1120
|
|
|
1135
|
-
A write is every call that could change what the
|
|
1121
|
+
A write is every call that could change what the grid holds: `rows.add`, `rows.update`,
|
|
1136
1122
|
`rows.move`, `rows.remove`, `sort.set`, `sort.remove`, `filter.set`, `filter.remove`,
|
|
1137
1123
|
`selection.select`, `selection.clear`, `selection.toggle`, `expansion.expand`, `expansion.clear`,
|
|
1138
|
-
`expansion.toggle`, `pagination.move`, `pagination.resize`, and the
|
|
1124
|
+
`expansion.toggle`, `pagination.move`, `pagination.resize`, and the grid's own `clear`. Every one of
|
|
1139
1125
|
them raises `DESTROYED` after teardown. `destroy` itself does not.
|
|
1140
1126
|
|
|
1141
1127
|
## Events
|
|
1142
1128
|
|
|
1143
|
-
Each event carries the fact that moved. No listener sees a state the
|
|
1129
|
+
Each event carries the fact that moved. No listener sees a state the grid has not finished writing.
|
|
1144
1130
|
An event fires only when something actually moved: a write that changes nothing announces nothing.
|
|
1145
1131
|
|
|
1146
|
-
| Event | Payload
|
|
1147
|
-
| ---------- |
|
|
1148
|
-
| `write` | the row's `key`
|
|
1149
|
-
| `remove` | the row's `key`
|
|
1150
|
-
| `sort` | every current `
|
|
1151
|
-
| `filter` | every current `
|
|
1152
|
-
| `select` | the picked `
|
|
1153
|
-
| `expand` | the opened `
|
|
1154
|
-
| `paginate` | the `page` shown
|
|
1155
|
-
| `clear` | nothing
|
|
1132
|
+
| Event | Payload | Fires |
|
|
1133
|
+
| ---------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1134
|
+
| `write` | the row's `key` | Once per row admitted, written over, or moved to a different place, in the order the grid wrote them. A listener that wants the row reads it back. |
|
|
1135
|
+
| `remove` | the row's `key` | Once per row taken out, in the order the grid removed them. A `clear` is the exception; see its row. |
|
|
1136
|
+
| `sort` | every current `GridOrder` | Whenever the term list's content changes, carrying the whole list as it stands. |
|
|
1137
|
+
| `filter` | every current `GridFilter` | Whenever the filter list's content changes, carrying the whole list as it stands. |
|
|
1138
|
+
| `select` | the picked `GridKey` set | Whenever the picked set changes, carrying the whole set — including when removing rows pruned it. |
|
|
1139
|
+
| `expand` | the opened `GridKey` set | Whenever the opened set changes, carrying the whole set — including when removing rows pruned it. |
|
|
1140
|
+
| `paginate` | the `page` shown | Whenever the paged window moves: a `move`, a `resize`, and a clamp caused by a narrower filter or by rows leaving. |
|
|
1141
|
+
| `clear` | nothing | On a completed `clear`. It is the whole announcement of that reset: no `remove`, no `sort`, no `filter`, no `select`, no `expand`, and no `paginate` is emitted beside it. |
|
|
1156
1142
|
|
|
1157
1143
|
A payload is owned by the listener. `sort` and `filter` carry the whole axis because a single term is
|
|
1158
1144
|
unreadable without the rest, and `select` and `expand` carry the same `ReadonlySet` shape the
|
|
@@ -1161,21 +1147,21 @@ holds moves underneath it.
|
|
|
1161
1147
|
|
|
1162
1148
|
One call can announce more than one thing, and the order is fixed: **the rows first, then the axes
|
|
1163
1149
|
they disturbed, in the order `select`, `expand`, `paginate`.** Removing two picked rows from a paged
|
|
1164
|
-
|
|
1150
|
+
grid therefore emits `remove`, `remove`, `select`, and then `paginate` if the page had to clamp.
|
|
1165
1151
|
|
|
1166
|
-
`
|
|
1152
|
+
`GridOptions.rows` seeds quietly. Seeding announces nothing at all, so a grid opens silent and
|
|
1167
1153
|
every later write is heard.
|
|
1168
1154
|
|
|
1169
|
-
Wire listeners at construction through `
|
|
1155
|
+
Wire listeners at construction through `GridOptions.on`, or afterwards through the `emitter`. Each
|
|
1170
1156
|
reaches the same typed emitter, and a listener that throws is isolated and reported to
|
|
1171
|
-
`
|
|
1157
|
+
`GridOptions.error` rather than breaking its siblings or the grid.
|
|
1172
1158
|
|
|
1173
1159
|
```ts
|
|
1174
|
-
import {
|
|
1160
|
+
import { createGrid } from '@orkestrel/table'
|
|
1175
1161
|
|
|
1176
1162
|
const seen: string[] = []
|
|
1177
1163
|
|
|
1178
|
-
const
|
|
1164
|
+
const grid = createGrid(
|
|
1179
1165
|
{
|
|
1180
1166
|
key: 'id',
|
|
1181
1167
|
columns: [
|
|
@@ -1193,12 +1179,12 @@ const table = createTable(
|
|
|
1193
1179
|
},
|
|
1194
1180
|
)
|
|
1195
1181
|
|
|
1196
|
-
|
|
1182
|
+
grid.emitter.on('clear', () => seen.push('clear'))
|
|
1197
1183
|
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1184
|
+
grid.rows.add({ id: '2', age: 45 })
|
|
1185
|
+
grid.sort.set({ column: 'age', direction: 'ascending' })
|
|
1186
|
+
grid.sort.set({ column: 'age', direction: 'ascending' }) // the same term twice
|
|
1187
|
+
grid.clear()
|
|
1202
1188
|
|
|
1203
1189
|
seen // ['write 2', 'sort 1', 'clear'] — the repeated term moved nothing and said nothing
|
|
1204
1190
|
```
|
|
@@ -1206,13 +1192,13 @@ seen // ['write 2', 'sort 1', 'clear'] — the repeated term moved nothing and s
|
|
|
1206
1192
|
## Wire safety
|
|
1207
1193
|
|
|
1208
1194
|
A schema is data, so it travels whole. It carries no function, nothing is dropped on the way, and
|
|
1209
|
-
`
|
|
1195
|
+
`serializeGrid` and `parseGrid` are the two ends of that trip.
|
|
1210
1196
|
|
|
1211
1197
|
```ts
|
|
1212
|
-
import {
|
|
1213
|
-
import type {
|
|
1198
|
+
import { parseGrid, serializeGrid } from '@orkestrel/table'
|
|
1199
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
1214
1200
|
|
|
1215
|
-
const schema:
|
|
1201
|
+
const schema: GridSchema = {
|
|
1216
1202
|
name: 'people',
|
|
1217
1203
|
label: 'People',
|
|
1218
1204
|
key: 'id',
|
|
@@ -1222,15 +1208,15 @@ const schema: TableSchema = {
|
|
|
1222
1208
|
],
|
|
1223
1209
|
}
|
|
1224
1210
|
|
|
1225
|
-
const wire = JSON.stringify(
|
|
1226
|
-
const received =
|
|
1211
|
+
const wire = JSON.stringify(serializeGrid(schema))
|
|
1212
|
+
const received = parseGrid(JSON.parse(wire))
|
|
1227
1213
|
|
|
1228
|
-
JSON.stringify(
|
|
1229
|
-
|
|
1230
|
-
|
|
1214
|
+
JSON.stringify(serializeGrid(received ?? schema)) === wire // true
|
|
1215
|
+
parseGrid({ key: 'id', columns: 'not a list' }) // undefined
|
|
1216
|
+
parseGrid({ columns: [{ cell: 'text', key: 'id' }] }) // undefined — no `key`
|
|
1231
1217
|
```
|
|
1232
1218
|
|
|
1233
|
-
The round trip is byte-stable because both projections fix the order they emit in: `
|
|
1219
|
+
The round trip is byte-stable because both projections fix the order they emit in: `serializeGrid`
|
|
1234
1220
|
writes a schema's members in declaration order and a column's in the order the contract declares
|
|
1235
1221
|
them, and `serializeRows` writes each row's cells in the schema's column order. Ordering is what
|
|
1236
1222
|
turns "the same data" into "the same bytes", and it is the only reason a caller can compare two wire
|
|
@@ -1239,7 +1225,7 @@ forms with `===` instead of walking them.
|
|
|
1239
1225
|
That is canonicalization, not preservation. A projection reorders whatever it was handed: an object
|
|
1240
1226
|
written `columns` before `key` comes back with `key` before `columns`, because declaration order is
|
|
1241
1227
|
the order the contract declares and not the order the caller typed. So the bytes settle at the first
|
|
1242
|
-
projection, and every projection after it — of that schema, or of what `
|
|
1228
|
+
projection, and every projection after it — of that schema, or of what `parseGrid` returned from
|
|
1243
1229
|
those bytes — reproduces them exactly. Compare two wire forms, never a wire form against arbitrary
|
|
1244
1230
|
incoming bytes.
|
|
1245
1231
|
|
|
@@ -1254,13 +1240,13 @@ payload, and so does a row with no usable identity or an identity another row al
|
|
|
1254
1240
|
`null` is a cell no column can hold, and it is the refusal a wire producer meets most often: absence
|
|
1255
1241
|
here is an absent key, so a producer writing `null` for an empty field drops the key instead. There is
|
|
1256
1242
|
no partial result, because a half-accepted row set is worse than a rejected one — and the door where
|
|
1257
|
-
identity is checked is this one, so nothing that reaches the
|
|
1243
|
+
identity is checked is this one, so nothing that reaches the grid has to be checked for it twice.
|
|
1258
1244
|
|
|
1259
1245
|
```ts
|
|
1260
1246
|
import { parseRows, serializeRows } from '@orkestrel/table'
|
|
1261
|
-
import type {
|
|
1247
|
+
import type { GridSchema } from '@orkestrel/table'
|
|
1262
1248
|
|
|
1263
|
-
const schema:
|
|
1249
|
+
const schema: GridSchema = {
|
|
1264
1250
|
key: 'id',
|
|
1265
1251
|
columns: [
|
|
1266
1252
|
{ cell: 'text', key: 'id' },
|
|
@@ -1277,13 +1263,13 @@ parseRows(schema, [{ id: '1', colour: 'red' }]) // undefined — no such column
|
|
|
1277
1263
|
serializeRows(schema, [{ age: 36, id: '1' }]) // [{ id: '1', age: 36 }] — schema column order
|
|
1278
1264
|
```
|
|
1279
1265
|
|
|
1280
|
-
**What never travels is everything that is not the document.** `
|
|
1266
|
+
**What never travels is everything that is not the document.** `GridOptions` does not: `on`,
|
|
1281
1267
|
`error`, `comparators`, and `matchers` are functions or hold them, and a function has no wire form.
|
|
1282
1268
|
Neither does live state — the sort terms, the filters, the picked and opened keys, and the page are
|
|
1283
1269
|
the lens a session is looking through, not the data it is looking at. A host that wants to persist a
|
|
1284
1270
|
lens reads `sort.orders()`, `filter.filters()`, `selection.keys`, and `pagination.page` and stores
|
|
1285
1271
|
them at its own door, in its own format. This package ships no parser for them, because it would be
|
|
1286
|
-
a parser for the host's decision rather than for the
|
|
1272
|
+
a parser for the host's decision rather than for the grid's document.
|
|
1287
1273
|
|
|
1288
1274
|
The guards are the same boundary read one value at a time, and every one of them is total.
|
|
1289
1275
|
|
|
@@ -1291,55 +1277,55 @@ The guards are the same boundary read one value at a time, and every one of them
|
|
|
1291
1277
|
import {
|
|
1292
1278
|
isColumnCell,
|
|
1293
1279
|
isColumnChoice,
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1280
|
+
isGridCell,
|
|
1281
|
+
isGridColumn,
|
|
1282
|
+
isGridRow,
|
|
1283
|
+
isGridSchema,
|
|
1298
1284
|
} from '@orkestrel/table'
|
|
1299
1285
|
|
|
1300
1286
|
isColumnCell('choice') // true
|
|
1301
1287
|
isColumnCell('date') // false — a date is `text` holding an ISO string
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1288
|
+
isGridCell(36) // true
|
|
1289
|
+
isGridCell(null) // false — absence is an absent key, never null
|
|
1290
|
+
isGridRow({ id: '1', age: 36 }) // true
|
|
1291
|
+
isGridRow({ id: ['1'] }) // false
|
|
1306
1292
|
isColumnChoice({ value: 'a', label: 'A' }) // true
|
|
1307
1293
|
isColumnChoice({ value: 'a', label: 'A', colour: 'red' }) // false — an unknown member refuses it
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1294
|
+
isGridColumn({ cell: 'choice', key: 'status', choices: [] }) // true — structure only
|
|
1295
|
+
isGridSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // true
|
|
1296
|
+
isGridSchema({ columns: [] }) // false — `key` is required
|
|
1311
1297
|
```
|
|
1312
1298
|
|
|
1313
1299
|
The schema guards are where the boundary is drawn twice, because a schema can be the right shape
|
|
1314
|
-
and still be a
|
|
1315
|
-
`
|
|
1316
|
-
and parsers read. The constructor reads `
|
|
1300
|
+
and still be a grid nobody could open. `isStructuralGridSchema` answers the shape;
|
|
1301
|
+
`isGridSchema` answers the shape and the audit together, and it is the single-call guard consumers
|
|
1302
|
+
and parsers read. The constructor reads `isStructuralGridSchema` and runs `auditGrid` once so its
|
|
1317
1303
|
`SCHEMA` message retains the diagnostics.
|
|
1318
1304
|
|
|
1319
1305
|
```ts
|
|
1320
|
-
import {
|
|
1306
|
+
import { isStructuralGridSchema, isGridSchema, parseGrid } from '@orkestrel/table'
|
|
1321
1307
|
|
|
1322
1308
|
const unsound = { key: 'missing', columns: [{ cell: 'text', key: 'id' }] }
|
|
1323
1309
|
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1310
|
+
isStructuralGridSchema(unsound) // true — every member is present and typed
|
|
1311
|
+
isGridSchema(unsound) // false — `key` names no declared column
|
|
1312
|
+
parseGrid(unsound) // undefined — the parser refuses exactly what the guard refuses
|
|
1313
|
+
isStructuralGridSchema({ columns: [] }) // false — `key` is required by the shape itself
|
|
1328
1314
|
```
|
|
1329
1315
|
|
|
1330
1316
|
### Owning what arrives
|
|
1331
1317
|
|
|
1332
|
-
The cloners are how a value stops being the caller's. The
|
|
1318
|
+
The cloners are how a value stops being the caller's. The grid clones the schema at construction and
|
|
1333
1319
|
every row at admission, and it clones every row it hands back. They are exported because a consumer
|
|
1334
1320
|
building its own row store needs the same guarantee.
|
|
1335
1321
|
|
|
1336
1322
|
Construction guards the schema it was handed, owns a copy, and then guards and audits that copy, so
|
|
1337
|
-
the schema a
|
|
1323
|
+
the schema a grid opens against is the one it validated. A schema whose property reads and stored
|
|
1338
1324
|
values disagree — a proxy answering a read with one value while holding another — is refused with
|
|
1339
1325
|
`SCHEMA` instead of opened.
|
|
1340
1326
|
|
|
1341
1327
|
```ts
|
|
1342
|
-
import { cloneRow,
|
|
1328
|
+
import { cloneRow, cloneGridSchema } from '@orkestrel/table'
|
|
1343
1329
|
|
|
1344
1330
|
const row = { id: '1', age: 36 }
|
|
1345
1331
|
const owned = cloneRow(row)
|
|
@@ -1347,14 +1333,16 @@ const owned = cloneRow(row)
|
|
|
1347
1333
|
owned === row // false
|
|
1348
1334
|
Object.isFrozen(owned) // true
|
|
1349
1335
|
|
|
1350
|
-
Object.isFrozen(
|
|
1336
|
+
Object.isFrozen(cloneGridSchema({ key: 'id', columns: [{ cell: 'text', key: 'id' }] })) // true
|
|
1351
1337
|
```
|
|
1352
1338
|
|
|
1353
1339
|
### Budgets
|
|
1354
1340
|
|
|
1355
1341
|
The budgets bound how much a schema can be, so a document that arrives from a wire cannot cost
|
|
1356
|
-
unbounded memory or unbounded scanning before anything decides to trust it.
|
|
1357
|
-
|
|
1342
|
+
unbounded memory or unbounded scanning before anything decides to trust it. This package exports
|
|
1343
|
+
`COLUMN_LIMIT`, and `@orkestrel/contract` exports `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`,
|
|
1344
|
+
`TEXT_LIMIT`, and `NODE_LIMIT`, so a host can check against the same number the package checks
|
|
1345
|
+
against.
|
|
1358
1346
|
|
|
1359
1347
|
| Constant | Value | Unit | Bounds |
|
|
1360
1348
|
| -------------- | ------- | ----------------------- | ----------------------------------------- |
|
|
@@ -1367,32 +1355,32 @@ a host can check against the same number the package checks against.
|
|
|
1367
1355
|
|
|
1368
1356
|
They bind at the schema door and the value door, and which door a limit sits at is the whole story.
|
|
1369
1357
|
|
|
1370
|
-
**The schema door reports.** `
|
|
1358
|
+
**The schema door reports.** `auditGrid` counts columns, choices, names, strings, total text, and
|
|
1371
1359
|
total nodes — `meta` included, because it is retained like everything else — and returns one human
|
|
1372
|
-
diagnostic per breach. `
|
|
1360
|
+
diagnostic per breach. `createGrid` raises `SCHEMA` carrying them and `parseGrid` refuses the
|
|
1373
1361
|
schema, so no over-budget schema is ever held.
|
|
1374
1362
|
|
|
1375
|
-
**The value door refuses.** `matchesCell` checks `STRING_LIMIT
|
|
1376
|
-
column, so an over-long cell is refused before anything else looks at
|
|
1377
|
-
and a seeded row raise `CELL`; `parseRows` returns `undefined`.
|
|
1363
|
+
**The value door refuses.** `matchesCell` checks `STRING_LIMIT`, from `@orkestrel/contract`, on any
|
|
1364
|
+
string before it consults the column, so an over-long cell is refused before anything else looks at
|
|
1365
|
+
it. `rows.add`, `rows.update`, and a seeded row raise `CELL`; `parseRows` returns `undefined`.
|
|
1378
1366
|
|
|
1379
|
-
`STRING_LIMIT
|
|
1380
|
-
than 65536 code units whichever way it arrived.
|
|
1367
|
+
`STRING_LIMIT`, from `@orkestrel/contract`, is the one that stands at each door, so no string this
|
|
1368
|
+
package retains is longer than 65536 code units whichever way it arrived.
|
|
1381
1369
|
|
|
1382
1370
|
The whole-schema ceilings are what make the arithmetic safe. Whatever the per-item limits admit,
|
|
1383
1371
|
one audited schema retains at most 1048576 string code units and at most 16384 nodes, so the worst
|
|
1384
1372
|
case is those ceilings rather than the product of the others.
|
|
1385
1373
|
|
|
1386
1374
|
Rows and the structural read stay unbounded, each for its own reason. **Rows are not budgeted**: a
|
|
1387
|
-
|
|
1388
|
-
constant's name. And the structural **read** at the parse door is not bounded either — `
|
|
1375
|
+
grid legitimately holds a million of them, and a ceiling here would be product policy wearing a
|
|
1376
|
+
constant's name. And the structural **read** at the parse door is not bounded either — `parseGrid`
|
|
1389
1377
|
copies and guards every column that arrived before the audit sees one of them, so a payload four
|
|
1390
1378
|
times over `COLUMN_LIMIT` is read four times over and then refused. Bound the size of a payload at
|
|
1391
1379
|
the transport that delivers it, which is the only layer holding the bytes.
|
|
1392
1380
|
|
|
1393
1381
|
### Auditing a schema
|
|
1394
1382
|
|
|
1395
|
-
`
|
|
1383
|
+
`auditGrid` is the semantic pass beyond structural validation. It reports the domain faults listed
|
|
1396
1384
|
following and every budget breach stated earlier. The shape alone cannot see them, except an unownable `meta`,
|
|
1397
1385
|
which the structural guard also refuses so the doors stay in agreement:
|
|
1398
1386
|
|
|
@@ -1404,10 +1392,10 @@ which the structural guard also refuses so the doors stay in agreement:
|
|
|
1404
1392
|
- A `choice` column offers no choice at all, so it is a column no cell could ever fill.
|
|
1405
1393
|
- A column's `meta` cannot be owned as exact JSON.
|
|
1406
1394
|
|
|
1407
|
-
The audit runs inside `
|
|
1395
|
+
The audit runs inside `createGrid` and inside `parseGrid`, so a consumer rarely calls it directly —
|
|
1408
1396
|
but it is exported, because a schema editor wants the diagnostics before it constructs anything.
|
|
1409
|
-
`
|
|
1410
|
-
guard, the constructor, and the parser cannot disagree about which schemas a
|
|
1397
|
+
`isGridSchema` is this list's emptiness over a structurally exact value, and nothing else, so the
|
|
1398
|
+
guard, the constructor, and the parser cannot disagree about which schemas a grid can be opened
|
|
1411
1399
|
against. The guard is the yes-or-no; the audit is why.
|
|
1412
1400
|
|
|
1413
1401
|
**It returns human diagnostics, not a machine contract.** Read them, show them, log them. Do not
|
|
@@ -1415,16 +1403,16 @@ branch on their text or parse a column key out of them: the wording is free to c
|
|
|
1415
1403
|
diagnostics, and only the emptiness of the list is a promise. It returns a string list rather than a
|
|
1416
1404
|
`Result` for exactly that reason — a `Result` would dress a diagnostic list as an outcome and invite
|
|
1417
1405
|
a consumer to treat one as the other. Where a machine outcome is what you need, use the guards, or
|
|
1418
|
-
use `
|
|
1406
|
+
use `parseGrid` and read `undefined`.
|
|
1419
1407
|
|
|
1420
1408
|
```ts
|
|
1421
|
-
import {
|
|
1409
|
+
import { auditGrid } from '@orkestrel/table'
|
|
1422
1410
|
|
|
1423
|
-
|
|
1411
|
+
auditGrid({ key: 'ref', columns: [{ cell: 'text', key: 'id' }] })
|
|
1424
1412
|
// ['schema key "ref" names no declared column']
|
|
1425
|
-
|
|
1413
|
+
auditGrid({ key: 'age', columns: [{ cell: 'number', key: 'age' }] })
|
|
1426
1414
|
// ['schema key "age" names a number column, which holds no identity']
|
|
1427
|
-
|
|
1415
|
+
auditGrid({
|
|
1428
1416
|
key: 'id',
|
|
1429
1417
|
columns: [
|
|
1430
1418
|
{ cell: 'text', key: 'id' },
|
|
@@ -1432,14 +1420,14 @@ auditTable({
|
|
|
1432
1420
|
],
|
|
1433
1421
|
})
|
|
1434
1422
|
// ['column "id" is declared more than once']
|
|
1435
|
-
|
|
1423
|
+
auditGrid({ key: 'id', columns: [{ cell: 'text', key: 'id' }] }) // []
|
|
1436
1424
|
```
|
|
1437
1425
|
|
|
1438
1426
|
## Methods
|
|
1439
1427
|
|
|
1440
1428
|
The public methods of the behavioral interfaces, which their classes implement exactly and add
|
|
1441
1429
|
nothing to. Every readonly data member stays in the `## Surface` rows stated earlier, in each
|
|
1442
|
-
interface's `
|
|
1430
|
+
interface's `Signature` cell, and is not repeated here.
|
|
1443
1431
|
|
|
1444
1432
|
Every other row in the Surface tables is a data shape, a union, a constant, a function, or an error
|
|
1445
1433
|
class, so none of them carries a method table. `CellComparator` and `CellMatcher` are callable
|
|
@@ -1447,30 +1435,30 @@ function types with one call signature and no named members.
|
|
|
1447
1435
|
|
|
1448
1436
|
Where a method takes no argument, one key, or a key list, that is one method with overloads rather
|
|
1449
1437
|
than several methods. A list is checked in full before any of it moves, and the call returns
|
|
1450
|
-
`true` only when every name in it names what its manager addresses: a row the
|
|
1438
|
+
`true` only when every name in it names what its manager addresses: a row the grid holds for
|
|
1451
1439
|
`rows`, `selection`, and `expansion`, and a column the schema declares for `sort` and `filter`. So
|
|
1452
1440
|
`selection.clear('9')` is `false` for a key no row carries, while `sort.remove('age')` is `true` for
|
|
1453
1441
|
a declared `age` column nothing was sorting by — the column exists, and afterwards nothing sorts by
|
|
1454
1442
|
it either way.
|
|
1455
1443
|
|
|
1456
|
-
#### `
|
|
1444
|
+
#### `GridInterface`
|
|
1457
1445
|
|
|
1458
|
-
| Method | Returns | Summary
|
|
1459
|
-
| --------- | ------- |
|
|
1460
|
-
| `clear` | `void` | Puts the
|
|
1461
|
-
| `destroy` | `void` | Tears the
|
|
1446
|
+
| Method | Returns | Summary |
|
|
1447
|
+
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
1448
|
+
| `clear` | `void` | Puts the grid back the way it opened, holding nothing. Rows, sort, filter, selection, expansion, and the page all reset. |
|
|
1449
|
+
| `destroy` | `void` | Tears the grid down. Idempotent; afterwards every write raises `DESTROYED` and every getter still answers. |
|
|
1462
1450
|
|
|
1463
1451
|
#### `RowManagerInterface`
|
|
1464
1452
|
|
|
1465
|
-
| Method | Returns
|
|
1466
|
-
| --------- |
|
|
1467
|
-
| `row` | `
|
|
1468
|
-
| `rows` | `readonly
|
|
1469
|
-
| `add` | `void`
|
|
1470
|
-
| `update` | `boolean`
|
|
1471
|
-
| `replace` | `boolean`
|
|
1472
|
-
| `move` | `boolean`
|
|
1473
|
-
| `remove` | `void` or `boolean`
|
|
1453
|
+
| Method | Returns | Summary |
|
|
1454
|
+
| --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
1455
|
+
| `row` | `GridRow` or `undefined` | Finds one row by key; `undefined` when the grid holds no such key. |
|
|
1456
|
+
| `rows` | `readonly GridRow[]` | Reads every row the grid holds, in its own order — unfiltered, unsorted, and unpaged. |
|
|
1457
|
+
| `add` | `void` | Takes in one row or several, appending them in the order given. Every row is checked before any is admitted. |
|
|
1458
|
+
| `update` | `boolean` | Writes over one row or several, each found by the key it carries. The cells given replace; the cells left out stay. |
|
|
1459
|
+
| `replace` | `boolean` | Replaces complete rows under existing keys, removing omitted cells without moving identities. |
|
|
1460
|
+
| `move` | `boolean` | Moves one row to another place in the grid's own order, counted from zero and clamped to the rows that exist. |
|
|
1461
|
+
| `remove` | `void` or `boolean` | Takes out every row, one row, or several. Selection and expansion drop the keys of the rows that went. |
|
|
1474
1462
|
|
|
1475
1463
|
#### `TableBindingInterface`
|
|
1476
1464
|
|
|
@@ -1481,27 +1469,27 @@ it either way.
|
|
|
1481
1469
|
|
|
1482
1470
|
#### `SortManagerInterface`
|
|
1483
1471
|
|
|
1484
|
-
| Method | Returns
|
|
1485
|
-
| -------- |
|
|
1486
|
-
| `order` | `
|
|
1487
|
-
| `orders` | `readonly
|
|
1488
|
-
| `set` | `void`
|
|
1489
|
-
| `remove` | `void` or `boolean`
|
|
1472
|
+
| Method | Returns | Summary |
|
|
1473
|
+
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1474
|
+
| `order` | `GridOrder` or `undefined` | Finds one column's term; `undefined` when nothing sorts that column. |
|
|
1475
|
+
| `orders` | `readonly GridOrder[]` | Reads every term the grid sorts by, first to last, in the order they decide. |
|
|
1476
|
+
| `set` | `void` | Sorts by one column or several. A term for a column already sorted replaces its direction in place; every other term joins the end. An undeclared column raises `COLUMN`. |
|
|
1477
|
+
| `remove` | `void` or `boolean` | Stops sorting by everything, by one column, or by several. An undeclared column returns `false` and stops nothing. |
|
|
1490
1478
|
|
|
1491
1479
|
#### `FilterManagerInterface`
|
|
1492
1480
|
|
|
1493
|
-
| Method | Returns
|
|
1494
|
-
| --------- |
|
|
1495
|
-
| `filter` | `
|
|
1496
|
-
| `filters` | `readonly
|
|
1497
|
-
| `set` | `void`
|
|
1498
|
-
| `remove` | `void` or `boolean`
|
|
1481
|
+
| Method | Returns | Summary |
|
|
1482
|
+
| --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1483
|
+
| `filter` | `GridFilter` or `undefined` | Finds one column's filter; `undefined` when nothing filters that column. |
|
|
1484
|
+
| `filters` | `readonly GridFilter[]` | Reads every filter the grid keeps rows by, in the order they were set. |
|
|
1485
|
+
| `set` | `void` | Filters one column or several. A filter for a column already filtered replaces it; every other one joins the end. An undeclared column raises `COLUMN`, and a filter the column does not admit raises `CELL`. |
|
|
1486
|
+
| `remove` | `void` or `boolean` | Stops filtering everything, one column, or several. An undeclared column returns `false` and stops nothing. |
|
|
1499
1487
|
|
|
1500
1488
|
#### `SelectionManagerInterface`
|
|
1501
1489
|
|
|
1502
1490
|
| Method | Returns | Summary |
|
|
1503
1491
|
| -------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
1504
|
-
| `select` | `void` or `boolean` | Picks every row the
|
|
1492
|
+
| `select` | `void` or `boolean` | Picks every row the grid holds, one row, or several. Every row, not every visible one. |
|
|
1505
1493
|
| `clear` | `void` or `boolean` | Drops every pick, one pick, or several. A known key that was not picked still answers `true`. |
|
|
1506
1494
|
| `toggle` | `boolean` | Picks one row, or drops it when it is already picked; over a list, turns each row around on its own. |
|
|
1507
1495
|
|
|
@@ -1509,7 +1497,7 @@ it either way.
|
|
|
1509
1497
|
|
|
1510
1498
|
| Method | Returns | Summary |
|
|
1511
1499
|
| -------- | ------------------- | --------------------------------------------------------------------------------------------------- |
|
|
1512
|
-
| `expand` | `void` or `boolean` | Opens every row the
|
|
1500
|
+
| `expand` | `void` or `boolean` | Opens every row the grid holds, one row, or several. |
|
|
1513
1501
|
| `clear` | `void` or `boolean` | Closes every row, one row, or several. A known key that was not open still answers `true`. |
|
|
1514
1502
|
| `toggle` | `boolean` | Opens one row, or closes it when it is already open; over a list, turns each row around on its own. |
|
|
1515
1503
|
|
|
@@ -1522,27 +1510,27 @@ it either way.
|
|
|
1522
1510
|
|
|
1523
1511
|
### Errors
|
|
1524
1512
|
|
|
1525
|
-
`
|
|
1526
|
-
value with `
|
|
1513
|
+
`GridError` carries a machine-readable `code` and an optional structured `context`. Narrow a caught
|
|
1514
|
+
value with `isGridError` and branch on `code`; never match on message text.
|
|
1527
1515
|
|
|
1528
|
-
| Code | Raised when
|
|
1529
|
-
| ----------- |
|
|
1530
|
-
| `SCHEMA` | The schema is not a
|
|
1531
|
-
| `COLUMN` | A term or a filter names a column the schema does not declare.
|
|
1532
|
-
| `KEY` | A row's identity is missing, unusable, already taken, or repeated inside one batch.
|
|
1533
|
-
| `CELL` | A cell is one its column cannot hold, or a filter's operator or operand is one its column cannot take.
|
|
1534
|
-
| `DESTROYED` | A write reached a
|
|
1516
|
+
| Code | Raised when |
|
|
1517
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1518
|
+
| `SCHEMA` | The schema is not a grid schema, or `auditGrid` found a domain fault or a budget breach — `createGrid` and the `Grid` constructor raise those. `serializeGrid` and `cloneGridSchema` raise it at their own door for a `meta` no clone can own, which the guard and the audit refuse first for every schema whose reads are stable. |
|
|
1519
|
+
| `COLUMN` | A term or a filter names a column the schema does not declare. |
|
|
1520
|
+
| `KEY` | A row's identity is missing, unusable, already taken, or repeated inside one batch. |
|
|
1521
|
+
| `CELL` | A cell is one its column cannot hold, or a filter's operator or operand is one its column cannot take. |
|
|
1522
|
+
| `DESTROYED` | A write reached a grid that has been torn down. |
|
|
1535
1523
|
|
|
1536
1524
|
```ts
|
|
1537
|
-
import {
|
|
1525
|
+
import { createGrid, isGridError } from '@orkestrel/table'
|
|
1538
1526
|
|
|
1539
1527
|
try {
|
|
1540
|
-
|
|
1528
|
+
createGrid({ key: 'missing', columns: [{ cell: 'text', key: 'id' }] })
|
|
1541
1529
|
} catch (error) {
|
|
1542
|
-
if (
|
|
1530
|
+
if (isGridError(error)) error.code // 'SCHEMA'
|
|
1543
1531
|
}
|
|
1544
1532
|
|
|
1545
|
-
const
|
|
1533
|
+
const grid = createGrid({
|
|
1546
1534
|
key: 'id',
|
|
1547
1535
|
columns: [
|
|
1548
1536
|
{ cell: 'text', key: 'id' },
|
|
@@ -1551,33 +1539,33 @@ const table = createTable({
|
|
|
1551
1539
|
})
|
|
1552
1540
|
|
|
1553
1541
|
try {
|
|
1554
|
-
|
|
1542
|
+
grid.sort.set({ column: 'nope', direction: 'ascending' })
|
|
1555
1543
|
} catch (error) {
|
|
1556
|
-
if (
|
|
1544
|
+
if (isGridError(error)) error.code // 'COLUMN'
|
|
1557
1545
|
}
|
|
1558
1546
|
|
|
1559
1547
|
try {
|
|
1560
|
-
|
|
1548
|
+
grid.rows.add({ id: '1', age: 'twelve' })
|
|
1561
1549
|
} catch (error) {
|
|
1562
|
-
if (
|
|
1550
|
+
if (isGridError(error)) error.code // 'CELL'
|
|
1563
1551
|
}
|
|
1564
1552
|
|
|
1565
|
-
|
|
1553
|
+
grid.rows.rows().length // 0 — a refused write changed nothing
|
|
1566
1554
|
```
|
|
1567
1555
|
|
|
1568
|
-
`
|
|
1569
|
-
only needs `
|
|
1556
|
+
`createGrid` and `new Grid(...)` are the same construction. Prefer the factory at a call site that
|
|
1557
|
+
only needs `GridInterface`; reach for the class where a class holds a grid as its own field and
|
|
1570
1558
|
wants the concrete type.
|
|
1571
1559
|
|
|
1572
1560
|
```ts
|
|
1573
|
-
import {
|
|
1561
|
+
import { Grid } from '@orkestrel/table'
|
|
1574
1562
|
|
|
1575
|
-
const
|
|
1563
|
+
const grid = new Grid(
|
|
1576
1564
|
{ key: 'id', columns: [{ cell: 'text', key: 'id' }] },
|
|
1577
1565
|
{ rows: [{ id: '1' }] },
|
|
1578
1566
|
)
|
|
1579
1567
|
|
|
1580
|
-
|
|
1568
|
+
grid.count // 1
|
|
1581
1569
|
```
|
|
1582
1570
|
|
|
1583
1571
|
## Contract
|
|
@@ -1591,26 +1579,26 @@ These invariants hold across [`src/core`](../src/core) and this guide.
|
|
|
1591
1579
|
2. **Documented methods equal interface methods.** Each `## Methods` table lists exactly its
|
|
1592
1580
|
interface's call-signature members, and each class implements every one and adds no public
|
|
1593
1581
|
behavior beyond them. Each interface has one table and one class.
|
|
1594
|
-
3. **Identity is a declared column's non-empty string cell.** `
|
|
1582
|
+
3. **Identity is a declared column's non-empty string cell.** `GridSchema.key` is required and must
|
|
1595
1583
|
name a declared column. A row whose cell there is missing, empty, or not a string is refused with
|
|
1596
|
-
`KEY`, and so is a key the
|
|
1584
|
+
`KEY`, and so is a key the grid already holds or a key repeated inside one batch. There is no
|
|
1597
1585
|
default column, no positional fallback, and no key generation anywhere in this package.
|
|
1598
|
-
4. **A row is owned at admission and at every read.** The
|
|
1586
|
+
4. **A row is owned at admission and at every read.** The grid clones and freezes each row it
|
|
1599
1587
|
admits and each row it hands back, and clones and freezes the schema at construction. An edit to
|
|
1600
|
-
the object a caller passed changes nothing inside the
|
|
1588
|
+
the object a caller passed changes nothing inside the grid, and no getter returns a live internal
|
|
1601
1589
|
reference.
|
|
1602
1590
|
5. **A write is all-or-nothing, and it refuses by raising or by returning `false`.** `rows.add`,
|
|
1603
1591
|
`rows.update`, `rows.remove`, `sort.set`, `sort.remove`, `filter.set`, `filter.remove`, and every
|
|
1604
1592
|
0/1/N verb on selection and expansion check the whole argument before any of it lands. A bad
|
|
1605
1593
|
value raises `KEY`, `CELL`, or `COLUMN`. A name that nothing answers to returns `false` and raises
|
|
1606
1594
|
nothing — an unheld row key for `rows`, `selection`, and `expansion`, and an undeclared column for
|
|
1607
|
-
`sort.remove` and `filter.remove`. Either way the
|
|
1595
|
+
`sort.remove` and `filter.remove`. Either way the grid is left exactly as it was.
|
|
1608
1596
|
6. **`update` merges and cannot move a key.** The cells given replace the cells held and the cells
|
|
1609
1597
|
left out stay as they are, and the row is found by the key it carries — so no sequence of
|
|
1610
1598
|
`update` calls changes any row's identity.
|
|
1611
1599
|
7. **The view is derived, never stored.** `view`, `count`, `pagination.offset`, and
|
|
1612
1600
|
`pagination.count` are worked out on every read from the rows, the filters, the terms, and
|
|
1613
|
-
`page`. Nothing caches them, so none of them can disagree with what the
|
|
1601
|
+
`page`. Nothing caches them, so none of them can disagree with what the grid holds.
|
|
1614
1602
|
8. **The lens applies in one order.** `view` is filtered, then sorted, then paged, always. A filter
|
|
1615
1603
|
therefore decides `count` and the page count, and paging never reorders anything.
|
|
1616
1604
|
9. **Sorting is stable and its terms are ordered.** The first term decides and each later term
|
|
@@ -1619,24 +1607,24 @@ These invariants hold across [`src/core`](../src/core) and this guide.
|
|
|
1619
1607
|
in the list. A `choice` column compares by the order its `choices` declares, a `flag` compares
|
|
1620
1608
|
false before true, a `number` by magnitude, and a `text` lexically. An absent cell sorts before
|
|
1621
1609
|
every present one in ascending order.
|
|
1622
|
-
10. **Filters are and-only, one per column.** The
|
|
1610
|
+
10. **Filters are and-only, one per column.** The grid holds at most one filter per column and
|
|
1623
1611
|
keeps the rows every one of them accepts. There is no either-or composition and no nesting. An
|
|
1624
1612
|
operator its column's cell does not admit, and an operand its column cannot hold, are both `CELL`
|
|
1625
1613
|
refusals rather than empty results.
|
|
1626
1614
|
11. **An override replaces one column's default and nothing else.** A `comparators` or `matchers`
|
|
1627
1615
|
entry is consulted only for the column its key names, receives `undefined` for a row carrying no
|
|
1628
1616
|
cell there, and never changes which columns exist. A comparator always describes ascending order
|
|
1629
|
-
and `
|
|
1617
|
+
and `GridDirection` is applied to its result. An entry naming an undeclared column is never
|
|
1630
1618
|
consulted and is not an error.
|
|
1631
|
-
12. **Selection and expansion hold keys, and prune.** Both hold `
|
|
1632
|
-
survives a sort, a filter, and a page turn; and a row leaving the
|
|
1633
|
-
both. Selecting with no argument picks every row the
|
|
1619
|
+
12. **Selection and expansion hold keys, and prune.** Both hold `GridKey` sets only, so a pick
|
|
1620
|
+
survives a sort, a filter, and a page turn; and a row leaving the grid removes its key from
|
|
1621
|
+
both. Selecting with no argument picks every row the grid holds, not every row in `view`.
|
|
1634
1622
|
13. **Pagination is derived and clamps.** `page` is the only stored fact, counted from one;
|
|
1635
1623
|
`offset` is `(page - 1) * limit` and zero when unpaged; `count` is `max(1, ceil(rows / limit))`
|
|
1636
|
-
and `1` when unpaged — so a paged
|
|
1624
|
+
and `1` when unpaged — so a paged grid with no admitted rows holds one page, and that page's
|
|
1637
1625
|
`view` is empty. A page beyond the last clamps to the last, including when a filter or a removal
|
|
1638
1626
|
shrinks the rows underneath it. `resize` keeps the first row the view was showing.
|
|
1639
|
-
14. **Every event fires after commit, and a no-op is silent.** No listener sees a state the
|
|
1627
|
+
14. **Every event fires after commit, and a no-op is silent.** No listener sees a state the grid has
|
|
1640
1628
|
not finished writing, and a call that moves nothing announces nothing — the same sort term twice,
|
|
1641
1629
|
a toggle back to where it was, a `move` to the index a row already occupies. When one call moves
|
|
1642
1630
|
several things, the rows announce first and then the axes they disturbed, in the order `select`,
|
|
@@ -1644,18 +1632,18 @@ These invariants hold across [`src/core`](../src/core) and this guide.
|
|
|
1644
1632
|
15. **`clear` is one announcement and `destroy` is idempotent.** `clear` emits `clear` alone,
|
|
1645
1633
|
whatever it reset, so a reset of ten thousand rows is one event. `destroy` called twice does what
|
|
1646
1634
|
calling it once did; afterwards every write raises `DESTROYED` while every getter still answers
|
|
1647
|
-
what the
|
|
1635
|
+
what the grid last held, and `destroyed` reports the fact so a host need not catch to learn it.
|
|
1648
1636
|
16. **Guards are total and parsers refuse.** No `is*` throws for any input — unexpected prototype,
|
|
1649
1637
|
symbol key, cycle, or depth. No `parse*` throws; each returns `undefined` on refusal. A
|
|
1650
1638
|
guard-valid value is never refused by its parser, and every parsed result satisfies its guard.
|
|
1651
|
-
`
|
|
1652
|
-
empty `
|
|
1653
|
-
`
|
|
1654
|
-
17. **Only data crosses the wire, and the round trip is byte-stable.** `
|
|
1639
|
+
`isGridSchema` is therefore semantic and not merely structural: it is the exact shape plus an
|
|
1640
|
+
empty `auditGrid`, which is exactly what `parseGrid` and the `Grid` constructor demand.
|
|
1641
|
+
`isStructuralGridSchema` is the shape alone, for a caller running the audit itself.
|
|
1642
|
+
17. **Only data crosses the wire, and the round trip is byte-stable.** `serializeGrid` and
|
|
1655
1643
|
`serializeRows` emit in canonical order — a schema's members in declaration order, a column's in
|
|
1656
1644
|
the order the contract declares them, and a row's cells in the schema's column order. Incoming
|
|
1657
1645
|
key order is canonicalized rather than preserved, so the bytes settle at the first projection
|
|
1658
|
-
and every projection after it reproduces them, including a projection of what `
|
|
1646
|
+
and every projection after it reproduces them, including a projection of what `parseGrid` or
|
|
1659
1647
|
`parseRows` returned from those bytes. `meta` survives verbatim key for key. Options and live
|
|
1660
1648
|
state have no projection at all: functions, sort terms, filters, picked keys, opened keys, and
|
|
1661
1649
|
the page never travel.
|
|
@@ -1663,14 +1651,15 @@ These invariants hold across [`src/core`](../src/core) and this guide.
|
|
|
1663
1651
|
no usable identity, when two rows share one, when a cell's column cannot hold it, or when a key
|
|
1664
1652
|
names no declared column. It coerces a numeric string for a `number` column and `'true'` /
|
|
1665
1653
|
`'false'` for a `flag` column, and nothing else.
|
|
1666
|
-
19. **Every retained size is budgeted.** `
|
|
1667
|
-
`
|
|
1668
|
-
|
|
1669
|
-
`
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
1673
|
-
|
|
1654
|
+
19. **Every retained size is budgeted.** `auditGrid` reports a breach of this package's
|
|
1655
|
+
`COLUMN_LIMIT` or of the `@orkestrel/contract` budgets `CHOICE_LIMIT`, `NAME_LIMIT`,
|
|
1656
|
+
`STRING_LIMIT`, `TEXT_LIMIT`, and `NODE_LIMIT`, so `createGrid` raises `SCHEMA` and
|
|
1657
|
+
`parseGrid` refuses; `matchesCell` refuses a string breaching `STRING_LIMIT`, from
|
|
1658
|
+
`@orkestrel/contract`, before it consults the column, so a write raises `CELL` and `parseRows`
|
|
1659
|
+
returns `undefined`. `TEXT_LIMIT` and `NODE_LIMIT`, from `@orkestrel/contract`, are whole-schema
|
|
1660
|
+
ceilings, `meta` included, so the per-item limits never multiply. Row count is deliberately
|
|
1661
|
+
unbudgeted, and so is the structural read at the parse door, which is the transport's to bound.
|
|
1662
|
+
20. **`auditGrid` returns diagnostics, not a contract.** The list's emptiness is the promise. The
|
|
1674
1663
|
wording of its strings is not. Never parse them.
|
|
1675
1664
|
21. **Temporal values are ISO text compared lexically, under one spelling.** A date, a time, and a
|
|
1676
1665
|
timestamp are `text` cells, and lexical order is chronological order only where a column's
|
|
@@ -1692,22 +1681,22 @@ this package answers today through a mechanism it already exposes.
|
|
|
1692
1681
|
|
|
1693
1682
|
| Concept | Layer | Why it sits there |
|
|
1694
1683
|
| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1695
|
-
| Rendering | host | The
|
|
1696
|
-
| ARIA and roles | host | `label` and `help` are the strings an accessible
|
|
1697
|
-
| Keyboard and focus | host | Arrow keys, roving focus, and type-ahead are input gestures over drawn cells. The
|
|
1698
|
-
| Virtualization | host | Which rows are cheap to draw is a measurement of drawn things. `pagination` already gives a windowing host `offset` and `limit`, and a virtualizer that wants the whole list leaves the
|
|
1699
|
-
| Column resizing | host | A width is pixels. `meta` carries one when a host must ship it in the schema, and the
|
|
1684
|
+
| Rendering | host | The grid owns values, not pixels. It names no host type, so one grid serves a browser, a terminal, a report, and an export equally — and the moment it drew one of them it would serve only that one. |
|
|
1685
|
+
| ARIA and roles | host | `label` and `help` are the strings an accessible table needs. The roles, the ids, and their uniqueness belong to the layer that owns the elements. |
|
|
1686
|
+
| Keyboard and focus | host | Arrow keys, roving focus, and type-ahead are input gestures over drawn cells. The grid has no cursor because it has no cells on a screen. |
|
|
1687
|
+
| Virtualization | host | Which rows are cheap to draw is a measurement of drawn things. `pagination` already gives a windowing host `offset` and `limit`, and a virtualizer that wants the whole list leaves the grid unpaged and reads `view`, which is every admitted row in sort order. `rows()` is the store's own order and ignores the lens. |
|
|
1688
|
+
| Column resizing | host | A width is pixels. `meta` carries one when a host must ship it in the schema, and the grid never reads it. |
|
|
1700
1689
|
| Column reordering and hiding | seam | `columns` order is presentation order and `hidden` is the flag. Reordering is building the next schema, which is one line over the array a host already holds. |
|
|
1701
|
-
| Row drag-and-drop | seam | The gesture is the host's; the result is `rows.move(key, index)`, which is the one verb that writes the
|
|
1690
|
+
| Row drag-and-drop | seam | The gesture is the host's; the result is `rows.move(key, index)`, which is the one verb that writes the grid's own order. |
|
|
1702
1691
|
| Sticky columns and headers | host | Which columns stay put while the rest scroll is a layout decision about drawn elements. |
|
|
1703
1692
|
| Or-filters and nested groups | out | v1 composes filters with **and** only, one per column, which is what a filter bar produces. The one thing it cannot express at all is the global search box that matches a term against every column: that is an or across columns, and a host wanting one narrows `rows()` with its own predicate and holds the result itself. Either-or turns a flat list into a tree and takes every guard, parser, and wire form with it. |
|
|
1704
|
-
| Grouping and aggregation | out | Group headers, subtotals, and rollups add a second row kind that is not a row, and a fold that is not a filter. `view` stays a flat list of the rows the
|
|
1693
|
+
| Grouping and aggregation | out | Group headers, subtotals, and rollups add a second row kind that is not a row, and a fold that is not a filter. `view` stays a flat list of the rows the grid holds. |
|
|
1705
1694
|
| Tree and hierarchical rows | out | A parent key would make `view` a traversal rather than a projection, and expansion would mean "show children" instead of "this row is open". Expansion here says only which rows are open. |
|
|
1706
1695
|
| Editing transactions | out | A staged edit set with commit and rollback is a second store beside the row store, and two writers that can disagree. A host that needs one holds the pending values and calls `update` once. |
|
|
1707
|
-
| Undo and history | out | The
|
|
1696
|
+
| Undo and history | out | The grid holds the rows. A stack of everything before is a host concern with a host's retention policy, built over the same `update` and `remove` calls. |
|
|
1708
1697
|
| Async data sources | host | Every read here is synchronous, so `view` is right the instant anything moves. Fetching, paging a server, and reconciling a response are the host's; it reads the lens and calls `add` or `clear`. |
|
|
1709
1698
|
| Server-side paging | seam | `sort.orders()`, `filter.filters()`, `pagination.offset`, and `pagination.limit` are already the shape a query asks for, in the vocabulary `@orkestrel/database` uses. |
|
|
1710
|
-
| Row count budget | out | A
|
|
1699
|
+
| Row count budget | out | A grid legitimately holds a million rows. The budgets bound one schema's declarations, which arrive from a wire; how many rows a host holds is the host's memory to spend. |
|
|
1711
1700
|
| Parsing a lens off the wire | out | Sort terms, filters, and the picked keys are what a session is looking through, not the document. A host persisting them owns the format, so a parser here would parse the host's decision. |
|
|
1712
1701
|
| Case folding and collation | seam | `contains` compares case-sensitively and `text` compares with the language's own string order. Locale is a decision this package cannot make for a host, so a `CellMatcher` or `CellComparator` makes it. |
|
|
1713
1702
|
| A temporal cell | out | ISO text written to one canonical spelling per instant — one offset, one precision, and no alternate spelling of a given date or time — sorts chronologically already, so a temporal cell would add a variant that behaves exactly like `text` and a calendar to go with it. Normalizing to that one canonical representation is the host's, and a `CellComparator` covers a column that arrives mixed. |
|
|
@@ -1722,44 +1711,43 @@ this package answers today through a mechanism it already exposes.
|
|
|
1722
1711
|
|
|
1723
1712
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ barrel bijection, the
|
|
1724
1713
|
interface ↔ class method bijections, and the equality gate: every `Summary` cell against its
|
|
1725
|
-
declaration's description paragraph, the titled `Open a
|
|
1714
|
+
declaration's description paragraph, the titled `Open a grid` fence against the `@example` block
|
|
1726
1715
|
of that title (pinned so the titled pair cannot be retired silently), and the README pitch against
|
|
1727
1716
|
this guide's tagline. It also runs the preceding worked examples against the real source so a
|
|
1728
1717
|
documented value that the code contradicts fails.
|
|
1729
|
-
- [`tests/src/core/
|
|
1718
|
+
- [`tests/src/core/Grid.test.ts`](../tests/src/core/Grid.test.ts) — construction, schema
|
|
1730
1719
|
ownership, seeding, the derived `view` and `count`, emission order, `clear`, `destroy`, and writes
|
|
1731
1720
|
after teardown.
|
|
1732
|
-
- [`tests/src/core/
|
|
1721
|
+
- [`tests/src/core/grids/RowManager.test.ts`](../tests/src/core/grids/RowManager.test.ts) —
|
|
1733
1722
|
`row`, `rows`, `add`, `update`, `move`, `remove`, batch atomicity, and identity refusals.
|
|
1734
|
-
- [`tests/src/core/
|
|
1723
|
+
- [`tests/src/core/grids/SortManager.test.ts`](../tests/src/core/grids/SortManager.test.ts) —
|
|
1735
1724
|
`order`, `orders`, `set`, `remove`, in-place replacement, stability, and comparator overrides.
|
|
1736
|
-
- [`tests/src/core/
|
|
1725
|
+
- [`tests/src/core/grids/FilterManager.test.ts`](../tests/src/core/grids/FilterManager.test.ts) —
|
|
1737
1726
|
`filter`, `filters`, `set`, `remove`, and-composition, operator refusals, and matcher overrides.
|
|
1738
|
-
- [`tests/src/core/
|
|
1727
|
+
- [`tests/src/core/grids/SelectionManager.test.ts`](../tests/src/core/grids/SelectionManager.test.ts)
|
|
1739
1728
|
— `select`, `clear`, `toggle`, the 0/1/N overloads, and pruning on removal.
|
|
1740
|
-
- [`tests/src/core/
|
|
1729
|
+
- [`tests/src/core/grids/ExpansionManager.test.ts`](../tests/src/core/grids/ExpansionManager.test.ts)
|
|
1741
1730
|
— `expand`, `clear`, `toggle`, the 0/1/N overloads, and pruning on removal.
|
|
1742
|
-
- [`tests/src/core/
|
|
1731
|
+
- [`tests/src/core/grids/KeyManager.test.ts`](../tests/src/core/grids/KeyManager.test.ts) — the
|
|
1743
1732
|
0/1/N forms, the unknown-key refusal, the announcement only on a move, the owned key set, and the
|
|
1744
1733
|
gate throw passed through.
|
|
1745
|
-
- [`tests/src/core/
|
|
1746
|
-
— `page`, `limit`, `offset`, `count`, `move`, `resize`, clamping, and the unpaged
|
|
1734
|
+
- [`tests/src/core/grids/PaginationManager.test.ts`](../tests/src/core/grids/PaginationManager.test.ts)
|
|
1735
|
+
— `page`, `limit`, `offset`, `count`, `move`, `resize`, clamping, and the unpaged grid.
|
|
1747
1736
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `extractColumn`,
|
|
1748
|
-
`
|
|
1749
|
-
`compareCells`, `admitsFilter`, `matchesFilter`, `
|
|
1750
|
-
`
|
|
1737
|
+
`extractGridKey`, `computeKeys`, `mergeTerms`, `removeTerms`, `matchesTerms`, `matchesCell`,
|
|
1738
|
+
`compareCells`, `admitsFilter`, `matchesFilter`, `filterGridRows`, `sortGridRows`, `auditGrid`,
|
|
1739
|
+
`serializeGrid`, `serializeRows`, and the budgets.
|
|
1751
1740
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard against
|
|
1752
|
-
valid, off-shape, and untrusted input, plus guard/parser soundness in both
|
|
1753
|
-
|
|
1741
|
+
valid, off-shape, and untrusted input, the cell registry, plus guard/parser soundness in both
|
|
1742
|
+
directions.
|
|
1743
|
+
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseGrid`, `parseRows`,
|
|
1754
1744
|
the coercions, identity at the parse door, and the canonical byte-stable round trip.
|
|
1755
1745
|
- [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — every clone is owned,
|
|
1756
1746
|
frozen, and deep enough that no caller reference survives.
|
|
1757
|
-
- [`tests/src/core/
|
|
1758
|
-
|
|
1759
|
-
- [`tests/src/core/
|
|
1760
|
-
|
|
1761
|
-
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createTable` returns
|
|
1762
|
-
a working `TableInterface`.
|
|
1747
|
+
- [`tests/src/core/errors.test.ts`](../tests/src/core/errors.test.ts) — `GridError`'s `code` and
|
|
1748
|
+
`context`, and `isGridError` narrowing.
|
|
1749
|
+
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createGrid` returns
|
|
1750
|
+
a working `GridInterface`.
|
|
1763
1751
|
- [`tests/src/core/index.test.ts`](../tests/src/core/index.test.ts) — the barrel resolves every
|
|
1764
1752
|
documented export.
|
|
1765
1753
|
|