@genesislcap/foundation-react-utils 15.18.0 → 15.19.0-DCD-4786.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-react-utils",
   "description": "Genesis Foundation React Utils",
-  "version": "15.18.0",
+  "version": "15.19.0-DCD-4786.3",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -47,13 +47,13 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.18.0",
-    "@genesislcap/genx": "15.18.0",
-    "@genesislcap/rollup-builder": "15.18.0",
-    "@genesislcap/ts-builder": "15.18.0",
-    "@genesislcap/uvu-playwright-builder": "15.18.0",
-    "@genesislcap/vite-builder": "15.18.0",
-    "@genesislcap/webpack-builder": "15.18.0",
+    "@genesislcap/foundation-testing": "15.19.0-DCD-4786.3",
+    "@genesislcap/genx": "15.19.0-DCD-4786.3",
+    "@genesislcap/rollup-builder": "15.19.0-DCD-4786.3",
+    "@genesislcap/ts-builder": "15.19.0-DCD-4786.3",
+    "@genesislcap/uvu-playwright-builder": "15.19.0-DCD-4786.3",
+    "@genesislcap/vite-builder": "15.19.0-DCD-4786.3",
+    "@genesislcap/webpack-builder": "15.19.0-DCD-4786.3",
     "react-router-dom": "^7.1.3"
   },
   "peerDependencies": {
@@ -67,10 +67,10 @@
     }
   },
   "dependencies": {
-    "@genesislcap/foundation-forms": "15.18.0",
-    "@genesislcap/foundation-layout": "15.18.0",
-    "@genesislcap/foundation-logger": "15.18.0",
-    "@genesislcap/web-core": "15.18.0",
+    "@genesislcap/foundation-forms": "15.19.0-DCD-4786.3",
+    "@genesislcap/foundation-layout": "15.19.0-DCD-4786.3",
+    "@genesislcap/foundation-logger": "15.19.0-DCD-4786.3",
+    "@genesislcap/web-core": "15.19.0-DCD-4786.3",
     "@jsonforms/core": "^3.2.1",
     "@r2wc/react-to-web-component": "^2.0.2"
   },
@@ -82,6 +82,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "customElements": "dist/custom-elements.json",
-  "gitHead": "a92013873774dbc7f67a32d37994f10777f86383"
+  "customElements": "dist/custom-elements.json"
 }

package/api-extractor.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "extends": "../../../api-extractor.json"
-}

package/dist/dts/router/router.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=router.test.d.ts.map

package/dist/dts/router/router.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"router.test.d.ts","sourceRoot":"","sources":["../../../src/router/router.test.ts"],"names":[],"mappings":""}

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

@@ -1,82 +0,0 @@
-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/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"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/src/create-grid-pro-cell-portals.tsx

