@genesislcap/foundation-react-utils 15.19.0 → 15.19.1

package/src/create-react-renderer.ts

@@ -1,148 +0,0 @@
-import {
-  controlWrapperTemplate,
-  type RendererControlProps,
-  type RendererEntry,
-} from '@genesislcap/foundation-forms';
-import { html } from '@genesislcap/web-core';
-import {
-  mapStateToControlProps,
-  type JsonFormsState,
-  type OwnPropsOfControl,
-  type RankedTester,
-  type StatePropsOfControl,
-} from '@jsonforms/core';
-import r2wc from '@r2wc/react-to-web-component';
-import type { ComponentType } from 'react';
-
-/**
- * Converts a React component into a `RendererEntry` for use with `foundation-form`'s
- * `additionalRenderers` property.
- *
- * The component is registered as a custom element via `r2wc` and wrapped in a FAST
- * `html` template so it integrates with the JSON Forms dispatch renderer.
- *
- * **Important — use platform web components for inputs, not native HTML elements.**
- * The React component runs inside an `r2wc` custom element inside a FAST template,
- * creating a three-layer shadow DOM boundary. React's synthetic event system does not
- * cross shadow boundaries, so `onChange` on a plain `<input>` will never fire.
- * Use `rapid-number-field`, `rapid-text-field`, etc. and attach listeners via
- * `addEventListener` in a `useEffect` instead.
- *
- * @example
- * ```tsx
- * import { useEffect, useRef } from 'react';
- * import { createReactRenderer, type RendererControlProps } from '@genesislcap/foundation-react-utils';
- * import { isNumberControl, rankWith } from '@jsonforms/core';
- *
- * function PriceRenderer({ data, path, enabled, handleChange }: RendererControlProps) {
- *   const ref = useRef<HTMLElement>(null);
- *
- *   useEffect(() => {
- *     const el = ref.current as any;
- *     if (!el) return;
- *     const onChange = (e: CustomEvent) => {
- *       const val = (e.target as any).value;
- *       handleChange(path, val === '' ? undefined : Number(val));
- *     };
- *     el.addEventListener('change', onChange);
- *     return () => el.removeEventListener('change', onChange);
- *   }, [path, handleChange]);
- *
- *   return <rapid-number-field ref={ref} value={data ?? ''} disabled={!enabled || undefined} />;
- * }
- *
- * export const priceRendererEntry = createReactRenderer(PriceRenderer, {
- *   name: 'my-price-renderer',
- *   tester: rankWith(6, isNumberControl),
- * });
- *
- * // On the form element:
- * // form.additionalRenderers = [priceRendererEntry];
- * ```
- *
- * @public
- */
-export function createReactRenderer(
-  Component: ComponentType<RendererControlProps>,
-  options: {
-    /**
-     * The custom element tag name to register. Must be unique and contain a hyphen.
-     * e.g. 'my-price-renderer'
-     */
-    name: string;
-    /**
-     * RankedTester from @jsonforms/core — determines when this renderer applies.
-     * Use rankWith(rank, tester) — rank 5+ recommended to override built-ins.
-     */
-    tester: RankedTester;
-    /**
-     * Custom mapper if you need to transform state differently.
-     * Defaults to mapStateToControlProps from @jsonforms/core.
-     */
-    mapper?: (state: JsonFormsState, ownProps: OwnPropsOfControl) => StatePropsOfControl;
-    /**
-     * Whether to wrap the React component in the platform's control-wrapper template,
-     * which provides consistent label rendering, error display, and accessibility.
-     * Defaults to true. Set to false if your React component handles its own labels/errors.
-     *
-     * Note: if your component has layout conflicts with the wrapper's internal flex styles
-     * (e.g. a block-level combobox that shrinks to content width), you can target the
-     * wrapper's inner element directly in light DOM:
-     *
-     *   .foundation-control-wrapper { display: block; }
-     */
-    wrapWithControlWrapper?: boolean;
-  },
-): RendererEntry {
-  const WebComponent = r2wc(Component, {
-    props: {
-      data: 'json',
-      path: 'string',
-      label: 'string',
-      errors: 'string',
-      enabled: 'boolean',
-      required: 'boolean',
-      handleChange: 'method',
-      uischema: 'json',
-    },
-  });
-
-  if (!customElements.get(options.name)) {
-    customElements.define(options.name, WebComponent);
-  }
-
-  const { name } = options;
-  const useWrapper = options.wrapWithControlWrapper !== false;
-
-  const innerTemplate = (elementName: string) => html`
-    <${elementName}
-      :data=${(x: any) => x.control.data}
-      :path=${(x: any) => x.control.path}
-      :label=${(x: any) => x.control.label}
-      :errors=${(x: any) => x.control.errors}
-      :enabled=${(x: any) => x.control.enabled}
-      :required=${(x: any) => x.control.required}
-      :handleChange=${(x: any) => x.control.handleChange}
-      :uischema=${(x: any) => x.control.uischema}
-    ></${elementName}>
-  `;
-
-  const template = useWrapper
-    ? html`
-        <template>
-          ${controlWrapperTemplate({
-            prefix: 'zero',
-            innerTemplate: innerTemplate(name) as any,
-          })}
-        </template>
-      `
-    : html`
-        <template>${innerTemplate(name)}</template>
-      `;
-
-  return {
-    renderer: template,
-    tester: options.tester,
-    mapper: options.mapper ?? mapStateToControlProps,
-  };
-}

