@robosystems/core 0.8.2 → 0.8.3

package/auth-core/config.d.ts

@@ -24,4 +24,6 @@ export declare const getAppConfig: (appName: string) => AppConfig;
  */
 export declare const LOGIN_HOME_APP: AppName;
 export declare const getLoginHomeUrl: () => string;
+/** Product-facing name of the login home, for "managed on X" copy. */
+export declare const getLoginHomeName: () => string;
 export declare const isLoginHome: () => boolean;

package/auth-core/config.js

@@ -61,4 +61,6 @@ export const getAppConfig = (appName) => {
  */
 export const LOGIN_HOME_APP = process.env.NEXT_PUBLIC_LOGIN_HOME_APP || 'robosystems';
 export const getLoginHomeUrl = () => getAppConfig(LOGIN_HOME_APP).url;
+/** Product-facing name of the login home, for "managed on X" copy. */
+export const getLoginHomeName = () => getAppConfig(LOGIN_HOME_APP).displayName;
 export const isLoginHome = () => CURRENT_APP === LOGIN_HOME_APP;

package/auth-core/sso.d.ts

@@ -1,4 +1,17 @@
 import type { AppConfig, AuthUser } from './types';
+export interface SSORedirectUrlOptions {
+    /**
+     * Mirror the target app / return URL into this tab's sessionStorage as a
+     * same-domain fallback for `handleSSOLogin`. Default true.
+     *
+     * Pass false when the URL is being handed to a *different* tab: the hints
+     * are unreadable there (separate tab, separate origin) and would linger in
+     * this tab, where a later same-tab SSO completion with no `returnUrl`
+     * param would pick up the stale path and redirect somewhere the user
+     * never asked to go.
+     */
+    persistSessionHints?: boolean;
+}
 export declare class SSOManager {
     private authClient;
     constructor(apiUrl: string);
@@ -13,7 +26,7 @@ export declare class SSOManager {
     /**
      * Get SSO redirect URL using secure POST-based flow
      */
-    getSSORedirectUrl(targetApp: string, returnUrl?: string): Promise<string>;
+    getSSORedirectUrl(targetApp: string, returnUrl?: string, options?: SSORedirectUrlOptions): Promise<string>;
     /**
      * Handle SSO login using secure POST-based flow
      */
@@ -37,6 +50,7 @@ export declare class SSOManager {
 export declare function useSSO(apiUrl: string): {
     checkSSOAuthentication: () => Promise<AuthUser>;
     handleSSOLogin: () => Promise<AuthUser>;
+    getSSORedirectUrl: (targetApp: string, returnUrl?: string, options?: SSORedirectUrlOptions) => Promise<string>;
     navigateToApp: (targetApp: string, returnUrl?: string) => Promise<void>;
     getAvailableApps: () => AppConfig[];
 };

package/auth-core/sso.js

@@ -33,7 +33,8 @@ export class SSOManager {
     /**
      * Get SSO redirect URL using secure POST-based flow
      */
-    async getSSORedirectUrl(targetApp, returnUrl) {
+    async getSSORedirectUrl(targetApp, returnUrl, options = {}) {
+        const { persistSessionHints = true } = options;
         const ssoData = await this.generateSSOToken();
         const appConfig = APP_CONFIGS[targetApp];
         if (!appConfig) {
@@ -50,15 +51,17 @@ export class SSOManager {
         }
         // Store only non-sensitive metadata in sessionStorage as backup for same-domain cases
         // Note: We avoid storing the session_id in sessionStorage for security
-        try {
-            sessionStorage.setItem('sso_target_app', targetApp);
-            if (returnUrl) {
-                sessionStorage.setItem('sso_return_url', returnUrl);
+        if (persistSessionHints) {
+            try {
+                sessionStorage.setItem('sso_target_app', targetApp);
+                if (returnUrl) {
+                    sessionStorage.setItem('sso_return_url', returnUrl);
+                }
+            }
+            catch (error) {
+                // Storage error - continue without backup storage
+                debugLog('sessionStorage write failed during SSO URL generation', error);
             }
-        }
-        catch (error) {
-            // Storage error - continue without backup storage
-            debugLog('sessionStorage write failed during SSO URL generation', error);
         }
         return url.toString();
     }
@@ -273,6 +276,7 @@ export function useSSO(apiUrl) {
     return useMemo(() => ({
         checkSSOAuthentication: () => ssoManager.checkSSOAuthentication(),
         handleSSOLogin: () => ssoManager.handleSSOLogin(),
+        getSSORedirectUrl: (targetApp, returnUrl, options) => ssoManager.getSSORedirectUrl(targetApp, returnUrl, options),
         navigateToApp: (targetApp, returnUrl) => ssoManager.navigateToApp(targetApp, returnUrl),
         getAvailableApps: () => ssoManager.getAvailableApps(),
     }), [ssoManager]);

package/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export { useApiError } from './use-api-error';
+export { useCrossAppLink, type CrossAppTarget, type OpenCrossAppOptions, type UseCrossAppLinkResult, } from './use-cross-app-link';
 export { useMediaQuery } from './use-media-query';
 export { useStreamingQuery } from './use-streaming-query';
 export { useToast, type ToastMessage } from './use-toast';

package/hooks/index.js

@@ -1,4 +1,5 @@
 export { useApiError } from './use-api-error';
+export { useCrossAppLink, } from './use-cross-app-link';
 export { useMediaQuery } from './use-media-query';
 export { useStreamingQuery } from './use-streaming-query';
 export { useToast } from './use-toast';

package/hooks/use-cross-app-link.d.ts

@@ -0,0 +1,38 @@
+export type CrossAppTarget = '_blank' | '_self';
+export interface OpenCrossAppOptions {
+    /** Relative path on the target app, e.g. `/settings`. */
+    path?: string;
+    /**
+     * `_blank` (default) hands the destination to a new tab, leaving the
+     * current app exactly where it was — right for a *detour* (account
+     * settings, graph creation), where the user is coming back.
+     *
+     * `_self` navigates in place — right when leaving *is* the intent, as in
+     * the app switcher.
+     */
+    target?: CrossAppTarget;
+}
+export interface UseCrossAppLinkResult {
+    /** Resolves true once the destination has been handed off. */
+    openApp: (targetApp: string, options?: OpenCrossAppOptions) => Promise<boolean>;
+    /** Convenience wrapper targeting the configured login home. */
+    openLoginHome: (options?: OpenCrossAppOptions) => Promise<boolean>;
+    /** True while the SSO handoff is in flight. */
+    isOpening: boolean;
+}
+/**
+ * Open another RoboSystems app at a specific path, in one click.
+ *
+ * Cross-app navigation can't be a plain `<a href>`: the destination doesn't
+ * exist until an SSO token is minted and exchanged for a session ID, two
+ * round-trips deep. The apps sit on separate registrable domains, so a naked
+ * link to the target would drop the user on a login screen instead.
+ *
+ * That async gap is also why the new tab is claimed *synchronously*, before
+ * the first await. A `window.open()` issued after an await is outside the
+ * user-gesture stack and popup blockers swallow it; opening `about:blank`
+ * inside the gesture and pointing it at the URL afterwards is the standard
+ * way around that. If the open is refused anyway (popups hard-blocked), we
+ * degrade to a same-tab navigation rather than dead-ending the click.
+ */
+export declare function useCrossAppLink(apiUrl?: string): UseCrossAppLinkResult;

package/hooks/use-cross-app-link.js

@@ -0,0 +1,56 @@
+'use client';
+import { useCallback, useMemo, useState } from 'react';
+import { LOGIN_HOME_APP } from '../auth-core/config';
+import { SSOManager } from '../auth-core/sso';
+const DEFAULT_API_URL = process.env.NEXT_PUBLIC_ROBOSYSTEMS_API_URL || 'http://localhost:8000';
+/**
+ * Open another RoboSystems app at a specific path, in one click.
+ *
+ * Cross-app navigation can't be a plain `<a href>`: the destination doesn't
+ * exist until an SSO token is minted and exchanged for a session ID, two
+ * round-trips deep. The apps sit on separate registrable domains, so a naked
+ * link to the target would drop the user on a login screen instead.
+ *
+ * That async gap is also why the new tab is claimed *synchronously*, before
+ * the first await. A `window.open()` issued after an await is outside the
+ * user-gesture stack and popup blockers swallow it; opening `about:blank`
+ * inside the gesture and pointing it at the URL afterwards is the standard
+ * way around that. If the open is refused anyway (popups hard-blocked), we
+ * degrade to a same-tab navigation rather than dead-ending the click.
+ */
+export function useCrossAppLink(apiUrl = DEFAULT_API_URL) {
+    const ssoManager = useMemo(() => new SSOManager(apiUrl), [apiUrl]);
+    const [isOpening, setIsOpening] = useState(false);
+    const openApp = useCallback(async (targetApp, options = {}) => {
+        const { path, target = '_blank' } = options;
+        // Claim the tab inside the gesture — see the note above.
+        const childWindow = target === '_blank' ? window.open('', '_blank') : null;
+        const openedNewTab = childWindow !== null;
+        setIsOpening(true);
+        try {
+            const url = await ssoManager.getSSORedirectUrl(targetApp, path, {
+                persistSessionHints: !openedNewTab,
+            });
+            if (childWindow) {
+                childWindow.location.href = url;
+            }
+            else {
+                window.location.href = url;
+            }
+            return true;
+        }
+        catch (error) {
+            // Leaving a blank tab behind is worse than no tab at all.
+            childWindow === null || childWindow === void 0 ? void 0 : childWindow.close();
+            if (process.env.NODE_ENV === 'development') {
+                console.error(`[SSO] Failed to open ${targetApp}${path ? path : ''}:`, error);
+            }
+            return false;
+        }
+        finally {
+            setIsOpening(false);
+        }
+    }, [ssoManager]);
+    const openLoginHome = useCallback((options) => openApp(LOGIN_HOME_APP, options), [openApp]);
+    return { openApp, openLoginHome, isOpening };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/core",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Shared RoboSystems frontend core library (auth, contexts, task monitoring, UI components) for the RoboSystems Next.js apps",
   "license": "MIT",
   "private": false,

package/ui-components/layout/CoreNavbar.js

@@ -2,13 +2,14 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { DarkThemeToggle, Dropdown, DropdownDivider, DropdownHeader, DropdownItem, Navbar as FlowbiteNavbar, NavbarBrand, Tooltip, } from 'flowbite-react';
 import Link from 'next/link';
-import { HiMenuAlt1, HiUserCircle, HiX } from 'react-icons/hi';
+import { HiExternalLink, HiMenuAlt1, HiUserCircle, HiX } from 'react-icons/hi';
 import { AppSwitcher } from '../../auth-components';
 import { useAuth } from '../../auth-components/AuthProvider';
 import { useSidebarContext } from '../../contexts';
 import { useMediaQuery, useUser } from '../../hooks';
 import { customTheme } from '../../theme';
 import { LogoBadge } from '../Logo';
+import { useAccountSettingsLink } from './account-settings';
 import { ThemeToggle } from './ThemeToggle';
 export function CoreNavbar({ appName, currentApp, apiUrl = process.env.NEXT_PUBLIC_ROBOSYSTEMS_API_URL ||
     'http://localhost:8000', homeHref = '/home', logoAltText, additionalComponents, className = '', borderColorClass = 'dark:border-gray-700', useCustomThemeToggle = true, showAppSwitcherFirst = false, }) {
@@ -43,10 +44,13 @@ export function CoreNavbar({ appName, currentApp, apiUrl = process.env.NEXT_PUBL
         return (_jsxs(_Fragment, { children: [_jsx("div", { className: "hidden dark:block", children: _jsx(Tooltip, { content: "Toggle light mode", theme: customTheme.tooltip, children: _jsx(DarkThemeToggle, {}) }) }), _jsx("div", { className: "dark:hidden", children: _jsx(Tooltip, { content: "Toggle dark mode", theme: customTheme.tooltip, children: _jsx(DarkThemeToggle, {}) }) })] }));
     };
     const renderAppSwitcher = () => (_jsx(Tooltip, { content: "Switch apps", theme: customTheme.tooltip, children: _jsx(AppSwitcher, { apiUrl: apiUrl, currentApp: currentApp }) }));
-    return (_jsx(FlowbiteNavbar, { fluid: true, theme: customTheme.navbar, className: `fixed top-0 z-30 w-full border-b border-gray-200 p-0 ${borderColorClass} bg-white sm:p-0 dark:bg-black ${className}`, children: _jsx("div", { className: "w-full p-3 pr-4", children: _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("div", { className: "flex items-center", children: [_jsxs("button", { onClick: handleToggleSidebar, className: "mr-3 cursor-pointer rounded-sm p-2 text-gray-600 hover:bg-zinc-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-zinc-700 dark:hover:text-white", children: [_jsx("span", { className: "sr-only", children: "Toggle sidebar" }), _jsx("div", { className: "lg:hidden", children: sidebar.mobile.isOpen ? (_jsx(HiX, { className: "h-6 w-6" })) : (_jsx(HiMenuAlt1, { className: "h-6 w-6" })) }), _jsx("div", { className: "hidden lg:block", children: _jsx(HiMenuAlt1, { className: "h-6 w-6" }) })] }), _jsxs(NavbarBrand, { as: Link, href: homeHref, className: "mr-14", children: [_jsx(LogoBadge, { app: currentApp, animate: "once", className: "mr-2 h-10 w-10" }), _jsx("span", { className: "font-heading mt-2 ml-1 self-center text-2xl font-semibold whitespace-nowrap text-gray-900 dark:text-white", children: appName })] })] }), _jsx("div", { className: "flex items-center lg:gap-3", children: _jsxs("div", { className: "flex items-center", children: [additionalComponents && (_jsx("div", { className: "mr-2 hidden md:block", children: additionalComponents })), _jsxs("div", { className: "flex items-center space-x-2", children: [showAppSwitcherFirst && renderAppSwitcher(), renderThemeToggle(), !showAppSwitcherFirst && renderAppSwitcher(), _jsx(UserDropdown, { user: user, onLogout: handleLogout })] })] }) })] }) }) }));
+    return (_jsx(FlowbiteNavbar, { fluid: true, theme: customTheme.navbar, className: `fixed top-0 z-30 w-full border-b border-gray-200 p-0 ${borderColorClass} bg-white sm:p-0 dark:bg-black ${className}`, children: _jsx("div", { className: "w-full p-3 pr-4", children: _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("div", { className: "flex items-center", children: [_jsxs("button", { onClick: handleToggleSidebar, className: "mr-3 cursor-pointer rounded-sm p-2 text-gray-600 hover:bg-zinc-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-zinc-700 dark:hover:text-white", children: [_jsx("span", { className: "sr-only", children: "Toggle sidebar" }), _jsx("div", { className: "lg:hidden", children: sidebar.mobile.isOpen ? (_jsx(HiX, { className: "h-6 w-6" })) : (_jsx(HiMenuAlt1, { className: "h-6 w-6" })) }), _jsx("div", { className: "hidden lg:block", children: _jsx(HiMenuAlt1, { className: "h-6 w-6" }) })] }), _jsxs(NavbarBrand, { as: Link, href: homeHref, className: "mr-14", children: [_jsx(LogoBadge, { app: currentApp, animate: "once", className: "mr-2 h-10 w-10" }), _jsx("span", { className: "font-heading mt-2 ml-1 self-center text-2xl font-semibold whitespace-nowrap text-gray-900 dark:text-white", children: appName })] })] }), _jsx("div", { className: "flex items-center lg:gap-3", children: _jsxs("div", { className: "flex items-center", children: [additionalComponents && (_jsx("div", { className: "mr-2 hidden md:block", children: additionalComponents })), _jsxs("div", { className: "flex items-center space-x-2", children: [showAppSwitcherFirst && renderAppSwitcher(), renderThemeToggle(), !showAppSwitcherFirst && renderAppSwitcher(), _jsx(UserDropdown, { user: user, apiUrl: apiUrl, onLogout: handleLogout })] })] }) })] }) }) }));
 }
-function UserDropdown({ user, onLogout }) {
-    return (_jsx("div", { className: "relative", children: _jsxs(Dropdown, { theme: Object.assign(Object.assign({}, customTheme.dropdown), { floating: Object.assign(Object.assign({}, customTheme.dropdown.floating), { base: `${customTheme.dropdown.floating.base} z-50! w-64` }) }), arrowIcon: false, inline: true, label: _jsxs("span", { className: "inline-flex h-10 w-10 items-center justify-center rounded-lg text-sm text-gray-500 hover:bg-zinc-100 focus:ring-2 focus:ring-gray-200 focus:outline-hidden dark:text-gray-400 dark:hover:bg-zinc-700 dark:focus:ring-gray-600", children: [_jsx("span", { className: "sr-only", children: "User menu" }), _jsx(HiUserCircle, { className: "h-6 w-6" })] }), children: [_jsxs(DropdownHeader, { theme: { header: customTheme.dropdown.floating.header }, className: "px-4 py-3", children: [_jsx("div", { className: "block text-sm font-medium text-gray-900 dark:text-white", children: (user === null || user === void 0 ? void 0 : user.name) || 'User' }), (user === null || user === void 0 ? void 0 : user.email) && (_jsx("div", { className: "block truncate text-sm text-gray-500 dark:text-gray-400", children: user.email }))] }), _jsx(DropdownItem, { theme: customTheme.dropdown.floating.item, as: Link, href: "/settings", className: "flex w-full items-center space-x-3 p-3", children: "User Settings" }), _jsx(DropdownDivider, { theme: { divider: customTheme.dropdown.floating.divider } }), _jsx(DropdownItem, { theme: customTheme.dropdown.floating.item, onClick: () => {
+function UserDropdown({ user, apiUrl, onLogout }) {
+    const settings = useAccountSettingsLink(apiUrl);
+    return (_jsx("div", { className: "relative", children: _jsxs(Dropdown, { theme: Object.assign(Object.assign({}, customTheme.dropdown), { floating: Object.assign(Object.assign({}, customTheme.dropdown.floating), { base: `${customTheme.dropdown.floating.base} z-50! w-64` }) }), arrowIcon: false, inline: true, label: _jsxs("span", { className: "inline-flex h-10 w-10 items-center justify-center rounded-lg text-sm text-gray-500 hover:bg-zinc-100 focus:ring-2 focus:ring-gray-200 focus:outline-hidden dark:text-gray-400 dark:hover:bg-zinc-700 dark:focus:ring-gray-600", children: [_jsx("span", { className: "sr-only", children: "User menu" }), _jsx(HiUserCircle, { className: "h-6 w-6" })] }), children: [_jsxs(DropdownHeader, { theme: { header: customTheme.dropdown.floating.header }, className: "px-4 py-3", children: [_jsx("div", { className: "block text-sm font-medium text-gray-900 dark:text-white", children: (user === null || user === void 0 ? void 0 : user.name) || 'User' }), (user === null || user === void 0 ? void 0 : user.email) && (_jsx("div", { className: "block truncate text-sm text-gray-500 dark:text-gray-400", children: user.email }))] }), settings.isCrossApp ? (_jsxs(DropdownItem, { theme: customTheme.dropdown.floating.item, onClick: () => {
+                        void settings.open();
+                    }, title: settings.description, className: "flex w-full items-center justify-between p-3", children: [_jsx("span", { children: "User Settings" }), _jsx(HiExternalLink, { "aria-hidden": "true", className: "ml-3 h-4 w-4 shrink-0 text-gray-400 dark:text-gray-500" }), _jsx("span", { className: "sr-only", children: ` (opens ${settings.hostAppName} in a new tab)` })] })) : (_jsx(DropdownItem, { theme: customTheme.dropdown.floating.item, as: Link, href: settings.href, className: "flex w-full items-center space-x-3 p-3", children: "User Settings" })), _jsx(DropdownDivider, { theme: { divider: customTheme.dropdown.floating.divider } }), _jsx(DropdownItem, { theme: customTheme.dropdown.floating.item, onClick: () => {
                         onLogout();
                     }, className: "flex w-full items-center space-x-3 p-3", children: "Sign out" })] }) }));
 }

package/ui-components/layout/CoreSidebar.js

@@ -7,6 +7,7 @@ import { HiCog, HiOfficeBuilding } from 'react-icons/hi';
 import { twMerge } from 'tailwind-merge';
 import { useOrg, useSidebarContext } from '../../contexts';
 import { customTheme } from '../../theme';
+import { useAccountSettingsLink } from './account-settings';
 export function CoreSidebar({ navigationItems, features = {}, bottomMenuActions = [], additionalMobileComponents, className = '', borderColorClass = 'dark:border-gray-700', }) {
     return (_jsxs(_Fragment, { children: [_jsx("div", { className: "lg:hidden", children: _jsx(MobileSidebar, { navigationItems: navigationItems, features: features, bottomMenuActions: bottomMenuActions, additionalMobileComponents: additionalMobileComponents, borderColorClass: borderColorClass }) }), _jsx("div", { className: `hidden lg:block ${className}`, children: _jsx(DesktopSidebar, { navigationItems: navigationItems, features: features, bottomMenuActions: bottomMenuActions, borderColorClass: borderColorClass }) })] }));
 }
@@ -57,6 +58,19 @@ function OrgSection({ isCollapsed, showOrgSection = true, }) {
                 ? 'bg-zinc-100 text-gray-900 dark:bg-zinc-800 dark:text-gray-200'
                 : '', children: _jsx("span", { className: "truncate text-sm", children: currentOrg.name }) }) }));
 }
+/**
+ * The account-settings cog. A plain link on the login home; on the product
+ * apps an SSO handoff into a new tab, so this app keeps its place.
+ */
+function SettingsButton() {
+    const settings = useAccountSettingsLink();
+    if (!settings.isCrossApp) {
+        return (_jsx(Tooltip, { content: settings.description, theme: customTheme.tooltip, children: _jsx(Button, { as: Link, href: settings.href, color: "ghost", className: "rounded-lg p-2 hover:bg-gray-100 dark:hover:bg-gray-700", children: _jsx(HiCog, { className: "text-lg text-gray-500 dark:text-gray-400" }) }) }));
+    }
+    return (_jsx(Tooltip, { content: settings.description, theme: customTheme.tooltip, children: _jsx(Button, { onClick: () => {
+                void settings.open();
+            }, disabled: settings.isOpening, color: "ghost", "aria-label": settings.description, className: "rounded-lg p-2 hover:bg-gray-100 disabled:opacity-50 dark:hover:bg-gray-700", children: _jsx(HiCog, { className: "text-lg text-gray-500 dark:text-gray-400" }) }) }));
+}
 function BottomMenu({ isCollapsed, features, bottomMenuActions, }) {
-    return (_jsxs("div", { className: `flex items-center justify-center border-t border-gray-200 px-4 py-4 dark:border-gray-700 ${isCollapsed ? 'flex-col gap-y-2' : 'gap-x-5'}`, children: [_jsx(Tooltip, { content: "Settings", theme: customTheme.tooltip, children: _jsx(Button, { as: Link, href: "/settings", color: "ghost", className: "rounded-lg p-2 hover:bg-gray-100 dark:hover:bg-gray-700", children: _jsx(HiCog, { className: "text-lg text-gray-500 dark:text-gray-400" }) }) }), bottomMenuActions.map((action, index) => (_jsx(Tooltip, { content: action.tooltip, theme: customTheme.tooltip, children: _jsx(Button, { onClick: action.onClick, color: "ghost", className: "rounded-lg p-2 hover:bg-gray-100 dark:hover:bg-gray-700", children: _jsx(action.icon, { className: "text-lg text-gray-500 dark:text-gray-400" }) }) }, index)))] }));
+    return (_jsxs("div", { className: `flex items-center justify-center border-t border-gray-200 px-4 py-4 dark:border-gray-700 ${isCollapsed ? 'flex-col gap-y-2' : 'gap-x-5'}`, children: [_jsx(SettingsButton, {}), bottomMenuActions.map((action, index) => (_jsx(Tooltip, { content: action.tooltip, theme: customTheme.tooltip, children: _jsx(Button, { onClick: action.onClick, color: "ghost", className: "rounded-lg p-2 hover:bg-gray-100 dark:hover:bg-gray-700", children: _jsx(action.icon, { className: "text-lg text-gray-500 dark:text-gray-400" }) }) }, index)))] }));
 }

package/ui-components/layout/account-settings.d.ts

@@ -0,0 +1,33 @@
+/** Where the account surface lives, on whichever app hosts it. */
+export declare const ACCOUNT_SETTINGS_PATH = "/settings";
+interface AccountSettingsLinkBase {
+    isOpening: boolean;
+    /** Name of the app hosting the account surface, e.g. "RoboSystems". */
+    hostAppName: string;
+    /** Tooltip / accessible description, honest about leaving the app. */
+    description: string;
+}
+/**
+ * Exactly one of `href` / `open` is meaningful, and the discriminant says
+ * which — so a caller can't render a link to a destination that needs an
+ * SSO handoff, or a button where a plain anchor belongs.
+ */
+export type AccountSettingsLink = AccountSettingsLinkBase & ({
+    isCrossApp: false;
+    href: string;
+    open?: never;
+} | {
+    isCrossApp: true;
+    href?: never;
+    open: () => Promise<boolean>;
+});
+/**
+ * Resolve how this app should reach account settings.
+ *
+ * Identity, password, passkeys and API keys are account-global and live on
+ * one app — the login home. On that app the cog is an ordinary link; on the
+ * product apps it's an SSO handoff into a new tab, so the user's place here
+ * (a half-written journal entry, a loaded report) survives the detour.
+ */
+export declare function useAccountSettingsLink(apiUrl?: string): AccountSettingsLink;
+export {};

package/ui-components/layout/account-settings.js

@@ -0,0 +1,33 @@
+'use client';
+import { getLoginHomeName, isLoginHome } from '../../auth-core/config';
+import { useCrossAppLink } from '../../hooks/use-cross-app-link';
+/** Where the account surface lives, on whichever app hosts it. */
+export const ACCOUNT_SETTINGS_PATH = '/settings';
+/**
+ * Resolve how this app should reach account settings.
+ *
+ * Identity, password, passkeys and API keys are account-global and live on
+ * one app — the login home. On that app the cog is an ordinary link; on the
+ * product apps it's an SSO handoff into a new tab, so the user's place here
+ * (a half-written journal entry, a loaded report) survives the detour.
+ */
+export function useAccountSettingsLink(apiUrl) {
+    const { openLoginHome, isOpening } = useCrossAppLink(apiUrl);
+    const hostAppName = getLoginHomeName();
+    if (isLoginHome()) {
+        return {
+            isCrossApp: false,
+            href: ACCOUNT_SETTINGS_PATH,
+            isOpening,
+            hostAppName,
+            description: 'Settings',
+        };
+    }
+    return {
+        isCrossApp: true,
+        open: () => openLoginHome({ path: ACCOUNT_SETTINGS_PATH, target: '_blank' }),
+        isOpening,
+        hostAppName,
+        description: `Settings (opens ${hostAppName} in a new tab)`,
+    };
+}

package/ui-components/layout/index.d.ts

@@ -1,3 +1,4 @@
+export { ACCOUNT_SETTINGS_PATH, useAccountSettingsLink, type AccountSettingsLink, } from './account-settings';
 export { CoreNavbar } from './CoreNavbar';
 export { CoreSidebar, type SidebarItemData } from './CoreSidebar';
 export { LandingFooter, type FooterLink, type LandingFooterProps, } from './LandingFooter';

package/ui-components/layout/index.js

@@ -1,3 +1,4 @@
+export { ACCOUNT_SETTINGS_PATH, useAccountSettingsLink, } from './account-settings';
 export { CoreNavbar } from './CoreNavbar';
 export { CoreSidebar } from './CoreSidebar';
 export { LandingFooter, } from './LandingFooter';