@xh/hoist 89.0.1 → 89.2.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 (93) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/build/types/cmp/grid/GridModel.d.ts +6 -0
  3. package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
  4. package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
  5. package/build/types/core/XH.d.ts +2 -1
  6. package/build/types/core/model/HoistModel.d.ts +1 -0
  7. package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
  8. package/build/types/core/persist/PersistenceProvider.d.ts +3 -0
  9. package/build/types/data/cube/View.d.ts +0 -2
  10. package/build/types/data/cube/impl/RowCache.d.ts +1 -1
  11. package/build/types/data/cube/row/BaseRow.d.ts +5 -0
  12. package/build/types/desktop/cmp/dash/DashViewSpec.d.ts +2 -1
  13. package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
  14. package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
  15. package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
  16. package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -0
  17. package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
  18. package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
  19. package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
  20. package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
  21. package/build/types/svc/FetchService.d.ts +19 -0
  22. package/build/types/test-support/agGrid.d.ts +2 -0
  23. package/build/types/test-support/hoistCore.d.ts +7 -1
  24. package/build/types/test-support/index.d.ts +1 -0
  25. package/build/types/test-support/jsonBlobs.d.ts +130 -0
  26. package/build/types/test-support/testApp.d.ts +5 -2
  27. package/cmp/grid/Grid.ts +2 -2
  28. package/cmp/grid/GridModel.ts +14 -1
  29. package/cmp/grid/columns/Column.ts +3 -2
  30. package/cmp/input/impl/LiveCommas.ts +59 -0
  31. package/cmp/viewmanager/ViewManagerModel.ts +25 -7
  32. package/core/XH.ts +8 -3
  33. package/core/model/HoistModel.ts +4 -2
  34. package/core/model/Hooks.ts +1 -0
  35. package/core/model/ManagedRefreshContextModel.ts +5 -1
  36. package/core/persist/PersistenceProvider.ts +15 -1
  37. package/data/cube/View.ts +3 -9
  38. package/data/cube/impl/RowCache.ts +2 -2
  39. package/data/cube/row/BaseRow.ts +14 -1
  40. package/data/cube/row/ParentRow.ts +1 -1
  41. package/desktop/cmp/dash/DashViewSpec.ts +2 -1
  42. package/desktop/cmp/dash/README.md +6 -5
  43. package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
  44. package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
  45. package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
  46. package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
  47. package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
  48. package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
  49. package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
  50. package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
  51. package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
  52. package/desktop/cmp/input/NumberInput.ts +51 -12
  53. package/desktop/cmp/input/Select.ts +25 -7
  54. package/desktop/cmp/tab/TabSwitcher.ts +4 -6
  55. package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
  56. package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
  57. package/docs/README.md +2 -0
  58. package/docs/build-and-publish.md +21 -11
  59. package/docs/companion-library-docs.md +205 -0
  60. package/docs/doc-registry.json +9 -1
  61. package/docs/lifecycle-app.md +17 -0
  62. package/docs/lifecycle-models-and-services.md +2 -1
  63. package/docs/persistence.md +2 -0
  64. package/docs/telemetry.md +29 -0
  65. package/docs/unit-testing.md +54 -3
  66. package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
  67. package/docs/version-compatibility.md +2 -1
  68. package/icon/README.md +4 -1
  69. package/mcp/README.md +79 -4
  70. package/mcp/cli/docs.ts +75 -30
  71. package/mcp/data/doc-id-resolver.ts +50 -9
  72. package/mcp/data/doc-registry.ts +462 -44
  73. package/mcp/data/doc-search.ts +25 -6
  74. package/mcp/formatters/docs.ts +136 -36
  75. package/mcp/instructions.ts +69 -0
  76. package/mcp/resources/docs.ts +10 -8
  77. package/mcp/server.ts +7 -13
  78. package/mcp/tools/docs.ts +64 -18
  79. package/mcp/util/paths.ts +85 -2
  80. package/mobile/cmp/input/NumberInput.ts +42 -4
  81. package/package.json +19 -19
  82. package/public/msal-redirect-bridge.min.js +1 -1
  83. package/svc/FetchService.ts +38 -2
  84. package/svc/JsonBlobService.ts +7 -4
  85. package/svc/README.md +7 -3
  86. package/test-support/agGrid.ts +12 -2
  87. package/test-support/hoistCore.ts +32 -5
  88. package/test-support/index.ts +1 -0
  89. package/test-support/jsonBlobs.ts +543 -0
  90. package/test-support/setup.ts +8 -6
  91. package/test-support/testApp.ts +36 -7
  92. package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
  93. package/desktop/cmp/tab/impl/TabContextMenuItems.ts +0 -23
