@marktiderman/genesis-core 2.16.1 → 2.17.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 (124) hide show
  1. package/README.md +3 -2
  2. package/dist/{aggregate-Y5IJ5aPn.d.ts → aggregate-v_r-nZbH.d.ts} +1 -1
  3. package/dist/{chunk-M5IX7C6U.js → chunk-24X4HWL5.js} +4 -4
  4. package/dist/{chunk-M5IX7C6U.js.map → chunk-24X4HWL5.js.map} +1 -1
  5. package/dist/chunk-2ORQLYVW.js +115 -0
  6. package/dist/chunk-2ORQLYVW.js.map +1 -0
  7. package/dist/{chunk-XPBS5YE4.js → chunk-4POVYF6P.js} +4 -4
  8. package/dist/{chunk-XPBS5YE4.js.map → chunk-4POVYF6P.js.map} +1 -1
  9. package/dist/{chunk-IYGVJFCV.js → chunk-5KLIFJYG.js} +3 -3
  10. package/dist/{chunk-IYGVJFCV.js.map → chunk-5KLIFJYG.js.map} +1 -1
  11. package/dist/{chunk-ALLWIK62.js → chunk-6B4CN2TC.js} +8 -6
  12. package/dist/chunk-6B4CN2TC.js.map +1 -0
  13. package/dist/chunk-6JOWGO2X.js +266 -0
  14. package/dist/chunk-6JOWGO2X.js.map +1 -0
  15. package/dist/{chunk-E3K2A3PK.js → chunk-6SHGMEA6.js} +3 -3
  16. package/dist/{chunk-E3K2A3PK.js.map → chunk-6SHGMEA6.js.map} +1 -1
  17. package/dist/chunk-6VNM6KAX.js +59 -0
  18. package/dist/chunk-6VNM6KAX.js.map +1 -0
  19. package/dist/{chunk-SOO54YYY.js → chunk-AQX5HQD6.js} +3 -3
  20. package/dist/{chunk-SOO54YYY.js.map → chunk-AQX5HQD6.js.map} +1 -1
  21. package/dist/chunk-BNKP2H7J.js +11 -0
  22. package/dist/chunk-BNKP2H7J.js.map +1 -0
  23. package/dist/{chunk-FXPODKCK.js → chunk-FBMKI22S.js} +6 -6
  24. package/dist/{chunk-FXPODKCK.js.map → chunk-FBMKI22S.js.map} +1 -1
  25. package/dist/{chunk-POUI7GAI.js → chunk-JF7FXSQB.js} +5 -5
  26. package/dist/{chunk-POUI7GAI.js.map → chunk-JF7FXSQB.js.map} +1 -1
  27. package/dist/chunk-JNWTHDGF.js +892 -0
  28. package/dist/chunk-JNWTHDGF.js.map +1 -0
  29. package/dist/chunk-K33LWVUF.js +31 -0
  30. package/dist/chunk-K33LWVUF.js.map +1 -0
  31. package/dist/chunk-KRRESUXT.js +192 -0
  32. package/dist/chunk-KRRESUXT.js.map +1 -0
  33. package/dist/{chunk-LB6FMQQM.js → chunk-KV2HW4G4.js} +3 -11
  34. package/dist/chunk-KV2HW4G4.js.map +1 -0
  35. package/dist/{chunk-42NVJJTT.js → chunk-MMMC37AP.js} +3 -3
  36. package/dist/{chunk-42NVJJTT.js.map → chunk-MMMC37AP.js.map} +1 -1
  37. package/dist/chunk-MZVFOTAE.js +96 -0
  38. package/dist/chunk-MZVFOTAE.js.map +1 -0
  39. package/dist/{chunk-R3YXYVWF.js → chunk-OIZNABG4.js} +5 -4
  40. package/dist/chunk-OIZNABG4.js.map +1 -0
  41. package/dist/{chunk-QGWQ6LK3.js → chunk-QJOKZZKY.js} +9 -6
  42. package/dist/chunk-QJOKZZKY.js.map +1 -0
  43. package/dist/chunk-TWLPC4S3.js +53 -0
  44. package/dist/chunk-TWLPC4S3.js.map +1 -0
  45. package/dist/{chunk-7EFTWOMA.js → chunk-UNEZF3ZP.js} +73 -15
  46. package/dist/chunk-UNEZF3ZP.js.map +1 -0
  47. package/dist/chunk-WNOCPV4A.js +220 -0
  48. package/dist/chunk-WNOCPV4A.js.map +1 -0
  49. package/dist/{chunk-ZYOJWU62.js → chunk-XIBQ5BTZ.js} +12 -53
  50. package/dist/chunk-XIBQ5BTZ.js.map +1 -0
  51. package/dist/chunk-YMFJLBIZ.js +159 -0
  52. package/dist/chunk-YMFJLBIZ.js.map +1 -0
  53. package/dist/{chunk-UDSTWXXZ.js → chunk-ZKLB2HB5.js} +3 -3
  54. package/dist/{chunk-UDSTWXXZ.js.map → chunk-ZKLB2HB5.js.map} +1 -1
  55. package/dist/csv.d.ts +12 -3
  56. package/dist/csv.js +4 -4
  57. package/dist/csv.js.map +1 -1
  58. package/dist/form-types.d.ts +1 -1
  59. package/dist/headless/index.d.ts +1 -1
  60. package/dist/hooks/index.d.ts +16 -6
  61. package/dist/hooks/index.js +27 -15
  62. package/dist/hooks/mutation-mode.d.ts +1 -1
  63. package/dist/hooks/mutation-mode.js +3 -3
  64. package/dist/hooks/related-keys.d.ts +1 -1
  65. package/dist/hooks/use-aggregate.d.ts +2 -2
  66. package/dist/hooks/use-aggregate.js +3 -3
  67. package/dist/hooks/use-board-columns.d.ts +79 -0
  68. package/dist/hooks/use-board-columns.js +4 -0
  69. package/dist/hooks/use-board-columns.js.map +1 -0
  70. package/dist/hooks/use-capabilities.d.ts +1 -1
  71. package/dist/hooks/use-capabilities.js +2 -2
  72. package/dist/hooks/use-infinite-resource.d.ts +1 -1
  73. package/dist/hooks/use-infinite-resource.js +3 -3
  74. package/dist/hooks/use-link-options.d.ts +1 -1
  75. package/dist/hooks/use-link-options.js +5 -5
  76. package/dist/hooks/use-list-state.d.ts +103 -0
  77. package/dist/hooks/use-list-state.js +21 -0
  78. package/dist/hooks/use-list-state.js.map +1 -0
  79. package/dist/hooks/use-live.d.ts +1 -1
  80. package/dist/hooks/use-live.js +2 -2
  81. package/dist/hooks/use-one.d.ts +7 -1
  82. package/dist/hooks/use-one.js +3 -3
  83. package/dist/hooks/use-persisted-ui-state.js +2 -2
  84. package/dist/hooks/use-relation-label.d.ts +1 -1
  85. package/dist/hooks/use-relation-label.js +2 -2
  86. package/dist/hooks/use-resource-form.d.ts +1 -1
  87. package/dist/hooks/use-resource-form.js +7 -7
  88. package/dist/hooks/use-resource.d.ts +7 -1
  89. package/dist/hooks/use-resource.js +5 -5
  90. package/dist/hooks/use-segment-counts.d.ts +23 -0
  91. package/dist/hooks/use-segment-counts.js +19 -0
  92. package/dist/hooks/use-segment-counts.js.map +1 -0
  93. package/dist/hooks/use-view-board.d.ts +120 -0
  94. package/dist/hooks/use-view-board.js +29 -0
  95. package/dist/hooks/use-view-board.js.map +1 -0
  96. package/dist/hooks/use-view-calendar-range.d.ts +91 -0
  97. package/dist/hooks/use-view-calendar-range.js +22 -0
  98. package/dist/hooks/use-view-calendar-range.js.map +1 -0
  99. package/dist/hooks/use-write.d.ts +1 -1
  100. package/dist/index.d.ts +41 -11
  101. package/dist/index.js +119 -26
  102. package/dist/index.js.map +1 -1
  103. package/dist/provider/index.d.ts +61 -8
  104. package/dist/provider/index.js +2 -2
  105. package/dist/resource-view/index.d.ts +162 -757
  106. package/dist/resource-view/index.js +31 -686
  107. package/dist/resource-view/index.js.map +1 -1
  108. package/dist/saved-views-C45lRm7i.d.ts +155 -0
  109. package/dist/schema/index.d.ts +3 -3
  110. package/dist/schema/index.js +2 -1
  111. package/dist/testing/index.d.ts +2 -2
  112. package/dist/types-BAhcze_-.d.ts +1063 -0
  113. package/dist/{types-BriIV4e_.d.ts → types-CiQY6hUy.d.ts} +11 -1
  114. package/dist/{viewer-scope-Dx0N9AYk.d.ts → viewer-oOk0ZZk9.d.ts} +36 -34
  115. package/dist/{workspaces-CxpiFu2-.d.ts → workspaces-DeaFix5Z.d.ts} +1 -1
  116. package/dist/workspaces.d.ts +2 -2
  117. package/dist/{write-outcome-CkQXgtJq.d.ts → write-outcome-DuwfsnyO.d.ts} +1 -1
  118. package/package.json +11 -1
  119. package/dist/chunk-7EFTWOMA.js.map +0 -1
  120. package/dist/chunk-ALLWIK62.js.map +0 -1
  121. package/dist/chunk-LB6FMQQM.js.map +0 -1
  122. package/dist/chunk-QGWQ6LK3.js.map +0 -1
  123. package/dist/chunk-R3YXYVWF.js.map +0 -1
  124. package/dist/chunk-ZYOJWU62.js.map +0 -1