@@ -1,216 +0,0 @@
-import { createLogger } from '@genesislcap/foundation-logger';
-import {
-  Component as ReactClassComponent,
-  memo,
-  useEffect,
-  useSyncExternalStore,
-  type ComponentType,
-  type ReactNode,
-} from 'react';
-import { createPortal, flushSync } from 'react-dom';
-
-const logger = createLogger('foundation-react-utils');
-
-/**
- * A single mounted cell tracked by a {@link GridProCellPortals} manager.
- * @internal
- */
-interface CellPortalEntry {
-  id: number;
-  container: HTMLElement;
-  Component: ComponentType<any>;
-  params: any;
-}
-
-/**
- * Shared portal manager for Grid Pro React cell renderers.
- *
- * Created with {@link createGridProCellPortals}. Render the {@link GridProCellPortals.Portals}
- * component exactly once inside your React tree — cells rendered through this manager become
- * part of that tree, so they inherit React Context (Redux providers, theme, router, etc.) from
- * wherever `Portals` sits. Pass the manager to {@link createGridProCellRenderer} via the
- * `portals` option to opt a renderer into portal mode.
- *
- * @public
- */
-export interface GridProCellPortals {
-  /**
-   * Host component for all cells rendered through this manager. Render it exactly once,
-   * inside every provider the cell renderers should inherit, and keep it mounted for as
-   * long as the grid is on screen — unmounting it blanks all portal-rendered cells.
-   */
-  Portals: ComponentType;
-  /**
-   * Mounts a component into a cell container and returns the entry id.
-   * Called by the cell renderer wrapper — not intended for direct use.
-   * @internal
-   */
-  mount(container: HTMLElement, Component: ComponentType<any>, params: any): number;
-  /**
-   * Re-renders a mounted cell with new params.
-   * Called by the cell renderer wrapper — not intended for direct use.
-   * @internal
-   */
-  update(id: number, params: any): void;
-  /**
-   * Removes a mounted cell.
-   * Called by the cell renderer wrapper — not intended for direct use.
-   * @internal
-   */
-  remove(id: number): void;
-}
-
-/**
- * Error boundary around each portal-rendered cell. A shared React tree means one throwing
- * renderer would otherwise unmount every portal cell in the grid — this contains the blast
- * radius to the failing cell (which renders empty).
- * @internal
- */
-class CellPortalErrorBoundary extends ReactClassComponent<
-  { children: ReactNode },
-  { failed: boolean }
-> {
-  public override state = { failed: false };
-
-  public static getDerivedStateFromError() {
-    return { failed: true };
-  }
-
-  public override componentDidCatch(error: unknown) {
-    logger.error('Grid Pro portal cell renderer threw during render:', error);
-  }
-
-  public override render() {
-    return this.state.failed ? null : this.props.children;
-  }
-}
-
-/**
- * One portal per cell. Memoised on the entry object — `update()` swaps the entry, so only
- * the changed cell reconciles when the manager re-renders.
- * @internal
- */
-const CellPortal = memo(function GridProCellPortal({ entry }: { entry: CellPortalEntry }) {
-  return createPortal(
-    <CellPortalErrorBoundary>
-      <entry.Component {...entry.params} />
-    </CellPortalErrorBoundary>,
-    entry.container,
-  );
-});
-
-/**
- * Creates a {@link GridProCellPortals} manager: a single React root shared by every cell
- * renderer registered with it, with each cell rendered into its grid cell via a portal.
- *
- * Use this instead of the default one-root-per-cell mode when cell renderers need to
- * inherit React Context from the application tree (Redux, theme, router, query clients...)
- * — portal-rendered cells live in the tree where `Portals` is rendered, so context updates
- * propagate into visible cells like any other React state.
- *
- * @example
- * ```tsx
- * const cellPortals = createGridProCellPortals();
- *
- * const gridOptions = {
- *   components: {
- *     priceCell: createGridProCellRenderer(PriceCell, { portals: cellPortals }),
- *   },
- *   columnDefs: [{ field: 'price', cellRenderer: 'priceCell' }],
- * };
- *
- * function Page() {
- *   return (
- *     <SomeProvider>
- *       <cellPortals.Portals />
- *       <RapidGridPro gridOptions={gridOptions} />
- *     </SomeProvider>
- *   );
- * }
- * ```
- *
- * @remarks
- * Trade-offs versus the default per-cell roots: all cells registered with one manager share
- * a React tree, so a renderer that throws is contained by a per-cell error boundary (the
- * failing cell renders empty rather than crashing the rest), and unmounting `Portals` while
- * the grid is alive blanks every portal-rendered cell. Cell mounts are committed
- * synchronously (so AG Grid measures real content), which re-renders the manager once per
- * created cell — the per-cell portals are memoised, keeping that cheap at grid-pro's
- * virtualised cell counts.
- *
- * @public
- */
-export function createGridProCellPortals(): GridProCellPortals {
-  let entries: readonly CellPortalEntry[] = [];
-  let nextId = 0;
-  let portalsMounted = false;
-  const listeners = new Set<() => void>();
-
-  const emit = () => {
-    listeners.forEach((listener) => listener());
-  };
-
-  /**
-   * Commits a store change synchronously so the cell content exists in the DOM before
-   * AG Grid measures the container (autoHeight, autoSizeColumns, sizeColumnsToFit).
-   * Mount runs from AG Grid's own (non-React) call stack, so flushing is safe; if it
-   * ever runs inside a host React render, React warns and defers the flush instead.
-   */
-  const emitSync = () => {
-    if (!portalsMounted) {
-      emit();
-      return;
-    }
-    flushSync(emit);
-  };
-
-  const subscribe = (listener: () => void) => {
-    listeners.add(listener);
-    return () => {
-      listeners.delete(listener);
-    };
-  };
-  const getSnapshot = () => entries;
-
-  const Portals: ComponentType = () => {
-    const snapshot = useSyncExternalStore(subscribe, getSnapshot);
-    useEffect(() => {
-      portalsMounted = true;
-      return () => {
-        portalsMounted = false;
-      };
-    }, []);
-    return (
-      <>
-        {snapshot.map((entry) => (
-          <CellPortal key={entry.id} entry={entry} />
-        ))}
-      </>
-    );
-  };
-
-  return {
-    Portals,
-    mount(container, Component, params) {
-      nextId += 1;
-      const id = nextId;
-      entries = [...entries, { id, container, Component, params }];
-      emitSync();
-      return id;
-    },
-    update(id, params) {
-      entries = entries.map((entry) => (entry.id === id ? { ...entry, params } : entry));
-      // Async on purpose: refresh() has already returned true and AG Grid does not
-      // re-measure on refresh, so there is nothing to commit synchronously for.
-      emit();
-    },
-    remove(id) {
-      entries = entries.filter((entry) => entry.id !== id);
-      // AG Grid can destroy cells synchronously while React is rendering (e.g. React
-      // Router unmounting the page hosting the grid); notifying subscribers there would
-      // set state mid-render, so defer with a macrotask — the container is already
-      // detached by AG Grid, so the portal lingering one tick is invisible.
-      setTimeout(emit);
-    },
-  };
-}

