@xh/hoist 89.0.1 → 89.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/build/types/cmp/grid/GridModel.d.ts +6 -0
  3. package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
  4. package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
  5. package/build/types/core/XH.d.ts +2 -1
  6. package/build/types/core/model/HoistModel.d.ts +1 -0
  7. package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
  8. package/build/types/core/persist/PersistenceProvider.d.ts +3 -0
  9. package/build/types/data/cube/View.d.ts +0 -2
  10. package/build/types/data/cube/impl/RowCache.d.ts +1 -1
  11. package/build/types/data/cube/row/BaseRow.d.ts +5 -0
  12. package/build/types/desktop/cmp/dash/DashViewSpec.d.ts +2 -1
  13. package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
  14. package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
  15. package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
  16. package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -0
  17. package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
  18. package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
  19. package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
  20. package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
  21. package/build/types/svc/FetchService.d.ts +19 -0
  22. package/build/types/test-support/agGrid.d.ts +2 -0
  23. package/build/types/test-support/hoistCore.d.ts +7 -1
  24. package/build/types/test-support/index.d.ts +1 -0
  25. package/build/types/test-support/jsonBlobs.d.ts +130 -0
  26. package/build/types/test-support/testApp.d.ts +5 -2
  27. package/cmp/grid/Grid.ts +2 -2
  28. package/cmp/grid/GridModel.ts +14 -1
  29. package/cmp/grid/columns/Column.ts +3 -2
  30. package/cmp/input/impl/LiveCommas.ts +59 -0
  31. package/cmp/viewmanager/ViewManagerModel.ts +25 -7
  32. package/core/XH.ts +8 -3
  33. package/core/model/HoistModel.ts +4 -2
  34. package/core/model/Hooks.ts +1 -0
  35. package/core/model/ManagedRefreshContextModel.ts +5 -1
  36. package/core/persist/PersistenceProvider.ts +15 -1
  37. package/data/cube/View.ts +3 -9
  38. package/data/cube/impl/RowCache.ts +2 -2
  39. package/data/cube/row/BaseRow.ts +14 -1
  40. package/data/cube/row/ParentRow.ts +1 -1
  41. package/desktop/cmp/dash/DashViewSpec.ts +2 -1
  42. package/desktop/cmp/dash/README.md +6 -5
  43. package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
  44. package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
  45. package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
  46. package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
  47. package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
  48. package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
  49. package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
  50. package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
  51. package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
  52. package/desktop/cmp/input/NumberInput.ts +51 -12
  53. package/desktop/cmp/input/Select.ts +25 -7
  54. package/desktop/cmp/tab/TabSwitcher.ts +4 -6
  55. package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
  56. package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
  57. package/docs/README.md +2 -0
  58. package/docs/build-and-publish.md +21 -11
  59. package/docs/companion-library-docs.md +205 -0
  60. package/docs/doc-registry.json +9 -1
  61. package/docs/lifecycle-app.md +17 -0
  62. package/docs/lifecycle-models-and-services.md +2 -1
  63. package/docs/persistence.md +2 -0
  64. package/docs/telemetry.md +29 -0
  65. package/docs/unit-testing.md +54 -3
  66. package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
  67. package/docs/version-compatibility.md +2 -1
  68. package/icon/README.md +4 -1
  69. package/mcp/README.md +79 -4
  70. package/mcp/cli/docs.ts +75 -30
  71. package/mcp/data/doc-id-resolver.ts +50 -9
  72. package/mcp/data/doc-registry.ts +462 -44
  73. package/mcp/data/doc-search.ts +25 -6
  74. package/mcp/formatters/docs.ts +136 -36
  75. package/mcp/instructions.ts +69 -0
  76. package/mcp/resources/docs.ts +10 -8
  77. package/mcp/server.ts +7 -13
  78. package/mcp/tools/docs.ts +64 -18
  79. package/mcp/util/paths.ts +85 -2
  80. package/mobile/cmp/input/NumberInput.ts +42 -4
  81. package/package.json +19 -19
  82. package/public/msal-redirect-bridge.min.js +1 -1
  83. package/svc/FetchService.ts +38 -2
  84. package/svc/JsonBlobService.ts +7 -4
  85. package/svc/README.md +7 -3
  86. package/test-support/agGrid.ts +12 -2
  87. package/test-support/hoistCore.ts +32 -5
  88. package/test-support/index.ts +1 -0
  89. package/test-support/jsonBlobs.ts +543 -0
  90. package/test-support/setup.ts +8 -6
  91. package/test-support/testApp.ts +36 -7
  92. package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
  93. package/desktop/cmp/tab/impl/TabContextMenuItems.ts +0 -23