package/src/index.ts

@@ -1,27 +0,0 @@
-/**
- * @genesislcap/foundation-react-utils
- *
- * Utility functions and helpers for building React applications with Genesis Foundation.
- *
- * Key exports:
- * - `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';

package/src/react-layout-factory.tsx

@@ -1,81 +0,0 @@
-import type { ComponentFactory } from '@genesislcap/foundation-layout';
-import * as React from 'react';
-import { createRoot, Root } from 'react-dom/client';
-
-/**
- * Creates a factory function for rendering React components in layout items.
- *
- * @param Component - React component to render
- * @param props - Optional props to pass to the component
- * @returns ComponentFactory compatible with foundation-layout
- *
- * @example
- * ```tsx
- * <foundation-layout-item
- *   registration="my-component"
- *   title="My Component"
- *   factory={reactFactory(MyComponent, { someProp: 'value' })}
- * />
- * ```
- */
-export function reactFactory<P = {}>(
-  Component: React.ComponentType<P>,
-  props?: P,
-): ComponentFactory {
-  return (container: HTMLElement) => {
-    const root: Root = createRoot(container);
-    root.render(<Component {...(props || ({} as P))} />);
-
-    // Return cleanup function
-    return () => {
-      root.unmount();
-    };
-  };
-}
-
-/**
- * Creates a factory function that wraps a React component with a provider (e.g., Redux Provider, Context Provider).
- *
- * @param Component - React component to render
- * @param Wrapper - Wrapper component (e.g., Redux Provider, Context Provider)
- * @param wrapperProps - Props for the wrapper component
- * @param componentProps - Optional props for the component
- * @returns ComponentFactory compatible with foundation-layout
- *
- * @example
- * ```tsx
- * import { Provider } from 'react-redux';
- * import { store } from './store';
- *
- * <foundation-layout-item
- *   registration="my-component"
- *   title="My Component"
- *   factory={reactFactoryWithProvider(
- *     MyComponent,
- *     Provider,
- *     { store },
- *     { someProp: 'value' }
- *   )}
- * />
- * ```
- */
-export function reactFactoryWithProvider<CP = {}, WP = {}>(
-  Component: React.ComponentType<CP>,
-  Wrapper: React.ComponentType<WP & { children: React.ReactNode }>,
-  wrapperProps: WP,
-  componentProps?: CP,
-): ComponentFactory {
-  return (container: HTMLElement) => {
-    const root: Root = createRoot(container);
-    root.render(
-      <Wrapper {...wrapperProps}>
-        <Component {...(componentProps || ({} as CP))} />
-      </Wrapper>,
-    );
-
-    // Return cleanup function
-    return () => {
-      root.unmount();
-    };
-  };
-}

package/src/router/app-routes.tsx

