@bpmn-nova/react 0.3.1-preview

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 BPMN Nova contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,183 @@
+# @bpmn-nova/react
+
+BPMN Nova 的 React 18+ Adapter，提供 Studio、Designer、Viewer、审批轨迹、Properties 和实例 Ref。
+
+> **English summary:** React 18+ components and refs for BPMN Nova process design, viewing, approval traces, properties, themes, and SVG export.
+
+> 当前版本为 `0.3.1-preview`。React 与 React DOM 由宿主工程提供，本包不会替应用选择或升级框架版本。
+
+![BPMN Nova React 流程工作台](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
+
+## 安装
+
+```bash
+npm install @bpmn-nova/react@preview
+```
+
+```jsx
+import '@bpmn-nova/react/styles.css'
+```
+
+只安装本包；`@bpmn-nova/studio` 会作为内部依赖自动解析。容器必须有明确高度。
+
+## 流程设计
+
+```jsx
+import { useRef } from 'react'
+import { BpmnStudio } from '@bpmn-nova/react'
+import '@bpmn-nova/react/styles.css'
+
+export function WorkflowEditor({ xml }) {
+  const studioRef = useRef(null)
+
+  return (
+    <div style={{ height: 720 }}>
+      <BpmnStudio
+        ref={studioRef}
+        xml={xml}
+        engine="flowable"
+        mode="design"
+        theme="auto"
+        onChange={(model, reason, nextXml) => {
+          console.log(reason, nextXml)
+        }}
+      />
+    </div>
+  )
+}
+```
+
+Ref 提供 `exportXml()`、`fitView()`、`setTheme()`、`exportSvg()` 和 `openSvgExportPreview()`。
+
+## 只读展示与审批轨迹
+
+```jsx
+import { BpmnViewer } from '@bpmn-nova/react'
+import '@bpmn-nova/react/styles.css'
+
+export function ApprovalTrace({ xml, runtime, resolveAsset }) {
+  return (
+    <div style={{ height: 720 }}>
+      <BpmnViewer
+        xml={xml}
+        engine="flowable"
+        runtime={runtime}
+        projection="compact"
+        responsive
+        theme="auto"
+        runtimeAssetResolver={resolveAsset}
+        onTraceClick={(event) => console.log(event)}
+      />
+    </div>
+  )
+}
+```
+
+- `approval`：实际发生的有效路径。
+- `compact`：移动时间线、审批动作、图片和附件。
+- `standard`：完整 BPMN 叠加运行状态。
+
+![BPMN Nova React 移动审批时间线](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-approval-mobile-timeline.jpg)
+
+## Runtime Action 与附件
+
+```js
+const runtime = {
+  processInstanceId: 'purchase-20260824',
+  status: 'running',
+  activities: [{
+    id: 'activity-manager-1',
+    elementId: 'UserTask_Manager',
+    visitId: 'visit-manager-1',
+    status: 'completed',
+    assignee: '李经理',
+  }],
+  actions: [{
+    id: 'approve-manager-1',
+    type: 'approve',
+    elementId: 'UserTask_Manager',
+    visitId: 'visit-manager-1',
+    occurredAt: '2026-08-24T10:12:00+08:00',
+    actor: { id: 'manager-li', name: '李经理' },
+    content: {
+      plainText: '资料完整，同意提交总经理审批。',
+      blocks: [{ type: 'file', assetId: 'purchase-checklist' }],
+      assets: [{
+        id: 'purchase-checklist',
+        name: '采购核验清单.txt',
+        mediaType: 'text/plain',
+        size: 248,
+      }],
+    },
+  }],
+  visitedEdges: [],
+}
+
+const resolveAsset = async (asset, { purpose, signal }) => {
+  const response = await fetch(
+    `/api/runtime-assets/${encodeURIComponent(asset.id)}?purpose=${purpose}`,
+    { signal },
+  )
+  return response.ok ? response.url : null
+}
+```
+
+Runtime Snapshot 只保存资源引用；上传、存储和权限签发由宿主负责。
+
+## 主题和 SVG 导出
+
+```jsx
+<BpmnStudio
+  ref={studioRef}
+  xml={xml}
+  theme={{
+    mode: 'auto',
+    dark: {
+      colors: {
+        canvas: '#0b1018',
+        surface: '#18202b',
+      },
+    },
+  }}
+/>
+```
+
+```js
+studioRef.current?.openSvgExportPreview({
+  theme: 'current',
+  filename: '采购申请审批流程.svg',
+})
+```
+
+主题属性变化会更新现有实例，不会重新挂载画布、清除选择或关闭详情。
+
+## Properties 与自定义 Renderer
+
+本包还导出：
+
+- `BpmnDesigner`、`BpmnCanvas`、`BpmnPalettePanel`、`BpmnPropertiesPanel`
+- `useBpmnStudio`
+- `createReactPropertyComponent`
+- `createReactRuntimeDetailsComponent`
+- `createReactRuntimeTransitionDetailsComponent`
+- `createReactRuntimeTimelineComponent`
+
+## 常见问题
+
+- **无高度：** 为外层容器设置明确高度。
+- **无样式：** 导入一次 `@bpmn-nova/react/styles.css`。
+- **Hooks/React 重复：** React 与 React DOM 应由宿主提供并保持单实例。
+- **SSR：** 将可视组件放到客户端挂载阶段。
+- **包选择：** React 项目只直接安装 `@bpmn-nova/react`。
+
+## 文档与 AI
+
+- [完整项目能力](https://github.com/daxiangme/bpmn-nova)
+- [React/Vue 组件说明](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/COMPONENTS.md)
+- [公开 Interface](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/API.md)
+- [AI 接入入口](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms.txt)
+- [AI 完整上下文](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/llms-full.txt)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import type {
+  ComponentType,
+  CSSProperties,
+  ForwardRefExoticComponent,
+  RefAttributes,
+} from 'react'
+import type { BpmnEdge, BpmnNode, ElementSelection, EngineId, LayoutOptions, ProcessModel } from '@bpmn-nova/studio'
+import type { BpmnDesigner as DesignerInstance } from '@bpmn-nova/studio/designer'
+import type { IconRegistry } from '@bpmn-nova/studio'
+import type { PaletteItem, PaletteProvider, PaletteRegistry, PaletteSection } from '@bpmn-nova/studio'
+import type {
+  PropertiesContext,
+  PropertiesProvider,
+  PropertiesRegistry,
+  PropertyEntry,
+} from '@bpmn-nova/studio'
+import type { ProcessInstanceSnapshot } from '@bpmn-nova/studio/runtime'
+import type { SvgExportArtifact, SvgExportOptions, SvgExportPreviewController } from '@bpmn-nova/studio/export-svg'
+import type {
+  BpmnCanvas as CanvasInstance,
+  BpmnStudioController,
+  BpmnStudioShell,
+  ContextMenuRegistry,
+  InteractionController,
+  StudioCommands,
+  StudioShellOptions,
+  StudioShellSlots,
+  StudioState,
+  TemplateRegistry,
+} from '@bpmn-nova/studio'
+import type { NovaThemeInput, NovaThemeState, RuntimeAppearanceOptions } from '@bpmn-nova/studio/theme'
+import type {
+  BpmnViewer as ViewerInstance,
+  RuntimeDetailsRenderer,
+  RuntimeTimelineRenderer,
+  RuntimeTraceClickEvent,
+  RuntimeTransitionDetailsRenderer,
+  ViewerOptions,
+  ViewerProjection,
+} from '@bpmn-nova/studio/viewer'
+
+export interface BpmnNovaVisualProps {
+  theme?: NovaThemeInput
+  runtimeAppearance?: RuntimeAppearanceOptions
+  onThemeChange?: (state: NovaThemeState) => void
+  className?: string
+  style?: CSSProperties
+}
+export interface BpmnModelProps {
+  model?: ProcessModel
+  xml?: string
+  engine?: EngineId
+}
+export interface UseBpmnStudioOptions extends BpmnModelProps {
+  studio?: BpmnStudioController
+  propertiesProfile?: 'business' | 'developer'
+}
+export interface UseBpmnStudioResult { studio: BpmnStudioController; state: StudioState; commands: StudioCommands }
+export function useBpmnStudio(options?: UseBpmnStudioOptions): UseBpmnStudioResult
+
+export interface BpmnCanvasProps extends BpmnNovaVisualProps {
+  studio: BpmnStudioController
+  interactions?: InteractionController
+  templates?: TemplateRegistry
+  iconRegistry?: IconRegistry
+  nodeRenderers?: Record<string, Function>
+  nodeRenderer?: Function
+  svgExport?: ViewerOptions['svgExport']
+}
+export interface BpmnCanvasHandle {
+  readonly instance: CanvasInstance | null
+  fitView(padding?: number, options?: Record<string, unknown>): void
+  clientToWorld(x: number, y: number): { x: number; y: number } | undefined
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+  exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact> | undefined
+  openSvgExportPreview(options?: SvgExportOptions & { previewTitle?: string; onDownload?: (artifact: SvgExportArtifact) => void }): SvgExportPreviewController | undefined
+}
+export const BpmnCanvas: ForwardRefExoticComponent<BpmnCanvasProps & RefAttributes<BpmnCanvasHandle>>
+
+export interface BpmnPalettePanelProps extends BpmnNovaVisualProps {
+  studio: BpmnStudioController
+  interactions?: InteractionController
+  templates?: TemplateRegistry
+  registry?: PaletteRegistry
+  providers?: PaletteProvider[]
+  canvas?: CanvasInstance | null
+  iconRegistry?: IconRegistry
+  renderItem?: (context: { item: PaletteItem; panel: unknown }) => HTMLElement | null
+  renderSection?: (context: { section: PaletteSection; panel: unknown }) => HTMLElement | null
+}
+export interface BpmnPalettePanelHandle {
+  readonly panel: unknown
+  render(): void
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+}
+export const BpmnPalettePanel: ForwardRefExoticComponent<BpmnPalettePanelProps & RefAttributes<BpmnPalettePanelHandle>>
+
+export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
+  studio?: BpmnStudioController
+  propertiesProfile?: 'business' | 'developer'
+  iconRegistry?: IconRegistry
+  paletteRegistry?: PaletteRegistry
+  propertiesRegistry?: PropertiesRegistry
+  templateRegistry?: TemplateRegistry
+  contextMenuRegistry?: ContextMenuRegistry
+  nodeRenderers?: Record<string, Function>
+  nodeRenderer?: Function
+  slots?: StudioShellSlots
+  layout?: StudioShellOptions['layout']
+  runtime?: ProcessInstanceSnapshot | null
+  mode?: 'design' | 'viewer' | 'instance'
+  projection?: ViewerProjection
+  responsive?: boolean
+  projectionOptions?: Array<{ value: ViewerProjection; label: string }>
+  leftWidth?: number
+  rightWidth?: number
+  timeline?: ViewerOptions['timeline']
+  runtimeDetails?: ViewerOptions['runtimeDetails']
+  runtimeTraceOptions?: ViewerOptions['runtimeTraceOptions']
+  runtimePresenter?: ViewerOptions['runtimePresenter']
+  runtimeTraceProjector?: ViewerOptions['runtimeTraceProjector']
+  runtimeAssetResolver?: ViewerOptions['runtimeAssetResolver']
+  runtimeTimelineRenderer?: RuntimeTimelineRenderer
+  svgExport?: ViewerOptions['svgExport']
+  runtimeDetailsRenderer?: RuntimeDetailsRenderer | null
+  runtimeTransitionDetailsRenderer?: RuntimeTransitionDetailsRenderer | null
+  onRuntimeTraceItemClick?: ViewerOptions['onRuntimeTraceItemClick']
+  onRuntimeDetailsOpen?: ViewerOptions['onRuntimeDetailsOpen']
+  onRuntimeTransitionDetailsOpen?: ViewerOptions['onRuntimeTransitionDetailsOpen']
+  onElementClick?: ViewerOptions['onElementClick']
+  onTraceClick?: (event: RuntimeTraceClickEvent) => void
+  onChange?: (model: ProcessModel, reason: string, xml: string) => void
+  onSelectionChange?: (selection: ElementSelection | null, element: StudioState['selectedElement']) => void
+  onScopeChange?: (activeScopeId: string, scopePath: StudioState['scopePath'], state: StudioState) => void
+}
+export interface BpmnStudioHandle {
+  readonly studio: BpmnStudioController
+  readonly shell: BpmnStudioShell | null
+  exportXml(engine?: EngineId): string
+  fitView(): void
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+  exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact> | undefined
+  openSvgExportPreview(options?: SvgExportOptions & { previewTitle?: string; onDownload?: (artifact: SvgExportArtifact) => void }): SvgExportPreviewController | null | undefined
+}
+export const BpmnStudio: ForwardRefExoticComponent<BpmnStudioProps & RefAttributes<BpmnStudioHandle>>
+
+export interface BpmnDesignerProps extends BpmnNovaVisualProps, BpmnModelProps {
+  svgExport?: ViewerOptions['svgExport']
+  onChange?: (model: ProcessModel, reason: string, xml: string) => void
+  onSelectionChange?: (selection: ElementSelection | null, element: BpmnNode | BpmnEdge | null) => void
+}
+export interface BpmnDesignerHandle {
+  readonly instance: DesignerInstance | null
+  readonly model: ProcessModel | undefined
+  exportXml(engine?: EngineId): string
+  fitView(): void
+  beautify(options?: LayoutOptions): void
+  rerouteEdges(options?: LayoutOptions): void
+  validate(): Array<{ level: 'error' | 'warning'; elementId?: string; message: string }>
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+  exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact> | undefined
+  openSvgExportPreview(options?: SvgExportOptions & { previewTitle?: string; onDownload?: (artifact: SvgExportArtifact) => void }): SvgExportPreviewController | undefined
+}
+export const BpmnDesigner: ForwardRefExoticComponent<BpmnDesignerProps & RefAttributes<BpmnDesignerHandle>>
+
+export interface BpmnViewerProps extends BpmnNovaVisualProps, BpmnModelProps, Omit<ViewerOptions, 'container' | 'model' | 'theme' | 'runtimeAppearance' | 'onThemeChange'> {}
+export interface BpmnViewerHandle {
+  readonly instance: ViewerInstance | null
+  fitView(): void
+  setProjection(projection: ViewerProjection): void
+  setRuntime(runtime: ProcessInstanceSnapshot | null): void
+  setDisplayOptions(options: Parameters<ViewerInstance['setDisplayOptions']>[0]): void
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+  exportSvg(options?: SvgExportOptions): Promise<SvgExportArtifact> | undefined
+  openSvgExportPreview(options?: SvgExportOptions & { previewTitle?: string; onDownload?: (artifact: SvgExportArtifact) => void }): SvgExportPreviewController | undefined
+}
+export const BpmnViewer: ForwardRefExoticComponent<BpmnViewerProps & RefAttributes<BpmnViewerHandle>>
+
+export interface ReactPropertyComponentProps {
+  entry: PropertyEntry
+  context: PropertiesContext
+  value: unknown
+  onChange(value: unknown): void
+}
+export function createReactPropertyComponent(component: ComponentType<ReactPropertyComponentProps>): (context: Record<string, unknown>) => void | (() => void)
+export interface BpmnPropertiesPanelProps extends BpmnNovaVisualProps {
+  studio?: BpmnStudioController
+  designer?: BpmnStudioController | DesignerInstance
+  registry?: PropertiesRegistry
+  providers?: PropertiesProvider[]
+  dataProviders?: Record<string, unknown>
+  components?: Record<string, ComponentType<ReactPropertyComponentProps>>
+}
+export interface BpmnPropertiesPanelHandle {
+  readonly panel: unknown
+  readonly registry: PropertiesRegistry | null
+  render(): void
+  setTheme(theme: NovaThemeInput): NovaThemeState | undefined
+}
+export const BpmnPropertiesPanel: ForwardRefExoticComponent<BpmnPropertiesPanelProps & RefAttributes<BpmnPropertiesPanelHandle>>
+
+export function createReactRuntimeDetailsComponent(component: ComponentType<Omit<Parameters<RuntimeDetailsRenderer>[0], 'container'>>): RuntimeDetailsRenderer
+export function createReactRuntimeTransitionDetailsComponent(component: ComponentType<Omit<Parameters<RuntimeTransitionDetailsRenderer>[0], 'container'>>): RuntimeTransitionDetailsRenderer
+export function createReactRuntimeTimelineComponent(component: ComponentType<Omit<Parameters<RuntimeTimelineRenderer>[0], 'container'>>): RuntimeTimelineRenderer