@@ -0,0 +1,543 @@
1
+ /*
2
+ * This file belongs to Hoist, an application development toolkit
3
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
4
+ *
5
+ * Copyright © 2026 Extremely Heavy Industries Inc.
6
+ */
7
+ import type {ViewUserState} from '@xh/hoist/cmp/viewmanager';
8
+ import type {PlainObject} from '@xh/hoist/core';
9
+ import type {JsonBlob} from '@xh/hoist/svc';
10
+ import {cloneDeep, forOwn, groupBy, has, isEmpty, isString, omit, pick} from 'lodash';
11
+ import type {FakeHoistCore, HoistError} from './hoistCore';
12
+
13
+ /*
14
+ * The fake hoist-core's JsonBlob store, and the two hoist-core services built on it:
15
+ * `JsonBlobService`, which `XH.jsonBlobService` calls through `XhController`, and `ViewService`,
16
+ * which `ViewManagerModel` calls through `XhViewController`. Views are blobs of the view manager's
17
+ * type. Each user's state for a type - current view, pins, auto-save - is one more blob of that
18
+ * type, named `xhUserState`.
19
+ *
20
+ * The fake answers as those services do, in the shapes `JsonBlob.formatForClient` renders. It lets
21
+ * a user read only the blobs they own or that are shared with all (`acl: '*'`), as the server does.
22
+ * It does not check write access or the uniqueness of names.
23
+ */
24
+
25
+ /** A JsonBlob as the fake stores it. `meta` is always an object, or null. */
26
+ export interface FakeJsonBlob extends JsonBlob {
27
+ meta: PlainObject;
28
+ }
29
+
30
+ /** A JsonBlob to add to the fake, with the fields `JsonBlobService.create` stores. */
31
+ export interface JsonBlobSpec {
32
+ type: string;
33
+ name: string;
34
+ /** Defaults to an empty object. */
35
+ value?: any;
36
+ /** Defaults to the current user. Pass `null` for a global blob. */
37
+ owner?: string;
38
+ /** `'*'` to let every user read the blob. */
39
+ acl?: '*';
40
+ meta?: PlainObject;
41
+ description?: string;
42
+ /** Defaults to a generated token. */
43
+ token?: string;
44
+ }
45
+
46
+ /** A ViewManager view to add to the fake, as `ViewService.create` stores it. */
47
+ export interface ViewSpec {
48
+ /** The `type` of the `ViewManagerModel` that loads the view. */
49
+ type: string;
50
+ name: string;
51
+ /** Defaults to an empty object. */
52
+ value?: PlainObject;
53
+ group?: string;
54
+ description?: string;
55
+ /** True to let every user read the view. */
56
+ isShared?: boolean;
57
+ /** True for a global view, which has no owner. */
58
+ isGlobal?: boolean;
59
+ /** Defaults to the current user. Ignored for a global view. */
60
+ owner?: string;
61
+ /** Defaults to a generated token. */
62
+ token?: string;
63
+ }
64
+
65
+ /**
66
+ * The JsonBlobs on the fake hoist-core, including ViewManager views and view state. Use the
67
+ * `hoistCore.jsonBlobs` instance. The store starts empty, so a `ViewManagerModel` loads no views
68
+ * and selects its in-code default.
69
+ */
70
+ export class FakeJsonBlobStore {
71
+ /**
72
+ * Roles that may write global blobs, by blob type, with `*` for any type not listed - as in
73
+ * hoist-core's `xhJsonBlobConfig`. A view manager reports `manageGlobal` from these and
74
+ * `hoistCore.roles`. List the role `*` to allow every user.
75
+ */
76
+ globalWriteRoles: Record<string, string[]>;
77
+
78
+ private blobs: FakeJsonBlob[] = [];
79
+ private nextId = 1;
80
+
81
+ constructor(private readonly core: FakeHoistCore) {
82
+ this.reset();
83
+ }
84
+
85
+ /** Add a blob, as `JsonBlobService.create` stores it. Returns the stored blob. */
86
+ add(spec: JsonBlobSpec): FakeJsonBlob {
87
+ const {username} = this.core,
88
+ {owner = username, acl = null, meta = null, description = null, value = {}} = spec;
89
+ return this.insert(
90
+ {type: spec.type, name: spec.name, owner, acl, meta, description, value},
91
+ spec.token
92
+ );
93
+ }
94
+
95
+ /** Add a ViewManager view, as `ViewService.create` stores it. Returns the stored blob. */
96
+ addView(spec: ViewSpec): FakeJsonBlob {
97
+ return this.insertView(spec, spec.owner ?? this.core.username, spec.token);
98
+ }
99
+
100
+ /**
101
+ * Set the current user's state for one view type, as `ViewService.updateState` saves it.
102
+ * Changes only the keys given.
103
+ *
104
+ * @param opts - `viewInstance`, the `instance` of the view manager whose current view is
105
+ * set. Defaults to 'default'.
106
+ */
107
+ setViewState(type: string, state: Partial<ViewUserState>, opts: {viewInstance?: string} = {}) {
108
+ const {viewInstance = 'default'} = opts,
109
+ blob =
110
+ this.findBlob(type, STATE_BLOB_NAME, this.core.username) ?? this.insertState(type),
111
+ value = blob.value;
112
+ if ('currentView' in state) {
113
+ value.currentView = {...value.currentView, [viewInstance]: state.currentView};
114
+ }
115
+ if ('userPinned' in state) value.userPinned = {...state.userPinned};
116
+ if ('autoSave' in state) value.autoSave = state.autoSave;
117
+ }
118
+
119
+ /** The current user's state for one view type, as the server sends it to a view manager. */
120
+ viewState(type: string, viewInstance: string = 'default'): ViewUserState {
121
+ return stateFromBlob(
122
+ this.findBlob(type, STATE_BLOB_NAME, this.core.username),
123
+ viewInstance
124
+ );
125
+ }
126
+
127
+ /**
128
+ * The stored blob with a token, archived or not. Change it to model an edit made elsewhere,
129
+ * e.g. advance `lastUpdated` to model a save by another session.
130
+ */
131
+ get(token: string): FakeJsonBlob {
132
+ return this.blobs.find(it => it.token === token) ?? null;
133
+ }
134
+
135
+ /** Remove every blob. */
136
+ clear() {
137
+ this.blobs = [];
138
+ }
139
+
140
+ /** @internal - empty the store and restore the default `globalWriteRoles`. */
141
+ reset() {
142
+ this.clear();
143
+ this.globalWriteRoles = {'*': ['HOIST_ADMIN']};
144
+ }
145
+
146
+ /**
147
+ * @internal - remove the current user's view state for every type, as hoist-core's
148
+ * `xh/clearUserState` does through `ViewService.clearAllState`.
149
+ */
150
+ clearViewState() {
151
+ const {username} = this.core;
152
+ this.blobs = this.blobs.filter(
153
+ it => !(it.name === STATE_BLOB_NAME && it.owner === username)
154
+ );
155
+ }
156
+
157
+ /** @internal - the endpoints served by `serve()`, relative to `XH.baseUrl`. */
158
+ get paths(): string[] {
159
+ return Object.keys(this.endpoints);
160
+ }
161
+
162
+ /**
163
+ * @internal - answer a request to one of `paths`. Returns the response body, or undefined for
164
+ * an empty 204. Throws a `FakeServerError` for an error response.
165
+ *
166
+ * @param params - the query string and form body merged, as Grails `params` read them.
167
+ * @param json - the parsed JSON body, if any.
168
+ */
169
+ serve(path: string, params: PlainObject, json: any): unknown {
170
+ return this.endpoints[path](params, json);
171
+ }
172
+
173
+ //------------------------
174
+ // Implementation
175
+ //------------------------
176
+ // XhController's JsonBlob actions and XhViewController's actions, by path.
177
+ private endpoints: Record<string, (params: PlainObject, json: any) => unknown> = {
178
+ 'xh/getJsonBlob': ({token}) => formatForClient(this.getBlob(token)),
179
+ 'xh/findJsonBlob': ({type, name, owner = null}) => {
180
+ const ret = this.findBlob(type, name, owner);
181
+ return ret ? formatForClient(ret) : null;
182
+ },
183
+ 'xh/listJsonBlobs': ({type, includeValue}) =>
184
+ this.listBlobs(type).map(it => formatForClient(it, includeValue === 'true')),
185
+ 'xh/createJsonBlob': ({data}) => formatForClient(this.createBlob(JSON.parse(data))),
186
+ 'xh/updateJsonBlob': ({token, update}) =>
187
+ formatForClient(this.updateBlob(this.getBlob(token), JSON.parse(update))),
188
+ 'xh/createOrUpdateJsonBlob': ({type, name, update}) =>
189
+ formatForClient(this.createOrUpdateBlob(type, name, JSON.parse(update))),
190
+ 'xh/archiveJsonBlob': ({token}) => formatForClient(this.archiveBlob(token)),
191
+
192
+ 'xhView/allData': ({type, viewInstance}) => this.getAllData(type, viewInstance),
193
+ 'xhView/updateState': ({type, viewInstance}, json) =>
194
+ this.updateState(type, viewInstance, json),
195
+ 'xhView/get': ({token}) => formatForClient(this.getBlob(token)),
196
+ 'xhView/create': (_, json) => this.createView(json),
197
+ 'xhView/delete': ({tokens}) => this.deleteViews(tokens.split(',')),
198
+ 'xhView/updateInfo': ({token}, json) => this.updateViewInfo(token, json),
199
+ 'xhView/bulkUpdateInfo': ({tokens}, json) =>
200
+ this.bulkUpdateViewInfo(tokens.split(','), json),
201
+ 'xhView/updateValue': ({token}, json) =>
202
+ formatForClient(this.updateBlob(this.getBlob(token), {value: json})),
203
+ 'xhView/renameGroup': ({type}, {from, to, isGlobal}) =>
204
+ this.renameGroup(type, isGlobal ? null : this.core.username, from, to)
205
+ };
206
+
207
+ //------------------------------------
208
+ // ViewService
209
+ //------------------------------------
210
+ private getAllData(type: string, viewInstance: string): PlainObject {
211
+ const blobs = this.listBlobs(type),
212
+ state = blobs.find(it => it.name === STATE_BLOB_NAME);
213
+ return {
214
+ state: stateFromBlob(state, viewInstance),
215
+ views: blobs.filter(it => it !== state).map(it => formatForClient(it, false)),
216
+ manageGlobal: this.canWriteGlobal(type)
217
+ };
218
+ }
219
+
220
+ private updateState(type: string, viewInstance: string, update: PlainObject): ViewUserState {
221
+ const {username} = this.core,
222
+ curr = this.findBlob(type, STATE_BLOB_NAME, username)?.value,
223
+ value = {
224
+ currentView: {...curr?.currentView},
225
+ userPinned: {...curr?.userPinned},
226
+ autoSave: curr?.autoSave ?? false
227
+ };
228
+
229
+ if ('currentView' in update) value.currentView[viewInstance] = update.currentView;
230
+ if ('userPinned' in update) Object.assign(value.userPinned, update.userPinned);
231
+ if ('autoSave' in update) value.autoSave = update.autoSave;
232
+
233
+ // Keep pins only for views that exist.
234
+ value.userPinned = pick(
235
+ value.userPinned,
236
+ this.listBlobs(type).map(it => it.token)
237
+ );
238
+
239
+ const blob = this.createOrUpdateBlob(type, STATE_BLOB_NAME, {value});
240
+ return stateFromBlob(blob, viewInstance);
241
+ }
242
+
243
+ private createView(data: PlainObject): JsonBlob {
244
+ const ret = this.insertView(data as ViewSpec, this.core.username);
245
+ if ('isPinned' in data) this.updatePinned(ret.type, [ret.token], data.isPinned);
246
+ return formatForClient(ret);
247
+ }
248
+
249
+ private updateViewInfo(token: string, data: PlainObject): JsonBlob {
250
+ const ret = this.applyViewInfo(token, data);
251
+ if ('isPinned' in data) this.updatePinned(ret.type, [ret.token], data.isPinned);
252
+ return formatForClient(ret);
253
+ }
254
+
255
+ // Best effort - updates every view it can, then reports the failures.
256
+ private bulkUpdateViewInfo(tokens: string[], data: PlainObject) {
257
+ const updated: FakeJsonBlob[] = [],
258
+ failures: Record<string, FakeServerError> = {};
259
+ tokens.forEach(token => {
260
+ try {
261
+ updated.push(this.applyViewInfo(token, data));
262
+ } catch (e) {
263
+ if (!(e instanceof FakeServerError)) throw e;
264
+ failures[token] = e;
265
+ }
266
+ });
267
+
268
+ if ('isPinned' in data) {
269
+ forOwn(groupBy(updated, 'type'), (blobs, type) =>
270
+ this.updatePinned(
271
+ type,
272
+ blobs.map(it => it.token),
273
+ data.isPinned
274
+ )
275
+ );
276
+ }
277
+
278
+ if (!isEmpty(failures)) {
279
+ const detail = Object.entries(failures)
280
+ .map(([token, e]) => `${token}: ${e.message}`)
281
+ .join('; ');
282
+ throw bulkFailure(
283
+ `Failed to update ${Object.keys(failures).length} of ${tokens.length} view(s) - ${detail}`,
284
+ Object.values(failures)
285
+ );
286
+ }
287
+ }
288
+
289
+ // Best effort - archives every view it can, then reports the failures.
290
+ private deleteViews(tokens: string[]) {
291
+ const failures: FakeServerError[] = [];
292
+ tokens.forEach(token => {
293
+ try {
294
+ this.archiveBlob(token);
295
+ } catch (e) {
296
+ if (!(e instanceof FakeServerError)) throw e;
297
+ failures.push(e);
298
+ }
299
+ });
300
+
301
+ if (failures.length) {
302
+ throw bulkFailure(
303
+ `Failed to delete ${failures.length} view(s) - ${failures[0].message}`,
304
+ failures
305
+ );
306
+ }
307
+ }
308
+
309
+ // ViewService.doUpdateInfo - name and description are blob fields, group lives in meta, and
310
+ // isShared and isGlobal set the owner, acl and meta together.
311
+ private applyViewInfo(token: string, data: PlainObject): FakeJsonBlob {
312
+ const blob = this.getBlob(token),
313
+ meta = {...blob.meta},
314
+ core: PlainObject = pick(data, ['name', 'description']);
315
+ if ('group' in data) meta.group = data.group;
316
+
317
+ if ('isGlobal' in data || 'isShared' in data) {
318
+ if (data.isGlobal) {
319
+ delete meta.isShared;
320
+ Object.assign(core, {owner: null, acl: '*'});
321
+ } else if (data.isShared) {
322
+ meta.isShared = data.isShared;
323
+ Object.assign(core, {owner: this.core.username, acl: '*'});
324
+ } else {
325
+ meta.isShared = false;
326
+ Object.assign(core, {owner: blob.owner || this.core.username, acl: null});
327
+ }
328
+ }
329
+
330
+ return this.updateBlob(blob, {...core, meta});
331
+ }
332
+
333
+ private updatePinned(type: string, tokens: string[], isPinned: boolean) {
334
+ const userPinned = Object.fromEntries(tokens.map(it => [it, isPinned]));
335
+ this.updateState(type, 'default', {userPinned});
336
+ }
337
+
338
+ private insertView(spec: ViewSpec, owner: string, token?: string): FakeJsonBlob {
339
+ const {
340
+ type,
341
+ name,
342
+ description = null,
343
+ group = null,
344
+ isShared = null,
345
+ isGlobal,
346
+ value = {}
347
+ } = spec;
348
+ return this.insert(
349
+ {
350
+ type,
351
+ name,
352
+ description,
353
+ owner: isGlobal ? null : owner,
354
+ acl: isGlobal || isShared ? '*' : null,
355
+ meta: isGlobal ? {group} : {group, isShared},
356
+ value
357
+ },
358
+ token
359
+ );
360
+ }
361
+
362
+ private insertState(type: string): FakeJsonBlob {
363
+ const value = {currentView: {}, userPinned: {}, autoSave: false};
364
+ return this.createBlob({type, name: STATE_BLOB_NAME, value});
365
+ }
366
+
367
+ //------------------------------------
368
+ // JsonBlobService
369
+ //------------------------------------
370
+ // An active blob the user can read.
371
+ private getBlob(token: string): FakeJsonBlob {
372
+ const ret = this.blobs.find(it => it.token === token && !it.archived);
373
+ if (!ret) throw notFound(token);
374
+ this.ensureReadable(ret);
375
+ return ret;
376
+ }
377
+
378
+ // An active blob by type, name and owner - a null owner matches only global blobs.
379
+ private findBlob(type: string, name: string, owner: string): FakeJsonBlob {
380
+ const ret = this.blobs.find(
381
+ it => it.type === type && it.name === name && it.owner === owner && !it.archived
382
+ );
383
+ if (ret) this.ensureReadable(ret);
384
+ return ret ?? null;
385
+ }
386
+
387
+ private listBlobs(type: string): FakeJsonBlob[] {
388
+ return this.blobs.filter(it => it.type === type && !it.archived && this.canRead(it));
389
+ }
390
+
391
+ private createBlob(data: PlainObject): FakeJsonBlob {
392
+ const {username} = this.core;
393
+ return this.insert({
394
+ owner: username,
395
+ acl: null,
396
+ meta: null,
397
+ description: null,
398
+ ...pick(data, CREATABLE_FIELDS)
399
+ });
400
+ }
401
+
402
+ // Applies the updatable fields given. An empty update changes nothing, not even the stamp.
403
+ private updateBlob(blob: FakeJsonBlob, data: PlainObject): FakeJsonBlob {
404
+ if (isEmpty(data)) return blob;
405
+ Object.assign(blob, cloneDeep(pick(data, UPDATABLE_FIELDS)), {
406
+ lastUpdated: Date.now(),
407
+ lastUpdatedBy: this.core.username
408
+ });
409
+ return blob;
410
+ }
411
+
412
+ private createOrUpdateBlob(type: string, name: string, data: PlainObject): FakeJsonBlob {
413
+ const blob = this.findBlob(type, name, this.core.username);
414
+ return blob ? this.updateBlob(blob, data) : this.createBlob({...data, type, name});
415
+ }
416
+
417
+ // Soft delete, recorded against the authenticated user - the admin, when impersonating.
418
+ private archiveBlob(token: string): FakeJsonBlob {
419
+ const blob = this.getBlob(token),
420
+ now = Date.now();
421
+ return Object.assign(blob, {
422
+ archived: true,
423
+ archivedDate: now,
424
+ lastUpdated: now,
425
+ lastUpdatedBy: this.core.authUser?.username ?? this.core.username
426
+ });
427
+ }
428
+
429
+ // Rewrites the group, and every group nested under it, of the active blobs of one owner -
430
+ // null for global blobs.
431
+ private renameGroup(type: string, owner: string, from: string, to: string): PlainObject {
432
+ from = from?.trim();
433
+ to = to?.trim();
434
+ let count = 0;
435
+ this.blobs.forEach(blob => {
436
+ const group = blob.meta?.group;
437
+ if (blob.type !== type || blob.owner !== owner || blob.archived) return;
438
+ if (!isString(group) || (group !== from && !group.startsWith(from + '/'))) return;
439
+
440
+ const renamed = to + group.substring(from.length);
441
+ if (renamed === group) return;
442
+ blob.meta.group = renamed;
443
+ Object.assign(blob, {lastUpdated: Date.now(), lastUpdatedBy: this.core.username});
444
+ count++;
445
+ });
446
+ return {count};
447
+ }
448
+
449
+ private canRead(blob: FakeJsonBlob): boolean {
450
+ return blob.acl === '*' || blob.owner === this.core.username;
451
+ }
452
+
453
+ private ensureReadable(blob: FakeJsonBlob) {
454
+ if (!this.canRead(blob)) throw notAuthorized(this.core.username, blob.token);
455
+ }
456
+
457
+ // A type's own entry in globalWriteRoles, even an empty one, replaces the `*` fallback.
458
+ private canWriteGlobal(type: string): boolean {
459
+ const {globalWriteRoles} = this,
460
+ required = has(globalWriteRoles, type) ? globalWriteRoles[type] : globalWriteRoles['*'];
461
+ if (isEmpty(required)) return false;
462
+ return required.includes('*') || required.some(it => this.core.roles.includes(it));
463
+ }
464
+
465
+ private insert(fields: PlainObject, token: string = this.newToken()): FakeJsonBlob {
466
+ const now = Date.now(),
467
+ ret = {
468
+ ...cloneDeep(fields),
469
+ id: this.nextId++,
470
+ token,
471
+ archived: false,
472
+ archivedDate: 0,
473
+ dateCreated: now,
474
+ lastUpdated: now,
475
+ lastUpdatedBy: this.core.username
476
+ } as FakeJsonBlob;
477
+ this.blobs.push(ret);
478
+ return ret;
479
+ }
480
+
481
+ // hoist-core generates 8-character tokens. Skips any token a spec has already used.
482
+ private newToken(): string {
483
+ let seq = this.nextId,
484
+ ret: string;
485
+ do {
486
+ ret = 'tok' + String(seq++).padStart(5, '0');
487
+ } while (this.get(ret));
488
+ return ret;
489
+ }
490
+ }
491
+
492
+ /**
493
+ * @internal - an error that the fake renders as hoist-core would, with `hoistError()`.
494
+ */
495
+ export class FakeServerError extends Error {
496
+ constructor(
497
+ readonly status: number,
498
+ readonly error: HoistError
499
+ ) {
500
+ super(error.message);
501
+ }
502
+ }
503
+
504
+ //------------------------
505
+ // Implementation
506
+ //------------------------
507
+ const STATE_BLOB_NAME = 'xhUserState',
508
+ UPDATABLE_FIELDS = ['name', 'description', 'value', 'meta', 'owner', 'acl'],
509
+ CREATABLE_FIELDS = ['type', ...UPDATABLE_FIELDS];
510
+
511
+ // JsonBlob.formatForClient - a copy, so later changes to the store do not reach the client.
512
+ function formatForClient(blob: JsonBlob, includeValue: boolean = true): JsonBlob {
513
+ const ret = cloneDeep(blob);
514
+ return includeValue ? ret : (omit(ret, 'value') as JsonBlob);
515
+ }
516
+
517
+ // ViewService.getStateFromBlob - `currentView` is sent only once saved for the instance.
518
+ function stateFromBlob(blob: FakeJsonBlob, viewInstance: string): ViewUserState {
519
+ const raw = blob?.value,
520
+ ret: ViewUserState = {userPinned: {...raw?.userPinned}, autoSave: raw?.autoSave ?? false};
521
+ if (has(raw?.currentView, viewInstance)) ret.currentView = raw.currentView[viewInstance];
522
+ return ret;
523
+ }
524
+
525
+ // JsonBlobService.get - a RuntimeException, rendered as a 500.
526
+ function notFound(token: string): FakeServerError {
527
+ return new FakeServerError(500, {message: `Active JsonBlob not found with token '${token}'`});
528
+ }
529
+
530
+ function notAuthorized(username: string, token: string): FakeServerError {
531
+ return new FakeServerError(403, {
532
+ name: 'NotAuthorizedException',
533
+ message: `User '${username}' does not have access to JsonBlob with token '${token}'`,
534
+ isRoutine: true
535
+ });
536
+ }
537
+
538
+ // ViewService.bulkFailure - routine only if every failure was routine.
539
+ function bulkFailure(message: string, failures: FakeServerError[]): FakeServerError {
540
+ return failures.every(it => it.error.isRoutine)
541
+ ? new FakeServerError(400, {name: 'RoutineRuntimeException', message, isRoutine: true})
542
+ : new FakeServerError(500, {message, cause: failures[0].message});
543
+ }
@@ -66,6 +66,11 @@ document.documentElement.style.transitionDuration = '0s';
66
66
  //------------------------------------------------------------------
