@genesislcap/foundation-react-utils 14.496.2-alpha-da9ccbd.0 → 14.497.0

package/dist/esm/router/pbc-routes.js

@@ -0,0 +1,19 @@
+/**
+ * Merge a static route table with PBC routes (e.g. from `getApp().routes`) into
+ * one {@link AppRouteConfig} array. PBC routes are guarded, in-layout, and carry
+ * their element/tag + navItems through `data` so downstream consumers (a PBC
+ * container, nav-item derivation) can read them — matching the `data` shape the
+ * hand-rolled version produced.
+ */
+export function mergePbcRoutes(staticRoutes, pbcRoutes, { renderPbc }) {
+    const mapped = pbcRoutes.map((pbc) => {
+        var _a;
+        return ({
+            path: `/${pbc.path}`,
+            element: renderPbc(pbc),
+            permissionCode: (_a = pbc.settings) === null || _a === void 0 ? void 0 : _a.permissionCode,
+            data: Object.assign(Object.assign({}, pbc.settings), { pbcElement: pbc.element, pbcElementTag: pbc.elementTag, navItems: pbc.navItems }),
+        });
+    });
+    return [...staticRoutes, ...mapped];
+}

package/dist/esm/router/post-login-redirect.js

@@ -0,0 +1,14 @@
+/**
+ * Build the post-login redirect target from a router location's `state.from`,
+ * preserving the query string and hash so deep-link params (e.g.
+ * `?component=<name>`) survive the login bounce. Falls back to `defaultPath`
+ * when there is no stashed origin.
+ *
+ * @param location - The current router location (needs only `state.from`).
+ * @param defaultPath - Where to land when nothing was stashed. Defaults to `/`.
+ */
+export function buildPostLoginRedirect(location, defaultPath = '/') {
+    var _a, _b, _c;
+    const from = (_a = location.state) === null || _a === void 0 ? void 0 : _a.from;
+    return from ? `${from.pathname}${(_b = from.search) !== null && _b !== void 0 ? _b : ''}${(_c = from.hash) !== null && _c !== void 0 ? _c : ''}` : defaultPath;
+}

