@xh/hoist 72.0.0 → 72.1.0

package/CHANGELOG.md

@@ -1,8 +1,28 @@
 # Changelog
 
+## v72.1.0 - 2025-02-13
+
+### 🎁 New Features
+
+* Introduced a new "JSON Search" feature to the Hoist Admin Console, accessible from the Config,
+  User Preference, and JSON Blob tabs. Supports searching JSON values stored within these objects
+  to filter and match data using JSON Path expressions.
+    * ⚠️Requires `hoist-core >= 28.1` with new APIs for this (optional) feature to function.
+* Added new getters `StoreRecord.isDirty`, `Store.dirtyRecords`, and `Store.isDirty` to provide a
+  more consistent API in the data package. The pre-existing `isModified` getters are retained as
+  aliases, with the same semantics.
+
+### 🐞 Bug Fixes
+
+* Tuned mobile swipe handling to prevent horizontal swipes on a scrolling grid view from triggering
+  the Navigator's back gesture.
+* Prevented the Admin Console Roles grid from losing its expand/collapse/scroll state on refresh.
+* Fixed bug when merging `PersistOptions` with conflicting implicit provider types.
+* Fixed bug where explicit `persistGrouping` options were not being respected by `GridModel`.
+
 ## v72.0.0 - 2025-01-27
 
-### 💥 Breaking Changes
+### 💥 Breaking Changes (upgrade difficulty: 🟢 TRIVIAL - minor changes to mobile nav)
 
 * Mobile `Navigator` no longer supports `animation` prop, and `NavigatorModel` no longer supports
   `swipeToGoBack`. Both of these properties are now managed internally by the `Navigator` component.
@@ -15,7 +35,8 @@
 ### 🐞 Bug Fixes
 
 * Fixed `ViewManagerModel` unique name validation.
-* Fixed `GridModel.restoreDefaultsAsync()` to restore any default filter, rather than simply clearing it.
+* Fixed `GridModel.restoreDefaultsAsync()` to restore any default filter, rather than simply
+  clearing it.
 * Improved suboptimal column state synchronization between `GridModel` and AG Grid.
 
 ### ⚙️ Technical

package/admin/jsonsearch/JsonSearch.ts

