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

package/src/router/protected-route.tsx

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react';
+import { Navigate, useLocation } from 'react-router-dom';
+
+/**
+ * Props for {@link ProtectedRoute}.
+ */
+export interface ProtectedRouteProps {
+  /** Whether the current user is authenticated. */
+  isAuthenticated: boolean;
+  /**
+   * Whether the current user may view this route. When `false` (and
+   * authenticated), redirects to `notPermittedPath` instead of rendering.
+   * Defaults to `true`.
+   */
+  hasPermission?: boolean;
+  /** Path to redirect to when unauthenticated. Defaults to `/login`. */
+  loginPath?: string;
+  /** Path to redirect to when authenticated but not permitted. Defaults to `/not-permitted`. */
+  notPermittedPath?: string;
+  children: ReactNode;
+}
+
+/**
+ * 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,
+}: ProtectedRouteProps) {
+  const location = useLocation();
+
+  if (!isAuthenticated) {
+    return <Navigate to={loginPath} state={{ from: location }} replace />;
+  }
+
+  if (!hasPermission) {
+    return <Navigate to={notPermittedPath} replace />;
+  }
+
+  return <>{children}</>;
+}
+
+/**
+ * Props of the component returned by {@link createProtectedRoute}. `permissionCode`
+ * is forwarded to the bound `hasPermission` check (e.g. by {@link renderAppRoutes}).
+ */
+export interface BoundProtectedRouteProps {
+  children: ReactNode;
+  /** Route permission code handed to the bound `hasPermission` check. */
+  permissionCode?: string;
+}
+
+/**
+ * Options for {@link createProtectedRoute}.
+ */
+export interface CreateProtectedRouteOptions {
+  /**
+   * Called at render time to determine auth state. Kept as a function (not a
+   * boolean) so it is re-evaluated on every render and the util stays free of
+   * any specific auth dependency.
+   */
+  getIsAuthenticated: () => boolean;
+  /**
+   * Optional per-route permission check, called at render time with the route's
+   * `permissionCode`. Absent → every authenticated user is permitted.
+   */
+  hasPermission?: (permissionCode: string | undefined) => boolean;
+  /** Path to redirect to when unauthenticated. Defaults to `/login`. */
+  loginPath?: string;
+  /** Path to redirect to when authenticated but not permitted. Defaults to `/not-permitted`. */
+  notPermittedPath?: string;
+}
+
+/**
+ * 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,
+}: CreateProtectedRouteOptions) {
+  return function BoundProtectedRoute({ children, permissionCode }: BoundProtectedRouteProps) {
+    return (
+      <ProtectedRoute
+        isAuthenticated={getIsAuthenticated()}
+        hasPermission={hasPermission ? hasPermission(permissionCode) : true}
+        loginPath={loginPath}
+        notPermittedPath={notPermittedPath}
+      >
+        {children}
+      </ProtectedRoute>
+    );
+  };
+}

package/src/router/router.test.ts

@@ -0,0 +1,107 @@
+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`', () => {
+  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(merged[0].data?.pbcElement, el);
+  assert.is(merged[0].data?.pbcElementTag, 'reporting-app');
+  assert.equal(merged[0].data?.navItems, navItems);
+  assert.is(merged[0].data?.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/src/router/single-component.tsx

@@ -0,0 +1,94 @@
+import type { ComponentType, ReactNode } from 'react';
+
+/**
+ * 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: string): string | null {
+  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: string): string => name.toLowerCase().replace(/[-_\s]/g, '');
+
+/**
+ * A name → component registry with tolerant lookup. Create one with
+ * {@link createComponentRegistry}.
+ */
+export interface ComponentRegistry {
+  /** The underlying name → component map. */
+  entries: Record<string, ComponentType<any>>;
+  /** All registered names, for help/error output. */
+  available(): string[];
+  /** Resolve a registered component by name, tolerant of case and separators. */
+  resolve(name: string | null | undefined): ComponentType<any> | undefined;
+}
+
+/**
+ * Create a name → component registry whose `resolve` is case- and
+ * separator-insensitive (`LimitDistributionChart` === `limit-distribution-chart`).
+ */
+export function createComponentRegistry(
+  entries: Record<string, ComponentType<any>>,
+): ComponentRegistry {
+  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;
+    },
+  };
+}
+
+/**
+ * Props for {@link SingleComponentOutlet}.
+ */
+export interface SingleComponentOutletProps {
+  /** The requested component name (typically captured via {@link readInitialParam}). */
+  name: string | null | undefined;
+  /** Registry to resolve the name against. */
+  registry: ComponentRegistry;
+  /**
+   * Render when no component matches. Defaults to a plain, unstyled
+   * "Unknown component" message; pass your own to theme it.
+   */
+  renderUnknown?: (name: string | null | undefined, available: string[]) => ReactNode;
+}
+
+const defaultUnknown = (name: string | null | undefined, available: string[]): ReactNode => (
+  <div role="alert" style={{ padding: 16 }}>
+    {`Unknown component "${name ?? ''}". Available: ${available.join(', ')}`}
+  </div>
+);
+
+/**
+ * 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,
+}: SingleComponentOutletProps) {
+  const Component = registry.resolve(name);
+  return <>{Component ? <Component /> : renderUnknown(name, registry.available())}</>;
+}