@viewkitjs/views 0.4.0 → 0.5.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.
Files changed (77) hide show
  1. package/CHANGELOG.md +148 -0
  2. package/README.md +3 -3
  3. package/dist/atoms/DrillRows.d.ts +3 -0
  4. package/dist/atoms/DrillRows.js +25 -0
  5. package/dist/atoms/PanelRows.d.ts +5 -0
  6. package/dist/atoms/PanelRows.js +40 -0
  7. package/dist/atoms/PanelSearch.d.ts +2 -0
  8. package/dist/atoms/PanelSearch.js +21 -0
  9. package/dist/atoms/SelectionSheet.d.ts +3 -0
  10. package/dist/atoms/SelectionSheet.js +30 -0
  11. package/dist/atoms/defaults.js +12 -0
  12. package/dist/atoms/types.d.ts +117 -1
  13. package/dist/contract.d.ts +170 -9
  14. package/dist/contract.js +179 -2
  15. package/dist/figures.d.ts +5 -48
  16. package/dist/figures.js +1 -63
  17. package/dist/grid/chrome/GridColumnMenu.d.ts +3 -3
  18. package/dist/grid/chrome/GridColumnSortSection.d.ts +3 -3
  19. package/dist/grid/chrome/GridGroupMenu.d.ts +2 -2
  20. package/dist/grid/chrome/GridTable.js +1 -1
  21. package/dist/grid/useGridTablePrefs.d.ts +1 -1
  22. package/dist/grouping/sort-groups.d.ts +6 -7
  23. package/dist/model/aggregates.d.ts +3 -3
  24. package/dist/model/aggregates.js +17 -71
  25. package/dist/model/column-order.d.ts +2 -2
  26. package/dist/model/column-schema.d.ts +6 -7
  27. package/dist/model/column-state.d.ts +3 -20
  28. package/dist/model/column-state.js +1 -4
  29. package/dist/model/column-types.d.ts +1 -15
  30. package/dist/model/column-types.js +1 -1
  31. package/dist/model/part-columns.d.ts +1 -6
  32. package/dist/model/part-columns.js +1 -1
  33. package/dist/model/part-rows.d.ts +2 -9
  34. package/dist/model/part-rows.js +1 -10
  35. package/dist/model/preferences.d.ts +3 -23
  36. package/dist/model/preferences.js +1 -17
  37. package/dist/model/prefs-buckets.d.ts +0 -27
  38. package/dist/model/prefs-buckets.js +1 -1
  39. package/dist/model/relation-filters.d.ts +0 -1
  40. package/dist/model/relation-filters.js +1 -1
  41. package/dist/model/row-icon.d.ts +5 -9
  42. package/dist/model/view-rules.d.ts +32 -6
  43. package/dist/model/view-rules.js +94 -22
  44. package/dist/provider/ViewsProvider.d.ts +6 -2
  45. package/dist/provider/ViewsProvider.js +3 -2
  46. package/dist/provider/components.d.ts +16 -0
  47. package/dist/provider/context.d.ts +3 -1
  48. package/dist/provider/desktop.d.ts +3 -0
  49. package/dist/provider/desktop.js +7 -4
  50. package/dist/react.d.ts +2 -2
  51. package/dist/selection/SelectionBar.d.ts +18 -0
  52. package/dist/selection/SelectionBar.js +92 -0
  53. package/dist/selection/SelectionBarPhone.d.ts +3 -0
  54. package/dist/selection/SelectionBarPhone.js +14 -0
  55. package/dist/selection/bar-overflow.d.ts +12 -0
  56. package/dist/selection/bar-overflow.js +42 -0
  57. package/dist/selection/bar-parts.d.ts +15 -0
  58. package/dist/selection/bar-parts.js +17 -0
  59. package/dist/selection/index.d.ts +2 -0
  60. package/dist/selection/index.js +1 -0
  61. package/dist/selection/types.d.ts +3 -2
  62. package/dist/selection/verbs.d.ts +34 -0
  63. package/dist/selection/verbs.js +1 -0
  64. package/docs/contract.md +62 -8
  65. package/docs/getting-started.md +1 -1
  66. package/docs/guides/atoms.md +2 -1
  67. package/docs/guides/selection.md +32 -20
  68. package/docs/guides/the-grid.md +3 -2
  69. package/docs/guides/the-provider.md +4 -2
  70. package/docs/index.md +2 -0
  71. package/docs/install.md +4 -1
  72. package/docs/reference/grid.md +2 -2
  73. package/docs/reference/react.md +13 -3
  74. package/docs/reference/selection.md +10 -2
  75. package/docs/reference/views.md +25 -27
  76. package/package.json +22 -3
  77. package/skills/views/SKILL.md +1 -1
@@ -0,0 +1,34 @@
1
+ import type { ReactNode } from "react";
2
+ import type { PickerOption } from "../editors/SelectEditor.js";
3
+ /** One verb, or one row of a `group`. */
4
+ export type SelectionVerbItem = {
5
+ label: string;
6
+ /** The app's glyph, drawn before the words. */
7
+ icon?: ReactNode;
8
+ onClick: () => void;
9
+ /** A verb that undoes or removes something (Cancel, Disconnect): drawn in the danger colour. Delete
10
+ * itself is the bar's own `onDelete`, never a verb. */
11
+ destructive?: boolean;
12
+ disabled?: boolean;
13
+ };
14
+ /** "Set this field on every selected row": the field's values as their badges, the same rows a cell's
15
+ * editor picks from. No current value: the rows may already hold several. */
16
+ export type SelectionOptionsVerb = {
17
+ kind: "options";
18
+ label: string;
19
+ icon?: ReactNode;
20
+ disabled?: boolean;
21
+ options: PickerOption[];
22
+ onSelect: (value: string) => void;
23
+ };
24
+ /** A verb on the bar: a direct `action`, a `group` that opens a small menu of related verbs, or an
25
+ * `options` verb whose values are picked as badges. */
26
+ export type SelectionVerb = ({
27
+ kind: "action";
28
+ } & SelectionVerbItem) | {
29
+ kind: "group";
30
+ label: string;
31
+ icon?: ReactNode;
32
+ disabled?: boolean;
33
+ items: SelectionVerbItem[];
34
+ } | SelectionOptionsVerb;
@@ -0,0 +1 @@
1
+ export {};
package/docs/contract.md CHANGED
@@ -51,6 +51,14 @@ use; the prefix keeps that selector from reaching an element of the app's own.
51
51
  Board's slots (`vk-board`, `vk-board-lane`, `vk-board-lane-header`, `vk-board-card`,
