@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.
- package/CHANGELOG.md +75 -0
- package/build/types/cmp/grid/GridModel.d.ts +6 -0
- package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
- package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
- package/build/types/core/XH.d.ts +2 -1
- package/build/types/core/model/HoistModel.d.ts +1 -0
- package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
- package/build/types/core/persist/PersistenceProvider.d.ts +3 -0
- package/build/types/data/cube/View.d.ts +0 -2
- package/build/types/data/cube/impl/RowCache.d.ts +1 -1
- package/build/types/data/cube/row/BaseRow.d.ts +5 -0
- package/build/types/desktop/cmp/dash/DashViewSpec.d.ts +2 -1
- package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
- package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
- package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
- package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -0
- package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
- package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
- package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
- package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
- package/build/types/svc/FetchService.d.ts +19 -0
- package/build/types/test-support/agGrid.d.ts +2 -0
- package/build/types/test-support/hoistCore.d.ts +7 -1
- package/build/types/test-support/index.d.ts +1 -0
- package/build/types/test-support/jsonBlobs.d.ts +130 -0
- package/build/types/test-support/testApp.d.ts +5 -2
- package/cmp/grid/Grid.ts +2 -2
- package/cmp/grid/GridModel.ts +14 -1
- package/cmp/grid/columns/Column.ts +3 -2
- package/cmp/input/impl/LiveCommas.ts +59 -0
- package/cmp/viewmanager/ViewManagerModel.ts +25 -7
- package/core/XH.ts +8 -3
- package/core/model/HoistModel.ts +4 -2
- package/core/model/Hooks.ts +1 -0
- package/core/model/ManagedRefreshContextModel.ts +5 -1
- package/core/persist/PersistenceProvider.ts +15 -1
- package/data/cube/View.ts +3 -9
- package/data/cube/impl/RowCache.ts +2 -2
- package/data/cube/row/BaseRow.ts +14 -1
- package/data/cube/row/ParentRow.ts +1 -1
- package/desktop/cmp/dash/DashViewSpec.ts +2 -1
- package/desktop/cmp/dash/README.md +6 -5
- package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
- package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
- package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
- package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
- package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
- package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
- package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
- package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
- package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
- package/desktop/cmp/input/NumberInput.ts +51 -12
- package/desktop/cmp/input/Select.ts +25 -7
- package/desktop/cmp/tab/TabSwitcher.ts +4 -6
- package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
- package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
- package/docs/README.md +2 -0
- package/docs/build-and-publish.md +21 -11
- package/docs/companion-library-docs.md +205 -0
- package/docs/doc-registry.json +9 -1
- package/docs/lifecycle-app.md +17 -0
- package/docs/lifecycle-models-and-services.md +2 -1
- package/docs/persistence.md +2 -0
- package/docs/telemetry.md +29 -0
- package/docs/unit-testing.md +54 -3
- package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
- package/docs/version-compatibility.md +2 -1
- package/icon/README.md +4 -1
- package/mcp/README.md +79 -4
- package/mcp/cli/docs.ts +75 -30
- package/mcp/data/doc-id-resolver.ts +50 -9
- package/mcp/data/doc-registry.ts +462 -44
- package/mcp/data/doc-search.ts +25 -6
- package/mcp/formatters/docs.ts +136 -36
- package/mcp/instructions.ts +69 -0
- package/mcp/resources/docs.ts +10 -8
- package/mcp/server.ts +7 -13
- package/mcp/tools/docs.ts +64 -18
- package/mcp/util/paths.ts +85 -2
- package/mobile/cmp/input/NumberInput.ts +42 -4
- package/package.json +19 -19
- package/public/msal-redirect-bridge.min.js +1 -1
- package/svc/FetchService.ts +38 -2
- package/svc/JsonBlobService.ts +7 -4
- package/svc/README.md +7 -3
- package/test-support/agGrid.ts +12 -2
- package/test-support/hoistCore.ts +32 -5
- package/test-support/index.ts +1 -0
- package/test-support/jsonBlobs.ts +543 -0
- package/test-support/setup.ts +8 -6
- package/test-support/testApp.ts +36 -7
- package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
- package/desktop/cmp/tab/impl/TabContextMenuItems.ts +0 -23
|
@@ -30,22 +30,32 @@ See [Unit Testing](./unit-testing.md) for how the tests and the report work.
|
|
|
30
30
|
## Deploy Snapshot (`deploySnapshot.yml`)
|
|
31
31
|
|
|
32
32
|
Publishes a SNAPSHOT build to npm on every push to `develop`. Can also be triggered manually via
|
|
33
|
-
`workflow_dispatch` with
|
|
33
|
+
`workflow_dispatch` for any branch, with two optional inputs:
|
|
34
|
+
|
|
35
|
+
- **Version** - overrides the version from `package.json`. `-SNAPSHOT` is appended if missing.
|
|
36
|
+
- **Experimental** - publishes with the `experimental` dist-tag instead of `next`, and skips the
|
|
37
|
+
Toolbox dispatch. Tick it when building a branch with breaking or unfinished changes that
|
|
38
|
+
should not reach Toolbox or other apps tracking `next`. Pushes to `develop` never set it.
|
|
39
|
+
|
|
40
|
+
How it works:
|
|
34
41
|
|
|
35
42
|
- The version is sourced from `package.json` (e.g. `82.0.0-SNAPSHOT`). A timestamp is appended
|
|
36
43
|
automatically to ensure each snapshot is unique.
|
|
37
|
-
- Snapshots are published with the `next` dist-tag so they don't affect `latest`.
|
|
44
|
+
- Snapshots are published with the `next` dist-tag so they don't affect `latest`. Experimental
|
|
45
|
+
runs use the `experimental` dist-tag and leave `next` alone. To try an experimental build in an
|
|
46
|
+
app, install the exact version shown in the run's job summary.
|
|
38
47
|
- Lint and unit tests run as part of this workflow. A failure in either blocks the publish.
|
|
48
|
+
- Publishing authenticates with npm via OIDC trusted publishing, with no stored npm token.
|
|
39
49
|
- Uses `concurrency` with `cancel-in-progress: true` to avoid redundant builds when multiple pushes
|
|
40
50
|
land in quick succession.
|
|
41
|
-
- After publishing, polls `npm view
|
|
42
|
-
to the version just published (10 minute limit). Publishing returns once npm
|
|
43
|
-
but the new version is not guaranteed to be resolvable at that moment.
|
|
44
|
-
- Finally fires a `repository_dispatch` (`hoist-react-snapshot`) to
|
|
45
|
-
and redeploys Toolbox against the new snapshot. The dispatch
|
|
46
|
-
**XH Build Bot** GitHub App via a short-lived installation token
|
|
47
|
-
`actions/create-github-app-token`, scoped to the toolbox repo with Contents: write.
|
|
48
|
-
triggered this way show `xh-build-bot[bot]` as the actor.
|
|
51
|
+
- After publishing, polls `npm view` until the registry resolves the dist-tag (`next` or
|
|
52
|
+
`experimental`) to the version just published (10 minute limit). Publishing returns once npm
|
|
53
|
+
accepts the tarball, but the new version is not guaranteed to be resolvable at that moment.
|
|
54
|
+
- Finally, for `next` builds only, fires a `repository_dispatch` (`hoist-react-snapshot`) to
|
|
55
|
+
`xh/toolbox`, which rebuilds and redeploys Toolbox against the new snapshot. The dispatch
|
|
56
|
+
authenticates as the org-owned **XH Build Bot** GitHub App via a short-lived installation token
|
|
57
|
+
minted by `actions/create-github-app-token`, scoped to the toolbox repo with Contents: write.
|
|
58
|
+
Toolbox runs triggered this way show `xh-build-bot[bot]` as the actor.
|
|
49
59
|
|
|
50
60
|
## Deploy Release (`deployRelease.yml`)
|
|
51
61
|
|
|
@@ -89,7 +99,7 @@ checking weekly.
|
|
|
89
99
|
| Name | Type | Used By | Purpose |
|
|
90
100
|
|------|------|---------|---------|
|
|
91
101
|
| `FONTAWESOME_PACKAGE_TOKEN` | Secret | CI, Snapshot, Release | Auth token for the Font Awesome Pro npm registry (`npm.fontawesome.com`) |
|
|
92
|
-
| `NPM_TOKEN` | Secret |
|
|
102
|
+
| `NPM_TOKEN` | Secret | Unpublish | Auth token for the npm public registry. Snapshot and Release publish via OIDC trusted publishing instead |
|
|
93
103
|
| `XH_BUILD_BOT_PRIVATE_KEY` | Secret | Snapshot | Private key for the XH Build Bot GitHub App, used to mint the Toolbox dispatch token |
|
|
94
104
|
| `XH_BUILD_BOT_CLIENT_ID` | Variable | Snapshot | Client ID of the XH Build Bot GitHub App |
|
|
95
105
|
| `GITHUB_TOKEN` | Secret | Release | Provided automatically by GitHub Actions; used for `gh release create` |
|
|
@@ -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.
|
package/docs/doc-registry.json
CHANGED
|
@@ -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",
|
|
@@ -365,7 +373,7 @@
|
|
|
365
373
|
"mcpCategory": "devops",
|
|
366
374
|
"viewerCategory": "devops",
|
|
367
375
|
"description": "GitHub Actions workflows for linting, CodeQL analysis, and npm publishing of hoist-react.",
|
|
368
|
-
"keywords": ["CI", "CD", "GitHub Actions", "lint", "CodeQL", "npm", "publish", "snapshot", "release"]
|
|
376
|
+
"keywords": ["CI", "CD", "GitHub Actions", "lint", "CodeQL", "npm", "publish", "snapshot", "release", "dist-tag", "experimental"]
|
|
369
377
|
},
|
|
370
378
|
{
|
|
371
379
|
"id": "docs/build-and-deploy-app.md",
|
package/docs/lifecycle-app.md
CHANGED
|
@@ -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 |
|
|
@@ -159,7 +159,8 @@ When the owning component unmounts, Hoist destroys the model by calling `destroy
|
|
|
159
159
|
3. Calls `XH.safeDestroy()` on all objects registered via `markManaged()`
|
|
160
160
|
4. Calls `XH.safeDestroy()` on all properties decorated with `@managed`
|
|
161
161
|
|
|
162
|
-
This cascade ensures child models, stores, and other resources are cleaned up automatically.
|
|
162
|
+
This cascade ensures child models, stores, and other resources are cleaned up automatically. If one
|
|
163
|
+
object's `destroy()` throws, the error is logged and the rest are still destroyed. The
|
|
163
164
|
`@managed` decorator is the primary mechanism for declaring ownership:
|
|
164
165
|
|
|
165
166
|
```typescript
|
package/docs/persistence.md
CHANGED
|
@@ -46,6 +46,8 @@ When persisted state changes:
|
|
|
46
46
|
observable changes that are not actually user-driven and should not be written back.
|
|
47
47
|
- Writes are **debounced** (default 250ms) to avoid excessive storage operations during rapid
|
|
48
48
|
changes like column resizing.
|
|
49
|
+
- Destroying a provider writes any pending change at once. Pushing stored state back to the
|
|
50
|
+
target drops a pending write, as when a `ViewManagerModel` loads another view.
|
|
49
51
|
|
|
50
52
|
## Backing Stores
|
|
51
53
|
|
package/docs/telemetry.md
CHANGED
|
@@ -110,6 +110,35 @@ list of `{match, sampleRate}` rules. `match` is a map of tag keys to glob patter
|
|
|
110
110
|
name. The first matching rule's `sampleRate` wins, falling back to a top-level `sampleRate`.
|
|
111
111
|
Child spans inherit their root's decision.
|
|
112
112
|
|
|
113
|
+
### Trace headers on fetch requests
|
|
114
|
+
|
|
115
|
+
While tracing is enabled, each fetch records a client span. `FetchService` sends that span to the
|
|
116
|
+
server in a W3C `traceparent` header, so the server's spans join the trace. By default it sends the
|
|
117
|
+
header only to the app's own server. That covers relative URLs, and absolute URLs on the origin of
|
|
118
|
+
the page or of `XH.baseUrl`.
|
|
119
|
+
|
|
120
|
+
A request to another origin still records its client span, but it carries no header. The
|
|
121
|
+
`traceparent` header is not CORS-safelisted. If a cross-origin server does not list it in
|
|
122
|
+
`Access-Control-Allow-Headers`, the preflight fails and the browser blocks the request. The header
|
|
123
|
+
would also send the app's trace IDs to a server outside the app.
|
|
124
|
+
|
|
125
|
+
To send the header to another server that accepts it, such as a second traced backend, set
|
|
126
|
+
`propagateTrace` on the request or in `FetchService.defaults`:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
// One request
|
|
130
|
+
await XH.fetchJson({url: 'https://pricing.example.com/quote', propagateTrace: true});
|
|
131
|
+
|
|
132
|
+
// Every request, in the app's Bootstrap module - a boolean, or a function of the FetchOptions
|
|
133
|
+
FetchService.defaults.propagateTrace = opts =>
|
|
134
|
+
FetchService.isHoistServerUrl(opts.url) ||
|
|
135
|
+
new URL(opts.url, window.location.href).origin === 'https://pricing.example.com';
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
A function default replaces the built-in check. Call `FetchService.isHoistServerUrl()` in it, as
|
|
139
|
+
shown, to keep sending the header to the app's own server. Set
|
|
140
|
+
`propagateTrace: false` on a request to omit the header for that request only.
|
|
141
|
+
|
|
113
142
|
### Joining a remote trace
|
|
114
143
|
|
|
115
144
|
To continue a trace started elsewhere (a `traceparent` received off-channel via WebSocket, SSE,
|
package/docs/unit-testing.md
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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 |
|
|
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
|
|