@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,335 @@
1
+ import type { MouseEvent as ReactMouseEvent, ReactNode } from "react";
2
+ import type { FieldBinding } from "../fields/binding.js";
3
+ import type { MoneyDeclaration } from "../fields/money.js";
4
+ import type { RelationSource } from "../fields/relation-source-types.js";
5
+ import type { MoneyReading } from "../fields/currency.js";
6
+ import type { CategoryColor } from "@viewkitjs/fields/design/category-colors";
7
+ import type { StageMark } from "@viewkitjs/fields/design/stage-marks";
8
+ import type { StatusSlot } from "@viewkitjs/fields/design/status-slots";
9
+ import type { FieldDef, RelationValue, ValueType } from "@viewkitjs/fields";
10
+ import type { ListColumnFormat } from "./column-format.js";
11
+ /** The grid's column vocabulary: a column presents a VALUE, so its type is
12
+ * the field's value type (a rollup or formula column is its result's type;
13
+ * `col.field` says it is derived) plus the one column ROLE, `title`. A
14
+ * field-less legacy column still names one of these; `legacyFieldFromColumn`
15
+ * is the bridge that reads it as a def. */
16
+ export type ListColumnType = ValueType | "title";
17
+ /** The list's name for the design system's slot — one union, aliased like
18
+ * `ListDurationStyle` below, so the two cannot drift. */
19
+ export type ListStatusSlot = StatusSlot;
20
+ /**
21
+ * Where a field lands on a CARD. The board's own type→zone table decides this
22
+ * for almost every column; this union is declared here, in the model, so a
23
+ * column can name its zone without the schema layer importing the board (which
24
+ * imports the schema — the cycle that forces the direction).
25
+ *
26
+ * `body` is prose (a description, a note): it is never a type default, only an
27
+ * opt-in via `card.zone`. It carries a `rich` density floor, so it draws on any
28
+ * card laid out at `rich` — a board card, and the roomy calendar card — and
29
+ * drops out of the tighter ones, where a month cell has no room for a sentence.
30
+ */
31
+ export type ListCardZone = "title" | "chips" | "figures" | "footer" | "body";
32
+ export type ListSelectColor = CategoryColor;
33
+ export type ListColumnOption = {
34
+ value: string;
35
+ label?: string;
36
+ slot?: ListStatusSlot;
37
+ color?: ListSelectColor;
38
+ /**
39
+ * The value's stage mark — set when this option is a POSITION ON A LADDER,
40
+ * from the feature's mark helper (the deals module's `stageMarkFrom`
41
+ * pattern). A view that draws the option as a dot draws the mark instead; `slot` keeps
42
+ * carrying the badge/tint treatments beside it. Absent = a plain dot.
43
+ */
44
+ mark?: StageMark;
45
+ /** Retired: out of every picker, still drawn on a row that holds it. Copied
46
+ * from the field's option by `columnFrom`. */
47
+ archived?: boolean;
48
+ };
49
+ /**
50
+ * One end of a many-to-one relation — a row pointing at another entity.
51
+ *
52
+ * ALREADY RESOLVED by the host. The grid renders and edits it; it never turns an
53
+ * id into a label itself, because a cell that fetches is a cell that can't be
54
+ * lifted into another application, which is the whole point of this component.
55
+ *
56
+ * `entity` and `icon` ride on the VALUE rather than the column, and that is the
57
+ * load-bearing decision: a monomorphic column (every cell a subscription) could
58
+ * carry them once on the column, but a polymorphic one cannot — an execution's
59
+ * entity is a prospect OR a thread OR a campaign OR a message OR a lead OR a
60
+ * video, in the same column. Put them on the column and every polymorphic list
61
+ * is locked out of the type. `ListColumn.relation.entity` supplies the default
62
+ * for the simple case.
63
+ *
64
+ * `id` / `label` / `entity` / `avatarUrl` ARE `RelationValue` — the contract's
65
+ * display shape, shared with every other surface that draws a relation. In grid
66
+ * terms: `id` is compared, stored and committed but never shown; `label` is what
67
+ * the cell shows, what sorts and what lands on the clipboard; `entity` is handed
68
+ * back to `onOpenRelation` so the host knows which drawer to open; `avatarUrl`
69
+ * wins over every icon tier when set (see EntityChipIdentity). The grid adds
70
+ * exactly one key of its own, and it is a React one — which is why it is added
71
+ * HERE and not in `lib/fields`.
72
+ */
73
+ export type ListRelationValue = RelationValue & {
74
+ /** Per-value glyph, for a column whose rows point at different kinds. */
75
+ icon?: ReactNode;
76
+ };
77
+ export type { ListColumnFormat, ListDateStyle, ListDateStyleOverrides, ListDurationStyle, ListDurationStyleOverrides, ListNumberFormatOverrides, ListNumberFormatState, ListPercentDisplayOverrides, ListShowTimeOverrides, } from "./column-format.js";
78
+ export type ListOptionColorOverrides = Record<string, Record<string, ListSelectColor>>;
79
+ /** `ratio` is sum-over-sum as a percent, offered only by a column carrying `ratio`. */
80
+ export type ListAggregateKind = "none" | "sum" | "avg" | "min" | "max" | "count" | "filled" | "unique" | "ratio";
81
+ export type ListCellAction<Row> = {
82
+ id: string;
83
+ icon: (row: Row) => ReactNode;
84
+ label?: (row: Row) => string;
85
+ onClick?: (row: Row, event?: ReactMouseEvent<HTMLButtonElement>) => void;
86
+ status?: (row: Row) => ListStatusSlot | null;
87
+ };
88
+ /**
89
+ * Declarative column schema. A typed `accessor` uses standard chrome; `render`
90
+ * is the explicit custom escape hatch. Mutation and persistence stay with the
91
+ * feature and enter through GridTable callbacks.
92
+ */
93
+ /** What the chassis hands a custom `render` beside the row: the column's
94
+ * figure as its `accessor` reads it and the code that figure is in. */
95
+ export type RenderedValue = {
96
+ value: unknown;
97
+ code?: string;
98
+ };
99
+ export type ListColumn<Row> = {
100
+ id: string;
101
+ header: ReactNode;
102
+ /** A custom cell. The chassis hands it the row and, beside it, the column's
103
+ * own figure — what `accessor` reads and the code that figure is in — so a
104
+ * custom money cell draws the chassis's reading and converts nothing. */
105
+ render?: (row: Row, cell?: RenderedValue) => ReactNode;
106
+ actions?: ListCellAction<Row>[];
107
+ indicator?: (row: Row) => ReactNode;
108
+ accessor?: (row: Row) => unknown;
109
+ /** Raw field used for editing when display accessor contains fallbacks. */
110
+ editAccessor?: (row: Row) => unknown;
111
+ /** Numeric contribution used by aggregate functions. */
112
+ aggAccessor?: (row: Row) => number | null;
113
+ /**
114
+ * The currency THIS ROW's money is denominated in, when the column has no
115
+ * single one. `format.currency` is one code for the whole column, which is
116
+ * right for a converted ledger (every amount shown in the display currency)
117
+ * and wrong for a list where each row keeps its own — a subscription billed
118
+ * in RON next to one billed in USD.
119
+ *
120
+ * Wins over `format.currency`; a per-user display-currency override still
121
+ * wins over both, because that override means "show me everything in one
122
+ * currency" and answers the same question this accessor does.
123
+ *
124
+ * Two limits, by nature rather than by omission: the FOOTER has no row, so a
125
+ * total falls back to `format.currency` (a cross-currency sum is meaningless
126
+ * anyway — supply your own aggregate); and the FILTER box is column-wide, so
127
+ * it shows no unit rather than one row's.
128
+ */
129
+ currencyAccessor?: (row: Row) => string;
130
+ /** A name column: the words this row's empty name draws (an email, say) — the row's own answer, like
131
+ * its currency. Absent, an empty name draws nothing. */
132
+ nameFallback?: (row: Row) => string | null | undefined;
133
+ /** ONE currency for every number in this money column, and the COLUMN says
134
+ * which — it converted the figures, or declared a column-wide
135
+ * `format.currency`. The counterpart of `currencyAccessor` (each row's own
136
+ * code); `denominationOf` reads both and states the whole rule. */
137
+ surfaceOwnsCurrency?: boolean;
138
+ /** A convertible money column's declaration — the figure in the row's own
139
+ * currency, its code, its rates, and the reading it opens on. Built by
140
+ * `columnFrom` from a binding whose `unit` states `rates`; read by
141
+ * `readMoneyColumn`, which derives `accessor`, `aggAccessor`,
142
+ * `format.currency`, `currencyAccessor` and `surfaceOwnsCurrency` from it
143
+ * for whatever reading is in force. A column without it reads one way. */
144
+ money?: MoneyDeclaration<Row>;
145
+ /** The reading in force on a convertible column — set by `readMoneyColumn`. */
146
+ reading?: MoneyReading;
147
+ defaultAggregate?: ListAggregateKind;
148
+ /** The field whose database figures this column's footer reads, when it is
149
+ * not the column's own (Transactions' Amount totals its paid figure). A
150
+ * money column reads it in the currency it shows. */
151
+ footerField?: string;
152
+ /** The picks this column's footer offers, `none` always among them; absent,
153
+ * every pick its type allows. */
154
+ footerKinds?: readonly ListAggregateKind[];
155
+ /** Drawn after a Sum · Avg · Min · Max figure in the footer — the unit the
156
+ * figure is in when it is not the cell's own ("/mo" over a price per cycle). */
157
+ aggregateSuffix?: string;
158
+ editUnit?: {
159
+ value: (row: Row) => string;
160
+ options?: string[];
161
+ };
162
+ type?: ListColumnType;
163
+ /**
164
+ * `relation` columns only — the candidates the picker offers, and the default
165
+ * kind for cells that don't name their own.
166
+ *
167
+ * These are link candidates, distinct from filter options derived from loaded
168
+ * rows; filtering therefore never needs the whole entity table.
169
+ * `source` is the field binding's complete static-or-remote contract. The
170
+ * legacy `options` shape remains supported for handwritten list columns.
171
+ */
172
+ relation?: {
173
+ source?: RelationSource;
174
+ options?: ListRelationValue[];
175
+ /** Kind for values that don't carry their own — the monomorphic case. */
176
+ entity?: string;
177
+ };
178
+ /**
179
+ * This cell holds SEVERAL values, not one (an array). Declared rather than
180
+ * inferred from the data because `gridEditorKind` has no row to look at —
181
+ * and it is the editability answer that depends on it: a text editor for one
182
+ * address, the value list editor for several.
183
+ *
184
+ * Beside `type` rather than inside `format`, because it is a fact about what
185
+ * the value IS, not about how it looks — `format` is decimals / currency /
186
+ * dateStyle / booleanDisplay, and this one silently withholds the editor from
187
+ * every type it is set on. A shape fact filed under presentation is a thing
188
+ * the next adopter copies wrong.
189
+ */
190
+ multiple?: boolean;
191
+ /** A list column whose row keeps only the values (`FieldBinding.labels`): its editor offers no label box. */
192
+ labels?: false;
193
+ /**
194
+ * `multiselect` columns whose values are not free-form: the rule that turns
195
+ * what somebody typed into what this field stores.
196
+ *
197
+ * Declared because the SERVER already applies one on several of these
198
+ * columns, and a client that doesn't apply the same rule commits `Ops Team`,
199
+ * refetches `ops-team` and reports it as somebody else's edit. A pure
200
+ * function on the column, like `marker.reason` and `format.icon` — the column
201
+ * states its vocabulary; the chips editor enforces it.
202
+ */
203
+ chips?: {
204
+ normalize?: (raw: string) => string;
205
+ };
206
+ format?: ListColumnFormat;
207
+ options?: ListColumnOption[];
208
+ sortKey?: string;
209
+ /** `false`: the list's source has no order for this field (a list of values, a place), so its header
210
+ * offers no Sort on a saved view, a declared `sortKey` included. Absent, a bound field sorts by its key. */
211
+ sortable?: false;
212
+ /**
213
+ * False takes this field out of every place a list is SPLIT by it — the
214
+ * Group by header menu and the board's "Board by". A field's type says it
215
+ * can be split; the list says whether splitting by it means anything here —
216
+ * a relation with as many values as rows (People's companies: 15,000 of
217
+ * mostly one person) is a split nobody reads and a discovery no source can
218
+ * answer in one request.
219
+ */
220
+ bucketable?: boolean;
221
+ icon?: ReactNode;
222
+ /** Starting width for ANY columnar view — the grid and the table both size
223
+ * from it. What the USER has since dragged it to lives in their prefs, not
224
+ * here. */
225
+ width: number;
226
+ defaultHidden?: boolean;
227
+ align?: "left" | "center" | "right";
228
+ /**
229
+ * PRESENTATION THAT BELONGS TO ONE VIEW.
230
+ *
231
+ * Namespaced because a field definition and a view's configuration over that
232
+ * field are two different facts. `width` is shared above because every
233
+ * columnar view needs it; clamping to a min or max is something only the
234
+ * spreadsheet does — so a table or a card never has to read past a namespace
235
+ * that isn't its own.
236
+ *
237
+ * Every column is a FIXED width. There is no "fill" column: a track that
238
+ * absorbs leftover space gives that space back when a neighbour grows, so
239
+ * dragging one border moved the border on its other side too. Slack belongs
240
+ * to the grid's trailing tail track only, and borders always push right.
241
+ */
242
+ grid?: {
243
+ minWidth?: number;
244
+ maxWidth?: number;
245
+ };
246
+ /**
247
+ * CARD presentation, namespaced like `grid` and `table` above.
248
+ *
249
+ * `zone` overrides the board's type→zone default for THIS column. The default
250
+ * stays type-driven so every board composes cards the same way without a host
251
+ * deciding — but a type the table keeps off cards entirely (`text`, whose
252
+ * columns are prose: notes, descriptions) has no way to say "this one is a
253
+ * short fact worth showing". Deal pricing terms are the case: free text by
254
+ * nature, and the most important thing on a performance deal's card.
255
+ *
256
+ * An opt-in on the column, never a per-host override: the same column shows
257
+ * the same way on every board that renders it.
258
+ */
259
+ card?: {
260
+ zone?: ListCardZone;
261
+ };
262
+ /** LIST-view presentation, like `grid` and `card` above; read only by the
263
+ * rows look's typed path, and `views/list/list-typed.tsx` has the why. The
264
+ * last three dress the `title` column's identity cell. */
265
+ list?: {
266
+ hidden?: boolean;
267
+ track?: string;
268
+ subtitle?: (row: Row) => ReactNode;
269
+ avatar?: (row: Row) => ReactNode;
270
+ inlineActions?: (row: Row) => ReactNode;
271
+ };
272
+ editable?: boolean;
273
+ clearable?: boolean;
274
+ /** `marker` booleans (see `format.booleanDisplay`): what the badge says and
275
+ * what its hover/tap panel explains. Kept as one field rather than three
276
+ * loose props, and named for the marker rather than something generic like
277
+ * `hint` — a generic name drifts into "any cell tooltip" within a month and
278
+ * the contract blurs. */
279
+ marker?: {
280
+ /** The badge word. Defaults to the column header ("Flag" → "flagged" reads
281
+ * better as a marker, so most columns will set this). */
282
+ label?: string;
283
+ /** The panel's eyebrow + the trigger's accessible name. */
284
+ title?: string;
285
+ /** Why THIS row's exception was raised. */
286
+ reason?: (row: Row) => string | null;
287
+ };
288
+ /** This column's value is DERIVED or is a PICTURE — a rollup/formula field, or
289
+ * a hand-written cell with no field. Structurally non-writable. `from`
290
+ * completes "Computed from …" in the user's words; `columnFrom` stamps it for
291
+ * a derived field and REFUSES a hand-written one on a bound column. */
292
+ custom?: {
293
+ from: string;
294
+ };
295
+ /** A ratio formula's two parts, read off the row — the footer sums both and
296
+ * divides once (`ratio` aggregate). Carried from the binding by `columnFrom`. */
297
+ ratio?: {
298
+ numerator: (row: Row) => number | null;
299
+ denominator: (row: Row) => number | null;
300
+ };
301
+ /** Changes only through the entity's verbs — the cell opens the verb menu
302
+ * (`edit.mutability: "command"`, spec §5). Non-writable on every route. */
303
+ command?: true;
304
+ /**
305
+ * Why an ABSENT capability is absent — data-model truth as declared data.
306
+ * `clearable`/`editable` being missing carries no reason on its own, so a
307
+ * refusal can only say a generic "no"; declaring the reason here lets ONE
308
+ * string feed both the refusal toast ("Type is required — it can't be
309
+ * emptied.") and the Settings → Tables panel. Write them as full
310
+ * sentences about the data model, not about the UI.
311
+ */
312
+ reasons?: {
313
+ /** Shown where "Editable" reads as unavailable (`editable` not set). */
314
+ editable?: string;
315
+ /** Shown when a clear is refused (`clearable` not set). */
316
+ clearable?: string;
317
+ };
318
+ /**
319
+ * The field this column presents, when its module declares one (a
320
+ * `defineFields()` registry). `columnFrom` sets it; the write gate reads it
321
+ * for acceptance — a value the field's own schema refuses never reaches a
322
+ * commit. Nothing on the def reads the row — that is `binding` below.
323
+ */
324
+ field?: FieldDef;
325
+ /**
326
+ * How that field READS AND WRITES this row — the module's binding (spec
327
+ * §3.5), the one declaration the grid, the drawer and the board all consume.
328
+ *
329
+ * `columnFrom` attaches it and copies its reads onto the keys above, so
330
+ * every existing reader keeps working unchanged. What is new is the WRITE:
331
+ * `useListWrites` maps a commit through `binding.write` and never consults
332
+ * the list's `patch` for a column that carries one.
333
+ */
334
+ binding?: FieldBinding<Row>;
335
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,17 @@
1
+ import type { ListColumn } from "./column-schema.js";
2
+ /**
3
+ * THE KEY A COLUMN SORTS BY, if it sorts at all.
4
+ *
5
+ * A column that says it cannot sort (`sortable: false`) offers none. A declared
6
+ * `sortKey` is otherwise the host's word and always wins. Without one, a
7
+ * bound column on a saved view sorts by its FIELD: the view stores a field
8
+ * key and `SORT_COMPARATORS` is total over the type, so nothing but the
9
+ * missing string stopped these columns sorting. Off a saved view the host
10
+ * owns the comparator, and a key it does not know sorts by whatever its
11
+ * comparator does last — so nothing is offered there without a declaration.
12
+ *
13
+ * A `location` sorts only by one of its parts (`by`), which a column's key
14
+ * cannot name, so its column offers none; a column with no display read has
15
+ * nothing to compare.
16
+ */
17
+ export declare function effectiveSortKey<Row>(col: ListColumn<Row>, viewBacked: boolean): string | undefined;
@@ -0,0 +1,11 @@
1
+ import { valueTypeOf } from "@viewkitjs/fields";
2
+ export function effectiveSortKey(col, viewBacked) {
3
+ if (col.sortable === false)
4
+ return undefined;
5
+ if (col.sortKey)
6
+ return col.sortKey;
7
+ if (!viewBacked || !col.field || !col.accessor)
8
+ return undefined;
9
+ const type = valueTypeOf(col.field);
10
+ return type === "location" || type === "rich_text" ? undefined : col.field.key;
11
+ }
@@ -0,0 +1,77 @@
1
+ import type { ReactNode } from "react";
2
+ import type { ListColumn } from "./column-schema.js";
3
+ /** One column of a view, as a list that shows and hides columns reads it. */
4
+ export type ListColumnItem = {
5
+ id: string;
6
+ label: string;
7
+ icon?: ReactNode;
8
+ hidden: boolean;
9
+ hideable: boolean;
10
+ /** Declaration-only column: a saved view cannot hide or reorder it. */
11
+ fixed?: boolean;
12
+ };
13
+ /**
14
+ * A view's columns with what may be done to them: the grid's "+ Add column" lists the hidden ones, and a host's
15
+ * own column list (the app's Fields list, a field editor's "+ Add column") may take the same. A host's richer
16
+ * config satisfies it.
17
+ */
18
+ export type ListColumnsConfig = {
19
+ items: ListColumnItem[];
20
+ onToggleHidden: (id: string, hidden: boolean) => void;
21
+ onReorder: (orderedIds: string[]) => void;
22
+ onReset?: () => void;
23
+ dirty?: boolean;
24
+ };
25
+ export type ListColumnState = {
26
+ widths?: Record<string, number>;
27
+ hidden?: string[];
28
+ visible?: string[];
29
+ order?: string[];
30
+ /** Board only: ids that START a new line on the card. Absent = the board's
31
+ * default line-building (dates on their own line); present — even empty —
32
+ * is the user's explicit layout. The grid ignores it. */
33
+ breaks?: string[];
34
+ };
35
+ export declare const LIST_DEFAULT_MIN_WIDTH = 60;
36
+ /**
37
+ * The density vocabulary, shared by every view. How a view SPENDS it differs —
38
+ * the grid multiplies its pixel scale, the rows views widen their padding — so
39
+ * only the names live here; see `grid-table/core/grid-scale.ts`.
40
+ */
41
+ export type ListDensity = "compact" | "default" | "spacious";
42
+ /**
43
+ * The decimal places a number column can be shown at, offered by BOTH doors onto
44
+ * the setting — the grid's header menu and the Layout drill-in's Columns panel.
45
+ *
46
+ * One constant because it used to be two, kept in step by a comment. Reaches to
47
+ * 4 because sub-cent money is real (LLM spend per run routinely rounds to
48
+ * `$0.00` at the house default of 2), and a knob that can't offer what a column
49
+ * already declares is a knob that destroys precision the moment it is touched.
50
+ */
51
+ export declare const LIST_DECIMALS_CHOICES: readonly [0, 1, 2, 3, 4];
52
+ export declare function columnHideable<Row>(col: ListColumn<Row>): boolean;
53
+ /**
54
+ * Is this column hidden by DEFAULT, for the view asking?
55
+ *
56
+ * The rows look shows a handful of columns in a grid that never scrolls
57
+ * sideways, while the same typed set gives the spreadsheet ten to eighteen —
58
+ * so "hidden until you ask for it" is a per-view answer, not a column-wide one.
59
+ * `list.hidden` states it for that one view; every other view, and every caller
60
+ * that names none, reads `defaultHidden` alone. That is what keeps the grid,
61
+ * the board and the calendar untouched by this.
62
+ *
63
+ * `viewId` is a plain string because the model cannot import the view registry
64
+ * (the registry's own module imports the model). `"list"` is the only value
65
+ * with an answer of its own today.
66
+ */
67
+ export declare function columnDefaultHidden<Row>(col: ListColumn<Row>, viewId?: string): boolean;
68
+ export declare function isColumnHidden<Row>(col: ListColumn<Row>, state?: ListColumnState, viewId?: string): boolean;
69
+ export declare function toggleColumnHidden<Row>(state: ListColumnState | undefined, col: ListColumn<Row>, hide: boolean, viewId?: string): ListColumnState;
70
+ export declare function clampColumnWidth<Row>(col: ListColumn<Row>, width: number): number;
71
+ export declare function resolveColumnOrder<Row>(declared: ListColumn<Row>[], order?: string[]): ListColumn<Row>[];
72
+ export declare function resolveVisibleColumns<Row>(declared: ListColumn<Row>[], state?: ListColumnState, viewId?: string): ListColumn<Row>[];
73
+ export declare function resolveColumnWidths<Row>(visible: ListColumn<Row>[], widths?: Record<string, number>): Record<string, number>;
74
+ export declare function prettifyOptionValue(value: string): string;
75
+ export declare function computeMinWidth(columns: ListColumn<never>[] | {
76
+ width: number;
77
+ }[], gutterPx: number): number;
@@ -0,0 +1,95 @@
1
+ export const LIST_DEFAULT_MIN_WIDTH = 60;
2
+ export const LIST_DECIMALS_CHOICES = [0, 1, 2, 3, 4];
3
+ export function columnHideable(col) {
4
+ return col.type !== "title";
5
+ }
6
+ export function columnDefaultHidden(col, viewId) {
7
+ if (viewId === "list" && col.list?.hidden !== undefined)
8
+ return col.list.hidden;
9
+ return col.defaultHidden === true;
10
+ }
11
+ export function isColumnHidden(col, state, viewId) {
12
+ if (!columnHideable(col))
13
+ return false;
14
+ if (state?.hidden?.includes(col.id))
15
+ return true;
16
+ if (columnDefaultHidden(col, viewId))
17
+ return !state?.visible?.includes(col.id);
18
+ return false;
19
+ }
20
+ export function toggleColumnHidden(state, col, hide, viewId) {
21
+ const next = { ...state };
22
+ if (columnDefaultHidden(col, viewId)) {
23
+ const visible = new Set(next.visible ?? []);
24
+ if (hide)
25
+ visible.delete(col.id);
26
+ else
27
+ visible.add(col.id);
28
+ if (visible.size === 0)
29
+ delete next.visible;
30
+ else
31
+ next.visible = [...visible];
32
+ if (next.hidden?.includes(col.id)) {
33
+ const hidden = next.hidden.filter((id) => id !== col.id);
34
+ if (hidden.length === 0)
35
+ delete next.hidden;
36
+ else
37
+ next.hidden = hidden;
38
+ }
39
+ return next;
40
+ }
41
+ const hidden = new Set(next.hidden ?? []);
42
+ if (hide)
43
+ hidden.add(col.id);
44
+ else
45
+ hidden.delete(col.id);
46
+ if (hidden.size === 0)
47
+ delete next.hidden;
48
+ else
49
+ next.hidden = [...hidden];
50
+ return next;
51
+ }
52
+ export function clampColumnWidth(col, width) {
53
+ const min = col.grid?.minWidth ?? LIST_DEFAULT_MIN_WIDTH;
54
+ return Math.round(Math.min(col.grid?.maxWidth ?? Infinity, Math.max(min, width)));
55
+ }
56
+ export function resolveColumnOrder(declared, order) {
57
+ if (!order || order.length === 0)
58
+ return declared;
59
+ const byId = new Map(declared.map((col) => [col.id, col]));
60
+ const result = order.filter((id) => byId.has(id));
61
+ for (let index = 0; index < declared.length; index++) {
62
+ const id = declared[index].id;
63
+ if (result.includes(id))
64
+ continue;
65
+ let insertAt = 0;
66
+ for (let previous = index - 1; previous >= 0; previous--) {
67
+ const resolvedIndex = result.indexOf(declared[previous].id);
68
+ if (resolvedIndex !== -1) {
69
+ insertAt = resolvedIndex + 1;
70
+ break;
71
+ }
72
+ }
73
+ result.splice(insertAt, 0, id);
74
+ }
75
+ return result.map((id) => byId.get(id));
76
+ }
77
+ export function resolveVisibleColumns(declared, state, viewId) {
78
+ const ordered = resolveColumnOrder(declared, state?.order);
79
+ const visible = ordered.filter((col) => !isColumnHidden(col, state, viewId));
80
+ return visible.length > 0 ? visible : ordered.slice(0, 1);
81
+ }
82
+ export function resolveColumnWidths(visible, widths) {
83
+ const resolved = {};
84
+ for (const col of visible) {
85
+ const width = widths?.[col.id];
86
+ resolved[col.id] = width != null ? clampColumnWidth(col, width) : col.width;
87
+ }
88
+ return resolved;
89
+ }
90
+ export function prettifyOptionValue(value) {
91
+ return value.replace(/[_-]+/g, " ").replace(/\b\w/g, (character) => character.toUpperCase());
92
+ }
93
+ export function computeMinWidth(columns, gutterPx) {
94
+ return columns.reduce((sum, column) => sum + column.width, gutterPx);
95
+ }
@@ -0,0 +1,109 @@
1
+ import type { ReactNode } from "react";
2
+ import type { RelationSource } from "../fields/relation-source-types.js";
3
+ import type { ListColumn, ListColumnType, ListRelationValue } from "./column-schema.js";
4
+ /**
5
+ * ONE declaration per column type — what the machinery may do with it.
6
+ *
7
+ * This exists because adding a type used to cost six edits in six files and the
8
+ * compiler only caught two of them. The column-glyph map (`LIST_TYPE_ICONS`,
9
+ * `cells/icons.tsx`) and the filter map were exhaustive `Record`s, but the
10
+ * editor map was `Partial` and both the render and the paste switch carried a
11
+ * `default` — so forgetting the renderer or the paste rule compiled clean and
12
+ * failed at runtime, which is the worst shape a bug takes here. "The grid
13
+ * supports N types" was a thing six files happened to agree on rather than a
14
+ * fact anything enforced.
15
+ *
16
+ * Now the three CORE answers live here in one exhaustive map, so a new member of
17
+ * `ListColumnType` cannot be added without answering all of them. The two that
18
+ * remain outside are the ones that need JSX, which core may not hold: the glyph
19
+ * (`LIST_TYPE_ICONS` in `cells/icons.tsx`, exhaustive — it takes each storage
20
+ * type's mark from `shared/fields/type-icons` and adds the list's own `title`
21
+ * role (the text mark) and `status`) and the cell renderer (`renderTypedCell` in `chrome/`,
22
+ * exhaustive via a `never` check). Four enforced points beats six unenforced
23
+ * ones, and the layering stays intact.
24
+ *
25
+ * The shape is deliberately DECLARATIVE — each field names a strategy rather
26
+ * than holding a function. A new type picks from strategies that already exist
27
+ * and are already tested, instead of arriving with its own bespoke behaviour.
28
+ */
29
+ /** Which editor a writable column mounts when clicked, Entered or typed into. */
30
+ export type GridEditorId = "text" | "select" | "number" | "date" | "relation" | "chips" | "range" | "name"
31
+ /** Several values of one kind (`multiple` email, phone, url or domain), each with its label and a main one. */
32
+ | "values";
33
+ /** Which editor this type opens in the Filter drill-in. `none` lists the
34
+ * column and opens nothing — a structured value with no rule to write. */
35
+ export type ListFilterEditor = "options" | "text" | "number" | "date" | "boolean" | "range" | "none";
36
+ /**
37
+ * How a pasted clipboard cell becomes this type's commit payload.
38
+ * `none` means the type refuses paste — the honest answer for a display-only
39
+ * type, and the same answer it gives about mounting an editor.
40
+ */
41
+ export type GridPasteKind = "text" | "option" | "number" | "date" | "boolean"
42
+ /** Match the pasted TEXT against the candidates' LABELS and commit the id —
43
+ * `option`'s strategy with one hop, because what a person copies out of a
44
+ * relation cell is the name, not the uuid. */
45
+ | "relation"
46
+ /** Split the pasted TEXT into several values — the mirror of how a list is
47
+ * copied, so a cell-to-cell paste round-trips and a spreadsheet column of
48
+ * comma-separated labels arrives whole. */
49
+ | "list"
50
+ /** A low and a high end: an in-grid copy carries the pair; outside text is
51
+ * read the way a range is written — "11–50", "10,001+", "up to 50", "7". */
52
+ | "range" | "none";
53
+ /**
54
+ * What a committed value has to LOOK like for this type — the write gate's
55
+ * rules, stated per type rather than re-checked at each call site.
56
+ * `any` is the honest default: most types accept whatever their editor emits.
57
+ */
58
+ export type GridValueKind = "any" | "email" | "url" | "boolean" | "relation" | "list";
59
+ export type GridTypeRule = {
60
+ /** `null` = no editor. Booleans are `null` and still writable: they commit
61
+ * instantly, so there is nothing to mount. */
62
+ editor: GridEditorId | null;
63
+ filter: ListFilterEditor;
64
+ paste: GridPasteKind;
65
+ value: GridValueKind;
66
+ };
67
+ export declare const GRID_TYPE_RULES: Record<ListColumnType, GridTypeRule>;
68
+ /** This type's rules, or null for a column that declares no type at all. */
69
+ export declare function typeRule(type: ListColumnType | undefined): GridTypeRule | null;
70
+ /**
71
+ * How a paste becomes this column's value. A column of several values (`multiple`) pastes as a list, whatever its
72
+ * type: an in-grid copy carries its items, outside text splits into values. A `multiple` column of a type that holds
73
+ * no list, or that presents no field to read its values, takes no paste, as it mounts no editor (`gridEditorKind`).
74
+ */
75
+ export declare function gridPasteKind<Row>(col: ListColumn<Row>): GridPasteKind | null;
76
+ /**
77
+ * A relation value with the column's default KIND filled in.
78
+ *
79
+ * The rule itself is the contract's (`resolveRelationValue`), because a display
80
+ * core has to answer it without a column to look at. What the list adds is the
81
+ * one thing the contract has no word for: where the default kind comes from —
82
+ * `col.relation.entity`, the monomorphic column's single answer. The value's
83
+ * own `entity` still wins, which is the polymorphic case.
84
+ *
85
+ * The result is typed as `ListRelationValue` because the list's value is the
86
+ * contract's plus an optional per-value `icon`, so a resolved value that
87
+ * carried one still has it.
88
+ */
89
+ export declare function resolveGridRelation<Row>(col: ListColumn<Row>, raw: unknown): ListRelationValue | null;
90
+ /**
91
+ * The column's candidates, each wearing the glyph its KIND wears everywhere
92
+ * else in the app — what the picker offers.
93
+ *
94
+ * Lives in core, beside `resolveGridRelation`, because it is the same rule
95
+ * applied to a different input: the CELL fills in the column's default kind to
96
+ * decide what it draws, and the PICKER has to fill in the same default to dress
97
+ * the row you are about to choose. Split across two layers, those drift, and
98
+ * the symptom is a list where the option you pick doesn't look like the value
99
+ * you get.
100
+ *
101
+ * `entityIcon` arrives as a RESOLVER, which is what keeps this file free of any
102
+ * app's entity vocabulary — core knows there is such a thing as a kind, never
103
+ * which kinds exist. Absent (a host that wired none), the candidates come back
104
+ * untouched and the picker draws no glyph lane at all.
105
+ *
106
+ * A value that brought its OWN icon keeps it: the polymorphic case, where the
107
+ * column has no single answer to give.
108
+ */
109
+ export declare function gridRelationSource<Row>(col: ListColumn<Row>, entityIcon?: (kind: string | undefined) => ReactNode): RelationSource;