ui-sdk-table-vue 0.1.1 → 0.1.3
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/agents.md +1 -1
- package/docs/excel-formulas.md +112 -0
- package/docs/export.md +1 -1
- package/docs/fill.md +110 -0
- package/docs/first-table.md +1 -1
- package/docs/formats.md +155 -0
- package/docs/history.md +121 -0
- package/docs/llms.txt +12 -1
- package/docs/range-copy-and-paste.md +101 -0
- package/docs/row-numbers-and-letters.md +110 -0
- package/docs/rows.md +42 -19
- package/docs/selection-and-keyboard.md +4 -2
- package/docs/sheet-formulas.md +292 -0
- package/docs/sheet-options.md +182 -0
- package/docs/sort-filter-and-search.md +13 -12
- package/docs/styling.md +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -21,346 +21,3 @@ const columns: ColumnDef<Person>[] = [
|
|
|
21
21
|
## Docs
|
|
22
22
|
|
|
23
23
|
The docs are at https://falldownthesystem.github.io/ui-sdk-table/. The same pages ship in this package as Markdown in `docs`: start with `docs/llms.txt`, and `docs/README.md` lists every page.
|
|
24
|
-
|
|
25
|
-
## A data sheet
|
|
26
|
-
|
|
27
|
-
```vue
|
|
28
|
-
<script setup lang="ts">
|
|
29
|
-
import { applyEdits, createTableController, Table, useTableView } from 'ui-sdk-table-vue'
|
|
30
|
-
|
|
31
|
-
const controller = createTableController()
|
|
32
|
-
const view = useTableView(controller)
|
|
33
|
-
</script>
|
|
34
|
-
|
|
35
|
-
<template>
|
|
36
|
-
<button :disabled="!view?.canUndo" @click="controller.undo()">Undo</button>
|
|
37
|
-
<button :disabled="!view?.canRedo" @click="controller.redo()">Redo</button>
|
|
38
|
-
<Table
|
|
39
|
-
:rows="rows"
|
|
40
|
-
:columns="columns"
|
|
41
|
-
:controller="controller"
|
|
42
|
-
sheet
|
|
43
|
-
@cell-edit="(edits) => (rows = applyEdits(rows, edits))"
|
|
44
|
-
/>
|
|
45
|
-
</template>
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
`sheet` is the table with the rules of a data sheet, and a preset: `editable`, `cell-selection`, `history` and `fill-handle` are on unless one is set to false. Each of them also works alone, so `<Table editable history>` is a table with undo. Without them, a table behaves as before.
|
|
49
|
-
|
|
50
|
-
| Key | With `sheet` |
|
|
51
|
-
| --- | --- |
|
|
52
|
-
| A character on a cell | Opens the editor with that character (`mode` is `replace`) |
|
|
53
|
-
| Enter in the editor | Saves and moves down, with Shift up. Inside a range it walks the range column by column |
|
|
54
|
-
| Tab in the editor | Saves and moves to the next cell. Inside a range it walks the range row by row |
|
|
55
|
-
| 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 |
|
|
56
|
-
| Tab on a cell | Leaves the table. With a range of more than one cell it walks the range, and Escape drops the range |
|
|
57
|
-
| Delete, Backspace on a cell | Empties the selected cells (reason `clear`) |
|
|
58
|
-
| Control or Command with X | Cuts: the text of a copy, then a clear (reason `cut`) |
|
|
59
|
-
| Control or Command with V | Pastes. A block repeats over a range that it fits a whole number of times |
|
|
60
|
-
| Control or Command with Z; with Y or Shift+Z | Undo and redo, with `history` |
|
|
61
|
-
| 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 |
|
|
62
|
-
| Control or Command with B; with I | Makes the selected cells bold; italic. On, unless every selected cell has it, and then off |
|
|
63
|
-
|
|
64
|
-
- **The owner applies every change.** 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. `details.cancel()` refuses an undo as it refuses an edit, and the step stays.
|
|
65
|
-
- **`applyEdits(rows, edits, getRowId?)`** finds the row of an edit by its object, and by its id when the object was replaced already, as at the second of two reports in one turn. Pass the `getRowId` of the table when it has one.
|
|
66
|
-
- **A step** is one report that no listener refused: one edit, one paste, one cut, one clear, one fill, one `editCell`, and one change of formats. Typing in an open editor is no step; there, Control+Z is the text field's. Sort, filter, column moves and selection are not in the history.
|
|
67
|
-
- **An undo runs no `parse` and no schema.** It puts back what the data held. 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.
|
|
68
|
-
- **Limits:** `:history="{ limit: 100, maxCells: 100000 }"` are the defaults. A step with more cells than `maxCells` empties the history, and the table says so.
|
|
69
|
-
- **Other data:** call `controller.clearHistory()` when the rows become another document. With `manual-page`, another page, sort or filter empties the history.
|
|
70
|
-
- **Empty values:** `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, and one refusal stops the whole clear.
|
|
71
|
-
- **Controller:** `undo()`, `redo()`, `clearHistory()`, `getHistory()`, `clearCells()`, `cutCells()` (returns the text), `selectAllCells()`, `selectCellRows(from, to?)`, `selectCellColumns(from, to?)`. `undo` and `redo` throw with the reason: no history, nothing to undo, a refused report, a check that runs.
|
|
72
|
-
- **View:** `canUndo`, `canRedo`, `activeCell` (`{ rowId, columnId }` or `null`) and `cellSelection` (`{ from, to, rows, columns }`, by id, data rows only).
|
|
73
|
-
- **Slots:** `#header` gets `selectColumn(event?)`, for a control that selects the cells of the column (with Shift, from the active cell on). `#editor` and `#edit-{id}` get `mode` (`replace` or `edit`) and `typed`, the character that opened the editor; `save(value, event)` with an Enter key moves down.
|
|
74
|
-
- **A number keyboard on a phone.** A column with `numberKeyboard: true` holds numbers: the field of its editor gets `inputmode="decimal"`, so a phone shows its number keyboard. The `#editor` and `#edit-{id}` slots get the same answer as `inputMode` (`'decimal'` or `undefined`), for a field that an app draws itself. The table holds the attribute back where the number keyboard has no key that a person needs: in a cell that can hold a formula (it takes a text with `=`, or it is a cell of a computed column whose field shows the formula of the column; `allowFormula: false` gives the keyboard back), and 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. 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.
|
|
75
|
-
- **Attributes:** `data-sheet` on the table.
|
|
76
|
-
- **Messages:** `cellsCleared`, `cellsCut`, `clearRefused`, `clearNowhere`, `undone`, `redone`, `undoRefused`, `nothingToUndo`, `nothingToRedo`, `historyBusy`, `historyTooLarge`.
|
|
77
|
-
|
|
78
|
-
### Row numbers
|
|
79
|
-
|
|
80
|
-
```ts
|
|
81
|
-
const columns = [rowNumberColumn<Row>(), { id: 'name' }, { id: 'price' }]
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
`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. Its cells are `th` elements with the role `rowheader` and `data-row-header`, with the name "Row 3" (message `rowNumber`), so a screen reader says the number with each cell of the row. The number is the place of the row among the data rows, counted over the pages; group rows have none. A press on a number selects the cells of its row, with Shift the rows from the active cell on, and a drag over numbers selects those rows. The `#row-header` slot gets `{ row, node, column, number, selectRow }`. Give the cell `position: sticky; inset-inline-start: 0` and an opaque background to keep it in view without a pinned column.
|
|
85
|
-
|
|
86
|
-
### Column letters
|
|
87
|
-
|
|
88
|
-
```vue
|
|
89
|
-
<Table :columns="[rowNumberColumn<Row>(), ...columns]" cell-selection column-letters />
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
`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()`. The letters are where a person selects whole columns, as the row numbers are for rows; a press on a header still sorts, moves and resizes.
|
|
93
|
-
|
|
94
|
-
- **Pointer:** a press on a letter selects the cells of its column, with Shift the columns from the active cell to it, and a drag over letters selects those columns (it stays whole columns when the pointer goes down into the rows). The corner, the letter cell above a first column that leads, 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.
|
|
95
|
-
- **Keys:** the arrows reach the letters from the header rows. Space, Control+Space, Shift+Space and Enter select the column of a letter (every column from the corner); Shift with Left or Right grows the selection by a column, also from right to left; Control+A selects what the corner does; Escape drops the range. Delete, a cut, a copy, a fill and the format keys act on the selected cells, as from a row number. Tab leaves the table.
|
|
96
|
-
- **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; it is the one rule for them.
|
|
97
|
-
- **The grid:** the row of letters is grid row 0, so the header rows start at row 1, `aria-rowcount` is one more, and `cellRange` counts it. It sticks with `sticky-header`, pinned columns pin their letter, and an export does not hold it.
|
|
98
|
-
- **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.
|
|
99
|
-
- **Attributes:** the row has `data-kind="letters"`; 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. The corner has `data-corner` and the name "All cells" (message `cornerCell`); the cells of leading columns have `data-lead`. `rowAttrs` gets `{ kind: 'letters' }` and `cellAttrs` gets `{ kind: 'letter', column, letter, corner }`.
|
|
100
|
-
- **Styling:** the row 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]`), plus `position: sticky; inset-inline-start: 0` on `[data-corner]` when the row numbers stick that way.
|
|
101
|
-
|
|
102
|
-
### Fill
|
|
103
|
-
|
|
104
|
-
The fill handle is the part `[data-slot='table-fill-handle']`, an empty `span` inside the cell at the end corner of the selected cells. Place it with `position: absolute` at `inset-block-end` and `inset-inline-end` of its cell, which needs `position: relative`; the logical sides put it at the left corner from right to left. Give it `touch-action: none`.
|
|
105
|
-
|
|
106
|
-
- **A drag** fills along the rows or along the columns, whichever the pointer went further on. While it runs, the table has `data-filling` and each cell that would be filled has `data-fill-target` and `data-fill-edge` (`top`, `right`, `bottom`, `left`, as `data-range-edge`), so a line around the target is the same CSS as the line around a range. Near an edge of the scroll frame the table scrolls, also with a row window. Escape ends the drag and changes nothing.
|
|
107
|
-
- **What it writes:** a source of one line repeats. A source of two or more lines goes on when it is numbers with one step (also negative, a fraction, upward and backward) or days with one step (`2028-02-22`, `2028-02-29` goes on with `2028-03-07`); everything else repeats in its order. The step of a series is counted without the noise of floats.
|
|
108
|
-
- **All or nothing, one step.** Each value passes the schema of its column. One refusal stops the fill before any cell changes, and the table says which column refused which text. A fill is one report through `cell-edit` with the reason `fill` and one step of the history; its undo puts back exactly the values of before, also for rows that were sorted, filtered or removed since.
|
|
109
|
-
- **`fill-handle="vertical"`** or `"horizontal"` keeps the handle and the keys on one axis. `:fill-handle="false"` with `sheet` takes both away.
|
|
110
|
-
- **Controller:** `fillCells('down' | 'up' | 'forward' | 'back', source = 1)` fills the selected cells from their first `source` lines. It works without the `fill-handle` option, which is about the handle and the keys. It throws for one selected line, for a wrong direction (with the valid ones), and with the reason of a refusal.
|
|
111
|
-
- A cell that cannot be edited keeps its value and its place in the line. A fill from pinned rows into the rows of the list is refused: they are no neighbours in the data.
|
|
112
|
-
|
|
113
|
-
### A summary of the selected cells
|
|
114
|
-
|
|
115
|
-
```vue
|
|
116
|
-
<script setup lang="ts">
|
|
117
|
-
const summary = useSelectionSummary(controller)
|
|
118
|
-
</script>
|
|
119
|
-
|
|
120
|
-
<template>
|
|
121
|
-
<p v-if="summary && summary.numbers > 1">Sum {{ summary.texts.sum }}, average {{ summary.texts.mean }}</p>
|
|
122
|
-
</template>
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
`useSelectionSummary(controller, { debounce = 100 })` is a ref with `{ cells, count, numbers, sum, mean, min, max, texts }` or `null`: how many cells of data rows are selected, how many hold a value, how many hold a number, and what the numbers add up to. It counts after the selection rests, so a drag over 50,000 rows counts one time, and it follows an edit inside the selection. `texts` are in the format of the column when the selection is inside one column of numbers, else 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. Show it in a plain element and not in a live region. `controller.getSelectionSummary()` is the same answer on request, kept for the same selection and rows.
|
|
126
|
-
|
|
127
|
-
### The function of a total at run time
|
|
128
|
-
|
|
129
|
-
```vue
|
|
130
|
-
<Table v-model:column-aggregates="aggregates" :rows="rows" :columns="columns">
|
|
131
|
-
<template #foot="{ column, text, aggregate, setAggregate }">
|
|
132
|
-
<MyPicker :value="aggregate" @change="(name) => setAggregate(name)" />
|
|
133
|
-
{{ text }}
|
|
134
|
-
</template>
|
|
135
|
-
</Table>
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
`columnAggregates` is a record by column id: `'sum' | 'mean' | 'min' | 'max' | 'count' | 'uniqueCount' | 'first'`, or `null` for no total. An entry wins over the `aggregate` of the column definition, and a column without an entry keeps its definition. The footer, the group rows, `getTotals` and an export follow; the footer row goes away with its last total. `setAggregate(name | null | undefined, event?)` of the `#foot` slot and `controller.setColumnAggregate(columnId, name)` change it (`undefined` gives the definition back). `#foot` and `#group-total` get `aggregate` (a name, `custom` for a function of the column, or `undefined`). A footer cell has `data-aggregate`, and a cell whose function a person chose has the name "Average: 12.40" (messages `aggregateLabel`, `totalLabel`). A change of the function is no step of the history.
|
|
139
|
-
|
|
140
|
-
### Formats of cells
|
|
141
|
-
|
|
142
|
-
```vue
|
|
143
|
-
<Table v-model:cell-formats="formats" :format-colors="['red', 'green']" sheet ... />
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
```ts
|
|
147
|
-
controller.formatCells({ bold: true, fill: 'green' }) // the selected cells
|
|
148
|
-
controller.formatCells({ format: 'percentage', decimals: 1 }, { columns: ['share'] })
|
|
149
|
-
controller.formatCells({ fill: null }, { from: { rowId: 'a', columnId: 'price' } })
|
|
150
|
-
controller.clearCellFormats()
|
|
151
|
-
controller.toggleCellFormat('bold') // for a toolbar button
|
|
152
|
-
controller.getCellFormat(rowId, columnId) // for the pressed state
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
- **The value** is `CellFormats`: `{ columns?: { [columnId]: CellFormat }, cells?: { [rowId]: { [columnId]: CellFormat } } }`. 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. A format follows its row through a sort, a filter and a page. It is plain data that an app saves with its document: pass it back as `cell-formats` or `default-cell-formats`.
|
|
156
|
-
- **`CellFormat`:** `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`. A patch with `null` for a key takes that property away. A wrong property, name or colour throws with the valid ones.
|
|
157
|
-
- **Looks are attributes.** 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. A colour is a name of `format-colors` and nothing of CSS: the style of the app gives each name its colours for light and dark, and holds the contrast. Give a fill an opaque background, so a pinned cell with a fill hides what scrolls under it, and decide what a selected cell with a fill looks like. `cellAttrs` of the caller cannot overwrite these attributes.
|
|
158
|
-
- **The text** of a cell with a format is made by the format: 0.342 with `{ format: 'percentage', decimals: 1 }` reads `34.2%`. The footer and the totals of a group follow the column layer. A CSV and an Excel file hold the text of the screen; a copy holds the plain value, as the editor shows it, so a paste into the same columns gives the same values. In an Excel file a cell whose own format decides its text is written as text. The `#cell` and `#col-{id}` slots get `format`, the format that the cell has of its own, and `text`.
|
|
159
|
-
- **The text field shows a percentage as the screen has it.** 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. The `#editor` and `#edit-{id}` slots get the plain value as `text`, and their `save` takes a value. A search and the label of a group read the column definition and do not follow a format of a cell.
|
|
160
|
-
- **Whole columns.** When the selected cells are every row that the table has, `formatCells` formats the columns, so the format holds for rows that come later and the value stays small. Never with `manual-page`, where the table does not have every row. 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.
|
|
161
|
-
- **History.** A change of formats is one step (`getHistory()` entries have `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.
|
|
162
|
-
- **Rows that left.** 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.
|
|
163
|
-
- **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 with a row window either is fast; without a window, prefer `default-cell-formats` and listen to `cell-formats-change`.
|
|
164
|
-
|
|
165
|
-
### New names of the sheet, in one list
|
|
166
|
-
|
|
167
|
-
- **Options:** `column-letters`, `fill-handle`, `column-aggregates` and `default-column-aggregates` (`v-model:column-aggregates`), `cell-formats` and `default-cell-formats` (`v-model:cell-formats`), `format-colors`; column key `rowHeader`.
|
|
168
|
-
- **Events:** `column-aggregates-change`, `cell-formats-change`.
|
|
169
|
-
- **Controller and agent actions:** `fillCells`, `setColumnAggregate`, `formatCells`, `clearCellFormats`, `toggleCellFormat`, `getCellFormat`, `getSelectionSummary`.
|
|
170
|
-
- **View:** `columnAggregates`, `cellFormats`.
|
|
171
|
-
- **Slots:** `#row-header`, `#letter`; `aggregate` and `setAggregate` in `#foot`, `aggregate` in `#group-total`, `format` in `#cell`.
|
|
172
|
-
- **Attributes:** `data-row-header`, `data-corner`, `data-kind="letters"` on a row and `data-kind="letter"` on a cell, `data-filling`, `data-fill-target`, `data-fill-edge`, `data-aggregate`, `data-align`, `data-bold`, `data-italic`, `data-color`, `data-fill`; the part `table-fill-handle`.
|
|
173
|
-
- **Messages:** `rowNumber`, `cornerCell`, `cellsFilled`, `fillRefused`, `fillNowhere`, `fillOverPinned`, `cellsFormatted`, `aggregateLabel`, `totalLabel`.
|
|
174
|
-
- **Exports:** `rowNumberColumn`, `columnLetter`, `lettersByColumn`, `useSelectionSummary`, `summarize`, `fillValues`, `fillLine`, `setFormats`, `revertFormats`, `pruneFormats`, `resolveFormat`, `aggregateName`, `CELL_FORMAT_NAMES`, `CELL_ALIGNS`, `CELL_DATE_STYLES`, `TableFillHandle`, and the types `CellFormat`, `CellFormats`, `CellFormatPatch`, `CellFormatName`, `FormatPlace`, `FormatTarget`, `ColumnAggregates`, `AggregateName`, `RangeSummary`, `FillWay`, `FillDirection`, `FillDraft`, `RowHeaderSlotProps`, `LetterSlotProps`, `TableStepReason`.
|
|
175
|
-
|
|
176
|
-
## Formulas
|
|
177
|
-
|
|
178
|
-
Formulas as in a spreadsheet, in two kinds. 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.
|
|
179
|
-
|
|
180
|
-
The engine is an entry of its own, so a table without formulas does not carry it:
|
|
181
|
-
|
|
182
|
-
```ts
|
|
183
|
-
import { createFormulaEngine, formulaColumn, useFormulaBar } from 'ui-sdk-table-vue/formulas'
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
`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.
|
|
187
|
-
|
|
188
|
-
### A column formula
|
|
189
|
-
|
|
190
|
-
```vue
|
|
191
|
-
<script setup lang="ts">
|
|
192
|
-
import { Table, type ColumnDef } from 'ui-sdk-table-vue'
|
|
193
|
-
import { formulaColumn } from 'ui-sdk-table-vue/formulas'
|
|
194
|
-
|
|
195
|
-
type Order = { id: string; product: string; price: number; qty: number }
|
|
196
|
-
const base: ColumnDef<Order>[] = [
|
|
197
|
-
{ id: 'product', header: 'Product' },
|
|
198
|
-
{ id: 'price', header: 'Price', format: 'currency' },
|
|
199
|
-
{ id: 'qty', header: 'Quantity', format: 'integer' },
|
|
200
|
-
]
|
|
201
|
-
const columns = [
|
|
202
|
-
...base,
|
|
203
|
-
formulaColumn({ id: 'total', header: 'Total', format: 'currency', aggregate: 'sum', formula: '=[price]*[qty]' }, base),
|
|
204
|
-
formulaColumn(
|
|
205
|
-
{ id: 'band', header: 'Band', groupable: true, formula: '=IFS([price]<10, "small", [price]<100, "medium", TRUE, "large")' },
|
|
206
|
-
base,
|
|
207
|
-
),
|
|
208
|
-
]
|
|
209
|
-
</script>
|
|
210
|
-
|
|
211
|
-
<template>
|
|
212
|
-
<Table :rows="orders" :columns="columns" label="Orders" />
|
|
213
|
-
</template>
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
`formulaColumn(definition, columns, { timeZone? })` needs no engine and no option of the table: it is a column with a `value` function. It reads the columns of its own row by id (`[price]`) or by header (`[Price]`), throws with the words that say why for a formula that cannot be read, and keeps the value of each row object, so an owner that changes a row passes a new object for it. Its cells cannot be edited.
|
|
217
|
-
|
|
218
|
-
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. The column is a plain column of the owner (`{ id: 'custom', header: 'Custom' }`); the formula gives it its values. It is one change of `cellFormulas` and one step of the history, and it reports no value. When the column of the owner can be edited (`editable`, or a table with `sheet` or `editable`), 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, and a value is refused with words (issue `columnCell`). `editCell` still refuses a value there. 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.
|
|
219
|
-
|
|
220
|
-
### A date group with the `period` format
|
|
221
|
-
|
|
222
|
-
```ts
|
|
223
|
-
const week = formulaColumn({ id: 'week', header: 'Week', groupable: true, sortable: true, formula: '=WEEKOF([created], 2)' }, base)
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
```vue
|
|
227
|
-
<Table :rows="orders" :columns="[...base, week]" :group-by="['week']" :sort="[{ id: 'week', desc: false }]" label="Orders" />
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
`WEEKOF`, `MONTHOF`, `QUARTEROF`, `YEAROF` and `DAYOF` give the first day of the period as a day (`2026-11-16`), so 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. 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". 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). The label of a group is the text of the format.
|
|
231
|
-
|
|
232
|
-
- **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.
|
|
233
|
-
- **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!`. The locale never changes what a formula computes, only what a person types and reads.
|
|
234
|
-
|
|
235
|
-
### Cell formulas
|
|
236
|
-
|
|
237
|
-
```vue
|
|
238
|
-
<script setup lang="ts">
|
|
239
|
-
import { applyEdits, createTableController, rowNumberColumn, Table, type CellFormulas } from 'ui-sdk-table-vue'
|
|
240
|
-
import { createFormulaEngine } from 'ui-sdk-table-vue/formulas'
|
|
241
|
-
import { shallowRef } from 'vue'
|
|
242
|
-
|
|
243
|
-
const engine = createFormulaEngine()
|
|
244
|
-
const formulas = shallowRef<CellFormulas>({ cells: { l1: { total: '=[price]*[qty]' } } })
|
|
245
|
-
const columns = [rowNumberColumn<Line>(), { id: 'item' }, { id: 'price' }, { id: 'qty' }, { id: 'total' }]
|
|
246
|
-
</script>
|
|
247
|
-
|
|
248
|
-
<template>
|
|
249
|
-
<Table
|
|
250
|
-
v-model:cell-formulas="formulas"
|
|
251
|
-
:formulas="engine"
|
|
252
|
-
:rows="lines"
|
|
253
|
-
:columns="columns"
|
|
254
|
-
sheet
|
|
255
|
-
column-letters
|
|
256
|
-
label="Lines"
|
|
257
|
-
@cell-edit="(edits) => (lines = applyEdits(lines, edits))"
|
|
258
|
-
/>
|
|
259
|
-
</template>
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
- **Typing.** A text that starts with `=` in the editor of a cell, the formula bar, a paste, a fill or `editCell` is a formula: `=C1*D1`, `=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`. 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").
|
|
263
|
-
- **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, as before.
|
|
264
|
-
- **The stored form** holds ids, so it survives a sort and a new row before it: `=C1*D1` in row 1 is `=[price]*[qty]` ("this row"), another row is `[price@l3]`, a whole column `[price@*]`, and `$` signs stay. `.` 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.
|
|
265
|
-
- **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.
|
|
266
|
-
- **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.
|
|
267
|
-
- **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.
|
|
268
|
-
- **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.
|
|
269
|
-
- **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.
|
|
270
|
-
|
|
271
|
-
### A formula bar
|
|
272
|
-
|
|
273
|
-
```vue
|
|
274
|
-
<script setup lang="ts">
|
|
275
|
-
const controller = createTableController()
|
|
276
|
-
const bar = useFormulaBar(controller)
|
|
277
|
-
</script>
|
|
278
|
-
|
|
279
|
-
<template>
|
|
280
|
-
<form @submit.prevent="bar.commit()">
|
|
281
|
-
<output>{{ bar.address.value }}</output>
|
|
282
|
-
<input
|
|
283
|
-
:value="bar.text.value"
|
|
284
|
-
:disabled="!bar.ready.value"
|
|
285
|
-
:aria-invalid="!!bar.error.value"
|
|
286
|
-
@input="bar.input(($event.target as HTMLInputElement).value)"
|
|
287
|
-
@keydown.escape.prevent="bar.cancel()"
|
|
288
|
-
/>
|
|
289
|
-
<output role="status">{{ bar.error.value }}</output>
|
|
290
|
-
</form>
|
|
291
|
-
<Table :controller="controller" :formulas="engine" sheet ... />
|
|
292
|
-
</template>
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
`useFormulaBar(controller)` gives `address` (`D7`), `text` (the draft, else the formula as a person reads it, else the value as the field of the cell shows it), `error` (why the last commit was refused, in the words for a person), `dirty`, `ready` (a cell is active), `input(text)`, `commit()` (saves through `editCell`, so a text with `=` is a formula and any other text a value; returns whether it saved) and `cancel()`. 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]`).
|
|
296
|
-
|
|
297
|
-
### An Excel file with formulas
|
|
298
|
-
|
|
299
|
-
```ts
|
|
300
|
-
const { downloadXlsx } = await import('ui-sdk-table-vue/export')
|
|
301
|
-
await downloadXlsx(controller.exportData(), 'lines', { formula: excelFormulas() })
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
`excelFormulas()` of the formulas entry is the `formula` option of `toXlsx` and `downloadXlsx`. A cell with a formula, of its own or of its column, gets the formula of the file (`<f>`) with its result beside it, when all of the formula means the same in Excel: every cell that it reads is in the file and holds there the value that it holds in the table (no day, no cell written as its text), a range is one column whose rows are in the file in the order of the document and next to each other, and each function is in `EXCEL_FUNCTIONS`. Else the cell holds its result, as without the option. The addresses are places in the file, so a sorted or filtered export keeps the formulas that read their own row. An error of a formula is an error cell of the file with the option; `#CYCLE!` stays a text. `ExportCell.formula` and `ExportRow.id` and `ExportData.document` carry the formulas to a writer of your own. A CSV holds the results.
|
|
305
|
-
|
|
306
|
-
With or without the option, a column with the format `period` whose unit is `day`, `month` or `year` is a date cell with a pattern when a spreadsheet shows the pattern as the screen does (`Nov 21, 2026`, `November 2026` and `2026` in `en-US`), else its text; a week, a quarter, an hour and a day of the week are texts.
|
|
307
|
-
|
|
308
|
-
### Functions
|
|
309
|
-
|
|
310
|
-
`controller.getFormulaFunctions()` and `FORMULA_FUNCTIONS` list each with its arguments and one line of help.
|
|
311
|
-
|
|
312
|
-
| Group | Functions |
|
|
313
|
-
| --- | --- |
|
|
314
|
-
| Operators | `+ - * / ^`, a leading `-`, `%` after a number, `&` (joins texts), `= <> < <= > >=` |
|
|
315
|
-
| Numbers | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `FLOOR`, `CEILING`, `ABS`, `INT`, `MOD` |
|
|
316
|
-
| Conditions | `IF`, `IFS`, `SWITCH`, `AND`, `OR`, `NOT`, `IFERROR`, `ISBLANK`, `ISNUMBER`, `ISTEXT`, `ISERROR` |
|
|
317
|
-
| Texts | `CONCAT`, `LEN`, `LEFT`, `RIGHT`, `MID`, `UPPER`, `LOWER`, `TRIM` |
|
|
318
|
-
| Periods of a date | `DAYOF`, `WEEKOF(d, [type])`, `MONTHOF`, `QUARTEROF`, `YEAROF`, `HOUROF` |
|
|
319
|
-
| Parts of a date | `YEAR`, `QUARTER`, `MONTH`, `DAY`, `HOUR`, `MINUTE`, `WEEKDAY(d, [type])`, `ISOWEEKNUM`, `ISOYEAR` |
|
|
320
|
-
| Date math | `DATE(year, month, day)`, `DAYS(end, start)`, `DATEADD(date, count, unit)` |
|
|
321
|
-
|
|
322
|
-
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:
|
|
323
|
-
|
|
324
|
-
- `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.
|
|
325
|
-
- 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.
|
|
326
|
-
- The date functions read the clock of a zone (above); Excel has no zone.
|
|
327
|
-
- `#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.
|
|
328
|
-
- No other sheets, names, arrays, lookups, `SUMIF`, `TODAY()` or `NOW()`.
|
|
329
|
-
|
|
330
|
-
### Names
|
|
331
|
-
|
|
332
|
-
- **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.
|
|
333
|
-
- **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.
|
|
334
|
-
- **Events:** `cell-formulas-change` (`details.cancel()` refuses), `update:cell-formulas`; `cell-edit` with `CellEdit.formula` and the reason `recalculate` for a check.
|
|
335
|
-
- **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.
|
|
336
|
-
- **View:** `formulas` (the option is on), `cellFormulas`, `formula` (`FormulaView` of the active cell: `rowId`, `columnId`, `address`, `formula`, `text`, `value`, `error`, `ofColumn`).
|
|
337
|
-
- **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).
|
|
338
|
-
- **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.
|
|
339
|
-
- **Messages:** `formulaIssue(issue)`, `formulaError(code)`, `recalculated({ cells })`. Without them, the English words of the engine (`describeFormulaIssue`).
|
|
340
|
-
- **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.
|
|
341
|
-
|
|
342
|
-
```ts
|
|
343
|
-
try {
|
|
344
|
-
controller.setColumnFormula('band', text)
|
|
345
|
-
} catch (error) {
|
|
346
|
-
shown.value = error instanceof Error && typeof error.cause === 'string' ? error.cause : String(error)
|
|
347
|
-
}
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
- **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:
|
|
351
|
-
|
|
352
|
-
```ts
|
|
353
|
-
const messages = {
|
|
354
|
-
formulaIssue: (issue: FormulaIssue) =>
|
|
355
|
-
issue.code === 'unknownFunction' ? `No function ${issue.name}.` : describeFormulaIssue(issue),
|
|
356
|
-
}
|
|
357
|
-
```
|
|
358
|
-
- **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`.
|
|
359
|
-
|
|
360
|
-
### What a styled table needs
|
|
361
|
-
|
|
362
|
-
- A formula bar: the address, a text field bound to `useFormulaBar`, the words of an error in a plain element with `role="status"`.
|
|
363
|
-
- 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.
|
|
364
|
-
- 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()`.
|
|
365
|
-
- A choice "group by day, week, month, quarter, year" for a date column: it sets a column formula (`=WEEKOF([created], 2)`) and `groupBy`.
|
|
366
|
-
- The row numbers (`rowNumberColumn()`) and `column-letters`, so a person sees the addresses that a formula names.
|
package/docs/README.md
CHANGED
|
@@ -26,6 +26,17 @@ Start with [llms.txt](./llms.txt): what the library is and the conventions every
|
|
|
26
26
|
- [Export](./export.md): Write the rows of the table to a CSV or an Excel file, with the text that the screen shows.
|
|
27
27
|
- [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.
|
|
28
28
|
|
|
29
|
+
## Data sheet
|
|
30
|
+
|
|
31
|
+
- [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.
|
|
32
|
+
- [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.
|
|
33
|
+
- [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.
|
|
34
|
+
- [History](./history.md): Let a person take a change back with Control+Z and put it on again with Control+Y.
|
|
35
|
+
- [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.
|
|
36
|
+
- [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.
|
|
37
|
+
- [Formulas](./sheet-formulas.md): Compute values with formulas as in a spreadsheet: a computed column, or a formula in one cell.
|
|
38
|
+
- [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.
|
|
39
|
+
|
|
29
40
|
## Source and licence
|
|
30
41
|
|
|
31
42
|
The format of these pages, the layout of `llms.txt` and parts of the text of Introduction, Installation and First table follow the docs of UI SDK (`@ui-sdk/vue/docs`, https://ui-sdk.dev), which are licensed under the Apache License 2.0.
|
package/docs/agents.md
CHANGED
|
@@ -27,7 +27,7 @@ const columns: ColumnDef<Ship>[] = [
|
|
|
27
27
|
|
|
28
28
|
// The agent of UI SDK sees every component of the page that has a name, and its actions.
|
|
29
29
|
const agent = createAgent()
|
|
30
|
-
const answer = shallowRef('')
|
|
30
|
+
const answer = shallowRef('No action yet.')
|
|
31
31
|
|
|
32
32
|
async function act(action: string, args: unknown[]) {
|
|
33
33
|
const result = await agent.act({ steps: [{ ref: 'Ships in port', action, args }] })
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# An Excel file with formulas
|
|
2
|
+
|
|
3
|
+
Download a sheet as an Excel file whose cells keep their formulas, where Excel computes them the same way.
|
|
4
|
+
|
|
5
|
+
Use it for a sheet with formulas that a person goes on with in a spreadsheet. Without it, the file holds the results only.
|
|
6
|
+
|
|
7
|
+
```vue title="file.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Button } from '@ui-sdk/vue/button'
|
|
10
|
+
import {
|
|
11
|
+
applyEdits,
|
|
12
|
+
createTableController,
|
|
13
|
+
rowNumberColumn,
|
|
14
|
+
Table,
|
|
15
|
+
type CellEdit,
|
|
16
|
+
type CellFormulas,
|
|
17
|
+
type ColumnDef,
|
|
18
|
+
} from 'ui-sdk-table-vue'
|
|
19
|
+
import { createFormulaEngine, excelFormulas } from 'ui-sdk-table-vue/formulas'
|
|
20
|
+
import { shallowRef } from 'vue'
|
|
21
|
+
|
|
22
|
+
type Month = { id: string; month: string; income: number; costs: number; profit?: unknown }
|
|
23
|
+
|
|
24
|
+
const rows = shallowRef<Month[]>([
|
|
25
|
+
{ id: 'm1', month: 'January', income: 8200, costs: 5100, profit: 3100 },
|
|
26
|
+
{ id: 'm2', month: 'February', income: 7600, costs: 5400, profit: 2200 },
|
|
27
|
+
{ id: 'm3', month: 'March', income: 9100, costs: 5050, profit: 4050 },
|
|
28
|
+
])
|
|
29
|
+
|
|
30
|
+
const columns: ColumnDef<Month>[] = [
|
|
31
|
+
rowNumberColumn<Month>(),
|
|
32
|
+
{ id: 'month', header: 'Month', editable: false },
|
|
33
|
+
{ id: 'income', header: 'Income', format: 'integer' },
|
|
34
|
+
{ id: 'costs', header: 'Costs', format: 'integer' },
|
|
35
|
+
{ id: 'profit', header: 'Profit', format: 'integer' },
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
const formulas = shallowRef<CellFormulas>({
|
|
39
|
+
cells: {
|
|
40
|
+
m1: { profit: '=[income]-[costs]' },
|
|
41
|
+
m2: { profit: '=[income]-[costs]' },
|
|
42
|
+
m3: { profit: '=[income]-[costs]' },
|
|
43
|
+
},
|
|
44
|
+
})
|
|
45
|
+
|
|
46
|
+
const engine = createFormulaEngine()
|
|
47
|
+
const controller = createTableController()
|
|
48
|
+
|
|
49
|
+
async function download() {
|
|
50
|
+
const { downloadXlsx } = await import('ui-sdk-table-vue/export')
|
|
51
|
+
// `excelFormulas()` writes a formula into the file where it means the same in Excel.
|
|
52
|
+
await downloadXlsx(controller.exportData(), 'profit', { formula: excelFormulas() })
|
|
53
|
+
}
|
|
54
|
+
</script>
|
|
55
|
+
|
|
56
|
+
<template>
|
|
57
|
+
<div>
|
|
58
|
+
<Button @click="download">Download Excel</Button>
|
|
59
|
+
</div>
|
|
60
|
+
<Table
|
|
61
|
+
v-model:cell-formulas="formulas"
|
|
62
|
+
:formulas="engine"
|
|
63
|
+
:rows="rows"
|
|
64
|
+
:columns="columns"
|
|
65
|
+
:controller="controller"
|
|
66
|
+
locale="en-US"
|
|
67
|
+
sheet
|
|
68
|
+
column-letters
|
|
69
|
+
aria-label="Profit by month"
|
|
70
|
+
@cell-edit="(edits: readonly CellEdit<Month>[]) => (rows = applyEdits(rows, edits))"
|
|
71
|
+
/>
|
|
72
|
+
</template>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Press Download Excel. In profit.xlsx, each cell under Profit holds the formula of its row, such as B2-C2, with its result beside it.
|
|
76
|
+
|
|
77
|
+
## Turn it on
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
const { downloadXlsx } = await import('ui-sdk-table-vue/export')
|
|
81
|
+
await downloadXlsx(controller.exportData(), 'profit', { formula: excelFormulas() })
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- `excelFormulas()` of the formulas entry is the `formula` option of `toXlsx` and `downloadXlsx`.
|
|
85
|
+
- A cell with a formula, of its own or of its column, gets the formula of the file (`<f>`) with its result beside it, when the formula means the same in Excel (below).
|
|
86
|
+
- The addresses are places in the file. A sorted or filtered export keeps the formulas that read their own row.
|
|
87
|
+
- An error of a formula is an error cell of the file. `#CYCLE!` stays a text.
|
|
88
|
+
- A CSV holds the results.
|
|
89
|
+
- `ExportCell.formula`, `ExportRow.id` and `ExportData.document` carry the formulas to a writer of your own.
|
|
90
|
+
|
|
91
|
+
## Dates of the `period` format
|
|
92
|
+
|
|
93
|
+
With or without the option, a column with the format `period` whose unit is `day`, `month` or `year` is a date cell with a pattern when a spreadsheet shows the pattern as the screen does: `Nov 21, 2026`, `November 2026` and `2026` in `en-US`. Else it is its text. A week, a quarter, an hour and a day of the week are texts.
|
|
94
|
+
|
|
95
|
+
## When a formula goes into the file
|
|
96
|
+
|
|
97
|
+
A cell gets the formula of the file only when the whole formula means the same in Excel:
|
|
98
|
+
|
|
99
|
+
- every cell that it reads is in the file and holds there the value that it holds in the table: no day, no cell written as its text;
|
|
100
|
+
- a range is one column whose rows are in the file in the order of the document and next to each other;
|
|
101
|
+
- each function is in `EXCEL_FUNCTIONS`.
|
|
102
|
+
|
|
103
|
+
Else the cell holds its result, as without the option. A file without the option holds the same bytes as the file of a table without formulas.
|
|
104
|
+
|
|
105
|
+
See the [Formula tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=formula) and the page [Export](./export.md).
|
|
106
|
+
|
|
107
|
+
## Names
|
|
108
|
+
|
|
109
|
+
- **Options of `toXlsx` and `downloadXlsx`:** `formula`, with `excelFormulas()` of the formulas entry.
|
|
110
|
+
- **Exports of the formulas entry:** `excelFormulas`, `EXCEL_FUNCTIONS`.
|
|
111
|
+
- **Exports of the export entry:** the type `XlsxFormulas`.
|
|
112
|
+
- **Fields of the data:** `ExportCell.formula`, `ExportRow.id`, `ExportData.document`.
|
package/docs/export.md
CHANGED
|
@@ -78,7 +78,7 @@ The text of a cell in a file is the text of the screen. An Excel cell is a numbe
|
|
|
78
78
|
## The writers
|
|
79
79
|
|
|
80
80
|
- `toCsv(data, options)` returns the text. Its options: `separator` (a comma), `lineEnd` (`\r\n`), `header` (true), `bom` (true, so Excel reads UTF-8), `escapeFormulas` (true: a text that a spreadsheet would read as a formula gets a `'` before it).
|
|
81
|
-
- `toXlsx(data, options)` returns the bytes of the file. Its options: `sheetName`, `freezeHeader` (true), `compress` (true), and `formula` for a table with formulas: see
|
|
81
|
+
- `toXlsx(data, options)` returns the bytes of the file. Its options: `sheetName`, `freezeHeader` (true), `compress` (true), and `formula` for a table with formulas: see [An Excel file with formulas](./excel-formulas.md).
|
|
82
82
|
- `downloadCsv(data, filename, options)` and `downloadXlsx(data, filename, options)` save a file in the browser.
|
|
83
83
|
|
|
84
84
|
With `manualPage`, the table has one page of a server, so each set of rows is of that page.
|
package/docs/fill.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Fill
|
|
2
|
+
|
|
3
|
+
Let a person drag the corner of a range to fill more cells, with a series where the values have one step.
|
|
4
|
+
|
|
5
|
+
Use it in a sheet where rows repeat a value or go on with a series: weeks, days, numbers.
|
|
6
|
+
|
|
7
|
+
```vue title="fill.vue"
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import { Button } from '@ui-sdk/vue/button'
|
|
10
|
+
import {
|
|
11
|
+
applyEdits,
|
|
12
|
+
createTableController,
|
|
13
|
+
Table,
|
|
14
|
+
type CellEdit,
|
|
15
|
+
type ColumnDef,
|
|
16
|
+
} from 'ui-sdk-table-vue'
|
|
17
|
+
import { shallowRef } from 'vue'
|
|
18
|
+
|
|
19
|
+
type Lesson = { id: string; week: number | null; day: string; room: string }
|
|
20
|
+
|
|
21
|
+
const columns: ColumnDef<Lesson>[] = [
|
|
22
|
+
{ id: 'week', header: 'Week', format: 'integer' },
|
|
23
|
+
{ id: 'day', header: 'Day' },
|
|
24
|
+
{ id: 'room', header: 'Room' },
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
const rows = shallowRef<Lesson[]>([
|
|
28
|
+
{ id: 'l1', week: 1, day: '2027-01-04', room: 'A1' },
|
|
29
|
+
{ id: 'l2', week: 2, day: '2027-01-11', room: 'B2' },
|
|
30
|
+
{ id: 'l3', week: null, day: '', room: '' },
|
|
31
|
+
{ id: 'l4', week: null, day: '', room: '' },
|
|
32
|
+
{ id: 'l5', week: null, day: '', room: '' },
|
|
33
|
+
])
|
|
34
|
+
|
|
35
|
+
const controller = createTableController()
|
|
36
|
+
|
|
37
|
+
// The first two rows are the source: numbers and days with one step go on as a series.
|
|
38
|
+
function fillDown() {
|
|
39
|
+
controller.selectCells({ rowId: 'l1', columnId: 'week' }, { rowId: 'l5', columnId: 'room' })
|
|
40
|
+
void controller.fillCells('down', 2)
|
|
41
|
+
}
|
|
42
|
+
</script>
|
|
43
|
+
|
|
44
|
+
<template>
|
|
45
|
+
<div>
|
|
46
|
+
<Button @click="fillDown">Fill down from two rows</Button>
|
|
47
|
+
</div>
|
|
48
|
+
<Table
|
|
49
|
+
:rows="rows"
|
|
50
|
+
:columns="columns"
|
|
51
|
+
:controller="controller"
|
|
52
|
+
sheet
|
|
53
|
+
aria-label="Lessons of a course"
|
|
54
|
+
@cell-edit="(edits: readonly CellEdit<Lesson>[]) => (rows = applyEdits(rows, edits))"
|
|
55
|
+
/>
|
|
56
|
+
</template>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Press Fill down from two rows: weeks 3, 4 and 5 and the days 2027-01-18, 01-25 and 02-01 follow, and the rooms repeat A1, B2. Or select a cell and drag the small square at its corner down.
|
|
60
|
+
|
|
61
|
+
## The handle
|
|
62
|
+
|
|
63
|
+
The fill handle is the part `[data-slot='table-fill-handle']`: an empty `span` inside the cell at the end corner of the selected cells.
|
|
64
|
+
|
|
65
|
+
- Place it with `position: absolute` at `inset-block-end` and `inset-inline-end` of its cell, which needs `position: relative`. The logical sides put it at the left corner from right to left.
|
|
66
|
+
- Give it `touch-action: none`.
|
|
67
|
+
- `fill-handle="vertical"` or `"horizontal"` keeps the handle and the keys on one axis. `:fill-handle="false"` with `sheet` takes both away.
|
|
68
|
+
|
|
69
|
+
## A drag
|
|
70
|
+
|
|
71
|
+
- A drag fills along the rows or along the columns, whichever the pointer went further on.
|
|
72
|
+
- While it runs, the table has `data-filling`. Each cell that would be filled has `data-fill-target` and `data-fill-edge` (`top`, `right`, `bottom`, `left`), so a line around the target is the same CSS as the line around a range.
|
|
73
|
+
- Near an edge of the scroll frame the table scrolls, also with a row window.
|
|
74
|
+
- Escape ends the drag and changes nothing.
|
|
75
|
+
|
|
76
|
+
## What it writes
|
|
77
|
+
|
|
78
|
+
- A source of one line repeats.
|
|
79
|
+
- A source of two or more lines goes on when it is numbers with one step (also negative, a fraction, upward and backward) or days with one step: `2028-02-22`, `2028-02-29` goes on with `2028-03-07`. Everything else repeats in its order.
|
|
80
|
+
- A fill along the rows passes values. A fill along the columns passes text through the `parse` of the next column.
|
|
81
|
+
- A cell that cannot be edited keeps its value and its place in the line.
|
|
82
|
+
- A fill from pinned rows into the rows of the list is refused: they are no neighbours in the data.
|
|
83
|
+
|
|
84
|
+
## All or nothing, one step
|
|
85
|
+
|
|
86
|
+
Each value passes the schema of its column. One refusal stops the fill before any cell changes, and the table says which column refused which text. A fill is one report through `@cell-edit` with the reason `fill`, and one step of the history. Its undo puts back the values of before, also for rows that were sorted, filtered or removed since.
|
|
87
|
+
|
|
88
|
+
## From code
|
|
89
|
+
|
|
90
|
+
`controller.fillCells('down' | 'up' | 'forward' | 'back', source = 1)` fills the selected cells from their first `source` lines. It works without the `fill-handle` option, which is about the handle and the keys. It throws for one selected line, for a wrong direction (with the valid ones), and with the reason of a refusal.
|
|
91
|
+
|
|
92
|
+
## Keys
|
|
93
|
+
|
|
94
|
+
| Key | With `fill-handle` |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| Control or Command with D | Fills the selected cells down from their first row |
|
|
97
|
+
| Control or Command with R | Fills the selected cells forward from their first column |
|
|
98
|
+
| Escape during a drag | Ends the drag and changes nothing |
|
|
99
|
+
|
|
100
|
+
With one line selected the keys stay the browser's: Control+R is its reload.
|
|
101
|
+
|
|
102
|
+
See the [Sheet tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=sheet).
|
|
103
|
+
|
|
104
|
+
## Names
|
|
105
|
+
|
|
106
|
+
- **Options:** `fillHandle` (`true`, `'vertical'`, `'horizontal'`, `false`).
|
|
107
|
+
- **Controller:** `fillCells`.
|
|
108
|
+
- **Attributes:** `data-filling` on the table; `data-fill-target` and `data-fill-edge` on a cell; the part `table-fill-handle`.
|
|
109
|
+
- **Messages:** `cellsFilled`, `fillRefused`, `fillNowhere`, `fillOverPinned`.
|
|
110
|
+
- **Exports:** `fillValues`, `fillLine`, `TableFillHandle`, and the types `FillWay`, `FillDirection`, `FillDraft`.
|