@marktiderman/genesis-core 1.12.0 → 1.14.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.
- package/README.md +77 -0
- package/dist/chunk-3B4IFDMK.js +117 -0
- package/dist/chunk-3B4IFDMK.js.map +1 -0
- package/dist/{chunk-S2ZXUNXB.js → chunk-3LZAZ5KB.js} +3 -3
- package/dist/{chunk-S2ZXUNXB.js.map → chunk-3LZAZ5KB.js.map} +1 -1
- package/dist/chunk-7FVTGKTX.js +8 -0
- package/dist/chunk-7FVTGKTX.js.map +1 -0
- package/dist/{chunk-NMFABW4Y.js → chunk-7YHGNPPO.js} +5 -5
- package/dist/{chunk-NMFABW4Y.js.map → chunk-7YHGNPPO.js.map} +1 -1
- package/dist/chunk-AUVKRXRC.js +81 -0
- package/dist/chunk-AUVKRXRC.js.map +1 -0
- package/dist/{chunk-TOU2CMDH.js → chunk-K7K6NY3C.js} +168 -168
- package/dist/chunk-K7K6NY3C.js.map +1 -0
- package/dist/chunk-LFWSTJWI.js +108 -0
- package/dist/chunk-LFWSTJWI.js.map +1 -0
- package/dist/{chunk-RCAP3Q4T.js → chunk-OYIUIW7C.js} +3 -2
- package/dist/chunk-OYIUIW7C.js.map +1 -0
- package/dist/chunk-OZYF55E3.js +6 -0
- package/dist/chunk-OZYF55E3.js.map +1 -0
- package/dist/chunk-PA6WJE5E.js +115 -0
- package/dist/chunk-PA6WJE5E.js.map +1 -0
- package/dist/chunk-PP3XFFQM.js +85 -0
- package/dist/chunk-PP3XFFQM.js.map +1 -0
- package/dist/{chunk-BGTXN2E6.js → chunk-RF6YVWHX.js} +4 -4
- package/dist/{chunk-BGTXN2E6.js.map → chunk-RF6YVWHX.js.map} +1 -1
- package/dist/{chunk-NZPJI7FC.js → chunk-UGGMJUFQ.js} +45 -13
- package/dist/chunk-UGGMJUFQ.js.map +1 -0
- package/dist/{chunk-KXVHDK3Q.js → chunk-UV3ROHQA.js} +27 -5
- package/dist/chunk-UV3ROHQA.js.map +1 -0
- package/dist/chunk-YDDPFSQ6.js +35 -0
- package/dist/chunk-YDDPFSQ6.js.map +1 -0
- package/dist/{chunk-OSPLIKSH.js → chunk-YFTGLQDQ.js} +18 -8
- package/dist/chunk-YFTGLQDQ.js.map +1 -0
- package/dist/chunk-ZIMQUFXD.js +154 -0
- package/dist/chunk-ZIMQUFXD.js.map +1 -0
- package/dist/csv.d.ts +41 -0
- package/dist/csv.js +77 -0
- package/dist/csv.js.map +1 -0
- package/dist/dates.js +1 -115
- package/dist/dates.js.map +1 -1
- package/dist/errors.d.ts +69 -0
- package/dist/errors.js +7 -0
- package/dist/errors.js.map +1 -0
- package/dist/hooks/index.d.ts +7 -43
- package/dist/hooks/index.js +14 -11
- package/dist/hooks/live-cache.d.ts +15 -0
- package/dist/hooks/live-cache.js +3 -0
- package/dist/hooks/live-cache.js.map +1 -0
- package/dist/hooks/mutation-mode.d.ts +2 -2
- package/dist/hooks/mutation-mode.js +2 -2
- package/dist/hooks/related-keys.d.ts +2 -2
- package/dist/hooks/use-capabilities.d.ts +1 -1
- package/dist/hooks/use-infinite-resource.d.ts +18 -2
- package/dist/hooks/use-infinite-resource.js +4 -3
- package/dist/hooks/use-live.d.ts +15 -3
- package/dist/hooks/use-live.js +2 -1
- package/dist/hooks/use-one.d.ts +2 -2
- package/dist/hooks/use-one.js +4 -3
- package/dist/hooks/use-resource-form.d.ts +9 -2
- package/dist/hooks/use-resource-form.js +6 -5
- package/dist/hooks/use-resource.d.ts +2 -2
- package/dist/hooks/use-resource.js +5 -4
- package/dist/hooks/use-write.d.ts +2 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +21 -14
- package/dist/provider/index.d.ts +11 -6
- package/dist/provider/index.js +3 -2
- package/dist/resource/index.d.ts +39 -0
- package/dist/resource/index.js +3 -0
- package/dist/resource/index.js.map +1 -0
- package/dist/resource-view/index.d.ts +468 -0
- package/dist/resource-view/index.js +542 -0
- package/dist/resource-view/index.js.map +1 -0
- package/dist/schema/index.d.ts +4 -4
- package/dist/schema/index.js +1 -0
- package/dist/status-BXRokZD9.d.ts +50 -0
- package/dist/testing/index.d.ts +3 -3
- package/dist/{types-B9DDfvWa.d.ts → types-CXhqXPN1.d.ts} +21 -4
- package/dist/{types-C7FJtFXV.d.ts → types-o8j7g6O6.d.ts} +38 -1
- package/dist/urls.d.ts +18 -0
- package/dist/urls.js +3 -0
- package/dist/urls.js.map +1 -0
- package/dist/viewer-scope-77MqxvmZ.d.ts +125 -0
- package/dist/{write-outcome-B2fE29yZ.d.ts → write-outcome-CFnpciUI.d.ts} +1 -1
- package/package.json +21 -1
- package/dist/chunk-5ORRAXIV.js +0 -30
- package/dist/chunk-5ORRAXIV.js.map +0 -1
- package/dist/chunk-KXVHDK3Q.js.map +0 -1
- package/dist/chunk-NZPJI7FC.js.map +0 -1
- package/dist/chunk-OSPLIKSH.js.map +0 -1
- package/dist/chunk-RCAP3Q4T.js.map +0 -1
- package/dist/chunk-TOU2CMDH.js.map +0 -1
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
export { C as ChipTone, R as Readiness, a as ReadinessFinding, b as ReadinessLabels, c as ReadinessOptions, S as SAVE_STATE_LABEL, d as SaveState, r as readinessChip, e as readinessOf } from '../status-BXRokZD9.js';
|
|
2
|
+
|
|
3
|
+
/** A day (YYYY-MM-DD) in words, given today on the same clock: "Today", "Yesterday", "Oct 21", "Oct 21, 2025". */
|
|
4
|
+
declare function dayLabel(day: string, today?: string): string;
|
|
5
|
+
|
|
6
|
+
/** One search param a prefilled link may set, and the values staff pick from. */
|
|
7
|
+
interface PrefillChoice {
|
|
8
|
+
key: string;
|
|
9
|
+
/** The picker's accessible name, e.g. "Location". */
|
|
10
|
+
label: string;
|
|
11
|
+
/** The picker's "leave it out" choice, e.g. "Any location". */
|
|
12
|
+
anyLabel: string;
|
|
13
|
+
options: readonly {
|
|
14
|
+
value: string;
|
|
15
|
+
label: string;
|
|
16
|
+
}[];
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* `url` with `values` set as search params (empty values left out), keeping what it has.
|
|
20
|
+
* An absolute link stays absolute; a relative one (`/f/a?x=1`) stays relative, so it never
|
|
21
|
+
* throws while a page is still working out its origin.
|
|
22
|
+
*/
|
|
23
|
+
declare function prefilledUrl(url: string, values: Record<string, string | undefined>): string;
|
|
24
|
+
/** An `<iframe>` that shows the page on another website, full width. */
|
|
25
|
+
declare function embedSnippet(url: string, title: string): string;
|
|
26
|
+
|
|
27
|
+
/** The colour of a headline number's detail: good news, bad news, a warning, or plain. */
|
|
28
|
+
type HeadlineTone = "positive" | "negative" | "warning" | "muted";
|
|
29
|
+
/** One headline number, as data: a label, the number, and a short line under it. */
|
|
30
|
+
interface HeadlineNumber {
|
|
31
|
+
key: string;
|
|
32
|
+
label: string;
|
|
33
|
+
value: string | number;
|
|
34
|
+
detail?: string | undefined;
|
|
35
|
+
/** The detail's colour. Default plain. */
|
|
36
|
+
tone?: HeadlineTone | undefined;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export { type HeadlineNumber, type HeadlineTone, type PrefillChoice, dayLabel, embedSnippet, prefilledUrl };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
|
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
import { D as DataRow, e as ResourceContract, F as FieldSchema, i as RowAction, j as RowOf } from '../types-o8j7g6O6.js';
|
|
2
|
+
import { C as ChipTone, R as Readiness } from '../status-BXRokZD9.js';
|
|
3
|
+
import { V as Viewer, R as ResourceScope } from '../viewer-scope-77MqxvmZ.js';
|
|
4
|
+
export { G as GenesisViewerRoles, N as NO_VIEWER } from '../viewer-scope-77MqxvmZ.js';
|
|
5
|
+
import { a as Identifier } from '../types-CXhqXPN1.js';
|
|
6
|
+
import '../form-types.js';
|
|
7
|
+
import 'react';
|
|
8
|
+
import '@tanstack/react-query';
|
|
9
|
+
import '../dates.js';
|
|
10
|
+
|
|
11
|
+
/** A chip's colour: the one Genesis tone set (`ChipTone`, genesis-core/resource). */
|
|
12
|
+
type ViewTone = ChipTone;
|
|
13
|
+
/**
|
|
14
|
+
* How a value is shown. A hint: each platform registers one renderer per hint, so the shared view
|
|
15
|
+
* never imports a platform. Derived from the field when the view doesn't say.
|
|
16
|
+
*/
|
|
17
|
+
type DisplayHint = "text" | "longText" | "number" | "currency" | "percent" | "boolean" | "badge" | "date" | "datetime" | "relation" | "url" | "email" | "image" | "json";
|
|
18
|
+
/** The field names a contract declares; `string` when the contract isn't a literal. */
|
|
19
|
+
type FieldNameOf<C extends ResourceContract> = C["fields"][number]["name"];
|
|
20
|
+
/** What a view says about one field. Every key is optional; the contract fills the rest. */
|
|
21
|
+
interface ViewField<Row extends DataRow = DataRow> {
|
|
22
|
+
/** The field's label. Default: the contract's label, then the name in title case. */
|
|
23
|
+
label?: string;
|
|
24
|
+
display?: DisplayHint;
|
|
25
|
+
/** A badge's tone per value, e.g. `{ active: "success", archived: "muted" }`. */
|
|
26
|
+
tones?: Readonly<Record<string, ViewTone>>;
|
|
27
|
+
/** Longest text a form accepts. Feeds the derived validation. */
|
|
28
|
+
max?: number;
|
|
29
|
+
/** Shown read-only even where the server would accept a write. Never widens. */
|
|
30
|
+
readOnly?: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Show the cell only when the row (and the viewer) say so: for values a server function masks
|
|
33
|
+
* by policy (`(row) => row.author_visible`). The masking itself is the server's. It hides
|
|
34
|
+
* table cells and the peek only: not workspace settings, an edit form's prefilled values, a
|
|
35
|
+
* view's `summary` or header, or sorting and searching on the column.
|
|
36
|
+
*/
|
|
37
|
+
when?: (row: Row, viewer: Viewer) => boolean;
|
|
38
|
+
/** In a form: show the field only while this holds for the form's values. A hidden field isn't saved. */
|
|
39
|
+
visible?: (values: Readonly<Record<string, unknown>>) => boolean;
|
|
40
|
+
/** A timestamp's clock: the viewer's (default), the practice's, or a fixed IANA zone. */
|
|
41
|
+
timeZone?: "viewer" | "practice" | (string & {});
|
|
42
|
+
}
|
|
43
|
+
/** A column computed from the row, never stored or sent. */
|
|
44
|
+
interface ComputedColumn<Row extends DataRow = DataRow> {
|
|
45
|
+
/** The column's key; must not clash with a field name. */
|
|
46
|
+
key: string;
|
|
47
|
+
label: string;
|
|
48
|
+
value: (row: Row) => unknown;
|
|
49
|
+
display?: DisplayHint;
|
|
50
|
+
}
|
|
51
|
+
/** One entry in a column list: a field by name, or a computed column. */
|
|
52
|
+
type ViewColumn<Name extends string, Row extends DataRow> = Name | ComputedColumn<Row>;
|
|
53
|
+
/** A form laid out in order: fields, and fields under a heading. */
|
|
54
|
+
type ViewFormItem<Name extends string> = Name | {
|
|
55
|
+
section: string;
|
|
56
|
+
title?: string;
|
|
57
|
+
fields: readonly Name[];
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* A named tab of the list: which columns, and which rows (`{ status: "open" }` is an equality
|
|
61
|
+
* filter, sent to the server, never applied to loaded rows).
|
|
62
|
+
*/
|
|
63
|
+
interface ViewPreset<Name extends string> {
|
|
64
|
+
label?: string;
|
|
65
|
+
columns?: string;
|
|
66
|
+
filter?: Readonly<Partial<Record<Name, string | number | boolean | null>>>;
|
|
67
|
+
}
|
|
68
|
+
/** `true` when allowed, or the reason it isn't, in one sentence for the disabled control. */
|
|
69
|
+
type Allowed = true | string;
|
|
70
|
+
/**
|
|
71
|
+
* Row rules the server can't cheaply express ("the default brand can't be deleted"). They only
|
|
72
|
+
* narrow: the effective right is the server's AND these. An invariant goes in the database too.
|
|
73
|
+
*
|
|
74
|
+
* Each gets the viewer (`useViewer()`: id, scope, roles). Outside a ViewerScope it is
|
|
75
|
+
* `{ id: null, scope: {} }`, so a guard that needs it refuses with its reason. Pure and
|
|
76
|
+
* synchronous; never a security check (row-level security is the boundary).
|
|
77
|
+
*/
|
|
78
|
+
interface ViewGuards<Row extends DataRow> {
|
|
79
|
+
create?: (viewer: Viewer) => Allowed;
|
|
80
|
+
update?: (row: Row, viewer: Viewer) => Allowed;
|
|
81
|
+
delete?: (row: Row, viewer: Viewer) => Allowed;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* A named operation on one row, shaped like core's {@link RowAction} (which a provider reports),
|
|
85
|
+
* plus a guard. The guard only narrows: the server still decides whether the action runs.
|
|
86
|
+
*
|
|
87
|
+
* ```ts
|
|
88
|
+
* actions: [{ name: "archive", label: "Archive", confirm: "Archive this brand?", can: (r) => (r.is_default ? "The default brand stays." : true) }]
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
91
|
+
interface ViewAction<Row extends DataRow = DataRow> extends RowAction {
|
|
92
|
+
/** Drawn as destructive (red, the menu's destructive style). */
|
|
93
|
+
destructive?: boolean;
|
|
94
|
+
can?: (row: Row, viewer: Viewer) => Allowed;
|
|
95
|
+
}
|
|
96
|
+
/** An action as a renderer lists it: the words only. Ask `view.canAction` whether a row allows it. */
|
|
97
|
+
type ResolvedViewAction = RowAction & {
|
|
98
|
+
readonly destructive?: boolean;
|
|
99
|
+
};
|
|
100
|
+
/** A row in one line, for pickers, notifications and page bars. */
|
|
101
|
+
interface RowSummary {
|
|
102
|
+
title: string;
|
|
103
|
+
subtitle?: string;
|
|
104
|
+
chips?: readonly {
|
|
105
|
+
label: string;
|
|
106
|
+
tone?: ViewTone;
|
|
107
|
+
}[];
|
|
108
|
+
/**
|
|
109
|
+
* A picture beside the row: `src` is shown only when `isSafeUrl` accepts it; otherwise the
|
|
110
|
+
* initials of `name`. `alt` defaults to empty (decorative). Resolve it with `rowPicture`.
|
|
111
|
+
*/
|
|
112
|
+
image?: RowImage;
|
|
113
|
+
}
|
|
114
|
+
/** A row's picture, as a view's `summary` gives it. */
|
|
115
|
+
interface RowImage {
|
|
116
|
+
src?: string;
|
|
117
|
+
/** Whose picture: the initials come from it when there is no safe `src`. */
|
|
118
|
+
name?: string;
|
|
119
|
+
/** Alternative text. Default empty: the picture is decorative (the row's title names it). */
|
|
120
|
+
alt?: string;
|
|
121
|
+
}
|
|
122
|
+
/** A row's picture, ready to draw: an image (with initials for when it fails to load), or initials. */
|
|
123
|
+
type RowPicture = {
|
|
124
|
+
readonly kind: "image";
|
|
125
|
+
readonly src: string;
|
|
126
|
+
readonly alt: string;
|
|
127
|
+
readonly fallback: string;
|
|
128
|
+
} | {
|
|
129
|
+
readonly kind: "initials";
|
|
130
|
+
readonly text: string;
|
|
131
|
+
};
|
|
132
|
+
/** The words a view shows. Each defaults from the contract (`noun`, labels). */
|
|
133
|
+
interface ViewCopy {
|
|
134
|
+
/** One row, in a sentence: "brand". */
|
|
135
|
+
noun?: string;
|
|
136
|
+
/** Several: "brands". Default `noun` + "s". */
|
|
137
|
+
nounPlural?: string;
|
|
138
|
+
/** The page title. Default: the contract's label, then the plural noun in title case. */
|
|
139
|
+
title?: string;
|
|
140
|
+
subtitle?: string;
|
|
141
|
+
empty?: {
|
|
142
|
+
title?: string;
|
|
143
|
+
body?: string;
|
|
144
|
+
};
|
|
145
|
+
create?: string;
|
|
146
|
+
}
|
|
147
|
+
/** What `defineView` accepts. */
|
|
148
|
+
interface ViewDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> {
|
|
149
|
+
copy?: ViewCopy;
|
|
150
|
+
fields?: {
|
|
151
|
+
readonly [K in FieldNameOf<C>]?: ViewField<Row>;
|
|
152
|
+
};
|
|
153
|
+
/**
|
|
154
|
+
* Column lists by preset name. `default` is the full list; others (`compact`) are what a screen
|
|
155
|
+
* picks. Without `default`: every field that isn't sensitive, generated-only or the key.
|
|
156
|
+
*/
|
|
157
|
+
columns?: {
|
|
158
|
+
readonly default?: readonly ViewColumn<FieldNameOf<C>, Row>[];
|
|
159
|
+
} & {
|
|
160
|
+
readonly [preset: string]: readonly ViewColumn<FieldNameOf<C>, Row>[] | undefined;
|
|
161
|
+
};
|
|
162
|
+
/** Tabs: columns plus filters. */
|
|
163
|
+
presets?: Readonly<Record<string, ViewPreset<FieldNameOf<C>>>>;
|
|
164
|
+
/** The record form. Default: every writable field, in contract order. */
|
|
165
|
+
form?: readonly ViewFormItem<FieldNameOf<C>>[];
|
|
166
|
+
can?: ViewGuards<Row>;
|
|
167
|
+
/** Named operations on one row, in the order a menu shows them. Names are unique. */
|
|
168
|
+
actions?: readonly ViewAction<Row>[];
|
|
169
|
+
summary?: (row: Row) => RowSummary;
|
|
170
|
+
/** The scope keys this view needs above it (`["practice_id"]`). They stay out of forms. */
|
|
171
|
+
scope?: readonly FieldNameOf<C>[];
|
|
172
|
+
/** Group rows under headers by this field. */
|
|
173
|
+
groupBy?: FieldNameOf<C>;
|
|
174
|
+
/** Default order; `manual: true` turns on drag to reorder, writing this field. */
|
|
175
|
+
orderBy?: {
|
|
176
|
+
field: FieldNameOf<C>;
|
|
177
|
+
direction?: "asc" | "desc";
|
|
178
|
+
manual?: boolean;
|
|
179
|
+
};
|
|
180
|
+
/** Bumped when stored preferences (saved views, column order) change shape. */
|
|
181
|
+
version?: number;
|
|
182
|
+
}
|
|
183
|
+
/** A column as a renderer draws it: everything resolved. */
|
|
184
|
+
interface ResolvedColumn<Row extends DataRow = DataRow> {
|
|
185
|
+
key: string;
|
|
186
|
+
label: string;
|
|
187
|
+
display: DisplayHint;
|
|
188
|
+
/** The field behind it; absent for a computed column. */
|
|
189
|
+
field?: FieldSchema;
|
|
190
|
+
value: (row: Row) => unknown;
|
|
191
|
+
tones?: Readonly<Record<string, ViewTone>>;
|
|
192
|
+
/** Whether to show the cell. Without a viewer it answers for no one (fail closed). */
|
|
193
|
+
when?: (row: Row, viewer?: Viewer) => boolean;
|
|
194
|
+
timeZone?: ViewField["timeZone"];
|
|
195
|
+
}
|
|
196
|
+
/** A form field as a renderer draws it. */
|
|
197
|
+
interface ResolvedFormField {
|
|
198
|
+
field: FieldSchema;
|
|
199
|
+
label: string;
|
|
200
|
+
display: DisplayHint;
|
|
201
|
+
required: boolean;
|
|
202
|
+
readOnly: boolean;
|
|
203
|
+
max?: number;
|
|
204
|
+
/** The heading it sits under, or null for none. */
|
|
205
|
+
section: string | null;
|
|
206
|
+
sectionTitle: string | null;
|
|
207
|
+
visible?: (values: Readonly<Record<string, unknown>>) => boolean;
|
|
208
|
+
}
|
|
209
|
+
/** What `defineView` returns: frozen, with everything the renderers need resolved. */
|
|
210
|
+
interface ResourceView<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> {
|
|
211
|
+
readonly contract: C;
|
|
212
|
+
readonly definition: Readonly<ViewDefinition<C, Row>>;
|
|
213
|
+
/** The resource name the provider addresses. */
|
|
214
|
+
readonly resource: string;
|
|
215
|
+
readonly noun: string;
|
|
216
|
+
readonly nounPlural: string;
|
|
217
|
+
readonly title: string;
|
|
218
|
+
/** The field that names a row, for links, pickers and the peek's title. */
|
|
219
|
+
readonly labelField: string | undefined;
|
|
220
|
+
/** The column presets this view has, `default` first. */
|
|
221
|
+
readonly presets: readonly string[];
|
|
222
|
+
field(name: string): FieldSchema | undefined;
|
|
223
|
+
label(name: string): string;
|
|
224
|
+
display(name: string): DisplayHint;
|
|
225
|
+
columns(preset?: string): readonly ResolvedColumn<Row>[];
|
|
226
|
+
form(mode: "create" | "edit"): readonly ResolvedFormField[];
|
|
227
|
+
/** Fields a writer may send: the form's, never generated, read-only, key or scope fields. */
|
|
228
|
+
writable(mode: "create" | "edit"): readonly string[];
|
|
229
|
+
/**
|
|
230
|
+
* Whether the view's guard allows it for this viewer: `true`, or the guard's reason. Without a
|
|
231
|
+
* viewer, guards get `NO_VIEWER` (no one), so one that needs the viewer refuses.
|
|
232
|
+
*/
|
|
233
|
+
can(action: "create", viewer?: Viewer): Allowed;
|
|
234
|
+
can(action: "update" | "delete", row: Row, viewer?: Viewer): Allowed;
|
|
235
|
+
/** The view's actions, in order, frozen. */
|
|
236
|
+
actions(): readonly ResolvedViewAction[];
|
|
237
|
+
/**
|
|
238
|
+
* Whether this row allows the named action: `true`, or the guard's reason. Only narrows what the
|
|
239
|
+
* server allows. Throws {@link ViewDefinitionError} for a name the view doesn't define.
|
|
240
|
+
*/
|
|
241
|
+
canAction(name: string, row: Row, viewer?: Viewer): Allowed;
|
|
242
|
+
summary(row: Row): RowSummary;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** A view that names a field, preset or section its contract doesn't have. */
|
|
246
|
+
declare class ViewDefinitionError extends Error {
|
|
247
|
+
readonly problems: readonly string[];
|
|
248
|
+
constructor(resource: string, problems: readonly string[]);
|
|
249
|
+
}
|
|
250
|
+
/** The display a field gets when the view doesn't name one. */
|
|
251
|
+
declare function deriveDisplay(field: FieldSchema): DisplayHint;
|
|
252
|
+
/**
|
|
253
|
+
* Describe what a resource means to people. The result is frozen and platform-neutral:
|
|
254
|
+
*
|
|
255
|
+
* ```ts
|
|
256
|
+
* export const brandsView = defineView(contracts["public.brands"], {
|
|
257
|
+
* fields: { status: { display: "badge", tones: { active: "success" } } },
|
|
258
|
+
* columns: { default: ["name", "status", "created_at"], compact: ["name"] },
|
|
259
|
+
* can: {
|
|
260
|
+
* delete: (row) => (row.is_default ? "The default brand stays." : true),
|
|
261
|
+
* update: (row, viewer) => (row.owner_id === viewer.id ? true : "Only its owner edits a brand."),
|
|
262
|
+
* },
|
|
263
|
+
* actions: [{ name: "archive", label: "Archive", can: (row) => (row.is_default ? "The default brand stays." : true) }],
|
|
264
|
+
* });
|
|
265
|
+
* ```
|
|
266
|
+
*
|
|
267
|
+
* Throws {@link ViewDefinitionError} when it names something the contract doesn't have, so a
|
|
268
|
+
* renamed column fails at start-up, not as a blank cell.
|
|
269
|
+
*/
|
|
270
|
+
declare function defineView<C extends ResourceContract, Row extends DataRow = RowOf<C>>(contract: C, definition?: ViewDefinition<C, Row>): ResourceView<C, Row>;
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* First and last initial of a name, from letters only: "Ada Lovelace" → "AL", "Ana-María López"
|
|
274
|
+
* → "AL", "李 小龙" → "李小", "Cher" → "C". Empty when the name has no letters (" ", "🎉🎉").
|
|
275
|
+
*/
|
|
276
|
+
declare function initialsOf(name: string | undefined): string;
|
|
277
|
+
/**
|
|
278
|
+
* What to draw for a summary's picture:
|
|
279
|
+
*
|
|
280
|
+
* ```ts
|
|
281
|
+
* rowPicture({ title: "Ada", image: { src: "https://…/ada.png", name: "Ada Lovelace" } });
|
|
282
|
+
* // { kind: "image", src: "https://…/ada.png", alt: "", fallback: "AL" }
|
|
283
|
+
* rowPicture({ title: "Ada", image: { src: "javascript:x", name: "Ada Lovelace" } });
|
|
284
|
+
* // { kind: "initials", text: "AL" }
|
|
285
|
+
* ```
|
|
286
|
+
*
|
|
287
|
+
* `null` when the summary has no `image`, or neither a safe `src` nor a `name` with letters.
|
|
288
|
+
*/
|
|
289
|
+
declare function rowPicture(summary: RowSummary): RowPicture | null;
|
|
290
|
+
|
|
291
|
+
type ScopeValue = string | number | boolean | null;
|
|
292
|
+
/**
|
|
293
|
+
* The view's declared scope keys with their values from the viewer's scope, ready to pass as a
|
|
294
|
+
* screen's `filter`: `scope: ["practice_id"]` reads `scope.practice_id`, then `scope.practiceId`.
|
|
295
|
+
*
|
|
296
|
+
* ```tsx
|
|
297
|
+
* <ResourceView view={brandsView} filter={scopeValues(brandsView, useViewerScope().scope)} />
|
|
298
|
+
* ```
|
|
299
|
+
*
|
|
300
|
+
* In development a declared key with no single value (missing, `undefined`, or a list) throws
|
|
301
|
+
* {@link ViewDefinitionError}, so a screen mounted outside its scope fails loudly. In production
|
|
302
|
+
* it is left out; row-level security still decides what the viewer reads.
|
|
303
|
+
*/
|
|
304
|
+
declare function scopeValues(view: Pick<ResourceView<any, any>, "resource" | "definition">, scope: ResourceScope | null | undefined): Readonly<Record<string, ScopeValue>>;
|
|
305
|
+
|
|
306
|
+
type AnyView = ResourceView<ResourceContract<any>, any>;
|
|
307
|
+
/** Equality filters for a child list, sent to the server: `{ brand_id: brand.id }`. `null` is "is empty". */
|
|
308
|
+
type WorkspaceFilter = Readonly<Record<string, string | number | boolean | null>>;
|
|
309
|
+
interface SectionBase {
|
|
310
|
+
/** Unique in the workspace; the screen's route segment or slot key. */
|
|
311
|
+
id: string;
|
|
312
|
+
label: string;
|
|
313
|
+
}
|
|
314
|
+
/** A child list: another view, filtered by this record. */
|
|
315
|
+
interface WorkspaceListSection<Row extends DataRow = DataRow> extends SectionBase {
|
|
316
|
+
list: {
|
|
317
|
+
view: AnyView;
|
|
318
|
+
filter: (row: Row) => WorkspaceFilter;
|
|
319
|
+
};
|
|
320
|
+
settings?: never;
|
|
321
|
+
}
|
|
322
|
+
/** A few of this record's own fields, edited in place. Each must be in `view.writable("edit")`. */
|
|
323
|
+
interface WorkspaceSettingsSection<Name extends string = string> extends SectionBase {
|
|
324
|
+
settings: readonly Name[];
|
|
325
|
+
list?: never;
|
|
326
|
+
}
|
|
327
|
+
/** A section the screen fills itself, through a slot keyed by `id`. */
|
|
328
|
+
interface WorkspaceSlotSection extends SectionBase {
|
|
329
|
+
list?: never;
|
|
330
|
+
settings?: never;
|
|
331
|
+
}
|
|
332
|
+
type WorkspaceSection<Row extends DataRow = DataRow, Name extends string = string> = WorkspaceListSection<Row> | WorkspaceSettingsSection<Name> | WorkspaceSlotSection;
|
|
333
|
+
/** One readiness check: "Has a logo", ok or not, and why not. */
|
|
334
|
+
interface WorkspaceReadinessItem {
|
|
335
|
+
/** A stable key for the check; default its position and title. */
|
|
336
|
+
id?: string;
|
|
337
|
+
title: string;
|
|
338
|
+
ok: boolean;
|
|
339
|
+
reason?: string;
|
|
340
|
+
/** Genesis chip tones only. Default `success` when ok, `warning` when not. */
|
|
341
|
+
tone?: ViewTone;
|
|
342
|
+
}
|
|
343
|
+
/** What `defineWorkspace` accepts. */
|
|
344
|
+
interface WorkspaceDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> {
|
|
345
|
+
/** The view actions the header offers, by name, in order. Default: every view action. */
|
|
346
|
+
header?: {
|
|
347
|
+
actions?: readonly string[];
|
|
348
|
+
};
|
|
349
|
+
sections: readonly WorkspaceSection<Row, FieldNameOf<C>>[];
|
|
350
|
+
readiness?: (row: Row) => readonly WorkspaceReadinessItem[];
|
|
351
|
+
}
|
|
352
|
+
/** A section as a renderer draws it. */
|
|
353
|
+
type ResolvedWorkspaceSection = {
|
|
354
|
+
readonly id: string;
|
|
355
|
+
readonly label: string;
|
|
356
|
+
readonly kind: "list";
|
|
357
|
+
readonly view: AnyView;
|
|
358
|
+
} | {
|
|
359
|
+
readonly id: string;
|
|
360
|
+
readonly label: string;
|
|
361
|
+
readonly kind: "settings";
|
|
362
|
+
readonly settings: readonly string[];
|
|
363
|
+
} | {
|
|
364
|
+
readonly id: string;
|
|
365
|
+
readonly label: string;
|
|
366
|
+
readonly kind: "slot";
|
|
367
|
+
};
|
|
368
|
+
/** A header action with whether this row allows it. */
|
|
369
|
+
interface WorkspaceHeaderAction {
|
|
370
|
+
readonly name: string;
|
|
371
|
+
readonly label: string;
|
|
372
|
+
readonly confirm?: string;
|
|
373
|
+
readonly description?: string;
|
|
374
|
+
readonly destructive?: boolean;
|
|
375
|
+
/** `true`, or the view guard's reason. Only narrows what the server allows. */
|
|
376
|
+
readonly allowed: Allowed;
|
|
377
|
+
}
|
|
378
|
+
/** The header for one row: the view's summary plus the header's actions. */
|
|
379
|
+
interface WorkspaceHeader {
|
|
380
|
+
readonly title: string;
|
|
381
|
+
readonly subtitle?: string;
|
|
382
|
+
readonly chips: readonly {
|
|
383
|
+
label: string;
|
|
384
|
+
tone?: ViewTone;
|
|
385
|
+
}[];
|
|
386
|
+
readonly actions: readonly WorkspaceHeaderAction[];
|
|
387
|
+
}
|
|
388
|
+
/** What a screen and its provider add to the header: they only narrow the view's guards. */
|
|
389
|
+
interface WorkspaceHeaderOptions<Row extends DataRow = DataRow> {
|
|
390
|
+
/** The screen's own rule: `false` hides the action, a sentence refuses it with that reason. */
|
|
391
|
+
can?: (action: string, row: Row) => Allowed | boolean;
|
|
392
|
+
/** Whether anything can run actions here (the screen's `onAction`, or the provider's `runAction`). `false` hides them all. */
|
|
393
|
+
runnable?: boolean;
|
|
394
|
+
/** The action names the provider reports serving (`ResourceSchema.actions`), when it reports them. Others are hidden. */
|
|
395
|
+
served?: readonly string[];
|
|
396
|
+
/** Who is looking (`useViewer()`), for the view's action guards. Without it they get no one. */
|
|
397
|
+
viewer?: Viewer;
|
|
398
|
+
}
|
|
399
|
+
/** A readiness check with its tone resolved. */
|
|
400
|
+
interface ResolvedReadinessItem {
|
|
401
|
+
/** Stable, for list keys: the check's `id`, or its position and title. */
|
|
402
|
+
readonly key: string;
|
|
403
|
+
readonly title: string;
|
|
404
|
+
readonly ok: boolean;
|
|
405
|
+
readonly reason?: string;
|
|
406
|
+
readonly tone: ViewTone;
|
|
407
|
+
}
|
|
408
|
+
/** What `defineWorkspace` returns: frozen, with pure helpers for the renderers. */
|
|
409
|
+
interface ResourceWorkspace<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> {
|
|
410
|
+
readonly view: ResourceView<C, Row>;
|
|
411
|
+
readonly sections: readonly ResolvedWorkspaceSection[];
|
|
412
|
+
/** The header's action names, in order. */
|
|
413
|
+
readonly headerActions: readonly string[];
|
|
414
|
+
readonly hasReadiness: boolean;
|
|
415
|
+
section(id: string): ResolvedWorkspaceSection | undefined;
|
|
416
|
+
/** The record's address for the provider: its key fields (`keyFields`), composite keys encoded. */
|
|
417
|
+
recordId(row: Row): Identifier;
|
|
418
|
+
/**
|
|
419
|
+
* Why settings can't be saved for this row and viewer: the view's `can("update", row, viewer)`
|
|
420
|
+
* reason, or `null` when they can. Renderers then show the settings read-only with the reason.
|
|
421
|
+
* Without a viewer the guard gets no one, so one that needs the viewer locks them.
|
|
422
|
+
*/
|
|
423
|
+
settingsLocked(row: Row, viewer?: Viewer): string | null;
|
|
424
|
+
headerFor(row: Row, options?: WorkspaceHeaderOptions<Row>): WorkspaceHeader;
|
|
425
|
+
/**
|
|
426
|
+
* Settings fields as the view's form resolves them (`view.form("edit")`), in the order listed:
|
|
427
|
+
* one section's, or every settings section's without an id.
|
|
428
|
+
*/
|
|
429
|
+
settingsFields(sectionId?: string): readonly ResolvedFormField[];
|
|
430
|
+
/** Only the section's listed keys that `values` has: what a save sends. */
|
|
431
|
+
settingsPatch(sectionId: string, values: Readonly<Record<string, unknown>>): Record<string, unknown>;
|
|
432
|
+
/**
|
|
433
|
+
* A list section's filter for this row. In development, a filter with no key, or a value that
|
|
434
|
+
* isn't a string, number, boolean or null, throws: it would show every child row.
|
|
435
|
+
*/
|
|
436
|
+
listFilter(sectionId: string, row: Row): WorkspaceFilter;
|
|
437
|
+
/** The readiness checks for this row, tones resolved; empty without `readiness`. */
|
|
438
|
+
readinessFor(row: Row): readonly ResolvedReadinessItem[];
|
|
439
|
+
/**
|
|
440
|
+
* The checks in one chip's terms (genesis-core/resource's `readinessOf`): an unmet `danger`
|
|
441
|
+
* check is a problem, any other unmet check one to look at. `null` without `readiness`. Draw
|
|
442
|
+
* it with `readinessChip`.
|
|
443
|
+
*/
|
|
444
|
+
readinessSummary(row: Row): Readiness | null;
|
|
445
|
+
}
|
|
446
|
+
/** Whether a value is a workspace (`defineWorkspace`'s result). */
|
|
447
|
+
declare function isWorkspace(value: unknown): value is ResourceWorkspace;
|
|
448
|
+
/**
|
|
449
|
+
* One record's screen from its view:
|
|
450
|
+
*
|
|
451
|
+
* ```ts
|
|
452
|
+
* export const brandWorkspace = defineWorkspace(brandsView, {
|
|
453
|
+
* header: { actions: ["archive"] },
|
|
454
|
+
* sections: [
|
|
455
|
+
* { id: "products", label: "Products", list: { view: productsView, filter: (b) => ({ brand_id: b.id }) } },
|
|
456
|
+
* { id: "settings", label: "Settings", settings: ["name", "website"] },
|
|
457
|
+
* { id: "activity", label: "Activity" }, // the screen fills it
|
|
458
|
+
* ],
|
|
459
|
+
* readiness: (b) => [{ title: "Has a website", ok: !!b.website, reason: "Add the website." }],
|
|
460
|
+
* });
|
|
461
|
+
* ```
|
|
462
|
+
*
|
|
463
|
+
* Throws {@link ViewDefinitionError} for a settings field the view can't write, a header action
|
|
464
|
+
* the view doesn't define, a repeated section id, or a section that holds another workspace.
|
|
465
|
+
*/
|
|
466
|
+
declare function defineWorkspace<C extends ResourceContract, Row extends DataRow = RowOf<C>>(view: ResourceView<C, Row>, definition: WorkspaceDefinition<C, Row>): ResourceWorkspace<C, Row>;
|
|
467
|
+
|
|
468
|
+
export { type Allowed, type ComputedColumn, type DisplayHint, type FieldNameOf, type ResolvedColumn, type ResolvedFormField, type ResolvedReadinessItem, type ResolvedViewAction, type ResolvedWorkspaceSection, type ResourceView, type ResourceWorkspace, type RowImage, RowOf, type RowPicture, type RowSummary, type ViewAction, type ViewColumn, type ViewCopy, type ViewDefinition, ViewDefinitionError, type ViewField, type ViewFormItem, type ViewGuards, type ViewPreset, type ViewTone, Viewer, type WorkspaceDefinition, type WorkspaceFilter, type WorkspaceHeader, type WorkspaceHeaderAction, type WorkspaceHeaderOptions, type WorkspaceListSection, type WorkspaceReadinessItem, type WorkspaceSection, type WorkspaceSettingsSection, type WorkspaceSlotSection, defineView, defineWorkspace, deriveDisplay, initialsOf, isWorkspace, rowPicture, scopeValues };
|