@viewkitjs/views 0.0.0-stage → 0.1.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 (270) hide show
  1. package/CHANGELOG.md +420 -0
  2. package/LICENSE.md +7 -0
  3. package/README.md +50 -2
  4. package/dist/atoms/CommandMenu.d.ts +2 -0
  5. package/dist/atoms/CommandMenu.js +20 -0
  6. package/dist/atoms/List.d.ts +2 -0
  7. package/dist/atoms/List.js +6 -0
  8. package/dist/atoms/LoadMore.d.ts +2 -0
  9. package/dist/atoms/LoadMore.js +25 -0
  10. package/dist/atoms/Loading.d.ts +2 -0
  11. package/dist/atoms/Loading.js +7 -0
  12. package/dist/atoms/PlatformMark.d.ts +2 -0
  13. package/dist/atoms/PlatformMark.js +4 -0
  14. package/dist/atoms/RelationLink.d.ts +2 -0
  15. package/dist/atoms/RelationLink.js +6 -0
  16. package/dist/atoms/Row.d.ts +3 -0
  17. package/dist/atoms/Row.js +30 -0
  18. package/dist/atoms/RowMenu.d.ts +2 -0
  19. package/dist/atoms/RowMenu.js +101 -0
  20. package/dist/atoms/StatusBadge.d.ts +2 -0
  21. package/dist/atoms/StatusBadge.js +7 -0
  22. package/dist/atoms/StatusMarker.d.ts +2 -0
  23. package/dist/atoms/StatusMarker.js +19 -0
  24. package/dist/atoms/Tag.d.ts +2 -0
  25. package/dist/atoms/Tag.js +13 -0
  26. package/dist/atoms/TickBox.d.ts +2 -0
  27. package/dist/atoms/TickBox.js +8 -0
  28. package/dist/atoms/defaults.d.ts +2 -0
  29. package/dist/atoms/defaults.js +27 -0
  30. package/dist/atoms/tones.d.ts +5 -0
  31. package/dist/atoms/tones.js +28 -0
  32. package/dist/atoms/types.d.ts +178 -0
  33. package/dist/atoms/types.js +3 -0
  34. package/dist/cells/cell-format.d.ts +138 -0
  35. package/dist/cells/cell-format.js +16 -0
  36. package/dist/cells/cell-title.d.ts +17 -0
  37. package/dist/cells/cell-title.js +8 -0
  38. package/dist/cells/cell-values.d.ts +28 -0
  39. package/dist/cells/cell-values.js +87 -0
  40. package/dist/cells/index.d.ts +4 -0
  41. package/dist/cells/index.js +4 -0
  42. package/dist/cells/legacy-field.d.ts +52 -0
  43. package/dist/cells/legacy-field.js +164 -0
  44. package/dist/cells/relation-wrap.d.ts +3 -0
  45. package/dist/cells/relation-wrap.js +24 -0
  46. package/dist/cells/use-cell-format.d.ts +5 -0
  47. package/dist/cells/use-cell-format.js +10 -0
  48. package/dist/contract.d.ts +431 -0
  49. package/dist/contract.js +663 -0
  50. package/dist/display/actor.d.ts +4 -0
  51. package/dist/display/actor.js +26 -0
  52. package/dist/display/boolean.d.ts +18 -0
  53. package/dist/display/boolean.js +43 -0
  54. package/dist/display/breakdown.d.ts +15 -0
  55. package/dist/display/breakdown.js +32 -0
  56. package/dist/display/currency.d.ts +9 -0
  57. package/dist/display/currency.js +29 -0
  58. package/dist/display/date.d.ts +12 -0
  59. package/dist/display/date.js +26 -0
  60. package/dist/display/display-cores.d.ts +31 -0
  61. package/dist/display/display-cores.js +57 -0
  62. package/dist/display/entity-chip.d.ts +26 -0
  63. package/dist/display/entity-chip.js +9 -0
  64. package/dist/display/format.d.ts +51 -0
  65. package/dist/display/format.js +181 -0
  66. package/dist/display/index.d.ts +8 -0
  67. package/dist/display/index.js +7 -0
  68. package/dist/display/link.d.ts +29 -0
  69. package/dist/display/link.js +48 -0
  70. package/dist/display/location.d.ts +7 -0
  71. package/dist/display/location.js +15 -0
  72. package/dist/display/multi-value.d.ts +18 -0
  73. package/dist/display/multi-value.js +28 -0
  74. package/dist/display/name.d.ts +6 -0
  75. package/dist/display/name.js +14 -0
  76. package/dist/display/number.d.ts +11 -0
  77. package/dist/display/number.js +27 -0
  78. package/dist/display/options.d.ts +153 -0
  79. package/dist/display/options.js +1 -0
  80. package/dist/display/percent.d.ts +4 -0
  81. package/dist/display/percent.js +33 -0
  82. package/dist/display/phone.d.ts +10 -0
  83. package/dist/display/phone.js +38 -0
  84. package/dist/display/range.d.ts +6 -0
  85. package/dist/display/range.js +29 -0
  86. package/dist/display/relation.d.ts +4 -0
  87. package/dist/display/relation.js +29 -0
  88. package/dist/display/rich-text.d.ts +10 -0
  89. package/dist/display/rich-text.js +34 -0
  90. package/dist/display/select.d.ts +6 -0
  91. package/dist/display/select.js +38 -0
  92. package/dist/display/text-class.d.ts +23 -0
  93. package/dist/display/text-class.js +5 -0
  94. package/dist/display/text.d.ts +19 -0
  95. package/dist/display/text.js +8 -0
  96. package/dist/display/use-display-options.d.ts +2 -0
  97. package/dist/display/use-display-options.js +14 -0
  98. package/dist/display/user.d.ts +11 -0
  99. package/dist/display/user.js +10 -0
  100. package/dist/display/value-list.d.ts +10 -0
  101. package/dist/display/value-list.js +12 -0
  102. package/dist/display/viewer.d.ts +4 -0
  103. package/dist/display/viewer.js +11 -0
  104. package/dist/display/web-href.d.ts +8 -0
  105. package/dist/display/web-href.js +12 -0
  106. package/dist/editors/ChipsEditor.d.ts +59 -0
  107. package/dist/editors/ChipsEditor.js +73 -0
  108. package/dist/editors/DateEditor.d.ts +25 -0
  109. package/dist/editors/DateEditor.js +122 -0
  110. package/dist/editors/LocationEditor.d.ts +22 -0
  111. package/dist/editors/LocationEditor.js +229 -0
  112. package/dist/editors/NameEditor.d.ts +22 -0
  113. package/dist/editors/NameEditor.js +91 -0
  114. package/dist/editors/NumberEditor.d.ts +67 -0
  115. package/dist/editors/NumberEditor.js +86 -0
  116. package/dist/editors/RangeEditor.d.ts +22 -0
  117. package/dist/editors/RangeEditor.js +70 -0
  118. package/dist/editors/RelationEditor.d.ts +65 -0
  119. package/dist/editors/RelationEditor.js +64 -0
  120. package/dist/editors/SelectEditor.d.ts +72 -0
  121. package/dist/editors/SelectEditor.js +59 -0
  122. package/dist/editors/ValueListEditor.d.ts +38 -0
  123. package/dist/editors/ValueListEditor.js +217 -0
  124. package/dist/editors/edit-cores.d.ts +83 -0
  125. package/dist/editors/edit-cores.js +38 -0
  126. package/dist/editors/edit-session.d.ts +74 -0
  127. package/dist/editors/edit-session.js +35 -0
  128. package/dist/editors/open-values.d.ts +28 -0
  129. package/dist/editors/open-values.js +26 -0
  130. package/dist/editors/relation-source.d.ts +66 -0
  131. package/dist/editors/relation-source.js +102 -0
  132. package/dist/fields/binding.d.ts +87 -0
  133. package/dist/fields/binding.js +117 -0
  134. package/dist/fields/currency.d.ts +92 -0
  135. package/dist/fields/currency.js +55 -0
  136. package/dist/fields/denomination.d.ts +42 -0
  137. package/dist/fields/denomination.js +11 -0
  138. package/dist/fields/edit-core-types.d.ts +40 -0
  139. package/dist/fields/edit-core-types.js +29 -0
  140. package/dist/fields/format-knobs.d.ts +34 -0
  141. package/dist/fields/format-knobs.js +36 -0
  142. package/dist/fields/menus.d.ts +28 -0
  143. package/dist/fields/menus.js +1 -0
  144. package/dist/fields/money.d.ts +59 -0
  145. package/dist/fields/money.js +77 -0
  146. package/dist/fields/number-edit.d.ts +11 -0
  147. package/dist/fields/number-edit.js +17 -0
  148. package/dist/fields/prepare-write.d.ts +55 -0
  149. package/dist/fields/prepare-write.js +67 -0
  150. package/dist/fields/relation-source-types.d.ts +54 -0
  151. package/dist/fields/relation-source-types.js +1 -0
  152. package/dist/figures.d.ts +52 -0
  153. package/dist/figures.js +63 -0
  154. package/dist/filters/date-filter.d.ts +2 -0
  155. package/dist/filters/date-filter.js +1 -0
  156. package/dist/filters/filter-model.d.ts +177 -0
  157. package/dist/filters/filter-model.js +41 -0
  158. package/dist/filters/number-filter.d.ts +2 -0
  159. package/dist/filters/number-filter.js +1 -0
  160. package/dist/filters/range-filter.d.ts +2 -0
  161. package/dist/filters/range-filter.js +1 -0
  162. package/dist/filters/registry.d.ts +136 -0
  163. package/dist/filters/registry.js +46 -0
  164. package/dist/filters/relation-filter.d.ts +16 -0
  165. package/dist/filters/relation-filter.js +53 -0
  166. package/dist/filters/text-filter.d.ts +2 -0
  167. package/dist/filters/text-filter.js +1 -0
  168. package/dist/filters/types.d.ts +27 -0
  169. package/dist/filters/types.js +1 -0
  170. package/dist/grouping/sort-groups.d.ts +18 -0
  171. package/dist/grouping/sort-groups.js +33 -0
  172. package/dist/grouping/types.d.ts +10 -0
  173. package/dist/grouping/types.js +1 -0
  174. package/dist/index.d.ts +29 -0
  175. package/dist/index.js +29 -0
  176. package/dist/internal/chip.d.ts +4 -0
  177. package/dist/internal/chip.js +3 -0
  178. package/dist/internal/cx.d.ts +3 -0
  179. package/dist/internal/cx.js +3 -0
  180. package/dist/model/aggregates.d.ts +59 -0
  181. package/dist/model/aggregates.js +186 -0
  182. package/dist/model/card-density.d.ts +8 -0
  183. package/dist/model/card-density.js +10 -0
  184. package/dist/model/card-layout.d.ts +85 -0
  185. package/dist/model/card-layout.js +90 -0
  186. package/dist/model/column-capabilities.d.ts +162 -0
  187. package/dist/model/column-capabilities.js +233 -0
  188. package/dist/model/column-filters.d.ts +106 -0
  189. package/dist/model/column-filters.js +321 -0
  190. package/dist/model/column-format.d.ts +103 -0
  191. package/dist/model/column-format.js +1 -0
  192. package/dist/model/column-from.d.ts +28 -0
  193. package/dist/model/column-from.js +160 -0
  194. package/dist/model/column-inspect.d.ts +18 -0
  195. package/dist/model/column-inspect.js +6 -0
  196. package/dist/model/column-knobs.d.ts +20 -0
  197. package/dist/model/column-knobs.js +16 -0
  198. package/dist/model/column-money.d.ts +13 -0
  199. package/dist/model/column-money.js +27 -0
  200. package/dist/model/column-order.d.ts +36 -0
  201. package/dist/model/column-order.js +68 -0
  202. package/dist/model/column-schema.d.ts +335 -0
  203. package/dist/model/column-schema.js +1 -0
  204. package/dist/model/column-sort.d.ts +17 -0
  205. package/dist/model/column-sort.js +11 -0
  206. package/dist/model/column-state.d.ts +77 -0
  207. package/dist/model/column-state.js +95 -0
  208. package/dist/model/column-types.d.ts +109 -0
  209. package/dist/model/column-types.js +50 -0
  210. package/dist/model/column-warnings.d.ts +44 -0
  211. package/dist/model/column-warnings.js +24 -0
  212. package/dist/model/density.d.ts +3 -0
  213. package/dist/model/density.js +13 -0
  214. package/dist/model/field-type-of.d.ts +21 -0
  215. package/dist/model/field-type-of.js +11 -0
  216. package/dist/model/filter-capabilities.d.ts +1 -0
  217. package/dist/model/filter-capabilities.js +1 -0
  218. package/dist/model/filter-pushdown.d.ts +106 -0
  219. package/dist/model/filter-pushdown.js +147 -0
  220. package/dist/model/index.d.ts +40 -0
  221. package/dist/model/index.js +21 -0
  222. package/dist/model/part-rows.d.ts +28 -0
  223. package/dist/model/part-rows.js +40 -0
  224. package/dist/model/preferences.d.ts +151 -0
  225. package/dist/model/preferences.js +84 -0
  226. package/dist/model/prefs-buckets.d.ts +173 -0
  227. package/dist/model/prefs-buckets.js +71 -0
  228. package/dist/model/relation-filters.d.ts +45 -0
  229. package/dist/model/relation-filters.js +78 -0
  230. package/dist/model/render-count.d.ts +2 -0
  231. package/dist/model/render-count.js +24 -0
  232. package/dist/model/row-icon.d.ts +23 -0
  233. package/dist/model/row-icon.js +5 -0
  234. package/dist/model/view-rules.d.ts +73 -0
  235. package/dist/model/view-rules.js +216 -0
  236. package/dist/provider/ViewsProvider.d.ts +26 -0
  237. package/dist/provider/ViewsProvider.js +12 -0
  238. package/dist/provider/components.d.ts +222 -0
  239. package/dist/provider/components.js +3 -0
  240. package/dist/provider/context.d.ts +19 -0
  241. package/dist/provider/context.js +10 -0
  242. package/dist/provider/icons.d.ts +6 -0
  243. package/dist/provider/icons.js +1 -0
  244. package/dist/provider/ports.d.ts +35 -0
  245. package/dist/provider/ports.js +8 -0
  246. package/dist/react.d.ts +9 -0
  247. package/dist/react.js +4 -0
  248. package/dist/selection/SelectCheckbox.d.ts +17 -0
  249. package/dist/selection/SelectCheckbox.js +11 -0
  250. package/dist/selection/index.d.ts +7 -0
  251. package/dist/selection/index.js +6 -0
  252. package/dist/selection/model.d.ts +55 -0
  253. package/dist/selection/model.js +86 -0
  254. package/dist/selection/row-click.d.ts +35 -0
  255. package/dist/selection/row-click.js +20 -0
  256. package/dist/selection/types.d.ts +17 -0
  257. package/dist/selection/types.js +1 -0
  258. package/dist/selection/useCheckDragSelect.d.ts +61 -0
  259. package/dist/selection/useCheckDragSelect.js +165 -0
  260. package/dist/selection/useListSelection.d.ts +39 -0
  261. package/dist/selection/useListSelection.js +48 -0
  262. package/dist/selection/useListSelectionShortcuts.d.ts +6 -0
  263. package/dist/selection/useListSelectionShortcuts.js +14 -0
  264. package/dist/selection/useRestIntent.d.ts +18 -0
  265. package/dist/selection/useRestIntent.js +35 -0
  266. package/docs/contract.md +453 -0
  267. package/docs/install.md +105 -0
  268. package/docs/reshaping.md +19 -0
  269. package/package.json +114 -3
  270. package/skills/views/SKILL.md +87 -0
