@genesislcap/foundation-react-utils

中文文档
15.96.2发布于 2026/11/16SEE LICENSE IN license.txtTypeScriptCommonJS近 30 天下载 1.5万

Genesis Foundation React Utils

原始使用文档
文档目录8 节
  1. Installation
  2. flexlayout-react
  3. Migrating an app that depends on flexlayout-react directly
  4. Error boundaries
  5. foundation-workspace
  6. flexlayout-react layouts
  7. License
  8. Licensed components

@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 workspaceComponents from @genesislcap/foundation-workspace with your design system.
  • Render layout panes through registerFactory + reactFactory, not as JSX children of rapid-layout-item. Loading a saved layout rebuilds the panes, and cloned DOM loses React-set properties such as gridOptions.
  • useWorkspaceFilter also 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

版本与发布记录

@genesislcap/foundation-react-utils 共发布 974 个版本,首次发布于 2025/11/15;过去 12 个月发布了 973 个版本。

版本发布日期距今
15.96.2latest2026/11/16今天
15.96.12026/11/16今天
15.96.0-GENC-1665.32026/11/142 天前
15.96.02026/11/142 天前
15.95.2-GENC-1665.22026/11/132 天前
15.95.22026/11/133 天前

其他发布通道:FUI-2341-3 → 14.367.1-FUI-2341-3.4,FUI-2456 → 14.371.0-FUI-2456.1,MX-499 → 14.373.2-MX-499.4,MX-499-LIST → 14.373.2-MX-499-LIST.1,FUI-2457 → 14.375.1-FUI-2457.1,TAMTECH-262 → 14.380.1-TAMTECH-262.2。

关于 @genesislcap/foundation-react-utils 的常见问题

@genesislcap/foundation-react-utils 是什么?

Genesis Foundation React Utils

如何安装 @genesislcap/foundation-react-utils?

在项目目录运行 npm install @genesislcap/foundation-react-utils,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.0.0)、react-dom(^19.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@genesislcap/foundation-react-utils 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genesislcap/foundation-react-utils 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@genesislcap/foundation-react-utils 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genesislcap/foundation-react-utils 可以商用吗?

@genesislcap/foundation-react-utils 使用 SEE LICENSE IN license.txt 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@genesislcap/foundation-react-utils 的下载量有多少?

根据 npm 官方下载统计,@genesislcap/foundation-react-utils 在 2026/10/16 – 2026/11/14 这 30 天内被下载 15,005 次,日均约 500 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genesislcap/foundation-react-utils 还在维护吗?

最新版本 15.96.2 发布于 2026/11/16(今天);至今共发布 974 个版本,其中过去 12 个月发布了 973 个;首次发布于 2025/11/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。