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,121 @@
1
+ # History
2
+
3
+ Let a person take a change back with Control+Z and put it on again with Control+Y.
4
+
5
+ Use it in any table that a person edits. It needs no code in the owner beyond `applyEdits`.
6
+
7
+ ```vue title="undo.vue"
8
+ <script setup lang="ts">
9
+ import { Button } from '@ui-sdk/vue/button'
10
+ import {
11
+ applyEdits,
12
+ createTableController,
13
+ Table,
14
+ useTableView,
15
+ type CellEdit,
16
+ type ColumnDef,
17
+ type TableEditDetails,
18
+ } from 'ui-sdk-table-vue'
19
+ import { computed, shallowRef } from 'vue'
20
+
21
+ type Room = { id: string; room: string; seats: number }
22
+
23
+ const columns: ColumnDef<Room>[] = [
24
+ { id: 'room', header: 'Room', editable: false },
25
+ { id: 'seats', header: 'Seats', format: 'integer' },
26
+ ]
27
+
28
+ const rows = shallowRef<Room[]>([
29
+ { id: 'r1', room: 'Oak', seats: 8 },
30
+ { id: 'r2', room: 'Pine', seats: 12 },
31
+ { id: 'r3', room: 'Birch', seats: 4 },
32
+ ])
33
+ const last = shallowRef('Nothing yet.')
34
+
35
+ const controller = createTableController()
36
+ const view = useTableView(controller)
37
+ // The steps are no state of the view, so they are read again when the view changes.
38
+ const steps = computed(() => {
39
+ if (!view.value) return ''
40
+ const { entries, position } = controller.getHistory()
41
+ return `Step ${position} of ${entries.length}`
42
+ })
43
+
44
+ // An undo comes as an edit with the reason `undo`: `applyEdits` needs no other code for it.
45
+ function onCellEdit(edits: readonly CellEdit<Room>[], details: TableEditDetails) {
46
+ rows.value = applyEdits(rows.value, edits)
47
+ last.value = `${details.reason}: ${edits.map((edit) => `${edit.row.room} ${edit.value}`).join(', ')}`
48
+ }
49
+
50
+ function addSeat() {
51
+ for (const row of rows.value) controller.editCell(row.id, 'seats', row.seats + 1)
52
+ }
53
+ </script>
54
+
55
+ <template>
56
+ <div>
57
+ <Button @click="addSeat">One seat more in each room</Button>
58
+ <Button :disabled="!view?.canUndo" @click="controller.undo()">Undo</Button>
59
+ <Button :disabled="!view?.canRedo" @click="controller.redo()">Redo</Button>
60
+ </div>
61
+ <Table
62
+ :rows="rows"
63
+ :columns="columns"
64
+ :controller="controller"
65
+ editable
66
+ history
67
+ aria-label="Meeting rooms"
68
+ @cell-edit="onCellEdit"
69
+ />
70
+ <p role="status">{{ steps }}. Last report: {{ last }}</p>
71
+ </template>
72
+ ```
73
+
74
+ Press One seat more in each room, then Undo three times: each room goes back, and the line says that each report came with the reason undo. Redo puts a seat back.
75
+
76
+ ## Turn it on
77
+
78
+ `history` on the table, or `sheet`. `:history="{ limit: 100, maxCells: 100000 }"` are the defaults.
79
+
80
+ ## How an undo reaches the owner
81
+
82
+ - An undo is a report through `@cell-edit` with the reason `undo` (a redo: `redo`), with the old values as `value`. An owner that puts edits into its rows with `applyEdits` needs no code for undo.
83
+ - `details.cancel()` refuses an undo as it refuses an edit, and the step stays. The table says so.
84
+ - An undo runs no `parse` and no schema. It puts back what the data held.
85
+ - A cell whose row or column left the table is skipped and counted in the announcement. A step with no cell left is dropped. Rows need stable ids.
86
+ - An undo of a row that the sort moved finds the row. An undo of a row far away in a row window scrolls to it.
87
+
88
+ ## What a step is
89
+
90
+ - One report that no listener refused: one edit, one paste, one cut, one clear, one fill, one `editCell`, one change of formats.
91
+ - Typing in an open editor is no step. There, Control+Z is the text field's.
92
+ - Sort, filter, column moves and selection are not in the history.
93
+ - A step with more cells than `maxCells` empties the history, and the table says so.
94
+ - While a check of a slow server runs, a key does nothing and `undo()` throws. The step is there after the answer.
95
+
96
+ ## Another document
97
+
98
+ Call `controller.clearHistory()` when the rows become another document. With `manual-page`, another page, sort or filter empties the history.
99
+
100
+ ## Read the steps
101
+
102
+ `controller.getHistory()` returns `{ entries, position }`. Each entry has `id`, `reason`, `source`, `cells` (how many cells got a new value), `formats` and `formulas` (whether the step changed them). The view has `canUndo` and `canRedo` for the buttons.
103
+
104
+ ## Keys
105
+
106
+ | Key | On a cell, with `history` |
107
+ | --- | --- |
108
+ | Control or Command with Z | Undo |
109
+ | Control or Command with Y, or with Shift+Z | Redo |
110
+
111
+ The keys act on a cell only. In the editor and in a control inside a cell, Control+Z is the field's.
112
+
113
+ See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
114
+
115
+ ## Names
116
+
117
+ - **Options:** `history` (`true` or `{ limit, maxCells }`).
118
+ - **Controller:** `undo`, `redo`, `clearHistory`, `getHistory`. `undo` and `redo` throw with the reason: no history, nothing to undo, a refused report, a check that runs.
119
+ - **View:** `canUndo`, `canRedo`.
120
+ - **Messages:** `undone`, `redone`, `undoRefused`, `nothingToUndo`, `nothingToRedo`, `historyBusy`, `historyTooLarge`.
121
+ - **Types:** `HistoryEntry`, `TableStepReason`.
package/docs/llms.txt CHANGED
@@ -269,3 +269,30 @@ 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.
288
+
289
+ ### Data sheet
290
+
291
+ - [The sheet options](./sheet-options.md): Turn a table into a data sheet: cells that a person types into, ranges, undo and a fill handle.
292
+ - [Range, copy and paste](./range-copy-and-paste.md): Let a person select a block of cells, copy it, paste into it and read its sum.
293
+ - [Fill](./fill.md): Let a person drag the corner of a range to fill more cells, with a series where the values have one step.
294
+ - [History](./history.md): Let a person take a change back with Control+Z and put it on again with Control+Y.
295
+ - [Formats](./formats.md): Let a person make cells bold, give them a colour, or show a number as a percentage, and save that with the document.
296
+ - [Row numbers and letters](./row-numbers-and-letters.md): Give a sheet a column of row numbers and a row of column letters, where a person selects whole rows and columns.
297
+ - [Formulas](./sheet-formulas.md): Compute values with formulas as in a spreadsheet: a computed column, or a formula in one cell.
298
+ - [An Excel file with formulas](./excel-formulas.md): Download a sheet as an Excel file whose cells keep their formulas, where Excel computes them the same way.
@@ -0,0 +1,203 @@
1
+ # Pages and server mode
2
+
3
+ Show the rows a page at a time, and take the rows, the pages, the sort and the filters from a server.
4
+
5
+ ## Pages
6
+
7
+ A `page` state of `{ page, pageSize }` shows one page of the rows. Without it, the table shows every row. The page counts from 1.
8
+
9
+ ```vue title="pages.vue"
10
+ <script setup lang="ts">
11
+ import {
12
+ Pagination,
13
+ PaginationEllipsis,
14
+ PaginationItem,
15
+ PaginationLink,
16
+ PaginationList,
17
+ PaginationNext,
18
+ PaginationPrevious,
19
+ } from '@ui-sdk/vue/pagination'
20
+ import {
21
+ createTableController,
22
+ Table,
23
+ useTableView,
24
+ type ColumnDef,
25
+ type PageState,
26
+ } from 'ui-sdk-table-vue'
27
+ import { shallowRef } from 'vue'
28
+
29
+ type Invoice = { id: string; number: string; client: string; amount: number }
30
+
31
+ const CLIENTS = ['Northway', 'Sola', 'Arc', 'Brightline', 'Kestrel']
32
+ const invoices: Invoice[] = Array.from({ length: 23 }, (_, index) => ({
33
+ id: `i${index + 1}`,
34
+ number: `INV-${String(1001 + index)}`,
35
+ client: CLIENTS[index % CLIENTS.length] ?? '',
36
+ amount: 400 + ((index * 137) % 900),
37
+ }))
38
+
39
+ const columns: ColumnDef<Invoice>[] = [
40
+ { id: 'number', header: 'Invoice' },
41
+ { id: 'client', header: 'Client', sortable: true },
42
+ { id: 'amount', header: 'Amount', sortable: true, format: 'integer' },
43
+ ]
44
+
45
+ const controller = createTableController()
46
+ const view = useTableView(controller)
47
+ const page = shallowRef<PageState | undefined>({ page: 1, pageSize: 5 })
48
+ </script>
49
+
50
+ <template>
51
+ <Table
52
+ v-model:page="page"
53
+ :rows="invoices"
54
+ :columns="columns"
55
+ :controller="controller"
56
+ aria-label="Invoices"
57
+ />
58
+ <Pagination
59
+ v-if="view"
60
+ aria-label="Pages of the invoices"
61
+ :page="view.page"
62
+ :page-count="view.pageCount"
63
+ @page-change="(next) => controller.setPage(next)"
64
+ >
65
+ <PaginationList v-slot="{ state }">
66
+ <PaginationItem><PaginationPrevious>Previous</PaginationPrevious></PaginationItem>
67
+ <PaginationItem v-for="item in state.items" :key="item">
68
+ <PaginationLink v-if="typeof item === 'number'" :page="item" />
69
+ <PaginationEllipsis v-else />
70
+ </PaginationItem>
71
+ <PaginationItem><PaginationNext>Next</PaginationNext></PaginationItem>
72
+ </PaginationList>
73
+ </Pagination>
74
+ <p v-if="view" role="status">
75
+ Page {{ view.page }} of {{ view.pageCount }}, {{ view.rowCount }} invoices
76
+ </p>
77
+ </template>
78
+ ```
79
+
80
+ Press 3 or Next to go to another page. The line under the pages says where you are: page 3 of 5, 23 invoices.
81
+
82
+ - The controls of the pages read the view: `page`, `pageCount`, `rowCount` and `pageSize`. The `Pagination` component of UI SDK draws them.
83
+ - `setPage`, `nextPage`, `previousPage`, `firstPage` and `lastPage` move. `setPageSize(size)` starts again from the first page, and `setPageSize(null)` shows every row.
84
+ - A new search starts on the first page.
85
+ - What the pages count is `pageUnit` of the view: `rows`, `groups` (each group, with its rows on the page of the group), `parents` (each top-level row, with its child rows on its page) or `mixed`.
86
+
87
+ ## Rows from a server
88
+
89
+ ```vue title="server.vue"
90
+ <script setup lang="ts">
91
+ import { Button } from '@ui-sdk/vue/button'
92
+ import {
93
+ createTableController,
94
+ Table,
95
+ useTableView,
96
+ type ColumnDef,
97
+ type PageState,
98
+ type SortRule,
99
+ } from 'ui-sdk-table-vue'
100
+ import { shallowRef, watch } from 'vue'
101
+
102
+ type Person = { id: string; name: string; score: number }
103
+
104
+ // A server in this file: 40 people, sorted and cut into pages after a short wait.
105
+ const PEOPLE: Person[] = Array.from({ length: 40 }, (_, index) => ({
106
+ id: `p${index + 1}`,
107
+ name: `Person ${index + 1}`,
108
+ score: (index * 37) % 100,
109
+ }))
110
+
111
+ function fetchPeople(sort: readonly SortRule[], page: PageState) {
112
+ const [rule] = sort
113
+ const sorted = rule
114
+ ? PEOPLE.toSorted((a, b) => {
115
+ const order = rule.id === 'score' ? a.score - b.score : a.name.localeCompare(b.name)
116
+ return rule.desc ? -order : order
117
+ })
118
+ : PEOPLE
119
+ const start = (page.page - 1) * page.pageSize
120
+ return new Promise<{ rows: Person[]; total: number }>((resolve) =>
121
+ setTimeout(
122
+ () => resolve({ rows: sorted.slice(start, start + page.pageSize), total: PEOPLE.length }),
123
+ 200,
124
+ ),
125
+ )
126
+ }
127
+
128
+ const columns: ColumnDef<Person>[] = [
129
+ { id: 'name', header: 'Name', sortable: true },
130
+ { id: 'score', header: 'Score', sortable: true, format: 'integer' },
131
+ ]
132
+
133
+ const controller = createTableController()
134
+ const view = useTableView(controller)
135
+ const sort = shallowRef<readonly SortRule[]>([])
136
+ const page = shallowRef<PageState | undefined>({ page: 1, pageSize: 5 })
137
+ const rows = shallowRef<Person[]>([])
138
+ const total = shallowRef<number>()
139
+ const loading = shallowRef(false)
140
+ let request = 0
141
+
142
+ // The state of the table is the request. An answer that a newer request overtook is dropped.
143
+ watch(
144
+ [sort, page],
145
+ async () => {
146
+ if (!page.value) return
147
+ const mine = ++request
148
+ loading.value = true
149
+ const answer = await fetchPeople(sort.value, page.value)
150
+ if (mine !== request) return
151
+ rows.value = answer.rows
152
+ total.value = answer.total
153
+ loading.value = false
154
+ },
155
+ { immediate: true },
156
+ )
157
+ </script>
158
+
159
+ <template>
160
+ <Table
161
+ v-model:sort="sort"
162
+ v-model:page="page"
163
+ :rows="rows"
164
+ :columns="columns"
165
+ :controller="controller"
166
+ :row-count="total"
167
+ :loading="loading"
168
+ manual-sort
169
+ manual-page
170
+ aria-label="People from a server"
171
+ />
172
+ <div v-if="view">
173
+ <Button :disabled="view.page <= 1" @click="controller.previousPage()">Previous</Button>
174
+ <Button :disabled="view.page >= view.pageCount" @click="controller.nextPage()">Next</Button>
175
+ <span role="status">{{ loading ? 'Loading' : `Page ${view.page} of ${view.pageCount}` }}</span>
176
+ </div>
177
+ </template>
178
+ ```
179
+
180
+ Press Score to sort, or Next for the next page. The table asks for nothing itself: the app watches the sort and the page, asks its server, and passes the rows that come back.
181
+
182
+ Three options tell the table that a server did the work:
183
+
184
+ - `manualSort`: the rows come in sort order. The table does not sort them. The `sort` state still changes, so the app knows what to ask for.
185
+ - `manualFilter`: the rows come with the search and the filters applied. The table does not filter them.
186
+ - `manualPage`: the rows are one page. The table shows them all, and the pages come from `rowCount`, the number of rows the server has after its filter.
187
+
188
+ A manual stage keeps the state: the sort, the filter and the page are requests to the owner.
189
+
190
+ - Without `rowCount`, a full page has a next page and a page that is not full is the last. An empty page after the first then sends the table one page back, so keep the rows of the page before, or set `loading`, while a page loads. `lastPage` needs the count.
191
+ - A step to the page that the table is on reports no change, so a listener that loads rows does not load them twice.
192
+ - `loading` tells assistive technology that rows are on their way (`aria-busy`), and the table keeps its rows. Without rows, the `#loading` slot shows.
193
+ - Every other feature works on the rows that the table has: an export, the totals and "select all" are of the page. Give `totals` for the totals of the server, and `facets` for the choices of every row of a filter control.
194
+ - With `manualPage`, a change of the page, the sort or the filter empties the history of a sheet.
195
+
196
+ ## Names
197
+
198
+ - **Options:** `page`, `defaultPage`, `manualSort`, `manualFilter`, `manualPage`, `rowCount`, `loading`, `totals`, `facets`.
199
+ - **Events:** `page-change`.
200
+ - **Controller:** `setPage`, `setPageSize`, `nextPage`, `previousPage`, `firstPage`, `lastPage`.
201
+ - **Types:** `PageState`, `PageUnit`, `ColumnFacetsSource`, `TableTotalsSource`.
202
+
203
+ See the [Rows tiles](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=rows) and the [Server tiles](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=server) of the sink.
@@ -0,0 +1,101 @@
1
+ # Range, copy and paste
2
+
3
+ Let a person select a block of cells, copy it, paste into it and read its sum.
4
+
5
+ Use it with `cell-selection` for any table whose cells a person compares or moves to a spreadsheet, and with `editable` too for a table that takes a paste.
6
+
7
+ ```vue title="range.vue"
8
+ <script setup lang="ts">
9
+ import {
10
+ applyEdits,
11
+ createTableController,
12
+ Table,
13
+ useSelectionSummary,
14
+ type CellEdit,
15
+ type ColumnDef,
16
+ } from 'ui-sdk-table-vue'
17
+ import { shallowRef } from 'vue'
18
+
19
+ type Week = { id: string; name: string; mon: number; tue: number; wed: number }
20
+
21
+ const columns: ColumnDef<Week>[] = [
22
+ { id: 'name', header: 'Name', editable: false },
23
+ { id: 'mon', header: 'Mon', format: 'decimal' },
24
+ { id: 'tue', header: 'Tue', format: 'decimal' },
25
+ { id: 'wed', header: 'Wed', format: 'decimal' },
26
+ ]
27
+
28
+ const rows = shallowRef<Week[]>([
29
+ { id: 'w1', name: 'Ada', mon: 7.5, tue: 8, wed: 6 },
30
+ { id: 'w2', name: 'Ben', mon: 8, tue: 7.5, wed: 8 },
31
+ { id: 'w3', name: 'Cleo', mon: 6, tue: 6, wed: 7.5 },
32
+ ])
33
+
34
+ const controller = createTableController()
35
+ // Counts once the selection rests, so a long drag counts one time.
36
+ const summary = useSelectionSummary(controller)
37
+ </script>
38
+
39
+ <template>
40
+ <Table
41
+ :rows="rows"
42
+ :columns="columns"
43
+ :controller="controller"
44
+ cell-selection
45
+ editable
46
+ aria-label="Hours of the week"
47
+ @cell-edit="(edits: readonly CellEdit<Week>[]) => (rows = applyEdits(rows, edits))"
48
+ />
49
+ <p data-testid="summary">
50
+ <template v-if="summary && summary.numbers > 1">
51
+ {{ summary.numbers }} cells, sum {{ summary.texts.sum }}, average {{ summary.texts.mean }}
52
+ </template>
53
+ <template v-else>Select two cells or more.</template>
54
+ </p>
55
+ </template>
56
+ ```
57
+
58
+ Press 7.50 under Mon and press Shift with the right arrow twice: three cells are selected, and the line under the table gives their sum and average. Copy with Control or Command with C, press a cell of Cleo, and paste.
59
+
60
+ ## Select a range
61
+
62
+ - A drag over cells, or Shift with an arrow, selects a range.
63
+ - The cells of a range have `data-selected` and `data-range-edge` (`top`, `right`, `bottom`, `left`), so a line around a range is one rule for each side.
64
+ - The state is `cellRange`. The view gives `cellSelection` (`{ from, to, rows, columns }`), by id, data rows only.
65
+ - `controller.selectCells(from, to?)` selects from code; `selectAllCells`, `selectCellRows` and `selectCellColumns` select whole rows or columns, and move the active cell into the range.
66
+ - Escape drops the range.
67
+ - A group row holds no values: its cells are never marked as part of a range.
68
+
69
+ ## Copy, cut and paste
70
+
71
+ - Control or Command with C copies the range as text, with tabs between cells and line breaks between rows. A group row gives an empty line. `controller.copyCells()` does the same.
72
+ - A copy holds the plain value of a cell, as the editor shows it, so a paste into the same columns gives the same values.
73
+ - Control or Command with V pastes. A block repeats over a range that it fits a whole number of times: copy two cells, select six, paste, and there are three copies.
74
+ - A paste is all or nothing. Each value passes the `parse` and the schema of its column; one refusal stops the paste before any cell changes.
75
+ - A paste is one report through `@cell-edit` with the reason `paste`, and one step of the history.
76
+ - Control or Command with X cuts: the text of a copy, then a clear (reason `cut`). A cut and a paste in another place move the block.
77
+ - A cell that cannot be edited keeps its value.
78
+
79
+ ## A summary of the selected cells
80
+
81
+ `useSelectionSummary(controller, { debounce = 100 })` is a ref with `{ cells, count, numbers, sum, mean, min, max, texts }` or `null`.
82
+
83
+ - `cells` is how many cells of data rows are selected, `count` how many hold a value, `numbers` how many hold a number. The rest is of the numbers.
84
+ - It counts after the selection rests, so a drag over 50,000 rows counts one time. It follows an edit inside the selection.
85
+ - `texts` are in the format of the column when the selection is inside one column of numbers. Else they are plain numbers of the locale, where the average has two decimals more than the values have (`35,391.67` for whole amounts) and six at most.
86
+ - Show it in a plain element and not in a live region.
87
+ - `controller.getSelectionSummary()` is the same answer on request, kept for the same selection and rows.
88
+
89
+ ## Attributes
90
+
91
+ - `data-cell-selection` on the table, `data-active` on the active cell.
92
+ - `data-selected` and `data-range-edge` on the cells of a range.
93
+
94
+ See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
95
+
96
+ ## Names
97
+
98
+ - **Options:** `cellSelection`, `cellRange`, `defaultCellRange`.
99
+ - **Controller:** `selectCells`, `clearCellSelection`, `selectAllCells`, `selectCellRows`, `selectCellColumns`, `copyCells`, `cutCells`, `getSelectionSummary`.
100
+ - **View:** `activeCell`, `cellSelection`.
101
+ - **Exports:** `useSelectionSummary`, `summarize`, and the types `RangeSummary`, `SelectionSummaryOptions`.
@@ -0,0 +1,110 @@
1
+ # Row numbers and letters
2
+
3
+ Give a sheet a column of row numbers and a row of column letters, where a person selects whole rows and columns.
4
+
5
+ Use them together with `cell-selection`, and always with formulas, so a person sees the addresses that a formula names.
6
+
7
+ ```vue title="letters.vue"
8
+ <script setup lang="ts">
9
+ import {
10
+ createTableController,
11
+ rowNumberColumn,
12
+ Table,
13
+ useTableView,
14
+ type ColumnDef,
15
+ } from 'ui-sdk-table-vue'
16
+ import { computed } from 'vue'
17
+
18
+ type City = { id: string; city: string; country: string; people: number }
19
+
20
+ const cities: City[] = [
21
+ { id: 'c1', city: 'Porto', country: 'Portugal', people: 232000 },
22
+ { id: 'c2', city: 'Ghent', country: 'Belgium', people: 265000 },
23
+ { id: 'c3', city: 'Tartu', country: 'Estonia', people: 97000 },
24
+ ]
25
+
26
+ const columns: ColumnDef<City>[] = [
27
+ // A column of row numbers: it stays first, and no range, copy or export holds it.
28
+ rowNumberColumn<City>(),
29
+ { id: 'city', header: 'City' },
30
+ { id: 'country', header: 'Country' },
31
+ { id: 'people', header: 'People', format: 'integer' },
32
+ ]
33
+
34
+ const controller = createTableController()
35
+ const view = useTableView(controller)
36
+ const said = computed(() => {
37
+ const cells = view.value?.cellSelection
38
+ return cells ? `${cells.rows} by ${cells.columns} cells` : 'Nothing selected'
39
+ })
40
+ </script>
41
+
42
+ <template>
43
+ <Table
44
+ :rows="cities"
45
+ :columns="columns"
46
+ :controller="controller"
47
+ cell-selection
48
+ column-letters
49
+ aria-label="Cities"
50
+ />
51
+ <p role="status">{{ said }}</p>
52
+ </template>
53
+ ```
54
+
55
+ Press the letter A: the cells of City are selected and the line says 3 by 1 cells. Press the row number 2, then the row number 3 with Shift: two whole rows. The corner above the numbers selects every cell, without the numbers.
56
+
57
+ ## Row numbers
58
+
59
+ ```ts
60
+ const columns = [rowNumberColumn<Row>(), { id: 'name' }, { id: 'price' }]
61
+ ```
62
+
63
+ - `rowNumberColumn(options?)` is a column with `lead: true` and `rowHeader: true`. It stays first, sticks with the start pins, and is outside every range, copy, paste, fill, format and export.
64
+ - Its cells are `th` elements with the role `rowheader` and `data-row-header`, with the name "Row 3" (message `rowNumber`). A screen reader says the number with each cell of the row.
65
+ - The number is the place of the row among the data rows, counted over the pages. Group rows have none. With formulas, it is the place of the row in `rows`: see [Formulas](./sheet-formulas.md).
66
+ - A press on a number selects the cells of its row, with Shift the rows from the active cell on. A drag over numbers selects those rows.
67
+ - The `#row-header` slot gets `{ row, node, column, number, selectRow }`.
68
+ - Give the cell `position: sticky; inset-inline-start: 0` and an opaque background to keep it in view without a pinned column.
69
+
70
+ ## Column letters
71
+
72
+ `column-letters` adds a row of letters above the header rows: A, B, C, then AA. It is not part of `sheet`; turn it on as you add `rowNumberColumn()`. A press on a header still sorts, moves and resizes.
73
+
74
+ - **Pointer:** a press on a letter selects the cells of its column, with Shift the columns from the active cell to it. A drag over letters selects those columns, and it stays whole columns when the pointer goes down into the rows.
75
+ - **The corner** is the letter cell above a first column that leads. It selects every column with a letter, so a column of row numbers or of checkboxes stays out. The letter cell of another column that leads is empty and selects nothing.
76
+ - **The letter** is the place of the column among the columns in view: a moved column, and the columns after a hidden one, take the letter of their new place. `lettersByColumn(layout)` gives the letters by column id. With formulas a letter stays with its column: see [Formulas](./sheet-formulas.md).
77
+ - **The grid:** the row of letters is grid row 0, so the header rows start at row 1 and `aria-rowcount` is one more. It sticks with `sticky-header`, pinned columns pin their letter, and an export does not hold it.
78
+ - **Slot:** `#letter` gets `{ column, letter, corner, selectColumn }`. `letter` is `undefined` for a column that leads. `selectColumn(event?)` selects what a press selects, and throws for a column that leads and is no corner. Without the slot, the cell shows the letter.
79
+
80
+ ## Keys
81
+
82
+ | Key | On a letter |
83
+ | --- | --- |
84
+ | An arrow | Reaches the letters from the header rows |
85
+ | Space, Control+Space, Shift+Space, Enter | Selects the column of the letter; every column from the corner |
86
+ | Shift with Left or Right | Grows the selection by a column, also from right to left |
87
+ | Control or Command with A | Selects what the corner does |
88
+ | Escape | Drops the range |
89
+ | Delete, a cut, a copy, a fill, the format keys | Act on the selected cells, as from a row number |
90
+ | Tab | Leaves the table |
91
+
92
+ ## Attributes
93
+
94
+ - The row of letters has `data-kind="letters"`. `rowAttrs` gets `{ kind: 'letters' }`.
95
+ - A letter cell is a `th` with the role `columnheader`, `data-kind="letter"`, `data-column`, and `data-selected` when every row of its column is selected. `cellAttrs` gets `{ kind: 'letter', column, letter, corner }`.
96
+ - The corner has `data-corner` and the name "All cells" (message `cornerCell`). The cells of leading columns have `data-lead`.
97
+ - A row number has `data-row-header`.
98
+
99
+ The row of letters needs no style to work. A styled table gives the letters a small centred text, a look for `[data-selected]`, and an opaque background where the row sticks (`tr[data-sticky]`) or a cell is pinned (`[data-pinned]`). Add `position: sticky; inset-inline-start: 0` on `[data-corner]` when the row numbers stick that way.
100
+
101
+ See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
102
+
103
+ ## Names
104
+
105
+ - **Options:** `columnLetters`; column key `rowHeader`.
106
+ - **Controller:** `selectCellRows`, `selectCellColumns`.
107
+ - **Slots:** `#row-header`, `#letter`.
108
+ - **Attributes:** `data-row-header`, `data-corner`, `data-kind="letters"` on a row and `data-kind="letter"` on a cell.
109
+ - **Messages:** `rowNumber`, `cornerCell`.
110
+ - **Exports:** `rowNumberColumn`, `columnLetter`, `lettersByColumn`, and the types `RowHeaderSlotProps`, `LetterSlotProps`.