@viewkitjs/views 0.1.0 → 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 +196 -1
- package/README.md +90 -41
- package/dist/atoms/Row.js +1 -1
- package/dist/atoms/RowMenu.d.ts +1 -1
- package/dist/atoms/RowMenu.js +15 -4
- package/dist/atoms/types.d.ts +4 -4
- package/dist/contract.d.ts +37 -7
- package/dist/contract.js +24 -5
- package/dist/display/format.d.ts +16 -1
- package/dist/display/format.js +10 -1
- package/dist/display/index.d.ts +1 -1
- package/dist/display/index.js +1 -1
- package/dist/display/link.js +5 -3
- package/dist/display/location.d.ts +4 -3
- package/dist/display/location.js +12 -5
- package/dist/display/options.d.ts +1 -1
- package/dist/display/percent.js +10 -3
- package/dist/display/phone.d.ts +2 -1
- package/dist/display/phone.js +8 -1
- package/dist/display/relation.js +1 -1
- package/dist/editors/ChipsEditor.js +1 -1
- package/dist/editors/LocationEditor.js +16 -17
- package/dist/editors/NameEditor.js +5 -4
- package/dist/editors/NumberEditor.js +2 -2
- package/dist/editors/RangeEditor.js +2 -2
- package/dist/editors/ValueListEditor.d.ts +2 -2
- package/dist/editors/ValueListEditor.js +8 -8
- package/dist/editors/edit-cores.d.ts +1 -1
- package/dist/fields/binding.d.ts +1 -1
- package/dist/fields/currency.d.ts +0 -10
- package/dist/fields/currency.js +0 -14
- package/dist/fields/money.d.ts +1 -0
- package/dist/fields/money.js +1 -0
- package/dist/filters/filter-model.d.ts +0 -1
- package/dist/filters/registry.d.ts +3 -36
- package/dist/filters/registry.js +0 -38
- package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
- package/dist/grid/chrome/GridAddColumn.js +29 -0
- package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
- package/dist/grid/chrome/GridAggregateMenu.js +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/index.d.ts +0 -1
- package/dist/index.js +0 -1
- package/dist/internal/viewport.d.ts +5 -0
- package/dist/internal/viewport.js +29 -0
- package/dist/model/column-capabilities.d.ts +2 -2
- package/dist/model/column-state.d.ts +1 -1
- package/dist/model/density.js +3 -3
- package/dist/model/filter-capabilities.d.ts +1 -1
- package/dist/model/filter-capabilities.js +1 -1
- package/dist/model/index.d.ts +4 -6
- package/dist/model/index.js +0 -1
- package/dist/model/preferences.d.ts +7 -3
- package/dist/provider/ViewsProvider.d.ts +1 -1
- package/dist/provider/ViewsProvider.js +5 -1
- package/dist/provider/components.d.ts +16 -8
- package/dist/provider/context.d.ts +3 -2
- package/dist/provider/menu-groups.d.ts +8 -0
- package/dist/provider/menu-groups.js +38 -0
- package/dist/provider/ports.d.ts +22 -0
- package/dist/provider/ports.js +1 -0
- package/dist/react.d.ts +1 -1
- package/docs/contract.md +128 -56
- 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 +9 -47
- 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/package.json +7 -3
- package/skills/views/SKILL.md +20 -5
- package/dist/filters/types.d.ts +0 -27
- package/dist/filters/types.js +0 -1
- package/dist/model/filter-pushdown.d.ts +0 -106
- package/dist/model/filter-pushdown.js +0 -147
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# Selection
|
|
2
|
+
|
|
3
|
+
People pick rows to act on several at once: a click with a modifier, a checkbox, a drag down the checkbox lane, select all. `@viewkitjs/views/selection` holds the selection itself and the rules a row follows; the bar a selection opens, and what its verbs do, are your app's. This page builds a plain list that people can select, then hands a selection to the grid, which wires the same pieces itself.
|
|
4
|
+
|
|
5
|
+
## A list's selection
|
|
6
|
+
|
|
7
|
+
`useListSelection({ orderedIds, retention, resetKey })` keeps a list's selection. `orderedIds` are the row ids in the order the list draws them, after filtering, sorting and grouping: a range runs over that order, and select all selects exactly what is on screen. Keep the array stable between renders (a `useMemo` over your rows).
|
|
8
|
+
|
|
9
|
+
It returns a `UseListSelectionResult`:
|
|
10
|
+
|
|
11
|
+
- `selectedIds`, `count`, `isSelected(id)`;
|
|
12
|
+
- `toggle(id, next?)`, which flips one row (or sets it to `next`) and makes it the range anchor (`anchorId`);
|
|
13
|
+
- `toggleRange(id)`, which adds every row from the anchor to `id`;
|
|
14
|
+
- `toggleMany(ids)`, which selects them all, or clears them when they are all selected already (a group's checkbox);
|
|
15
|
+
- `selectAll()`, `clear()` (which also drops the anchor) and `setSelected(ids)`;
|
|
16
|
+
- `allSelected` and `someSelected`, for a header checkbox and its indeterminate state.
|
|
17
|
+
|
|
18
|
+
Turning a row on or off ticks the provider's `haptics.selection()`, select all gives `haptics.impact("medium")`, and `clear` is silent, as it is also what your batch action calls once it is done. The haptics port is yours, handed to the provider (the [contract](../contract.md) lists the ports).
|
|
19
|
+
|
|
20
|
+
`resetKey` empties the selection when it changes: pass the identity of the view and its filter, so a selection never carries over to rows a person can't see. `retention` says what happens to a selected id that leaves `orderedIds`. `"ordered"`, the default, drops it. `"external"` (a `SelectionRetention`) keeps it, for a selection across a whole query whose rows aren't all loaded. Either way the range anchor has to stay on screen to count.
|
|
21
|
+
|
|
22
|
+
`useEscapeToClear(active, clear)` clears on Escape anywhere in the window while `active` is true.
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { useMemo, useRef, type MouseEvent as ReactMouseEvent, type ReactNode } from "react";
|
|
26
|
+
import {
|
|
27
|
+
preventShiftTextSelect,
|
|
28
|
+
REST_INTENT_MS,
|
|
29
|
+
ROW_CHECK_ATTR,
|
|
30
|
+
ROW_INTERACTIVE_SELECTOR,
|
|
31
|
+
ROW_NO_TEXT_SELECT,
|
|
32
|
+
ROW_OPEN_STOP_SELECTOR,
|
|
33
|
+
SelectCheckbox,
|
|
34
|
+
selectFromClick,
|
|
35
|
+
useCheckDragSelect,
|
|
36
|
+
useEscapeToClear,
|
|
37
|
+
useListSelection,
|
|
38
|
+
useRestIntent,
|
|
39
|
+
type ListBatchApi,
|
|
40
|
+
type ListSelectionConfig,
|
|
41
|
+
type UseListSelectionResult,
|
|
42
|
+
} from "@viewkitjs/views/selection";
|
|
43
|
+
|
|
44
|
+
type Deal = { id: string; title: string; stage: string };
|
|
45
|
+
|
|
46
|
+
// Your app's own routes.
|
|
47
|
+
declare function openDeal(id: string): void;
|
|
48
|
+
declare function prefetchDeal(id: string): void;
|
|
49
|
+
|
|
50
|
+
function useDealSelection(deals: Deal[], filterKey: string) {
|
|
51
|
+
const orderedIds = useMemo(() => deals.map((deal) => deal.id), [deals]);
|
|
52
|
+
const sel = useListSelection({ orderedIds, resetKey: filterKey });
|
|
53
|
+
useEscapeToClear(sel.count > 0, sel.clear);
|
|
54
|
+
return { orderedIds, sel };
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## A row: what a click does
|
|
59
|
+
|
|
60
|
+
A click on a row goes, in order:
|
|
61
|
+
|
|
62
|
+
1. To a real control inside the row, when it lands on one: `ROW_INTERACTIVE_SELECTOR` matches links, buttons, form controls, elements with a button, switch, checkbox, menu item or tab role, editable content, `[data-popover-trigger]` and `[data-no-nav]`. The control handles it, whether or not the list is selecting.
|
|
63
|
+
2. To the selection, when it carries a modifier: `selectFromClick(event, id, sel)` toggles the row on Cmd or Ctrl and extends the range on Shift, and returns `true` when it handled the click.
|
|
64
|
+
3. To the selection again while rows are selected: a plain click toggles the row.
|
|
65
|
+
4. Nowhere, when it lands in a region marked `data-row-stop` (`ROW_OPEN_STOP_SELECTOR`), such as a trailing menu gutter. It is checked after the toggle, so the region still selects; it only refuses to open the row.
|
|
66
|
+
5. To opening the row.
|
|
67
|
+
|
|
68
|
+
`preventShiftTextSelect` on the row's `mousedown` stops a Shift-click from selecting text, and `ROW_NO_TEXT_SELECT` is the classes for a selectable row: no text selection, and no long-press callout on iOS.
|
|
69
|
+
|
|
70
|
+
`SelectCheckbox` draws the row's checkbox through your components map's `Checkbox`. It shows while the lane around it, marked with the `group/selzone` class, is hovered, and stays shown while `revealed` or checked. Its `onChange(next, shift)` reads the Shift key off the press that changed it, so a Shift-click on a checkbox extends the range.
|
|
71
|
+
|
|
72
|
+
`useRestIntent(onRest, accepts)` starts reading a record before it is opened: `onRest` runs once a mouse has rested on the row for `REST_INTENT_MS` (100 ms), at most once per visit. A finger, a held button (a drag passing over), a pointer that leaves first, or content portaled out of the row (a menu it opened) starts nothing. `accepts(target, row)` bounds which part of the row counts; it returns two handlers to spread on the row.
|
|
73
|
+
|
|
74
|
+
```tsx
|
|
75
|
+
function DealRow({ deal, sel }: { deal: Deal; sel: UseListSelectionResult }) {
|
|
76
|
+
const selecting = sel.count > 0;
|
|
77
|
+
const rest = useRestIntent(
|
|
78
|
+
() => prefetchDeal(deal.id),
|
|
79
|
+
(target) => !target.closest(ROW_INTERACTIVE_SELECTOR)
|
|
80
|
+
);
|
|
81
|
+
|
|
82
|
+
const onClick = (event: ReactMouseEvent<HTMLDivElement>) => {
|
|
83
|
+
const target = event.target as Element;
|
|
84
|
+
if (target.closest(ROW_INTERACTIVE_SELECTOR)) return;
|
|
85
|
+
if (selectFromClick(event, deal.id, sel)) return;
|
|
86
|
+
if (selecting) {
|
|
87
|
+
sel.toggle(deal.id);
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
if (target.closest(ROW_OPEN_STOP_SELECTOR)) return;
|
|
91
|
+
openDeal(deal.id);
|
|
92
|
+
};
|
|
93
|
+
|
|
94
|
+
return (
|
|
95
|
+
<div
|
|
96
|
+
data-row-id={deal.id}
|
|
97
|
+
className={ROW_NO_TEXT_SELECT}
|
|
98
|
+
onMouseDown={preventShiftTextSelect}
|
|
99
|
+
onClick={onClick}
|
|
100
|
+
{...rest}
|
|
101
|
+
>
|
|
102
|
+
<div className="group/selzone" data-row-check="">
|
|
103
|
+
<SelectCheckbox
|
|
104
|
+
checked={sel.isSelected(deal.id)}
|
|
105
|
+
revealed={selecting}
|
|
106
|
+
aria-label={`Select ${deal.title}`}
|
|
107
|
+
onChange={(next, shift) => (shift ? sel.toggleRange(deal.id) : sel.toggle(deal.id, next))}
|
|
108
|
+
/>
|
|
109
|
+
</div>
|
|
110
|
+
<span>{deal.title}</span>
|
|
111
|
+
<span data-row-stop="">{deal.stage}</span>
|
|
112
|
+
</div>
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`selectFromClick` reads only the click's modifier keys and calls the selection's `toggle` or `toggleRange`, so it can be asked directly:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import assert from "node:assert/strict";
|
|
121
|
+
|
|
122
|
+
const calls: string[] = [];
|
|
123
|
+
const recorder = {
|
|
124
|
+
toggle: (id: string) => {
|
|
125
|
+
calls.push(`toggle ${id}`);
|
|
126
|
+
},
|
|
127
|
+
toggleRange: (id: string) => {
|
|
128
|
+
calls.push(`range ${id}`);
|
|
129
|
+
},
|
|
130
|
+
};
|
|
131
|
+
const click = (keys: { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean }) =>
|
|
132
|
+
({ metaKey: false, ctrlKey: false, shiftKey: false, ...keys }) as ReactMouseEvent;
|
|
133
|
+
|
|
134
|
+
assert.equal(selectFromClick(click({ metaKey: true }), "d1", recorder), true);
|
|
135
|
+
assert.equal(selectFromClick(click({ ctrlKey: true }), "d2", recorder), true);
|
|
136
|
+
assert.equal(selectFromClick(click({ shiftKey: true }), "d3", recorder), true);
|
|
137
|
+
// A plain click is not the selection's: the row opens.
|
|
138
|
+
assert.equal(selectFromClick(click({}), "d4", recorder), false);
|
|
139
|
+
assert.deepEqual(calls, ["toggle d1", "toggle d2", "range d3"]);
|
|
140
|
+
|
|
141
|
+
let prevented = 0;
|
|
142
|
+
const press = (shiftKey: boolean) =>
|
|
143
|
+
({
|
|
144
|
+
shiftKey,
|
|
145
|
+
preventDefault: () => {
|
|
146
|
+
prevented += 1;
|
|
147
|
+
},
|
|
148
|
+
}) as ReactMouseEvent;
|
|
149
|
+
preventShiftTextSelect(press(true));
|
|
150
|
+
preventShiftTextSelect(press(false));
|
|
151
|
+
assert.equal(prevented, 1);
|
|
152
|
+
|
|
153
|
+
assert.equal(ROW_OPEN_STOP_SELECTOR, "[data-row-stop]");
|
|
154
|
+
assert.equal(REST_INTENT_MS, 100);
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Dragging down the checkbox lane
|
|
158
|
+
|
|
159
|
+
`useCheckDragSelect` lets a mouse drag down the checkbox lane to set a run of rows. The lane is the element carrying `ROW_CHECK_ATTR` (`data-row-check`), inside a row carrying `data-row-id`. The run goes from the row the drag started on to the row under the pointer, and every row in it takes the opposite of the first row's state, so a drag from an unselected row selects and one from a selected row clears. Dragging back restores the rows that fall out of the run to what they were. A move under 4px stays a plain click, and near the scroller's edge the container scrolls so the run can outgrow the screen. A finger's drag stays a scroll.
|
|
160
|
+
|
|
161
|
+
It takes `enabled`, `rootRef` (the container the drag stays within), `rowIds` (the visible order, without rows hidden in collapsed groups), `isSelected`, `setRowSelected(id, next)` and, when a row's `data-row-id` is not the selection's id, `rowIdOf` to map one to the other. It returns `tryArm`, for the container's `onPointerDown` (`true` when it armed, so the event is handled), and `consumeDrag`, for a capture-phase click handler (`true` once after a real drag, so the click that ends it does not toggle the first row again).
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
assert.equal(ROW_CHECK_ATTR, "data-row-check");
|
|
165
|
+
|
|
166
|
+
function DealList({ deals, filterKey }: { deals: Deal[]; filterKey: string }) {
|
|
167
|
+
const { orderedIds, sel } = useDealSelection(deals, filterKey);
|
|
168
|
+
const rootRef = useRef<HTMLDivElement>(null);
|
|
169
|
+
const drag = useCheckDragSelect({
|
|
170
|
+
enabled: true,
|
|
171
|
+
rootRef,
|
|
172
|
+
rowIds: orderedIds,
|
|
173
|
+
isSelected: sel.isSelected,
|
|
174
|
+
setRowSelected: sel.toggle,
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
return (
|
|
178
|
+
<div
|
|
179
|
+
ref={rootRef}
|
|
180
|
+
onPointerDown={(event) => {
|
|
181
|
+
drag.tryArm(event);
|
|
182
|
+
}}
|
|
183
|
+
onClickCapture={(event) => {
|
|
184
|
+
if (!drag.consumeDrag()) return;
|
|
185
|
+
event.preventDefault();
|
|
186
|
+
event.stopPropagation();
|
|
187
|
+
}}
|
|
188
|
+
>
|
|
189
|
+
{deals.map((deal) => (
|
|
190
|
+
<DealRow key={deal.id} deal={deal} sel={sel} />
|
|
191
|
+
))}
|
|
192
|
+
<DealsBar sel={sel} />
|
|
193
|
+
</div>
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## The bar is yours
|
|
199
|
+
|
|
200
|
+
What a selection lets a person do (move twelve deals to a stage, export them, delete them) is your app's, and so is the bar that offers it. It reads the selection and acts through your API, then calls `clear`.
|
|
201
|
+
|
|
202
|
+
A renderer with an editing model also hands the bar a `ListBatchApi`: `setColumnValue(rowIds, columnId, value)` writes one column across the rows through the renderer's own write path, and resolves to whether the write landed. The grid's goes through the same gate as a cell edit, so a column that can't be written, or one a workspace locked, resolves `false`, and a selected id whose row isn't loaded is skipped. The plain list above has no editing model, so its bar gets none.
|
|
203
|
+
|
|
204
|
+
```tsx
|
|
205
|
+
function DealsBar({ sel, batch }: { sel: UseListSelectionResult; batch?: ListBatchApi }) {
|
|
206
|
+
if (sel.count === 0) return null;
|
|
207
|
+
const moveToProposal = async () => {
|
|
208
|
+
const landed = await batch?.setColumnValue([...sel.selectedIds], "stage", "proposal");
|
|
209
|
+
if (landed) sel.clear();
|
|
210
|
+
};
|
|
211
|
+
return (
|
|
212
|
+
<div role="toolbar">
|
|
213
|
+
<span>{sel.count} selected</span>
|
|
214
|
+
{batch ? (
|
|
215
|
+
<button type="button" onClick={() => void moveToProposal()}>
|
|
216
|
+
Move to proposal
|
|
217
|
+
</button>
|
|
218
|
+
) : null}
|
|
219
|
+
<button type="button" onClick={sel.clear}>
|
|
220
|
+
Clear
|
|
221
|
+
</button>
|
|
222
|
+
</div>
|
|
223
|
+
);
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## The grid takes a selection
|
|
228
|
+
|
|
229
|
+
`GridTable` wires the selection itself when you pass `selection`, a `ListSelectionConfig`: its checkbox rail (Shift on a checkbox extends the range), the drag down the lane (rows in collapsed groups left out), a plain click toggling a row while rows are selected, Escape, and a group's checkbox. One rule differs from a plain list: in the grid a modifier click on a cell is a cell-range gesture, as in a spreadsheet (Shift extends the active range, Cmd or Ctrl adds the cell), so rows are picked from the rail. You give it:
|
|
230
|
+
|
|
231
|
+
- `resetKey`: the selection clears when it changes;
|
|
232
|
+
- `renderBar(sel, batch?)`: your bar, drawn from the selection and, when the grid can write (you passed `onCellCommit`), its `ListBatchApi`. The grid calls it on every render, so the bar draws nothing while `sel.count` is zero;
|
|
233
|
+
- optionally `orderedIds`, when the order a range runs over is not the grid's rows as drawn, and `retention`.
|
|
234
|
+
|
|
235
|
+
```tsx
|
|
236
|
+
import type { ListColumn } from "@viewkitjs/views";
|
|
237
|
+
import { GridTable, type GridCellCommitFn } from "@viewkitjs/views/grid";
|
|
238
|
+
|
|
239
|
+
// Built with columnFrom, and your commit handler: the getting started page has both.
|
|
240
|
+
declare const DEAL_COLUMNS: ListColumn<Deal>[];
|
|
241
|
+
declare const commitDealCell: GridCellCommitFn<Deal>;
|
|
242
|
+
|
|
243
|
+
function DealsGrid({ deals, filterKey }: { deals: Deal[]; filterKey: string }): ReactNode {
|
|
244
|
+
const selection: ListSelectionConfig = {
|
|
245
|
+
resetKey: filterKey,
|
|
246
|
+
renderBar: (sel, batch) => <DealsBar sel={sel} batch={batch} />,
|
|
247
|
+
};
|
|
248
|
+
return (
|
|
249
|
+
<GridTable
|
|
250
|
+
groups={[{ key: "all", label: null, items: deals }]}
|
|
251
|
+
grouped={false}
|
|
252
|
+
getRowId={(deal) => deal.id}
|
|
253
|
+
columns={DEAL_COLUMNS}
|
|
254
|
+
onOpenRow={(deal) => openDeal(deal.id)}
|
|
255
|
+
onPrefetchRow={(deal) => prefetchDeal(deal.id)}
|
|
256
|
+
onCellCommit={commitDealCell}
|
|
257
|
+
selection={selection}
|
|
258
|
+
/>
|
|
259
|
+
);
|
|
260
|
+
}
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
A person's standing choice to keep the checkboxes shown is `alwaysCheckboxes` on the grid. Leave `selection` out and the grid has no checkboxes and no bar.
|
|
264
|
+
|
|
265
|
+
## Next
|
|
266
|
+
|
|
267
|
+
- [Columns](columns.md): which columns a batch write can reach
|
|
268
|
+
- [The grid](the-grid.md): grouping, sorting, preferences, figures and writes
|
|
269
|
+
- [`@viewkitjs/views/selection` reference](../reference/selection.md): every name on the door
|
|
270
|
+
- [`@viewkitjs/views/grid` reference](../reference/grid.md): every prop `GridTable` takes
|