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/README.md +3 -423
- package/docs/README.md +27 -0
- package/docs/agents.md +71 -0
- package/docs/cell-editing.md +132 -0
- package/docs/cells-and-slots.md +124 -0
- package/docs/column-definitions.md +225 -0
- package/docs/controller-and-view.md +97 -0
- package/docs/excel-formulas.md +112 -0
- package/docs/export.md +92 -0
- package/docs/fill.md +110 -0
- package/docs/formats.md +145 -0
- package/docs/groups-and-totals.md +104 -0
- package/docs/history.md +121 -0
- package/docs/llms.txt +27 -0
- package/docs/pages-and-server-mode.md +203 -0
- package/docs/range-copy-and-paste.md +101 -0
- package/docs/row-numbers-and-letters.md +110 -0
- package/docs/rows.md +277 -0
- package/docs/selection-and-keyboard.md +118 -0
- package/docs/sheet-formulas.md +291 -0
- package/docs/sheet-options.md +182 -0
- package/docs/sort-filter-and-search.md +240 -0
- package/docs/state-and-events.md +85 -0
- package/docs/styling.md +177 -0
- package/package.json +2 -2
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
# Sort, filter and search
|
|
2
|
+
|
|
3
|
+
Sort by one or more columns, filter each column, and search every column with a pause in the typing.
|
|
4
|
+
|
|
5
|
+
The rows pass a sort, then the filters. Sort is first on purpose: a filter keeps the order of its input, so a key in the search field never sorts. The `sort` and `filter` states hold what a person chose.
|
|
6
|
+
|
|
7
|
+
## Sort
|
|
8
|
+
|
|
9
|
+
A column with `sortable: true` gets a button in its header. A press sorts up, the next press down, and the third press takes the sort away.
|
|
10
|
+
|
|
11
|
+
```vue title="sort.vue"
|
|
12
|
+
<script setup lang="ts">
|
|
13
|
+
import { Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
14
|
+
|
|
15
|
+
type Runner = { id: string; name: string; club: string; time: number }
|
|
16
|
+
|
|
17
|
+
const runners: Runner[] = [
|
|
18
|
+
{ id: 'r1', name: 'Jack Ellis', club: 'Harriers', time: 34.12 },
|
|
19
|
+
{ id: 'r2', name: 'Ivy Adams', club: 'Striders', time: 33.48 },
|
|
20
|
+
{ id: 'r3', name: 'Cleo Vance', club: 'Harriers', time: 35.02 },
|
|
21
|
+
{ id: 'r4', name: 'Ben Nolan', club: 'Striders', time: 32.57 },
|
|
22
|
+
{ id: 'r5', name: 'Rosa Diaz', club: 'Pacers', time: 33.9 },
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
const columns: ColumnDef<Runner>[] = [
|
|
26
|
+
{ id: 'name', header: 'Runner', sortable: true },
|
|
27
|
+
{ id: 'club', header: 'Club', sortable: true },
|
|
28
|
+
{
|
|
29
|
+
id: 'time',
|
|
30
|
+
header: '10 km',
|
|
31
|
+
sortable: true,
|
|
32
|
+
format: 'decimal',
|
|
33
|
+
formatOptions: { suffix: ' min' },
|
|
34
|
+
},
|
|
35
|
+
]
|
|
36
|
+
</script>
|
|
37
|
+
|
|
38
|
+
<template>
|
|
39
|
+
<Table :rows="runners" :columns="columns" aria-label="Results of the 10 km run" />
|
|
40
|
+
</template>
|
|
41
|
+
|
|
42
|
+
<style scoped>
|
|
43
|
+
/* `data-sort-index` holds the place of a column in the sort, from 1. */
|
|
44
|
+
:deep(th[data-sort-index] button)::before {
|
|
45
|
+
content: attr(data-sort-index) ' ';
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
:deep(th[data-sort-index]) {
|
|
49
|
+
color: #1e3a8a;
|
|
50
|
+
}
|
|
51
|
+
</style>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Press Club, then hold Shift and press 10 km. The clubs stay together, and inside each club the fastest runner comes first. The number before each header is its place in the sort.
|
|
55
|
+
|
|
56
|
+
- `sort` is a list of `{ id, desc? }`. The first rule sorts first.
|
|
57
|
+
- `multiSort` decides how a press adds a column. `'modifier'` (the default): a press replaces the sort, and a press with Shift, Control or Command adds the column. `'none'`: one column at a time, whatever key is held. `'always'`: each press adds the column. Enter on a header follows the same rule.
|
|
58
|
+
- `alwaysSorted`: a press on the only column of the sort turns the order and never clears it. It does not sort a table that starts without a sort; give `defaultSort` for that.
|
|
59
|
+
- `compare(a, b, rowA, rowB)` on a column gives it its own order, such as Urgent before Low.
|
|
60
|
+
- `sortChildren: false` keeps the child rows of a tree in their order.
|
|
61
|
+
- `toggleSort(event)` of the `#header` slot passes the event, and the table reads the keys. `controller.toggleSort(id, { append: true })` and `sortBy(id, direction, { append: true })` throw in the mode `none`.
|
|
62
|
+
- A `sort` of the owner with more columns than the mode allows is left as it is.
|
|
63
|
+
|
|
64
|
+
## Search with a pause
|
|
65
|
+
|
|
66
|
+
```vue title="search.vue"
|
|
67
|
+
<script setup lang="ts">
|
|
68
|
+
import { Input } from '@ui-sdk/vue/input'
|
|
69
|
+
import {
|
|
70
|
+
createTableController,
|
|
71
|
+
Table,
|
|
72
|
+
useTableSearch,
|
|
73
|
+
useTableView,
|
|
74
|
+
type ColumnDef,
|
|
75
|
+
} from 'ui-sdk-table-vue'
|
|
76
|
+
|
|
77
|
+
type Member = { id: string; name: string; team: string; city: string }
|
|
78
|
+
|
|
79
|
+
const members: Member[] = [
|
|
80
|
+
{ id: 'm1', name: 'Ada Lindqvist', team: 'Design', city: 'Stockholm' },
|
|
81
|
+
{ id: 'm2', name: 'Tomas Reyes', team: 'Platform', city: 'Madrid' },
|
|
82
|
+
{ id: 'm3', name: 'Maya Okafor', team: 'Design', city: 'Lagos' },
|
|
83
|
+
{ id: 'm4', name: 'Leo Brandt', team: 'Support', city: 'Hamburg' },
|
|
84
|
+
{ id: 'm5', name: 'Nina Sato', team: 'Platform', city: 'Osaka' },
|
|
85
|
+
{ id: 'm6', name: 'Omar Haddad', team: 'Support', city: 'Amman' },
|
|
86
|
+
]
|
|
87
|
+
|
|
88
|
+
const columns: ColumnDef<Member>[] = [
|
|
89
|
+
{ id: 'name', header: 'Name' },
|
|
90
|
+
{ id: 'team', header: 'Team' },
|
|
91
|
+
{ id: 'city', header: 'City' },
|
|
92
|
+
]
|
|
93
|
+
|
|
94
|
+
const controller = createTableController()
|
|
95
|
+
const search = useTableSearch(controller)
|
|
96
|
+
const view = useTableView(controller)
|
|
97
|
+
</script>
|
|
98
|
+
|
|
99
|
+
<template>
|
|
100
|
+
<Input
|
|
101
|
+
type="search"
|
|
102
|
+
aria-label="Search the members"
|
|
103
|
+
placeholder="Name, team or city"
|
|
104
|
+
:value="search.text.value"
|
|
105
|
+
@value-change="(text) => (search.text.value = text)"
|
|
106
|
+
@keydown.escape="search.clear()"
|
|
107
|
+
@keydown.enter="search.flush()"
|
|
108
|
+
/>
|
|
109
|
+
<p role="status">
|
|
110
|
+
{{ search.pending.value ? 'Waiting for a pause' : `${view?.dataRowCount ?? 0} members found` }}
|
|
111
|
+
</p>
|
|
112
|
+
<Table
|
|
113
|
+
:rows="members"
|
|
114
|
+
:columns="columns"
|
|
115
|
+
:controller="controller"
|
|
116
|
+
:search-debounce="300"
|
|
117
|
+
aria-label="Members of the team"
|
|
118
|
+
>
|
|
119
|
+
<template #empty>No member matches the search.</template>
|
|
120
|
+
</Table>
|
|
121
|
+
</template>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Type desi. The field shows each letter at once, and the table filters when the typing pauses. Escape clears the field, and Enter filters without the wait.
|
|
125
|
+
|
|
126
|
+
`useTableSearch(controller)` gives a search field what it needs:
|
|
127
|
+
|
|
128
|
+
- `text`: the text of the field. A new text shows at once. The table filters when the typing pauses for `searchDebounce` milliseconds, 200 without the prop. With 0, each letter filters.
|
|
129
|
+
- `pending`: whether a text waits for its pause.
|
|
130
|
+
- `clear()`: empties the search at once, for a clear button and for Escape.
|
|
131
|
+
- `flush()`: filters now, for Enter.
|
|
132
|
+
|
|
133
|
+
The filter changes once, after the pause, with the reason `input-change`. `clear`, `setSearch`, `clearFilters` and a new search text from the owner of `v-model:filter` act at once and drop a text that waits.
|
|
134
|
+
|
|
135
|
+
- The search reads the text of each cell, as the screen shows it. `searchable: false` leaves a column out.
|
|
136
|
+
- `searchMode: 'fuzzy'` also finds near matches, with letters in order but apart. `fuzzyThreshold` (0 to 1) is the score that a match needs.
|
|
137
|
+
- The table says nothing to a screen reader about a search. Announce the rows found when `filter` changes, which is one time after the pause.
|
|
138
|
+
|
|
139
|
+
Without Vue, the same is `controller.inputSearch(text, event)`, `controller.flushSearch()`, and `search` and `searchPending` of `getView()`. `createDebounce(run, { debounce })` is the timer under it, with `call`, `cancel`, `flush` and `pending`.
|
|
140
|
+
|
|
141
|
+
## Filter a column
|
|
142
|
+
|
|
143
|
+
`filter.columns` holds one value for each column that filters. `controller.setColumnFilter(columnId, value)` sets it. The shape of the value decides how it matches, unless the column says otherwise with `filter`:
|
|
144
|
+
|
|
145
|
+
| Value | Kind | Matches |
|
|
146
|
+
| --- | --- | --- |
|
|
147
|
+
| A text | `text` | Cells whose text holds it |
|
|
148
|
+
| A list | `select` | Cells whose value is in the list |
|
|
149
|
+
| `{ min, max }` | `range` | Numbers between the ends. One end can be left out |
|
|
150
|
+
| `{ from, to }` | `dateRange` | Dates between the days. A day as `YYYY-MM-DD` means the whole day |
|
|
151
|
+
|
|
152
|
+
A function `filter(value, filterValue, row)` on a column decides for itself. An empty text, an empty list and an object of empty ends ask for nothing.
|
|
153
|
+
|
|
154
|
+
## Facets for filter controls
|
|
155
|
+
|
|
156
|
+
```vue title="facets.vue"
|
|
157
|
+
<script setup lang="ts">
|
|
158
|
+
import { Toggle, ToggleGroup } from '@ui-sdk/vue/toggle'
|
|
159
|
+
import { createTableController, Table, useTableView, type ColumnDef } from 'ui-sdk-table-vue'
|
|
160
|
+
import { computed } from 'vue'
|
|
161
|
+
|
|
162
|
+
type Shoe = { id: string; model: string; brand: string; color: string }
|
|
163
|
+
|
|
164
|
+
const shoes: Shoe[] = [
|
|
165
|
+
{ id: 's1', model: 'Trail 2', brand: 'Northway', color: 'Black' },
|
|
166
|
+
{ id: 's2', model: 'Glide', brand: 'Sola', color: 'White' },
|
|
167
|
+
{ id: 's3', model: 'Ridge', brand: 'Northway', color: 'Green' },
|
|
168
|
+
{ id: 's4', model: 'Tempo', brand: 'Sola', color: 'Black' },
|
|
169
|
+
{ id: 's5', model: 'Cloud 9', brand: 'Arc', color: 'White' },
|
|
170
|
+
{ id: 's6', model: 'Summit', brand: 'Northway', color: 'Black' },
|
|
171
|
+
]
|
|
172
|
+
|
|
173
|
+
const columns: ColumnDef<Shoe>[] = [
|
|
174
|
+
{ id: 'model', header: 'Model' },
|
|
175
|
+
{ id: 'brand', header: 'Brand', filter: 'select' },
|
|
176
|
+
{ id: 'color', header: 'Color', filter: 'select' },
|
|
177
|
+
]
|
|
178
|
+
|
|
179
|
+
const LISTS = [
|
|
180
|
+
{ id: 'brand', label: 'Brand' },
|
|
181
|
+
{ id: 'color', label: 'Color' },
|
|
182
|
+
]
|
|
183
|
+
|
|
184
|
+
const controller = createTableController()
|
|
185
|
+
const view = useTableView(controller)
|
|
186
|
+
|
|
187
|
+
// The facets are read again after each change of the view.
|
|
188
|
+
const lists = computed(() =>
|
|
189
|
+
view.value
|
|
190
|
+
? LISTS.map((list) => ({
|
|
191
|
+
...list,
|
|
192
|
+
values: controller.getFacets(list.id).values,
|
|
193
|
+
chosen: (view.value?.filter.columns?.[list.id] as string[] | undefined) ?? [],
|
|
194
|
+
}))
|
|
195
|
+
: [],
|
|
196
|
+
)
|
|
197
|
+
</script>
|
|
198
|
+
|
|
199
|
+
<template>
|
|
200
|
+
<ToggleGroup
|
|
201
|
+
v-for="list in lists"
|
|
202
|
+
:key="list.id"
|
|
203
|
+
multiple
|
|
204
|
+
:aria-label="list.label"
|
|
205
|
+
:value="list.chosen"
|
|
206
|
+
@value-change="(values) => controller.setColumnFilter(list.id, values)"
|
|
207
|
+
>
|
|
208
|
+
<Toggle v-for="facet in list.values" :key="facet.text" :value="String(facet.value)">
|
|
209
|
+
{{ facet.text }} ({{ facet.count }})
|
|
210
|
+
</Toggle>
|
|
211
|
+
</ToggleGroup>
|
|
212
|
+
<Table :rows="shoes" :columns="columns" :controller="controller" aria-label="Running shoes" />
|
|
213
|
+
</template>
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Press Northway. The colors list counts only the shoes of Northway. Press Black too: two shoes match both. Press Northway again to let it go.
|
|
217
|
+
|
|
218
|
+
`controller.getFacets(columnId)` answers with what a control offers:
|
|
219
|
+
|
|
220
|
+
| Control | Read |
|
|
221
|
+
| --- | --- |
|
|
222
|
+
| A list of values | `values`: each with `value`, `text` in the format of the column, and `count`. A combobox can search the list by `text`; `fuzzyScore` of `@ui-sdk/core/text-match` is the search of the table |
|
|
223
|
+
| A slider | `range`: `min`, `max` and `step`, the smallest change that the format of the column shows |
|
|
224
|
+
| A date picker | `days`: the first and the last day as `YYYY-MM-DD`, in the time zone of the column; `dates` holds the two moments |
|
|
225
|
+
|
|
226
|
+
- The facets follow the search and the filters of the other columns, and never the filter of the column itself, so a filter does not take away its own choices. `getFacets(columnId, { rows: 'all' })` gives the facets of every row.
|
|
227
|
+
- A value that the filter names stays in the list with the count 0 when no row holds it any more.
|
|
228
|
+
- `kind` says which filter fits the column: its `filter` option, or what its format says. A column of dates gives `dateRange`, a column of numbers `range`, any other column `text`.
|
|
229
|
+
- `sliderBounds(range, { steps: 100 })` gives a slider its ends and a step that a thumb can use: 1, 2 or 5 times a power of ten of the step of a cell, and about a hundred stops.
|
|
230
|
+
- A facet is counted when it is asked for, and kept until the search or another filter changes.
|
|
231
|
+
|
|
232
|
+
## Names
|
|
233
|
+
|
|
234
|
+
- **Options:** `sort`, `defaultSort`, `filter`, `defaultFilter`, `multiSort`, `alwaysSorted`, `searchDebounce`, `searchMode`, `fuzzyThreshold`, `sortChildren`, `facets`; column keys `sortable`, `compare`, `filter`, `searchable`.
|
|
235
|
+
- **Events:** `sort-change`, `filter-change`.
|
|
236
|
+
- **Controller:** `sortBy`, `toggleSort`, `setSearch`, `inputSearch`, `flushSearch`, `setColumnFilter`, `clearFilters`, `clearColumnFilters`, `getFacets`.
|
|
237
|
+
- **Exports:** `useTableSearch`, `createDebounce`, `sliderBounds`, `isEmptyFilter`, and the types `SortRule`, `FilterState`, `FilterKind`, `FilterMatcher`, `MultiSortMode`, `ColumnFacets`, `ColumnFacetValue`, `FacetOptions`, `TableSearch`.
|
|
238
|
+
- **Attributes:** `aria-sort`, `data-sorted` and `data-sort-index` on a header cell.
|
|
239
|
+
|
|
240
|
+
See the [Sort tiles](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sort) and the [Filter tiles](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=filter) of the sink.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# State and events
|
|
2
|
+
|
|
3
|
+
Start a state where you want it, hold it in your app, and hear each change with its reason.
|
|
4
|
+
|
|
5
|
+
Every state of the table works the same way, as the state of a UI SDK component does. Use `default<Key>` to choose where a state starts, and `v-model:<key>` to hold it in your app.
|
|
6
|
+
|
|
7
|
+
```vue title="controlled.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Table, type ColumnDef, type SortRule, type TableChangeDetails } from 'ui-sdk-table-vue'
|
|
10
|
+
import { shallowRef } from 'vue'
|
|
11
|
+
|
|
12
|
+
type Player = { id: string; name: string; club: string; goals: number }
|
|
13
|
+
|
|
14
|
+
const players: Player[] = [
|
|
15
|
+
{ id: 'p1', name: 'Lena Fischer', club: 'Rovers', goals: 14 },
|
|
16
|
+
{ id: 'p2', name: 'Sam Carter', club: 'United', goals: 21 },
|
|
17
|
+
{ id: 'p3', name: 'Noor Haddad', club: 'Rovers', goals: 9 },
|
|
18
|
+
{ id: 'p4', name: 'Ivan Petrov', club: 'Athletic', goals: 17 },
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
const columns: ColumnDef<Player>[] = [
|
|
22
|
+
{ id: 'name', header: 'Player', sortable: true },
|
|
23
|
+
{ id: 'club', header: 'Club', sortable: true },
|
|
24
|
+
{ id: 'goals', header: 'Goals', sortable: true, format: 'integer' },
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
// The app holds the sort: the table shows what this ref says.
|
|
28
|
+
const sort = shallowRef<readonly SortRule[]>([{ id: 'goals', desc: true }])
|
|
29
|
+
const said = shallowRef('No change yet.')
|
|
30
|
+
|
|
31
|
+
function onSortChange(value: readonly SortRule[], details: TableChangeDetails) {
|
|
32
|
+
// The club column sorts only with another column before it.
|
|
33
|
+
if (value[0]?.id === 'club' && value.length === 1) {
|
|
34
|
+
details.cancel()
|
|
35
|
+
said.value = 'Refused: sort by goals or by player first, then add the club with Shift.'
|
|
36
|
+
return
|
|
37
|
+
}
|
|
38
|
+
said.value = `${value.map((rule) => `${rule.id} ${rule.desc ? 'down' : 'up'}`).join(', ') || 'no sort'}, by ${details.reason}`
|
|
39
|
+
}
|
|
40
|
+
</script>
|
|
41
|
+
|
|
42
|
+
<template>
|
|
43
|
+
<Table
|
|
44
|
+
v-model:sort="sort"
|
|
45
|
+
:rows="players"
|
|
46
|
+
:columns="columns"
|
|
47
|
+
aria-label="Goals of the season"
|
|
48
|
+
@sort-change="onSortChange"
|
|
49
|
+
/>
|
|
50
|
+
<p role="status">{{ said }}</p>
|
|
51
|
+
</template>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Press a header to sort. The line under the table says the sort and its reason. Press Club alone and the app refuses it; press Goals, then Club with Shift, and the sort holds both.
|
|
55
|
+
|
|
56
|
+
## Three props for each state
|
|
57
|
+
|
|
58
|
+
| Prop | What it does |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `<key>` | The value of the state. With it, the app holds the state: `v-model:<key>` |
|
|
61
|
+
| `default<Key>` | Where the state starts when the table holds it |
|
|
62
|
+
| `@<key>-change` | Runs at each change, with `(value, details)` |
|
|
63
|
+
|
|
64
|
+
The keys are `sort`, `filter`, `groupBy`, `page`, `expanded`, `selected`, `columnVisibility`, `columnOrder`, `columnWidths`, `columnPinning`, `rowPinning`, `columnAggregates`, `cellFormats`, `cellFormulas` and `cellRange`.
|
|
65
|
+
|
|
66
|
+
`columnWidths` and `cellRange` change at each step of a drag. Their `@column-widths-commit` and `@cell-range-commit` run once, when the drag ends.
|
|
67
|
+
|
|
68
|
+
## The details of a change
|
|
69
|
+
|
|
70
|
+
- `details.reason` says why the state changed: `press`, `item-press`, `list-navigation`, `input-change`, `imperative` (a call of the controller), `reset`, `drag`, `move-key`, `resize-key`, `escape-key`, `shortcut`, `undo` or `redo`. The type is `TableReason`.
|
|
71
|
+
- `details.event` is the event behind the change, when there was one.
|
|
72
|
+
- `details.source` says how the person caused it: `mouse`, `touch`, `pen`, `keyboard`, `virtual`, `agent` for a call of an agent, or `programmatic`. Read it for analytics, never for behavior.
|
|
73
|
+
- `details.cancel()` refuses the change. The table then sends no `update:<key>`, so a `v-model` keeps its value.
|
|
74
|
+
|
|
75
|
+
## The table never changes your data
|
|
76
|
+
|
|
77
|
+
The rows and the columns are yours. The table never copies or changes a row object. Each row needs a stable id: the `id` property, or what `getRowId(row, index, parent)` returns.
|
|
78
|
+
|
|
79
|
+
An edit of a cell is no state. The table reports it through `@cell-edit`, and the app puts the value into its rows: see [Editing](./cell-editing.md).
|
|
80
|
+
|
|
81
|
+
With `v-model:<key>`, the table renders whole at each change, as for every prop that the owner holds. With `default<Key>`, the table keeps the value itself. For a large table, prefer `default<Key>` and listen to `@<key>-change` where the app only needs to hear a change.
|
|
82
|
+
|
|
83
|
+
## Keep going
|
|
84
|
+
|
|
85
|
+
- [Controller and view](./controller-and-view.md) changes a state from code, and reads what the table shows.
|
package/docs/styling.md
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Styling
|
|
2
|
+
|
|
3
|
+
Give the table the looks of your app with CSS that reads its parts and its state.
|
|
4
|
+
|
|
5
|
+
The table has no looks of its own: no class, no colour and no inline style for state. Every element carries a `data-slot`, and its state shows as `aria-*` and `data-*` attributes and a few CSS variables. A style reads those. Write it in plain CSS, in Tailwind CSS or in the tokens of your design system.
|
|
6
|
+
|
|
7
|
+
```vue title="sticky.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
10
|
+
|
|
11
|
+
type Reading = {
|
|
12
|
+
id: string
|
|
13
|
+
station: string
|
|
14
|
+
day: string
|
|
15
|
+
low: number
|
|
16
|
+
high: number
|
|
17
|
+
rain: number
|
|
18
|
+
wind: number
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const STATIONS = ['Bergen', 'Cork', 'Porto', 'Gdansk', 'Tromso', 'Nantes']
|
|
22
|
+
const readings: Reading[] = Array.from({ length: 18 }, (_, index) => ({
|
|
23
|
+
id: `r${index}`,
|
|
24
|
+
station: STATIONS[index % STATIONS.length] ?? '',
|
|
25
|
+
day: `2026-11-${String(10 + Math.floor(index / 6)).padStart(2, '0')}`,
|
|
26
|
+
low: 2 + ((index * 3) % 7),
|
|
27
|
+
high: 8 + ((index * 5) % 9),
|
|
28
|
+
rain: (index * 7) % 13,
|
|
29
|
+
wind: 10 + ((index * 11) % 25),
|
|
30
|
+
}))
|
|
31
|
+
|
|
32
|
+
const columns: ColumnDef<Reading>[] = [
|
|
33
|
+
{ id: 'station', header: 'Station', width: 120 },
|
|
34
|
+
{ id: 'day', header: 'Day', width: 120 },
|
|
35
|
+
{ id: 'low', header: 'Low, °C', width: 110, format: 'integer', aggregate: 'min' },
|
|
36
|
+
{ id: 'high', header: 'High, °C', width: 110, format: 'integer', aggregate: 'max' },
|
|
37
|
+
{ id: 'rain', header: 'Rain, mm', width: 110, format: 'integer', aggregate: 'sum' },
|
|
38
|
+
{ id: 'wind', header: 'Wind, km/h', width: 120, format: 'integer', aggregate: 'max' },
|
|
39
|
+
]
|
|
40
|
+
</script>
|
|
41
|
+
|
|
42
|
+
<template>
|
|
43
|
+
<!-- The frame scrolls both ways. The header, the footer and the station stay in view. -->
|
|
44
|
+
<div class="frame">
|
|
45
|
+
<Table
|
|
46
|
+
:rows="readings"
|
|
47
|
+
:columns="columns"
|
|
48
|
+
:default-column-pinning="{ start: ['station'] }"
|
|
49
|
+
sticky-header
|
|
50
|
+
sticky-footer
|
|
51
|
+
aria-label="Weather readings"
|
|
52
|
+
/>
|
|
53
|
+
</div>
|
|
54
|
+
</template>
|
|
55
|
+
|
|
56
|
+
<style scoped>
|
|
57
|
+
.frame {
|
|
58
|
+
max-inline-size: 460px;
|
|
59
|
+
max-block-size: 260px;
|
|
60
|
+
overflow: auto;
|
|
61
|
+
border: 1px solid #e4e4e7;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/* What sticks needs a background of its own, so the rows that scroll under it do not show through. */
|
|
65
|
+
.frame :deep(tr[data-sticky] > *),
|
|
66
|
+
.frame :deep([data-pinned]) {
|
|
67
|
+
background: #fff;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
.frame :deep([data-pinned-edge]) {
|
|
71
|
+
box-shadow: inset -1px 0 0 #a1a1aa;
|
|
72
|
+
}
|
|
73
|
+
</style>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Scroll the frame down and to the side. The header and the footer stay at their edges, and the Station column stays at the start. Each sticky cell has a background, so the rows under it do not show through.
|
|
77
|
+
|
|
78
|
+
## Parts
|
|
79
|
+
|
|
80
|
+
| Part | `data-slot` | Element |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| The table | `table` | `table` |
|
|
83
|
+
| The head, the body and the foot | `table-head`, `table-body`, `table-foot` | `thead`, `tbody`, `tfoot` |
|
|
84
|
+
| A column | `table-col` | `col` |
|
|
85
|
+
| A header row | `table-header-row` | `tr` |
|
|
86
|
+
| A body row and a footer row | `table-row` | `tr` |
|
|
87
|
+
| The row of an empty or a loading table | `table-plain-row` | `tr` |
|
|
88
|
+
| The stand-in for rows of the row window | `table-spacer` | `tr` |
|
|
89
|
+
| A cell | `table-cell` | `th` in the head and for a row number, else `td` |
|
|
90
|
+
| The editor of a cell | `table-editor` | `input` |
|
|
91
|
+
| Why an edit was refused | `table-edit-error` | `span` |
|
|
92
|
+
| The handle of a resize | `table-resizer` | `span` |
|
|
93
|
+
| The fill handle of a sheet | `table-fill-handle` | `span` |
|
|
94
|
+
|
|
95
|
+
A header cell of a sortable column holds a `button` without a `data-slot`. A cell that your slot fills holds what the slot gives.
|
|
96
|
+
|
|
97
|
+
## State as attributes
|
|
98
|
+
|
|
99
|
+
| What | Where | Attribute |
|
|
100
|
+
| --- | --- | --- |
|
|
101
|
+
| Kind of a row | `tr` | `data-kind`: `row`, `group`, `detail`, `empty`, `letters` |
|
|
102
|
+
| Kind of a cell of a group row | `td` | `data-kind`: `group-label`, `group-total`, `group-blank` |
|
|
103
|
+
| Column of a cell | cell | `data-column` |
|
|
104
|
+
| Format | cell | `data-format`, the name of the format that makes the text |
|
|
105
|
+
| Sort | header cell | `aria-sort`, `data-sorted` (`asc`, `desc`), `data-sort-index` from 1 |
|
|
106
|
+
| A selected row | `tr` | `aria-selected="true"`, `data-selected`. A row that can be selected and is not has `aria-selected="false"` |
|
|
107
|
+
| An open tree row, group or detail | `tr` | `aria-expanded`, `data-expanded` |
|
|
108
|
+
| The level of a row of a tree or a group | `tr` | `aria-level`, from 1 |
|
|
109
|
+
| A pinned cell | cell | `data-pinned` (`start`, `end`), `data-pinned-edge` on the last one |
|
|
110
|
+
| A pinned or sticky row | `tr` | `data-pinned` (`top`, `bottom`), `data-sticky` (`top`, `bottom`) |
|
|
111
|
+
| A lead column | cell | `data-lead` |
|
|
112
|
+
| The cell with the tab stop | cell | `data-active` |
|
|
113
|
+
| A cell in a selected range | cell | `data-selected`, `data-range-edge` (`top`, `right`, `bottom`, `left`) |
|
|
114
|
+
| A cell that can be edited, or is | cell | `data-editable`, `data-editing`, `data-checking` while a check runs |
|
|
115
|
+
| A refused text | editor | `aria-invalid="true"`, `data-invalid` |
|
|
116
|
+
| Rows on their way | table | `aria-busy`, `data-loading` |
|
|
117
|
+
| Options that change keys | table | `data-cell-selection`, `data-sheet`, `data-row-window` |
|
|
118
|
+
|
|
119
|
+
The attributes of the data sheet and of formulas are on their own pages.
|
|
120
|
+
|
|
121
|
+
## CSS variables
|
|
122
|
+
|
|
123
|
+
| Variable | On | What it holds |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `--table-width` | table | The sum of the widths, for a table whose columns are resized |
|
|
126
|
+
| `--table-column-width` | cell | The width of the column of the cell |
|
|
127
|
+
| `--table-pin-offset` | pinned cell | How far it sticks from its edge |
|
|
128
|
+
| `--table-pin-start-size`, `--table-pin-end-size` | head, body | The widths of the pinned columns at each edge |
|
|
129
|
+
| `--table-sticky-offset` | sticky cell | How far it sticks from its edge |
|
|
130
|
+
| `--table-sticky-top-size`, `--table-sticky-bottom-size` | head, body | The heights of what sticks at each edge |
|
|
131
|
+
| `--table-row-height` | table | The height of a row in the row window |
|
|
132
|
+
| `--table-spacer-size` | spacer row | The height of the rows that it stands in for |
|
|
133
|
+
|
|
134
|
+
A page with a fixed header or footer of its own sets `--table-sticky-top` and `--table-sticky-bottom` on the table or a parent, and the sticky rows stop there.
|
|
135
|
+
|
|
136
|
+
## Sticky rows and pinned columns
|
|
137
|
+
|
|
138
|
+
The table marks what sticks. The style makes it stick:
|
|
139
|
+
|
|
140
|
+
```css
|
|
141
|
+
[data-slot='table'] tr[data-sticky] > * {
|
|
142
|
+
position: sticky;
|
|
143
|
+
z-index: 2;
|
|
144
|
+
background: white;
|
|
145
|
+
}
|
|
146
|
+
[data-slot='table'] tr[data-sticky='top'] > * {
|
|
147
|
+
inset-block-start: var(--table-sticky-offset, 0);
|
|
148
|
+
}
|
|
149
|
+
[data-slot='table'] tr[data-sticky='bottom'] > * {
|
|
150
|
+
inset-block-end: var(--table-sticky-offset, 0);
|
|
151
|
+
}
|
|
152
|
+
[data-slot='table-cell'][data-pinned] {
|
|
153
|
+
position: sticky;
|
|
154
|
+
z-index: 1;
|
|
155
|
+
background: white;
|
|
156
|
+
}
|
|
157
|
+
[data-slot='table-cell'][data-pinned='start'] {
|
|
158
|
+
inset-inline-start: var(--table-pin-offset);
|
|
159
|
+
}
|
|
160
|
+
[data-slot='table-cell'][data-pinned='end'] {
|
|
161
|
+
inset-inline-end: var(--table-pin-offset);
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- A sticky cell needs an opaque background, so the rows that scroll under it stay hidden.
|
|
166
|
+
- A row sticks to the nearest parent that scrolls. A frame with `overflow-x: auto` alone leaves the page as the frame of the rows.
|
|
167
|
+
- A cell that gets focus scrolls into view. Give the cells `scroll-margin-block: var(--table-sticky-top-size, 0) var(--table-sticky-bottom-size, 0)` and `scroll-margin-inline: var(--table-pin-start-size, 0) var(--table-pin-end-size, 0)`, so it stops beside what sticks and not under it.
|
|
168
|
+
|
|
169
|
+
## Right to left
|
|
170
|
+
|
|
171
|
+
Set `dir="rtl"` on the page or a parent. The arrow keys follow the reading direction, and a pin to the start sticks at the right edge. Use logical properties, such as `inset-inline-start`, in your style.
|
|
172
|
+
|
|
173
|
+
See the [Style tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=style): four looks of the same table, each in CSS of its own.
|
|
174
|
+
|
|
175
|
+
## Keep going
|
|
176
|
+
|
|
177
|
+
- [Cells and slots](./cells-and-slots.md) gives rows and cells a class of your own.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ui-sdk-table-vue",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Vue parts for the ui-sdk-table primitive: slots, v-model and controllers.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"data-grid",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"access": "public"
|
|
38
38
|
},
|
|
39
39
|
"dependencies": {
|
|
40
|
-
"ui-sdk-table-core": "0.1.
|
|
40
|
+
"ui-sdk-table-core": "0.1.2"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@types/jsdom": "^30.0.0",
|