@genesislcap/foundation-react-utils
Documentation for this package is published on the Genesis docs site:
Docs: Framework integration
Installation
Add the package to your package.json dependencies. After changing dependencies, run npm run bootstrap (or your project's equivalent). See package.json basics for more information.
{
"dependencies": {
"@genesislcap/foundation-react-utils": "latest"
}
}
flexlayout-react
flexlayout-react is re-exported from the ./flexlayout entry point at a version this package
pins, so apps neither declare nor upgrade it themselves:
import { Actions, DockLocation, Layout, Model, TabNode } from '@genesislcap/foundation-react-utils/flexlayout';
The entry point re-exports the whole flexlayout-react API and installs the Rapid Design System
theme for it into the document on import. No stylesheet import is needed, and flexlayout-react's
own stylesheets should not be imported — they are the unthemed upstream defaults. Colours resolve
from Rapid design tokens, so render the layout under a <rapid-design-system-provider>.
Styles adopted into the document do not cross a shadow boundary, so a layout mounted inside a shadow root needs the theme adopted there as well:
import { installRapidFlexLayoutReactStyles } from '@genesislcap/foundation-react-utils/flexlayout';
installRapidFlexLayoutReactStyles(myShadowRoot);
Migrating an app that depends on flexlayout-react directly
Remove flexlayout-react from the app's package.json, drop any flexlayout-react/style/*.css
import, and point the remaining imports at ./flexlayout. Keeping the app-level dependency risks
resolving a second copy of the library, which breaks the instanceof checks flexlayout-react
relies on internally; the entry point logs a warning when the version it loads differs from the one
the theme was generated against.
Error boundaries
AppErrorBoundary wraps the whole app, and TileErrorBoundary (or the withTileErrorBoundary
HOC) wraps a single tile, so a crash replaces only that tile. Both render a fallback with a
reference ID, copyable diagnostics and a Retry button that remounts the children.
With setupErrorMonitoring from @genesislcap/foundation-utils, caught errors are reported with
their reference ID, scope, title, tile registration and component stack, and nothing else is
needed:
import { AppErrorBoundary, onCaughtError } from '@genesislcap/foundation-react-utils';
createRoot(el, { onCaughtError }).render(
<AppErrorBoundary>
<App />
</AppErrorBoundary>,
);
import { TileErrorBoundary, withTileErrorBoundary } from '@genesislcap/foundation-react-utils';
<TileErrorBoundary title="Trade Blotter" tileRegistration="tradeBlotter">
<TradeBlotter />
</TileErrorBoundary>;
export const TradeBlotterTile = withTileErrorBoundary(TradeBlotter, 'Trade Blotter', 'tradeBlotter');
To handle caught errors yourself, pass onError. It receives an ErrorBoundaryReport (error,
componentStack, referenceId, scope, title, tileRegistration). withTileErrorBoundary
takes it as a fourth argument.
Pass onCaughtError to createRoot. By default React 19 logs every error a boundary catches to
console.error before the boundary runs, so a console-capturing monitoring tool reports the bare
error first and can drop or duplicate the boundary's own report. onCaughtError skips that log
for these boundaries, and still logs errors caught by any other boundary, with their component
stack.
Without onError, a boundary logs each caught error through a foundation logger named
ERROR_BOUNDARY_LOGGER_NAME, with a message that names its scope, title, tile registration and
reference ID and gives its component stack. A global log reporter (addGlobalLogReporter from
@genesislcap/foundation-logger) receives it, which is how setupErrorMonitoring reports it. With
onError set, the boundary doesn't log the error, so it isn't reported twice. If onError throws,
the boundary logs the original error and the handler's error, so neither is lost.
The fallback takes its colours, font and corner radius from the design system's tokens
(--neutral-layer-1, --neutral-foreground-rest, --accent-fill-rest, --error-color,
--body-font, --control-corner-radius and others), so it follows the app's theme, including light
and dark mode. To override them, set --eb-* custom properties (--eb-bg, --eb-surface,
--eb-text, --eb-text-muted, --eb-border, --eb-accent, --eb-error, --eb-font, and others)
on an ancestor. Without a design system it uses its own light palette. The last 20 reports are also kept
on window.__GENESIS_ERROR_BOUNDARY_REPORTS__ for dev tooling such as the Genesis Create preview.
foundation-workspace
Workspaces (save/load of layouts, grid column state and filters) work in React through the element
wrappers @genesislcap/foundation-workspace/react already ships, plus one hook for filter state.
@genesislcap/foundation-workspace is an optional peer dependency: add it to your app's own
dependencies to use @genesislcap/foundation-react-utils/workspace.
import { registerFactory } from '@genesislcap/foundation-layout';
import { reactFactory } from '@genesislcap/foundation-react-utils';
import { useWorkspaceFilter } from '@genesislcap/foundation-react-utils/workspace';
import { GridRegister, LayoutWrapper, WorkspaceManager } from '@genesislcap/foundation-workspace/react';
const PositionsPanel = () => {
const [search, setSearch] = useState('');
useWorkspaceFilter('positions-search', search, setSearch);
return (
<GridRegister gridKey="positions">
<RapidGridPro persistColumnStateKey="positions">…</RapidGridPro>
</GridRegister>
);
};
registerFactory('positions', reactFactory(PositionsPanel));
<LayoutWrapper layoutKey="my-layout">
<rapid-layout auto-save-key="my-layout">
<rapid-layout-region>
<rapid-layout-item registration="positions" title="Positions" />
</rapid-layout-region>
</rapid-layout>
</LayoutWrapper>
<WorkspaceManager />
- Register
workspaceComponentsfrom@genesislcap/foundation-workspacewith your design system. - Render layout panes through
registerFactory+reactFactory, not as JSX children ofrapid-layout-item. Loading a saved layout rebuilds the panes, and cloned DOM loses React-set properties such asgridOptions. useWorkspaceFilteralso applies the current workspace's saved value on mount, so a filter inside a pane that is recreated by a layout load still picks up its saved value.
flexlayout-react layouts
LayoutWrapper only covers rapid-layout. For a flexlayout-react layout, hold the Model in
state and register it with useWorkspaceFlexLayout; loading a workspace hands you a new model:
import { Layout, Model } from '@genesislcap/foundation-react-utils/flexlayout';
import { useWorkspaceFlexLayout } from '@genesislcap/foundation-react-utils/workspace';
const [model, setModel] = useState(() => Model.fromJson(defaultLayout));
useWorkspaceFlexLayout('home-layout', model, setModel);
return <Layout model={model} factory={factory} />;
Tabs opened or closed by a loaded layout mount and unmount as usual, so GridRegister and
useWorkspaceFilter inside them pick up the workspace's state as they register.
License
Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact Genesis Global for more details.
Licensed components
Genesis low-code platform