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.
package/docs/rows.md ADDED
@@ -0,0 +1,277 @@
1
+ # Rows
2
+
3
+ Show rows with child rows, a detail row under a row, rows pinned to an edge, and many thousand rows in a window.
4
+
5
+ Each row needs a stable id: its `id` property, or what `getRowId(row, index, parent)` returns. The table never copies or changes a row object.
6
+
7
+ ## Tree rows
8
+
9
+ `getChildren(row)` gives the child rows of a row. With it, the table is a tree. The root then has the role `treegrid`, and each row has `aria-level`, `aria-posinset` and `aria-setsize`.
10
+
11
+ ```vue title="tree.vue"
12
+ <script setup lang="ts">
13
+ import { Table, type ColumnDef } from 'ui-sdk-table-vue'
14
+
15
+ type Entry = { id: string; name: string; size?: number; children?: Entry[] }
16
+
17
+ const files: Entry[] = [
18
+ {
19
+ id: 'src',
20
+ name: 'src',
21
+ children: [
22
+ { id: 'src/main.ts', name: 'main.ts', size: 1.2 },
23
+ { id: 'src/app.vue', name: 'app.vue', size: 4.8 },
24
+ ],
25
+ },
26
+ {
27
+ id: 'docs',
28
+ name: 'docs',
29
+ children: [{ id: 'docs/guide.md', name: 'guide.md', size: 9.5 }],
30
+ },
31
+ { id: 'package.json', name: 'package.json', size: 0.9 },
32
+ ]
33
+
34
+ const columns: ColumnDef<Entry>[] = [
35
+ { id: 'name', header: 'Name', sortable: true },
36
+ {
37
+ id: 'size',
38
+ header: 'Size',
39
+ sortable: true,
40
+ format: 'decimal',
41
+ formatOptions: { suffix: ' kB' },
42
+ },
43
+ ]
44
+ </script>
45
+
46
+ <template>
47
+ <Table
48
+ :rows="files"
49
+ :columns="columns"
50
+ :get-children="(entry: Entry) => entry.children"
51
+ :default-expanded="['src']"
52
+ aria-label="Files of a project"
53
+ >
54
+ <template #col-name="{ text, expandable, expanded, toggleExpanded }">
55
+ <button
56
+ v-if="expandable"
57
+ type="button"
58
+ :aria-expanded="expanded"
59
+ :aria-label="`Folder ${text}`"
60
+ @click="toggleExpanded"
61
+ >
62
+ {{ expanded ? '▾' : '▸' }}
63
+ </button>
64
+ {{ text }}
65
+ </template>
66
+ </Table>
67
+ </template>
68
+ ```
69
+
70
+ Press the arrow before docs to open the folder. Sort by Size: the child rows sort inside their folder.
71
+
72
+ - `expanded` holds the ids of the open rows. `expand`, `collapse`, `toggleExpanded`, `expandAll` and `collapseAll` change it.
73
+ - The `#cell` slot gets `expandable`, `expanded`, `level` and `toggleExpanded`. Put the button that opens a row in a slot of your own.
74
+ - A row of a tree has `aria-level`, `aria-posinset` and `aria-setsize`, and `aria-expanded` when it has child rows.
75
+ - `sortChildren: false` keeps the child rows in their order.
76
+
77
+ ## Detail rows
78
+
79
+ `hasDetail(row)` names the rows that have a detail row: one wide row under the row, which opens and closes as a tree row does.
80
+
81
+ ```vue title="detail.vue"
82
+ <script setup lang="ts">
83
+ import { Table, type ColumnDef } from 'ui-sdk-table-vue'
84
+ import { shallowRef } from 'vue'
85
+
86
+ type Order = { id: string; customer: string; state: string; note: string }
87
+
88
+ const orders: Order[] = [
89
+ { id: 'o1', customer: 'Northway', state: 'Paid', note: '' },
90
+ { id: 'o2', customer: 'Sola', state: 'Late', note: 'Ten days late. Send a reminder today.' },
91
+ { id: 'o3', customer: 'Arc', state: 'Open', note: 'Waits for the signed contract.' },
92
+ ]
93
+
94
+ const columns: ColumnDef<Order>[] = [
95
+ { id: 'customer', header: 'Customer' },
96
+ { id: 'state', header: 'State' },
97
+ ]
98
+
99
+ // A paid order has nothing more to say. Pass the same function at each render.
100
+ const hasDetail = (order: Order) => order.state !== 'Paid'
101
+ const open = shallowRef<readonly string[]>([])
102
+ </script>
103
+
104
+ <template>
105
+ <Table
106
+ v-model:expanded="open"
107
+ :rows="orders"
108
+ :columns="columns"
109
+ :has-detail="hasDetail"
110
+ aria-label="Orders with notes"
111
+ >
112
+ <template #col-customer="{ text, expandable, expanded, toggleExpanded }">
113
+ <button
114
+ v-if="expandable"
115
+ type="button"
116
+ :aria-expanded="expanded"
117
+ :aria-label="`Note of ${text}`"
118
+ @click="toggleExpanded"
119
+ >
120
+ {{ expanded ? '▾' : '▸' }}
121
+ </button>
122
+ {{ text }}
123
+ </template>
124
+ <template #detail="{ row }">{{ row.note }}</template>
125
+ </Table>
126
+ </template>
127
+ ```
128
+
129
+ Press the arrow before Sola to open its note. Northway is paid and has no note, so it has no arrow.
130
+
131
+ - The `#detail` slot fills the detail row. It gets `row`, `node` and `toggleExpanded`.
132
+ - The detail row has `data-kind="detail"`.
133
+ - Pass the same function while its answers are the same: a new function makes the table list its rows again.
134
+
135
+ ## Pinned rows
136
+
137
+ `rowPinning` holds the ids of the rows that stay at the top or the bottom edge: `{ top?: ids, bottom?: ids }`.
138
+
139
+ ```vue title="pinned.vue"
140
+ <script setup lang="ts">
141
+ import { createTableController, Table, type ColumnDef, type RowPinning } from 'ui-sdk-table-vue'
142
+ import { shallowRef } from 'vue'
143
+
144
+ type Product = { id: string; name: string; stock: number }
145
+
146
+ const products: Product[] = [
147
+ { id: 'p1', name: 'Oat milk', stock: 42 },
148
+ { id: 'p2', name: 'Rye bread', stock: 8 },
149
+ { id: 'p3', name: 'Green tea', stock: 120 },
150
+ { id: 'p4', name: 'Dark coffee', stock: 3 },
151
+ { id: 'p5', name: 'Honey', stock: 27 },
152
+ ]
153
+
154
+ const columns: ColumnDef<Product>[] = [
155
+ { id: 'name', header: 'Product', sortable: true },
156
+ { id: 'stock', header: 'In stock', sortable: true, format: 'integer' },
157
+ ]
158
+
159
+ const controller = createTableController()
160
+ const pinning = shallowRef<RowPinning>({ top: ['p4'] })
161
+ </script>
162
+
163
+ <template>
164
+ <Table
165
+ v-model:row-pinning="pinning"
166
+ :rows="products"
167
+ :columns="columns"
168
+ :controller="controller"
169
+ aria-label="Products, the pinned ones on top"
170
+ >
171
+ <template #col-name="{ row, text, pinned }">
172
+ <button
173
+ type="button"
174
+ :aria-pressed="!!pinned"
175
+ :aria-label="`Pin ${text} to the top`"
176
+ @click="controller.pinRow(row.id, pinned ? null : 'top')"
177
+ >
178
+ {{ pinned ? '★' : '☆' }}
179
+ </button>
180
+ {{ text }}
181
+ </template>
182
+ </Table>
183
+ </template>
184
+ ```
185
+
186
+ Press the star before Honey to pin it. It moves to the top with Dark coffee, and a sort leaves both there.
187
+
188
+ - A filter or a page does not hide a pinned row. The totals are of the rows that pass the filter, so a pinned row that the filter refuses is in view and not in a total.
189
+ - A row with child rows cannot be pinned.
190
+ - `controller.pinRow(rowId, 'top' | 'bottom' | null)` pins and frees a row. The `#cell` slot gets `pinned`.
191
+ - A pinned row has `data-pinned` and `data-sticky` with its edge. Style it as a sticky row: see [Styling](./styling.md).
192
+
193
+ ## The row window
194
+
195
+ `rowWindow` renders only the rows near the scroll frame, with a spacer row for the rest.
196
+
197
+ ```vue title="window.vue"
198
+ <script setup lang="ts">
199
+ import { Button } from '@ui-sdk/vue/button'
200
+ import { createTableController, Table, type ColumnDef } from 'ui-sdk-table-vue'
201
+
202
+ type Reading = { id: string; number: number; sensor: string; value: number }
203
+
204
+ const SENSORS = ['North', 'East', 'South', 'West']
205
+ const readings: Reading[] = Array.from({ length: 10_000 }, (_, index) => ({
206
+ id: `r${index + 1}`,
207
+ number: index + 1,
208
+ sensor: SENSORS[index % SENSORS.length] ?? '',
209
+ value: (index * 7919) % 1000,
210
+ }))
211
+
212
+ const columns: ColumnDef<Reading>[] = [
213
+ { id: 'number', header: 'Row', format: 'integer' },
214
+ { id: 'sensor', header: 'Sensor' },
215
+ { id: 'value', header: 'Value', format: 'integer' },
216
+ ]
217
+
218
+ const controller = createTableController()
219
+ </script>
220
+
221
+ <template>
222
+ <div>
223
+ <Button @click="controller.scrollToRow('r5000', 'center')">Row 5,000</Button>
224
+ <Button @click="controller.scrollToRow('r1', 'start')">First row</Button>
225
+ </div>
226
+ <!-- The frame scrolls. The table renders the rows near it, and a spacer for the rest. -->
227
+ <div class="frame">
228
+ <Table
229
+ :rows="readings"
230
+ :columns="columns"
231
+ :controller="controller"
232
+ :row-height="35"
233
+ row-window
234
+ sticky-header
235
+ aria-label="Ten thousand readings"
236
+ />
237
+ </div>
238
+ </template>
239
+
240
+ <style scoped>
241
+ .frame {
242
+ block-size: 280px;
243
+ overflow: auto;
244
+ }
245
+
246
+ .frame :deep(tr[data-sticky] > *) {
247
+ background: #fff;
248
+ }
249
+
250
+ .frame :deep([data-slot='table-row']) {
251
+ block-size: var(--table-row-height);
252
+ }
253
+ </style>
254
+ ```
255
+
256
+ Scroll the frame, or press Row 5,000. The table renders a few dozen rows at a time, and a jump takes one step.
257
+
258
+ - The frame is the nearest parent whose content is higher than itself, or the page.
259
+ - `rowHeight` gives every row one height in pixels. Without it, the window measures each row, and `estimatedRowHeight` (36 by default) is the height of a row that it did not measure yet. With `hasDetail` it measures too.
260
+ - `overscan` is how many rows more than the frame shows it renders on each side, 8 by default.
261
+ - `controller.scrollToRow(rowId, align)` scrolls a row into view in one step, also when the row is not rendered yet. `align` is `start`, `center`, `end` or `nearest` (the default).
262
+ - The table has `data-row-window` and the CSS variable `--table-row-height`. A spacer row is `[data-slot='table-spacer']` and needs `block-size: var(--table-spacer-size)`.
263
+ - `aria-rowcount` and `aria-rowindex` count every row, so a screen reader says the place of a row among all of them.
264
+
265
+ ## Sticky header and footer
266
+
267
+ `stickyHeader` and `stickyFooter` keep the header rows and the footer row in view while the rows scroll. The rows get `data-sticky`; the style makes them stick.
268
+
269
+ ## Names
270
+
271
+ - **Options:** `getRowId`, `getChildren`, `sortChildren`, `hasDetail`, `expanded`, `defaultExpanded`, `rowPinning`, `defaultRowPinning`, `rowWindow`, `rowHeight`, `estimatedRowHeight`, `overscan`, `stickyHeader`, `stickyFooter`.
272
+ - **Events:** `expanded-change`, `row-pinning-change`.
273
+ - **Controller:** `expand`, `collapse`, `toggleExpanded`, `expandAll`, `collapseAll`, `pinRow`, `scrollToRow`.
274
+ - **Slots:** `#detail`.
275
+ - **Types:** `DataRow`, `TableRow`, `RowPin`, `RowPinning`, `DetailSlotProps`.
276
+
277
+ See the [Rows tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=rows).
@@ -0,0 +1,118 @@
1
+ # Selection and keyboard
2
+
3
+ Let a person select rows, and move through the table with the keys of a grid.
4
+
5
+ The table is a grid: one cell holds the tab stop, and the arrow keys move between the cells. Tab goes into the table and out of it again, as one stop of the page.
6
+
7
+ ## Select rows
8
+
9
+ ```vue title="select.vue"
10
+ <script setup lang="ts">
11
+ import { Checkbox, CheckboxIndicator } from '@ui-sdk/vue/checkbox'
12
+ import { createTableController, Table, useTableView, type ColumnDef } from 'ui-sdk-table-vue'
13
+ import { computed, shallowRef } from 'vue'
14
+
15
+ type Mail = { id: string; from: string; subject: string; locked: boolean }
16
+
17
+ const mails: Mail[] = [
18
+ { id: 'm1', from: 'Ada', subject: 'The plan for May', locked: false },
19
+ { id: 'm2', from: 'Tomas', subject: 'Invoice 1042', locked: true },
20
+ { id: 'm3', from: 'Maya', subject: 'Photos of the trip', locked: false },
21
+ { id: 'm4', from: 'Leo', subject: 'Lunch on Friday?', locked: false },
22
+ ]
23
+
24
+ const columns: ColumnDef<Mail>[] = [
25
+ // A lead column stays first, and holds the checkbox of its row.
26
+ { id: 'pick', header: 'Pick', lead: true, hideable: false, searchable: false },
27
+ { id: 'from', header: 'From' },
28
+ { id: 'subject', header: 'Subject' },
29
+ ]
30
+
31
+ // A locked mail cannot be picked.
32
+ const canSelect = (mail: Mail) => !mail.locked
33
+ const controller = createTableController()
34
+ const view = useTableView(controller)
35
+ const selected = shallowRef<string[]>([])
36
+
37
+ const all = computed(() => {
38
+ const open = view.value?.selectable.length ?? 0
39
+ if (selected.value.length === 0) return false
40
+ return selected.value.length === open ? true : 'indeterminate'
41
+ })
42
+ </script>
43
+
44
+ <template>
45
+ <p role="status">{{ selected.length }} picked</p>
46
+ <Table
47
+ v-model:selected="selected"
48
+ :rows="mails"
49
+ :columns="columns"
50
+ :controller="controller"
51
+ :can-select="canSelect"
52
+ selection="multiple"
53
+ aria-label="Inbox"
54
+ >
55
+ <template #header-pick>
56
+ <Checkbox
57
+ :checked="all"
58
+ aria-label="Pick every mail"
59
+ @checked-change="
60
+ (on) => (on === true ? controller.selectAll() : controller.clearSelection())
61
+ "
62
+ >
63
+ <CheckboxIndicator>✓</CheckboxIndicator>
64
+ </Checkbox>
65
+ </template>
66
+ <template #col-pick="{ row, selected: on, toggleSelected }">
67
+ <Checkbox
68
+ v-if="canSelect(row)"
69
+ :checked="on"
70
+ :aria-label="`Pick the mail from ${row.from}`"
71
+ @checked-change="toggleSelected()"
72
+ >
73
+ <CheckboxIndicator>✓</CheckboxIndicator>
74
+ </Checkbox>
75
+ </template>
76
+ </Table>
77
+ </template>
78
+ ```
79
+
80
+ Check Ada and Maya. The box in the header shows that some mails are picked; press it to pick every mail that is not locked. The mail from Tomas is locked.
81
+
82
+ - `selection` is `'single'` or `'multiple'`. Without it, rows cannot be selected.
83
+ - `selected` holds the ids of the selected rows. `canSelect(row)` keeps a row out.
84
+ - `select`, `toggleSelected`, `selectRows`, `deselectRows`, `selectAll` and `clearSelection` change it. `selectAll` selects the rows that pass the filters and can be selected: `selectable` of the view.
85
+ - The `#cell` slot gets `selected` and `toggleSelected(event?)`. Put a checkbox in a column with `lead: true`, so it stays first.
86
+ - A selected row has `aria-selected="true"` and `data-selected`.
87
+
88
+ ## Keys
89
+
90
+ | Key | What it does |
91
+ | --- | --- |
92
+ | Tab | Goes into the table, to the cell that holds the tab stop, and out again |
93
+ | The arrows | Move one cell. In right-to-left text, Left and Right follow the reading direction |
94
+ | Home, End | The first and the last cell of the row |
95
+ | Control or Command with Home, End | The first and the last cell of the table |
96
+ | Page Up, Page Down | The rows of one page up or down: `pageSize` of the `page` state, else ten |
97
+ | Enter on a header | Sorts a sortable column |
98
+ | Enter on a row | Opens or closes a row with child rows, a detail row or a group |
99
+ | Space on a row | Selects the row, with `selection`. With Shift, the rows from the last one |
100
+ | Space on a group row | Selects the rows of the group, with `selection="multiple"` |
101
+
102
+ A key from a control inside a cell, such as a button or a field, belongs to that control.
103
+
104
+ The grid gives focus back to a cell only when a change of the table took it away, such as a sort that moved the row. A press elsewhere or a Tab key in between leaves focus where the person put it.
105
+
106
+ ## Ranges of cells
107
+
108
+ With `cellSelection`, a person selects a range of cells: Shift with an arrow, or a drag. Control or Command with C copies the range as text, with tabs between cells and line breaks between rows. With `editable` too, Control or Command with V pastes into it. See [Editing](./cell-editing.md).
109
+
110
+ The cells of a range have `data-selected` and `data-range-edge`. The state is `cellRange`. [Range, copy and paste](./range-copy-and-paste.md) covers the rest.
111
+
112
+ ## Names
113
+
114
+ - **Options:** `selection`, `canSelect`, `selected`, `defaultSelected`, `cellSelection`.
115
+ - **Events:** `selected-change`.
116
+ - **Controller:** `select`, `toggleSelected`, `selectRows`, `deselectRows`, `selectAll`, `clearSelection`, `selectCells`, `clearCellSelection`, `copyCells`.
117
+
118
+ See the [Rows tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=rows).