52
52
  `vk-board-add-card`) join this table when the board arrives.
53
53
 
54
+ The selection bar's parts (`SelectionBar`, `@viewkitjs/views/selection`):
55
+
56
+ | Slot | Part |
57
+ | ------------------------------------ | ---------------------------------------------------------- |
58
+ | `data-slot="vk-selection-bar"` | the fixed box the app places (the provider's `selectionBar`) |
59
+ | `data-slot="vk-selection-pill"` | the pill inside it: the count, the verbs, the trash, More |
60
+ | `data-slot="vk-selection-chip"` | the count that clears the selection, on the desktop |
61
+
54
62
  ## States
55
63
 
56
64
  Flags the rendering styles, present as an attribute when true and absent when false, so a skin
@@ -161,7 +169,8 @@ declares both wherever a ground declares its own, so a part takes the states of
161
169
  The default atoms and the display also read `--vk-success`, `--vk-warning`, `--vk-info`,
162
170
  `--vk-label-blue`, `--vk-label-green`, `--vk-label-amber`, `--vk-label-red`, `--vk-label-purple`,
163
171
  `--vk-label-pink` and `--vk-label-teal` when the app declares them, each with a built-in fallback. The
164
- corners come from the app's Tailwind radius scale.
172
+ selection bar reads `--vk-float-shadow`, a whole `box-shadow` value for what floats over a list, with a
173
+ built-in fallback. The corners come from the app's Tailwind radius scale.
165
174
 
166
175
  **The page gutter is the app's, if it has one.** `--vk-gutter` is the side padding a page gives its
167
176
  content: the grid's rows run edge to edge and line their content up with it. An app that pads its
@@ -307,9 +316,12 @@ container: the inset a run of rows sits in, inside a panel or a command list's g
307
316
  a button or, with `interactive={false}`, a static line), `RowContent` (a row's inside, for inside a
308
317
  command list's item, which owns the element and the highlight), `TickBox` (a paint-only tick box),
309
318
  `StatusBadge` (a pill by status slot), `StatusMarker` (an attention badge that opens its reason) and
310
- `Tag` (a category chip, removable, with an optional leading glyph), `CommandMenu` (a `command` cell's verb menu, opened from the trigger the cell drew; the default is the components map's `Menu`), `RowMenu` (the rows' right-click menu, once around each section's rows' container and aimed at the row a press or a right-click came from, its props that row's: Open page, the rows the rendering builds, Delete; the default is the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`), wrapped in `data-slot="vk-row-menu"`; the grid's row-menu keys send a cell the same right-click, with no press before it, so a `RowMenu` of your own opens on any `contextmenu` and doesn't wait for a press; its Delete asks the `confirm` port with `views.menus.row-delete-confirm` (the browser's own confirm when you hand none), and a delete that rejects says so through the toast port's `error` with `views.menus.row-delete-failed`; a long-press on a phone opens nothing) and `RelationLink` (where a relation chip goes, around the chip the display drew; the default goes nowhere), `RelationRoles` (a link's roles, inside its chip after the record's name, on a `many` relation that declares `links`; the default draws their labels in the subtle colour after a middle dot, wrapped in `data-slot="vk-relation-roles"`), `Loading` (a wait: the list reloading, or more rows arriving; the default is a plain ring) `LoadMore` (how a list asks for its next page; the default watches a sentinel past the last row) and `PlatformMark` (a link's platform, drawn before it, read from its address with the conventions' platforms; the default draws nothing, so a link looks plain, and the package ships no brand art, so an app that wants marks draws its own by the platform's key into `data-slot="vk-platform"`). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
319
+ `Tag` (a category chip, removable, with an optional leading glyph), `CommandMenu` (a `command` cell's verb menu, opened from the trigger the cell drew; the default is the components map's `Menu`), `RowMenu` (the rows' right-click menu, once around each section's rows' container and aimed at the row a press or a right-click came from, its props that row's: Open page, the rows the rendering builds, Delete; the default is the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`), wrapped in `data-slot="vk-row-menu"`; the grid's row-menu keys send a cell the same right-click, with no press before it, so a `RowMenu` of your own opens on any `contextmenu` and doesn't wait for a press; its Delete asks the `confirm` port with `views.menus.row-delete-confirm` (the browser's own confirm when you hand none), and a delete that rejects says so through the toast port's `error` with `views.menus.row-delete-failed`; a long-press on a phone opens nothing) and `RelationLink` (where a relation chip goes, around the chip the display drew; the default goes nowhere), `RelationRoles` (a link's roles, inside its chip after the record's name, on a `many` relation that declares `links`; the default draws their labels in the subtle colour after a middle dot, wrapped in `data-slot="vk-relation-roles"`), `Loading` (a wait: the list reloading, or more rows arriving; the default is a plain ring) `LoadMore` (how a list asks for its next page; the default watches a sentinel past the last row) and `PlatformMark` (a link's platform, drawn before it, read from its address with the conventions' platforms; the default draws nothing, so a link looks plain, and the package ships no brand art, so an app that wants marks draws its own by the platform's key into `data-slot="vk-platform"`), and the rows the panels (`/panels`) draw with: `ChoiceRow` (picks a value: its label, a second line, a right-hand meta, the check when chosen), `CheckRow` (toggles one of many, a tick box on the left), `RadioRow` (picks one of a set, its mark a check or, with `mark="box"`, a tick box; a disabled row's reason in your `Tooltip`), `DirectionButton` (a sort's direction arrow, named `views.panels.direction`), `MenuRow` (a drill-in row: a glyph, the section, where it stands, a chevron), `ToggleRow` (a boolean flipped in place, with a way back named `views.panels.toggle-reset`) and `PanelSearch` (a panel's text box, a filled well with a magnifier). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
311
320
  from the app's colours; an app swaps any of them through the provider's `atoms`, and the rest
312
- stay the defaults.
321
+ stay the defaults. `SelectionSheet` is the phone's sheet of a selection's verbs, opened by the
322
+ selection bar's Actions: the default is the components map's `Sheet` holding the atoms' rows, a group's
323
+ or an options verb's rows opening in place under it and the delete last in words; picking a row closes
324
+ the sheet, then runs it. An app swaps in its own action sheet.
313
325
 
314
326
  A row's `size` is `compact` (13px: a command list's rows, a list of values) or `regular` (the app's
315
327
  menu size, the default). Its label truncates when it is text and is laid out in a row when it is a
