@xh/hoist 89.1.0 → 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 (38) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/build/types/cmp/grid/GridModel.d.ts +6 -0
  3. package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
  4. package/build/types/core/XH.d.ts +2 -1
  5. package/build/types/core/persist/PersistenceProvider.d.ts +3 -0
  6. package/build/types/desktop/cmp/dash/DashViewSpec.d.ts +2 -1
  7. package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
  8. package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
  9. package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
  10. package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -0
  11. package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
  12. package/build/types/svc/FetchService.d.ts +19 -0
  13. package/cmp/grid/Grid.ts +2 -2
  14. package/cmp/grid/GridModel.ts +14 -1
  15. package/cmp/grid/columns/Column.ts +2 -1
  16. package/cmp/viewmanager/ViewManagerModel.ts +25 -7
  17. package/core/XH.ts +8 -3
  18. package/core/persist/PersistenceProvider.ts +15 -1
  19. package/desktop/cmp/dash/DashViewSpec.ts +2 -1
  20. package/desktop/cmp/dash/README.md +6 -5
  21. package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
  22. package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
  23. package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
  24. package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
  25. package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
  26. package/desktop/cmp/tab/TabSwitcher.ts +4 -6
  27. package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
  28. package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
  29. package/docs/build-and-publish.md +21 -11
  30. package/docs/doc-registry.json +1 -1
  31. package/docs/lifecycle-models-and-services.md +2 -1
  32. package/docs/persistence.md +2 -0
  33. package/docs/telemetry.md +29 -0
  34. package/package.json +1 -1
  35. package/svc/FetchService.ts +38 -2
  36. package/svc/README.md +7 -3
  37. package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
  38. package/desktop/cmp/tab/impl/TabContextMenuItems.ts +0 -23
@@ -10,6 +10,11 @@ import {div, vframe} from '@xh/hoist/cmp/layout';
10
10
  import {creates, hoistCmp, HoistProps, TestSupportProps, uses} from '@xh/hoist/core';
11
11
  import {DashCanvasModel, DashCanvasViewSpec} from '@xh/hoist/desktop/cmp/dash';
12
12
  import {DashCanvasWidgetChooserModel} from '@xh/hoist/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooserModel';
13
+ import {
14
+ groupViewSpecs,
15
+ ViewSpecGroup,
16
+ type ViewSpecNode
17
+ } from '@xh/hoist/desktop/cmp/dash/impl/DashUtils';
13
18
  import {every} from 'lodash';
14
19
  import type {ReactElement, ReactNode} from 'react';
15
20
  import './DashCanvasWidgetChooser.scss';
@@ -21,8 +26,9 @@ export interface DashCanvasWidgetChooserProps extends HoistProps, TestSupportPro
21
26
 
22
27
  /**
23
28
  * Displays available {@link DashCanvasViewSpec}s as draggable items that can be dropped onto a
24
- * {@link DashCanvas} to add new views. View specs are listed in their defined order, grouped by
25
- * their `groupName` property if present. Place inside a collapsible panel alongside a DashCanvas.
29
+ * {@link DashCanvas} to add new views. View specs are listed in their defined order, grouped into
30
+ * (nested) cards by their `groupName` property if present. Place inside a collapsible panel
31
+ * alongside a DashCanvas.
26
32
  */
27
33
  export const [DashCanvasWidgetChooser, dashCanvasWidgetChooser] =
