@viewkitjs/views 0.4.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 +768 -0
- package/README.md +5 -3
- 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 +3 -0
- package/dist/atoms/DrillRows.js +27 -0
- package/dist/atoms/Loading.d.ts +6 -0
- package/dist/atoms/Loading.js +4 -1
- package/dist/atoms/PanelRows.d.ts +5 -0
- package/dist/atoms/PanelRows.js +38 -0
- package/dist/atoms/PanelSearch.d.ts +2 -0
- package/dist/atoms/PanelSearch.js +21 -0
- 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.d.ts +3 -0
- package/dist/atoms/SelectionSheet.js +31 -0
- package/dist/atoms/ToolbarButton.d.ts +2 -0
- package/dist/atoms/ToolbarButton.js +18 -0
- package/dist/atoms/defaults.js +22 -0
- package/dist/atoms/types.d.ts +257 -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 +515 -18
- package/dist/contract.js +660 -5
- 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/figures.d.ts +5 -48
- package/dist/figures.js +1 -63
- 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 +7 -4
- package/dist/grid/chrome/GridColumnMenu.js +5 -3
- package/dist/grid/chrome/GridColumnSortSection.d.ts +23 -3
- 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 +7 -3
- 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 +20 -21
- package/dist/grid/useGridTablePrefs.js +6 -58
- package/dist/grid/useGridTableSettings.d.ts +60 -0
- package/dist/grid/useGridTableSettings.js +61 -0
- package/dist/grouping/sort-groups.d.ts +6 -7
- package/dist/internal/count.d.ts +3 -0
- package/dist/internal/count.js +3 -0
- package/dist/model/aggregates.d.ts +3 -3
- package/dist/model/aggregates.js +17 -71
- 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-order.d.ts +2 -2
- package/dist/model/column-schema.d.ts +6 -7
- package/dist/model/column-sort.d.ts +11 -0
- package/dist/model/column-sort.js +14 -0
- package/dist/model/column-state.d.ts +3 -20
- package/dist/model/column-state.js +1 -4
- package/dist/model/column-types.d.ts +1 -15
- package/dist/model/column-types.js +1 -1
- package/dist/model/one-value.d.ts +6 -0
- package/dist/model/one-value.js +5 -0
- package/dist/model/part-columns.d.ts +1 -6
- package/dist/model/part-columns.js +1 -1
- package/dist/model/part-rows.d.ts +2 -9
- package/dist/model/part-rows.js +1 -10
- 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/preferences.d.ts +3 -23
- package/dist/model/preferences.js +1 -17
- package/dist/model/prefs-buckets.d.ts +0 -27
- package/dist/model/prefs-buckets.js +1 -1
- package/dist/model/relation-filters.d.ts +13 -3
- package/dist/model/relation-filters.js +9 -4
- package/dist/model/row-icon.d.ts +17 -11
- 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.d.ts +32 -6
- package/dist/model/view-rules.js +99 -23
- 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 +50 -6
- package/dist/provider/ViewsProvider.js +33 -2
- package/dist/provider/components.d.ts +274 -11
- package/dist/provider/context.d.ts +23 -2
- package/dist/provider/desktop.d.ts +3 -0
- package/dist/provider/desktop.js +7 -4
- package/dist/react.d.ts +5 -2
- package/dist/selection/SelectionBar.d.ts +18 -0
- package/dist/selection/SelectionBar.js +98 -0
- package/dist/selection/SelectionBarPhone.d.ts +3 -0
- package/dist/selection/SelectionBarPhone.js +14 -0
- package/dist/selection/bar-overflow.d.ts +12 -0
- package/dist/selection/bar-overflow.js +55 -0
- package/dist/selection/bar-parts.d.ts +17 -0
- package/dist/selection/bar-parts.js +19 -0
- package/dist/selection/index.d.ts +2 -0
- package/dist/selection/index.js +1 -0
- package/dist/selection/types.d.ts +3 -2
- package/dist/selection/useListSelectionShortcuts.d.ts +3 -2
- package/dist/selection/useListSelectionShortcuts.js +1 -1
- package/dist/selection/verbs.d.ts +41 -0
- package/dist/selection/verbs.js +1 -0
- package/docs/contract.md +355 -35
- package/docs/getting-started.md +1 -1
- package/docs/guides/atoms.md +39 -6
- 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 +35 -21
- package/docs/guides/the-grid.md +24 -13
- package/docs/guides/the-provider.md +24 -6
- package/docs/index.md +2 -0
- package/docs/install.md +3 -1
- 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 +10 -7
- package/docs/reference/panels-react.md +101 -0
- package/docs/reference/panels.md +123 -0
- package/docs/reference/react.md +45 -12
- package/docs/reference/selection.md +11 -3
- package/docs/reference/views.md +41 -38
- package/package.json +33 -4
- package/skills/views/SKILL.md +5 -4
|
@@ -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.
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/text` in a client component: the door opens with the client directive. It holds the one editor for every text-like value: `text`, `url`, `domain`, `email`, `phone` and `rich_text`, a line or a paragraph. It tidies what was typed (trimmed; rich text tidied only at its edges, with fields' `normalizeMarkdown`, so its first line keeps its indent), and an unchanged value closes as no save. It owns the box and what a close means; its host owns where it opens (in place, a popover, a sheet), the session and the write. It commits a string. Guide: [editors](../guides/editors.md#a-text-box).
|
|
4
4
|
|
|
5
|
-
- `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`.
|
|
6
|
-
- `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`,
|
|
5
|
+
- `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`. Handed the components map's `TextBody`, the editor opens it in place of its own box, in a frame carrying `data-slot="vk-text-body"`: it hands the body the draft and the field's settings (`ViewsTextBodyProps`), and keeps the draft, Escape's rule, Tab, ⌘ or Ctrl Enter (closes as `"enter"`), in place a press outside (`"blur"`), the close's tidy (a line's line breaks become a space; a phone that reads as the stored number is a `noop`) and the save.
|
|
6
|
+
- `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`, `boxData` (`data-*` attributes set on the box, over its own slot), and for a `TextBody`: `check` (the host's reading of a value, handed to the body), `region` (a phone's country, handed to the body and read by its close), `escapeKeeps` (the session keeps on Escape: the frame carries `EDITOR_INNER_ESCAPE`) and `form` (`phone` in a sheet, default `computer`).
|
|
7
7
|
- `TextEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Read-only answers `noop`; Escape cancels; otherwise the tidied draft against the tidied `initial`: equal is a `noop`, different a `commit` of the tidied draft.
|
|
8
8
|
- `TextEditorType` — the types it edits: `text`, `url`, `domain`, `email`, `phone`, `rich_text`.
|
|
9
9
|
- `TEXT_INPUT_TYPE` — the native input type per `TextEditorType`, the phone keyboard each brings: `text` and `rich_text` `text`, `url` and `domain` `url`, `email` `email`, `phone` `tel`.
|
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/value-list` in a client component: the door opens with the client directive. It holds the editor of a field holding several values of one kind (a `multiple` email, phone, url or domain field), each with its label and one of them the main one. It is a draft, like the chips editor: the whole list commits once when the host closes it. It owns the rows, the reading of each value and what a close means; its host owns the popover, the anchor and the write. It commits a list of `ValueItem`s of `@viewkitjs/fields`, `{ value, label, main }`, the main one first, or null. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal; so does Escape with `escapeKeeps` (a host whose session keeps, `EditSession.keeps`), which also marks the list's box `EDITOR_INNER_ESCAPE`, so a popover leaves that Escape to the rows. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
|
|
5
|
+
- `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal; so does Escape with `escapeKeeps` (a host whose session keeps, `EditSession.keeps`), which also marks the list's box `EDITOR_INNER_ESCAPE`, so a popover leaves that Escape to the rows. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false), `label` (the field's name for an app's `ValuesBody`; default `field.label`), `holds` (`"one"`: one line with no main mark, no label box and no Add row, × empties the line and it stays; default `"several"`) and `seed` (what was typed on what opened it: the first row's text starts as it). Handed `ValuesBody` (the components map), the editor opens it in place of its own rows, handing it the draft as lines, the field's type, its check, `labels`, `holds`, a phone's `region`, `typed` and `form`, and keeps the draft, which value is kept as stored, Escape, Tab and the close; with a body it draws no row, no reason and no open action of its own.
|
|
6
6
|
- `ValueListEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels; any other close keeps what was built. Blank rows are dropped. A row left untouched keeps its stored value exactly as stored, and a row typed in commits its trimmed text for the field's commit to read. With no main mark the first row is the main one. The same values, labels and main as opened is a `noop`; an empty list commits null with `allowEmpty` and cancels without it.
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/field-row` in a client component, under your `ViewsProvider`: the door opens with the client directive. It holds a record's field row: one field drawn as its label, its value and, on a click, its type's editor in place, and the write path that admits each edit at once, queues one record's writes, settles each on the save's receipt and rolls a failure back. The row knows no entity, only a binding, a value and a commit, so your app builds its record's panel (its sections, its related records) around the rows. It draws with your provider's `Popover`, `Sheet`, `Collapse`, `AppIcon`, icons, `CommandMenu` atom and toast port. The shapes its writes go through (the write target, the receipt, the admission, a value's note, the reconciliation error) are the root door's, described under [A write's target](views.md#a-writes-target), and this door re-exports them. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape throws the edit away, unless the provider's `escape` keeps the field's type, on a desktop, where it keeps what was typed and a refusal stays open until a second Escape throws the edit away; a sheet's swipe or ✕ changes nothing. On a desktop, a short select opened by Enter or Space on the row puts the focus on the value it holds, so the arrows walk it and Enter picks; opened by a pointer, it moves no focus. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once its exit has played out and a write still saving has saved, so the next Tab moves on from that row; a press or a focus outside an editor's panel since the close lets that go, so a row opened meanwhile keeps its editor, and an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
|
|
6
|
-
- `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
|
|
5
|
+
- `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width, except that with a `PartsBody` handed a name and a range open anchored under the value, as a place does, and that a single email or domain opens the value list holding one value, anchored, where the provider's `oneValue` says `list` for its type. Escape throws the edit away, unless the provider's `escape` keeps the field's type, on a desktop, where it keeps what was typed and a refusal stays open until a second Escape throws the edit away; a sheet's swipe or ✕ changes nothing. On a desktop, a short select opened by Enter or Space on the row puts the focus on the value it holds, so the arrows walk it and Enter picks; opened by a pointer, it moves no focus. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once its exit has played out and a write still saving has saved, so the next Tab moves on from that row; a press or a focus outside an editor's panel since the close lets that go, so a row opened meanwhile keeps its editor, and an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry. A text, an email, a phone, a link, a domain, long or rich text edits in place in the row; handed the components map's `TextBody`, the row opens it there, at every width, with the field's own check and the record's country. A number, money or a percent edits in place too; handed `NumberBody`, the row opens it there, at every width, with the field's own check and its limits (a duration keeps the editor's own box).
|
|
6
|
+
- `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles; an editor still open when the page or the row goes is asked as for a press outside, so it can be called inside `pagehide`), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
|
|
7
7
|
- `RowEditor` — the editor a row mounts for its field's type, picked from `ROW_HOSTS`.
|
|
8
8
|
- `ROW_HOSTS` — the host each field type mounts in a row, or `null` for a type the row never opens (a boolean, a derived or system field).
|
|
9
9
|
- `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message`, `kindIcon` and `openedByKey` (true when a key, Enter or Space, pressed the row's button rather than a pointer).
|
package/docs/reference/grid.md
CHANGED
|
@@ -1,29 +1,32 @@
|
|
|
1
1
|
# `@viewkitjs/views/grid`
|
|
2
2
|
|
|
3
|
-
The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The
|
|
3
|
+
The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. The bar a selection opens is `SelectionBar` from `@viewkitjs/views/selection`, which your `selection`'s `renderBar` draws with your verbs. Guide: [the grid](../guides/the-grid.md).
|
|
4
4
|
|
|
5
5
|
## The grid
|
|
6
6
|
|
|
7
7
|
- `GridTable` — draws the spreadsheet: rows in their groups under a header whose column menus sort, group, format and hide, a checkbox rail and a ⋯ tail on each row, editors opened over cells, a selected range with copy, paste and undo, and a footer of figures per column. An edit shows in its cell at once and goes to `onCellCommit` (a batch to `onCellsCommit`); a failed write rolls the cell back. While `transitionPending` is true, or for one commit after `transitionKey` changes, it draws your app's loading atom instead of the rows. It takes a `GridTableProps`.
|
|
8
8
|
- `GridTableProps` — what `GridTable` takes, flat, typed over your row. Five are required: `groups` (the rows, as the model's `ListGroup`s), `grouped` (whether they draw as group bands), `getRowId`, `columns` (the model's `ListColumn`s) and `onOpenRow` (what opening a row does: the title's text opens it; it receives the row and a `GridRowOpenedFrom`, which brings the focus back to the row's cell once what it opened closes). The rest are optional:
|
|
9
|
-
- Rows and groups: `rowHref`, `onPrefetchRow` (warm a row's detail on a pointer's intent), `rowClassName`, `rowIcon` and `showRowIcon` (the title cell's glyph, as a descriptor the grid sizes and colours), `onOpenRelation` and `entityIcon` (opening the record a relation cell points at, and the glyph for a kind; without `onOpenRelation`, relation cells are inert), `isCollapsed` and `onToggleGroup` (your group collapse), `renderGroupLabel`, `renderGroupFooter` (a group's paged continuation after its loaded rows), `onHideGroup`, `countOf`, `loadMore` (`hasMore`, `onReveal` and a `label`), `emptyState`, and `transitionKey`, `transitionPending` and `transitionLabel` (a view change: the wait paints before the new rows mount).
|
|
10
|
-
- Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; the bar it opens is
|
|
11
|
-
- Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupMenu` (the parts a group band's ⋯ holds, as `GridGroupMenuPart`s: `"sort"`, `"figures"`, `"hide"`; with it the sort list always searches through your `Command` on the `popover` route), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
|
|
9
|
+
- Rows and groups: `rowHref`, `onPrefetchRow` (warm a row's detail on a pointer's intent), `rowClassName`, `rowIcon` and `showRowIcon` (the title cell's glyph, as a descriptor the grid sizes and colours, or the row's picture through your `Avatar` atom when the descriptor hands an `avatar`), `onOpenRelation` and `entityIcon` (opening the record a relation cell points at, and the glyph for a kind; without `onOpenRelation`, relation cells are inert), `isCollapsed` and `onToggleGroup` (your group collapse), `oneHeader` (a grouped grid draws one row of column names, pinned at the top over every group, in place of each group's own; each group's bar pins under it, and the row's checkbox picks every row; off by default, when each group draws its own with the box that picks its rows), `renderGroupLabel`, `renderGroupFooter` (a group's paged continuation after its loaded rows), `onHideGroup`, `countOf`, `loadMore` (`hasMore`, `onReveal` and a `label`), `pages` (`GridPages`: `page` from 1, `size`, `total`, the view's count, `exact`, false for a capped count, `sizes`, the page-size pick's choices, default 25, 50 and 100, and `onPage` and `onSize`: an ungrouped grid draws the page you hand and the pager part `vk-grid-pager` under it, `loadMore` is then not drawn, picks clear on a page or size change, and the footer shows only the figures a group carries in `figures`; a grouped grid draws no pager; absent by default), `emptyState`, and `transitionKey`, `transitionPending` and `transitionLabel` (a view change: the wait paints before the new rows mount).
|
|
10
|
+
- Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; its optional `renderBar` draws the bar it opens, `SelectionBar` with your verbs, and without one the rows still tick and no bar is drawn).
|
|
11
|
+
- Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupMenu` (the parts a group band's ⋯ holds, as `GridGroupMenuPart`s: `"select"` (Select all in group, on a grid with a `selection`), `"sort"`, `"figures"`, `"hide"`; with it the sort list always searches through your `Command` on the `popover` route), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
|
|
12
12
|
- Format overrides and their handlers, every map keyed by field key: `optionColors`, `dateStyles`, `durationStyles`, `numberFormats` (decimals null is the field's own), `showTimeOverrides` and `percentDisplays`, each with its `on…Change` handler taking the field key first, and `formatsWritable` (false hides the stored format knobs from the column menu; default true).
|
|
13
|
-
- Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, or answering `undefined`, `false` or `""`, the grid's own lists the hidden columns; answering `null`, none is drawn and no room is kept for it), `addColumnOnPhone` ("+ Add column" on a phone too, its list in your `Sheet`, or your `Menu` on the `menu` route; off by default), `parts` (a column per part of a name, a place or a range, offered under its field in "+ Add column"; off by default), `renderColumnMenuRows` (your rows in a column's menu, above Hide), `columnMenuItems` (the same rows as data, on the `menu` route), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale
|
|
13
|
+
- Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, or answering `undefined`, `false` or `""`, the grid's own lists the hidden columns; answering `null`, none is drawn and no room is kept for it), `addColumnOnPhone` ("+ Add column" on a phone too, its list in your `Sheet`, or your `Menu` on the `menu` route; off by default), `parts` (a column per part of a name, a place or a range, offered under its field in "+ Add column"; off by default), `renderColumnMenuRows` (your rows in a column's menu, above Hide), `columnMenuItems` (the same rows as data, on the `menu` route), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`; and `headerVerticalBorders` (the header's columns ruled as the rows' are under `verticalBorders`, the last bare; off by default); and `fillWidth` (the columns share the grid's whole width, each in proportion to its own width and never below it, a column the person resized or one with a `grid.maxWidth` keeping its width; a table wider than the grid scrolls sideways as without it; off by default).
|
|
14
14
|
- Writes: `onCellCommit` (`GridCellCommitFn`) and `onCellsCommit` (`GridCellsCommitFn`).
|
|
15
15
|
- List config: `listConfig` (the settings layer every user of the list inherits, which may only take away from what the columns declare: the table read-only, per-column locks; a constraint on the screen, while your API guards its own writes). The grid only reads it: a surface of your own changes it.
|
|
16
16
|
- `useGridTablePrefs` — wires a list's view preferences to the grid. It takes `prefs` (the list's `ListViewPrefs`), `setPrefs` (stores a patch of them), `columns` (whose money reading the number formats read) and `viewBacked`, and returns `{ gridProps }` to spread on `GridTable`: the borders, row icon, frozen identity, checkboxes and scale, the format overrides, the column state, the group figures and the footer figures, each with the handler that writes it back through `setPrefs`.
|
|
17
|
+
- `useGridTableSettings` — wires a list's settings and a person's layer to the grid, for a list kept as `@viewkitjs/fields/query`'s `ListSettings`. It takes `settings`, `layer` (the person's `ListPersonalLayer`), `columns` (the declared ones), `parts` (the same `parts` the grid takes, so a part column the settings place is drawn and moved as the grid draws it), `onChange` (a `ListSettingsChange`, never empty), `onLayerChange` (a layer patch), `defaults` (the reader's `ListDefaults`) and `formats` with `setFormats`, and returns `{ gridProps }` to spread on `GridTable`, as `useGridTablePrefs` does: a column hidden, moved, given a line break or a figure, and a group header's figures, come back through `onChange`; a resize through `onLayerChange` as the person's width (a width taken back by a double-click leaves it); a format through `setFormats`.
|
|
18
|
+
- `GridFormatPrefs` — how a list's fields read, which `useGridTableSettings` takes apart from its settings: `gridOptionColors`, `gridDateStyles`, `gridDurationStyles`, `gridShowTime`, `gridPercentDisplays`, `gridDecimals` and `gridCurrencies`, each keyed by field key.
|
|
17
19
|
|
|
18
20
|
## Sort, group and figures
|
|
19
21
|
|
|
20
|
-
- `GridSortState` — the list's sort, as the header menu reads and writes it: `value` (the sort key in force), `dir` and `onChange({ value, dir })`. The menu is a second control for the same stored sort your view's options drive.
|
|
22
|
+
- `GridSortState` — the list's sort, as the header menu reads and writes it: `value` (the sort key in force; for a place column, the part key `partKey(fieldKey, part)` its menu picked, read with `parsePartKey`), `dir` and `onChange({ value, dir })`. The menu is a second control for the same stored sort your view's options drive.
|
|
21
23
|
- `GridGroupByState` — the view's grouping, for the header menu's Group by and Ungroup: `fieldKey` (or null) and `onChange(fieldKey)`, null to ungroup. Present on lists backed by a saved view.
|
|
22
24
|
- `GridGroupSortOption` — one sort a group band's menu offers, sorting the rows of every group at once: its `value`, `label` and an optional `defaultDir`.
|
|
23
25
|
- `GridGroupFigure` — one figure a group's band can show, either a `GridDeclaredFigure` or a `GridDrawnFigure`. Both carry the summary `part` that turns it on.
|
|
26
|
+
- `GridPages` — a grid in pages, `GridTable`'s `pages`: `page` (from 1), `size`, `total` (the view's count), `exact` (false for a capped count, which reads "of 1,000+"; default true), `sizes` (the page-size pick's choices; default 25, 50 and 100), `onPage` and `onSize`.
|
|
24
27
|
- `GridDeclaredFigure` — a figure the grid works out: its `column` (the column's id) and `kind` (a footer pick), written as that column's footer writes it, a paged group's from the source, or as your own footer cell where `renderAggregate` draws one; `label`, optional, is the column's header unless given.
|
|
25
28
|
- `GridDrawnFigure` — a figure you draw: its `label` and `render(group)`, how it draws for a group.
|
|
26
|
-
- `GridGroupMenuPart` — a part of a group band's ⋯ menu: `"sort"` (its sort choices), `"figures"` (the count and each figure, turned on and off) or `"hide"`.
|
|
29
|
+
- `GridGroupMenuPart` — a part of a group band's ⋯ menu: `"select"` (Select all in group, which picks every row of the group or, when all are picked, clears them; on a grid that selects), `"sort"` (its sort choices), `"figures"` (the count and each figure, turned on and off) or `"hide"`.
|
|
27
30
|
- `GridRowOpenedFrom` — what `onOpenRow` hands with the row: the way back to the cell it was opened from. `focus()` puts the focus back on that cell and returns true; `element()` is that cell, for a dialog's final-focus option (pass the function itself: both are plain properties). A record a refetch moved under another group is found again by its id, at its first place; a record no longer shown sends the focus to the grid's frame (`focus()` returns false, `element()` is the frame; a dialog that focuses only a tabbable element, and so passes the frame on to its first one, still leaves the focus on the frame, with no cell selected). On a desktop the cell becomes the grid's selected cell once the focus is on it, so the next arrow moves from it; below your `desktopQuery` only the focus goes back, with no cell selected. Asked while a dialog closes, `element()` is settled again once the close is done: the focus moves to the cell (a row a refetch moved out of the drawn rows is drawn first) unless it went somewhere outside the grid. Once the grid is gone they return `false` and `null`.
|
|
28
31
|
- `GroupCountNoun` — a group count's noun, `{ one, other }`, so a header reads "2 companies"; without one the count is bare.
|
|
29
32
|
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# `@viewkitjs/views/panels/react`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/panels/react` for the panels as they draw: each is a client component that reads your `ViewsProvider` (its components, atoms, icons, conventions and words), so it renders under the provider your app mounts. The door carries the client directive. What the panels edit and say, the settings and their labels, is the pure door [`@viewkitjs/views/panels`](./panels.md), which a server file may read without shipping a panel. Rows draw through the panels' atoms, and a calendar through the `RangeCalendar` atom (see [the atoms](../contract.md#the-atoms)); every word is a `views.panels.*` key.
|
|
4
|
+
|
|
5
|
+
## The filter panel
|
|
6
|
+
|
|
7
|
+
- `CompactFilterList` — the Filter drill-in: a row per filter, grouped under each filter's `section`, then the time scope and the date ranges; a press opens that row's detail through `onOpenPanel`.
|
|
8
|
+
- `dimensionRows` — the same rows without the scroll box, for a root list that shows them unfolded.
|
|
9
|
+
- `FilterSectionHeading` — a section's rule and heading in the filter panel, and the Where heading inside a relation's filter.
|
|
10
|
+
- `FilterIcon` — a filter row's glyph: the filter's own `icon`, else its kind's (`filterStatus`, `filterCategory`, `filterMetric`), else `filter`.
|
|
11
|
+
- `CompactFilterDetail` — one filter's page: the body for its type, an unavailable filter's reason and its Clear saved filter, a multi filter's ticked options, or a single filter's options after its All row. A relation's Where row opens its far field through `onOpenField`.
|
|
12
|
+
- `TextFilterBody` — a text filter's box and operators; the box commits after a short idle, on Enter or on its clear.
|
|
13
|
+
- `NumberFilterBody` — a number filter's bound or bounds and operators; a duration reads and writes the cell's own wording, stored in the column's unit.
|
|
14
|
+
- `RangeFilterBody` — a range filter's presets, bounds and operators; an empty bound is an open end.
|
|
15
|
+
- `RelationFilterBody` — a relation filter's Any, No and Every, the sentence that says what the list shows, and the far fields as Where rows your surface draws.
|
|
16
|
+
- `DateFilterBody` — a date filter's editor: the operator through your `Menu`, the relative direction and unit, the date boxes and the month.
|
|
17
|
+
- `DateFilterFields` — everything under the operator, for a surface that draws its own operator (a phone's sheet).
|
|
18
|
+
- `useDateFilterEditor` — the date editor's state: the rule, the end being picked, the boxes' refs, and its setters.
|
|
19
|
+
- `DateFilterEditor` — what `useDateFilterEditor` returns.
|
|
20
|
+
- `DateFilterCalendar` — the date filter's month, through `RangeCalendar`: a press sets the end being picked and hands the caret to the other end's box; a relative rule paints its window and takes no press.
|
|
21
|
+
- `DateFilterEditingEnd` — which end a press sets, `from` or `to`.
|
|
22
|
+
- `DateFilterInput` — one end's typed date, committed once it reads as a whole day, or on its clear.
|
|
23
|
+
- `CompactToggleDetail` — a toggle's On and Off; a pick goes back.
|
|
24
|
+
- `CompactDateRangeDetail` — a date range's month, with a Clear under it while either end is set.
|
|
25
|
+
- `CompactTimeScopeDetail` — a time scope's presets and its Custom row, which opens a month; a press on a finished custom range starts a new one, and your popover's back arrow steps from the month to the presets through `registerBackHandler`.
|
|
26
|
+
|
|
27
|
+
## The views row
|
|
28
|
+
|
|
29
|
+
The row of views over a list, and any row of pills: each pill is your `Pill` atom, a pill's verbs open through your `Menu`, the folded views and the picker's list through your `Popover`, a view's glyph through your `AppIcon`. The pills drag with dnd-kit, by the mouse and the keyboard (Space on a pill's grip, the arrows, Space), within their block: a private view moves among the private ones, a shared view among the shared. The active pill's `Menu` is drawn beside it in the row, so a closed `Menu` must render nothing in place (a portaled popup does): the fold measures the row's children. Install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it. The axes it draws are `/panels`' (`ViewTabOption`, `CollectionViewsConfig` and the rest).
|
|
30
|
+
|
|
31
|
+
- `PillGroup` — a single-select drawn as pills, `solid` or `plain`, `default` or `sm`, reordering by drag when handed `onReorder`. Its options are `PillOption`s.
|
|
32
|
+
- `HScrollRow` — a scroll rail that keeps the active pill in view, its width and end room from `--vk-scroll-row-inset` and `--vk-scroll-row-end`.
|
|
33
|
+
- `ViewTabs` — one axis as plain pills on a scroll rail.
|
|
34
|
+
- `toPillOptions` — views turned into pill options: the label and count joined by `views.panels.view-count`, a slot's colours, the glyph by your `AppIcon`.
|
|
35
|
+
- `FoldingViewRow` — the saved-views row that folds what doesn't fit into a "+N" chip, never folding the active view, and closes with the + when the axis grows.
|
|
36
|
+
- `ViewPicker` — the same axis as one chip naming the active view, its views in a list: shared, then personal, a search past five, and "New view…" last. The list opens in your `Popover` at the chip; on a phone (in a `Toolbar`, its phone form; elsewhere your provider's `desktopQuery`) in your `Sheet` (`snap: "auto"`, titled `views.panels.views-list`), its search not taking the focus.
|
|
37
|
+
- `ViewPickerRow` — one view as a row of a list, with the active view's `⋮`.
|
|
38
|
+
- `ViewCreatePill` — the + that creates a view.
|
|
39
|
+
- `ViewAxes` — an axis or several on one row: one axis at the row's size folds, peer axes share one rail, each in its own track.
|
|
40
|
+
|
|
41
|
+
## The Sort and Group panels
|
|
42
|
+
|
|
43
|
+
A panel's list keeps `--vk-panel-padding` from its edge ([Tokens](../contract.md#tokens)). Each panel's root is a `data-vs-detail` list and each row a `data-vs-row`, so a host that frames a panel styles it through those. This is the one door that may reach dnd-kit, the package's optional peers: the Columns list, the group order and the view pills drag through it. Install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it; an app that takes only the grid, or only the panels' pure door, never does.
|
|
44
|
+
|
|
45
|
+
- `CompactSortDetail` — Sort's page: every option the list sorts by, the current one ticked with its direction arrow, and a search once there are more than eight (`GROUP_BY_SEARCH_AFTER`). Takes `sort` (`SortConfig`); a pick sorts by that option in its own direction.
|
|
46
|
+
- `CompactGroupDetail` — the Group panel: Group by, Sort and Date by as rows that open pages of their own, Hide empty groups as a switch, the Groups to show, hide and drag, and Remove grouping. Takes `group` (`GroupConfig`) and `onOpenPanel`, called with `{ type: "groupBy" }`, `{ type: "groupSort" }` or `{ type: "groupDateBy" }`. A `group` with no `hideEmpty` or `groups` draws no such section.
|
|
47
|
+
- `CompactGroupByDetail` — Group by's page: None and every dimension, the current one checked, a search past eight. Takes `group` and `onBack`, called after a pick.
|
|
48
|
+
- `CompactGroupSortDetail` — the Group panel's Sort page: the dimension's orders both ways, then Manual where its groups can be dragged. Takes `group` and `onBack`.
|
|
49
|
+
- `CompactGroupDateByDetail` — Date by's page: a date dimension's granularities. Takes `group` and `onBack`.
|
|
50
|
+
- `GroupBucketsList` — the group order: every group with a grip to drag it and an eye to show or hide it, an empty group dimmed and the empty one named `views.panels.group-empty`. Takes `groups` (`GroupConfig["groups"]`) and `variant`, `"compact"` (a panel's row) or `"comfortable"` (a phone sheet's taller row). It drags by mouse after 8 px, by a long press of 250 ms that gives up past 5 px, and by the keyboard (Space or Enter lifts a focused grip, the arrows move it); the grip carries `data-base-ui-swipe-ignore`, so a drawer that honours it keeps still while a row inside it is dragged.
|
|
51
|
+
|
|
52
|
+
## The Layout panel and the columns
|
|
53
|
+
|
|
54
|
+
- `CompactLayoutDetail` — the Layout panel: the layouts a list can draw, the ones it refuses greyed with their reason on a resting pointer, then the active layout's Options, its own pick-one settings, Density and the reader's For you section. Takes `layout` (`LayoutConfig`).
|
|
55
|
+
- `LayoutColumnsList` — the Columns list: a grip to reorder, an eye to show or hide, the row's body to open a column's settings, a board card's new-line toggle, and Reset when a column differs from the view. Takes `columns` (`LayoutColumnsConfig`), `variant`, `onOpenColumn`, `canOpen` (which rows open; every row when absent), `showNewLine` and `fieldEditor`. It drags as `GroupBucketsList` does; a `fixed` column has no grip and no eye.
|
|
56
|
+
- `PopoverColumnDetail` — one column's settings: Visible, its pick-one settings and toggles under their sections, and the field editor's rows for its field. Takes `column`, `columns`, `onDone` (called once a field editor's row has opened its window) and `fieldEditor`.
|
|
57
|
+
- `PanelFieldEditor` — what an app's field editor adds to the panels: `columnMenu(fieldKey, close)`, the rows a column's settings show for its field (`null` for a field it does not change), and `fieldsFooter(columns)`, what the Columns list shows under its rows. Without one, both draw as they always have.
|
|
58
|
+
|
|
59
|
+
## Customize
|
|
60
|
+
|
|
61
|
+
The panel a list's Options button opens, put together from the panels above: one header frame (a back arrow only when deep, the title, Clear all at the root without a shared view, a ✕ when the host can close it) over the root list or the page a row opened, and, at the root of a shared view, its footer. Its root is a `data-vs-detail` list, its header `data-vs-header`, its footer `data-vs-footer` with `data-vs-inset` and each actions row a `data-vs-row`, so a drawer of your own insets them through those; the root's rows carry `data-vs-row` when your `MenuRow` and `ToggleRow` atoms do. Your app hosts it: in a popover, or in a full-height drawer with `fill`.
|
|
62
|
+
|
|
63
|
+
- `ViewOptionsPanelContent` — the panel. Takes the list's `filters`, `sort`, `group`, `timeScopeConfig`, `dateRangeConfigs`, `toggles` and `layout` (`ViewOptionInputs`), `activePanel` and `onOpenPanel`, `anyActive` and `clearAll`, and optionally `view` (`CollectionViewState`), `foldFilters` (one Filter row, on by default; off, every filter is a root row), `onClose`, `closeButton` (whether its header draws the ✕, default true; false in a sheet whose head draws it, `onClose` still closing it from inside, as a column's Done does), `fill` and `fieldEditor` (`PanelFieldEditor`). Back walks one level: a relation's Where field to its filter, a folded filter to the Filter list, a column to the Columns list, Group's own Group by, Sort and Date by pages to Group, anything else to the root.
|
|
64
|
+
- `PopoverRootList` — the root: Layout, Columns (`views.panels.columns-shown`), Filter (or each filter, unfolded), Sort, Group and the toggles, each opening its page through `onOpenPanel`.
|
|
65
|
+
- `ViewFooter` — Reset · Set default for everyone on a shared view this person has drifted from; a member sees Reset alone, and nothing draws while `changes` is 0. `className` replaces its side inset.
|
|
66
|
+
- `ViewOptionsActions` — the actions row: Copy link and Share parked, Export CSV live when `exportCsv` (`CollectionExportCsv`) is handed in, its count on the row and one export at a time behind the `loading` glyph, which your app draws turning.
|
|
67
|
+
- `ViewOptionsPopoverPanel` — the panel for a popover: `ViewOptionsPanelContent` with `setActivePanel` for `onOpenPanel`.
|
|
68
|
+
- `useViewOptionsPopover` — the state the trigger and the popover share (`ViewOptionsPopoverState`): `open`, the page it is on, the trigger's `badge` (the drift from everyone's view on a shared view, else the active options) and its `clearAll` (Reset, else clear them), and `handleOpenChange`, which forgets the page on a close. The trigger's own look is yours.
|
|
69
|
+
- `ViewOptionsPopoverState` — what `useViewOptionsPopover` hands back: `open` and `setOpen`, `badge`, `activePanel` and `setActivePanel`, `anyActive`, `clearAll` and `handleOpenChange`.
|
|
70
|
+
- `useViewActivePanel` — the page alone, with the active-options count and clear, for a host that keeps its own open state (a phone's sheet).
|
|
71
|
+
- `viewOptionsPopoverClassName` — the popover's own classes: its width (`w-60`, or the one you pass), `w-62` on a date range's or time scope's page whatever you pass, `z-90`, and its slide from the right, which needs your app's animation utilities.
|
|
72
|
+
- `keepPanelOpenForPortals` — hand it to your popover's outside-press and outside-focus handlers: a click inside one of the panel's own portalled children (a select's list, a nested popover, each inside Radix's `[data-radix-popper-content-wrapper]`), or on a page body a modal layer has locked, never closes the panel.
|
|
73
|
+
|
|
74
|
+
## The toolbar
|
|
75
|
+
|
|
76
|
+
The frame that holds a list's controls, and the parts that need no list settings. `Toolbar` takes the parts your app hands it, each placed at the start or the end, on the first line or the second, and draws them in one of three forms (`/panels`' [arrangement](panels.md#the-toolbars-arrangement)): `row`, `narrow` (its own box under 700px) or `phone` (your provider's `desktopQuery` says it is not a desktop). Pass `phone` or `narrow` to decide either yourself. A part is any node: the frame tells it where it stands through `useToolbarSlot`, and its buttons draw through the `ToolbarButton` atom at their line's size. A part that opens something (a menu, a panel, a pane your app holds) registers it with `useToolbarPanel`, and opening one closes every other, however it opened. A change of form draws the parts afresh, so keep what must last across it (a search's text, a panel's open state) in your app: a panel part left to hold its own state closes when the box crosses 700px, and one handed its state from `useToolbarPanelState`, held above the `Toolbar`, stays open on its page. The row's end controls float over the views on a fade of `--vk-ground` (`data-toolbar-cluster`), which the folding views row measures. Its look is plain; its pieces carry the `data-slot`s the [contract](../contract.md) lists.
|
|
77
|
+
|
|
78
|
+
- `Toolbar` — the frame. Takes `parts` (`ToolbarPart[]`), and optionally `phone`, `narrow`, `narrowBelow` (700 by default) and `className`.
|
|
79
|
+
- `ToolbarPart` — a part as your app hands it: a `ToolbarPlacement` (its `key`, `side`, `line`, `role`) and its `node`.
|
|
80
|
+
- `ToolbarViews` — the views row: `views` (`CollectionViewsInput`) and `viewsLayout`. On the row and in the narrow panel it draws `ViewAxes`, or with `as="picker"` and one axis alone its `ViewPicker`; placed again with `stacked` on the second line, it draws the axes a stacked layout pushes beneath, small. On the phone it draws a `ViewPicker` per axis, every axis, and nothing for `stacked`. With `showCounts` the toolbar owns Show counts (`withCounts`). Place it only when the list has views: the phone's search fills the row when nothing is placed at the start.
|
|
81
|
+
- `ToolbarSearch` — the search, placed with `role: "search"`: `value`, `onChange`, `placeholder` (`views.panels.search` by default) and `searching` (while true, a spinner, worded `views.panels.searching`, stands where its glass is, on the button and in the field, and the field, marked `aria-busy`, keeps its value and its typing; your app decides when it is true). On the row, and beside the phone's views, a button that opens an inline field; in the narrow panel, and on a phone with no views, a field that fills its line. A field that holds a value shows from the start. Escape and its ✕ clear it and close a field the button opened; a blur with nothing typed closes it. The field is your `Input`.
|
|
82
|
+
- `ToolbarNew` — the +: `onAdd` (one way to add, the button fires it) or `items` (several, opened through your `Menu`, one of the toolbar's panels), `label` (`views.panels.toolbar-new` by default) and `icon` (your `add` glyph by default); its word for a dress is its label. With neither, the row draws it disabled, so its place never moves; the narrow panel and the phone draw nothing.
|
|
83
|
+
- `ToolbarButton` — the `ToolbarButton` atom at the size of the line it stands in, for a custom part's buttons.
|
|
84
|
+
- `useToolbarSlot` — where this part stands (`ToolbarSlotState`): `form`, `fill`, `size` and its line's kind; outside a `Toolbar`, the row's main line at `md`.
|
|
85
|
+
- `ToolbarSlotState` — what `useToolbarSlot` returns.
|
|
86
|
+
- `useToolbarPanel` — a part's open state as one of the toolbar's panels, named by a key: `{ open, onOpenChange }`. Each call is its own panel, so two parts that name the same key still close each other. Hand it `{ open, onOpenChange }` for a panel your app holds; without, it holds its own. Outside a `Toolbar`, plain open state.
|
|
87
|
+
|
|
88
|
+
### The panel parts and the ready toolbar
|
|
89
|
+
|
|
90
|
+
Options, Sort and Filter each open their panel from their own button, and each takes the builder's panels ([`settingsPanels`](panels.md#built-from-a-lists-settings)): an app that arranges its own parts calls the builder and hands them in. A panel hangs in your `Popover` at its button (`chrome="menu"`, aligned to its end), or in a host you hand in, your side drawer or your sheet, where it draws full height. On a phone (in a `Toolbar`, its phone form; elsewhere your provider's `desktopQuery`) it opens in your `Sheet` instead (`snap: "full"`, named `label` with the part's name, its own header titling it), full height, with every page the popover has; a host you hand still takes it. With your provider's `sheetActions: "head"`, the sheet's head draws the panel's ✕ (`actions.close`, no `done`) and the panel draws none. Each is one of the toolbar's panels, so opening one closes the others. Hand `open` and `onOpenChange` (and `page` and `onPageChange` where it drills in) to hold its state yourself; without, it holds its own, forgetting its page when it closes.
|
|
91
|
+
|
|
92
|
+
- `ToolbarOptions` — Customize behind its own button, named and worded `views.panels.toolbar-options`: the builder's `filters`, `sort`, `group` and `layout`, your `toggles`, `timeScopeConfig` and `dateRangeConfigs` (a `ViewOptionInputs`), and optionally `view` (a shared view: the drift dot on the button instead of a count, and the panel's footer), `fieldEditor`, `foldFilters` (true by default), `onClear` (the ✕ and the panel's Clear all; by default each active option cleared through its own `onChange`, the builder's filter rows adding up so every filter clears, or Reset on a shared view; for one change, `settingsCleared(…, "options")`), `widthClassName` and `host`. Its button counts the active options (`countActiveViewOptions`) with a ✕ that clears them. Draws nothing when there is nothing to customize.
|
|
93
|
+
- `ToolbarSort` — the sort panel behind its own button, named `views.panels.sort`: the builder's `sort`, lit (`changed`) while the list sorts other than its default. Draws nothing when nothing sorts.
|
|
94
|
+
- `ToolbarFilter` — the filter list and its drill-ins behind its own button, named `views.panels.filter`: the builder's `filters`, and optionally `timeScopeConfig`, `dateRangeConfigs` and `onClear` (by default every applied filter cleared through the builder's rows, which add up, the last change clearing them all; for one change, `settingsCleared(…, "filters")`). Its button counts what is applied (`countActiveFilters`) with a ✕. Draws nothing with nothing to filter.
|
|
95
|
+
- `ToolbarPanelHost` — a host for a panel part: a component taking `open`, `onOpenChange`, `title` (the part's name) and the panel as `children`.
|
|
96
|
+
- `useToolbarPanelState` — a panel part's state for your app to hold (`ToolbarPanelState`): `open`, `onOpenChange`, `page` and `onPageChange`; closing forgets the page.
|
|
97
|
+
- `ToolbarPanelState` — what `useToolbarPanelState` returns.
|
|
98
|
+
- `FilterPanelContent` — the Filter panel standing alone, for a host of your own: the filter list at its root (titled `views.panels.filter`, no back arrow) and the pages it opens, with `filters`, `timeScopeConfig`, `dateRangeConfigs`, `page`, `onPageChange`, `onClose` and `fill`.
|
|
99
|
+
- `ReadyToolbar` — the toolbar for an app that doesn't arrange its own (`ReadyToolbarProps`): the builder's input (`settings`, `layer`, `columns`, `onChange`, `onLayerChange` and the rest of `SettingsPanelsInput`), and optionally `views`, `viewsLayout`, `showCounts` with `onShowCountsChange` (held by the toolbar, on, when absent), `onAdd` or `addItems` and `addLabel`, `view`, `toggles`, `fieldEditor`, `searchPlaceholder`, `searching` (handed to its search), `hosts` (`{ options, sort, filter }`), `phone`, `narrow` and `className`. It calls the builder and draws the views on the left; search, sort, filter, options and new on the right. Every change comes back as a `ListSettingsChange` or a layer patch: its search writes the settings' search, its ✕s clear in one change (`settingsCleared`), and the active view's menu gains "Edit view…" (`withEditView`), which opens Customize. It holds the three panels' state above its frame, so a change of form keeps a panel open on its page, in a sheet once the form is the phone's. Show counts joins Customize's toggles where the views carry counts, and Group steps aside on a board (`groupShown`).
|
|
100
|
+
- `ReadyToolbarProps` — what `ReadyToolbar` takes.
|
|
101
|
+
- `useListSettingsState` — a list's settings and layer held in memory, for an app that keeps none yet (a proof page, a test): `{ settings, layer? }` in, `{ settings, layer, onChange, onLayerChange }` out, ready to spread into `ReadyToolbar` beside its `columns`. Each change is applied to the latest settings (`applySettingsChange`), each patch merged into the latest layer.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# `@viewkitjs/views/panels`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/panels` for what a list's panels read and say: the settings they edit, which sections exist on a viewport, the Group panel's orders, and every row's value in words. The door carries no client directive; its one hook, `useFilterOpened`, carries its own. Every word is a `views.panels.*` key (see [the contract's message keys](../contract.md#message-keys)): each label takes your resolver last and defaults to the package's English. The panels' rows are atoms (`ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow`, `PanelSearch`; see [the atoms](../contract.md#the-atoms)). The panels themselves, which draw under your provider, are [`@viewkitjs/views/panels/react`](./panels-react.md). These two doors are the only ones that may reach dnd-kit, the package's optional peers, once a panel whose list drags joins them: install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it; an app that takes only the grid never does. This door is pure, so a server file may import it.
|
|
4
|
+
|
|
5
|
+
## The settings a panel edits
|
|
6
|
+
|
|
7
|
+
- `SortConfig` — a list's sort: its `options`, the `value` and `dir`, the `defaultValue` it resets to, `onChange`, and an optional `label`.
|
|
8
|
+
- `SortOption` — one field a list sorts by: `value`, `label` and the `defaultDir` it opens in.
|
|
9
|
+
- `GroupConfig` — a list's group: its `dimensions`, the `value` (or `"none"`), each dimension's `order` and `granularity`, `onChange`, `hideEmpty` and, while grouped, the `groups` to show, hide and drag.
|
|
10
|
+
- `GroupDimension` — one field a list groups by: its `orderOptions`, `defaultOrder`, and a date's `granularities` and `defaultGranularity`.
|
|
11
|
+
- `GroupOrderOption` — one way a dimension's groups are ordered, with the `defaultDir` it opens in.
|
|
12
|
+
- `GroupListEntry` — one group as the Group panel lists it: its `key`, `label`, and whether it is `empty` or `hidden`.
|
|
13
|
+
- `groupOrderFor` — the order a dimension opens in under a mode: that choice's own direction, else the mode's.
|
|
14
|
+
- `ToggleConfig` — a boolean the panel flips in place: `key`, `label`, `value`, `onChange`, an `icon`, `desktopOnly`, a `reset` back to the reader's default, and the `section` it sits under.
|
|
15
|
+
- `LayoutConfig` — the layouts a list can draw and the active one, with the layouts it refuses and why, its toggles, columns, per-view choices, density, the reader's own section (`personal`) and the phone's own layout.
|
|
16
|
+
- `LayoutColumnsConfig` — the Columns drill-in: the views package's columns, with each column's settings and the card layout's line breaks (`newLine`).
|
|
17
|
+
- `LayoutColumnItem` — one column, with the `settings` its drill-in shows.
|
|
18
|
+
- `LayoutColumnChoice` — a pick-one setting on a column (a currency, decimals).
|
|
19
|
+
- `LayoutViewChoice` — a pick-one setting of the active view, gated by the `views` it means something on.
|
|
20
|
+
- `LayoutDensityConfig` — the active view's row spacing.
|
|
21
|
+
- `LayoutPersonalConfig` — the reader's own settings over a shared view, under their own heading.
|
|
22
|
+
- `TimeScopeConfig` — a time range's choices, with an optional custom range.
|
|
23
|
+
- `DateRangeConfig` — a date range a list filters by: `key`, `label`, `value` (`DateRangeValue`) and `onChange`.
|
|
24
|
+
- `DateRangeValue` — a range's two ends, each a `Date` or `null`.
|
|
25
|
+
- `ActivePanel` — which drill-in is open: a filter (and a Where field inside a relation's), group, sort, time scope, a date range, a toggle, layout, the Filter list, Columns, one column, or Group's by, sort and date-by pages.
|
|
26
|
+
- `ViewOptionInputs` — everything a Customize panel is handed: filters, sort, group, time scope, date ranges, toggles and layout.
|
|
27
|
+
- `CollectionViewState` — the shared view on screen: how far what this person sees drifted from it (`changes`, `stale`), whether they may publish, a write in flight, and the two verbs that settle the drift.
|
|
28
|
+
- `CollectionExportCsv` — a list's export, when it offers one: `count`, the rows it would take, which the Export CSV row shows, and `run`, which builds and downloads the file and says how it went.
|
|
29
|
+
- `isSortActive` — whether a sort differs from its default.
|
|
30
|
+
- `isGroupActive` — whether a list is grouped.
|
|
31
|
+
- `isDateRangeActive` — whether a date range has either end.
|
|
32
|
+
- `countActiveFilters` — how many filter dimensions are filtering: the Filter row's count.
|
|
33
|
+
- `countActiveViewOptions` — the trigger's count: filters, sort, group and date ranges that differ from their defaults.
|
|
34
|
+
- `clearViewOptions` — clears every refinement, keeping each group's order and granularity.
|
|
35
|
+
|
|
36
|
+
## Which sections exist
|
|
37
|
+
|
|
38
|
+
- `getViewOptionAvailability` — whether a Customize panel has anything to show on the desktop and on the phone.
|
|
39
|
+
- `resolvePersonalSection` — the "For you" section as it draws, or `null` when it has nothing: its label (`views.panels.for-you` unless the layout names one), toggles, choices and reset.
|
|
40
|
+
|
|
41
|
+
## The Group panel's orders
|
|
42
|
+
|
|
43
|
+
- `groupSortChoices` — each of a dimension's orders in both directions, its own first, then Manual unless `manual` is false, each named by what it does ("Most first", "Newest first", "Alphabetical").
|
|
44
|
+
- `groupSortValue` — a choice's key: the mode and direction, or `"manual"`.
|
|
45
|
+
- `offersManualOrder` — whether the Group panel's sort offers Manual: where its groups can be dragged, or where Manual is already the order.
|
|
46
|
+
|
|
47
|
+
## Every row's words
|
|
48
|
+
|
|
49
|
+
- `filterValueLabel` — a filter row's value: the conventions it reads ranges and dates with, then your resolver.
|
|
50
|
+
- `relationSentence` — what a relation's filter keeps, in one sentence: "Clients with at least one campaign where status is Active."
|
|
51
|
+
- `dateRangeValueLabel` — a date range's value: "All time", "Jan 1 — Jan 9", "From …", "Until …". Its days are written in the conventions' locale, its optional third argument.
|
|
52
|
+
- `timeScopeRowValueLabel` — a time range's value, a custom range's ends or its label; the ends in the conventions' locale, its optional third argument.
|
|
53
|
+
- `sortValueLabel` — the Sort row's value: "Name desc".
|
|
54
|
+
- `groupValueLabel` — the Group row's value: the dimension's label, or "None".
|
|
55
|
+
- `activeGroupDimension` — the dimension a grouped list is grouped by, or `null`.
|
|
56
|
+
- `groupSortLabel` — the Group panel's Sort row value, a stored order the dimension doesn't offer named in the same words.
|
|
57
|
+
- `groupDateByLabel` — the Group panel's Date by row value.
|
|
58
|
+
- `layoutValueLabel` — the Layout row's value.
|
|
59
|
+
- `filterRowValueLabel` — the Filter row's value: "None", "1 filter", "2 filters".
|
|
60
|
+
- `GROUP_BY_SEARCH_AFTER` — how many dimensions or sort options a page lists before it offers a search (8).
|
|
61
|
+
- `matchGroupDimensions` — the dimensions a Group by page lists for a search.
|
|
62
|
+
- `matchSortOptions` — the options a Sort page lists for a search.
|
|
63
|
+
- `useFilterOpened` — tells a filter row's host it opened, once per row, so the host may ask for what the row offers.
|
|
64
|
+
|
|
65
|
+
## The views row's axes
|
|
66
|
+
|
|
67
|
+
What a list hands the views row ([`@viewkitjs/views/panels/react`](panels-react.md) draws it).
|
|
68
|
+
|
|
69
|
+
- `ViewTabOption` — one view: its `value`, `label`, `count`, a status `slot` or your own `activeClassName`, its `icon` by your own glyph's name, whether it is `private`, and its verbs as `menu` (the package's menu rows, reached from the active view only).
|
|
70
|
+
- `CollectionViewsConfig` — one axis of views: its `value`, `options`, `onChange`, `hideCounts`, `onCreate` and its `createLabel`, `onReorder` (one block in its new order, folded views included) and `canDrag`.
|
|
71
|
+
- `CollectionViewsInput` — one axis, or an array of peer axes.
|
|
72
|
+
- `ViewsLayout` — how peer axes lay out: `stacked` (each after the first on a row of its own) or `inline`.
|
|
73
|
+
- `CollectionChildAxis` — a child axis whose options depend on the primary selection, as data, for a phone's sheet.
|
|
74
|
+
- `toViewAxes` — the array form of either arity.
|
|
75
|
+
- `splitViewAxes` — the axes split into the primary row and the row a stacked layout pushes beneath.
|
|
76
|
+
- `PillOption` — one of a `PillGroup`'s options: its `value`, `label`, `badge`, a leading glyph, your own active and hover classes, whether it is `private`, and its `menu`.
|
|
77
|
+
|
|
78
|
+
## The toolbar's arrangement
|
|
79
|
+
|
|
80
|
+
Which form a toolbar draws and where each part stands in it; [`@viewkitjs/views/panels/react`](panels-react.md)'s `Toolbar` draws it. Three forms: `row`, one line with the start and the end cluster and a second line beneath; `narrow`, for a box under 700px on a big screen, the search filling its own line with the end controls beside it and the views flowing on the line under it; and `phone`, one row with the views at the start, or the search filling the row when nothing stands at the start. A part marked as the search is the one the forms move; every other part stands where it asks.
|
|
81
|
+
|
|
82
|
+
- `ToolbarForm` — `"row"`, `"narrow"` or `"phone"`.
|
|
83
|
+
- `ToolbarPlacement` — where a part stands: its `key`, its `side` (`start`, the default, or `end`), its `line` (`1`, the default, or `2`) and `role: "search"` for the search. A second part marked as the search stands as a plain part.
|
|
84
|
+
- `ToolbarSlot` — one part in a line: its `key`, and `fill` when it takes the line's room (the search as a field).
|
|
85
|
+
- `ToolbarLine` — one line: its `kind` (`main`, `search`, `views` or `below`), its `start` and `end` slots, and the `size` its buttons take (`md` or `sm`).
|
|
86
|
+
- `TOOLBAR_NARROW_BELOW` — the box width under which a toolbar is narrow (700).
|
|
87
|
+
- `toolbarForm` — the form from `{ phone, narrow }`: a phone draws its own row whatever its box; a narrow box draws the narrow panel; not measured yet (`null`), the row.
|
|
88
|
+
- `arrangeToolbar` — the parts laid out into lines for a form, in the order they were handed in on each side; a line with nothing on it is dropped.
|
|
89
|
+
|
|
90
|
+
What the toolbar owns over a list's settings:
|
|
91
|
+
|
|
92
|
+
- `SHOW_COUNTS_KEY` — `"show_counts"`, the key of the toolbar's own Show counts.
|
|
93
|
+
- `withCounts` — the views with every axis that doesn't say `hideCounts` itself hiding its counts while Show counts is off.
|
|
94
|
+
- `countsToggle` — the toolbar's own Show counts as a `ToggleConfig` for the Options panel, worded `views.panels.show-counts`: absent when no option carries a number, or when the list's toggles already hold one keyed `show_counts`.
|
|
95
|
+
- `groupShown` — the list's `GroupConfig`, or nothing on a board: when the active layout (the phone's own on a phone) is one the layout's `hidesGroupFor` names.
|
|
96
|
+
- `withEditView` — the views with a row of yours (`ViewsMenuItem`, "Edit view…" in the ready toolbar, worded `views.panels.edit-view`) at the head of the active option's menu on every axis whose active option has a menu, the row after it carrying `separatorBefore`. One config in, one config out; an array, an array. Apply it once to the views your app hands in: applied twice, it adds the row twice.
|
|
97
|
+
- `settingsCleared` — what a toolbar ✕ clears over a list's settings, as one `ListSettingsChange`, or `null` when nothing would change: `"filters"` the Filter panel's rows, `"options"` those, the sort (back to its default) and the group (to none) where Options shows it: on a board the group is the table's and stays untouched, as `groupShown` says (pass `{ phone: true }` to read the phone's own layout). It takes the builder's input without its callbacks. Clearing the builder's rows through their own `onChange` hands several changes, the last of which clears them all (the rows of one build add up); this folds the clear through the builder and hands back one change.
|
|
98
|
+
|
|
99
|
+
## Built from a list's settings
|
|
100
|
+
|
|
101
|
+
Every panel's config from one value: a list's `ListSettings` (`@viewkitjs/fields/query`), a person's `ListPersonalLayer` over it and the list's columns go in, and each change comes back through `onChange` as a `ListSettingsChange` (only the parts it changes, never empty) or through `onLayerChange` as a layer patch. Your app keeps the settings and the layer where it likes (a saved view, a draft, the link, its own store) and calls the builder again when they move; what is set aside in the settings is kept through every write. Every word is a `views.panels.*` key, worded by the `resolve` you hand in. Each call builds fresh configs and callbacks: memoize it on the settings and the layer, so a panel keeps its identity between renders. The look's toggles show what the person sees (their layer's look over the view's) and write the view's. `columns` are the list's declared columns; a part column the grid derives (its `parts`) is the grid's, and the Filter panel draws its rows under its whole column (`filterData.parts`).
|
|
102
|
+
|
|
103
|
+
- `settingsPanels` — every panel at once: `filters`, `sort`, `group`, `groupBy` (the grid header's), `layout`, and the two writes a list's body makes, `setLaneVisible` (a board lane shown or hidden) and `setFolded` (the groups the person folded, their layer's).
|
|
104
|
+
- `SettingsPanels` — what `settingsPanels` returns.
|
|
105
|
+
- `SettingsPanelsInput` — what every builder takes: `settings`, `layer`, `columns`, `onChange`, `onLayerChange`, and optionally `defaults` (the reader's), `resolve`, `conventions` (the reader's: the Filter rows' country names read its `language`; `ReadyToolbar` hands the provider's), `layouts` (the layouts the list offers, in order), `boardField` and `calendarField` (the fields a board and a calendar take when the settings name none), `rowsShowColumns`, `rowIcon`, `manualOrder` (Sort offers Manual), `defaultSort`, `sortOptions` and `groupDimensions` (a list's own, until it moves onto its fields), `groupHeads` (the answer's groups), `columnIcon`, `columnSettings` (a column's drill-in beyond Visible: its formats, a lock), `filterData` (what the filter rows offer) and `relationFilters`.
|
|
106
|
+
- `PanelGroupHead` — one group of the answer, as the Group panel lists it: `key`, `label`, `count`, `hidden`.
|
|
107
|
+
- `SettingsGroupDimension` — a Group dimension with the `fieldKey` it groups by.
|
|
108
|
+
- `settingsFilters` — the Filter rows: each column's root rule read from the settings' filter, an edit written back with every group, relation rule and set-aside rule kept; a column with no field is a row a saved list can't filter on.
|
|
109
|
+
- `settingsSort` — the Sort panel: the first live sort, a pick writing that one sort with the set-aside ones on other fields kept; with `manualOrder`, Manual first. A place column adds one option per part it sorts by ("Address · City"), keyed by the part key and written as `{ fieldKey, direction, by }`.
|
|
110
|
+
- `settingsGroup` — the Group panel: a new field opens with Hide empty groups on, the same field keeps its groups unless a new granularity re-keys them, and with `groupHeads` the groups to show, hide and drag.
|
|
111
|
+
- `settingsGroupBy` — the grid header's Group by over the settings.
|
|
112
|
+
- `groupDimensionFor` — what a field's Group by offers and opens with, worded through your resolver.
|
|
113
|
+
- `settingsLayout` — the Layout panel: the layouts the columns can draw (the others refused, with why), a switch to a board or a calendar naming its field in the same change, the phone's own layout (the layer's), the look's toggles and density, the Columns list with a card's line breaks, the board's and the calendar's fields, and the reader's own section.
|
|
114
|
+
- `columnStateOf` — the settings' columns as the grid's `ListColumnState`, the person's widths over the view's.
|
|
115
|
+
- `columnsChangeOf` — a column state handed back, as `{ change, layer }`: the settings' columns in its order and visibility, and only the widths that differ in the person's layer.
|
|
116
|
+
- `columnsReset` — the Columns list's reset, as a change.
|
|
117
|
+
- `aggregatesOf` — each placed column's figure, by grid column id.
|
|
118
|
+
- `figuresChangeOf` — the figures picked, as a change; a computed column is never totalled.
|
|
119
|
+
- `seenLook` — the look a person sees: theirs, the view's, then the defaults (the reader's own for vertical borders).
|
|
120
|
+
- `SeenLook` — that look, every setting resolved.
|
|
121
|
+
- `lookChange` — one look setting set on the view, as a change; vertical borders set to the reader's default leaves the view without an answer of its own.
|
|
122
|
+
- `boardFieldOf` — the column a board is laid out by: the settings' field, else the preferred one, else the type rule's.
|
|
123
|
+
- `calendarFieldOf` — the column a calendar is laid out by: the settings' field, else the preferred one, else the first a person can edit.
|