@marktiderman/genesis-core 1.13.0 → 1.14.1

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 (42) hide show
  1. package/README.md +45 -0
  2. package/dist/{chunk-REYTMXAA.js → chunk-3LZAZ5KB.js} +3 -3
  3. package/dist/{chunk-REYTMXAA.js.map → chunk-3LZAZ5KB.js.map} +1 -1
  4. package/dist/chunk-4VRVVN2S.js +109 -0
  5. package/dist/chunk-4VRVVN2S.js.map +1 -0
  6. package/dist/{chunk-JKZ2FVWK.js → chunk-7YHGNPPO.js} +4 -4
  7. package/dist/{chunk-JKZ2FVWK.js.map → chunk-7YHGNPPO.js.map} +1 -1
  8. package/dist/{chunk-TCL27Q5W.js → chunk-K7K6NY3C.js} +4 -113
  9. package/dist/chunk-K7K6NY3C.js.map +1 -0
  10. package/dist/chunk-OZYF55E3.js +6 -0
  11. package/dist/chunk-OZYF55E3.js.map +1 -0
  12. package/dist/chunk-PA6WJE5E.js +115 -0
  13. package/dist/chunk-PA6WJE5E.js.map +1 -0
  14. package/dist/chunk-PP3XFFQM.js +85 -0
  15. package/dist/chunk-PP3XFFQM.js.map +1 -0
  16. package/dist/{chunk-GEF5W2LO.js → chunk-YFTGLQDQ.js} +4 -4
  17. package/dist/{chunk-GEF5W2LO.js.map → chunk-YFTGLQDQ.js.map} +1 -1
  18. package/dist/chunk-ZIMQUFXD.js +154 -0
  19. package/dist/chunk-ZIMQUFXD.js.map +1 -0
  20. package/dist/errors.d.ts +69 -0
  21. package/dist/errors.js +7 -0
  22. package/dist/errors.js.map +1 -0
  23. package/dist/hooks/index.d.ts +1 -1
  24. package/dist/hooks/index.js +15 -11
  25. package/dist/hooks/mutation-mode.js +2 -2
  26. package/dist/hooks/use-resource-form.js +6 -6
  27. package/dist/hooks/use-resource.js +4 -4
  28. package/dist/index.d.ts +2 -1
  29. package/dist/index.js +18 -15
  30. package/dist/provider/index.js +4 -3
  31. package/dist/resource/index.d.ts +2 -49
  32. package/dist/resource/index.js +1 -83
  33. package/dist/resource/index.js.map +1 -1
  34. package/dist/resource-view/index.d.ts +216 -17
  35. package/dist/resource-view/index.js +263 -13
  36. package/dist/resource-view/index.js.map +1 -1
  37. package/dist/status-BXRokZD9.d.ts +50 -0
  38. package/dist/{viewer-scope-0dR-_o0f.d.ts → viewer-scope-77MqxvmZ.d.ts} +51 -2
  39. package/package.json +5 -1
  40. package/dist/chunk-FARKPY6R.js +0 -66
  41. package/dist/chunk-FARKPY6R.js.map +0 -1
  42. package/dist/chunk-TCL27Q5W.js.map +0 -1
@@ -1,12 +1,15 @@
1
1
  import { D as DataRow, e as ResourceContract, F as FieldSchema, i as RowAction, j as RowOf } from '../types-o8j7g6O6.js';
2
- import { R as ResourceScope } from '../viewer-scope-0dR-_o0f.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';
3
6
  import '../form-types.js';
4
7
  import 'react';
5
8
  import '@tanstack/react-query';
6
9
  import '../dates.js';
7
10
 
8
- /** A chip's colour: the tinted, AA-safe Genesis badge tones (genesis-ui's `ChipTone`). */
9
- type ViewTone = "success" | "warning" | "danger" | "info" | "muted";
11
+ /** A chip's colour: the one Genesis tone set (`ChipTone`, genesis-core/resource). */
12
+ type ViewTone = ChipTone;
10
13
  /**
11
14
  * How a value is shown. A hint: each platform registers one renderer per hint, so the shared view
12
15
  * never imports a platform. Derived from the field when the view doesn't say.
@@ -21,15 +24,22 @@ interface ViewField<Row extends DataRow = DataRow> {
21
24
  display?: DisplayHint;
22
25
  /** A badge's tone per value, e.g. `{ active: "success", archived: "muted" }`. */
