@viewkitjs/views 0.0.0-stage → 0.2.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 +615 -0
- package/LICENSE.md +7 -0
- package/README.md +99 -2
- package/dist/atoms/CommandMenu.d.ts +2 -0
- package/dist/atoms/CommandMenu.js +20 -0
- package/dist/atoms/List.d.ts +2 -0
- package/dist/atoms/List.js +6 -0
- package/dist/atoms/LoadMore.d.ts +2 -0
- package/dist/atoms/LoadMore.js +25 -0
- package/dist/atoms/Loading.d.ts +2 -0
- package/dist/atoms/Loading.js +7 -0
- package/dist/atoms/PlatformMark.d.ts +2 -0
- package/dist/atoms/PlatformMark.js +4 -0
- package/dist/atoms/RelationLink.d.ts +2 -0
- package/dist/atoms/RelationLink.js +6 -0
- package/dist/atoms/Row.d.ts +3 -0
- package/dist/atoms/Row.js +30 -0
- package/dist/atoms/RowMenu.d.ts +2 -0
- package/dist/atoms/RowMenu.js +112 -0
- package/dist/atoms/StatusBadge.d.ts +2 -0
- package/dist/atoms/StatusBadge.js +7 -0
- package/dist/atoms/StatusMarker.d.ts +2 -0
- package/dist/atoms/StatusMarker.js +19 -0
- package/dist/atoms/Tag.d.ts +2 -0
- package/dist/atoms/Tag.js +13 -0
- package/dist/atoms/TickBox.d.ts +2 -0
- package/dist/atoms/TickBox.js +8 -0
- package/dist/atoms/defaults.d.ts +2 -0
- package/dist/atoms/defaults.js +27 -0
- package/dist/atoms/tones.d.ts +5 -0
- package/dist/atoms/tones.js +28 -0
- package/dist/atoms/types.d.ts +178 -0
- package/dist/atoms/types.js +3 -0
- package/dist/cells/cell-format.d.ts +138 -0
- package/dist/cells/cell-format.js +16 -0
- package/dist/cells/cell-title.d.ts +17 -0
- package/dist/cells/cell-title.js +8 -0
- package/dist/cells/cell-values.d.ts +28 -0
- package/dist/cells/cell-values.js +87 -0
- package/dist/cells/index.d.ts +4 -0
- package/dist/cells/index.js +4 -0
- package/dist/cells/legacy-field.d.ts +52 -0
- package/dist/cells/legacy-field.js +164 -0
- package/dist/cells/relation-wrap.d.ts +3 -0
- package/dist/cells/relation-wrap.js +24 -0
- package/dist/cells/use-cell-format.d.ts +5 -0
- package/dist/cells/use-cell-format.js +10 -0
- package/dist/contract.d.ts +461 -0
- package/dist/contract.js +682 -0
- package/dist/display/actor.d.ts +4 -0
- package/dist/display/actor.js +26 -0
- package/dist/display/boolean.d.ts +18 -0
- package/dist/display/boolean.js +43 -0
- package/dist/display/breakdown.d.ts +15 -0
- package/dist/display/breakdown.js +32 -0
- package/dist/display/currency.d.ts +9 -0
- package/dist/display/currency.js +29 -0
- package/dist/display/date.d.ts +12 -0
- package/dist/display/date.js +26 -0
- package/dist/display/display-cores.d.ts +31 -0
- package/dist/display/display-cores.js +57 -0
- package/dist/display/entity-chip.d.ts +26 -0
- package/dist/display/entity-chip.js +9 -0
- package/dist/display/format.d.ts +66 -0
- package/dist/display/format.js +190 -0
- package/dist/display/index.d.ts +8 -0
- package/dist/display/index.js +7 -0
- package/dist/display/link.d.ts +29 -0
- package/dist/display/link.js +50 -0
- package/dist/display/location.d.ts +8 -0
- package/dist/display/location.js +22 -0
- package/dist/display/multi-value.d.ts +18 -0
- package/dist/display/multi-value.js +28 -0
- package/dist/display/name.d.ts +6 -0
- package/dist/display/name.js +14 -0
- package/dist/display/number.d.ts +11 -0
- package/dist/display/number.js +27 -0
- package/dist/display/options.d.ts +153 -0
- package/dist/display/options.js +1 -0
- package/dist/display/percent.d.ts +4 -0
- package/dist/display/percent.js +40 -0
- package/dist/display/phone.d.ts +11 -0
- package/dist/display/phone.js +45 -0
- package/dist/display/range.d.ts +6 -0
- package/dist/display/range.js +29 -0
- package/dist/display/relation.d.ts +4 -0
- package/dist/display/relation.js +29 -0
- package/dist/display/rich-text.d.ts +10 -0
- package/dist/display/rich-text.js +34 -0
- package/dist/display/select.d.ts +6 -0
- package/dist/display/select.js +38 -0
- package/dist/display/text-class.d.ts +23 -0
- package/dist/display/text-class.js +5 -0
- package/dist/display/text.d.ts +19 -0
- package/dist/display/text.js +8 -0
- package/dist/display/use-display-options.d.ts +2 -0
- package/dist/display/use-display-options.js +14 -0
- package/dist/display/user.d.ts +11 -0
- package/dist/display/user.js +10 -0
- package/dist/display/value-list.d.ts +10 -0
- package/dist/display/value-list.js +12 -0
- package/dist/display/viewer.d.ts +4 -0
- package/dist/display/viewer.js +11 -0
- package/dist/display/web-href.d.ts +8 -0
- package/dist/display/web-href.js +12 -0
- package/dist/editors/ChipsEditor.d.ts +59 -0
- package/dist/editors/ChipsEditor.js +73 -0
- package/dist/editors/DateEditor.d.ts +25 -0
- package/dist/editors/DateEditor.js +122 -0
- package/dist/editors/LocationEditor.d.ts +22 -0
- package/dist/editors/LocationEditor.js +228 -0
- package/dist/editors/NameEditor.d.ts +22 -0
- package/dist/editors/NameEditor.js +92 -0
- package/dist/editors/NumberEditor.d.ts +67 -0
- package/dist/editors/NumberEditor.js +86 -0
- package/dist/editors/RangeEditor.d.ts +22 -0
- package/dist/editors/RangeEditor.js +70 -0
- package/dist/editors/RelationEditor.d.ts +65 -0
- package/dist/editors/RelationEditor.js +64 -0
- package/dist/editors/SelectEditor.d.ts +72 -0
- package/dist/editors/SelectEditor.js +59 -0
- package/dist/editors/ValueListEditor.d.ts +38 -0
- package/dist/editors/ValueListEditor.js +217 -0
- package/dist/editors/edit-cores.d.ts +83 -0
- package/dist/editors/edit-cores.js +38 -0
- package/dist/editors/edit-session.d.ts +74 -0
- package/dist/editors/edit-session.js +35 -0
- package/dist/editors/open-values.d.ts +28 -0
- package/dist/editors/open-values.js +26 -0
- package/dist/editors/relation-source.d.ts +66 -0
- package/dist/editors/relation-source.js +102 -0
- package/dist/fields/binding.d.ts +87 -0
- package/dist/fields/binding.js +117 -0
- package/dist/fields/currency.d.ts +82 -0
- package/dist/fields/currency.js +41 -0
- package/dist/fields/denomination.d.ts +42 -0
- package/dist/fields/denomination.js +11 -0
- package/dist/fields/edit-core-types.d.ts +40 -0
- package/dist/fields/edit-core-types.js +29 -0
- package/dist/fields/format-knobs.d.ts +34 -0
- package/dist/fields/format-knobs.js +36 -0
- package/dist/fields/menus.d.ts +28 -0
- package/dist/fields/menus.js +1 -0
- package/dist/fields/money.d.ts +60 -0
- package/dist/fields/money.js +78 -0
- package/dist/fields/number-edit.d.ts +11 -0
- package/dist/fields/number-edit.js +17 -0
- package/dist/fields/prepare-write.d.ts +55 -0
- package/dist/fields/prepare-write.js +67 -0
- package/dist/fields/relation-source-types.d.ts +54 -0
- package/dist/fields/relation-source-types.js +1 -0
- package/dist/figures.d.ts +52 -0
- package/dist/figures.js +63 -0
- package/dist/filters/date-filter.d.ts +2 -0
- package/dist/filters/date-filter.js +1 -0
- package/dist/filters/filter-model.d.ts +176 -0
- package/dist/filters/filter-model.js +41 -0
- package/dist/filters/number-filter.d.ts +2 -0
- package/dist/filters/number-filter.js +1 -0
- package/dist/filters/range-filter.d.ts +2 -0
- package/dist/filters/range-filter.js +1 -0
- package/dist/filters/registry.d.ts +103 -0
- package/dist/filters/registry.js +8 -0
- package/dist/filters/relation-filter.d.ts +16 -0
- package/dist/filters/relation-filter.js +53 -0
- package/dist/filters/text-filter.d.ts +2 -0
- package/dist/filters/text-filter.js +1 -0
- package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
- package/dist/grid/chrome/GridAddColumn.js +29 -0
- package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
- package/dist/grid/chrome/GridAggregateMenu.js +27 -0
- package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
- package/dist/grid/chrome/GridCellEditors.js +55 -0
- package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
- package/dist/grid/chrome/GridCellOutline.js +21 -0
- package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
- package/dist/grid/chrome/GridChipsEditor.js +40 -0
- package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
- package/dist/grid/chrome/GridColumnColorSection.js +40 -0
- package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
- package/dist/grid/chrome/GridColumnDateSection.js +23 -0
- package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
- package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
- package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
- package/dist/grid/chrome/GridColumnMenu.js +99 -0
- package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
- package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
- package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
- package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
- package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
- package/dist/grid/chrome/GridColumnSortSection.js +16 -0
- package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
- package/dist/grid/chrome/GridDateEditor.js +31 -0
- package/dist/grid/chrome/GridFlyout.d.ts +44 -0
- package/dist/grid/chrome/GridFlyout.js +80 -0
- package/dist/grid/chrome/GridFooter.d.ts +23 -0
- package/dist/grid/chrome/GridFooter.js +81 -0
- package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
- package/dist/grid/chrome/GridGroupMenu.js +57 -0
- package/dist/grid/chrome/GridHeader.d.ts +61 -0
- package/dist/grid/chrome/GridHeader.js +37 -0
- package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
- package/dist/grid/chrome/GridLongTextEditor.js +127 -0
- package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
- package/dist/grid/chrome/GridMenuRow.js +15 -0
- package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
- package/dist/grid/chrome/GridNameEditor.js +36 -0
- package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
- package/dist/grid/chrome/GridNumberEditor.js +25 -0
- package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
- package/dist/grid/chrome/GridRangeEditor.js +25 -0
- package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
- package/dist/grid/chrome/GridRelationEditor.js +30 -0
- package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
- package/dist/grid/chrome/GridResizeHandle.js +19 -0
- package/dist/grid/chrome/GridRow.d.ts +25 -0
- package/dist/grid/chrome/GridRow.js +136 -0
- package/dist/grid/chrome/GridRowActions.d.ts +32 -0
- package/dist/grid/chrome/GridRowActions.js +25 -0
- package/dist/grid/chrome/GridRowCells.d.ts +4 -0
- package/dist/grid/chrome/GridRowCells.js +133 -0
- package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
- package/dist/grid/chrome/GridRowGlyph.js +13 -0
- package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
- package/dist/grid/chrome/GridSelectEditor.js +49 -0
- package/dist/grid/chrome/GridStructure.d.ts +48 -0
- package/dist/grid/chrome/GridStructure.js +45 -0
- package/dist/grid/chrome/GridTable.d.ts +4 -0
- package/dist/grid/chrome/GridTable.js +125 -0
- package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
- package/dist/grid/chrome/GridTableSurface.js +6 -0
- package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
- package/dist/grid/chrome/GridTextEditor.js +40 -0
- package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
- package/dist/grid/chrome/GridValueListEditor.js +36 -0
- package/dist/grid/chrome/StuckMarker.d.ts +16 -0
- package/dist/grid/chrome/StuckMarker.js +34 -0
- package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
- package/dist/grid/chrome/cell-clipboard.js +28 -0
- package/dist/grid/chrome/cells.d.ts +21 -0
- package/dist/grid/chrome/cells.js +20 -0
- package/dist/grid/chrome/checks.d.ts +35 -0
- package/dist/grid/chrome/checks.js +22 -0
- package/dist/grid/chrome/column-glyph.d.ts +14 -0
- package/dist/grid/chrome/column-glyph.js +44 -0
- package/dist/grid/chrome/editors.d.ts +9 -0
- package/dist/grid/chrome/editors.js +10 -0
- package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
- package/dist/grid/chrome/grid-cell-classes.js +30 -0
- package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
- package/dist/grid/chrome/grid-menu-search.js +7 -0
- package/dist/grid/chrome/grid-row-props.d.ts +131 -0
- package/dist/grid/chrome/grid-row-props.js +1 -0
- package/dist/grid/chrome/grid-styles.d.ts +37 -0
- package/dist/grid/chrome/grid-styles.js +8 -0
- package/dist/grid/chrome/grid-table-props.d.ts +173 -0
- package/dist/grid/chrome/grid-table-props.js +1 -0
- package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
- package/dist/grid/chrome/useGridBatchApi.js +35 -0
- package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
- package/dist/grid/chrome/useGridColumnLayout.js +206 -0
- package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
- package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
- package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
- package/dist/grid/chrome/useGridKeyboard.js +274 -0
- package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
- package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
- package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
- package/dist/grid/chrome/useGridRailReveal.js +67 -0
- package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
- package/dist/grid/chrome/useGridRangeActions.js +188 -0
- package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
- package/dist/grid/chrome/useGridRangeGestures.js +190 -0
- package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
- package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
- package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
- package/dist/grid/chrome/useGridScaleStyles.js +29 -0
- package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
- package/dist/grid/chrome/useGridScrollSync.js +176 -0
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
- package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
- package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
- package/dist/grid/chrome/useGridTableSelection.js +55 -0
- package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
- package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
- package/dist/grid/core/clipboard-model.d.ts +81 -0
- package/dist/grid/core/clipboard-model.js +291 -0
- package/dist/grid/core/column-values.d.ts +27 -0
- package/dist/grid/core/column-values.js +76 -0
- package/dist/grid/core/commit-model.d.ts +34 -0
- package/dist/grid/core/commit-model.js +3 -0
- package/dist/grid/core/coordinates.d.ts +48 -0
- package/dist/grid/core/coordinates.js +27 -0
- package/dist/grid/core/edit-values.d.ts +9 -0
- package/dist/grid/core/edit-values.js +1 -0
- package/dist/grid/core/editing-controller.d.ts +59 -0
- package/dist/grid/core/editing-controller.js +240 -0
- package/dist/grid/core/editing-model.d.ts +78 -0
- package/dist/grid/core/editing-model.js +136 -0
- package/dist/grid/core/grid-scale.d.ts +14 -0
- package/dist/grid/core/grid-scale.js +8 -0
- package/dist/grid/core/nav.d.ts +94 -0
- package/dist/grid/core/nav.js +92 -0
- package/dist/grid/core/pending-reconciliation.d.ts +50 -0
- package/dist/grid/core/pending-reconciliation.js +49 -0
- package/dist/grid/core/range-model.d.ts +25 -0
- package/dist/grid/core/range-model.js +59 -0
- package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
- package/dist/grid/core/spreadsheet-operations.js +253 -0
- package/dist/grid/core/useGridEditing.d.ts +43 -0
- package/dist/grid/core/useGridEditing.js +90 -0
- package/dist/grid/core/useGridRange.d.ts +20 -0
- package/dist/grid/core/useGridRange.js +24 -0
- package/dist/grid/core/value-equality.d.ts +32 -0
- package/dist/grid/core/value-equality.js +34 -0
- package/dist/grid/index.d.ts +18 -0
- package/dist/grid/index.js +5 -0
- package/dist/grid/useGridTablePrefs.d.ts +50 -0
- package/dist/grid/useGridTablePrefs.js +101 -0
- package/dist/grouping/sort-groups.d.ts +18 -0
- package/dist/grouping/sort-groups.js +33 -0
- package/dist/grouping/types.d.ts +10 -0
- package/dist/grouping/types.js +1 -0
- package/dist/index.d.ts +28 -0
- package/dist/index.js +28 -0
- package/dist/internal/chip.d.ts +4 -0
- package/dist/internal/chip.js +3 -0
- package/dist/internal/cx.d.ts +3 -0
- package/dist/internal/cx.js +3 -0
- package/dist/internal/viewport.d.ts +5 -0
- package/dist/internal/viewport.js +29 -0
- package/dist/model/aggregates.d.ts +59 -0
- package/dist/model/aggregates.js +186 -0
- package/dist/model/card-density.d.ts +8 -0
- package/dist/model/card-density.js +10 -0
- package/dist/model/card-layout.d.ts +85 -0
- package/dist/model/card-layout.js +90 -0
- package/dist/model/column-capabilities.d.ts +162 -0
- package/dist/model/column-capabilities.js +233 -0
- package/dist/model/column-filters.d.ts +106 -0
- package/dist/model/column-filters.js +321 -0
- package/dist/model/column-format.d.ts +103 -0
- package/dist/model/column-format.js +1 -0
- package/dist/model/column-from.d.ts +28 -0
- package/dist/model/column-from.js +160 -0
- package/dist/model/column-inspect.d.ts +18 -0
- package/dist/model/column-inspect.js +6 -0
- package/dist/model/column-knobs.d.ts +20 -0
- package/dist/model/column-knobs.js +16 -0
- package/dist/model/column-money.d.ts +13 -0
- package/dist/model/column-money.js +27 -0
- package/dist/model/column-order.d.ts +36 -0
- package/dist/model/column-order.js +68 -0
- package/dist/model/column-schema.d.ts +335 -0
- package/dist/model/column-schema.js +1 -0
- package/dist/model/column-sort.d.ts +17 -0
- package/dist/model/column-sort.js +11 -0
- package/dist/model/column-state.d.ts +77 -0
- package/dist/model/column-state.js +95 -0
- package/dist/model/column-types.d.ts +109 -0
- package/dist/model/column-types.js +50 -0
- package/dist/model/column-warnings.d.ts +44 -0
- package/dist/model/column-warnings.js +24 -0
- package/dist/model/density.d.ts +3 -0
- package/dist/model/density.js +13 -0
- package/dist/model/field-type-of.d.ts +21 -0
- package/dist/model/field-type-of.js +11 -0
- package/dist/model/filter-capabilities.d.ts +1 -0
- package/dist/model/filter-capabilities.js +1 -0
- package/dist/model/index.d.ts +38 -0
- package/dist/model/index.js +20 -0
- package/dist/model/part-rows.d.ts +28 -0
- package/dist/model/part-rows.js +40 -0
- package/dist/model/preferences.d.ts +155 -0
- package/dist/model/preferences.js +84 -0
- package/dist/model/prefs-buckets.d.ts +173 -0
- package/dist/model/prefs-buckets.js +71 -0
- package/dist/model/relation-filters.d.ts +45 -0
- package/dist/model/relation-filters.js +78 -0
- package/dist/model/render-count.d.ts +2 -0
- package/dist/model/render-count.js +24 -0
- package/dist/model/row-icon.d.ts +23 -0
- package/dist/model/row-icon.js +5 -0
- package/dist/model/view-rules.d.ts +73 -0
- package/dist/model/view-rules.js +216 -0
- package/dist/provider/ViewsProvider.d.ts +26 -0
- package/dist/provider/ViewsProvider.js +16 -0
- package/dist/provider/components.d.ts +230 -0
- package/dist/provider/components.js +3 -0
- package/dist/provider/context.d.ts +20 -0
- package/dist/provider/context.js +10 -0
- package/dist/provider/icons.d.ts +6 -0
- package/dist/provider/icons.js +1 -0
- package/dist/provider/menu-groups.d.ts +8 -0
- package/dist/provider/menu-groups.js +38 -0
- package/dist/provider/ports.d.ts +57 -0
- package/dist/provider/ports.js +9 -0
- package/dist/react.d.ts +9 -0
- package/dist/react.js +4 -0
- package/dist/selection/SelectCheckbox.d.ts +17 -0
- package/dist/selection/SelectCheckbox.js +11 -0
- package/dist/selection/index.d.ts +7 -0
- package/dist/selection/index.js +6 -0
- package/dist/selection/model.d.ts +55 -0
- package/dist/selection/model.js +86 -0
- package/dist/selection/row-click.d.ts +35 -0
- package/dist/selection/row-click.js +20 -0
- package/dist/selection/types.d.ts +17 -0
- package/dist/selection/types.js +1 -0
- package/dist/selection/useCheckDragSelect.d.ts +61 -0
- package/dist/selection/useCheckDragSelect.js +165 -0
- package/dist/selection/useListSelection.d.ts +39 -0
- package/dist/selection/useListSelection.js +48 -0
- package/dist/selection/useListSelectionShortcuts.d.ts +6 -0
- package/dist/selection/useListSelectionShortcuts.js +14 -0
- package/dist/selection/useRestIntent.d.ts +18 -0
- package/dist/selection/useRestIntent.js +35 -0
- package/docs/contract.md +525 -0
- package/docs/getting-started.md +250 -0
- package/docs/guides/atoms.md +245 -0
- package/docs/guides/cells.md +302 -0
- package/docs/guides/columns.md +412 -0
- package/docs/guides/display.md +203 -0
- package/docs/guides/editors.md +404 -0
- package/docs/guides/ports.md +246 -0
- package/docs/guides/selection.md +270 -0
- package/docs/guides/the-grid.md +677 -0
- package/docs/guides/the-provider.md +446 -0
- package/docs/index.md +50 -0
- package/docs/install.md +67 -0
- package/docs/reference/cells.md +28 -0
- package/docs/reference/display.md +42 -0
- package/docs/reference/editors-chips.md +6 -0
- package/docs/reference/editors-date.md +6 -0
- package/docs/reference/editors-location.md +10 -0
- package/docs/reference/editors-name.md +6 -0
- package/docs/reference/editors-number.md +11 -0
- package/docs/reference/editors-open-values.md +9 -0
- package/docs/reference/editors-range.md +6 -0
- package/docs/reference/editors-relation.md +9 -0
- package/docs/reference/editors-select.md +8 -0
- package/docs/reference/editors-session.md +9 -0
- package/docs/reference/editors-value-list.md +6 -0
- package/docs/reference/editors.md +5 -0
- package/docs/reference/grid.md +39 -0
- package/docs/reference/react.md +86 -0
- package/docs/reference/selection.md +33 -0
- package/docs/reference/views.md +601 -0
- package/docs/reshaping.md +19 -0
- package/package.json +118 -3
- package/skills/views/SKILL.md +102 -0
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/chips`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/chips` in a client component: the door opens with the client directive. It holds the editor of a `multiselect` field, a value that is several values. The chosen values stay on screen while you edit them, as the very tags the cell draws, and adds and removes build a draft that commits once when the host closes the panel: several tags are one write and one undo step. A pick adds a value and keeps the panel open, so this editor never sees the `pick` reason. It owns the field of chips, the list and what a close means; its host owns the popover, the anchor and the write. It commits the list of values, a `string[]`. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `ChipsEditor` — the chips panel; its ref is a `ChipsEditorHandle`. Its top zone is a field holding the chosen values as tags, each with its remove, and the input among them, focused without scrolling; Backspace in an empty input takes the last chip. Below it are the values on offer, those not already chosen, filtered on their labels as you type, and a row that adds the typed text when no chosen or offered value is it, ignoring case. It takes `values` (what the cell holds), `suggestions` (what the column already holds, the same list its filter offers), `resolve` (one value's label and colour as a `PickerOption`, including a value just typed), `onRequestClose` (called with `escape`) and `message`, and optionally `normalize`, the rule every added value goes through (default: trimmed).
|
|
6
|
+
- `ChipsEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Its close rule is the odd one out: Escape discards, and any other close, an outside click included, commits the list when it differs from `values` (compared as fields compares a list) and is a `noop` when it doesn't.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/date`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/date` in a client component: the door opens with the client directive. It holds the editor of a `date` and a `datetime` field: a value bar with a typeable date and a time chip, above your app's calendar. It owns the value bar, the calendar, the lenient reading of a typed date and the draft; its host owns the popover, the anchor and when a close means commit. It commits `YYYY-MM-DD` when no time is set, or `YYYY-MM-DDTHH:MM` in local time. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `DateEditor` — the date panel; its ref is a `DateEditorHandle`. The date box reads a typed date day first and writes it back as `dd/mm/yyyy`; the time chip offers quick picks every 15 minutes; the calendar is the pointer path to the same day, with a year picker from 1900 to ten years ahead (a typed date outside it still lands). It takes `initial` (the stored value, a full ISO string or `YYYY-MM-DD`, which picks the day and the month it opens on), `onRequestClose` (Enter means done and Escape means leave; the panel never closes itself) and `message` (the fields message resolver, defaulting to the provider's conventions). With `timeOptional` the time chip starts empty and stays out of the commit until set; without it the chip carries the stored time, or 00:00, and every commit includes one. With no stored value the box starts on today, and a close with no interaction writes nothing.
|
|
6
|
+
- `DateEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. For a date every close means the same thing: commit the draft when it differs from the stored value, `noop` otherwise, with text still typed in the date box read first. It takes the reason and does not read it; telling reasons apart is the host's.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/location`
|
|
2
|
+
|
|
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
|
+
|
|
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` and `conventions` (whose locale names the countries and picks each country's format; default: the provider's).
|
|
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
|
+
- 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
|
+
- 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
|
+
- 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.
|
|
10
|
+
- `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.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/name`
|
|
2
|
+
|
|
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
|
+
|
|
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 `conventions`.
|
|
6
|
+
- `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.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/number`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/number` in a client component: the door opens with the client directive. It holds the editor of a `number`, `percent` and `currency` field. It is inline: it replaces the cell's own content rather than opening a panel over it, so its closes are the keyboard's and the blur's (Enter, Tab, Shift-Tab, Escape, a blur) and never `outside`. It owns the input, the reading of what is typed, and the unit chip with its own popover, which never blurs the input into a commit. Its host owns where it mounts and the write. It commits a `NumberEditValue`. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `NumberEditor` — the number input, focused without scrolling; its ref is a `NumberEditorHandle`. It takes `initial` (the signed stored value), `onRequestClose`, and optionally:
|
|
6
|
+
- Text: `seed`, the character that opened the editor, replacing the text while `initial` stays the value it compares against; `decimals`, the rounding and the opening precision in the stored unit (default 2, and 0 for a whole-number field); `conventions`, how your people write a number (default: the provider's); `allowEmpty`, which makes a blank input a real null commit.
|
|
7
|
+
- Unit: `unit`, the row's currency, drawn as a chip; `unitOptions`, which make the chip a picker; `unitLeft`, the chip before the figure.
|
|
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
|
+
- Layout: `align`, `end` (the default, a right-aligned column) or `start` (a row read left to right, with the chip following the figure).
|
|
10
|
+
- `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
|
+
- `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.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/open-values`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/open-values` in a client component: the door opens with the client directive. An open pick-list (a field whose vocabulary is `custom-values`) has no options of its own: its values are whatever its records hold, which your app's list answers. This door carries those values to every editor of the field: your app provides them above a surface (a record's panel, a list's body), and the panel row, the grid cell and the card read them, so a field offers the same values wherever it is edited. A host asks for a field's values once, when its editor mounts. A closed field, or no provider, reads none and asks nothing. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `OpenValuesProvider` — provides its `value`, an `OpenValues` or undefined, to the editors below it.
|
|
6
|
+
- `OpenValues` — what the provider holds: `values`, field key to the values the list answered for it, most used first; `labels`, field key to value to its name, for the named values of a relation, user or actor field; and `onWanted(fieldKey)`, called when an editor of an open field opens, so your app may fetch its values.
|
|
7
|
+
- `useOpenValues` — the values an open field holds, as the nearest provider knows them, given the field or undefined. It calls the provider's `onWanted` with the field's key when it mounts, and returns an empty list for a closed field, no field or no provider.
|
|
8
|
+
- `useOpenValuesContext` — the nearest provider's `OpenValues` whole, or undefined: what a host hands `buildRelationFilters` as `farValues`.
|
|
9
|
+
- `offeredValues` — what an editor offers, each value once: given a field, the known values and those seen on screen (default none), it returns the field's declared options, then the known values, then the seen ones.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/range`
|
|
2
|
+
|
|
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
|
+
|
|
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`) and `conventions` (how a number is written; default: the provider's).
|
|
6
|
+
- `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.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/relation`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/relation` in a client component: the door opens with the client directive. It holds the picker for a link, the editor of a `relation` and a `user` field: search the candidates, pick one, and it replaces the link. The candidates are the host's, through a `RelationSource`: a static list the panel filters on its labels, or a remote search your function answers a page at a time. The panel owns the search box, the rows, the paging (it waits before a typed query searches, drops an answer a newer query superseded, asks for the next page as the end of the list scrolls into view, and says when it is searching, failed or found nothing) and what a close means: a pick is the commit, every other close discards. It never does the asking itself, so access stays in your function's closure. Its host owns the popover, the anchor and the write. It commits the picked id, or null for None. The door also re-exports `RelationCandidate`, `RelationSearch` and `RelationSource`, which are documented with the root door. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `RelationEditor` — the relation-picking panel, built from your app's command list; its ref is a `RelationEditorHandle`. It takes `candidates` (the `RelationSource`), `initial` (the linked id, or null), `clearable` (a None row for a link the surface says is optional, hidden while a query is typed), `onRequestClose` (called with `pick` when someone chooses), `kindGlyph` (the glyph worn by every candidate with no icon of its own; given, every row keeps a glyph lane so the labels line up), `noneLabel` (the surface's words for the None row), `message` (the fields message resolver, defaulting to the provider's conventions) and `creates` (`RelationCreate` rows pinned under the list). A candidate's `sublabel` draws as a muted second line and its `badge` as a small chip at the row's end.
|
|
6
|
+
- `RelationEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked id, or null for None, only for `pick` and only when it differs from `initial`; `noop` for a `pick` with nothing picked or the link already held; `cancel` for every other reason.
|
|
7
|
+
- `RelationCreate` — a row pinned under the list for a record that isn't in it yet: `label(query)` gives its words from the trimmed query, and `onCreate(query)` runs after the host has been asked to close, so your own create form opens with what was typed. A click on it is a `pick` that resolves `noop`: nothing is written.
|
|
8
|
+
- `RELATION_SEARCH_DEBOUNCE_MS` — 200: how many milliseconds a typed query waits before a remote search runs. The empty query runs at once, so the panel opens on a first page.
|
|
9
|
+
- `RELATION_PAGE_SIZE` — 20: the rows per page when a remote source names no `pageSize`. A page shorter than the size ends the list.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/select`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/select` in a client component: the door opens with the client directive. It holds the picker for one value out of a set, the editor of a `select` and a `status` field. The panel draws each option as your app's row with its badge or tag and owns what a close means: a pick is the commit, and every other close discards. Its host owns the popover, the anchor, the exit gap and the write. It commits the picked option's `value`, a string, and `""` for None, which a host maps to null. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `SelectEditor` — the option-picking panel; its ref is a `SelectEditorHandle`. It takes `options` (`PickerOption`s in display order, colours already resolved), `initial` (the value the surface holds, checked in the list), `clearable` (a None row first, for a value the surface says is optional), `onRequestClose` (called with `pick` when someone chooses) and `message` (the fields message resolver, defaulting to the provider's conventions). With `creatable`, for an open select, it adds a search over the option labels and, after the matches, a row that uses the typed text when no option's value is it, ignoring case; Enter picks the first match, and picking the row commits the trimmed text.
|
|
6
|
+
- `SelectEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked value only for `pick`, and only when the pick differs from `initial` (`""` and null are the same absence); `noop` for a `pick` with nothing picked or the value already held; `cancel` for every other reason, so Escape and an outside click discard.
|
|
7
|
+
- `PickerOption` — one option as the panel draws it: its `value` and `label`, and a `slot` (a status's lifecycle state, drawn as your status badge) or a `color` (a category colour, drawn as your tag), or neither for a plain label. `icon` names your app's glyph, drawn before the label. Colours are resolved by the caller, never by the panel.
|
|
8
|
+
- `pickerOptionsFromField` — a select or status field's options dressed the way its cells draw them, so a pick in a form looks like the grid. Archived options are left out. A status keeps each option's slot (`muted` when it names none); a select takes the category colour chain: your `optionColors` overrides, then the field's own colour, then the derived hue. Each option's icon is carried. `extraValues` adds values your rows hold that no option names, labelled with their raw code, so a stray value can be picked back; an archived value stays out.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/session`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/session` in a client component: the door opens with the client directive. It holds the plumbing every host that opens an editor in a panel over a value repeats: the guard that lets a session answer once, and the gap that lets the popover's exit play before the value renders again behind it. A session that answers twice writes twice, and one that answers during its own exit unmounts the panel mid-flight. The host keeps its popover, its anchor, its focus and the shape of what it hands back. It is a door of its own so a host that needs the session does not load the editors. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `useAnchoredEditSession` — runs one edit session and returns `{ open, close }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts. On it the session asks the editor's `resolveClose(reason)` through `editorRef` (a `noop` when there is no editor) and passes a commit's value through `mapPayload`, which never sees a cancel or a noop. Then one of two modes:
|
|
6
|
+
- Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns `{ accepted }`. A refusal keeps the session open for another try; an acceptance closes it and calls `onClose` after the exit gap, a timer cleared if the host unmounts.
|
|
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
|
+
- Gap: `exitMs` sets it, defaulting to `EDITOR_EXIT_MS`.
|
|
9
|
+
- `EDITOR_EXIT_MS` — 160: the milliseconds an anchored host waits between closing its popover and reporting its answer, so the exit animation plays out first.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/value-list`
|
|
2
|
+
|
|
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
|
+
|
|
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. 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` and `region` (the record's country, where a phone typed without its country code is read; else the conventions' region).
|
|
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.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors`
|
|
2
|
+
|
|
3
|
+
The table of editors, one per storage type. The door carries no client directive; each editor file behind it carries its own, and each editor also has a door of its own, which a host imports when it needs one editor and not the table. An editor owns its panel and what a close means. Its host (a grid cell, a form field, a drawer row, a card) owns the popover, the anchor, focus, when to commit, and the write. Every editor speaks the same handshake: when it sees a key or a pick that means done, it calls the host's `onRequestClose(reason)`; the host closes, then asks the editor's handle `resolveClose(reason)`, which answers `commit` with the value, `cancel` or `noop` (the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`). The words an editor draws come from the provider; an editor that takes `message` reads the fields messages from it instead. `hasEditCore`, documented with the root door, says whether a type opens a panel at all without loading any editor. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `EDIT_CORES` — the editor for each storage type, one member for every `FieldType`, so a type added to fields with no answer here fails to compile. `date` and `datetime` share `DateEditor`, `select` and `status` share `SelectEditor`, `multiselect` is `ChipsEditor`, `relation` and `user` share `RelationEditor`, `number`, `percent` and `currency` share `NumberEditor`, and `range`, `name` and `location` each have their own. A `null` member is a decision, not a gap: `text`, `url`, `domain`, `email` and `phone` are a bare input the host already owns, a `boolean` is edited by its checkbox, an `actor` is set by the system, `rich_text` is edited as markdown in the host's own text box, and `lookup`, `rollup` and `formula` are read-only or derived. Each member is typed as its editor's props and handle, so binding the wrong editor is a type error. `ValueListEditor`, for a field holding several emails, phones, links or domains, has its own door and no member here.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# `@viewkitjs/views/grid`
|
|
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 selection bar, the house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. Guide: [the grid](../guides/the-grid.md).
|
|
4
|
+
|
|
5
|
+
## The grid
|
|
6
|
+
|
|
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
|
+
- `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). 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 yours).
|
|
11
|
+
- Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `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
|
+
- 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, the grid's own lists the hidden columns), `renderColumnMenuRows` (your rows in a column's menu, above Hide), and the per-user toggles `freezeIdentity` (default true), `wrapCells`, `alwaysCheckboxes`, `verticalBorders` and `scale`.
|
|
14
|
+
- Writes: `onCellCommit` (`GridCellCommitFn`) and `onCellsCommit` (`GridCellsCommitFn`).
|
|
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
|
+
- `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, wrapping, 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
|
+
|
|
18
|
+
## Sort, group and figures
|
|
19
|
+
|
|
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.
|
|
21
|
+
- `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
|
+
- `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
|
+
- `GridGroupFigure` — one figure a group's header can show: the summary `part` that turns it on, its column's header as its `label`, and `render(group)`, how it draws for a group.
|
|
24
|
+
- `GroupCountNoun` — a group count's noun, `{ one, other }`, so a header reads "2 companies"; without one the count is bare.
|
|
25
|
+
|
|
26
|
+
## Writes
|
|
27
|
+
|
|
28
|
+
- `GridCellCommitFn` — writes one cell: `(row, columnId, value, context?)`, returning a promise of nothing or a `GridCommitOutcome`. Nothing counts as confirmed; a rejection rolls the cell back. `context` is present on an undo or a redo.
|
|
29
|
+
- `GridCellsCommitFn` — writes several cells at once (a paste, a fill, an undo of several): `(edits)`, each `{ row, columnId, value, context? }`, returning a promise of nothing or one outcome per edit, in order. A failed edit rolls its own cell back. Without it, or for a single cell, the grid calls `GridCellCommitFn` for each.
|
|
30
|
+
- `GridCommitContext` — what a write is: `{ kind: "commit" }`, with `reload: false` when the caller reloads once after a second write, or `{ kind: "restore", expected }`, an undo or a redo writing a value back, `expected` the value the cell is held to before it.
|
|
31
|
+
- `GridCommitOutcome` — how a write ended. `confirmed`, with an optional `history` (false keeps it out of undo, or `{ prev, next }` are the values undo and redo write instead) and `settlement` (`requested`: the row holds the value but its provider has not accepted it yet, and the cell says so); `unconfirmed`, never in the undo history; or `failed`, with an optional `error`, which rolls the cell back.
|
|
32
|
+
|
|
33
|
+
## Helpers a binding shares
|
|
34
|
+
|
|
35
|
+
- `deriveGridSelectValues` — the values each select, status and multiselect column offers, given the columns and the rows: column id to values. A status offers its options; a select or multiselect offers its options, then the values the rows hold, each once. Archived values are left out unless `includeArchived` is set, as a filter sets it so a row still holding a retired value can be found.
|
|
36
|
+
- `deriveGridRelationValues` — the relations present in the loaded rows, given the columns and the rows: column id to `ListRelationValue`s, each once, sorted by label, for every relation, user and actor column (an actor's id is its key). It reads the rows, never the candidates a column can link to, so a filter lists only what the table holds.
|
|
37
|
+
- `cellEditBaseline` — the value an edit of a cell starts from: the column's pending value when one is given, else the column's `editAccessor`, else its `accessor`.
|
|
38
|
+
- `cellCopyText` — a cell's value as copied text, given its column and its baseline (from `cellEditBaseline`), which a CSV export can reuse. Empty for no value; a relation or an actor copies as its name, not its id; a select, status or multiselect copies as its options' labels, not their keys; a place, a name and a range copy as their cells write them; a list copies its items joined by commas, several values of one kind their values, the main one first.
|
|
39
|
+
- `GRID_TITLE_LINK_CLASS` — the class that dresses the row-open text inside a title cell (the element carrying `data-cell-open`) as a link on its own hover: the brand colour and an underline.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# `@viewkitjs/views/react`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/react` in a client component: the door opens with the client directive, and every name behind it is a client-side thing. It holds the provider your app mounts once above its views, the types your adapter implements (the components map, the icons, the ports), and the atoms the rendering is built from. It also re-exports five names of the root door, `ComponentName`, `PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`; those are documented on the root's page, [views](views.md), not here. The model half of the package, with no React at runtime, is `@viewkitjs/views`.
|
|
4
|
+
|
|
5
|
+
## The provider
|
|
6
|
+
|
|
7
|
+
Guide: [the provider](../guides/the-provider.md).
|
|
8
|
+
|
|
9
|
+
- `ViewsProvider` — the provider every view reads: mount it once at your app's client root, above every view, with its components, icons, ports and conventions. It lays your atoms over the defaults, hands your `Menu` its items with every row under a disabled group already disabled, and fills in the browser's own confirm where your ports carry no `confirm`. It hands its views one context value per distinct set of inputs, so pass module-level objects: a new one on each render re-renders every view.
|
|
10
|
+
- `ViewsProviderProps` — what the provider takes.
|
|
11
|
+
- Required: `components` (your primitives, `ViewsComponents`), `icons` (your glyphs by meaning, `ViewsIcons`), `ports` (your runtime services, `ViewsPorts`), `conventions` (the `FieldConventions` of `@viewkitjs/fields` every value is read with) and `children`.
|
|
12
|
+
- Optional: `atoms`, any of your own atoms, each laid over the default of its name; `messages`, your wording for the package's own messages, defaulting to `resolveViewsMessage` (the package's English); `presentation`, `(defaults: FieldPresentation) => FieldPresentation`, how your numbers, dates and durations read: given the package's defaults in the conventions' locale, return yours. It is called where a value is drawn, so your provider imports none of the display.
|
|
13
|
+
- `useViews` — reads the nearest provider's value inside a view or an atom of your own. It throws an error that says where to mount one when no `ViewsProvider` is above it.
|
|
14
|
+
- `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`, and your `presentation` when you handed one.
|
|
15
|
+
- `NOOP_PORTS` — ports that do nothing, for a server render, a test or an app without a device: the toasts and haptics are empty, the clipboard writes nothing (resolving `false`) and reads `null`, and the prefs store keeps nothing. It carries no `confirm`, so the provider falls back to the browser's.
|
|
16
|
+
|
|
17
|
+
## The components map
|
|
18
|
+
|
|
19
|
+
The primitives your app hands in, modelled on Base UI's shapes: a controlled `open` with `onOpenChange(open, details)`, an `anchor` rather than a trigger child on the popover and the menu, and no `asChild`. An adapter on Base UI wraps its copies thinly; one on Radix absorbs the difference. The package ships none of them and depends on neither library. The [contract](../contract.md) says what each slot promises and how to write an adapter.
|
|
20
|
+
|
|
21
|
+
- `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself.
|
|
22
|
+
- `ViewsButtonProps` — a button: its `children`, `onClick`, `disabled`, a `variant` (`default`, `ghost`, `outline`, `destructive`), a `size` (`default`, `sm`, `icon`), its `type`, a class, `aria-label` and `title`.
|
|
23
|
+
- `ViewsPopoverProps` — a popover opened at an `anchor`, controlled by `open` and `onOpenChange`, placed by `side`, `align`, `sideOffset` and `alignOffset`.
|
|
24
|
+
- Focus: `initialFocus` false keeps focus where it was when the popup opens, for an editor that focuses its own input (with `preventScroll`). Default true.
|
|
25
|
+
- Vetoes: `onOutsidePress` is handed the pointer press, its `target` where it landed, and returns `false` to keep the popup open, also against the focus that press moves; focus leaving by keyboard closes without asking. `onEscape` does the same for Escape.
|
|
26
|
+
- Look: `chrome` is `panel` (your card popover, the default) or `menu` (your menu panel's surface, for a popover that holds a list: no inset, no card width). `onPanelClick` takes a click inside the popup, `panelData` sets `data-*` attributes on it, and `style` carries what a class cannot say, such as a width that follows a cell.
|
|
27
|
+
- `ViewsTooltipProps` — a tooltip around the element it wraps (`children`), showing `content`, with `side`, `align`, `delayMs` and a class. Your app mounts one tooltip provider above the views; a tooltip never mounts its own.
|
|
28
|
+
- `ViewsCheckboxProps` — a checkbox: `checked`, and `indeterminate` for a box ticked partly, whose press hands `true` while `checked` is false. `onCheckedChange` hands the new value and, where your library reports it, `{ event }`, the press that changed it (a list reads its shift key for a range). `partialTone` colours the partial mark, `muted` by default or `brand` for a select-all with a live selection; with `disabled`, a class, `tabIndex` and `aria-label`.
|
|
29
|
+
- `ViewsMenuProps` — a menu opened at an `anchor`, with no trigger child and no flyouts, controlled by `open` and `onOpenChange`, drawing its `items` and placed by `side` and `align`. On Base UI it is the menu's root, positioner and popup, the anchor handed to the positioner.
|
|
30
|
+
- `ViewsMenuItem` — one row of a menu, as data your `Menu` draws: its `key`, `label`, `icon`, `onSelect`, `disabled` and `destructive`, a `separatorBefore`, a `shortcut` hint drawn at its end and never bound, and an `href` that makes it a link (with `onSelect` still firing). A `checked` row is checkable and closes the menu like any row. A row with `children` is a group: its rows drawn in place under its label, never a flyout, its own `onSelect`, `href` and `checked` ignored; a disabled group's rows reach your `Menu` already `disabled`.
|
|
31
|
+
- `ViewsCommandParts` — the command list's parts, the shape cmdk-based copies already have: `Root` (taking `label`, `shouldFilter` false to hand filtering to the host, a scoring `filter`, and `loop` to wrap the arrows), `Input` (a controlled `value` with `onValueChange`, a `placeholder`, `autoFocus`, a `ref`, `onKeyDown`, and `chrome` `search` for your search row or `bare` for the input alone), `List`, `Empty`, `Group` (with a `heading`) and `Item` (a `value`, `onSelect`, `disabled`, and `chosen`, which you colour as your chosen row while the package's row inside draws the check).
|
|
32
|
+
- `ViewsCalendarProps` — a calendar over ISO days (`YYYY-MM-DD`): its `value` and `onChange`, `min` and `max`, a `month` (`YYYY-MM`) controlled with `onMonthChange`, a `captionLayout` of `label` or `dropdown`, the `startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it draws its month and weekday names and starts its week (an adapter may keep its calendar's own). Your date library stays your own.
|
|
33
|
+
- `ViewsCollapseProps` — a box that opens and closes its `children` with `open`, over `durationMs`, with a class and a `clipClassName` on the box that crops the content.
|
|
34
|
+
- `ViewsSheetProps` — a phone sheet, controlled by `open` and `onOpenChange`, with a `title`, a `description`, a class, its `children`, and `snap` (`full`, `half`, `peek`, `auto`), a hint a sheet with no snap points ignores.
|
|
35
|
+
- `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
|
|
36
|
+
- `ViewsSide` — the side a floating part opens on: `top`, `right`, `bottom` or `left`.
|
|
37
|
+
- `ViewsAlign` — how a floating part lines up along that side: `start`, `center` or `end`.
|
|
38
|
+
- `ViewsCloseReason` — why a floating part closed, by Base UI's names: `trigger-press`, `outside-press`, `escape-key`, `focus-out`, `item-press`, `close-press` (a close button inside it), `swipe` (a sheet dragged away), and `none` for any other reason your library reports.
|
|
39
|
+
- `ViewsOpenChange` — the `onOpenChange` callback a popover, a menu and a sheet take: the new open state, and optional details carrying its `reason`.
|
|
40
|
+
|
|
41
|
+
## The icons
|
|
42
|
+
|
|
43
|
+
The glyphs the rendering asks for, by meaning; the names are listed in the [contract](../contract.md). Your app maps each one to a component of its own icon library, and the package imports none.
|
|
44
|
+
|
|
45
|
+
- `ViewsIcons` — the record your app hands the provider: every icon name the contract lists, each to a component taking `ViewsIconProps`.
|
|
46
|
+
- `ViewsIconProps` — what an icon component takes: an optional `className`.
|
|
47
|
+
|
|
48
|
+
## The ports
|
|
49
|
+
|
|
50
|
+
Guide: [ports](../guides/ports.md).
|
|
51
|
+
|
|
52
|
+
Runtime services your app hands in, each the narrowest surface the rendering needs, so your toast library, haptics module, clipboard helper, per-device store and dialog map onto them in a few lines.
|
|
53
|
+
|
|
54
|
+
- `ViewsPorts` — what the provider's `ports` takes: `toast`, `haptics`, `clipboard` and `viewPrefs`, each required, and `confirm`, optional. Without a `confirm`, a destructive act asks the browser's own confirm with its message.
|
|
55
|
+
- `ViewsToastPort` — the toasts: `success`, `error` and `info`, each taking a message, and `warning`, taking a message and an optional `description` as a second line, for a change the person did not make (a value someone else wrote).
|
|
56
|
+
- `ViewsHapticsPort` — the device's haptics: `selection()`, `impact(style)` (`light`, `medium`, `heavy`) and `notification(type)` (`success`, `warning`, `error`). An app without a device hands in no-ops.
|
|
57
|
+
- `ViewsClipboardPort` — the clipboard: `writeText(text)` resolving to whether the text reached it, and `readText()` resolving to its text, or `null` where reading is refused.
|
|
58
|
+
- `ViewsPrefsPort` — per-device state the grid keeps between visits, such as a column's width before the view saved it or a collapsed group: `get(key)`, `set(key, value)` and `subscribe(key, listener)`, which returns its unsubscribe. The keys are the package's, namespaced `vk:`.
|
|
59
|
+
- `ViewsConfirmPort` — a question asked before an act: takes a `ViewsConfirmRequest` and resolves to whether the person said yes. A rejection or a throw counts as no.
|
|
60
|
+
- `ViewsConfirmRequest` — what the confirm port is asked: the `message` (the package's words, such as `views.menus.row-delete-confirm` before a row's Delete), the yes button's `confirmLabel`, the `subject` the act is done to as the host names it (a row's `deleteLabel`, absent when it names nothing), and `destructive` when the act removes something, so your dialog draws its destructive look.
|
|
61
|
+
- `ViewsResolvedPorts` — the ports as the provider hands them on through `useViews`: your ports, with `confirm` always a function, the browser's where you handed none.
|
|
62
|
+
|
|
63
|
+
## The atoms
|
|
64
|
+
|
|
65
|
+
Guide: [atoms](../guides/atoms.md).
|
|
66
|
+
|
|
67
|
+
The pieces the rendering is built from, and your app's own pieces it cannot draw itself. Each ships as a default, drawn from your app's colours and marked with its own `data-slot`; your app swaps any of them through the provider's `atoms`, and the rest stay the defaults. A swapped atom marks itself as your app does. The [contract](../contract.md) lists their slots and states.
|
|
68
|
+
|
|
69
|
+
- `DEFAULT_VIEWS_ATOMS` — the atoms every app starts with, one default per name of `ViewsAtoms`; the provider lays your `atoms` over it.
|
|
70
|
+
- `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `Loading`, `LoadMore`, `PlatformMark` and `RowMenu`. The provider's `atoms` takes any part of it.
|
|
71
|
+
- `ViewsListProps` — the rows' container, the inset a run of rows sits in inside a panel or a command list's group: its `children` and a class.
|
|
72
|
+
- `ViewsRowContentProps` — a row's inside, all the row is inside a command list's item, which owns the element, the highlight and the keyboard.
|
|
73
|
+
- What it says: a `label` (text truncates to one line, any other node is laid out in a row so it centres; `wrap` lets a long label break), a `description` line under it, a `leading` glyph (with `leadingLane` to keep its width when there is none), `trailing` content after the label, and a `detail` at its right edge in the subtle colour, such as a setting's current choice.
|
|
74
|
+
- How it reads: `chosen` draws a trailing check (a chosen row with a `detail` draws the detail in the brand colour and no check), `chosenTint` false keeps a badge label's own colour, `tone` `muted` for a row that offers rather than lists (none, create, add), and `size` `compact` (13px) or `regular` (your menu size, the default).
|
|
75
|
+
- `ViewsRowProps` — a whole row: everything `ViewsRowContentProps` takes, as a button, or with `interactive` false a static line. It adds `onClick`, `onMouseDown` (for a row inside an editor that keeps its input focused), `disabled`, `title`, a `role` with `aria-selected`, and `opens` and `open` for a row that opens a flyout beside its menu.
|
|
76
|
+
- `ViewsTickBoxProps` — a paint-only tick box: `checked` and a class. The control around it is the caller's.
|
|
77
|
+
- `ViewsStatusBadgeProps` — a pill coloured by a status slot of `@viewkitjs/fields`: its `slot` and `label`, a `leading` mark that replaces the slot's own, a `title`, a `size` (`compact`, 11px, the default, as a status value is drawn in a cell; or `regular`) and a class.
|
|
78
|
+
- `ViewsStatusMarkerProps` — an attention badge that opens its reason in a popover: its `label`, its `title` (the panel's heading and the marker's accessible name), a `slot` (`warning` by default), the `reason`, the `emptyReason` shown when there is none (the package's wording by default), and `onResolve` with its `resolveLabel`; without `onResolve` the marker is read-only.
|
|
79
|
+
- `ViewsTagProps` — a category chip: its `label` and category `color`, a `leading` glyph (an option's icon, drawn by your `AppIcon`), a class, and `onRemove`, which draws a remove control, named by `removeLabel` (the package's wording by default).
|
|
80
|
+
- `ViewsCommandMenuProps` — a `command` cell's verb menu: the `trigger` the cell drew (a button), the host's `items` as `FieldRowMenuItem`s, and `align`. The default is your components map's `Menu`; your app may swap in its own action menu.
|
|
81
|
+
- `ViewsRowMenuProps` — the row's right-click menu, around the row it opens on (`children`): opened by a right-click on the row or by its ⋯, it lists an Open page row for `openHref` (a new tab), the `items` the rendering built, and a Delete row when `onDelete` is given, called with `rowId` once the confirm port says yes, with `deleteLabel` as its `subject`. A delete that rejects says so through the toast port's `error`. `onToggleSelect` flips the row's selection, for an app whose long-press selects; the default doesn't use it, and a long-press on a phone opens nothing.
|
|
82
|
+
- `ViewsRowMenuItem` — one row of the row's menu, the shape a host's own row-menu items already have: a rule (`{ separator: true }`), or a row with its `label`, `icon`, `onClick`, `destructive`, `disabled` and a `shortcut` hint drawn at its end and never bound.
|
|
83
|
+
- `ViewsRelationLinkProps` — where a relation chip goes: the `relation` value and the chip the display drew as `children`, for your app's own link around it. The default goes nowhere, since a relation is a fact as often as a destination.
|
|
84
|
+
- `ViewsLoadingProps` — a wait: `placement` `body` (the whole list reloading) or `footer` (more rows arriving), and the `label` read to assistive technology. The default is a plain ring, larger in the body.
|
|
85
|
+
- `ViewsLoadMoreProps` — how a list asks for its next page once its end comes near: `onReveal`, and an optional `label` drawn while it waits. The default watches a sentinel past the last row, calls `onReveal` as it comes within 600px of the viewport, and draws your `Loading` (or the label) meanwhile.
|
|
86
|
+
- `ViewsPlatformMarkProps` — a link's platform, drawn before the link: the `platform` (its key says which, its name what to call it) and a class. The default draws nothing, so a link looks plain; the package ships no brand art, so an app that wants marks draws its own.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# `@viewkitjs/views/selection`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/selection` to let people pick rows of a list: the selection over the rows' visual order with a range anchor, the row checkbox, the drag down its lane, the rules a row click follows, and the rest that starts a record's read before the click. The door carries no client directive; each hook and component file behind it carries its own, and they read the provider's components and haptics. The bar a selection opens, and what its verbs do, stay your app's.
|
|
4
|
+
|
|
5
|
+
## The selection
|
|
6
|
+
|
|
7
|
+
Guide: [selection](../guides/selection.md).
|
|
8
|
+
|
|
9
|
+
- `useListSelection` — a list's selection: takes `orderedIds` (the ids in visual order, after filter, sort and grouping), an optional `retention` (`"ordered"` by default) and an optional `resetKey`, and returns a `UseListSelectionResult`. A new `resetKey` empties it. Turning rows on or off ticks the provider's `haptics.selection()`; selecting all gives a medium impact; `clear` is silent.
|
|
10
|
+
- `UseListSelectionResult` — what `useListSelection` returns: `selectedIds`, `count`, `isSelected(id)`, `anchorId`, `allSelected` and `someSelected` (some but not all, for an indeterminate box), and the verbs `toggle(id, next?)` (sets the range anchor), `toggleRange(id)` (adds the run from the anchor to `id`), `toggleMany(ids)` (selects them all, or clears them when all are selected), `selectAll()`, `clear()` (also resets the anchor) and `setSelected(ids)`.
|
|
11
|
+
- `SelectionRetention` — what happens to a selected id that leaves the visual order: `"ordered"` drops it; `"external"` keeps it, for a selection across a whole query whose rows need not all be loaded. Either way the range anchor must stay visible to count.
|
|
12
|
+
- `useEscapeToClear` — while `active` is true, Escape anywhere in the window calls `clear`.
|
|
13
|
+
- `ListSelectionConfig` — what a list or table takes to be selectable (the grid's `selection`): `resetKey` (the selection clears when it changes) and `renderBar` (draws your bar from the selection and, when the renderer can write, a `ListBatchApi`), with optional `orderedIds` and `retention`.
|
|
14
|
+
- `ListBatchApi` — the batch write a renderer with an editing model hands your bar: `setColumnValue(rowIds, columnId, value)`, resolving to whether the write landed. The grid's resolves `false` for a column it cannot write, and skips an id whose row is not loaded.
|
|
15
|
+
|
|
16
|
+
## Picking rows with the pointer
|
|
17
|
+
|
|
18
|
+
- `selectFromClick` — the modifier click on a row: takes the click, the row's id and the selection's `toggle` and `toggleRange`. Cmd or Ctrl toggles the row, Shift extends the range, and it returns `true` when it handled the click, so your handler stops before opening the row.
|
|
19
|
+
- `preventShiftTextSelect` — a `mousedown` handler that stops a shift-click from selecting text.
|
|
20
|
+
- `SelectCheckbox` — the row checkbox, drawn with the components map's `Checkbox`. It takes `checked`, `revealed`, `onChange(next, shift)` (the shift key read off the press that changed it, for a range), an optional `aria-label` and `className`. It shows only while the lane around it, marked with the `group/selzone` class, is hovered, and stays shown when `revealed` or checked.
|
|
21
|
+
- `useCheckDragSelect` — drag down the checkbox lane to set a run of rows, with the mouse only. It takes `enabled`, `rootRef` (the container the drag stays within), `rowIds` (visible order, without rows in collapsed groups), an optional `rowIdOf` (maps a row's `data-row-id` to a selection id), `isSelected` and `setRowSelected(id, next)`. It returns `tryArm`, called from the container's `onPointerDown` (`true` when it armed, so stop handling the event), and `consumeDrag`, called from a capture-phase click handler (`true` once after a real drag, so swallow that click). The run goes from the row the drag starts on to the row under the pointer, all set to the opposite of the first row's state; dragging back restores rows to what they were. A move under 4px stays a plain click, and near the scroller's edge the container scrolls.
|
|
22
|
+
- `ROW_CHECK_ATTR` — `"data-row-check"`, the attribute on a row's checkbox lane: a drag that starts anywhere in the lane arms `useCheckDragSelect`.
|
|
23
|
+
|
|
24
|
+
## Row-click rules
|
|
25
|
+
|
|
26
|
+
- `ROW_INTERACTIVE_SELECTOR` — the selector for a real control inside a row (a link, a button, a form control, an element with a button, switch, checkbox, menu item or tab role, editable content, `[data-popover-trigger]`, `[data-no-nav]`). A click on one belongs to the control; a click anywhere else opens the row, or toggles it while selecting.
|
|
27
|
+
- `ROW_OPEN_STOP_SELECTOR` — `"[data-row-stop]"`, for a part of a row that must not open it (a trailing menu gutter) but still toggles it while selecting. Checked after the selection toggle, so it gates only the open.
|
|
28
|
+
- `ROW_NO_TEXT_SELECT` — the classes for a selectable row: no text selection and no long-press callout on iOS, so a long press selects the row without highlighting its text.
|
|
29
|
+
|
|
30
|
+
## Reading ahead
|
|
31
|
+
|
|
32
|
+
- `useRestIntent` — starts a record's read when a mouse rests on its row: takes `onRest` and an optional `accepts(target, row)` that bounds which part of the row counts, and returns `onPointerOver` and `onPointerLeave` for the row. `onRest` runs once the pointer has stayed over the row for `REST_INTENT_MS`, at most once per visit. A finger, a held button, a pointer that leaves first, or content portaled out of the row starts nothing.
|
|
33
|
+
- `REST_INTENT_MS` — `100`, how long a mouse rests on a row before its record is read.
|