package/dist/esm/router/protected-route.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Navigate, useLocation } from 'react-router-dom';
+/**
+ * Route guard. In order:
+ * - not authenticated → redirect to `loginPath`, stashing the full current
+ *   location in `state.from` (incl. `search` + `hash`) so the login flow can
+ *   restore the original deep-link via {@link buildPostLoginRedirect};
+ * - authenticated but `hasPermission === false` → redirect to `notPermittedPath`;
+ * - otherwise → render `children`.
+ *
+ * Deliberately decoupled from any auth package — pass the booleans in (or use
+ * {@link createProtectedRoute} to bind the checks once).
+ */
+export function ProtectedRoute({ isAuthenticated, hasPermission = true, loginPath = '/login', notPermittedPath = '/not-permitted', children, }) {
+    const location = useLocation();
+    if (!isAuthenticated) {
+        return _jsx(Navigate, { to: loginPath, state: { from: location }, replace: true });
+    }
+    if (!hasPermission) {
+        return _jsx(Navigate, { to: notPermittedPath, replace: true });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Bind auth (and optionally permission) checks once and get an ergonomic
+ * `<ProtectedRoute>` that only needs `children` (plus an optional
+ * `permissionCode`) — ideal when a route table wraps many elements.
+ *
+ * **Call this at module scope, never inside a component's render.** It returns a
+ * new component type each call; invoking it during render recreates that type
+ * every render, forcing React to unmount and remount the entire protected
+ * subtree (flicker + lost state).
+ *
+ * @example
+ * ```tsx
+ * const ProtectedRoute = createProtectedRoute({
+ *   getIsAuthenticated: () => getUser().isAuthenticated,
+ *   hasPermission: (code) => !code || canView(getUser(), code),
+ * });
+ * ```
+ */
+export function createProtectedRoute({ getIsAuthenticated, hasPermission, loginPath, notPermittedPath, }) {
+    return function BoundProtectedRoute({ children, permissionCode }) {
+        return (_jsx(ProtectedRoute, { isAuthenticated: getIsAuthenticated(), hasPermission: hasPermission ? hasPermission(permissionCode) : true, loginPath: loginPath, notPermittedPath: notPermittedPath, children: children }));
+    };
+}

package/dist/esm/router/router.test.js

@@ -0,0 +1,82 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { mergePbcRoutes } from './pbc-routes';
+import { buildPostLoginRedirect } from './post-login-redirect';
+import { createComponentRegistry } from './single-component';
+const RedirectSuite = createLogicSuite('buildPostLoginRedirect');
+RedirectSuite('falls back to `/` when there is no stashed origin', () => {
+    assert.is(buildPostLoginRedirect({}), '/');
+    assert.is(buildPostLoginRedirect({ state: null }), '/');
+    assert.is(buildPostLoginRedirect({ state: {} }), '/');
+});
+RedirectSuite('honours a custom default path', () => {
+    assert.is(buildPostLoginRedirect({}, '/home'), '/home');
+});
+RedirectSuite('returns the pathname when there is no search/hash', () => {
+    assert.is(buildPostLoginRedirect({ state: { from: { pathname: '/grids' } } }), '/grids');
+});
+RedirectSuite('preserves search and hash so deep-link params survive', () => {
+    assert.is(buildPostLoginRedirect({
+        state: { from: { pathname: '/', search: '?component=Home', hash: '#top' } },
+    }), '/?component=Home#top');
+});
+RedirectSuite.run();
+const RegistrySuite = createLogicSuite('createComponentRegistry');
+const Home = () => null;
+const GridsShowcase = () => null;
+const registry = createComponentRegistry({ Home, GridsShowcase });
+RegistrySuite('resolves an exact name', () => {
+    assert.is(registry.resolve('Home'), Home);
+    assert.is(registry.resolve('GridsShowcase'), GridsShowcase);
+});
+RegistrySuite('resolves case- and separator-insensitively', () => {
+    assert.is(registry.resolve('home'), Home);
+    assert.is(registry.resolve('gridsshowcase'), GridsShowcase);
+    assert.is(registry.resolve('grids-showcase'), GridsShowcase);
+    assert.is(registry.resolve('grids_showcase'), GridsShowcase);
+    assert.is(registry.resolve('Grids Showcase'), GridsShowcase);
+});
+RegistrySuite('returns undefined for unknown or empty names', () => {
+    assert.is(registry.resolve('nope'), undefined);
+    assert.is(registry.resolve(null), undefined);
+    assert.is(registry.resolve(undefined), undefined);
+    assert.is(registry.resolve(''), undefined);
+});
+RegistrySuite('exposes the registered names via available()', () => {
+    assert.equal(registry.available(), ['Home', 'GridsShowcase']);
+});
+RegistrySuite.run();
+const PbcSuite = createLogicSuite('mergePbcRoutes');
+PbcSuite('appends PBC routes after the static ones', () => {
+    const staticRoutes = [{ path: '/home', element: null }];
+    const merged = mergePbcRoutes(staticRoutes, [{ path: 'reporting' }], {
+        renderPbc: () => 'pbc',
+    });
+    assert.is(merged.length, 2);
+    assert.is(merged[0].path, '/home');
+    assert.is(merged[1].path, '/reporting');
+    assert.is(merged[1].element, 'pbc');
+});
+PbcSuite('carries pbc element/tag + navItems + settings through `data`', () => {
+    var _a, _b, _c, _d;
+    const navItems = [{ navId: 'header', title: 'Reporting' }];
+    const el = () => 'loader';
+    const merged = mergePbcRoutes([], [
+        {
+            path: 'reporting',
+            element: el,
+            elementTag: 'reporting-app',
+            navItems,
+            settings: { permissionCode: 'ReportView' },
+        },
+    ], { renderPbc: () => null });
+    assert.is(merged[0].permissionCode, 'ReportView');
+    assert.is((_a = merged[0].data) === null || _a === void 0 ? void 0 : _a.pbcElement, el);
+    assert.is((_b = merged[0].data) === null || _b === void 0 ? void 0 : _b.pbcElementTag, 'reporting-app');
+    assert.equal((_c = merged[0].data) === null || _c === void 0 ? void 0 : _c.navItems, navItems);
+    assert.is((_d = merged[0].data) === null || _d === void 0 ? void 0 : _d.permissionCode, 'ReportView');
+});
+PbcSuite('returns only the static routes when there are no PBC routes', () => {
+    const staticRoutes = [{ path: '/home', element: null }];
+    assert.equal(mergePbcRoutes(staticRoutes, [], { renderPbc: () => null }), staticRoutes);
+});
+PbcSuite.run();

package/dist/esm/router/single-component.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Read a query-string parameter from the current URL.
+ *
+ * Call this at **module-evaluation time** in your app (i.e. as a top-level
+ * `const`), before the app shell's async bootstrap rewrites the URL and drops
+ * the query string, and store the result. That way a deep-link param such as
+ * `?component=<name>` survives even though it is gone by the time the router
+ * mounts.
+ */
+export function readInitialParam(key) {
+    const search = typeof window !== 'undefined' ? window.location.search : '';
+    return new URLSearchParams(search).get(key);
+}
+/** Normalize a name so lookups are case-insensitive and separator-agnostic. */
+const normalize = (name) => name.toLowerCase().replace(/[-_\s]/g, '');
+/**
+ * Create a name → component registry whose `resolve` is case- and
+ * separator-insensitive (`LimitDistributionChart` === `limit-distribution-chart`).
+ */
+export function createComponentRegistry(entries) {
+    return {
+        entries,
+        available: () => Object.keys(entries),
+        resolve(name) {
+            if (!name) {
+                return undefined;
+            }
+            const direct = entries[name];
+            if (direct) {
+                return direct;
+            }
+            const target = normalize(name);
+            const key = Object.keys(entries).find((k) => normalize(k) === target);
+            return key ? entries[key] : undefined;
+        },
+    };
+}
+const defaultUnknown = (name, available) => (_jsx("div", { role: "alert", style: { padding: 16 }, children: `Unknown component "${name !== null && name !== void 0 ? name : ''}". Available: ${available.join(', ')}` }));
+/**
+ * Resolve `name` against `registry` and render the matching component, or a
+ * fallback when unmatched.
+ *
+ * Theming/provider chrome is intentionally left to the caller — wrap this outlet
+ * in your app's design-system provider so the standalone component is themed
+ * identically to how it appears in-app.
+ */
+export function SingleComponentOutlet({ name, registry, renderUnknown = defaultUnknown, }) {
+    const Component = registry.resolve(name);
+    return _jsx(_Fragment, { children: Component ? _jsx(Component, {}) : renderUnknown(name, registry.available()) });
+}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/create-grid-pro-cell-portals.tsx","../src/create-grid-pro-cell-renderer.ts","../src/create-react-renderer.ts","../src/index.ts","../src/react-layout-factory.tsx"],"version":"5.9.2"}
+{"root":["../src/create-grid-pro-cell-portals.tsx","../src/create-grid-pro-cell-renderer.ts","../src/create-react-renderer.ts","../src/index.ts","../src/react-layout-factory.tsx","../src/router/app-routes.tsx","../src/router/index.ts","../src/router/pbc-routes.ts","../src/router/post-login-redirect.ts","../src/router/protected-route.tsx","../src/router/router.test.ts","../src/router/single-component.tsx"],"version":"5.9.2"}

package/package.json

@@ -1,11 +1,29 @@
 {
   "name": "@genesislcap/foundation-react-utils",
   "description": "Genesis Foundation React Utils",
-  "version": "14.496.2-alpha-da9ccbd.0",
+  "version": "14.497.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./router": {
+      "types": "./dist/dts/router/index.d.ts",
+      "default": "./dist/esm/router/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "router": [
+        "./dist/dts/router/index.d.ts"
+      ]
+    }
+  },
   "engines": {
     "node": ">=22.0.0"
   },
@@ -29,23 +47,30 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/genx": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/rollup-builder": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/ts-builder": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/uvu-playwright-builder": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/vite-builder": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/webpack-builder": "14.496.2-alpha-da9ccbd.0"
+    "@genesislcap/foundation-testing": "14.497.0",
+    "@genesislcap/genx": "14.497.0",
+    "@genesislcap/rollup-builder": "14.497.0",
+    "@genesislcap/ts-builder": "14.497.0",
+    "@genesislcap/uvu-playwright-builder": "14.497.0",
+    "@genesislcap/vite-builder": "14.497.0",
+    "@genesislcap/webpack-builder": "14.497.0",
+    "react-router-dom": "^7.1.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@genesislcap/foundation-forms": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/foundation-layout": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/foundation-logger": "14.496.2-alpha-da9ccbd.0",
-    "@genesislcap/web-core": "14.496.2-alpha-da9ccbd.0",
+    "@genesislcap/foundation-forms": "14.497.0",
+    "@genesislcap/foundation-layout": "14.497.0",
+    "@genesislcap/foundation-logger": "14.497.0",
+    "@genesislcap/web-core": "14.497.0",
     "@jsonforms/core": "^3.2.1",
     "@r2wc/react-to-web-component": "^2.0.2"
   },
