@genesislcap/foundation-react-utils 14.481.2-alpha-829ad82.0 → 14.482.1-FUI-2575.1

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

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

package/src/index.ts

@@ -7,10 +7,21 @@
  * - `createReactRenderer` — wraps a React component as a `RendererEntry` for use with
  *   `foundation-forms` `additionalRenderers`. Use this instead of writing raw FAST templates
  *   when your custom form renderer is authored in React/JSX.
+ * - `createGridProCellRenderer` — wraps a React component as an AG Grid cell renderer
+ *   component class for use with `grid-pro` (register via `gridOptions.components` or the
+ *   grid's `gridComponents` property).
  * - `reactFactory` / `reactFactoryWithProvider` — mount React component trees into
  *   Genesis Foundation layout regions.
  */
 
 export { reactFactory, reactFactoryWithProvider } from './react-layout-factory';
 export { createReactRenderer } from './create-react-renderer';
+export { createGridProCellRenderer } from './create-grid-pro-cell-renderer';
+export { createGridProCellPortals } from './create-grid-pro-cell-portals';
+export type { GridProCellPortals } from './create-grid-pro-cell-portals';
+export type {
+  GridProCellRendererOptions,
+  GridProCellRendererProps,
+  GridProReactCellRenderer,
+} from './create-grid-pro-cell-renderer';
 export type { RendererControlProps } from '@genesislcap/foundation-forms';