@genesislcap/foundation-react-utils 14.481.1 → 14.482.0

package/dist/esm/create-grid-pro-cell-renderer.js

@@ -0,0 +1,141 @@
+import { createLogger } from '@genesislcap/foundation-logger';
+import { createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+const logger = createLogger('foundation-react-utils');
+/**
+ * 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(Component, options = {}) {
+    const fillCell = options.fillCell !== false;
+    const portals = options.portals;
+    return class ReactCellRenderer {
+        constructor() {
+            this.root = null;
+            this.portalId = null;
+        }
+        init(params) {
+            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));
+            });
+        }
+        getGui() {
+            return this.container;
+        }
+        refresh(params) {
+            var _a;
+            if (portals) {
+                if (this.portalId != null) {
+                    portals.update(this.portalId, params);
+                }
+                return true;
+            }
+            (_a = this.root) === null || _a === void 0 ? void 0 : _a.render(createElement(Component, params));
+            return true;
+        }
+        destroy() {
+            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/dist/esm/index.js

@@ -7,8 +7,13 @@
  * - `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';