ui-sdk-table-vue 0.2.0 → 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
@@ -42,6 +42,16 @@ Start with [llms.txt](./llms.txt): what the library is and the conventions every
42
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
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
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
+
45
55
  ## Source and licence
46
56
 
47
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.
@@ -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).
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
@@ -301,3 +303,13 @@ The rules of a scoped style reach the elements of the table through `:deep()`, b
301
303
 
302
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.
303
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.
@@ -0,0 +1,55 @@
1
+ # Messages
2
+
3
+ Every text that the table writes itself, for the `messages` prop.
4
+
5
+ Pass the texts that you change; the others keep the English words of `defaultMessages`. Each text is a function, so a language can put the parts in its own order.
6
+
7
+ ## TableMessages
8
+
9
+ - `formulaIssue?` (`(issue: FormulaIssue) => string`): The words for an issue of a formula. Without it, the words of the engine: a table without formulas carries none.
10
+ - `formulaError?` (`(code: FormulaError) => string`): Why a formula gives an error value, for the description of its cell. Without it, the words of the engine.
11
+ - `recalculated?` (`(details: { cells: number }) => string`): What the table says after `recalculate()`: how many cells got new values. Without it, the words of the engine.
12
+ - `noRows` (`() => string`): What the body says when no row passes the filters.
13
+ - `loading` (`() => string`): What the body says while the first rows are on their way.
14
+ - `expandRow` (`() => string`): The name of the button that opens a row with child rows or a detail row.
15
+ - `collapseRow` (`() => string`): The name of the button that closes such a row.
16
+ - `expandSign` (`() => string`): The sign on the button of a closed row.
17
+ - `collapseSign` (`() => string`): The sign on the button of an open row.
18
+ - `groupRow` (`(details: { text: string; count: number }) => string`): The text of a group row: the value of the group and how many rows it holds.
19
+ - `resizeColumn` (`(column: string) => string`): The name of the resize handle of a column.
20
+ - `columnResized` (`(details: { column: string; width: number }) => string`): What a screen reader says after a column gets a new width.
21
+ - `columnMoved` (`(details: ColumnReorderMessage) => string`): What a screen reader says while a column moves.
22
+ - `editCell` (`(details: { column: string }) => string`): The name of the text field that edits a cell.
23
+ - `notNumber` (`(text: string) => string`): Why a text is refused in a column of numbers.
24
+ - `notDate` (`(text: string) => string`): Why a text is refused in a cell that holds a date.
25
+ - `notBoolean` (`(text: string) => string`): Why a text is refused in a cell that holds true or false.
26
+ - `invalidValue` (`() => string`): Why a value is refused when its schema gives no message.
27
+ - `editRefused` (`() => string`): Why an edit is refused when a listener of `onCellEdit` cancels it.
28
+ - `cellsSelected` (`(details: { rows: number; columns: number }) => string`): What a screen reader says after the range of cells changed from the keyboard.
29
+ - `cellsCopied` (`(details: { cells: number }) => string`): What a screen reader says after a copy.
30
+ - `cellsPasted` (`(details: { cells: number }) => string`): What a screen reader says after a paste.
31
+ - `pasteRefused` (`(details: { column: string; text: string; message: string }) => string`): Why a paste did nothing: one of its values was refused.
32
+ - `pasteNowhere` (`() => string`): Why a paste did nothing: no cell under it can be edited.
33
+ - `pasteTooLarge` (`(details: { rows: number; columns: number }) => string`): Why a paste did nothing: the text has more rows or columns than the table has from the first cell on.
34
+ - `pasteOverRow` (`() => string`): Why a paste did nothing: a row under it is a group row or a detail row, which holds no values.
35
+ - `editRowGone` (`() => string`): Why an edit was not saved: its row left the table while the value was checked.
36
+ - `cellsCleared` (`(details: { cells: number }) => string`): What a screen reader says after Delete or `clearCells` emptied cells.
37
+ - `cellsCut` (`(details: { cells: number }) => string`): What a screen reader says after a cut.
38
+ - `clearRefused` (`(details: { column: string; message: string }) => string`): Why a clear or a cut did nothing: a column refuses an empty value.
39
+ - `clearNowhere` (`() => string`): Why a clear or a cut did nothing: no cell under it can be edited.
40
+ - `undone` (`(details: { cells: number; gone: number; hidden: number }) => string`): What a screen reader says after an undo. `cells` got their old value back, `gone` of the step are not in the table any more, and `hidden` of the cells that changed are not in view: a filter, a page or a closed row hides them.
41
+ - `redone` (`(details: { cells: number; gone: number; hidden: number }) => string`): What a screen reader says after a redo.
42
+ - `undoRefused` (`() => string`): Why an undo or a redo did nothing: a listener of `onCellEdit` refused it.
43
+ - `nothingToUndo` (`() => string`): Why an undo did nothing: the history has no step to take back.
44
+ - `nothingToRedo` (`() => string`): Why a redo did nothing: the history has no step to bring back.
45
+ - `historyBusy` (`() => string`): Why an undo or a redo must wait: the check of a new value runs.
46
+ - `historyTooLarge` (`(details: { cells: number }) => string`): What a screen reader says when one change holds more cells than the history keeps, so it cannot be undone.
47
+ - `rowNumber` (`(details: { number: number }) => string`): The name of the header of a row: its number, from 1. A screen reader says it with each cell of the row.
48
+ - `cornerCell` (`() => string`): The name of the corner cell of the row of letters, which selects every cell.
49
+ - `cellsFilled` (`(details: { cells: number }) => string`): What a screen reader says after a fill.
50
+ - `fillRefused` (`(details: { column: string; text: string; message: string }) => string`): Why a fill did nothing: a column refuses one of its values.
51
+ - `fillNowhere` (`() => string`): Why a fill did nothing: no cell under it can be edited.
52
+ - `fillOverPinned` (`() => string`): Why a fill did nothing: it would go from pinned rows to rows of the list, which are no neighbours in the data.
53
+ - `cellsFormatted` (`(details: { cells: number }) => string`): What a screen reader says after the formats of cells changed from a key or from code.
54
+ - `aggregateLabel` (`(name: string) => string`): The name of a function of the sum row, for a picker and for the name of a footer cell: `sum`, `mean`, `min`, `max`, `count`, `uniqueCount`, `first`, or `custom` for a function of the column.
55
+ - `totalLabel` (`(details: { label: string; text: string }) => string`): The name of a footer cell whose function a person chose: the function and the total.
@@ -0,0 +1,244 @@
1
+ # Table
2
+
3
+ Every prop, event and slot of `Table`, with the props that each slot gets.
4
+
5
+ Props are written in camel case here; a template takes them in kebab case (`default-sort`). Each state has three members: `<key>` controls it, `default<Key>` starts it when the table holds it, and the event `<key>Change` (`@sort-change`) reports a change that `details.cancel()` can stop. `v-model:<key>` binds the first and `update:<key>`. See [State and events](./state-and-events.md).
6
+
7
+ ## Props
8
+
9
+ - `rows?` (`readonly Row[]`): The rows of the table. Each row needs a stable id (see `getRowId`). The table never changes or copies a row.
10
+ - `columns?` (`readonly ColumnDef<Row>[]`): The columns, in the order of the definitions. A column with `columns` is a header group.
11
+ - `getRowId?` (`(row: Row, index: number, parent: DataRow<Row> | null) => string | number`): A stable id for a row. Without it, the `id` property of the row is used.
12
+ - `getChildren?` (`(row: Row) => readonly Row[] | undefined`): The child rows of a row. With it, the table is a tree.
13
+ - `locale?` (`string`): The locale of the texts that the table writes: numbers, dates, the search without case, and the signs of a formula that a person types. Without it, the formats use `en-US`. A format whose `formatOptions` has a `locale` keeps its own.
14
+ - `searchMode?` (`'contains' | 'fuzzy'`): How the search matches. `'contains'` (the default): the text of a cell holds the search, without case. `'fuzzy'`: the letters of the search are in the text in order.
15
+ - `fuzzyThreshold?` (`number`): With `searchMode: 'fuzzy'`, the score that a match must pass, from 0 to 1. Defaults to 0: every match in order passes.
16
+ - `sortChildren?` (`boolean`): Also sort the tree children of each row. Defaults to true.
17
+ - `canGroup?` (`(row: Row) => boolean`): Which rows go into groups. A row that it refuses stays out of every group and comes first, before the groups.
18
+ - `selection?` (`'single' | 'multiple'`): Row selection. Without it, rows cannot be selected.
19
+ - `canSelect?` (`(row: Row) => boolean`): Which rows can be selected. A row that it refuses has no selection, and `select` throws for it.
20
+ - `resizable?` (`boolean`): Whether a person can resize columns. A column can say otherwise. Defaults to false.
21
+ - `reorderable?` (`boolean`): Whether a person can move columns. A column can say otherwise. Defaults to false.
22
+ - `columnMinWidth?` (`number`): The smallest width of a column that has no `minWidth`, in pixels. Defaults to 48.
23
+ - `columnMaxWidth?` (`number`): The largest width of a column that has no `maxWidth`, in pixels. Without it, no limit.
24
+ - `messages?` (`Partial<TableMessages>`): Texts of the table in another language, or with other words.
25
+ - `controller?` (`TableController`): Gives the actions of the table to code outside it. Create one with `createTableController()`.
26
+ - `multiSort?` (`MultiSortMode`): Whether a press on a header can add its column to the sort. `'none'`: one column at a time, and a modifier key changes nothing. `'modifier'` (the default): a press with Shift, Control or Command adds the column. `'always'`: each press adds the column. Enter on a header follows the same rule. A `sort` that the owner sets is never cut to the mode.
27
+ - `alwaysSorted?` (`boolean`): Whether the table keeps a sort once it has one. With it, a press on the only column of the sort turns the order, ascending and descending, and never takes the sort away. Without it, the third press does. Defaults to false. It does not sort a table that starts without a sort; give `defaultSort` for that.
28
+ - `searchDebounce?` (`number`): How long the typing in a search field must pause before the table filters, in milliseconds, for a text from `inputSearch`. Defaults to 200. With 0, each text filters at once.
29
+ - `groupTotals?` (`boolean`): Whether a group row shows the total of each column in a cell under that column, as the footer does. The label of the group then covers the columns before the first total. It applies while a column in view has an `aggregate`; without one, and with `false`, a group row is one cell as wide as the table. Defaults to true.
30
+ - `totals?` (`TableTotalsSource`): Totals as the owner of the rows knows them. The footer, the group rows, `getTotals` and the totals of an export show them in place of what the rows of the table give. For rows from a server: the table has one page of them, and its own totals are of that page.
31
+ - `sort?` (`readonly SortRule[]`): The sort: the columns in the order in which they sort. Pass it to control the sort.
32
+ - `defaultSort?` (`readonly SortRule[]`): The `sort` at first, when the table holds this state itself.
33
+ - `filter?` (`FilterState`): The search and the filter of each column. Pass it to control the filter.
34
+ - `defaultFilter?` (`FilterState`): The `filter` at first, when the table holds this state itself.
35
+ - `groupBy?` (`readonly string[]`): The ids of the columns that group the rows, outermost first. Pass it to control the groups.
36
+ - `defaultGroupBy?` (`readonly string[]`): The `groupBy` at first, when the table holds this state itself.
37
+ - `page?` (`PageState`): With a page, the table shows one page of rows. Without it, all rows.
38
+ - `defaultPage?` (`PageState`): The `page` at first, when the table holds this state itself.
39
+ - `expanded?` (`readonly string[]`): The ids of the expanded tree rows and groups.
40
+ - `defaultExpanded?` (`readonly string[]`): The `expanded` at first, when the table holds this state itself.
41
+ - `selected?` (`string[]`): The ids of the selected rows.
42
+ - `defaultSelected?` (`string[]`): The `selected` at first, when the table holds this state itself.
43
+ - `columnVisibility?` (`ColumnVisibility`): Columns with `false` are hidden. The id of a header group hides all its columns.
44
+ - `defaultColumnVisibility?` (`ColumnVisibility`): The `columnVisibility` at first, when the table holds this state itself.
45
+ - `columnOrder?` (`readonly string[]`): Column ids in display order. Columns that are not listed come after, in definition order.
46
+ - `defaultColumnOrder?` (`readonly string[]`): The `columnOrder` at first, when the table holds this state itself.
47
+ - `columnWidths?` (`ColumnWidths`): Column widths in pixels, by column id. A column without an entry has the width of its definition.
48
+ - `defaultColumnWidths?` (`ColumnWidths`): The `columnWidths` at first, when the table holds this state itself.
49
+ - `columnPinning?` (`ColumnPinning`): The columns that stay at the start or the end edge while the rest scrolls.
50
+ - `defaultColumnPinning?` (`ColumnPinning`): The `columnPinning` at first, when the table holds this state itself.
51
+ - `rowWindow?` (`boolean`): Render only the rows near the scroll frame, with a spacer for the rest. The frame is the nearest parent that scrolls, or the page. Defaults to false.
52
+ - `rowHeight?` (`number`): One height for every row, in pixels. Without it, the row window measures each row. With `hasDetail` it measures too, because a detail row has a height of its own, and this height is what a row counts with before.
53
+ - `estimatedRowHeight?` (`number`): The height of a row that the row window did not measure yet, in pixels. Defaults to 36.
54
+ - `overscan?` (`number`): How many rows more than the frame shows the row window renders on each side. Defaults to 8.
55
+ - `stickyHeader?` (`boolean`): Whether the header rows stay at the top of the scroll frame. Defaults to false.
56
+ - `stickyFooter?` (`boolean`): Whether the footer row stays at the bottom of the scroll frame. Defaults to false.
57
+ - `hasDetail?` (`(row: Row) => boolean`): Which rows have a detail row: one wide row under the row, which opens and closes as a tree row does. Pass the same function while its answers are the same: a new function makes the table list its rows again.
58
+ - `rowPinning?` (`RowPinning`): The rows that stay at the top or the bottom edge. A filter or a page does not hide them. The totals are of the rows that pass the filter, so a pinned row that the filter refuses is in view and not in the totals. A row with child rows cannot be pinned.
59
+ - `defaultRowPinning?` (`RowPinning`): The `rowPinning` at first, when the table holds this state itself.
60
+ - `columnAggregates?` (`ColumnAggregates`): The function of the total of a column where a person chose one, by column id: `sum`, `mean`, `min`, `max`, `count`, `uniqueCount` or `first`. An entry wins over the `aggregate` of the column, and `null` takes the total of the column away. The footer, the group rows, `getTotals` and an export all follow it. With `totals` of the owner, the owner hears the change and gives the number of the chosen function.
61
+ - `defaultColumnAggregates?` (`ColumnAggregates`): The `columnAggregates` at first, when the table holds this state itself.
62
+ - `cellFormats?` (`CellFormats`): The formats of cells and of whole columns: how a value becomes text and how the cell looks, by row id and column id. A property of a cell wins over the same property of its column, and both win over the `format` of the column definition. The looks reach a cell as `data-align`, `data-bold`, `data-italic`, `data-color` and `data-fill`, and the style of the app gives them a meaning. The value is reported whole and shares what did not change, so an owner saves it as it is. Colour alone must not carry a meaning: a screen reader says the text of a cell, not its looks.
63
+ - `defaultCellFormats?` (`CellFormats`): The `cellFormats` at first, when the table holds this state itself.
64
+ - `formulas?` (`FormulaEngine`): Turns formulas on: the value of `createFormulaEngine()` of the entry `ui-sdk-table-core/formulas`. Pass one engine for the life of the table; a new engine at each render computes every formula again.
65
+ - `cellFormulas?` (`CellFormulas`): The formulas of the table, as data of the owner, in the stored form. `columns` makes a column computed: each row gets the value of the formula, also a row that comes later, and its cells cannot be edited. A formula that cannot be read, or column formulas that read each other in a circle, show an error in every row. Read only with `formulas`.
66
+ - `defaultCellFormulas?` (`CellFormulas`): The `cellFormulas` at first, when the table holds this state itself.
67
+ - `formatColors?` (`readonly string[]`): The names that `color` and `fill` of a cell format can have, such as `['red', 'amber', 'green']`. The table writes a name into `data-color` or `data-fill`, and the style of the app maps it to its own colours for light and dark. Without the option, a format can carry no colour.
68
+ - `sheet?` (`boolean`): The rules of a data sheet. In the editor, Enter saves and moves down (with Shift up), and an arrow key saves and moves when a character opened the editor. Inside a selected range, Enter and Tab walk the range and Tab on a cell stays in it; without a range, Tab on a cell leaves the table as before. Delete and Backspace empty the selected cells, a cut empties them too, and a paste repeats a block that fits the range a whole number of times. It is also a preset: `editable`, `cellSelection` and `history` are on unless one of them is set to false. Defaults to false.
69
+ - `history?` (`boolean | TableHistoryOptions`): Undo and redo for cell values: Control or Command with Z, and with Shift+Z or Y, on a cell, and `undo` and `redo` of the controller. A step is one report of `onCellEdit` that no listener refused. An undo reports the old values through `onCellEdit` with the reason `undo`, without `parse` and without the schema, and the owner of the rows puts them in. Rows need stable ids for it. With `manualPage`, a change of the page, the sort or the filter empties the history. Pass limits in place of `true` to change them. Defaults to the `sheet` option.
70
+ - `fillHandle?` (`boolean | 'vertical' | 'horizontal'`): The fill handle: a small part at the corner of the selected cells that a person drags to fill more cells, and with `sheet` the keys Control+D (fill down) and Control+R (fill forward). `'vertical'` and `'horizontal'` let a fill go along one axis only. Needs cell selection. Defaults to the `sheet` option.
71
+ - `editable?` (`boolean`): Whether a person can edit cells. A column can say otherwise. Defaults to the `sheet` option, else to `entry`.
72
+ - `entry?` (`boolean`): A mode for entering data, which an app can turn on and off, for example with an Edit button. While it is on, cells can be edited unless `editable` is false or a column says otherwise, one plain press on a cell opens its editor, and Tab and Shift+Tab on a cell and in the editor go to the next and the previous cell that can be edited, across the rows. From the last such cell Tab leaves the table, and from the first Shift+Tab. Inside a selected range of more than one cell, Tab keeps the rule of the range. Defaults to false.
73
+ - `cellSelection?` (`boolean`): Whether a person can select a range of cells, to copy it or to paste into it. Defaults to the `sheet` option.
74
+ - `columnLetters?` (`boolean`): A row of letters above the header rows, as a spreadsheet has: A, B, C, then AA. It is the place where a person selects whole columns, as the row numbers of `rowNumberColumn()` are for whole rows: 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. Space on a letter selects its column, and Shift with an arrow takes the next columns. The cell above the row numbers selects every cell. A column that leads the table has an empty letter cell that selects nothing. A letter is the place of the column among the columns in view. The row is grid row 0: it counts in `aria-rowindex`, `aria-rowcount` and the rows of `cellRange`, and it sticks with `stickyHeader`. An export does not hold it. Selecting needs `cellSelection`; this option is not part of `sheet`. Defaults to false.
75
+ - `cellRange?` (`CellRange | null`): The selected range of cells, from the cell where it started to the cell it reaches, or `null`. A cell is a place in the grid: `row` counts the header rows first, as `aria-rowindex` does, from 0. A range holds body rows only. It goes away when other rows or columns come to its places.
76
+ - `defaultCellRange?` (`CellRange | null`): The `cellRange` at first, when the table holds this state itself.
77
+ - `manualSort?` (`boolean`): The rows come from a server in sort order. The table does not sort them. The `sort` state still changes, so the caller knows what to ask for.
78
+ - `manualFilter?` (`boolean`): The rows come from a server with the search and the column filters applied. The table does not filter them. Facets and totals are of the rows that the table has; give `facets` for the choices of every row, and `totals` for the totals of every row.
79
+ - `facets?` (`Readonly<Record<string, ColumnFacetsSource>>`): The facets of columns as the owner of the rows knows them, by column id. `getFacets` answers with them in place of what the rows of the table hold. A server that filters knows every value of a column; the rows that it sends hold only the values that pass.
80
+ - `manualPage?` (`boolean`): The rows are one page from a server. The table shows them all, and the pages come from `rowCount`. Every other feature works on the rows that the table has: an export, the totals and "select all" are of this page. Give `totals` for the totals that the server knows.
81
+ - `rowCount?` (`number`): How many rows the server has after its filter, for `manualPage`. Without it, a full page has a next page and a page that is not full is the last. An empty page after the first then sends the table one page back, so keep the rows of the page before, or set `loading`, while a page loads. `lastPage` needs the count.
82
+ - `loading?` (`boolean`): Whether new rows are on their way. The table says so to assistive technology and keeps its rows.
83
+ - `rowAttrs?` (`(context: RowAttrsContext<Row>) => PartAttrs | undefined`): Attributes of a `tr` element.
84
+ - `cellAttrs?` (`(context: CellAttrsContext<Row>) => PartAttrs | undefined`): Attributes of a `th` or `td` element.
85
+ - `sectionAttrs?` (`{ head?: PartAttrs; body?: PartAttrs; foot?: PartAttrs }`): Attributes of the `thead`, `tbody` and `tfoot` elements.
86
+
87
+ ## Events
88
+
89
+ - `update:sort` (`(value: readonly SortRule[]) => void`): The new `sort`, for `v-model:sort`. It does not run when `sortChange` cancels the change.
90
+ - `update:filter` (`(value: FilterState) => void`): The new `filter`, for `v-model:filter`. It does not run when `filterChange` cancels the change.
91
+ - `update:groupBy` (`(value: readonly string[]) => void`): The new `groupBy`, for `v-model:groupBy`. It does not run when `groupByChange` cancels the change.
92
+ - `update:page` (`(value: PageState | undefined) => void`): The new `page`, for `v-model:page`. It does not run when `pageChange` cancels the change.
93
+ - `update:expanded` (`(value: readonly string[]) => void`): The new `expanded`, for `v-model:expanded`. It does not run when `expandedChange` cancels the change.
94
+ - `update:selected` (`(value: string[]) => void`): The new `selected`, for `v-model:selected`. It does not run when `selectedChange` cancels the change.
95
+ - `update:columnVisibility` (`(value: ColumnVisibility) => void`): The new `columnVisibility`, for `v-model:columnVisibility`. It does not run when `columnVisibilityChange` cancels the change.
96
+ - `update:columnOrder` (`(value: readonly string[]) => void`): The new `columnOrder`, for `v-model:columnOrder`. It does not run when `columnOrderChange` cancels the change.
97
+ - `update:columnWidths` (`(value: ColumnWidths) => void`): The new `columnWidths`, for `v-model:columnWidths`. It does not run when `columnWidthsChange` cancels the change.
98
+ - `update:columnPinning` (`(value: ColumnPinning) => void`): The new `columnPinning`, for `v-model:columnPinning`. It does not run when `columnPinningChange` cancels the change.
99
+ - `update:rowPinning` (`(value: RowPinning) => void`): The new `rowPinning`, for `v-model:rowPinning`. It does not run when `rowPinningChange` cancels the change.
100
+ - `update:columnAggregates` (`(value: ColumnAggregates) => void`): The new `columnAggregates`, for `v-model:columnAggregates`. It does not run when `columnAggregatesChange` cancels the change.
101
+ - `update:cellFormats` (`(value: CellFormats) => void`): The new `cellFormats`, for `v-model:cellFormats`. It does not run when `cellFormatsChange` cancels the change.
102
+ - `update:cellFormulas` (`(value: CellFormulas) => void`): The new `cellFormulas`, for `v-model:cellFormulas`. It does not run when `cellFormulasChange` cancels the change.
103
+ - `update:cellRange` (`(value: CellRange | null) => void`): The new `cellRange`, for `v-model:cellRange`. It does not run when `cellRangeChange` cancels the change.
104
+ - `sortChange` (`(value: readonly SortRule[], details: TableChangeDetails) => void`): Runs when `sort` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
105
+ - `filterChange` (`(value: FilterState, details: TableChangeDetails) => void`): Runs when `filter` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
106
+ - `groupByChange` (`(value: readonly string[], details: TableChangeDetails) => void`): Runs when `groupBy` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
107
+ - `pageChange` (`(value: PageState | undefined, details: TableChangeDetails) => void`): Runs when `page` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
108
+ - `expandedChange` (`(value: readonly string[], details: TableChangeDetails) => void`): Runs when `expanded` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
109
+ - `selectedChange` (`(value: string[], details: TableChangeDetails) => void`): Runs when `selected` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
110
+ - `columnVisibilityChange` (`(value: ColumnVisibility, details: TableChangeDetails) => void`): Runs when `columnVisibility` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
111
+ - `columnOrderChange` (`(value: readonly string[], details: TableChangeDetails) => void`): Runs when `columnOrder` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
112
+ - `columnWidthsChange` (`(value: ColumnWidths, details: TableChangeDetails) => void`): Runs for each step of a resize.
113
+ - `columnWidthsCommit` (`(value: ColumnWidths, details: TableCommitDetails) => void`): Runs once when a resize ends: on release of the handle, and after each key.
114
+ - `columnPinningChange` (`(value: ColumnPinning, details: TableChangeDetails) => void`): Runs when `columnPinning` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
115
+ - `rowPinningChange` (`(value: RowPinning, details: TableChangeDetails) => void`): Runs when `rowPinning` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
116
+ - `columnAggregatesChange` (`(value: ColumnAggregates, details: TableChangeDetails) => void`): Runs when `columnAggregates` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
117
+ - `cellFormatsChange` (`(value: CellFormats, details: TableChangeDetails) => void`): Runs when `cellFormats` wants to change, with the new value and its details. `details.reason` says why, and `details.cancel()` keeps the old value.
118
+ - `cellFormulasChange` (`(value: CellFormulas, details: TableChangeDetails) => void`): A formula that a person entered changes with the reason of the edit (`enter-key`, `paste`).
119
+ - `cellRangeChange` (`(value: CellRange | null, details: TableChangeDetails) => void`): Runs for each step of a drag, and for each other change of the range.
120
+ - `cellRangeCommit` (`(value: CellRange | null, details: TableCommitDetails) => void`): Runs once when a drag that changed the range ends.
121
+ - `cellEdit` (`(edits: readonly CellEdit<any>[], details: TableEditDetails) => void`): Cells got new values. Put them into the rows; `details.cancel()` refuses them.
122
+
123
+ ## Slots
124
+
125
+ A slot with a column id in its name wins over the slot without one.
126
+
127
+ - `header-{id}?` (`(props: HeaderSlotProps<Row>) => VNodeChild`): One header cell. `header-{column id}` wins over `header`.
128
+ - `col-{id}?` (`(props: CellSlotProps<Row>) => VNodeChild`): One body cell. `col-{column id}` wins over `cell`.
129
+ - `foot-{id}?` (`(props: FootSlotProps<Row>) => VNodeChild`): One total in the footer. `foot-{column id}` wins over `foot`.
130
+ - `group-total-{id}?` (`(props: GroupTotalSlotProps<Row>) => VNodeChild`): The cell of a group row under one column, which holds the total of the group for that column. `group-total-{column id}` wins over `group-total`.
131
+ - `edit-{id}?` (`(props: EditorSlotProps<Row>) => VNodeChild`): The editor of one cell, in place of the text field of the table. `edit-{column id}` wins over `editor`. The control must take focus itself.
132
+ - `editor?` (`(props: EditorSlotProps<Row>) => VNodeChild`): The editor of a cell, in place of the text field of the table. The control must take focus itself.
133
+ - `header?` (`(props: HeaderSlotProps<Row>) => VNodeChild`): One header cell, for every column without a `header-{column id}` slot.
134
+ - `cell?` (`(props: CellSlotProps<Row>) => VNodeChild`): One body cell, for every column without a `col-{column id}` slot.
135
+ - `foot?` (`(props: FootSlotProps<Row>) => VNodeChild`): One total in the footer, for every column without a `foot-{column id}` slot.
136
+ - `group?` (`(props: GroupSlotProps<Row>) => VNodeChild`): The label cell of a group row.
137
+ - `group-total?` (`(props: GroupTotalSlotProps<Row>) => VNodeChild`): The cell of a group row under one column, for every column without a `group-total-{column id}` slot.
138
+ - `row-header?` (`(props: RowHeaderSlotProps<Row>) => VNodeChild`): The cell with the number of a row, in a column with `rowHeader`.
139
+ - `letter?` (`(props: LetterSlotProps<Row>) => VNodeChild`): A cell of the row of letters, with the `columnLetters` option. Without it, the cell shows the letter.
140
+ - `detail?` (`(props: DetailSlotProps<Row>) => VNodeChild`): The detail row of a row, for the rows that `hasDetail` names.
141
+ - `empty?` (`() => VNodeChild`): Shown in place of the rows when no row passes the filters.
142
+ - `loading?` (`() => VNodeChild`): Shown in place of the rows while `loading` is set and the table has no rows.
143
+
144
+ ## Slot props
145
+
146
+ ### HeaderSlotProps
147
+
148
+ - `column` (`ColumnDef<Row>`): The definition of the column.
149
+ - `label` (`string`): The header text: `column.header`, or the column id.
150
+ - `leaf` (`boolean`): False for a header group, which holds columns and no cells.
151
+ - `sort` (`SortDirection | undefined`): The direction of the column in the sort, `'asc'` or `'desc'`, or `undefined` when it does not sort.
152
+ - `sortIndex` (`number | undefined`): The place of the column in the sort, from 1. With several columns in the sort, the first one sorts first.
153
+ - `toggleSort` (`(event?: Event) => void`): Sorts by the column as a press on the header does. Pass the event: with `multiSort`, its keys decide whether the column joins the sort.
154
+ - `pin` (`'start' | 'end' | undefined`): The edge that the column is pinned to, or `undefined`.
155
+ - `selectColumn` (`(event?: Event) => void`): Selects the cells of the column, for a control in its header. With Shift in the event, the columns from the active cell to this one. It throws for a header group and without the `cellSelection` option.
156
+ - `formula` (`string | undefined`): The formula of a computed column, as a person reads it. `undefined` for a column without one.
157
+
158
+ ### CellSlotProps
159
+
160
+ - `row` (`Row`): The row object of the data, as the owner passed it.
161
+ - `node` (`DataRow<Row>`): The node of the row in the row model: its id, its parent and its children.
162
+ - `column` (`ColumnDef<Row>`): The definition of the column.
163
+ - `value` (`unknown`): The value of the cell: `value` of the column, else the property that `key` names.
164
+ - `text` (`string`): The value as text, with the format of the cell, else of its column.
165
+ - `format` (`CellFormat | undefined`): The format that the cell has of its own, from `cellFormats`: the format of its column with the format of the cell over it. `undefined` when neither says anything. Its looks are also on the cell as `data-align`, `data-bold`, `data-italic`, `data-color` and `data-fill`.
166
+ - `selected` (`boolean`): Whether the row is selected.
167
+ - `expanded` (`boolean`): Whether the row is open: its child rows or its detail row show.
168
+ - `expandable` (`boolean`): Whether the row can open: it has child rows or a detail row.
169
+ - `level` (`number`): Tree and group levels above this row, from 0.
170
+ - `pinned` (`RowPin | undefined`): The edge that the row is pinned to.
171
+ - `toggleSelected` (`(event?: Event) => void`): Selects the row or takes it out of the selection, for a checkbox in the cell.
172
+ - `toggleExpanded` (`(event?: Event) => void`): Opens or closes the row, for a button in the cell.
173
+ - `formula` (`{ text: string; error?: { code: FormulaError; message: string } } | undefined`): With formulas: the formula of the cell as a person reads it, and the code and the words of an error value. `undefined` for a cell with neither. The error is also on the cell as `data-formula-error`.
174
+
175
+ ### EditorSlotProps
176
+
177
+ - `row` (`Row`): The row object of the data, as the owner passed it.
178
+ - `node` (`DataRow<Row>`): The node of the row in the row model: its id, its parent and its children.
179
+ - `column` (`ColumnDef<Row>`): The definition of the column.
180
+ - `value` (`unknown`): The value of the cell now.
181
+ - `text` (`string`): The value as plain text, without a format: 0.25 for a cell that shows 25 %. `save` takes a value.
182
+ - `error` (`string | undefined`): Why the last value was refused.
183
+ - `checking` (`boolean`): A check that takes time runs for a saved value. A save does nothing until it answers.
184
+ - `mode` (`'replace' | 'edit'`): How the editor was opened. `replace`: the person typed a character on the cell, which is `typed`, and means to write over the value. `edit`: Enter, F2, a double press or code opened it, to change the value.
185
+ - `typed` (`string | undefined`): The character that opened the editor, or `undefined`.
186
+ - `save` (`(value: unknown, event?: Event) => void`): Saves a value, with the check of the column, and closes the editor. A value that is refused keeps the editor open, and `error` says why.
187
+ - `cancel` (`() => void`): Closes the editor without a save. Focus goes back to the cell.
188
+ - `formula` (`string | undefined`): With formulas: the formula of the cell as a person reads it, such as `=C2*D2`. A save of a text that starts with `=` sets a formula.
189
+ - `inputMode` (`'decimal' | undefined`): `decimal` when a field of numbers should ask a phone for its number keyboard (`numberKeyboard` of the column), else `undefined`. Put it on the field as `inputmode`.
190
+
191
+ ### GroupSlotProps
192
+
193
+ - `group` (`GroupRow<Row>`): The group: its id, the column and the value that make it, and its rows.
194
+ - `column` (`ColumnDef<Row> | undefined`): The column that makes the group.
195
+ - `text` (`string`): The value of the group as text, with the format of its column.
196
+ - `expanded` (`boolean`): Whether the group is open.
197
+ - `level` (`number`): The groups above this one, from 0.
198
+ - `totals` (`Record<string, unknown>`): Column totals of the rows in the group.
199
+ - `totalTexts` (`Record<string, string>`): The totals as text, with the format of their columns, by column id.
200
+ - `path` (`readonly GroupPathEntry<Row>[]`): The groups from the outermost one down to this group, each with its column, its value and its text: "Europe", then "Finland".
201
+ - `covered` (`readonly ColumnDef<Row>[]`): The columns that this cell covers. With totals under their columns, a total of one of these columns has no cell of its own.
202
+ - `toggleExpanded` (`(event?: Event) => void`): Opens or closes the group, for a button in the cell.
203
+
204
+ ### GroupTotalSlotProps
205
+
206
+ - `group` (`GroupRow<Row>`): The group of the row.
207
+ - `column` (`ColumnDef<Row>`): The column of the cell.
208
+ - `value` (`unknown`): The total of the column over the rows of the group. `undefined` for a column without an `aggregate`.
209
+ - `text` (`string`): The total as text, with the format of the column, or an empty text.
210
+ - `totals` (`Record<string, unknown>`): The totals of every column that has one, by column id.
211
+ - `aggregate` (`AggregateName | 'custom' | undefined`): The function of the total: one of the built-in names, `custom` for a function of the column, or `undefined` without a total.
212
+ - `expanded` (`boolean`): Whether the group is open.
213
+ - `level` (`number`): The groups above this one, from 0.
214
+ - `path` (`readonly GroupPathEntry<Row>[]`): The groups from the outermost one down to this group.
215
+
216
+ ### FootSlotProps
217
+
218
+ - `column` (`ColumnDef<Row>`): The column of the cell.
219
+ - `value` (`unknown`): The total of the column, or `undefined` for a column without an `aggregate`.
220
+ - `text` (`string`): The total as text, with the format of the column, or an empty text.
221
+ - `totals` (`Record<string, unknown>`): The totals of every column that has one, by column id.
222
+ - `aggregate` (`AggregateName | 'custom' | undefined`): The function of the total: one of the built-in names, `custom` for a function of the column, or `undefined` without a total.
223
+ - `setAggregate` (`(aggregate: AggregateName | null | undefined, event?: Event) => void`): Chooses the function of the total of this column, for a picker in the footer. `null` takes the total away, and `undefined` gives the column the `aggregate` of its definition back. The group rows and an export follow.
224
+
225
+ ### RowHeaderSlotProps
226
+
227
+ - `row` (`Row`): The row object of the data, as the owner passed it.
228
+ - `node` (`DataRow<Row>`): The node of the row in the row model: its id, its parent and its children.
229
+ - `column` (`ColumnDef<Row>`): The definition of the column with `rowHeader`.
230
+ - `number` (`number`): The number of the row, from 1: its place among the rows that the table shows, counted over the pages.
231
+ - `selectRow` (`(event?: Event) => void`): Selects the cells of the row. With Shift in the event, the rows from the active cell to this one. A press on the cell does the same; this is for a control inside it. It throws without the `cellSelection` option.
232
+
233
+ ### LetterSlotProps
234
+
235
+ - `column` (`ColumnDef<Row>`): The definition of the column under the letter.
236
+ - `letter` (`string | undefined`): The letter of the column: its place among the columns in view. `undefined` for a column that leads the table.
237
+ - `corner` (`boolean`): Whether the cell is the corner, above the row numbers, which selects every cell.
238
+ - `selectColumn` (`(event?: Event) => void`): Selects what a press on the cell selects: the cells of the column, with Shift in the event from the active cell on, or every cell from the corner. A press on the cell does the same; this is for a control inside it. It throws for an empty cell of a column that leads, and without the `cellSelection` option.
239
+
240
+ ### DetailSlotProps
241
+
242
+ - `row` (`Row`): The row object of the data, as the owner passed it.
243
+ - `node` (`DataRow<Row>`): The node of the row in the row model: its id, its parent and its children.
244
+ - `toggleExpanded` (`(event?: Event) => void`): Closes the detail row.
@@ -0,0 +1,110 @@
1
+ # View
2
+
3
+ Every field of `getView()`, the plain data that the controls beside a table read.
4
+
5
+ Read the view again in `subscribe`, or with `useTableView(controller)`. See [Controller and view](./controller-and-view.md).
6
+
7
+ ## TableView
8
+
9
+ - `sort` (`readonly SortRule[]`): The sort: the columns in the order in which they sort.
10
+ - `filter` (`FilterState`): The filter: the search and the filter of each column.
11
+ - `search` (`string`): The text that a search field shows: the text that waits from `inputSearch`, else the search of the filter.
12
+ - `searchPending` (`boolean`): Whether a text from `inputSearch` waits for its pause, so the rows do not follow `search` yet.
13
+ - `groupBy` (`readonly string[]`): The ids of the columns that group the rows, in order.
14
+ - `expanded` (`readonly string[]`): The ids of the open tree rows, groups and rows with a detail row.
15
+ - `selected` (`readonly string[]`): The ids of the selected rows.
16
+ - `page` (`number`): The page in view, from 1. A table without pages has one page.
17
+ - `pageSize` (`number | undefined`): How many rows a page holds, or `undefined` for a table without pages.
18
+ - `pageCount` (`number`): How many pages there are. A table without pages has one.
19
+ - `rowCount` (`number`): How many entries the pages divide: what `pageUnit` names. With pages from a server, its `rowCount`.
20
+ - `pageUnit` (`PageUnit`): What the pages count. `rows`: each row. `groups`: each group, with its rows on the page of the group. `parents`: each top-level row, with its child rows on the same page. `mixed`: groups, and rows outside every group.
21
+ - `dataRowCount` (`number`): How many data rows pass the filters, child rows too. With `rows`, it is `rowCount`.
22
+ - `lastPageKnown` (`boolean`): Whether the last page is known. It is not for pages from a server that gave no count.
23
+ - `columns` (`readonly ColumnDef[]`): Every column that holds cells, hidden ones too, in definition order.
24
+ - `visibleColumns` (`readonly ColumnDef[]`): The columns in view, in display order.
25
+ - `selectable` (`readonly string[]`): The ids of the rows that `selectAll` selects: the rows that pass the filters and can be selected.
26
+ - `hasExpandable` (`boolean`): Whether the table has a group or a row with child rows: what `expandAll` opens.
27
+ - `hasExpanded` (`boolean`): Whether one of them is open now. An id in `expanded` that no group or row has any more does not count.
28
+ - `loading` (`boolean`): The `loading` option: whether new rows are on their way.
29
+ - `columnAggregates` (`ColumnAggregates`): The functions of the totals that were chosen at run time, by column id.
30
+ - `cellFormats` (`CellFormats`): The formats of cells and columns that were set at run time.
31
+ - `formulas` (`boolean`): Whether the table has the `formulas` option.
32
+ - `cellFormulas` (`CellFormulas`): The formulas of the table.
33
+ - `formula` (`FormulaView | null`): The formula of the active cell or of its column, for a formula bar. `null` without formulas and without an active cell.
34
+ - `canUndo` (`boolean`): Whether `undo` has a step to take back. Always false without the `history` option.
35
+ - `canRedo` (`boolean`): Whether `redo` has a step to bring back. Always false without the `history` option.
36
+ - `activeCell` (`CellRef | null`): The cell that has the tab stop, when it is a cell of a data row.
37
+ - `cellSelection` (`CellSelectionView | null`): The selected cells of a table with `cellSelection`: the range, or the active cell alone. `null` when no cell of a data row is selected.
38
+
39
+ ## CellSelectionView
40
+
41
+ - `from` (`CellRef`): The first selected cell that holds a value, at the top and the start.
42
+ - `to` (`CellRef`): The last selected cell that holds a value, at the bottom and the end.
43
+ - `rows` (`number`): How many data rows the selection covers.
44
+ - `columns` (`number`): How many columns the selection covers.
45
+
46
+ ## RangeSummary
47
+
48
+ - `cells` (`number`): How many cells of data rows the selection holds.
49
+ - `count` (`number`): How many of them hold a value.
50
+ - `numbers` (`number`): How many hold a number. The four values after it are of these cells.
51
+ - `sum` (`number`): The sum of the numbers. 0 without a number.
52
+ - `mean` (`number | undefined`): The mean of the numbers, or `undefined` without a number.
53
+ - `min` (`number | undefined`): The smallest number, or `undefined` without a number.
54
+ - `max` (`number | undefined`): The largest number, or `undefined` without a number.
55
+ - `texts` (`{ sum: string; mean: string; min: string; max: string }`): Each value as text: in the format of the column when the selection is inside one column that shows numbers, else as a plain number of the locale, where the mean has the decimals of `meanDecimals`. An empty text for a value that does not exist.
56
+
57
+ ## TableSearch
58
+
59
+ What `useTableSearch(controller)` gives.
60
+
61
+ - `text` (`WritableComputedRef<string>`): The text of the search field, for `v-model`. A new text shows at once, and the table filters when the typing pauses (`searchDebounce` of the table). A search text that the table gets from elsewhere shows here too.
62
+ - `pending` (`Readonly<ShallowRef<boolean>>`): Whether a text waits for its pause, so the rows do not follow the field yet.
63
+ - `clear` (`() => void`): Empties the search at once, for a clear button and for Escape.
64
+ - `flush` (`() => void`): Filters now by the text that waits, for Enter.
65
+
66
+ ## EditDraft
67
+
68
+ What `useEditDraft` gives.
69
+
70
+ - `rows` (`ComputedRef<Row[]>`): The rows to pass to the table: the rows of the owner with the values of the draft in them.
71
+ - `count` (`ComputedRef<number>`): How many cells hold another value than the rows of the owner.
72
+ - `changed` (`(rowId: string, columnId: string) => boolean`): Whether a cell holds another value than the rows of the owner, by the row id and the column id.
73
+ - `onCellEdit` (`(edits: readonly CellEdit<Row>[]) => void`): Pass it as the `cell-edit` listener of the table. It takes every report: an edit, a paste, a fill, a clear and an undo. It throws for an edit of a row that is not in the rows of the owner, such as a child row.
74
+ - `save` (`() => CellEdit<Row>[]`): The edits against the rows of the owner, one for each cell that differs, and an empty draft.
75
+ - `cancel` (`() => void`): Empties the draft.
76
+
77
+ ## EditDraftOptions
78
+
79
+ - `getRowId?` (`(row: Row, index: number, parent: null) => string | number`): The `getRowId` of the table, when it has one. Without it, a row is found by its `id`, else by its place.
80
+
81
+ ## Rows
82
+
83
+ ### DataRow
84
+
85
+ - `kind` (`'row'`): Always `'row'`: a row of the data.
86
+ - `id` (`string`): The id of the row, from `getRowId`.
87
+ - `row` (`Row`): The row object of the data, as the owner passed it.
88
+ - `index` (`number`): Position among its siblings in the source data.
89
+ - `depth` (`number`): Tree depth in the source data, 0 for a top-level row.
90
+ - `parentId` (`string | null`): The id of the tree row above this row, or `null`.
91
+ - `children?` (`readonly DataRow<Row>[]`): The child rows, for a tree row.
92
+
93
+ ### GroupRow
94
+
95
+ - `kind` (`'group'`): Always `'group'`: a group of rows.
96
+ - `id` (`string`): The id of the group, such as `group/team=Design`. `expanded` holds it.
97
+ - `columnId` (`string`): The id of the column that makes the group.
98
+ - `value` (`unknown`): The value of that column that the rows of the group share.
99
+ - `depth` (`number`): Grouping level, 0 for the first `groupBy` column.
100
+ - `parentId` (`string | null`): The id of the group above this one, or `null`.
101
+ - `parent` (`GroupRow<Row> | null`): The group that holds this group, or `null` for a group of the first `groupBy` column.
102
+ - `children` (`readonly TableRow<Row>[]`): The groups or the rows right under this group.
103
+ - `leaves` (`readonly DataRow<Row>[]`): Every data row under the group, in order, without their tree children.
104
+
105
+ ### GroupPathEntry
106
+
107
+ - `group` (`GroupRow<Row>`): The group.
108
+ - `column` (`ColumnDef<Row> | undefined`): The column that the group is made from. `undefined` when the table has no such column any more.
109
+ - `value` (`unknown`): The value that the rows of the group share.
110
+ - `text` (`string`): The value as text, with the format of its column.
@@ -229,11 +229,13 @@ A draft stays with the cell where it started, also when the active cell moves. A
229
229
  | --- | --- |
