@xh/hoist 89.0.1 → 89.1.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 (59) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
  3. package/build/types/core/model/HoistModel.d.ts +1 -0
  4. package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
  5. package/build/types/data/cube/View.d.ts +0 -2
  6. package/build/types/data/cube/impl/RowCache.d.ts +1 -1
  7. package/build/types/data/cube/row/BaseRow.d.ts +5 -0
  8. package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
  9. package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
  10. package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
  11. package/build/types/test-support/agGrid.d.ts +2 -0
  12. package/build/types/test-support/hoistCore.d.ts +7 -1
  13. package/build/types/test-support/index.d.ts +1 -0
  14. package/build/types/test-support/jsonBlobs.d.ts +130 -0
  15. package/build/types/test-support/testApp.d.ts +5 -2
  16. package/cmp/grid/columns/Column.ts +1 -1
  17. package/cmp/input/impl/LiveCommas.ts +59 -0
  18. package/core/model/HoistModel.ts +4 -2
  19. package/core/model/Hooks.ts +1 -0
  20. package/core/model/ManagedRefreshContextModel.ts +5 -1
  21. package/data/cube/View.ts +3 -9
  22. package/data/cube/impl/RowCache.ts +2 -2
  23. package/data/cube/row/BaseRow.ts +14 -1
  24. package/data/cube/row/ParentRow.ts +1 -1
  25. package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
  26. package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
  27. package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
  28. package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
  29. package/desktop/cmp/input/NumberInput.ts +51 -12
  30. package/desktop/cmp/input/Select.ts +25 -7
  31. package/docs/README.md +2 -0
  32. package/docs/companion-library-docs.md +205 -0
  33. package/docs/doc-registry.json +8 -0
  34. package/docs/lifecycle-app.md +17 -0
  35. package/docs/unit-testing.md +54 -3
  36. package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
  37. package/docs/version-compatibility.md +2 -1
  38. package/icon/README.md +4 -1
  39. package/mcp/README.md +79 -4
  40. package/mcp/cli/docs.ts +75 -30
  41. package/mcp/data/doc-id-resolver.ts +50 -9
  42. package/mcp/data/doc-registry.ts +462 -44
  43. package/mcp/data/doc-search.ts +25 -6
  44. package/mcp/formatters/docs.ts +136 -36
  45. package/mcp/instructions.ts +69 -0
  46. package/mcp/resources/docs.ts +10 -8
  47. package/mcp/server.ts +7 -13
  48. package/mcp/tools/docs.ts +64 -18
  49. package/mcp/util/paths.ts +85 -2
  50. package/mobile/cmp/input/NumberInput.ts +42 -4
  51. package/package.json +19 -19
  52. package/public/msal-redirect-bridge.min.js +1 -1
  53. package/svc/JsonBlobService.ts +7 -4
  54. package/test-support/agGrid.ts +12 -2
  55. package/test-support/hoistCore.ts +32 -5
  56. package/test-support/index.ts +1 -0
  57. package/test-support/jsonBlobs.ts +543 -0
  58. package/test-support/setup.ts +8 -6
  59. package/test-support/testApp.ts +36 -7
@@ -25,14 +25,17 @@ import {ForwardedRef, ReactElement, useCallback} from 'react';
25
25
  * @param component - ElementFactory for HoistInput to render.
26
26
  * @param props - props passed to containing component
27
27
  * @param ref - forwardRef passed to containing component
28
+ * @param applyInitialKey - applies a printable key that started the edit to the focused input.
29
+ * Defaults to entering the key as the input's value.
28
30
  */
