@marktiderman/genesis-core 2.14.0 → 2.16.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 (101) hide show
  1. package/dist/aggregate-Y5IJ5aPn.d.ts +34 -0
  2. package/dist/{chunk-7PUFVNPB.js → chunk-2IGAUXYH.js} +5 -3
  3. package/dist/chunk-2IGAUXYH.js.map +1 -0
  4. package/dist/{chunk-KA3BUJ4H.js → chunk-42NVJJTT.js} +3 -3
  5. package/dist/{chunk-KA3BUJ4H.js.map → chunk-42NVJJTT.js.map} +1 -1
  6. package/dist/{chunk-JN47G4UE.js → chunk-7EFTWOMA.js} +56 -2
  7. package/dist/chunk-7EFTWOMA.js.map +1 -0
  8. package/dist/{chunk-P3FHXRS2.js → chunk-ALLWIK62.js} +6 -6
  9. package/dist/{chunk-P3FHXRS2.js.map → chunk-ALLWIK62.js.map} +1 -1
  10. package/dist/chunk-APFXV6FZ.js +130 -0
  11. package/dist/chunk-APFXV6FZ.js.map +1 -0
  12. package/dist/chunk-BDPRWVFW.js +17 -0
  13. package/dist/chunk-BDPRWVFW.js.map +1 -0
  14. package/dist/{chunk-S2VYJWB4.js → chunk-E3K2A3PK.js} +3 -3
  15. package/dist/{chunk-S2VYJWB4.js.map → chunk-E3K2A3PK.js.map} +1 -1
  16. package/dist/{chunk-OYDJGPDY.js → chunk-FXPODKCK.js} +5 -5
  17. package/dist/{chunk-OYDJGPDY.js.map → chunk-FXPODKCK.js.map} +1 -1
  18. package/dist/{chunk-SDAJSJNN.js → chunk-IYGVJFCV.js} +3 -3
  19. package/dist/{chunk-SDAJSJNN.js.map → chunk-IYGVJFCV.js.map} +1 -1
  20. package/dist/chunk-J54XXKQD.js +104 -0
  21. package/dist/chunk-J54XXKQD.js.map +1 -0
  22. package/dist/{chunk-KV2HW4G4.js → chunk-LB6FMQQM.js} +11 -3
  23. package/dist/chunk-LB6FMQQM.js.map +1 -0
  24. package/dist/{chunk-G6GQPXQS.js → chunk-M5IX7C6U.js} +5 -5
  25. package/dist/{chunk-G6GQPXQS.js.map → chunk-M5IX7C6U.js.map} +1 -1
  26. package/dist/{chunk-DFABPMEQ.js → chunk-POUI7GAI.js} +5 -5
  27. package/dist/{chunk-DFABPMEQ.js.map → chunk-POUI7GAI.js.map} +1 -1
  28. package/dist/{chunk-NE2D74BP.js → chunk-QGWQ6LK3.js} +5 -5
  29. package/dist/{chunk-NE2D74BP.js.map → chunk-QGWQ6LK3.js.map} +1 -1
  30. package/dist/{chunk-2K4747KX.js → chunk-R3YXYVWF.js} +7 -2
  31. package/dist/chunk-R3YXYVWF.js.map +1 -0
  32. package/dist/{chunk-RFHUOXZC.js → chunk-SOO54YYY.js} +4 -4
  33. package/dist/{chunk-RFHUOXZC.js.map → chunk-SOO54YYY.js.map} +1 -1
  34. package/dist/{chunk-YZV3Z6ZA.js → chunk-SQLM5CIJ.js} +3 -3
  35. package/dist/{chunk-YZV3Z6ZA.js.map → chunk-SQLM5CIJ.js.map} +1 -1
  36. package/dist/{chunk-WDPM5TBO.js → chunk-UDSTWXXZ.js} +3 -3
  37. package/dist/{chunk-WDPM5TBO.js.map → chunk-UDSTWXXZ.js.map} +1 -1
  38. package/dist/chunk-XPBS5YE4.js +24 -0
  39. package/dist/chunk-XPBS5YE4.js.map +1 -0
  40. package/dist/{chunk-AHFIS42U.js → chunk-ZYOJWU62.js} +5 -5
  41. package/dist/{chunk-AHFIS42U.js.map → chunk-ZYOJWU62.js.map} +1 -1
  42. package/dist/csv.d.ts +1 -1
  43. package/dist/form-types.d.ts +1 -1
  44. package/dist/headless/index.d.ts +334 -0
  45. package/dist/headless/index.js +490 -0
  46. package/dist/headless/index.js.map +1 -0
  47. package/dist/hooks/index.d.ts +4 -2
  48. package/dist/hooks/index.js +20 -17
  49. package/dist/hooks/mutation-mode.d.ts +1 -1
  50. package/dist/hooks/mutation-mode.js +5 -4
  51. package/dist/hooks/related-keys.d.ts +1 -1
  52. package/dist/hooks/use-aggregate.d.ts +25 -0
  53. package/dist/hooks/use-aggregate.js +10 -0
  54. package/dist/hooks/use-aggregate.js.map +1 -0
  55. package/dist/hooks/use-capabilities.d.ts +1 -1
  56. package/dist/hooks/use-capabilities.js +4 -2
  57. package/dist/hooks/use-draft.js +2 -2
  58. package/dist/hooks/use-infinite-resource.d.ts +1 -1
  59. package/dist/hooks/use-infinite-resource.js +6 -4
  60. package/dist/hooks/use-link-options.d.ts +1 -1
  61. package/dist/hooks/use-link-options.js +8 -6
  62. package/dist/hooks/use-live.d.ts +1 -1
  63. package/dist/hooks/use-live.js +4 -2
  64. package/dist/hooks/use-one.d.ts +1 -1
  65. package/dist/hooks/use-one.js +6 -4
  66. package/dist/hooks/use-persisted-ui-state.js +4 -2
  67. package/dist/hooks/use-relation-label.d.ts +1 -1
  68. package/dist/hooks/use-relation-label.js +4 -2
  69. package/dist/hooks/use-resource-form.d.ts +1 -1
  70. package/dist/hooks/use-resource-form.js +8 -7
  71. package/dist/hooks/use-resource.d.ts +1 -1
  72. package/dist/hooks/use-resource.js +7 -6
  73. package/dist/hooks/use-write.d.ts +1 -1
  74. package/dist/index.d.ts +110 -6
  75. package/dist/index.js +129 -20
  76. package/dist/index.js.map +1 -1
  77. package/dist/navigation.d.ts +77 -1
  78. package/dist/navigation.js +32 -2
  79. package/dist/navigation.js.map +1 -1
  80. package/dist/provider/index.d.ts +12 -4
  81. package/dist/provider/index.js +3 -2
  82. package/dist/resource-view/index.d.ts +456 -166
  83. package/dist/resource-view/index.js +251 -5
  84. package/dist/resource-view/index.js.map +1 -1
  85. package/dist/schema/index.d.ts +3 -3
  86. package/dist/schema/index.js +1 -2
  87. package/dist/testing/index.d.ts +2 -2
  88. package/dist/{types-CtJxwoyv.d.ts → types-BriIV4e_.d.ts} +78 -3
  89. package/dist/workspaces-CxpiFu2-.d.ts +263 -0
  90. package/dist/workspaces.d.ts +2 -160
  91. package/dist/workspaces.js +2 -1
  92. package/dist/{write-outcome-Goy1v39G.d.ts → write-outcome-CkQXgtJq.d.ts} +1 -1
  93. package/package.json +14 -4
  94. package/dist/chunk-2K4747KX.js.map +0 -1
  95. package/dist/chunk-7PUFVNPB.js.map +0 -1
  96. package/dist/chunk-JN47G4UE.js.map +0 -1
  97. package/dist/chunk-KV2HW4G4.js.map +0 -1
  98. package/dist/chunk-UHOMTFBD.js +0 -72
  99. package/dist/chunk-UHOMTFBD.js.map +0 -1
  100. package/dist/chunk-YDMKMNDS.js +0 -8
  101. package/dist/chunk-YDMKMNDS.js.map +0 -1