package/src/create-grid-pro-cell-renderer.ts

@@ -1,235 +0,0 @@
-import { createLogger } from '@genesislcap/foundation-logger';
-import { createElement, type ComponentType } from 'react';
-import { flushSync } from 'react-dom';
-import { createRoot, type Root } from 'react-dom/client';
-import type { GridProCellPortals } from './create-grid-pro-cell-portals';
-
-const logger = createLogger('foundation-react-utils');
-
-/**
- * Props passed to a React component used as a Grid Pro cell renderer.
- *
- * This is a structural subset of AG Grid's `ICellRendererParams` — the full params object
- * (including any custom `cellRendererParams` from the column definition) is spread onto the
- * component as props on every render, so anything available on `ICellRendererParams` is
- * available here. Declared locally to avoid coupling this package to a specific
- * `ag-grid-community` version.
- *
- * @public
- */
-export interface GridProCellRendererProps<TData = any, TValue = any> {
-  /** The cell value. */
-  value: TValue;
-  /** Value formatted by the column's value formatter, if any. */
-  valueFormatted?: string | null;
-  /** The full row data. */
-  data: TData;
-  /** The AG Grid row node. */
-  node: any;
-  /** The AG Grid api. */
-  api: any;
-  /** The row index of the cell. */
-  rowIndex: number;
-  /** The grid context object, as supplied via `gridOptions.context`. */
-  context?: any;
-  /** The column this cell belongs to. */
-  column?: any;
-  /** The column definition. */
-  colDef?: any;
-  /** Custom params from `cellRendererParams` and any other AG Grid params. */
-  [key: string]: any;
-}
-
-/**
- * Options for {@link createGridProCellRenderer}.
- *
- * @public
- */
-export interface GridProCellRendererOptions {
-  /**
-   * When true (the default), the cell container is styled as a full-size flex row
-   * (`display: flex; align-items: center; height: 100%; width: 100%`) so content is
-   * vertically centred like grid-pro's built-in renderers.
-   *
-   * Set to false to leave the container unstyled and let the cell's own layout apply.
-   * Do this when the forced flex/height layout gets in the way, e.g.:
-   * - `autoHeight`/`wrapText` columns — `height: 100%` is circular when the row height
-   *   derives from the content, so the cell can collapse instead of growing;
-   * - right-aligned numeric cells relying on `text-align` (a flex item packs to the start);
-   * - content using `text-overflow: ellipsis` (a flex item won't truncate without
-   *   `min-width: 0`).
-   */
-  fillCell?: boolean;
-
-  /**
-   * Render cells through a shared {@link GridProCellPortals} manager instead of giving each
-   * cell its own React root. Portal-rendered cells become part of the React tree where the
-   * manager's `Portals` component is rendered, so they inherit React Context (Redux, theme,
-   * router, etc.) from the application — the main limitation of the default mode.
-   *
-   * Create one with `createGridProCellPortals()` and render `<manager.Portals />` once,
-   * inside the providers the cells should see. When omitted (the default), each cell gets
-   * its own isolated root.
-   */
-  portals?: GridProCellPortals;
-}
-
-/**
- * The subset of AG Grid's `ICellRendererComp` contract implemented by the wrapper class
- * returned from {@link createGridProCellRenderer}.
- *
- * @public
- */
-export interface GridProReactCellRenderer {
-  init(params: GridProCellRendererProps): void;
-  getGui(): HTMLElement;
-  refresh(params: GridProCellRendererProps): boolean;
-  destroy(): void;
-}
-
-/**
- * Wraps a React component as an AG Grid cell renderer component class for use with
- * `grid-pro` / `grid-pro-beta` (`<foundation-grid-pro>` / `<rapid-grid-pro>`).
- *
- * Grid Pro is a framework-agnostic Web Component, so AG Grid inside it only understands
- * plain-JS component classes. This helper bridges the gap: it returns a class implementing
- * `ICellRendererComp` that mounts the React component into the cell with its own React root,
- * re-renders it on `refresh` (so value changes and cell flashing keep working without
- * remounting), and unmounts it when the cell is destroyed.
- *
- * The component receives the full AG Grid `ICellRendererParams` object as props — including
- * `value`, `data`, `node`, `api` and anything supplied via the column's `cellRendererParams`.
- * Hooks and local state inside the component work as normal.
- *
- * Note on React Context/Redux: by default each cell is rendered into its own independent
- * React root, so renderers do NOT inherit contexts (Redux providers, theme context, React
- * Router, etc.) from the application tree hosting the grid. Either pass data/callbacks
- * explicitly via `cellRendererParams`, or opt into portal mode with the `portals` option
- * (see {@link GridProCellRendererOptions.portals} and `createGridProCellPortals`) — portal
- * cells share the application tree and inherit its contexts.
- *
- * Note on `key`: props are passed by spreading the AG Grid params object, and React reserves
- * `key` — a `cellRendererParams` entry named `key` is consumed as the element key and never
- * reaches the component, so avoid that name. (`ref` is fine: React 19 forwards it to function
- * components as a regular prop.)
- *
- * Note on styling: cells render inside grid-pro's shadow root, so document-level stylesheets
- * (CSS files imported by your app/page) do NOT reach the rendered component. Style renderers
- * with inline styles or CSS-in-JS. Design-system tokens remain usable either way — CSS custom
- * properties inherit across shadow boundaries (e.g. `color: 'var(--accent-fill-rest)'`).
- *
- * @example
- * ```tsx
- * import { createGridProCellRenderer, type GridProCellRendererProps } from '@genesislcap/foundation-react-utils';
- *
- * function PriceCell({ value }: GridProCellRendererProps) {
- *   return <span style={{ color: value >= 0 ? 'green' : 'red' }}>{value}</span>;
- * }
- *
- * const gridOptions = {
- *   components: {
- *     priceCell: createGridProCellRenderer(PriceCell),
- *   },
- *   columnDefs: [
- *     { field: 'price', cellRenderer: 'priceCell' },
- *   ],
- * };
- *
- * // <rapid-grid-pro gridOptions={gridOptions} /> — or register via the grid's
- * // `gridComponents` property to make the renderer available across all columns.
- * ```
- *
- * @param Component - The React component to render inside the cell.
- * @param options - Optional {@link GridProCellRendererOptions} to tune the wrapper behaviour.
- * @returns A cell renderer component class registrable via `gridOptions.components`,
- * the grid's `gridComponents` property, or directly as a column's `cellRenderer`.
- *
- * @public
- */
-export function createGridProCellRenderer<
-  P extends GridProCellRendererProps = GridProCellRendererProps,
->(
-  Component: ComponentType<P>,
-  options: GridProCellRendererOptions = {},
-): new () => GridProReactCellRenderer {
-  const fillCell = options.fillCell !== false;
-  const portals = options.portals;
-
-  return class ReactCellRenderer implements GridProReactCellRenderer {
-    private container!: HTMLElement;
-    private root: Root | null = null;
-    private portalId: number | null = null;
-
-    public init(params: P): void {
-      this.container = document.createElement('div');
-      if (fillCell) {
-        // Fill the cell so the React content can align itself like native renderers do.
-        // See GridProCellRendererOptions.fillCell for when to opt out.
-        this.container.style.display = 'flex';
-        this.container.style.alignItems = 'center';
-        this.container.style.height = '100%';
-        this.container.style.width = '100%';
-      }
-
-      if (portals) {
-        // Portal mode: the shared manager renders the component into this container as
-        // part of the application tree (mount commits synchronously so AG Grid measures
-        // real content — same reasoning as the flushSync below).
-        this.portalId = portals.mount(this.container, Component, params);
-        return;
-      }
-
-      this.root = createRoot(this.container);
-      // React 19 concurrent roots only *schedule* render(), but AG Grid inserts and can
-      // synchronously measure the container as soon as init/getGui return (autoHeight,
-      // autoSizeColumns, sizeColumnsToFit) — flush the first render so the grid measures
-      // real content instead of an empty div (also avoids a one-frame empty flash).
-      // Cell init runs from AG Grid's own (non-React) call stack, so flushing is safe
-      // here; if it ever runs inside a host React render, React warns and falls back to
-      // a deferred flush rather than breaking. refresh() intentionally stays async.
-      flushSync(() => {
-        this.root!.render(createElement(Component, params));
-      });
-    }
-
-    public getGui(): HTMLElement {
-      return this.container;
-    }
-
-    public refresh(params: P): boolean {
-      if (portals) {
-        if (this.portalId != null) {
-          portals.update(this.portalId, params);
-        }
-        return true;
-      }
-      this.root?.render(createElement(Component, params));
-      return true;
-    }
-
-    public destroy(): void {
-      if (portals) {
-        if (this.portalId != null) {
-          portals.remove(this.portalId);
-          this.portalId = null;
-        }
-        return;
-      }
-
-      const root = this.root;
-      this.root = null;
-      if (root) {
-        // AG Grid can destroy cells synchronously while React is rendering (e.g. React Router
-        // unmounting the page that hosts the grid). Unmounting a root mid-render is not allowed,
-        // and microtasks still run inside the render cycle — defer with a macrotask instead.
-        setTimeout(() => {
-          try {
-            root.unmount();
-          } catch (error) {
-            logger.error('Error unmounting React root in Grid Pro cell renderer:', error);
-          }
-        });
-      }
-    }
-  };
-}