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,112 @@
1
+ # An Excel file with formulas
2
+
3
+ Download a sheet as an Excel file whose cells keep their formulas, where Excel computes them the same way.
4
+
5
+ Use it for a sheet with formulas that a person goes on with in a spreadsheet. Without it, the file holds the results only.
6
+
7
+ ```vue title="file.vue"
8
+ <script setup lang="ts">
9
+ import { Button } from '@ui-sdk/vue/button'
10
+ import {
11
+ applyEdits,
12
+ createTableController,
13
+ rowNumberColumn,
14
+ Table,
15
+ type CellEdit,
16
+ type CellFormulas,
17
+ type ColumnDef,
18
+ } from 'ui-sdk-table-vue'
19
+ import { createFormulaEngine, excelFormulas } from 'ui-sdk-table-vue/formulas'
20
+ import { shallowRef } from 'vue'
21
+
22
+ type Month = { id: string; month: string; income: number; costs: number; profit?: unknown }
23
+
24
+ const rows = shallowRef<Month[]>([
25
+ { id: 'm1', month: 'January', income: 8200, costs: 5100, profit: 3100 },
26
+ { id: 'm2', month: 'February', income: 7600, costs: 5400, profit: 2200 },
27
+ { id: 'm3', month: 'March', income: 9100, costs: 5050, profit: 4050 },
28
+ ])
29
+
30
+ const columns: ColumnDef<Month>[] = [
31
+ rowNumberColumn<Month>(),
32
+ { id: 'month', header: 'Month', editable: false },
33
+ { id: 'income', header: 'Income', format: 'integer' },
34
+ { id: 'costs', header: 'Costs', format: 'integer' },
35
+ { id: 'profit', header: 'Profit', format: 'integer' },
36
+ ]
37
+
38
+ const formulas = shallowRef<CellFormulas>({
39
+ cells: {
40
+ m1: { profit: '=[income]-[costs]' },
41
+ m2: { profit: '=[income]-[costs]' },
42
+ m3: { profit: '=[income]-[costs]' },
43
+ },
44
+ })
45
+
46
+ const engine = createFormulaEngine()
47
+ const controller = createTableController()
48
+
49
+ async function download() {
50
+ const { downloadXlsx } = await import('ui-sdk-table-vue/export')
51
+ // `excelFormulas()` writes a formula into the file where it means the same in Excel.
52
+ await downloadXlsx(controller.exportData(), 'profit', { formula: excelFormulas() })
53
+ }
54
+ </script>
55
+
56
+ <template>
57
+ <div>
58
+ <Button @click="download">Download Excel</Button>
59
+ </div>
60
+ <Table
61
+ v-model:cell-formulas="formulas"
62
+ :formulas="engine"
63
+ :rows="rows"
64
+ :columns="columns"
65
+ :controller="controller"
66
+ locale="en-US"
67
+ sheet
68
+ column-letters
69
+ aria-label="Profit by month"
70
+ @cell-edit="(edits: readonly CellEdit<Month>[]) => (rows = applyEdits(rows, edits))"
71
+ />
72
+ </template>
73
+ ```
74
+
75
+ Press Download Excel. In profit.xlsx, each cell under Profit holds the formula of its row, such as B2-C2, with its result beside it.
76
+
77
+ ## Turn it on
78
+
79
+ ```ts
80
+ const { downloadXlsx } = await import('ui-sdk-table-vue/export')
81
+ await downloadXlsx(controller.exportData(), 'profit', { formula: excelFormulas() })
82
+ ```
83
+
84
+ - `excelFormulas()` of the formulas entry is the `formula` option of `toXlsx` and `downloadXlsx`.
85
+ - A cell with a formula, of its own or of its column, gets the formula of the file (`<f>`) with its result beside it, when the formula means the same in Excel (below).
86
+ - The addresses are places in the file. A sorted or filtered export keeps the formulas that read their own row.
87
+ - An error of a formula is an error cell of the file. `#CYCLE!` stays a text.
88
+ - A CSV holds the results.
89
+ - `ExportCell.formula`, `ExportRow.id` and `ExportData.document` carry the formulas to a writer of your own.
90
+
91
+ ## Dates of the `period` format
92
+
93
+ With or without the option, a column with the format `period` whose unit is `day`, `month` or `year` is a date cell with a pattern when a spreadsheet shows the pattern as the screen does: `Nov 21, 2026`, `November 2026` and `2026` in `en-US`. Else it is its text. A week, a quarter, an hour and a day of the week are texts.
94
+
95
+ ## When a formula goes into the file
96
+
97
+ A cell gets the formula of the file only when the whole formula means the same in Excel:
98
+
99
+ - every cell that it reads is in the file and holds there the value that it holds in the table: no day, no cell written as its text;
100
+ - a range is one column whose rows are in the file in the order of the document and next to each other;
101
+ - each function is in `EXCEL_FUNCTIONS`.
102
+
103
+ Else the cell holds its result, as without the option. A file without the option holds the same bytes as the file of a table without formulas.
104
+
105
+ See the [Formula tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=formula) and the page [Export](./export.md).
106
+
107
+ ## Names
108
+
109
+ - **Options of `toXlsx` and `downloadXlsx`:** `formula`, with `excelFormulas()` of the formulas entry.
110
+ - **Exports of the formulas entry:** `excelFormulas`, `EXCEL_FUNCTIONS`.
111
+ - **Exports of the export entry:** the type `XlsxFormulas`.
112
+ - **Fields of the data:** `ExportCell.formula`, `ExportRow.id`, `ExportData.document`.
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 [An Excel file with formulas](./excel-formulas.md).
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).
package/docs/fill.md ADDED
@@ -0,0 +1,110 @@
1
+ # Fill
2
+
3
+ Let a person drag the corner of a range to fill more cells, with a series where the values have one step.
4
+
5
+ Use it in a sheet where rows repeat a value or go on with a series: weeks, days, numbers.
6
+
7
+ ```vue title="fill.vue"
8
+ <script setup lang="ts">
9
+ import { Button } from '@ui-sdk/vue/button'
10
+ import {
11
+ applyEdits,
12
+ createTableController,
13
+ Table,
14
+ type CellEdit,
15
+ type ColumnDef,
16
+ } from 'ui-sdk-table-vue'
17
+ import { shallowRef } from 'vue'
18
+
19
+ type Lesson = { id: string; week: number | null; day: string; room: string }
20
+
21
+ const columns: ColumnDef<Lesson>[] = [
22
+ { id: 'week', header: 'Week', format: 'integer' },
23
+ { id: 'day', header: 'Day' },
24
+ { id: 'room', header: 'Room' },
25
+ ]
26
+
27
+ const rows = shallowRef<Lesson[]>([
28
+ { id: 'l1', week: 1, day: '2027-01-04', room: 'A1' },
29
+ { id: 'l2', week: 2, day: '2027-01-11', room: 'B2' },
30
+ { id: 'l3', week: null, day: '', room: '' },
31
+ { id: 'l4', week: null, day: '', room: '' },
32
+ { id: 'l5', week: null, day: '', room: '' },
33
+ ])
34
+
35
+ const controller = createTableController()
36
+
37
+ // The first two rows are the source: numbers and days with one step go on as a series.
38
+ function fillDown() {
39
+ controller.selectCells({ rowId: 'l1', columnId: 'week' }, { rowId: 'l5', columnId: 'room' })
40
+ void controller.fillCells('down', 2)
41
+ }
42
+ </script>
43
+
44
+ <template>
45
+ <div>
46
+ <Button @click="fillDown">Fill down from two rows</Button>
47
+ </div>
48
+ <Table
49
+ :rows="rows"
50
+ :columns="columns"
51
+ :controller="controller"
52
+ sheet
53
+ aria-label="Lessons of a course"
54
+ @cell-edit="(edits: readonly CellEdit<Lesson>[]) => (rows = applyEdits(rows, edits))"
55
+ />
56
+ </template>
57
+ ```
58
+
59
+ Press Fill down from two rows: weeks 3, 4 and 5 and the days 2027-01-18, 01-25 and 02-01 follow, and the rooms repeat A1, B2. Or select a cell and drag the small square at its corner down.
60
+
61
+ ## The handle
62
+
63
+ The fill handle is the part `[data-slot='table-fill-handle']`: an empty `span` inside the cell at the end corner of the selected cells.
64
+
65
+ - Place it with `position: absolute` at `inset-block-end` and `inset-inline-end` of its cell, which needs `position: relative`. The logical sides put it at the left corner from right to left.
66
+ - Give it `touch-action: none`.
67
+ - `fill-handle="vertical"` or `"horizontal"` keeps the handle and the keys on one axis. `:fill-handle="false"` with `sheet` takes both away.
68
+
69
+ ## A drag
70
+
71
+ - A drag fills along the rows or along the columns, whichever the pointer went further on.
72
+ - While it runs, the table has `data-filling`. Each cell that would be filled has `data-fill-target` and `data-fill-edge` (`top`, `right`, `bottom`, `left`), so a line around the target is the same CSS as the line around a range.
73
+ - Near an edge of the scroll frame the table scrolls, also with a row window.
74
+ - Escape ends the drag and changes nothing.
75
+
76
+ ## What it writes
77
+
78
+ - A source of one line repeats.
79
+ - A source of two or more lines goes on when it is numbers with one step (also negative, a fraction, upward and backward) or days with one step: `2028-02-22`, `2028-02-29` goes on with `2028-03-07`. Everything else repeats in its order.
80
+ - A fill along the rows passes values. A fill along the columns passes text through the `parse` of the next column.
81
+ - A cell that cannot be edited keeps its value and its place in the line.
82
+ - A fill from pinned rows into the rows of the list is refused: they are no neighbours in the data.
83
+
84
+ ## All or nothing, one step
85
+
86
+ Each value passes the schema of its column. One refusal stops the fill before any cell changes, and the table says which column refused which text. A fill is one report through `@cell-edit` with the reason `fill`, and one step of the history. Its undo puts back the values of before, also for rows that were sorted, filtered or removed since.
87
+
88
+ ## From code
89
+
90
+ `controller.fillCells('down' | 'up' | 'forward' | 'back', source = 1)` fills the selected cells from their first `source` lines. It works without the `fill-handle` option, which is about the handle and the keys. It throws for one selected line, for a wrong direction (with the valid ones), and with the reason of a refusal.
91
+
92
+ ## Keys
93
+
94
+ | Key | With `fill-handle` |
95
+ | --- | --- |
96
+ | Control or Command with D | Fills the selected cells down from their first row |
97
+ | Control or Command with R | Fills the selected cells forward from their first column |
98
+ | Escape during a drag | Ends the drag and changes nothing |
99
+
100
+ With one line selected the keys stay the browser's: Control+R is its reload.
101
+
102
+ See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
103
+
104
+ ## Names
105
+
106
+ - **Options:** `fillHandle` (`true`, `'vertical'`, `'horizontal'`, `false`).
107
+ - **Controller:** `fillCells`.
108
+ - **Attributes:** `data-filling` on the table; `data-fill-target` and `data-fill-edge` on a cell; the part `table-fill-handle`.
109
+ - **Messages:** `cellsFilled`, `fillRefused`, `fillNowhere`, `fillOverPinned`.
110
+ - **Exports:** `fillValues`, `fillLine`, `TableFillHandle`, and the types `FillWay`, `FillDirection`, `FillDraft`.
@@ -0,0 +1,145 @@
1
+ # Formats
2
+
3
+ Let a person make cells bold, give them a colour, or show a number as a percentage, and save that with the document.
4
+
5
+ Use it in a sheet with a toolbar. A format of a cell is data, as the values are: the app saves it and passes it back.
6
+
7
+ ```vue title="formats.vue"
8
+ <script setup lang="ts">
9
+ import { Button } from '@ui-sdk/vue/button'
10
+ import {
11
+ createTableController,
12
+ Table,
13
+ useTableView,
14
+ type CellFormat,
15
+ type CellFormats,
16
+ type ColumnDef,
17
+ } from 'ui-sdk-table-vue'
18
+ import { computed, shallowRef } from 'vue'
19
+
20
+ type Fund = { id: string; fund: string; fee: number; year: number }
21
+
22
+ const funds: Fund[] = [
23
+ { id: 'f1', fund: 'Nordic Index', fee: 0.002, year: 0.0784 },
24
+ { id: 'f2', fund: 'Global Bonds', fee: 0.0035, year: -0.0136 },
25
+ { id: 'f3', fund: 'Small Caps', fee: 0.011, year: 0.1207 },
26
+ ]
27
+
28
+ const columns: ColumnDef<Fund>[] = [
29
+ { id: 'fund', header: 'Fund' },
30
+ { id: 'fee', header: 'Fee', format: 'decimal' },
31
+ { id: 'year', header: 'One year', format: 'decimal' },
32
+ ]
33
+
34
+ const controller = createTableController()
35
+ const view = useTableView(controller)
36
+ // Formats are plain data that the app saves with its document.
37
+ const formats = shallowRef<CellFormats | undefined>({ cells: { f2: { year: { color: 'alert' } } } })
38
+
39
+ // The format of the active cell gives the pressed state of the buttons.
40
+ const active = computed<CellFormat>(() => {
41
+ const at = view.value?.activeCell
42
+ void formats.value
43
+ return at ? controller.getCellFormat(at.rowId, at.columnId) : {}
44
+ })
45
+ </script>
46
+
47
+ <template>
48
+ <div>
49
+ <Button :aria-pressed="active.bold === true" @click="controller.toggleCellFormat('bold')">
50
+ Bold
51
+ </Button>
52
+ <Button @click="controller.formatCells({ format: 'percentage', decimals: 1 })">Percent</Button>
53
+ <Button @click="controller.formatCells({ fill: 'accent' })">Mark</Button>
54
+ <Button @click="controller.clearCellFormats()">Clear</Button>
55
+ </div>
56
+ <!-- A colour of a format is a name. The style of the page gives each name its colours. -->
57
+ <Table
58
+ v-model:cell-formats="formats"
59
+ :rows="funds"
60
+ :columns="columns"
61
+ :controller="controller"
62
+ :format-colors="['accent', 'alert']"
63
+ cell-selection
64
+ aria-label="Funds"
65
+ />
66
+ </template>
67
+ ```
68
+
69
+ Select the three cells under Fee and press Percent: they read 0.2%, 0.4% and 1.1%. Press Bold: the button shows it pressed. Clear takes the formats of the selected cells away.
70
+
71
+ ## The value
72
+
73
+ `CellFormats` is `{ columns?: { [columnId]: CellFormat }, cells?: { [rowId]: { [columnId]: CellFormat } } }`.
74
+
75
+ - A property of a cell wins over the same property of its column, and both win over the `format` and `formatOptions` of the column definition.
76
+ - A format follows its row through a sort, a filter and a page.
77
+ - Pass it as `v-model:cell-formats`, `cell-formats` or `default-cell-formats`.
78
+
79
+ `CellFormat` has `format` (`text`, `integer`, `decimal`, `currency`, `percentage`, `date`, `datetime`), `decimals` (0 to 10), `currency` (an ISO code), `dateStyle` (`short`, `medium`, `long`, `full`), `align` (`start`, `center`, `end`), `bold`, `italic`, `color` and `fill`.
80
+
81
+ ## Change formats
82
+
83
+ ```ts
84
+ controller.formatCells({ bold: true, fill: 'green' }) // the selected cells
85
+ controller.formatCells({ format: 'percentage', decimals: 1 }, { columns: ['share'] })
86
+ controller.formatCells({ fill: null }, { from: { rowId: 'a', columnId: 'price' } })
87
+ controller.clearCellFormats()
88
+ controller.toggleCellFormat('bold') // for a toolbar button
89
+ controller.getCellFormat(rowId, columnId) // for the pressed state
90
+ ```
91
+
92
+ - A patch with `null` for a key takes that property away.
93
+ - A wrong property, name or colour throws with the valid ones.
94
+ - Control or Command with B and with I make the selected cells bold and italic, with `sheet`.
95
+
96
+ ## Looks are attributes
97
+
98
+ - A cell has `data-align`, `data-bold`, `data-italic`, `data-color`, `data-fill`, and `data-format` with the name that decides its text. The table writes no class and no style.
99
+ - A colour is a name of `format-colors` and nothing of CSS. The style of the app gives each name its colours and holds the contrast.
100
+ - Give a fill an opaque background, so a pinned cell with a fill hides what scrolls under it. Decide what a selected cell with a fill looks like.
101
+ - `cellAttrs` of the caller cannot overwrite these attributes.
102
+
103
+ ## The text of a cell
104
+
105
+ - The format makes the text: 0.342 with `{ format: 'percentage', decimals: 1 }` reads `34.2%`.
106
+ - The footer and the totals of a group follow the column layer.
107
+ - A CSV and an Excel file hold the text of the screen. In an Excel file a cell whose own format decides its text is written as text.
108
+ - A copy holds the plain value, as the editor shows it, so a paste into the same columns gives the same values.
109
+ - The `#cell` and `#col-{id}` slots get `format`, the format that the cell has of its own, and `text`.
110
+ - A search and the label of a group read the column definition and do not follow a format of a cell.
111
+
112
+ ## A percentage in the text field
113
+
114
+ A cell that shows `25%` opens with `25`, and `30` or `30%` in the field is 0.3, as in a column with the `percentage` format. Every other text holds the value itself: a paste, a fill and `editCell` read `0.3` as 0.3, as a copy gives it, and a text with a percent sign (`30%`) is that percentage. A column with a `parse`, or with `scale: 'percent'` in its `formatOptions`, keeps the plain value in its field.
115
+
116
+ ## Whole columns
117
+
118
+ When the selected cells are every row that the table has, `formatCells` formats the columns. The format then holds for rows that come later, and the value stays small. Never with `manual-page`, where the table does not have every row.
119
+
120
+ Format a column, not 50,000 cells, when the value is saved as JSON: cells that share a format share one object in memory, but JSON writes one entry for each row.
121
+
122
+ ## History
123
+
124
+ A change of formats is one step: its entry in `getHistory()` has `formats: true` and `cells: 0`. An undo reports the formats of before through `update:cell-formats` and `cell-formats-change` with the reason `undo`, property by property, so a format that the owner gave another cell meanwhile stays. `details.cancel()` in `cell-formats-change` refuses a change.
125
+
126
+ ## Rows that left
127
+
128
+ The table keeps the format of a row that is gone, because the row can come back with the next page. `pruneFormats(formats, rowIds, columnIds)` drops them when the owner knows better. `setFormats(formats, place, patch)` and `revertFormats` are the pure functions behind the controller.
129
+
130
+ ## Rendering
131
+
132
+ With `v-model:cell-formats` the table renders whole at a change, as for every prop that the owner holds. With `default-cell-formats` the table keeps the value and only the changed cells render. For a large sheet without a row window, prefer `default-cell-formats` and listen to `cell-formats-change`.
133
+
134
+ See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
135
+
136
+ ## Names
137
+
138
+ - **Options:** `cellFormats`, `defaultCellFormats`, `formatColors`.
139
+ - **Events:** `cell-formats-change`, `update:cell-formats`.
140
+ - **Controller:** `formatCells`, `clearCellFormats`, `toggleCellFormat`, `getCellFormat`.
141
+ - **View:** `cellFormats`.
142
+ - **Slot props:** `format` in `#cell` and `#col-{id}`.
143
+ - **Attributes:** `data-align`, `data-bold`, `data-italic`, `data-color`, `data-fill`, `data-format`.
144
+ - **Messages:** `cellsFormatted`.
145
+ - **Exports:** `setFormats`, `revertFormats`, `pruneFormats`, `resolveFormat`, `CELL_FORMAT_NAMES`, `CELL_ALIGNS`, `CELL_DATE_STYLES`, and the types `CellFormat`, `CellFormats`, `CellFormatPatch`, `CellFormatName`, `FormatPlace`, `FormatTarget`.
@@ -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).