@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.
Files changed (246) hide show
  1. package/CHANGELOG.md +196 -1
  2. package/README.md +90 -41
  3. package/dist/atoms/Row.js +1 -1
  4. package/dist/atoms/RowMenu.d.ts +1 -1
  5. package/dist/atoms/RowMenu.js +15 -4
  6. package/dist/atoms/types.d.ts +4 -4
  7. package/dist/contract.d.ts +37 -7
  8. package/dist/contract.js +24 -5
  9. package/dist/display/format.d.ts +16 -1
  10. package/dist/display/format.js +10 -1
  11. package/dist/display/index.d.ts +1 -1
  12. package/dist/display/index.js +1 -1
  13. package/dist/display/link.js +5 -3
  14. package/dist/display/location.d.ts +4 -3
  15. package/dist/display/location.js +12 -5
  16. package/dist/display/options.d.ts +1 -1
  17. package/dist/display/percent.js +10 -3
  18. package/dist/display/phone.d.ts +2 -1
  19. package/dist/display/phone.js +8 -1
  20. package/dist/display/relation.js +1 -1
  21. package/dist/editors/ChipsEditor.js +1 -1
  22. package/dist/editors/LocationEditor.js +16 -17
  23. package/dist/editors/NameEditor.js +5 -4
  24. package/dist/editors/NumberEditor.js +2 -2
  25. package/dist/editors/RangeEditor.js +2 -2
  26. package/dist/editors/ValueListEditor.d.ts +2 -2
  27. package/dist/editors/ValueListEditor.js +8 -8
  28. package/dist/editors/edit-cores.d.ts +1 -1
  29. package/dist/fields/binding.d.ts +1 -1
  30. package/dist/fields/currency.d.ts +0 -10
  31. package/dist/fields/currency.js +0 -14
  32. package/dist/fields/money.d.ts +1 -0
  33. package/dist/fields/money.js +1 -0
  34. package/dist/filters/filter-model.d.ts +0 -1
  35. package/dist/filters/registry.d.ts +3 -36
  36. package/dist/filters/registry.js +0 -38
  37. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  38. package/dist/grid/chrome/GridAddColumn.js +29 -0
  39. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  40. package/dist/grid/chrome/GridAggregateMenu.js +27 -0
  41. package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
  42. package/dist/grid/chrome/GridCellEditors.js +55 -0
  43. package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
  44. package/dist/grid/chrome/GridCellOutline.js +21 -0
  45. package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
  46. package/dist/grid/chrome/GridChipsEditor.js +40 -0
  47. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  48. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  49. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  50. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  51. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  52. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  53. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  54. package/dist/grid/chrome/GridColumnMenu.js +99 -0
  55. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  56. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  57. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  58. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  59. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  60. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  61. package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
  62. package/dist/grid/chrome/GridDateEditor.js +31 -0
  63. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  64. package/dist/grid/chrome/GridFlyout.js +80 -0
  65. package/dist/grid/chrome/GridFooter.d.ts +23 -0
  66. package/dist/grid/chrome/GridFooter.js +81 -0
  67. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  68. package/dist/grid/chrome/GridGroupMenu.js +57 -0
  69. package/dist/grid/chrome/GridHeader.d.ts +61 -0
  70. package/dist/grid/chrome/GridHeader.js +37 -0
  71. package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
  72. package/dist/grid/chrome/GridLongTextEditor.js +127 -0
  73. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  74. package/dist/grid/chrome/GridMenuRow.js +15 -0
  75. package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
  76. package/dist/grid/chrome/GridNameEditor.js +36 -0
  77. package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
  78. package/dist/grid/chrome/GridNumberEditor.js +25 -0
  79. package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
  80. package/dist/grid/chrome/GridRangeEditor.js +25 -0
  81. package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
  82. package/dist/grid/chrome/GridRelationEditor.js +30 -0
  83. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  84. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  85. package/dist/grid/chrome/GridRow.d.ts +25 -0
  86. package/dist/grid/chrome/GridRow.js +136 -0
  87. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  88. package/dist/grid/chrome/GridRowActions.js +25 -0
  89. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  90. package/dist/grid/chrome/GridRowCells.js +133 -0
  91. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  92. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  93. package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
  94. package/dist/grid/chrome/GridSelectEditor.js +49 -0
  95. package/dist/grid/chrome/GridStructure.d.ts +48 -0
  96. package/dist/grid/chrome/GridStructure.js +45 -0
  97. package/dist/grid/chrome/GridTable.d.ts +4 -0
  98. package/dist/grid/chrome/GridTable.js +125 -0
  99. package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
  100. package/dist/grid/chrome/GridTableSurface.js +6 -0
  101. package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
  102. package/dist/grid/chrome/GridTextEditor.js +40 -0
  103. package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
  104. package/dist/grid/chrome/GridValueListEditor.js +36 -0
  105. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  106. package/dist/grid/chrome/StuckMarker.js +34 -0
  107. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  108. package/dist/grid/chrome/cell-clipboard.js +28 -0
  109. package/dist/grid/chrome/cells.d.ts +21 -0
  110. package/dist/grid/chrome/cells.js +20 -0
  111. package/dist/grid/chrome/checks.d.ts +35 -0
  112. package/dist/grid/chrome/checks.js +22 -0
  113. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  114. package/dist/grid/chrome/column-glyph.js +44 -0
  115. package/dist/grid/chrome/editors.d.ts +9 -0
  116. package/dist/grid/chrome/editors.js +10 -0
  117. package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
  118. package/dist/grid/chrome/grid-cell-classes.js +30 -0
  119. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  120. package/dist/grid/chrome/grid-menu-search.js +7 -0
  121. package/dist/grid/chrome/grid-row-props.d.ts +131 -0
  122. package/dist/grid/chrome/grid-row-props.js +1 -0
  123. package/dist/grid/chrome/grid-styles.d.ts +37 -0
  124. package/dist/grid/chrome/grid-styles.js +8 -0
  125. package/dist/grid/chrome/grid-table-props.d.ts +173 -0
  126. package/dist/grid/chrome/grid-table-props.js +1 -0
  127. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  128. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  129. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  130. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  131. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  132. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  133. package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
  134. package/dist/grid/chrome/useGridKeyboard.js +274 -0
  135. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  136. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  137. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  138. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  139. package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
  140. package/dist/grid/chrome/useGridRangeActions.js +188 -0
  141. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  142. package/dist/grid/chrome/useGridRangeGestures.js +190 -0
  143. package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
  144. package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
  145. package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
  146. package/dist/grid/chrome/useGridScaleStyles.js +29 -0
  147. package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
  148. package/dist/grid/chrome/useGridScrollSync.js +176 -0
  149. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
  150. package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
  151. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  152. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  153. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  154. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  155. package/dist/grid/core/clipboard-model.d.ts +81 -0
  156. package/dist/grid/core/clipboard-model.js +291 -0
  157. package/dist/grid/core/column-values.d.ts +27 -0
  158. package/dist/grid/core/column-values.js +76 -0
  159. package/dist/grid/core/commit-model.d.ts +34 -0
  160. package/dist/grid/core/commit-model.js +3 -0
  161. package/dist/grid/core/coordinates.d.ts +48 -0
  162. package/dist/grid/core/coordinates.js +27 -0
  163. package/dist/grid/core/edit-values.d.ts +9 -0
  164. package/dist/grid/core/edit-values.js +1 -0
  165. package/dist/grid/core/editing-controller.d.ts +59 -0
  166. package/dist/grid/core/editing-controller.js +240 -0
  167. package/dist/grid/core/editing-model.d.ts +78 -0
  168. package/dist/grid/core/editing-model.js +136 -0
  169. package/dist/grid/core/grid-scale.d.ts +14 -0
  170. package/dist/grid/core/grid-scale.js +8 -0
  171. package/dist/grid/core/nav.d.ts +94 -0
  172. package/dist/grid/core/nav.js +92 -0
  173. package/dist/grid/core/pending-reconciliation.d.ts +50 -0
  174. package/dist/grid/core/pending-reconciliation.js +49 -0
  175. package/dist/grid/core/range-model.d.ts +25 -0
  176. package/dist/grid/core/range-model.js +59 -0
  177. package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
  178. package/dist/grid/core/spreadsheet-operations.js +253 -0
  179. package/dist/grid/core/useGridEditing.d.ts +43 -0
  180. package/dist/grid/core/useGridEditing.js +90 -0
  181. package/dist/grid/core/useGridRange.d.ts +20 -0
  182. package/dist/grid/core/useGridRange.js +24 -0
  183. package/dist/grid/core/value-equality.d.ts +32 -0
  184. package/dist/grid/core/value-equality.js +34 -0
  185. package/dist/grid/index.d.ts +18 -0
  186. package/dist/grid/index.js +5 -0
  187. package/dist/grid/useGridTablePrefs.d.ts +50 -0
  188. package/dist/grid/useGridTablePrefs.js +101 -0
  189. package/dist/index.d.ts +0 -1
  190. package/dist/index.js +0 -1
  191. package/dist/internal/viewport.d.ts +5 -0
  192. package/dist/internal/viewport.js +29 -0
  193. package/dist/model/column-capabilities.d.ts +2 -2
  194. package/dist/model/column-state.d.ts +1 -1
  195. package/dist/model/density.js +3 -3
  196. package/dist/model/filter-capabilities.d.ts +1 -1
  197. package/dist/model/filter-capabilities.js +1 -1
  198. package/dist/model/index.d.ts +4 -6
  199. package/dist/model/index.js +0 -1
  200. package/dist/model/preferences.d.ts +7 -3
  201. package/dist/provider/ViewsProvider.d.ts +1 -1
  202. package/dist/provider/ViewsProvider.js +5 -1
  203. package/dist/provider/components.d.ts +16 -8
  204. package/dist/provider/context.d.ts +3 -2
  205. package/dist/provider/menu-groups.d.ts +8 -0
  206. package/dist/provider/menu-groups.js +38 -0
  207. package/dist/provider/ports.d.ts +22 -0
  208. package/dist/provider/ports.js +1 -0
  209. package/dist/react.d.ts +1 -1
  210. package/docs/contract.md +128 -56
  211. package/docs/getting-started.md +250 -0
  212. package/docs/guides/atoms.md +245 -0
  213. package/docs/guides/cells.md +302 -0
  214. package/docs/guides/columns.md +412 -0
  215. package/docs/guides/display.md +203 -0
  216. package/docs/guides/editors.md +404 -0
  217. package/docs/guides/ports.md +246 -0
  218. package/docs/guides/selection.md +270 -0
  219. package/docs/guides/the-grid.md +677 -0
  220. package/docs/guides/the-provider.md +446 -0
  221. package/docs/index.md +50 -0
  222. package/docs/install.md +9 -47
  223. package/docs/reference/cells.md +28 -0
  224. package/docs/reference/display.md +42 -0
  225. package/docs/reference/editors-chips.md +6 -0
  226. package/docs/reference/editors-date.md +6 -0
  227. package/docs/reference/editors-location.md +10 -0
  228. package/docs/reference/editors-name.md +6 -0
  229. package/docs/reference/editors-number.md +11 -0
  230. package/docs/reference/editors-open-values.md +9 -0
  231. package/docs/reference/editors-range.md +6 -0
  232. package/docs/reference/editors-relation.md +9 -0
  233. package/docs/reference/editors-select.md +8 -0
  234. package/docs/reference/editors-session.md +9 -0
  235. package/docs/reference/editors-value-list.md +6 -0
  236. package/docs/reference/editors.md +5 -0
  237. package/docs/reference/grid.md +39 -0
  238. package/docs/reference/react.md +86 -0
  239. package/docs/reference/selection.md +33 -0
  240. package/docs/reference/views.md +601 -0
  241. package/package.json +7 -3
  242. package/skills/views/SKILL.md +20 -5
  243. package/dist/filters/types.d.ts +0 -27
  244. package/dist/filters/types.js +0 -1
  245. package/dist/model/filter-pushdown.d.ts +0 -106
  246. package/dist/model/filter-pushdown.js +0 -147
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@viewkitjs/views",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "ViewKit views — the grid, board, calendar and list over typed fields: a headless engine and a default rendering written to skin discipline. By Sheaf.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -85,6 +85,10 @@
85
85
  "types": "./dist/selection/index.d.ts",