67
67
  const problems: string[] = [];
68
68
 
69
+ // Every guard reports through hoistCore.onProblem(), so that initTestAppAsync() can collect the
70
+ // problems raised during boot and fail the boot instead. The fake also reports an error thrown by a
71
+ // route added with hoistCore.route() - the client sees a 500.
72
+ hoistCore.onProblem = msg => problems.push(msg);
73
+
69
74
  // A request or WebSocket with no handler. Hoist services often catch and log network errors, so a
70
75
  // failed request alone would not fail the test. Throwing makes MSW fail the request - a callback
71
76
  // that returns normally lets it through to the real network.
@@ -75,7 +80,7 @@ function onUnhandledFrame({frame}: {frame: {data: unknown}}): never {
75
80
  ? `${request.method} ${request.url}`
76
81
  : `WebSocket ${connection.client.url}`,
77
82
  msg = `Not handled by fake hoist-core: ${target}`;
78
- problems.push(msg);
83
+ hoistCore.onProblem(msg);
79
84
  throw new Error(msg);
80
85
  }
81
86
 
@@ -85,17 +90,14 @@ interface FrameData {
85
90
  connection?: {client: {url: URL}};
86
91
  }
87
92
 
88
- // An error thrown by a route added with hoistCore.route(). The client sees a 500.
89
- hoistCore.onProblem = msg => problems.push(msg);
90
-
91
93
  // An error thrown inside a MobX reaction or autorun. MobX catches and logs these.
