@xh/hoist 80.0.0-SNAPSHOT.1767982629403 → 80.0.0-SNAPSHOT.1768251023007

package/CHANGELOG.md

@@ -11,9 +11,15 @@
       so there is no deprecated alias. Any app usages should swap to `XH.appLoadObserver`.
     * Removed additional references to deprecated `loadModel` within Hoist itself.
 * Removed the following instance getters - use new static typeguards instead:
-  * `Store.isStore`
-  * `View.isView`
-  * `Filter.isFilter`
+    * `Store.isStore`
+    * `View.isView`
+    * `Filter.isFilter`
+
+### 🎁 New Features
+
+* Added new `AppMenuButton.renderWithUserProfile` prop as a built-in alternative to the default
+  hamburger menu. Set to `true` to render the current user's initials instead or provide a function
+  to render a custom element for the user.
 
 ### ⚙️ Typescript API Adjustments
 

package/build/types/cmp/tab/TabContainerModel.d.ts

@@ -1,5 +1,5 @@
-import { TabSwitcherConfig, IDynamicTabSwitcherModel } from '@xh/hoist/cmp/tab/Types';
-import { HoistModel, PersistOptions, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
+import type { TabSwitcherConfig, IDynamicTabSwitcherModel, TabContainerModelPersistOptions } from '@xh/hoist/cmp/tab/Types';
+import { HoistModel, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
 import { ReactNode } from 'react';
 import { TabConfig, TabModel } from './TabModel';
 export interface TabContainerConfig {
@@ -12,7 +12,7 @@ export interface TabContainerConfig {
     defaultTabId?: string;
     /**
      * Base route name for this container. If set, this container will be route-enabled, with the
-     * route for each tab being "[route]/[tab.id]".  Cannot be used with `persistWith`.
+     * route for each tab being "[route]/[tab.id]".
      */
     route?: string;
     /**
@@ -35,8 +35,13 @@ export interface TabContainerConfig {
      * See enum for description of supported modes.
      */
     refreshMode?: RefreshMode;
-    /** Options governing persistence. Cannot be used with `route`. */
-    persistWith?: PersistOptions;
+    /**
+     * Options governing persistence. Tab containers can persist their last-active tab as well
+     * as favorite tabs for the dynamic `switcher` option. Note that this must be left unset or
+     * its nested `persistActiveTabId` option must be set to false if also using `route`, to avoid
+     * a possible conflict between an initial route and persisted last active tab.
+     */
+    persistWith?: TabContainerModelPersistOptions;
     /**
      * Placeholder to display if no tabs are provided or all tabs have been removed via
      * their `omit` config.

package/build/types/core/XH.d.ts

@@ -1,7 +1,7 @@
 import { RouterModel } from '@xh/hoist/appcontainer/RouterModel';
 import { HoistAuthModel } from '@xh/hoist/core/HoistAuthModel';
 import { Store } from '@xh/hoist/data';
-import { AlertBannerService, AutoRefreshService, ChangelogService, ConfigService, EnvironmentService, FetchOptions, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, SessionStorageService, TrackService, WebSocketService, ClientHealthService } from '@xh/hoist/svc';
+import { AlertBannerService, AutoRefreshService, ChangelogService, ClientHealthService, ConfigService, EnvironmentService, FetchOptions, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, SessionStorageService, TrackService, WebSocketService } from '@xh/hoist/svc';
 import { LogLevel } from '@xh/hoist/utils/js';
 import { Router, State } from 'router5';
 import { CancelFn } from 'router5/types/types/base';
@@ -175,6 +175,8 @@ export declare class XHApi {
      * @see IdentityService.username
      */
     getUsername(): string;
+    /** @returns the current acting user's initials. */
+    getUserInitials(): string;
     /**
      * Logout the current user.
      * @see HoistAuthModel.logoutAsync

package/build/types/desktop/cmp/button/AppMenuButton.d.ts

@@ -1,6 +1,7 @@
-import { MenuItemLike } from '@xh/hoist/core';
+import { HoistUser, MenuItemLike } from '@xh/hoist/core';
 import { ButtonProps } from '@xh/hoist/desktop/cmp/button';
 import '@xh/hoist/desktop/register';
+import { ReactNode } from 'react';
 export interface AppMenuButtonProps extends ButtonProps {
     /**
      * Array of extra menu items. Can contain:
@@ -31,5 +32,13 @@ export interface AppMenuButtonProps extends ButtonProps {
     hideOptionsItem?: boolean;
     /** True to hide the Theme Toggle button. */
     hideThemeItem?: boolean;
+    /**
+     * Replace the default hamburger icon with a user profile representation. Set to true to render
+     * the user's initials from their `HoistUser.displayName`. Alternately, provide a custom
+     * function to render an alternate compact string or element for the current user.
+     */
+    renderWithUserProfile?: boolean | RenderWithUserProfileCustomFn;
 }
+type RenderWithUserProfileCustomFn = (user: HoistUser) => ReactNode;
 export declare const AppMenuButton: import("react").FC<AppMenuButtonProps>, appMenuButton: import("@xh/hoist/core").ElementFactory<AppMenuButtonProps>;
+export {};

package/build/types/mobile/cmp/header/AppMenuButton.d.ts

@@ -1,6 +1,7 @@
-import { MenuItemLike } from '@xh/hoist/core';
+import { HoistUser, MenuItemLike } from '@xh/hoist/core';
 import { MenuButtonProps } from '@xh/hoist/mobile/cmp/menu';
 import '@xh/hoist/mobile/register';
+import { ReactNode } from 'react';
 export interface AppMenuButtonProps extends MenuButtonProps {
     /** Array of app-specific MenuItems or configs to create them. */
     extraItems?: MenuItemLike[];
@@ -21,7 +22,14 @@ export interface AppMenuButtonProps extends MenuButtonProps {
     hideThemeItem?: boolean;
     /** True to hide the About button */
     hideAboutItem?: boolean;
+    /**
+     * Replace the default hamburger icon with a user profile representation. Set to true to render
+     * the user's initials from their `HoistUser.displayName`. Alternately, provide a custom
+     * function to render an alternate compact string or element for the current user.
+     */
+    renderWithUserProfile?: boolean | RenderWithUserProfileCustomFn;
 }
+type RenderWithUserProfileCustomFn = (user: HoistUser) => ReactNode;
 /**
  * A top-level application drop down menu, which installs a standard set of menu items for common
  * application actions. Application specific items can be displayed before these standard items.
@@ -30,3 +38,4 @@ export interface AppMenuButtonProps extends MenuButtonProps {
  * or they can each be explicitly hidden.
  */
 export declare const AppMenuButton: import("react").FC<AppMenuButtonProps>, appMenuButton: import("@xh/hoist/core").ElementFactory<AppMenuButtonProps>;
+export {};

package/build/types/svc/IdentityService.d.ts

@@ -11,10 +11,12 @@ export declare class IdentityService extends HoistService {
     private _authUser;
     private _apparentUser;
     initAsync(): Promise<void>;
-    /** Current acting user (see authUser for notes on impersonation) */
+    /** @returns current acting user (see authUser for notes on impersonation) */
     get user(): HoistUser;
-    /** Current acting user's username. */
+    /** @returns current acting user's username. */
     get username(): string;
+    /** @returns current acting user's initials, based on displayName. */
+    get userInitials(): string;
     /**
      * Actual user who authenticated to the web application.
      * This will be the same as the user except when an administrator is impersonation another

package/cmp/tab/TabContainerModel.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {
+import type {
     TabSwitcherConfig,
     IDynamicTabSwitcherModel,
     TabContainerModelPersistOptions
@@ -14,7 +14,6 @@ import {
     managed,
     PersistableState,
     PersistenceProvider,
-    PersistOptions,
     RefreshContextModel,
     RefreshMode,
     RenderMode,
@@ -41,7 +40,7 @@ export interface TabContainerConfig {
 
     /**
      * Base route name for this container. If set, this container will be route-enabled, with the
-     * route for each tab being "[route]/[tab.id]".  Cannot be used with `persistWith`.
+     * route for each tab being "[route]/[tab.id]".
      */
     route?: string;
 
@@ -69,8 +68,13 @@ export interface TabContainerConfig {
      */
     refreshMode?: RefreshMode;
 
-    /** Options governing persistence. Cannot be used with `route`. */
-    persistWith?: PersistOptions;
+    /**
+     * Options governing persistence. Tab containers can persist their last-active tab as well
+     * as favorite tabs for the dynamic `switcher` option. Note that this must be left unset or
+     * its nested `persistActiveTabId` option must be set to false if also using `route`, to avoid
+     * a possible conflict between an initial route and persisted last active tab.
+     */
+    persistWith?: TabContainerModelPersistOptions;
 
     /**
      * Placeholder to display if no tabs are provided or all tabs have been removed via

package/core/XH.ts

@@ -14,6 +14,7 @@ import {
     AlertBannerService,
     AutoRefreshService,
     ChangelogService,
+    ClientHealthService,
     ConfigService,
     EnvironmentService,
     FetchOptions,
@@ -28,13 +29,13 @@ import {
     PrefService,
     SessionStorageService,
     TrackService,
-    WebSocketService,
-    ClientHealthService
+    WebSocketService
 } from '@xh/hoist/svc';
-import {getLogLevel, setLogLevel, LogLevel, apiDeprecated} from '@xh/hoist/utils/js';
+import {apiDeprecated, getLogLevel, LogLevel, setLogLevel} from '@xh/hoist/utils/js';
 import {camelCase, flatten, isString, uniqueId} from 'lodash';
 import {Router, State} from 'router5';
 import {CancelFn} from 'router5/types/types/base';
+import ShortUniqueId from 'short-unique-id';
 import {SetOptional} from 'type-fest';
 import {AppContainerModel} from '../appcontainer/AppContainerModel';
 import {BannerModel} from '../appcontainer/BannerModel';
@@ -66,7 +67,6 @@ import {
 import {installServicesAsync} from './impl/InstallServices';
 import {instanceManager} from './impl/InstanceManager';
 import {HoistModel, ModelSelector, RefreshContextModel} from './model';
-import ShortUniqueId from 'short-unique-id';
 
 export const MIN_HOIST_CORE_VERSION = '31.2';
 
@@ -360,6 +360,11 @@ export class XHApi {
         return this.identityService?.username ?? null;
     }
 
+    /** @returns the current acting user's initials. */
+    getUserInitials(): string {
+        return this.identityService?.userInitials ?? null;
+    }
+
     /**
      * Logout the current user.
      * @see HoistAuthModel.logoutAsync

package/desktop/cmp/appbar/AppBar.scss

@@ -6,11 +6,6 @@
  */
 
 .xh-appbar {
-  // Menu button might be on left or right of appBar - add right margin when on left only.
-  .xh-app-menu-button:first-child {
-    margin-right: var(--xh-pad-px);
-  }
-
   .xh-appbar-icon {
     margin-right: var(--xh-pad-px);
   }
@@ -20,6 +15,30 @@
     font-size: var(--xh-appbar-title-font-size-px);
     margin-right: var(--xh-pad-px);
   }
+
+  .xh-app-menu-button {
+    // Menu button might be on left or right of appBar - add right margin when on left only.
+    &:first-child {
+      margin-right: var(--xh-pad-px);
+    }
+
+    &__user-profile {
+      border-radius: 50%;
+      border: var(--xh-border-solid);
+      cursor: pointer;
+      height: 32px;
+      line-height: 31px;
+      text-align: center;
+      width: 32px;
+    }
+
+    // Trigger profile-specific hover styles on parent button hover
+    &:hover .xh-app-menu-button__user-profile {
+      color: var(--xh-appbar-user-profile-hover-color);
+      border-color: var(--xh-appbar-user-profile-hover-color);
+      background-color: transparent;
+    }
+  }
 }
 
 //------------------------

package/desktop/cmp/button/AppMenuButton.ts

@@ -4,13 +4,16 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {hoistCmp, MenuItemLike, XH} from '@xh/hoist/core';
+import {div} from '@xh/hoist/cmp/layout';
+import {hoistCmp, HoistProps, HoistUser, MenuItemLike, XH} from '@xh/hoist/core';
 import {ButtonProps, button} from '@xh/hoist/desktop/cmp/button';
 import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
 import {menu, popover} from '@xh/hoist/kit/blueprint';
 import {parseMenuItems} from '@xh/hoist/utils/impl';
 import {withDefault} from '@xh/hoist/utils/js';
+import {isFunction} from 'lodash';
+import {ReactNode} from 'react';
 
 export interface AppMenuButtonProps extends ButtonProps {
     /**
@@ -50,8 +53,17 @@ export interface AppMenuButtonProps extends ButtonProps {
 
     /** True to hide the Theme Toggle button. */
     hideThemeItem?: boolean;
+
+    /**
+     * Replace the default hamburger icon with a user profile representation. Set to true to render
+     * the user's initials from their `HoistUser.displayName`. Alternately, provide a custom
+     * function to render an alternate compact string or element for the current user.
+     */
+    renderWithUserProfile?: boolean | RenderWithUserProfileCustomFn;
 }
 
+type RenderWithUserProfileCustomFn = (user: HoistUser) => ReactNode;
+
 export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButtonProps>({
     displayName: 'AppMenuButton',
     model: false,
@@ -70,6 +82,7 @@ export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButton
             hideOptionsItem,
             hideThemeItem,
             disabled,
+            renderWithUserProfile,
             ...rest
         } = props;
 
@@ -79,7 +92,8 @@ export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButton
             position: 'bottom-right',
             minimal: true,
             item: button({
-                icon: Icon.menu(),
+                icon: renderWithUserProfile ? null : Icon.menu(),
+                text: renderWithUserProfile ? userProfile({renderWithUserProfile}) : null,
                 disabled,
                 ...rest
             }),
@@ -95,6 +109,20 @@ export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButton
 //---------------------------
 // Implementation
 //---------------------------
+const userProfile = hoistCmp.factory<
+    HoistProps & {renderWithUserProfile: true | RenderWithUserProfileCustomFn}
+>({
+    model: false,
+    render({renderWithUserProfile}) {
+        return div({
+            className: 'xh-app-menu-button__user-profile',
+            item: isFunction(renderWithUserProfile)
+                ? renderWithUserProfile(XH.getUser())
+                : XH.getUserInitials()
+        });
+    }
+});
+
 function buildMenuItems(props: AppMenuButtonProps) {
     let {
         hideAboutItem,

package/mobile/cmp/header/AppBar.scss

@@ -18,6 +18,17 @@
     display: flex;
   }
 
+  .xh-app-menu-button__user-profile {
+    border-radius: 50%;
+    border: 1px solid var(--xh-appbar-title-color);
+    cursor: pointer;
+    height: 28px;
+    font-size: var(--xh-font-size-small-em);
+    line-height: 27px;
+    text-align: center;
+    width: 28px;
+  }
+
   .xh-button {
     background: transparent !important;
     color: var(--xh-appbar-title-color) !important;

package/mobile/cmp/header/AppMenuButton.ts

@@ -4,11 +4,14 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {hoistCmp, MenuItemLike, XH} from '@xh/hoist/core';
+import {div} from '@xh/hoist/cmp/layout';
+import {hoistCmp, HoistProps, HoistUser, MenuItemLike, XH} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
 import {menuButton, MenuButtonProps} from '@xh/hoist/mobile/cmp/menu';
 import '@xh/hoist/mobile/register';
 import {withDefault} from '@xh/hoist/utils/js';
+import {isFunction} from 'lodash';
+import {ReactNode} from 'react';
 
 export interface AppMenuButtonProps extends MenuButtonProps {
     /** Array of app-specific MenuItems or configs to create them. */
@@ -37,8 +40,17 @@ export interface AppMenuButtonProps extends MenuButtonProps {
 
     /** True to hide the About button */
     hideAboutItem?: boolean;
+
+    /**
+     * Replace the default hamburger icon with a user profile representation. Set to true to render
+     * the user's initials from their `HoistUser.displayName`. Alternately, provide a custom
+     * function to render an alternate compact string or element for the current user.
+     */
+    renderWithUserProfile?: boolean | RenderWithUserProfileCustomFn;
 }
 
+type RenderWithUserProfileCustomFn = (user: HoistUser) => ReactNode;
+
 /**
  * A top-level application drop down menu, which installs a standard set of menu items for common
  * application actions. Application specific items can be displayed before these standard items.
@@ -62,11 +74,13 @@ export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButton
             hideOptionsItem,
             hideThemeItem,
             hideAboutItem,
+            renderWithUserProfile,
             ...rest
         } = props;
 
         return menuButton({
             className,
+            icon: renderWithUserProfile ? userProfile({renderWithUserProfile}) : Icon.menu(),
             menuItems: buildMenuItems(props),
             menuClassName: 'xh-app-menu',
             popoverProps: {popoverClassName: 'xh-app-menu-popover'},
@@ -78,6 +92,20 @@ export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButton
 //---------------------------
 // Implementation
 //---------------------------
+const userProfile = hoistCmp.factory<
+    HoistProps & {renderWithUserProfile: true | RenderWithUserProfileCustomFn}
+>({
+    model: false,
+    render({renderWithUserProfile}) {
+        return div({
+            className: 'xh-app-menu-button__user-profile',
+            item: isFunction(renderWithUserProfile)
+                ? renderWithUserProfile(XH.getUser())
+                : XH.getUserInitials()
+        });
+    }
+});
+
 function buildMenuItems({
     hideOptionsItem,
     hideFeedbackItem,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "80.0.0-SNAPSHOT.1767982629403",
+  "version": "80.0.0-SNAPSHOT.1768251023007",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/styles/vars.scss

@@ -205,13 +205,14 @@ body {
   //---------
   --xh-appbar-bg: var(--appbar-bg, var(--xh-bg-alt));
   --xh-appbar-border-color: var(--appbar-border-color, transparent);
+  --xh-appbar-box-shadow: var(--appbar-box-shadow, #{0 0 0 1px rgb(17 20 24 / 10%), 0 1px 1px rgb(17 20 24 / 20%)});
   --xh-appbar-color: var(--appbar-color, var(--xh-text-color));
   --xh-appbar-height: var(--appbar-height, 42);
   --xh-appbar-height-px: calc(var(--xh-appbar-height) * 1px);
   --xh-appbar-title-color: var(--appbar-title-color, #{mc('blue-grey', '700')});
   --xh-appbar-title-font-size: var(--appbar-title-font-size, calc(var(--xh-font-size) * 1.9));
   --xh-appbar-title-font-size-px: calc(var(--xh-appbar-title-font-size) * 1px);
-  --xh-appbar-box-shadow: var(--appbar-box-shadow, #{0 0 0 1px rgb(17 20 24 / 10%), 0 1px 1px rgb(17 20 24 / 20%)});
+  --xh-appbar-user-profile-hover-color: var(--appbar-user-profile-hover-color, var(--xh-orange));
 
   &.xh-dark {
     --xh-appbar-border-color: var(--appbar-border-color, #{mc('blue-grey', '700')});

package/svc/IdentityService.ts

@@ -30,16 +30,28 @@ export class IdentityService extends HoistService {
         }
     }
 
-    /** Current acting user (see authUser for notes on impersonation) */
+    /** @returns current acting user (see authUser for notes on impersonation) */
     get user(): HoistUser {
         return this._apparentUser;
     }
 
-    /** Current acting user's username. */
+    /** @returns current acting user's username. */
     get username(): string {
         return this.user?.username ?? null;
     }
 
+    /** @returns current acting user's initials, based on displayName. */
+    get userInitials(): string {
+        // Handle common case of displayName being left as an email address.
+        const [displayName] = this.user.displayName.split('@'),
+            nameParts = displayName.split(/[\s.]+/);
+
+        return nameParts
+            .map(part => part.charAt(0).toUpperCase())
+            .join('')
+            .substring(0, XH.isMobileApp ? 2 : 3);
+    }
+
     /**
      * Actual user who authenticated to the web application.
      * This will be the same as the user except when an administrator is impersonation another