@@ -0,0 +1,50 @@
1
+ import { isMultipleType, resolveRelationValue } from "@viewkitjs/fields";
2
+ export const GRID_TYPE_RULES = {
3
+ title: { editor: "text", filter: "text", paste: "text", value: "any" },
4
+ text: { editor: "text", filter: "text", paste: "text", value: "any" },
5
+ number: { editor: "number", filter: "number", paste: "number", value: "any" },
6
+ percent: { editor: "number", filter: "number", paste: "number", value: "any" },
7
+ currency: { editor: "number", filter: "number", paste: "number", value: "any" },
8
+ date: { editor: "date", filter: "date", paste: "date", value: "any" },
9
+ datetime: { editor: "date", filter: "date", paste: "date", value: "any" },
10
+ status: { editor: "select", filter: "options", paste: "option", value: "any" },
11
+ select: { editor: "select", filter: "options", paste: "option", value: "any" },
12
+ multiselect: { editor: "chips", filter: "options", paste: "list", value: "list" },
13
+ boolean: { editor: null, filter: "boolean", paste: "boolean", value: "boolean" },
14
+ relation: { editor: "relation", filter: "options", paste: "relation", value: "relation" },
15
+ user: { editor: "relation", filter: "options", paste: "relation", value: "relation" },
16
+ phone: { editor: "text", filter: "text", paste: "text", value: "any" },
17
+ location: { editor: null, filter: "none", paste: "none", value: "any" },
18
+ name: { editor: "name", filter: "text", paste: "text", value: "any" },
19
+ actor: { editor: null, filter: "options", paste: "none", value: "any" },
20
+ rich_text: { editor: "text", filter: "text", paste: "text", value: "any" },
21
+ range: { editor: "range", filter: "range", paste: "range", value: "any" },
22
+ url: { editor: "text", filter: "text", paste: "text", value: "url" },
23
+ domain: { editor: "text", filter: "text", paste: "text", value: "any" },
24
+ email: { editor: "text", filter: "text", paste: "text", value: "email" },
25
+ };
26
+ export function typeRule(type) {
27
+ return type ? GRID_TYPE_RULES[type] : null;
28
+ }
29
+ export function gridPasteKind(col) {
30
+ if (col.multiple)
31
+ return col.field && col.type && isMultipleType(col.type) ? "list" : null;
32
+ return typeRule(col.type)?.paste ?? null;
33
+ }
34
+ export function resolveGridRelation(col, raw) {
35
+ return resolveRelationValue(raw, col.relation?.entity);
36
+ }
37
+ export function gridRelationSource(col, entityIcon) {
38
+ const source = col.relation?.source ?? { kind: "static", items: col.relation?.options ?? [] };
39
+ if (!entityIcon)
40
+ return source;
41
+ const dress = (option) => option.icon
42
+ ? option
43
+ : { ...option, icon: entityIcon(resolveGridRelation(col, option)?.entity) };
44
+ if (source.kind === "static")
45
+ return { ...source, items: source.items.map(dress) };
46
+ return {
47
+ ...source,
48
+ search: async (query, signal, offset) => (await source.search(query, signal, offset)).map(dress),
49
+ };
50
+ }
@@ -0,0 +1,44 @@
1
+ import type { ListColumn } from "./column-schema.js";
2
+ /**
3
+ * THE DECLARATIONS THAT LIE — mistakes a column can make that nothing else can
4
+ * catch.
5
+ *
6
+ * Both of these are pure and list-shaped rather than boolean, so the caller can
7
+ * NAME the offenders, and both are wired as dev-only warnings at the mount site
8
+ * (`ListBody`). They live apart from the capability answers they consult because
9
+ * they are a different job: `column-capabilities` tells a running grid what it
10
+ * may do, these two tell the person writing the page that they wrote something
11
+ * the grid will quietly ignore.
12
+ *
13
+ * Enforcing either at the type level would mean threading a second generic
14
+ * through every file that writes `ListColumn<Row>`, for mistakes that only exist
15
+ * while a page is being written.
16
+ */
17
+ /**
18
+ * Every `sortKey` a column advertises that the host's sort vocabulary doesn't
19
+ * know — i.e. the sort trap, made checkable.
20
+ *
21
+ * The grid never sorts: the header menu offers "Sort A→Z" for ANY column
22
+ * carrying a `sortKey` and hands that plain string to the host's `onChange`.
23
+ * `sortKey` is not typed against the host's key union, so the two ways this
24
+ * goes wrong are both silent — a typo falls through to whatever the host's
25
+ * comparator does last (a wrong order, no error), and a correct key missing
26
+ * from `sort.options` renders as its raw camelCase in the toolbar's Sort row.
27
+ */
28
+ export declare function unknownSortKeys<Row>(columns: readonly ListColumn<Row>[], sortOptions: readonly {
29
+ value: string;
30
+ }[]): string[];
31
+ /**
32
+ * Every column that declares `editable` for a type which cannot mount an
33
+ * editor — a promise the grid silently drops.
34
+ *
35
+ * `url` names no editor, so `editable: true` on it type-checks, reads as
36
+ * writable in the declaration, and then refuses every write at runtime with no
37
+ * error and nothing to explain it. That is the worst shape a capability bug
38
+ * takes: the code says yes, the UI says nothing, and the user concludes the cell
39
+ * is broken.
40
+ *
41
+ * Booleans are excluded on purpose — they are writable WITHOUT an editor, which
42
+ * is the whole reason `columnWritable` exists apart from `gridColumnHasEditor`.
43
+ */
44
+ export declare function columnsClaimingAbsentEditors<Row>(columns: readonly ListColumn<Row>[]): string[];
@@ -0,0 +1,24 @@
1
+ import { isMultipleType } from "@viewkitjs/fields";
2
+ import { hasEditCore } from "../fields/edit-core-types.js";
3
+ import { gridBooleanMode, gridColumnHasEditor } from "./column-capabilities.js";
4
+ export function unknownSortKeys(columns, sortOptions) {
5
+ const known = new Set(sortOptions.map((option) => option.value));
6
+ const missing = new Set();
7
+ for (const col of columns) {
8
+ if (col.sortKey && !known.has(col.sortKey))
9
+ missing.add(col.sortKey);
10
+ }
11
+ return [...missing];
12
+ }
13
+ export function columnsClaimingAbsentEditors(columns) {
14
+ return columns
15
+ .filter((col) => col.editable && !columnMountsEditor(col) && gridBooleanMode(col) == null)
16
+ .map((col) => col.id);
17
+ }
18
+ function columnMountsEditor(col) {
19
+ if (col.multiple)
20
+ return !!col.field && !!col.type && isMultipleType(col.type);
21
+ if (col.field && hasEditCore(col.field.type))
22
+ return true;
23
+ return gridColumnHasEditor(col);
24
+ }
@@ -0,0 +1,3 @@
1
+ import type { CSSProperties } from "react";
2
+ import type { ListDensity } from "./column-state.js";
3
+ export declare function densityStyle(density: ListDensity): CSSProperties & Record<string, string>;
@@ -0,0 +1,13 @@
1
+ const DENSITY = {
2
+ compact: { py: "0.375rem", headMb: "0.25rem", gap: "0.5rem" },
3
+ default: { py: "0.75rem", headMb: "0.5rem", gap: "0.75rem" },
4
+ spacious: { py: "1.125rem", headMb: "0.75rem", gap: "1rem" },
5
+ };
6
+ export function densityStyle(density) {
7
+ const spec = DENSITY[density] ?? DENSITY.default;
8
+ return {
9
+ "--dt-row-py": spec.py,
10
+ "--dt-head-mb": spec.headMb,
11
+ "--dt-row-gap": spec.gap,
12
+ };
13
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The storage type behind a column — what `FORMAT_KNOBS` and the query
3
+ * contract are keyed by.
4
+ *
5
+ * A column that declares a field answers with its VALUE type — a rollup or
6
+ * formula is its result. One that does not is read off `ListColumnType`,
7
+ * which IS the value-type vocabulary plus the one column role: `title` is the
8
+ * text a row is called. A column with no type at all is a hand-rendered cell,
9
+ * and text is the reading that offers it nothing rather than the wrong thing.
10
+ *
11
+ * Kept in its own file rather than appended to `column-schema.ts`: that file
12
+ * is held under the component ratchet's line ceiling, and the policy is split,
13
+ * never raise it.
14
+ */
15
+ import { type ValueType } from "@viewkitjs/fields";
16
+ import type { TemporalKind } from "@viewkitjs/fields/query";
17
+ import type { ListColumn } from "./column-schema.js";
18
+ export declare function fieldTypeOf<Row>(col: ListColumn<Row>): ValueType;
19
+ /** The temporal kind: a bound column's field decides; a field-less column's
20
+ * own type does — `date` is a calendar day, `datetime` an instant. */
21
+ export declare function temporalKindOf<Row>(col: ListColumn<Row>): TemporalKind;
@@ -0,0 +1,11 @@
1
+ import { valueTypeOf } from "@viewkitjs/fields";
2
+ export function fieldTypeOf(col) {
3
+ if (col.field)
4
+ return valueTypeOf(col.field);
5
+ if (!col.type || col.type === "title")
6
+ return "text";
7
+ return col.type;
8
+ }
9
+ export function temporalKindOf(col) {
10
+ return fieldTypeOf(col) === "date" ? "date" : "datetime";
11
+ }
@@ -0,0 +1 @@
1
+ export { ListFilterCapabilityError, validateFilterCapabilities, type ListFilterCapability, type ListFilterCapabilities, } from "../filters/registry.js";
@@ -0,0 +1 @@
1
+ export { ListFilterCapabilityError, validateFilterCapabilities, } from "../filters/registry.js";
@@ -0,0 +1,106 @@
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;
@@ -0,0 +1,147 @@
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
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * THE VIEW-NEUTRAL LIST MODEL.
3
+ *
4
+ * What a list's columns ARE (`column-schema`), what may be DONE to them
5
+ * (`column-capabilities`), which of them are shown and in what order
6
+ * (`column-state`), how they narrow a cohort (`column-filters`,
7
+ * `filter-pushdown`), and what a user has persisted about them
8
+ * (`preferences`).
9
+ *
10
+ * It lives OUTSIDE `grid-table/` because none of it is about a spreadsheet.
11
+ * A table view reads the same schema to align its columns; a card view reads
12
+ * it to find the title field; a board would read a `select` column's `options`
13
+ * to get its lanes; and all of them must ask `column-capabilities` before a
14
+ * write, or a workspace lock would protect the grid and nothing else.
15
+ *
16
+ * What stayed behind in `grid-table/` is what only a spreadsheet does: cell
17
+ * editors, range selection, clipboard, keyboard navigation, and the pixel
18
+ * scale (`core/grid-scale.ts`).
19
+ */
20
+ export * from "./column-schema.js";
21
+ export * from "./field-type-of.js";
22
+ export * from "./column-knobs.js";
23
+ export * from "./column-sort.js";
24
+ export * from "./column-order.js";
25
+ export * from "./column-from.js";
26
+ export * from "./row-icon.js";
27
+ export * from "./column-state.js";
28
+ export * from "./column-types.js";
29
+ export * from "./column-capabilities.js";
30
+ export * from "./column-warnings.js";
31
+ export * from "./column-filters.js";
32
+ export * from "./filter-pushdown.js";
33
+ export * from "./filter-capabilities.js";
34
+ export * from "./preferences.js";
35
+ export * from "./view-rules.js";
36
+ export * from "./part-rows.js";
37
+ export * from "./prefs-buckets.js";
38
+ export * from "./density.js";
39
+ export * from "./aggregates.js";
40
+ export { countRowRender, takeRowRenders } from "./render-count.js";
@@ -0,0 +1,21 @@
1
+ export * from "./column-schema.js";
2
+ export * from "./field-type-of.js";
3
+ export * from "./column-knobs.js";
4
+ export * from "./column-sort.js";
5
+ export * from "./column-order.js";
6
+ export * from "./column-from.js";
7
+ export * from "./row-icon.js";
8
+ export * from "./column-state.js";
9
+ export * from "./column-types.js";
10
+ export * from "./column-capabilities.js";
11
+ export * from "./column-warnings.js";
12
+ export * from "./column-filters.js";
13
+ export * from "./filter-pushdown.js";
14
+ export * from "./filter-capabilities.js";
15
+ export * from "./preferences.js";
16
+ export * from "./view-rules.js";
17
+ export * from "./part-rows.js";
18
+ export * from "./prefs-buckets.js";
19
+ export * from "./density.js";
20
+ export * from "./aggregates.js";
21
+ export { countRowRender, takeRowRenders } from "./render-count.js";
@@ -0,0 +1,28 @@
1
+ import type { FieldType } from "@viewkitjs/fields";
2
+ import { type ViewsMessageResolver } from "../contract.js";
3
+ /** Joins a row's id and its part. A part never holds it, so a key splits at its last one. */
4
+ export declare const PART_KEY_SEPARATOR = "::";
5
+ /** A row's key for one part: a column id (Filter) or a field key (Sort, Group), then the part. */
6
+ export declare function partKey(id: string, part: string): string;
7
+ /** `{ id }` for a whole-value key, `{ id, part }` for a part key; split at the LAST separator. */
8
+ export declare function parsePartKey(key: string): {
9
+ id: string;
10
+ part?: string;
11
+ };
12
+ /** The parts each type offers a Filter row for, in the order the rows are listed. A name's full name has none: the
13
+ * name's own row already reads it. */
14
+ export declare const FILTER_PART_ROWS: {
15
+ readonly [K in FieldType]?: readonly string[];
16
+ };
17
+ /** The orders each type offers a Sort option for, beyond its whole-value sort (a name's is its full name). */
18
+ export declare const SORT_PART_ROWS: {
19
+ readonly [K in FieldType]?: readonly string[];
20
+ };
21
+ /** The orders each type offers a Group dimension for, beyond grouping by the whole value. */
22
+ export declare const GROUP_PART_ROWS: {
23
+ readonly [K in FieldType]?: readonly string[];
24
+ };
25
+ /** A part's word ("Country", "Given name"); undefined for a part no table lists. */
26
+ export declare function partWord(type: FieldType, part: string, messages?: ViewsMessageResolver): string | undefined;
27
+ /** "Location · Country": the field's label and the part's word, through `views.menus.part-row`. */
28
+ export declare function partLabel(fieldLabel: string, type: FieldType, part: string, messages?: ViewsMessageResolver): string;
@@ -0,0 +1,40 @@
1
+ import { LOCATION_FILTER_PARTS, LOCATION_ORDERS } from "@viewkitjs/fields/query";
2
+ import { resolveViewsMessage } from "../contract.js";
3
+ export const PART_KEY_SEPARATOR = "::";
4
+ export function partKey(id, part) {
5
+ return `${id}${PART_KEY_SEPARATOR}${part}`;
6
+ }
7
+ export function parsePartKey(key) {
8
+ const at = key.lastIndexOf(PART_KEY_SEPARATOR);
9
+ if (at < 0)
10
+ return { id: key };
11
+ return { id: key.slice(0, at), part: key.slice(at + PART_KEY_SEPARATOR.length) };
12
+ }
13
+ export const FILTER_PART_ROWS = {
14
+ location: LOCATION_FILTER_PARTS,
15
+ name: ["given", "family"],
16
+ };
17
+ export const SORT_PART_ROWS = {
18
+ location: LOCATION_ORDERS,
19
+ name: ["family", "given"],
20
+ };
21
+ export const GROUP_PART_ROWS = {
22
+ location: LOCATION_ORDERS,
23
+ };
24
+ const PART_WORDS = {
25
+ location: {
26
+ countryCode: "views.editors.place-country",
27
+ region: "views.editors.place-region",
28
+ city: "views.editors.place-city-city",
29
+ postalCode: "views.editors.place-postal-postal",
30
+ },
31
+ name: { given: "views.editors.name-given", family: "views.editors.name-family" },
32
+ };
33
+ export function partWord(type, part, messages = resolveViewsMessage) {
34
+ const words = PART_WORDS[type];
35
+ const key = words && Object.hasOwn(words, part) ? words[part] : undefined;
36
+ return key ? messages({ key }) : undefined;
37
+ }
38
+ export function partLabel(fieldLabel, type, part, messages = resolveViewsMessage) {
39
+ return messages({ key: "views.menus.part-row", values: { field: fieldLabel, part: partWord(type, part, messages) ?? part } });
40
+ }