@@ -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
+ }
@@ -46,7 +46,8 @@ export const [BooleanEditor, booleanEditor] = hoistCmp.withFactory<BooleanEditor
46
46
 
47
47
  return quickToggle
48
48
  ? useInstantEditor(props.agParams, ref)
49
- : useInlineEditorModel(checkbox, props, ref);
49
+ : // A checkbox's value is a boolean, so ignore the key that started the edit.
50
+ useInlineEditorModel(checkbox, props, ref, () => {});
50
51
  }
51
52
  });
52
53
 
@@ -46,6 +46,9 @@ export const [DateEditor, dateEditor] = hoistCmp.withFactory<DateEditorProps>({
46
46
  ...inputProps
47
47
  }
48
48
  };
49
- return useInlineEditorModel(dateInput, props, ref);
49
+ // A date input's value holds a date, so enter the key that started the edit as its text.
50
+ return useInlineEditorModel(dateInput, props, ref, (input, key) =>
51
+ (input as any).textInputRef.current?.noteValueChange(key)
52
+ );
50
53
  }
51
54
  });
@@ -49,6 +49,9 @@ export const [SelectEditor, selectEditor] = hoistCmp.withFactory<SelectEditorPro
49
49
  }
50
50
  };
51
51
 
52
- return useInlineEditorModel(select, props, ref);
52
+ // A select's value holds an option, so enter the key that started the edit as search text.
53
+ return useInlineEditorModel(select, props, ref, (input, key) =>
54
+ (input as any).enterSearchText(key)
55
+ );
53
56
  }
54
57
  });
@@ -25,14 +25,17 @@ import {ForwardedRef, ReactElement, useCallback} from 'react';
25
25
  * @param component - ElementFactory for HoistInput to render.
26
26
  * @param props - props passed to containing component
27
27
  * @param ref - forwardRef passed to containing component
28
+ * @param applyInitialKey - applies a printable key that started the edit to the focused input.
29
+ * Defaults to entering the key as the input's value.
28
30
  */
