@xh/hoist 89.1.0 → 90.0.0-SNAPSHOT.1792498946334

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 CHANGED
@@ -11,6 +11,17 @@
11
11
  codebase, or with the symbol itself (`Foo.bar` now ...) when a living API changed behavior.
12
12
  3. Plain ASCII punctuation only. Use " - " for in-sentence breaks, never an em dash.
13
13
  -->
14
+ ## 90.0.0-SNAPSHOT - unreleased
15
+
16
+ ### 🎁 New Features
17
+
18
+ * `DashViewSpec.groupName` now nests groups when it separates names with `/`, as in `Charts/Line`.
19
+ The add view menus of `DashContainer` and `DashCanvas` show each level as a submenu, and
20
+ `DashCanvasWidgetChooser` shows each as a card. Existing group names that contain `/` now nest.
21
+ * `DashCanvas` add view menus and `DashCanvasWidgetChooser` now list each group where its first
22
+ view spec appears, as `DashContainer` does, not ahead of all ungrouped specs. To keep groups at
23
+ the top, define grouped specs first.
24
+
14
25
  ## 89.1.0 - 2026-10-19
15
26
 
16
27
  ### 🎁 New Features
@@ -33,6 +44,9 @@
33
44
  * Fixed desktop `NumberInput` with `min` or `max` rendering blank on mount when its formatted value
34
45
  was not a plain number, as with `displayWithCommas` and a value of 1,000 or more, or a
35
46
  `valueLabel`. Changing `min` or `max` on such an input could also set its value to 0.
47
+ * Fixed a grouped `Grid` showing its grouped column again on any column state change, such as a
48
+ resize, an autosize or a view restore. A header drag while grouped also saved the column as
49
+ hidden, so it stayed hidden after ungrouping.
36
50
  * Fixed `onShowLazy` tabs and other managed refresh contexts replaying a missed auto-refresh as a
37
51
  manual refresh when shown. The replay now stays an auto-refresh unless a missed refresh was manual.
38
52
  * Fixed a model created with `creates()` re-running `onLinked()` on every render when its component