@@ -323,7 +335,7 @@ since the flyout is the components map's `Popover`, a dialog of plain rows; and
323
335
  and `open` while that flyout is up (`data-open`, the pressed ground).
324
336
 
325
337
  The defaults mark themselves with `data-slot="vk-list"`, `data-slot="vk-row"`, `data-slot="vk-row-content"`,
326
- `data-slot="vk-tick"`, `data-slot="vk-status"`, `data-slot="vk-marker"`, `data-slot="vk-tag"`, `data-slot="vk-command-menu"`, `data-slot="vk-relation-link"`, `data-slot="vk-relation-roles"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"` and `data-slot="vk-row-menu"`, and
338
+ `data-slot="vk-tick"`, `data-slot="vk-status"`, `data-slot="vk-marker"`, `data-slot="vk-tag"`, `data-slot="vk-command-menu"`, `data-slot="vk-relation-link"`, `data-slot="vk-relation-roles"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"`, `data-slot="vk-row-menu"` and `data-slot="vk-selection-sheet"`, the panels' rows with `data-slot="vk-choice-row"`, `data-slot="vk-check-row"`, `data-slot="vk-radio-row"`, `data-slot="vk-direction"`, `data-slot="vk-menu-row"`, `data-slot="vk-toggle-row"` and `data-slot="vk-panel-search"`, and
327
339
  with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked`, `data-open` (flags),
328
340
  `data-status` (the slot's name) and `data-platform` (a link's platform key). A swapped atom marks itself as its app does.
329
341
 
@@ -364,6 +376,8 @@ The grid's menus: `moveLeft` `moveRight` `group` `clearSort` `sortRowsUp` `sortR
364
376
  `sortRowsDown` are a menu's verbs, sorting the rows by a column; `sortAsc` and `sortDesc` are the mark a
365
377
  sorted header wears.
366
378
 