@@ -0,0 +1,294 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+
+import {errorMessage} from '@xh/hoist/cmp/error';
+import {grid, GridConfig, gridCountLabel} from '@xh/hoist/cmp/grid';
+import {a, box, filler, fragment, hframe, label, li, p, span, ul, vbox} from '@xh/hoist/cmp/layout';
+import {hoistCmp, HoistProps, SelectOption, useLocalModel} from '@xh/hoist/core';
+import {button} from '@xh/hoist/desktop/cmp/button';
+import {clipboardButton} from '@xh/hoist/desktop/cmp/clipboard';
+import {buttonGroupInput, jsonInput, select, textInput} from '@xh/hoist/desktop/cmp/input';
+import {panel} from '@xh/hoist/desktop/cmp/panel';
+import {toolbar, toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
+import {Icon} from '@xh/hoist/icon';
+import {dialog, popover} from '@xh/hoist/kit/blueprint';
+import {pluralize} from '@xh/hoist/utils/js';
+import {startCase} from 'lodash';
+import {JsonSearchImplModel} from './impl/JsonSearchImplModel';
+
+export interface JsonSearchButtonProps extends HoistProps {
+    /** Descriptive label for the type of records being searched - will be auto-pluralized. */
+    subjectName: string;
+
+    /** Endpoint to search and return matches - Hoist `JsonSearchController` action expected. */
+    docSearchUrl: string;
+
+    /** Config for GridModel used to display search results. */
+    gridModelConfig: GridConfig;
+
+    /** Field names on returned results to enable for grouping in the search results grid. */
+    groupByOptions: Array<SelectOption | any>;
+}
+
+/**
+ * Main entry point component for the JSON search feature. Supported out-of-the-box for a limited
+ * set of Hoist artifacts that hold JSON values: JSONBlob, Configs, and User Preferences.
+ */
+export const jsonSearchButton = hoistCmp.factory<JsonSearchButtonProps>({
+    displayName: 'JsonSearchButton',
+
+    render() {
+        const impl = useLocalModel(JsonSearchImplModel);
+
+        return fragment(
+            button({
+                icon: Icon.json(),
+                text: 'JSON Search',
+                onClick: () => impl.toggleSearchIsOpen()
+            }),
+            jsonSearchDialog({
+                omit: !impl.isOpen,
+                model: impl
+            })
+        );
+    }
+});
+
+const jsonSearchDialog = hoistCmp.factory<JsonSearchImplModel>({
+    displayName: 'JsonSearchDialog',
+
+    render({model}) {
+        const {error, subjectName} = model;
+
+        return dialog({
+            title: `JSON Search: ${subjectName}`,
+            style: {
+                width: '90vw',
+                height: '90vh'
+            },
+            icon: Icon.json(),
+            isOpen: true,
+            className: 'xh-admin-diff-detail',
+            onClose: () => model.toggleSearchIsOpen(),
+            item: panel({
+                tbar: searchTbar(),
+                item: panel({
+                    mask: model.docLoadTask,
+                    items: [
+                        errorMessage({
+                            error,
+                            title: error?.name ? startCase(error.name) : undefined
+                        }),
+                        hframe({
+                            omit: error,
+                            items: [
+                                panel({
+                                    item: grid({model: model.gridModel}),
+                                    modelConfig: {
+                                        side: 'left',
+                                        defaultSize: '30%',
+                                        collapsible: true,
+                                        defaultCollapsed: false,
+                                        resizable: true
+                                    }
+                                }),
+                                panel({
+                                    mask: model.nodeLoadTask,
+                                    tbar: readerTbar(),
+                                    item: jsonInput({
+                                        model,
+                                        bind: 'readerContent',
+                                        flex: 1,
+                                        width: '100%',
+                                        readonly: true,
+                                        showCopyButton: true
+                                    })
+                                })
+                            ]
+                        })
+                    ]
+                })
+            })
+        });
+    }
+});
+
+const searchTbar = hoistCmp.factory<JsonSearchImplModel>({
+    render({model}) {
+        return toolbar(
+            pathField({model}),
+            button({
+                text: `Search ${model.subjectName}`,
+                intent: 'success',
+                outlined: true,
+                disabled: !model.path,
+                onClick: () => model.loadMatchingDocsAsync()
+            }),
+            '-',
+            helpButton({model}),
+            '-',
+            span('Group by:'),
+            select({
+                bind: 'groupBy',
+                options: model.groupByOptions,
+                width: 160,
+                enableFilter: false
+            }),
+            '-',
+            gridCountLabel({
+                gridModel: model.gridModel,
+                unit: 'match'
+            })
+        );
+    }
+});
+
+const pathField = hoistCmp.factory<JsonSearchImplModel>({
+    render({model}) {
+        return textInput({
+            bind: 'path',
+            autoFocus: true,
+            commitOnChange: true,
+            leftIcon: Icon.search(),
+            enableClear: true,
+            placeholder: 'Provide a JSON Path expression to evaluate',
+            width: null,
+            flex: 1,
+            onKeyDown: e => {
+                if (e.key === 'Enter') model.loadMatchingDocsAsync();
+            }
+        });
+    }
+});
+
+const helpButton = hoistCmp.factory<JsonSearchImplModel>({
+    render({model}) {
+        return popover({
+            item: button({
+                icon: Icon.questionCircle(),
+                outlined: true
+            }),
+            content: vbox({
+                className: 'xh-pad',
+                items: [
+                    p(
+                        `JSON Path expressions allow you to recursively query JSON documents, matching nodes based on their path, properties, and values.`
+                    ),
+                    p(
+                        `Enter a path and press [Enter] to search for matches within the JSON content of ${model.subjectName}.`
+                    ),
+                    ul({
+                        items: queryExamples.map(({query, explanation}) =>
+                            li({
+                                key: query,
+                                items: [
+                                    span({
+                                        className:
+                                            'xh-border xh-pad-half xh-bg-alt xh-font-family-mono',
+                                        item: query
+                                    }),
+                                    ' ',
+                                    clipboardButton({
+                                        text: null,
+                                        icon: Icon.copy(),
+                                        getCopyText: () => query,
+                                        successMessage: 'Query copied to clipboard.'
+                                    }),
+                                    ' ',
+                                    explanation
+                                ]
+                            })
+                        ),
+                        style: {marginTop: 0}
+                    }),
+                    a({
+                        href: 'https://github.com/json-path/JsonPath?tab=readme-ov-file#operators',
+                        target: '_blank',
+                        item: 'Path Syntax Docs & More Examples'
+                    })
+                ]
+            })
+        });
+    }
+});
+
+const readerTbar = hoistCmp.factory<JsonSearchImplModel>(({model}) => {
+    return toolbar({
+        items: [
+            buttonGroupInput({
+                model,
+                bind: 'readerContentType',
+                minimal: true,
+                outlined: true,
+                disabled: !model.selectedRecord,
+                items: [
+                    button({
+                        text: 'Document',
+                        value: 'document'
+                    }),
+                    button({
+                        text: 'Matches',
+                        value: 'matches'
+                    })
+                ]
+            }),
+            fragment({
+                omit: model.readerContentType !== 'matches' || !model.selectedRecord,
+                items: [
+                    toolbarSep(),
+                    label('View path as'),
+                    buttonGroupInput({
+                        model,
+                        bind: 'pathFormat',
+                        minimal: true,
+                        outlined: true,
+                        items: [
+                            button({
+                                text: 'XPath',
+                                value: 'XPath'
+                            }),
+                            button({
+                                text: 'JSONPath',
+                                value: 'JSONPath'
+                            })
+                        ]
+                    })
+                ]
+            }),
+            filler(),
+            box({
+                omit: !model.matchingNodeCount,
+                item: `${pluralize('match', model.matchingNodeCount, true)} within this document`
+            })
+        ]
+    });
+});
+
+const queryExamples = [
+    {
+        query: '$.displayMode',
+        explanation: 'Return documents with a top-level property "displayMode"'
+    },
+    {
+        query: "$..[?(@.colId == 'trader')]",
+        explanation:
+            'Find all nodes (anywhere in the document) with a property "colId" equal to "trader"'
+    },
+    {
+        query: '$..[?(@.colId && @.width)]',
+        explanation: 'Find all nodes with a property "colId" and a property "width"'
+    },
+    {
+        query: '$..[?(@.colId && @.hidden != true)]',
+        explanation:
+            'Find all nodes with a property "colId" and a property "hidden" not equal to true'
+    },
+    {
+        query: '$..grid[?(@.version == 1)]',
+        explanation: 'Find all nodes with a key of "grid" and a property "version" equal to 1'
+    }
+];

package/admin/jsonsearch/impl/JsonSearchImplModel.ts

@@ -0,0 +1,175 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+
+import {GridConfig, GridModel} from '@xh/hoist/cmp/grid';
+import {HoistModel, managed, TaskObserver, XH} from '@xh/hoist/core';
+import {action, bindable, makeObservable, observable} from '@xh/hoist/mobx';
+import {pluralize} from '@xh/hoist/utils/js';
+import {camelCase, isEmpty, zipWith} from 'lodash';
+
+/**
+ * @internal
+ */
+export class JsonSearchImplModel extends HoistModel {
+    override xhImpl = true;
+
+    private matchingNodesUrl = 'jsonSearch/getMatchingNodes';
+
+    @managed gridModel: GridModel;
+    @managed docLoadTask: TaskObserver = TaskObserver.trackLast();
+    @managed nodeLoadTask: TaskObserver = TaskObserver.trackLast();
+
+    @observable groupBy: string = null;
+    @observable isOpen: boolean = false;
+
+    @bindable.ref error = null;
+    @bindable path: string = '';
+    @bindable readerContentType: 'document' | 'matches' = 'matches';
+    @bindable pathFormat: 'XPath' | 'JSONPath' = 'XPath';
+    @bindable readerContent: string = '';
+    @bindable matchingNodeCount: number = 0;
+
+    get subjectName(): string {
+        return pluralize(this.componentProps.subjectName);
+    }
+
+    get docSearchUrl(): string {
+        return this.componentProps.docSearchUrl;
+    }
+
+    get gridModelConfig(): GridConfig {
+        return this.componentProps.gridModelConfig;
+    }
+
+    get selectedRecord() {
+        return this.gridModel.selectedRecord;
+    }
+
+    get groupByOptions() {
+        const cols = this.gridModel.getLeafColumns();
+        return [
+            ...this.componentProps.groupByOptions.map(it => ({
+                value: it,
+                label: cols.find(col => col.colId === it)?.displayName ?? it
+            })),
+            {value: null, label: 'None'}
+        ];
+    }
+
+    @action
+    toggleSearchIsOpen() {
+        this.isOpen = !this.isOpen;
+    }
+
+    constructor() {
+        super();
+        makeObservable(this);
+    }
+
+    override onLinked() {
+        this.gridModel = new GridModel({
+            ...this.gridModelConfig,
+            emptyText: 'No matches found...',
+            selModel: 'single'
+        });
+
+        this.markPersist('path', {localStorageKey: `xhJsonSearch${camelCase(this.subjectName)}`});
+
+        this.addReaction(
+            {
+                track: () => this.path,
+                run: path => {
+                    if (isEmpty(path)) {
+                        this.error = null;
+                        this.gridModel.clear();
+                    }
+                }
+            },
+            {
+                track: () => [this.selectedRecord, this.readerContentType, this.pathFormat],
+                run: () => this.loadReaderContentAsync(),
+                debounce: 300
+            }
+        );
+
+        // We might have a persisted path - go ahead and load if so.
+        this.loadMatchingDocsAsync();
+    }
+
+    async loadMatchingDocsAsync() {
+        const {path, gridModel, docLoadTask} = this;
+
+        if (isEmpty(path)) {
+            this.error = null;
+            gridModel.clear();
+            return;
+        }
+
+        try {
+            const data = await XH.fetchJson({
+                url: this.docSearchUrl,
+                params: {path}
+            }).linkTo(docLoadTask);
+
+            this.error = null;
+            gridModel.loadData(data);
+            gridModel.preSelectFirstAsync();
+        } catch (e) {
+            gridModel.clear();
+            this.error = e;
+        }
+    }
+
+    private async loadReaderContentAsync() {
+        if (!this.selectedRecord) {
+            this.matchingNodeCount = 0;
+            this.readerContent = '';
+            return;
+        }
+
+        const {json} = this.selectedRecord.data;
+
+        if (this.readerContentType === 'document') {
+            this.readerContent = JSON.stringify(JSON.parse(json), null, 2);
+            return;
+        }
+
+        let nodes = await XH.fetchJson({
+            url: this.matchingNodesUrl,
+            params: {
+                path: this.path,
+                json
+            }
+        }).linkTo(this.nodeLoadTask);
+
+        this.matchingNodeCount = nodes.paths.length;
+        nodes = zipWith(nodes.paths, nodes.values, (path: string, value) => {
+            return {
+                path: this.pathFormat === 'XPath' ? this.convertToXPath(path) : path,
+                value
+            };
+        });
+        this.readerContent = JSON.stringify(nodes, null, 2);
+    }
+
+    private convertToXPath(JSONPath: string): string {
+        return JSONPath.replaceAll(/^\$\['?/g, '/')
+            .replaceAll(/^\$/g, '')
+            .replaceAll(/'?]\['?/g, '/')
+            .replaceAll(/'?]$/g, '');
+    }
+
+    @action
+    private setGroupBy(groupBy: string) {
+        this.groupBy = groupBy;
+
+        // Always select first when regrouping.
+        const groupByArr = groupBy ? groupBy.split(',') : [];
+        this.gridModel.setGroupBy(groupByArr);
+        this.gridModel.preSelectFirstAsync();
+    }
+}

package/admin/tabs/general/config/ConfigPanel.ts

@@ -4,10 +4,14 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
+import * as AdminCol from '@xh/hoist/admin/columns';
+import * as Col from '@xh/hoist/admin/columns/Rest';
+import {jsonSearchButton} from '@xh/hoist/admin/jsonsearch/JsonSearch';
 import {fragment} from '@xh/hoist/cmp/layout';
 import {creates, hoistCmp} from '@xh/hoist/core';
 import {button} from '@xh/hoist/desktop/cmp/button';
 import {restGrid} from '@xh/hoist/desktop/cmp/rest';
+import {toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
 import {Icon} from '@xh/hoist/icon';
 import {differ} from '../../../differ/Differ';
 import {regroupDialog} from '../../../regroup/RegroupDialog';
@@ -20,13 +24,31 @@ export const configPanel = hoistCmp.factory({
         return fragment(
             restGrid({
                 testId: 'config',
-                extraToolbarItems: () => {
-                    return button({
+                extraToolbarItems: () => [
+                    button({
                         icon: Icon.diff(),
                         text: 'Compare w/ Remote',
                         onClick: () => model.openDiffer()
-                    });
-                }
+                    }),
+                    toolbarSep(),
+                    jsonSearchButton({
+                        subjectName: 'Config',
+                        docSearchUrl: 'jsonSearch/searchConfigs',
+                        gridModelConfig: {
+                            sortBy: ['groupName', 'name'],
+                            columns: [
+                                {...AdminCol.groupName},
+                                {...AdminCol.name},
+                                {
+                                    field: {name: 'json', type: 'string'},
+                                    hidden: true
+                                },
+                                {...Col.lastUpdated}
+                            ]
+                        },
+                        groupByOptions: ['groupName']
+                    })
+                ]
             }),
             differ({omit: !model.differModel}),
             regroupDialog()

package/admin/tabs/userData/jsonblob/JsonBlobPanel.ts

@@ -5,10 +5,15 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {fragment} from '@xh/hoist/cmp/layout';
+import * as Col from '@xh/hoist/admin/columns/Rest';
+import * as AdminCol from '@xh/hoist/admin/columns';
+import {hframe} from '@xh/hoist/cmp/layout';
 import {creates, hoistCmp} from '@xh/hoist/core';
 import {button} from '@xh/hoist/desktop/cmp/button';
+import {jsonSearchButton} from '@xh/hoist/admin/jsonsearch/JsonSearch';
+import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {restGrid} from '@xh/hoist/desktop/cmp/rest';
+import {toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
 import {Icon} from '@xh/hoist/icon';
 import {differ} from '../../../differ/Differ';
 import {JsonBlobModel} from './JsonBlobModel';
@@ -17,15 +22,47 @@ export const jsonBlobPanel = hoistCmp.factory({
     model: creates(JsonBlobModel),
 
     render({model}) {
-        return fragment(
-            restGrid({
-                extraToolbarItems: () => {
-                    return button({
-                        icon: Icon.diff(),
-                        text: 'Compare w/ Remote',
-                        onClick: () => model.openDiffer()
-                    });
-                }
+        return hframe(
+            panel({
+                item: restGrid({
+                    extraToolbarItems: () => [
+                        button({
+                            icon: Icon.diff(),
+                            text: 'Compare w/ Remote',
+                            onClick: () => model.openDiffer()
+                        }),
+                        toolbarSep(),
+                        jsonSearchButton({
+                            subjectName: 'JSON Blob',
+                            docSearchUrl: 'jsonSearch/searchBlobs',
+                            gridModelConfig: {
+                                sortBy: ['type', 'name', 'owner'],
+                                columns: [
+                                    {
+                                        field: {name: 'token', type: 'string'},
+                                        hidden: true,
+                                        width: 100
+                                    },
+                                    {
+                                        field: {name: 'type', type: 'string'},
+                                        width: 200
+                                    },
+                                    {
+                                        field: {name: 'owner', type: 'string'},
+                                        width: 200
+                                    },
+                                    {...AdminCol.name},
+                                    {
+                                        field: {name: 'json', type: 'string'},
+                                        hidden: true
+                                    },
+                                    {...Col.lastUpdated}
+                                ]
+                            },
+                            groupByOptions: ['owner', 'type', 'name']
+                        })
+                    ]
+                })
             }),
             differ({omit: !model.differModel})
         );