@@ -0,0 +1,1063 @@
1
+ import { R as ResourceContract, e as DataRow, l as RowOf, c as Identifier, m as RowAction, a as FilterParam, F as FieldSchema } from './types-CiQY6hUy.js';
2
+ import { R as Readiness, C as ChipTone } from './status-BXRokZD9.js';
3
+ import { V as Viewer, R as ResourceScope } from './viewer-oOk0ZZk9.js';
4
+ import { GalleryItem } from './gallery/index.js';
5
+
6
+ type AnyView = ResourceView<ResourceContract<any>, any>;
7
+ /** Equality filters for a child list, sent to the server: `{ brand_id: brand.id }`. `null` is "is empty". */
8
+ type RecordViewFilter = Readonly<Record<string, string | number | boolean | null>>;
9
+ interface SectionBase {
10
+ /** Unique in the record view; the screen's route segment or slot key. */
11
+ id: string;
12
+ label: string;
13
+ }
14
+ /** A child list: another view, filtered by this record. */
15
+ interface RecordViewListSection<Row extends DataRow = DataRow> extends SectionBase {
16
+ list: {
17
+ view: AnyView;
18
+ filter: (row: Row) => RecordViewFilter;
19
+ };
20
+ settings?: never;
21
+ }
22
+ /** A few of this record's own fields, edited in place. Each must be in `view.writable("edit")`. */
23
+ interface RecordViewSettingsSection<Name extends string = string> extends SectionBase {
24
+ settings: readonly Name[];
25
+ list?: never;
26
+ }
27
+ /** A section the screen fills itself, through a slot keyed by `id`. */
28
+ interface RecordViewSlotSection extends SectionBase {
29
+ list?: never;
30
+ settings?: never;
31
+ }
32
+ type RecordViewSection<Row extends DataRow = DataRow, Name extends string = string> = RecordViewListSection<Row> | RecordViewSettingsSection<Name> | RecordViewSlotSection;
33
+ /** One readiness check: "Has a logo", ok or not, and why not. */
34
+ interface RecordViewReadinessItem {
35
+ /** A stable key for the check; default its position and title. */
36
+ id?: string;
37
+ title: string;
38
+ ok: boolean;
39
+ reason?: string;
40
+ /** Genesis chip tones only. Default `success` when ok, `warning` when not. */
41
+ tone?: ViewTone;
42
+ }
43
+ /**
44
+ * A record page template (ADR 0021): `standard` (a header with the summary and actions, then the
45
+ * sections) or `document` (a cover, an icon, a large title, the properties, then the body, like
46
+ * a page in a notes app).
47
+ *
48
+ * @stability Beta
49
+ */
50
+ type RecordPageTemplate = "standard" | "document";
51
+ /**
52
+ * Where a `document` template finds its parts, by field name. Each is optional; a part whose
53
+ * field is empty on a row isn't drawn.
54
+ *
55
+ * @stability Beta
56
+ */
57
+ interface RecordViewDocument<Name extends string = string> {
58
+ /** A text field holding the cover image's URL. */
59
+ cover?: Name;
60
+ /** A text field holding the icon: an emoji or a short text, or an image's URL. */
61
+ icon?: Name;
62
+ /** The fields listed under the title, as label and value, in order. */
63
+ properties?: readonly Name[];
64
+ /** The long text below the properties. */
65
+ body?: Name;
66
+ }
67
+ /** What `defineRecordView` accepts. */
68
+ interface RecordViewDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> {
69
+ /** The view actions the header offers, by name, in order. Default: every view action. */
70
+ header?: {
71
+ actions?: readonly string[];
72
+ };
73
+ /** The sections. A `document` template may have none (the document is the page). */
74
+ sections: readonly RecordViewSection<Row, FieldNameOf<C>>[];
75
+ readiness?: (row: Row) => readonly RecordViewReadinessItem[];
76
+ /** The record page template. Default `standard`, the page as before. */
77
+ template?: RecordPageTemplate;
78
+ /** With `template: "document"`: the fields its cover, icon, properties and body show. */
79
+ document?: RecordViewDocument<FieldNameOf<C>>;
80
+ }
81
+ /** A section as a renderer draws it. */
82
+ type ResolvedRecordViewSection = {
83
+ readonly id: string;
84
+ readonly label: string;
85
+ readonly kind: "list";
86
+ readonly view: AnyView;
87
+ } | {
88
+ readonly id: string;
89
+ readonly label: string;
90
+ readonly kind: "settings";
91
+ readonly settings: readonly string[];
92
+ } | {
93
+ readonly id: string;
94
+ readonly label: string;
95
+ readonly kind: "slot";
96
+ };
97
+ /** A header action with whether this row allows it. */
98
+ interface RecordViewHeaderAction {
99
+ readonly name: string;
100
+ readonly label: string;
101
+ readonly confirm?: string;
102
+ readonly description?: string;
103
+ readonly destructive?: boolean;
104
+ /** `true`, or the view guard's reason. Only narrows what the server allows. */
105
+ readonly allowed: Allowed;
106
+ }
107
+ /** The header for one row: the view's summary plus the header's actions. */
108
+ interface RecordViewHeader {
109
+ readonly title: string;
110
+ readonly subtitle?: string;
111
+ readonly chips: readonly {
112
+ label: string;
113
+ tone?: ViewTone;
114
+ }[];
115
+ readonly actions: readonly RecordViewHeaderAction[];
116
+ }
117
+ /** What a screen and its provider add to the header: they only narrow the view's guards. */
118
+ interface RecordViewHeaderOptions<Row extends DataRow = DataRow> {
119
+ /** The screen's own rule: `false` hides the action, a sentence refuses it with that reason. */
120
+ can?: (action: string, row: Row) => Allowed | boolean;
121
+ /** Whether anything can run actions here (the screen's `onAction`, or the provider's `runAction`). `false` hides them all. */
122
+ runnable?: boolean;
123
+ /** The action names the provider reports serving (`ResourceSchema.actions`), when it reports them. Others are hidden. */
124
+ served?: readonly string[];
125
+ /** Who is looking (`useViewer()`), for the view's action guards. Without it they get no one. */
126
+ viewer?: Viewer;
127
+ }
128
+ /** A readiness check with its tone resolved. */
129
+ interface ResolvedReadinessItem {
130
+ /** Stable, for list keys: the check's `id`, or its position and title. */
131
+ readonly key: string;
132
+ readonly title: string;
133
+ readonly ok: boolean;
134
+ readonly reason?: string;
135
+ readonly tone: ViewTone;
136
+ }
137
+ /**
138
+ * Any record view, whatever its contract: the type a view's `recordView` returns. Name it on that
139
+ * function (`recordView: (): AnyRecordView => brandRecordView`), since the record view is defined
140
+ * from the view and TypeScript can't infer one from the other.
141
+ *
142
+ * @stability Beta
143
+ */
144
+ type AnyRecordView = RecordView<ResourceContract<any>, any>;
145
+ /** What `defineRecordView` returns: frozen, with pure helpers for the renderers. */
146
+ interface RecordView<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> {
147
+ readonly view: ResourceView<C, Row>;
148
+ readonly sections: readonly ResolvedRecordViewSection[];
149
+ /** The header's action names, in order. */
150
+ readonly headerActions: readonly string[];
151
+ readonly hasReadiness: boolean;
152
+ /** The record page template: `standard` unless the definition says `document`. */
153
+ readonly template: RecordPageTemplate;
154
+ /** The document template's fields (frozen); empty for `standard`. */
155
+ readonly document: Readonly<RecordViewDocument>;
156
+ section(id: string): ResolvedRecordViewSection | undefined;
157
+ /** The record's address for the provider: its key fields (`keyFields`), composite keys encoded. */
158
+ recordId(row: Row): Identifier;
159
+ /**
160
+ * Why settings can't be saved for this row and viewer: the view's `can("update", row, viewer)`
161
+ * reason, or `null` when they can. Renderers then show the settings read-only with the reason.
162
+ * Without a viewer the guard gets no one, so one that needs the viewer locks them.
163
+ */
164
+ settingsLocked(row: Row, viewer?: Viewer): string | null;
165
+ headerFor(row: Row, options?: RecordViewHeaderOptions<Row>): RecordViewHeader;
166
+ /**
167
+ * Settings fields as the view's form resolves them (`view.form("edit")`), in the order listed:
168
+ * one section's, or every settings section's without an id.
169
+ */
170
+ settingsFields(sectionId?: string): readonly ResolvedFormField[];
171
+ /** Only the section's listed keys that `values` has: what a save sends. */
172
+ settingsPatch(sectionId: string, values: Readonly<Record<string, unknown>>): Record<string, unknown>;
173
+ /**
174
+ * A list section's filter for this row. In development, a filter with no key, or a value that
175
+ * isn't a string, number, boolean or null, throws: it would show every child row.
176
+ */
177
+ listFilter(sectionId: string, row: Row): RecordViewFilter;
178
+ /** The readiness checks for this row, tones resolved; empty without `readiness`. */
179
+ readinessFor(row: Row): readonly ResolvedReadinessItem[];
180
+ /**
181
+ * The checks in one chip's terms (genesis-core/resource's `readinessOf`): an unmet `danger`
182
+ * check is a problem, any other unmet check one to look at. `null` without `readiness`. Draw
183
+ * it with `readinessChip`.
184
+ */
185
+ readinessSummary(row: Row): Readiness | null;
186
+ }
187
+ /**
188
+ * Whether two values are the same as a settings form holds them: 2 and "2", and null, undefined
189
+ * and "", are the same. A settings section compares an edit with the row through it, so an edit
190
+ * back to the stored value isn't a change (web and native RecordView).
191
+ */
192
+ declare function sameFormValue(a: unknown, b: unknown): boolean;
193
+ /** Whether a value is a record view (`defineRecordView`'s result). */
194
+ declare function isRecordView(value: unknown): value is RecordView;
195
+ /**
196
+ * One record's screen from its view:
197
+ *
198
+ * ```ts
199
+ * export const brandRecordView = defineRecordView(brandsView, {
200
+ * header: { actions: ["archive"] },
201
+ * sections: [
202
+ * { id: "products", label: "Products", list: { view: productsView, filter: (b) => ({ brand_id: b.id }) } },
203
+ * { id: "settings", label: "Settings", settings: ["name", "website"] },
204
+ * { id: "activity", label: "Activity" }, // the screen fills it
205
+ * ],
206
+ * readiness: (b) => [{ title: "Has a website", ok: !!b.website, reason: "Add the website." }],
207
+ * });
208
+ * ```
209
+ *
210
+ * Throws {@link ViewDefinitionError} for a settings field the view can't write, a header action
211
+ * the view doesn't define, a repeated section id, or a section that holds another record view.
212
+ */
213
+ declare function defineRecordView<C extends ResourceContract, Row extends DataRow = RowOf<C>>(view: ResourceView<C, Row>, definition: RecordViewDefinition<C, Row>): RecordView<C, Row>;
214
+ /** @deprecated Renamed `defineRecordView`. Removed in the next major. @stability Deprecated */
215
+ declare const defineWorkspace: typeof defineRecordView;
216
+ /** @deprecated Renamed `isRecordView`. Removed in the next major. @stability Deprecated */
217
+ declare const isWorkspace: typeof isRecordView;
218
+ /** @deprecated Renamed `RecordView`. Removed in the next major. @stability Deprecated */
219
+ type ResourceWorkspace<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> = RecordView<C, Row>;
220
+ /** @deprecated Renamed `RecordViewDefinition`. */
221
+ type WorkspaceDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> = RecordViewDefinition<C, Row>;
222
+ /** @deprecated Renamed `RecordViewSection`. */
223
+ type WorkspaceSection<Row extends DataRow = DataRow, Name extends string = string> = RecordViewSection<Row, Name>;
224
+ /** @deprecated Renamed `RecordViewHeaderAction`. */
225
+ type WorkspaceHeaderAction = RecordViewHeaderAction;
226
+
227
+ /** A chip's colour: the one Genesis tone set (`ChipTone`, genesis-core/resource). */
228
+ type ViewTone = ChipTone;
229
+ /**
230
+ * How a value is shown. A hint: each platform registers one renderer per hint, so the shared view
231
+ * never imports a platform. Derived from the field when the view doesn't say.
232
+ */
233
+ type DisplayHint = "text" | "longText" | "number" | "currency" | "percent" | "boolean" | "badge" | "date" | "datetime" | "relation" | "url" | "email" | "image" | "json";
234
+ /** The field names a contract declares; `string` when the contract isn't a literal. */
235
+ type FieldNameOf<C extends ResourceContract> = C["fields"][number]["name"];
236
+ /** What a view says about one field. Every key is optional; the contract fills the rest. */
237
+ interface ViewField<Row extends DataRow = DataRow> {
238
+ /** The field's label. Default: the contract's label, then the name in title case. */
239
+ label?: string;
240
+ display?: DisplayHint;
241
+ /** A badge's tone per value, e.g. `{ active: "success", archived: "muted" }`. */
242
+ tones?: Readonly<Record<string, ViewTone>>;
243
+ /**
244
+ * The words for a value, e.g. `{ draft: "In progress" }`: badges, form choices, group titles.
245
+ * A value without one shows in title case. Keys must be the field's enum values, if it has any.
246
+ */
247
+ labels?: Readonly<Record<string, string>>;
248
+ /**
249
+ * For a link (`relation`): the linked row's field that names it, e.g. `"full_name"`. Default:
250
+ * the linked resource's `labelField` (`provider.describe`), else a `name`/`title`-like field.
251
+ */
252
+ labelField?: string;
253
+ /**
254
+ * For a link: the words when the linked row is hidden from this viewer or gone, e.g.
255
+ * `"Someone you can't see"`. Default: the catalogue's `common.hiddenLink`. Never the raw id.
256
+ */
257
+ missingLabel?: string;
258
+ /**
259
+ * For a link: edit it in the view's forms with a picker, and how the picker lists the rows it
260
+ * can point at. Setting it (`{}` is enough) opts the link in; without it (or the view's
261
+ * `editLinks`) a link stays read-only. `view` narrows it to the linked view's rules (its scope
262
+ * and default filter); `filter` adds more.
263
+ */
264
+ link?: ViewLink;
265
+ /** Longest text a form accepts. Feeds the derived validation. */
266
+ max?: number;
267
+ /**
268
+ * In a form: the browser's autofill token (`email`, `tel`, `given-name`, `one-time-code`,
269
+ * `off`, ...). Unset, the input carries no `autocomplete` attribute and gets no token from its
270
+ * type, so the browser applies its own heuristics (it may still offer to fill it). Set a token
271
+ * where the form is about the viewer, and `off` on a form about someone else (an admin editing
272
+ * a member) to ask the browser not to fill in the person at the keyboard.
273
+ */
274
+ autoComplete?: string;
275
+ /** In a form: which on-screen keyboard a phone shows. Unset, it follows the field's type. */
276
+ inputMode?: "none" | "text" | "decimal" | "numeric" | "tel" | "search" | "email" | "url";
277
+ /** In a form: the label on the keyboard's Return key (`next`, `done`, `go`, `search`, `send`). */
278
+ enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
279
+ /** Shown read-only even where the server would accept a write. Never widens. */
280
+ readOnly?: boolean;
281
+ /**
282
+ * Show the cell only when the row (and the viewer) say so: for values a server function masks
283
+ * by policy (`(row) => row.author_visible`). The masking itself is the server's. It hides
284
+ * table cells and the peek only: not workspace settings, an edit form's prefilled values, a
285
+ * view's `summary` or header, or sorting and searching on the column.
286
+ */
287
+ when?: (row: Row, viewer: Viewer) => boolean;
288
+ /** In a form: show the field only while this holds for the form's values. A hidden field isn't saved. */
289
+ visible?: (values: Readonly<Record<string, unknown>>) => boolean;
290
+ /**
291
+ * A timestamp's clock: the viewer's (default), the scope's (the zone of whatever the screen is
292
+ * scoped to: ViewerScope's `scopeTimeZone`, or NativeResourceView's prop), or a fixed IANA zone.
293
+ * Closed: any other word (the removed `"practice"`) is a type error, and `defineView` refuses a
294
+ * zone the runtime doesn't know.
295
+ */
296
+ timeZone?: ViewTimeZone;
297
+ /**
298
+ * How much the field matters in a row (ADR 0017): `title` (the row's name, strongest; one per
299
+ * view, default the `labelField`), `secondary` or `muted`. Meaning, not markup: each platform
300
+ * and brand decides how it looks.
301
+ */
302
+ emphasis?: ViewEmphasis;
303
+ /** `false` keeps the column's header from sorting the list (a value the server can't order by). */
304
+ sortable?: boolean;
305
+ /** Hide the column below this screen width on the web: `sm`, `md`, `lg` or `xl`. */
306
+ hideBelow?: ViewBreakpoint;
307
+ /** The column's starting width: a number of pixels, or a CSS length (`"12rem"`). */
308
+ width?: number | string;
309
+ }
310
+ /** How much a field matters in a row (`ViewField.emphasis`). @stability Beta */
311
+ type ViewEmphasis = "title" | "secondary" | "muted";
312
+ /** A screen width a column hides below (`ViewField.hideBelow`). @stability Beta */
313
+ type ViewBreakpoint = "sm" | "md" | "lg" | "xl";
314
+ /**
315
+ * A field a person can narrow the list by (ADR 0017, `defineView`'s `filters`). The platform
316
+ * draws it from what the contract and the view know: a field with choices (an enum, a yes/no)
317
+ * gets multi-select chips in its words and tones, a date or number a range, a text field
318
+ * "contains". Every value is sent to the server, never applied to loaded rows.
319
+ *
320
+ * @stability Beta
321
+ */
322
+ interface ViewFilter<Name extends string = string> {
323
+ field: Name;
324
+ /** The filter's label. Default the field's. */
325
+ label?: string;
326
+ /** Default from the field: `choice` for an enum or yes/no, `range` for a date or number, else `text`. */
327
+ kind?: ViewFilterKind;
328
+ /** For `choice`: narrow the values offered (and, for a field without fixed values, name them). */
329
+ options?: readonly string[];
330
+ /** The value the filter starts at: values for a choice, `{ gte, lte }` for a range, words for text. */
331
+ default?: ViewFilterValue;
332
+ }
333
+ /** How a declared filter narrows the list. @stability Beta */
334
+ type ViewFilterKind = "choice" | "range" | "text";
335
+ /**
336
+ * A declared filter's value: the chosen values (`choice`), a range (`{ gte, lte }`, either end
337
+ * open) or words (`text`, matched as "contains").
338
+ *
339
+ * @stability Beta
340
+ */
341
+ type ViewFilterValue = readonly string[] | {
342
+ readonly gte?: string;
343
+ readonly lte?: string;
344
+ } | string;
345
+ /**
346
+ * Which rows a segment holds: equality per field, `null` for "is empty", a list for "any of", and
347
+ * `{ gte, lte }` for a range. Sent to the server with the list request.
348
+ *
349
+ * @stability Beta
350
+ */
351
+ type SegmentWhere<Name extends string = string> = Readonly<Partial<Record<Name, string | number | boolean | null | readonly (string | number)[] | {
352
+ readonly gte?: string | number;
353
+ readonly lte?: string | number;
354
+ }>>>;
355
+ /**
356
+ * A named tab over a list ("Open", "Mine", "All") with its own filter and an optional count
357
+ * (ADR 0017). Not a preset (a screen's fixed columns and filter) and not a saved view (a person's
358
+ * own).
359
+ *
360
+ * @stability Beta
361
+ */
362
+ interface ViewSegment<Name extends string = string> {
363
+ /** Lowercase letters, digits, `-` and `_`: it goes in the URL (`?seg=open`). */
364
+ id: string;
365
+ label: string;
366
+ /** Its rows, or a function of the viewer for one relative to them (`(v) => ({ owner_id: v.id })`). No `where`: every row. */
367
+ where?: SegmentWhere<Name> | ((viewer: Viewer) => SegmentWhere<Name>);
368
+ /**
369
+ * Arguments for a function-backed source (`source.args`'s `take`), sent as equality filters the
370
+ * function takes and the query leaves out: `{ inbox_view: "mine" }`. Not fields, so not checked
371
+ * against the contract.
372
+ */
373
+ args?: Readonly<Record<string, string | number | boolean | null>>;
374
+ /** Show a count beside the label: one count request through the provider. */
375
+ count?: boolean;
376
+ /** A column preset the segment shows (`columns`). Default the screen's. */
377
+ columns?: string;
378
+ }
379
+ /** A group or footer total (`defineView`'s `totals`). @stability Beta */
380
+ type ViewTotal = "sum" | "avg" | "min" | "max" | "count";
381
+ /**
382
+ * A view's CSV export (ADR 0017 §8). The default columns are the column preset's, minus sensitive
383
+ * fields and computed columns; values are written in words (a badge's label) unless `raw`.
384
+ *
385
+ * @stability Beta
386
+ */
387
+ interface ViewExport<Name extends string = string> {
388
+ /** The fields exported, in order. Default the shown preset's field columns. */
389
+ columns?: readonly Name[];
390
+ /** The file's name, without `.csv`. Default the view's plural noun. */
391
+ filename?: string;
392
+ /** Stop after this many rows (the file says it was cut short). Default 10 000. */
393
+ maxRows?: number;
394
+ /** Write stored values (codes) instead of their words. Default false. */
395
+ raw?: boolean;
396
+ }
397
+ /**
398
+ * What a bulk action runs on: the selected rows, or (only for a `run` that says `matching`) every
399
+ * row the list's filters, segment and search match, sent as those filters and never as ids.
400
+ *
401
+ * @stability Beta
402
+ */
403
+ type BulkTarget<Row extends DataRow = DataRow> = {
404
+ readonly kind: "rows";
405
+ readonly rows: readonly Row[];
406
+ } | {
407
+ readonly kind: "matching";
408
+ readonly filters: readonly FilterParam[];
409
+ readonly search?: {
410
+ readonly query: string;
411
+ readonly fields: readonly string[];
412
+ };
413
+ readonly total: number;
414
+ };
415
+ /**
416
+ * A view action that also runs on many rows at once (ADR 0017 §3, `ViewAction.bulk`). Without
417
+ * `run`, it runs the row action once per selected row through the provider, checking `can` per
418
+ * row and reporting the rows it skipped and why.
419
+ *
420
+ * @stability Beta
421
+ */
422
+ interface ViewBulkAction<Row extends DataRow = DataRow> {
423
+ /** The bulk bar's words. Default the action's label. */
424
+ label?: string;
425
+ /** A confirmation, with `{count}`: "Archive {count} tasks?". Default the action's own `confirm`. */
426
+ confirm?: string;
427
+ /** Runs it on many rows at once (one server call). Default: the row action per row. */
428
+ run?: (target: BulkTarget<Row>, viewer: Viewer) => void | Promise<void>;
429
+ /**
430
+ * `run` accepts every matching row as filters (`target.kind === "matching"`), so "select all
431
+ * matching" can reach it. Such a run gets no rows, so no per-row `can` check has happened: it
432
+ * must enforce access itself (a server function under the caller's row-level security, checking
433
+ * each row it touches), and treat the filters and search as untrusted input from the browser.
434
+ */
435
+ matching?: boolean;
436
+ }
437
+ /**
438
+ * A picker's filter: equality per field. `null` is "is empty", a list is "any of". Sent to the
439
+ * server with the list request, never applied to loaded rows.
440
+ */
441
+ type LinkFilter = Readonly<Record<string, string | number | boolean | null | readonly (string | number)[]>>;
442
+ /** The parts of the linked resource's view a picker reads. */
443
+ type LinkedView = Pick<ResourceView<any, any>, "resource" | "definition" | "labelField">;
444
+ /**
445
+ * How a link's picker lists the linked rows (`fields.owner_id.link`). The list always goes through
446
+ * the provider, so row-level security decides what the viewer can pick; these only narrow it.
447
+ */
448
+ interface ViewLink {
449
+ /**
450
+ * The linked resource's view. Its `scope` keys (read from the viewer's scope, as its own lists
451
+ * do), its `default` preset's filter (or `preset`'s) and its `labelField` apply to the picker.
452
+ * A function for two views that link each other (`() => usersView`).
453
+ */
454
+ view?: LinkedView | (() => LinkedView);
455
+ /** One of the linked view's presets whose filter the picker uses. Default: its `default` preset. */
456
+ preset?: string;
457
+ /**
458
+ * More filters: fixed, or from the form's values, for a picker that follows another field
459
+ * (`(values) => ({ project_id: values.project_id })`, the tasks of the chosen project).
460
+ */
461
+ filter?: LinkFilter | ((values: Readonly<Record<string, unknown>>) => LinkFilter);
462
+ /** The linked fields a search matches. Default: the naming field (`labelField`). */
463
+ searchFields?: readonly string[];
464
+ /**
465
+ * The order the picker lists rows in. Default: by the naming field, then the key. `"view"`
466
+ * uses the linked view's own `orderBy` (a `position` its list is sorted by) and needs `view`;
467
+ * a linked view without one keeps the default. `{ field, direction }` names a linked field.
468
+ */
469
+ orderBy?: "view" | LinkOrder;
470
+ }
471
+ /** A picker's order: a field of the linked resource, ascending unless it says so. */
472
+ interface LinkOrder {
473
+ field: string;
474
+ direction?: "asc" | "desc";
475
+ /** Where rows with no value go. Unset, the store decides. */
476
+ nulls?: "first" | "last";
477
+ }
478
+ /** A link's picker, resolved: what to list, what names a row, and the filters to send. */
479
+ interface ResolvedLink {
480
+ /** The linked resource. */
481
+ resource: string;
482
+ /** The linked field the link stores (its key, usually `id`). */
483
+ field: string;
484
+ /** The linked field that names a row: the view field's, else the linked view's. Undefined: the provider's `describe`. */
485
+ readonly labelField: string | undefined;
486
+ /** The linked fields a search matches. Unset: the naming field. */
487
+ searchFields?: readonly string[];
488
+ /**
489
+ * The order the picker lists rows in (`link.orderBy`, or the linked view's `orderBy` for
490
+ * `"view"`), then the key. Undefined: by the naming field, then the key.
491
+ */
492
+ readonly orderBy?: {
493
+ readonly field: string;
494
+ readonly direction: "asc" | "desc";
495
+ readonly nulls?: "first" | "last" | undefined;
496
+ } | undefined;
497
+ /**
498
+ * The filters a picker sends: the linked view's scope keys from `scope` (as its own lists apply
499
+ * them), its preset's filter, then the link's own `filter` for these form values.
500
+ */
501
+ filters(scope?: ResourceScope | null, values?: Readonly<Record<string, unknown>>): FilterParam[];
502
+ }
503
+ /**
504
+ * An IANA zone name as written: `"UTC"`, `"GMT"` or `Area/Location` (`"Europe/Berlin"`). The
505
+ * type keeps a bare word out; `defineView` checks the runtime knows the zone.
506
+ */
507
+ type TimeZoneName = "UTC" | "GMT" | `${string}/${string}`;
508
+ /** A view field's clock: the viewer's, the scope's, or a fixed zone. */
509
+ type ViewTimeZone = "viewer" | "scope" | TimeZoneName;
510
+ /** A column computed from the row, never stored or sent. */
511
+ interface ComputedColumn<Row extends DataRow = DataRow> {
512
+ /** The column's key; must not clash with a field name. */
513
+ key: string;
514
+ label: string;
515
+ value: (row: Row) => unknown;
516
+ display?: DisplayHint;
517
+ }
518
+ /** One entry in a column list: a field by name, or a computed column. */
519
+ type ViewColumn<Name extends string, Row extends DataRow> = Name | ComputedColumn<Row>;
520
+ /** A form laid out in order: fields, and fields under a heading. */
521
+ type ViewFormItem<Name extends string> = Name | {
522
+ section: string;
523
+ title?: string;
524
+ fields: readonly Name[];
525
+ };
526
+ /**
527
+ * A named tab of the list: which columns, and which rows (`{ status: "open" }` is an equality
528
+ * filter, sent to the server, never applied to loaded rows).
529
+ */
530
+ interface ViewPreset<Name extends string> {
531
+ label?: string;
532
+ columns?: string;
533
+ filter?: Readonly<Partial<Record<Name, string | number | boolean | null>>>;
534
+ }
535
+ /** `true` when allowed, or the reason it isn't, in one sentence for the disabled control. */
536
+ type Allowed = true | string;
537
+ /**
538
+ * Row rules the server can't cheaply express ("the default brand can't be deleted"). They only
539
+ * narrow: the effective right is the server's AND these. An invariant goes in the database too.
540
+ *
541
+ * Each gets the viewer (`useViewer()`: id, scope, roles). Outside a ViewerScope it is
542
+ * `{ id: null, scope: {} }`, so a guard that needs it refuses with its reason. Pure and
543
+ * synchronous; never a security check (row-level security is the boundary).
544
+ */
545
+ interface ViewGuards<Row extends DataRow> {
546
+ create?: (viewer: Viewer) => Allowed;
547
+ update?: (row: Row, viewer: Viewer) => Allowed;
548
+ delete?: (row: Row, viewer: Viewer) => Allowed;
549
+ }
550
+ /**
551
+ * A named operation on one row, shaped like core's {@link RowAction} (which a provider reports),
552
+ * plus a guard. The guard only narrows: the server still decides whether the action runs.
553
+ *
554
+ * ```ts
555
+ * actions: [{ name: "archive", label: "Archive", confirm: "Archive this brand?", can: (r) => (r.is_default ? "The default brand stays." : true) }]
556
+ * ```
557
+ */
558
+ interface ViewAction<Row extends DataRow = DataRow> extends RowAction {
559
+ /** Drawn as destructive (red, the menu's destructive style). */
560
+ destructive?: boolean;
561
+ can?: (row: Row, viewer: Viewer) => Allowed;
562
+ /** Also offer it on many selected rows (ADR 0017): `true`, or how it runs on them. */
563
+ bulk?: boolean | ViewBulkAction<Row>;
564
+ }
565
+ /** An action as a renderer lists it: the words only. Ask `view.canAction` whether a row allows it. */
566
+ type ResolvedViewAction = RowAction & {
567
+ readonly destructive?: boolean;
568
+ /** Set when the action runs on many rows: its bar label, confirmation and whether it takes every matching row. */
569
+ readonly bulk?: {
570
+ readonly label: string;
571
+ readonly confirm?: string;
572
+ readonly matching: boolean;
573
+ readonly batch: boolean;
574
+ };
575
+ };
576
+ /** A row in one line, for pickers, notifications and page bars. */
577
+ interface RowSummary {
578
+ title: string;
579
+ subtitle?: string;
580
+ chips?: readonly {
581
+ label: string;
582
+ tone?: ViewTone;
583
+ }[];
584
+ /**
585
+ * A picture beside the row: `src` is shown only when `isSafeUrl` accepts it; otherwise the
586
+ * initials of `name`. `alt` defaults to empty (decorative). Resolve it with `rowPicture`.
587
+ */
588
+ image?: RowImage;
589
+ }
590
+ /** A row's picture, as a view's `summary` gives it. */
591
+ interface RowImage {
592
+ src?: string;
593
+ /** Whose picture: the initials come from it when there is no safe `src`. */
594
+ name?: string;
595
+ /** Alternative text. Default empty: the picture is decorative (the row's title names it). */
596
+ alt?: string;
597
+ }
598
+ /** A row's picture, ready to draw: an image (with initials for when it fails to load), or initials. */
599
+ type RowPicture = {
600
+ readonly kind: "image";
601
+ readonly src: string;
602
+ readonly alt: string;
603
+ readonly fallback: string;
604
+ } | {
605
+ readonly kind: "initials";
606
+ readonly text: string;
607
+ };
608
+ /**
609
+ * The words a view shows. Each one is a step in a chain, and each step overrides the one before:
610
+ * words derived from the resource's name, then the contract's (`noun`, `nounPlural`, `label`, which
611
+ * `genesis introspect` reads from the table comment's `@genesis {...}`), then these, then the
612
+ * screen's own props. Templates take `{noun}`, `{nouns}`, `{count}` and `{total}`.
613
+ */
614
+ interface ViewCopy {
615
+ /** One row, in a sentence: "brand". Default: the contract's `noun`, then the table name's singular. */
616
+ noun?: string;
617
+ /**
618
+ * Several: "brands". Default: the contract's `nounPlural`, then the plural of a `noun` the view or
619
+ * contract gives ("entry" → "entries"); with only a noun derived from the name, the contract's
620
+ * label when it reads as a plural ("People"), else the table name.
621
+ */
622
+ nounPlural?: string;
623
+ /** The page title. Default: the contract's label, then the plural noun in title case. */
624
+ title?: string;
625
+ subtitle?: string;
626
+ empty?: {
627
+ title?: string;
628
+ body?: string;
629
+ };
630
+ /** The create button. Default "New". */
631
+ create?: string;
632
+ /**
633
+ * The form's words. Titles: default "New {noun}" and "Edit {noun}" (the UI catalogue's `form`).
634
+ * Submit buttons: default "Create" and "Save". Descriptions (read out with the title): default
635
+ * the UI catalogue's `form.createDescription` and `form.editDescription`.
636
+ */
637
+ form?: {
638
+ createTitle?: string;
639
+ editTitle?: string;
640
+ createSubmit?: string;
641
+ editSubmit?: string;
642
+ createDescription?: string;
643
+ editDescription?: string;
644
+ };
645
+ /**
646
+ * The count beside the title. Default "{count} {noun}" for one, "{count} {nouns}" for more, and
647
+ * "{count} of {total}" when filtered (the UI catalogue's `page.count*`).
648
+ */
649
+ count?: {
650
+ one?: string;
651
+ other?: string;
652
+ filtered?: string;
653
+ };
654
+ }
655
+ /** How a calendar lays out its window: a month grid, 1–4 weeks, a day-by-day agenda, or a row per lane. */
656
+ type ViewCalendarLayout = "month" | "weeks" | "agenda" | "lanes";
657
+ /** What a calendar's `durationField` counts. */
658
+ type ViewCalendarDurationUnit = "minutes" | "hours" | "days";
659
+ /**
660
+ * How the view's rows show as a calendar: ResourceView's `mode="calendar"` on the web,
661
+ * NativeResourceView's later. Plain values only, so every platform reads the same block; a screen
662
+ * overrides the layout, weeks and anchor, and adds functions (dot colours, `onSelect`).
663
+ */
664
+ interface ViewCalendar<Name extends string = string> {
665
+ /** The date or timestamp field that places each row. */
666
+ field: Name;
667
+ /** Where a row ends: its last day for a date field, its end instant for a timestamp. */
668
+ endField?: Name;
669
+ /**
670
+ * A number field holding how long a row runs, for a row with no end column: its end is the
671
+ * start plus this many `durationUnit`s. A row whose `endField` has a value keeps that end.
672
+ */
673
+ durationField?: Name;
674
+ /** What `durationField` counts. Default `minutes`. */
675
+ durationUnit?: ViewCalendarDurationUnit;
676
+ /**
677
+ * The longest a row with a `durationField` runs, in `durationUnit`s. The calendar reads rows that
678
+ * started up to this long before its window too, so one that runs into the window from before
679
+ * it (a session at 23:00 for two hours) is drawn. Without it, such a row is drawn only on the
680
+ * days it starts in the window, and a calendar with no `endField` warns once. Past the read's
681
+ * limit, the latest starts are kept.
682
+ */
683
+ maxDuration?: number;
684
+ /** A yes/no field: the row is all day, its timestamp shown without a time. */
685
+ allDayField?: Name;
686
+ /** The field whose value (or list of values) names a row's lanes: a dot each, a lane each. */
687
+ laneBy?: Name;
688
+ /** Default `month`. */
689
+ layout?: ViewCalendarLayout;
690
+ /**
691
+ * The layout on a phone (below 768px), until the person picks one from the layout switch:
692
+ * `"agenda"` turns a month grid too narrow to read into a day-by-day list. Unset, a phone shows
693
+ * `layout`, as before.
694
+ */
695
+ phoneLayout?: ViewCalendarLayout;
696
+ /** For `weeks`, `agenda` and `lanes`: 1 to 4. Default 2. */
697
+ weeks?: 1 | 2 | 3 | 4;
698
+ /** 0 Sunday or 1 Monday (default). */
699
+ weekStartsOn?: 0 | 1;
700
+ }
701
+ /**
702
+ * How the view's rows show as a board: a column per value of one field, a card per row.
703
+ * ResourceView's `mode="board"` draws it, and moving a card between columns writes the field
704
+ * through the provider. Plain values only, so every platform reads the same block.
705
+ */
706
+ interface ViewBoard<Name extends string = string> {
707
+ /** The field whose value is a card's column: a field with choices (an enum) or a yes/no one. */
708
+ field: Name;
709
+ /**
710
+ * The columns, in order, as values of `field`. Default: its choices in the contract's order,
711
+ * then a "No value" column when it can be empty. Listing them shows only those.
712
+ */
713
+ columns?: readonly string[];
714
+ /** The fields a card shows under its title, in order. Default none: the title alone. */
715
+ cardFields?: readonly Name[];
716
+ /**
717
+ * The most cards a column should hold, by value (`{ doing: 3 }`): a work-in-progress limit.
718
+ * A column over its limit says so; nothing stops a move into it.
719
+ */
720
+ limits?: Readonly<Record<string, number>>;
721
+ }
722
+ /**
723
+ * How the view's rows show as a gallery: ResourceView's `mode="grid"` draws a photo per row in
724
+ * justified rows (the layout `GalleryGrid` uses, from `@marktiderman/genesis-core/gallery`) in
725
+ * place of cards. Plain field names only, so every platform reads the same block.
726
+ */
727
+ interface ViewGallery<Name extends string = string> {
728
+ /** The field holding the image's URL. */
729
+ image: Name;
730
+ /** The image's width and height in pixels, when the rows store them: rows pack by their ratio, 4:3 without. */
731
+ width?: Name;
732
+ height?: Name;
733
+ /** A short line under the photo in the viewer. Default none. */
734
+ caption?: Name;
735
+ /** The photo's text alternative. Default the row's label (the view's `labelField`). */
736
+ alt?: Name;
737
+ /** The target row height, px on the web and points on a phone. Default 180, as `GalleryGrid`. */
738
+ rowHeight?: number;
739
+ }
740
+ /**
741
+ * How the view's rows show as an inbox (ADR 0017, the `inbox` view type): a three-pane layout of
742
+ * segments, a list of rows like messages, and the open record. Field names only, except `unread`,
743
+ * which may be a function of the row; every platform reads the same block.
744
+ *
745
+ * @stability Beta
746
+ */
747
+ interface ViewInbox<Name extends string = string, Row extends DataRow = DataRow> {
748
+ /** The row's title line: a field, or a function of the row (a direct message's other person). Default the view's `labelField`. */
749
+ title?: Name | ((row: Row) => string | null | undefined);
750
+ /** One line under the title (the latest message, a description): a field, or a function of the row. */
751
+ preview?: Name | ((row: Row) => string | null | undefined);
752
+ /** A date or timestamp field: the row's short relative time. */
753
+ time?: Name;
754
+ /** Who it's from, in words: a line under the preview, and the avatar's initials. A field, or a function of the row. */
755
+ from?: Name | ((row: Row) => string | null | undefined);
756
+ /** An image field: the avatar beside the row. */
757
+ avatar?: Name;
758
+ /** A yes/no field, or a function of the row: bold, with a dot, while it's unread. */
759
+ unread?: Name | ((row: Row) => boolean);
760
+ /** A field drawn as a badge at the row's end, in its `fields.<name>.tones`. */
761
+ badge?: Name;
762
+ /** What fills the left rail: the view's segments (and saved views). Default `"segments"` when the view has segments. */
763
+ rail?: "segments" | "none";
764
+ /** The view action the `e` key runs on the open row ("done", "close"). Default an action named `done` or `close`. */
765
+ doneAction?: string;
766
+ /**
767
+ * The view action run when an unread row is opened, to mark it read. Default an action named
768
+ * `markRead`, if the view declares one. Genesis never writes on its own.
769
+ */
770
+ markRead?: string;
771
+ }
772
+ /** One row as an inbox draws it (`ResourceView.inboxRow`). @stability Beta */
773
+ interface InboxRow {
774
+ readonly id: string;
775
+ readonly title: string;
776
+ readonly preview?: string;
777
+ /** The time field's value, as stored (an ISO date or timestamp). */
778
+ readonly time?: string;
779
+ readonly from?: string;
780
+ readonly avatar?: string;
781
+ readonly unread: boolean;
782
+ readonly badge?: {
783
+ readonly label: string;
784
+ readonly tone?: ViewTone;
785
+ };
786
+ }
787
+ /**
788
+ * How a record opens from a view (a record page, ADR 0021): a **side peek** (a panel at the edge,
789
+ * the list still beside it), a **center peek** (a dialog over the list) or a full **page** (the
790
+ * record's own route).
791
+ *
792
+ * @stability Beta
793
+ */
794
+ type RecordOpen = "side-peek" | "center-peek" | "page";
795
+ /** The open modes, in the order a picker lists them. @stability Beta */
796
+ declare const RECORD_OPEN_MODES: readonly RecordOpen[];
797
+ /** What `defineView` accepts. */
798
+ interface ViewDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> {
799
+ copy?: ViewCopy;
800
+ fields?: {
801
+ readonly [K in FieldNameOf<C>]?: ViewField<Row>;
802
+ };
803
+ /**
804
+ * Column lists by preset name. `default` is the full list; others (`compact`) are what a screen
805
+ * picks. Without `default`: every field that isn't sensitive, generated-only or the key.
806
+ */
807
+ columns?: {
808
+ readonly default?: readonly ViewColumn<FieldNameOf<C>, Row>[];
809
+ } & {
810
+ readonly [preset: string]: readonly ViewColumn<FieldNameOf<C>, Row>[] | undefined;
811
+ };
812
+ /** Tabs: columns plus filters. */
813
+ presets?: Readonly<Record<string, ViewPreset<FieldNameOf<C>>>>;
814
+ /** The record form. Default: every writable field, in contract order. */
815
+ form?: readonly ViewFormItem<FieldNameOf<C>>[];
816
+ /**
817
+ * Edit every link in this view's forms with a picker. Default false: a link is read-only (and
818
+ * never sent) unless its `fields.<link>.link` is set (`{}` is enough). The default flips in 3.0.
819
+ */
820
+ editLinks?: boolean;
821
+ can?: ViewGuards<Row>;
822
+ /** Named operations on one row, in the order a menu shows them. Names are unique. */
823
+ actions?: readonly ViewAction<Row>[];
824
+ summary?: (row: Row) => RowSummary;
825
+ /** The scope keys this view needs above it (`["org_id"]`). They stay out of forms. */
826
+ scope?: readonly FieldNameOf<C>[];
827
+ /** How the rows show as a calendar (`mode="calendar"`). */
828
+ calendar?: ViewCalendar<FieldNameOf<C>>;
829
+ /** How the rows show as a board (`mode="board"`). */
830
+ board?: ViewBoard<FieldNameOf<C>>;
831
+ /** How the rows show as a gallery of photos (`mode="grid"`), in place of cards. */
832
+ gallery?: ViewGallery<FieldNameOf<C>>;
833
+ /** How the rows show as an inbox (`type="inbox"`): a list like messages beside the open record. */
834
+ inbox?: ViewInbox<FieldNameOf<C>, Row>;
835
+ /** Group rows under headers by this field. */
836
+ groupBy?: FieldNameOf<C>;
837
+ /**
838
+ * How a record opens from every view type of this view (ADR 0021): `side-peek` (default),
839
+ * `center-peek` or `page`. A screen's own `open` (or ResourcePage's older `detail`) wins.
840
+ */
841
+ open?: RecordOpen;
842
+ /**
843
+ * The record view a peek renders: a function, because the record view is defined from this
844
+ * view, with its return type named so TypeScript needn't infer one from the other:
845
+ * `recordView: (): AnyRecordView => brandRecordView`. Without one, a peek shows the view's
846
+ * columns as today.
847
+ */
848
+ recordView?: () => AnyRecordView;
849
+ /**
850
+ * Default order; `manual: true` turns on drag to reorder, writing this field. `nulls` says where
851
+ * rows with no value go (unset, the store decides: Postgres puts them first on a descending sort).
852
+ */
853
+ orderBy?: {
854
+ field: FieldNameOf<C>;
855
+ direction?: "asc" | "desc";
856
+ nulls?: "first" | "last";
857
+ manual?: boolean;
858
+ };
859
+ /** Bumped when stored preferences (saved views, column order) change shape. */
860
+ version?: number;
861
+ /**
862
+ * The fields a person can narrow the list by (ADR 0017 §1): drawn as a filter bar on the web,
863
+ * sent to the server, and kept in the URL (`f.<field>`) once the app gives the list a URL adapter.
864
+ */
865
+ filters?: readonly ViewFilter<FieldNameOf<C>>[];
866
+ /** Named tabs over the list, each with its own filter and an optional count (ADR 0017 §1). */
867
+ segments?: readonly ViewSegment<FieldNameOf<C>>[];
868
+ /**
869
+ * The view types a person may switch between (ADR 0017): `table`, `list`, `grid`, `board`,
870
+ * `calendar`, `gallery` or a registered type's id. Default: table, list and grid, plus each
871
+ * type the view has a block for (gallery, board, calendar). A switcher shows when there are two
872
+ * or more; each person's choice is kept in the app's saved-view store.
873
+ */
874
+ types?: readonly string[];
875
+ /** Per field, a total shown in each group's header and the list's footer (`sum`, `avg`, `min`, `max`, `count`). */
876
+ totals?: Readonly<Partial<Record<FieldNameOf<C>, ViewTotal>>>;
877
+ /**
878
+ * A row's tone (an overdue task, a paused client), drawn from tokens: a leading bar and a
879
+ * tinted row on the web. Return nothing for a plain row.
880
+ */
881
+ rowTone?: (row: Row) => ViewTone | null | undefined;
882
+ /** Offer "Export CSV" on the list (`true`, or which columns, the file's name and the cap). */
883
+ export?: boolean | ViewExport<FieldNameOf<C>>;
884
+ /**
885
+ * A refused row or bulk action: `disable` (default) shows it with the guard's reason, `hide`
886
+ * leaves it out (for an action only some people ever have).
887
+ */
888
+ refusals?: "disable" | "hide";
889
+ }
890
+ /** A declared filter as a renderer draws it: everything resolved. @stability Beta */
891
+ interface ResolvedFilter {
892
+ readonly field: string;
893
+ readonly label: string;
894
+ readonly kind: ViewFilterKind;
895
+ /** For `choice`: each value with its words and tone, in the contract's order. */
896
+ readonly options: readonly {
897
+ readonly value: string;
898
+ readonly label: string;
899
+ readonly tone?: ViewTone;
900
+ }[];
901
+ /** For `range`: whether the values are dates (`date`), timestamps (`datetime`) or numbers. */
902
+ readonly input?: "date" | "datetime" | "number";
903
+ /**
904
+ * For a `date` input over a timestamp column (one shown as a date): a day is the viewer's day, so
905
+ * a range runs from that day's start in their zone to the next day's start.
906
+ */
907
+ readonly instants?: boolean;
908
+ readonly default?: ViewFilterValue;
909
+ }
910
+ /** A segment as a renderer draws it. @stability Beta */
911
+ interface ResolvedSegment {
912
+ readonly id: string;
913
+ readonly label: string;
914
+ readonly count: boolean;
915
+ readonly columns?: string;
916
+ }
917
+ /** A column as a renderer draws it: everything resolved. */
918
+ interface ResolvedColumn<Row extends DataRow = DataRow> {
919
+ key: string;
920
+ label: string;
921
+ display: DisplayHint;
922
+ /** The field behind it; absent for a computed column. */
923
+ field?: FieldSchema;
924
+ value: (row: Row) => unknown;
925
+ tones?: Readonly<Record<string, ViewTone>>;
926
+ /** The words for a value (`ViewField.labels`); `valueText` reads them. */
927
+ labels?: Readonly<Record<string, string>>;
928
+ /** For a link: the linked row's field that names it (`ViewField.labelField`). */
929
+ labelField?: string;
930
+ /** For a link: the words when its row is hidden or gone (`ViewField.missingLabel`). */
931
+ missingLabel?: string;
932
+ /** Whether to show the cell. Without a viewer it answers for no one (fail closed). */
933
+ when?: (row: Row, viewer?: Viewer) => boolean;
934
+ timeZone?: ViewField["timeZone"];
935
+ /** `ViewField.emphasis`; the label field's column is `title` unless the view says otherwise. */
936
+ emphasis?: ViewEmphasis;
937
+ /** `false` when the header mustn't sort (`ViewField.sortable`, or a computed column). */
938
+ sortable?: boolean;
939
+ hideBelow?: ViewBreakpoint;
940
+ width?: number | string;
941
+ }
942
+ /** A form field as a renderer draws it. */
943
+ interface ResolvedFormField {
944
+ field: FieldSchema;
945
+ label: string;
946
+ display: DisplayHint;
947
+ required: boolean;
948
+ readOnly: boolean;
949
+ max?: number;
950
+ /** The input's autofill token (`ViewField.autoComplete`). */
951
+ autoComplete?: string;
952
+ /** The keyboard a phone shows (`ViewField.inputMode`). */
953
+ inputMode?: ViewField["inputMode"];
954
+ /** The Return key's label (`ViewField.enterKeyHint`). */
955
+ enterKeyHint?: ViewField["enterKeyHint"];
956
+ /** For a link: the linked row's field that names it (`ViewField.labelField`). */
957
+ labelField?: string;
958
+ /** For a link: the words when its row is hidden or gone (`ViewField.missingLabel`). */
959
+ missingLabel?: string;
960
+ /** An enum field's choices, in the contract's order, with the view's words. */
961
+ options?: readonly {
962
+ value: string;
963
+ label: string;
964
+ }[];
965
+ /** For a link the view opted in (`fields.<link>.link`, `editLinks`): how its picker lists the linked rows. */
966
+ link?: ResolvedLink;
967
+ /** The heading it sits under, or null for none. */
968
+ section: string | null;
969
+ sectionTitle: string | null;
970
+ visible?: (values: Readonly<Record<string, unknown>>) => boolean;
971
+ }
972
+ /** What `defineView` returns: frozen, with everything the renderers need resolved. */
973
+ interface ResourceView<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> {
974
+ readonly contract: C;
975
+ readonly definition: Readonly<ViewDefinition<C, Row>>;
976
+ /** The resource name the provider addresses. */
977
+ readonly resource: string;
978
+ readonly noun: string;
979
+ readonly nounPlural: string;
980
+ readonly title: string;
981
+ /** The field that names a row, for links, pickers and the peek's title. */
982
+ readonly labelField: string | undefined;
983
+ /** The column presets this view has, `default` first. */
984
+ readonly presets: readonly string[];
985
+ field(name: string): FieldSchema | undefined;
986
+ label(name: string): string;
987
+ display(name: string): DisplayHint;
988
+ /** A value in words: the field's `labels`, else title case. For badges, choices and group titles. */
989
+ valueLabel(name: string, value: unknown): string;
990
+ columns(preset?: string): readonly ResolvedColumn<Row>[];
991
+ /**
992
+ * One field as a column, resolved as a preset lists it (a board card's fields, say). Undefined
993
+ * for a name that isn't a field or one the viewer can't read (`permissions.read: false`).
994
+ */
995
+ column(name: string): ResolvedColumn<Row> | undefined;
996
+ form(mode: "create" | "edit"): readonly ResolvedFormField[];
997
+ /** Fields a writer may send: the form's, never generated, read-only, key or scope fields. */
998
+ writable(mode: "create" | "edit"): readonly string[];
999
+ /**
1000
+ * Whether the view's guard allows it for this viewer: `true`, or the guard's reason. Without a
1001
+ * viewer, guards get `NO_VIEWER` (no one), so one that needs the viewer refuses.
1002
+ */
1003
+ can(action: "create", viewer?: Viewer): Allowed;
1004
+ can(action: "update" | "delete", row: Row, viewer?: Viewer): Allowed;
1005
+ /** The view's actions, in order, frozen. */
1006
+ actions(): readonly ResolvedViewAction[];
1007
+ /**
1008
+ * Whether this row allows the named action: `true`, or the guard's reason. Only narrows what the
1009
+ * server allows. Throws {@link ViewDefinitionError} for a name the view doesn't define.
1010
+ */
1011
+ canAction(name: string, row: Row, viewer?: Viewer): Allowed;
1012
+ summary(row: Row): RowSummary;
1013
+ /**
1014
+ * The row as a gallery photo, by the view's `gallery` block and any `override` a screen passes
1015
+ * (ResourceView's `gallery`): undefined without a gallery block. Its `id` is the row's key, its
1016
+ * `alt` the row's label unless the block names a field; a row without an image has an empty `src`,
1017
+ * which GalleryGrid and NativeGalleryGrid draw as a placeholder tile; leave those out of a Lightbox.
1018
+ */
1019
+ galleryItem(row: Row, override?: Partial<ViewGallery>): GalleryItem | undefined;
1020
+ /** The declared filters, resolved (ADR 0017). Empty without `filters`. @stability Beta */
1021
+ filters(): readonly ResolvedFilter[];
1022
+ /** The declared segments, resolved. Empty without `segments`. @stability Beta */
1023
+ segments(): readonly ResolvedSegment[];
1024
+ /**
1025
+ * A segment's rows as provider filters, for this viewer. Throws {@link ViewDefinitionError} for
1026
+ * an id the view doesn't define. @stability Beta
1027
+ */
1028
+ segmentFilters(id: string, viewer?: Viewer): FilterParam[];
1029
+ /**
1030
+ * Declared filters' values as provider filters. Only declared filters count, and a value a
1031
+ * filter doesn't accept (a choice it doesn't offer, a malformed range) is dropped: the URL is
1032
+ * an allow-list, never a way to send any field. Days and times on a timestamp column are read
1033
+ * on `zone`'s clock (the viewer's; default the device's): a day runs from its start to the next
1034
+ * day's start, and a time with no offset is that zone's. @stability Beta
1035
+ */
1036
+ filterParams(values: Readonly<Record<string, ViewFilterValue | undefined>> | null | undefined, zone?: string): FilterParam[];
1037
+ /** The view types a person may switch between, in order (`types`, or the derived default). @stability Beta */
1038
+ types(): readonly string[];
1039
+ /** The row's tone (`rowTone`), or undefined. @stability Beta */
1040
+ rowTone(row: Row): ViewTone | undefined;
1041
+ /**
1042
+ * What "Export CSV" writes for a column preset, or undefined when the view has no `export`.
1043
+ * @stability Beta
1044
+ */
1045
+ exportPlan(preset?: string): {
1046
+ readonly columns: readonly ResolvedColumn<Row>[];
1047
+ readonly filename: string;
1048
+ readonly maxRows: number;
1049
+ readonly raw: boolean;
1050
+ } | undefined;
1051
+ /**
1052
+ * The row as an inbox draws it, by the view's `inbox` block (its title from `labelField` when
1053
+ * the block says none). Works without a block too: the summary's title. @stability Beta
1054
+ */
1055
+ inboxRow(row: Row): InboxRow;
1056
+ /** The inbox's `done` and `markRead` actions, when the view declares them. @stability Beta */
1057
+ inboxActions(): {
1058
+ readonly done?: string;
1059
+ readonly markRead?: string;
1060
+ };
1061
+ }
1062
+
1063
+ export { type ViewColumn as $, type Allowed as A, type BulkTarget as B, type ComputedColumn as C, type DisplayHint as D, type RecordViewSection as E, type FieldNameOf as F, type RecordViewSettingsSection as G, type RecordViewSlotSection as H, type InboxRow as I, type ResolvedColumn as J, type ResolvedFormField as K, type LinkFilter as L, type ResolvedLink as M, type ResolvedReadinessItem as N, type ResolvedRecordViewSection as O, type ResolvedSegment as P, type ResolvedViewAction as Q, type ResourceView as R, type SegmentWhere as S, type ResourceWorkspace as T, type RowImage as U, type ViewBoard as V, type TimeZoneName as W, type ViewAction as X, type ViewBreakpoint as Y, type ViewBulkAction as Z, type ViewCalendarLayout as _, type ViewTone as a, type ViewCopy as a0, type ViewEmphasis as a1, type ViewExport as a2, type ViewField as a3, type ViewFilter as a4, type ViewFormItem as a5, type ViewGuards as a6, type ViewLink as a7, type ViewPreset as a8, type ViewSegment as a9, type ViewTimeZone as aa, type ViewTotal as ab, type WorkspaceDefinition as ac, type WorkspaceHeaderAction as ad, type WorkspaceSection as ae, defineRecordView as af, defineWorkspace as ag, isRecordView as ah, isWorkspace as ai, sameFormValue as aj, type ViewFilterValue as b, type ViewFilterKind as c, type ResolvedFilter as d, type ViewCalendar as e, type ViewDefinition as f, type ViewGallery as g, type ViewInbox as h, type RowSummary as i, type RowPicture as j, type ViewCalendarDurationUnit as k, type AnyRecordView as l, type LinkOrder as m, type LinkedView as n, RECORD_OPEN_MODES as o, type RecordOpen as p, type RecordPageTemplate as q, type RecordView as r, type RecordViewDefinition as s, type RecordViewDocument as t, type RecordViewFilter as u, type RecordViewHeader as v, type RecordViewHeaderAction as w, type RecordViewHeaderOptions as x, type RecordViewListSection as y, type RecordViewReadinessItem as z };