379
+ The panels: `search` (a panel's text box, a magnifier) and `reset` (a setting's way back to the reader's default).
380
+
367
381
  An app maps its own icon names onto these in its adapter; a glyph the rendering needs that is not
368
382
  here is added here first, with a changelog line.
369
383
 
@@ -372,7 +386,7 @@ here is added here first, with a changelog line.
372
386
  The package words only its own strings; a string `@viewkitjs/fields` already keys stays a fields
373
387
  message, read from the conventions the provider carries. The package's are a closed list of
374
388
  `{ key, values }` messages under `views.grid.*`,
375
- `views.editors.*`, `views.menus.*` and `views.display.*`: `views.editors.tag-remove` (`{ label }`),
389
+ `views.editors.*`, `views.menus.*`, `views.display.*`, `views.selection.*` and `views.panels.*`: `views.editors.tag-remove` (`{ label }`),
376
390
  `views.editors.marker-resolve`, `views.editors.marker-no-reason`, `views.editors.range-low` and
377
391
  `views.editors.range-high` (a range editor's two boxes, "From" and "To"), and `views.editors.name-given`,
378
392
  `views.editors.name-family` and `views.editors.name-full` (a name editor's three boxes); `views.editors.values-add` ("Add"), `views.editors.values-label` ("Label"), `views.editors.values-main` ("Main", the main value's mark), `views.editors.values-make-main` (`{ value }`, "Make {value} the main one") and `views.editors.values-remove` (`{ value }`, "Remove {value}") (a value list editor's rows); `views.editors.discard` ("Discard", the editor sheet's ✕) and `views.editors.save` ("Save", its ✓); `views.editors.open-email`, `views.editors.open-phone` and `views.editors.open-link` (`{ value }`, "Email {value}", "Call {value}", "Open {value}", the open action beside a stored value in a phone's sheet); the place editor's: `views.editors.place-country` ("Country"), `views.editors.place-country-search` ("Search countries"), `views.editors.place-change-country` ("Change country"), `views.editors.place-region-search` ("Search"), `views.editors.place-line1` ("Address line 1"), `views.editors.place-line2` ("Address line 2"), `views.editors.place-required` (`{ label }`, "{label} *", a part its country asks for), the region's words `views.editors.place-region-area`, `views.editors.place-region-county`, `views.editors.place-region-department`, `views.editors.place-region-district`, `views.editors.place-region-do-si`, `views.editors.place-region-emirate`, `views.editors.place-region-island`, `views.editors.place-region-oblast`, `views.editors.place-region-parish`, `views.editors.place-region-prefecture`, `views.editors.place-region-province` and `views.editors.place-region-state`, the city's `views.editors.place-city-city`, `views.editors.place-city-district`, `views.editors.place-city-post-town` and `views.editors.place-city-suburb`, and the postal code's `views.editors.place-postal-eircode`, `views.editors.place-postal-pin`, `views.editors.place-postal-postal` and `views.editors.place-postal-zip` (each its word in English: "County", "Do/Si", "Post town", "PIN code", "ZIP code"); `placeWordKey(kind, word)` gives the key for a word `placeFormat` names; `views.editors.place-region` ("Region") beside the place editor's `views.editors.place-country`,
@@ -433,6 +447,35 @@ a batch, once, with the first refusal's words when it has any); and the warnings
433
447
  (the title on a phone stored as typed), and `views.display.converted-from` (`{ code }`, "Converted from USD", the
434
448
  title on a money figure shown in another currency than its record's) and `views.display.as-shown` ("as shown",
435
449
  after that figure under a money editor).
450
+ And the panels' words, for the panels' door a later release publishes: the "For you" heading, `views.panels.for-you`; the Group
451
+ panel's orders, `views.panels.group-order-most` ("Most first"), `views.panels.group-order-fewest`,
452
+ `views.panels.group-order-newest`, `views.panels.group-order-oldest`, `views.panels.group-order-alphabetical`,
453
+ `views.panels.group-order-reverse-alphabetical`, `views.panels.group-order-reversed` (`{ label }`, "Stage, reversed"),
454
+ `views.panels.group-order-default`, `views.panels.group-order-count`, `views.panels.group-order-name` and
455
+ `views.panels.group-order-manual`; a list's joins, `views.panels.join-or` (" or ") and `views.panels.join-and`
456
+ (" and "), which hand the keys below a list already joined, since a value is text or a number; a relation filter's:
457
+ `views.panels.quantifier` (`{ quantifier }`: `"any"`,
458
+ `"none"` or `"every"`), `views.panels.relation-condition-options` (`{ field, options }`: "status is Active or
459
+ Paused"), `views.panels.relation-condition` (`{ field, value }`), `views.panels.relation-sentence`
460
+ (`{ rule, subject, one, many, conditions }`, the whole sentence: "Clients with at least one campaign where status is Active.", its
461
+ `rule` `"all"`, `"any"`, `"none"`, `"every"` or `"every-unmatched"`), `views.panels.relation-value-one`
462
+ (`{ quantifier, field, value }`, "Any · Status: Active") and `views.panels.relation-value-many`
463
+ (`{ quantifier, count }`); a row's value: `views.panels.filter-unavailable` ("Saved filter unavailable"), `views.panels.filter-all`
464
+ ("All"), `views.panels.filter-all-of` (`{ field }`, "All owners"), `views.panels.filter-selected` (`{ count }`),
465
+ `views.panels.date-range-all` ("All time"), `views.panels.date-range-between` (`{ from, to }`, "Jan 1 — Jan 9"),
466
+ `views.panels.date-range-from`, `views.panels.date-range-until`, `views.panels.time-scope-custom` ("Custom"),
467
+ `views.panels.sort-value` (`{ label, dir }`, "Name desc"), `views.panels.group-none` ("None") and
468
+ `views.panels.filter-count` (`{ count }`: "None", "1 filter", "2 filters"); and the rows':
469
+ `views.panels.direction` (`{ dir }`, "Direction: ascending"), `views.panels.toggle-reset` (`{ label }`, "Reset
470
+ Wrap"), `views.panels.toggle-reset-hint` ("Back to your default") and `views.panels.search-clear` ("Clear"). The
471
+ panels' label functions take the resolver last; each defaults to `resolveViewsMessage`.
472
+ The selection bar's words are under `views.selection.*`: `views.selection.count` (`{ count }`, "3 selected",
473
+ the phone sheet's title), `views.selection.selected` (the word after the count the bar draws),
474
+ `views.selection.deselect-all` (the count chip), `views.selection.clear` (the phone's ✕),
475
+ `views.selection.delete` (the trash's default name), `views.selection.more` and
476
+ `views.selection.more-label` (More, and its accessible name), `views.selection.actions` (the phone's
477
+ Actions), `views.selection.sheet-label` (the sheet's accessible name) and `views.selection.escape`
478
+ (the key cap in the chip's tooltip).
436
479
  A span behind now is fields' own `time.ago`. The provider's `messages` resolves them; it defaults to the
437
480
  package's English, `resolveViewsMessage`; an app's resolver that words only some keys calls
438
481
  `resolveViewsMessage` for the rest, since the provider does not fall back for it. A new key is a
@@ -479,7 +522,7 @@ A field whose changes are transitions with rules of their own (a lost deal needs
479
522
 
480
523
  ## The doors
481
524
 
482
- Twenty-one doors, and nothing else is importable but `./package.json`. What each holds is summarised here; each door's reference page names every export, one line each, starting at [`reference/views.md`](reference/views.md).
525
+ Twenty-one doors in this version, and nothing else is importable but `./package.json`; the twenty-second, the panels', is described last and comes in a later release. What each holds is summarised here; each door's reference page names every export, one line each, starting at [`reference/views.md`](reference/views.md).
483
526
 
484
527
  `@viewkitjs/views`, no React at runtime, holds two things. The rendering contract, every name listed:
485
528
  the constants `VK_PREFIX`, `GRID_SLOTS`, `GRID_STATES`, `VK_TOKENS`, `VK_COLOURS`,
@@ -622,8 +665,19 @@ an app writes its props against, `GridSortState`, `GridGroupSortOption`, `GridCe
622
665
  host's binding shares with the grid: `GridCommitContext` and `GridCommitOutcome` (what a commit was and how it ended),
623
666
  `deriveGridSelectValues` and `deriveGridRelationValues` (the values a column's filter offers),
624
667
  `cellCopyText` and `cellEditBaseline` (a cell's copy text and the value an edit starts from, which a
625
- CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The selection bar, the house menu rows, the group
626
- collapse and the type icons are the app's.
668
+ CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The house menu rows, the group collapse and the type
669
+ icons are the app's; the selection bar is `SelectionBar`, on the selection door, drawn with the app's verbs.
670
+
671
+ `@viewkitjs/views/panels`, not in this version (a later release publishes it, with the controls), no client
672
+ directive on the door, the one hook behind it (`useFilterOpened`) carrying
673
+ its own: what a list's panels read and say. The settings they edit (`SortConfig`, `GroupConfig`, `ToggleConfig`,
674
+ `LayoutConfig` and its parts, `TimeScopeConfig`, `DateRangeConfig`, `ActivePanel`, `ViewOptionInputs`,
675
+ `CollectionViewState`) with their predicates and `clearViewOptions`; which sections exist on a viewport
676
+ (`getViewOptionAvailability`, `resolvePersonalSection`); the Group panel's orders (`groupSortChoices`); and every
677
+ row's value (`filterValueLabel`, `relationSentence`, `sortValueLabel` and their siblings), each worded through a
678
+ `views.panels.*` key, the resolver taken last. The panels themselves join it as they move in. It is the one door
679
+ that may reach dnd-kit (`@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`), the package's optional peers,
680
+ which a panel's list drags with: an app that takes only the grid never installs them. The panels' rows are atoms.
627
681
 
628
682
  ## Registry items
629
683
 
@@ -8,7 +8,7 @@ This page takes you from install to a grid of records drawn with your own primit
8
8
  pnpm add @viewkitjs/views @viewkitjs/fields zod
9
9
  ```
10
10
 
11
- `react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The package is ESM only and runs on Node 20 or later.
11
+ `react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The dnd-kit packages are optional peers of views, for the panels' door a later release publishes; this version needs none of them. The package is ESM only and runs on Node 20 or later.
12
12
 
13
13
  The rendering carries Tailwind classes drawn from your tokens and paints through its own colour names. Two lines of setup make it look like your app: one `@source` line, so Tailwind sees the package, and one block mapping the `--vk-*` colours onto your theme. [Install](install.md) has both.
14
14
 
@@ -20,6 +20,7 @@ The components map hands the package your primitives: a button, a popover, a men
20
20
  - `LoadMore`: how a list asks for its next page.
21
21
  - `PlatformMark`: a link's platform mark, drawn before the link.
22
22
  - `RowMenu`: the row's right-click menu.
23
+ - `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`: the rows the panels (`/panels`) draw with, a value row, a tick row, a one-of-a-set row, a sort's direction arrow, a drill-in row, a switch row and a panel's text box.
23
24
 
24
25
  The names are `ATOM_NAMES` from `@viewkitjs/views`, and the defaults hold exactly those.
25
26
 
@@ -251,7 +252,7 @@ Inside a command list's item, which owns the element, the highlight and the keyb
251
252
 
252
253
  ## Styling the defaults
253
254
 
254
- The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform` and `vk-row-menu` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
255
+ The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform`, `vk-row-menu`, and the panels' `vk-choice-row`, `vk-check-row`, `vk-radio-row`, `vk-direction`, `vk-menu-row`, `vk-toggle-row` and `vk-panel-search` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
255
256
 
256
257
  ```css
257
258
  [data-slot="vk-row"][data-open] {
@@ -1,6 +1,6 @@
1
1
  # Selection
2
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.
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, the rules a row follows and the bar a selection opens; what its verbs do is 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
4
 
5
5
  ## A list's selection
6
6
 
@@ -31,6 +31,7 @@ import {
31
31
  ROW_NO_TEXT_SELECT,
32
32
  ROW_OPEN_STOP_SELECTOR,
33
33
  SelectCheckbox,
34
+ SelectionBar,
34
35
  selectFromClick,
35
36
  useCheckDragSelect,
36
37
  useEscapeToClear,
@@ -38,6 +39,7 @@ import {
38
39
  useRestIntent,
39
40
  type ListBatchApi,
40
41
  type ListSelectionConfig,
42
+ type SelectionVerb,
41
43
  type UseListSelectionResult,
42
44
  } from "@viewkitjs/views/selection";
43
45
 
@@ -195,41 +197,51 @@ function DealList({ deals, filterKey }: { deals: Deal[]; filterKey: string }) {
195
197
  }
196
198
  ```
197
199
 
198
- ## The bar is yours
200
+ ## The bar
199
201
 
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`.
202
+ `SelectionBar` is the bar a selection opens: the count, which clears the selection when pressed (Escape does too, where the list wires `useEscapeToClear`, as the grid does), your verbs, a trash when you hand `onDelete`, and More. On a desktop it floats as an island at the foot of the screen, the first four verbs on it and the rest in More; on a phone it is a pill reading "3 selected · Actions · ✕", whose Actions open a sheet of every verb. It draws nothing while `count` is zero, so a `renderBar` can always return it.
203
+
204
+ What a selection lets a person do (move twelve deals to a stage, export them, delete them) is your app's. You hand the bar its verbs as data, a `SelectionVerb` each, and each verb's handler calls your own action over the selected ids, then `clear`; an agent working through your actions does the same thing. A verb is one of three kinds:
205
+
206
+ - `action`: a button, with its `label`, an optional `icon` and `onClick`; `destructive` paints it in the danger colour;
207
+ - `group`: a button opening a small menu of `items`, each an action;
208
+ - `options`: one field set on every selected row, its `options` drawn as the badges a cell shows (a `PickerOption` each), `onSelect` handed the value picked.
209
+
210
+ Delete is not a verb: it is the bar's own `onDelete`, drawn as the trailing trash in the same place on every list (in words, last, in the phone's sheet). `busy` disables everything while a batch runs.
201
211
 
202
212
  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
213
 
204
214
  ```tsx
205
215
  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");
216
+ const moveTo = async (stage: string) => {
217
+ const landed = await batch?.setColumnValue([...sel.selectedIds], "stage", stage);
209
218
  if (landed) sel.clear();
210
219
  };
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
- );
220
+ const verbs: SelectionVerb[] = batch
221
+ ? [
222
+ {
223
+ kind: "options",
224
+ label: "Move to stage",
225
+ options: [
226
+ { value: "proposal", label: "Proposal", slot: "running" },
227
+ { value: "won", label: "Won", slot: "success" },
228
+ ],
229
+ onSelect: (stage) => void moveTo(stage),
230
+ },
231
+ ]
232
+ : [];
233
+ return <SelectionBar count={sel.count} onClear={sel.clear} verbs={verbs} />;
224
234
  }
225
235
  ```
226
236
 
237
+ Where the bar sits is yours, set once on the provider's `selectionBar`: its `bottom`, `zIndex` and `className` on each form, and a `phoneQuery` when your shell's phone layout starts at another width (an app with a bottom nav lifts the pill above it). The phone's sheet is the `SelectionSheet` atom: its default is your `Sheet` holding plain rows, and you swap in your own action sheet through the provider's `atoms`.
238
+
227
239
  ## The grid takes a selection
228
240
 
229
241
  `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
242
 
231
243
  - `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;
244
+ - optionally `renderBar(sel, batch?)`: the bar, drawn from the selection and, when the grid can write (you passed `onCellCommit`), its `ListBatchApi`. The grid calls it on every render, and `SelectionBar` draws nothing while `sel.count` is zero. Leave it out and rows still tick, with no bar;
233
245
  - optionally `orderedIds`, when the order a range runs over is not the grid's rows as drawn, and `retention`.
234
246
 
235
247
  ```tsx
@@ -169,7 +169,8 @@ The header's menu offers Sort ascending, Sort descending and Clear sort, and Gro
169
169
 
170
170
  ```tsx
171
171
  import { useMemo, useState } from "react";
172
- import { columnLabel, sortableColumns, sortDirFor, type OrderDir } from "@viewkitjs/views";
172
+ import type { SortDirection } from "@viewkitjs/fields/query";
173
+ import { columnLabel, sortableColumns, sortDirFor } from "@viewkitjs/views";
173
174
  import type { GridGroupByState, GridGroupSortOption, GridSortState } from "@viewkitjs/views/grid";
174
175
 
175
176
  const dealSortOptions: GridGroupSortOption[] = sortableColumns(columns).map((entry) => ({
@@ -191,7 +192,7 @@ assert.deepEqual(
191
192
  );
192
193
 
193
194
  function SortedDeals({ deals, onOpen }: { deals: Deal[]; onOpen: (deal: Deal) => void }) {
194
- const [order, setOrder] = useState<{ value: string; dir: OrderDir }>({ value: "value", dir: "desc" });
195
+ const [order, setOrder] = useState<{ value: string; dir: SortDirection }>({ value: "value", dir: "desc" });
195
196
  const [groupKey, setGroupKey] = useState<string | null>("stage");
196
197
  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set());
197
198
 
@@ -4,7 +4,7 @@ Every view reads what it takes from its app, other than its own props, from one
4
4
 
5
5
  ## Mount it once
6
6
 
7
- `ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Eight more are optional: `atoms`, `messages`, `presentation`, `desktopQuery`, `sheetActions`, `escape`, `sayRefusals` and `menus`.
7
+ `ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Nine more are optional: `atoms`, `messages`, `presentation`, `desktopQuery`, `sheetActions`, `escape`, `sayRefusals`, `menus` and `selectionBar`.
8
8
 
9
9
  `desktopQuery` says which screens are desktops: there an editor opens as a popover, and elsewhere as a sheet. It defaults to `DEFAULT_DESKTOP_QUERY`, `(min-width: 1024px)`; hand in the query your own shell switches on, so the editors and your layout change at the same width. A server render counts as a desktop.
10
10
 
@@ -14,6 +14,8 @@ Every view reads what it takes from its app, other than its own props, from one
14
14
 
15
15
  `sheetActions` says where an editor's ✕ and ✓ stand in that sheet. `bar`, the default, is the editor panel's own bar inside your `Sheet`. `head` hands them to your `Sheet` as `actions` (`close`, and `done` unless the body saves on its pick), for a sheet that draws them in its own head, and the panel draws no bar.
16
16
 
17
+ `selectionBar` says where the selection bar sits: its `bottom`, its `zIndex` and your `className` on the desktop and on the phone, and a `phoneQuery` when your shell switches to its phone layout at another width than `desktopQuery`. An app with a bottom nav lifts the phone's pill above it; pass a module-level object.
18
+
17
19
  `menus` says how the grid opens its own menus. `popover`, the default, draws ViewKit's rows in your `Popover`. `menu` hands them to your `Menu` as rows: today the footer's figure picker, one ticked row per figure, a column's header menu, each format setting and each option's colour a group beside it, a group's ⋯, its sort choices a group beside it with no search field and its figure toggles ticks that keep the menu open, and the grid's own "+ Add column", each field with parts a group beside it, with no search field and on a phone too. The row menu and a command cell's menu always go through your `Menu`.
18
20
 
19
21
  Each piece lives in a module of its own, which the sections below write. Here they are declared, so the page compiles without them.
@@ -350,7 +352,7 @@ These are the package's glyphs. The ones a host names itself, a row's icon or a
350
352
 
351
353
  ## Messages
352
354
 
353
- The package words only its own strings. They are a closed list of messages, each a `key` under `views.grid.*`, `views.editors.*`, `views.menus.*` or `views.display.*` and, where the sentence carries something, its `values`: `{ key: "views.menus.group-by", values: { field: "Stage" } }`. The [contract](../contract.md#message-keys) lists every key with its English. A string `@viewkitjs/fields` already keys stays a fields message, worded through the conventions.
355
+ The package words only its own strings. They are a closed list of messages, each a `key` under `views.grid.*`, `views.editors.*`, `views.menus.*`, `views.display.*`, `views.selection.*` or `views.panels.*` and, where the sentence carries something, its `values`: `{ key: "views.menus.group-by", values: { field: "Stage" } }`. The [contract](../contract.md#message-keys) lists every key with its English. A string `@viewkitjs/fields` already keys stays a fields message, worded through the conventions.
354
356
 
355
357
  `messages` is a `ViewsMessageResolver`, a function from a `ViewsMessage` to its text. It defaults to `resolveViewsMessage`, the package's English. The provider doesn't fall back for you: a resolver that words only some keys calls `resolveViewsMessage` for the rest.
356
358
 
package/docs/index.md CHANGED
@@ -50,3 +50,5 @@ One page per door. Each lists every name the door exports.
50
50
  - [`@viewkitjs/views/cells`](reference/cells.md): a column's typed cell
51
51
  - [`@viewkitjs/views/selection`](reference/selection.md): a list's selection
52
52
  - [`@viewkitjs/views/grid`](reference/grid.md): the grid, its props and the helpers a host shares with it
53
+
54
+ `@viewkitjs/views/panels`, what a list's panels read and say, is not in this version: it is still being built, and a later release publishes it with the controls. Its rows, icons and words are already here.
package/docs/install.md CHANGED
@@ -6,7 +6,10 @@
6
6
  pnpm add @viewkitjs/views @viewkitjs/fields zod
7
7
  ```
8
8
 
9
- `react` and `react-dom` 19 are peers you already have. ESM only, Node 20 or later.
9
+ `react` and `react-dom` 19 are peers you already have. `@dnd-kit/core`, `@dnd-kit/sortable` and
10
+ `@dnd-kit/utilities` are optional peers for the panels' door, which a later release publishes: this
11
+ version needs none of them. ESM only,
12
+ Node 20 or later.
10
13
 
11
14
  2. **Let Tailwind see it.** The rendering carries Tailwind classes drawn from your own tokens. Add one
12
15
  line to the stylesheet that imports Tailwind:
@@ -1,13 +1,13 @@
1
1
  # `@viewkitjs/views/grid`
2
2
 
3
- The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The 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).
3
+ The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. The bar a selection opens is `SelectionBar` from `@viewkitjs/views/selection`, which your `selection`'s `renderBar` draws with your verbs. Guide: [the grid](../guides/the-grid.md).
4
4
 
5
5
  ## The grid
6
6
 
7
7
  - `GridTable` — draws the spreadsheet: rows in their groups under a header whose column menus sort, group, format and hide, a checkbox rail and a ⋯ tail on each row, editors opened over cells, a selected range with copy, paste and undo, and a footer of figures per column. An edit shows in its cell at once and goes to `onCellCommit` (a batch to `onCellsCommit`); a failed write rolls the cell back. While `transitionPending` is true, or for one commit after `transitionKey` changes, it draws your app's loading atom instead of the rows. It takes a `GridTableProps`.
8
8
  - `GridTableProps` — what `GridTable` takes, flat, typed over your row. Five are required: `groups` (the rows, as the model's `ListGroup`s), `grouped` (whether they draw as group bands), `getRowId`, `columns` (the model's `ListColumn`s) and `onOpenRow` (what opening a row does: the title's text opens it; it receives the row and a `GridRowOpenedFrom`, which brings the focus back to the row's cell once what it opened closes). The rest are optional:
9
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).
10
+ - Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; its optional `renderBar` draws the bar it opens, `SelectionBar` with your verbs, and without one the rows still tick and no bar is drawn).
11
11
  - Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupMenu` (the parts a group band's ⋯ holds, as `GridGroupMenuPart`s: `"sort"`, `"figures"`, `"hide"`; with it the sort list always searches through your `Command` on the `popover` route), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
12
12
  - Format overrides and their handlers, every map keyed by field key: `optionColors`, `dateStyles`, `durationStyles`, `numberFormats` (decimals null is the field's own), `showTimeOverrides` and `percentDisplays`, each with its `on…Change` handler taking the field key first, and `formatsWritable` (false hides the stored format knobs from the column menu; default true).
13
13
  - Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, or answering `undefined`, `false` or `""`, the grid's own lists the hidden columns; answering `null`, none is drawn and no room is kept for it), `addColumnOnPhone` ("+ Add column" on a phone too, its list in your `Sheet`, or your `Menu` on the `menu` route; off by default), `parts` (a column per part of a name, a place or a range, offered under its field in "+ Add column"; off by default), `renderColumnMenuRows` (your rows in a column's menu, above Hide), `columnMenuItems` (the same rows as data, on the `menu` route), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`.
@@ -7,14 +7,14 @@ Import from `@viewkitjs/views/react` in a client component: the door opens with
7
7
  Guide: [the provider](../guides/the-provider.md).
8
8
 
9
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. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`. Its optional `sheetActions` (`ViewsSheetActionsPlace`, default `bar`) says where an editor's ✕ and ✓ stand in that sheet. Its optional `escape` (`ViewsEscapeRules`) says what Escape does in an editor of each field type on a desktop, `"keep"` or `"cancel"`, a type left out cancelling. Its optional `sayRefusals` (default false) has the grid say, through the toast port's `error`, why your app refused an edit it sent. Its optional `menus` (`ViewsMenuRoute`, default `popover`) says how the grid opens its own menus: in your `Popover` with ViewKit's rows, or through your `Menu`.
10
+ - `ViewsProviderProps` — what the provider takes. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`. Its optional `sheetActions` (`ViewsSheetActionsPlace`, default `bar`) says where an editor's ✕ and ✓ stand in that sheet. Its optional `escape` (`ViewsEscapeRules`) says what Escape does in an editor of each field type on a desktop, `"keep"` or `"cancel"`, a type left out cancelling. Its optional `sayRefusals` (default false) has the grid say, through the toast port's `error`, why your app refused an edit it sent. Its optional `menus` (`ViewsMenuRoute`, default `popover`) says how the grid opens its own menus: in your `Popover` with ViewKit's rows, or through your `Menu`. Its optional `selectionBar` (`ViewsSelectionBarSettings`) says where the selection bar sits.
11
11
  - `EditEscape` — `"cancel" | "keep"`: what Escape does in an edit session (`@viewkitjs/views/editors/session` hands it on too).
12
12
  - `ViewsEscapeRules` — `Partial<Record<FieldType, EditEscape>>`, the provider's `escape`.
13
13
  - `DEFAULT_DESKTOP_QUERY` — `(min-width: 1024px)`: the width a desktop starts at when the provider is handed no `desktopQuery`. Where the screen can't be asked (a server render, a browser with no `matchMedia`), it is a desktop.
14
14
  - 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`.
15
15
  - 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.
16
16
  - `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.
17
- - `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`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`); `escape` and `sayRefusals` when you handed them; and `menus`, how the grid opens its own menus (absent means `popover`).
17
+ - `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`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`); `escape` and `sayRefusals` when you handed them; and `menus`, how the grid opens its own menus (absent means `popover`); `selectionBar` when you handed it.
18
18
  - `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.
19
19
 
20
20
  ## The components map
@@ -44,6 +44,8 @@ The primitives your app hands in, modelled on Base UI's shapes: a controlled `op
44
44
  - `ViewsSheetActions` — the editor panel's ✕ and ✓, handed to a sheet that draws them in its head: `close`, which throws the edit away as a swipe does, and `done`, which closes it as done, absent where the body saves on its pick.
45
45
  - `ViewsSheetAction` — one of them: its `label` (the accessible name) and `onPress`. The glyph is yours.
46
46
  - `ViewsMenuRoute` — `"popover" | "menu"`, the provider's `menus`: how the grid opens its own menus (a column's, a footer's figure picker, a group's ⋯, Add column). `popover` (the default) draws ViewKit's rows in your `Popover`; `menu` hands your `Menu` its rows as data. The row menu and a command cell's menu always go through your `Menu`.
47
+ - `ViewsSelectionBarSettings` — the provider's `selectionBar`: `phoneQuery` (the media query under which the bar is the phone's pill; without it, wherever `desktopQuery` does not match), and `desktop` and `phone`, each a `ViewsBarPlacement`.
48
+ - `ViewsBarPlacement` — where the selection bar's fixed box sits on one form: `bottom` (a CSS length, default `calc(1rem + env(safe-area-inset-bottom))`), `zIndex` (default 50) and `className` (your own classes on the box).
47
49
  - `ViewsSheetActionsPlace` — where the ✕ and ✓ stand on a phone, the provider's `sheetActions`: `bar` (the default, the panel's own bar inside your sheet) or `head` (handed to your sheet as `actions`, and no bar).
48
50
  - `ViewsInputProps` — a single-line text box: every prop of an `<input>`, `ref` included, which your element must receive, and `chrome`, `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame).
49
51
  - `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
@@ -81,7 +83,14 @@ Guide: [atoms](../guides/atoms.md).
81
83
  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.
82
84
 
83
85
  - `DEFAULT_VIEWS_ATOMS` — the atoms every app starts with, one default per name of `ViewsAtoms`; the provider lays your `atoms` over it.
84
- - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `RelationRoles`, `Loading`, `LoadMore`, `PlatformMark` and `RowMenu`. The provider's `atoms` takes any part of it.
86
+ - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `RelationRoles`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu`, and the panels' rows `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`. The provider's `atoms` takes any part of it.
87
+ - `ViewsChoiceRowProps` — a panel's value row: `label`, a `description` under it, a right-hand `meta` (a sample, a count; a row with one draws no check), `leading`, `trailing`, `selected`, `onClick`, `onMouseDown`, `disabled`, `role` and `aria-selected`.
88
+ - `ViewsCheckRowProps` — toggles one of many, a tick box on the left: `checked`, `onClick`, its `children`, `leading`, `trailing`, `disabled`.
89
+ - `ViewsRadioRowProps` — picks one of a set: `selected`, `label`, `onClick`, `leading`, `trailing`, `mark` (`"check"` or `"box"`), `disabled` and the `disabledReason` your `Tooltip` shows, and class hooks for the check and the label.
90
+ - `ViewsDirectionButtonProps` — a sort's direction arrow: `dir` (`"asc"` or `"desc"`) and `onClick`; a press never reaches the row around it.
91
+ - `ViewsMenuRowProps` — a drill-in row: `icon`, `label`, `value` (where the section stands), `active`, `disabled`, `onClick`.
92
+ - `ViewsToggleRowProps` — a boolean flipped in place: `icon`, `label`, `active`, `disabled`, `onClick`, and `reset` (`{ onReset }`), the way back to the reader's default.
93
+ - `ViewsPanelSearchProps` — a panel's text box: `value`, `onChange`, `onClear`, `placeholder`, `autoFocus`, `onKeyDown`, `onFocus`, `inputRef`, `leading` (`null` drops the magnifier), `suffix` and `inputMode`.
85
94
  - `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.
86
95
  - `ViewsRowContentProps` — a row's inside, all the row is inside a command list's item, which owns the element, the highlight and the keyboard.
87
96
  - 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.
@@ -92,6 +101,7 @@ The pieces the rendering is built from, and your app's own pieces it cannot draw
92
101
  - `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.
93
102
  - `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).