86
86
  "default": "./dist/selection/index.js"
87
87
  },
88
+ "./grid": {
89
+ "types": "./dist/grid/index.d.ts",
90
+ "default": "./dist/grid/index.js"
91
+ },
88
92
  "./package.json": "./package.json"
89
93
  },
90
94
  "publishConfig": {
@@ -92,7 +96,7 @@
92
96
  "access": "public"
93
97
  },
94
98
  "peerDependencies": {
95
- "@viewkitjs/fields": "^0.8.0",
99
+ "@viewkitjs/fields": "^0.9.0",
96
100
  "react": "^19.0.0",
97
101
  "react-dom": "^19.0.0",
98
102
  "zod": "^4.1.12"
@@ -107,7 +111,7 @@
107
111
  "typescript": "^5",
108
112
  "vitest": "^4.1.5",
109
113
  "zod": "^4.1.12",
110
- "@viewkitjs/fields": "0.8.0"
114
+ "@viewkitjs/fields": "0.9.0"
111
115
  },
112
116
  "scripts": {
113
117
  "typecheck": "tsc -p tsconfig.json",
@@ -5,8 +5,13 @@ description: Mount and adapt @viewkitjs/views — the provider, the components m
5
5
 
6
6
  # ViewKit views
7
7
 
8
- Use the package through its declared doors only — `@viewkitjs/views` and `@viewkitjs/views/react` —
9
- never a deep path.
8
+ Use the package through its eighteen declared doors only, never a deep path: `@viewkitjs/views` (the
9
+ contract and the model), `@viewkitjs/views/react` (the provider, the atoms, the adapter's types),
10
+ `/display`, `/editors`, `/editors/select`, `/editors/relation`, `/editors/number`, `/editors/range`,
11
+ `/editors/name`, `/editors/location`, `/editors/value-list`, `/editors/date`, `/editors/chips`,
12
+ `/editors/session`, `/editors/open-values`, `/cells`, `/selection` and `/grid`. The package's docs
13
+ start at `docs/index.md`: `docs/getting-started.md` goes from install to a grid on screen, a guide per
14
+ concept sits in `docs/guides/`, and `docs/reference/` names every export of each door.
10
15
 
11
16
  ## Mount the provider once
12
17
 
@@ -53,7 +58,7 @@ export function AppViews({ children }: { children: ReactNode }) {
53
58
 
54
59
  ## Write the adapter against the contract
55
60
 
56
- `docs/contract.md` lists the eleven components, the four ports and the icon names. Implement
61
+ `docs/contract.md` lists the eleven components, the five ports (`confirm` optional) and the icon names. Implement
57
62
  `ViewsComponents` over your own shadcn copies: a controlled `open` with `onOpenChange(open, details)`,
58
63
  an `anchor` element or ref on the popover and the menu, and no `asChild`; `AppIcon` is your own
59
64
  icon component by your own names. The shapes are Base UI's; `docs/contract.md`'s "Writing an
@@ -74,14 +79,24 @@ The atoms — `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMark
74
79
  `RelationLink`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu` — ship as defaults drawn from your theme. Swap any of them through `atoms` so the views wear
75
80
  your own menus and pills. `CommandMenu`, `RowMenu` and `RelationLink` are your app's own pieces — the verb menu a
76
81
  command cell opens, the row's right-click menu, and where a relation chip goes; their defaults are the map's menu,
77
- the map's menu at the pointer (its Delete asks the browser's own confirm), and a chip that goes nowhere. `Loading` and `LoadMore` are your waits — the list reloading, and how it asks for more rows; their
82
+ the map's menu at the pointer (its Delete asks the `confirm` port, the browser's own confirm when you hand none), and a chip that goes nowhere. `Loading` and `LoadMore` are your waits — the list reloading, and how it asks for more rows; their
78
83
  defaults are a plain ring and a sentinel past the last row. `PlatformMark` is a link's platform, drawn before
79
84
  it: the package ships no brand art, so its default draws nothing and a link looks plain; you draw your own
80
85
  marks by `platform.key`.
81
86
  The field display is `@viewkitjs/views/display`; the editors are `@viewkitjs/views/editors/<name>`, each
82
87
  drawn through the map and the atoms — your app hosts them (the popover, the anchor, the write) and never
83
88
  writes one. A place's editor is `editors/location` (the country first, then its parts, a region from its list; its
84
- 27 `views.editors.place-*` words are yours to translate). Several emails, phones, links or domains edit in
89
+ 28 `views.editors.place-*` words are yours to translate). Several emails, phones, links or domains edit in
85
90
  `editors/value-list` (a row each: the value, its label, a main mark), committed as one list; bind `labels: false`