230
230
  | Operators | `+ - * / ^`, a leading `-`, `%` after a number, `&` (joins texts), `= <> < <= > >=` |
231
231
  | Numbers | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `FLOOR`, `CEILING`, `ABS`, `INT`, `MOD` |
232
- | Conditions | `IF`, `IFS`, `SWITCH`, `AND`, `OR`, `NOT`, `IFERROR`, `ISBLANK`, `ISNUMBER`, `ISTEXT`, `ISERROR` |
233
- | Texts | `CONCAT`, `LEN`, `LEFT`, `RIGHT`, `MID`, `UPPER`, `LOWER`, `TRIM` |
232
+ | Conditions | `IF`, `IFS`, `SWITCH`, `AND`, `OR`, `NOT`, `IFERROR`, `IFNA`, `ISBLANK`, `ISNUMBER`, `ISTEXT`, `ISERROR` |
233
+ | Ranges with criteria | `COUNTIF`, `COUNTIFS`, `SUMIF`, `SUMIFS`, `AVERAGEIF`, `AVERAGEIFS`, `COUNTBLANK` |
234
+ | Lookups | `XLOOKUP`, `VLOOKUP`, `INDEX`, `MATCH` |
235
+ | Texts | `CONCAT`, `TEXTJOIN`, `LEN`, `LEFT`, `RIGHT`, `MID`, `UPPER`, `LOWER`, `TRIM`, `SUBSTITUTE`, `FIND`, `SEARCH`, `VALUE`, `TEXT` |
234
236
  | Periods of a date | `DAYOF`, `WEEKOF(d, [type])`, `MONTHOF`, `QUARTEROF`, `YEAROF`, `HOUROF` |