@@ -58,5 +83,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "daac29f621ee844cc6e269c0b8bd52c56bff8cf0"
+  "gitHead": "8859a3cd83bd40fc5e5bbff9be5ebe02380fb6ec"
 }

package/src/router/app-routes.tsx

@@ -0,0 +1,141 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import { Navigate, Route, Routes } from 'react-router-dom';
+import type { BoundProtectedRouteProps } from './protected-route';
+
+/**
+ * Declarative description of one app route. The `element` is rendered when the
+ * path matches; guarding, layout nesting, and permission are derived from the
+ * flags below so the app doesn't hand-write the `<Route>`/`<ProtectedRoute>`
+ * boilerplate per route.
+ */
+export interface AppRouteConfig {
+  path: string;
+  element: ReactNode;
+  /** Skip the auth guard (e.g. login, not-permitted). Default `false`. */
+  public?: boolean;
+  /** Render outside the shared layout. Default `false` (guarded routes sit in the layout). */
+  noLayout?: boolean;
+  /** Permission code handed to the guard's optional permission check. */
+  permissionCode?: string;
+  /**
+   * Nested child routes rendered inside this route's `element` (which must
+   * render an `<Outlet />`). Children use paths relative to this route and
+   * inherit its guard — they are rendered as plain routes, not re-guarded.
+   */
+  children?: AppRouteConfig[];
+  /** Arbitrary metadata preserved for other consumers (nav items, PBC info, ...). */
+  data?: Record<string, any>;
+}
+
+/** A simple `from → to` redirect. */
+export interface RouteRedirect {
+  from: string;
+  to: string;
+}
+
+/**
+ * Options for {@link renderAppRoutes}.
+ */
+export interface RenderAppRoutesOptions {
+  /** The full route table (static + any merged PBC routes). */
+  routes: AppRouteConfig[];
+  /**
+   * Guard component (typically from `createProtectedRoute`) wrapping every
+   * non-public route; receives each route's `permissionCode`.
+   */
+  ProtectedRoute: ComponentType<BoundProtectedRouteProps>;
+  /**
+   * Layout route element (rendering an `<Outlet />`) that wraps in-layout
+   * routes. Omit to render every route at the top level.
+   */
+  layout?: ReactElement;
+  /** `from → to` redirects rendered before the routes. */
+  redirects?: RouteRedirect[];
+  /** Element for unmatched paths (`*`). */
+  notFound?: ReactNode;
+  /**
+   * When `name` is truthy, short-circuit to single-component mode: render only
+   * the public routes (so login / session-restore still work) plus a catch-all
+   * rendering `element` behind the guard. See the single-component deep-link.
+   */
+  singleComponent?: { name: string | null | undefined; element: ReactNode };
+}
+
+const resolvePermissionCode = (route: AppRouteConfig): string | undefined =>
+  route.permissionCode ?? (route.data?.permissionCode as string | undefined);
+
+/**
+ * Build the app's `<Routes>` tree from a declarative route table, applying the
+ * auth guard, layout nesting, redirects, not-found, and the single-component
+ * short-circuit — so a consuming app configures routes instead of hand-writing
+ * repetitive `<Route element={<ProtectedRoute>…}>` markup.
+ */
+export function renderAppRoutes({
+  routes,
+  ProtectedRoute,
+  layout,
+  redirects = [],
+  notFound,
+  singleComponent,
+}: RenderAppRoutesOptions): ReactElement {
+  const publicRoutes = routes.filter((r) => r.public);
+
+  // Single-component mode: keep public routes reachable (login / session
+  // restore) and gate everything else behind the guard rendering the component.
+  if (singleComponent?.name) {
+    return (
+      <Routes>
+        {publicRoutes.map((r) => (
+          <Route key={r.path} path={r.path} element={r.element} />
+        ))}
+        <Route path="*" element={<ProtectedRoute>{singleComponent.element}</ProtectedRoute>} />
+      </Routes>
+    );
+  }
+
+  const guarded = routes.filter((r) => !r.public);
+  const inLayout = guarded.filter((r) => !r.noLayout);
+  const topLevelGuarded = guarded.filter((r) => r.noLayout);
+
+  // Nested children render as plain relative routes inside the parent's
+  // `<Outlet />`; they inherit the parent's guard, so they are not re-wrapped.
+  const renderChild = (c: AppRouteConfig): ReactElement =>
+    c.children?.length ? (
+      <Route key={c.path} path={c.path} element={c.element}>
+        {c.children.map(renderChild)}
+      </Route>
+    ) : (
+      <Route key={c.path} path={c.path} element={c.element} />
+    );
+
+  const renderGuarded = (r: AppRouteConfig) => {
+    const element = (
+      <ProtectedRoute permissionCode={resolvePermissionCode(r)}>{r.element}</ProtectedRoute>
+    );
+    return r.children?.length ? (
+      <Route key={r.path} path={r.path} element={element}>
+        {r.children.map(renderChild)}
+      </Route>
+    ) : (
+      <Route key={r.path} path={r.path} element={element} />
+    );
+  };
+
+  return (
+    <Routes>
+      {redirects.map((r) => (
+        <Route key={`redirect:${r.from}`} path={r.from} element={<Navigate to={r.to} replace />} />
+      ))}
+      {publicRoutes.map((r) => (
+        <Route key={r.path} path={r.path} element={r.element} />
+      ))}
+      {topLevelGuarded.map(renderGuarded)}
+      {layout ? (
+        <Route element={layout}>{inLayout.map(renderGuarded)}</Route>
+      ) : (
+        inLayout.map(renderGuarded)
+      )}
+      {notFound ? <Route path="*" element={notFound} /> : null}
+    </Routes>
+  );
+}