92
- onReactionError(e => problems.push(`Error in MobX reaction: ${e}`));
94
+ onReactionError(e => hoistCore.onProblem(`Error in MobX reaction: ${e}`));
93
95
 
94
96
  // A MobX strict-mode warning - Hoist sets `enforceActions: 'observed'`, so this flags observable
95
97
  // state changed outside an action.
96
98
  const consoleWarn = console.warn;
97
99
  console.warn = (...args: any[]) => {
98
- if (String(args[0]).startsWith('[MobX]')) problems.push(String(args[0]));
100
+ if (String(args[0]).startsWith('[MobX]')) hoistCore.onProblem(String(args[0]));
99
101
  consoleWarn(...args);
100
102
  };
101
103
 
@@ -7,6 +7,7 @@
7
7
  import {AppSpec, HoistAppModel, XH} from '@xh/hoist/core';
8
8
  import {when} from 'mobx';
9
9
  import {vi} from 'vitest';
10
+ import {hoistCore} from './hoistCore';
10
11
 
11
12
  export type TestAppSpec = Partial<ConstructorParameters<typeof AppSpec>[0]>;
12
13
 
@@ -21,8 +22,11 @@ export type TestAppSpec = Partial<ConstructorParameters<typeof AppSpec>[0]>;
21
22
  * graph, and with it a fresh `XH`. Adjust `hoistCore` state first to boot against other server
