@genesislcap/foundation-react-utils 14.481.2-alpha-829ad82.0 → 14.482.0

package/dist/foundation-react-utils.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentFactory } from '@genesislcap/foundation-layout';
-import type { ComponentType } from 'react';
+import { ComponentType } from 'react';
 import { JsonFormsState } from '@jsonforms/core';
 import { OwnPropsOfControl } from '@jsonforms/core';
 import { RankedTester } from '@jsonforms/core';
@@ -8,6 +8,110 @@ import { RendererControlProps } from '@genesislcap/foundation-forms';
 import { RendererEntry } from '@genesislcap/foundation-forms';
 import { StatePropsOfControl } from '@jsonforms/core';
 
+/**
+ * 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 declare function createGridProCellPortals(): GridProCellPortals;
+
+/**
+ * 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 declare function createGridProCellRenderer<P extends GridProCellRendererProps = GridProCellRendererProps>(Component: ComponentType<P>, options?: GridProCellRendererOptions): new () => GridProReactCellRenderer;
+
 /**
  * Converts a React component into a `RendererEntry` for use with `foundation-form`'s
  * `additionalRenderers` property.
@@ -86,6 +190,124 @@ export declare function createReactRenderer(Component: ComponentType<RendererCon
     wrapWithControlWrapper?: boolean;
 }): RendererEntry;
 
+/**
+ * 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 declare 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;
+}
+
+/**
+ * Options for {@link createGridProCellRenderer}.
+ *
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * The subset of AG Grid's `ICellRendererComp` contract implemented by the wrapper class
+ * returned from {@link createGridProCellRenderer}.
+ *
+ * @public
+ */
+export declare interface GridProReactCellRenderer {
+    init(params: GridProCellRendererProps): void;
+    getGui(): HTMLElement;
+    refresh(params: GridProCellRendererProps): boolean;
+    destroy(): void;
+}
+
 /**
  * Creates a factory function for rendering React components in layout items.
  *

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../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"],"version":"5.9.2"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-react-utils",
   "description": "Genesis Foundation React Utils",
-  "version": "14.481.2-alpha-829ad82.0",
+  "version": "14.482.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -29,23 +29,23 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/genx": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/rollup-builder": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/ts-builder": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/uvu-playwright-builder": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/vite-builder": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/webpack-builder": "14.481.2-alpha-829ad82.0"
+    "@genesislcap/foundation-testing": "14.482.0",
+    "@genesislcap/genx": "14.482.0",
+    "@genesislcap/rollup-builder": "14.482.0",
+    "@genesislcap/ts-builder": "14.482.0",
+    "@genesislcap/uvu-playwright-builder": "14.482.0",
+    "@genesislcap/vite-builder": "14.482.0",
+    "@genesislcap/webpack-builder": "14.482.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-forms": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/foundation-layout": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/foundation-logger": "14.481.2-alpha-829ad82.0",
-    "@genesislcap/web-core": "14.481.2-alpha-829ad82.0",
+    "@genesislcap/foundation-forms": "14.482.0",
+    "@genesislcap/foundation-layout": "14.482.0",
+    "@genesislcap/foundation-logger": "14.482.0",
+    "@genesislcap/web-core": "14.482.0",
     "@jsonforms/core": "^3.2.1",
     "@r2wc/react-to-web-component": "^2.0.2"
   },
@@ -58,5 +58,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "074779b7bd0998af5157821fa5739ecce0ac36a8"
+  "gitHead": "176fdab04821da415454fcdbc124f7fabac07aa7"
 }

package/src/create-grid-pro-cell-portals.tsx

@@ -0,0 +1,216 @@
+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);
+    },
+  };
+}