@viewkitjs/views 0.1.0 → 0.3.0
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/CHANGELOG.md +767 -1
- package/README.md +92 -41
- package/dist/atoms/LoadMore.js +11 -1
- package/dist/atoms/Row.js +1 -1
- package/dist/atoms/RowMenu.d.ts +1 -1
- package/dist/atoms/RowMenu.js +20 -6
- package/dist/atoms/types.d.ts +4 -4
- package/dist/cells/cell-format.d.ts +3 -3
- package/dist/cells/cell-title.d.ts +1 -2
- package/dist/cells/cell-title.js +2 -2
- package/dist/cells/cell-values.js +6 -3
- package/dist/contract.d.ts +79 -8
- package/dist/contract.js +55 -8
- package/dist/display/converted.d.ts +19 -0
- package/dist/display/converted.js +12 -0
- package/dist/display/format.d.ts +16 -1
- package/dist/display/format.js +10 -1
- package/dist/display/index.d.ts +2 -1
- package/dist/display/index.js +2 -1
- package/dist/display/link-click.d.ts +11 -0
- package/dist/display/link-click.js +3 -0
- package/dist/display/link.js +12 -6
- package/dist/display/location.d.ts +4 -3
- package/dist/display/location.js +12 -5
- package/dist/display/multi-value.d.ts +1 -1
- package/dist/display/multi-value.js +1 -1
- package/dist/display/options.d.ts +8 -2
- package/dist/display/percent.js +10 -3
- package/dist/display/phone.d.ts +2 -1
- package/dist/display/phone.js +11 -2
- package/dist/display/relation.js +1 -1
- package/dist/editors/ChipsEditor.d.ts +9 -4
- package/dist/editors/ChipsEditor.js +7 -3
- package/dist/editors/DateEditor.d.ts +21 -6
- package/dist/editors/DateEditor.js +118 -30
- package/dist/editors/EditorPanel.d.ts +61 -0
- package/dist/editors/EditorPanel.js +54 -0
- package/dist/editors/LocationEditor.d.ts +3 -0
- package/dist/editors/LocationEditor.js +28 -21
- package/dist/editors/NameEditor.d.ts +3 -0
- package/dist/editors/NameEditor.js +15 -10
- package/dist/editors/NumberEditor.d.ts +3 -0
- package/dist/editors/NumberEditor.js +7 -7
- package/dist/editors/RangeEditor.d.ts +16 -1
- package/dist/editors/RangeEditor.js +22 -6
- package/dist/editors/RelationEditor.d.ts +13 -28
- package/dist/editors/RelationEditor.js +17 -40
- package/dist/editors/RelationSetEditor.d.ts +53 -0
- package/dist/editors/RelationSetEditor.js +112 -0
- package/dist/editors/SelectEditor.d.ts +21 -3
- package/dist/editors/SelectEditor.js +55 -9
- package/dist/editors/TextEditor.d.ts +51 -0
- package/dist/editors/TextEditor.js +81 -0
- package/dist/editors/ValueListEditor.d.ts +5 -2
- package/dist/editors/ValueListEditor.js +11 -9
- package/dist/editors/edit-cores.d.ts +13 -10
- package/dist/editors/edit-cores.js +7 -6
- package/dist/editors/edit-session.d.ts +21 -11
- package/dist/editors/edit-session.js +19 -5
- package/dist/editors/keep-inside.d.ts +12 -0
- package/dist/editors/keep-inside.js +20 -0
- package/dist/editors/open-value.d.ts +21 -0
- package/dist/editors/open-value.js +36 -0
- package/dist/editors/open-values.d.ts +4 -0
- package/dist/editors/open-values.js +7 -0
- package/dist/editors/relation-kinds.d.ts +7 -0
- package/dist/editors/relation-kinds.js +21 -0
- package/dist/editors/relation-panel.d.ts +69 -0
- package/dist/editors/relation-panel.js +40 -0
- package/dist/field-row/FieldNoteLine.d.ts +14 -0
- package/dist/field-row/FieldNoteLine.js +14 -0
- package/dist/field-row/FieldRow.d.ts +73 -0
- package/dist/field-row/FieldRow.js +157 -0
- package/dist/field-row/FieldRowLane.d.ts +19 -0
- package/dist/field-row/FieldRowLane.js +11 -0
- package/dist/field-row/editors/RowChipsEditor.d.ts +11 -0
- package/dist/field-row/editors/RowChipsEditor.js +25 -0
- package/dist/field-row/editors/RowDateEditor.d.ts +16 -0
- package/dist/field-row/editors/RowDateEditor.js +18 -0
- package/dist/field-row/editors/RowEditor.d.ts +39 -0
- package/dist/field-row/editors/RowEditor.js +64 -0
- package/dist/field-row/editors/RowNameEditor.d.ts +4 -0
- package/dist/field-row/editors/RowNameEditor.js +15 -0
- package/dist/field-row/editors/RowNumberEditor.d.ts +12 -0
- package/dist/field-row/editors/RowNumberEditor.js +18 -0
- package/dist/field-row/editors/RowPlaceEditor.d.ts +8 -0
- package/dist/field-row/editors/RowPlaceEditor.js +18 -0
- package/dist/field-row/editors/RowRangeEditor.d.ts +4 -0
- package/dist/field-row/editors/RowRangeEditor.js +15 -0
- package/dist/field-row/editors/RowRelationEditor.d.ts +20 -0
- package/dist/field-row/editors/RowRelationEditor.js +77 -0
- package/dist/field-row/editors/RowSelectEditor.d.ts +13 -0
- package/dist/field-row/editors/RowSelectEditor.js +23 -0
- package/dist/field-row/editors/RowTextEditor.d.ts +15 -0
- package/dist/field-row/editors/RowTextEditor.js +16 -0
- package/dist/field-row/editors/RowValueListEditor.d.ts +4 -0
- package/dist/field-row/editors/RowValueListEditor.js +21 -0
- package/dist/field-row/editors/host.d.ts +59 -0
- package/dist/field-row/editors/host.js +1 -0
- package/dist/field-row/editors/row-session.d.ts +49 -0
- package/dist/field-row/editors/row-session.js +49 -0
- package/dist/field-row/index.d.ts +5 -0
- package/dist/field-row/index.js +5 -0
- package/dist/field-row/row-target.d.ts +20 -0
- package/dist/field-row/row-target.js +3 -0
- package/dist/field-row/useFieldWrite.d.ts +45 -0
- package/dist/field-row/useFieldWrite.js +190 -0
- package/dist/field-row/useRowSettlement.d.ts +33 -0
- package/dist/field-row/useRowSettlement.js +23 -0
- package/dist/fields/binding.d.ts +7 -2
- package/dist/fields/binding.js +13 -6
- package/dist/fields/currency.d.ts +0 -10
- package/dist/fields/currency.js +0 -14
- package/dist/fields/edit-core-types.d.ts +9 -9
- package/dist/fields/edit-core-types.js +6 -6
- package/dist/fields/money.d.ts +6 -0
- package/dist/fields/money.js +11 -0
- package/dist/fields/number-edit.d.ts +6 -0
- package/dist/fields/number-edit.js +4 -0
- package/dist/fields/prepare-write.js +6 -1
- package/dist/fields/relation-source-types.d.ts +12 -0
- package/dist/fields/write-target.d.ts +50 -0
- package/dist/fields/write-target.js +10 -0
- package/dist/filters/filter-model.d.ts +0 -1
- package/dist/filters/registry.d.ts +3 -36
- package/dist/filters/registry.js +0 -38
- package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
- package/dist/grid/chrome/GridAddColumn.js +29 -0
- package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
- package/dist/grid/chrome/GridAggregateMenu.js +29 -0
- package/dist/grid/chrome/GridCellEditors.d.ts +71 -0
- package/dist/grid/chrome/GridCellEditors.js +126 -0
- package/dist/grid/chrome/GridCellOutline.d.ts +49 -0
- package/dist/grid/chrome/GridCellOutline.js +16 -0
- package/dist/grid/chrome/GridChipsEditor.d.ts +38 -0
- package/dist/grid/chrome/GridChipsEditor.js +35 -0
- package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
- package/dist/grid/chrome/GridColumnColorSection.js +40 -0
- package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
- package/dist/grid/chrome/GridColumnDateSection.js +23 -0
- package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
- package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
- package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
- package/dist/grid/chrome/GridColumnMenu.js +103 -0
- package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
- package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
- package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
- package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
- package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
- package/dist/grid/chrome/GridColumnSortSection.js +16 -0
- package/dist/grid/chrome/GridDateEditor.d.ts +34 -0
- package/dist/grid/chrome/GridDateEditor.js +19 -0
- package/dist/grid/chrome/GridFlyout.d.ts +44 -0
- package/dist/grid/chrome/GridFlyout.js +80 -0
- package/dist/grid/chrome/GridFooter.d.ts +33 -0
- package/dist/grid/chrome/GridFooter.js +85 -0
- package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
- package/dist/grid/chrome/GridGroupMenu.js +64 -0
- package/dist/grid/chrome/GridHeader.d.ts +66 -0
- package/dist/grid/chrome/GridHeader.js +42 -0
- package/dist/grid/chrome/GridLongTextEditor.d.ts +55 -0
- package/dist/grid/chrome/GridLongTextEditor.js +69 -0
- package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
- package/dist/grid/chrome/GridMenuRow.js +15 -0
- package/dist/grid/chrome/GridNameEditor.d.ts +24 -0
- package/dist/grid/chrome/GridNameEditor.js +21 -0
- package/dist/grid/chrome/GridNumberEditor.d.ts +49 -0
- package/dist/grid/chrome/GridNumberEditor.js +51 -0
- package/dist/grid/chrome/GridPlaceEditor.d.ts +26 -0
- package/dist/grid/chrome/GridPlaceEditor.js +22 -0
- package/dist/grid/chrome/GridRangeEditor.d.ts +30 -0
- package/dist/grid/chrome/GridRangeEditor.js +21 -0
- package/dist/grid/chrome/GridRelationEditor.d.ts +45 -0
- package/dist/grid/chrome/GridRelationEditor.js +92 -0
- package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
- package/dist/grid/chrome/GridResizeHandle.js +19 -0
- package/dist/grid/chrome/GridRow.d.ts +31 -0
- package/dist/grid/chrome/GridRow.js +179 -0
- package/dist/grid/chrome/GridRowActions.d.ts +32 -0
- package/dist/grid/chrome/GridRowActions.js +25 -0
- package/dist/grid/chrome/GridRowCells.d.ts +4 -0
- package/dist/grid/chrome/GridRowCells.js +128 -0
- package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
- package/dist/grid/chrome/GridRowGlyph.js +13 -0
- package/dist/grid/chrome/GridSelectEditor.d.ts +33 -0
- package/dist/grid/chrome/GridSelectEditor.js +43 -0
- package/dist/grid/chrome/GridStructure.d.ts +47 -0
- package/dist/grid/chrome/GridStructure.js +41 -0
- package/dist/grid/chrome/GridTable.d.ts +4 -0
- package/dist/grid/chrome/GridTable.js +192 -0
- package/dist/grid/chrome/GridTableSurface.d.ts +52 -0
- package/dist/grid/chrome/GridTableSurface.js +15 -0
- package/dist/grid/chrome/GridTextEditor.d.ts +45 -0
- package/dist/grid/chrome/GridTextEditor.js +38 -0
- package/dist/grid/chrome/GridValueListEditor.d.ts +30 -0
- package/dist/grid/chrome/GridValueListEditor.js +19 -0
- package/dist/grid/chrome/StuckMarker.d.ts +16 -0
- package/dist/grid/chrome/StuckMarker.js +34 -0
- package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
- package/dist/grid/chrome/cell-clipboard.js +28 -0
- package/dist/grid/chrome/cell-cut-off.d.ts +11 -0
- package/dist/grid/chrome/cell-cut-off.js +20 -0
- package/dist/grid/chrome/cells.d.ts +21 -0
- package/dist/grid/chrome/cells.js +19 -0
- package/dist/grid/chrome/checks.d.ts +32 -0
- package/dist/grid/chrome/checks.js +32 -0
- package/dist/grid/chrome/column-glyph.d.ts +14 -0
- package/dist/grid/chrome/column-glyph.js +44 -0
- package/dist/grid/chrome/editors.d.ts +9 -0
- package/dist/grid/chrome/editors.js +10 -0
- package/dist/grid/chrome/grid-cell-classes.d.ts +53 -0
- package/dist/grid/chrome/grid-cell-classes.js +32 -0
- package/dist/grid/chrome/grid-cell-link.d.ts +13 -0
- package/dist/grid/chrome/grid-cell-link.js +9 -0
- package/dist/grid/chrome/grid-edit-session.d.ts +63 -0
- package/dist/grid/chrome/grid-edit-session.js +118 -0
- package/dist/grid/chrome/grid-hover.d.ts +60 -0
- package/dist/grid/chrome/grid-hover.js +81 -0
- package/dist/grid/chrome/grid-menu-focus.d.ts +43 -0
- package/dist/grid/chrome/grid-menu-focus.js +93 -0
- package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
- package/dist/grid/chrome/grid-menu-search.js +7 -0
- package/dist/grid/chrome/grid-row-menu-key.d.ts +15 -0
- package/dist/grid/chrome/grid-row-menu-key.js +36 -0
- package/dist/grid/chrome/grid-row-props.d.ts +143 -0
- package/dist/grid/chrome/grid-row-props.js +1 -0
- package/dist/grid/chrome/grid-row-window.d.ts +61 -0
- package/dist/grid/chrome/grid-row-window.js +212 -0
- package/dist/grid/chrome/grid-scroll-owner.d.ts +38 -0
- package/dist/grid/chrome/grid-scroll-owner.js +75 -0
- package/dist/grid/chrome/grid-styles.d.ts +40 -0
- package/dist/grid/chrome/grid-styles.js +9 -0
- package/dist/grid/chrome/grid-table-props.d.ts +172 -0
- package/dist/grid/chrome/grid-table-props.js +1 -0
- package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
- package/dist/grid/chrome/useGridBatchApi.js +35 -0
- package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
- package/dist/grid/chrome/useGridColumnLayout.js +206 -0
- package/dist/grid/chrome/useGridFocus.d.ts +45 -0
- package/dist/grid/chrome/useGridFocus.js +122 -0
- package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
- package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
- package/dist/grid/chrome/useGridKeyboard.d.ts +64 -0
- package/dist/grid/chrome/useGridKeyboard.js +450 -0
- package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
- package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
- package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
- package/dist/grid/chrome/useGridRailReveal.js +67 -0
- package/dist/grid/chrome/useGridRangeActions.d.ts +51 -0
- package/dist/grid/chrome/useGridRangeActions.js +195 -0
- package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
- package/dist/grid/chrome/useGridRangeGestures.js +237 -0
- package/dist/grid/chrome/useGridRowContextMenu.d.ts +37 -0
- package/dist/grid/chrome/useGridRowContextMenu.js +153 -0
- package/dist/grid/chrome/useGridScaleStyles.d.ts +3 -0
- package/dist/grid/chrome/useGridScaleStyles.js +28 -0
- package/dist/grid/chrome/useGridScrollArea.d.ts +21 -0
- package/dist/grid/chrome/useGridScrollArea.js +65 -0
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +78 -0
- package/dist/grid/chrome/useGridTableInteractionModel.js +249 -0
- package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
- package/dist/grid/chrome/useGridTableSelection.js +55 -0
- package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
- package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
- package/dist/grid/core/clipboard-model.d.ts +83 -0
- package/dist/grid/core/clipboard-model.js +291 -0
- package/dist/grid/core/column-values.d.ts +27 -0
- package/dist/grid/core/column-values.js +76 -0
- package/dist/grid/core/commit-model.d.ts +41 -0
- package/dist/grid/core/commit-model.js +3 -0
- package/dist/grid/core/coordinates.d.ts +48 -0
- package/dist/grid/core/coordinates.js +27 -0
- package/dist/grid/core/edge-scroll.d.ts +21 -0
- package/dist/grid/core/edge-scroll.js +23 -0
- package/dist/grid/core/edit-values.d.ts +9 -0
- package/dist/grid/core/edit-values.js +1 -0
- package/dist/grid/core/editing-controller.d.ts +60 -0
- package/dist/grid/core/editing-controller.js +266 -0
- package/dist/grid/core/editing-model.d.ts +87 -0
- package/dist/grid/core/editing-model.js +148 -0
- package/dist/grid/core/flat-rows.d.ts +35 -0
- package/dist/grid/core/flat-rows.js +20 -0
- package/dist/grid/core/grid-aria.d.ts +27 -0
- package/dist/grid/core/grid-aria.js +39 -0
- package/dist/grid/core/grid-focus.d.ts +54 -0
- package/dist/grid/core/grid-focus.js +148 -0
- package/dist/grid/core/grid-scale.d.ts +14 -0
- package/dist/grid/core/grid-scale.js +8 -0
- package/dist/grid/core/nav.d.ts +94 -0
- package/dist/grid/core/nav.js +92 -0
- package/dist/grid/core/pending-reconciliation.d.ts +53 -0
- package/dist/grid/core/pending-reconciliation.js +51 -0
- package/dist/grid/core/range-model.d.ts +25 -0
- package/dist/grid/core/range-model.js +59 -0
- package/dist/grid/core/row-window.d.ts +40 -0
- package/dist/grid/core/row-window.js +43 -0
- package/dist/grid/core/spreadsheet-operations.d.ts +101 -0
- package/dist/grid/core/spreadsheet-operations.js +280 -0
- package/dist/grid/core/useGridEditing.d.ts +46 -0
- package/dist/grid/core/useGridEditing.js +93 -0
- package/dist/grid/core/useGridRange.d.ts +20 -0
- package/dist/grid/core/useGridRange.js +24 -0
- package/dist/grid/core/value-equality.d.ts +54 -0
- package/dist/grid/core/value-equality.js +80 -0
- package/dist/grid/index.d.ts +18 -0
- package/dist/grid/index.js +5 -0
- package/dist/grid/useGridTablePrefs.d.ts +49 -0
- package/dist/grid/useGridTablePrefs.js +99 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/internal/viewport.d.ts +3 -0
- package/dist/internal/viewport.js +15 -0
- package/dist/model/column-capabilities.d.ts +3 -2
- package/dist/model/column-capabilities.js +28 -8
- package/dist/model/column-from.js +3 -0
- package/dist/model/column-inspect.d.ts +10 -2
- package/dist/model/column-inspect.js +9 -0
- package/dist/model/column-schema.d.ts +6 -1
- package/dist/model/column-state.d.ts +1 -1
- package/dist/model/column-types.d.ts +3 -1
- package/dist/model/column-types.js +1 -1
- package/dist/model/density.js +3 -3
- package/dist/model/filter-capabilities.d.ts +1 -1
- package/dist/model/filter-capabilities.js +1 -1
- package/dist/model/index.d.ts +4 -6
- package/dist/model/index.js +0 -1
- package/dist/model/preferences.d.ts +7 -7
- package/dist/model/preferences.js +0 -1
- package/dist/model/prefs-buckets.d.ts +0 -1
- package/dist/model/prefs-buckets.js +0 -3
- package/dist/model/render-count.d.ts +6 -0
- package/dist/model/render-count.js +11 -0
- package/dist/provider/ViewsProvider.d.ts +6 -2
- package/dist/provider/ViewsProvider.js +12 -2
- package/dist/provider/components.d.ts +35 -9
- package/dist/provider/components.js +4 -2
- package/dist/provider/context.d.ts +8 -4
- package/dist/provider/desktop.d.ts +9 -0
- package/dist/provider/desktop.js +22 -0
- package/dist/provider/menu-groups.d.ts +8 -0
- package/dist/provider/menu-groups.js +38 -0
- package/dist/provider/plain-input.d.ts +8 -0
- package/dist/provider/plain-input.js +5 -0
- package/dist/provider/ports.d.ts +22 -0
- package/dist/provider/ports.js +1 -0
- package/dist/react.d.ts +3 -2
- package/dist/react.js +1 -0
- package/dist/selection/SelectCheckbox.d.ts +3 -1
- package/dist/selection/SelectCheckbox.js +2 -2
- package/dist/selection/useCheckDragSelect.js +6 -5
- package/docs/contract.md +202 -72
- package/docs/getting-started.md +250 -0
- package/docs/guides/atoms.md +245 -0
- package/docs/guides/cells.md +302 -0
- package/docs/guides/columns.md +413 -0
- package/docs/guides/display.md +204 -0
- package/docs/guides/editors.md +462 -0
- package/docs/guides/ports.md +246 -0
- package/docs/guides/selection.md +270 -0
- package/docs/guides/the-grid.md +696 -0
- package/docs/guides/the-provider.md +448 -0
- package/docs/index.md +52 -0
- package/docs/install.md +9 -47
- package/docs/reference/cells.md +28 -0
- package/docs/reference/display.md +44 -0
- package/docs/reference/editors-chips.md +6 -0
- package/docs/reference/editors-date.md +6 -0
- package/docs/reference/editors-location.md +10 -0
- package/docs/reference/editors-name.md +6 -0
- package/docs/reference/editors-number.md +11 -0
- package/docs/reference/editors-open-values.md +10 -0
- package/docs/reference/editors-panel.md +12 -0
- package/docs/reference/editors-range.md +6 -0
- package/docs/reference/editors-relation.md +12 -0
- package/docs/reference/editors-select.md +9 -0
- package/docs/reference/editors-session.md +11 -0
- package/docs/reference/editors-text.md +9 -0
- package/docs/reference/editors-value-list.md +6 -0
- package/docs/reference/editors.md +5 -0
- package/docs/reference/field-row.md +16 -0
- package/docs/reference/grid.md +39 -0
- package/docs/reference/react.md +89 -0
- package/docs/reference/selection.md +33 -0
- package/docs/reference/views.md +622 -0
- package/package.json +27 -4
- package/skills/views/SKILL.md +20 -5
- package/dist/filters/types.d.ts +0 -27
- package/dist/filters/types.js +0 -1
- package/dist/model/filter-pushdown.d.ts +0 -106
- package/dist/model/filter-pushdown.js +0 -147
|
@@ -0,0 +1,696 @@
|
|
|
1
|
+
# The grid
|
|
2
|
+
|
|
3
|
+
`GridTable`, from `@viewkitjs/views/grid`, is a spreadsheet over the rows you hand it: cell focus, typed editors, ranges, fill, copy and paste, undo, a footer per column and figures beside each group. It draws what it is given and reports what a person did. Which rows, in what order and in which groups, where an edit is saved, and what each person keeps between visits are your app's, and this page walks through each in the order a real list needs them. [Getting started](../getting-started.md) draws the first grid; this page assumes it.
|
|
4
|
+
|
|
5
|
+
## The rows and the columns
|
|
6
|
+
|
|
7
|
+
Every example on this page reads one registry of deals, bound to plain rows. A grid's columns come from `columnFrom`, as the [columns guide](columns.md) covers in full; each one states its starting `width`.
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
import assert from "node:assert/strict";
|
|
11
|
+
import { defineConventions, defineFields } from "@viewkitjs/fields";
|
|
12
|
+
import { bindFields, columnFrom, type ListGroup } from "@viewkitjs/views";
|
|
13
|
+
|
|
14
|
+
const DEAL_FIELDS = defineFields({
|
|
15
|
+
entity: "deal",
|
|
16
|
+
identity: "title",
|
|
17
|
+
fields: {
|
|
18
|
+
title: { type: "text", label: "Title", required: true },
|
|
19
|
+
value: { type: "currency", label: "Value", code: { fixed: "EUR" } },
|
|
20
|
+
stage: {
|
|
21
|
+
type: "status",
|
|
22
|
+
label: "Stage",
|
|
23
|
+
options: [
|
|
24
|
+
{ value: "open", label: "Open", slot: "pending" },
|
|
25
|
+
{ value: "won", label: "Won", slot: "success" },
|
|
26
|
+
{ value: "lost", label: "Lost", slot: "error" },
|
|
27
|
+
],
|
|
28
|
+
},
|
|
29
|
+
starred: { type: "boolean", label: "Starred" },
|
|
30
|
+
closeOn: { type: "date", label: "Close on", nullable: true },
|
|
31
|
+
company: { type: "relation", label: "Company", relation: { kind: "company" }, nullable: true },
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
|
|
36
|
+
|
|
37
|
+
type Link = { id: string; label: string };
|
|
38
|
+
type Deal = {
|
|
39
|
+
id: string;
|
|
40
|
+
title: string;
|
|
41
|
+
value: number;
|
|
42
|
+
stage: string;
|
|
43
|
+
starred: boolean;
|
|
44
|
+
closeOn: string | null;
|
|
45
|
+
company: Link | null;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
const DEAL_BINDINGS = bindFields<Deal, typeof DEAL_FIELDS>(DEAL_FIELDS, {
|
|
49
|
+
title: {
|
|
50
|
+
read: (deal) => deal.title,
|
|
51
|
+
// A text box emptied commits "": a deal needs a title, so the write refuses it.
|
|
52
|
+
write: (_deal, commit) =>
|
|
53
|
+
commit === "" ? { skip: true, reason: "A deal needs a title." } : { body: { title: commit } },
|
|
54
|
+
},
|
|
55
|
+
value: { read: (deal) => deal.value },
|
|
56
|
+
stage: { read: (deal) => deal.stage, write: (_deal, commit) => ({ body: { stage: commit } }) },
|
|
57
|
+
starred: { read: (deal) => deal.starred, write: (_deal, commit) => ({ body: { starred: commit } }) },
|
|
58
|
+
// A clear commits "", not a day: the field is nullable, so it stores null.
|
|
59
|
+
closeOn: {
|
|
60
|
+
read: (deal) => deal.closeOn,
|
|
61
|
+
write: (_deal, commit) => ({ body: { closeOn: commit === "" ? null : commit } }),
|
|
62
|
+
},
|
|
63
|
+
company: { read: (deal) => deal.company },
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
const columns = [
|
|
67
|
+
columnFrom(DEAL_BINDINGS.title, { id: "title", width: 240, editable: true }),
|
|
68
|
+
columnFrom(DEAL_BINDINGS.value, { id: "value", width: 120, defaultAggregate: "sum" }),
|
|
69
|
+
columnFrom(DEAL_BINDINGS.stage, { id: "stage", width: 120, editable: true }),
|
|
70
|
+
columnFrom(DEAL_BINDINGS.starred, { id: "starred", width: 90, editable: true }),
|
|
71
|
+
columnFrom(DEAL_BINDINGS.closeOn, { id: "closeOn", width: 120, editable: true }),
|
|
72
|
+
columnFrom(DEAL_BINDINGS.company, { id: "company", width: 160 }),
|
|
73
|
+
];
|
|
74
|
+
const [titleColumn, valueColumn, stageColumn, starredColumn, closeOnColumn, companyColumn] = columns;
|
|
75
|
+
|
|
76
|
+
const ACME: Link = { id: "c1", label: "Acme" };
|
|
77
|
+
const GLOBEX: Link = { id: "c2", label: "Globex" };
|
|
78
|
+
const LUMEN: Link = { id: "c3", label: "Lumen" };
|
|
79
|
+
|
|
80
|
+
const DEALS: Deal[] = [
|
|
81
|
+
{ id: "d1", title: "Acme renewal", value: 1200, stage: "won", starred: true, closeOn: "2026-03-06", company: ACME },
|
|
82
|
+
{ id: "d2", title: "Globex pilot", value: 5400, stage: "open", starred: false, closeOn: null, company: GLOBEX },
|
|
83
|
+
{ id: "d3", title: "Birch audit", value: 800, stage: "open", starred: false, closeOn: "2026-04-01", company: null },
|
|
84
|
+
{ id: "d4", title: "Lumen trial", value: 30000, stage: "won", starred: true, closeOn: "2026-02-20", company: LUMEN },
|
|
85
|
+
];
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Five props, and the rows in groups
|
|
89
|
+
|
|
90
|
+
`GridTable` needs five props: `groups`, the rows in groups; `grouped`, whether the list is grouped; `getRowId`, each row's id; `columns`; and `onOpenRow`, what opening a row does (a click on the title's text). Everything else is optional.
|
|
91
|
+
|
|
92
|
+
The rows always arrive in groups. A `ListGroup` is one group: its `key`, its `label` (`null` for none), its `items`, already filtered and sorted, and, when your database counted them over the whole group, its `figures` (below). A list that isn't grouped hands one group with `grouped={false}`, and the grid draws its rows with no band.
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
import { GridTable } from "@viewkitjs/views/grid";
|
|
96
|
+
|
|
97
|
+
const allDeals: ListGroup<Deal>[] = [{ key: "all", label: null, items: DEALS }];
|
|
98
|
+
|
|
99
|
+
function PlainDeals({ onOpen }: { onOpen: (deal: Deal) => void }) {
|
|
100
|
+
return (
|
|
101
|
+
<GridTable groups={allDeals} grouped={false} getRowId={(deal) => deal.id} columns={columns} onOpenRow={onOpen} />
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The same record may sit in two groups (grouped by a list of tags, a deal sits under each of its tags): the grid keys each drawn row by its group and its id, so focus, an editor and a range land on the copy you pointed at.
|
|
107
|
+
|
|
108
|
+
When the rows a view shows are replaced as a whole (another saved view, another filter), pass that view's identity as `transitionKey`: the grid paints its wait first, then mounts the rows. `transitionPending` holds the wait while your rows load, and `transitionLabel` words it.
|
|
109
|
+
|
|
110
|
+
## Filtering, sorting and grouping the rows you hold
|
|
111
|
+
|
|
112
|
+
When your app holds the rows, `evaluateView` from `@viewkitjs/fields/query` runs a saved view over them: the filter, the sorts, then the group. It returns the rows in order and, when the view groups, its buckets. A bucket is a group nearly as the grid takes it, so turning the answer into `ListGroup`s is a map. Fields' queries guide, at `node_modules/@viewkitjs/fields/docs/guides/queries.md`, covers the filter tree, the sort and the group in full.
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import type { FieldDef } from "@viewkitjs/fields";
|
|
116
|
+
import { evaluateView, type FilterTree, type ViewFieldReader, type ViewQuery } from "@viewkitjs/fields/query";
|
|
117
|
+
|
|
118
|
+
const DEAL_FIELD_MAP: Readonly<Record<string, FieldDef>> = DEAL_FIELDS;
|
|
119
|
+
|
|
120
|
+
/** How the evaluator reads a deal: the field from the registry, the value from the row's own key. */
|
|
121
|
+
const dealReader: ViewFieldReader<Deal> = {
|
|
122
|
+
fieldOf: (key) => DEAL_FIELD_MAP[key],
|
|
123
|
+
read: (deal, key) => (deal as Record<string, unknown>)[key],
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
/** A view's answer as the grid's groups: one group when the view does not group, else a group per bucket shown. */
|
|
127
|
+
function groupsOf(rows: readonly Deal[], query: ViewQuery): ListGroup<Deal>[] {
|
|
128
|
+
const { rows: ordered, buckets } = evaluateView(rows, query, dealReader, { conventions });
|
|
129
|
+
if (!buckets) return [{ key: "all", label: null, items: ordered }];
|
|
130
|
+
return buckets
|
|
131
|
+
.filter((bucket) => !bucket.hidden)
|
|
132
|
+
.map((bucket) => ({ key: bucket.key, label: bucket.label, items: bucket.items }));
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const bigDeals: FilterTree = { op: "and", items: [{ fieldKey: "value", operator: "gte", value: 1000 }] };
|
|
136
|
+
const bigDealsByStage: ViewQuery = {
|
|
137
|
+
filter: bigDeals,
|
|
138
|
+
sorts: [{ fieldKey: "value", direction: "desc" }],
|
|
139
|
+
// A status groups in its declared order; `hideEmpty` flags the stages nobody holds, and `groupsOf` drops them.
|
|
140
|
+
group: { fieldKey: "stage", order: { mode: "lifecycle", dir: "asc" }, buckets: [], hideEmpty: true },
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
const stageGroups = groupsOf(DEALS, bigDealsByStage);
|
|
144
|
+
assert.deepEqual(
|
|
145
|
+
stageGroups.map((group) => [group.key, group.label, group.items.map((deal) => deal.id)]),
|
|
146
|
+
[
|
|
147
|
+
["open", "Open", ["d2"]],
|
|
148
|
+
["won", "Won", ["d4", "d1"]],
|
|
149
|
+
]
|
|
150
|
+
);
|
|
151
|
+
|
|
152
|
+
// The same view ungrouped: one group, the rows in the view's order.
|
|
153
|
+
const bigDealsFlat = groupsOf(DEALS, { ...bigDealsByStage, group: null });
|
|
154
|
+
assert.deepEqual(bigDealsFlat[0].items.map((deal) => deal.id), ["d4", "d2", "d1"]);
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
A list whose rows come a page at a time from a database runs the same view there instead, and hands the grid the groups its query answered.
|
|
158
|
+
|
|
159
|
+
## The sort and the group
|
|
160
|
+
|
|
161
|
+
The header's menu offers Sort ascending, Sort descending and Clear sort, and Group by and Ungroup; a group's band offers its own Sort rows. The grid holds none of that state: it shows what you hand it and calls you with what the person picked.
|
|
162
|
+
|
|
163
|
+
- `sort`, a `GridSortState`: the sort key in force (`value`), its direction (`dir`, `"asc"` or `"desc"`), and `onChange`, called with the pick. Clear sort calls it with an empty `value`.
|
|
164
|
+
- `groupBy`, a `GridGroupByState`: the field key the list is grouped by, or `null`, and `onChange`, called with a field key, or `null` to ungroup.
|
|
165
|
+
- `sortOptions`, the `GridGroupSortOption`s a group's band offers: each a sort key, its label and the direction it opens in.
|
|
166
|
+
- `viewBacked`: the list is a saved view over your fields. The header then offers Sort on every bound column (a column with a declared `sortKey` offers it anywhere) and Group by on every field whose type can split a list.
|
|
167
|
+
|
|
168
|
+
`sortableColumns` from the root door lists the keys a saved view can sort by, one per key in the columns' order, and `sortDirFor` the direction a field opens in: a number, a date or a yes/no largest or newest first, text and options A to Z.
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
171
|
+
import { useMemo, useState } from "react";
|
|
172
|
+
import { columnLabel, sortableColumns, sortDirFor, type OrderDir } from "@viewkitjs/views";
|
|
173
|
+
import type { GridGroupByState, GridGroupSortOption, GridSortState } from "@viewkitjs/views/grid";
|
|
174
|
+
|
|
175
|
+
const dealSortOptions: GridGroupSortOption[] = sortableColumns(columns).map((entry) => ({
|
|
176
|
+
value: entry.key,
|
|
177
|
+
label: columnLabel(entry.column),
|
|
178
|
+
defaultDir: entry.column.field ? sortDirFor(entry.column.field) : "asc",
|
|
179
|
+
}));
|
|
180
|
+
|
|
181
|
+
assert.deepEqual(
|
|
182
|
+
dealSortOptions.map((option) => [option.value, option.label, option.defaultDir]),
|
|
183
|
+
[
|
|
184
|
+
["title", "Title", "asc"],
|
|
185
|
+
["value", "Value", "desc"],
|
|
186
|
+
["stage", "Stage", "asc"],
|
|
187
|
+
["starred", "Starred", "desc"],
|
|
188
|
+
["closeOn", "Close on", "desc"],
|
|
189
|
+
["company", "Company", "asc"],
|
|
190
|
+
]
|
|
191
|
+
);
|
|
192
|
+
|
|
193
|
+
function SortedDeals({ deals, onOpen }: { deals: Deal[]; onOpen: (deal: Deal) => void }) {
|
|
194
|
+
const [order, setOrder] = useState<{ value: string; dir: OrderDir }>({ value: "value", dir: "desc" });
|
|
195
|
+
const [groupKey, setGroupKey] = useState<string | null>("stage");
|
|
196
|
+
const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set());
|
|
197
|
+
|
|
198
|
+
const groups = useMemo(
|
|
199
|
+
() =>
|
|
200
|
+
groupsOf(deals, {
|
|
201
|
+
filter: bigDeals,
|
|
202
|
+
sorts: order.value ? [{ fieldKey: order.value, direction: order.dir }] : [],
|
|
203
|
+
group: groupKey
|
|
204
|
+
? { fieldKey: groupKey, order: { mode: "lifecycle", dir: "asc" }, buckets: [], hideEmpty: true }
|
|
205
|
+
: null,
|
|
206
|
+
}),
|
|
207
|
+
[deals, order, groupKey]
|
|
208
|
+
);
|
|
209
|
+
|
|
210
|
+
const sort: GridSortState = { ...order, onChange: setOrder };
|
|
211
|
+
const groupBy: GridGroupByState = { fieldKey: groupKey, onChange: setGroupKey };
|
|
212
|
+
|
|
213
|
+
return (
|
|
214
|
+
<GridTable
|
|
215
|
+
groups={groups}
|
|
216
|
+
grouped={groupKey != null}
|
|
217
|
+
getRowId={(deal) => deal.id}
|
|
218
|
+
columns={columns}
|
|
219
|
+
onOpenRow={onOpen}
|
|
220
|
+
viewBacked
|
|
221
|
+
sort={sort}
|
|
222
|
+
groupBy={groupBy}
|
|
223
|
+
sortOptions={dealSortOptions}
|
|
224
|
+
isCollapsed={(key) => collapsed.has(key)}
|
|
225
|
+
onToggleGroup={(key) =>
|
|
226
|
+
setCollapsed((current) => {
|
|
227
|
+
const next = new Set(current);
|
|
228
|
+
if (next.has(key)) next.delete(key);
|
|
229
|
+
else next.add(key);
|
|
230
|
+
return next;
|
|
231
|
+
})
|
|
232
|
+
}
|
|
233
|
+
/>
|
|
234
|
+
);
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Collapsing is yours too: `isCollapsed` answers for a group's key and `onToggleGroup` is called when its caret is pressed. `renderGroupLabel` draws a group's name your way (a relation's chip, an avatar), and `onHideGroup`, where your view can hide a group, puts Hide group on its band's menu.
|
|
239
|
+
|
|
240
|
+
## Writes
|
|
241
|
+
|
|
242
|
+
Editing turns on with `onCellCommit`: without it the grid is read-only, and invites no edit. It is called with the row, the column's id, the value the editor committed and, for an undo or a redo, a `GridCommitContext`. The grid shows the value at once and keeps it while the write runs; how your function ends decides what happens next.
|
|
243
|
+
|
|
244
|
+
- It resolves with nothing, or `{ status: "confirmed" }`: the write landed, and ⌘Z can undo it. `history: { prev, next }` records what undo and redo put back, when what was stored is not what the cell sent; `history: false` keeps no step for this write. `settlement: "requested"` says the row holds the value but the provider behind it has not accepted it yet: the cell keeps its value and wears the pending look until your rows carry it.
|
|
245
|
+
- It resolves with `{ status: "confirmed", stored }`: the write landed, but what your server kept isn't what the cell sent (it stripped an invisible character, read a label as its key, kept `""` as `null`). `stored` is the value as your rows will read it in this column. The cell shows it at once in place of what was typed, ⌘Z restores from it (unless `history` says otherwise), and when your rows carry it the cell clears without a "changed elsewhere". Leave `stored` out and nothing changes: the cell holds what was typed until your rows carry exactly that. On an undo or a redo it is ignored.
|
|
246
|
+
- It resolves with `{ status: "unconfirmed", history: false }`: nothing says the write landed, and it leaves no step to undo.
|
|
247
|
+
- It rejects (or throws): the cell rolls back to the value it held. Never swallow a failed request, since the rejection is what rolls the cell back.
|
|
248
|
+
|
|
249
|
+
A `write` that refuses, `{ skip: true, reason }`, is a rejection too: throw its reason, and the cell rolls back. The grid shows no reason for a rejection, so your app shows it, through its own toast. Returning nothing on a refusal would count a write that was never sent as landed, with a step to undo.
|
|
250
|
+
|
|
251
|
+
What a cell commits is its type's commit ([the contract](../contract.md#four-shapes-of-a-value)), with one exception: Delete, Cut, the row menu's Clear and a clear over a range commit `""` for most types (a relation `null`, a multiselect `[]`, a boolean `false`). A `write` maps `""` to what the row stores for nothing, as `closeOn` does above. An undo that empties a number, percent or money cell again writes `null`.
|
|
252
|
+
|
|
253
|
+
An undo or a redo calls you again with `{ kind: "restore", expected }`: `expected` is what the cell holds if nobody changed it since. A host that versions its rows can refuse the restore when the row holds something else.
|
|
254
|
+
|
|
255
|
+
A fill, a paste, a Delete over a range or a batch action writes many cells at once. With `onCellsCommit` they arrive in one call, and you answer with one `GridCommitOutcome` per edit, in order: a `failed` outcome rolls that cell back and keeps the rest. A rejection rolls every cell of the call back. Without `onCellsCommit`, each cell goes to `onCellCommit` alone.
|
|
256
|
+
|
|
257
|
+
```tsx
|
|
258
|
+
import type { GridCellCommitFn, GridCellsCommitFn, GridCommitOutcome } from "@viewkitjs/views/grid";
|
|
259
|
+
|
|
260
|
+
const saved: { id: string; body: Record<string, unknown> }[] = [];
|
|
261
|
+
/** Your PATCH request: here it refuses a deal that is gone. */
|
|
262
|
+
async function saveDeal(id: string, body: Record<string, unknown>): Promise<void> {
|
|
263
|
+
if (id === "gone") throw new Error("This deal was deleted");
|
|
264
|
+
saved.push({ id, body });
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
const refusals: string[] = [];
|
|
268
|
+
/** Your toast. */
|
|
269
|
+
function showRefusal(reason: string): void {
|
|
270
|
+
refusals.push(reason);
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
const onCellCommit: GridCellCommitFn<Deal> = async (deal, columnId, value) => {
|
|
274
|
+
const patch = columns.find((column) => column.id === columnId)?.binding?.write?.(deal, value);
|
|
275
|
+
if (!patch) throw new Error(`${columnId} can't be edited`);
|
|
276
|
+
if ("skip" in patch) {
|
|
277
|
+
// Refused: thrown, so the cell rolls back, and said through your toast, since the grid says nothing.
|
|
278
|
+
const reason = patch.reason ?? "This change can't be saved.";
|
|
279
|
+
showRefusal(reason);
|
|
280
|
+
throw new Error(reason);
|
|
281
|
+
}
|
|
282
|
+
await saveDeal(deal.id, patch.body); // a rejection rolls the cell back
|
|
283
|
+
return { status: "confirmed" };
|
|
284
|
+
};
|
|
285
|
+
|
|
286
|
+
/** Many cells at once: one outcome each, so a refused cell rolls back alone. */
|
|
287
|
+
async function commitEach(edits: Parameters<GridCellsCommitFn<Deal>>[0]): Promise<GridCommitOutcome[]> {
|
|
288
|
+
return Promise.all(
|
|
289
|
+
edits.map(async ({ row, columnId, value, context }): Promise<GridCommitOutcome> => {
|
|
290
|
+
try {
|
|
291
|
+
return (await onCellCommit(row, columnId, value, context)) ?? { status: "confirmed" };
|
|
292
|
+
} catch (error) {
|
|
293
|
+
return { status: "failed", error };
|
|
294
|
+
}
|
|
295
|
+
})
|
|
296
|
+
);
|
|
297
|
+
}
|
|
298
|
+
const onCellsCommit: GridCellsCommitFn<Deal> = commitEach;
|
|
299
|
+
|
|
300
|
+
assert.deepEqual(await onCellCommit(DEALS[1], "stage", "won"), { status: "confirmed" });
|
|
301
|
+
// An emptied title is refused: the promise rejects and your toast says why.
|
|
302
|
+
await assert.rejects(onCellCommit(DEALS[0], "title", ""));
|
|
303
|
+
assert.deepEqual(refusals, ["A deal needs a title."]);
|
|
304
|
+
|
|
305
|
+
const goneDeal: Deal = { ...DEALS[2], id: "gone" };
|
|
306
|
+
const outcomes = await commitEach([
|
|
307
|
+
{ row: DEALS[2], columnId: "stage", value: "won" },
|
|
308
|
+
{ row: goneDeal, columnId: "stage", value: "lost" },
|
|
309
|
+
]);
|
|
310
|
+
assert.deepEqual(
|
|
311
|
+
outcomes.map((outcome) => outcome.status),
|
|
312
|
+
["confirmed", "failed"]
|
|
313
|
+
);
|
|
314
|
+
assert.deepEqual(saved, [
|
|
315
|
+
{ id: "d2", body: { stage: "won" } },
|
|
316
|
+
{ id: "d3", body: { stage: "won" } },
|
|
317
|
+
]);
|
|
318
|
+
|
|
319
|
+
// A cleared close date arrives as "" and is stored as null.
|
|
320
|
+
await onCellCommit(DEALS[0], "closeOn", "");
|
|
321
|
+
assert.deepEqual(saved.at(-1), { id: "d1", body: { closeOn: null } });
|
|
322
|
+
|
|
323
|
+
function EditableDeals({ onOpen }: { onOpen: (deal: Deal) => void }) {
|
|
324
|
+
return (
|
|
325
|
+
<GridTable
|
|
326
|
+
groups={allDeals}
|
|
327
|
+
grouped={false}
|
|
328
|
+
getRowId={(deal) => deal.id}
|
|
329
|
+
columns={columns}
|
|
330
|
+
onOpenRow={onOpen}
|
|
331
|
+
onCellCommit={onCellCommit}
|
|
332
|
+
onCellsCommit={onCellsCommit}
|
|
333
|
+
/>
|
|
334
|
+
);
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Before a value reaches you it has passed the grid's write gate (Editing and writes, below): a value the column refuses is never sent. Most refusals are said in a toast through your toast port. A select, status, date, tags, relation, number or range editor keeps the value open with its reason instead (Editing and writes, below). In a batch a refused cell is dropped while the rest are written.
|
|
339
|
+
|
|
340
|
+
## Preferences
|
|
341
|
+
|
|
342
|
+
What each person keeps for a list (the table's switches, the density, the columns' widths, order and visibility, each field's format, the footer's picks and the figures beside a group's name) is a `ListViewPrefs`. `useGridTablePrefs` turns one into the grid's props: hand it the preferences and a setter that takes a patch, and spread the `gridProps` it returns onto the grid.
|
|
343
|
+
|
|
344
|
+
Where they are kept is yours: your own store, a saved view's row, `localStorage`. The hook reads only what you hand it and writes only through your setter. `LIST_VIEW_PREF_DEFAULTS` is a list nobody has touched. Here the preferences live in component state; a real list loads them from its store and saves each patch back.
|
|
345
|
+
|
|
346
|
+
```tsx
|
|
347
|
+
import { useCallback } from "react";
|
|
348
|
+
import { LIST_VIEW_PREF_DEFAULTS, type ListViewPrefs } from "@viewkitjs/views";
|
|
349
|
+
import { useGridTablePrefs } from "@viewkitjs/views/grid";
|
|
350
|
+
|
|
351
|
+
/** Decimals set back to Automatic arrive as their key holding null: the key leaves the map. */
|
|
352
|
+
function mergeDecimals(current: Record<string, number>, patch: Record<string, number>): Record<string, number> {
|
|
353
|
+
const next: Record<string, number> = { ...current, ...patch };
|
|
354
|
+
for (const key of Object.keys(next)) if (next[key] == null) delete next[key];
|
|
355
|
+
return next;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
assert.deepEqual(mergeDecimals({ value: 0, other: 2 }, { value: null as unknown as number }), { other: 2 });
|
|
359
|
+
|
|
360
|
+
/** A patch applied to the preferences: each key replaced, decimals merged. */
|
|
361
|
+
function applyPrefsPatch(current: ListViewPrefs, patch: Partial<ListViewPrefs>): ListViewPrefs {
|
|
362
|
+
const next: ListViewPrefs = { ...current, ...patch };
|
|
363
|
+
if (patch.gridDecimals) next.gridDecimals = mergeDecimals(current.gridDecimals, patch.gridDecimals);
|
|
364
|
+
return next;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
assert.deepEqual(applyPrefsPatch(LIST_VIEW_PREF_DEFAULTS, { gridAlwaysCheckboxes: true }).gridAlwaysCheckboxes, true);
|
|
368
|
+
|
|
369
|
+
function useDealPrefs() {
|
|
370
|
+
const [prefs, setStored] = useState<ListViewPrefs>(LIST_VIEW_PREF_DEFAULTS);
|
|
371
|
+
const setPrefs = useCallback(
|
|
372
|
+
(patch: Partial<ListViewPrefs>) => setStored((current) => applyPrefsPatch(current, patch)),
|
|
373
|
+
[]
|
|
374
|
+
);
|
|
375
|
+
return { prefs, setPrefs };
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
function DealsWithPrefs({ onOpen }: { onOpen: (deal: Deal) => void }) {
|
|
379
|
+
const { prefs, setPrefs } = useDealPrefs();
|
|
380
|
+
const { gridProps } = useGridTablePrefs({ prefs, setPrefs, columns, viewBacked: true });
|
|
381
|
+
return (
|
|
382
|
+
<GridTable
|
|
383
|
+
{...gridProps}
|
|
384
|
+
groups={allDeals}
|
|
385
|
+
grouped={false}
|
|
386
|
+
getRowId={(deal) => deal.id}
|
|
387
|
+
columns={columns}
|
|
388
|
+
onOpenRow={onOpen}
|
|
389
|
+
/>
|
|
390
|
+
);
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
The columns' widths, order and visibility travel as `columnState`, a `ListColumnState` (`widths` by column id, `hidden` ids, `visible` ids of columns hidden by default that the person turned on, and `order`), and every change as `onColumnStateChange`; `gridProps` carries both. Resizing, moving and hiding a column, and the header's "+ Add column", which lists the hidden columns, appear only where `onColumnStateChange` is passed, since there would be nowhere to keep them. `renderAddColumn` replaces that last cell with your own, and `renderColumnMenuRows` adds your rows (Edit field, say) to a column's menu above Hide.
|
|
395
|
+
|
|
396
|
+
`gridProps` also carries the per-person switches: `verticalBorders`, `showRowIcon` (the `rowIcon` you declare, in the title cell), `freezeIdentity` (every column through the title pinned at the left edge; off in `LIST_VIEW_PREF_DEFAULTS`, so start your prefs with `gridFreezeIdentity: true` to open it on), `alwaysCheckboxes` and `scale`, the density. Every row is one height, and a cell's text stays on one line.
|
|
397
|
+
|
|
398
|
+
## Figures
|
|
399
|
+
|
|
400
|
+
Each column's footer shows one figure: the person's pick from what the column offers (sum, average, min, max and count for a number, count, filled and unique for the rest), else the column's `defaultAggregate`. Pass `aggregates`, the picks by column id, and `onAggregateChange`, which makes each footer cell a picker. On a `viewBacked` list only a column with a field can change its pick. With neither `onAggregateChange` nor a `renderAggregate` of your own, the grid draws no footer. `renderAggregate(columnId, group)` draws a footer cell yourself, with no label.
|
|
401
|
+
|
|
402
|
+
A group's band shows its count and, beside it, the figures the person turned on. `groupSummary` is that set of parts (`"count"`, `"total"` for the list's first figure, `total:<columnId>` for each one after it), changed through `onGroupSummaryChange`, and `groupFigures` declares which figures a band can show and how each draws. `countNoun` words the count ("2 deals"); without it the count is bare. `countOf` answers the count when a group holds more rows than are loaded.
|
|
403
|
+
|
|
404
|
+
When the rows come a page at a time, a group's `figures` are your database's over the whole group, and the footer reads its picks from them rather than from the rows in hand. `GroupFigures` in the [root reference](../reference/views.md) has the shape.
|
|
405
|
+
|
|
406
|
+
```tsx
|
|
407
|
+
import { groupFigurePart, type ListAggregateKind } from "@viewkitjs/views";
|
|
408
|
+
import type { GridGroupFigure, GroupCountNoun } from "@viewkitjs/views/grid";
|
|
409
|
+
|
|
410
|
+
const euros = new Intl.NumberFormat(conventions.locale, { style: "currency", currency: "EUR" });
|
|
411
|
+
|
|
412
|
+
/** A group's total value: the database's figure when it counted one, else the rows in hand. */
|
|
413
|
+
function dealTotal(group: ListGroup<Deal>): string {
|
|
414
|
+
const counted = group.figures?.fields.value?.sum;
|
|
415
|
+
return euros.format(counted ?? group.items.reduce((sum, deal) => sum + deal.value, 0));
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
const dealFigures: GridGroupFigure<Deal>[] = [{ part: groupFigurePart("value", true), label: "Value", render: dealTotal }];
|
|
419
|
+
const dealNoun: GroupCountNoun = { one: "deal", other: "deals" };
|
|
420
|
+
|
|
421
|
+
assert.equal(dealFigures[0].part, "total");
|
|
422
|
+
assert.equal(dealTotal(stageGroups[1]), "€31,200.00");
|
|
423
|
+
|
|
424
|
+
function DealsWithFigures({ onOpen }: { onOpen: (deal: Deal) => void }) {
|
|
425
|
+
const [aggregates, setAggregates] = useState<Record<string, ListAggregateKind>>({});
|
|
426
|
+
return (
|
|
427
|
+
<GridTable
|
|
428
|
+
groups={stageGroups}
|
|
429
|
+
grouped
|
|
430
|
+
getRowId={(deal) => deal.id}
|
|
431
|
+
columns={columns}
|
|
432
|
+
onOpenRow={onOpen}
|
|
433
|
+
aggregates={aggregates}
|
|
434
|
+
onAggregateChange={(columnId, kind) => setAggregates((current) => ({ ...current, [columnId]: kind }))}
|
|
435
|
+
groupSummary={["count", "total"]}
|
|
436
|
+
groupFigures={dealFigures}
|
|
437
|
+
countNoun={dealNoun}
|
|
438
|
+
/>
|
|
439
|
+
);
|
|
440
|
+
}
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
`defaultCurrency` is the reader's own currency: a money column read in its original currencies totals in it.
|
|
444
|
+
|
|
445
|
+
## The row's menu and opening a row
|
|
446
|
+
|
|
447
|
+
On a desktop, a click on the title's text calls `onOpenRow`, and a click anywhere else selects the cell. Below your provider's `desktopQuery`, a tap anywhere on the title's cell calls `onOpenRow`, and a tap on any other cell opens its editor (The keyboard and the pointer, below). `rowHref` gives a row its own page: a middle-click opens it in a new tab, and the row's menu starts with Open page. `onPrefetchRow` is called on a pointer's intent to open, to warm the row's detail.
|
|
448
|
+
|
|
449
|
+
The row's menu opens on a right-click and from the row's ⋯ at its end. It holds the cell's Copy, Cut, Paste and Clear, the rows your `rowMenu` builds, and Delete when you pass `onRowDelete`. Delete asks your `confirm` port first, with `deleteLabel` as what is deleted, and a delete that rejects says so through your toast port. `contextMenu` replaces `rowMenu` on right-click when the two must differ.
|
|
450
|
+
|
|
451
|
+
`onOpenRelation` makes relation chips open what they point at; it receives the chip's value, so `value.entity` says which kind of record to open. Without it, a chip goes where your `RelationLink` atom says ([atoms](atoms.md)). `entityIcon` gives each kind of record its glyph in relation cells that carry none.
|
|
452
|
+
|
|
453
|
+
A field whose changes carry rules of their own (a lost deal needs a reason) is changed through verbs, not an editor: its column is a `command` column, and its cell opens the verbs `commands` names for its field key. The same map serves a record's panel and a card, so each verb is declared once. Without it, a command column is a read-only badge.
|
|
454
|
+
|
|
455
|
+
```tsx
|
|
456
|
+
import type { FieldMenus, ListRelationValue } from "@viewkitjs/views";
|
|
457
|
+
import type { ViewsRowMenuItem } from "@viewkitjs/views/react";
|
|
458
|
+
|
|
459
|
+
declare function duplicateDeal(deal: Deal): void;
|
|
460
|
+
declare function deleteDeal(id: string): Promise<void>;
|
|
461
|
+
declare function openRecord(kind: string | undefined, id: string): void;
|
|
462
|
+
declare function reopenDeal(deal: Deal): void;
|
|
463
|
+
declare function markDealLost(deal: Deal): void;
|
|
464
|
+
|
|
465
|
+
function dealMenu(deal: Deal): ViewsRowMenuItem[] {
|
|
466
|
+
return [{ label: "Duplicate", onClick: () => duplicateDeal(deal) }];
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/** The verbs a command field offers, by field key, resolved per row. */
|
|
470
|
+
const dealVerbs: FieldMenus<Deal> = {
|
|
471
|
+
stage: (deal) =>
|
|
472
|
+
deal.stage === "open"
|
|
473
|
+
? [{ label: "Mark lost", onClick: () => markDealLost(deal), destructive: true }]
|
|
474
|
+
: [{ label: "Reopen", onClick: () => reopenDeal(deal) }],
|
|
475
|
+
};
|
|
476
|
+
|
|
477
|
+
function DealsWithMenus({ onOpen }: { onOpen: (deal: Deal) => void }) {
|
|
478
|
+
return (
|
|
479
|
+
<GridTable
|
|
480
|
+
groups={allDeals}
|
|
481
|
+
grouped={false}
|
|
482
|
+
getRowId={(deal) => deal.id}
|
|
483
|
+
columns={columns}
|
|
484
|
+
onOpenRow={onOpen}
|
|
485
|
+
rowHref={(deal) => `/deals/${deal.id}`}
|
|
486
|
+
rowMenu={dealMenu}
|
|
487
|
+
onRowDelete={deleteDeal}
|
|
488
|
+
deleteLabel="deal"
|
|
489
|
+
onOpenRelation={(value: ListRelationValue) => openRecord(value.entity, value.id)}
|
|
490
|
+
commands={dealVerbs}
|
|
491
|
+
/>
|
|
492
|
+
);
|
|
493
|
+
}
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
`rowActions` adds buttons to a row's title cell, drawn on the row under the pointer, and `rowClassName` a class to a row. Each of `rowActions` that applies to a row (a glyph, a click and a label for it) is also a row of that row's menu, after Select, so a key and a right-click reach it; one whose label your `contextMenu` already carries isn't listed twice.
|
|
497
|
+
|
|
498
|
+
## Format overrides
|
|
499
|
+
|
|
500
|
+
A column's menu carries the knobs its type allows: an option's colour, a date's style and whether it shows its time, a duration's style, a number's decimals and a money column's currency, a percent's display. Each pair is a map and a handler: `optionColors` and `onOptionColorChange`, `dateStyles` and `onDateStyleChange`, `durationStyles` and `onDurationStyleChange`, `showTimeOverrides` and `onShowTimeChange`, `numberFormats` and `onNumberFormatChange` (`decimals: null` is the field's own, Automatic), `percentDisplays` and `onPercentDisplayChange`. Every map is keyed by field key, and every handler's first argument is that key, because a format is an answer about a field, shared by every surface that draws it. `fieldKeyOf` gives a column's field key; `gridProps` from `useGridTablePrefs` carries every pair.
|
|
501
|
+
|
|
502
|
+
```ts
|
|
503
|
+
import { fieldKeyOf } from "@viewkitjs/views";
|
|
504
|
+
|
|
505
|
+
assert.equal(fieldKeyOf(valueColumn), "value");
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
`formatsWritable={false}` hides those knobs where there is nowhere to store them. A reader's own currency reading stays either way.
|
|
509
|
+
|
|
510
|
+
## A list's locks
|
|
511
|
+
|
|
512
|
+
Three layers decide whether a cell may be written, and each only takes away from the one before: the column's declaration, your workspace's settings for the list, and a person's preferences. The settings are a `ListSettingsConfig` you store and hand the grid as `listConfig`: `readOnly` for the whole list, or a lock per field under `columns`. A locked column refuses every write, by every route, and still sorts, hides and resizes; a read-only list says so with a badge in its header. `toggleListColumnLock` and `toggleListReadOnly` build the config, sparse.
|
|
513
|
+
|
|
514
|
+
```tsx
|
|
515
|
+
import {
|
|
516
|
+
columnEffectiveWritable,
|
|
517
|
+
columnWritable,
|
|
518
|
+
toggleListColumnLock,
|
|
519
|
+
toggleListReadOnly,
|
|
520
|
+
type ListSettingsConfig,
|
|
521
|
+
} from "@viewkitjs/views";
|
|
522
|
+
|
|
523
|
+
const stageLocked: ListSettingsConfig = toggleListColumnLock(undefined, "stage");
|
|
524
|
+
assert.deepEqual(stageLocked, { columns: { stage: { locked: true } } });
|
|
525
|
+
assert.equal(columnWritable(stageColumn), true); // the declaration allows it
|
|
526
|
+
assert.equal(columnEffectiveWritable(stageColumn, stageLocked), false); // the lock takes it away
|
|
527
|
+
assert.deepEqual(toggleListColumnLock(stageLocked, "stage"), {});
|
|
528
|
+
assert.equal(columnEffectiveWritable(titleColumn, toggleListReadOnly(undefined)), false);
|
|
529
|
+
|
|
530
|
+
function LockedDeals({ settings, onOpen }: { settings: ListSettingsConfig; onOpen: (deal: Deal) => void }) {
|
|
531
|
+
return (
|
|
532
|
+
<GridTable
|
|
533
|
+
groups={allDeals}
|
|
534
|
+
grouped={false}
|
|
535
|
+
getRowId={(deal) => deal.id}
|
|
536
|
+
columns={columns}
|
|
537
|
+
onOpenRow={onOpen}
|
|
538
|
+
onCellCommit={onCellCommit}
|
|
539
|
+
listConfig={settings}
|
|
540
|
+
/>
|
|
541
|
+
);
|
|
542
|
+
}
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
The locks constrain the interface, not access: your API still guards its own writes. The grid draws no lock toggle and stores no config: a settings surface of your own changes `settings` and hands the grid the new value.
|
|
546
|
+
|
|
547
|
+
## Loading more and the empty state
|
|
548
|
+
|
|
549
|
+
A list that loads its rows a page at a time passes `loadMore`: `hasMore`, `onReveal`, called when the person reaches the end, and an optional `label`. The `LoadMore` atom draws it (the default watches a point past the last row). `renderGroupFooter` draws a group's own continuation after its loaded rows. `emptyState` is drawn under the header when there is nothing to show: no rows in an ungrouped list, no groups in a grouped one. The grid keeps it to the width in view, so a table wider than its box still shows the message whole and centred where the person looks; pass it as it is, with no wrapper of your own.
|
|
550
|
+
|
|
551
|
+
```tsx
|
|
552
|
+
function PagedDeals({
|
|
553
|
+
deals,
|
|
554
|
+
hasMore,
|
|
555
|
+
onMore,
|
|
556
|
+
onOpen,
|
|
557
|
+
}: {
|
|
558
|
+
deals: Deal[];
|
|
559
|
+
hasMore: boolean;
|
|
560
|
+
onMore: () => void;
|
|
561
|
+
onOpen: (deal: Deal) => void;
|
|
562
|
+
}) {
|
|
563
|
+
return (
|
|
564
|
+
<GridTable
|
|
565
|
+
groups={[{ key: "all", label: null, items: deals }]}
|
|
566
|
+
grouped={false}
|
|
567
|
+
getRowId={(deal) => deal.id}
|
|
568
|
+
columns={columns}
|
|
569
|
+
onOpenRow={onOpen}
|
|
570
|
+
loadMore={{ hasMore, onReveal: onMore, label: "More deals" }}
|
|
571
|
+
emptyState={<p>No deals match this view.</p>}
|
|
572
|
+
/>
|
|
573
|
+
);
|
|
574
|
+
}
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
`selection` turns on the checkbox rail and a bar of your own over the selected rows ([the selection guide](selection.md)).
|
|
578
|
+
|
|
579
|
+
## Editing and writes
|
|
580
|
+
|
|
581
|
+
**Which editor.** A column marked `editable` mounts the editor its type names, as `gridEditorKind` answers. A column carrying `multiple` (several emails, phones, links or domains) mounts the value list editor and pastes as a list; on any other type `multiple` mounts nothing. `editable` on a type with no editor mounts nothing.
|
|
582
|
+
|
|
583
|
+
**Two questions, not one.** `gridColumnHasEditor` answers whether a column mounts an editor: what a click on the focused cell, a double-click, Enter and typing ask. `columnWritable` answers whether it can be written at all, by any route: an editor, Delete, Clear, a fill, a paste, a boolean's own button. It refuses a derived (`custom`) or `command` column first. A boolean has no editor and is still writable. The grid asks `columnEffectiveWritable`, which adds the list's locks, and so should anything of yours that gates a write.
|
|
584
|
+
|
|
585
|
+
```ts
|
|
586
|
+
import { gridColumnHasEditor, gridEditorKind, gridNormalizeWrite } from "@viewkitjs/views";
|
|
587
|
+
|
|
588
|
+
assert.equal(gridEditorKind(titleColumn), "text");
|
|
589
|
+
assert.equal(gridEditorKind(stageColumn), "select");
|
|
590
|
+
assert.equal(gridEditorKind(closeOnColumn), "date");
|
|
591
|
+
assert.equal(gridEditorKind(valueColumn), null); // not editable
|
|
592
|
+
|
|
593
|
+
assert.equal(gridColumnHasEditor(starredColumn), false); // a boolean flips in place
|
|
594
|
+
assert.equal(columnWritable(starredColumn), true);
|
|
595
|
+
assert.equal(columnWritable(companyColumn), false); // its binding has no write
|
|
596
|
+
|
|
597
|
+
// The write gate: a value is coerced by the column's type, then accepted by its field.
|
|
598
|
+
assert.deepEqual(gridNormalizeWrite(titleColumn, " Acme renewal ", conventions), { ok: true, value: "Acme renewal" });
|
|
599
|
+
assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
**One of a set.** A `select` or a `status` opens the select editor: its options, the cell's value checked, and a pick saves. A column that may be emptied (`clearable`) opens with None first; a required status shows none. Delete still clears a column that may be emptied. A closed list offers its options, and the cell's own value when no option names it, so a stray value shows on the row that holds it and on no other; an open select offers the values its records hold and a row that uses the typed text. A list of more than 8 options opens with a search on top, and a letter typed on the cell opens it already filtered by that letter; a shorter list opens as it is.
|
|
603
|
+
|
|
604
|
+
**A set of values.** A `multiselect` opens the chips editor: the chosen values as the cell's own badges with the input among them, the candidates below. It is a draft: adds and removes commit as one write when the panel closes or Tab moves on (Shift-Tab to the cell before), closing it unchanged writes nothing, and Escape discards it. Enter adds the highlighted value and keeps the panel open. A closed multiselect offers its options alone and filters them as you type, with no row to add what was typed; a value the cell already holds that no option names stays as a chip and is saved as it is. An open one offers the values on screen and adds what is typed. A vocabulary that is not free-form declares `chips: { normalize }` on its column, the rule that turns what somebody typed into what the field stores.
|
|
605
|
+
|
|
606
|
+
**A day or a moment.** A `date` opens the date editor with its date box and the calendar, no time: a click on a day saves it. A `datetime` keeps its time box (an empty time starts at 00:00) and stays open after a day click, so the time can be set; a click away or Enter saves both. Today, Tomorrow and Next Monday sit above the calendar, each setting its day as a click on the calendar does, a datetime's time kept. A column that may be emptied (`clearable`) ends the editor with a Clear row that empties the date; a required date shows none, and Delete still clears. A character typed on the cell opens the editor with it in the date box, and Enter saves the date it reads. On a phone the day and the time are in one sheet, and ✓ saves both.
|
|
607
|
+
|
|
608
|
+
**A text cell** (text, a link, an email, a phone, a domain) types in the cell through the text editor (`@viewkitjs/views/editors/text`): what was typed is trimmed, an unchanged value writes nothing, and each type brings its own phone keyboard. Enter writes and moves down, Tab writes and moves on, Escape cancels.
|
|
609
|
+
|
|
610
|
+
**A long text** (a `text` field with `format: { long: true }`, or rich text) opens a panel on the cell: Enter is a newline, ⌘ or Ctrl Enter commits and moves down, Tab commits and moves on, Escape cancels, and a click away commits. Where it cannot be written, the same panel opens read-only (`gridColumnInspectable`).
|
|
611
|
+
|
|
612
|
+
**A cut-off text** (a plain text, or a title that is text) opens whole in that panel when its cell cuts it off: a second click, a double-click or Enter shows all of it over the cell, editable where the cell can be written and read-only where it can't. It stays a line: the box wraps, Enter writes and moves down, and a newline is written as a space. Typing a character still replaces the value in the cell, and a text that fits opens in the cell as above. Links, emails, phones and domains keep their one-line box.
|
|
613
|
+
|
|
614
|
+
**On a phone** (narrower than the provider's `desktopQuery`, `(min-width: 1024px)` unless you hand in your own), a text cell and a long text open in a sheet titled with the column's header instead: ✕ and a swipe change nothing, ✓ saves and closes without moving the selection, and the save lands once the sheet has slid away.
|
|
615
|
+
|
|
616
|
+
**The write gate** is `gridNormalizeWrite`, which every write the grid starts passes once: a key, the row's menu, a fill, a paste, a boolean's button. It coerces the value by the column's type, then has the column's field accept it, so a type's write rules are stated once: a marker boolean refuses any write but clear, an email or a url must look like one, a multiselect commits its whole set, trimmed and without duplicates. An emptied value passes unchecked, since `clearable` decides whether a clear may run; a clear reaches you as `""`, except a relation's `null`, a multiselect's `[]` and a boolean's `false` (Writes, above). A refusal is said in a toast and nothing is sent. Undo and redo do not pass the gate: they put a recorded value back as it was.
|
|
617
|
+
|
|
618
|
+
**A select, status, date, tags, relation, number, range, place or list-of-values editor** opens through the same panel: your `Popover` on a desktop and your `Sheet` below your `desktopQuery`. Each asks the same gate before it closes, and the list's settings too, so a column locked while its editor is open says the lock in the editor. A value the gate refuses keeps the editor open with its reason, and nothing is sent until the value changes or Escape throws the edit away. Leaving the cell while the reason stands writes nothing, and says the reason in a toast. These editors share the edit session's rules: Escape always discards, and a refused value stays open with its reason. In the place editor's country or region list, Escape first closes the list, back to its boxes. On a desktop a picker opens your `Popover` under its cell, and a number or a range is typed in the cell. Below your provider's `desktopQuery`, each opens in your `Sheet`, a number or a range included, titled with the column's header, with ✕ and ✓, while the cell behind it keeps showing its value. ✕, a swipe and Escape change nothing. ✓ saves, and so does a pick. A value is sent once its popover or sheet has played out; a number or a range typed in the cell is sent at once. A list of values whose every value was removed, or a place whose every part was emptied, on a column that isn't `clearable`, stays open saying the field can't be emptied (the column's `reasons.clearable` when it declares one); Escape still throws the edit away. The name editor still closes and says a refusal in a toast.
|
|
619
|
+
|
|
620
|
+
**The row's country.** A column's `region` (a binding's, carried by `columnFrom`) reads the record's country off the row, and a phone typed, pasted or filled without its country code is read in it, at the gate and in the editors' own check. Absent, the conventions' region reads it.
|
|
621
|
+
|
|
622
|
+
**A relation** commits what its row stores, not the `{ id, label }` its cell draws: the id of the record picked, a ref `{ kind, id }` on a field that names its kinds, or, on a relation holding several records, the whole set (ids, or links with their kind, stored role and one lead where the field leads by a flag), edited in `RelationSetEditor` with the list open and saved as one change on a click outside, Tab or the sheet's ✓. A letter typed on a relation or member cell opens its picker searching for it; on a phone the picker's sheet opens on the list with the keyboard down. A relation whose binding carries `create` offers that row under its candidates, and links what the app's form saves as a change of its own. The grid shows no value of its own while the write runs: the cell repaints when your rows come back. A date, a range, a name, a place and a list of values show no value of their own while the write runs either. A place takes no paste: a text names none of its parts.
|
|
623
|
+
|
|
624
|
+
**A multi-value cell is written whole.** Your `onCellCommit` receives the whole list, never one item added or removed.
|
|
625
|
+
|
|
626
|
+
## The keyboard and the pointer
|
|
627
|
+
|
|
628
|
+
Tab enters the grid at its focused cell, or at the first cell on screen, and the keyboard is a spreadsheet's: the arrows and ⇧-arrows, ⌘A, Home and End, ⌘Home and ⌘End, Tab with the row wrapping, typing to replace (on a select or a status, typing starts its search), Enter to edit (or to flip a boolean), ⌘C, ⌘X and Delete over a range, ⌘Z and ⇧⌘Z, and pasted tab-separated text. On a desktop, a click selects a cell; a second click on it, a double-click or Enter opens its editor, or the panel of a long text or a cut-off text. An email, a phone, a url or a domain is part of its cell: a click on it selects the cell like any other, and a ⌘-click (Ctrl-click on Windows) follows the link. ⌘X and Delete over a range empty what may be emptied, then say in one toast which fields they left because those can't be empty (`views.grid.clear-required`). A drag selects a range, and the dot at its corner fills it. Below your provider's `desktopQuery`, one tap on a cell opens its editor in your `Sheet`, and a cell that opens nothing is selected and says why. The answer is read at the tap, so a test that clicks the grid answers your desktop query in its `matchMedia` stub to keep a desktop's clicks.
|
|
629
|
+
|
|
630
|
+
Every cell takes the browser's own focus, and the grid's keys listen on the grid itself; only ⌘Z listens on the window, so an undo works wherever focus is, and lands on the cell it changed: selected, and holding the focus unless something outside the grid has it, so the next key moves from there. Tab past the grid's last cell (Shift+Tab before its first) leaves it, and Escape with nothing open clears the cell and lets go of the grid: the next Tab or Shift+Tab leaves. The arrows also reach what surrounds the cells: ↑ from a group's first row lands on its column names, where Enter or Space opens a column's menu with focus on its first row; ↓ from its last row lands on its footer, where Enter or Space opens the figure picker; above the column names is the group's bar, where Enter, Space or ← collapse it and Enter, Space or → open it again, and → on an open bar reaches its ⋯ menu; ← from a row's first column reaches its checkbox, and Space ticks it (the select-all and a group's box the same way from the column names). On a cell, Shift+F10, the menu key, or ⌘⇧\ (Ctrl+Shift+\ off a Mac, as in Google Sheets) opens the row's menu, the one a right-click on that cell opens, under the cell; the grid sends that right-click to your `RowMenu`, and your `Menu` puts focus on its first row. Safari may keep ⌘⇧\ for its own tab overview: there, fn+Shift+F10 opens it. In a column's menu, the figure picker and a group's ⋯ menu, ↓ and ↑ move between the rows, round at either end, and Enter picks the focused one. Past eight sort choices a group's menu lists them under a search, whose own arrows walk its matches: ↓ past the last match goes on to the rows below it, and ↑ from the first of those comes back. That reads the match your `Command` has highlighted from its field's `aria-activedescendant`, as cmdk names it; a list that names none keeps its own arrows, and Tab leaves it. Escape, or a pick, closes a menu and puts focus back on its cell, after your `Popover` or `Menu` has played its exit and left the page. The keyboard, a range, a copy, a clear, a paste and a fill skip a collapsed group's rows, and collapsing a group keeps an edit open in it.
|
|
631
|
+
|
|
632
|
+
A screen reader reads the grid as a grid, or as a tree grid when it is grouped: every row is numbered among all of them (a group's bar, its column names and its footer are rows too, so the total runs a little above the record count), a cell is read with its column's name, a group's bar with its name, its count and whether it is open, and a grouped record with its place in its group. While more rows remain to load, a row reads its number with no total.
|
|
633
|
+
|
|
634
|
+
## Known gaps
|
|
635
|
+
|
|
636
|
+
- A row's ⋯ opens by pointer, and its menu (the name's actions among its rows) by a key on a cell (The keyboard and the pointer); a screen reader reaches the ⋯ as the row's last cell.
|
|
637
|
+
- Only the rows on screen are drawn, with ten more each side, so the browser's own find (⌘F) finds only those: your list's own search finds the rest. The focused row, the row being edited and a row whose checkbox holds the focus stay drawn when they scroll away.
|
|
638
|
+
- On touch, a range drag and fill need a fine pointer: the fill dot is drawn only under `(hover: hover) and (pointer: fine)`.
|
|
639
|
+
- A cell holding several values is written as a whole set.
|
|
640
|
+
- Writes carry no version: when two people edit one row the last write wins, and the grid warns only when a third party's value replaced yours. A difference of format is not one: `null`, `""` and `[]` are all nothing, so a cell emptied to `""` that your rows read back as `null` clears without a word.
|
|
641
|
+
|
|
642
|
+
## Styling
|
|
643
|
+
|
|
644
|
+
The grid styles through attributes, never class names: each part carries a `data-slot` (`data-slot="vk-grid"` on the frame, `vk-grid-row`, `vk-grid-cell`, `vk-grid-group-header` and the rest), and its states are bare `data-*` flags beside it (`data-focused`, `data-selected`, `data-editing`, `data-pending`, `data-invalid` …). The grid sets its geometry and density as `--vk-*` variables on its frame (`--vk-row-h`, `--vk-px`, `--vk-scale` …), which a skin reads and your app may override there. `--vk-gutter`, the side padding your page gives its content, lines the rows' content up with your page when you declare it. [The contract](../contract.md) lists every slot, state and token; [Install](../install.md) maps the colours onto your theme.
|
|
645
|
+
|
|
646
|
+
## Helpers a host shares with the grid
|
|
647
|
+
|
|
648
|
+
A surface of your own beside the grid reads values the way the grid does with these.
|
|
649
|
+
|
|
650
|
+
- `cellEditBaseline(column, row)` is a cell's value as an editor and a copy see it: the column's raw edit value where it declares one, else what it draws.
|
|
651
|
+
- `cellCopyText(column, value)` is that value as the clipboard writes it: a relation by its label, an option by its label, several values joined with commas, a name or a place as its cell writes it, a range as "11–50". A CSV export reuses the two, so its cells read as a copy from the grid does.
|
|
652
|
+
- `deriveGridSelectValues(columns, rows)` is the values each option column offers, by column id: its active options in declared order, then any other value its rows hold. `{ includeArchived: true }` keeps archived options, for a filter that must still find a row holding one.
|
|
653
|
+
- `deriveGridRelationValues(columns, rows)` is the records each relation column's rows point at, by column id, as `{ id, label }` in alphabetical order: what a filter offers is what the list holds, never every record that could be linked.
|
|
654
|
+
- `GRID_TITLE_LINK_CLASS` is the class a title cell wears: the element marked `data-cell-open` inside it, the text that opens the row, takes the brand colour and an underline on its own hover. A title you draw beside the grid wears it to read the same.
|
|
655
|
+
|
|
656
|
+
```ts
|
|
657
|
+
import {
|
|
658
|
+
cellCopyText,
|
|
659
|
+
cellEditBaseline,
|
|
660
|
+
deriveGridRelationValues,
|
|
661
|
+
deriveGridSelectValues,
|
|
662
|
+
GRID_TITLE_LINK_CLASS,
|
|
663
|
+
} from "@viewkitjs/views/grid";
|
|
664
|
+
|
|
665
|
+
/** The rows as CSV, each cell as the grid would copy it. */
|
|
666
|
+
function dealsCsv(rows: readonly Deal[]): string {
|
|
667
|
+
const quote = (text: string) => (/[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text);
|
|
668
|
+
const header = columns.map((column) => quote(columnLabel(column))).join(",");
|
|
669
|
+
const lines = rows.map((row) =>
|
|
670
|
+
columns.map((column) => quote(cellCopyText(column, cellEditBaseline(column, row)))).join(",")
|
|
671
|
+
);
|
|
672
|
+
return [header, ...lines].join("\n");
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
assert.equal(cellCopyText(companyColumn, cellEditBaseline(companyColumn, DEALS[0])), "Acme");
|
|
676
|
+
assert.equal(
|
|
677
|
+
dealsCsv(DEALS.slice(0, 2)),
|
|
678
|
+
[
|
|
679
|
+
"Title,Value,Stage,Starred,Close on,Company",
|
|
680
|
+
"Acme renewal,1200,Won,true,2026-03-06,Acme",
|
|
681
|
+
"Globex pilot,5400,Open,false,,Globex",
|
|
682
|
+
].join("\n")
|
|
683
|
+
);
|
|
684
|
+
|
|
685
|
+
assert.deepEqual(deriveGridSelectValues(columns, DEALS), { stage: ["open", "won", "lost"] });
|
|
686
|
+
assert.deepEqual(deriveGridRelationValues(columns, DEALS), { company: [ACME, GLOBEX, LUMEN] });
|
|
687
|
+
assert.ok(GRID_TITLE_LINK_CLASS.includes("data-cell-open"));
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
## Next
|
|
691
|
+
|
|
692
|
+
- [The grid door](../reference/grid.md): every name `@viewkitjs/views/grid` exports
|
|
693
|
+
- [Columns](columns.md): bindings, columns and what may be done to them
|
|
694
|
+
- [Ports](ports.md): the toast, the clipboard and the confirm the grid speaks through
|
|
695
|
+
- [The root door](../reference/views.md): preferences, locks, figures, sorting and grouping in full
|
|
696
|
+
- [The contract](../contract.md): slots, states, tokens and message keys
|