23
26
  tones?: Readonly<Record<string, ViewTone>>;
27
+ /**
28
+ * The words for a value, e.g. `{ draft: "In progress" }`: badges, form choices, group titles.
29
+ * A value without one shows in title case. Keys must be the field's enum values, if it has any.
30
+ */
31
+ labels?: Readonly<Record<string, string>>;
24
32
  /** Longest text a form accepts. Feeds the derived validation. */
25
33
  max?: number;
26
34
  /** Shown read-only even where the server would accept a write. Never widens. */
27
35
  readOnly?: boolean;
28
36
  /**
29
- * Show the cell only when the row says so: for values a server function masks by policy
30
- * (`(row) => row.author_visible`). The masking itself is the server's.
37
+ * Show the cell only when the row (and the viewer) say so: for values a server function masks
38
+ * by policy (`(row) => row.author_visible`). The masking itself is the server's. It hides
39
+ * table cells and the peek only: not workspace settings, an edit form's prefilled values, a
40
+ * view's `summary` or header, or sorting and searching on the column.
31
41
  */
32
- when?: (row: Row) => boolean;
42
+ when?: (row: Row, viewer: Viewer) => boolean;
33
43
  /** In a form: show the field only while this holds for the form's values. A hidden field isn't saved. */
34
44
  visible?: (values: Readonly<Record<string, unknown>>) => boolean;
35
45
  /** A timestamp's clock: the viewer's (default), the practice's, or a fixed IANA zone. */
@@ -65,11 +75,15 @@ type Allowed = true | string;
65
75
  /**
66
76
  * Row rules the server can't cheaply express ("the default brand can't be deleted"). They only
67
77
  * narrow: the effective right is the server's AND these. An invariant goes in the database too.
78
+ *
79
+ * Each gets the viewer (`useViewer()`: id, scope, roles). Outside a ViewerScope it is
80
+ * `{ id: null, scope: {} }`, so a guard that needs it refuses with its reason. Pure and
81
+ * synchronous; never a security check (row-level security is the boundary).
68
82
  */
69
83
  interface ViewGuards<Row extends DataRow> {
70
- create?: () => Allowed;
71
- update?: (row: Row) => Allowed;
72
- delete?: (row: Row) => Allowed;
84
+ create?: (viewer: Viewer) => Allowed;
85
+ update?: (row: Row, viewer: Viewer) => Allowed;
86
+ delete?: (row: Row, viewer: Viewer) => Allowed;
73
87
  }
74
88
  /**
75
89
  * A named operation on one row, shaped like core's {@link RowAction} (which a provider reports),
@@ -80,10 +94,14 @@ interface ViewGuards<Row extends DataRow> {
80
94
  * ```
81
95
  */
82
96
  interface ViewAction<Row extends DataRow = DataRow> extends RowAction {
83
- can?: (row: Row) => Allowed;
97
+ /** Drawn as destructive (red, the menu's destructive style). */
98
+ destructive?: boolean;
99
+ can?: (row: Row, viewer: Viewer) => Allowed;
84
100
  }
85
101
  /** An action as a renderer lists it: the words only. Ask `view.canAction` whether a row allows it. */
86
- type ResolvedViewAction = RowAction;
102
+ type ResolvedViewAction = RowAction & {
103
+ readonly destructive?: boolean;
104
+ };
87
105
  /** A row in one line, for pickers, notifications and page bars. */