22
23
  * data (e.g. `hoistCore.configs.myConfig = 42`).
23
24
  *
24
- * Resolves once the app is `RUNNING`. Rejects, naming `XH.appState`, if boot stops anywhere else -
25
- * `ACCESS_DENIED`, `LOAD_FAILED`, or `LOGIN_REQUIRED`, where boot waits for the user to sign in.
25
+ * Resolves once the app is `RUNNING` and the requests boot started have finished. Rejects, naming
26
+ * `XH.appState`, if boot stops anywhere else - `ACCESS_DENIED`, `LOAD_FAILED`, or
27
+ * `LOGIN_REQUIRED`, where boot waits for the user to sign in. Also rejects if boot triggers a
28
+ * problem that the kit's guards catch, such as a request the fake does not handle. Logs any error
29
+ * that the app handles during boot.
26
30
  *
27
31
  * @param spec - overrides for the test app's `AppSpec`. Defaults to a desktop app with a minimal
28
32
  * app model, open to any user. Pass `checkAccess` to require a role.
@@ -47,22 +51,47 @@ export async function initTestAppAsync(spec: TestAppSpec = {}): Promise<void> {
47
51
  });
48
52
 
49
53
  // initAsync() reports a failed boot via XH.handleException - capture it to fail loudly here.