94
103
  - `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.
104
+ - `ViewsSelectionSheetProps` — the phone's sheet of a selection's verbs, opened by the selection bar's Actions: `open`, `onOpenChange`, `title` ("3 selected"), the `verbs`, `onDelete` and `deleteLabel` for the bar's own delete, drawn last, and `busy`. Picking a row closes the sheet, then runs it.
95
105
  - `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.
96
106
  - `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.
97
107
  - `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.
@@ -1,6 +1,6 @@
1
1
  # `@viewkitjs/views/selection`
2
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.
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, the rest that starts a record's read before the click, and the bar a selection opens. 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. What the bar's verbs do stays your app's.
4
4
 
5
5
  ## The selection
6
6
 
@@ -10,9 +10,17 @@ Guide: [selection](../guides/selection.md).
10
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
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
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`.
13
+ - `ListSelectionConfig` — what a list or table takes to be selectable (the grid's `selection`): `resetKey` (the selection clears when it changes), with optional `renderBar` (draws the bar from the selection and, when the renderer can write, a `ListBatchApi`; left out, rows still tick and no bar is drawn), `orderedIds` and `retention`.
14
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
15
 
16
+ ## The bar
17
+
18
+ - `SelectionBar` — the bar a selection opens, portalled to the body and placed by the provider's `selectionBar`. On a desktop, an island: the count chip (a press clears the selection; its tooltip names Escape), the first four verbs, the trash when `onDelete` is handed, a hairline and More, always drawn, holding the rest (a group or an options verb opening its rows beside it). On a phone, a pill reading the count, Actions and ✕; Actions opens the `SelectionSheet` atom. It draws nothing while `count` is zero.
19
+ - `SelectionBarProps` — what `SelectionBar` takes: `count`, `onClear`, `verbs` (`SelectionVerb`s, in order), optional `busy` (disables every control), `onDelete` (the bar's own verb, the trailing trash; never a verb in `verbs`) and `deleteLabel` (the trash's name; default the `views.selection.delete` message).
20
+ - `SelectionVerb` — one verb, as data: `{ kind: "action" }` with a `SelectionVerbItem`'s fields; `{ kind: "group", label, icon?, disabled?, items }`, a button opening a menu of `SelectionVerbItem`s; or a `SelectionOptionsVerb`.
21
+ - `SelectionVerbItem` — an action: `label`, optional `icon` (your glyph), `onClick`, `destructive` (the danger colour) and `disabled`.
22
+ - `SelectionOptionsVerb` — one field set on every selected row: `{ kind: "options", label, icon?, disabled?, options, onSelect }`, its `options` `PickerOption`s drawn as the badges a cell shows, `onSelect` handed the value picked. It closes, then runs.
23
+
16
24
  ## Picking rows with the pointer
17
25
 
18
26
  - `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.