29
31
  export function useInlineEditorModel(
30
32
  component: ElementFactory,
31
33
  props: EditorProps<any>,
32
- ref: ForwardedRef<any>
34
+ ref: ForwardedRef<any>,
35
+ applyInitialKey: InitialKeyFn = (input, key) => input.noteValueChange(key)
33
36
  ): ReactElement {
34
37
  const {className, inputProps, agParams, gridModel} = props,
35
- impl = useLocalModel(() => new InlineEditorModel(agParams, gridModel));
38
+ impl = useLocalModel(() => new InlineEditorModel(agParams, gridModel, applyInitialKey));
36
39
 
37
40
  useGridCellEditor({
38
41
  // This is called in full-row editing when the user tabs into the cell
@@ -62,6 +65,9 @@ export function useInlineEditorModel(
62
65
  });
63
66
  }
64
67
 
68
+ /** Applies the printable key that started an edit to the editor's focused input. */
69
+ export type InitialKeyFn = (input: HoistInputModel, key: string) => void;
70
+
65
71
  /**
66
72
  * Local Model supporting inline cell editor components. Provides base functionality required by
67
73
  * ag-grid plus extension points for editors needing more complex behaviors.
@@ -76,15 +82,21 @@ class InlineEditorModel extends HoistModel {
76
82
  ref = createObservableRef<HoistInputModel>();
77
83
 
78
84
  agParams: CustomCellEditorProps;
85
+ applyInitialKey: InitialKeyFn;
79
86
 
80
87
  get inputEl() {
81
88
  return this.ref.current?.inputEl;
82
89
  }
83
90
 
84
- constructor(agParams: CustomCellEditorProps, gridModel: GridModel) {
91
+ constructor(
92
+ agParams: CustomCellEditorProps,
93
+ gridModel: GridModel,
94
+ applyInitialKey: InitialKeyFn
95
+ ) {
85
96
  super();
86
97
 
87
98
  this.agParams = agParams;
99
+ this.applyInitialKey = applyInitialKey;
88
100
  this.value = agParams.value;
89
101
 
90
102
  // Focus into the input once the component is rendered. With full row editing, multiple
@@ -104,9 +116,9 @@ class InlineEditorModel extends HoistModel {
104
116
  inputEl.focus();
105
117
 
106
118
  const {eventKey} = this.agParams;
107
- // Enter initial keystroke in value (if single char and not special key e.g (F2 or Enter).
119
+ // Apply initial keystroke (if single char and not special key e.g (F2 or Enter).
108
120
  if (eventKey?.length === 1) {
109
- ref.current.noteValueChange(eventKey);
121
+ this.applyInitialKey(ref.current, eventKey);
110
122
  } else {
111
123
  inputEl.select();
112
124
  }
@@ -11,15 +11,21 @@ import {
11
11
  PasswordManagerSupportProps,
12
12
  useHoistInputModel
13
13
  } from '@xh/hoist/cmp/input';
14
+ import {
15
+ addCommasWhileEditing,
16
+ getCaretSkippingCommas,
17
+ setCaretSkippingCommas,
18
+ skipCommaOnDelete
19
+ } from '@xh/hoist/cmp/input/impl/LiveCommas';
14
20
  import {hoistCmp, HoistProps, LayoutProps, StyleProps} from '@xh/hoist/core';
15
21
  import '@xh/hoist/desktop/register';
16
22
  import {fmtNumber, NumericPrecision, parseNumber, Precision, ZeroPad} from '@xh/hoist/format';
17
23
  import {numericInput} from '@xh/hoist/kit/blueprint';
18
24
  import {wait} from '@xh/hoist/promise';
19
25
  import {TEST_ID, throwIf, withDefault} from '@xh/hoist/utils/js';
20
- import {useComposedRefs, getLayoutProps} from '@xh/hoist/utils/react';
26
+ import {getLayoutProps, useComposedRefs, useOnMount} from '@xh/hoist/utils/react';
21
27
  import type {Property} from 'csstype';
22
- import {debounce, isNaN, isNil, isNumber, round} from 'lodash';
28
+ import {clamp, debounce, isNaN, isNil, isNumber, round} from 'lodash';
23
29
  import {KeyboardEventHandler, ReactElement, ReactNode, Ref, useLayoutEffect} from 'react';
24
30
 
25
31
  export interface NumberInputProps
@@ -32,8 +38,11 @@ export interface NumberInputProps
32
38
  /** True to commit on every change/keystroke, default false. */
33
39
  commitOnChange?: boolean;
34
40
 
35
- /** True to insert commas in displayed value. */
36
- displayWithCommas?: boolean;
41
+ /**
42
+ * Insert commas in displayed value - 'whenBlurred' (or true) to show them only when the input
43
+ * does not have focus, 'always' to also show them while the user types.
44
+ */
45
+ displayWithCommas?: boolean | 'always' | 'whenBlurred';
37
46
 
38
47
  /** True to convert entries suffixed with k/m/b to thousands/millions/billions. */
39
48
  enableShorthandUnits?: boolean;
@@ -147,7 +156,16 @@ class NumberInputModel extends HoistInputModel {
147
156
  return withDefault(this.componentProps.scaleFactor, 1);
148
157
  }
149
158
 
159
+ get commasWhileEditing(): boolean {
160
+ return this.componentProps.displayWithCommas === 'always';
161
+ }
162
+
163
+ // Caret position to restore after a reformat while editing, as a count of non-comma chars.
164
+ caretPos: number = null;
165
+
150
166
  onValueChange = (val, valAsString) => {
167
+ if (this.commasWhileEditing)
168
+ this.caretPos = getCaretSkippingCommas(this.inputEl as HTMLInputElement);
151
169
  this.noteValueChange(valAsString);
152
170
  };
153
171
 
@@ -187,7 +205,7 @@ class NumberInputModel extends HoistInputModel {
187
205
  if (isNaN(val)) return false;
188
206
  if (val === null) return true;
189
207
 
190
- // Enforce min/max here on commit. BP props only limit the incremental step change
208
+ // Hoist owns min/max, checking the parsed value - see clampSteppedValue().
191
209
  if (!isNil(min) && val < min) return false;
192
210
  if (!isNil(max) && val > max) return false;
193
211
 
@@ -196,9 +214,24 @@ class NumberInputModel extends HoistInputModel {
196
214
 
197
215
  onKeyDown: KeyboardEventHandler<HTMLInputElement> = ev => {
198
216
  if (ev.key === 'Enter') this.doCommit();
217
+ if (ev.key === 'ArrowUp' || ev.key === 'ArrowDown') this.clampSteppedValue();
199
218
  this.componentProps.onKeyDown?.(ev);
200
219
  };
201
220
 
221
+ onBeforeInput = (ev: InputEvent) => {
222
+ if (this.commasWhileEditing) skipCommaOnDelete(ev);
223
+ };
224
+
225
+ // BP steps the value on arrow keys without applying min/max - clamp the stepped value.
226
+ private clampSteppedValue() {
227
+ const {min, max} = this.componentProps,
228
+ val = this.toExternal(this.internalValue);
229
+ if (!isNumber(val) || isNaN(val)) return;
230
+
231
+ const clamped = clamp(val, min ?? -Infinity, max ?? Infinity);
232
+ if (clamped !== val) this.noteValueChange(this.toInternal(clamped));
233
+ }
234
+
202
235
  formatRenderValue(value: number) {
203
236
  const {componentProps, precision} = this;
204
237
 
@@ -206,7 +239,9 @@ class NumberInputModel extends HoistInputModel {
206
239
 
207
240
  if (this.hasFocus) {
208
241
  const ret = isNumber(value) && !isNil(precision) ? round(value, precision) : value;
209
- return ret?.toString();
242
+ return this.commasWhileEditing
243
+ ? addCommasWhileEditing(ret.toString())
244
+ : ret?.toString();
210
245
  }
211
246
 
212
247
  const {valueLabel, displayWithCommas} = componentProps,
@@ -240,13 +275,17 @@ const cmp = hoistCmp.factory<NumberInputModel>(({model, className, ...props}, re
240
275
  const {width, flex, ...layoutProps} = getLayoutProps(props),
241
276
  renderValue = model.formatRenderValue(model.renderValue);
242
277
 
243
- // BP workaround -- min, max, and stepsize can block Blueprint from rendering
244
- // intended value in underlying control -- ensure it is always shown.
278
+ // Restore the caret after a reformat while editing moved it.
245
279
  useLayoutEffect(() => {
246
- const input = model.inputEl;
247
- if (input) input.value = renderValue;
280
+ const input = model.inputEl as HTMLInputElement;
281
+ if (!input || model.caretPos == null) return;
282
+ setCaretSkippingCommas(input, model.caretPos);
283
+ model.caretPos = null;
248
284
  });
249
285
 
286
+ // Native listener, as React's onBeforeInput does not fire for deletes.
287
+ useOnMount(() => model.inputEl?.addEventListener('beforeinput', model.onBeforeInput));
288
+
250
289
  // BP bases expected precision off of dps in minorStepSize, if specified.
251
290
  // The default BP value of 0.1 for this prop emits a console warning any time the input
252
291
  // value extends beyond 1 dp. Re-default here to sync with our `precision` prop.
@@ -265,8 +304,8 @@ const cmp = hoistCmp.factory<NumberInputModel>(({model, className, ...props}, re
265
304
  disabled: props.disabled,
266
305
  inputRef: useComposedRefs(model.inputRef as Ref<HTMLInputElement>, props.inputRef),
267
306
  leftIcon: props.leftIcon,
268
- min: props.min,
269
- max: props.max,
307
+ // Lets BP parse a comma-formatted value when stepping with the arrow keys.
308
+ locale: model.commasWhileEditing ? 'en-US' : undefined,
270
309
  minorStepSize,
271
310
  majorStepSize,
272
311
  placeholder: props.placeholder,
@@ -414,18 +414,36 @@ class SelectInputModel extends HoistInputModel {
414
414
  super.noteFocused();
415
415
  }
416
416
 
417
- private selectText() {
418
- const {reactSelect} = this;
419
- if (!reactSelect) return;
417
+ /**
418
+ * Enter text into the search input and open the menu, as if typed by the user.
419
+ * Ignored if the select is not searchable.
420
+ */
421
+ enterSearchText(text: string) {
422
+ // Delay to run after the text selection scheduled by `noteFocused()`.
423
+ wait().then(() => {
424
+ const selectComp = this.innerSelect;
425
+ if (!this.hasFocus || !selectComp?.props.isSearchable) return;
426
+
427
+ selectComp.props.onInputChange(text, {
428
+ action: 'input-change',
429
+ prevInputValue: selectComp.props.inputValue ?? ''
430
+ });
431
+ selectComp.openMenu('first');
432
+ });
433
+ }
420
434
 
421
- // Unwrap the HOCs added by AsyncSelect / Creatable / WindowedSelect (each exposes the
422
- // inner Select via `.select`) to reach the underlying Select that owns the inputRef.
423
- let selectComp = reactSelect;
435
+ // Unwrap the HOCs added by AsyncSelect / Creatable / WindowedSelect (each exposes the inner
436
+ // Select via `.select`) to reach the underlying Select that owns the inputRef.
437
+ private get innerSelect() {
438
+ let selectComp = this.reactSelect;
424
439
  while (selectComp && !selectComp.inputRef) {
425
440
  selectComp = selectComp.select;
426
441
  }
427
- const inputElem = selectComp?.inputRef;
442
+ return selectComp;
443
+ }
428
444
 
445
+ private selectText() {
446
+ const inputElem = this.innerSelect?.inputRef;
429
447
  if (this.hasFocus && inputElem && document.activeElement === inputElem) {
430
448
  inputElem.select();
431
449
  }
package/docs/README.md CHANGED
@@ -64,6 +64,7 @@ See [`docs-roadmap.md`](./planning/docs-roadmap.md) for documentation coverage t
64
64
  | Configure local development environment | [Development Environment](./development-environment.md) |
65
65
  | Write or run unit tests, in an app or hoist-react | [Unit Testing](./unit-testing.md) |
66
66
  | Use MCP tools with AI assistants | [`/mcp/`](../mcp/README.md) |
67
+ | Serve a Hoist library's docs through the MCP tools | [Companion Library Docs](./companion-library-docs.md) |
67
68
  | Customize colors, fonts, spacing, or theme | [`/styles/`](../styles/README.md) |
68
69
  | Follow XH coding conventions | [Coding Conventions](./coding-conventions.md) |
69
70
  | Check hoist-react / hoist-core / hoist-dev-utils version compatibility | [Version Compatibility](./version-compatibility.md) |
@@ -158,6 +159,7 @@ for planned coverage:
158
159
  | Tool | Description |
159
160
  |------|-------------|
160
161
  | [MCP Server](../mcp/README.md) | Model Context Protocol server providing AI assistants with structured access to documentation, TypeScript types, and code generation prompts |
162
+ | [Companion Library Docs](./companion-library-docs.md) | How a library that builds on Hoist serves its docs through the MCP server and `hoist-docs` CLI, using a `hoist.docRegistry` field in its `package.json` |
161
163
 
162
164
  ## Upgrade Notes
163
165
 
@@ -0,0 +1,205 @@
1
+ # Companion Library Docs
2
+
3
+ A companion library is an npm package that builds on Hoist. Examples are `@xh/hoist-chat-kit` and
4
+ a client firm's shared package of Hoist overrides and components. Such a library can serve its own
5
+ docs through the hoist-react MCP server and the `hoist-docs` CLI. It needs no MCP server or CLI of
6
+ its own.
7
+
8
+ The library declares a doc registry in its `package.json`. When an app installs the library, the
9
+ hoist-react tools find the registry and serve its docs next to Hoist's own. Agents search, list, and
10
+ read them with the same tools, and the server instructions tell agents that the library exists.
11
+
12
+ ## How It Works
13
+
14
+ 1. The tools find the app's `package.json`. See [Discovery](#discovery).
15
+ 2. They check the app package and each of its direct `dependencies` and `devDependencies` for a
16
+ `hoist.docRegistry` field.
17
+ 3. They load each declared registry and prefix its doc ids with the package name. For example,
18
+ `core/README.md` in `@acme/hoist-acme` becomes `@acme/hoist-acme/core/README.md`.
19
+ 4. They merge those docs into one search index with Hoist's docs.
20
+ 5. The MCP server lists each library in its instructions, with its version, description, index
21
+ doc, source location, and any [guidance](#agent-guidance) from its authors. `hoist-ping` and
22
+ `hoist-docs ping` list the same, plus any load problems.
23
+
24
+ Hoist's own doc ids do not change. Short ids such as `core`, `grid`, and `index` always mean Hoist
25
+ docs.
26
+
27
+ ## Opting In
28
+
29
+ 1. Write the docs as markdown files in the package: package READMEs, concept docs, or both. Use
30
+ `##` and `###` headings. Search ranks and returns docs by section.
31
+ 2. Add a registry file, for example `docs/doc-registry.json`. See
32
+ [Registry Format](#registry-format).
33
+ 3. Declare the registry in `package.json`:
34
+
35
+ ```json
36
+ {
37
+ "name": "@acme/hoist-acme",
38
+ "description": "Acme overrides and components for Hoist apps.",
39
+ "hoist": {"docRegistry": "docs/doc-registry.json"}
40
+ }
41
+ ```
42
+
43
+ 4. Publish the docs. Add the registry and every doc file to the `files` field in `package.json`,
44
+ if the package uses one.
45
+ 5. Install the package in an app and run `npx hoist-docs ping` from the app's `client-app/`
46
+ folder. The output names the library and its doc count, or the problem that stopped it from
47
+ loading.
48
+
49
+ The `description` in `package.json` appears in the server instructions, so keep it to one short
50
+ sentence about what the library provides.
51
+
52
+ ## Registry Format
53
+
54
+ The registry uses the same JSON schema as hoist-react's
55
+ [`docs/doc-registry.json`](./doc-registry.json). Only `entries[].id` is required, so a small
56
+ library can start with this:
57
+
58
+ ```json
59
+ {
60
+ "entries": [
61
+ {"id": "docs/README.md", "title": "Acme Index", "mcpCategory": "index"},
62
+ {
63
+ "id": "grid/README.md",
64
+ "title": "Acme Grids",
65
+ "description": "AcmeGrid, the firm-standard wrapper around Hoist's grid.",
66
+ "keywords": ["AcmeGrid", "AcmeGridModel", "GridModel", "export", "column presets"]
67
+ }
68
+ ]
69
+ }
70
+ ```
71
+
72
+ | Field | Required | Description |
73
+ |---|---|---|
74
+ | `entries[].id` | Yes | Doc path relative to the package root. The tools reject a path that leaves the package root. |
75
+ | `entries[].title` | No | Display title. Defaults to the id. |
76
+ | `entries[].description` | No | One sentence for list output and search ranking. |
77
+ | `entries[].keywords` | No | API names and topics. Terms here boost the doc in search. |
78
+ | `entries[].mcpCategory` | No | Category for filtering. Defaults to `package`. |
79
+ | `entries[].aliases` | No | Extra short names. The tools scope them under the package name. |
80
+ | `entries[].mcpAudience` | No | Set to `maintainers` to serve the doc only in the library's own repo. See [Maintainer Docs](#maintainer-docs). |
81
+ | `mcpCategories` | No | Category ids and titles. An undeclared category gets a title from its id. |
82
+ | `mcpInstructions` | No | Guidance for agents, as a string or an array of lines. See [Agent Guidance](#agent-guidance). |
83
+ | `viewerCategories`, `entries[].viewerCategory` | No | Ignored by the MCP tools. The Toolbox doc viewer uses them. |
84
+
85
+ Use the hoist-react categories where they fit: `package`, `concept`, `devops`, `conventions`, and
86
+ `index`. Give the index doc the id `docs/README.md`. The tools treat that path as the library
87
+ index.
88
+
89
+ ## Agent Guidance
90
+
91
+ A library can give agents short, direct guidance with `mcpInstructions` in its registry file. The
92
+ MCP server adds it to its instructions under the library's name, and the ping surfaces show it.
93
+ Agents read server instructions before they use any tool, so guidance reaches an agent that never
94
+ searches the docs.
95
+
96
+ Use guidance to say what the library changes about writing Hoist code. A client package of Hoist
97
+ overrides is the main case:
98
+
99
+ ```json
100
+ {
101
+ "mcpInstructions": [
102
+ "Use acmeGrid and AcmeGridModel instead of grid and GridModel in Acme apps.",
103
+ "Fetch through AcmeFetchService, which adds the Acme auth headers. Do not call XH.fetchService directly.",
104
+ "Read @acme/hoist-acme/docs/README.md before you build a new screen."
105
+ ],
106
+ "entries": []
107
+ }
108
+ ```
109
+
110
+ - **Keep it short.** The server cuts guidance longer than 1,500 characters and logs a warning.
111
+ Put the details in the docs, and point to them.
112
+ - **State rules, not features.** Name the Hoist API that the library replaces, and what to use
113
+ instead. The library description and index already say what the library provides.
114
+ - **Stay in scope.** The server tells agents that library guidance covers components and patterns
115
+ only, and that it never overrides the user.
116
+
117
+ The tools trim each line and drop blank lines. If the value is not a string or an array of
118
+ strings, the tools ignore it and log a warning.
119
+
120
+ ## Maintainer Docs
121
+
122
+ Some docs are for the people who work on the library, not for the apps that use it. A guide to
123
+ writing the library's docs is one example. In an app, such a doc only adds noise to search
124
+ results.
125
+
126
+ Mark the entry with `"mcpAudience": "maintainers"`. The tools then serve it only when the library
127
+ is the app root, as when an agent works in the library's own repo. An app that installs the
128
+ library never sees it. The entry stays in the registry for other readers, such as the Toolbox doc
129
+ viewer.
130
+
131
+ ```json
132
+ {"id": "docs/doc-conventions.md", "mcpCategory": "conventions", "mcpAudience": "maintainers"}
133
+ ```
134
+
135
+ ## Doc IDs
136
+
137
+ Each id is the package name plus the registry path. The resolver also accepts these forms:
138
+
139
+ | Input | Resolves to |
140
+ |---|---|
141
+ | `@acme/hoist-acme/grid/README.md` | The doc, by its full id |
142
+ | `@acme/hoist-acme/grid` | Same doc, without `/README.md` |
143
+ | `hoist-acme/grid` | Same doc, with the package name unscoped |
144
+ | `@acme/hoist-acme` or `hoist-acme` | The library index, `docs/README.md` |
145
+ | `@acme/hoist-acme/<alias>` | The doc that declares the alias |
146
+ | `grid` | Hoist's `cmp/grid/README.md`, never a companion doc |
147
+
148
+ The `hoist://docs/{+docId}` resource accepts the same ids, for example
149
+ `hoist://docs/@acme/hoist-acme/grid/README.md`.
150
+
151
+ Write links between your docs as ordinary relative links, such as `../grid/README.md`. The tools
152
+ rewrite each one when they serve the doc, so an agent that follows it stays in your package:
153
+
154
+ - A link to a doc the tools serve becomes its full id, such as `@acme/hoist-acme/grid/README.md`.
155
+ - A link to any other file in the package, such as source or a maintainer doc, becomes a file
156
+ path that the agent can open, such as `client-app/node_modules/@acme/hoist-acme/grid/AcmeGrid.ts`.
157
+ - Links that leave the package root, and links inside code, stay as written.
158
+
159
+ ## Writing Docs Agents Can Use
160
+
161
+ - **Lead the index with what changes.** A package of client overrides should say early which Hoist
162
+ components and patterns it replaces. For example: "Use `acmeGrid` instead of `grid` in Acme
163
+ apps."
164
+ - **Name APIs in keywords.** Agents search with API names. Put each class, config key, and function
165
+ that a doc covers in its `keywords`.
166
+ - **Put examples under specific headings.** A search result is one section, so a heading such as
167
+ "Export a grid to Excel" finds its reader better than "Usage".
168
+ - **Link to Hoist docs by topic.** Agents can read hoist-react docs with the same tools, so a
169
+ library doc need not repeat them.
170
+
171
+ ## Discovery
172
+
173
+ The tools start from the package that consumes `@xh/hoist`. They check these places in order:
174
+
175
+ 1. The `HOIST_MCP_APP_ROOT` environment variable, if set.
176
+ 2. The working directory and its `client-app/` folder, then the same pair in each parent folder.
177
+ The first `package.json` that is `@xh/hoist` or depends on it wins, so a run from inside an
178
+ app, such as from `client-app/src`, still finds the app.
179
+ 3. Otherwise, the first `package.json` in the working directory or its `client-app/` folder.
180
+
181
+ Claude Code starts the MCP server from the project root, so a standard Hoist app resolves to
182
+ `client-app/`. The app package itself can opt in too. An app can use this to serve its own docs to
183
+ the agents that work on it.
184
+
185
+ The tools find each dependency at `node_modules/<name>`, walking up from the app, as Node does.
186
+ They read only direct dependencies. A library that a companion library depends on must also be a
187
+ direct dependency of the app for its docs to load.
188
+
189
+ ## Limits
190
+
191
+ - **Docs only.** The symbol tools (`hoist-search-symbols`, `hoist-get-symbol`, and
192
+ `hoist-get-members`) cover `@xh/hoist` only. The server instructions tell agents to read a
193
+ companion library's docs and then its source for exact APIs.
194
+ - **Loaded at startup.** The MCP server reads the registries when it starts. Restart it after an
195
+ install changes a companion library.
196
+ - **Untrusted content.** Any opted-in dependency can add docs. The server instructions tell the
197
+ client to treat all doc content as data, not as instructions. Library guidance is the one
198
+ exception, and the instructions frame it as advice from the package authors.
199
+ - **Load problems are not fatal.** A missing registry, a missing doc file, or a bad path skips that
200
+ item, and the tools log a warning to stderr and report it in `hoist-ping` and `hoist-docs ping`.
201
+ A field of the wrong type falls back to its default. Only `entries` and `mcpCategories` warn when
202
+ they are not lists, so run `hoist-docs list` to check that titles and categories came through.
203
+
204
+ See the [MCP Server README](../mcp/README.md#companion-library-docs) for how the tools implement
205
+ this.
@@ -279,6 +279,14 @@
279
279
  "description": "Model Context Protocol server providing AI assistants with documentation search, TypeScript type exploration, and code generation prompts.",
280
280
  "keywords": ["MCP", "Model Context Protocol", "AI assistant", "Claude Code", "tools", "resources", "prompts", "search", "symbols", "documentation"]
281
281
  },
282
+ {
283
+ "id": "docs/companion-library-docs.md",
284
+ "title": "Companion Library Docs",
285
+ "mcpCategory": "devops",
286
+ "viewerCategory": "devops",
287
+ "description": "How a library that builds on Hoist, such as hoist-chat-kit or a client firm's shared package, serves its docs through the hoist-react MCP server and hoist-docs CLI.",
288
+ "keywords": ["companion library", "hoist.docRegistry", "docRegistry", "package.json", "client package", "overrides", "sidecar", "HOIST_MCP_APP_ROOT", "package-prefixed doc ids", "library docs"]
289
+ },
282
290
  {
283
291
  "id": "docs/lifecycle-app.md",
284
292
  "title": "Lifecycle: App Initialization",
@@ -210,6 +210,23 @@ Every entry point begins with `import '../Bootstrap'`. This `Bootstrap.ts` file
210
210
  This import must come first (or at least before `XH.renderApp()`) to ensure all registrations and
211
211
  type augmentations are in place before the framework initializes.
212
212
 
213
+ ### Import `@xh/hoist/core` First
214
+
215
+ Within `Bootstrap.ts`, import `@xh/hoist/core` before any other Hoist module, including app modules
216
+ that import Hoist themselves. Hoist's packages import each other in cycles that resolve only when
217
+ `core` loads first. If another package loads first - `@xh/hoist/icon` via an app's icon
218
+ registrations, for example - the app crashes at startup with an error such as
219
+ `TypeError: span is not a function`. Typecheck, lint and app-level cycle checks do not catch this,
220
+ because the cycles are inside Hoist.
221
+
222
+ ```typescript
223
+ // Bootstrap.ts
224
+ import {XH} from '@xh/hoist/core'; // First Hoist import
225
+ import {installAgGrid} from '@xh/hoist/kit/ag-grid';
226
+ // ...
227
+ import './core/Icons'; // App modules that import Hoist come after core
228
+ ```
229
+
213
230
  ## Key Source Files
214
231
 
215
232
  | File | Contents |
@@ -59,7 +59,8 @@ Most of Hoist depends on the hoist-core server. `Store` reads a soft config, `Gr
59
59
  to user prefs, and nearly every service loads data on init. Tests therefore need a server.
60
60
 
61
61
  `test-support/hoistCore.ts` provides one. It is a small, in-memory stand-in for hoist-core's
62
- `XhController` endpoints: auth status, environment, configs, prefs, and activity tracking. It
62
+ `XhController` endpoints: auth status, environment, configs, prefs, activity tracking, and
63
+ JsonBlobs. It also serves the `XhViewController` endpoints that `ViewManagerModel` calls. It
63
64
  answers in the exact JSON shapes hoist-core renders, and names the server source of each shape.
64
65
  Hoist's real `fetch` calls reach it through [MSW](https://mswjs.io), so the code under test runs
65
66
  unchanged, from `FetchService` down.
@@ -176,6 +177,9 @@ describe('PrefService', () => {
176
177
  - A file boots once. To test a different boot outcome, such as access denied, use a separate spec
177
178
  file. `initTestAppAsync()` rejects, naming `XH.appState`, if boot stops before `RUNNING`. That
178
179
  includes `LOGIN_REQUIRED`, where an app with a login form waits for the user to sign in.
180
+ - `initTestAppAsync()` also rejects if boot triggers a problem that the kit's guards catch, such as
181
+ a request the fake does not handle. It waits for the requests that boot started, so none lands in
182
+ the first test's request log. It logs any error that the app handles during boot.
179
183
 
180
184
  Tests that do not touch services, such as `LocalDate` or filter tests, do not need to boot.
181
185
 
@@ -258,6 +262,26 @@ Write the test for the correct behavior. If the fix belongs in a separate change
258
262
  `it.fails()` and add a `// BUG:` comment that describes the problem. The suite stays green, and the
259
263
  test starts failing once the bug is fixed, as a reminder to remove the marker.
260
264
 
265
+ `it.fails()` cannot mark a promise that rejects with nothing to handle it, such as a load started
266
+ without an `await`. Vitest reports that rejection as an error of the whole run, not of a test, and
267
+ fails the run on purpose. Fix the code to await or catch the promise. If the fix must wait, filter
268
+ that one error with Vitest's [`onUnhandledError`](https://vitest.dev/config/onunhandlederror)
269
+ option. The filter applies to every spec, so match the error narrowly:
270
+
271
+ ```typescript
272
+ // vitest.config.mts
273
+ export default defineConfig(
274
+ mergeConfig(configureVitest({appCode: 'myApp'}), {
275
+ test: {
276
+ onUnhandledError(e) {
277
+ // BUG: OrderService.refreshAsync() leaves a rejection when the server is down.
278
+ if (e.message?.includes('Orders unavailable')) return false;
279
+ }
280
+ }
281
+ })
282
+ );
283
+ ```
284
+
261
285
  ### Desktop and mobile
262
286
 
263
287
  A module graph can load the desktop or the mobile platform, not both. `initTestAppAsync()` boots a
@@ -357,8 +381,35 @@ it('flags orders over the configured limit', () => {
357
381
  - A path can also be an absolute URL, for an external API the app calls.
358
382
  - A request that the fake does not serve fails the test, and the failure names the URL.
359
383
  - A file boots once, so test each role set or user in its own spec file.
360
- - The fake returns canned data. It does not enforce the server's business rules or role scoping.
361
- Test those against a real server.
384
+ - The fake returns canned data. It does not enforce the server's business rules or role scoping,
385
+ except for which JsonBlobs a user can read - see [Views and JsonBlobs](#views-and-jsonblobs).
386
+ Test those rules against a real server.
387
+
388
+ ### Views and JsonBlobs
389
+
390
+ The fake keeps an in-memory JsonBlob store, `hoistCore.jsonBlobs`. It serves `XH.jsonBlobService`
391
+ and the endpoints that `ViewManagerModel` calls. The store starts empty. An app model that creates a
392
+ view manager at boot therefore needs no setup: the view manager loads no views and selects its
393
+ in-code default. Seed views and the user's view state to test anything else:
394
+
395
+ ```typescript
396
+ const {jsonBlobs} = hoistCore;
397
+ jsonBlobs.addView({type: 'portfolioGrid', name: 'My Positions', value: {sortBy: 'pnl'}});
398
+ jsonBlobs.addView({type: 'portfolioGrid', name: 'Firm Standard', isGlobal: true, token: 'firm'});
399
+ jsonBlobs.addView({type: 'portfolioGrid', name: 'Risk', owner: 'bsmith', isShared: true});
400
+ jsonBlobs.setViewState('portfolioGrid', {currentView: 'firm', autoSave: true});
401
+ jsonBlobs.add({type: 'appNotes', name: 'notes', value: {text: 'Hello'}}); // a plain JsonBlob
402
+ ```
403
+
404
+ - `jsonBlobs.get(token)` returns the stored blob, so a test can assert on what the client saved.
405
+ Change the blob to model an edit made elsewhere, such as a later `lastUpdated`.
406
+ - `jsonBlobs.viewState(type)` returns the user's state for a view type, as the client receives it.
407
+ - Blobs last for the whole file, like prefs. `jsonBlobs.clear()` removes them all.
408
+ - A user reads only the blobs they own and the blobs shared with all users, as on the server. The
409
+ fake sends `manageGlobal` from `hoistCore.roles` and `jsonBlobs.globalWriteRoles`. Those roles
410
+ default to `HOIST_ADMIN`, as in hoist-core's `xhJsonBlobConfig`.
411
+ - The fake does not check write access or duplicate names. To test the error for one of those,
412
+ serve the endpoint with `hoistCore.route()` and `hoistError()`.
362
413
 
363
414
  ### Server state for every spec
364
415
 
@@ -376,8 +376,14 @@ the app renders. A registration runs when its module loads, so one left in a laz
376
376
  missing from `IconPicker` and from `Icon.get()` until that tab loads. Toolbox keeps its icons in
377
377
  `client-app/src/core/Icons.ts`.
378
378
 
379
+ Put that import below the import of `@xh/hoist/core` in `Bootstrap.ts`. Hoist's packages import each
380
+ other in cycles that resolve only when `core` loads first. If `@xh/hoist/icon` is the first Hoist
381
+ module to load, the app crashes at startup. Typecheck, lint and app-level cycle checks do not catch
382
+ this, because the cycles are inside Hoist. See
383
+ [Import `@xh/hoist/core` First](../lifecycle-app.md#import-xhhoistcore-first).
384
+
379
385
  ```typescript
380
- // client-app/src/core/Icons.ts - imported by Bootstrap.ts
386
+ // client-app/src/core/Icons.ts - imported by Bootstrap.ts, below @xh/hoist/core
381
387
  import {faGithub} from '@fortawesome/free-brands-svg-icons';
382
388
  import {faFaceFrown, faFaceSmile} from '@fortawesome/pro-regular-svg-icons';
383
389
  import {Icon} from '@xh/hoist/icon';
@@ -61,7 +61,7 @@ Verified against both hoist-react and hoist-core changelogs.
61
61
 
62
62
  | hoist-react | Min Core Required | Recommended Core | Max Core Tested | Notes | Upgrade |
63
63
  |---|---|---|---|---|---|
64
- | 89.0 | -- | 42.0 | 42.0 | No new server-side pairing requirements | [Notes](./upgrade-notes/v89-upgrade-notes.md) |
64
+ | 89.0 | -- | 42.0 | 43.0 | No new server-side pairing requirements | [Notes](./upgrade-notes/v89-upgrade-notes.md) |
65
65
  | 88.1 | -- | 42.0 | 42.0 | Use 88.1.2 or later - earlier 88 releases drop `MsalClient` defaults. `ViewManagerModel.manageGlobal` derived from server `globalWriteRoles` (42, degrades gracefully). TC39 decorators are client-only - requires hoist-dev-utils 16 | [Notes](./upgrade-notes/v88-upgrade-notes.md) |
66
66
  | 87.0 | 40.5.0 | 41.0 | 41.0 | `ViewManager` group rename + bulk edit (40.5); directory group names/search, tabbed config editor (41, degrade gracefully) | [Notes](./upgrade-notes/v87-upgrade-notes.md) |
67
67
  | 86.0 | -- | 40.0.1 | 40.0.1 | Client `MetricsService`, `Runner` API, remote-`traceparent` spans | [Notes](./upgrade-notes/v86-upgrade-notes.md) |
@@ -121,6 +121,7 @@ to find the minimum hoist-react version for a given core release.
121
121
 
122
122
  | hoist-core | Min hoist-react | Notes |
123
123
  |---|---|---|
124
+ | 43.0 | -- | Grails 8 / Spring Boot 4 / Java 21 server upgrade. No client-facing changes and no hoist-react bump. |
124
125
  | 42.0 | 88.0 recommended | `JsonBlobService` limits global blob writes to `xhJsonBlobConfig.globalWriteRoles` and reports `manageGlobal` on `xhView/allData`, consumed by v88's `ViewManagerModel`. Older hoist-react keeps its client-side `manageGlobal`, which the server now also enforces. No hard hoist-react bump. |
125
126
  | 41.0 | 87.0 recommended | Tabbed/typed config editor, directory group names + search endpoints - consumed by v87's Admin Console, which degrades gracefully without them. No hard hoist-react bump. |
126
127
  | 40.5 | 87.0 recommended | `ViewManager` group rename + bulk-editing endpoints consumed by v87 (which requires 40.5 as its floor). No hard hoist-react bump from 40.0. |
package/icon/README.md CHANGED
@@ -231,7 +231,10 @@ instead. Runtime installation matters when you replace a built-in (see below), b
231
231
  calls to that factory then render the app's icon.
232
232
 
233
233
  Registration is a one-time task at app startup. Import your `Icons.ts` from `Bootstrap.ts`, or any
234
- module that runs before the first render, so the factories exist before use.
234
+ module that runs before the first render, so the factories exist before use. Put that import below
235
+ the import of `@xh/hoist/core` - an app crashes at startup if `@xh/hoist/icon` is the first Hoist
236
+ module it loads. See
237
+ [Import `@xh/hoist/core` First](../docs/lifecycle-app.md#import-xhhoistcore-first).
235
238
 
236
239
  ### Registering Multiple Weights
237
240