@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,462 @@
|
|
|
1
|
+
# Editors and the edit session
|
|
2
|
+
|
|
3
|
+
An editor is the panel a person changes a value in: the option list of a status, the calendar of a date, the three boxes of a name. The grid mounts them for you; this page is for when you mount one yourself, in a form field, a drawer row or a card. It covers the table that picks an editor for a type, what each editor commits, what an editor owns against what you own, the session that turns a close into one answer, an open field's values, and where a relation's candidates come from. A record's whole field row, its hosts and its write path included, is ready-made behind `@viewkitjs/views/field-row`.
|
|
4
|
+
|
|
5
|
+
Every block on this page continues the one before, and the whole page runs as written.
|
|
6
|
+
|
|
7
|
+
## One editor per storage type
|
|
8
|
+
|
|
9
|
+
`EDIT_CORES`, from `@viewkitjs/views/editors`, holds the editor for every storage type fields declares. It has a member for each type, so a type fields adds that nothing here answers fails to compile. Several types share one editor: `date` and `datetime` share the date editor, `select` and `status` the select editor, `relation` and `user` the relation editor, and `number`, `percent` and `currency` the number editor; `text`, `url`, `domain`, `email`, `phone` and `rich_text` share the text editor.
|
|
10
|
+
|
|
11
|
+
A member that is `null` is a decision: the type has no editor of its own. A `boolean` is edited by its checkbox; an `actor` is set by the system; `lookup`, `rollup` and `formula` are read-only or derived. `hasEditCore(type)` answers the same question; imported from the root door, `@viewkitjs/views`, it loads no editor, for a host deciding whether to wire one at all.
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
import assert from "node:assert/strict";
|
|
15
|
+
import { EDIT_CORES, hasEditCore } from "@viewkitjs/views/editors";
|
|
16
|
+
import { SelectEditor } from "@viewkitjs/views/editors/select";
|
|
17
|
+
import { TextEditor } from "@viewkitjs/views/editors/text";
|
|
18
|
+
|
|
19
|
+
assert.equal(EDIT_CORES.status, EDIT_CORES.select);
|
|
20
|
+
assert.equal(EDIT_CORES.select, SelectEditor);
|
|
21
|
+
assert.equal(EDIT_CORES.percent, EDIT_CORES.number);
|
|
22
|
+
assert.equal(EDIT_CORES.text, TextEditor);
|
|
23
|
+
assert.equal(EDIT_CORES.phone, TextEditor);
|
|
24
|
+
assert.equal(EDIT_CORES.boolean, null);
|
|
25
|
+
|
|
26
|
+
assert.equal(hasEditCore("currency"), true);
|
|
27
|
+
assert.equal(hasEditCore("boolean"), false);
|
|
28
|
+
assert.equal(hasEditCore("formula"), false);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Each editor also has a door of its own. Import from the editor's door when you need one editor, and from `@viewkitjs/views/editors` only when you need the table.
|
|
32
|
+
|
|
33
|
+
## What each editor commits
|
|
34
|
+
|
|
35
|
+
What an editor hands back is a commit, which is not always the shape your row stores: a select commits `""` for None, a number commits the figure with its unit. [Four shapes of a value](../contract.md#four-shapes-of-a-value) in the contract names the stored, draft, commit and display shapes, and your binding's `write` is where a commit becomes your request's body.
|
|
36
|
+
|
|
37
|
+
| Door | Edits | Commits |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `@viewkitjs/views/editors/select` | `select`, `status` | the picked option's `value`, `""` for None |
|
|
40
|
+
| `@viewkitjs/views/editors/text` | `text`, `url`, `domain`, `email`, `phone`, `rich_text` | the tidied text: trimmed, rich text only at its edges |
|
|
41
|
+
| `@viewkitjs/views/editors/relation` | `relation`, `user` | the picked candidate's `id`, `null` for None; `RelationSetEditor`, a relation holding several records: the whole set as `RelationDraftLink[]` |
|
|
42
|
+
| `@viewkitjs/views/editors/number` | `number`, `percent`, `currency` | `{ value, unit }`, the value a number or `null` |
|
|
43
|
+
| `@viewkitjs/views/editors/range` | `range` | `{ low, high }`, each a number or `null` |
|
|
44
|
+
| `@viewkitjs/views/editors/name` | `name` | `{ full, given, family }`, or `null` |
|
|
45
|
+
| `@viewkitjs/views/editors/location` | `location` | the place's parts, or `null` |
|
|
46
|
+
| `@viewkitjs/views/editors/value-list` | a `multiple` email, phone, url or domain | a list of `{ value, label, main }`, the main one first, or `null` |
|
|
47
|
+
| `@viewkitjs/views/editors/date` | `date`, `datetime` | `YYYY-MM-DD`, or `YYYY-MM-DDTHH:MM` with a time; `""` from its Clear row |
|
|
48
|
+
| `@viewkitjs/views/editors/chips` | `multiselect` | the list of values, a `string[]` |
|
|
49
|
+
|
|
50
|
+
The value-list editor has no member in `EDIT_CORES`: a list of emails is still an `email` field, whose single value is a plain input. Each editor's reference page has its props and its close rule in full: [select](../reference/editors-select.md), [text](../reference/editors-text.md), [relation](../reference/editors-relation.md), [number](../reference/editors-number.md), [range](../reference/editors-range.md), [name](../reference/editors-name.md), [location](../reference/editors-location.md), [value list](../reference/editors-value-list.md), [date](../reference/editors-date.md) and [chips](../reference/editors-chips.md).
|
|
51
|
+
|
|
52
|
+
## A text box
|
|
53
|
+
|
|
54
|
+
`TextEditor`, from `@viewkitjs/views/editors/text`, is the one box for every text-like value: text, a link, an email, a phone, a domain, long text and rich text. It tidies what was typed (trimmed; rich text tidied only at its edges, so its first line keeps its indent), answers `noop` when the tidied text equals the tidied stored value, and brings each type's own phone keyboard (`TEXT_INPUT_TYPE`: a phone `tel`, an email `email`, a link or a domain `url`). A line closes on Enter; a paragraph (`multiline`, the default for rich text) takes Enter as a newline and closes on ⌘ or Ctrl Enter. Escape discards, Tab and Shift-Tab close with their reason, and leaving the box closes it unless you pass `closeOnBlur={false}`, which a host inside a popover or a sheet does, so a tap on ✕ or ✓ is not a close. A line draws through your `Input`; a paragraph is the package's own textarea.
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
import { TEXT_INPUT_TYPE } from "@viewkitjs/views/editors/text";
|
|
58
|
+
|
|
59
|
+
assert.equal(TEXT_INPUT_TYPE.phone, "tel");
|
|
60
|
+
assert.equal(TEXT_INPUT_TYPE.domain, "url");
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## What an editor owns, and what you own
|
|
64
|
+
|
|
65
|
+
An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
|
|
66
|
+
|
|
67
|
+
The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
|
|
68
|
+
|
|
69
|
+
1. When the editor sees a key or a pick that means done, it calls your `onRequestClose(reason)`. Your popover's own closes (an outside press, Escape) reach the same place with their own reasons.
|
|
70
|
+
2. You close, and ask the editor's handle `resolveClose(reason)`.
|
|
71
|
+
3. It answers `commit` with the value, `cancel`, or `noop` when nothing changed. Asking twice gives the same answer, and it starts no timer.
|
|
72
|
+
|
|
73
|
+
What an editor never does on its own (write, fetch, toast, decide the popover) is listed in [What an edit core never does](../contract.md#what-an-edit-core-never-does). A field whose changes go through the record's own verbs has no editor at all; [A command field](../contract.md#a-command-field) covers what its cell offers instead.
|
|
74
|
+
|
|
75
|
+
## The anchored edit session
|
|
76
|
+
|
|
77
|
+
Every host that opens a panel over a value repeats two things, and both are easy to get wrong without seeing it. A close can arrive more than once (your popover reports an Escape, then the closed state it caused), and a session that answers twice writes twice. And the popover has an exit animation: answering at once re-renders the value behind it and unmounts the panel mid-animation.
|
|
78
|
+
|
|
79
|
+
`useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape always throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. It gives you two ways to hear the answer:
|
|
80
|
+
|
|
81
|
+
- `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false, reason }` to refuse it: the panel stays open, the session hands the reason back as `refusal` until the next attempt, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
|
|
82
|
+
- `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
|
|
83
|
+
|
|
84
|
+
The gap is `EDITOR_EXIT_MS` unless you pass `exitMs`. `mapPayload` reshapes a commit before it reaches you, and only a commit: a host that offers None maps the select's `""` to `null` with `mapPayload: (value) => (value === "" ? null : value)`.
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
import { EDITOR_EXIT_MS } from "@viewkitjs/views/editors/session";
|
|
88
|
+
|
|
89
|
+
assert.equal(EDITOR_EXIT_MS, 160);
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Here is a host: a deal's stage picked in a popover your components map draws, its commit sent through your own save. First the fields and the provider, as in getting started; the components map is plain elements, so the page runs anywhere.
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
import { defineConventions, defineFields, type CloseReason } from "@viewkitjs/fields";
|
|
96
|
+
import { ICON_NAMES } from "@viewkitjs/views";
|
|
97
|
+
import type { ViewsComponents, ViewsIcons } from "@viewkitjs/views/react";
|
|
98
|
+
|
|
99
|
+
const DEAL_FIELDS = defineFields({
|
|
100
|
+
entity: "deal",
|
|
101
|
+
identity: "title",
|
|
102
|
+
fields: {
|
|
103
|
+
title: { type: "text", label: "Title", required: true },
|
|
104
|
+
stage: {
|
|
105
|
+
type: "status",
|
|
106
|
+
label: "Stage",
|
|
107
|
+
options: [
|
|
108
|
+
{ value: "new", label: "New", slot: "pending" },
|
|
109
|
+
{ value: "won", label: "Won", slot: "success" },
|
|
110
|
+
{ value: "lost", label: "Lost", slot: "error" },
|
|
111
|
+
],
|
|
112
|
+
},
|
|
113
|
+
industry: {
|
|
114
|
+
type: "select",
|
|
115
|
+
label: "Industry",
|
|
116
|
+
vocabulary: "custom-values",
|
|
117
|
+
options: [{ value: "Software", label: "Software", color: "purple" }],
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
type Deal = { id: string; title: string; stage: string; industry: string | null; companyId: string | null };
|
|
123
|
+
|
|
124
|
+
const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
|
|
125
|
+
|
|
126
|
+
const components: ViewsComponents = {
|
|
127
|
+
Button: ({ children, onClick, disabled, type = "button", className, title }) => (
|
|
128
|
+
<button type={type} onClick={onClick} disabled={disabled} className={className} title={title}>
|
|
129
|
+
{children}
|
|
130
|
+
</button>
|
|
131
|
+
),
|
|
132
|
+
Popover: ({ open, children, className }) => (open ? <div className={className}>{children}</div> : null),
|
|
133
|
+
Tooltip: ({ children }) => children,
|
|
134
|
+
Checkbox: ({ checked, onCheckedChange, disabled }) => (
|
|
135
|
+
<input
|
|
136
|
+
type="checkbox"
|
|
137
|
+
checked={checked}
|
|
138
|
+
disabled={disabled}
|
|
139
|
+
onChange={(event) => onCheckedChange(event.target.checked, { event: event.nativeEvent })}
|
|
140
|
+
/>
|
|
141
|
+
),
|
|
142
|
+
Menu: ({ open, items }) =>
|
|
143
|
+
open ? (
|
|
144
|
+
<div role="menu">
|
|
145
|
+
{items.map((item) => (
|
|
146
|
+
<button key={item.key} type="button" role="menuitem" onClick={item.onSelect}>
|
|
147
|
+
{item.label}
|
|
148
|
+
</button>
|
|
149
|
+
))}
|
|
150
|
+
</div>
|
|
151
|
+
) : null,
|
|
152
|
+
Command: {
|
|
153
|
+
Root: ({ children, className }) => <div className={className}>{children}</div>,
|
|
154
|
+
Input: ({ value, onValueChange, placeholder, ref, onKeyDown }) => (
|
|
155
|
+
<input
|
|
156
|
+
ref={ref}
|
|
157
|
+
value={value}
|
|
158
|
+
placeholder={placeholder}
|
|
159
|
+
onChange={(event) => onValueChange(event.target.value)}
|
|
160
|
+
onKeyDown={onKeyDown}
|
|
161
|
+
/>
|
|
162
|
+
),
|
|
163
|
+
List: ({ children }) => <div role="listbox">{children}</div>,
|
|
164
|
+
Empty: ({ children }) => <div>{children}</div>,
|
|
165
|
+
Group: ({ children }) => <div>{children}</div>,
|
|
166
|
+
Item: ({ value, onSelect, chosen, children }) => (
|
|
167
|
+
<div role="option" aria-selected={chosen === true} onClick={() => onSelect(value)}>
|
|
168
|
+
{children}
|
|
169
|
+
</div>
|
|
170
|
+
),
|
|
171
|
+
},
|
|
172
|
+
Calendar: ({ value, onChange }) => (
|
|
173
|
+
<input type="date" value={value ?? ""} onChange={(event) => onChange(event.target.value)} />
|
|
174
|
+
),
|
|
175
|
+
Collapse: ({ open, children }) => (open ? <>{children}</> : null),
|
|
176
|
+
Sheet: ({ open, children }) => (open ? <div role="dialog">{children}</div> : null),
|
|
177
|
+
AppIcon: ({ name, className }) => <i data-icon={name} className={className} />,
|
|
178
|
+
Markdown: ({ source, className }) => <div className={className}>{source}</div>,
|
|
179
|
+
};
|
|
180
|
+
|
|
181
|
+
const icons = Object.fromEntries(
|
|
182
|
+
ICON_NAMES.map((name) => [name, ({ className }: { className?: string }) => <i data-icon={name} className={className} />])
|
|
183
|
+
) as ViewsIcons;
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`pickerOptionsFromField` dresses a select's or a status's options the way its cells draw them, so the panel looks like the grid: a status keeps each option's slot, a select takes its category colour. Archived options are left out. Pass `current`, the value your surface holds, and it is offered after the options when none of them is it, so its own list shows it checked; it is never offered to another record's list.
|
|
187
|
+
|
|
188
|
+
```tsx
|
|
189
|
+
import { pickerOptionsFromField, type SelectEditorHandle } from "@viewkitjs/views/editors/select";
|
|
190
|
+
|
|
191
|
+
const stageOptions = pickerOptionsFromField(DEAL_FIELDS.stage);
|
|
192
|
+
|
|
193
|
+
assert.deepEqual(stageOptions, [
|
|
194
|
+
{ value: "new", label: "New", slot: "pending" },
|
|
195
|
+
{ value: "won", label: "Won", slot: "success" },
|
|
196
|
+
{ value: "lost", label: "Lost", slot: "error" },
|
|
197
|
+
]);
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The host. Its popover is your components map's, read through `useViews()`; the anchor is whatever element the value sits in. Every close lands in the session's `close`: the editor's pick, your popover's Escape, and its closed state, which follows the Escape and is ignored, because the session has already answered.
|
|
201
|
+
|
|
202
|
+
```tsx
|
|
203
|
+
import { useRef, type RefObject } from "react";
|
|
204
|
+
import { useViews } from "@viewkitjs/views/react";
|
|
205
|
+
import { useAnchoredEditSession } from "@viewkitjs/views/editors/session";
|
|
206
|
+
|
|
207
|
+
declare function saveDeal(id: string, body: Record<string, unknown>): Promise<void>;
|
|
208
|
+
declare function showSaveFailed(): void;
|
|
209
|
+
|
|
210
|
+
function DealStageEditor({
|
|
211
|
+
deal,
|
|
212
|
+
anchor,
|
|
213
|
+
onClosed,
|
|
214
|
+
}: {
|
|
215
|
+
deal: Deal;
|
|
216
|
+
anchor: RefObject<HTMLElement | null>;
|
|
217
|
+
onClosed: () => void;
|
|
218
|
+
}) {
|
|
219
|
+
const { Popover } = useViews().components;
|
|
220
|
+
const editorRef = useRef<SelectEditorHandle>(null);
|
|
221
|
+
const { open, close } = useAnchoredEditSession<string>({
|
|
222
|
+
editorRef,
|
|
223
|
+
onAttempt: (resolution) => {
|
|
224
|
+
// Asked the moment the close happens: the write leaves at once, the popover closes after.
|
|
225
|
+
if (resolution.kind === "commit") {
|
|
226
|
+
saveDeal(deal.id, { stage: resolution.payload }).catch(showSaveFailed);
|
|
227
|
+
}
|
|
228
|
+
return { accepted: true };
|
|
229
|
+
},
|
|
230
|
+
// After the exit gap: unmount the editor and draw the value again.
|
|
231
|
+
onClose: onClosed,
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
return (
|
|
235
|
+
<Popover
|
|
236
|
+
open={open}
|
|
237
|
+
onOpenChange={(next) => {
|
|
238
|
+
if (!next) close("outside");
|
|
239
|
+
}}
|
|
240
|
+
onEscape={() => close("escape")}
|
|
241
|
+
anchor={anchor}
|
|
242
|
+
align="start"
|
|
243
|
+
// The editor focuses its own input, without scrolling the page.
|
|
244
|
+
initialFocus={false}
|
|
245
|
+
chrome="menu"
|
|
246
|
+
>
|
|
247
|
+
<SelectEditor ref={editorRef} options={stageOptions} initial={deal.stage} onRequestClose={close} />
|
|
248
|
+
</Popover>
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Rendered inside the provider, the panel draws each option as your status badge and marks the stage the deal holds.
|
|
254
|
+
|
|
255
|
+
```tsx
|
|
256
|
+
import { renderToStaticMarkup } from "react-dom/server";
|
|
257
|
+
import { NOOP_PORTS, ViewsProvider } from "@viewkitjs/views/react";
|
|
258
|
+
|
|
259
|
+
const acme: Deal = { id: "d1", title: "Acme renewal", stage: "new", industry: null, companyId: null };
|
|
260
|
+
|
|
261
|
+
const stageHtml = renderToStaticMarkup(
|
|
262
|
+
<ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
|
|
263
|
+
<DealStageEditor deal={acme} anchor={{ current: null }} onClosed={() => {}} />
|
|
264
|
+
</ViewsProvider>
|
|
265
|
+
);
|
|
266
|
+
|
|
267
|
+
assert.ok(stageHtml.includes("Won") && stageHtml.includes("Lost"));
|
|
268
|
+
assert.ok(stageHtml.includes('data-status="success"')); // each option wears its slot
|
|
269
|
+
assert.ok(stageHtml.includes("data-chosen")); // the stage the deal holds is checked
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
A pick of Won calls `close("pick")`; the editor answers `{ kind: "commit", payload: "won" }`, `saveDeal` sends `{ stage: "won" }`, and 160 milliseconds later `onClosed` runs. A pick of New, which the deal already holds, answers `noop`, and an outside press or Escape answers `cancel`: nothing is sent either way, and the popover still closes.
|
|
273
|
+
|
|
274
|
+
## The panel: a popover on the desktop, a sheet on the phone
|
|
275
|
+
|
|
276
|
+
The host above draws its own popover, so on a phone it still opens a popover. `EditorPanel`, from `@viewkitjs/views/editors/panel`, opens the same editor in your `Popover` on a desktop and your `Sheet` on a phone, by the provider's `desktopQuery` (`(min-width: 1024px)` unless you hand in your own), chosen once when the session opens. It routes every dismissal to the session, so each means the same on every surface:
|
|
277
|
+
|
|
278
|
+
- **Desktop:** the popover's Escape discards. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
|
|
279
|
+
- **Phone:** the sheet carries the field's name as its title, and a bar with ✕ and ✓. ✕, a swipe and the backdrop change nothing. ✓ closes as done, and a pick in a select saves on its own.
|
|
280
|
+
- **Refusals:** a value your `onAttempt` refuses with a `reason` stays open, and the reason is drawn under the editor.
|
|
281
|
+
|
|
282
|
+
A type-in editor passes `inPlace`: it stays where the value stands, and goes into the sheet on a phone only when its host passes `sheetOnPhone`. The same stage, refusing Lost until the deal has a reason:
|
|
283
|
+
|
|
284
|
+
```tsx
|
|
285
|
+
import { EditorPanel } from "@viewkitjs/views/editors/panel";
|
|
286
|
+
|
|
287
|
+
function DealStagePanel({ deal, anchor, onClosed }: { deal: Deal; anchor: RefObject<HTMLElement | null>; onClosed: () => void }) {
|
|
288
|
+
const editorRef = useRef<SelectEditorHandle>(null);
|
|
289
|
+
const session = useAnchoredEditSession<string>({
|
|
290
|
+
editorRef,
|
|
291
|
+
onAttempt: (resolution) => {
|
|
292
|
+
if (resolution.kind !== "commit") return { accepted: true };
|
|
293
|
+
if (resolution.payload === "lost") return { accepted: false, reason: "A lost deal needs a reason first" };
|
|
294
|
+
saveDeal(deal.id, { stage: resolution.payload }).catch(showSaveFailed);
|
|
295
|
+
return { accepted: true };
|
|
296
|
+
},
|
|
297
|
+
onClose: onClosed,
|
|
298
|
+
});
|
|
299
|
+
|
|
300
|
+
return (
|
|
301
|
+
<EditorPanel session={session} title="Stage" anchor={anchor} align="start" initialFocus={false} chrome="menu">
|
|
302
|
+
<SelectEditor ref={editorRef} options={stageOptions} initial={deal.stage} onRequestClose={session.close} />
|
|
303
|
+
</EditorPanel>
|
|
304
|
+
);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// A server render can't ask the screen, so it draws the desktop's popover.
|
|
308
|
+
const panelHtml = renderToStaticMarkup(
|
|
309
|
+
<ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
|
|
310
|
+
<DealStagePanel deal={acme} anchor={{ current: null }} onClosed={() => {}} />
|
|
311
|
+
</ViewsProvider>
|
|
312
|
+
);
|
|
313
|
+
|
|
314
|
+
assert.ok(panelHtml.includes("Won") && panelHtml.includes("Lost"));
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
## An open field's values
|
|
318
|
+
|
|
319
|
+
An open select or multiselect (`vocabulary: "custom-values"`) has no closed list of options: its values are whatever its records hold, which only your app's data can answer. `OpenValuesProvider`, from `@viewkitjs/views/editors/open-values`, carries them to every editor of the field below it, so a field offers the same values in the grid, a form and a card.
|
|
320
|
+
|
|
321
|
+
You provide the values above a surface: `values`, each field's values by its key, most used first, and `onWanted(fieldKey)`, so you can ask for a field's values when they are first needed. `useOpenValues(field)` is how a host reads them, and it calls `onWanted` once when the host of an open field mounts. Keep `onWanted` stable: a new function each render asks again each render.
|
|
322
|
+
|
|
323
|
+
```tsx
|
|
324
|
+
import { useCallback, useMemo, useState, type ReactNode } from "react";
|
|
325
|
+
import { OpenValuesProvider, offeredValues, useOpenValues, type OpenValues } from "@viewkitjs/views/editors/open-values";
|
|
326
|
+
|
|
327
|
+
declare function fetchFieldValues(entity: string, fieldKey: string): Promise<string[]>;
|
|
328
|
+
|
|
329
|
+
function DealOpenValues({ children }: { children: ReactNode }) {
|
|
330
|
+
const [values, setValues] = useState<Record<string, string[]>>({});
|
|
331
|
+
const onWanted = useCallback((fieldKey: string) => {
|
|
332
|
+
void fetchFieldValues("deal", fieldKey).then((list) =>
|
|
333
|
+
setValues((current) => ({ ...current, [fieldKey]: list }))
|
|
334
|
+
);
|
|
335
|
+
}, []);
|
|
336
|
+
const openValues = useMemo<OpenValues>(() => ({ values, onWanted }), [values, onWanted]);
|
|
337
|
+
return <OpenValuesProvider value={openValues}>{children}</OpenValuesProvider>;
|
|
338
|
+
}
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
A closed field, or a host with no provider above it, reads no values and asks for none: its editor offers its declared options.
|
|
342
|
+
|
|
343
|
+
`offeredValues(field, known, seen)` is what a host offers: the field's declared options, then the values the provider knows, then any seen on screen, each once. It is a plain function. `pickerOptionsFromField`'s `extraValues` turns the values no option names into rows labelled with the raw value, coloured by the same rule the cells use.
|
|
344
|
+
|
|
345
|
+
```tsx
|
|
346
|
+
const offered = offeredValues(DEAL_FIELDS.industry, ["Retail", "Software"], ["Health"]);
|
|
347
|
+
assert.deepEqual(offered, ["Software", "Retail", "Health"]);
|
|
348
|
+
|
|
349
|
+
const industryOptions = pickerOptionsFromField(DEAL_FIELDS.industry, { extraValues: offered });
|
|
350
|
+
assert.deepEqual(
|
|
351
|
+
industryOptions.map((option) => option.label),
|
|
352
|
+
["Software", "Retail", "Health"]
|
|
353
|
+
);
|
|
354
|
+
assert.equal(industryOptions[0].color, "purple"); // the option's own colour
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
A host of an open select hands those rows to the select editor with `creatable`, which adds a search over the labels and a row that uses the typed text when no option's value is it:
|
|
358
|
+
|
|
359
|
+
```tsx
|
|
360
|
+
function IndustryPanel({
|
|
361
|
+
deal,
|
|
362
|
+
seen,
|
|
363
|
+
editorRef,
|
|
364
|
+
onRequestClose,
|
|
365
|
+
}: {
|
|
366
|
+
deal: Deal;
|
|
367
|
+
seen: readonly string[];
|
|
368
|
+
editorRef: RefObject<SelectEditorHandle | null>;
|
|
369
|
+
onRequestClose: (reason: CloseReason) => void;
|
|
370
|
+
}) {
|
|
371
|
+
const known = useOpenValues(DEAL_FIELDS.industry);
|
|
372
|
+
const options = pickerOptionsFromField(DEAL_FIELDS.industry, {
|
|
373
|
+
extraValues: offeredValues(DEAL_FIELDS.industry, known, seen),
|
|
374
|
+
});
|
|
375
|
+
return (
|
|
376
|
+
<SelectEditor ref={editorRef} options={options} initial={deal.industry} creatable onRequestClose={onRequestClose} />
|
|
377
|
+
);
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
## A relation's candidates
|
|
382
|
+
|
|
383
|
+
The relation editor never asks for its candidates itself: you hand them in as a `RelationSource`, so who may see what stays in your own function. A source is one of two kinds:
|
|
384
|
+
|
|
385
|
+
- `static`: a list you already hold, whole. The panel filters it on the labels as a person types.
|
|
386
|
+
- `remote`: a search you run. The panel calls it with the empty query the moment it opens, then with each typed query after a pause, then for the next page as the list scrolls to its end, with `offset` the number of rows it already holds. The `AbortSignal` aborts when a newer query replaces it, and a stale answer is dropped.
|
|
387
|
+
|
|
388
|
+
A candidate is an `id` (stored and committed, never shown) and a `label`, with an optional `sublabel` (a muted second line that tells two same-named rows apart), `badge`, `icon`, `avatarUrl` and `kind`.
|
|
389
|
+
|
|
390
|
+
```tsx
|
|
391
|
+
import {
|
|
392
|
+
RELATION_PAGE_SIZE,
|
|
393
|
+
RELATION_SEARCH_DEBOUNCE_MS,
|
|
394
|
+
RelationEditor,
|
|
395
|
+
type RelationEditorHandle,
|
|
396
|
+
type RelationSource,
|
|
397
|
+
} from "@viewkitjs/views/editors/relation";
|
|
398
|
+
|
|
399
|
+
const OWNERS: RelationSource = {
|
|
400
|
+
kind: "static",
|
|
401
|
+
items: [
|
|
402
|
+
{ id: "u1", label: "Ana Pop", sublabel: "ana@example.com" },
|
|
403
|
+
{ id: "u2", label: "Ana Pop", sublabel: "ana.pop@example.com" },
|
|
404
|
+
],
|
|
405
|
+
};
|
|
406
|
+
|
|
407
|
+
declare function searchCompanies(
|
|
408
|
+
query: string,
|
|
409
|
+
offset: number,
|
|
410
|
+
limit: number,
|
|
411
|
+
signal: AbortSignal
|
|
412
|
+
): Promise<{ id: string; name: string; domain: string | null }[]>;
|
|
413
|
+
|
|
414
|
+
const COMPANIES: RelationSource = {
|
|
415
|
+
kind: "remote",
|
|
416
|
+
pageSize: 25,
|
|
417
|
+
search: async (query, signal, offset) => {
|
|
418
|
+
const rows = await searchCompanies(query, offset, 25, signal);
|
|
419
|
+
return rows.map((row) => ({ id: row.id, label: row.name, sublabel: row.domain ?? undefined }));
|
|
420
|
+
},
|
|
421
|
+
};
|
|
422
|
+
|
|
423
|
+
assert.equal(OWNERS.kind, "static");
|
|
424
|
+
assert.equal(RELATION_SEARCH_DEBOUNCE_MS, 200); // a typed query waits this long
|
|
425
|
+
assert.equal(RELATION_PAGE_SIZE, 20); // a page, when the source names no pageSize
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
A page shorter than `pageSize` is how the panel knows the list has ended, so `pageSize` must be what your search really asks its route for: a mismatch ends the list early, or asks once more for nothing.
|
|
429
|
+
|
|
430
|
+
The editor itself takes the source as `candidates`, the linked id as `initial`, and `clearable` for a None row. It commits the picked id, or `null` for None, and only on a pick; every other close discards. Its host is the stage host above with `RelationEditorHandle` in place of `SelectEditorHandle`:
|
|
431
|
+
|
|
432
|
+
```tsx
|
|
433
|
+
function CompanyPanel({
|
|
434
|
+
deal,
|
|
435
|
+
editorRef,
|
|
436
|
+
onRequestClose,
|
|
437
|
+
}: {
|
|
438
|
+
deal: Deal;
|
|
439
|
+
editorRef: RefObject<RelationEditorHandle | null>;
|
|
440
|
+
onRequestClose: (reason: CloseReason) => void;
|
|
441
|
+
}) {
|
|
442
|
+
return (
|
|
443
|
+
<RelationEditor
|
|
444
|
+
ref={editorRef}
|
|
445
|
+
candidates={COMPANIES}
|
|
446
|
+
initial={deal.companyId}
|
|
447
|
+
clearable
|
|
448
|
+
noneLabel="No company"
|
|
449
|
+
onRequestClose={onRequestClose}
|
|
450
|
+
/>
|
|
451
|
+
);
|
|
452
|
+
}
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
On a binding, `relation` carries the same source, and the grid hands it to this editor when a relation cell opens, or to `RelationSetEditor` when the relation holds several records.
|
|
456
|
+
|
|
457
|
+
## Next
|
|
458
|
+
|
|
459
|
+
- [Cells](cells.md): drawing a column's value outside the grid
|
|
460
|
+
- [The contract](../contract.md): the four shapes of a value, what an edit core never does, a command field
|
|
461
|
+
- [The session's reference](../reference/editors-session.md), [the panel's reference](../reference/editors-panel.md) and [open values' reference](../reference/editors-open-values.md)
|
|
462
|
+
- [Getting started](../getting-started.md)
|