54
+ // Log each call instead of showing it, as an app may handle an error at boot on purpose.
50
55
  // Read the reported error before restoring the spy, which clears its recorded calls.
51
56
  // At LOGIN_REQUIRED, initAsync() waits for a sign-in that never comes, so stop waiting there.
52
- const handleException = vi.spyOn(XH, 'handleException').mockImplementation(() => {}),
57
+ const handleException = vi
58
+ .spyOn(XH, 'handleException')
59
+ .mockImplementation(e => console.error('Error handled during test app boot:', e)),
53
60
  loginRequired = when(() => XH.appState === 'LOGIN_REQUIRED');
61
+
62
+ // Take the problems the kit's guards catch during boot, to fail the boot rather than the
63
+ // file's first test.
64
+ const bootProblems: string[] = [],
65
+ {onProblem} = hoistCore;
66
+ hoistCore.onProblem = msg => bootProblems.push(msg);
67
+
54
68
  let cause: unknown;
55
69
  try {
56
- await Promise.race([acm.initAsync(), loginRequired]);
70
+ try {
71
+ await Promise.race([acm.initAsync(), loginRequired]);
72
+ } finally {
73
+ loginRequired.cancel();
74
+ // A failed boot reports its error last - any before it, the app handled.
75
+ cause = handleException.mock.calls.at(-1)?.[0];
76
+ handleException.mockRestore();
77
+ }
78
+ // Let requests that boot started without awaiting finish now, so none lands in the first
79
+ // test's request log.
80
+ await hoistCore.settleAsync().catch(e => bootProblems.push(e.message));
57
81
  } finally {
58
- loginRequired.cancel();
59
- cause = handleException.mock.calls[0]?.[0];
60
- handleException.mockRestore();
82
+ hoistCore.onProblem = onProblem;
61
83
  }