@@ -1,6 +1,6 @@
1
- import { x as ResourceContract, b as Identifier, h as DataRow } from '../types-CtJxwoyv.js';
2
- export { c as AuditEntry, k as FieldPermissions, l as FieldReference, F as FieldSchema, n as FilterOperator, t as ProviderCapabilities, u as RecordComment, v as ResourceAccess, z as ResourceRelation, E as ResourceSchema, J as ResourceSummary, K as RowAction, O as RowOf, U as StorageType, Z as VersionField, m as WidgetHint, _ as defineResource } from '../types-CtJxwoyv.js';
3
- export { D as DataWriteError, a as DataWriteErrorOptions, N as NO_ROWS_MATCHED, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-Goy1v39G.js';
1
+ import { M as ResourceContract, d as Identifier, j as DataRow } from '../types-BriIV4e_.js';
2
+ export { h as AuditEntry, C as ControlHint, s as FieldPermissions, e as FieldReference, F as FieldSchema, u as FilterOperator, P as ProviderCapabilities, J as RecordComment, K as ResourceAccess, O as ResourceRelation, Q as ResourceSchema, T as ResourceSummary, U as RowAction, X as RowOf, _ as StorageType, a1 as VersionField, a2 as WidgetHint, a3 as defineResource, a4 as fieldControl } from '../types-BriIV4e_.js';
3
+ export { D as DataWriteError, a as DataWriteErrorOptions, N as NO_ROWS_MATCHED, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-CkQXgtJq.js';
4
4
  export { W as WriteConflict, a as WriteConflictOptions, b as WriteState, w as writeConflict } from '../write-state-DVC4Yq9T.js';
5
5
  export { D as DataReadError, a as DataReadErrorOptions, R as ReadOutcome, i as isDataReadError, r as readFailureMessage } from '../read-outcome-BnboMYOV.js';
6
6
 
@@ -1,5 +1,4 @@
1
- export { defineResource } from '../chunk-YDMKMNDS.js';
2
- export { decodeRecordKey, encodeRecordKey, keyFields } from '../chunk-KV2HW4G4.js';
1
+ export { decodeRecordKey, defineResource, encodeRecordKey, fieldControl, keyFields } from '../chunk-LB6FMQQM.js';
3
2
  export { writeConflict } from '../chunk-LKRJB632.js';
4
3
  export { DataReadError, isDataReadError, readFailureMessage } from '../chunk-HUNGCTRA.js';
5
4
  export { DataWriteError, NO_ROWS_MATCHED, isDataWriteError } from '../chunk-WLDSIQJ2.js';
@@ -1,5 +1,5 @@
1
- import { D as DataProvider, b as Identifier } from '../types-CtJxwoyv.js';
2
- import { D as DataWriteError } from '../write-outcome-Goy1v39G.js';
1
+ import { D as DataProvider, d as Identifier } from '../types-BriIV4e_.js';
2
+ import { D as DataWriteError } from '../write-outcome-CkQXgtJq.js';
3
3
 
4
4
  /** The shared fixture logins, the same ids `genesis_testing.user_id()` uses. */
5
5
  declare const FIXTURE_USERS: {
@@ -110,6 +110,8 @@ interface ResourceFormFieldDef {
110
110
  arrayMin?: number;
111
111
  /** Maximum number of array items. */
112
112
  arrayMax?: number;
113
+ /** One array item's name, for the add button ("Address" makes "Add Address"). Default: the label, made singular. */
114
+ arrayItemLabel?: string;
113
115
  /** Group heading for field grouping in the form. */
114
116
  group?: string;
115
117
  /** Column span in 2-column layout. Default 1. */
@@ -120,6 +122,18 @@ interface ResourceFormFieldDef {
120
122
  disabled?: (values: Record<string, unknown>) => boolean;
121
123
  }
122
124
 
125
+ /**
126
+ * Which form control fits a field (`text`, `textarea`, `date`, `tel`…): a hint a form reads.
127
+ * The field's `control` (decision F, ADR 0021).
128
+ *
129
+ * @stability Beta
130
+ */
131
+ type ControlHint = FieldType;
132
+ /**
133
+ * @deprecated Renamed `ControlHint`: "widget" now means a dashboard tile (docs/GLOSSARY.md).
134
+ * Kept as an alias; removed in the next major.
135
+ */
136
+ type WidgetHint = ControlHint;
123
137
  /**
124
138
  * Portable storage type of a field — what kind of value the store holds,
125
139
  * independent of how a UI should edit it. The exact native type, when the
@@ -171,8 +185,16 @@ interface FieldSchema {
171
185
  readonly label?: string;
172
186
  /** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
173
187
  readonly dbType?: string;
174
- /** Which control fits this field. A hint: a UI may still choose another. */
175
- readonly widget?: FieldType;
188
+ /**
189
+ * Which form control fits this field (`textarea`, `date`, `tel`…). A hint: a UI may still
190
+ * choose another. Read it with `fieldControl(field)`, which also reads the old `widget`.
191
+ */
192
+ readonly control?: ControlHint;
193
+ /**
194
+ * @deprecated Renamed `control` ("widget" now means a dashboard tile). Still read wherever
195
+ * `control` is (`fieldControl`); `control` wins when both are set. Removed in the next major.
196
+ */
197
+ readonly widget?: ControlHint;
176
198
  /** True when the store accepts null for this field. */
177
199
  readonly nullable?: boolean;
178
200
  /** True when the store fills the field itself on insert. */
@@ -455,6 +477,16 @@ interface AuditEntry {
455
477
  /** Values of the changed fields after the edit. */
456
478
  readonly after: DataRow | null;
457
479
  }
480
+ /**
481
+ * A field's form-control hint: its `control`, else the deprecated `widget`. Every reader goes
482
+ * through this, so a contract written with either name works.
483
+ *
484
+ * @stability Beta
485
+ */
486
+ declare function fieldControl(field: {
487
+ readonly control?: string | undefined;
488
+ readonly widget?: string | undefined;
489
+ } | undefined): ControlHint | undefined;
458
490
 
459
491
  /** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
460
492
  type Identifier = string | number;
@@ -565,6 +597,42 @@ interface ListResult<T> {
565
597
  */
566
598
  prevCursor?: string | null;
567
599
  }
600
+ /**
601
+ * One total over a list: how many rows (`count`), or the sum, average, lowest or highest of a
602
+ * numeric field. Rows with no value in the field are left out of `sum`, `avg`, `min` and `max`,
603
+ * as SQL leaves them out.
604
+ */
605
+ type AggregateMetric = {
606
+ fn: "count";
607
+ } | {
608
+ fn: "sum" | "avg" | "min" | "max";
609
+ field: string;
610
+ };
611
+ /**
612
+ * Parameters for `aggregate`: the totals to work out, by a name the caller picks, over the rows
613
+ * the same `filters` and `search` would list.
614
+ */
615
+ interface AggregateParams {
616
+ /** The totals, by name: `{ open: { fn: "count" }, value: { fn: "sum", field: "amount" } }`. */
617
+ metrics: Readonly<Record<string, AggregateMetric>>;
618
+ filters?: FilterParam[];
619
+ search?: {
620
+ query: string;
621
+ fields: string[];
622
+ };
623
+ /** How `count` is counted (see `CountMode`); `none` isn't allowed here. Default exact. */
624
+ count?: Exclude<CountMode, "none">;
625
+ }
626
+ /** Result of `aggregate`. */
627
+ interface AggregateResult {
628
+ /**
629
+ * Each metric's value, by its name. `count` is always a number; the others are `null` when no
630
+ * row has a value (SQL's answer for an empty sum).
631
+ */
632
+ values: Record<string, number | null>;
633
+ /** True when a count is the database's estimate, so a screen says "about". */
634
+ isEstimate?: boolean;
635
+ }
568
636
  /** Parameters for `getOne`. */
569
637
  interface GetOneParams {
570
638
  id: Identifier;
@@ -734,6 +802,13 @@ interface DataProvider {
734
802
  * are omitted entirely.
735
803
  */
736
804
  describe?(resource: string): Promise<ResourceSchema>;
805
+ /**
806
+ * Totals over the rows a list with the same filters and search would return, worked out by
807
+ * the store under the same rules as `getList` (row security included), so a widget never
808
+ * reads rows it only counts. Optional: `resolveAggregate` falls back to `getList` for a
809
+ * provider without it.
810
+ */
811
+ aggregate?(resource: string, params: AggregateParams): Promise<AggregateResult>;
737
812
  /** Every resource this user may see, for a sidebar or a picker. */
738
813
  listResources?(): Promise<ResourceSummary[]>;
739
814
  /**
@@ -825,4 +900,4 @@ interface DataProvider {
825
900
  invalidates?(event: WriteEvent): InvalidationKey[];
826
901
  }
827
902
 
828
- export { type ArrayFilter as A, type BaseRecord as B, type CountMode as C, type DataProvider as D, type ResourceSchema as E, type FieldSchema as F, type GetManyParams as G, type HistoryParams as H, type InvalidationKey as I, type ResourceSummary as J, type RowAction as K, type ListParams as L, type RowFailure as M, type NullFilter as N, type RowOf as O, type PaginationParam as P, type ScalarFilter as Q, type RangeFilter as R, type SortParam as S, type SelectOption as T, type StorageType as U, type SubscribeParams as V, type WriteEvent as W, type UpdateParams as X, type UpdateResult as Y, type VersionField as Z, defineResource as _, type FilterParam as a, type Identifier as b, type AuditEntry as c, type BulkChange as d, type BulkResult as e, type CreateParams as f, type CreateResult as g, type DataRow as h, type DeleteParams as i, type DeleteResult as j, type FieldPermissions as k, type FieldReference as l, type FieldType as m, type FilterOperator as n, type GetManyResult as o, type GetOneParams as p, type GetOneResult as q, type ImportParams as r, type ListResult as s, type ProviderCapabilities as t, type RecordComment as u, type ResourceAccess as v, type ResourceChangeEvent as w, type ResourceContract as x, type ResourceFormFieldDef as y, type ResourceRelation as z };
903
+ export { type UpdateParams as $, type AggregateParams as A, type BaseRecord as B, type ControlHint as C, type DataProvider as D, type RangeFilter as E, type FieldSchema as F, type GetManyParams as G, type HistoryParams as H, type InvalidationKey as I, type RecordComment as J, type ResourceAccess as K, type ListResult as L, type ResourceContract as M, type NullFilter as N, type ResourceRelation as O, type ProviderCapabilities as P, type ResourceSchema as Q, type ResourceFormFieldDef as R, type SortParam as S, type ResourceSummary as T, type RowAction as U, type RowFailure as V, type WriteEvent as W, type RowOf as X, type ScalarFilter as Y, type SelectOption as Z, type StorageType as _, type FilterParam as a, type UpdateResult as a0, type VersionField as a1, type WidgetHint as a2, defineResource as a3, fieldControl as a4, type AggregateResult as b, type ListParams as c, type Identifier as d, type FieldReference as e, type SubscribeParams as f, type ResourceChangeEvent as g, type AuditEntry as h, type AggregateMetric as i, type DataRow as j, type ArrayFilter as k, type BulkChange as l, type BulkResult as m, type CountMode as n, type CreateParams as o, type CreateResult as p, type DeleteParams as q, type DeleteResult as r, type FieldPermissions as s, type FieldType as t, type FilterOperator as u, type GetManyResult as v, type GetOneParams as w, type GetOneResult as x, type ImportParams as y, type PaginationParam as z };
@@ -0,0 +1,263 @@
1
+ import { R as ResourceScope, G as GenesisViewerRoles } from './viewer-scope-Dx0N9AYk.js';
2
+
3
+ /**
4
+ * Appearance preferences, as data (ADR 0024): the values and the order that decides which one
5
+ * applies. No React, so a server, a phone or `workspaces.ts` can use it; the provider is
6
+ * `appearance.tsx`.
7
+ *
8
+ * app lock > person > organization default > theme default > Genesis default
9
+ */
10
+ /** Light, dark, or follow the device: the person's appearance. */
11
+ type Appearance = "light" | "dark" | "system";
12
+ /** How tightly rows and controls sit. */
13
+ type Density = "compact" | "comfortable" | "spacious";
14
+ /** The appearances, in a picker's order. */
15
+ declare const APPEARANCES: readonly Appearance[];
16
+ /** The densities, tightest first. */
17
+ declare const DENSITIES: readonly Density[];
18
+ /** An appearance and a density, either of which may be unset. */
19
+ interface AppearancePreferenceValues {
20
+ appearance?: Appearance | undefined;
21
+ density?: Density | undefined;
22
+ }
23
+ /** Genesis's own defaults, the last step of the order. */
24
+ declare const GENESIS_APPEARANCE_DEFAULTS: Readonly<Required<AppearancePreferenceValues>>;
25
+ /** Where a resolved value came from. */
26
+ type AppearancePreferenceSource = "app" | "person" | "organization" | "theme" | "genesis";
27
+ /** Each layer of the order; any may be missing. */
28
+ interface AppearancePreferenceLayers {
29
+ /** The app's lock: a value set here can't be changed by anyone below it. */
30
+ lock?: AppearancePreferenceValues | undefined;
31
+ /** The person's own choice. */
32
+ person?: AppearancePreferenceValues | undefined;
33
+ /** The organization's default for its people (`WorkspaceTheme.defaults`). */
34
+ organization?: AppearancePreferenceValues | undefined;
35
+ /** The app theme's default (its layout's density, say). */
36
+ theme?: AppearancePreferenceValues | undefined;
37
+ }
38
+ /** The values that apply, and where each came from. */
39
+ interface ResolvedAppearancePreferences {
40
+ appearance: Appearance;
41
+ density: Density;
42
+ source: {
43
+ appearance: AppearancePreferenceSource;
44
+ density: AppearancePreferenceSource;
45
+ };
46
+ }
47
+ /** Whether a value is an appearance. */
48
+ declare const isAppearance: (v: unknown) => v is Appearance;
49
+ /** Whether a value is a density. */
50
+ declare const isDensity: (v: unknown) => v is Density;
51
+ /** Only the known values: a stored or typed-in value that isn't one is left out. */
52
+ declare function toAppearancePreferenceValues(input: unknown): AppearancePreferenceValues;
53
+ /**
54
+ * The appearance and density that apply: app lock, then the person, then the organization's
55
+ * default, then the theme's, then Genesis's. Values that aren't known appearances or densities
56
+ * are skipped, so a bad stored value falls through to the next layer.
57
+ *
58
+ * @stability Beta
59
+ */
60
+ declare function resolveAppearancePreferences(layers: AppearancePreferenceLayers): ResolvedAppearancePreferences;
61
+
62
+ /**
63
+ * Workspaces (docs/adr/0004-workspaces.md): where the viewer is working, chosen first and kept in
64
+ * the URL. A workspace is one tenant (an organization), the roll-up across them, or the viewer's
65
+ * own personal space. Everything inside it is scoped to it: its `scope` is the `ResourceScope`
66
+ * every view reads, and its path prefixes every URL inside it.
67
+ *
68
+ * Router-free and DOM-free, like `navigation`: web and native shells share it.
69
+ */
70
+
71
+ /**
72
+ * The kinds of workspace. Genesis ships three; an app adds its own by module augmentation, and
73
+ * the switcher groups and orders them like the built-in ones:
74
+ *
75
+ * ```ts
76
+ * declare module "@marktiderman/genesis-core/workspaces" {
77
+ * interface GenesisWorkspaceKinds {
78
+ * location: true;
79
+ * }
80
+ * }
81
+ * ```
82
+ *
83
+ * @stability Beta
84
+ */
85
+ interface GenesisWorkspaceKinds {
86
+ /** One tenant: an organization the viewer is a member or staff of. */
87
+ tenant: true;
88
+ /** The roll-up across every tenant the viewer works in. */
89
+ rollup: true;
90
+ /** The viewer's own things, belonging to no tenant. */
91
+ personal: true;
92
+ }
93
+ /** @stability Beta */
94
+ type WorkspaceKind = keyof GenesisWorkspaceKinds;
95
+ /**
96
+ * One place the viewer can work in.
97
+ *
98
+ * @stability Beta
99
+ */
100
+ interface Workspace {
101
+ /** Unique among the viewer's workspaces. For a tenant, usually its URL segment. */
102
+ id: string;
103
+ kind: WorkspaceKind;
104
+ /** Its name: the organization's name, "All organizations", "Personal". */
105
+ label: string;
106
+ /** A second line in the switcher: the viewer's role there, a location. */
107
+ description?: string;
108
+ /**
109
+ * Where it starts, and the prefix of every URL inside it: `/o/acme`, `/all`, `/me`. Matched at
110
+ * segment boundaries, so `/o/acme` never matches `/o/acme-west`.
111
+ */
112
+ path: string;
113
+ /** What views read inside it: `{ orgId }`, `{ orgId: [...] }`, `{ personId }`. */
114
+ scope: ResourceScope;
115
+ /** The viewer's roles here, for view guards (see `GenesisViewerRoles`). */
116
+ roles?: GenesisViewerRoles;
117
+ /** The workspace's IANA time zone, for columns read on the scope's clock. */
118
+ timeZone?: string | null;
119
+ /** Its picture: a logo URL, else initials made from `label`. */
120
+ image?: string;
121
+ /**
122
+ * A count or short status beside it in the switcher: unread messages, tasks waiting. `0`, an
123
+ * empty string, `null` and undefined show nothing.
124
+ */
125
+ badge?: string | number | null;
126
+ /** Its brand, for the switcher's picture and anything the app themes inside it. */
127
+ theme?: WorkspaceTheme;
128
+ /** Anything else the app needs; Genesis never reads it. */
129
+ meta?: Readonly<Record<string, unknown>>;
130
+ }
131
+ /**
132
+ * A workspace's brand. `accent` takes the same values as a public page's brand accent (`#rgb`,
133
+ * `#rrggbb`, `rgb()`, `hsl()` or a bare token triplet like `"160 84% 39%"`); genesis-ui turns it
134
+ * into the design system's `--primary` (`workspaceThemeStyle`), darkened when it is too light to
135
+ * carry text.
136
+ *
137
+ * @stability Beta
138
+ */
139
+ interface WorkspaceTheme {
140
+ accent?: string;
141
+ /**
142
+ * The app brand this organization wears, by id (`defineAppBrand`'s name, what
143
+ * `data-app-brand` names): its colours and typefaces across the app while the workspace is
144
+ * active. `resolveWorkspaceBrand` picks it, checked against the brands the app ships.
145
+ */
146
+ brand?: string;
147
+ /**
148
+ * The organization's defaults for its people's appearance and density. A person's own choice
149
+ * wins over them, and the app's lock over that (`resolveAppearancePreferences`).
150
+ */
151
+ defaults?: AppearancePreferenceValues;
152
+ }
153
+ /**
154
+ * The app brand that applies in a workspace: its `theme.brand` when the app ships a brand by
155
+ * that id (`available`, ids or anything with an `id`), else `fallback`. Without `available`,
156
+ * any brand id is taken as given.
157
+ *
158
+ * ```ts
159
+ * const brand = resolveWorkspaceBrand(active, { available: STARTER_BRANDS, fallback: "acme" });
160
+ * document.documentElement.dataset.appBrand = brand;
161
+ * ```
162
+ *
163
+ * @stability Beta
164
+ */
165
+ declare function resolveWorkspaceBrand(workspace: Pick<Workspace, "theme"> | null | undefined, options?: {
166
+ available?: readonly (string | {
167
+ readonly id: string;
168
+ })[];
169
+ fallback?: string;
170
+ }): string | undefined;
171
+ /**
172
+ * The organization's appearance and density defaults, for `AppearancePreferencesProvider`'s
173
+ * `organization`: only known values, empty without a workspace.
174
+ *
175
+ * @stability Beta
176
+ */
177
+ declare function resolveWorkspaceAppearance(workspace: Pick<Workspace, "theme"> | null | undefined): AppearancePreferenceValues;
178
+ /** The kinds in their default order: personal, roll-up, then each tenant. */
179
+ declare const WORKSPACE_KIND_ORDER: readonly WorkspaceKind[];
180
+ /**
181
+ * The workspace a URL is in: the one whose `path` is the longest prefix of `pathname`, or
182
+ * undefined when the URL is in none (a sign-in page, the app's front door).
183
+ *
184
+ * @stability Beta
185
+ */
186
+ declare function workspaceAt<W extends Workspace>(workspaces: readonly W[], pathname: string): W | undefined;
187
+ /**
188
+ * The path inside a workspace: `/o/acme/clients/42` in `/o/acme` is `/clients/42`; the workspace's
189
+ * own landing page is `/`.
190
+ *
191
+ * @stability Beta
192
+ */
193
+ declare function pathInWorkspace(workspace: Pick<Workspace, "path">, pathname: string): string;
194
+ /** @stability Beta */
195
+ interface WorkspaceHrefOptions {
196
+ /**
197
+ * Whether to keep the viewer's place when switching: given the path inside the current
198
+ * workspace (`/clients`) and the two workspaces, return the path to open in the target, or
199
+ * false for its landing page. By default the place is kept between workspaces of the same kind,
200
+ * up to the first segment (a list, not one record that belongs to the old workspace):
201
+ * `/o/acme/clients/42` switches to `/o/globex/clients`.
202
+ */
203
+ keep?: (rest: string, from: Workspace, to: Workspace) => string | false;
204
+ }
205
+ /** The default `keep`: the same kind keeps the section (the first segment), never a record. */
206
+ declare function keepSection(rest: string, from: Workspace, to: Workspace): string | false;
207
+ /**
208
+ * Where switching to `to` goes from `pathname`. The URL moves with the viewer: it lands in the same
209
+ * section of the new workspace when that makes sense (see `keep`), else on its landing page.
210
+ *
211
+ * @stability Beta
212
+ */
213
+ declare function workspaceHref(workspaces: readonly Workspace[], to: Workspace, pathname: string | undefined, options?: WorkspaceHrefOptions): string;
214
+ /** @stability Beta */
215
+ interface WorkspaceGroup<W extends Workspace = Workspace> {
216
+ kind: WorkspaceKind;
217
+ workspaces: W[];
218
+ }
219
+ /**
220
+ * The workspaces grouped by kind, in `order` (default {@link WORKSPACE_KIND_ORDER}, then any kind
221
+ * an app added), each group in the order given. Empty groups are left out.
222
+ *
223
+ * @stability Beta
224
+ */
225
+ declare function groupWorkspaces<W extends Workspace>(workspaces: readonly W[], order?: readonly WorkspaceKind[]): WorkspaceGroup<W>[];
226
+ /**
227
+ * The workspace to open when the URL names none (the app's front door): the remembered one if the
228
+ * viewer still has it, else the first tenant, else the first workspace.
229
+ *
230
+ * @stability Beta
231
+ */
232
+ declare function defaultWorkspace<W extends Workspace>(workspaces: readonly W[], rememberedId?: string | null): W | undefined;
233
+ /**
234
+ * Initials for a workspace with no image: the first letters of its first two words.
235
+ *
236
+ * @stability Beta
237
+ */
238
+ declare function workspaceInitials(label: string): string;
239
+ /**
240
+ * The workspaces whose label or second line contains every word of `query`, ignoring case and
241
+ * accents, in the order given. An empty query keeps them all. For the switcher's search box, on
242
+ * the web and on the phone.
243
+ *
244
+ * @stability Beta
245
+ */
246
+ declare function filterWorkspaces<W extends Workspace>(workspaces: readonly W[], query: string): W[];
247
+ /**
248
+ * The workspaces in the order the switcher lists them (grouped by kind, in `order`): the order its
249
+ * keyboard jump numbers them, 1 to 9.
250
+ *
251
+ * @stability Beta
252
+ */
253
+ declare function orderedWorkspaces<W extends Workspace>(workspaces: readonly W[], order?: readonly WorkspaceKind[]): W[];
254
+ /** With a switcher's `search="auto"`, past this many workspaces it opens with a search box. On the web and the phone. */
255
+ declare const WORKSPACE_SWITCHER_SEARCH_THRESHOLD = 7;
256
+ /** The default heading over each kind's group in a switcher, on the web and the phone. */
257
+ declare const DEFAULT_WORKSPACE_KIND_LABELS: Readonly<Partial<Record<WorkspaceKind, string>>>;
258
+ /** Whether a workspace's badge shows: `0`, an empty string, `null` and undefined show nothing. */
259
+ declare function hasWorkspaceBadge(value: Workspace["badge"]): value is string | number;
260
+ /** What a screen reader hears for a badge: "3 new" for a number, the text itself otherwise. */
261
+ declare function workspaceBadgeLabel(_workspace: Workspace, value: string | number): string;
262
+
263
+ export { type AppearancePreferenceValues as A, workspaceAt as B, workspaceBadgeLabel as C, type Density as D, workspaceHref as E, workspaceInitials as F, GENESIS_APPEARANCE_DEFAULTS as G, type ResolvedAppearancePreferences as R, type Workspace as W, type AppearancePreferenceLayers as a, type Appearance as b, APPEARANCES as c, type AppearancePreferenceSource as d, DENSITIES as e, isDensity as f, type WorkspaceHrefOptions as g, DEFAULT_WORKSPACE_KIND_LABELS as h, isAppearance as i, type GenesisWorkspaceKinds as j, WORKSPACE_KIND_ORDER as k, WORKSPACE_SWITCHER_SEARCH_THRESHOLD as l, type WorkspaceGroup as m, type WorkspaceKind as n, type WorkspaceTheme as o, defaultWorkspace as p, filterWorkspaces as q, resolveAppearancePreferences as r, groupWorkspaces as s, toAppearancePreferenceValues as t, hasWorkspaceBadge as u, keepSection as v, orderedWorkspaces as w, pathInWorkspace as x, resolveWorkspaceAppearance as y, resolveWorkspaceBrand as z };
@@ -1,163 +1,5 @@
1
- import { R as ResourceScope, G as GenesisViewerRoles } from './viewer-scope-Dx0N9AYk.js';
1
+ import './viewer-scope-Dx0N9AYk.js';
2
+ export { h as DEFAULT_WORKSPACE_KIND_LABELS, j as GenesisWorkspaceKinds, k as WORKSPACE_KIND_ORDER, l as WORKSPACE_SWITCHER_SEARCH_THRESHOLD, W as Workspace, m as WorkspaceGroup, g as WorkspaceHrefOptions, n as WorkspaceKind, o as WorkspaceTheme, p as defaultWorkspace, q as filterWorkspaces, s as groupWorkspaces, u as hasWorkspaceBadge, v as keepSection, w as orderedWorkspaces, x as pathInWorkspace, y as resolveWorkspaceAppearance, z as resolveWorkspaceBrand, B as workspaceAt, C as workspaceBadgeLabel, E as workspaceHref, F as workspaceInitials } from './workspaces-CxpiFu2-.js';
2
3
  import 'react';
3
4
  import '@tanstack/react-query';
4
5
  import './dates.js';
5
-
6
- /**
7
- * Workspaces (docs/adr/0004-workspaces.md): where the viewer is working, chosen first and kept in
8
- * the URL. A workspace is one tenant (an organization), the roll-up across them, or the viewer's
9
- * own personal space. Everything inside it is scoped to it: its `scope` is the `ResourceScope`
10
- * every view reads, and its path prefixes every URL inside it.
11
- *
12
- * Router-free and DOM-free, like `navigation`: web and native shells share it.
13
- */
14
-
15
- /**
16
- * The kinds of workspace. Genesis ships three; an app adds its own by module augmentation, and
17
- * the switcher groups and orders them like the built-in ones:
18
- *
19
- * ```ts
20
- * declare module "@marktiderman/genesis-core/workspaces" {
21
- * interface GenesisWorkspaceKinds {
22
- * location: true;
23
- * }
24
- * }
25
- * ```
26
- *
27
- * @stability Beta
28
- */
29
- interface GenesisWorkspaceKinds {
30
- /** One tenant: an organization the viewer is a member or staff of. */
31
- tenant: true;
32
- /** The roll-up across every tenant the viewer works in. */
33
- rollup: true;
34
- /** The viewer's own things, belonging to no tenant. */
35
- personal: true;
36
- }
37
- /** @stability Beta */
38
- type WorkspaceKind = keyof GenesisWorkspaceKinds;
39
- /**
40
- * One place the viewer can work in.
41
- *
42
- * @stability Beta
43
- */
44
- interface Workspace {
45
- /** Unique among the viewer's workspaces. For a tenant, usually its URL segment. */
46
- id: string;
47
- kind: WorkspaceKind;
48
- /** Its name: the organization's name, "All organizations", "Personal". */
49
- label: string;
50
- /** A second line in the switcher: the viewer's role there, a location. */
51
- description?: string;
52
- /**
53
- * Where it starts, and the prefix of every URL inside it: `/o/acme`, `/all`, `/me`. Matched at
54
- * segment boundaries, so `/o/acme` never matches `/o/acme-west`.
55
- */
56
- path: string;
57
- /** What views read inside it: `{ orgId }`, `{ orgId: [...] }`, `{ personId }`. */
58
- scope: ResourceScope;
59
- /** The viewer's roles here, for view guards (see `GenesisViewerRoles`). */
60
- roles?: GenesisViewerRoles;
61
- /** The workspace's IANA time zone, for columns read on the scope's clock. */
62
- timeZone?: string | null;
63
- /** Its picture: a logo URL, else initials made from `label`. */
64
- image?: string;
65
- /**
66
- * A count or short status beside it in the switcher: unread messages, tasks waiting. `0`, an
67
- * empty string, `null` and undefined show nothing.
68
- */
69
- badge?: string | number | null;
70
- /** Its brand, for the switcher's picture and anything the app themes inside it. */
71
- theme?: WorkspaceTheme;
72
- /** Anything else the app needs; Genesis never reads it. */
73
- meta?: Readonly<Record<string, unknown>>;
74
- }
75
- /**
76
- * A workspace's brand. `accent` takes the same values as a public page's brand accent (`#rgb`,
77
- * `#rrggbb`, `rgb()`, `hsl()` or a bare token triplet like `"160 84% 39%"`); genesis-ui turns it
78
- * into the design system's `--primary` (`workspaceThemeStyle`), darkened when it is too light to
79
- * carry text.
80
- *
81
- * @stability Beta
82
- */
83
- interface WorkspaceTheme {
84
- accent?: string;
85
- }
86
- /** The kinds in their default order: personal, roll-up, then each tenant. */
87
- declare const WORKSPACE_KIND_ORDER: readonly WorkspaceKind[];
88
- /**
89
- * The workspace a URL is in: the one whose `path` is the longest prefix of `pathname`, or
90
- * undefined when the URL is in none (a sign-in page, the app's front door).
91
- *
92
- * @stability Beta
93
- */
94
- declare function workspaceAt<W extends Workspace>(workspaces: readonly W[], pathname: string): W | undefined;
95
- /**
96
- * The path inside a workspace: `/o/acme/clients/42` in `/o/acme` is `/clients/42`; the workspace's
97
- * own landing page is `/`.
98
- *
99
- * @stability Beta
100
- */
101
- declare function pathInWorkspace(workspace: Pick<Workspace, "path">, pathname: string): string;
102
- /** @stability Beta */
103
- interface WorkspaceHrefOptions {
104
- /**
105
- * Whether to keep the viewer's place when switching: given the path inside the current
106
- * workspace (`/clients`) and the two workspaces, return the path to open in the target, or
107
- * false for its landing page. By default the place is kept between workspaces of the same kind,
108
- * up to the first segment (a list, not one record that belongs to the old workspace):
109
- * `/o/acme/clients/42` switches to `/o/globex/clients`.
110
- */
111
- keep?: (rest: string, from: Workspace, to: Workspace) => string | false;
112
- }
113
- /** The default `keep`: the same kind keeps the section (the first segment), never a record. */
114
- declare function keepSection(rest: string, from: Workspace, to: Workspace): string | false;
115
- /**
116
- * Where switching to `to` goes from `pathname`. The URL moves with the viewer: it lands in the same
117
- * section of the new workspace when that makes sense (see `keep`), else on its landing page.
118
- *
119
- * @stability Beta
120
- */
121
- declare function workspaceHref(workspaces: readonly Workspace[], to: Workspace, pathname: string | undefined, options?: WorkspaceHrefOptions): string;
122
- /** @stability Beta */
123
- interface WorkspaceGroup<W extends Workspace = Workspace> {
124
- kind: WorkspaceKind;
125
- workspaces: W[];
126
- }
127
- /**
128
- * The workspaces grouped by kind, in `order` (default {@link WORKSPACE_KIND_ORDER}, then any kind
129
- * an app added), each group in the order given. Empty groups are left out.
130
- *
131
- * @stability Beta
132
- */
133
- declare function groupWorkspaces<W extends Workspace>(workspaces: readonly W[], order?: readonly WorkspaceKind[]): WorkspaceGroup<W>[];
134
- /**
135
- * The workspace to open when the URL names none (the app's front door): the remembered one if the
136
- * viewer still has it, else the first tenant, else the first workspace.
137
- *
138
- * @stability Beta
139
- */
140
- declare function defaultWorkspace<W extends Workspace>(workspaces: readonly W[], rememberedId?: string | null): W | undefined;
141
- /**
142
- * Initials for a workspace with no image: the first letters of its first two words.
143
- *
144
- * @stability Beta
145
- */
146
- declare function workspaceInitials(label: string): string;
147
- /**
148
- * The workspaces whose label or second line contains every word of `query`, ignoring case and
149
- * accents, in the order given. An empty query keeps them all. For the switcher's search box, on
150
- * the web and on the phone.
151
- *
152
- * @stability Beta
153
- */
154
- declare function filterWorkspaces<W extends Workspace>(workspaces: readonly W[], query: string): W[];
155
- /**
156
- * The workspaces in the order the switcher lists them (grouped by kind, in `order`): the order its
157
- * keyboard jump numbers them, 1 to 9.
158
- *
159
- * @stability Beta
160
- */
161
- declare function orderedWorkspaces<W extends Workspace>(workspaces: readonly W[], order?: readonly WorkspaceKind[]): W[];
162
-
163
- export { type GenesisWorkspaceKinds, WORKSPACE_KIND_ORDER, type Workspace, type WorkspaceGroup, type WorkspaceHrefOptions, type WorkspaceKind, type WorkspaceTheme, defaultWorkspace, filterWorkspaces, groupWorkspaces, keepSection, orderedWorkspaces, pathInWorkspace, workspaceAt, workspaceHref, workspaceInitials };
@@ -1,3 +1,4 @@
1
- export { WORKSPACE_KIND_ORDER, defaultWorkspace, filterWorkspaces, groupWorkspaces, keepSection, orderedWorkspaces, pathInWorkspace, workspaceAt, workspaceHref, workspaceInitials } from './chunk-UHOMTFBD.js';
1
+ export { DEFAULT_WORKSPACE_KIND_LABELS, WORKSPACE_KIND_ORDER, WORKSPACE_SWITCHER_SEARCH_THRESHOLD, defaultWorkspace, filterWorkspaces, groupWorkspaces, hasWorkspaceBadge, keepSection, orderedWorkspaces, pathInWorkspace, resolveWorkspaceAppearance, resolveWorkspaceBrand, workspaceAt, workspaceBadgeLabel, workspaceHref, workspaceInitials } from './chunk-APFXV6FZ.js';
2
+ import './chunk-BDPRWVFW.js';
2
3
  //# sourceMappingURL=workspaces.js.map
3
4
  //# sourceMappingURL=workspaces.js.map
@@ -1,4 +1,4 @@
1
- import { h as DataRow } from './types-CtJxwoyv.js';
1
+ import { j as DataRow } from './types-BriIV4e_.js';
2
2
 
3
3
  /**
4
4
  * - `conflict`: someone else changed the row since it was read. `current`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marktiderman/genesis-core",
3
- "version": "2.14.0",
3
+ "version": "2.16.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -104,6 +104,10 @@
104
104
  "types": "./dist/csv.d.ts",
105
105
  "import": "./dist/csv.js"
106
106
  },
107
+ "./headless": {
108
+ "types": "./dist/headless/index.d.ts",
109
+ "import": "./dist/headless/index.js"
110
+ },
107
111
  "./errors": {
108
112
  "types": "./dist/errors.d.ts",
109
113
  "import": "./dist/errors.js"
@@ -115,19 +119,19 @@
115
119
  "README.md"
116
120
  ],
117
121
  "peerDependencies": {
118
- "@hookform/resolvers": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0",
122
+ "@hookform/resolvers": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0",
119
123
  "@tanstack/react-query": "^5.0.0",
120
124
  "react": "^19.0.0",
121
125
  "react-hook-form": "^7.0.0",
122
126
  "zod": "^3.0.0 || ^4.0.0"
123
127
  },
124
128
  "devDependencies": {
125
- "@hookform/resolvers": "^6.0.0",
129
+ "@hookform/resolvers": "^7.0.1",
126
130
  "@tanstack/react-query": "^5.105.0",
127
131
  "@testing-library/react": "^16.3.2",
128
132
  "@types/react": "^19.2.14",
129
133
  "@types/react-dom": "^19.2.3",
130
- "fake-indexeddb": "6.2.5",
134
+ "fake-indexeddb": "6.2.7",
131
135
  "happy-dom": "^21.0.4",
132
136
  "react": "^19.0.0",
133
137
  "react-dom": "^19.0.0",
@@ -231,6 +235,12 @@
231
235
  "need": "write errors and refusals",
232
236
  "use": "DataWriteError and readFailureMessage",
233
237
  "import": "@marktiderman/genesis-core/errors"
238
+ },
239
+ {
240
+ "need": "an organization's own brand and defaults inside the app",
241
+ "use": "WorkspaceTheme's brand and defaults, read with resolveWorkspaceBrand and resolveWorkspaceAppearance",
242
+ "import": "@marktiderman/genesis-core/workspaces",
243
+ "docs": "https://github.com/marktiderman/genesis/blob/main/docs/adr/0024-who-sets-what.md"
234
244
  }
235
245
  ]
236
246
  }