package/src/router/index.ts

@@ -0,0 +1,41 @@
+/**
+ * `@genesislcap/foundation-react-utils/router`
+ *
+ * Reusable `react-router-dom` primitives for Genesis Foundation React apps, so
+ * the app-shell routing logic doesn't have to be reimplemented per app.
+ *
+ * Exposed as a subpath (`/router`) rather than from the package root so that
+ * consumers which don't route (and don't depend on `react-router-dom`) are
+ * unaffected.
+ *
+ * Key exports:
+ * - `ProtectedRoute` / `createProtectedRoute` — auth + permission gate that
+ *   stashes the full origin location (incl. `search` + `hash`) for post-login
+ *   restore, and redirects to a not-permitted path when authorized-but-blocked.
+ * - `buildPostLoginRedirect` — rebuild the return URL preserving query + hash.
+ * - `readInitialParam` / `createComponentRegistry` / `SingleComponentOutlet` —
+ *   render a single registered component full-screen from a `?param=<name>`
+ *   deep-link captured before the shell strips the query string.
+ * - `renderAppRoutes` — build the app's `<Routes>` from a declarative route
+ *   table (guarding, layout nesting, redirects, not-found, single-component).
+ * - `mergePbcRoutes` — merge static routes with shell/PBC routes into one table.
+ */
+
+export { ProtectedRoute, createProtectedRoute } from './protected-route';
+export type {
+  ProtectedRouteProps,
+  BoundProtectedRouteProps,
+  CreateProtectedRouteOptions,
+} from './protected-route';
+export { buildPostLoginRedirect } from './post-login-redirect';
+export type { RedirectableLocationState } from './post-login-redirect';
+export {
+  readInitialParam,
+  createComponentRegistry,
+  SingleComponentOutlet,
+} from './single-component';
+export type { ComponentRegistry, SingleComponentOutletProps } from './single-component';
+export { renderAppRoutes } from './app-routes';
+export type { AppRouteConfig, RouteRedirect, RenderAppRoutesOptions } from './app-routes';
+export { mergePbcRoutes } from './pbc-routes';
+export type { PbcRouteInput, MergePbcRoutesOptions } from './pbc-routes';

