ui-sdk-table-vue 0.1.3 → 0.2.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/docs/README.md +15 -0
- package/docs/cell-editing.md +107 -3
- package/docs/excel-formulas.md +2 -0
- package/docs/how-the-table-is-built.md +107 -0
- package/docs/llms.txt +17 -0
- package/docs/reference-columns.md +62 -0
- package/docs/reference-controller.md +133 -0
- package/docs/reference-export.md +59 -0
- package/docs/reference-formulas.md +39 -0
- package/docs/reference-messages.md +55 -0
- package/docs/reference-table.md +244 -0
- package/docs/reference-view.md +110 -0
- package/docs/sheet-formulas.md +11 -4
- package/docs/styled-table.md +163 -0
- package/package.json +2 -2
- package/src/draft.ts +136 -0
- package/src/index.ts +1 -0
- package/src/table.ts +44 -0
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# A styled table for an app
|
|
2
|
+
|
|
3
|
+
Build the table component of your design system on the headless table: the order of the work, and for each control what the library gives and what your app writes.
|
|
4
|
+
|
|
5
|
+
Read it when you write the one table that every page of an app uses. A page of the app then passes rows, columns and a few options, and gets the looks and the controls of the design system.
|
|
6
|
+
|
|
7
|
+
```vue title="toolbar.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Button } from '@ui-sdk/vue/button'
|
|
10
|
+
import { Checkbox, CheckboxIndicator } from '@ui-sdk/vue/checkbox'
|
|
11
|
+
import { Input } from '@ui-sdk/vue/input'
|
|
12
|
+
import {
|
|
13
|
+
createTableController,
|
|
14
|
+
Table,
|
|
15
|
+
useTableSearch,
|
|
16
|
+
useTableView,
|
|
17
|
+
type ColumnDef,
|
|
18
|
+
} from 'ui-sdk-table-vue'
|
|
19
|
+
|
|
20
|
+
type Book = { id: string; title: string; author: string; year: number }
|
|
21
|
+
|
|
22
|
+
const books: Book[] = [
|
|
23
|
+
{ id: 'b1', title: 'The Long Field', author: 'Ines Moreau', year: 2019 },
|
|
24
|
+
{ id: 'b2', title: 'Salt and Iron', author: 'Tom Ashby', year: 2021 },
|
|
25
|
+
{ id: 'b3', title: 'Small Hours', author: 'Ines Moreau', year: 2016 },
|
|
26
|
+
{ id: 'b4', title: 'North Light', author: 'Kai Lund', year: 2023 },
|
|
27
|
+
{ id: 'b5', title: 'The River Road', author: 'Tom Ashby', year: 2012 },
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
const columns: ColumnDef<Book>[] = [
|
|
31
|
+
// The title stays: a person cannot hide it.
|
|
32
|
+
{ id: 'title', header: 'Title', sortable: true, hideable: false },
|
|
33
|
+
{ id: 'author', header: 'Author', sortable: true },
|
|
34
|
+
{ id: 'year', header: 'Year', sortable: true },
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
// The controls read the view and call the controller; the table holds the state.
|
|
38
|
+
const controller = createTableController()
|
|
39
|
+
const view = useTableView(controller)
|
|
40
|
+
const search = useTableSearch(controller)
|
|
41
|
+
// A constant, not a literal in the template: a new object at each render is a new state.
|
|
42
|
+
const firstPage = { page: 1, pageSize: 2 }
|
|
43
|
+
const page = () => view.value?.page ?? 1
|
|
44
|
+
const pageCount = () => view.value?.pageCount ?? 1
|
|
45
|
+
</script>
|
|
46
|
+
|
|
47
|
+
<template>
|
|
48
|
+
<div role="toolbar" aria-label="Books">
|
|
49
|
+
<Input
|
|
50
|
+
type="search"
|
|
51
|
+
aria-label="Search the books"
|
|
52
|
+
:value="search.text.value"
|
|
53
|
+
@value-change="(text) => (search.text.value = text)"
|
|
54
|
+
/>
|
|
55
|
+
<label
|
|
56
|
+
v-for="column in view?.columns.filter((each) => each.hideable !== false)"
|
|
57
|
+
:key="column.id"
|
|
58
|
+
>
|
|
59
|
+
<Checkbox
|
|
60
|
+
:checked="view?.visibleColumns.includes(column) ?? true"
|
|
61
|
+
@checked-change="(next) => controller.setColumnVisibility(column.id, next === true)"
|
|
62
|
+
>
|
|
63
|
+
<CheckboxIndicator>✓</CheckboxIndicator>
|
|
64
|
+
</Checkbox>
|
|
65
|
+
{{ column.header }}
|
|
66
|
+
</label>
|
|
67
|
+
</div>
|
|
68
|
+
<Table
|
|
69
|
+
:rows="books"
|
|
70
|
+
:columns="columns"
|
|
71
|
+
:controller="controller"
|
|
72
|
+
:default-page="firstPage"
|
|
73
|
+
aria-label="Books"
|
|
74
|
+
/>
|
|
75
|
+
<nav aria-label="Pages of the books">
|
|
76
|
+
<Button :disabled="page() === 1" @click="controller.setPage(page() - 1)">Previous</Button>
|
|
77
|
+
<span role="status">Page {{ page() }} of {{ pageCount() }}</span>
|
|
78
|
+
<Button :disabled="page() === pageCount()" @click="controller.setPage(page() + 1)">Next</Button>
|
|
79
|
+
</nav>
|
|
80
|
+
</template>
|
|
81
|
+
|
|
82
|
+
<style scoped>
|
|
83
|
+
/* The looks of the controls are the app's. Here they only get room. */
|
|
84
|
+
[role='toolbar'],
|
|
85
|
+
nav {
|
|
86
|
+
display: flex;
|
|
87
|
+
gap: 12px;
|
|
88
|
+
align-items: center;
|
|
89
|
+
}
|
|
90
|
+
label {
|
|
91
|
+
display: flex;
|
|
92
|
+
gap: 6px;
|
|
93
|
+
align-items: center;
|
|
94
|
+
}
|
|
95
|
+
</style>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Type an author into the search field, take Year out of the table with its box, and step through the pages. Each control reads the view and calls the controller; the table holds the state.
|
|
99
|
+
|
|
100
|
+
## The order of the work
|
|
101
|
+
|
|
102
|
+
1. **The wrapper.** One component that renders `Table` and passes its props, its events, its slots and a `controller` through. Take the controller from a prop, else make one with `createTableController()`, and expose it.
|
|
103
|
+
2. **The looks of the table.** Style the parts by `data-slot` and the state by `data-*` and `aria-*` attributes. See [Styling](./styling.md).
|
|
104
|
+
3. **The controls beside the table.** A toolbar, a search field, filters, a column menu, the pages, an export menu. Each reads `useTableView(controller)` and calls a method of the controller.
|
|
105
|
+
4. **The sheet controls**, when the app needs them: a sheet toolbar, a formula bar, a summary of the selected cells.
|
|
106
|
+
5. **The words.** Pass `messages` with the texts of your language.
|
|
107
|
+
|
|
108
|
+
## The wrapper
|
|
109
|
+
|
|
110
|
+
- **What the library gives:** `Table` with its props, events and slots; `createTableController`; `rowAttrs`, `cellAttrs` and `sectionAttrs` for classes.
|
|
111
|
+
- **What the app writes:** the list of props it passes through, the events it sends on, the slots it forwards, and its own lead columns, such as a checkbox column (`lead: true`).
|
|
112
|
+
- An option that a page does not set must reach the table as not set, so the table keeps its own default. Vue reads a boolean prop that is not set as `false`: give each boolean prop of the wrapper the default `undefined`.
|
|
113
|
+
- Keep `rowAttrs` and `cellAttrs` the same functions for the life of the table, and read the props inside them. A new function is a new option, and the table renders again.
|
|
114
|
+
- Pass arrays and objects as constants, not as literals in a template: a literal is a new value at each render.
|
|
115
|
+
- The export is named `Table`. A design system that has a `Table` of its own imports this one under another name: `import { Table as HeadlessTable } from 'ui-sdk-table-vue'`.
|
|
116
|
+
|
|
117
|
+
## Looks
|
|
118
|
+
|
|
119
|
+
- **What the library gives:** `data-slot` on every part, state as attributes, the CSS variables of widths, pins and sticky rows. See [Styling](./styling.md).
|
|
120
|
+
- **What the app writes:** one place for the classes of the design system. A class reaches a row or a cell through `rowAttrs` and `cellAttrs`, which get the `kind` of the row or cell (`header`, `row`, `cell`, `foot`, `group`, `group-total`, `detail`, `empty`, `letters`, `letter`). A caller cannot replace a state attribute of the table with them.
|
|
121
|
+
- A state shows through a selector of an attribute, such as `[data-pinned]` or `[aria-selected='true']`, never through a class that a script switches.
|
|
122
|
+
- A cell that sticks needs an opaque background, so the rows under it do not show through.
|
|
123
|
+
|
|
124
|
+
## The toolbar and the search field
|
|
125
|
+
|
|
126
|
+
- **What the library gives:** `useTableSearch(controller)` with `text`, `pending`, `clear()` and `flush()`; the option `searchDebounce`.
|
|
127
|
+
- **What the app writes:** the field of the design system, bound to `search.text`. Escape calls `clear()` and Enter `flush()`. See [Sort, filter and search](./sort-filter-and-search.md).
|
|
128
|
+
- The table says nothing to a screen reader about a search. Announce the rows found when `filter` changes.
|
|
129
|
+
|
|
130
|
+
## Filter controls
|
|
131
|
+
|
|
132
|
+
- **What the library gives:** `controller.getFacets(columnId)` with `kind`, `values`, `range` and `days`; `getFacets(columnId, { rows: 'all' })`; `setColumnFilter`, `clearColumnFilters`, `clearFilters`; `sliderBounds`, `isEmptyFilter`, `toText`.
|
|
133
|
+
- **What the app writes:** a control for each `kind`: a list of values, a slider with two fields, a date range. A search field in a long list. Which columns have a filter control.
|
|
134
|
+
- Read the ends of a slider and of a calendar from `getFacets(columnId, { rows: 'all' })`, so they do not move while a person filters another column. Read the counts of a list from `getFacets(columnId)`.
|
|
135
|
+
- A hidden column can still filter. List its filter, so a person can see why rows are gone.
|
|
136
|
+
|
|
137
|
+
## The column menu
|
|
138
|
+
|
|
139
|
+
- **What the library gives:** `setColumnVisibility`, `showAllColumns`, `hideAllColumns`, `resetColumnVisibility`, `resetColumnOrder`, `resetColumnPinning`, `resetColumnWidths`, `pinColumn`; the view fields `columns` and `visibleColumns`. `setColumnVisibility` throws for a column with `hideable: false`.
|
|
140
|
+
- **What the app writes:** the menu, a box for each column that can be hidden, and the entries for pins and resets that the app wants. See [Columns](./column-definitions.md).
|
|
141
|
+
|
|
142
|
+
## The pages
|
|
143
|
+
|
|
144
|
+
- **What the library gives:** `setPage`, `setPageSize` (`null` for one page with every row); the view fields `page` (from 1), `pageSize`, `pageCount`, `rowCount`, `pageUnit` and `lastPageKnown`.
|
|
145
|
+
- **What the app writes:** the pagination of the design system, a list of page sizes, and the text "11–20 of 23". With pages from a server that gave no count, `lastPageKnown` is false. See [Pages and server mode](./pages-and-server-mode.md).
|
|
146
|
+
|
|
147
|
+
## The export menu
|
|
148
|
+
|
|
149
|
+
- **What the library gives:** `controller.exportData(options)`; `toCsv`, `toXlsx`, `downloadCsv` and `downloadXlsx` in the entry `ui-sdk-table-vue/export`; `excelFormulas()` in `ui-sdk-table-vue/formulas`.
|
|
150
|
+
- **What the app writes:** the menu, and a message when the file fails. Load the entry with `import()` when a person asks for a file, never with a static import. See [Export](./export.md).
|
|
151
|
+
|
|
152
|
+
## The sheet toolbar, the formula bar and the summary
|
|
153
|
+
|
|
154
|
+
- **What the library gives:** `formatCells`, `toggleCellFormat`, `clearCellFormats`, `getCellFormat`, `undo`, `redo`; the view fields `activeCell`, `cellSelection`, `canUndo`, `canRedo`; `useFormulaBar(controller)`; `useSelectionSummary(controller)`; `getColumnFormula`, `setColumnFormula`, `getFormulaFunctions`.
|
|
155
|
+
- **What the app writes:** the buttons and lists, their pressed state from `getCellFormat` of the active cell, and focus back to the active cell (`[data-active]`) after a choice. A method that refuses throws: show the `cause` of the error when it is a text, else its `message`. See [Formats](./formats.md), [History](./history.md) and [Formulas](./sheet-formulas.md).
|
|
156
|
+
- Show the summary in a plain element, not in a live region: a new sum at each step of a selection is noise.
|
|
157
|
+
|
|
158
|
+
## The words
|
|
159
|
+
|
|
160
|
+
- **What the library gives:** `defaultMessages` and the type `TableMessages`. Pass your own as `messages`. `describeFormulaIssue` of the formulas entry gives the English words of a formula issue.
|
|
161
|
+
- **What the app writes:** the texts of its own controls in its language, and the texts of the table it wants other than English.
|
|
162
|
+
|
|
163
|
+
See the [More tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=more): `more-app` is one table with many options in one scene.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ui-sdk-table-vue",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
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.2.1"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@types/jsdom": "^30.0.0",
|
package/src/draft.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { cellKey, cellValue, type CellEdit, type ColumnDef } from 'ui-sdk-table-core'
|
|
2
|
+
import { computed, shallowRef, toValue, type ComputedRef, type MaybeRefOrGetter } from 'vue'
|
|
3
|
+
|
|
4
|
+
export type EditDraftOptions<Row> = {
|
|
5
|
+
/** The `getRowId` of the table, when it has one. Without it, a row is found by its `id`, else by its place. */
|
|
6
|
+
getRowId?: (row: Row, index: number, parent: null) => string | number
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
export type EditDraft<Row> = {
|
|
10
|
+
/** The rows to pass to the table: the rows of the owner with the values of the draft in them. */
|
|
11
|
+
rows: ComputedRef<Row[]>
|
|
12
|
+
/** How many cells hold another value than the rows of the owner. */
|
|
13
|
+
count: ComputedRef<number>
|
|
14
|
+
/** Whether a cell holds another value than the rows of the owner, by the row id and the column id. */
|
|
15
|
+
changed: (rowId: string, columnId: string) => boolean
|
|
16
|
+
/**
|
|
17
|
+
* Pass it as the `cell-edit` listener of the table. It takes every report:
|
|
18
|
+
* an edit, a paste, a fill, a clear and an undo. It throws for an edit of a
|
|
19
|
+
* row that is not in the rows of the owner, such as a child row.
|
|
20
|
+
*/
|
|
21
|
+
onCellEdit: (edits: readonly CellEdit<Row>[]) => void
|
|
22
|
+
/** The edits against the rows of the owner, one for each cell that differs, and an empty draft. */
|
|
23
|
+
save: () => CellEdit<Row>[]
|
|
24
|
+
/** Empties the draft. */
|
|
25
|
+
cancel: () => void
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
type Entry<Row> = { rowId: string; column: ColumnDef<Row>; value: unknown }
|
|
29
|
+
|
|
30
|
+
const same = (a: unknown, b: unknown) =>
|
|
31
|
+
Object.is(a, b) || (a instanceof Date && b instanceof Date && a.getTime() === b.getTime())
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A draft of edits that the owner saves or cancels as a whole, for a table
|
|
35
|
+
* whose cells a person fills in before a Save button. It never changes a row
|
|
36
|
+
* object of the owner: a row with values of the draft is a new object.
|
|
37
|
+
*
|
|
38
|
+
* The draft reads the top level of the rows only, as `applyEdits` does, and
|
|
39
|
+
* finds a row by the `getRowId` of the table, else by its `id`, else by its
|
|
40
|
+
* place. An edit of a row that it cannot find, such as a child row of a tree,
|
|
41
|
+
* throws, so no edit is dropped without a word.
|
|
42
|
+
*
|
|
43
|
+
* A value is kept by its row id and its column id. When the owner passes new
|
|
44
|
+
* rows, the draft stays over them, and a cell whose new value is the value of
|
|
45
|
+
* the draft no longer differs. A cell of a row that is gone counts no more,
|
|
46
|
+
* and `save` does not give it. The draft holds values only: the formulas of a
|
|
47
|
+
* table with `formulas` are in its `cellFormulas` state and stay there.
|
|
48
|
+
*/
|
|
49
|
+
export function useEditDraft<Row>(
|
|
50
|
+
source: MaybeRefOrGetter<readonly Row[]>,
|
|
51
|
+
options: EditDraftOptions<Row> = {},
|
|
52
|
+
): EditDraft<Row> {
|
|
53
|
+
const entries = shallowRef<ReadonlyMap<string, Entry<Row>>>(new Map())
|
|
54
|
+
|
|
55
|
+
const owner = computed(() => {
|
|
56
|
+
const byId = new Map<string, Row>()
|
|
57
|
+
toValue(source).forEach((row, index) => {
|
|
58
|
+
const own = (row as { id?: unknown } | null)?.id
|
|
59
|
+
const id = options.getRowId
|
|
60
|
+
? options.getRowId(row, index, null)
|
|
61
|
+
: typeof own === 'string' || typeof own === 'number'
|
|
62
|
+
? own
|
|
63
|
+
: index
|
|
64
|
+
byId.set(String(id), row)
|
|
65
|
+
})
|
|
66
|
+
return byId
|
|
67
|
+
})
|
|
68
|
+
|
|
69
|
+
/** The entries whose row is there and whose value is not the value of the owner. */
|
|
70
|
+
const differing = computed(() => {
|
|
71
|
+
const kept = new Map<string, Entry<Row>>()
|
|
72
|
+
for (const [key, entry] of entries.value) {
|
|
73
|
+
const row = owner.value.get(entry.rowId)
|
|
74
|
+
if (row !== undefined && !same(cellValue(row, entry.column), entry.value)) {
|
|
75
|
+
kept.set(key, entry)
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
return kept
|
|
79
|
+
})
|
|
80
|
+
|
|
81
|
+
const rows = computed(() => {
|
|
82
|
+
const byRow = new Map<Row, Record<string, unknown>>()
|
|
83
|
+
for (const entry of differing.value.values()) {
|
|
84
|
+
const row = owner.value.get(entry.rowId) as Row
|
|
85
|
+
let change = byRow.get(row)
|
|
86
|
+
if (!change) byRow.set(row, (change = {}))
|
|
87
|
+
change[entry.column.key ?? entry.column.id] = entry.value
|
|
88
|
+
}
|
|
89
|
+
return toValue(source).map((row) => {
|
|
90
|
+
const change = byRow.get(row)
|
|
91
|
+
return change ? { ...row, ...change } : row
|
|
92
|
+
})
|
|
93
|
+
})
|
|
94
|
+
|
|
95
|
+
return {
|
|
96
|
+
rows,
|
|
97
|
+
count: computed(() => differing.value.size),
|
|
98
|
+
changed: (rowId, columnId) => differing.value.has(cellKey(rowId, columnId)),
|
|
99
|
+
onCellEdit: (edits) => {
|
|
100
|
+
for (const edit of edits) {
|
|
101
|
+
if (!owner.value.has(edit.rowId)) {
|
|
102
|
+
throw new Error(
|
|
103
|
+
`The draft has no row "${edit.rowId}" for the edit of column "${edit.columnId}": it reads the top level of the rows only. Pass the \`getRowId\` of the table to \`useEditDraft\`; the edits of child rows need code of your own.`,
|
|
104
|
+
)
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
const next = new Map(entries.value)
|
|
108
|
+
for (const edit of edits) {
|
|
109
|
+
const key = cellKey(edit.rowId, edit.columnId)
|
|
110
|
+
const row = owner.value.get(edit.rowId)
|
|
111
|
+
// A cell that is set back to the value of the owner leaves the draft.
|
|
112
|
+
if (row !== undefined && same(cellValue(row, edit.column), edit.value)) next.delete(key)
|
|
113
|
+
else next.set(key, { rowId: edit.rowId, column: edit.column, value: edit.value })
|
|
114
|
+
}
|
|
115
|
+
entries.value = next
|
|
116
|
+
},
|
|
117
|
+
save: () => {
|
|
118
|
+
const edits = [...differing.value.values()].map((entry): CellEdit<Row> => {
|
|
119
|
+
const row = owner.value.get(entry.rowId) as Row
|
|
120
|
+
return {
|
|
121
|
+
rowId: entry.rowId,
|
|
122
|
+
columnId: entry.column.id,
|
|
123
|
+
row,
|
|
124
|
+
column: entry.column,
|
|
125
|
+
value: entry.value,
|
|
126
|
+
previous: cellValue(row, entry.column),
|
|
127
|
+
}
|
|
128
|
+
})
|
|
129
|
+
entries.value = new Map()
|
|
130
|
+
return edits
|
|
131
|
+
},
|
|
132
|
+
cancel: () => {
|
|
133
|
+
entries.value = new Map()
|
|
134
|
+
},
|
|
135
|
+
}
|
|
136
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -38,6 +38,7 @@ export {
|
|
|
38
38
|
export { createTableController } from './controller'
|
|
39
39
|
export { useTableSearch, type TableSearch } from './search'
|
|
40
40
|
export { useTableView } from './view'
|
|
41
|
+
export { useEditDraft, type EditDraft, type EditDraftOptions } from './draft'
|
|
41
42
|
export { useSelectionSummary, type SelectionSummaryOptions } from './summary'
|
|
42
43
|
export {
|
|
43
44
|
aggregateName,
|
package/src/table.ts
CHANGED
|
@@ -157,6 +157,7 @@ const OPTIONS = [
|
|
|
157
157
|
'history',
|
|
158
158
|
'fillHandle',
|
|
159
159
|
'editable',
|
|
160
|
+
'entry',
|
|
160
161
|
'cellSelection',
|
|
161
162
|
'columnLetters',
|
|
162
163
|
'manualSort',
|
|
@@ -198,6 +199,7 @@ const BOOLEANS: readonly string[] = [
|
|
|
198
199
|
'stickyFooter',
|
|
199
200
|
'sheet',
|
|
200
201
|
'editable',
|
|
202
|
+
'entry',
|
|
201
203
|
'cellSelection',
|
|
202
204
|
'columnLetters',
|
|
203
205
|
'manualSort',
|
|
@@ -320,6 +322,7 @@ const OWN_ATTRS: ReadonlySet<string> = new Set([
|
|
|
320
322
|
'data-editable',
|
|
321
323
|
'data-editing',
|
|
322
324
|
'data-empty',
|
|
325
|
+
'data-entry',
|
|
323
326
|
'data-expanded',
|
|
324
327
|
'data-fill',
|
|
325
328
|
'data-fill-edge',
|
|
@@ -418,15 +421,19 @@ export type TableEmits = {
|
|
|
418
421
|
}
|
|
419
422
|
|
|
420
423
|
export type HeaderSlotProps<Row> = {
|
|
424
|
+
/** The definition of the column. */
|
|
421
425
|
column: ColumnDef<Row>
|
|
422
426
|
/** The header text: `column.header`, or the column id. */
|
|
423
427
|
label: string
|
|
424
428
|
/** False for a header group, which holds columns and no cells. */
|
|
425
429
|
leaf: boolean
|
|
430
|
+
/** The direction of the column in the sort, `'asc'` or `'desc'`, or `undefined` when it does not sort. */
|
|
426
431
|
sort: SortDirection | undefined
|
|
427
432
|
/** The place of the column in the sort, from 1. With several columns in the sort, the first one sorts first. */
|
|
428
433
|
sortIndex: number | undefined
|
|
434
|
+
/** Sorts by the column as a press on the header does. Pass the event: with `multiSort`, its keys decide whether the column joins the sort. */
|
|
429
435
|
toggleSort: (event?: Event) => void
|
|
436
|
+
/** The edge that the column is pinned to, or `undefined`. */
|
|
430
437
|
pin: 'start' | 'end' | undefined
|
|
431
438
|
/**
|
|
432
439
|
* Selects the cells of the column, for a control in its header. With
|
|
@@ -439,9 +446,13 @@ export type HeaderSlotProps<Row> = {
|
|
|
439
446
|
}
|
|
440
447
|
|
|
441
448
|
export type CellSlotProps<Row> = {
|
|
449
|
+
/** The row object of the data, as the owner passed it. */
|
|
442
450
|
row: Row
|
|
451
|
+
/** The node of the row in the row model: its id, its parent and its children. */
|
|
443
452
|
node: DataRow<Row>
|
|
453
|
+
/** The definition of the column. */
|
|
444
454
|
column: ColumnDef<Row>
|
|
455
|
+
/** The value of the cell: `value` of the column, else the property that `key` names. */
|
|
445
456
|
value: unknown
|
|
446
457
|
/** The value as text, with the format of the cell, else of its column. */
|
|
447
458
|
text: string
|
|
@@ -452,14 +463,19 @@ export type CellSlotProps<Row> = {
|
|
|
452
463
|
* `data-bold`, `data-italic`, `data-color` and `data-fill`.
|
|
453
464
|
*/
|
|
454
465
|
format: CellFormat | undefined
|
|
466
|
+
/** Whether the row is selected. */
|
|
455
467
|
selected: boolean
|
|
468
|
+
/** Whether the row is open: its child rows or its detail row show. */
|
|
456
469
|
expanded: boolean
|
|
470
|
+
/** Whether the row can open: it has child rows or a detail row. */
|
|
457
471
|
expandable: boolean
|
|
458
472
|
/** Tree and group levels above this row, from 0. */
|
|
459
473
|
level: number
|
|
460
474
|
/** The edge that the row is pinned to. */
|
|
461
475
|
pinned: RowPin | undefined
|
|
476
|
+
/** Selects the row or takes it out of the selection, for a checkbox in the cell. */
|
|
462
477
|
toggleSelected: (event?: Event) => void
|
|
478
|
+
/** Opens or closes the row, for a button in the cell. */
|
|
463
479
|
toggleExpanded: (event?: Event) => void
|
|
464
480
|
/**
|
|
465
481
|
* With formulas: the formula of the cell as a person reads it, and the
|
|
@@ -470,9 +486,13 @@ export type CellSlotProps<Row> = {
|
|
|
470
486
|
}
|
|
471
487
|
|
|
472
488
|
export type EditorSlotProps<Row> = {
|
|
489
|
+
/** The row object of the data, as the owner passed it. */
|
|
473
490
|
row: Row
|
|
491
|
+
/** The node of the row in the row model: its id, its parent and its children. */
|
|
474
492
|
node: DataRow<Row>
|
|
493
|
+
/** The definition of the column. */
|
|
475
494
|
column: ColumnDef<Row>
|
|
495
|
+
/** The value of the cell now. */
|
|
476
496
|
value: unknown
|
|
477
497
|
/** The value as plain text, without a format: 0.25 for a cell that shows 25 %. `save` takes a value. */
|
|
478
498
|
text: string
|
|
@@ -502,8 +522,11 @@ export type EditorSlotProps<Row> = {
|
|
|
502
522
|
}
|
|
503
523
|
|
|
504
524
|
export type RowHeaderSlotProps<Row> = {
|
|
525
|
+
/** The row object of the data, as the owner passed it. */
|
|
505
526
|
row: Row
|
|
527
|
+
/** The node of the row in the row model: its id, its parent and its children. */
|
|
506
528
|
node: DataRow<Row>
|
|
529
|
+
/** The definition of the column with `rowHeader`. */
|
|
507
530
|
column: ColumnDef<Row>
|
|
508
531
|
/** The number of the row, from 1: its place among the rows that the table shows, counted over the pages. */
|
|
509
532
|
number: number
|
|
@@ -516,6 +539,7 @@ export type RowHeaderSlotProps<Row> = {
|
|
|
516
539
|
}
|
|
517
540
|
|
|
518
541
|
export type LetterSlotProps<Row> = {
|
|
542
|
+
/** The definition of the column under the letter. */
|
|
519
543
|
column: ColumnDef<Row>
|
|
520
544
|
/** The letter of the column: its place among the columns in view. `undefined` for a column that leads the table. */
|
|
521
545
|
letter: string | undefined
|
|
@@ -532,18 +556,24 @@ export type LetterSlotProps<Row> = {
|
|
|
532
556
|
}
|
|
533
557
|
|
|
534
558
|
export type DetailSlotProps<Row> = {
|
|
559
|
+
/** The row object of the data, as the owner passed it. */
|
|
535
560
|
row: Row
|
|
561
|
+
/** The node of the row in the row model: its id, its parent and its children. */
|
|
536
562
|
node: DataRow<Row>
|
|
537
563
|
/** Closes the detail row. */
|
|
538
564
|
toggleExpanded: (event?: Event) => void
|
|
539
565
|
}
|
|
540
566
|
|
|
541
567
|
export type GroupSlotProps<Row> = {
|
|
568
|
+
/** The group: its id, the column and the value that make it, and its rows. */
|
|
542
569
|
group: GroupRow<Row>
|
|
570
|
+
/** The column that makes the group. */
|
|
543
571
|
column: ColumnDef<Row> | undefined
|
|
544
572
|
/** The value of the group as text, with the format of its column. */
|
|
545
573
|
text: string
|
|
574
|
+
/** Whether the group is open. */
|
|
546
575
|
expanded: boolean
|
|
576
|
+
/** The groups above this one, from 0. */
|
|
547
577
|
level: number
|
|
548
578
|
/** Column totals of the rows in the group. */
|
|
549
579
|
totals: Record<string, unknown>
|
|
@@ -559,11 +589,14 @@ export type GroupSlotProps<Row> = {
|
|
|
559
589
|
* total of one of these columns has no cell of its own.
|
|
560
590
|
*/
|
|
561
591
|
covered: readonly ColumnDef<Row>[]
|
|
592
|
+
/** Opens or closes the group, for a button in the cell. */
|
|
562
593
|
toggleExpanded: (event?: Event) => void
|
|
563
594
|
}
|
|
564
595
|
|
|
565
596
|
export type GroupTotalSlotProps<Row> = {
|
|
597
|
+
/** The group of the row. */
|
|
566
598
|
group: GroupRow<Row>
|
|
599
|
+
/** The column of the cell. */
|
|
567
600
|
column: ColumnDef<Row>
|
|
568
601
|
/** The total of the column over the rows of the group. `undefined` for a column without an `aggregate`. */
|
|
569
602
|
value: unknown
|
|
@@ -573,14 +606,20 @@ export type GroupTotalSlotProps<Row> = {
|
|
|
573
606
|
totals: Record<string, unknown>
|
|
574
607
|
/** The function of the total: one of the built-in names, `custom` for a function of the column, or `undefined` without a total. */
|
|
575
608
|
aggregate: AggregateName | 'custom' | undefined
|
|
609
|
+
/** Whether the group is open. */
|
|
576
610
|
expanded: boolean
|
|
611
|
+
/** The groups above this one, from 0. */
|
|
577
612
|
level: number
|
|
613
|
+
/** The groups from the outermost one down to this group. */
|
|
578
614
|
path: readonly GroupPathEntry<Row>[]
|
|
579
615
|
}
|
|
580
616
|
|
|
581
617
|
export type FootSlotProps<Row> = {
|
|
618
|
+
/** The column of the cell. */
|
|
582
619
|
column: ColumnDef<Row>
|
|
620
|
+
/** The total of the column, or `undefined` for a column without an `aggregate`. */
|
|
583
621
|
value: unknown
|
|
622
|
+
/** The total as text, with the format of the column, or an empty text. */
|
|
584
623
|
text: string
|
|
585
624
|
/** The totals of every column that has one, by column id. */
|
|
586
625
|
totals: Record<string, unknown>
|
|
@@ -612,12 +651,17 @@ export type TableSlots<Row> = {
|
|
|
612
651
|
*/
|
|
613
652
|
[name: `edit-${string}`]: (props: EditorSlotProps<Row>) => VNodeChild
|
|
614
653
|
} & {
|
|
654
|
+
/** The editor of a cell, in place of the text field of the table. The control must take focus itself. */
|
|
615
655
|
editor?: (props: EditorSlotProps<Row>) => VNodeChild
|
|
656
|
+
/** One header cell, for every column without a `header-{column id}` slot. */
|
|
616
657
|
header?: (props: HeaderSlotProps<Row>) => VNodeChild
|
|
658
|
+
/** One body cell, for every column without a `col-{column id}` slot. */
|
|
617
659
|
cell?: (props: CellSlotProps<Row>) => VNodeChild
|
|
660
|
+
/** One total in the footer, for every column without a `foot-{column id}` slot. */
|
|
618
661
|
foot?: (props: FootSlotProps<Row>) => VNodeChild
|
|
619
662
|
/** The label cell of a group row. */
|
|
620
663
|
group?: (props: GroupSlotProps<Row>) => VNodeChild
|
|
664
|
+
/** The cell of a group row under one column, for every column without a `group-total-{column id}` slot. */
|
|
621
665
|
'group-total'?: (props: GroupTotalSlotProps<Row>) => VNodeChild
|
|
622
666
|
/** The cell with the number of a row, in a column with `rowHeader`. */
|
|
623
667
|
'row-header'?: (props: RowHeaderSlotProps<Row>) => VNodeChild
|