@viewkitjs/views 0.5.0 → 0.6.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 +620 -0
- package/README.md +4 -2
- package/dist/atoms/Avatar.d.ts +2 -0
- package/dist/atoms/Avatar.js +13 -0
- package/dist/atoms/CellMore.d.ts +2 -0
- package/dist/atoms/CellMore.js +4 -0
- package/dist/atoms/DisabledReason.d.ts +11 -0
- package/dist/atoms/DisabledReason.js +10 -0
- package/dist/atoms/DrillRows.d.ts +2 -2
- package/dist/atoms/DrillRows.js +7 -5
- package/dist/atoms/Loading.d.ts +6 -0
- package/dist/atoms/Loading.js +4 -1
- package/dist/atoms/PanelRows.js +3 -5
- package/dist/atoms/Pill.d.ts +2 -0
- package/dist/atoms/Pill.js +25 -0
- package/dist/atoms/RangeCalendar.d.ts +8 -0
- package/dist/atoms/RangeCalendar.js +30 -0
- package/dist/atoms/RelationRoles.js +2 -2
- package/dist/atoms/SelectionSheet.js +5 -4
- package/dist/atoms/ToolbarButton.d.ts +2 -0
- package/dist/atoms/ToolbarButton.js +18 -0
- package/dist/atoms/defaults.js +10 -0
- package/dist/atoms/types.d.ts +141 -1
- package/dist/cells/cell-format.d.ts +10 -1
- package/dist/cells/cell-title.d.ts +5 -1
- package/dist/cells/cell-title.js +2 -2
- package/dist/cells/cell-values.js +22 -7
- package/dist/cells/relation-wrap.js +1 -1
- package/dist/contract.d.ts +351 -15
- package/dist/contract.js +482 -4
- package/dist/display/actor.js +1 -1
- package/dist/display/boolean.js +5 -0
- package/dist/display/entity-chip.d.ts +12 -9
- package/dist/display/entity-chip.js +4 -5
- package/dist/display/fit-values.d.ts +34 -0
- package/dist/display/fit-values.js +45 -0
- package/dist/display/location.js +1 -1
- package/dist/display/multi-value.js +72 -8
- package/dist/display/options.d.ts +9 -1
- package/dist/display/relation.js +1 -1
- package/dist/display/rich-text.js +17 -6
- package/dist/display/select.js +6 -4
- package/dist/display/status-steps.d.ts +8 -0
- package/dist/display/status-steps.js +18 -0
- package/dist/display/viewer.js +1 -0
- package/dist/editors/BodyFrame.d.ts +29 -0
- package/dist/editors/BodyFrame.js +80 -0
- package/dist/editors/DateEditor.js +13 -17
- package/dist/editors/LocationEditor.d.ts +2 -0
- package/dist/editors/LocationEditor.js +29 -5
- package/dist/editors/NameEditor.d.ts +2 -0
- package/dist/editors/NameEditor.js +27 -7
- package/dist/editors/NumberEditor.d.ts +18 -0
- package/dist/editors/NumberEditor.js +29 -2
- package/dist/editors/RangeEditor.d.ts +2 -0
- package/dist/editors/RangeEditor.js +29 -4
- package/dist/editors/SelectEditor.d.ts +5 -0
- package/dist/editors/SelectEditor.js +3 -2
- package/dist/editors/TextEditor.d.ts +11 -1
- package/dist/editors/TextEditor.js +25 -8
- package/dist/editors/ValueListEditor.d.ts +7 -0
- package/dist/editors/ValueListEditor.js +60 -48
- package/dist/editors/body-panel.d.ts +7 -0
- package/dist/editors/body-panel.js +8 -0
- package/dist/editors/edit-session.d.ts +20 -3
- package/dist/editors/edit-session.js +43 -3
- package/dist/editors/leave-scope.d.ts +23 -0
- package/dist/editors/leave-scope.js +28 -0
- package/dist/editors/number-body.d.ts +29 -0
- package/dist/editors/number-body.js +37 -0
- package/dist/editors/parts-body.d.ts +66 -0
- package/dist/editors/parts-body.js +114 -0
- package/dist/editors/tab-ends.d.ts +5 -0
- package/dist/editors/tab-ends.js +7 -0
- package/dist/editors/text-body.d.ts +16 -0
- package/dist/editors/text-body.js +30 -0
- package/dist/editors/values-body.d.ts +47 -0
- package/dist/editors/values-body.js +140 -0
- package/dist/field-row/FieldRow.d.ts +7 -0
- package/dist/field-row/FieldRow.js +44 -24
- package/dist/field-row/FieldRowLane.js +12 -4
- package/dist/field-row/editors/RowChipsEditor.js +3 -1
- package/dist/field-row/editors/RowEditor.js +2 -1
- package/dist/field-row/editors/RowNameEditor.d.ts +5 -2
- package/dist/field-row/editors/RowNameEditor.js +12 -5
- package/dist/field-row/editors/RowNumberEditor.js +18 -2
- package/dist/field-row/editors/RowPlaceEditor.js +4 -2
- package/dist/field-row/editors/RowRangeEditor.d.ts +5 -2
- package/dist/field-row/editors/RowRangeEditor.js +13 -6
- package/dist/field-row/editors/RowRelationEditor.js +5 -2
- package/dist/field-row/editors/RowSelectEditor.js +4 -1
- package/dist/field-row/editors/RowTextEditor.d.ts +1 -1
- package/dist/field-row/editors/RowTextEditor.js +12 -3
- package/dist/field-row/editors/RowValueListEditor.d.ts +2 -1
- package/dist/field-row/editors/RowValueListEditor.js +17 -4
- package/dist/field-row/editors/host.d.ts +3 -0
- package/dist/field-row/editors/row-session.d.ts +12 -1
- package/dist/field-row/editors/row-session.js +52 -2
- package/dist/field-row/field-row-button.d.ts +40 -0
- package/dist/field-row/field-row-button.js +18 -0
- package/dist/field-row/field-row-checkbox.d.ts +9 -0
- package/dist/field-row/field-row-checkbox.js +7 -0
- package/dist/filters/filter-model.d.ts +2 -0
- package/dist/grid/chrome/GridAddColumn.js +17 -3
- package/dist/grid/chrome/GridAggregateMenu.d.ts +2 -0
- package/dist/grid/chrome/GridAggregateMenu.js +2 -0
- package/dist/grid/chrome/GridCellEditors.js +16 -6
- package/dist/grid/chrome/GridCellOutline.d.ts +7 -4
- package/dist/grid/chrome/GridCellOutline.js +4 -2
- package/dist/grid/chrome/GridChipsEditor.js +3 -1
- package/dist/grid/chrome/GridColumnMenu.d.ts +4 -1
- package/dist/grid/chrome/GridColumnMenu.js +5 -3
- package/dist/grid/chrome/GridColumnSortSection.d.ts +20 -0
- package/dist/grid/chrome/GridColumnSortSection.js +18 -1
- package/dist/grid/chrome/GridFooter.d.ts +4 -1
- package/dist/grid/chrome/GridFooter.js +6 -4
- package/dist/grid/chrome/GridGroupMenu.d.ts +5 -1
- package/dist/grid/chrome/GridGroupMenu.js +30 -8
- package/dist/grid/chrome/GridHeader.d.ts +5 -1
- package/dist/grid/chrome/GridHeader.js +9 -5
- package/dist/grid/chrome/GridLongTextEditor.js +15 -11
- package/dist/grid/chrome/GridNameEditor.js +4 -2
- package/dist/grid/chrome/GridNumberEditor.d.ts +8 -1
- package/dist/grid/chrome/GridNumberEditor.js +15 -3
- package/dist/grid/chrome/GridPager.d.ts +7 -0
- package/dist/grid/chrome/GridPager.js +34 -0
- package/dist/grid/chrome/GridPlaceEditor.js +4 -2
- package/dist/grid/chrome/GridRangeEditor.js +12 -4
- package/dist/grid/chrome/GridRelationEditor.js +5 -2
- package/dist/grid/chrome/GridRow.js +18 -6
- package/dist/grid/chrome/GridRowActions.d.ts +8 -3
- package/dist/grid/chrome/GridRowActions.js +16 -6
- package/dist/grid/chrome/GridRowCells.js +23 -7
- package/dist/grid/chrome/GridRowGlyph.d.ts +3 -1
- package/dist/grid/chrome/GridRowGlyph.js +7 -2
- package/dist/grid/chrome/GridSelectEditor.js +6 -3
- package/dist/grid/chrome/GridStructure.d.ts +6 -1
- package/dist/grid/chrome/GridStructure.js +32 -8
- package/dist/grid/chrome/GridTable.js +36 -24
- package/dist/grid/chrome/GridTableSurface.d.ts +5 -1
- package/dist/grid/chrome/GridTableSurface.js +5 -2
- package/dist/grid/chrome/GridTextEditor.d.ts +5 -1
- package/dist/grid/chrome/GridTextEditor.js +13 -3
- package/dist/grid/chrome/GridValueListEditor.d.ts +12 -4
- package/dist/grid/chrome/GridValueListEditor.js +11 -3
- package/dist/grid/chrome/StuckMarker.d.ts +3 -1
- package/dist/grid/chrome/StuckMarker.js +6 -2
- package/dist/grid/chrome/cells.d.ts +4 -2
- package/dist/grid/chrome/cells.js +2 -2
- package/dist/grid/chrome/grid-add-column-items.d.ts +1 -1
- package/dist/grid/chrome/grid-add-column-items.js +8 -1
- package/dist/grid/chrome/grid-button.d.ts +32 -0
- package/dist/grid/chrome/grid-button.js +12 -0
- package/dist/grid/chrome/grid-cell-classes.d.ts +38 -0
- package/dist/grid/chrome/grid-cell-classes.js +30 -0
- package/dist/grid/chrome/grid-column-menu-items.d.ts +3 -0
- package/dist/grid/chrome/grid-column-menu-items.js +32 -3
- package/dist/grid/chrome/grid-columns-template.d.ts +27 -0
- package/dist/grid/chrome/grid-columns-template.js +13 -0
- package/dist/grid/chrome/grid-edit-session.d.ts +4 -1
- package/dist/grid/chrome/grid-edit-session.js +11 -1
- package/dist/grid/chrome/grid-group-menu-items.d.ts +8 -1
- package/dist/grid/chrome/grid-group-menu-items.js +17 -0
- package/dist/grid/chrome/grid-group-menu-parts.d.ts +10 -6
- package/dist/grid/chrome/grid-group-menu-parts.js +4 -2
- package/dist/grid/chrome/grid-hover.d.ts +4 -1
- package/dist/grid/chrome/grid-hover.js +16 -6
- package/dist/grid/chrome/grid-pages.d.ts +15 -0
- package/dist/grid/chrome/grid-pages.js +9 -0
- package/dist/grid/chrome/grid-row-menu-items.js +18 -10
- package/dist/grid/chrome/grid-row-props.d.ts +6 -2
- package/dist/grid/chrome/grid-row-window.d.ts +7 -0
- package/dist/grid/chrome/grid-row-window.js +35 -1
- package/dist/grid/chrome/grid-table-props.d.ts +38 -4
- package/dist/grid/chrome/useGridColumnLayout.d.ts +3 -1
- package/dist/grid/chrome/useGridColumnLayout.js +29 -9
- package/dist/grid/chrome/useGridPartColumns.js +1 -1
- package/dist/grid/chrome/useGridScrollArea.js +2 -0
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +1 -0
- package/dist/grid/chrome/useGridTableInteractionModel.js +5 -3
- package/dist/grid/chrome/useGridTableSelection.d.ts +3 -1
- package/dist/grid/chrome/useGridTableSelection.js +2 -2
- package/dist/grid/chrome/useHeaderDragReorder.js +2 -0
- package/dist/grid/core/editing-controller.d.ts +36 -11
- package/dist/grid/core/editing-controller.js +92 -25
- package/dist/grid/core/grid-aria.d.ts +4 -0
- package/dist/grid/core/grid-aria.js +6 -4
- package/dist/grid/core/grid-focus.d.ts +6 -0
- package/dist/grid/core/grid-focus.js +28 -5
- package/dist/grid/core/useGridEditing.d.ts +11 -2
- package/dist/grid/core/useGridEditing.js +9 -5
- package/dist/grid/core/write-states.d.ts +20 -0
- package/dist/grid/core/write-states.js +21 -0
- package/dist/grid/grid-format-props.d.ts +26 -0
- package/dist/grid/grid-format-props.js +65 -0
- package/dist/grid/index.d.ts +3 -1
- package/dist/grid/index.js +1 -0
- package/dist/grid/useGridTablePrefs.d.ts +19 -20
- package/dist/grid/useGridTablePrefs.js +6 -58
- package/dist/grid/useGridTableSettings.d.ts +60 -0
- package/dist/grid/useGridTableSettings.js +61 -0
- package/dist/internal/count.d.ts +3 -0
- package/dist/internal/count.js +3 -0
- package/dist/model/body-frame.d.ts +16 -0
- package/dist/model/body-frame.js +5 -0
- package/dist/model/column-capabilities.d.ts +4 -1
- package/dist/model/column-capabilities.js +4 -1
- package/dist/model/column-filters.d.ts +7 -4
- package/dist/model/column-filters.js +26 -18
- package/dist/model/column-inspect.d.ts +3 -2
- package/dist/model/column-inspect.js +3 -1
- package/dist/model/column-sort.d.ts +11 -0
- package/dist/model/column-sort.js +14 -0
- package/dist/model/one-value.d.ts +6 -0
- package/dist/model/one-value.js +5 -0
- package/dist/model/part-write.js +1 -1
- package/dist/model/place-parts.d.ts +6 -0
- package/dist/model/place-parts.js +14 -0
- package/dist/model/relation-filters.d.ts +13 -2
- package/dist/model/relation-filters.js +9 -4
- package/dist/model/row-icon.d.ts +16 -6
- package/dist/model/settings-columns.d.ts +34 -0
- package/dist/model/settings-columns.js +146 -0
- package/dist/model/settings-look.d.ts +17 -0
- package/dist/model/settings-look.js +23 -0
- package/dist/model/view-rules.js +6 -2
- package/dist/panels/availability.d.ts +26 -0
- package/dist/panels/availability.js +28 -0
- package/dist/panels/filter/DateFilterBody.d.ts +42 -0
- package/dist/panels/filter/DateFilterBody.js +64 -0
- package/dist/panels/filter/DateFilterCalendar.d.ts +19 -0
- package/dist/panels/filter/DateFilterCalendar.js +37 -0
- package/dist/panels/filter/DateFilterInput.d.ts +16 -0
- package/dist/panels/filter/DateFilterInput.js +37 -0
- package/dist/panels/filter/FilterIcon.d.ts +7 -0
- package/dist/panels/filter/FilterIcon.js +15 -0
- package/dist/panels/filter/MenuSelect.d.ts +12 -0
- package/dist/panels/filter/MenuSelect.js +34 -0
- package/dist/panels/filter/NumberFilterBody.d.ts +21 -0
- package/dist/panels/filter/NumberFilterBody.js +76 -0
- package/dist/panels/filter/RangeFilterBody.d.ts +19 -0
- package/dist/panels/filter/RangeFilterBody.js +71 -0
- package/dist/panels/filter/RelationFilterBody.d.ts +17 -0
- package/dist/panels/filter/RelationFilterBody.js +20 -0
- package/dist/panels/filter/TextFilterBody.d.ts +31 -0
- package/dist/panels/filter/TextFilterBody.js +44 -0
- package/dist/panels/filter/TimeScopeDetail.d.ts +6 -0
- package/dist/panels/filter/TimeScopeDetail.js +47 -0
- package/dist/panels/filter/details.d.ts +17 -0
- package/dist/panels/filter/details.js +73 -0
- package/dist/panels/filter/filter-list.d.ts +23 -0
- package/dist/panels/filter/filter-list.js +38 -0
- package/dist/panels/group-sort.d.ts +24 -0
- package/dist/panels/group-sort.js +58 -0
- package/dist/panels/index.d.ts +24 -0
- package/dist/panels/index.js +17 -0
- package/dist/panels/labels.d.ts +37 -0
- package/dist/panels/labels.js +166 -0
- package/dist/panels/model.d.ts +343 -0
- package/dist/panels/model.js +77 -0
- package/dist/panels/react/GroupBucketsList.d.ts +16 -0
- package/dist/panels/react/GroupBucketsList.js +38 -0
- package/dist/panels/react/LayoutColumnsList.d.ts +24 -0
- package/dist/panels/react/LayoutColumnsList.js +71 -0
- package/dist/panels/react/PopoverColumnDetail.d.ts +11 -0
- package/dist/panels/react/PopoverColumnDetail.js +24 -0
- package/dist/panels/react/chrome.d.ts +17 -0
- package/dist/panels/react/chrome.js +8 -0
- package/dist/panels/react/column-refusals.d.ts +7 -0
- package/dist/panels/react/column-refusals.js +14 -0
- package/dist/panels/react/customize.d.ts +26 -0
- package/dist/panels/react/customize.js +98 -0
- package/dist/panels/react/drag.d.ts +2 -0
- package/dist/panels/react/drag.js +6 -0
- package/dist/panels/react/field-editor.d.ts +10 -0
- package/dist/panels/react/field-editor.js +1 -0
- package/dist/panels/react/filter-panel.d.ts +15 -0
- package/dist/panels/react/filter-panel.js +48 -0
- package/dist/panels/react/layout-detail.d.ts +4 -0
- package/dist/panels/react/layout-detail.js +21 -0
- package/dist/panels/react/order-details.d.ts +32 -0
- package/dist/panels/react/order-details.js +81 -0
- package/dist/panels/react/panel-header.d.ts +10 -0
- package/dist/panels/react/panel-header.js +12 -0
- package/dist/panels/react/panel-sheet.d.ts +19 -0
- package/dist/panels/react/panel-sheet.js +22 -0
- package/dist/panels/react/popover.d.ts +71 -0
- package/dist/panels/react/popover.js +47 -0
- package/dist/panels/react/root-list.d.ts +6 -0
- package/dist/panels/react/root-list.js +31 -0
- package/dist/panels/react/toolbar/ReadyToolbar.d.ts +42 -0
- package/dist/panels/react/toolbar/ReadyToolbar.js +92 -0
- package/dist/panels/react/toolbar/Toolbar.d.ts +16 -0
- package/dist/panels/react/toolbar/Toolbar.js +34 -0
- package/dist/panels/react/toolbar/ToolbarButton.d.ts +5 -0
- package/dist/panels/react/toolbar/ToolbarButton.js +9 -0
- package/dist/panels/react/toolbar/ToolbarFilter.d.ts +19 -0
- package/dist/panels/react/toolbar/ToolbarFilter.js +32 -0
- package/dist/panels/react/toolbar/ToolbarNew.d.ts +12 -0
- package/dist/panels/react/toolbar/ToolbarNew.js +21 -0
- package/dist/panels/react/toolbar/ToolbarOptions.d.ts +25 -0
- package/dist/panels/react/toolbar/ToolbarOptions.js +33 -0
- package/dist/panels/react/toolbar/ToolbarSearch.d.ts +9 -0
- package/dist/panels/react/toolbar/ToolbarSearch.js +41 -0
- package/dist/panels/react/toolbar/ToolbarSort.d.ts +12 -0
- package/dist/panels/react/toolbar/ToolbarSort.js +16 -0
- package/dist/panels/react/toolbar/ToolbarViews.d.ts +13 -0
- package/dist/panels/react/toolbar/ToolbarViews.js +24 -0
- package/dist/panels/react/toolbar/context.d.ts +29 -0
- package/dist/panels/react/toolbar/context.js +49 -0
- package/dist/panels/react/toolbar/panel-part.d.ts +37 -0
- package/dist/panels/react/toolbar/panel-part.js +37 -0
- package/dist/panels/react/toolbar/panel-state.d.ts +9 -0
- package/dist/panels/react/toolbar/panel-state.js +12 -0
- package/dist/panels/react/toolbar/use-box-narrow.d.ts +2 -0
- package/dist/panels/react/toolbar/use-box-narrow.js +18 -0
- package/dist/panels/react/toolbar/use-list-settings-state.d.ts +10 -0
- package/dist/panels/react/toolbar/use-list-settings-state.js +10 -0
- package/dist/panels/react/view-actions.d.ts +4 -0
- package/dist/panels/react/view-actions.js +37 -0
- package/dist/panels/react/view-footer.d.ts +16 -0
- package/dist/panels/react/view-footer.js +11 -0
- package/dist/panels/react/views-row/FoldingViewRow.d.ts +4 -0
- package/dist/panels/react/views-row/FoldingViewRow.js +105 -0
- package/dist/panels/react/views-row/HScrollRow.d.ts +7 -0
- package/dist/panels/react/views-row/HScrollRow.js +42 -0
- package/dist/panels/react/views-row/PillGroup.d.ts +30 -0
- package/dist/panels/react/views-row/PillGroup.js +86 -0
- package/dist/panels/react/views-row/ViewAxes.d.ts +6 -0
- package/dist/panels/react/views-row/ViewAxes.js +16 -0
- package/dist/panels/react/views-row/ViewCreatePill.d.ts +7 -0
- package/dist/panels/react/views-row/ViewCreatePill.js +11 -0
- package/dist/panels/react/views-row/ViewPicker.d.ts +5 -0
- package/dist/panels/react/views-row/ViewPicker.js +65 -0
- package/dist/panels/react/views-row/ViewPickerRow.d.ts +7 -0
- package/dist/panels/react/views-row/ViewPickerRow.js +18 -0
- package/dist/panels/react/views-row/ViewTabs.d.ts +31 -0
- package/dist/panels/react/views-row/ViewTabs.js +29 -0
- package/dist/panels/react/views-row/menu-classes.d.ts +6 -0
- package/dist/panels/react/views-row/menu-classes.js +3 -0
- package/dist/panels/react/views-row/use-anchored-toggle.d.ts +19 -0
- package/dist/panels/react/views-row/use-anchored-toggle.js +31 -0
- package/dist/panels/react.d.ts +51 -0
- package/dist/panels/react.js +43 -0
- package/dist/panels/settings/axes.d.ts +28 -0
- package/dist/panels/settings/axes.js +71 -0
- package/dist/panels/settings/filters.d.ts +5 -0
- package/dist/panels/settings/filters.js +62 -0
- package/dist/panels/settings/group-buckets.d.ts +23 -0
- package/dist/panels/settings/group-buckets.js +73 -0
- package/dist/panels/settings/input.d.ts +69 -0
- package/dist/panels/settings/input.js +1 -0
- package/dist/panels/settings/layout.d.ts +5 -0
- package/dist/panels/settings/layout.js +244 -0
- package/dist/panels/settings/order.d.ts +19 -0
- package/dist/panels/settings/order.js +271 -0
- package/dist/panels/settings/settings-panels.d.ts +17 -0
- package/dist/panels/settings/settings-panels.js +28 -0
- package/dist/panels/toolbar/clear.d.ts +9 -0
- package/dist/panels/toolbar/clear.js +26 -0
- package/dist/panels/toolbar/counts.d.ts +15 -0
- package/dist/panels/toolbar/counts.js +21 -0
- package/dist/panels/toolbar/edit-view.d.ts +5 -0
- package/dist/panels/toolbar/edit-view.js +18 -0
- package/dist/panels/toolbar/model.d.ts +34 -0
- package/dist/panels/toolbar/model.js +52 -0
- package/dist/panels/use-filter-opened.d.ts +8 -0
- package/dist/panels/use-filter-opened.js +11 -0
- package/dist/panels/view-state.d.ts +38 -0
- package/dist/panels/view-state.js +1 -0
- package/dist/panels/views-row/model.d.ts +131 -0
- package/dist/panels/views-row/model.js +14 -0
- package/dist/provider/ViewsProvider.d.ts +46 -6
- package/dist/provider/ViewsProvider.js +32 -2
- package/dist/provider/components.d.ts +258 -11
- package/dist/provider/context.d.ts +21 -2
- package/dist/react.d.ts +5 -2
- package/dist/selection/SelectionBar.js +13 -7
- package/dist/selection/bar-overflow.js +14 -1
- package/dist/selection/bar-parts.d.ts +4 -2
- package/dist/selection/bar-parts.js +5 -3
- package/dist/selection/useListSelectionShortcuts.d.ts +3 -2
- package/dist/selection/useListSelectionShortcuts.js +1 -1
- package/dist/selection/verbs.d.ts +7 -0
- package/docs/contract.md +307 -41
- package/docs/getting-started.md +1 -1
- package/docs/guides/atoms.md +37 -5
- package/docs/guides/columns.md +1 -1
- package/docs/guides/display.md +3 -2
- package/docs/guides/editors.md +4 -3
- package/docs/guides/selection.md +4 -2
- package/docs/guides/the-grid.md +21 -11
- package/docs/guides/the-provider.md +22 -6
- package/docs/index.md +2 -2
- package/docs/install.md +2 -3
- package/docs/reference/cells.md +1 -1
- package/docs/reference/display.md +5 -4
- package/docs/reference/editors-location.md +3 -1
- package/docs/reference/editors-name.md +3 -1
- package/docs/reference/editors-number.md +1 -0
- package/docs/reference/editors-range.md +3 -1
- package/docs/reference/editors-session.md +1 -0
- package/docs/reference/editors-text.md +2 -2
- package/docs/reference/editors-value-list.md +1 -1
- package/docs/reference/field-row.md +2 -2
- package/docs/reference/grid.md +8 -5
- package/docs/reference/panels-react.md +101 -0
- package/docs/reference/panels.md +123 -0
- package/docs/reference/react.md +39 -16
- package/docs/reference/selection.md +5 -5
- package/docs/reference/views.md +17 -12
- package/package.json +16 -6
- package/skills/views/SKILL.md +4 -3
package/docs/getting-started.md
CHANGED
|
@@ -8,7 +8,7 @@ This page takes you from install to a grid of records drawn with your own primit
|
|
|
8
8
|
pnpm add @viewkitjs/views @viewkitjs/fields zod
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
`react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The dnd-kit packages are optional peers of views, for the panels' door
|
|
11
|
+
`react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The dnd-kit packages are optional peers of views, for the drawn panels' door (`@viewkitjs/views/panels/react`): install them only if you import it. The package is ESM only and runs on Node 20 or later.
|
|
12
12
|
|
|
13
13
|
The rendering carries Tailwind classes drawn from your tokens and paints through its own colour names. Two lines of setup make it look like your app: one `@source` line, so Tailwind sees the package, and one block mapping the `--vk-*` colours onto your theme. [Install](install.md) has both.
|
|
14
14
|
|
package/docs/guides/atoms.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Atoms
|
|
2
2
|
|
|
3
|
-
The components map hands the package your primitives: a button, a popover, a menu. The atoms sit one level up. They are the small pieces the rendering is built from (a row, a tag, a status badge), and the pieces of your app it cannot draw itself (where a relation chip goes, a command cell's verbs, the row's right-click menu). Every atom ships with a default drawn from your colours, so an app that swaps nothing still gets a complete rendering. This page covers
|
|
3
|
+
The components map hands the package your primitives: a button, a popover, a menu. The atoms sit one level up. They are the small pieces the rendering is built from (a row, a tag, a status badge), and the pieces of your app it cannot draw itself (where a relation chip goes, a command cell's verbs, the row's right-click menu). Every atom ships with a default drawn from your colours, so an app that swaps nothing still gets a complete rendering. This page covers every atom, swapping any of them, and drawing your own panels with the same rows the rendering uses.
|
|
4
4
|
|
|
5
|
-
## The
|
|
5
|
+
## The atoms and their defaults
|
|
6
6
|
|
|
7
7
|
`DEFAULT_VIEWS_ATOMS`, from `@viewkitjs/views/react`, holds one default per atom:
|
|
8
8
|
|
|
@@ -16,11 +16,16 @@ The components map hands the package your primitives: a button, a popover, a men
|
|
|
16
16
|
- `CommandMenu`: a `command` cell's verbs.
|
|
17
17
|
- `RelationLink`: where a relation chip goes.
|
|
18
18
|
- `RelationRoles`: a link's roles, inside its chip after the record's name.
|
|
19
|
+
- `CellMore`: the "+N" after a cell's shown values, inside `data-slot="vk-cell-more"`. ViewKit's own keeps its frame; yours draws inside a bare button, so your count tag stands there alone.
|
|
19
20
|
- `Loading`: a wait, the whole list reloading or more rows arriving.
|
|
20
21
|
- `LoadMore`: how a list asks for its next page.
|
|
21
22
|
- `PlatformMark`: a link's platform mark, drawn before the link.
|
|
22
23
|
- `RowMenu`: the row's right-click menu.
|
|
24
|
+
- `Avatar`: a person's or a record's picture, in a user's, a relation's and an actor's chip, and before the name when the list hands a row's picture. The default draws the picture, else the glyph the chip would draw.
|
|
23
25
|
- `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`: the rows the panels (`/panels`) draw with, a value row, a tick row, a one-of-a-set row, a sort's direction arrow, a drill-in row, a switch row and a panel's text box.
|
|
26
|
+
- `Pill`: one option of a row of pills, the views row's (`/panels/react`) and any tab row's.
|
|
27
|
+
- `RangeCalendar`: the filter panel's month, a day or a range in ISO days. The default is your components map's one-day `Calendar` on the end being picked, and paints no range; hand your own to paint one.
|
|
28
|
+
- `ToolbarButton`: the toolbar's button (`/panels/react`), a glyph in a circle with its word for a dress that shows words, a count that becomes a ✕ badge when it can clear what it counts, and a dot. Hand your own to give the toolbar your buttons' look.
|
|
24
29
|
|
|
25
30
|
The names are `ATOM_NAMES` from `@viewkitjs/views`, and the defaults hold exactly those.
|
|
26
31
|
|
|
@@ -32,7 +37,7 @@ import { DEFAULT_VIEWS_ATOMS, type ViewsAtoms } from "@viewkitjs/views/react";
|
|
|
32
37
|
assert.deepEqual(Object.keys(DEFAULT_VIEWS_ATOMS).sort(), [...ATOM_NAMES].sort());
|
|
33
38
|
```
|
|
34
39
|
|
|
35
|
-
The first seven are the rendering's own look, and their defaults are usually all an app needs. The
|
|
40
|
+
The first seven are the rendering's own look, and their defaults are usually all an app needs. The next eight are where your app comes in: the package can't know where a record opens, which menu your app opens verbs in, what a LinkedIn mark looks like, or how your app draws a person. Their defaults are deliberately plain: a relation chip that goes nowhere, a command menu and a row menu on your components map's `Menu`, a ring for a wait, no platform mark at all, and a chip's picture or glyph as the package has always drawn it.
|
|
36
41
|
|
|
37
42
|
## Swapping an atom
|
|
38
43
|
|
|
@@ -164,13 +169,40 @@ function AppPlatformMark({ platform, className }: ViewsPlatformMarkProps) {
|
|
|
164
169
|
|
|
165
170
|
In your app the glyph is your icon component per key. The platform is read for filters whatever the mark draws.
|
|
166
171
|
|
|
172
|
+
## A person's or a record's picture
|
|
173
|
+
|
|
174
|
+
A user's, a relation's and an actor's chip draw `Avatar` before their name, at `size="chip"`. The name draws it too, at `size="glyph"` (sized by `--vk-glyph`), for a row whose `rowIcon` hands an `avatar` (`{ icon: "building", avatar: { label: row.name, avatarUrl: row.logo, kind: "company" } }`). Each time it is handed `label` (whose picture it is), `avatarUrl` when there is one, `kind` (a relation's `entity`, `user` for a member, an actor's type) and `fallback`, the glyph the chip or the name draws without a picture. The default draws the picture while it loads and the fallback otherwise, the same picture-or-glyph the chips have always drawn. Hand your own to draw initials on a tone, or a record in its own shape:
|
|
175
|
+
|
|
176
|
+
```tsx
|
|
177
|
+
import type { ViewsAvatarProps } from "@viewkitjs/views/react";
|
|
178
|
+
|
|
179
|
+
const DRESSED = new Set(["user", "person", "company"]);
|
|
180
|
+
|
|
181
|
+
function AppAvatar({ label, avatarUrl, kind, size, fallback }: ViewsAvatarProps) {
|
|
182
|
+
// An automation, an API key, the system: the glyph the chip would draw anyway.
|
|
183
|
+
if (kind !== undefined && !DRESSED.has(kind)) return <>{fallback}</>;
|
|
184
|
+
const shape = kind === "company" ? "avatar avatar-square" : "avatar";
|
|
185
|
+
const sized = size === "chip" ? `${shape} avatar-16` : `${shape} avatar-glyph`;
|
|
186
|
+
if (avatarUrl) return <img src={avatarUrl} alt="" className={sized} />;
|
|
187
|
+
const initials = label
|
|
188
|
+
.split(/\s+/)
|
|
189
|
+
.slice(0, 2)
|
|
190
|
+
.map((word) => word[0] ?? "")
|
|
191
|
+
.join("")
|
|
192
|
+
.toUpperCase();
|
|
193
|
+
return <span className={`${sized} avatar-initials`}>{initials}</span>;
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
In your app it is your own Avatar component, its tone read from the label. What wraps the chip still owns its click (`RelationLink`), so an avatar only paints. A picture that fails to load is yours to catch: the default falls back to the glyph.
|
|
198
|
+
|
|
167
199
|
## A command cell's verbs
|
|
168
200
|
|
|
169
|
-
A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items`, `align` and `label`, the field's name. Each item has a `label`, an optional `icon`, its `onClick`, `destructive` and `disabled` flags, and a `disabledReason` for a disabled one. The default names your components map's `Menu` after the field ("Actions for Stage"), anchors it on the trigger and keeps the click off the row, so opening the verbs neither selects the cell nor opens the row. Swap it when your app has its own action menu, or a sheet on a phone. [The contract](../contract.md#a-command-field) says how a command field is declared.
|
|
201
|
+
A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items`, `align` and `label`, the field's name. Each item has a `label`, an optional `icon`, its `onClick`, `destructive` and `disabled` flags, and a `disabledReason` for a disabled one; while the record loads, every verb arrives disabled, with your reason or else "Wait for current data before editing" (`views.menus.loading`). The default names your components map's `Menu` after the field ("Actions for Stage"), anchors it on the trigger and keeps the click off the row, so opening the verbs neither selects the cell nor opens the row. Swap it when your app has its own action menu, or a sheet on a phone. [The contract](../contract.md#a-command-field) says how a command field is declared.
|
|
170
202
|
|
|
171
203
|
## The row's menu
|
|
172
204
|
|
|
173
|
-
`RowMenu` wraps a section's rows: the grid mounts it once around each section's rows' container, never around each row, and aims it at the row a press or a right-click came from. Its props are that row's, set in the same event your menu opens on; `children` is the rows' container, which takes the props and `ref` your trigger hands it (a `Slot`, `asChild`) and passes them to its element; a right-click on no row arrives already prevented and opens nothing. The rendering builds its `items` (the clicked cell's clipboard rows, Select, your verbs for the row), and the menu adds an Open page row before them when the row has a page (`openHref`, opened in a new tab) and a Delete row after them when the row can be deleted (`onDelete`). Its props are `ViewsRowMenuProps`; each item is a `ViewsRowMenuItem`, a rule (`{ separator: true }`) or a labelled row with its `onClick`, optional `icon`, `destructive`, `disabled` with its `disabledReason
|
|
205
|
+
`RowMenu` wraps a section's rows: the grid mounts it once around each section's rows' container, never around each row, and aims it at the row a press or a right-click came from. Its props are that row's, set in the same event your menu opens on; `children` is the rows' container, which takes the props and `ref` your trigger hands it (a `Slot`, `asChild`) and passes them to its element; a right-click on no row arrives already prevented and opens nothing. The rendering builds its `items` (the clicked cell's clipboard rows, Select, your verbs for the row), and the menu adds an Open page row before them when the row has a page (`openHref`, opened in a new tab) and a Delete row after them when the row can be deleted (`onDelete`). Its props are `ViewsRowMenuProps`; each item is a `ViewsRowMenuItem`, a rule (`{ separator: true }`) or a labelled row with its `onClick`, optional `icon`, `destructive`, `disabled` with its `disabledReason` (the grid's own Cut, Paste and Clear carry one whenever they are disabled), and a `shortcut` hint the menu draws but never binds. The default names your `Menu` "Row actions" (`views.menus.row-menu`).
|
|
174
206
|
|
|
175
207
|
The default opens your `Menu` at the pointer on a right-click, or from the row's ⋯ (`data-slot="vk-grid-row-more"`). On a touch screen a long-press opens nothing: the ⋯ is the way in there. Its Delete asks first, through the `confirm` port, with the message `views.menus.row-delete-confirm` and the row's `deleteLabel` as the `subject`; an app that hands no `confirm` gets the browser's own, and a confirm that rejects or throws counts as no. A delete that then rejects leaves the row where it was and says so through the toast port's `error`, with `views.menus.row-delete-failed`. [Ports](ports.md) covers `confirm` and the toast.
|
|
176
208
|
|
package/docs/guides/columns.md
CHANGED
|
@@ -377,7 +377,7 @@ assert.throws(
|
|
|
377
377
|
);
|
|
378
378
|
```
|
|
379
379
|
|
|
380
|
-
The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled` and its `disabledReason`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
|
|
380
|
+
The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled` and its `disabledReason`). Being a function of the row, the menu follows the record's state. While the record loads, each verb arrives disabled, with your reason or else "Wait for current data before editing". The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
|
|
381
381
|
|
|
382
382
|
```ts
|
|
383
383
|
import type { FieldMenus } from "@viewkitjs/views";
|
package/docs/guides/display.md
CHANGED
|
@@ -82,6 +82,7 @@ assert.equal(DISPLAY_CORES.date, DISPLAY_CORES.datetime);
|
|
|
82
82
|
- **lookup** and **formula**: as the field their result is. A **rollup** grouped by an option draws a segmented bar beside its headline, and one grouped by time a sparkline, the current bucket faded.
|
|
83
83
|
|
|
84
84
|
A value that holds several, of any of these types, uses `MultiValueCell`: one value, or three when wrapped, then a `+N` count that opens all of them in a list. It is exported for your own cells; [the display reference](../reference/display.md) has its props.
|
|
85
|
+
With the provider's `severalValues: "fit"`, a value on one line shows as many whole values as fit its width, then the count ([the provider](the-provider.md)). The count is the `CellMore` atom ([atoms](atoms.md)).
|
|
85
86
|
|
|
86
87
|
## What the field can't know
|
|
87
88
|
|
|
@@ -89,7 +90,7 @@ A field says what the value is. The rest arrives in `DisplayOptions`, from the s
|
|
|
89
90
|
|
|
90
91
|
- The row's answers: `currency` (the code this value is in), `nameFallback` (the words for an empty name, say the person's email), `labelFallback` and `optionColors`.
|
|
91
92
|
- The reader's choices: `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay` and `wrap`.
|
|
92
|
-
- A boolean's verbs and words: `onToggle`, `booleanDisabled`, `booleanIcon`, `marker`, `markerReason` and `onResolve`.
|
|
93
|
+
- A boolean's verbs and words: `onToggle`, `booleanDisabled`, `booleanIcon`, `booleanCheckbox`, `marker`, `markerReason` and `onResolve`. `booleanCheckbox` is a checkbox control of yours (the components map's `Checkbox`): handed one, the checkbox style draws it alone in place of the tick box and its switch, as the grid does while the provider's `gridCheckboxes` is `checkbox`, and a field row while `fieldRowCheckboxes` is.
|
|
93
94
|
- A relation's: `entityIcon` and `relationWrap`.
|
|
94
95
|
- `slotOwnsClick`, for a host whose own element is already the button, such as a calendar card: every core then draws bare content, with no link, no toggle and a count that opens nothing.
|
|
95
96
|
- `hostOwnsPlainClick`, for a host whose plain click on a value is its own, as the grid's click selects its cell: an email, phone, url or domain stays a link, marked `data-cell-link`, but no longer stops its click, so your host decides (the grid follows it only on a ⌘- or Ctrl-click).
|
|
@@ -124,7 +125,7 @@ const openInDrawer =
|
|
|
124
125
|
|
|
125
126
|
A footer total, a column menu's live preview or a server-rendered email need the value as a string, not an element. `formatDateValue` and `formatNumberValue` are those strings, the same ones the cells draw, and the door carries no client directive, so a server module imports them as they are.
|
|
126
127
|
|
|
127
|
-
Both read a viewer: who is reading, in which locale and time zone, at what moment. `viewerFrom(conventions, messages?, now?)` builds one from the conventions you hand fields: their locale, zone, region and wording, with the package's words unless you hand a resolver and the current moment unless you hand one.
|
|
128
|
+
Both read a viewer: who is reading, in which locale and time zone, at what moment. `viewerFrom(conventions, messages?, now?)` builds one from the conventions you hand fields: their locale, names language, zone, region and wording, with the package's words unless you hand a resolver and the current moment unless you hand one.
|
|
128
129
|
|
|
129
130
|
```ts
|
|
130
131
|
import { formatDateValue, formatNumberValue, viewerFrom } from "@viewkitjs/views/display";
|
package/docs/guides/editors.md
CHANGED
|
@@ -62,7 +62,7 @@ assert.equal(TEXT_INPUT_TYPE.domain, "url");
|
|
|
62
62
|
|
|
63
63
|
## What an editor owns, and what you own
|
|
64
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 (or opens your app's own `DateBody` in their place, keeping the draft) 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.
|
|
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 (or opens your app's own `DateBody` in their place, keeping the draft) 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. Where it opens your app's own body (`Picker`, `PartsBody` or `ValuesBody`), the popover around it keeps ViewKit's width and padding, unless the provider's `bodyFrame` is `popover`: then it stands at your `Popover`'s own width, marked `data-vk-body` ([the provider](the-provider.md)).
|
|
66
66
|
|
|
67
67
|
The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
|
|
68
68
|
|
|
@@ -76,9 +76,9 @@ What an editor never does on its own (write, fetch, toast, decide the popover) i
|
|
|
76
76
|
|
|
77
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
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 throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. Hand it `escape: "keep"` and, on a desktop, Escape keeps what was typed: the session asks the editor as it would for a press outside, so a value
|
|
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 throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. Hand it `escape: "keep"` and, on a desktop, Escape keeps what was typed: the session asks the editor as it would for a press outside, so a value your host refuses in its answer to the attempt stays open with its reason, and a second Escape while that refusal stands throws the edit away. A refusal that comes after the session has closed (your server's answer to the save) is your host's to show, as it is after Enter; the grid shows it on the cell and a field row under the row. Read the rule for a field's type from the provider with `useEscapeRule(type)`; the app sets it once, `<ViewsProvider escape={{ date: "keep", location: "keep" }}>`, and a type it leaves out throws the edit away. An editor that commits only on a pick (a select, a status, a single relation, a user) throws the edit away on Escape whatever the rule, and the value list checks its rows first, as on Enter (`escapeKeeps={session.keeps}`). It gives you two ways to hear the answer:
|
|
80
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.
|
|
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, or at once when the page goes first (Leaving the page, below). Prefer this one.
|
|
82
82
|
- `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
|
|
83
83
|
|
|
84
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)`.
|
|
@@ -278,6 +278,7 @@ The host above draws its own popover, so on a phone it still opens a popover. `E
|
|
|
278
278
|
- **Desktop:** the popover's Escape discards, or keeps where the session keeps. 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
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
280
|
- **Refusals:** a value your `onAttempt` refuses with a `reason` stays open, and the reason is drawn under the editor.
|
|
281
|
+
- **Leaving the page:** a grid or field-row editor still open when the page goes (`pagehide`), or when the grid or the row goes while the page stays (a route, Back inside the app, a drawer closed), writes what a press outside would on a desktop, and nothing in a phone's sheet; a refused value writes nothing, and its reason is said in a toast only when the grid goes while the page stays. The session calls your commit inside `pagehide`, so a write that must outlive the page is yours to send (`fetch(…, { keepalive: true })` or a beacon); listen to `pagehide` yourself to know the page is going. A host of your own asks an editor still open nothing unless you pass `leave: "outside"` to its session; on every host an answer already given is finished at once when the page goes, its `onClose` (or `onDone`) running then instead of after the gap.
|
|
281
282
|
|
|
282
283
|
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
|
|
package/docs/guides/selection.md
CHANGED
|
@@ -19,7 +19,7 @@ Turning a row on or off ticks the provider's `haptics.selection()`, select all g
|
|
|
19
19
|
|
|
20
20
|
`resetKey` empties the selection when it changes: pass the identity of the view and its filter, so a selection never carries over to rows a person can't see. `retention` says what happens to a selected id that leaves `orderedIds`. `"ordered"`, the default, drops it. `"external"` (a `SelectionRetention`) keeps it, for a selection across a whole query whose rows aren't all loaded. Either way the range anchor has to stay on screen to count.
|
|
21
21
|
|
|
22
|
-
`useEscapeToClear(active, clear)` clears on Escape anywhere in the window while `active` is true.
|
|
22
|
+
`useEscapeToClear(active, clear)` clears on Escape anywhere in the window while `active` is true, unless something open already took that Escape: a menu or popover that closes on the key marks it handled with `preventDefault` (Radix and Base UI both do), so one press closes the menu and the next clears the selection. A popup of your own that closes on Escape does the same.
|
|
23
23
|
|
|
24
24
|
```tsx
|
|
25
25
|
import { useMemo, useRef, type MouseEvent as ReactMouseEvent, type ReactNode } from "react";
|
|
@@ -207,6 +207,8 @@ What a selection lets a person do (move twelve deals to a stage, export them, de
|
|
|
207
207
|
- `group`: a button opening a small menu of `items`, each an action;
|
|
208
208
|
- `options`: one field set on every selected row, its `options` drawn as the badges a cell shows (a `PickerOption` each), `onSelect` handed the value picked.
|
|
209
209
|
|
|
210
|
+
Any of the three can be `disabled`, and say why with `disabledReason`, in the person's words: More's rows hand it to your `Menu`, the bar's own button shows it in your `Tooltip`, and the phone's sheet draws it under the row. A group's rows that give no reason of their own carry the group's.
|
|
211
|
+
|
|
210
212
|
Delete is not a verb: it is the bar's own `onDelete`, drawn as the trailing trash in the same place on every list (in words, last, in the phone's sheet). `busy` disables everything while a batch runs.
|
|
211
213
|
|
|
212
214
|
A renderer with an editing model also hands the bar a `ListBatchApi`: `setColumnValue(rowIds, columnId, value)` writes one column across the rows through the renderer's own write path, and resolves to whether the write landed. The grid's goes through the same gate as a cell edit, so a column that can't be written, or one a workspace locked, resolves `false`, and a selected id whose row isn't loaded is skipped. The plain list above has no editing model, so its bar gets none.
|
|
@@ -234,7 +236,7 @@ function DealsBar({ sel, batch }: { sel: UseListSelectionResult; batch?: ListBat
|
|
|
234
236
|
}
|
|
235
237
|
```
|
|
236
238
|
|
|
237
|
-
Where the bar sits is yours, set once on the provider's `selectionBar`: its `bottom`, `zIndex` and `className` on each form,
|
|
239
|
+
Where the bar sits is yours, set once on the provider's `selectionBar`: its `bottom`, `zIndex` and `className` on each form, a `phoneQuery` when your shell's phone layout starts at another width, and a `chip: "button"` when your `Button` should draw the count chip (an app with a bottom nav lifts the pill above it). The phone's sheet is the `SelectionSheet` atom: its default is your `Sheet` holding plain rows, and you swap in your own action sheet through the provider's `atoms`.
|
|
238
240
|
|
|
239
241
|
## The grid takes a selection
|
|
240
242
|
|
package/docs/guides/the-grid.md
CHANGED
|
@@ -89,7 +89,7 @@ const DEALS: Deal[] = [
|
|
|
89
89
|
|
|
90
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
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.
|
|
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. A grouped grid draws each group's column names under its bar; `oneHeader` draws one row of them over every group instead, pinned at the top, each bar pinning under it.
|
|
93
93
|
|
|
94
94
|
```tsx
|
|
95
95
|
import { GridTable } from "@viewkitjs/views/grid";
|
|
@@ -158,9 +158,9 @@ A list whose rows come a page at a time from a database runs the same view there
|
|
|
158
158
|
|
|
159
159
|
## The sort and the group
|
|
160
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.
|
|
161
|
+
The header's menu offers Sort ascending, Sort descending and Clear sort, and Group by and Ungroup; on a place column Sort ascending and Sort descending each open its parts beside the menu (City, Region, Country, Postal code), and the pick is the part key `partKey(fieldKey, part)`, which you read with `parsePartKey`; 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
162
|
|
|
163
|
-
- `sort`, a `GridSortState`: the sort key in force (`value
|
|
163
|
+
- `sort`, a `GridSortState`: the sort key in force (`value`, a place's part key while a place sorts by one of its parts), its direction (`dir`, `"asc"` or `"desc"`), and `onChange`, called with the pick. Clear sort calls it with an empty `value`.
|
|
164
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
165
|
- `sortOptions`, the `GridGroupSortOption`s a group's band offers: each a sort key, its label and the direction it opens in.
|
|
166
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.
|
|
@@ -240,7 +240,7 @@ Collapsing is yours too: `isCollapsed` answers for a group's key and `onToggleGr
|
|
|
240
240
|
|
|
241
241
|
## Writes
|
|
242
242
|
|
|
243
|
-
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
|
+
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`. An editor still open when the page goes (`pagehide`) or the grid goes while the page stays commits as a press outside would, so it can be called inside `pagehide`: send a write that must outlive the page with `keepalive`. The grid shows the value at once and keeps it while the write runs; how your function ends decides what happens next.
|
|
244
244
|
|
|
245
245
|
- 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.
|
|
246
246
|
- 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.
|
|
@@ -342,7 +342,7 @@ Before a value reaches you it has passed the grid's write gate (Editing and writ
|
|
|
342
342
|
|
|
343
343
|
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.
|
|
344
344
|
|
|
345
|
-
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
|
+
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. A list kept as `@viewkitjs/fields/query`'s `ListSettings` and a person's `ListPersonalLayer` takes `useGridTableSettings` instead: the same props, each change handed back as a settings change or a layer patch.
|
|
346
346
|
|
|
347
347
|
```tsx
|
|
348
348
|
import { useCallback } from "react";
|
|
@@ -396,10 +396,12 @@ The columns' widths, order and visibility travel as `columnState`, a `ListColumn
|
|
|
396
396
|
|
|
397
397
|
### A column per part
|
|
398
398
|
|
|
399
|
-
With `parts`, a name, a place or a range offers a column per part beside its whole column: a place's country, region, city and postal code, a name's given and family names, a range's low and high ends. Each starts hidden; "+ Add column" lists a field with parts as one row that drills into the field (when hidden) and its hidden parts, as Attio's does, and a search lists parts by their full label ("Address · Country"). On the `menu` route (the provider's `menus`) that field is a group beside your `Menu`, its count as `detail`, with no search field, and on a phone too it is your `Menu`, not your `Sheet`. A part column's id is `partKey(columnId, part)`, the key its Filter row has when your panels pass `parts: true`, so that row filters what the column shows; its sort value is `partKey(fieldKey, part)`, which `parsePartKey` turns into a sort's `fieldKey` and `by`. It reads and copies its part, and it edits and pastes as its part, in a box of its own: text for a name's part and a place's region, city and postal code, a number for a range's end, and the select over every country by name, searchable, for a place's country. A paste or a fill into a country cell takes a country's name, in the app's locale or
|
|
399
|
+
With `parts`, a name, a place or a range offers a column per part beside its whole column: a place's country, region, city and postal code, a name's given and family names, a range's low and high ends. Each starts hidden; "+ Add column" lists a field with parts as one row that drills into the field (when hidden) and its hidden parts, as Attio's does, and a search lists parts by their full label ("Address · Country"). On the `menu` route (the provider's `menus`) that field is a group beside your `Menu`, its count as `detail`, with no search field, and on a phone too it is your `Menu`, not your `Sheet`. A part column's id is `partKey(columnId, part)`, the key its Filter row has when your panels pass `parts: true`, so that row filters what the column shows; its sort value is `partKey(fieldKey, part)`, which `parsePartKey` turns into a sort's `fieldKey` and `by`. It reads and copies its part, and it edits and pastes as its part, in a box of its own: text for a name's part and a place's region, city and postal code, a number for a range's end, and the select over every country by name, searchable, for a place's country. A paste or a fill into a country cell takes a country's name, in the app's names language (the conventions' `language`), its locale or English, or its code. A part is locked, refused and read-only as its whole is, and it may be emptied unless its whole declares `clearable: false`; emptying the last part is judged by the field. A box refuses a value the whole field would refuse, such as a range's low end above its high end, and stays open with the field's reason. Your `onCellCommit` and `onCellsCommit` receive the whole column's id and the whole value with that part replaced, so a place keeps its other parts, a range its other end and a name its other part. A name's full name follows its given or family name only when it was empty or exactly the two joined by a space; "Nagy Imre" is kept. A place's other country clears its region and its code, and another region clears its code. A paste over two parts of one field in one row lands as one edit of the whole, and a part edit made while the field's earlier ones are still in flight builds on them. Like every composite value's, the commit goes without a pending overlay; the refetch repaints. Escape in a part's box follows the box's own type, text or number, not the field's, so `escape={{ name: "keep" }}` on the provider does not reach a given name's box. A place field limited to some `parts` offers part columns only for those. Its menu offers no Group row. Keep part columns out of your panels: they belong to the grid, and your panels take the columns you declare.
|
|
400
400
|
|
|
401
401
|
`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.
|
|
402
402
|
|
|
403
|
+
`fillWidth` is your app's choice, not a preference `gridProps` carries. On, the columns share the grid's whole width: each grows in proportion to its own width and never gets narrower than it, the header, the rows, the footer and a group's head alike, and while any column grows "+ Add column" stands right after the last one. A table already wider than the grid draws and scrolls sideways as it does without it. A column with a width set, by the person's resize or by the view, keeps it while the others take the rest, and a double-click on its edge clears a width the person set, giving it back its share; a column that declares `grid.maxWidth` keeps its own width. When no column can grow, the space after the last one stays empty, as without the option.
|
|
404
|
+
|
|
403
405
|
## Figures
|
|
404
406
|
|
|
405
407
|
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.
|
|
@@ -468,7 +470,7 @@ function DealsWithDrawer() {
|
|
|
468
470
|
}
|
|
469
471
|
```
|
|
470
472
|
|
|
471
|
-
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.
|
|
473
|
+
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 (a disabled one says why as its `disabledReason`: the column's own reason, nothing to paste, or the paste's refusal), 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.
|
|
472
474
|
|
|
473
475
|
`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.
|
|
474
476
|
|
|
@@ -596,11 +598,15 @@ function PagedDeals({
|
|
|
596
598
|
}
|
|
597
599
|
```
|
|
598
600
|
|
|
601
|
+
### Rows in pages
|
|
602
|
+
|
|
603
|
+
An ungrouped list can show its rows in pages instead: hand the page's rows as the one group and `pages` (`page` from 1, `size`, `total`, `onPage` and `onSize`). Under the rows the grid draws a pager: where you are ("26–50 of 213"), a page-size pick (25, 50 and 100 unless `sizes` names others) and Previous and Next, each your `Button`, the size pick opening your `Menu`. With `@viewkitjs/postgres`, the count is `totalQuery`'s (with a cap, hand `exact: false` and the pager reads "of 1,000+"), the page is `pageQuery({ ..., size, page })`, and the footer's figures are `figuresQuery`'s, handed as the group's `figures`, so the totals cover the whole view on every page. Picks cover the page on screen and clear when the page or its size changes. An app that hands no figures sees an empty footer in pages, apart from its own `renderAggregate` cells. `loadMore` is not drawn in pages, and a grouped grid draws no pager: each group keeps its own "more".
|
|
604
|
+
|
|
599
605
|
`selection` turns on the checkbox rail and a bar of your own over the selected rows ([the selection guide](selection.md)).
|
|
600
606
|
|
|
601
607
|
## Editing and writes
|
|
602
608
|
|
|
603
|
-
**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.
|
|
609
|
+
**Which editor.** A column marked `editable` mounts the editor its type names, as `gridEditorKind` answers; a single email or domain mounts the value list holding one value where the provider's `oneValue` says `list` for its type. 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.
|
|
604
610
|
|
|
605
611
|
**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.
|
|
606
612
|
|
|
@@ -633,6 +639,10 @@ assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
|
|
|
633
639
|
|
|
634
640
|
**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.
|
|
635
641
|
|
|
642
|
+
**With an app's `TextBody`** (the components map), every text that can be written, long text and a cut-off text included, opens the app's body in the cell on a computer and in the sheet on a phone; the keys stay as above. A text opened only to be read still opens the panel.
|
|
643
|
+
|
|
644
|
+
**With an app's `NumberBody`**, a number, money or percent cell opens the app's body in the cell on a computer, lifted as a grown editor is, and in the sheet on a phone; the keys stay as the number editor's own. A duration keeps ViewKit's own box.
|
|
645
|
+
|
|
636
646
|
**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.
|
|
637
647
|
|
|
638
648
|
**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.
|
|
@@ -649,9 +659,9 @@ assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
|
|
|
649
659
|
|
|
650
660
|
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.
|
|
651
661
|
|
|
652
|
-
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 (with the provider's `menus` set to `menu`, the figure picker, a column's menu, a group's ⋯ and Add column are your `Menu`, and their keys are your `Menu`'s). On the `popover` route, past eight sort choices, or at any count once you pass `groupMenu`, a group's menu lists them under a search (on the `menu` route they open beside the menu with no search field), 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.
|
|
662
|
+
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). With `oneHeader`, a group has no column names and no box of its own: ↑ from its first row lands on its bar, and above the first bar is the one row of 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 (with the provider's `menus` set to `menu`, the figure picker, a column's menu, a group's ⋯ and Add column are your `Menu`, and their keys are your `Menu`'s). On the `popover` route, past eight sort choices, or at any count once you pass `groupMenu`, a group's menu lists them under a search (on the `menu` route they open beside the menu with no search field), 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.
|
|
653
663
|
|
|
654
|
-
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.
|
|
664
|
+
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; with `oneHeader` the one row of column names is the first row, counted once), 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.
|
|
655
665
|
|
|
656
666
|
## Known gaps
|
|
657
667
|
|
|
@@ -673,7 +683,7 @@ A surface of your own beside the grid reads values the way the grid does with th
|
|
|
673
683
|
- `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.
|
|
674
684
|
- `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.
|
|
675
685
|
- `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.
|
|
676
|
-
- `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.
|
|
686
|
+
- `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. In the grid that element is also the part `vk-grid-title`, which your app styles at rest and under the pointer (the contract's Slots).
|
|
677
687
|
|
|
678
688
|
```ts
|
|
679
689
|
import {
|
|
@@ -4,20 +4,36 @@ Every view reads what it takes from its app, other than its own props, from one
|
|
|
4
4
|
|
|
5
5
|
## Mount it once
|
|
6
6
|
|
|
7
|
-
`ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`.
|
|
7
|
+
`ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Seventeen more are optional: `atoms`, `messages`, `presentation`, `desktopQuery`, `sheetActions`, `escape`, `oneValue`, `sayRefusals`, `menus`, `gridButtons`, `gridCheckboxes`, `fieldRowButtons`, `fieldRowCheckboxes`, `severalValues`, `bodyFrame`, `selectionBar` and `datePicks`.
|
|
8
8
|
|
|
9
|
-
`desktopQuery` says which screens are desktops: there an editor opens as a popover, and elsewhere as a sheet. It defaults to `DEFAULT_DESKTOP_QUERY`, `(min-width: 1024px)`; hand in the query your own shell switches on, so the editors and your layout change at the same width. A server render counts as a desktop.
|
|
9
|
+
`desktopQuery` says which screens are desktops: there an editor opens as a popover, and elsewhere as a sheet; so do the toolbar's panels and the views picker outside a `Toolbar` (inside one, the toolbar's phone form decides). It defaults to `DEFAULT_DESKTOP_QUERY`, `(min-width: 1024px)`; hand in the query your own shell switches on, so the editors and your layout change at the same width. A server render counts as a desktop.
|
|
10
10
|
|
|
11
|
-
`escape` says what Escape does in an editor, per field type: `{ date: "keep", location: "keep" }` keeps what was typed in a date's and a place's editor and closes it, as a press outside does, and a value
|
|
11
|
+
`escape` says what Escape does in an editor, per field type: `{ date: "keep", location: "keep" }` keeps what was typed in a date's and a place's editor and closes it, as a press outside does, and a value the editor or your app refuses on the spot stays open with its reason, until a second Escape throws the edit away. A refusal your server sends after the save arrives once the editor has closed, as it does after Enter: on the cell in the grid, and under the row in a field row, whose editor, pressed again, opens on the refused value with your server's reason until the value changes. A type you leave out throws the edit away, which is the default for every type. It holds on a desktop: on a phone, every way out of the sheet throws the edit away. Pass a module-level object.
|
|
12
|
+
|
|
13
|
+
`oneValue` says how a field holding one email or one domain is edited: `{ email: "list", domain: "list" }` opens it as the value list holding one value (one line, no label, no main mark, no line to add another, × empties it), in the grid and in a field row alike, where it otherwise opens the text box in its cell. It writes the same string the text box writes, and a key typed on its cell starts its line, as it starts the text box. A type you leave out, or `"text"`, opens the text box; a phone and a link always do. With a `ValuesBody`, the list of one opens it, handed `holds: "one"` and `labels: false`. Pass a module-level object.
|
|
12
14
|
|
|
13
15
|
`sayRefusals`, off by default, has the grid say why your app refused an edit it sent, through your toast's `error`: the error's own words, "Couldn't save Amount." when it has none, and a batch once, with its count. Turn it on and stop toasting your own refusals, or each says twice.
|
|
14
16
|
|
|
15
|
-
`sheetActions` says where an editor's ✕ and
|
|
17
|
+
`sheetActions` says where an editor's ✕ and ✓, and a toolbar panel's ✕, stand in that sheet. `bar`, the default, is the editor panel's own bar inside your `Sheet`. `head` hands them to your `Sheet` as `actions` (`close`, and `done` unless the body saves on its pick), for a sheet that draws them in its own head, and the panel draws no bar; a toolbar panel hands only `close`, and draws no ✕ of its own.
|
|
18
|
+
|
|
19
|
+
`bodyFrame` says who sets the width and padding of the popover around a whole body your app hands, its `Picker`, `PartsBody` or `ValuesBody`. `views`, the default, keeps ViewKit's own, the widths it gives its own lists, whether or not you hand a body. `popover` hands that popover no width and no padding of ViewKit's, only its layer, so your `Popover` stands at its own width, and marks it with the body it holds: `data-vk-body` is `picker`, `parts` or `values`. An editor drawing ViewKit's own body keeps ViewKit's width either way, and a phone's sheet is unchanged. Before you turn it on, give the popover that opens with `chrome: "menu"` a width that doesn't follow its content (or it widens and narrows as a list filters), cap it by the room on screen, and pad it as you want; a body that needs more room, a place's parts on one line, is reached by `[data-vk-body="parts"]`.
|
|
16
20
|
|
|
17
|
-
`selectionBar` says where the selection bar sits: its `bottom`, its `zIndex` and your `className` on the desktop and on the phone, and a `phoneQuery` when your shell switches to its phone layout at another width than `desktopQuery
|
|
21
|
+
`selectionBar` says where the selection bar sits: its `bottom`, its `zIndex` and your `className` on the desktop and on the phone, and a `phoneQuery` when your shell switches to its phone layout at another width than `desktopQuery`, and a `chip`, who draws the count chip that clears the selection: ViewKit (`own`, the default) or your `Button` (`button`). An app with a bottom nav lifts the phone's pill above it; pass a module-level object.
|
|
18
22
|
|
|
19
23
|
`menus` says how the grid opens its own menus. `popover`, the default, draws ViewKit's rows in your `Popover`. `menu` hands them to your `Menu` as rows: today the footer's figure picker, one ticked row per figure, a column's header menu, each format setting and each option's colour a group beside it, a group's ⋯, its sort choices a group beside it with no search field and its figure toggles ticks that keep the menu open, and the grid's own "+ Add column", each field with parts a group beside it, with no search field and on a phone too. The row menu and a command cell's menu always go through your `Menu`.
|
|
20
24
|
|
|
25
|
+
`gridButtons` says who draws the buttons the grid draws itself: a group's fold and ⋯, "+ Add column", a row's ⋯, the name's actions (the pencil and your `rowActions`), an action column's buttons, a pick-list cell's ▾, and a command cell's ▾ and its trigger. `own`, the default, draws ViewKit's own, as on 0.5.0. `button` draws your `Button`, so they take your pointer, hover, press and focus ring: the grid hands its box (size, place, the reveal on hover) in `className`, `variant` `ghost` or `outline`, `size` `icon` or `sm`. Before you set it, make your `Button` forward `ref`, `tabIndex`, `aria-haspopup`, `aria-expanded`, `data-slot` and `data-open` to its element and let the `className` it is handed win over its own size: a `Button` that drops the ref leaves the ⋯'s and "+ Add column"'s menus with nothing to anchor on, and one that drops `tabIndex` makes every grid button a Tab stop. The example adapters on this page forward none of them; they suit the default.
|
|
26
|
+
|
|
27
|
+
`severalValues` says how a cell of several values (a multiselect's options, several emails or records, a lookup's names) draws on one line. `first`, the default, draws its first value and a "+N" count at any width, as on 0.5.0. `fit` draws as many whole values as fit the cell's width, then the count, and follows a column resize; when even the first doesn't fit whole, it shows cut. A wrapped row shows three either way. Each cell measures its values once when it mounts or they change, and a resize is arithmetic over what it kept, so fitting costs no row a redraw.
|
|
28
|
+
|
|
29
|
+
`gridCheckboxes` says who draws a yes/no cell's box in the grid. `own`, the default, draws ViewKit's tick box in its own switch button, as on 0.5.0. `checkbox` draws your `Checkbox`, the box your rail draws, so a row's two boxes are one: it is handed `checked`, the column's name, `tabIndex` -1 and `onCheckedChange`, and a press writes the value once. A cell the grid can't write is handed `readOnly` and a press that writes nothing. Before you set it, make your `Checkbox` forward `readOnly`: one that drops it shows a read-only cell that looks pressable and does nothing when pressed.
|
|
30
|
+
|
|
31
|
+
`fieldRowButtons` says who draws a field row's own buttons: its edit target, the verb trigger around a value, the lane's ▾ and rich text's Show more. `own`, the default, draws ViewKit's own, as on 0.5.0. `button` draws your `Button`, `ghost`, with ViewKit's box in `className` and the row's own type kept. Before you set it, make your `Button` forward the ref and `aria-disabled` (the edit target holds its focus with it while a write is pending), render a real `<button>`, and let the `className` handed win over its own size. `gridButtons` doesn't reach a field row.
|
|
32
|
+
|
|
33
|
+
`fieldRowCheckboxes` says who draws a field row's yes/no box. `own`, the default, draws ViewKit's tick box in its own switch button. `checkbox` draws your `Checkbox`, a Tab stop as the switch is, and a press writes the value once; a row that can't be written is handed `readOnly`. Forward `readOnly` before you set it. The panels' tick rows draw your `TickBox` atom, the picture of your box, whichever you set.
|
|
34
|
+
|
|
35
|
+
`datePicks` names the quick days the date editors offer, in order: any of `today`, `tomorrow`, `next-monday` and `in-a-week`, a week from today. The date editor hands exactly these to your `DateBody` and ViewKit's own panel draws the same, so a cell and your own pages offer the same days. Absent, `today`, `tomorrow` and `next-monday`, as on 0.5.0. Pass a module-level array.
|
|
36
|
+
|
|
21
37
|
Each piece lives in a module of its own, which the sections below write. Here they are declared, so the page compiles without them.
|
|
22
38
|
|
|
23
39
|
```tsx
|
|
@@ -59,7 +75,7 @@ assert.equal(conventions.locale, "en-GB"); // the app's own, untouched
|
|
|
59
75
|
|
|
60
76
|
## The components map
|
|
61
77
|
|
|
62
|
-
The package draws nothing with a UI library of its own. `ViewsComponents`, from `@viewkitjs/views/react`, is the map you hand it: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`, and
|
|
78
|
+
The package draws nothing with a UI library of its own. `ViewsComponents`, from `@viewkitjs/views/react`, is the map you hand it: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`, and nine you may leave out: `Input`, `Command` (the command list's parts), `Picker` (a whole pick list your app draws), `Calendar` (the date editor's month), `DateBody` (a whole date body your app draws), `PartsBody` (a whole body for a name, a place or a range), `ValuesBody` (a whole body for several emails, phones, links or domains), `TextBody` (a whole body for a text typed as one string) and `NumberBody` (a whole body for a number, money or a percent). The [contract](../contract.md#the-components-map) says what each slot must accept; the [`@viewkitjs/views/react` reference](../reference/react.md) lists every prop.
|
|
63
79
|
|
|
64
80
|
The shapes are Base UI's, and the types promise three things:
|
|
65
81
|
|
package/docs/index.md
CHANGED
|
@@ -50,5 +50,5 @@ One page per door. Each lists every name the door exports.
|
|
|
50
50
|
- [`@viewkitjs/views/cells`](reference/cells.md): a column's typed cell
|
|
51
51
|
- [`@viewkitjs/views/selection`](reference/selection.md): a list's selection
|
|
52
52
|
- [`@viewkitjs/views/grid`](reference/grid.md): the grid, its props and the helpers a host shares with it
|
|
53
|
-
|
|
54
|
-
`@viewkitjs/views/panels
|
|
53
|
+
- [`@viewkitjs/views/panels`](reference/panels.md): what a list's panels read and say, built from its settings, and the toolbar's arrangement, with no React
|
|
54
|
+
- [`@viewkitjs/views/panels/react`](reference/panels-react.md): the panels as they draw, the toolbar's frame, its parts and the ready toolbar
|
package/docs/install.md
CHANGED
|
@@ -7,9 +7,8 @@
|
|
|
7
7
|
```
|
|
8
8
|
|
|
9
9
|
`react` and `react-dom` 19 are peers you already have. `@dnd-kit/core`, `@dnd-kit/sortable` and
|
|
10
|
-
`@dnd-kit/utilities` are optional peers for the panels' door
|
|
11
|
-
|
|
12
|
-
Node 20 or later.
|
|
10
|
+
`@dnd-kit/utilities` are optional peers for the drawn panels' door (`@viewkitjs/views/panels/react`): install
|
|
11
|
+
them only if you import it. ESM only, Node 20 or later.
|
|
13
12
|
|
|
14
13
|
2. **Let Tailwind see it.** The rendering carries Tailwind classes drawn from your own tokens. Add one
|
|
15
14
|
line to the stylesheet that imports Tailwind:
|
package/docs/reference/cells.md
CHANGED
|
@@ -12,7 +12,7 @@ Guide: [cells](../guides/cells.md).
|
|
|
12
12
|
- The formatting: `presentation` and `viewer`.
|
|
13
13
|
- The reader's overrides: `optionColors`, `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay` and `wrap` (text wraps instead of truncating).
|
|
14
14
|
- The row's answers: `currency` (the code a value is in when the caller knows it and the column does not), `valueOverride` (a pending value, which wins over the accessor; only typed cells honour it) and `markerReason`.
|
|
15
|
-
- The verbs: `onResolve` (clears a marker), `onToggle` (flips a checkbox or icon boolean; its presence makes it clickable), `commandItems` (a command column's verbs for this row; without them the cell is a read-only badge) and `onOpenRelation` (opens the record a chip points at, handed the clicked value, for a list whose relations go somewhere your app-wide answer cannot know).
|
|
15
|
+
- The verbs: `onResolve` (clears a marker), `onToggle` (flips a checkbox or icon boolean; its presence makes it clickable), `booleanCheckbox` (a checkbox control the checkbox style draws in place of the tick box and its switch; the grid hands the components map's `Checkbox` while the provider's `gridCheckboxes` is `checkbox`, and a field row while `fieldRowCheckboxes` is), `commandItems` (a command column's verbs for this row; without them the cell is a read-only badge) and `onOpenRelation` (opens the record a chip points at, handed the clicked value, for a list whose relations go somewhere your app-wide answer cannot know).
|
|
16
16
|
- The host's: `entityIcon` (your glyph for an entity kind) and `slotOwnsClick` (a host whose own element is the button: every cell draws bare content) and `hostOwnsPlainClick` (a host whose plain click on a value is its own: links stay links, marked `data-cell-link`, and let the click through).
|
|
17
17
|
|
|
18
18
|
## Column-shaped text
|
|
@@ -13,11 +13,12 @@ Guide: [display](../guides/display.md).
|
|
|
13
13
|
- The formatting: `presentation` and `viewer`, which win over the provider's.
|
|
14
14
|
- The reader's overrides: `dateStyle`, `durationStyle`, `decimals`, `withTime` (wins over the field's `withTime`), `percentDisplay` (wins over the field's `format.display`), and `wrap` (`true` clamps text to three lines, `"full"` shows it whole; see `cellTextClass`).
|
|
15
15
|
- The row's answers: `currency` (the code this value is in), `nameFallback` (the words for an empty name), `optionColors` (a reader's colour per option) and `labelFallback` (a label for a select value no option names; without it the value draws as the muted unknown chip).
|
|
16
|
-
- A boolean's: `booleanIcon` (the two-state glyph), `marker`, `markerReason` and `onResolve` (the marker style's words, reason and clearing verb), `onToggle` (its presence makes a checkbox or icon boolean clickable; without it the glyph is plain)
|
|
16
|
+
- A boolean's: `booleanIcon` (the two-state glyph), `marker`, `markerReason` and `onResolve` (the marker style's words, reason and clearing verb), `onToggle` (its presence makes a checkbox or icon boolean clickable; without it the glyph is plain), `booleanDisabled` (keeps the control's shape, disabled) and `booleanCheckbox` (a checkbox control, `ViewsCheckboxProps`, the checkbox style draws alone in place of the tick box and its switch: handed `checked`, the field's label, `tabIndex` -1 and `onCheckedChange`, or `readOnly` without `onToggle`).
|
|
17
17
|
- A relation's: `entityIcon` (your glyph for an entity kind) and `relationWrap` (where a chip goes; absent, the chip is inert).
|
|
18
18
|
- The host's slot: `slotOwnsClick`, set by a host whose own element is the button, such as a calendar card. Every core then draws bare content: an overflow count as plain text, a boolean with no toggle. `hostOwnsPlainClick`, set by a host whose plain click on a value is its own, such as the grid: an email, phone, url or domain stays a link, marked `data-cell-link`, not draggable, and lets its click through for the host to decide.
|
|
19
|
-
- `RelationWrap` — the type of `relationWrap`: `(relation, chip) => ReactNode`. The core draws the chip (its
|
|
19
|
+
- `RelationWrap` — the type of `relationWrap`: `(relation, chip) => ReactNode`. The core draws the chip (its picture or glyph, through your `Avatar` atom, and its label); your function wraps it in your own link or button, since where a record opens is your app's.
|
|
20
20
|
- `MultiValueCell` — the layout for a value that holds several: several emails, phones, links or domains, a multiselect, the far side of a relation. It takes `items` (one drawn node per value), and optionally `details` (a word beside each value in the list, never in the cell), `wrap`, `title` (the native hover text) and `slotOwnsClick`. It shows one value, or three when wrapped, then a `+N` count that opens every value in a read-only list in the components map's `Popover`, drawn with the `List` and `Row` atoms. With `slotOwnsClick` the count is plain text and nothing opens. No items draws nothing.
|
|
21
|
+
With the provider's `severalValues: "fit"`, on one line it shows as many whole values as fit its width instead (at most 20 are measured), then the count, following its width; the first shows cut when even it doesn't fit. The count is drawn by the `CellMore` atom inside `data-slot="vk-cell-more"`, with `data-open` while the list is open.
|
|
21
22
|
- `ConvertedFigure` — a money figure shown in another currency than its record's own, marked: ≈ before its `children`, and a title naming the currency it came `from` ("Converted from USD", the `views.display.converted-from` message). `renderTypedCellValue` draws it around a converted cell, and a field row around a figure its host reads in another currency; an app draws it on a surface of its own.
|
|
22
23
|
- `ConversionLine` — the line under a money editor opened from a converted figure: the marked `figure`, then "as shown" (`views.display.as-shown`), so the record's own amount being edited and the figure the person clicked read as one value. An optional `className` spaces it.
|
|
23
24
|
|
|
@@ -31,8 +32,8 @@ Guide: [display](../guides/display.md).
|
|
|
31
32
|
|
|
32
33
|
## The viewer and the presentation
|
|
33
34
|
|
|
34
|
-
- `FieldViewerContext` — who is reading: `locale`, `now`, and optionally `timeZone`, `region` (a phone of that country is written as at home), `fieldMessages` (fields' words, fields' English by default) and `messages` (the package's words, its English by default).
|
|
35
|
-
- `viewerFrom` — builds a `FieldViewerContext` from your conventions: their locale, zone, region and messages, with the package's words (`resolveViewsMessage` unless you pass a resolver) and `now` (the current moment unless you pass one).
|
|
35
|
+
- `FieldViewerContext` — who is reading: `locale`, `now`, and optionally `language` (the names language a place's country is written in; `locale` when absent), `timeZone`, `region` (a phone of that country is written as at home), `fieldMessages` (fields' words, fields' English by default) and `messages` (the package's words, its English by default).
|
|
36
|
+
- `viewerFrom` — builds a `FieldViewerContext` from your conventions: their locale, names language, zone, region and messages, with the package's words (`resolveViewsMessage` unless you pass a resolver) and `now` (the current moment unless you pass one).
|
|
36
37
|
- `FieldPresentation` — every formatter a value is printed through, so your app can replace how numbers, durations and dates read: `message`, `number`, `duration`, `calendarDay`, `instant`, `relativeCalendarDay` and `relativeInstant`, each handed the viewer. The provider's `presentation` option returns one, given the defaults.
|
|
37
38
|
- `DEFAULT_FIELD_PRESENTATION` — the package's own `FieldPresentation`. Numbers print through `Intl.NumberFormat` in the viewer's locale; a percent, stored as 0 to 100, prints as it is with `%`; a currency defaults to `EUR` with two decimals. Days print `short` ("27 Sep", the year added when it is not the current one), `long` ("27 September 2026") or `numeric` ("27/09/2026"), a time ("14:05") after a comma, in the viewer's zone. Relative styles say "just now", "5m ago", "in 1d", and "today", "yesterday" or "tomorrow" for a day. Month names and relative words come from the viewer's messages.
|
|
38
39
|
|
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/location` in a client component: the door opens with the client directive. It holds the editor of a `location` field: the country first, then that country's own parts in its own order and with its own words (one country's postal code, county and city on one line, another's city first), the parts the country asks for marked as required and never refused. It owns the boxes, the country list, the region list and what a close means; its host owns the popover, the anchor and the write. It commits a `LocationValue` of `@viewkitjs/fields` holding the field's parts, or null. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `LocationEditor` — the place editor; its ref is a `LocationEditorHandle`. It takes `field` (the location field, whose `parts` limit what it edits), `initial` (the stored place, or null) and `onRequestClose`, and optionally `allowEmpty
|
|
5
|
+
- `LocationEditor` — the place editor; its ref is a `LocationEditorHandle`. It takes `field` (the location field, whose `parts` limit what it edits), `initial` (the stored place, or null) and `onRequestClose`, and optionally `allowEmpty`, `conventions` (whose names language, `language`, names the countries and regions and picks each country's format; default: the provider's) and `label` (the field's name, for your `PartsBody`; default the field's label).
|
|
6
6
|
- Country: a field that takes the country opens on a searchable country list when its place has none (matched by name, marks ignored, or by code); once picked, the country is a button that opens the list again. Picking another country clears the region and its code.
|
|
7
7
|
- Region: where the country has a region list, the region is picked from it, storing the region's name and its ISO 3166-2 code; the list loads when the editor lands on that country. A typed region has no code.
|
|
8
8
|
- Parts: a field limited to some parts edits only those, and a part it names that the country's format has no place for comes after the country's lines, as does a part a stored place holds that its country has no place for.
|
|
9
9
|
- Keys: Tab walks the controls; Escape in a list goes back to the boxes, keeping what was typed, and only the first country list, with nothing behind it, closes the editor. A list with boxes behind it carries the panel's `EDITOR_INNER_ESCAPE` mark, so an `EditorPanel` popover leaves that Escape to the list.
|
|
10
|
+
|
|
11
|
+
Handed `PartsBody` in the components map, the editor opens it in place of its boxes and lists, as `kind: "place"`: it hands the body the place's parts, the boxes the field takes and their rows in the country's own order, each box's words, the parts the country asks for, every country where the field takes one, the country's regions once loaded, and `opens: "countries"` where the place has no country yet. It keeps the region's code (read from the region, cleared with a new country), the draft, Escape, Tab and the close.
|
|
10
12
|
- `LocationEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. Each of the field's parts is trimmed, an empty one null; the same stored value as `initial` is a `noop`; every part empty commits null with `allowEmpty` and cancels without it; anything else commits.
|
|
@@ -2,5 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/name` in a client component: the door opens with the client directive. It holds the editor of a `name` field: three text boxes, given, family and full. Once a part is edited, the full box follows the parts ("given family") while nobody has typed in it, and stops once someone does; a stored full name the parts would not give is the person's own and is left as it is, and an editor closed untouched writes nothing. Tab walks the three boxes, and a blur that lands on another box is not a close. It owns the boxes and what a close means; its host owns where it mounts, the write, and keeping each part in its own column. It commits a `NameValue` of `@viewkitjs/fields`, `{ full, given, family }`, or null. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `NameEditor` — the three boxes, the given box focused without scrolling; its ref is a `NameEditorHandle`. It takes `initial` (the stored name, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the given box), `allowEmpty` and `
|
|
5
|
+
- `NameEditor` — the three boxes, the given box focused without scrolling; its ref is a `NameEditorHandle`. It takes `initial` (the stored name, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the given box), `allowEmpty`, `conventions` and `label` (the field's name, for your `PartsBody`; default "Full name").
|
|
6
|
+
|
|
7
|
+
Handed `PartsBody` in the components map, the editor opens it in place of its three boxes, as `kind: "name"`: it hands the body `{ given, family, full }`, `full` as the rule above shows it, and keeps the rule itself (a full name typed in the body is its own; a changed part, while the full name isn't its own, makes it follow), the draft, Escape, Tab and the close.
|
|
6
8
|
- `NameEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. The name is tidied as fields tidies one; the same name as `initial` is a `noop`; three empty boxes commit null with `allowEmpty` and cancel without it; anything else commits.
|
|
@@ -7,5 +7,6 @@ Import from `@viewkitjs/views/editors/number` in a client component: the door op
|
|
|
7
7
|
- Unit: `unit`, the row's currency, drawn as a chip; `unitOptions`, which make the chip a picker; `unitLeft`, the chip before the figure; `code`, a fixed currency's code (`numberEditCode`), drawn beside the amount as a unit is and never part of the commit, ignored when `unit` is given.
|
|
8
8
|
- Duration: `durationUnit`, the unit a duration is stored in. The input then opens as written text (`1m 30s`), reads units, compounds or a bare number of seconds, and commits in that unit.
|
|
9
9
|
- Layout: `align`, `end` (the default, a right-aligned column) or `start` (a row read left to right, with the chip following the figure).
|
|
10
|
+
- An app's number body: `type` (`number`, `percent` or `currency`; default `number`), `label`, `min`, `max`, `check` (the host's reading of a value and its unit, asked with the value rounded to `decimals`), `escapeKeeps` (the session keeps on Escape), `closeOnBlur` (default true: in place, a focus leaving the body closes it, and a Tab between its controls never reaches the grid; a sheet passes false) and `form` (`phone` in a sheet). Handed `NumberBody` in the components map, the editor opens it in place of its own box (a duration excepted), hands it the draft and the field's settings, and keeps the draft, the rounding, Escape's rule, Tab, ⌘ or Ctrl Enter, the close and the save; the body's `NaN` (text that reads as no number) closes as a cancel.
|
|
10
11
|
- `NumberEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. A blank input cancels, or with `allowEmpty` commits a null value (`noop` when it was already empty and the unit is unchanged). Text that is not a number cancels, never clears. The same number at the editor's decimals with the same unit is a `noop`; anything else commits.
|
|
11
12
|
- `NumberEditValue` — what a number commits: `{ value, unit }`, the value a number or null and the unit the chip shows (the `NumberCommit` of `@viewkitjs/fields`). The host maps it onto its row, such as a unit onto a currency column.
|
|
@@ -2,5 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/range` in a client component: the door opens with the client directive. It holds the editor of a `range` field: two number boxes, low and high, inline like the number editor. Tab moves from low to high inside the editor, and a blur that lands on the other box is not a close. An empty box is an open end. It owns the two boxes and what a close means; its host owns where it mounts, the write, and keeping the pair in its own columns. It commits a `RangeValue` of `@viewkitjs/fields`, `{ low, high }`, each a number or null. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`), `conventions` (how a number is written; default: the provider's), `bands` (the field's `presets`, listed under the boxes; a click writes the band's ends into the boxes and closes as `pick`, so it is read and judged as typed ends are), `bandsAt` (`popover` by default, a small menu under the boxes; `below`, in the editor's own column, for an editor already in a sheet or a panel), `refusal` (your reason for refusing the range: with bands listed the editor draws it between the boxes and the bands, atop the menu or above the list, so you draw none and tell your `EditorPanel` with `editorDrawsRefusal`; without bands it draws nothing and you draw it as for any type-in)
|
|
5
|
+
- `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`), `conventions` (how a number is written; default: the provider's), `bands` (the field's `presets`, listed under the boxes; a click writes the band's ends into the boxes and closes as `pick`, so it is read and judged as typed ends are), `bandsAt` (`popover` by default, a small menu under the boxes; `below`, in the editor's own column, for an editor already in a sheet or a panel), `refusal` (your reason for refusing the range: with bands listed the editor draws it between the boxes and the bands, atop the menu or above the list, so you draw none and tell your `EditorPanel` with `editorDrawsRefusal`; without bands it draws nothing and you draw it as for any type-in), `boxClassName` (classes for the box holding the two inputs, such as a sheet's field) and `label` (the field's name, for your `PartsBody`; default the two ends' words).
|
|
6
|
+
|
|
7
|
+
Handed `PartsBody` in the components map, the editor opens it in place of its boxes and bands, as `kind: "range"`: it hands the body the two ends, `decimals`, the `suffix` as `unit`, and the `bands` for the body to draw as picks (a band picked closes as `pick`). It keeps the draft, rounds the ends to `decimals` as it closes, and draws no refusal of its own: your panel draws it. Escape, Tab and the close are as above.
|
|
6
8
|
- `RangeEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels, and so does a box holding text that is not a number. Both ends unchanged as the boxes showed them is a `noop`, so a stored 2.555 that opened as 2.56 writes nothing. Two empty boxes cancel, or commit with `allowEmpty`. A low end above the high end commits as typed, for the host's acceptance to refuse in its own words.
|
|
@@ -6,6 +6,7 @@ Import from `@viewkitjs/views/editors/session` in a client component: the door o
|
|
|
6
6
|
- Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns an `EditSessionAttempt`. A refusal keeps the session open for another try, and its `reason` comes back as `refusal` until the next attempt; an acceptance closes it and calls `onClose` after the exit gap, a timer cleared if the host unmounts. While `onAttempt` runs the session counts as answered, so a close that arrives during it (a write that moves the focus, and a box that closes on blur) is ignored; a refusal, or an `onAttempt` that throws, opens it again for the next try.
|
|
7
7
|
- Deferred: the session closes at once and hands the answer to `onDone` after the exit gap, for a host whose answer still carries the write.
|
|
8
8
|
- Gap: `exitMs` sets it, defaulting to `EDITOR_EXIT_MS`.
|
|
9
|
+
- Leaving: `leave` (`"outside"` or `"discard"`, read once when the session opens; default `"discard"`) says what happens to a session still open when its page goes (`pagehide`: a reload, a closed tab, a removed frame, Back to another document), or when the grid or field row around it goes. `"outside"` asks the editor as for a press outside, so its draft is written by its own rule and a refusal writes nothing; `"discard"` asks nothing, which keeps a host of your own as it was. Pass `"outside"` to have its open editor asked; the grid and the field row pass it on a desktop and `"discard"` in a phone's sheet. Either way an answer already given and waiting out its exit is finished at once, inside the event, and the admitted mode's `onLeave` is called first. A session closed by Escape is never asked again. One `pagehide` listener per session, for its life; a page that comes back from the back-forward cache finds the session closed and its value written.
|
|
9
10
|
- `EditSession` — what the session hands its host, and what `EditorPanel` (`@viewkitjs/views/editors/panel`) takes: `open`, `close(reason)`, and `refusal`, the reason the host gave for the last refused attempt until the next one, `null` otherwise and always in the deferred mode; and `keeps`, optional, true when this session's Escape keeps (an editor that checks its draft before a key closes it, the value list, checks it before Escape too).
|
|
10
11
|
- `useEscapeRule(type)` — the provider's `escape` for a field type (`ViewsProvider`, `@viewkitjs/views/react`): `"keep"` where it names the type keep, else `"cancel"`, and `"cancel"` with no provider. A host of your own reads it and hands it to its session as `escape`.
|
|
11
12
|
- `EditSessionAttempt` — the host's answer to an attempt: `{ accepted: boolean; reason?: string }`. A refusal may say why; the reason is what `refusal` shows.
|