62
84
 
63
85
  if (XH.appState !== 'RUNNING') {
64
86
  throw new Error(`Test app failed to start - state is '${XH.appState}'`, {cause});
65
87
  }
88
+
89
+ if (bootProblems.length) {
90
+ const msg = bootProblems.join('\n');
91
+ throw new Error(
92
+ `Test app triggered problems during boot that Hoist would otherwise swallow:\n${msg}`
93
+ );
94
+ }
66
95
  }
67
96
 
68
97
  /** Default app model for test apps. */
@@ -1,4 +0,0 @@
1
- import { TabSwitcherMenuContext } from '@xh/hoist/cmp/tab';
2
- import { type MenuItemLike, MenuToken } from '@xh/hoist/core';
3
- /** @internal */
4
- export declare function getContextMenuItem(item: MenuItemLike<MenuToken, TabSwitcherMenuContext>, context: TabSwitcherMenuContext): MenuItemLike<MenuToken, TabSwitcherMenuContext>;
@@ -1,23 +0,0 @@
1
- /*
2
- * This file belongs to Hoist, an application development toolkit
3
- * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
4
- *
5
- * Copyright © 2026 Extremely Heavy Industries Inc.
6
- */
7
- import {TabSwitcherMenuContext} from '@xh/hoist/cmp/tab';
8
- import {isMenuHeading, isMenuItem, type MenuItemLike, MenuToken} from '@xh/hoist/core';
9
- import {bindMenuHeadingContext} from '@xh/hoist/cmp/menu/impl/Menus';
10
-
11
- /** @internal */
12
- export function getContextMenuItem(
13
- item: MenuItemLike<MenuToken, TabSwitcherMenuContext>,
14
- context: TabSwitcherMenuContext
15
- ): MenuItemLike<MenuToken, TabSwitcherMenuContext> {
16
- if (isMenuHeading(item)) return bindMenuHeadingContext(item, context);
17
- if (!isMenuItem(item)) return item;
18
- const ret = {...item};
19
- if (item.actionFn) ret.actionFn = e => item.actionFn(e, context);
20
- if (item.prepareFn) ret.prepareFn = e => item.prepareFn(e, context);
21
- if (item.items) ret.items = item.items.map(it => this.buildMenuItem(it, context));
22
- return ret;
23
- }