ui-sdk-table-vue 0.1.0 → 0.1.1
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 -80
- package/docs/README.md +16 -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/export.md +92 -0
- package/docs/groups-and-totals.md +104 -0
- package/docs/llms.txt +16 -0
- package/docs/pages-and-server-mode.md +203 -0
- package/docs/rows.md +277 -0
- package/docs/selection-and-keyboard.md +118 -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,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).
|
package/docs/export.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Export
|
|
2
|
+
|
|
3
|
+
Write the rows of the table to a CSV or an Excel file, with the text that the screen shows.
|
|
4
|
+
|
|
5
|
+
`controller.exportData()` collects the cells as plain data. The writers are in the entry `ui-sdk-table-vue/export`, so a page without an export does not carry them: load it with `import()` where a person asks for a file.
|
|
6
|
+
|
|
7
|
+
```vue title="files.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Button } from '@ui-sdk/vue/button'
|
|
10
|
+
import { createTableController, Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
11
|
+
import { shallowRef } from 'vue'
|
|
12
|
+
|
|
13
|
+
type Order = { id: string; customer: string; city: string; total: number }
|
|
14
|
+
|
|
15
|
+
const orders: Order[] = [
|
|
16
|
+
{ id: 'o1', customer: 'Northway', city: 'Oslo', total: 1240 },
|
|
17
|
+
{ id: 'o2', customer: 'Sola', city: 'Seville', total: 860.5 },
|
|
18
|
+
{ id: 'o3', customer: 'Arc', city: 'Lyon', total: 2310 },
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
const columns: ColumnDef<Order>[] = [
|
|
22
|
+
{ id: 'customer', header: 'Customer', sortable: true },
|
|
23
|
+
{ id: 'city', header: 'City' },
|
|
24
|
+
{ id: 'total', header: 'Total', format: 'decimal', aggregate: 'sum' },
|
|
25
|
+
// The id is for the screen only.
|
|
26
|
+
{ id: 'id', header: 'Id', exportable: false },
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
const controller = createTableController()
|
|
30
|
+
const csv = shallowRef('')
|
|
31
|
+
|
|
32
|
+
async function preview() {
|
|
33
|
+
// The writers are an entry of their own: they load at the first export.
|
|
34
|
+
const { toCsv } = await import('ui-sdk-table-vue/export')
|
|
35
|
+
csv.value = toCsv(controller.exportData({ totals: true }))
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
async function download() {
|
|
39
|
+
const { downloadXlsx } = await import('ui-sdk-table-vue/export')
|
|
40
|
+
await downloadXlsx(controller.exportData(), 'orders')
|
|
41
|
+
}
|
|
42
|
+
</script>
|
|
43
|
+
|
|
44
|
+
<template>
|
|
45
|
+
<div>
|
|
46
|
+
<Button @click="preview">Show the CSV</Button>
|
|
47
|
+
<Button @click="download">Download Excel</Button>
|
|
48
|
+
</div>
|
|
49
|
+
<Table
|
|
50
|
+
:rows="orders"
|
|
51
|
+
:columns="columns"
|
|
52
|
+
:controller="controller"
|
|
53
|
+
locale="en-US"
|
|
54
|
+
aria-label="Orders to export"
|
|
55
|
+
/>
|
|
56
|
+
<pre v-if="csv" data-testid="csv">{{ csv }}</pre>
|
|
57
|
+
</template>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Press Show the CSV. The file holds the customer, the city and the total of each order and a row of totals, and no id. Download Excel saves the same rows as orders.xlsx.
|
|
61
|
+
|
|
62
|
+
## What goes in
|
|
63
|
+
|
|
64
|
+
`exportData(options)` takes:
|
|
65
|
+
|
|
66
|
+
- `rows`: `'filtered'` (the default, every row that passes the filters, on all pages, in the order of the screen), `'page'`, `'all'` (in the order of the data) or `'selected'`.
|
|
67
|
+
- `columns`: `'visible'` (the default, in their order), `'all'` (the hidden columns after them) or a list of ids.
|
|
68
|
+
- `children`: whether the child rows of a tree come with it, open or not. Defaults to true.
|
|
69
|
+
- `groups`: whether each group gets a row of its own before its rows. Defaults to false.
|
|
70
|
+
- `totals`: whether a last row holds the totals. Defaults to false.
|
|
71
|
+
|
|
72
|
+
A column with `exportable: false` is in no file. `exportValue(row)` of a column gives the value of a file in place of the value and its format, for a column whose cell is a slot.
|
|
73
|
+
|
|
74
|
+
## The text of a cell
|
|
75
|
+
|
|
76
|
+
The text of a cell in a file is the text of the screen. An Excel cell is a number or a date with a pattern only when a spreadsheet shows it as the screen does; else the cell is text.
|
|
77
|
+
|
|
78
|
+
## The writers
|
|
79
|
+
|
|
80
|
+
- `toCsv(data, options)` returns the text. Its options: `separator` (a comma), `lineEnd` (`\r\n`), `header` (true), `bom` (true, so Excel reads UTF-8), `escapeFormulas` (true: a text that a spreadsheet would read as a formula gets a `'` before it).
|
|
81
|
+
- `toXlsx(data, options)` returns the bytes of the file. Its options: `sheetName`, `freezeHeader` (true), `compress` (true), and `formula` for a table with formulas: see the page "An Excel file with formulas" of the group "Data sheet".
|
|
82
|
+
- `downloadCsv(data, filename, options)` and `downloadXlsx(data, filename, options)` save a file in the browser.
|
|
83
|
+
|
|
84
|
+
With `manualPage`, the table has one page of a server, so each set of rows is of that page.
|
|
85
|
+
|
|
86
|
+
## Names
|
|
87
|
+
|
|
88
|
+
- **Controller:** `exportData`.
|
|
89
|
+
- **Column keys:** `exportable`, `exportValue`.
|
|
90
|
+
- **Export entry:** `toCsv`, `toXlsx`, `downloadCsv`, `downloadXlsx`, `downloadFile`, `zip`, `XLSX_TYPE`, and the types `CsvOptions`, `XlsxOptions`, `XlsxFormulas`, `ExportData`, `ExportRow`, `ExportColumn`, `ExportCell`, `ExportOptions`.
|
|
91
|
+
|
|
92
|
+
See the [More tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=more).
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Groups and totals
|
|
2
|
+
|
|
3
|
+
Group the rows by the values of a column, and show a total of a column under it, for each group and for the table.
|
|
4
|
+
|
|
5
|
+
```vue title="groups.vue"
|
|
6
|
+
<script setup lang="ts">
|
|
7
|
+
import { Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
8
|
+
|
|
9
|
+
type Sale = { id: string; region: string; rep: string; deals: number; amount: number }
|
|
10
|
+
|
|
11
|
+
const sales: Sale[] = [
|
|
12
|
+
{ id: 's1', region: 'North', rep: 'Ada Lindqvist', deals: 4, amount: 12400 },
|
|
13
|
+
{ id: 's2', region: 'North', rep: 'Leo Brandt', deals: 2, amount: 5300 },
|
|
14
|
+
{ id: 's3', region: 'South', rep: 'Tomas Reyes', deals: 6, amount: 18750 },
|
|
15
|
+
{ id: 's4', region: 'South', rep: 'Maya Okafor', deals: 3, amount: 9100 },
|
|
16
|
+
{ id: 's5', region: 'South', rep: 'Nina Sato', deals: 1, amount: 2200 },
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
const columns: ColumnDef<Sale>[] = [
|
|
20
|
+
{ id: 'region', header: 'Region' },
|
|
21
|
+
{ id: 'rep', header: 'Rep', sortable: true },
|
|
22
|
+
{ id: 'deals', header: 'Deals', format: 'integer', aggregate: 'sum' },
|
|
23
|
+
{
|
|
24
|
+
id: 'amount',
|
|
25
|
+
header: 'Amount',
|
|
26
|
+
format: 'currency',
|
|
27
|
+
formatOptions: { currency: 'EUR', showUnit: true },
|
|
28
|
+
aggregate: 'sum',
|
|
29
|
+
},
|
|
30
|
+
]
|
|
31
|
+
</script>
|
|
32
|
+
|
|
33
|
+
<template>
|
|
34
|
+
<Table
|
|
35
|
+
:rows="sales"
|
|
36
|
+
:columns="columns"
|
|
37
|
+
:group-by="['region']"
|
|
38
|
+
:default-expanded="['group/region=North']"
|
|
39
|
+
:default-column-visibility="{ region: false }"
|
|
40
|
+
locale="en-US"
|
|
41
|
+
aria-label="Sales by region"
|
|
42
|
+
>
|
|
43
|
+
<template #group="{ text, expanded, toggleExpanded, group }">
|
|
44
|
+
<button type="button" :aria-expanded="expanded" @click="toggleExpanded">
|
|
45
|
+
{{ expanded ? '▾' : '▸' }} {{ text }}
|
|
46
|
+
</button>
|
|
47
|
+
({{ group.leaves.length }} reps)
|
|
48
|
+
</template>
|
|
49
|
+
<template #foot-rep>All regions</template>
|
|
50
|
+
</Table>
|
|
51
|
+
</template>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Press South to open its group. Each group row shows the deals and the amount of its reps under their columns, and the footer shows the totals of every region.
|
|
55
|
+
|
|
56
|
+
## Totals
|
|
57
|
+
|
|
58
|
+
A column with `aggregate` has a total: `sum`, `mean`, `min`, `max`, `count`, `uniqueCount` or `first`, or a function `(values, rows) => total`. The table then has a footer row with the total of each column, in the format of the column.
|
|
59
|
+
|
|
60
|
+
- The footer, the group rows, `controller.getTotals()` and the totals of an export read one function. A total counts the rows that pass the filters, on every page, with their child rows.
|
|
61
|
+
- A pinned row that the filter refuses is in view and not in a total.
|
|
62
|
+
- `#foot` and `#foot-{column id}` fill a footer cell. They get `column`, `value`, `text`, `totals` and `aggregate`.
|
|
63
|
+
- With rows from a server, the table has one page of rows and its totals are of that page. Pass `:totals="{ table: { amount: 1234 }, groups: { 'group/team=Design': { amount: 800 } } }"` for the totals of the server.
|
|
64
|
+
|
|
65
|
+
## Group rows
|
|
66
|
+
|
|
67
|
+
`groupBy` is a list of column ids. Each one adds a level of groups. `canGroup(row)` keeps a row out of the groups: the rows that it refuses come first, before every group.
|
|
68
|
+
|
|
69
|
+
`groupable: true` on a column is for the controls of your app: it marks the columns that a person may group by. The table itself groups by any column that `groupBy` names.
|
|
70
|
+
|
|
71
|
+
The id of a group is `group/<column id>=<value>`, such as `group/region=North`. `expanded` holds the ids of the open groups, as it holds the ids of open tree rows.
|
|
72
|
+
|
|
73
|
+
A group row has a label cell and, from the first column with an `aggregate` on, one cell for each column: the total of the group stands under its header and over the total of the footer. The label covers the columns before that. It ends where pinned columns end, so it sticks or scrolls as one cell.
|
|
74
|
+
|
|
75
|
+
- `#group` fills the label cell. It gets `group`, `text`, `expanded`, `level`, `totals`, `totalTexts`, `toggleExpanded`, the `path` of the group (the groups above it and itself, each with `column`, `value` and `text`, for a label such as "Europe / Finland") and `covered`, the columns under the label. A total of a covered column has no cell of its own.
|
|
76
|
+
- `#group-total-{column id}` and `#group-total` fill a cell under a column. They get `group`, `column`, `value`, `text`, `totals`, `aggregate`, `expanded`, `level` and `path`. A column without an `aggregate` has an empty cell, with an empty `text`.
|
|
77
|
+
- `:group-totals="false"` gives one cell as wide as the table, as a table without any `aggregate` has.
|
|
78
|
+
- Hide the column of the groups with `columnVisibility`: the group rows say its values.
|
|
79
|
+
|
|
80
|
+
## Keys
|
|
81
|
+
|
|
82
|
+
| Key | On a cell of a group row |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| Enter | Opens or closes the group, from every cell of its row |
|
|
85
|
+
| Space | Selects the rows of the group, with `selection="multiple"` |
|
|
86
|
+
| The arrows | Cross the cells of the row, as in any row |
|
|
87
|
+
|
|
88
|
+
A group row holds no values. Its cells are never part of a cell range, and a copy gives an empty line for it.
|
|
89
|
+
|
|
90
|
+
## Attributes
|
|
91
|
+
|
|
92
|
+
- `data-kind="group"` on the row, with `aria-expanded` and `aria-level`. A table with group rows has the role `treegrid`.
|
|
93
|
+
- `data-kind` on a cell of a group row: `group-label`, `group-total` or `group-blank`.
|
|
94
|
+
- `cellAttrs` gets the kind `group` for the label cell and `group-total` for the cells under a column. `rowAttrs` gets the kind `group` with the `path`.
|
|
95
|
+
|
|
96
|
+
## Names
|
|
97
|
+
|
|
98
|
+
- **Options:** `groupBy`, `defaultGroupBy`, `groupTotals`, `totals`, `canGroup`; column keys `aggregate`, `groupable`.
|
|
99
|
+
- **Events:** `group-by-change`.
|
|
100
|
+
- **Controller:** `setGroupBy`, `expandAll`, `collapseAll`, `getTotals`.
|
|
101
|
+
- **Slots:** `#group`, `#group-total`, `#group-total-{column id}`, `#foot`, `#foot-{column id}`.
|
|
102
|
+
- **Types:** `GroupRow`, `GroupPathEntry`, `AggregateName`, `AggregateFn`, `ColumnTotal`, `TableTotalsSource`.
|
|
103
|
+
|
|
104
|
+
See the [Group tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=group).
|
package/docs/llms.txt
CHANGED
|
@@ -269,3 +269,19 @@ The rules of a scoped style reach the elements of the table through `:deep()`, b
|
|
|
269
269
|
- [Introduction](./introduction.md): A headless table for Vue: the logic of a data table, and no looks.
|
|
270
270
|
- [Installation](./installation.md): Add the packages to your Vue app.
|
|
271
271
|
- [First table](./first-table.md): Put a table on a page and give it looks.
|
|
272
|
+
|
|
273
|
+
### Using the table
|
|
274
|
+
|
|
275
|
+
- [Columns](./column-definitions.md): Say what each column shows, how its value becomes text, and how a person can change its place and width.
|
|
276
|
+
- [Cells and slots](./cells-and-slots.md): Put your own content in a header, a cell, a footer or the empty table, and give rows and cells your own attributes.
|
|
277
|
+
- [State and events](./state-and-events.md): Start a state where you want it, hold it in your app, and hear each change with its reason.
|
|
278
|
+
- [Styling](./styling.md): Give the table the looks of your app with CSS that reads its parts and its state.
|
|
279
|
+
- [Controller and view](./controller-and-view.md): Change the table from a control beside it, and read what it shows now.
|
|
280
|
+
- [Sort, filter and search](./sort-filter-and-search.md): Sort by one or more columns, filter each column, and search every column with a pause in the typing.
|
|
281
|
+
- [Groups and totals](./groups-and-totals.md): Group the rows by the values of a column, and show a total of a column under it, for each group and for the table.
|
|
282
|
+
- [Pages and server mode](./pages-and-server-mode.md): Show the rows a page at a time, and take the rows, the pages, the sort and the filters from a server.
|
|
283
|
+
- [Rows](./rows.md): Show rows with child rows, a detail row under a row, rows pinned to an edge, and many thousand rows in a window.
|
|
284
|
+
- [Selection and keyboard](./selection-and-keyboard.md): Let a person select rows, and move through the table with the keys of a grid.
|
|
285
|
+
- [Editing](./cell-editing.md): Let a person change the value of a cell, check it first, and put it into your rows.
|
|
286
|
+
- [Export](./export.md): Write the rows of the table to a CSV or an Excel file, with the text that the screen shows.
|
|
287
|
+
- [Agents](./agents.md): Let an agent find a table on the page, read it and act on it, with the same actions that a person has.
|