@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,4 @@
1
+ /** Shared chip skin, so the inert span, a host's button and a host's link are
2
+ * the same object with different verbs. */
3
+ export declare const CHIP_BASE = "flex min-w-0 items-center gap-1.5";
4
+ export declare const CHIP_INTERACTIVE: string;
@@ -0,0 +1,3 @@
1
+ import { cx } from "./cx.js";
2
+ export const CHIP_BASE = "flex min-w-0 items-center gap-1.5";
3
+ export const CHIP_INTERACTIVE = cx(CHIP_BASE, "rounded-sm text-left transition-colors", "text-inherit", "hover:text-(color:--vk-fg-brand) hover:[&>span]:underline hover:[&>span]:decoration-(color:--vk-fg-brand)", "[&>span]:underline-offset-[3px]");
@@ -0,0 +1,3 @@
1
+ /** Joins class names, dropping the empty ones. No merging: an atom's own classes
2
+ * and a host's `className` must not name the same property. */
3
+ export declare function cx(...parts: Array<string | false | null | undefined>): string;
@@ -0,0 +1,3 @@
1
+ export function cx(...parts) {
2
+ return parts.filter(Boolean).join(" ");
3
+ }
@@ -0,0 +1,59 @@
1
+ import { type ViewsMessageResolver } from "../contract.js";
2
+ import { type DisplayCurrency } from "../fields/currency.js";
3
+ import type { ListAggregateKind, ListColumn } from "./column-schema.js";
4
+ /** A figure's name, as the app words it: `views.grid.figure`. */
5
+ export declare function aggregateLabel(kind: ListAggregateKind, messages?: ViewsMessageResolver): string;
6
+ /** The figures' names in the package's English. A grid reads `aggregateLabel` with the provider's `messages`. */
7
+ export declare const LIST_AGGREGATE_LABELS: Record<Exclude<ListAggregateKind, "none">, string>;
8
+ export declare function gridColumnIsNumericAgg<Row>(col: ListColumn<Row>): boolean;
9
+ /** A source list's footer (POR-470, POR-472): the keys whose figures the
10
+ * database answered, and the reader's default currency — the key a money
11
+ * column read in Original is totalled under. */
12
+ export type SourcedAggregates = {
13
+ totalled: ReadonlySet<string>;
14
+ defaultCurrency: DisplayCurrency;
15
+ };
16
+ /** The key a column's database figure is read under: a convertible money
17
+ * column's in the currency it shows — the reader's default under Original —
18
+ * else its field's — or the field its footer names (`footerField`). The
19
+ * server's `moneyFigureKey` writes the same key. */
20
+ export declare function figureKeyOf<Row>(col: ListColumn<Row>, defaultCurrency: DisplayCurrency): string;
21
+ /**
22
+ * The aggregates a column offers. A PERCENT never offers `sum` — adding
23
+ * percents is meaningless — and offers `ratio` only when the column carries the
24
+ * two readers (a ratio formula): sum over sum is the honest total for a
25
+ * percent-of-something, where `avg` weights every row alike. The rule reads
26
+ * the column's value type — a bound column's field, a field-less column's own.
27
+ */
28
+ export declare function aggregateOptions<Row>(col: ListColumn<Row>, sourced?: SourcedAggregates): ListAggregateKind[];
29
+ export declare function resolveAggregateKind<Row>(col: ListColumn<Row>, prefs?: Readonly<Record<string, ListAggregateKind>>, sourced?: SourcedAggregates): ListAggregateKind;
30
+ export declare function computeAggregate<Row>(kind: ListAggregateKind, col: ListColumn<Row>, rows: readonly Row[]): number | null;
31
+ /** One figure, and the currency it is in. */
32
+ export type MoneyTotal = {
33
+ amount: number;
34
+ code: string | undefined;
35
+ };
36
+ /**
37
+ * ONE number for a money column's total — never a list per currency.
38
+ *
39
+ * A column read in a currency totals in that currency: its accessors already
40
+ * converted every row (`readMoneyColumn`), so the ordinary reduction is right
41
+ * and the code is the column's own. A column read in ORIGINAL keeps each cell
42
+ * in its own currency, but a total over mixed currencies is either one
43
+ * converted figure or nothing, and the list chose one figure: each row's
44
+ * figure is converted into the reader's DEFAULT currency, for the total only.
45
+ * A money column that carries no rates and no single code (a per-row column
46
+ * nothing can convert) answers `null` — nothing honest to draw.
47
+ *
48
+ * `undefined` means "not this function's question": a non-money column, or a
49
+ * kind that is not numeric (a count is a count in any currency). The footer
50
+ * takes `computeAggregate` for those.
51
+ */
52
+ export declare function moneyTotal<Row>(kind: ListAggregateKind, col: ListColumn<Row>, rows: readonly Row[], defaultCurrency: DisplayCurrency): MoneyTotal | null | undefined;
53
+ /**
54
+ * The currency a money column's DATABASE figure is drawn in — `moneyTotal`'s
55
+ * choice, without the rows: under Original, the reader's default currency (the
56
+ * source totals the column converted into it); read in a currency, the
57
+ * column's code; a per-row column nothing can convert, null (no figure).
58
+ */
59
+ export declare function moneyFigureCode<Row>(col: ListColumn<Row>, defaultCurrency: DisplayCurrency): string | undefined | null;
@@ -0,0 +1,186 @@
1
+ import { isMultipleType, locationText, nameText, presentedDef, scalarOf, valueItems, valueKey, } from "@viewkitjs/fields";
2
+ import { phoneMatchText } from "@viewkitjs/fields/phone";
3
+ import { resolveViewsMessage } from "../contract.js";
4
+ import { COLUMN_WIDE_CODE } from "../fields/denomination.js";
5
+ import { convertMoney } from "../fields/money.js";
6
+ import { ORIGINAL_READING } from "../fields/currency.js";
7
+ import { fieldTypeOf } from "./field-type-of.js";
8
+ import { fieldKeyOf } from "./view-rules.js";
9
+ export function aggregateLabel(kind, messages = resolveViewsMessage) {
10
+ return messages({ key: "views.grid.figure", values: { kind } });
11
+ }
12
+ export const LIST_AGGREGATE_LABELS = {
13
+ sum: aggregateLabel("sum"),
14
+ avg: aggregateLabel("avg"),
15
+ min: aggregateLabel("min"),
16
+ max: aggregateLabel("max"),
17
+ count: aggregateLabel("count"),
18
+ filled: aggregateLabel("filled"),
19
+ unique: aggregateLabel("unique"),
20
+ ratio: aggregateLabel("ratio"),
21
+ };
22
+ const NUMERIC = new Set(["number", "percent", "currency"]);
23
+ export function gridColumnIsNumericAgg(col) {
24
+ return !!col.aggAccessor || NUMERIC.has(fieldTypeOf(col));
25
+ }
26
+ export function figureKeyOf(col, defaultCurrency) {
27
+ const key = col.footerField ?? fieldKeyOf(col);
28
+ if (!col.money)
29
+ return key;
30
+ const currency = col.reading && col.reading !== ORIGINAL_READING ? col.reading : defaultCurrency;
31
+ return `${key}.${currency}`;
32
+ }
33
+ function isOneCurrencyField(field) {
34
+ const shown = presentedDef(field);
35
+ const code = shown.type === "currency" ? shown.code : undefined;
36
+ return !!code && "fixed" in code;
37
+ }
38
+ function sourceCanTotal(col) {
39
+ if (!col.field || !gridColumnIsNumericAgg(col))
40
+ return false;
41
+ if (fieldTypeOf(col) !== "currency")
42
+ return true;
43
+ return !!col.money || isOneCurrencyField(col.field);
44
+ }
45
+ export function aggregateOptions(col, sourced) {
46
+ const offered = typeOptions(col, sourced);
47
+ const named = col.footerKinds;
48
+ return named ? offered.filter((kind) => kind === "none" || named.includes(kind)) : offered;
49
+ }
50
+ function typeOptions(col, sourced) {
51
+ if (sourced) {
52
+ const totalled = sourceCanTotal(col) ||
53
+ (gridColumnIsNumericAgg(col) && sourced.totalled.has(figureKeyOf(col, sourced.defaultCurrency)));
54
+ if (!totalled)
55
+ return col.ratio ? ["none", "ratio", "count"] : ["none", "count"];
56
+ if (fieldTypeOf(col) === "percent")
57
+ return col.ratio
58
+ ? ["none", "ratio", "avg", "min", "max", "count"]
59
+ : ["none", "avg", "min", "max", "count"];
60
+ return ["none", "sum", "avg", "min", "max", "count"];
61
+ }
62
+ if (fieldTypeOf(col) === "percent") {
63
+ return col.ratio
64
+ ? ["none", "ratio", "avg", "min", "max", "count"]
65
+ : ["none", "avg", "min", "max", "count"];
66
+ }
67
+ return gridColumnIsNumericAgg(col)
68
+ ? ["none", "sum", "avg", "min", "max", "count"]
69
+ : ["none", "count", "filled", "unique"];
70
+ }
71
+ export function resolveAggregateKind(col, prefs, sourced) {
72
+ const options = aggregateOptions(col, sourced);
73
+ const chosen = prefs?.[col.id];
74
+ if (chosen && options.includes(chosen))
75
+ return chosen;
76
+ if (col.ratio && options.includes("ratio"))
77
+ return "ratio";
78
+ const declared = col.defaultAggregate;
79
+ if (!declared || !options.includes(declared))
80
+ return "none";
81
+ if (sourced && declared !== "count" && !sourced.totalled.has(figureKeyOf(col, sourced.defaultCurrency)))
82
+ return "none";
83
+ return declared;
84
+ }
85
+ export function computeAggregate(kind, col, rows) {
86
+ if (kind === "none")
87
+ return null;
88
+ if (kind === "count")
89
+ return rows.length;
90
+ if (kind === "filled" || kind === "unique") {
91
+ const type = fieldTypeOf(col);
92
+ if (col.multiple && isMultipleType(type)) {
93
+ const lists = rows
94
+ .map((row) => {
95
+ const value = col.accessor?.(row);
96
+ const one = Array.isArray(value) ? valueItems(value) : valueItems([value]);
97
+ return one.map((item) => valueKey(item.value, type));
98
+ })
99
+ .filter((keys) => keys.length > 0);
100
+ if (kind === "filled")
101
+ return lists.length;
102
+ return new Set(lists.map((keys) => [...keys].sort().join("|"))).size;
103
+ }
104
+ const asText = type === "location" ? locationText : type === "name" ? nameText : type === "phone" ? phoneMatchText : undefined;
105
+ const written = (value) => !asText ? value : Array.isArray(value) ? value.map((item) => asText(item)).filter(Boolean) : asText(value);
106
+ const values = rows
107
+ .map((row) => written(col.accessor?.(row)))
108
+ .filter((value) => value != null && value !== "" && !(Array.isArray(value) && value.length === 0));
109
+ if (kind === "filled")
110
+ return values.length;
111
+ return new Set(values.map((value) => Array.isArray(value) ? value.map(String).sort().join("|") : String(value))).size;
112
+ }
113
+ if (kind === "ratio") {
114
+ if (!col.ratio)
115
+ return null;
116
+ let num = 0;
117
+ let den = 0;
118
+ for (const row of rows) {
119
+ num += col.ratio.numerator(row) ?? 0;
120
+ den += col.ratio.denominator(row) ?? 0;
121
+ }
122
+ return den > 0 ? Math.round((num / den) * 100) : null;
123
+ }
124
+ return reduceNumbers(kind, totalledNumbers(col, rows));
125
+ }
126
+ const NUMERIC_AGGREGATES = new Set(["sum", "avg", "min", "max"]);
127
+ function totalledNumber(col, row) {
128
+ const read = col.aggAccessor ? col.aggAccessor(row) : col.accessor?.(row);
129
+ const value = col.field ? scalarOf(col.field, read) : read;
130
+ const number = typeof value === "number" ? value : value == null || value === "" ? NaN : Number(value);
131
+ return Number.isNaN(number) ? null : number;
132
+ }
133
+ function totalledNumbers(col, rows) {
134
+ const numbers = [];
135
+ for (const row of rows) {
136
+ const number = totalledNumber(col, row);
137
+ if (number != null)
138
+ numbers.push(number);
139
+ }
140
+ return numbers;
141
+ }
142
+ function reduceNumbers(kind, numbers) {
143
+ if (numbers.length === 0)
144
+ return null;
145
+ switch (kind) {
146
+ case "sum":
147
+ return numbers.reduce((sum, value) => sum + value, 0);
148
+ case "avg":
149
+ return numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
150
+ case "min":
151
+ return Math.min(...numbers);
152
+ default:
153
+ return Math.max(...numbers);
154
+ }
155
+ }
156
+ export function moneyTotal(kind, col, rows, defaultCurrency) {
157
+ if (!NUMERIC_AGGREGATES.has(kind) || fieldTypeOf(col) !== "currency")
158
+ return undefined;
159
+ const money = col.money;
160
+ if (money && col.reading === ORIGINAL_READING) {
161
+ const numbers = [];
162
+ for (const row of rows) {
163
+ const own = money.total ? money.total(row) : money.amount(row);
164
+ const converted = convertMoney(money, row, own, defaultCurrency);
165
+ if (converted != null)
166
+ numbers.push(converted);
167
+ }
168
+ const amount = reduceNumbers(kind, numbers);
169
+ return amount == null ? null : { amount, code: defaultCurrency };
170
+ }
171
+ if (col.currencyAccessor && !money)
172
+ return null;
173
+ const amount = reduceNumbers(kind, totalledNumbers(col, rows));
174
+ if (amount == null)
175
+ return null;
176
+ const code = col.format?.currency;
177
+ return { amount, code: code && code !== COLUMN_WIDE_CODE ? code : undefined };
178
+ }
179
+ export function moneyFigureCode(col, defaultCurrency) {
180
+ if (col.money && col.reading === ORIGINAL_READING)
181
+ return defaultCurrency;
182
+ if (col.currencyAccessor && !col.money)
183
+ return null;
184
+ const code = col.format?.currency;
185
+ return code && code !== COLUMN_WIDE_CODE ? code : undefined;
186
+ }
@@ -0,0 +1,8 @@
1
+ /**
2
+ * How much of a card gets drawn. Lives in the LIST model, not in calendar:
3
+ * board and calendar name the same three tiers, and the zone table's density
4
+ * floors are stated once against this scale.
5
+ */
6
+ export type CardDensity = "compact" | "standard" | "rich";
7
+ /** Is a field with this floor drawn at this density? No floor ⇒ always. */
8
+ export declare function meetsDensity(floor: CardDensity | undefined, actual: CardDensity): boolean;
@@ -0,0 +1,10 @@
1
+ const DENSITY_RANK = {
2
+ compact: 0,
3
+ standard: 1,
4
+ rich: 2,
5
+ };
6
+ export function meetsDensity(floor, actual) {
7
+ if (!floor)
8
+ return true;
9
+ return DENSITY_RANK[actual] >= DENSITY_RANK[floor];
10
+ }
@@ -0,0 +1,85 @@
1
+ import type { CardDensity } from "./card-density.js";
2
+ import type { ListCardZone, ListColumn, ListColumnType } from "./column-schema.js";
3
+ import { type ListColumnState } from "./column-state.js";
4
+ /**
5
+ * A card is typed ZONES, not aligned columns: the title line, a chip row where
6
+ * the badge-shaped types flow and wrap, a figures strip for the numeric facts,
7
+ * a footer for dates, and — at `rich` density only — a body line for prose.
8
+ * Which zone a field lands in is decided by its TYPE — never per host — so
9
+ * every card in the app (board or calendar) composes the same way and a
10
+ * restyle is an edit to one table.
11
+ */
12
+ export type CardZoneRule = {
13
+ zone: ListCardZone;
14
+ minDensity?: CardDensity;
15
+ };
16
+ /**
17
+ * THE type→zone table. Total over `ListColumnType` on purpose: a new column
18
+ * type fails to compile until someone decides where (or whether) it appears.
19
+ * `null` keeps a type off cards by default — prose and link-like types. A
20
+ * `text` column that IS a short fact opts in per column via `card.zone`.
21
+ */
22
+ export declare const ZONE_BY_TYPE: Record<ListColumnType, CardZoneRule | null>;
23
+ /** One field bound for a card: its column plus the zone that styles it. The
24
+ * zone stopped deciding PLACEMENT when the Fields panel took ownership of
25
+ * order — it now only picks the field's dress (money / chip / labeled date). */
26
+ export type CardField<Row> = {
27
+ col: ListColumn<Row>;
28
+ zone: ListCardZone;
29
+ };
30
+ export type CardLayout<Row> = {
31
+ title?: ListColumn<Row>;
32
+ /** The card's body fields in display order — the Fields panel's order, or
33
+ * zone rank when the user has set none. */
34
+ fields: CardField<Row>[];
35
+ /** Ids that START a new line. Applied per ROW (see `buildCardLines`), never
36
+ * baked into the field list, because which fields render varies by row. */
37
+ breakIds: ReadonlySet<string>;
38
+ };
39
+ /**
40
+ * Split a row's rendered fields into lines at the break ids.
41
+ *
42
+ * Applied PER ROW, over the fields that actually produced a cell — a break
43
+ * belongs to its field, so when that field is empty for this row the break
44
+ * leaves with it and the fields after it flow on instead of dropping to a line
45
+ * of their own. Splitting the layout up front instead left a card whose client
46
+ * was blank showing its two money figures stacked, because the absent client's
47
+ * break outlived it.
48
+ *
49
+ * A break on the first surviving item is a no-op: there is no line above it to
50
+ * end.
51
+ */
52
+ export declare function buildCardLines<T>(items: readonly T[], idOf: (item: T) => string, breakIds: ReadonlySet<string>): T[][];
53
+ export type ListCardLayoutOpts = {
54
+ /** Excluded from the card: the column the board is laid out by — every card
55
+ * in a column shares that value, so on the card it is noise. */
56
+ laneColumnId?: string | null;
57
+ /** Excluded from the card regardless of zone — a column the host is already
58
+ * drawing elsewhere (e.g. the row it positions the card by). */
59
+ suppressColumnId?: string | null;
60
+ /** How much of the card to draw. Defaults to `"rich"` so a caller that
61
+ * passes none (board, today) keeps drawing exactly what it draws now. */
62
+ density?: CardDensity;
63
+ };
64
+ /** The break set the card is actually using: the user's stored ids once any
65
+ * were written (empty included — that is "everything on one line"), else the
66
+ * defaults. The panel reads this so a first toggle edits the real layout
67
+ * rather than an empty set. */
68
+ export declare function effectiveCardBreakIds<Row>(columns: ListColumn<Row>[], state: ListColumnState | undefined, excludeId: string | null): string[];
69
+ /**
70
+ * Where a column lands on a card — its own declaration first, then its type.
71
+ *
72
+ * Lifted out of `listCardFields` because the phone row asks the same question
73
+ * the board card does, and two copies of this rule is exactly how the two
74
+ * surfaces would come to disagree about where a date goes.
75
+ */
76
+ export declare function cardZoneOf<Row>(col: ListColumn<Row>, density?: CardDensity): ListCardZone | null;
77
+ /**
78
+ * The card's body plan: which fields, in what order, and where the user asked
79
+ * for a new line. Deliberately NOT pre-split into lines — that is
80
+ * `buildCardLines`'s job, per row, once it is known which fields rendered.
81
+ *
82
+ * Visibility and order come from the host view's OWN slot in the layout
83
+ * bucket (the Fields panel).
84
+ */
85
+ export declare function listCardLayout<Row>(columns: ListColumn<Row>[], state: ListColumnState | undefined, opts?: ListCardLayoutOpts): CardLayout<Row>;
@@ -0,0 +1,90 @@
1
+ import { meetsDensity } from "./card-density.js";
2
+ import { resolveVisibleColumns } from "./column-state.js";
3
+ export const ZONE_BY_TYPE = {
4
+ title: { zone: "title" },
5
+ relation: { zone: "chips" },
6
+ status: { zone: "chips" },
7
+ select: { zone: "chips" },
8
+ multiselect: { zone: "chips" },
9
+ number: { zone: "figures" },
10
+ percent: { zone: "figures" },
11
+ currency: { zone: "figures" },
12
+ date: { zone: "footer" },
13
+ datetime: { zone: "footer" },
14
+ user: { zone: "chips" },
15
+ actor: { zone: "chips" },
16
+ rich_text: null,
17
+ range: { zone: "figures" },
18
+ text: null,
19
+ boolean: null,
20
+ url: null,
21
+ domain: null,
22
+ email: null,
23
+ phone: null,
24
+ location: null,
25
+ name: null,
26
+ };
27
+ const ZONE_FLOOR = {
28
+ body: "rich",
29
+ };
30
+ export function buildCardLines(items, idOf, breakIds) {
31
+ const lines = [];
32
+ for (const item of items) {
33
+ if (lines.length === 0 || breakIds.has(idOf(item)))
34
+ lines.push([]);
35
+ lines[lines.length - 1].push(item);
36
+ }
37
+ return lines;
38
+ }
39
+ const DEFAULT_ZONE_RANK = {
40
+ title: 0,
41
+ figures: 1,
42
+ chips: 2,
43
+ footer: 3,
44
+ body: 4,
45
+ };
46
+ function defaultBreakIds(fields) {
47
+ const first = fields.find((f) => f.zone === "footer");
48
+ return first ? [first.col.id] : [];
49
+ }
50
+ export function effectiveCardBreakIds(columns, state, excludeId) {
51
+ if (state?.breaks)
52
+ return state.breaks;
53
+ return defaultBreakIds(listCardFields(columns, state, { laneColumnId: excludeId }).fields);
54
+ }
55
+ export function cardZoneOf(col, density = "rich") {
56
+ const rule = col.card?.zone
57
+ ? { zone: col.card.zone, minDensity: ZONE_FLOOR[col.card.zone] }
58
+ : col.type
59
+ ? ZONE_BY_TYPE[col.type]
60
+ : null;
61
+ if (!rule)
62
+ return null;
63
+ return meetsDensity(rule.minDensity, density) ? rule.zone : null;
64
+ }
65
+ function listCardFields(columns, state, opts) {
66
+ const density = opts.density ?? "rich";
67
+ let title;
68
+ const fields = [];
69
+ for (const col of resolveVisibleColumns(columns, state)) {
70
+ if (col.id === opts.laneColumnId)
71
+ continue;
72
+ if (opts.suppressColumnId && col.id === opts.suppressColumnId)
73
+ continue;
74
+ const zone = cardZoneOf(col, density);
75
+ if (!zone)
76
+ continue;
77
+ if (zone === "title")
78
+ title ??= col;
79
+ else
80
+ fields.push({ col, zone });
81
+ }
82
+ if (!state?.order?.length) {
83
+ fields.sort((a, b) => DEFAULT_ZONE_RANK[a.zone] - DEFAULT_ZONE_RANK[b.zone]);
84
+ }
85
+ return { title, fields };
86
+ }
87
+ export function listCardLayout(columns, state, opts = {}) {
88
+ const { title, fields } = listCardFields(columns, state, opts);
89
+ return { title, fields, breakIds: new Set(state?.breaks ?? defaultBreakIds(fields)) };
90
+ }
@@ -0,0 +1,162 @@
1
+ import { type FieldConventions } from "@viewkitjs/fields";
2
+ import { type ViewsMessageResolver } from "../contract.js";
3
+ import type { ListColumn } from "./column-schema.js";
4
+ import { type GridEditorId } from "./column-types.js";
5
+ export type { GridEditorId };
6
+ export declare function gridEditorKind<Row>(col: ListColumn<Row>): GridEditorId | null;
7
+ export declare function gridColumnHasEditor<Row>(col: ListColumn<Row>): boolean;
8
+ /**
9
+ * The grid's WRITE policy — what a column accepts, and in what shape.
10
+ *
11
+ * This exists because `gridColumnHasEditor` was quietly answering two different
12
+ * questions: "does this column mount an editor?" (click / double-click / Enter /
13
+ * type-to-replace) and "can this column be written at all?" (Delete, the context
14
+ * menu's Cut/Clear, fill-drag, paste). Those came apart the moment a type could
15
+ * be written WITHOUT an editor — a boolean commits instantly, there is nothing
16
+ * to mount. Faking a registry entry to satisfy the second question would have
17
+ * made all four mount sites try to open an editor that doesn't exist.
18
+ *
19
+ * So: `gridColumnHasEditor` keeps the mount question, `columnWritable`
20
+ * answers the write question, and `gridNormalizeWrite` is the single place any
21
+ * value is checked and coerced before it reaches a commit.
22
+ */
23
+ /**
24
+ * Workspace-settings list capability config — the CONFIG layer of the three-layer
25
+ * chain `declaration (code) → config (workspace, DB) → prefs (user, DB)`, where
26
+ * each layer may ONLY SUBTRACT: config can never widen what the code (and
27
+ * ultimately the data model) permits. Sparse — absence at any level means the
28
+ * declaration wins. Core-safe mirror of the host's stored shape
29
+ * (public.workspace_list_settings.config); the host threads it in as a prop.
30
+ *
31
+ * NOT access control: this constrains the UI. The host's API routes guard
32
+ * their own writes independently, and a direct call bypasses this entirely.
33
+ */
34
+ export type ListColumnConfig = {
35
+ /** Column locked by workspace settings: no writes through ANY route (editor, Delete,
36
+ * Clear, fill, paste). Display, sort, hide and resize are untouched. */
37
+ locked?: boolean;
38
+ };
39
+ export type ListSettingsConfig = {
40
+ /** Whole list read-only for everyone: no cell writes anywhere. */
41
+ readOnly?: boolean;
42
+ /**
43
+ * Per-FIELD locks — keyed by `lockKeyOf(col)`: the column's field key when it
44
+ * presents one, its own id when it doesn't. `columns` is the stored name and
45
+ * stays for the rows already written; the key is a field's.
46
+ *
47
+ * A key matching neither a field nor a column is inert: nothing reads it, and
48
+ * a lock the declaration no longer offers simply stops applying.
49
+ */
50
+ columns?: Record<string, ListColumnConfig>;
51
+ };
52
+ /** Toggle one column's workspace-settings lock, keeping the config SPARSE (empty maps are
53
+ * dropped — `{}` = nothing locked = declaration wins). ONE builder shared by
54
+ * every editing surface (header menu, view-options Columns drill-in) so two
55
+ * doors can never produce different shapes. */
56
+ export declare function toggleListColumnLock(config: ListSettingsConfig | undefined, columnId: string): ListSettingsConfig;
57
+ /** Toggle the table-level read-only lock (sparse: off = key absent). */
58
+ export declare function toggleListReadOnly(config: ListSettingsConfig | undefined): ListSettingsConfig;
59
+ /** Boolean columns only: which write model this column follows. */
60
+ export declare function gridBooleanMode<Row>(col: ListColumn<Row>): "toggle" | "marker" | null;
61
+ /**
62
+ * Can this column be written — by ANY route (editor, Delete, Clear, fill,
63
+ * paste)? Booleans qualify without an editor; everything else still needs one.
64
+ *
65
+ * This is the DECLARATION layer only. Every gate site should ask the
66
+ * `gridColumnEffective*` variants below, which also apply the workspace config
67
+ * layer (`ListSettingsConfig`) — declaration → config → prefs, each may only
68
+ * subtract.
69
+ */
70
+ export declare function columnWritable<Row>(col: ListColumn<Row>): boolean;
71
+ /** Human label for a column in a toast/readout: header string, else its id. */
72
+ export declare function columnLabel<Row>(col: ListColumn<Row>): string;
73
+ /** A saved view can persist only columns backed by a declared field. */
74
+ export declare function columnManagedByView<Row>(col: ListColumn<Row>): boolean;
75
+ /** A saved view can PLACE a column — its position, width and visibility — when
76
+ * the column has a field, or is a computed column (`custom`): the view stores
77
+ * a computed column under its id, which its list's source names (`computed`,
78
+ * POR-496). Filtering and totals stay `columnManagedByView`'s: a computed
79
+ * column never filters, sorts, groups or totals. */
80
+ export declare function columnPlacedByView<Row>(col: ListColumn<Row>): boolean;
81
+ export declare const VIEW_FIELDLESS_FILTER_REASON = "Not a field of this list; a view cannot filter on it.";
82
+ /** Reorder the columns a view places while leaving the rest in their declared
83
+ * slots. Unknown and omitted ids follow resolveColumnOrder's forgiving
84
+ * behavior through the declared fallback: a FIELD the view does not name
85
+ * follows the ones it does; a COMPUTED column it does not name keeps its
86
+ * declared slot, exactly as a column the view cannot place does — every view
87
+ * stored before POR-496 names none, and must draw them where it always did.
88
+ * Once the view names one (a drag, a hide), it is placed like a field. */
89
+ export declare function resolveViewColumnOrder<Row>(columns: ListColumn<Row>[], requested?: readonly string[]): string[];
90
+ /** The complete order a Move or a header drag rewrites: the order the grid
91
+ * DRAWS. On a saved view that is `resolveViewColumnOrder` — a column the view
92
+ * does not name sits in its declared slot — never the declared-neighbour
93
+ * fallback, which puts it elsewhere and made a Move swap the wrong columns
94
+ * (POR-496). Off a view, the fallback is what the grid draws. */
95
+ export declare function baseColumnOrder<Row>(columns: ListColumn<Row>[], order: readonly string[] | undefined, viewBacked: boolean): string[];
96
+ /**
97
+ * THE KEY A LOCK IS STORED UNDER — the column's FIELD, when it has one.
98
+ *
99
+ * A lock is a rule about a field ("nobody edits Value in this workspace"), and
100
+ * it has to hold on every surface that field reaches: the grid cell, the drawer
101
+ * row, the board card. Those surfaces share the field key and nothing else —
102
+ * the grid calls `value_one_off` "value", and a drawer has no column ids at all
103
+ * — so the field key is the only identity all of them can ask under.
104
+ *
105
+ * A column with no field (a rollup, a pre-registry hand-written column) keeps
106
+ * its own id, which is still the only name it has.
107
+ *
108
+ * That is the field key, and `fieldKeyOf` is where it is computed — this name
109
+ * stays because a lock site reads better saying what it is looking up.
110
+ */
111
+ export declare function lockKeyOf<Row>(col: ListColumn<Row>): string;
112
+ /** Is this column locked by the workspace config (a column lock or the whole
113
+ * table's read-only)? Locks only ever SUBTRACT — they never grant. */
114
+ export declare function gridColumnLocked<Row>(col: ListColumn<Row>, config: ListSettingsConfig | undefined): boolean;
115
+ /** Declaration && !locked — the writable answer every gate site should use. */
116
+ export declare function columnEffectiveWritable<Row>(col: ListColumn<Row>, config: ListSettingsConfig | undefined): boolean;
117
+ /** Effective "accepts Clear/Cut/Delete-to-empty". */
118
+ export declare function gridColumnEffectiveClearable<Row>(col: ListColumn<Row>, config: ListSettingsConfig | undefined): boolean;
119
+ /**
120
+ * Why a clear was refused — the toast string. Two DIFFERENT walls that must
121
+ * not read the same: "locked by workspace settings" is actionable (a permitted owner can unlock
122
+ * it); a required field never is, and its column-declared reason explains the
123
+ * data model. Falls back to the historic generic string.
124
+ */
125
+ export declare function gridClearRefusal<Row>(col: ListColumn<Row>, config: ListSettingsConfig | undefined, messages?: ViewsMessageResolver): string;
126
+ /** Why this column can't be emptied, by DECLARATION alone — no workspace config
127
+ * consulted. The toast (`gridClearRefusal`) adds the lock case on top; the
128
+ * Settings readout wants only this half. One string, two surfaces. */
129
+ export declare function columnClearRefusal<Row>(col: ListColumn<Row>, messages?: ViewsMessageResolver): string;
130
+ /** Why this column can't be edited, in the user's words — the column's own
131
+ * declared reason, else the cause its field names (`lockReason`: derived,
132
+ * system-set, provider-owned, create-only), else what a hand-written cell is
133
+ * computed from. A `command` column gets no sentence — the caret is the
134
+ * affordance. One function so the grid's refusal toast and the Settings
135
+ * manifest can't word it differently. */
136
+ export declare function columnEditRefusal<Row>(col: ListColumn<Row>, conventions: FieldConventions, messages?: ViewsMessageResolver): string | undefined;
137
+ /** Why the grid won't edit this column — `gridClearRefusal`'s twin: the
138
+ * workspace's lock first, then the column's own reason. The one sentence a
139
+ * refused gesture (a click, a key, a paste) and a refused commit both say. */
140
+ export declare function gridEditRefusal<Row>(col: ListColumn<Row>, config: ListSettingsConfig | undefined, conventions: FieldConventions, messages?: ViewsMessageResolver): string | undefined;
141
+ export type GridWriteResult = {
142
+ ok: true;
143
+ value: unknown;
144
+ } | {
145
+ ok: false;
146
+ reason: string;
147
+ };
148
+ /**
149
+ * THE write gate: coerce (the grid's rules, by column type), then — when the
150
+ * column presents a registry field — accept (the field's rules, by value).
151
+ * Columns not yet on a registry keep the old behaviour exactly.
152
+ */
153
+ export declare function gridNormalizeWrite<Row>(col: ListColumn<Row>, next: unknown, conventions: FieldConventions,
154
+ /** `region`: the record's country, where a phone typed without its country code is read. A host whose rows carry
155
+ * a country passes the row's here; absent, the conventions' region reads it. `messages`: the app's words for a
156
+ * refusal, the package's English when absent. `stored`: the cell's value before this edit, as stored; a phone
157
+ * that comes back as it is here is kept, never read again (fields' `stored`). */
158
+ options?: {
159
+ region?: string | null;
160
+ messages?: ViewsMessageResolver;
161
+ stored?: unknown;
162
+ }): GridWriteResult;