ui-sdk-table-vue 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/README.md CHANGED
@@ -37,6 +37,21 @@ Start with [llms.txt](./llms.txt): what the library is and the conventions every
37
37
  - [Formulas](./sheet-formulas.md): Compute values with formulas as in a spreadsheet: a computed column, or a formula in one cell.
38
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
39
 
40
+ ## Build on it
41
+
42
+ - [A styled table for an app](./styled-table.md): Build the table component of your design system on the headless table: the order of the work, and for each control what the library gives and what your app writes.
43
+ - [How the table is built](./how-the-table-is-built.md): The four layers of the table, from the behaviors to the `Table` component, and which word means what.
44
+
45
+ ## Reference
46
+
47
+ - [Table](./reference-table.md): Every prop, event and slot of `Table`, with the props that each slot gets.
48
+ - [ColumnDef](./reference-columns.md): Every key of a column definition, and the shapes of the state that names columns.
49
+ - [Controller](./reference-controller.md): Every method of the controller that `createTableController()` makes.
50
+ - [View](./reference-view.md): Every field of `getView()`, the plain data that the controls beside a table read.
51
+ - [Messages](./reference-messages.md): Every text that the table writes itself, for the `messages` prop.
52
+ - [Formulas](./reference-formulas.md): The types of the entry `ui-sdk-table-vue/formulas`.
53
+ - [Export](./reference-export.md): The types of `exportData` and of the entry `ui-sdk-table-vue/export`.
54
+
40
55
  ## Source and licence
41
56
 
42
57
  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.
@@ -95,7 +95,7 @@ Double-press a price, type 7, and press Enter. The line under the table says wha
95
95
  | Escape in the editor | Closes it and puts the value back |
96
96
  | A press elsewhere | Saves |
97
97
 