235
237
  | Parts of a date | `YEAR`, `QUARTER`, `MONTH`, `DAY`, `HOUR`, `MINUTE`, `WEEKDAY(d, [type])`, `ISOWEEKNUM`, `ISOYEAR` |
236
- | Date math | `DATE(year, month, day)`, `DAYS(end, start)`, `DATEADD(date, count, unit)` |
238
+ | Date math | `DATE(year, month, day)`, `DAYS(end, start)`, `DATEADD(date, count, unit)`, `EOMONTH(date, months)`, `TODAY()`, `NOW()` |
237
239
 
238
240
  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:
239
241
 
@@ -241,7 +243,12 @@ A function whose name Excel has behaves as in Excel, with its arguments and edge
241
243
  - 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.
242
244
  - The date functions read the clock of a zone (above); Excel has no zone.
243
245
  - `#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.
244
- - No other sheets, names, arrays, lookups, `SUMIF`, `TODAY()` or `NOW()`.
246
+ - **Criteria** of `COUNTIF` and its family are those of Excel: `5`, `">5"`, `"<>done"`, `""` for the empty cells, `"a*"` and `"?"` as wildcards and `~` before one of them; capital and small letters are the same, and a criterion of a number takes a text of that number. A date is no number here, so a day text in a criterion (`">2026-01-31"`) compares with the days of a range, and a number never takes a date. The ranges of one call have the same rows and columns: `SUMIF` and `AVERAGEIF` give `#VALUE!` where Excel would stretch a smaller range of values.
247
+ - **Lookups** give one cell. A result that Excel spills into the cells beside it, such as `XLOOKUP` with results of two columns or `INDEX` with a row or a column 0 of a range of more than one, is `#VALUE!`. A value matches a cell of its own kind only. `MATCH` and `VLOOKUP` with an approximate match, and `XLOOKUP` with the search `2` or `-2`, give what Excel gives on sorted data; Excel searches such data in halves, and on data that is not sorted it can give another cell, where these look at every cell. A lookup of an empty value is `#N/A`.
248
+ - **`VALUE`** reads a text as a formula reads a number: `12.5`, `-3`, `1e3`, with spaces around it. It reads no comma of thousands, no currency, no percent and no date, in any locale: those are `#VALUE!`.
249
+ - **`TEXT`** knows these codes, the same in every locale. A number: `0`, `#`, the decimal point, a comma between the digits (thousands, as in `#,##0.00`) and `%`. A date: `yy`, `yyyy`, `m` to `mmmmm`, `d` to `dddd` (the months and days in English), `h`, `hh`, `m` and `mm` after an hour or before a second (the minutes), `s`, `ss` and `AM/PM`. Both take text in quotes, a character after `\`, a space and the characters `$-+()/:` (and `.` and `,` in a date); `General` gives the plain text. Any other code is `#VALUE!`: no colours, no sections with `;`, no `E+`, no comma at the end. A date with a number code and a number with a date code are `#VALUE!`, because a date is no number here. A half goes away from zero.
250
+ - **`TODAY()` and `NOW()`** hold the moment when they were computed: after an entry, after rows came or went, or at `controller.recalculate()`. Nothing computes them on a timer and a render does not. `TODAY()` is the day in the zone of the formula (`timeZone` of the engine), `NOW()` a `Date`. A test passes a clock: `createFormulaEngine({ now: () => Date.UTC(2026, 10, 22) })`.
251
+ - **Left out:** `FILTER`, `UNIQUE`, `SORT`, `SORTBY`, `SEQUENCE` and `TRANSPOSE` give a list that Excel spills into the cells beside the formula; a cell of the table holds one value and the rows belong to the owner. `SUBTOTAL` skips the rows that a filter hides; a formula reads places of the document and never the view, and the footer, `getTotals` and the selection summary already follow the filter. No other sheets, names or arrays.
245
252
 