29
31
  export function useInlineEditorModel(
30
32
  component: ElementFactory,
31
33
  props: EditorProps<any>,
32
- ref: ForwardedRef<any>
34
+ ref: ForwardedRef<any>,
35
+ applyInitialKey: InitialKeyFn = (input, key) => input.noteValueChange(key)
33
36
  ): ReactElement {
34
37
  const {className, inputProps, agParams, gridModel} = props,
35
- impl = useLocalModel(() => new InlineEditorModel(agParams, gridModel));
38
+ impl = useLocalModel(() => new InlineEditorModel(agParams, gridModel, applyInitialKey));
36
39
 
37
40
  useGridCellEditor({
38
41
  // This is called in full-row editing when the user tabs into the cell
@@ -62,6 +65,9 @@ export function useInlineEditorModel(
62
65
  });
63
66
  }
64
67
 
68
+ /** Applies the printable key that started an edit to the editor's focused input. */
69
+ export type InitialKeyFn = (input: HoistInputModel, key: string) => void;
70
+
65
71
  /**
66
72
  * Local Model supporting inline cell editor components. Provides base functionality required by
67
73
  * ag-grid plus extension points for editors needing more complex behaviors.
@@ -76,15 +82,21 @@ class InlineEditorModel extends HoistModel {
76
82
  ref = createObservableRef<HoistInputModel>();
77
83
 
78
84
  agParams: CustomCellEditorProps;
85
+ applyInitialKey: InitialKeyFn;
79
86
 
80
87
  get inputEl() {
81
88
  return this.ref.current?.inputEl;
82
89
  }
83
90
 
84
- constructor(agParams: CustomCellEditorProps, gridModel: GridModel) {
91
+ constructor(
92
+ agParams: CustomCellEditorProps,
93
+ gridModel: GridModel,
94
+ applyInitialKey: InitialKeyFn
95
+ ) {
85
96
  super();
86
97
 
87
98
  this.agParams = agParams;
99
+ this.applyInitialKey = applyInitialKey;
88
100
  this.value = agParams.value;
89
101
 
90
102
  // Focus into the input once the component is rendered. With full row editing, multiple
@@ -104,9 +116,9 @@ class InlineEditorModel extends HoistModel {
104
116
  inputEl.focus();
105
117
 
106
118
  const {eventKey} = this.agParams;
107
- // Enter initial keystroke in value (if single char and not special key e.g (F2 or Enter).
119
+ // Apply initial keystroke (if single char and not special key e.g (F2 or Enter).
108
120
  if (eventKey?.length === 1) {
109
- ref.current.noteValueChange(eventKey);
121
+ this.applyInitialKey(ref.current, eventKey);
110
122
  } else {
111
123
  inputEl.select();
112
124
  }
@@ -11,15 +11,21 @@ import {
11
11
  PasswordManagerSupportProps,
12
12
  useHoistInputModel
13
13
  } from '@xh/hoist/cmp/input';
14
+ import {
15
+ addCommasWhileEditing,
16
+ getCaretSkippingCommas,
17
+ setCaretSkippingCommas,
18
+ skipCommaOnDelete
19
+ } from '@xh/hoist/cmp/input/impl/LiveCommas';
14
20
  import {hoistCmp, HoistProps, LayoutProps, StyleProps} from '@xh/hoist/core';
15
21
  import '@xh/hoist/desktop/register';
16
22
  import {fmtNumber, NumericPrecision, parseNumber, Precision, ZeroPad} from '@xh/hoist/format';
17
23
  import {numericInput} from '@xh/hoist/kit/blueprint';
18
24
  import {wait} from '@xh/hoist/promise';
19
25
  import {TEST_ID, throwIf, withDefault} from '@xh/hoist/utils/js';
20
- import {useComposedRefs, getLayoutProps} from '@xh/hoist/utils/react';
26
+ import {getLayoutProps, useComposedRefs, useOnMount} from '@xh/hoist/utils/react';
21
27
  import type {Property} from 'csstype';
22
- import {debounce, isNaN, isNil, isNumber, round} from 'lodash';
28
+ import {clamp, debounce, isNaN, isNil, isNumber, round} from 'lodash';
23
29
  import {KeyboardEventHandler, ReactElement, ReactNode, Ref, useLayoutEffect} from 'react';
24
30
 
25
31
  export interface NumberInputProps
@@ -32,8 +38,11 @@ export interface NumberInputProps
32
38
  /** True to commit on every change/keystroke, default false. */
33
39
  commitOnChange?: boolean;
34
40
 
35
- /** True to insert commas in displayed value. */
36
- displayWithCommas?: boolean;
41
+ /**
42
+ * Insert commas in displayed value - 'whenBlurred' (or true) to show them only when the input
43
+ * does not have focus, 'always' to also show them while the user types.
44
+ */
45
+ displayWithCommas?: boolean | 'always' | 'whenBlurred';
37
46
 
38
47
  /** True to convert entries suffixed with k/m/b to thousands/millions/billions. */
39
48
  enableShorthandUnits?: boolean;
@@ -147,7 +156,16 @@ class NumberInputModel extends HoistInputModel {
147
156
  return withDefault(this.componentProps.scaleFactor, 1);
148
157
  }
149
158
 
159
+ get commasWhileEditing(): boolean {
160
+ return this.componentProps.displayWithCommas === 'always';
161
+ }
162
+
163
+ // Caret position to restore after a reformat while editing, as a count of non-comma chars.
164
+ caretPos: number = null;
165
+
150
166
  onValueChange = (val, valAsString) => {
167
+ if (this.commasWhileEditing)
168
+ this.caretPos = getCaretSkippingCommas(this.inputEl as HTMLInputElement);
151
169
  this.noteValueChange(valAsString);
152
170
  };
153
171
 
@@ -187,7 +205,7 @@ class NumberInputModel extends HoistInputModel {
187
205
  if (isNaN(val)) return false;
188
206
  if (val === null) return true;
189
207
 
190
- // Enforce min/max here on commit. BP props only limit the incremental step change
208
+ // Hoist owns min/max, checking the parsed value - see clampSteppedValue().
191
209
  if (!isNil(min) && val < min) return false;
192
210
  if (!isNil(max) && val > max) return false;
193
211
 
@@ -196,9 +214,24 @@ class NumberInputModel extends HoistInputModel {
196
214
 
197
215
  onKeyDown: KeyboardEventHandler<HTMLInputElement> = ev => {
198
216
  if (ev.key === 'Enter') this.doCommit();
217
+ if (ev.key === 'ArrowUp' || ev.key === 'ArrowDown') this.clampSteppedValue();
199
218
  this.componentProps.onKeyDown?.(ev);
200
219
  };
201
220
 
221
+ onBeforeInput = (ev: InputEvent) => {
222
+ if (this.commasWhileEditing) skipCommaOnDelete(ev);
223
+ };
224
+
225
+ // BP steps the value on arrow keys without applying min/max - clamp the stepped value.
226
+ private clampSteppedValue() {
227
+ const {min, max} = this.componentProps,
228
+ val = this.toExternal(this.internalValue);
229
+ if (!isNumber(val) || isNaN(val)) return;
230
+
231
+ const clamped = clamp(val, min ?? -Infinity, max ?? Infinity);
232
+ if (clamped !== val) this.noteValueChange(this.toInternal(clamped));
233
+ }
234
+
202
235
  formatRenderValue(value: number) {
203
236
  const {componentProps, precision} = this;
204
237
 
@@ -206,7 +239,9 @@ class NumberInputModel extends HoistInputModel {
206
239
 
207
240
  if (this.hasFocus) {
208
241
  const ret = isNumber(value) && !isNil(precision) ? round(value, precision) : value;
209
- return ret?.toString();
242
+ return this.commasWhileEditing
243
+ ? addCommasWhileEditing(ret.toString())
244
+ : ret?.toString();
210
245
  }
211
246
 
212
247
  const {valueLabel, displayWithCommas} = componentProps,
@@ -240,13 +275,17 @@ const cmp = hoistCmp.factory<NumberInputModel>(({model, className, ...props}, re
240
275
  const {width, flex, ...layoutProps} = getLayoutProps(props),
241
276
  renderValue = model.formatRenderValue(model.renderValue);
242
277
 
243
- // BP workaround -- min, max, and stepsize can block Blueprint from rendering
244
- // intended value in underlying control -- ensure it is always shown.
278
+ // Restore the caret after a reformat while editing moved it.
245
279
  useLayoutEffect(() => {
246
- const input = model.inputEl;
247
- if (input) input.value = renderValue;
280
+ const input = model.inputEl as HTMLInputElement;
281
+ if (!input || model.caretPos == null) return;
282
+ setCaretSkippingCommas(input, model.caretPos);
283
+ model.caretPos = null;
248
284
  });
249
285
 
286
+ // Native listener, as React's onBeforeInput does not fire for deletes.
287
+ useOnMount(() => model.inputEl?.addEventListener('beforeinput', model.onBeforeInput));
288
+
250
289
  // BP bases expected precision off of dps in minorStepSize, if specified.
251
290
  // The default BP value of 0.1 for this prop emits a console warning any time the input
252
291
  // value extends beyond 1 dp. Re-default here to sync with our `precision` prop.
@@ -265,8 +304,8 @@ const cmp = hoistCmp.factory<NumberInputModel>(({model, className, ...props}, re
265
304
  disabled: props.disabled,
266
305
  inputRef: useComposedRefs(model.inputRef as Ref<HTMLInputElement>, props.inputRef),
267
306
  leftIcon: props.leftIcon,
268
- min: props.min,
269
- max: props.max,
307
+ // Lets BP parse a comma-formatted value when stepping with the arrow keys.
308
+ locale: model.commasWhileEditing ? 'en-US' : undefined,
270
309
  minorStepSize,
271
310
  majorStepSize,
272
311
  placeholder: props.placeholder,
@@ -414,18 +414,36 @@ class SelectInputModel extends HoistInputModel {
414
414
  super.noteFocused();
415
415
  }
416
416
 
417
- private selectText() {
418
- const {reactSelect} = this;
419
- if (!reactSelect) return;
417
+ /**
418
+ * Enter text into the search input and open the menu, as if typed by the user.
419
+ * Ignored if the select is not searchable.
420
+ */
421
+ enterSearchText(text: string) {
422
+ // Delay to run after the text selection scheduled by `noteFocused()`.
423
+ wait().then(() => {
424
+ const selectComp = this.innerSelect;
425
+ if (!this.hasFocus || !selectComp?.props.isSearchable) return;
426
+
427
+ selectComp.props.onInputChange(text, {
428
+ action: 'input-change',
429
+ prevInputValue: selectComp.props.inputValue ?? ''
430
+ });
431
+ selectComp.openMenu('first');
432
+ });
433
+ }
420
434
 
421
- // Unwrap the HOCs added by AsyncSelect / Creatable / WindowedSelect (each exposes the
422
- // inner Select via `.select`) to reach the underlying Select that owns the inputRef.
423
- let selectComp = reactSelect;
435
+ // Unwrap the HOCs added by AsyncSelect / Creatable / WindowedSelect (each exposes the inner
436
+ // Select via `.select`) to reach the underlying Select that owns the inputRef.
437
+ private get innerSelect() {
438
+ let selectComp = this.reactSelect;
424
439
  while (selectComp && !selectComp.inputRef) {
425
440
  selectComp = selectComp.select;
426
441
  }
427
- const inputElem = selectComp?.inputRef;
442
+ return selectComp;
443
+ }
428
444
 
445
+ private selectText() {
446
+ const inputElem = this.innerSelect?.inputRef;
429
447
  if (this.hasFocus && inputElem && document.activeElement === inputElem) {
430
448
  inputElem.select();
431
449
  }
@@ -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
 
package/docs/README.md CHANGED
@@ -64,6 +64,7 @@ See [`docs-roadmap.md`](./planning/docs-roadmap.md) for documentation coverage t
64
64
  | Configure local development environment | [Development Environment](./development-environment.md) |
65
65
  | Write or run unit tests, in an app or hoist-react | [Unit Testing](./unit-testing.md) |
66
66
  | Use MCP tools with AI assistants | [`/mcp/`](../mcp/README.md) |
67
+ | Serve a Hoist library's docs through the MCP tools | [Companion Library Docs](./companion-library-docs.md) |
67
68
  | Customize colors, fonts, spacing, or theme | [`/styles/`](../styles/README.md) |
68
69
  | Follow XH coding conventions | [Coding Conventions](./coding-conventions.md) |
69
70
  | Check hoist-react / hoist-core / hoist-dev-utils version compatibility | [Version Compatibility](./version-compatibility.md) |
@@ -158,6 +159,7 @@ for planned coverage:
158
159
  | Tool | Description |
159
160
  |------|-------------|
160
161
  | [MCP Server](../mcp/README.md) | Model Context Protocol server providing AI assistants with structured access to documentation, TypeScript types, and code generation prompts |
162
+ | [Companion Library Docs](./companion-library-docs.md) | How a library that builds on Hoist serves its docs through the MCP server and `hoist-docs` CLI, using a `hoist.docRegistry` field in its `package.json` |
161
163
 
162
164
  ## Upgrade Notes
163
165