package/src/router/pbc-routes.ts

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react';
+import type { AppRouteConfig } from './app-routes';
+
+/**
+ * Minimal shape of a PBC route as provided by the shell (e.g. `getApp().routes`).
+ * Kept as an input type — rather than importing `foundation-shell` — so this
+ * helper stays dependency-free and the `/router` subpath doesn't pull the shell
+ * into apps that don't use PBCs.
+ */
+export interface PbcRouteInput {
+  path: string;
+  title?: string;
+  /** The PBC element (module/loader) the container will mount. */
+  element?: unknown;
+  /** Explicit custom-element tag, if the container shouldn't derive one. */
+  elementTag?: string;
+  /** Nav items contributed by this PBC. */
+  navItems?: unknown;
+  /** Extra per-route settings (e.g. `permissionCode`), spread into `data`. */
+  settings?: Record<string, unknown>;
+}
+
+/**
+ * Options for {@link mergePbcRoutes}.
+ */
+export interface MergePbcRoutesOptions {
+  /** Render the element for a PBC route (typically `() => <PBCContainer />`). */
+  renderPbc: (pbc: PbcRouteInput) => ReactNode;
+}
+
+/**
+ * Merge a static route table with PBC routes (e.g. from `getApp().routes`) into
+ * one {@link AppRouteConfig} array. PBC routes are guarded, in-layout, and carry
+ * their element/tag + navItems through `data` so downstream consumers (a PBC
+ * container, nav-item derivation) can read them — matching the `data` shape the
+ * hand-rolled version produced.
+ */
+export function mergePbcRoutes(
+  staticRoutes: AppRouteConfig[],
+  pbcRoutes: PbcRouteInput[],
+  { renderPbc }: MergePbcRoutesOptions,
+): AppRouteConfig[] {
+  const mapped: AppRouteConfig[] = pbcRoutes.map((pbc) => ({
+    path: `/${pbc.path}`,
+    element: renderPbc(pbc),
+    permissionCode: pbc.settings?.permissionCode as string | undefined,
+    data: {
+      ...pbc.settings,
+      pbcElement: pbc.element,
+      pbcElementTag: pbc.elementTag,
+      navItems: pbc.navItems,
+    },
+  }));
+
+  return [...staticRoutes, ...mapped];
+}

package/src/router/post-login-redirect.ts

@@ -0,0 +1,29 @@
+/**
+ * Shape of the router location `state` that a route guard stashes before
+ * redirecting to login. Structural, so it works with `react-router-dom`'s
+ * `Location` without importing it here.
+ */
+export interface RedirectableLocationState {
+  from?: {
+    pathname: string;
+    search?: string;
+    hash?: string;
+  };
+}
+
+/**
+ * Build the post-login redirect target from a router location's `state.from`,
+ * preserving the query string and hash so deep-link params (e.g.
+ * `?component=<name>`) survive the login bounce. Falls back to `defaultPath`
+ * when there is no stashed origin.
+ *
+ * @param location - The current router location (needs only `state.from`).
+ * @param defaultPath - Where to land when nothing was stashed. Defaults to `/`.
+ */
+export function buildPostLoginRedirect(
+  location: { state?: RedirectableLocationState | null },
+  defaultPath = '/',
+): string {
+  const from = location.state?.from;
+  return from ? `${from.pathname}${from.search ?? ''}${from.hash ?? ''}` : defaultPath;
+}