@@ -1,141 +0,0 @@
-import type { ComponentType, ReactElement, ReactNode } from 'react';
-import { Navigate, Route, Routes } from 'react-router-dom';
-import type { BoundProtectedRouteProps } from './protected-route';
-
-/**
- * Declarative description of one app route. The `element` is rendered when the
- * path matches; guarding, layout nesting, and permission are derived from the
- * flags below so the app doesn't hand-write the `<Route>`/`<ProtectedRoute>`
- * boilerplate per route.
- */
-export interface AppRouteConfig {
-  path: string;
-  element: ReactNode;
-  /** Skip the auth guard (e.g. login, not-permitted). Default `false`. */
-  public?: boolean;
-  /** Render outside the shared layout. Default `false` (guarded routes sit in the layout). */
-  noLayout?: boolean;
-  /** Permission code handed to the guard's optional permission check. */
-  permissionCode?: string;
-  /**
-   * Nested child routes rendered inside this route's `element` (which must
-   * render an `<Outlet />`). Children use paths relative to this route and
-   * inherit its guard — they are rendered as plain routes, not re-guarded.
-   */
-  children?: AppRouteConfig[];
-  /** Arbitrary metadata preserved for other consumers (nav items, PBC info, ...). */
-  data?: Record<string, any>;
-}
-
-/** A simple `from → to` redirect. */
-export interface RouteRedirect {
-  from: string;
-  to: string;
-}
-
-/**
- * Options for {@link renderAppRoutes}.
- */
-export interface RenderAppRoutesOptions {
-  /** The full route table (static + any merged PBC routes). */
-  routes: AppRouteConfig[];
-  /**
-   * Guard component (typically from `createProtectedRoute`) wrapping every
-   * non-public route; receives each route's `permissionCode`.
-   */
-  ProtectedRoute: ComponentType<BoundProtectedRouteProps>;
-  /**
-   * Layout route element (rendering an `<Outlet />`) that wraps in-layout
-   * routes. Omit to render every route at the top level.
-   */
-  layout?: ReactElement;
-  /** `from → to` redirects rendered before the routes. */
-  redirects?: RouteRedirect[];
-  /** Element for unmatched paths (`*`). */
-  notFound?: ReactNode;
-  /**
-   * When `name` is truthy, short-circuit to single-component mode: render only
-   * the public routes (so login / session-restore still work) plus a catch-all
-   * rendering `element` behind the guard. See the single-component deep-link.
-   */
-  singleComponent?: { name: string | null | undefined; element: ReactNode };
-}
-
-const resolvePermissionCode = (route: AppRouteConfig): string | undefined =>
-  route.permissionCode ?? (route.data?.permissionCode as string | undefined);
-
-/**
- * Build the app's `<Routes>` tree from a declarative route table, applying the
- * auth guard, layout nesting, redirects, not-found, and the single-component
- * short-circuit — so a consuming app configures routes instead of hand-writing
- * repetitive `<Route element={<ProtectedRoute>…}>` markup.
- */
-export function renderAppRoutes({
-  routes,
-  ProtectedRoute,
-  layout,
-  redirects = [],
-  notFound,
-  singleComponent,
-}: RenderAppRoutesOptions): ReactElement {
-  const publicRoutes = routes.filter((r) => r.public);
-
-  // Single-component mode: keep public routes reachable (login / session
-  // restore) and gate everything else behind the guard rendering the component.
-  if (singleComponent?.name) {
-    return (
-      <Routes>
-        {publicRoutes.map((r) => (
-          <Route key={r.path} path={r.path} element={r.element} />
-        ))}
-        <Route path="*" element={<ProtectedRoute>{singleComponent.element}</ProtectedRoute>} />
-      </Routes>
-    );
-  }
-
-  const guarded = routes.filter((r) => !r.public);
-  const inLayout = guarded.filter((r) => !r.noLayout);
-  const topLevelGuarded = guarded.filter((r) => r.noLayout);
-
-  // Nested children render as plain relative routes inside the parent's
-  // `<Outlet />`; they inherit the parent's guard, so they are not re-wrapped.
-  const renderChild = (c: AppRouteConfig): ReactElement =>
-    c.children?.length ? (
-      <Route key={c.path} path={c.path} element={c.element}>
-        {c.children.map(renderChild)}
-      </Route>
-    ) : (
-      <Route key={c.path} path={c.path} element={c.element} />
-    );
-
-  const renderGuarded = (r: AppRouteConfig) => {
-    const element = (
-      <ProtectedRoute permissionCode={resolvePermissionCode(r)}>{r.element}</ProtectedRoute>
-    );
-    return r.children?.length ? (
-      <Route key={r.path} path={r.path} element={element}>
-        {r.children.map(renderChild)}
-      </Route>
-    ) : (
-      <Route key={r.path} path={r.path} element={element} />
-    );
-  };
-
-  return (
-    <Routes>
-      {redirects.map((r) => (
-        <Route key={`redirect:${r.from}`} path={r.from} element={<Navigate to={r.to} replace />} />
-      ))}
-      {publicRoutes.map((r) => (
-        <Route key={r.path} path={r.path} element={r.element} />
-      ))}
-      {topLevelGuarded.map(renderGuarded)}
-      {layout ? (
-        <Route element={layout}>{inLayout.map(renderGuarded)}</Route>
-      ) : (
-        inLayout.map(renderGuarded)
-      )}
-      {notFound ? <Route path="*" element={notFound} /> : null}
-    </Routes>
-  );
-}

package/src/router/index.ts