28
34
  hoistCmp.withFactory<DashCanvasWidgetChooserProps>({
@@ -66,60 +72,37 @@ const draggableWidget = hoistCmp.factory<
66
72
  function createDraggableItems(dashCanvasModel: DashCanvasModel): ReactNode[] {
67
73
  if (!dashCanvasModel?.ref.current) return [];
68
74
 
69
- const groupedItems: Record<string, GroupEntry[]> = {},
70
- ungroupedItems: ReactElement[] = [];
71
-
72
- dashCanvasModel.viewSpecs
73
- .filter(viewSpec => {
74
- return (
75
- viewSpec.allowAdd &&
76
- (!viewSpec.unique || !dashCanvasModel.getViewsBySpecId(viewSpec.id).length)
77
- );
78
- })
79
- .forEach(viewSpec => {
80
- const {groupName} = viewSpec,
81
- item = draggableWidget({viewSpec});
82
-
83
- if (groupName) {
84
- const group = groupedItems[groupName],
85
- entry: GroupEntry = {item, icon: viewSpec.icon};
86
- if (group) {
87
- group.push(entry);
88
- } else {
89
- groupedItems[groupName] = [entry];
90
- }
91
- } else {
92
- ungroupedItems.push(item);
93
- }
94
- });
75
+ const addableSpecs = dashCanvasModel.viewSpecs.filter(viewSpec => {
76
+ return (
77
+ viewSpec.allowAdd &&
78
+ (!viewSpec.unique || !dashCanvasModel.getViewsBySpecId(viewSpec.id).length)
79
+ );
80
+ });
95
81
 
96
- return [
97
- ...Object.keys(groupedItems).map(groupName => {
98
- const entries = groupedItems[groupName],
99
- firstIcon = entries[0]?.icon,
100
- icon =
101
- firstIcon &&
102
- every(
103
- entries,
104
- it =>
105
- (it.icon?.props as {faName?: string})?.faName ===
106
- (firstIcon.props as {faName?: string}).faName
107
- )
108
- ? firstIcon
109
- : null;
82
+ return createGroupItems(groupViewSpecs(addableSpecs));
83
+ }
110
84
 
111
- return card({
112
- icon,
113
- title: groupName,
114
- items: entries.map(it => it.item),
115
- modelConfig: {collapsible: true}
116
- });
117
- }),
118
- ...ungroupedItems
119
- ];
85
+ /** Render groups as collapsible cards, nested as their `groupName` dictates. */
86
+ function createGroupItems(nodes: ViewSpecNode<DashCanvasViewSpec>[]): ReactNode[] {
87
+ return nodes.map(it =>
88
+ it instanceof ViewSpecGroup
89
+ ? card({
90
+ key: `group-${it.name}`,
91
+ icon: getSharedIcon(it.allViewSpecs),
92
+ title: it.name,
93
+ items: createGroupItems(it.children),
94
+ modelConfig: {collapsible: true}
95
+ })
96
+ : draggableWidget({key: it.id, viewSpec: it})
97
+ );
120
98
  }
121
99
 
122
- interface GroupEntry {
123
- item: ReactElement;
124
- icon?: ReactElement;
100
+ /** The icon of the first spec, if every spec has an icon of the same name. */
101
+ function getSharedIcon(viewSpecs: DashCanvasViewSpec[]): ReactElement {
102
+ const faName = (icon: ReactElement) => (icon?.props as {faName?: string})?.faName,
103
+ firstIcon = viewSpecs[0]?.icon;
104
+
105
+ return firstIcon && every(viewSpecs, it => faName(it.icon) === faName(firstIcon))
106
+ ? firstIcon
107
+ : null;
125
108
  }
@@ -10,13 +10,14 @@ import {contextMenu} from '@xh/hoist/desktop/cmp/contextmenu/ContextMenu';
10
10
  import {Icon} from '@xh/hoist/icon';
11
11
  import {popover} from '@xh/hoist/kit/blueprint';
12
12
  import {isEmpty} from 'lodash';
13
+ import {createViewSpecMenuItems} from '../../impl/DashUtils';
13
14
  import {DashContainerModel} from '../DashContainerModel';
14
15
 
15
16
  /**
16
17
  * Context menu for title bar/tabs of a stack in a DashContainer.
17
18
  *
18
19
  * Available view specs are listed in their defined order, optionally
19
- * grouped by their `groupName` property
20
+ * grouped by their `groupName` property into (nested) submenus.
20
21
  *
21
22
  * @internal
22
23
  */
@@ -103,8 +104,7 @@ function createMenuItems(props): MenuItemLike[] {
103
104
 
104
105
  // Convert any available viewSpecs into menu items
105
106
  function createAddMenuItems(props) {
106
- let {dashContainerModel, stack, index} = props,
107
- ret = [];
107
+ const {dashContainerModel, stack, index} = props;
108
108
 
109
109
  const addableSpecs = dashContainerModel.viewSpecs.filter(viewSpec => {
110
110
  if (!viewSpec.allowAdd) return false;
@@ -115,40 +115,9 @@ function createAddMenuItems(props) {
115
115
  return true;
116
116
  });
117
117
 
118
- if (isEmpty(addableSpecs)) return [];
119
-
120
- let hasUngrouped;
121
- addableSpecs.forEach(viewSpec => {
122
- const {id, title, icon, groupName} = viewSpec,
123
- item = {
124
- text: title,
125
- icon: icon,
126
- actionFn: () => dashContainerModel.addView(id, stack, index + 1)
127
- };
128
-
129
- // Group if necessary
130
- if (groupName) {
131
- let groupSpec = ret.find(it => it.groupName === groupName);
132
- if (!groupSpec) {
133
- groupSpec = {groupName, text: groupName, items: []};
134
- ret.push(groupSpec);
135
- }
136
- groupSpec.items.push(item);
137
- } else {
138
- ret.push(item);
139
- hasUngrouped = true;
140
- }
141
- });
142
-
143
- // Convert groups into nested menu items
144
- return ret.map(item => {
145
- if (!item.groupName) return item;
146
-
147
- // If we have any ungrouped root items (i.e. in a 'mixed mode'),
148
- // insert a hidden icon to align the item text.
149
- const icon = hasUngrouped ? Icon.angleRight({style: {visibility: 'hidden'}}) : undefined,
150
- {text, items} = item;
151
-
152
- return {icon, text, items};
153
- });
118
+ return createViewSpecMenuItems(addableSpecs, ({id, title, icon}) => ({
119
+ text: title,
120
+ icon: icon,
121
+ actionFn: () => dashContainerModel.addView(id, stack, index + 1)
122
+ }));
154
123
  }
@@ -0,0 +1,90 @@
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 {MenuItem, MenuItemLike} from '@xh/hoist/core';
8
+ import {Icon} from '@xh/hoist/icon';
9
+ import {compact, split} from 'lodash';
10
+ import type {DashViewSpec} from '../DashViewSpec';
11
+
12
+ /**
13
+ * A group of view specs, built from their `groupName`. A slash-delimited name nests groups - e.g.
14
+ * a spec with `groupName: 'Charts/Line'` sits in group 'Line', within group 'Charts'.
15
+ * @internal
16
+ */
17
+ export class ViewSpecGroup<T extends DashViewSpec = DashViewSpec> {
18
+ /** One segment of a `groupName` - the name shown for this group. */
19
+ readonly name: string;
20
+
21
+ /** Nested groups and view specs, in the order each first appears in the source specs. */
22
+ readonly children: ViewSpecNode<T>[] = [];
23
+
24
+ constructor(name: string) {
25
+ this.name = name;
26
+ }
27
+
28
+ /** All view specs within this group, including those within its nested groups. */
29
+ get allViewSpecs(): T[] {
30
+ return this.children.flatMap(it => (it instanceof ViewSpecGroup ? it.allViewSpecs : it));
31
+ }
32
+ }
33
+
34
+ /** @internal */
35
+ export type ViewSpecNode<T extends DashViewSpec = DashViewSpec> = ViewSpecGroup<T> | T;
36
+
37
+ /**
38
+ * Arrange view specs into groups by their `groupName`, split on '/' into nested groups. Blank
39
+ * segments are ignored and surrounding spaces trimmed, so `Charts / Line` matches `Charts/Line`.
40
+ *
41
+ * @returns top-level groups and ungrouped specs, in the order each first appears.
42
+ * @internal
43
+ */
44
+ export function groupViewSpecs<T extends DashViewSpec>(viewSpecs: T[]): ViewSpecNode<T>[] {
45
+ const root = new ViewSpecGroup<T>(null);
46
+ viewSpecs.forEach(viewSpec => {
47
+ let parent = root;
48
+ compact(split(viewSpec.groupName, '/').map(it => it.trim())).forEach(name => {
49
+ let group = parent.children.find(
50
+ it => it instanceof ViewSpecGroup && it.name === name
51
+ ) as ViewSpecGroup<T>;
52
+ if (!group) {
53
+ group = new ViewSpecGroup<T>(name);
54
+ parent.children.push(group);
55
+ }
56
+ parent = group;
57
+ });
58
+ parent.children.push(viewSpec);
59
+ });
60
+ return root.children;
61
+ }
62
+
63
+ /**
64
+ * Create menu items for adding views, nesting specs into submenus by their `groupName`. Groups
65
+ * and specs are listed in the order each first appears.
66
+ *
67
+ * @param viewSpecs - specs to list, in their defined order.
68
+ * @param createItem - creates the menu item for a single spec.
69
+ * @internal
70
+ */
71
+ export function createViewSpecMenuItems<T extends DashViewSpec>(
72
+ viewSpecs: T[],
73
+ createItem: (viewSpec: T) => MenuItem
74
+ ): MenuItemLike[] {
75
+ const toMenuItems = (nodes: ViewSpecNode<T>[]): MenuItemLike[] => {
76
+ // If any specs sit alongside groups (i.e. in a 'mixed mode'),
77
+ // give each group a hidden icon to align its text with theirs.
78
+ const groupIcon = nodes.some(it => !(it instanceof ViewSpecGroup))
79
+ ? Icon.angleRight({style: {visibility: 'hidden'}})
80
+ : undefined;
81
+
82
+ return nodes.map(it =>
83
+ it instanceof ViewSpecGroup
84
+ ? {icon: groupIcon, text: it.name, items: toMenuItems(it.children)}
85
+ : createItem(it)
86
+ );
87
+ };
88
+
89
+ return toMenuItems(groupViewSpecs(viewSpecs));
90
+ }
@@ -6,12 +6,11 @@
6
6
  */
7
7
  import {box, div, hframe, span} from '@xh/hoist/cmp/layout';
8
8
  import {TabContainerModel, TabModel} from '@xh/hoist/cmp/tab';
9
- import {TabSwitcherProps} from '@xh/hoist/cmp/tab/Types';
9
+ import {TabSwitcherMenuContext, TabSwitcherProps} from '@xh/hoist/cmp/tab/Types';
10
10
  import {hoistCmp, HoistModel, useLocalModel, uses} from '@xh/hoist/core';
11
11
  import {button} from '@xh/hoist/desktop/cmp/button';
12
12
  import '@xh/hoist/desktop/register';
13
13
  import {contextMenu} from '@xh/hoist/desktop/cmp/contextmenu';
14
- import {getContextMenuItem} from '@xh/hoist/desktop/cmp/tab/impl/TabContextMenuItems';
15
14
  import {Icon} from '@xh/hoist/icon';
16
15
  import {
17
16
  menu,
@@ -137,11 +136,10 @@ export const [TabSwitcher, tabSwitcher] = hoistCmp.withFactory<TabSwitcherProps>
137
136
  }),
138
137
  onContextMenu: e => {
139
138
  const domRect = e.currentTarget.getBoundingClientRect(),
140
- menuItems = (switcherConfig.extraMenuItems ?? []).map(it =>
141
- getContextMenuItem(it, {contextMenuEvent: e, tab})
142
- );
139
+ menuItems = switcherConfig.extraMenuItems ?? [];
143
140
  if (isEmpty(menuItems)) return;
144
- showContextMenu(contextMenu({menuItems}), {
141
+ const context: TabSwitcherMenuContext = {contextMenuEvent: e, tab};
142
+ showContextMenu(contextMenu({menuItems, context}), {
145
143
  left: orientation === 'left' ? domRect.right : domRect.left,
146
144
  top: orientation === 'top' ? domRect.bottom : domRect.top
147
145
  });
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import {box, div, hframe} from '@xh/hoist/cmp/layout';
8
8
  import {TabContainerModel, TabModel} from '@xh/hoist/cmp/tab';
9
- import {TabSwitcherProps} from '@xh/hoist/cmp/tab/Types';
9
+ import {TabSwitcherMenuContext, TabSwitcherProps} from '@xh/hoist/cmp/tab/Types';
10
10
  import {
11
11
  hoistCmp,
12
12
  HoistModel,
@@ -163,12 +163,11 @@ const tabCmp = hoistCmp.factory<TabProps>(({tab, index, localModel, model}) => {
163
163
  if (!disabled) model.activate(tab.id);
164
164
  },
165
165
  onContextMenu: e => {
166
- const domRect = e.currentTarget.getBoundingClientRect();
166
+ const domRect = e.currentTarget.getBoundingClientRect(),
167
+ context: TabSwitcherMenuContext = {contextMenuEvent: e, tab};
167
168
  consumeEvent(e);
168
169
  showContextMenu(
169
- contextMenu({
170
- menuItems: model.getContextMenuItems(e, tab)
171
- }),
170
+ contextMenu({menuItems: model.getContextMenuItems(tab), context}),
172
171
  {
173
172
  left: props.orientation === 'left' ? domRect.right : domRect.left,
174
173
  top: props.orientation === 'top' ? domRect.bottom : domRect.top
@@ -11,11 +11,9 @@ import {
11
11
  TabSwitcherMenuContext
12
12
  } from '@xh/hoist/cmp/tab/Types';
13
13
  import {HoistModel, MenuItemLike, MenuToken, ReactionSpec, XH} from '@xh/hoist/core';
14
- import {getContextMenuItem} from '@xh/hoist/desktop/cmp/tab/impl/TabContextMenuItems';
15
14
  import {Icon} from '@xh/hoist/icon';
16
15
  import {compact, find} from 'lodash';
17
16
  import {action, computed, when, observableRef} from '@xh/hoist/mobx';
18
- import React from 'react';
19
17
 
20
18
  /**
21
19
  * State management for the DynamicTabSwitcher component.
@@ -99,10 +97,7 @@ export class DynamicTabSwitcherModel extends HoistModel implements IDynamicTabSw
99
97
  this.visibleTabState = this.visibleTabState.filter(it => it.tabId !== tabId);
100
98
  }
101
99
 
102
- getContextMenuItems(
103
- e: React.MouseEvent<HTMLDivElement, MouseEvent>,
104
- tab: TabModel
105
- ): Array<MenuItemLike<MenuToken, TabSwitcherMenuContext>> {
100
+ getContextMenuItems(tab: TabModel): Array<MenuItemLike<MenuToken, TabSwitcherMenuContext>> {
106
101
  const isFavorite = this.isTabFavorite(tab.id);
107
102
  return [
108
103
  {
@@ -110,7 +105,7 @@ export class DynamicTabSwitcherModel extends HoistModel implements IDynamicTabSw
110
105
  text: isFavorite ? 'Remove from Favorites' : 'Add to Favorites',
111
106
  actionFn: () => this.toggleTabFavorite(tab.id)
112
107
  },
113
- ...this.extraMenuItems.map(item => getContextMenuItem(item, {contextMenuEvent: e, tab}))
108
+ ...this.extraMenuItems
114
109
  ];
115
110
  }
116
111
 
@@ -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 an optional version override.
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 @xh/hoist@next` until the registry resolves the `next` dist-tag
42
- to the version just published (10 minute limit). Publishing returns once npm accepts the tarball,
43
- but the new version is not guaranteed to be resolvable at that moment.
44
- - Finally fires a `repository_dispatch` (`hoist-react-snapshot`) to `xh/toolbox`, which rebuilds
45
- and redeploys Toolbox against the new snapshot. The dispatch authenticates as the org-owned
46
- **XH Build Bot** GitHub App via a short-lived installation token minted by
47
- `actions/create-github-app-token`, scoped to the toolbox repo with Contents: write. Toolbox runs
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 | Snapshot, Release, Unpublish | Auth token for publishing to the npm public registry |
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` |
@@ -373,7 +373,7 @@
373
373
  "mcpCategory": "devops",
374
374
  "viewerCategory": "devops",
375
375
  "description": "GitHub Actions workflows for linting, CodeQL analysis, and npm publishing of hoist-react.",
376
- "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"]
377
377
  },
378
378
  {
379
379
  "id": "docs/build-and-deploy-app.md",
@@ -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. The
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
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xh/hoist",
3
- "version": "89.1.0",
3
+ "version": "89.2.0",
4
4
  "description": "Hoist add-on for building and deploying React Applications.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -31,6 +31,7 @@ export interface FetchServiceDefaults {
31
31
  autoGenCorrelationIds?: boolean | ((opts: FetchOptions) => boolean);
32
32
  correlationIdHeaderKey?: string;
33
33
  genCorrelationId?: () => string;
34
+ propagateTrace?: boolean | ((opts: FetchOptions) => boolean);
34
35
  }
35
36
 
36
37
  /**
@@ -48,6 +49,8 @@ export interface FetchServiceDefaults {
48
49
  * - Configurable timeouts (default 30s) via {@link FetchOptions.timeout}
49
50
  * - Auto-abort of duplicate in-flight requests via {@link FetchOptions.autoAbortKey}
50
51
  * - Optional correlation IDs for request tracking (see `defaults.autoGenCorrelationIds`)
52
+ * - W3C `traceparent` headers when tracing is enabled, sent by default only to the app's own
53
+ * server (see `defaults.propagateTrace` and {@link FetchOptions.propagateTrace})
51
54
  * - Request/response interceptors via {@link addInterceptor}
52
55
  * - Default headers for all requests via {@link addDefaultHeaders}
53
56
  * - Rich exception handling with HTTP status, server messages, and trace IDs
@@ -63,9 +66,25 @@ export class FetchService extends HoistService {
63
66
  static defaults: FetchServiceDefaults = {
64
67
  autoGenCorrelationIds: false,
65
68
  correlationIdHeaderKey: 'X-Correlation-ID',
66
- genCorrelationId: () => FetchService.defaultIdGenerator.rnd()
69
+ genCorrelationId: () => FetchService.defaultIdGenerator.rnd(),
70
+ propagateTrace: opts => FetchService.isHoistServerUrl(opts.url)
67
71
  };
68
72
 
73
+ /**
74
+ * Does a request url target the app's own server? True for relative and root-relative urls,
75
+ * and for absolute urls on the origin of the page or of {@link XH.baseUrl}.
76
+ */
77
+ static isHoistServerUrl(url: string): boolean {
78
+ if (!url?.includes('//')) return true;
79
+ try {
80
+ const {origin} = window.location,
81
+ target = new URL(url, origin).origin;
82
+ return target === origin || target === new URL(XH.baseUrl, origin).origin;
83
+ } catch {
84
+ return false;
85
+ }
86
+ }
87
+
69
88
  NO_JSON_RESPONSES = [StatusCodes.NO_CONTENT, StatusCodes.RESET_CONTENT];
70
89
 
71
90
  /**
@@ -383,7 +402,7 @@ export class FetchService extends HoistService {
383
402
  'Content-Type': isForm ? 'application/x-www-form-urlencoded' : 'text/plain',
384
403
  ...defaultHeaders,
385
404
  ...(opts.asJson ? {Accept: 'application/json'} : {}),
386
- ...(span
405
+ ...(span && this.shouldPropagateTrace(opts)
387
406
  ? {traceparent: formatTraceparent(span.traceId, span.spanId, span.sampled)}
388
407
  : {}),
389
408
  ...opts.headers
@@ -403,6 +422,12 @@ export class FetchService extends HoistService {
403
422
  return {...opts, method, headers};
404
423
  }
405
424
 
425
+ private shouldPropagateTrace(opts: FetchOptions): boolean {
426
+ if (!isNil(opts.propagateTrace)) return opts.propagateTrace;
427
+ const {propagateTrace} = FetchService.defaults;
428
+ return isFunction(propagateTrace) ? propagateTrace(opts) : propagateTrace;
429
+ }
430
+
406
431
  private async managedFetchAsync(opts: FetchOptions, callCtx: CallContext): Promise<any> {
407
432
  // Prepare auto-aborter
408
433
  const {autoAborters, defaultTimeout} = this,
@@ -860,6 +885,17 @@ export interface FetchOptions {
860
885
  */
861
886
  correlationId?: string | boolean;
862
887
 
888
+ /**
889
+ * True to send a W3C `traceparent` header with this request, false to omit it. Applies only
890
+ * when tracing is enabled. The request still records a client span either way, but only a
891
+ * server that receives the header can join the trace. Defaults to
892
+ * `FetchService.defaults.propagateTrace`, which sends the header only to the app's own server.
893
+ *
894
+ * Note `traceparent` is not a CORS-safelisted header. A cross-origin server must list it in
895
+ * `Access-Control-Allow-Headers`, or the browser blocks the request.
896
+ */
897
+ propagateTrace?: boolean;
898
+
863
899
  /**
864
900
  * Parameters to encode and append as a query string, or send with the request body
865
901
  * (for POSTs/PUTs sending form-url-encoded).
package/svc/README.md CHANGED
@@ -100,6 +100,7 @@ Managed HTTP requests with enhancements over the native Fetch API.
100
100
 
101
101
  **Key Features:**
102
102
  - Automatic correlation IDs for request tracking
103
+ - W3C `traceparent` headers on requests to the app's own server, when tracing is enabled
103
104
  - Configurable timeouts (default 30 seconds)
104
105
  - Auto-abort of duplicate requests via `autoAbortKey`
105
106
  - Request/response interceptors
@@ -136,19 +137,22 @@ override async doLoadAsync(loadSpec: LoadSpec) {
136
137
  | `headers` | object | Additional headers |
137
138
  | `timeout` | number | Timeout in ms (default 30000) |
138
139
  | `autoAbortKey` | string | Cancel previous requests with same key |
140
+ | `propagateTrace` | boolean | Send a `traceparent` header when tracing is enabled. Overrides `FetchService.defaults.propagateTrace` |
139
141
  | `loadSpec` | LoadSpec | Metadata for tracking |
140
142
  | `span` | Span | Parent span for tracing. Typically supplied via a `Runner` chain (`runner.fetchJson(...)`) rather than set directly |
141
143
 
142
144
  **App-Level Defaults (`FetchService.defaults`):**
143
145
 
144
- FetchService exposes a `static defaults` object for correlation ID configuration. Best configured
145
- in the app's `Bootstrap` module to ensure settings are active from the very first request.
146
+ FetchService exposes a `static defaults` object for correlation ID and trace header configuration.
147
+ Best configured in the app's `Bootstrap` module to ensure settings are active from the very first
148
+ request.
146
149
 
147
150
  | Property | Type | Default | Description |
148
151
  |----------|------|---------|-------------|
149
152
  | `autoGenCorrelationIds` | `boolean \| function` | `false` | Auto-generate correlation IDs. Set `true` or a `(opts) => boolean` function for per-request control |
150
153
  | `genCorrelationId` | `() => string` | 16-char random string | Custom ID generator function |
151
154
  | `correlationIdHeaderKey` | `string` | `'X-Correlation-ID'` | HTTP header name for correlation IDs |
155
+ | `propagateTrace` | `boolean \| function` | App's own server only | Send a `traceparent` header when tracing is enabled. Set `true` for all requests, or a `(opts) => boolean` function. See [Trace headers on fetch requests](../docs/telemetry.md#trace-headers-on-fetch-requests) |
152
156
 
153
157
  ```typescript
154
158
  // In Bootstrap module
@@ -321,7 +325,7 @@ category while all other entries continue to require INFO or above.
321
325
  > tracing, metrics, and activity tracking.
322
326
 
323
327
  Client-side distributed tracing — creates spans for user actions and fetch calls, injects
324
- `traceparent` headers on outgoing requests, and batches completed spans for export to the
328
+ `traceparent` headers on requests to the app's own server, and batches completed spans for export to the
325
329
  Hoist server. Exceptions thrown during traced operations include a `traceId` for correlation
326
330
  with server-side traces. Controlled by the `xhTraceConfig` soft config. Requires hoist-core 37+.
327
331
 
@@ -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
- }