98
- The arrows in the editor move the caret. Without an editor, Tab leaves the table.
98
+ The arrows in the editor move the caret. Without an editor, Tab leaves the table; in the [entry mode](./cell-editing.md#an-entry-mode-with-save-and-cancel) it goes to the next cell that can be edited.
99
99
 
100
100
  ## Check a value
101
101
 
@@ -116,17 +116,121 @@ A check can answer with a promise. The editor then waits (`data-checking`), and
116
116
 
117
117
  `controller.editCell(rowId, columnId, value)` gives a cell a value with the check of its column, and reports it with the reason `imperative`. It throws with the reason when the value is refused. `startEdit` opens the editor of a cell in view, and `cancelEdit` closes it.
118
118
 
119
+ ## An entry mode with Save and Cancel
120
+
121
+ `entry` turns the table into a form for many cells at once: a person moves with Tab and types. Turn it on and off from your own Edit button; while it is on, cells can be edited as with `editable`, unless `editable` is false or a column says otherwise.
122
+
123
+ ```vue title="entry.vue"
124
+ <script setup lang="ts">
125
+ import { Button } from '@ui-sdk/vue/button'
126
+ import {
127
+ applyEdits,
128
+ Table,
129
+ useEditDraft,
130
+ type CellAttrsContext,
131
+ type ColumnDef,
132
+ } from 'ui-sdk-table-vue'
133
+ import { shallowRef } from 'vue'
134
+
135
+ type Shift = { id: string; person: string; day: string; hours: number; note: string }
136
+
137
+ const columns: ColumnDef<Shift>[] = [
138
+ { id: 'person', header: 'Person', editable: false },
139
+ { id: 'day', header: 'Day' },
140
+ { id: 'hours', header: 'Hours', format: 'decimal', numberKeyboard: true },
141
+ { id: 'note', header: 'Note' },
142
+ ]
143
+
144
+ // The rows are yours. The draft holds the edits until Save.
145
+ const rows = shallowRef<Shift[]>([
146
+ { id: 's1', person: 'Kofi', day: 'Monday', hours: 8, note: '' },
147
+ { id: 's2', person: 'Ines', day: 'Tuesday', hours: 6.5, note: 'Late start' },
148
+ { id: 's3', person: 'Tomas', day: 'Friday', hours: 4, note: '' },
149
+ ])
150
+ const draft = useEditDraft(rows)
151
+ const editing = shallowRef(false)
152
+ const last = shallowRef('Nothing saved yet.')
153
+
154
+ function save() {
155
+ const edits = draft.save()
156
+ rows.value = applyEdits(rows.value, edits)
157
+ last.value = `Saved ${edits.length} ${edits.length === 1 ? 'cell' : 'cells'}.`
158
+ editing.value = false
159
+ }
160
+
161
+ function cancel() {
162
+ draft.cancel()
163
+ editing.value = false
164
+ }
165
+
166
+ // A cell whose value differs from your rows gets a mark of its own.
167
+ const cellAttrs = (context: CellAttrsContext<Shift>) =>
168
+ context.kind === 'cell' && draft.changed(context.node.id, context.column.id)
169
+ ? { class: 'changed' }
170
+ : undefined
171
+ </script>
172
+
173
+ <template>
174
+ <div>
175
+ <Button v-if="!editing" @click="editing = true">Edit</Button>
176
+ <template v-else>
177
+ <Button @click="save">Save</Button>
178
+ <Button @click="cancel">Cancel</Button>
179
+ <span>{{ draft.count.value }} changed</span>
180
+ </template>
181
+ </div>
182
+ <Table
183
+ :rows="draft.rows.value"
184
+ :columns="columns"
185
+ :entry="editing"
186
+ :cell-attrs="cellAttrs"
187
+ aria-label="Shifts"
188
+ @cell-edit="draft.onCellEdit"
189
+ />
190
+ <p role="status">{{ last }}</p>
191
+ </template>
192
+
193
+ <style scoped>
194
+ /* In the entry mode, the cells that take input show it. */
195
+ :deep([data-entry] td[data-editable]) {
196
+ box-shadow: inset 0 -1px 0 #94a3b8;
197
+ cursor: text;
198
+ }
199
+
200
+ :deep(td.changed) {
201
+ background: #fef9c3;
202
+ }
203
+ </style>
204
+ ```
205
+
206
+ Press Edit, then press a day: its editor opens. Type Sunday and press Tab: the day is saved and focus goes to the hours, where typing 7 replaces the value. Press Tab, then Save. Cancel puts every cell back.
207
+
208
+ - **Tab and Shift+Tab** on a cell and in the editor go to the next and the previous cell that can be edited, in reading order and across the rows. They pass over a cell that cannot be edited, a group row and a column that leads. From the last such cell Tab leaves the table, and from the first Shift+Tab: the table is never a trap. Inside a selected range of more than one cell, Tab walks the range.
209
+ - **One press** on a cell that can be edited opens its editor. A press with Shift, Control, Command or Alt, and a drag, keep their meaning, also with `cell-selection`.
210
+ - **A character** on a cell replaces its value, and Tab, Enter or a press elsewhere saves it, as without the mode.
211
+ - The root has `data-entry`, so a style can show which cells take input: `[data-entry] [data-editable]`.
212
+
213
+ `useEditDraft(rows, { getRowId? })` holds the edits until a person saves them. It never changes one of your row objects. It reads the top level of your rows only, as `applyEdits` does, and finds a row by `getRowId`, else by its `id`, else by its place: pass the `getRowId` of the table when it has one.
214
+
215
+ - `rows` is the list to pass to the table: your rows, with the values of the draft in new objects.
216
+ - `onCellEdit` is the `@cell-edit` listener. It takes every report: an edit, a paste, a fill, a clear and an undo. For an edit of a row that it cannot find, such as a child row of a tree, it throws with the row id, and takes nothing of that report.
217
+ - `count` is how many cells differ from your rows, and `changed(rowId, columnId)` says whether one does, for a mark through `cellAttrs`. A cell set back to its first value no longer differs.
218
+ - `save()` gives the edits against your rows, one for each cell that differs, and empties the draft: pass them to `applyEdits`, or to your server. `cancel()` empties the draft.
219
+ - **New rows while a draft is open:** the draft is kept by row id and column id and stays over the new rows. A cell whose new value is the value of the draft no longer differs, and a cell of a row that is gone counts no more and is not saved.
220
+ - **Formulas:** the draft holds values only. A formula that a person types goes into the `cellFormulas` state of the table at once, as without a draft, and `cancel()` does not take it back. For a table with `formulas`, keep the formulas in a `v-model:cell-formulas` of your own and put the old state back on Cancel.
221
+
119
222
  ## Attributes
120
223
 
224
+ - `data-entry` on the root in the entry mode.
121
225
  - `data-editable` on a cell that can be edited, `data-editing` while its editor is open, `data-checking` while a check runs.
122
226
  - The editor is `[data-slot='table-editor']`, with `aria-invalid` and `data-invalid` after a refusal. Its name is "Edit Price" (message `editCell`).
123
227
  - The reason of a refusal is `[data-slot='table-edit-error']`, which the editor names with `aria-errormessage`.
124
228
 
125
229
  ## Names
126
230
 
127
- - **Options:** `editable`, `onCellEdit` (`@cell-edit`); column keys `editable`, `parse`, `schema`, `numberKeyboard`.
231
+ - **Options:** `editable`, `entry`, `onCellEdit` (`@cell-edit`); column keys `editable`, `parse`, `schema`, `numberKeyboard`.
128
232
  - **Controller:** `editCell`, `startEdit`, `cancelEdit`.
129
233
  - **Slots:** `#editor`, `#edit-{column id}`.
130
- - **Exports:** `applyEdits`, `cellValue`, `emptyValue`, and the types `CellEdit`, `TableEditDetails`, `TableEditReason`, `StandardSchemaV1`, `EditorSlotProps`.
234
+ - **Exports:** `applyEdits`, `cellValue`, `emptyValue`, `useEditDraft`, and the types `EditDraft`, `EditDraftOptions`, `CellEdit`, `TableEditDetails`, `TableEditReason`, `StandardSchemaV1`, `EditorSlotProps`.
131
235
 
132
236
  See the [Edit tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=edit).
@@ -100,6 +100,8 @@ A cell gets the formula of the file only when the whole formula means the same i
100
100
  - a range is one column whose rows are in the file in the order of the document and next to each other;
101
101
  - each function is in `EXCEL_FUNCTIONS`.
102
102
 
103
+ A function that came after Excel 2007 (`CONCAT`, `IFS`, `SWITCH`, `IFNA`, `TEXTJOIN`) is written with the prefix `_xlfn.` that the file format asks for. `SUMIF`, `AVERAGEIF`, the lookups, `VALUE`, `TEXT`, `TODAY`, `NOW`, `EOMONTH` and the date functions go as their result: Excel stretches a smaller range of `SUMIF`, searches sorted data in halves, reads its own locale in `VALUE` and `TEXT`, computes `TODAY` and `NOW` again when it opens the file, and has no day text.
104
+
103
105
  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
106
 
105
107
  See the [Formula tiles of the sink](https://falldownthesystem.github.io/ui-sdk-table/?page=sink&only=formula) and the page [Export](./export.md).
@@ -0,0 +1,107 @@
1
+ # How the table is built
2
+
3
+ The four layers of the table, from the behaviors to the `Table` component, and which word means what.
4
+
5
+ Read it before you write a part of your own, or when `Table` does not give the markup you need.
6
+
7
+ ```vue title="parts.vue"
8
+ <script setup lang="ts">
9
+ import {
10
+ TableBody,
11
+ TableCell,
12
+ TableHead,
13
+ TableHeaderCell,
14
+ TableHeaderRow,
15
+ TableRoot,
16
+ TableRow,
17
+ type ColumnDef,
18
+ } from 'ui-sdk-table-vue'
19
+
20
+ type Planet = { id: string; name: string; moons: number }
21
+
22
+ const planets: Planet[] = [
23
+ { id: 'mars', name: 'Mars', moons: 2 },
24
+ { id: 'jupiter', name: 'Jupiter', moons: 95 },
25
+ { id: 'saturn', name: 'Saturn', moons: 146 },
26
+ ]
27
+
28
+ // `TableRoot` is not generic: its columns are `ColumnDef` of rows of an unknown type.
29
+ const columns: ColumnDef[] = [
30
+ { id: 'name', header: 'Planet' },
31
+ { id: 'moons', header: 'Moons' },
32
+ ]
33
+ </script>
34
+
35
+ <template>
36
+ <!-- The root takes the options of the table. Each part gets a key of its own as `value`, and its place in the grid. -->
37
+ <TableRoot :rows="planets" :columns="columns" aria-label="Planets and their moons">
38
+ <TableHead>
39
+ <TableHeaderRow value="header" :index="0">
40
+ <TableHeaderCell
41
+ v-for="(column, col) in columns"
42
+ :key="column.id"
43
+ :value="`h|${column.id}`"
44
+ :row="0"
45
+ :col="col"
46
+ header
47
+ >
48
+ {{ column.header }}
49
+ </TableHeaderCell>
50
+ </TableHeaderRow>
51
+ </TableHead>
52
+ <TableBody>
53
+ <TableRow
54
+ v-for="(planet, index) in planets"
55
+ :key="planet.id"
56
+ :value="planet.id"
57
+ :index="index + 1"
58
+ >
59
+ <TableCell :value="`${planet.id}|name`" :row="index + 1" :col="0">{{
60
+ planet.name
61
+ }}</TableCell>
62
+ <TableCell :value="`${planet.id}|moons`" :row="index + 1" :col="1">{{
63
+ planet.moons
64
+ }}</TableCell>
65
+ </TableRow>
66
+ </TableBody>
67
+ </TableRoot>
68
+ </template>
69
+ ```
70
+
71
+ A table built by hand from the parts, with no Table component. Press a cell and use the arrow keys: focus moves from cell to cell, as in a Table.
72
+
73
+ ## The four layers
74
+
75
+ 1. **Behaviors.** Each is a function `create<Thing>(context, options)` in `ui-sdk-table-core`: the focus of the grid (`createTableGrid`), a range of cells (`createTableRange`), an editor (`createCellEdit`), the resize, the move and the pins of columns, sticky rows, the row window, the fill handle, the writes of many cells and the history. Most of them wrap one behavior of UI SDK, such as `createGridFocus` or `createCellRange`. A behavior does not know the others.
76
+ 2. **The primitive.** `table` of `ui-sdk-table-core` is one `definePrimitive` of UI SDK. It holds the options, the state, the row pipeline and the behaviors, and it meets them in its `api`. Its slots are the elements of a table: `root`, `head`, `body`, `foot`, `col`, `header-row`, `plain-row`, `spacer`, `row`, `cell`, `editor`, `edit-error`, `fill-handle` and `resizer`. Each slot gives its element a role, ARIA and `data-*` attributes, and its event handlers.
77
+ 3. **The parts.** `createParts` of `@ui-sdk/vue/primitive` turns each slot into a Vue component with its element: `TableRoot` is a `table`, `TableRow` a `tr`, `TableCell` a `td`. A slot has one element, so `TableHeaderCell` is a second part of the `cell` slot, as a `th`.
78
+ 4. **`Table`.** The component that you use on a page. It renders the parts from `rows` and `columns`: the header rows, the rows of the body, the group rows, the footer and the editor. It gives Vue slots with the row and the value, a `v-model` for each state and the `controller`.
79
+
80
+ ## Two kinds of slot
81
+
82
+ - A **slot of the primitive** is an element: `cell` is every `td` and `th` of a grid cell. Its name is the `data-slot` of the element, with `table-` before it (`table-cell`).
83
+ - A **Vue slot of `Table`** is a place for your content: `#col-price` fills the cells of the column `price`, `#header` fills the header cells. The element around it stays the table's.
84
+
85
+ ## Build a table from the parts
86
+
87
+ The parts work without `Table`. A test in the package (`packages/vue/src/parts.test.ts`, "a table built by hand from the parts") builds a table from `TableRoot`, `TableHead`, `TableHeaderRow`, `TableHeaderCell`, `TableBody`, `TableRow` and `TableCell`, and shows:
88
+
89
+ - the root has the role `grid`, its `aria-label`, and `aria-rowcount` and `aria-colcount`;
90
+ - each row has the role `row` and its `aria-rowindex`, from 1 for the header row;
91
+ - a header cell has the role `columnheader`, a body cell the role `gridcell` and its `aria-colindex`;
92
+ - the arrow keys move focus from cell to cell, and the cell with focus has `tabindex="0"`.
93
+
94
+ What you pass yourself:
95
+
96
+ - `TableRoot` takes the options of the table as props, as `Table` does: `rows`, `columns` and the rest. It has no Vue slots for cells.
97
+ - `TableRoot` is not generic. Its `columns` are `ColumnDef[]`, columns of rows of an unknown type: a list typed `ColumnDef<Planet>[]` does not fit it. Type the list `ColumnDef[]`.
98
+ - Each row and cell needs `value`, a key that is unique in the table. A row takes the id of its row; a cell any text of its own.
99
+ - A row needs `index`, its place in the grid from 0 for the first header row. A cell needs `row` and `col`, its place in the grid. A header cell needs `header`.
100
+
101
+ `Table` does all of this, and the group rows, the footer, the editor, the row window and the slots. The test covers the roles, the numbers and the arrow keys only; build on the parts when you need markup that `Table` cannot give, and test the rest yourself.
102
+
103
+ ## Names
104
+
105
+ - **Parts:** `TableRoot`, `TableHead`, `TableBody`, `TableFoot`, `TableCol`, `TableHeaderRow`, `TableHeaderCell`, `TablePlainRow`, `TableSpacer`, `TableRow`, `TableCell`, `TableEditor`, `TableEditError`, `TableFillHandle`, `TableResizer`.
106
+ - **Props of the parts:** `value` (`col`, `header-row`, `row`, `cell`, `spacer`, `editor`, `edit-error`, `resizer`), `index` (`header-row`, `plain-row`, `row`), `row`, `col`, `colspan`, `rowspan`, `header` (`cell`), `footer` (`plain-row`), `size` (`spacer`).
107
+ - **Core:** the primitive `table` of `ui-sdk-table-core`.
package/docs/llms.txt CHANGED
@@ -15,6 +15,8 @@ This file is the context an agent needs to build a table with ui-sdk-table-vue:
15
15
  - An action that gets a wrong argument throws a message that lists the valid values.
16
16
  - The controls around a table, such as a search field, a select or a pagination, come from the design system of the app. UI SDK ships them as headless components too.
17
17
 
18
+ The pages of the group "Reference" list every prop, event, slot, controller method, view field and column key with its type, from the types of the package.
19
+
18
20
  The UI SDK docs for Vue are at `node_modules/@ui-sdk/vue/docs/llms.txt`.
19
21
 
20
22
  ## Introduction
@@ -296,3 +298,18 @@ The rules of a scoped style reach the elements of the table through `:deep()`, b
296
298
  - [Row numbers and letters](./row-numbers-and-letters.md): Give a sheet a column of row numbers and a row of column letters, where a person selects whole rows and columns.
297
299
  - [Formulas](./sheet-formulas.md): Compute values with formulas as in a spreadsheet: a computed column, or a formula in one cell.
298
300
  - [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.
301
+
302
+ ### Build on it
303
+
304
+ - [A styled table for an app](./styled-table.md): Build the table component of your design system on the headless table: the order of the work, and for each control what the library gives and what your app writes.
305
+ - [How the table is built](./how-the-table-is-built.md): The four layers of the table, from the behaviors to the `Table` component, and which word means what.
306
+
307
+ ### Reference
308
+
309
+ - [Table](./reference-table.md): Every prop, event and slot of `Table`, with the props that each slot gets.
310
+ - [ColumnDef](./reference-columns.md): Every key of a column definition, and the shapes of the state that names columns.
311
+ - [Controller](./reference-controller.md): Every method of the controller that `createTableController()` makes.
312
+ - [View](./reference-view.md): Every field of `getView()`, the plain data that the controls beside a table read.
313
+ - [Messages](./reference-messages.md): Every text that the table writes itself, for the `messages` prop.
314
+ - [Formulas](./reference-formulas.md): The types of the entry `ui-sdk-table-vue/formulas`.
315
+ - [Export](./reference-export.md): The types of `exportData` and of the entry `ui-sdk-table-vue/export`.
@@ -0,0 +1,62 @@
1
+ # ColumnDef
2
+
3
+ Every key of a column definition, and the shapes of the state that names columns.
4
+
5
+ See [Columns](./column-definitions.md) for how they work together.
6
+
7
+ ## ColumnDef
8
+
9
+ - `id` (`string`): The id of the column: a key of the state (sort, filter, widths) and of the slots `col-{id}`. Give each column an id of its own.
10
+ - `header?` (`string`): The text of the header. Defaults to the id.
11
+ - `key?` (`string`): The property that holds the cell value. Defaults to `id`.
12
+ - `value?` (`(row: Row) => unknown`): Computes the cell value. Wins over `key`.
13
+ - `columns?` (`readonly ColumnDef<Row>[]`): Child columns. A column with children is a header group and holds no cells.
14
+ - `sortable?` (`boolean`): Whether a press on the header sorts by the column: the header renders a button and gets `aria-sort`. Code can sort by any column with `sortBy`.
15
+ - `compare?` (`(a: unknown, b: unknown, rowA: Row, rowB: Row) => number`): Compares two values for the sort, ascending: a negative number puts `a` first. An empty value goes last in both directions and never reaches it. Without it, numbers, dates and texts of the locale.
16
+ - `filter?` (`FilterKind | FilterMatcher<Row>`): How a column filter matches. Without it, the shape of the filter value decides.
17
+ - `searchable?` (`boolean`): Whether the search reads this column. Defaults to true.
18
+ - `groupable?` (`boolean`): A mark for the controls of the app: whether a person may group by the column. The table groups by any column that `groupBy` names.
19
+ - `aggregate?` (`AggregateName | AggregateFn<Row>`): The total of the column in the footer and in the group rows: a built-in name, or a function of the values and the rows.
20
+ - `format?` (`FormatName`): How the cell value becomes text. Without it, the value is shown as it is.
21
+ - `formatOptions?` (`FormatOptions`): The options of the `format`, such as the decimals, the currency or the time zone.
22
+ - `width?` (`number`): The width in pixels that the column asks for. A resize by a person wins over it.
23
+ - `minWidth?` (`number`): The smallest width in pixels that a resize gives. Without it, the `columnMinWidth` option of the table.
24
+ - `maxWidth?` (`number`): The largest width in pixels that a resize gives. Without it, the `columnMaxWidth` option of the table.
25
+ - `resizable?` (`boolean`): Whether a person can resize the column. Without it, the `resizable` option of the table decides.
26
+ - `reorderable?` (`boolean`): Whether a person can move the column. Without it, the `reorderable` option of the table decides.
27
+ - `lead?` (`boolean`): The column leads the table: it stays before every other column, whatever the column order says, and it sticks to the start as soon as another column is pinned there. A column order and the pins do not hold it. For a top-level column that holds a control of its row, such as a checkbox.
28
+ - `rowHeader?` (`boolean`): The column holds the number of each row, and its cells are the row headers of the table: a screen reader says the number with each cell of the row. Such a column leads the table, as with `lead`, and it is outside every range of cells: a number is never copied, emptied or filled. A press on a number selects the cells of its row. See `rowNumberColumn`.
29
+ - `hideable?` (`boolean`): Whether the column can be hidden. Defaults to true.
30
+ - `editable?` (`boolean | ((row: Row) => boolean)`): Whether a person can edit the cells of the column, or which rows have a cell that can be edited. Without it, the `editable` option of the table decides.
31
+ - `numberKeyboard?` (`boolean`): Whether the editor of a cell asks a phone for its number keyboard (`inputmode="decimal"`): the cells of the column hold numbers. Off by default. The table holds it back where the field can hold a formula, and for a cell whose format is no number format.
32
+ - `allowFormula?` (`boolean`): With formulas: whether a cell of the column takes a text that starts with `=` as a formula. True by default for a cell that can be edited; a column that must keep such a text as its value sets false.
33
+ - `schema?` (`StandardSchemaV1`): Checks a new value before the table reports the edit. Any Standard Schema works: Zod, Valibot, ArkType. A value that the schema refuses keeps the editor open, with the message of the schema.
34
+ - `parse?` (`(text: string, row: Row) => unknown`): Makes the value of a cell from the text of the editor or of a paste. Without it, see `parseText`.
35
+ - `exportable?` (`boolean`): Whether an export holds the column. Defaults to true.
36
+ - `exportValue?` (`(row: Row) => unknown`): The value of a cell in an export, in place of the cell value and its format: for a column whose cell is a slot, or whose file value differs from the screen.
37
+ - `meta?` (`unknown`): Data of the app for the column. The table does not read it.
38
+
39
+ ## SortRule
40
+
41
+ - `id` (`string`): The id of the column.
42
+ - `desc?` (`boolean`): Whether the column sorts descending. Without it, ascending.
43
+
44
+ ## FilterState
45
+
46
+ - `search?` (`string`): The search text, which every column with `searchable` reads.
47
+ - `columns?` (`Readonly<Record<string, unknown>>`): The filter of each column, by column id. The shape of a value, or `filter` of the column, decides how it matches.
48
+
49
+ ## PageState
50
+
51
+ - `page` (`number`): The page in view, from 1.
52
+ - `pageSize` (`number`): How many rows a page holds.
53
+
54
+ ## ColumnPinning
55
+
56
+ - `start?` (`readonly string[]`): The ids of the columns that stay at the start edge, in order.
57
+ - `end?` (`readonly string[]`): The ids of the columns that stay at the end edge, in order.
58
+
59
+ ## RowPinning
60
+
61
+ - `top?` (`readonly string[]`): The ids of the rows that stay above the others, in order.
62
+ - `bottom?` (`readonly string[]`): The ids of the rows that stay below the others, in order.
@@ -0,0 +1,133 @@
1
+ # Controller
2
+
3
+ Every method of the controller that `createTableController()` makes.
4
+
5
+ Pass the controller to the table as `controller`. A method checks its arguments and throws with a message that names the valid values. An agent calls the same methods. See [Controller and view](./controller-and-view.md).
6
+
7
+ ## TableController
8
+
9
+ - `sortBy` (`(columnId: string, direction?: SortDirection | null, options?: { append?: boolean }) => void`): Sorts by a column in a direction, `'asc'` by default. Without `append: true`, the column replaces the sort, whatever the `multiSort` mode. With `append`, `null` takes the column out of the sort; without it, `null` empties the sort.
10
+ - `toggleSort` (`(columnId: string, options?: { append?: boolean; event?: Event }) => void`): Sorts by a column as a press on its header does: ascending, descending, not sorted. Without `append`, the `multiSort` option of the table and the keys of the event decide whether the column joins the sort or replaces it. With `alwaysSorted`, the last column of the sort turns back to ascending and the sort is never empty.
11
+ - `setSearch` (`(text: string) => void`): Gives the table a search text at once. A text that waits from `inputSearch` is dropped.
12
+ - `inputSearch` (`(text: string, event?: Event) => void`): Takes the text of a search field while a person types. `getView().search` holds the text at once, and the table filters when the typing pauses for `searchDebounce` milliseconds. Pass the event of the field for the details of the change.
13
+ - `flushSearch` (`() => void`): Filters now by the text that waits from `inputSearch`, for example on Enter. Without one, nothing happens.
14
+ - `setColumnFilter` (`(columnId: string, value: unknown) => void`): Sets the filter of one column. A value that asks for nothing (see `isEmptyFilter`) takes the filter of the column away.
15
+ - `clearFilters` (`() => void`): Takes the search and the filter of every column away, in one change. A search text that waits from `inputSearch` goes too.
16
+ - `clearColumnFilters` (`() => void`): Takes the filter of every column away, in one change. The search stays.
17
+ - `setGroupBy` (`(columnIds: readonly string[]) => void`): Groups the rows by these columns, in this order. An empty list takes the groups away.
18
+ - `setPage` (`(page: number) => void`): Goes to a page, from 1. A page past the last goes to the last. It throws when the table has no pages or the page is not a whole number.
19
+ - `setPageSize` (`(pageSize: number | null) => void`): Gives the table pages of a size, from its first page. `null` takes the pages away: every row shows.
20
+ - `nextPage` (`() => void`): Goes to the next page. On the last page, nothing changes.
21
+ - `previousPage` (`() => void`): Goes to the page before. On the first page, nothing changes.
22
+ - `firstPage` (`() => void`): Goes to the first page.
23
+ - `lastPage` (`() => void`): Goes to the last page. It throws with `manualPage` and no `rowCount`: the table does not know its last page.
24
+ - `expand` (`(rowId: string) => void`): Opens a tree row, a group or a row with a detail row. It throws for a row that cannot open.
25
+ - `collapse` (`(rowId: string) => void`): Closes a tree row, a group or a row with a detail row. It throws for a row that cannot open.
26
+ - `toggleExpanded` (`(rowId: string, event?: Event) => void`): Opens a row that is closed and closes one that is open. Pass the event of a press for the details of the change.
27
+ - `expandAll` (`() => void`): Opens every tree row and group, in one change. A detail row stays as it is.
28
+ - `collapseAll` (`() => void`): Closes every row and group, detail rows too, in one change.
29
+ - `select` (`(rowId: string) => void`): Selects one row in place of the selection. It throws without the `selection` option, and for a row that `canSelect` refuses.
30
+ - `toggleSelected` (`(rowId: string, event?: Event) => void`): Adds a row to the selection, or takes a selected row away. Pass the event of a press for the details of the change.
31
+ - `selectAll` (`() => void`): Selects every row of the list that can be selected, in one change. It needs `selection: 'multiple'`. A selected row that the filter hides stays selected.
32
+ - `clearSelection` (`() => void`): Takes every row out of the selection.
33
+ - `setColumnVisibility` (`(columnId: string, visible: boolean) => void`): Shows or hides a column, or every column of a header group.
34
+ - `toggleColumnVisibility` (`(columnId: string) => void`): Hides a column that shows and shows one that is hidden.
35
+ - `showAllColumns` (`() => void`): Shows every column, in one change.
36
+ - `hideAllColumns` (`() => void`): Hides every column that can be hidden, in one change. A column with `hideable: false` and a column that leads the table stay. A table needs one column: when no other column would be left, the first one in view stays.
37
+ - `resetColumnVisibility` (`() => void`): Brings the hidden columns back to what the table started with: `defaultColumnVisibility`, or every column in view.
38
+ - `resetColumnOrder` (`() => void`): Brings the column order back to what the table started with: `defaultColumnOrder`, or the order of the definitions.
39
+ - `resetColumnPinning` (`() => void`): Brings the pinned columns back to what the table started with: `defaultColumnPinning`, or no pinned column.
40
+ - `moveColumn` (`(columnId: string, index: number) => void`): Moves a column to a place among the columns that can move, from 0.
41
+ - `setColumnOrder` (`(columnIds: readonly string[]) => void`): Puts the columns in this order. Columns that are not listed come after, in the order of the definitions. It throws for an id that is listed twice.
42
+ - `setColumnWidth` (`(columnId: string, width: number | null) => void`): Gives a column a width in pixels. `null` takes the width away again.
43
+ - `resetColumnWidths` (`() => void`): Takes every width that a resize or `setColumnWidth` gave away, so each column has the width of its definition again.
44
+ - `pinColumn` (`(columnId: string, side: ColumnPin | null) => void`): Pins a column to the start or the end of the table. `null` frees it.
45
+ - `pinRow` (`(rowId: string, edge: RowPin | null) => void`): Pins a row to the top or the bottom of the rows. `null` frees it.
46
+ - `scrollToRow` (`(rowId: string, align?: RowAlign) => void`): Scrolls a row into view, in one step, also when the row is not rendered yet.
47
+ - `editCell` (`(rowId: string, columnId: string, value: unknown) => void | Promise<void>`): Gives a cell a new value, with the check of its column, and reports it through `onCellEdit`. A text is read as the editor reads it. It throws with the reason when the value is refused; when the schema of the column answers with a promise, the result is a promise that rejects.
48
+ - `startEdit` (`(rowId: string, columnId: string) => void`): Opens the editor of a cell that is in view.
49
+ - `cancelEdit` (`() => void`): Closes the editor without a save.
50
+ - `selectCells` (`(from: CellRef, to?: CellRef) => void`): Selects the cells from one cell to another, or one cell. Needs the `cellSelection` option.
51
+ - `clearCellSelection` (`() => void`): Takes the range of cells away.
52
+ - `copyCells` (`() => string`): The text of the selected cells, with tabs between cells and line breaks between rows.
53
+ - `pasteCells` (`(text: string) => void | Promise<void>`): Puts tab-separated text into the cells from the first selected cell on, as a paste does. It throws with the reason when a value is refused, and then no cell changes.
54
+ - `clearCells` (`() => void | Promise<void>`): Empties the selected cells, as Delete does in a sheet: each gets the empty value of its column (`emptyValue`), with the check of the column. It throws with the reason when a column refuses an empty value, and then no cell changes. Cells that cannot be edited are left as they are.
55
+ - `cutCells` (`() => string | Promise<string>`): Empties the selected cells and returns their text, as `copyCells` gives it. A caller puts the text on the clipboard. It throws as `clearCells` does.
56
+ - `fillCells` (`(direction: FillWay, source?: number) => void | Promise<void>`): Fills the selected cells from their first line: `'down'` from the first row, `'up'` from the last row, `'forward'` from the first column, `'back'` from the last column. `source` is how many lines the fill starts from, 1 without it; with two or more, numbers and days with one step go on, and everything else repeats. Each value passes the check of its column, and one refusal stops the fill before any cell changes. It throws when the selected cells are one line in that direction.
57
+ - `selectAllCells` (`() => void`): Selects every cell of the body. Needs the `cellSelection` option.
58
+ - `selectCellRows` (`(fromRowId: string, toRowId?: string) => void`): Selects every cell of a row, or of the rows from one to another as the list shows them.
59
+ - `selectCellColumns` (`(fromColumnId: string, toColumnId?: string) => void`): Selects every cell of a column, or of the columns from one to another as the table shows them.
60
+ - `undo` (`() => void`): Takes the last change of cell values back: it reports the old values through `onCellEdit` with the reason `undo`, and the owner of the rows puts them in, as for an edit. Needs the `history` option. It throws when there is nothing to undo, when a listener refuses the report, and while the check of a value runs.
61
+ - `redo` (`() => void`): Puts the change on again that `undo` took back last, with the reason `redo`.
62
+ - `clearHistory` (`() => void`): Forgets every step. Call it when the rows become other data, such as another document.
63
+ - `getHistory` (`() => { entries: readonly HistoryEntry<TableStepReason>[]; position: number }`): The steps of the history, oldest first, and how many of them are applied: `undo` takes back the last of those.
64
+ - `setColumnAggregate` (`(columnId: string, aggregate: AggregateName | null | undefined) => void`): Chooses the function of the total of a column, in the footer, in the group rows and in an export: `sum`, `mean`, `min`, `max`, `count`, `uniqueCount` or `first`. `null` takes the total of the column away, and `undefined` gives the column the `aggregate` of its definition back.
65
+ - `getColumnFormula` (`(columnId: string) => { formula: string; text: string; error: string | null } | null`): The formula of a computed column, as a person reads it (the headers of the columns, the signs of the locale) and in the stored form, or `null` for a column without one. `error` says why the formula gives an error in every row. Needs the `formulas` option.
66
+ - `setColumnFormula` (`(columnId: string, formula: string | null) => void`): Sets the formula of a column, as a person types it or in the stored form, or takes it away with `null`: one change of `cellFormulas` and one step of the history. It throws when the formula cannot be read, reads another row, or reads its own column through other formulas. Needs the `formulas` option.
67
+ - `getAddress` (`(rowId: string, columnId: string) => string | null`): The address of a cell, such as `D7`: the letter of its column among the columns of the owner and the number of its row in the document. `null` for a column without a letter. Needs the `formulas` option.
68
+ - `cellAt` (`(address: string) => CellRef`): The cell of an address such as `D7`. It throws for an address that the table does not have. Needs the `formulas` option.
69
+ - `getCellFormula` (`(rowId: string, columnId: string) => FormulaView | null`): The formula of a cell: the stored form, the text as a person reads it, the address, the value and the words of its error. `null` for a cell without a formula of its own. Needs the `formulas` option.
70
+ - `setCellFormula` (`(rowId: string, columnId: string, formula: string | null) => void`): Gives a cell a formula, as a person types it or in the stored form, or takes it away with `null` (the cell keeps its value). One report with every cell that follows, and one step. It throws when the cell cannot hold a formula, the formula cannot be read, or it reads its own cell.
71
+ - `recalculate` (`() => number`): Computes every formula of a cell and reports each cell whose value is not the one its formula gives, with the reason `recalculate`. Returns how many cells it reported. The table does this by itself after new rows, for the cells that they change; this is for a check after a load.
72
+ - `getFormulaSummary` (`(limit?: number) => { lines: FormulaSummaryLine[]; more: number }`): The formulas as a short list: each text of a column once, with how many cells hold it. `limit` is 1 to 500, 100 by default.
73
+ - `evaluateFormula` (`(formula: string, at?: CellRef) => unknown`): The value that a formula would give at a cell, the active cell by default. Nothing is written.
74
+ - `getFormulaFunctions` (`() => readonly { name: string; args: string; help: string }[]`): The functions of the formulas: name, arguments and one line of help.
75
+ - `formatCells` (`(patch: CellFormatPatch, target?: FormatTarget) => void`): Changes the format of cells: how their values become text (`format`, `decimals`, `currency`, `dateStyle`) and how they look (`align`, `bold`, `italic`, `color`, `fill`). A key with `null` takes that property away. Without a target, the selected cells get it; when those are every row that the table has, the format goes to the whole columns and holds for rows that come later. It throws for a property, a format name or a colour that the table does not know, and lists the valid ones.
76
+ - `clearCellFormats` (`(target?: FormatTarget) => void`): Takes every format of cells away: of the target, or of the selected cells.
77
+ - `toggleCellFormat` (`(property: 'bold' | 'italic') => void`): Makes the selected cells bold or italic, for a button of a toolbar, as the keys of a sheet do: on, unless every selected cell has it, and then off.
78
+ - `getCellFormat` (`(rowId: string, columnId: string) => CellFormat`): The format that a cell has of its own: the format of its column in `cellFormats` with the format of the cell over it. An empty object when neither says anything, and for the number of a row. The `format` of the column definition is not in it.
79
+ - `getSelectionSummary` (`() => RangeSummary | null`): What the selected cells add up to: how many hold a value and a number, and the sum, the mean, the smallest and the largest of the numbers, each also as text. Counted when it is asked for, and kept for the same selection and the same rows. `null` when no cell of a data row is selected. Group rows and the numbers of the rows are left out.
80
+ - `exportData` (`(options?: ExportOptions) => ExportData`): The cells of the table as plain data, for a file: every row that passes the filters and the visible columns, or what the options ask for. The writers are in the `export` entry of the package (`toCsv`, `toXlsx`).
81
+ - `selectRows` (`(rowIds: readonly string[]) => void`): Selects rows in one change, beside the rows that are selected. It throws for a row that cannot be selected.
82
+ - `deselectRows` (`(rowIds: readonly string[]) => void`): Takes rows out of the selection in one change.
83
+ - `getView` (`() => TableView`): What the table shows now, for a control beside it: a search field, a list of columns, the pages. It answers at the time of the call; `subscribe` says when to ask again.
84
+ - `getFacets` (`(columnId: string, options?: FacetOptions) => ColumnFacets`): What a filter control of a column offers: its kind, and the values, the numbers or the dates that the column holds. They follow the search and the filters of the other columns, and never the filter of the column itself, so a filter does not take away its own choices. `rows: 'all'` gives the facets of every row of the table. A column that the `facets` option names has the facets of the owner, for both.
85
+ - `getTotals` (`(groupId?: string) => Readonly<Record<string, ColumnTotal>>`): The total of each column that has an `aggregate`, with its text in the format of the column: of the rows that pass the filters, as the footer shows them, or of one group by its id.
86
+ - `subscribe` (`(listener: (changed: readonly string[]) => void) => () => void`): Runs the listener after each change of the state, of the rows or of the columns, with the keys of the state that changed. Returns the function that stops it. A table that is destroyed stops every listener itself.
87
+
88
+ ## FacetOptions
89
+
90
+ - `rows?` (`'filtered' | 'all'`): `'filtered'` (the default): the rows that pass the search and the filters of the other columns. `'all'`: every row of the table.
91
+
92
+ ## ColumnFacets
93
+
94
+ - `kind` (`FilterKind`): The filter of the column: its `filter` option, or what its format says. A column of dates filters by a range of dates, a column of numbers by a range, any other column by text.
95
+ - `values` (`readonly ColumnFacetValue[]`): Each different value, sorted. Filled for the kind `select`.
96
+ - `range` (`{ min: number; max: number; step: number } | null`): The lowest and the highest number, and the step of a slider between them: the smallest change that the format of the column shows. Filled for the kind `range`. `sliderBounds` gives ends that are whole steps.
97
+ - `dates` (`{ from: Date; to: Date } | null`): The earliest and the latest date. Filled for the kind `dateRange`.
98
+ - `days` (`{ from: string; to: string } | null`): The days of `dates` as `YYYY-MM-DD`, in the zone of the column (the `timeZone` of its format options) or in local time: the days that a range of dates on this column is matched by.
99
+
100
+ ## ColumnFacetValue
101
+
102
+ - `value` (`unknown`): The value as the rows hold it.
103
+ - `text` (`string`): The value as text, as a cell of the column shows it.
104
+ - `count?` (`number`): How many rows hold the value.
105
+
106
+ ## ColumnTotal
107
+
108
+ - `value` (`unknown`): The total as a value.
109
+ - `text` (`string`): The total as text, with the format of the column.
110
+
111
+ ## CellEdit
112
+
113
+ - `rowId` (`string`): The id of the row of the cell.
114
+ - `columnId` (`string`): The id of the column of the cell.
115
+ - `row` (`Row`): The caller's own row object, as it is before the edit.
116
+ - `column` (`ColumnDef<Row>`): The definition of the column.
117
+ - `value` (`unknown`): The new value, after `parse` and the schema of the column.
118
+ - `previous` (`unknown`): The value of the cell before the edit.
119
+ - `formula?` (`string | null`): With formulas: the formula that the cell holds now (a text in the stored form), or `null` when its formula went. Not set for a value and for a result that followed from other cells.
120
+
121
+ ## CellRef
122
+
123
+ - `rowId` (`string`): The id of the row.
124
+ - `columnId` (`string`): The id of the column.
125
+
126
+ ## HistoryEntry
127
+
128
+ - `id` (`number`): The number of the step: the steps of a table count up from 1.
129
+ - `reason` (`Reason`): What made the step: the reason of its edit, `shortcut` or `formula`.
130
+ - `source` (`ChangeSource`): Who made it: a person with a key or a pointer, code, or an agent.
131
+ - `cells` (`number`): How many cells got a new value. 0 for a step of formats.
132
+ - `formats` (`boolean`): Whether the step changed formats and no value.
133
+ - `formulas` (`boolean`): Whether the step changed formulas.
@@ -0,0 +1,59 @@
1
+ # Export
2
+
3
+ The types of `exportData` and of the entry `ui-sdk-table-vue/export`.
4
+
5
+ See [Export](./export.md) for how they work together.
6
+
7
+ ## ExportOptions
8
+
9
+ What `controller.exportData(options)` takes.
10
+
11
+ - `rows?` (`'filtered' | 'page' | 'all' | 'selected'`): Which rows to take. `'filtered'` (the default) is every row that passes the filters, on all pages, in the order of the screen. `'page'` is the rows of the page in view. `'all'` is every row of the data, in the order of the data. `'selected'` is the selected rows, in sort order. A table with `manualPage` has one page of a server, so each set is of that page.
12
+ - `columns?` (`'visible' | 'all' | readonly string[]`): Which columns to take. `'visible'` (the default) is the columns on the screen in their order. `'all'` adds the hidden columns after them. A list of ids gives those columns in that order. A column with `exportable: false` is in none of them.
13
+ - `children?` (`boolean`): Whether the child rows of a tree row come with it, open or not. Defaults to true.
14
+ - `groups?` (`boolean`): Whether each group gets a row of its own before its rows, for `'filtered'` and `'page'`. Defaults to false. `'all'` and `'selected'` have no groups.
15
+ - `totals?` (`boolean`): Whether a last row holds totals. Defaults to false. For `'filtered'` and `'page'` they are the totals of the footer on the screen. For `'all'` and `'selected'` they are the totals of the rows in the file.
16
+
17
+ ## ExportData
18
+
19
+ - `columns` (`ExportColumn<Row>[]`): The columns of the export, in the order of the screen.
20
+ - `rows` (`ExportRow<Row>[]`): The rows of the export: rows of the data, group rows and the row of totals.
21
+ - `locale` (`string | undefined`): The `locale` of the table, which a writer uses for its numbers and dates.
22
+ - `document?` (`readonly string[]`): With formulas: the id of every row in the order of the document, for the ranges of the formulas.
23
+
24
+ ## ExportColumn
25
+
26
+ - `id` (`string`): The id of the column.
27
+ - `header` (`string`): The header text of the column.
28
+ - `column` (`ColumnDef<Row>`): The definition of the column.
29
+
30
+ ## ExportRow
31
+
32
+ - `kind` (`'row' | 'group' | 'total'`): `'row'`: a row of the data. `'group'`: a group row. `'total'`: the row of totals, with the `totals` option of the export.
33
+ - `row?` (`Row`): The row of the data, for a row of kind `'row'`.
34
+ - `level` (`number`): Tree and group levels above this row, from 0.
35
+ - `label?` (`string`): The name of a group, for a row of kind `'group'`. It is also in a cell: the first one without a total, or the first one before its total when every column has a total.
36
+ - `cells` (`ExportCell[]`): One cell for each column of the export.
37
+ - `id?` (`string`): With formulas: the id of a row of kind `'row'`, for the formulas that name it.
38
+
39
+ ## ExportCell
40
+
41
+ - `value` (`unknown`): The value of the cell, as the row has it.
42
+ - `text` (`string`): The text of the cell, as a person sees it on the screen.
43
+ - `format?` (`CellFormat`): The format that the cell has of its own, from the `cellFormats` of the table.
44
+ - `formula?` (`string`): With formulas: the formula of the cell, or of its column, in the stored form.
45
+
46
+ ## CsvOptions
47
+
48
+ - `separator?` (`string`): The text between two cells. Defaults to a comma.
49
+ - `lineEnd?` (`string`): The text between two rows. Defaults to `\r\n`, as RFC 4180 says.
50
+ - `header?` (`boolean`): Whether the first row holds the header texts. Defaults to true.
51
+ - `bom?` (`boolean`): Whether the text starts with a byte order mark. Defaults to true: without it, Excel reads a UTF-8 file in the code page of the computer.
52
+ - `escapeFormulas?` (`boolean`): Whether a text that a spreadsheet would read as a formula gets a `'` before it. Defaults to true. A cell that a person typed can otherwise run a formula on the computer of the person who opens the file.
53
+
54
+ ## XlsxOptions
55
+
56
+ - `sheetName?` (`string`): The name of the sheet. Defaults to `Sheet1`.
57
+ - `freezeHeader?` (`boolean`): Whether the header row stays in view while the rows scroll. Defaults to true.
58
+ - `compress?` (`boolean`): Whether the file is compressed, where the environment can do that. Defaults to true.
59
+ - `formula?` (`XlsxFormulas`): Writes the formulas of the cells as formulas of the file, with the result beside each: `excelFormulas()` of the entry `ui-sdk-table-core/formulas`. Without it, a cell holds its result.
@@ -0,0 +1,39 @@
1
+ # Formulas
2
+
3
+ The types of the entry `ui-sdk-table-vue/formulas`.
4
+
5
+ See [Formulas](./sheet-formulas.md) for how they work together.
6
+
7
+ ## FormulaEngineOptions
8
+
9
+ What `createFormulaEngine(options)` takes.
10
+
11
+ - `timeZone?` (`string`): The zone of a date that is no reference to a column with a zone of its own (`formatOptions.timeZone`), such as a date that a function gives. Without it, local time: a result that is saved should not depend on the computer that made it, so pass one when a formula reads a moment.
12
+ - `now?` (`() => number`): The clock of `TODAY` and `NOW`, in milliseconds since 1970: `Date.now` by default. A test passes a clock of its own.
13
+ - `maxReads?` (`number`): The most cells that one change may read, 5,000,000 by default. A formula in each row that sums from the first row to its own reads the square of the rows; past the limit the change is refused with words.
14
+
15
+ ## CellFormulas
16
+
17
+ The value of `cellFormulas`.
18
+
19
+ - `columns?` (`Readonly<Record<string, string>>`): The formula of each computed column, by column id, in the stored form.
20
+ - `cells?` (`Readonly<Record<string, Readonly<Record<string, string>>>>`): The formula of each cell, by row id and column id, in the stored form.
21
+
22
+ ## FormulaBar
23
+
24
+ What `useFormulaBar(controller)` gives.
25
+
26
+ - `address` (`ComputedRef<string>`): The address of the cell, such as `D7`, or `''` without an active cell.
27
+ - `text` (`ComputedRef<string>`): The text of the field: the draft while a person types, else the formula or the value of the cell.
28
+ - `error` (`ComputedRef<string>`): Why the last commit was refused, in the words for a person, or `''`.
29
+ - `dirty` (`ComputedRef<boolean>`): Whether the text is a draft that is not saved.
30
+ - `ready` (`ComputedRef<boolean>`): Whether a cell is active, so the field can be used.
31
+ - `input` (`(text: string) => void`): The new text of the field.
32
+ - `commit` (`() => boolean`): Saves the draft into its cell, as the editor of the cell does. Returns whether it was saved.
33
+ - `cancel` (`() => void`): Drops the draft and the error.
34
+
35
+ ## FormulaFunctionInfo
36
+
37
+ - `name` (`string`): The name of the function, such as `SUM`.
38
+ - `args` (`string`): Its arguments as a person writes them, such as `number, ...`.
39
+ - `help` (`string`): One line that says what it gives.