ui-sdk-table-vue 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +0 -343
- package/docs/README.md +11 -0
- package/docs/excel-formulas.md +112 -0
- package/docs/export.md +1 -1
- package/docs/fill.md +110 -0
- package/docs/formats.md +145 -0
- package/docs/history.md +121 -0
- package/docs/llms.txt +11 -0
- package/docs/range-copy-and-paste.md +101 -0
- package/docs/row-numbers-and-letters.md +110 -0
- package/docs/selection-and-keyboard.md +1 -1
- package/docs/sheet-formulas.md +291 -0
- package/docs/sheet-options.md +182 -0
- package/package.json +2 -2
package/docs/formats.md
ADDED
|
@@ -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`.
|
package/docs/history.md
ADDED
|
@@ -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
|
@@ -285,3 +285,14 @@ The rules of a scoped style reach the elements of the table through `:deep()`, b
|
|
|
285
285
|
- [Editing](./cell-editing.md): Let a person change the value of a cell, check it first, and put it into your rows.
|
|
286
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
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,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`.
|
|
@@ -107,7 +107,7 @@ The grid gives focus back to a cell only when a change of the table took it away
|
|
|
107
107
|
|
|
108
108
|
With `cellSelection`, a person selects a range of cells: Shift with an arrow, or a drag. Control or Command with C copies the range as text, with tabs between cells and line breaks between rows. With `editable` too, Control or Command with V pastes into it. See [Editing](./cell-editing.md).
|
|
109
109
|
|
|
110
|
-
The cells of a range have `data-selected` and `data-range-edge`. The state is `cellRange`.
|
|
110
|
+
The cells of a range have `data-selected` and `data-range-edge`. The state is `cellRange`. [Range, copy and paste](./range-copy-and-paste.md) covers the rest.
|
|
111
111
|
|
|
112
112
|
## Names
|
|
113
113
|
|