88
106
  interface RowSummary {
89
107
  title: string;
@@ -176,7 +194,10 @@ interface ResolvedColumn<Row extends DataRow = DataRow> {
176
194
  field?: FieldSchema;
177
195
  value: (row: Row) => unknown;
178
196
  tones?: Readonly<Record<string, ViewTone>>;
179
- when?: (row: Row) => boolean;
197
+ /** The words for a value (`ViewField.labels`); `valueText` reads them. */
198
+ labels?: Readonly<Record<string, string>>;
199
+ /** Whether to show the cell. Without a viewer it answers for no one (fail closed). */
200
+ when?: (row: Row, viewer?: Viewer) => boolean;
180
201
  timeZone?: ViewField["timeZone"];
181
202
  }
182
203
  /** A form field as a renderer draws it. */
@@ -187,6 +208,11 @@ interface ResolvedFormField {
187
208
  required: boolean;
188
209
  readOnly: boolean;
189
210
  max?: number;
211
+ /** An enum field's choices, in the contract's order, with the view's words. */
212
+ options?: readonly {
213
+ value: string;
214
+ label: string;
215
+ }[];
190
216
  /** The heading it sits under, or null for none. */
191
217
  section: string | null;
192
218
  sectionTitle: string | null;
@@ -208,19 +234,25 @@ interface ResourceView<C extends ResourceContract = ResourceContract, Row extend
208
234
  field(name: string): FieldSchema | undefined;
209
235
  label(name: string): string;
210
236
  display(name: string): DisplayHint;
237
+ /** A value in words: the field's `labels`, else title case. For badges, choices and group titles. */
238
+ valueLabel(name: string, value: unknown): string;
211
239
  columns(preset?: string): readonly ResolvedColumn<Row>[];
212
240
  form(mode: "create" | "edit"): readonly ResolvedFormField[];
213
241
  /** Fields a writer may send: the form's, never generated, read-only, key or scope fields. */
214
242
  writable(mode: "create" | "edit"): readonly string[];
215
- can(action: "create"): Allowed;
216
- can(action: "update" | "delete", row: Row): Allowed;
243
+ /**
244
+ * Whether the view's guard allows it for this viewer: `true`, or the guard's reason. Without a
245
+ * viewer, guards get `NO_VIEWER` (no one), so one that needs the viewer refuses.
246
+ */
247
+ can(action: "create", viewer?: Viewer): Allowed;
248
+ can(action: "update" | "delete", row: Row, viewer?: Viewer): Allowed;
217
249
  /** The view's actions, in order, frozen. */
218
250
  actions(): readonly ResolvedViewAction[];
219
251
  /**
220
252
  * Whether this row allows the named action: `true`, or the guard's reason. Only narrows what the
221
253
  * server allows. Throws {@link ViewDefinitionError} for a name the view doesn't define.
222
254
  */
223
- canAction(name: string, row: Row): Allowed;
255
+ canAction(name: string, row: Row, viewer?: Viewer): Allowed;
224
256
  summary(row: Row): RowSummary;
225
257
  }
226
258
 
@@ -231,6 +263,8 @@ declare class ViewDefinitionError extends Error {
231
263
  }
232
264
  /** The display a field gets when the view doesn't name one. */
233
265
  declare function deriveDisplay(field: FieldSchema): DisplayHint;
266
+ /** A value in words: its entry in `labels`, else the value in title case (`draft` → "Draft"). */
267
+ declare function valueText(labels: Readonly<Record<string, string>> | undefined, value: unknown): string;
234
268
  /**
235
269
  * Describe what a resource means to people. The result is frozen and platform-neutral:
236
270
  *
@@ -238,7 +272,10 @@ declare function deriveDisplay(field: FieldSchema): DisplayHint;
238
272
  * export const brandsView = defineView(contracts["public.brands"], {
239
273
  * fields: { status: { display: "badge", tones: { active: "success" } } },
240
274
  * columns: { default: ["name", "status", "created_at"], compact: ["name"] },
241
- * can: { delete: (row) => (row.is_default ? "The default brand stays." : true) },
275
+ * can: {
276
+ * delete: (row) => (row.is_default ? "The default brand stays." : true),
277
+ * update: (row, viewer) => (row.owner_id === viewer.id ? true : "Only its owner edits a brand."),
278
+ * },
242
279
  * actions: [{ name: "archive", label: "Archive", can: (row) => (row.is_default ? "The default brand stays." : true) }],
243
280
  * });
244
281
  * ```
@@ -282,4 +319,166 @@ type ScopeValue = string | number | boolean | null;
282
319
  */
283
320
  declare function scopeValues(view: Pick<ResourceView<any, any>, "resource" | "definition">, scope: ResourceScope | null | undefined): Readonly<Record<string, ScopeValue>>;
284
321
 
285
- export { type Allowed, type ComputedColumn, type DisplayHint, type FieldNameOf, type ResolvedColumn, type ResolvedFormField, type ResolvedViewAction, type ResourceView, 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, defineView, deriveDisplay, initialsOf, rowPicture, scopeValues };
322
+ type AnyView = ResourceView<ResourceContract<any>, any>;
323
+ /** Equality filters for a child list, sent to the server: `{ brand_id: brand.id }`. `null` is "is empty". */
324
+ type WorkspaceFilter = Readonly<Record<string, string | number | boolean | null>>;
325
+ interface SectionBase {
326
+ /** Unique in the workspace; the screen's route segment or slot key. */
327
+ id: string;
328
+ label: string;
329
+ }
330
+ /** A child list: another view, filtered by this record. */
331
+ interface WorkspaceListSection<Row extends DataRow = DataRow> extends SectionBase {
332
+ list: {
333
+ view: AnyView;
334
+ filter: (row: Row) => WorkspaceFilter;
335
+ };
336
+ settings?: never;
337
+ }
338
+ /** A few of this record's own fields, edited in place. Each must be in `view.writable("edit")`. */
339
+ interface WorkspaceSettingsSection<Name extends string = string> extends SectionBase {
340
+ settings: readonly Name[];
341
+ list?: never;
342
+ }
343
+ /** A section the screen fills itself, through a slot keyed by `id`. */
344
+ interface WorkspaceSlotSection extends SectionBase {
345
+ list?: never;
346
+ settings?: never;
347
+ }
348
+ type WorkspaceSection<Row extends DataRow = DataRow, Name extends string = string> = WorkspaceListSection<Row> | WorkspaceSettingsSection<Name> | WorkspaceSlotSection;
349
+ /** One readiness check: "Has a logo", ok or not, and why not. */
350
+ interface WorkspaceReadinessItem {
351
+ /** A stable key for the check; default its position and title. */
352
+ id?: string;
353
+ title: string;
354
+ ok: boolean;
355
+ reason?: string;
356
+ /** Genesis chip tones only. Default `success` when ok, `warning` when not. */
357
+ tone?: ViewTone;
358
+ }
359
+ /** What `defineWorkspace` accepts. */
360
+ interface WorkspaceDefinition<C extends ResourceContract, Row extends DataRow = RowOf<C>> {
361
+ /** The view actions the header offers, by name, in order. Default: every view action. */
362
+ header?: {
363
+ actions?: readonly string[];
364
+ };
365
+ sections: readonly WorkspaceSection<Row, FieldNameOf<C>>[];
366
+ readiness?: (row: Row) => readonly WorkspaceReadinessItem[];
367
+ }
368
+ /** A section as a renderer draws it. */
369
+ type ResolvedWorkspaceSection = {
370
+ readonly id: string;
371
+ readonly label: string;
372
+ readonly kind: "list";
373
+ readonly view: AnyView;
374
+ } | {
375
+ readonly id: string;
376
+ readonly label: string;
377
+ readonly kind: "settings";
378
+ readonly settings: readonly string[];
379
+ } | {
380
+ readonly id: string;
381
+ readonly label: string;
382
+ readonly kind: "slot";
383
+ };
384
+ /** A header action with whether this row allows it. */
385
+ interface WorkspaceHeaderAction {
386
+ readonly name: string;
387
+ readonly label: string;
388
+ readonly confirm?: string;
389
+ readonly description?: string;
390
+ readonly destructive?: boolean;
391
+ /** `true`, or the view guard's reason. Only narrows what the server allows. */
392
+ readonly allowed: Allowed;
393
+ }
394
+ /** The header for one row: the view's summary plus the header's actions. */
395
+ interface WorkspaceHeader {
396
+ readonly title: string;
397
+ readonly subtitle?: string;
398
+ readonly chips: readonly {
399
+ label: string;
400
+ tone?: ViewTone;
401
+ }[];
402
+ readonly actions: readonly WorkspaceHeaderAction[];
403
+ }
404
+ /** What a screen and its provider add to the header: they only narrow the view's guards. */
405
+ interface WorkspaceHeaderOptions<Row extends DataRow = DataRow> {
406
+ /** The screen's own rule: `false` hides the action, a sentence refuses it with that reason. */
407
+ can?: (action: string, row: Row) => Allowed | boolean;
408
+ /** Whether anything can run actions here (the screen's `onAction`, or the provider's `runAction`). `false` hides them all. */
409
+ runnable?: boolean;
410
+ /** The action names the provider reports serving (`ResourceSchema.actions`), when it reports them. Others are hidden. */
411
+ served?: readonly string[];
412
+ /** Who is looking (`useViewer()`), for the view's action guards. Without it they get no one. */
413
+ viewer?: Viewer;
414
+ }
415
+ /** A readiness check with its tone resolved. */
416
+ interface ResolvedReadinessItem {
417
+ /** Stable, for list keys: the check's `id`, or its position and title. */
418
+ readonly key: string;
419
+ readonly title: string;
420
+ readonly ok: boolean;
421
+ readonly reason?: string;
422
+ readonly tone: ViewTone;
423
+ }
424
+ /** What `defineWorkspace` returns: frozen, with pure helpers for the renderers. */
425
+ interface ResourceWorkspace<C extends ResourceContract = ResourceContract, Row extends DataRow = RowOf<C>> {
426
+ readonly view: ResourceView<C, Row>;
427
+ readonly sections: readonly ResolvedWorkspaceSection[];
428
+ /** The header's action names, in order. */
429
+ readonly headerActions: readonly string[];
430
+ readonly hasReadiness: boolean;
431
+ section(id: string): ResolvedWorkspaceSection | undefined;
432
+ /** The record's address for the provider: its key fields (`keyFields`), composite keys encoded. */
433
+ recordId(row: Row): Identifier;
434
+ /**
435
+ * Why settings can't be saved for this row and viewer: the view's `can("update", row, viewer)`
436
+ * reason, or `null` when they can. Renderers then show the settings read-only with the reason.
437
+ * Without a viewer the guard gets no one, so one that needs the viewer locks them.
438
+ */
439
+ settingsLocked(row: Row, viewer?: Viewer): string | null;
440
+ headerFor(row: Row, options?: WorkspaceHeaderOptions<Row>): WorkspaceHeader;
441
+ /**
442
+ * Settings fields as the view's form resolves them (`view.form("edit")`), in the order listed:
443
+ * one section's, or every settings section's without an id.
444
+ */
445
+ settingsFields(sectionId?: string): readonly ResolvedFormField[];
446
+ /** Only the section's listed keys that `values` has: what a save sends. */
447
+ settingsPatch(sectionId: string, values: Readonly<Record<string, unknown>>): Record<string, unknown>;
448
+ /**
449
+ * A list section's filter for this row. In development, a filter with no key, or a value that
450
+ * isn't a string, number, boolean or null, throws: it would show every child row.
451
+ */
452
+ listFilter(sectionId: string, row: Row): WorkspaceFilter;
453
+ /** The readiness checks for this row, tones resolved; empty without `readiness`. */
454
+ readinessFor(row: Row): readonly ResolvedReadinessItem[];
455
+ /**
456
+ * The checks in one chip's terms (genesis-core/resource's `readinessOf`): an unmet `danger`
457
+ * check is a problem, any other unmet check one to look at. `null` without `readiness`. Draw
458
+ * it with `readinessChip`.
459
+ */
460
+ readinessSummary(row: Row): Readiness | null;
461
+ }
462
+ /** Whether a value is a workspace (`defineWorkspace`'s result). */
463
+ declare function isWorkspace(value: unknown): value is ResourceWorkspace;
464
+ /**
465
+ * One record's screen from its view:
466
+ *
467
+ * ```ts
468
+ * export const brandWorkspace = defineWorkspace(brandsView, {
469
+ * header: { actions: ["archive"] },
470
+ * sections: [
471
+ * { id: "products", label: "Products", list: { view: productsView, filter: (b) => ({ brand_id: b.id }) } },
472
+ * { id: "settings", label: "Settings", settings: ["name", "website"] },
473
+ * { id: "activity", label: "Activity" }, // the screen fills it
474
+ * ],
475
+ * readiness: (b) => [{ title: "Has a website", ok: !!b.website, reason: "Add the website." }],
476
+ * });
477
+ * ```
478
+ *
479
+ * Throws {@link ViewDefinitionError} for a settings field the view can't write, a header action
480
+ * the view doesn't define, a repeated section id, or a section that holds another workspace.
481
+ */
482
+ declare function defineWorkspace<C extends ResourceContract, Row extends DataRow = RowOf<C>>(view: ResourceView<C, Row>, definition: WorkspaceDefinition<C, Row>): ResourceWorkspace<C, Row>;
483
+
484
+ 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, valueText };