246
253
 
247
254
  ## What a styled table needs
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ui-sdk-table-vue",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Vue parts for the ui-sdk-table primitive: slots, v-model and controllers.",
5
5
  "keywords": [
6
6
  "data-grid",
@@ -37,7 +37,7 @@
37
37
  "access": "public"
38
38
  },
39
39
  "dependencies": {
40
- "ui-sdk-table-core": "0.2.0"
40
+ "ui-sdk-table-core": "0.2.1"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/jsdom": "^30.0.0",
package/src/table.ts CHANGED
@@ -421,15 +421,19 @@ export type TableEmits = {
421
421
  }
422
422
 
423
423
  export type HeaderSlotProps<Row> = {
424
+ /** The definition of the column. */
424
425
  column: ColumnDef<Row>
425
426
  /** The header text: `column.header`, or the column id. */
426
427
  label: string
427
428
  /** False for a header group, which holds columns and no cells. */
428
429
  leaf: boolean
430
+ /** The direction of the column in the sort, `'asc'` or `'desc'`, or `undefined` when it does not sort. */
429
431
  sort: SortDirection | undefined
430
432
  /** The place of the column in the sort, from 1. With several columns in the sort, the first one sorts first. */
431
433
  sortIndex: number | undefined
434
+ /** Sorts by the column as a press on the header does. Pass the event: with `multiSort`, its keys decide whether the column joins the sort. */
432
435
  toggleSort: (event?: Event) => void
436
+ /** The edge that the column is pinned to, or `undefined`. */
433
437
  pin: 'start' | 'end' | undefined
434
438
  /**
435
439
  * Selects the cells of the column, for a control in its header. With
@@ -442,9 +446,13 @@ export type HeaderSlotProps<Row> = {
442
446
  }
443
447
 
444
448
  export type CellSlotProps<Row> = {
449
+ /** The row object of the data, as the owner passed it. */
445
450
  row: Row
451
+ /** The node of the row in the row model: its id, its parent and its children. */
446
452
  node: DataRow<Row>
453
+ /** The definition of the column. */
447
454
  column: ColumnDef<Row>
455
+ /** The value of the cell: `value` of the column, else the property that `key` names. */
448
456
  value: unknown
449
457
  /** The value as text, with the format of the cell, else of its column. */
450
458
  text: string
@@ -455,14 +463,19 @@ export type CellSlotProps<Row> = {
455
463
  * `data-bold`, `data-italic`, `data-color` and `data-fill`.
456
464
  */
457
465
  format: CellFormat | undefined
466
+ /** Whether the row is selected. */
458
467
  selected: boolean
468
+ /** Whether the row is open: its child rows or its detail row show. */
459
469
  expanded: boolean
470
+ /** Whether the row can open: it has child rows or a detail row. */
460
471
  expandable: boolean
461
472
  /** Tree and group levels above this row, from 0. */
462
473
  level: number
463
474
  /** The edge that the row is pinned to. */
464
475
  pinned: RowPin | undefined
476
+ /** Selects the row or takes it out of the selection, for a checkbox in the cell. */
465
477
  toggleSelected: (event?: Event) => void
478
+ /** Opens or closes the row, for a button in the cell. */
466
479
  toggleExpanded: (event?: Event) => void
467
480
  /**
468
481
  * With formulas: the formula of the cell as a person reads it, and the
@@ -473,9 +486,13 @@ export type CellSlotProps<Row> = {
473
486
  }
474
487
 
475
488
  export type EditorSlotProps<Row> = {
489
+ /** The row object of the data, as the owner passed it. */
476
490
  row: Row
491
+ /** The node of the row in the row model: its id, its parent and its children. */
477
492
  node: DataRow<Row>
493
+ /** The definition of the column. */
478
494
  column: ColumnDef<Row>
495
+ /** The value of the cell now. */
479
496
  value: unknown
480
497
  /** The value as plain text, without a format: 0.25 for a cell that shows 25 %. `save` takes a value. */
481
498
  text: string
@@ -505,8 +522,11 @@ export type EditorSlotProps<Row> = {
505
522
  }
506
523
 
507
524
  export type RowHeaderSlotProps<Row> = {
525
+ /** The row object of the data, as the owner passed it. */
508
526
  row: Row
527
+ /** The node of the row in the row model: its id, its parent and its children. */
509
528
  node: DataRow<Row>
529
+ /** The definition of the column with `rowHeader`. */
510
530
  column: ColumnDef<Row>
511
531
  /** The number of the row, from 1: its place among the rows that the table shows, counted over the pages. */
512
532
  number: number
@@ -519,6 +539,7 @@ export type RowHeaderSlotProps<Row> = {
519
539
  }
520
540
 
521
541
  export type LetterSlotProps<Row> = {
542
+ /** The definition of the column under the letter. */
522
543
  column: ColumnDef<Row>
523
544
  /** The letter of the column: its place among the columns in view. `undefined` for a column that leads the table. */
524
545
  letter: string | undefined
@@ -535,18 +556,24 @@ export type LetterSlotProps<Row> = {
535
556
  }
536
557
 
537
558
  export type DetailSlotProps<Row> = {
559
+ /** The row object of the data, as the owner passed it. */
538
560
  row: Row
561
+ /** The node of the row in the row model: its id, its parent and its children. */
539
562
  node: DataRow<Row>
540
563
  /** Closes the detail row. */
541
564
  toggleExpanded: (event?: Event) => void
542
565
  }
543
566
 
544
567
  export type GroupSlotProps<Row> = {
568
+ /** The group: its id, the column and the value that make it, and its rows. */
545
569
  group: GroupRow<Row>
570
+ /** The column that makes the group. */
546
571
  column: ColumnDef<Row> | undefined
547
572
  /** The value of the group as text, with the format of its column. */
548
573
  text: string
574
+ /** Whether the group is open. */
549
575
  expanded: boolean
576
+ /** The groups above this one, from 0. */
550
577
  level: number
551
578
  /** Column totals of the rows in the group. */
552
579
  totals: Record<string, unknown>
@@ -562,11 +589,14 @@ export type GroupSlotProps<Row> = {
562
589
  * total of one of these columns has no cell of its own.
563
590
  */
564
591
  covered: readonly ColumnDef<Row>[]
592
+ /** Opens or closes the group, for a button in the cell. */
565
593
  toggleExpanded: (event?: Event) => void
566
594
  }
567
595
 
568
596
  export type GroupTotalSlotProps<Row> = {
597
+ /** The group of the row. */
569
598
  group: GroupRow<Row>
599
+ /** The column of the cell. */
570
600
  column: ColumnDef<Row>
571
601
  /** The total of the column over the rows of the group. `undefined` for a column without an `aggregate`. */
572
602
  value: unknown
@@ -576,14 +606,20 @@ export type GroupTotalSlotProps<Row> = {
576
606
  totals: Record<string, unknown>
577
607
  /** The function of the total: one of the built-in names, `custom` for a function of the column, or `undefined` without a total. */
578
608
  aggregate: AggregateName | 'custom' | undefined
609
+ /** Whether the group is open. */
579
610
  expanded: boolean
611
+ /** The groups above this one, from 0. */
580
612
  level: number
613
+ /** The groups from the outermost one down to this group. */
581
614
  path: readonly GroupPathEntry<Row>[]
582
615
  }
583
616
 
584
617
  export type FootSlotProps<Row> = {
618
+ /** The column of the cell. */
585
619
  column: ColumnDef<Row>
620
+ /** The total of the column, or `undefined` for a column without an `aggregate`. */
586
621
  value: unknown
622
+ /** The total as text, with the format of the column, or an empty text. */
587
623
  text: string
588
624
  /** The totals of every column that has one, by column id. */
589
625
  totals: Record<string, unknown>
@@ -615,12 +651,17 @@ export type TableSlots<Row> = {
615
651
  */
616
652
  [name: `edit-${string}`]: (props: EditorSlotProps<Row>) => VNodeChild
617
653
  } & {
654
+ /** The editor of a cell, in place of the text field of the table. The control must take focus itself. */
618
655
  editor?: (props: EditorSlotProps<Row>) => VNodeChild
656
+ /** One header cell, for every column without a `header-{column id}` slot. */
619
657
  header?: (props: HeaderSlotProps<Row>) => VNodeChild
658
+ /** One body cell, for every column without a `col-{column id}` slot. */
620
659
  cell?: (props: CellSlotProps<Row>) => VNodeChild
660
+ /** One total in the footer, for every column without a `foot-{column id}` slot. */
621
661
  foot?: (props: FootSlotProps<Row>) => VNodeChild
622
662
  /** The label cell of a group row. */
623
663
  group?: (props: GroupSlotProps<Row>) => VNodeChild
664
+ /** The cell of a group row under one column, for every column without a `group-total-{column id}` slot. */
624
665
  'group-total'?: (props: GroupTotalSlotProps<Row>) => VNodeChild
625
666
  /** The cell with the number of a row, in a column with `rowHeader`. */
626
667
  'row-header'?: (props: RowHeaderSlotProps<Row>) => VNodeChild