86
91
  where your row keeps only the values. A name's editor is `editors/name` (given, family and full); its display draws an empty name
87
92
  as the words you give it, `nameFallback` in the display options or `nameFallback(row)` on a column.
93
+
94
+ ## Draw the grid
95
+
96
+ The grid is `GridTable` from `@viewkitjs/views/grid`. Bind your fields to your rows (`bindFields`), build its
97
+ columns with `columnFrom`, and hand it five props: `groups` (your rows as `ListGroup`s, one group when the list
98
+ is not grouped), `grouped`, `getRowId`, `columns` and `onOpenRow`. An edit reaches your `onCellCommit`
99
+ (`GridCellCommitFn`): map the value through the column binding's `write` and send the body to your API; a
100
+ rejected promise rolls the cell back. Filtering, sorting and grouping the rows (`evaluateView` from
101
+ `@viewkitjs/fields/query`), a person's preferences (`useGridTablePrefs`) and saving are your app's:
102
+ `docs/guides/the-grid.md` walks through each.
@@ -1,27 +0,0 @@
1
- /** Runtime-neutral wire contract shared by the list serializer and server parser/translator. */
2
- export declare const GRID_FILTER_PARAM_MAX_BYTES = 4096;
3
- export type ListWireRule = {
4
- editor: "text";
5
- operator: "is" | "is_not" | "contains" | "not_contains" | "starts_with" | "ends_with" | "is_empty" | "is_not_empty";
6
- query: string;
7
- } | {
8
- editor: "options";
9
- values: string[];
10
- } | {
11
- editor: "number";
12
- operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "is_empty" | "is_not_empty";
13
- value: number | null;
14
- value2?: number | null;
15
- decimals: number;
16
- } | {
17
- editor: "date";
18
- operator: "in_range";
19
- fromDay: string | null;
20
- toDayExclusive: string | null;
21
- fromInstant: string | null;
22
- toInstantExclusive: string | null;
23
- } | {
24
- editor: "date";
25
- operator: "is_empty" | "is_not_empty";
26
- };
27
- export type ListWireRuleState = Record<string, ListWireRule>;
@@ -1 +0,0 @@
1
- export const GRID_FILTER_PARAM_MAX_BYTES = 4096;
@@ -1,106 +0,0 @@
1
- import type { FieldConventions } from "@viewkitjs/fields";
2
- import type { ListFilterRuleState } from "./preferences.js";
3
- import { type ListWireRuleState } from "../filters/types.js";
4
- import type { ListFilterCapabilities } from "./filter-capabilities.js";
5
- /**
6
- * Turning persisted filter rules into something a SERVER can act on.
7
- *
8
- * The grid has always evaluated its rules in the browser, over rows a list
9
- * already holds. That is correct for a list that loads everything, and wrong for
10
- * a PAGINATED one: the server sends 50 rows, the browser discards the ones that
11
- * don't match, and "a page of 50" silently becomes a page of 21. The number the
12
- * user sees stops being a page size and becomes the filter's survival rate.
13
- *
14
- * So a rule needs a second evaluator. This file owns the half that can travel —
15
- * it converts a rule into a form that carries no assumptions the server can't
16
- * make, and it names which columns a given host can answer for.
17
- *
18
- * ## What it deliberately does NOT do
19
- *
20
- * It emits no SQL, knows no database column names, and imports nothing from the
21
- * app. The grid is meant to be lifted into another application, so the mapping
22
- * from a column id to a physical column belongs to the HOST — the same reason
23
- * `entityIcon` and `onOpenRelation` arrive as resolvers rather than tables.
24
- * What crosses this boundary is a rule; what a backend does with it is its own
25
- * business.
26
- *
27
- * ## The three things resolved before sending
28
- *
29
- * Each is something only the CLIENT can know:
30
- *
31
- * 1. **A relative window.** `past × week` is stored as intent so it still means
32
- * last week tomorrow. Resolving it here means the server needs no clock, and
33
- * — far more importantly — "past week" keeps exactly ONE definition
34
- * (`resolveRelativeWindow`, already written and already tested). A second
35
- * definition in SQL would be two things that must agree forever.
36
- * 2. **A local calendar day's real instants.** Rules compare by local day; the
37
- * columns hold timestamps. Only the browser knows the user's zone and its
38
- * offset on those particular days.
39
- * 3. **The decimals the cell is showing.** Number equality rounds both sides to
40
- * what is on screen, which is a display fact the database cannot see.
41
- */
42
- /** Column ids whose rules the host's backend can answer. Everything else stays
43
- * in the browser. A plain list rather than a map, because the grid has no use
44
- * for what each id maps TO. */
45
- export type GridPushdownSupport = readonly string[];
46
- /**
47
- * One rule, resolved for transport.
48
- *
49
- * Deliberately close to `ListFilterRule` so a param can be pasted into a console
50
- * and read. The differences are exactly the three resolutions above.
51
- */
52
- export type { ListWireRule, ListWireRuleState } from "../filters/types.js";
53
- export { GRID_FILTER_PARAM_MAX_BYTES } from "../filters/types.js";
54
- export type GridFilterSplit = {
55
- /** Sent to the server. NOT re-applied in the browser — see `useList`. */
56
- wire: ListWireRuleState;
57
- /** Only the browser can answer these. Still `ListFilterRule`s, still
58
- * relative-intent-preserving, still fed to `listCohort` unchanged. */
59
- local: ListFilterRuleState;
60
- /** Refused by an explicitly unavailable capability. Kept separate so the UI
61
- * can report and clear stale persisted rules without evaluating them. */
62
- unavailable?: ListFilterRuleState;
63
- /** An explicit-capability host refuses this request rather than evaluating
64
- * source rules over one already-paged browser cohort. */
65
- oversized?: boolean;
66
- };
67
- /**
68
- * Partition a list's rules into the half a server can answer and the half it
69
- * can't.
70
- *
71
- * A column absent from `support` is not an error and needs no flag — a host
72
- * declares what it can filter, and silence means "the browser does this one".
73
- * That keeps a derived column (a label resolved across three tables) working
74
- * exactly as it does today with no extra declaration to forget.
75
- */
76
- export declare function splitFilterRules(rules: ListFilterRuleState, support: GridPushdownSupport, options: {
77
- decimals?: Record<string, number>;
78
- now?: Date;
79
- capabilities?: ListFilterCapabilities;
80
- } | undefined, conventions: FieldConventions): GridFilterSplit;
81
- /**
82
- * The decimals each number cell is actually SHOWING: the user's per-column
83
- * override, else the column's declared format, else the house default of 2 —
84
- * the same precedence `numberDecimals` uses for the in-memory matcher.
85
- *
86
- * Exported because TWO callers need it and must not disagree: the binding, to
87
- * decide what the cohort compares against, and whatever assembles the request,
88
- * to tell the server what a `= 100` was aimed at. A number rule's equality is a
89
- * band the width of the displayed precision, so the two computing it differently
90
- * would aim at different bands.
91
- */
92
- export declare function effectiveDecimals(columns: readonly {
93
- id: string;
94
- format?: {
95
- decimals?: number;
96
- };
97
- }[], overrides?: Record<string, number>): Record<string, number>;
98
- /**
99
- * Stable JSON: keys SORTED.
100
- *
101
- * `setFilterRule` spreads, so insertion order drifts as a user sets and
102
- * clears rules. An unsorted `JSON.stringify` would then mint a different string
103
- * for an identical filter — a fresh cache key, a spurious refetch, and a
104
- * dependency array that fires when nothing changed.
105
- */
106
- export declare function serializeFilters(wire: ListWireRuleState): string;
@@ -1,147 +0,0 @@
1
- import { fromDayKey, isDateRuleActive, resolveRelativeWindow, toDayKey, } from "../filters/date-filter.js";
2
- import { isNumberRuleActive } from "../filters/number-filter.js";
3
- import { isRangeRuleActive } from "../filters/range-filter.js";
4
- import { isTextRuleActive } from "../filters/text-filter.js";
5
- import { GRID_FILTER_PARAM_MAX_BYTES, } from "../filters/types.js";
6
- export { GRID_FILTER_PARAM_MAX_BYTES } from "../filters/types.js";
7
- function addDays(day, count) {
8
- const date = fromDayKey(day);
9
- if (!date)
10
- return null;
11
- return toDayKey(new Date(date.getFullYear(), date.getMonth(), date.getDate() + count));
12
- }
13
- function instantOf(day) {
14
- if (!day)
15
- return null;
16
- return fromDayKey(day)?.toISOString() ?? null;
17
- }
18
- function range(from, toInclusive) {
19
- const toExclusive = toInclusive ? addDays(toInclusive, 1) : null;
20
- return {
21
- editor: "date",
22
- operator: "in_range",
23
- fromDay: from,
24
- toDayExclusive: toExclusive,
25
- fromInstant: instantOf(from),
26
- toInstantExclusive: instantOf(toExclusive),
27
- };
28
- }
29
- function dateToWire(rule, now, conventions) {
30
- switch (rule.operator) {
31
- case "is_empty":
32
- case "is_not_empty":
33
- return { editor: "date", operator: rule.operator };
34
- case "is_relative": {
35
- const window = resolveRelativeWindow(rule.direction, rule.unit, now, conventions);
36
- return range(window.from, window.to);
37
- }
38
- case "is":
39
- return range(rule.from, rule.from);
40
- case "is_before":
41
- return range(null, addDays(rule.from, -1));
42
- case "is_after":
43
- return range(addDays(rule.from, 1), null);
44
- case "is_on_or_before":
45
- return range(null, rule.from);
46
- case "is_on_or_after":
47
- return range(rule.from, null);
48
- case "is_between": {
49
- const [low, high] = [rule.from, rule.to].sort();
50
- return range(low, high);
51
- }
52
- }
53
- return null;
54
- }
55
- function isActive(rule) {
56
- switch (rule.editor) {
57
- case "text":
58
- return isTextRuleActive(rule);
59
- case "number":
60
- return isNumberRuleActive(rule);
61
- case "date":
62
- return isDateRuleActive(rule);
63
- case "range":
64
- return isRangeRuleActive(rule);
65
- case "options":
66
- return rule.values.length > 0;
67
- }
68
- }
69
- function toWire(rule, columnId, options, conventions) {
70
- switch (rule.editor) {
71
- case "text":
72
- return { editor: "text", operator: rule.operator, query: rule.query };
73
- case "options":
74
- return { editor: "options", values: rule.values };
75
- case "number":
76
- return {
77
- editor: "number",
78
- operator: rule.operator,
79
- value: rule.value,
80
- value2: rule.value2,
81
- decimals: options.decimals?.[columnId] ?? 2,
82
- };
83
- case "date":
84
- return dateToWire(rule, options.now, conventions);
85
- case "range":
86
- return null;
87
- }
88
- }
89
- export function splitFilterRules(rules, support, options, conventions) {
90
- const pushable = new Set(support);
91
- const now = options?.now ?? new Date();
92
- const wire = {};
93
- const local = {};
94
- const unavailable = {};
95
- for (const [columnId, rule] of Object.entries(rules)) {
96
- if (!isActive(rule))
97
- continue;
98
- const capability = options?.capabilities?.[columnId];
99
- if (capability?.mode === "unavailable") {
100
- unavailable[columnId] = rule;
101
- continue;
102
- }
103
- if (capability?.mode === "local" || !pushable.has(columnId)) {
104
- local[columnId] = rule;
105
- continue;
106
- }
107
- const translated = toWire(rule, columnId, { decimals: options?.decimals, now }, conventions);
108
- if (translated)
109
- wire[columnId] = translated;
110
- else
111
- local[columnId] = rule;
112
- }
113
- if (new TextEncoder().encode(serializeFilters(wire)).byteLength > GRID_FILTER_PARAM_MAX_BYTES) {
114
- if (options?.capabilities)
115
- return { wire, local, unavailable, oversized: true };
116
- const fallback = {};
117
- for (const [columnId, rule] of Object.entries(rules)) {
118
- if (options?.capabilities?.[columnId]?.mode !== "unavailable")
119
- fallback[columnId] = rule;
120
- }
121
- return {
122
- wire: {},
123
- local: fallback,
124
- ...(options?.capabilities ? { unavailable } : {}),
125
- };
126
- }
127
- return { wire, local, ...(options?.capabilities ? { unavailable } : {}) };
128
- }
129
- export function effectiveDecimals(columns, overrides) {
130
- const out = {};
131
- for (const col of columns) {
132
- const declared = col.format?.decimals;
133
- const override = overrides?.[col.id];
134
- if (override != null || declared != null)
135
- out[col.id] = override ?? declared ?? 2;
136
- }
137
- return out;
138
- }
139
- export function serializeFilters(wire) {
140
- const keys = Object.keys(wire).sort();
141
- if (keys.length === 0)
142
- return "";
143
- const ordered = {};
144
- for (const key of keys)
145
- ordered[key] = wire[key];
146
- return JSON.stringify(ordered);
147
- }