@@ -673,6 +673,12 @@ export declare class GridModel extends HoistModel {
673
673
  * property is not updated with state changes.
674
674
  */
675
675
  isColumnVisible(colId: string): boolean;
676
+ /**
677
+ * True if ag-Grid is hiding this column because the grid is grouped by it. Hoist leaves the
678
+ * visibility of such a column to ag-Grid, keeping its own `hidden` state for after ungrouping.
679
+ * @internal
680
+ */
681
+ isColumnHiddenByGrouping(colId: string): boolean;
676
682
  setColumnVisible(colId: string, visible: boolean): void;
677
683
  showColumn(colId: string): void;
678
684
  hideColumn(colId: string): void;
@@ -17,7 +17,8 @@ export interface DashViewSpec {
17
17
  icon?: ReactElement;
18
18
  /**
19
19
  * Group name to display within the add view component. The default context menu will
20
- * automatically group its available views if provided.
20
+ * automatically group its available views if provided. Separate names with '/' to nest
21
+ * groups - e.g. `Charts/Line`.
21
22
  */
22
23
  groupName?: string;
23
24
  /**
@@ -2,7 +2,7 @@
2
2
  * Context menu to add items to a DashCanvas
3
3
  *
4
4
  * Available view specs are listed in their defined order, optionally
5
- * grouped by their 'groupName' property
5
+ * grouped by their `groupName` property into (nested) submenus.
6
6
  * @internal
7
7
  */
8
8
  export declare const dashCanvasContextMenu: import("@xh/hoist/core").ElementFactory<import("@xh/hoist/core").DefaultHoistProps<import("@xh/hoist/core").HoistModel>>;
@@ -7,7 +7,8 @@ export interface DashCanvasWidgetChooserProps extends HoistProps, TestSupportPro
7
7
  }
8
8
  /**
9
9
  * Displays available {@link DashCanvasViewSpec}s as draggable items that can be dropped onto a
10
- * {@link DashCanvas} to add new views. View specs are listed in their defined order, grouped by
11
- * their `groupName` property if present. Place inside a collapsible panel alongside a DashCanvas.
10
+ * {@link DashCanvas} to add new views. View specs are listed in their defined order, grouped into
11
+ * (nested) cards by their `groupName` property if present. Place inside a collapsible panel
12
+ * alongside a DashCanvas.
12
13
  */
13
14
  export declare const DashCanvasWidgetChooser: import("react").FC<DashCanvasWidgetChooserProps>, dashCanvasWidgetChooser: import("@xh/hoist/core").ElementFactory<DashCanvasWidgetChooserProps>;
@@ -3,7 +3,7 @@ import { DashContainerModel } from '../DashContainerModel';
3
3
  * Context menu for title bar/tabs of a stack in a DashContainer.
4
4
  *
5
5
  * Available view specs are listed in their defined order, optionally
6
- * grouped by their `groupName` property
6
+ * grouped by their `groupName` property into (nested) submenus.
7
7
  *
8
8
  * @internal
9
9
  */
@@ -0,0 +1,35 @@
1
+ import type { MenuItem, MenuItemLike } from '@xh/hoist/core';
2
+ import type { DashViewSpec } from '../DashViewSpec';
3
+ /**
4
+ * A group of view specs, built from their `groupName`. A slash-delimited name nests groups - e.g.
5
+ * a spec with `groupName: 'Charts/Line'` sits in group 'Line', within group 'Charts'.
6
+ * @internal
7
+ */
8
+ export declare class ViewSpecGroup<T extends DashViewSpec = DashViewSpec> {
9
+ /** One segment of a `groupName` - the name shown for this group. */
10
+ readonly name: string;
11
+ /** Nested groups and view specs, in the order each first appears in the source specs. */
12
+ readonly children: ViewSpecNode<T>[];
13
+ constructor(name: string);
14
+ /** All view specs within this group, including those within its nested groups. */
15
+ get allViewSpecs(): T[];
16
+ }
17
+ /** @internal */
18
+ export type ViewSpecNode<T extends DashViewSpec = DashViewSpec> = ViewSpecGroup<T> | T;
19
+ /**
20
+ * Arrange view specs into groups by their `groupName`, split on '/' into nested groups. Blank
21
+ * segments are ignored and surrounding spaces trimmed, so `Charts / Line` matches `Charts/Line`.
22
+ *
23
+ * @returns top-level groups and ungrouped specs, in the order each first appears.
24
+ * @internal
25
+ */
26
+ export declare function groupViewSpecs<T extends DashViewSpec>(viewSpecs: T[]): ViewSpecNode<T>[];
27
+ /**
28
+ * Create menu items for adding views, nesting specs into submenus by their `groupName`. Groups
29
+ * and specs are listed in the order each first appears.
30
+ *
31
+ * @param viewSpecs - specs to list, in their defined order.
32
+ * @param createItem - creates the menu item for a single spec.
33
+ * @internal
34
+ */
35
+ export declare function createViewSpecMenuItems<T extends DashViewSpec>(viewSpecs: T[], createItem: (viewSpec: T) => MenuItem): MenuItemLike[];
package/cmp/grid/Grid.ts CHANGED
@@ -442,7 +442,7 @@ export class GridLocalModel extends HoistModel {
442
442
 
443
443
  // Re-assert configured visibility - AG Grid re-shows a column when ungrouped (#4473).
444
444
  const state = model.columnState
445
- .filter(({colId}) => !groupBy.includes(colId))
445
+ .filter(({colId}) => !model.isColumnHiddenByGrouping(colId))
446
446
  .map(({colId, hidden}) => ({colId, hide: hidden}));
447
447
  agApi.applyColumnState({state});
448
448
  }
@@ -523,7 +523,7 @@ export class GridLocalModel extends HoistModel {
523
523
  hasChanges = true;
524
524
  }
525
525
 
526
- if (agCol.hide !== hidden) {
526
+ if (agCol.hide !== hidden && !model.isColumnHiddenByGrouping(colId)) {
527
527
  ret.hide = hidden;
528
528
  hasChanges = true;
529
529
  }
@@ -1439,7 +1439,7 @@ export class GridModel extends HoistModel {
1439
1439
  return {
1440
1440
  colId,
1441
1441
  pinned: isBoolean(pinned) ? (pinned ? 'left' : null) : pinned,
1442
- hidden: !!hide,
1442
+ hidden: this.isColumnHiddenByGrouping(colId) ? null : !!hide,
1443
1443
  width: col.flex ? undefined : width
1444
1444
  };
1445
1445
  }
@@ -1590,6 +1590,19 @@ export class GridModel extends HoistModel {
1590
1590
  return state ? !state.hidden : false;
1591
1591
  }
1592
1592
 
1593
+ /**
1594
+ * True if ag-Grid is hiding this column because the grid is grouped by it. Hoist leaves the
1595
+ * visibility of such a column to ag-Grid, keeping its own `hidden` state for after ungrouping.
1596
+ * @internal
1597
+ */
1598
+ isColumnHiddenByGrouping(colId: string): boolean {
1599
+ const {agApi} = this;
1600
+ if (!agApi || !this.groupBy.includes(colId)) return false;
1601
+
1602
+ const suppress = agApi.getGridOption('suppressGroupChangesColumnVisibility');
1603
+ return suppress !== true && suppress !== 'suppressHideOnGroup';
1604
+ }
1605
+
1593
1606
  setColumnVisible(colId: string, visible: boolean) {
1594
1607
  this.updateColumnState([{colId, hidden: !visible}]);
1595
1608
  }
@@ -807,7 +807,8 @@ export class Column {
807
807
  },
808
808
  headerClass: getAgHeaderClassFn(this),
809
809
  headerTooltip: this.headerTooltip,
810
- hide: this.hidden,
810
+ // Undefined keeps ag-Grid's current visibility on update.
811
+ hide: gridModel.isColumnHiddenByGrouping(this.colId) ? undefined : this.hidden,
811
812
  columnGroupShow: toAgColumnGroupShow(this.groupShowMode),
812
813
  minWidth: this.minWidth,
813
814
  maxWidth: this.maxWidth,
@@ -28,7 +28,8 @@ export interface DashViewSpec {
28
28
 
29
29
  /**
30
30
  * Group name to display within the add view component. The default context menu will
31
- * automatically group its available views if provided.
31
+ * automatically group its available views if provided. Separate names with '/' to nest
32
+ * groups - e.g. `Charts/Line`.
32
33
  */
33
34
  groupName?: string;
34
35
 
@@ -78,7 +78,7 @@ DashViewSpec (base interface)
78
78
  ├── content: Content # Rendered content
79
79
  ├── title: string # Default title (defaults to startCase(id))
80
80
  ├── icon: ReactElement # Default icon
81
- ├── groupName: string # Menu grouping
81
+ ├── groupName: string # Menu grouping, '/' to nest
82
82
  ├── unique: boolean # Allow multiple instances?
83
83
  ├── allowAdd/Remove/Rename # Permission flags
84
84
  └── omit: Thunkable<boolean> # Exclude from dashboard
@@ -367,9 +367,10 @@ canvasModel.isEmpty; // No widgets?
367
367
  view specs for a `DashCanvas`. Users can drag widgets from the chooser and drop them onto the
368
368
  canvas. It is typically placed inside a collapsible panel alongside the canvas.
369
369
 
370
- Available view specs are listed in their defined order, grouped by their `groupName` property
371
- if present. Specs with `unique: true` that already have an instance on the canvas are
372
- automatically hidden from the chooser.
370
+ Available view specs are listed in their defined order, grouped into collapsible cards by their
371
+ `groupName` property if present - a slash-delimited name nests cards within cards. Specs with
372
+ `unique: true` that already have an instance on the canvas are automatically hidden from the
373
+ chooser.
373
374
 
374
375
  ### Requirements
375
376
 
@@ -413,7 +414,7 @@ Both dash types share these base properties on their ViewSpecs:
413
414
  | `content` | `Content` | View content to render. Required. |
414
415
  | `title` | `string` | Default display title. Defaults to `startCase(id)`. |
415
416
  | `icon` | `ReactElement` | Display icon. |
416
- | `groupName` | `string` | Group name for the "Add" menu — specs with the same group are nested into a submenu. |
417
+ | `groupName` | `string` | Group name for the "Add" menu - specs with the same group are nested into a submenu. Separate names with `/` to nest groups, e.g. `Charts/Line`. Each group is listed where its first spec appears. |
417
418
  | `omit` | `Thunkable<boolean>` | Skip this spec entirely. References in state are quietly dropped. Useful for role-based exclusion. Default `false`. |
418
419
  | `unique` | `boolean` | Only one instance allowed at a time. Default `false`. |
419
420
  | `allowAdd` | `boolean` | Can add new instances via the menu. Existing instances in state are still loaded. Default `true`. |
@@ -15,7 +15,7 @@ import {isEmpty} from 'lodash';
15
15
  * Context menu to add items to a DashCanvas
16
16
  *
17
17
  * Available view specs are listed in their defined order, optionally
18
- * grouped by their 'groupName' property
18
+ * grouped by their `groupName` property into (nested) submenus.
19
19
  * @internal
20
20
  */
21
21
  export const dashCanvasContextMenu = hoistCmp.factory({
@@ -6,7 +6,7 @@
6
6
  */
7
7
 
8
8
  import {type MenuItemLike} from '@xh/hoist/core';
9
- import {Icon} from '@xh/hoist/icon';
9
+ import {createViewSpecMenuItems} from '../../impl/DashUtils';
10
10
  import {DashCanvasModel} from '../DashCanvasModel';
11
11
 
12
12
  /**
@@ -21,64 +21,29 @@ export function createViewMenuItems({
21
21
  }): MenuItemLike[] {
22
22
  if (!dashCanvasModel.ref.current) return [];
23
23
 
24
- const groupedItems = {},
25
- ungroupedItems = [],
26
- x = position?.x ?? 0,
24
+ const x = position?.x ?? 0,
27
25
  y = position?.y ?? 0,
28
- addPosition = !viewId ? calcAddPosition(x, y, dashCanvasModel) : null;
29
-
30
- const addToGroup = (item, groupName) => {
31
- const group = groupedItems[groupName];
32
- if (group) {
33
- group.push(item);
34
- } else {
35
- groupedItems[groupName] = [item];
36
- }
37
- };
38
-
39
- dashCanvasModel.viewSpecs
40
- .filter(viewSpec => {
26
+ addPosition = !viewId ? calcAddPosition(x, y, dashCanvasModel) : null,
27
+ addableSpecs = dashCanvasModel.viewSpecs.filter(viewSpec => {
41
28
  return (
42
29
  viewSpec.allowAdd &&
43
30
  (!viewSpec.unique || !dashCanvasModel.getViewsBySpecId(viewSpec.id).length)
44
31
  );
45
- })
46
- .forEach(viewSpec => {
47
- const {title, icon, groupName, id} = viewSpec,
48
- item = {
49
- text: title,
50
- icon: icon,
51
- actionFn: () => {
52
- if (replaceExisting) {
53
- dashCanvasModel.replaceView(viewId, id);
54
- } else {
55
- dashCanvasModel
56
- .addViewInternal(id, {layout: addPosition, previousViewId: viewId})
57
- .ensureVisible();
58
- }
59
- }
60
- };
32
+ });
61
33
 
62
- if (groupName) {
63
- addToGroup(item, groupName);
34
+ return createViewSpecMenuItems(addableSpecs, ({title, icon, id}) => ({
35
+ text: title,
36
+ icon: icon,
37
+ actionFn: () => {
38
+ if (replaceExisting) {
39
+ dashCanvasModel.replaceView(viewId, id);
64
40
  } else {
65
- ungroupedItems.push(item);
41
+ dashCanvasModel
42
+ .addViewInternal(id, {layout: addPosition, previousViewId: viewId})
43
+ .ensureVisible();
66
44
  }
67
- });
68
-
69
- return [
70
- ...Object.keys(groupedItems).map(group => {
71
- // If we have any ungrouped root items (i.e. in a 'mixed mode'),
72
- // insert a hidden icon to align the item text.
73
- const icon = ungroupedItems.length
74
- ? Icon.angleRight({style: {visibility: 'hidden'}})
75
- : undefined,
76
- text = group,
77
- items = groupedItems[group];
78
- return {icon, text, items};
79
- }),
80
- ...ungroupedItems
81
- ];
45
+ }
46
+ }));
82
47
  }
83
48
 
84
49
  /**
@@ -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
+ }
@@ -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",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xh/hoist",
3
- "version": "89.1.0",
3
+ "version": "90.0.0-SNAPSHOT.1792498946334",
4
4
  "description": "Hoist add-on for building and deploying React Applications.",
5
5
  "repository": {
6
6
  "type": "git",