ui-sdk-table-vue 0.1.0 → 0.1.2

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.
@@ -0,0 +1,132 @@
1
+ # Editing
2
+
3
+ Let a person change the value of a cell, check it first, and put it into your rows.
4
+
5
+ The table never writes a row. It reports each edit through `@cell-edit`, and the app puts the value into its rows. `applyEdits` does that for plain rows.
6
+
7
+ ```vue title="prices.vue"
8
+ <script setup lang="ts">
9
+ import {
10
+ applyEdits,
11
+ Table,
12
+ type CellEdit,
13
+ type ColumnDef,
14
+ type StandardSchemaV1,
15
+ type TableEditDetails,
16
+ } from 'ui-sdk-table-vue'
17
+ import { shallowRef } from 'vue'
18
+
19
+ type Product = { id: string; name: string; price: number; stock: number }
20
+
21
+ // Any Standard Schema works: Zod, Valibot, ArkType. This one is written by hand.
22
+ function check(test: (value: unknown) => string | undefined): StandardSchemaV1 {
23
+ return {
24
+ '~standard': {
25
+ version: 1,
26
+ vendor: 'example',
27
+ validate: (value) => {
28
+ const message = test(value)
29
+ return message === undefined ? { value } : { issues: [{ message }] }
30
+ },
31
+ },
32
+ }
33
+ }
34
+
35
+ const columns: ColumnDef<Product>[] = [
36
+ { id: 'name', header: 'Product', editable: false },
37
+ {
38
+ id: 'price',
39
+ header: 'Price',
40
+ format: 'decimal',
41
+ numberKeyboard: true,
42
+ schema: check((value) =>
43
+ typeof value === 'number' && value >= 0 ? undefined : 'A price is a number, zero or more.',
44
+ ),
45
+ },
46
+ {
47
+ id: 'stock',
48
+ header: 'In stock',
49
+ format: 'integer',
50
+ numberKeyboard: true,
51
+ schema: check((value) =>
52
+ Number.isInteger(value) && Number(value) >= 0 ? undefined : 'Stock is a whole number.',
53
+ ),
54
+ },
55
+ ]
56
+
57
+ // The rows are yours. The table reports an edit and never writes a row.
58
+ const rows = shallowRef<Product[]>([
59
+ { id: 'p1', name: 'Green tea', price: 6.5, stock: 40 },
60
+ { id: 'p2', name: 'Dark coffee', price: 9.9, stock: 12 },
61
+ { id: 'p3', name: 'Oat cookies', price: 3.2, stock: 75 },
62
+ ])
63
+ const last = shallowRef('Nothing edited yet.')
64
+
65
+ function onCellEdit(edits: readonly CellEdit<Product>[], details: TableEditDetails) {
66
+ rows.value = applyEdits(rows.value, edits)
67
+ const [edit] = edits
68
+ if (edit)
69
+ last.value = `${edit.row.name}: ${edit.column.header} ${edit.previous} to ${edit.value}, by ${details.reason}`
70
+ }
71
+ </script>
72
+
73
+ <template>
74
+ <Table :rows="rows" :columns="columns" editable aria-label="Prices" @cell-edit="onCellEdit" />
75
+ <p role="status">{{ last }}</p>
76
+ </template>
77
+ ```
78
+
79
+ Double-press a price, type 7, and press Enter. The line under the table says what changed. Type -1 and the editor stays open with the reason. Product names cannot be edited.
80
+
81
+ ## Turn it on
82
+
83
+ - `editable` on the table lets a person edit every cell. `editable` on a column says otherwise for its cells: `false`, or a function `(row) => boolean` for some rows.
84
+ - `@cell-edit` gets `(edits, details)`. Each edit has `rowId`, `columnId`, `row` (your object, as it was before), `column`, `value` and `previous`. `details.reason` says how it came: `enter-key`, `tab-key`, `focus-out`, `paste` or `imperative`. `details.cancel()` refuses the edit.
85
+ - `applyEdits(rows, edits, getRowId?)` returns a new array with a new object for each row that changed. The other rows stay the same objects. It finds the row of an edit by its object, and by its id when the object was replaced already. Pass the `getRowId` of the table when it has one. It reads the top level only: the child rows of a tree need your own code.
86
+
87
+ ## Keys
88
+
89
+ | Key | On a cell that can be edited |
90
+ | --- | --- |
91
+ | Enter, F2 or a double press | Opens the editor with the value |
92
+ | A character | Opens the editor with that character |
93
+ | Enter in the editor | Saves, and focus goes back to the cell |
94
+ | Tab, Shift+Tab in the editor | Saves and goes to the next or the cell before |
95
+ | Escape in the editor | Closes it and puts the value back |
96
+ | A press elsewhere | Saves |
97
+
98
+ The arrows in the editor move the caret. Without an editor, Tab leaves the table.
99
+
100
+ ## Check a value
101
+
102
+ A text becomes a value in two steps:
103
+
104
+ 1. `parse(text, row)` of the column makes the value. Without it, the value that the cell holds now decides: a number stays a number, a boolean a boolean, a date a date, and anything else gets the text. An empty text empties a number or a date.
105
+ 2. `schema` of the column checks the value. Any Standard Schema works: Zod, Valibot, ArkType. A refusal keeps the editor open with the message of the schema.
106
+
107
+ A check can answer with a promise. The editor then waits (`data-checking`), and Escape takes the edit back.
108
+
109
+ `numberKeyboard: true` on a column gives the field of its editor `inputmode="decimal"`, so a phone shows its number keyboard. The field stays a text field and never `type="number"`.
110
+
111
+ ## Your own editor
112
+
113
+ `#editor` and `#edit-{column id}` fill the editor of a cell. They get `row`, `column`, `value`, `text`, `error`, `checking`, `mode`, `typed`, `inputMode`, `save(value, event)` and `cancel()`. The control must take focus itself. A `save` goes through the same check as the field of the table.
114
+
115
+ ## From code
116
+
117
+ `controller.editCell(rowId, columnId, value)` gives a cell a value with the check of its column, and reports it with the reason `imperative`. It throws with the reason when the value is refused. `startEdit` opens the editor of a cell in view, and `cancelEdit` closes it.
118
+
119
+ ## Attributes
120
+
121
+ - `data-editable` on a cell that can be edited, `data-editing` while its editor is open, `data-checking` while a check runs.
122
+ - The editor is `[data-slot='table-editor']`, with `aria-invalid` and `data-invalid` after a refusal. Its name is "Edit Price" (message `editCell`).
123
+ - The reason of a refusal is `[data-slot='table-edit-error']`, which the editor names with `aria-errormessage`.
124
+
125
+ ## Names
126
+
127
+ - **Options:** `editable`, `onCellEdit` (`@cell-edit`); column keys `editable`, `parse`, `schema`, `numberKeyboard`.
128
+ - **Controller:** `editCell`, `startEdit`, `cancelEdit`.
129
+ - **Slots:** `#editor`, `#edit-{column id}`.
130
+ - **Exports:** `applyEdits`, `cellValue`, `emptyValue`, and the types `CellEdit`, `TableEditDetails`, `TableEditReason`, `StandardSchemaV1`, `EditorSlotProps`.
131
+
132
+ See the [Edit tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=edit).
@@ -0,0 +1,124 @@
1
+ # Cells and slots
2
+
3
+ Put your own content in a header, a cell, a footer or the empty table, and give rows and cells your own attributes.
4
+
5
+ Every cell of the table is a Vue slot. A slot gets the row, the column, the value and its text, and the functions that act on its row. Without a slot, a cell shows the text of its value.
6
+
7
+ ```vue title="slots.vue"
8
+ <script setup lang="ts">
9
+ import { Table, type ColumnDef } from 'ui-sdk-table-vue'
10
+
11
+ type Task = {
12
+ id: string
13
+ title: string
14
+ owner: string
15
+ state: 'todo' | 'doing' | 'done'
16
+ hours: number
17
+ }
18
+
19
+ const tasks: Task[] = [
20
+ { id: 't1', title: 'Write the release notes', owner: 'Ada', state: 'doing', hours: 3 },
21
+ { id: 't2', title: 'Fix the login page', owner: 'Tomas', state: 'done', hours: 5 },
22
+ { id: 't3', title: 'Plan the next sprint', owner: 'Maya', state: 'todo', hours: 2 },
23
+ ]
24
+
25
+ const STATES = { todo: 'To do', doing: 'Doing', done: 'Done' }
26
+
27
+ const columns: ColumnDef<Task>[] = [
28
+ { id: 'title', header: 'Task' },
29
+ { id: 'owner', header: 'Owner' },
30
+ { id: 'state', header: 'State' },
31
+ { id: 'hours', header: 'Hours', format: 'integer', aggregate: 'sum' },
32
+ ]
33
+ </script>
34
+
35
+ <template>
36
+ <Table
37
+ :rows="tasks"
38
+ :columns="columns"
39
+ :cell-attrs="
40
+ (cell) =>
41
+ cell.kind === 'cell' && cell.column.id === 'state' ? { class: 'state' } : undefined
42
+ "
43
+ aria-label="Tasks of the week"
44
+ >
45
+ <!-- A slot for one column wins over the slot for every cell. -->
46
+ <template #col-state="{ row }">
47
+ <mark :data-state="row.state">{{ STATES[row.state] }}</mark>
48
+ </template>
49
+ <template #header-hours="{ label }">{{ label }} (sum below)</template>
50
+ <template #foot-title>All tasks</template>
51
+ <template #empty>No task this week.</template>
52
+ </Table>
53
+ </template>
54
+
55
+ <style scoped>
56
+ mark {
57
+ padding: 2px 8px;
58
+ border-radius: 999px;
59
+ background: #e4e4e7;
60
+ color: #18181b;
61
+ font-size: 13px;
62
+ }
63
+
64
+ mark[data-state='done'] {
65
+ background: #dcfce7;
66
+ color: #14532d;
67
+ }
68
+
69
+ mark[data-state='doing'] {
70
+ background: #e0e7ff;
71
+ color: #1e3a8a;
72
+ }
73
+ </style>
74
+
75
+ <style scoped>
76
+ /* `cellAttrs` gives the cells of the state column a class. The table renders them, so the rule reaches them through :deep(). */
77
+ :deep(.state) {
78
+ text-align: center;
79
+ }
80
+ </style>
81
+ ```
82
+
83
+ The State column shows a badge from its own slot. The Hours header has its own text, and the footer shows the sum under it.
84
+
85
+ ## The slots
86
+
87
+ | Slot | Fills | Gets |
88
+ | --- | --- | --- |
89
+ | `#cell`, `#col-{column id}` | A body cell | `row`, `node`, `column`, `value`, `text`, `format`, `selected`, `expanded`, `expandable`, `level`, `pinned`, `toggleSelected`, `toggleExpanded`, `formula` |
90
+ | `#header`, `#header-{column id}` | A header cell | `column`, `label`, `leaf`, `sort`, `sortIndex`, `toggleSort`, `pin`, `selectColumn`, `formula` |
91
+ | `#foot`, `#foot-{column id}` | A footer cell | `column`, `value`, `text`, `totals`, `aggregate`, `setAggregate` |
92
+ | `#group` | The label cell of a group row | See [Groups and totals](./groups-and-totals.md) |
93
+ | `#group-total`, `#group-total-{column id}` | A cell of a group row under a column | See [Groups and totals](./groups-and-totals.md) |
94
+ | `#detail` | The detail row of a row | `row`, `node`, `toggleExpanded` |
95
+ | `#editor`, `#edit-{column id}` | The editor of a cell | See [Editing](./cell-editing.md) |
96
+ | `#empty` | The body, when no row passes the filters | Nothing |
97
+ | `#loading` | The body, while `loading` is set and the table has no rows | Nothing |
98
+
99
+ A slot for one column wins over the slot for every column: `#col-state` wins over `#cell`.
100
+
101
+ - `text` is the value with the format of the cell, else of its column. Show `text` unless the cell needs more.
102
+ - `row` is your own row object. `node` is the place of the row in the table: its `id`, its `depth` and its `parentId`.
103
+ - A header slot of a sortable column replaces the sort button too. Call `toggleSort(event)` from your own button, and pass the event: the table reads the Shift key from it.
104
+
105
+ ## Attributes of rows and cells
106
+
107
+ `rowAttrs`, `cellAttrs` and `sectionAttrs` give attributes to the elements that the table renders, such as a class or a `data-*` attribute of your own.
108
+
109
+ - `rowAttrs(context)` gets the kind of the row: `header`, `letters`, `row`, `group`, `detail`, `foot` or `empty`, with the row or the group.
110
+ - `cellAttrs(context)` gets the kind of the cell: `header`, `letter`, `cell`, `group`, `group-total`, `detail`, `foot` or `empty`, with the column and the row.
111
+ - `sectionAttrs` is an object with `head`, `body` and `foot`.
112
+
113
+ The table spreads these first and its own attributes after them. A caller cannot replace a part prop (`value`, `index`, `row`, `col`, `colspan`), a role, a `tabindex` or a state attribute of the table (`aria-*` and the `data-*` attributes of the table). Such a name in the answer is left out.
114
+
115
+ The table calls `rowAttrs` when it renders its rows, not for a new selection or a new active cell. Show such state with the attributes of the table, such as `aria-selected`. Pass the same function while its answers stay the same: a new function renders every row again.
116
+
117
+ A scoped style of your component does not reach the elements that the table renders. Use `:deep()`, or a style that is not scoped.
118
+
119
+ ## Names
120
+
121
+ - **Slot props types:** `CellSlotProps`, `HeaderSlotProps`, `FootSlotProps`, `GroupSlotProps`, `GroupTotalSlotProps`, `DetailSlotProps`, `EditorSlotProps`, `RowHeaderSlotProps`, `LetterSlotProps`, `TableSlots`.
122
+ - **Attribute types:** `TableAttrsProps`, `RowAttrsContext`, `CellAttrsContext`, `PartAttrs`.
123
+
124
+ See the [More tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=more).
@@ -0,0 +1,225 @@
1
+ # Columns
2
+
3
+ Say what each column shows, how its value becomes text, and how a person can change its place and width.
4
+
5
+ A column is a plain object of the type `ColumnDef<Row>`. The table reads the list in its order. A person can hide, move, resize and pin columns when the columns allow it, and each of these changes is state with a `v-model`.
6
+
7
+ ```vue title="formats.vue"
8
+ <script setup lang="ts">
9
+ import { Table, type ColumnDef } from 'ui-sdk-table-vue'
10
+
11
+ type Book = {
12
+ id: string
13
+ title: string
14
+ author: { first: string; last: string }
15
+ price: number
16
+ sold: number
17
+ share: number
18
+ published: string
19
+ }
20
+
21
+ const books: Book[] = [
22
+ {
23
+ id: 'b1',
24
+ title: 'The River Road',
25
+ author: { first: 'Ada', last: 'Lindqvist' },
26
+ price: 18.5,
27
+ sold: 12480,
28
+ share: 0.312,
29
+ published: '2024-03-14',
30
+ },
31
+ {
32
+ id: 'b2',
33
+ title: 'Small Hours',
34
+ author: { first: 'Tomas', last: 'Reyes' },
35
+ price: 24,
36
+ sold: 8120,
37
+ share: 0.203,
38
+ published: '2023-09-02',
39
+ },
40
+ {
41
+ id: 'b3',
42
+ title: 'Salt and Iron',
43
+ author: { first: 'Maya', last: 'Okafor' },
44
+ price: 15.75,
45
+ sold: 19400,
46
+ share: 0.485,
47
+ published: '2025-01-20',
48
+ },
49
+ ]
50
+
51
+ const columns: ColumnDef<Book>[] = [
52
+ { id: 'title', header: 'Title', sortable: true },
53
+ // A value that is not one property of the row comes from a function.
54
+ {
55
+ id: 'author',
56
+ header: 'Author',
57
+ sortable: true,
58
+ value: (book) => `${book.author.last}, ${book.author.first}`,
59
+ },
60
+ {
61
+ id: 'published',
62
+ header: 'Published',
63
+ sortable: true,
64
+ format: 'date',
65
+ formatOptions: { dateStyle: 'medium', timeZone: 'UTC' },
66
+ },
67
+ // A header group: one header above the columns that it holds.
68
+ {
69
+ id: 'sales',
70
+ header: 'Sales',
71
+ columns: [
72
+ { id: 'sold', header: 'Copies', sortable: true, format: 'integer' },
73
+ {
74
+ id: 'price',
75
+ header: 'Price',
76
+ sortable: true,
77
+ format: 'currency',
78
+ formatOptions: { currency: 'USD', showUnit: true },
79
+ },
80
+ {
81
+ id: 'share',
82
+ header: 'Share',
83
+ sortable: true,
84
+ format: 'percentage',
85
+ formatOptions: { showUnit: true, maximumFractionDigits: 1 },
86
+ },
87
+ ],
88
+ },
89
+ ]
90
+ </script>
91
+
92
+ <template>
93
+ <Table :rows="books" :columns="columns" locale="en-US" aria-label="Books and their sales" />
94
+ </template>
95
+ ```
96
+
97
+ Press a header to sort by it. Copies, Price and Share sit under one header group, Sales. The dates and the numbers are text of the en-US locale.
98
+
99
+ ## The value of a cell
100
+
101
+ - `id` names the column. Without `key` and `value`, it is also the property of the row that holds the value.
102
+ - `key` names another property of the row.
103
+ - `value(row)` computes the value. It wins over `key`. A sort, a filter, a search and a total read this value.
104
+ - `header` is the text of the header cell. Without it, the header shows the id.
105
+ - `columns` makes the column a header group: one header cell above the columns that it holds. A header group holds no cells. Its id in `columnVisibility` hides all of its columns.
106
+
107
+ ## Formats
108
+
109
+ `format` decides how a value becomes text. Without it, the value is shown as it is. The names are `text`, `integer`, `decimal`, `number`, `currency`, `percentage`, `date`, `time`, `datetime`, `url`, `email`, `boolean`, `truncate`, `relativeTime` and `period`.
110
+
111
+ `formatOptions` fine-tunes the format:
112
+
113
+ - `currency` takes `currency` (an ISO code) and needs `showUnit: true` to show the sign. Without `showUnit`, the number is a plain decimal.
114
+ - `percentage` reads 0.25 as 25 %. `scale: 'percent'` reads 25 as 25 %. It needs `showUnit: true` to show the percent sign.
115
+ - `date` and `datetime` take the options of `Intl.DateTimeFormat`, such as `dateStyle` and `timeZone`.
116
+ - Every format takes `prefix`, `suffix` and `locale`, and the texts for an empty value (`nullValue`, `emptyValue`).
117
+
118
+ The `locale` option of the table is the locale of every format. A cell carries the name of its format as `data-format`, for a style that aligns numbers to the end.
119
+
120
+ ## Width, order and pins
121
+
122
+ ```vue title="layout.vue"
123
+ <script setup lang="ts">
124
+ import { Button } from '@ui-sdk/vue/button'
125
+ import {
126
+ createTableController,
127
+ Table,
128
+ type ColumnDef,
129
+ type ColumnPinning,
130
+ type ColumnVisibility,
131
+ } from 'ui-sdk-table-vue'
132
+ import { shallowRef } from 'vue'
133
+
134
+ type City = { id: string; name: string; country: string; people: number; area: number }
135
+
136
+ const cities: City[] = [
137
+ { id: 'c1', name: 'Lisbon', country: 'Portugal', people: 545000, area: 100 },
138
+ { id: 'c2', name: 'Vienna', country: 'Austria', people: 1982000, area: 415 },
139
+ { id: 'c3', name: 'Oslo', country: 'Norway', people: 709000, area: 454 },
140
+ ]
141
+
142
+ const columns: ColumnDef<City>[] = [
143
+ // A city has no name to hide: the column stays.
144
+ { id: 'name', header: 'City', width: 140, hideable: false },
145
+ { id: 'country', header: 'Country', width: 140 },
146
+ { id: 'people', header: 'People', width: 130, format: 'integer' },
147
+ { id: 'area', header: 'Area, km²', width: 130, format: 'integer' },
148
+ ]
149
+
150
+ const controller = createTableController()
151
+ const visibility = shallowRef<ColumnVisibility>({})
152
+ const pinning = shallowRef<ColumnPinning>({})
153
+ </script>
154
+
155
+ <template>
156
+ <div>
157
+ <Button @click="controller.toggleColumnVisibility('country')">
158
+ {{ visibility.country === false ? 'Show' : 'Hide' }} the country
159
+ </Button>
160
+ <Button @click="controller.pinColumn('name', pinning.start?.includes('name') ? null : 'start')">
161
+ {{ pinning.start?.includes('name') ? 'Free' : 'Pin' }} the city
162
+ </Button>
163
+ <Button @click="controller.resetColumnWidths()">Reset the widths</Button>
164
+ </div>
165
+ <Table
166
+ v-model:column-visibility="visibility"
167
+ v-model:column-pinning="pinning"
168
+ :rows="cities"
169
+ :columns="columns"
170
+ :controller="controller"
171
+ resizable
172
+ reorderable
173
+ aria-label="Cities"
174
+ />
175
+ </template>
176
+ ```
177
+
178
+ Drag the edge of a header to resize a column, or drag a header to move it. Press the buttons to hide the country and to pin the city. The page can scroll the table sideways, and a pinned city stays.
179
+
180
+ - `resizable` and `reorderable` on the table let a person resize and move every column. The same keys on a column say otherwise for that column.
181
+ - `width`, `minWidth` and `maxWidth` are pixels. A resize by a person wins over `width`. `columnMinWidth` is the smallest width of a column without `minWidth`, 48 by default.
182
+ - `hideable: false` keeps a column in view.
183
+ - `lead: true` puts a column before every other column, whatever the order says. It sticks to the start with the first pinned column. Use it for the checkbox of a row.
184
+ - A table whose columns can be resized is as wide as its columns (`inline-size: var(--table-width)`). Do not stretch it to its frame: a drag starts from the width that the column has on the screen.
185
+
186
+ The state of the columns:
187
+
188
+ | State | Value | Change |
189
+ | --- | --- | --- |
190
+ | `columnVisibility` | `{ [columnId]: false }` hides a column | `setColumnVisibility`, `toggleColumnVisibility`, `showAllColumns`, `hideAllColumns` |
191
+ | `columnOrder` | Column ids in display order. Columns that are not listed come after them, in definition order | `moveColumn`, `setColumnOrder`, a drag |
192
+ | `columnWidths` | `{ [columnId]: pixels }` | `setColumnWidth`, a drag. `columnWidthsCommit` runs once when a drag ends |
193
+ | `columnPinning` | `{ start?: ids, end?: ids }` | `pinColumn(id, 'start' \| 'end' \| null)` |
194
+
195
+ ## Back to the start
196
+
197
+ `controller.hideAllColumns()` hides every column that can be hidden, in one change. A column with `hideable: false` and a `lead` column stay. The first column in view stays when no other would.
198
+
199
+ `resetColumnVisibility()`, `resetColumnOrder()` and `resetColumnPinning()` bring a state back to what the table started with: its `default…` prop, else the empty state. They report the reason `reset`. `resetColumnWidths()` takes every width away.
200
+
201
+ A `v-model:column-visibility` that hides every column gives a table without columns. The table does not correct the state of its owner.
202
+
203
+ ## Keys
204
+
205
+ | Key | On a header cell |
206
+ | --- | --- |
207
+ | Space | Picks a column up, with `reorderable`. The arrows move it, Space drops it, and Escape puts it back |
208
+ | Alt with Left or Right | Makes the column narrower or wider by 10 pixels, with Shift by 50 |
209
+ | Enter | Sorts a column that is `sortable` |
210
+
211
+ ## Attributes and CSS variables
212
+
213
+ - `data-column` on every cell, with the column id. `data-format` on every cell of a column with a format.
214
+ - `data-pinned` (`start` or `end`) on a pinned cell, and `data-pinned-edge` on the last pinned cell before the free ones. `--table-pin-offset` is how far the cell sticks from its edge.
215
+ - `data-lead` on the cells of a lead column.
216
+ - `data-moving` on a header that is picked up, and `data-grabbed` while a pointer drags it.
217
+ - `--table-width` on the table and `--table-column-width` on a cell, for a table with widths.
218
+ - The handle of a resize is the part `[data-slot='table-resizer']`, with `data-dragging` during a drag. It needs `position: absolute` in a cell with `position: relative`, and `touch-action: none`.
219
+
220
+ See the [Columns tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=columns).
221
+
222
+ ## Keep going
223
+
224
+ - [Cells and slots](./cells-and-slots.md) puts your own content in a cell.
225
+ - [Styling](./styling.md) lists every attribute that a style reads.
@@ -0,0 +1,97 @@
1
+ # Controller and view
2
+
3
+ Change the table from a control beside it, and read what it shows now.
4
+
5
+ A toolbar, a search field, a filter control and the pages of a table live outside the table. They act through a controller and read a view. The same controller is what an agent calls.
6
+
7
+ ```vue title="outside.vue"
8
+ <script setup lang="ts">
9
+ import { Button } from '@ui-sdk/vue/button'
10
+ import { createTableController, Table, useTableView, type ColumnDef } from 'ui-sdk-table-vue'
11
+
12
+ type Flight = { id: string; flight: string; to: string; gate: string; delay: number }
13
+
14
+ const flights: Flight[] = [
15
+ { id: 'f1', flight: 'SK 411', to: 'Oslo', gate: 'A4', delay: 0 },
16
+ { id: 'f2', flight: 'LH 870', to: 'Frankfurt', gate: 'B12', delay: 25 },
17
+ { id: 'f3', flight: 'AY 132', to: 'Helsinki', gate: 'A9', delay: 5 },
18
+ { id: 'f4', flight: 'BA 795', to: 'London', gate: 'C2', delay: 40 },
19
+ { id: 'f5', flight: 'KL 1170', to: 'Amsterdam', gate: 'B3', delay: 0 },
20
+ ]
21
+
22
+ const columns: ColumnDef<Flight>[] = [
23
+ { id: 'flight', header: 'Flight', sortable: true },
24
+ { id: 'to', header: 'To', sortable: true },
25
+ { id: 'gate', header: 'Gate' },
26
+ { id: 'delay', header: 'Delay, min', sortable: true, format: 'integer' },
27
+ ]
28
+
29
+ // The controller is the handle to the table, the view is what the table shows now.
30
+ const controller = createTableController()
31
+ const view = useTableView(controller)
32
+ </script>
33
+
34
+ <template>
35
+ <div>
36
+ <Button @click="controller.sortBy('delay', 'desc')">Most delayed first</Button>
37
+ <Button @click="controller.setColumnFilter('delay', { min: 1 })">Only delayed</Button>
38
+ <Button @click="controller.clearFilters()">Every flight</Button>
39
+ </div>
40
+ <p role="status">
41
+ {{ view?.dataRowCount ?? 0 }} of {{ flights.length }} flights<template v-if="view?.sort[0]"
42
+ >, sorted by {{ view.sort[0].id }}</template
43
+ >
44
+ </p>
45
+ <Table :rows="flights" :columns="columns" :controller="controller" aria-label="Departures" />
46
+ </template>
47
+ ```
48
+
49
+ Press Most delayed first, then Only delayed. The line above the table reads the view: how many flights pass and the sort. Every flight brings the rows back.
50
+
51
+ ## The controller
52
+
53
+ ```ts
54
+ import { createTableController } from 'ui-sdk-table-vue'
55
+
56
+ const controller = createTableController()
57
+ ```
58
+
59
+ Pass it as the `controller` prop. Then call its methods from anywhere:
60
+
61
+ - **Sort and filter:** `sortBy`, `toggleSort`, `setSearch`, `inputSearch`, `flushSearch`, `setColumnFilter`, `clearFilters`, `clearColumnFilters`.
62
+ - **Groups and pages:** `setGroupBy`, `setPage`, `setPageSize`, `nextPage`, `previousPage`, `firstPage`, `lastPage`.
63
+ - **Rows:** `expand`, `collapse`, `toggleExpanded`, `expandAll`, `collapseAll`, `select`, `toggleSelected`, `selectAll`, `selectRows`, `deselectRows`, `clearSelection`, `pinRow`, `scrollToRow`.
64
+ - **Columns:** `setColumnVisibility`, `toggleColumnVisibility`, `showAllColumns`, `hideAllColumns`, `moveColumn`, `setColumnOrder`, `setColumnWidth`, `pinColumn`, the `reset…` methods, `setColumnAggregate`.
65
+ - **Cells:** `editCell`, `startEdit`, `cancelEdit`, `selectCells`, `copyCells`, `pasteCells` and the methods of the data sheet.
66
+ - **Reads:** `getView`, `getFacets`, `getTotals`, `getSelectionSummary`, `exportData`, `subscribe`.
67
+
68
+ A method that gets a wrong argument throws a message that lists the valid values, such as `No column "age" to sort by. Columns: name, score.`
69
+
70
+ A controller can be made before the table mounts. Before the table exists, a call does nothing and answers `undefined`. `subscribe` is safe to call early: its listener waits for the table, runs once when the table is there, and then after each change. A table that comes in place of another (a new `key`) takes over every listener.
71
+
72
+ ## The view
73
+
74
+ `useTableView(controller)` is a ref of `getView()` that follows the table. It holds `undefined` until the table is there.
75
+
76
+ | Field | What it holds |
77
+ | --- | --- |
78
+ | `sort`, `filter`, `groupBy`, `expanded`, `selected` | The state |
79
+ | `search`, `searchPending` | The text of a search field, and whether it waits for a pause |
80
+ | `page`, `pageSize`, `pageCount`, `rowCount`, `pageUnit`, `lastPageKnown` | The pages |
81
+ | `dataRowCount` | How many data rows pass the filters, child rows too |
82
+ | `columns`, `visibleColumns` | Every column that holds cells, and the columns in view in their order |
83
+ | `selectable` | The ids of the rows that `selectAll` selects |
84
+ | `hasExpandable`, `hasExpanded` | Whether something can open, and whether something is open |
85
+ | `loading` | The `loading` prop |
86
+ | `activeCell`, `cellSelection`, `canUndo`, `canRedo` | For a sheet |
87
+
88
+ A read that depends on the table, such as `controller.getFacets(id)`, goes in a `computed` that reads the view first. It is then asked again after each change.
89
+
90
+ Without Vue, `controller.subscribe(listener)` runs the listener after each change of the state, the rows or the columns, with the keys that changed. It returns the function that stops it.
91
+
92
+ ## Names
93
+
94
+ - **Vue:** `createTableController`, `useTableView`, `useTableSearch`, `useSelectionSummary`.
95
+ - **Types:** `TableController`, `TableView`, `CellSelectionView`, `PageUnit`.
96
+
97
+ See the [More tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=more).