@@ -1,41 +0,0 @@
-/**
- * `@genesislcap/foundation-react-utils/router`
- *
- * Reusable `react-router-dom` primitives for Genesis Foundation React apps, so
- * the app-shell routing logic doesn't have to be reimplemented per app.
- *
- * Exposed as a subpath (`/router`) rather than from the package root so that
- * consumers which don't route (and don't depend on `react-router-dom`) are
- * unaffected.
- *
- * Key exports:
- * - `ProtectedRoute` / `createProtectedRoute` — auth + permission gate that
- *   stashes the full origin location (incl. `search` + `hash`) for post-login
- *   restore, and redirects to a not-permitted path when authorized-but-blocked.
- * - `buildPostLoginRedirect` — rebuild the return URL preserving query + hash.
- * - `readInitialParam` / `createComponentRegistry` / `SingleComponentOutlet` —
- *   render a single registered component full-screen from a `?param=<name>`
- *   deep-link captured before the shell strips the query string.
- * - `renderAppRoutes` — build the app's `<Routes>` from a declarative route
- *   table (guarding, layout nesting, redirects, not-found, single-component).
- * - `mergePbcRoutes` — merge static routes with shell/PBC routes into one table.
- */
-
-export { ProtectedRoute, createProtectedRoute } from './protected-route';
-export type {
-  ProtectedRouteProps,
-  BoundProtectedRouteProps,
-  CreateProtectedRouteOptions,
-} from './protected-route';
-export { buildPostLoginRedirect } from './post-login-redirect';
-export type { RedirectableLocationState } from './post-login-redirect';
-export {
-  readInitialParam,
-  createComponentRegistry,
-  SingleComponentOutlet,
-} from './single-component';
-export type { ComponentRegistry, SingleComponentOutletProps } from './single-component';
-export { renderAppRoutes } from './app-routes';
-export type { AppRouteConfig, RouteRedirect, RenderAppRoutesOptions } from './app-routes';
-export { mergePbcRoutes } from './pbc-routes';
-export type { PbcRouteInput, MergePbcRoutesOptions } from './pbc-routes';

package/src/router/pbc-routes.ts

@@ -1,56 +0,0 @@
-import type { ReactNode } from 'react';
-import type { AppRouteConfig } from './app-routes';
-
-/**
- * Minimal shape of a PBC route as provided by the shell (e.g. `getApp().routes`).
- * Kept as an input type — rather than importing `foundation-shell` — so this
- * helper stays dependency-free and the `/router` subpath doesn't pull the shell
- * into apps that don't use PBCs.
- */
-export interface PbcRouteInput {
-  path: string;
-  title?: string;
-  /** The PBC element (module/loader) the container will mount. */
-  element?: unknown;
-  /** Explicit custom-element tag, if the container shouldn't derive one. */
-  elementTag?: string;
-  /** Nav items contributed by this PBC. */
-  navItems?: unknown;
-  /** Extra per-route settings (e.g. `permissionCode`), spread into `data`. */
-  settings?: Record<string, unknown>;
-}
-
-/**
- * Options for {@link mergePbcRoutes}.
- */
-export interface MergePbcRoutesOptions {
-  /** Render the element for a PBC route (typically `() => <PBCContainer />`). */
-  renderPbc: (pbc: PbcRouteInput) => ReactNode;
-}
-
-/**
- * Merge a static route table with PBC routes (e.g. from `getApp().routes`) into
- * one {@link AppRouteConfig} array. PBC routes are guarded, in-layout, and carry
- * their element/tag + navItems through `data` so downstream consumers (a PBC
- * container, nav-item derivation) can read them — matching the `data` shape the
- * hand-rolled version produced.
- */
-export function mergePbcRoutes(
-  staticRoutes: AppRouteConfig[],
-  pbcRoutes: PbcRouteInput[],
-  { renderPbc }: MergePbcRoutesOptions,
-): AppRouteConfig[] {
-  const mapped: AppRouteConfig[] = pbcRoutes.map((pbc) => ({
-    path: `/${pbc.path}`,
-    element: renderPbc(pbc),
-    permissionCode: pbc.settings?.permissionCode as string | undefined,
-    data: {
-      ...pbc.settings,
-      pbcElement: pbc.element,
-      pbcElementTag: pbc.elementTag,
-      navItems: pbc.navItems,
-    },
-  }));
-
-  return [...staticRoutes, ...mapped];
-}

package/src/router/post-login-redirect.ts

@@ -1,29 +0,0 @@
-/**
- * Shape of the router location `state` that a route guard stashes before
- * redirecting to login. Structural, so it works with `react-router-dom`'s
- * `Location` without importing it here.
- */
-export interface RedirectableLocationState {
-  from?: {
-    pathname: string;
-    search?: string;
-    hash?: string;
-  };
-}
-
-/**
- * Build the post-login redirect target from a router location's `state.from`,
- * preserving the query string and hash so deep-link params (e.g.
- * `?component=<name>`) survive the login bounce. Falls back to `defaultPath`
- * when there is no stashed origin.
- *
- * @param location - The current router location (needs only `state.from`).
- * @param defaultPath - Where to land when nothing was stashed. Defaults to `/`.
- */
-export function buildPostLoginRedirect(
-  location: { state?: RedirectableLocationState | null },
-  defaultPath = '/',
-): string {
-  const from = location.state?.from;
-  return from ? `${from.pathname}${from.search ?? ''}${from.hash ?? ''}` : defaultPath;
-}

package/src/router/protected-route.tsx

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