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
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# Formulas
|
|
2
|
+
|
|
3
|
+
Compute values with formulas as in a spreadsheet: a computed column, or a formula in one cell.
|
|
4
|
+
|
|
5
|
+
Use a column formula for a value that every row has, such as a total of price and quantity. Use a cell formula for a sheet where a person types `=` into a cell. A **column formula** makes a computed column: every row gets the value of the formula of its own row, also a row that comes later, and a group, a sort, a filter and a total read it as any column. A **cell formula** belongs to one cell: the table computes it, reports the result through `@cell-edit` as a plain value in the row, and reports again the cells that follow when a cell they read changes.
|
|
6
|
+
|
|
7
|
+
```vue title="column.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
10
|
+
import { formulaColumn } from 'ui-sdk-table-vue/formulas'
|
|
11
|
+
|
|
12
|
+
type Order = { id: string; product: string; price: number; qty: number }
|
|
13
|
+
|
|
14
|
+
const orders: Order[] = [
|
|
15
|
+
{ id: 'o1', product: 'Desk lamp', price: 39, qty: 4 },
|
|
16
|
+
{ id: 'o2', product: 'Chair', price: 249, qty: 1 },
|
|
17
|
+
{ id: 'o3', product: 'Cable', price: 6, qty: 10 },
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
const base: ColumnDef<Order>[] = [
|
|
21
|
+
{ id: 'product', header: 'Product' },
|
|
22
|
+
{ id: 'price', header: 'Price', format: 'decimal', sortable: true },
|
|
23
|
+
{ id: 'qty', header: 'Quantity', format: 'integer' },
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
// A computed column: each row gets the value of the formula of its own row.
|
|
27
|
+
const columns: ColumnDef<Order>[] = [
|
|
28
|
+
...base,
|
|
29
|
+
formulaColumn(
|
|
30
|
+
{
|
|
31
|
+
id: 'total',
|
|
32
|
+
header: 'Total',
|
|
33
|
+
format: 'decimal',
|
|
34
|
+
aggregate: 'sum',
|
|
35
|
+
sortable: true,
|
|
36
|
+
formula: '=[price]*[qty]',
|
|
37
|
+
},
|
|
38
|
+
base,
|
|
39
|
+
),
|
|
40
|
+
formulaColumn(
|
|
41
|
+
{
|
|
42
|
+
id: 'band',
|
|
43
|
+
header: 'Band',
|
|
44
|
+
formula: '=IFS([price]<10, "small", [price]<100, "medium", TRUE, "large")',
|
|
45
|
+
},
|
|
46
|
+
base,
|
|
47
|
+
),
|
|
48
|
+
]
|
|
49
|
+
</script>
|
|
50
|
+
|
|
51
|
+
<template>
|
|
52
|
+
<Table :rows="orders" :columns="columns" locale="en-US" aria-label="Orders" />
|
|
53
|
+
</template>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Total is the price times the quantity of its row, and Band an IFS of the price. Press Total: the column sorts like any other, and the footer adds it up.
|
|
57
|
+
|
|
58
|
+
## The entry
|
|
59
|
+
|
|
60
|
+
The engine is an entry of its own, so a table without formulas does not carry it:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { createFormulaEngine, formulaColumn, useFormulaBar } from 'ui-sdk-table-vue/formulas'
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`ui-sdk-table-vue/formulas` holds everything of `ui-sdk-table-core/formulas` and `useFormulaBar`. Create one engine for the life of the table: a new engine at each render computes every formula again.
|
|
67
|
+
|
|
68
|
+
## A column formula
|
|
69
|
+
|
|
70
|
+
`formulaColumn(definition, columns, { timeZone? })` needs no engine and no option of the table: it is a column with a `value` function.
|
|
71
|
+
|
|
72
|
+
- It reads the columns of its own row by id (`[price]`) or by header (`[Price]`).
|
|
73
|
+
- It throws with the words that say why for a formula that cannot be read.
|
|
74
|
+
- It keeps the value of each row object, so an owner that changes a row passes a new object for it.
|
|
75
|
+
- Its cells cannot be edited.
|
|
76
|
+
|
|
77
|
+
A column formula that a person sets at run time is state instead: `cell-formulas` with a `columns` layer, and `controller.setColumnFormula(columnId, text | null)`, which throws with the words of the issue.
|
|
78
|
+
|
|
79
|
+
- The column is a plain column of the owner (`{ id: 'custom', header: 'Custom' }`); the formula gives it its values.
|
|
80
|
+
- It is one change of `cellFormulas` and one step of the history, and it reports no value.
|
|
81
|
+
- When the column of the owner can be edited, a cell of it opens with the formula of the column as a person reads it (`=[Quantity]*2`). Enter on a text with `=` sets the formula of the column, as one step that Control+Z takes back. A value is refused with words (issue `columnCell`). `editCell` still refuses a value there.
|
|
82
|
+
- A formula of the owner that cannot be read, or column formulas that read each other in a circle, show an error in every row of the column.
|
|
83
|
+
|
|
84
|
+
## A date group with the `period` format
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const week = formulaColumn(
|
|
88
|
+
{ id: 'week', header: 'Week', groupable: true, sortable: true, formula: '=WEEKOF([created], 2)' },
|
|
89
|
+
base,
|
|
90
|
+
)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
```vue
|
|
94
|
+
<Table
|
|
95
|
+
:rows="orders"
|
|
96
|
+
:columns="[...base, week]"
|
|
97
|
+
:group-by="['week']"
|
|
98
|
+
:sort="[{ id: 'week', desc: false }]"
|
|
99
|
+
aria-label="Orders"
|
|
100
|
+
/>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- `WEEKOF`, `MONTHOF`, `QUARTEROF`, `YEAROF` and `DAYOF` give the first day of the period as a day (`2026-11-16`). Each period is one group, a sort puts the groups in time order, and the date filter, the facets, a fill and an export treat it as a day. `HOUROF` gives the moment at which the hour began.
|
|
104
|
+
- A column formula whose outer function gives a period gets the format `period` when its definition has no `format`: "Nov 16 – 22, 2026", "November 2026", "Q4 2026", "2026".
|
|
105
|
+
- Set it by hand with `format: 'period'` and `formatOptions: { unit: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'weekday', weekdays?, timeZone? }`. `unit: 'weekday'` writes the name of the day for a number of `WEEKDAY` (`weekdays` is the type that gave it).
|
|
106
|
+
- The label of a group is the text of the format.
|
|
107
|
+
- **The zone.** A date function that reads a column reads the moment on the clock of the `timeZone` of that column's `formatOptions`, so a moment that reads 23:30 on the 21st falls on the 21st. Any other date uses the `timeZone` of `formulaColumn` or of `createFormulaEngine`, else local time. Pass a zone when a saved result must be the same for every person.
|
|
108
|
+
- **The week.** `WEEKOF(d, [type])` takes the type of `WEEKNUM` of Excel for the first day: Sunday without it or with 1, Monday with 2 or 11, 12 to 16 Tuesday to Saturday, 17 Sunday, 21 Monday. Another type gives `#NUM!`.
|
|
109
|
+
|
|
110
|
+
## Cell formulas and a formula bar
|
|
111
|
+
|
|
112
|
+
```vue title="cells.vue"
|
|
113
|
+
<script setup lang="ts">
|
|
114
|
+
import {
|
|
115
|
+
applyEdits,
|
|
116
|
+
createTableController,
|
|
117
|
+
rowNumberColumn,
|
|
118
|
+
Table,
|
|
119
|
+
type CellEdit,
|
|
120
|
+
type CellFormulas,
|
|
121
|
+
type ColumnDef,
|
|
122
|
+
} from 'ui-sdk-table-vue'
|
|
123
|
+
import { createFormulaEngine, useFormulaBar } from 'ui-sdk-table-vue/formulas'
|
|
124
|
+
import { shallowRef, useTemplateRef } from 'vue'
|
|
125
|
+
|
|
126
|
+
// A cell that can hold a formula can hold the text of an error, such as `#DIV/0!`.
|
|
127
|
+
type Line = { id: string; item: string; price: number | null; qty: number | null; total?: unknown }
|
|
128
|
+
|
|
129
|
+
const lines = shallowRef<Line[]>([
|
|
130
|
+
{ id: 'l1', item: 'Desk lamp', price: 39, qty: 4, total: 156 },
|
|
131
|
+
{ id: 'l2', item: 'Monitor arm', price: 89, qty: 2, total: 178 },
|
|
132
|
+
{ id: 'l3', item: 'Keyboard', price: 59, qty: 3, total: 177 },
|
|
133
|
+
{ id: 'sum', item: 'Order total', price: null, qty: null, total: 511 },
|
|
134
|
+
])
|
|
135
|
+
|
|
136
|
+
const columns: ColumnDef<Line>[] = [
|
|
137
|
+
rowNumberColumn<Line>(),
|
|
138
|
+
{ id: 'item', header: 'Item', allowFormula: false },
|
|
139
|
+
{ id: 'price', header: 'Price', format: 'decimal' },
|
|
140
|
+
{ id: 'qty', header: 'Qty', format: 'integer' },
|
|
141
|
+
{ id: 'total', header: 'Total', format: 'decimal' },
|
|
142
|
+
]
|
|
143
|
+
|
|
144
|
+
// The stored form holds ids: `[price]` is "this row", `[total@l1]` the total of row l1.
|
|
145
|
+
const formulas = shallowRef<CellFormulas>({
|
|
146
|
+
cells: {
|
|
147
|
+
l1: { total: '=[price]*[qty]' },
|
|
148
|
+
l2: { total: '=[price]*[qty]' },
|
|
149
|
+
l3: { total: '=[price]*[qty]' },
|
|
150
|
+
sum: { total: '=SUM([total@l1]:[total@l3])' },
|
|
151
|
+
},
|
|
152
|
+
})
|
|
153
|
+
|
|
154
|
+
// One engine for the life of the table.
|
|
155
|
+
const engine = createFormulaEngine()
|
|
156
|
+
const controller = createTableController()
|
|
157
|
+
const bar = useFormulaBar(controller)
|
|
158
|
+
const frame = useTemplateRef<HTMLElement>('frame')
|
|
159
|
+
|
|
160
|
+
// After the bar, focus goes back to the active cell.
|
|
161
|
+
const backToCell = () => frame.value?.querySelector<HTMLElement>('[data-active]')?.focus()
|
|
162
|
+
function commit() {
|
|
163
|
+
if (bar.commit()) backToCell()
|
|
164
|
+
}
|
|
165
|
+
function cancel() {
|
|
166
|
+
bar.cancel()
|
|
167
|
+
backToCell()
|
|
168
|
+
}
|
|
169
|
+
</script>
|
|
170
|
+
|
|
171
|
+
<template>
|
|
172
|
+
<form @submit.prevent="commit">
|
|
173
|
+
<output data-testid="address">{{ bar.address.value || '—' }}</output>
|
|
174
|
+
<input
|
|
175
|
+
aria-label="Formula of the active cell"
|
|
176
|
+
:value="bar.text.value"
|
|
177
|
+
:disabled="!bar.ready.value"
|
|
178
|
+
:aria-invalid="!!bar.error.value"
|
|
179
|
+
@input="bar.input(($event.target as HTMLInputElement).value)"
|
|
180
|
+
@keydown.escape.prevent="cancel"
|
|
181
|
+
/>
|
|
182
|
+
<p role="status">{{ bar.error.value }}</p>
|
|
183
|
+
</form>
|
|
184
|
+
<div ref="frame">
|
|
185
|
+
<Table
|
|
186
|
+
v-model:cell-formulas="formulas"
|
|
187
|
+
:formulas="engine"
|
|
188
|
+
:rows="lines"
|
|
189
|
+
:columns="columns"
|
|
190
|
+
:controller="controller"
|
|
191
|
+
locale="en-US"
|
|
192
|
+
sheet
|
|
193
|
+
column-letters
|
|
194
|
+
aria-label="An order with formulas"
|
|
195
|
+
@cell-edit="(edits: readonly CellEdit<Line>[]) => (lines = applyEdits(lines, edits))"
|
|
196
|
+
/>
|
|
197
|
+
</div>
|
|
198
|
+
</template>
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Press the price of the Desk lamp (B1) and type 49, then Enter: its total and the order total change. Press D4 and type =SUMM(D1:D3) in the field above: the bar shows why it refuses.
|
|
202
|
+
|
|
203
|
+
- **Typing.** A text that starts with `=` in the editor of a cell, the formula bar, a paste, a fill or `editCell` is a formula: `=B1*C1`, `=SUM(D1:D4)`, `=$C$1*D2`, `=SUM(D:D)`. A refusal keeps the editor open with the words of the issue. `'=text` is the text `=text`.
|
|
204
|
+
- A column with `allowFormula: false` keeps such a text as its value. A cell that cannot be edited, a computed column and a table with `manual-page` hold no formula. A formula that would read its own cell is refused, with its path ("D2 reads B2, and B2 reads D2").
|
|
205
|
+
- **Addresses** are places in the document, not on the screen. The number of a row is its place in `rows` (children after their parent), and the letter of a column its place among `columns`, without the columns that lead. A sort, a filter, a page, a pin and a move change neither: after a sort the row numbers read 7, 2, 9, and a hidden column leaves a gap in the row of letters (A, C). Without `formulas`, the numbers and the letters are places of the view.
|
|
206
|
+
- **The stored form** holds ids, so it survives a sort and a new row before it: with the columns item, price, qty and total after the row numbers, `=B1*C1` in row 1 is `=[price]*[qty]` ("this row"), another row is `[price@l3]`, a whole column `[price@*]`, and `$` signs stay.
|
|
207
|
+
- **The locale.** In the stored form `.` is the decimal sign and `,` separates arguments, in every locale. A person types and reads the signs of the `locale` of the table: with a decimal comma (`fi-FI`) a number is `1,5` and only `;` separates arguments. Function names are English in every locale. The locale never changes what a formula computes.
|
|
208
|
+
- **One act, one report.** An edit reports its cell and every formula cell that follows, in order, through one `@cell-edit` (`CellEdit.formula` is the formula that was set, or `null` for one that went), then `cellFormulas` changes. A listener that refuses the values refuses all of it; one that refuses the formulas keeps the values. It is one step of the history, and its undo puts the values and the formulas back without computing.
|
|
209
|
+
- **Fill, paste, cut, copy, clear.** A copy puts the values on the clipboard and remembers the formulas. A paste of that same text pastes the formulas, with each reference without `$` moved by the distance the cell moved (past the edge, `#REF!`). A cut moves its formulas once, unmoved. A fill gives the formula of its source to its targets, moved. Delete takes values and formulas. A paste of the formula that a cell holds is no change.
|
|
210
|
+
- **New rows of the owner.** After new `rows` the table checks the formula cells that they change, in a microtask, and reports the differences with the reason `recalculate`, which is no step. A row that a formula names and that is gone turns it into `#REF!`. An owner that does not take a result gets it once, not in a loop. At the mount nothing is computed: `controller.recalculate()` checks every formula cell, for a check after a load. With `manual-page` there is no check.
|
|
211
|
+
- **Errors** are texts in the row: `#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#NUM!`, `#N/A`, `#CYCLE!` (`FORMULA_ERRORS`, `isFormulaError`). A formula that reads an error passes it on, a sum skips it, a range filter leaves it out, and the text of the cell is the code in every format. Type a column that can hold a formula so that it can hold such a text.
|
|
212
|
+
- **Rendering.** A new formula renders its cell and the cells that read it, when the table holds the formulas (`default-cell-formulas`). `v-model:cell-formulas` renders the table at each change, as every prop of the owner does.
|
|
213
|
+
|
|
214
|
+
`useFormulaBar(controller)` gives:
|
|
215
|
+
|
|
216
|
+
- `address` (`D7`) and `ready` (a cell is active);
|
|
217
|
+
- `text`: the draft, else the formula as a person reads it, else the value as the field of the cell shows it;
|
|
218
|
+
- `error`: why the last commit was refused, in the words for a person;
|
|
219
|
+
- `dirty`, `input(text)`, `cancel()`, and `commit()`, which saves through `editCell` (a text with `=` is a formula and any other text a value) and returns whether it saved.
|
|
220
|
+
|
|
221
|
+
A draft stays with the cell where it started, also when the active cell moves. After a commit or a cancel, give focus back to the active cell (`[data-active]`).
|
|
222
|
+
|
|
223
|
+
## Functions
|
|
224
|
+
|
|
225
|
+
`controller.getFormulaFunctions()` and `FORMULA_FUNCTIONS` list each with its arguments and one line of help.
|
|
226
|
+
|
|
227
|
+
| Group | Functions |
|
|
228
|
+
| --- | --- |
|
|
229
|
+
| Operators | `+ - * / ^`, a leading `-`, `%` after a number, `&` (joins texts), `= <> < <= > >=` |
|
|
230
|
+
| Numbers | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `FLOOR`, `CEILING`, `ABS`, `INT`, `MOD` |
|
|
231
|
+
| Conditions | `IF`, `IFS`, `SWITCH`, `AND`, `OR`, `NOT`, `IFERROR`, `ISBLANK`, `ISNUMBER`, `ISTEXT`, `ISERROR` |
|
|
232
|
+
| Texts | `CONCAT`, `LEN`, `LEFT`, `RIGHT`, `MID`, `UPPER`, `LOWER`, `TRIM` |
|
|
233
|
+
| Periods of a date | `DAYOF`, `WEEKOF(d, [type])`, `MONTHOF`, `QUARTEROF`, `YEAROF`, `HOUROF` |
|
|
234
|
+
| Parts of a date | `YEAR`, `QUARTER`, `MONTH`, `DAY`, `HOUR`, `MINUTE`, `WEEKDAY(d, [type])`, `ISOWEEKNUM`, `ISOYEAR` |
|
|
235
|
+
| Date math | `DATE(year, month, day)`, `DAYS(end, start)`, `DATEADD(date, count, unit)` |
|
|
236
|
+
|
|
237
|
+
A function whose name Excel has behaves as in Excel, with its arguments and edges: `MONTH` gives 1 to 12, `WEEKDAY` counts from Sunday by default and takes the types of Excel, `IF`, `IFS`, `SWITCH`, `AND`, `OR` and `IFERROR` read only the arguments they need. The differences:
|
|
238
|
+
|
|
239
|
+
- `DAYOF`, `WEEKOF`, `MONTHOF`, `QUARTEROF`, `YEAROF`, `HOUROF`, `QUARTER`, `ISOYEAR` and `DATEADD` are not in Excel. `DATEADD` takes the units `year`, `quarter`, `month`, `week`, `day`, `hour` and `minute`; a month at its end stays at the end of a shorter month.
|
|
240
|
+
- A day is a text `YYYY-MM-DD` and a moment a `Date`, not a serial number: `DATE(2026, 11, 21)` gives `2026-11-21`, and `DAYS` and the parts read both kinds. A date before 1900 gives `#NUM!`, and a year under 1900 gets 1900 added, as in Excel.
|
|
241
|
+
- The date functions read the clock of a zone (above); Excel has no zone.
|
|
242
|
+
- `#CYCLE!` is not in Excel: a circle that comes with the `cell-formulas` of the owner. Excel stores such a formula and warns; here an entry that makes a circle is refused.
|
|
243
|
+
- No other sheets, names, arrays, lookups, `SUMIF`, `TODAY()` or `NOW()`.
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
## What a styled table needs
|
|
247
|
+
|
|
248
|
+
- A formula bar: the address, a text field bound to `useFormulaBar`, the words of an error in a plain element with `role="status"`.
|
|
249
|
+
- A look for `[data-formula]` (a small mark in a corner), for `[data-formula-error]` (a colour of the alert kind; the `aria-description` as a tooltip if you want one) and for `[data-formula-column]` in a header.
|
|
250
|
+
- A field or a menu item for the formula of a column (`setColumnFormula`, and the `error` of `getColumnFormula`), and a list of functions from `getFormulaFunctions()`.
|
|
251
|
+
- A choice "group by day, week, month, quarter, year" for a date column: it sets a column formula (`=WEEKOF([created], 2)`) and `groupBy`.
|
|
252
|
+
- The row numbers (`rowNumberColumn()`) and `column-letters`, so a person sees the addresses that a formula names.
|
|
253
|
+
|
|
254
|
+
## Attributes
|
|
255
|
+
|
|
256
|
+
- `data-formulas` on the table.
|
|
257
|
+
- `data-formula` on a cell with a formula of its own.
|
|
258
|
+
- `data-formula-error` (`div0`, `value`, `ref`, `name`, `num`, `na`, `cycle`) with the words of the error as `aria-description`.
|
|
259
|
+
- `data-formula-column` on the header and the cells of a computed column.
|
|
260
|
+
|
|
261
|
+
See the [Formula tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=formula).
|
|
262
|
+
|
|
263
|
+
## Names
|
|
264
|
+
|
|
265
|
+
- **Options:** `formulas` (the engine), `cell-formulas` and `default-cell-formulas` (`v-model:cell-formulas`), column key `allowFormula`. `createFormulaEngine({ timeZone?, maxReads? })`: `maxReads` (5,000,000 by default) refuses one change that would read more cells, such as a running sum by ranges over 50,000 rows.
|
|
266
|
+
- **Value:** `CellFormulas` is `{ columns?: { [columnId]: formula }, cells?: { [rowId]: { [columnId]: formula } } }`, in the stored form: plain data that an app saves with its document. `setFormulas`, `revertFormulas`, `pruneFormulas` and `formulaAt` of the formulas entry are the pure functions behind it.
|
|
267
|
+
- **Events:** `cell-formulas-change` (`details.cancel()` refuses), `update:cell-formulas`; `cell-edit` with `CellEdit.formula` and the reason `recalculate` for a check.
|
|
268
|
+
- **Controller and agent actions:** `getCellFormula`, `setCellFormula`, `getColumnFormula`, `setColumnFormula`, `getAddress`, `cellAt`, `recalculate`, `getFormulaSummary`, `evaluateFormula`, `getFormulaFunctions`. Each throws "This table has no formulas: pass `formulas`." without an engine. `getFormulaSummary(limit?)` gives each text of a column once with its count, so an agent reads 50,000 cells as one line.
|
|
269
|
+
- **View:** `formulas` (the option is on), `cellFormulas`, `formula` (`FormulaView` of the active cell: `rowId`, `columnId`, `address`, `formula`, `text`, `value`, `error`, `ofColumn`).
|
|
270
|
+
- **Slot props:** `formula` in `#cell` and `#col-{id}` (`{ text, error?: { code, message } }`), in `#editor` and `#edit-{id}` (the formula as a person reads it; a save of a text with `=` sets a formula), and in `#header` (the formula of a computed column).
|
|
271
|
+
- **Attributes:** `data-formulas` on the table; `data-formula` on a cell with a formula of its own; `data-formula-error` (`div0`, `value`, `ref`, `name`, `num`, `na`, `cycle`) with the words of the error as `aria-description`; `data-formula-column` on the header and the cells of a computed column.
|
|
272
|
+
- **Messages:** `formulaIssue(issue)`, `formulaError(code)`, `recalculated({ cells })`. Without them, the English words of the engine (`describeFormulaIssue`).
|
|
273
|
+
- **Words of a refusal.** `editCell`, `setCellFormula` and `setColumnFormula` throw an `Error` whose `message` is for a developer or an agent: it names the column, the row and the text (`Column "total" refuses "=SUMM(B2)" for row "l2": No function …`). Its `cause` is a text with the words for a person, the words that the editor of the cell shows. A control beside the table shows the `cause`; `useFormulaBar().error` does that already.
|
|
274
|
+
|
|
275
|
+
```ts
|
|
276
|
+
try {
|
|
277
|
+
controller.setColumnFormula('band', text)
|
|
278
|
+
} catch (error) {
|
|
279
|
+
shown.value = error instanceof Error && typeof error.cause === 'string' ? error.cause : String(error)
|
|
280
|
+
}
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
- **Own words for one kind of issue.** `messages.formulaIssue` gets the issue as data (`code` and its fields) and decides for every kind; `describeFormulaIssue` of the formulas entry gives the words of the engine for the rest. They reach the editor, the formula bar and the `cause` of a refusal alike:
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
const messages = {
|
|
287
|
+
formulaIssue: (issue: FormulaIssue) =>
|
|
288
|
+
issue.code === 'unknownFunction' ? `No function ${issue.name}.` : describeFormulaIssue(issue),
|
|
289
|
+
}
|
|
290
|
+
```
|
|
291
|
+
- **Exports of the formulas entry:** `createFormulaEngine`, `formulaColumn`, `compileRowFormula`, `parseFormula`, `printFormula`, `formulaShows`, `formulaSigns`, `describeFormulaIssue`, `FORMULA_FUNCTIONS`, `setFormulas`, `revertFormulas`, `pruneFormulas`, `formulaAt`, `excelFormulas`, `EXCEL_FUNCTIONS`, `useFormulaBar`. Of the export entry: the `formula` option of `toXlsx` and the type `XlsxFormulas`.
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# The sheet options
|
|
2
|
+
|
|
3
|
+
Turn a table into a data sheet: cells that a person types into, ranges, undo and a fill handle.
|
|
4
|
+
|
|
5
|
+
Use it for data that people change cell by cell, as in a spreadsheet: prices, stock, a budget. A data sheet is the same `Table` with more options. There is no second component.
|
|
6
|
+
|
|
7
|
+
```vue title="sheet.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
|
+
} from 'ui-sdk-table-vue'
|
|
18
|
+
import { shallowRef } from 'vue'
|
|
19
|
+
|
|
20
|
+
type Item = { id: string; name: string; price: number; stock: number }
|
|
21
|
+
|
|
22
|
+
const columns: ColumnDef<Item>[] = [
|
|
23
|
+
{ id: 'name', header: 'Item' },
|
|
24
|
+
{ id: 'price', header: 'Price', format: 'decimal' },
|
|
25
|
+
{ id: 'stock', header: 'Stock', format: 'integer' },
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
const rows = shallowRef<Item[]>([
|
|
29
|
+
{ id: 'i1', name: 'Notebook', price: 4.5, stock: 120 },
|
|
30
|
+
{ id: 'i2', name: 'Pencil', price: 0.8, stock: 640 },
|
|
31
|
+
{ id: 'i3', name: 'Eraser', price: 1.2, stock: 310 },
|
|
32
|
+
{ id: 'i4', name: 'Ruler', price: 2.3, stock: 95 },
|
|
33
|
+
])
|
|
34
|
+
|
|
35
|
+
const controller = createTableController()
|
|
36
|
+
const view = useTableView(controller)
|
|
37
|
+
</script>
|
|
38
|
+
|
|
39
|
+
<template>
|
|
40
|
+
<div>
|
|
41
|
+
<Button :disabled="!view?.canUndo" @click="controller.undo()">Undo</Button>
|
|
42
|
+
<Button :disabled="!view?.canRedo" @click="controller.redo()">Redo</Button>
|
|
43
|
+
</div>
|
|
44
|
+
<!-- `sheet` turns on editing, ranges of cells, undo and redo, and the fill handle. -->
|
|
45
|
+
<Table
|
|
46
|
+
:rows="rows"
|
|
47
|
+
:columns="columns"
|
|
48
|
+
:controller="controller"
|
|
49
|
+
sheet
|
|
50
|
+
aria-label="Stock of the shop"
|
|
51
|
+
@cell-edit="(edits: readonly CellEdit<Item>[]) => (rows = applyEdits(rows, edits))"
|
|
52
|
+
/>
|
|
53
|
+
</template>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Press a price and type 5: the editor opens with that character. Press Enter to save and move down. Select two cells with Shift and an arrow, press Delete, then Undo.
|
|
57
|
+
|
|
58
|
+
## Turn it on
|
|
59
|
+
|
|
60
|
+
- `sheet` is a preset: `editable`, `cell-selection`, `history` and `fill-handle` are on unless one is set to false.
|
|
61
|
+
- Each of them also works alone, so `<Table editable history>` is a table with undo.
|
|
62
|
+
- Without these options, a table behaves as before. The keys of a sheet do nothing in a plain table.
|
|
63
|
+
- The table has `data-sheet` with the option.
|
|
64
|
+
- The owner applies every change. Pass `@cell-edit` and put the edits into your rows, for example with `applyEdits`. See [Editing](./cell-editing.md).
|
|
65
|
+
|
|
66
|
+
## Keys
|
|
67
|
+
|
|
68
|
+
| Key | With `sheet` |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| A character on a cell | Opens the editor with that character (`mode` is `replace`) |
|
|
71
|
+
| Enter in the editor | Saves and moves down, with Shift up. Inside a range it walks the range column by column |
|
|
72
|
+
| Tab in the editor | Saves and moves to the next cell. Inside a range it walks the range row by row |
|
|
73
|
+
| An arrow in the editor | After a character: saves and moves one cell (reason `list-navigation`). After F2, Enter or a double press: moves the caret. F2 in the editor turns the first into the second |
|
|
74
|
+
| Tab on a cell | Leaves the table. With a range of more than one cell it walks the range, and Escape drops the range |
|
|
75
|
+
| Delete, Backspace on a cell | Empties the selected cells (reason `clear`) |
|
|
76
|
+
| Control or Command with X | Cuts: the text of a copy, then a clear (reason `cut`) |
|
|
77
|
+
| Control or Command with V | Pastes. A block repeats over a range that it fits a whole number of times |
|
|
78
|
+
| Control or Command with Z; with Y or Shift+Z | Undo and redo, with `history` |
|
|
79
|
+
| Control or Command with D; with R | Fills the selected cells down from their first row; forward from their first column, with `fill-handle`. With one line selected the keys stay the browser's |
|
|
80
|
+
| Control or Command with B; with I | Makes the selected cells bold; italic. On, unless every selected cell has it, and then off |
|
|
81
|
+
|
|
82
|
+
Delete and Backspace inside an open editor remove a character. A key in a control inside a cell belongs to that control.
|
|
83
|
+
|
|
84
|
+
## Empty a cell
|
|
85
|
+
|
|
86
|
+
`emptyValue(row, column)` is what a clear writes: the `parse` of the column for an empty text, else `null` for a number or a date, `false` for a boolean and an empty text for the rest. It goes through the schema of the column, and one refusal stops the whole clear. The table then says why and changes nothing.
|
|
87
|
+
|
|
88
|
+
## The function of a total at run time
|
|
89
|
+
|
|
90
|
+
A person can change the function of a total, for example from a sum to an average.
|
|
91
|
+
|
|
92
|
+
```vue title="totals.vue"
|
|
93
|
+
<script setup lang="ts">
|
|
94
|
+
import { Button } from '@ui-sdk/vue/button'
|
|
95
|
+
import { Table, type AggregateName, type ColumnAggregates, type ColumnDef } from 'ui-sdk-table-vue'
|
|
96
|
+
import { shallowRef } from 'vue'
|
|
97
|
+
|
|
98
|
+
type Trip = { id: string; city: string; nights: number; cost: number }
|
|
99
|
+
|
|
100
|
+
const trips: Trip[] = [
|
|
101
|
+
{ id: 't1', city: 'Lisbon', nights: 3, cost: 420 },
|
|
102
|
+
{ id: 't2', city: 'Vienna', nights: 2, cost: 380 },
|
|
103
|
+
{ id: 't3', city: 'Krakow', nights: 4, cost: 310 },
|
|
104
|
+
]
|
|
105
|
+
|
|
106
|
+
const columns: ColumnDef<Trip>[] = [
|
|
107
|
+
{ id: 'city', header: 'City' },
|
|
108
|
+
{ id: 'nights', header: 'Nights', format: 'integer', aggregate: 'sum' },
|
|
109
|
+
{ id: 'cost', header: 'Cost', format: 'integer', aggregate: 'sum' },
|
|
110
|
+
]
|
|
111
|
+
|
|
112
|
+
// The app holds the function of each total. A column without an entry keeps its `aggregate`.
|
|
113
|
+
const aggregates = shallowRef<ColumnAggregates>({})
|
|
114
|
+
const choices: AggregateName[] = ['sum', 'mean', 'max']
|
|
115
|
+
</script>
|
|
116
|
+
|
|
117
|
+
<template>
|
|
118
|
+
<Table
|
|
119
|
+
v-model:column-aggregates="aggregates"
|
|
120
|
+
:rows="trips"
|
|
121
|
+
:columns="columns"
|
|
122
|
+
aria-label="Trips of the year"
|
|
123
|
+
>
|
|
124
|
+
<template #foot="{ column, text, aggregate, setAggregate }">
|
|
125
|
+
<template v-if="aggregate">
|
|
126
|
+
{{ text }}
|
|
127
|
+
<Button
|
|
128
|
+
v-for="name in choices"
|
|
129
|
+
:key="name"
|
|
130
|
+
:aria-label="`${name} of ${column.header}`"
|
|
131
|
+
:aria-pressed="aggregate === name"
|
|
132
|
+
@click="setAggregate(name)"
|
|
133
|
+
>
|
|
134
|
+
{{ name }}
|
|
135
|
+
</Button>
|
|
136
|
+
</template>
|
|
137
|
+
</template>
|
|
138
|
+
</Table>
|
|
139
|
+
</template>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Press mean under Nights: the footer shows the average. Press sum to go back.
|
|
143
|
+
|
|
144
|
+
- `columnAggregates` is a record by column id: `'sum' | 'mean' | 'min' | 'max' | 'count' | 'uniqueCount' | 'first'`, or `null` for no total. Use `v-model:column-aggregates` or `default-column-aggregates`.
|
|
145
|
+
- An entry wins over the `aggregate` of the column definition. A column without an entry keeps its definition.
|
|
146
|
+
- The footer, the group rows, `getTotals` and an export follow. The footer row goes away with its last total.
|
|
147
|
+
- `setAggregate(name | null | undefined, event?)` of the `#foot` slot and `controller.setColumnAggregate(columnId, name)` change it. `undefined` gives the definition back.
|
|
148
|
+
- `#foot` and `#group-total` get `aggregate`: a name, `custom` for a function of the column, or `undefined`.
|
|
149
|
+
- A footer cell has `data-aggregate`. A cell whose function a person chose has the name "Average: 12.40" (messages `aggregateLabel`, `totalLabel`).
|
|
150
|
+
- A change of the function is no step of the history.
|
|
151
|
+
|
|
152
|
+
## Your own editor
|
|
153
|
+
|
|
154
|
+
`#editor` and `#edit-{column id}` get `mode` (`replace` or `edit`) and `typed`, the character that opened the editor. `save(value, event)` with an Enter key moves down. `#header` gets `selectColumn(event?)`, for a control that selects the cells of the column, with Shift from the active cell on.
|
|
155
|
+
|
|
156
|
+
## A number keyboard on a phone
|
|
157
|
+
|
|
158
|
+
A column with `numberKeyboard: true` gives the field of its editor `inputmode="decimal"`. The `#editor` and `#edit-{id}` slots get the same answer as `inputMode` (`'decimal'` or `undefined`).
|
|
159
|
+
|
|
160
|
+
The table holds the attribute back where the number keyboard has no key that a person needs:
|
|
161
|
+
|
|
162
|
+
- in a cell that can hold a formula: it takes a text with `=`. `allowFormula: false` gives the keyboard back;
|
|
163
|
+
- in a cell whose format is set and is no number format (`integer`, `decimal`, `number`, `currency`, `percentage`), such as a cell that a person gave a date format.
|
|
164
|
+
|
|
165
|
+
The field stays a text field and never `type="number"`: such a field refuses a decimal comma in some locales, a percent sign and a pasted text.
|
|
166
|
+
|
|
167
|
+
## The view
|
|
168
|
+
|
|
169
|
+
`getView()` and `useTableView` hold `canUndo`, `canRedo`, `activeCell` (`{ rowId, columnId }` or `null`), `cellSelection` (`{ from, to, rows, columns }`, by id, data rows only) and `columnAggregates`.
|
|
170
|
+
|
|
171
|
+
See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
|
|
172
|
+
|
|
173
|
+
## Names
|
|
174
|
+
|
|
175
|
+
- **Options:** `sheet`, `editable`, `cellSelection`, `history`, `fillHandle`, `columnAggregates`, `defaultColumnAggregates`; column key `numberKeyboard`.
|
|
176
|
+
- **Events:** `column-aggregates-change`, `update:column-aggregates`.
|
|
177
|
+
- **Controller:** `clearCells`, `cutCells` (returns the text), `selectAllCells`, `selectCellRows(from, to?)`, `selectCellColumns(from, to?)`, `setColumnAggregate`.
|
|
178
|
+
- **View:** `canUndo`, `canRedo`, `activeCell`, `cellSelection`, `columnAggregates`.
|
|
179
|
+
- **Slot props:** `selectColumn` in `#header`; `mode`, `typed` and `inputMode` in `#editor` and `#edit-{id}`; `aggregate` and `setAggregate` in `#foot`, `aggregate` in `#group-total`.
|
|
180
|
+
- **Attributes:** `data-sheet`, `data-aggregate`.
|
|
181
|
+
- **Messages:** `cellsCleared`, `cellsCut`, `clearRefused`, `clearNowhere`, `aggregateLabel`, `totalLabel`.
|
|
182
|
+
- **Exports:** `emptyValue`, `aggregateName`, and the types `ColumnAggregates`, `AggregateName`, `TableStepReason`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ui-sdk-table-vue",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
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.1.2"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@types/jsdom": "^30.0.0",
|