@bpmn-nova/vue 0.3.4-preview → 0.3.6-preview

package/README.md

@@ -4,7 +4,7 @@ BPMN Nova 的 Vue 3.3+ Adapter，提供 Studio、Designer、Viewer、审批轨
 
 > **English summary:** Vue 3.3+ components and exposed instance methods for BPMN Nova process design, viewing, approval traces, properties, themes, and SVG export.
 
-> 当前版本为 `0.3.4-preview`。Vue 由宿主工程提供，本包不会替应用选择或升级框架版本。
+> 当前版本为 `0.3.6-preview`。Vue 由宿主工程提供，本包不会替应用选择或升级框架版本。
 
 ![BPMN Nova Vue 流程工作台](https://raw.githubusercontent.com/daxiangme/bpmn-nova/dev/docs/assets/bpmn-nova-designer.jpg)
 
@@ -14,29 +14,11 @@ BPMN Nova 的 Vue 3.3+ Adapter，提供 Studio、Designer、Viewer、审批轨
 npm install @bpmn-nova/vue@preview
 ```
 
-```js
-import '@bpmn-nova/vue/styles.css'
-```
-
-只安装本包；`@bpmn-nova/studio` 会作为内部依赖自动解析。容器必须有明确高度。
-
-TypeScript 类型也从 Vue 入口导入，不要为了模型类型额外声明 Studio 直依赖：
-
-```ts
-import type {
-  BpmnNode,
-  EdgeType,
-  ElementSelection,
-  NodeType,
-  ProcessModel,
-} from '@bpmn-nova/vue'
-```
+只安装本包；匹配版本的 `@bpmn-nova/studio` 会作为依赖自动解析。公共 TypeScript 类型直接从 `@bpmn-nova/vue` 导入，不需要为类型额外添加 Studio 直依赖。
 
-公共类型门面还包含 `BpmnEdge`、`EngineId` 和 `LayoutOptions`。
+CSS 必须显式导入 `@bpmn-nova/vue/styles.css`；视觉容器及其父级需要具有可计算高度。
 
-使用代码生成助手或 IDE Agent 接入时，从随包的 `llms.txt` 开始；需要完整接口和定制资料时再读取 `llms-full.txt`。两份文件都包含在 npm tarball 中，不依赖源码仓库可见性。
-
-## 流程设计
+## 最小用法
 
 ```vue
 <script setup>
@@ -46,6 +28,7 @@ import '@bpmn-nova/vue/styles.css'
 
 const props = defineProps({ initialXml: String })
 const studioRef = ref(null)
+const studioConfig = { ui: { controlSize: 'medium' } }
 
 function handleChange(model, reason, nextXml) {
   console.log(reason, nextXml)
@@ -58,6 +41,7 @@ function handleChange(model, reason, nextXml) {
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
+      :config="studioConfig"
       mode="design"
       :allowed-modes="['design']"
       theme="auto"
@@ -67,254 +51,17 @@ function handleChange(model, reason, nextXml) {
 </template>
 ```
 
-Expose 提供 `getActions()`、`validate()`、`exportXml()`、`fitView()`、`setTheme()`、`exportSvg()` 和 `openSvgExportPreview()`。
-
-`xml`/`model` 是外部替换输入，`change` 的 XML 是草稿输出。宿主回写完全相同的导出 XML 不会重新导入或清空撤销历史；切换服务器 revision 或流程时传入不同 XML 会替换模型。Activiti 宿主应显式使用 `engine="activiti"`。
-
-## 组合宿主头部与业务属性面板
-
-默认 `BpmnStudio` 是包含 Header、Palette、Canvas、Properties 和 Statusbar 的完整工作台。下面的接入显式隐藏 Nova Properties，保留 Nova Palette，并只替换 Header 左侧品牌区：
-
-```vue
-<script setup>
-import { ref } from 'vue'
-import { BpmnStudio } from '@bpmn-nova/vue'
-import '@bpmn-nova/vue/styles.css'
-
-const studioRef = ref(null)
-const selectedElement = ref(null)
-const supportedNodeTypes = ['startEvent', 'userTask', 'exclusiveGateway', 'endEvent']
-
-function handleSelectionChange(selection, element) {
-  selectedElement.value = selection ? element : null
-}
-</script>
-
-<template>
-  <div class="process-design-workbench">
-    <BpmnStudio
-      ref="studioRef"
-      :xml="xml"
-      engine="activiti"
-      mode="design"
-      :allowed-modes="['design']"
-      :allowed-node-types="supportedNodeTypes"
-      :allowed-edge-types="['sequenceFlow']"
-      :regions="{ right: 'hidden' }"
-      theme="auto"
-      @change="handleChange"
-      @selection-change="handleSelectionChange"
-      @validation="handleValidation"
-    >
-      <template #header-start="{ state, actions }">
-        <button type="button" @click="back">← 返回审批列表</button>
-        <ApprovalIcon :icon="icon" />
-        <strong>{{ processName }}</strong>
-        <span>{{ processType }}</span>
-      </template>
-      <template #header-actions="{ actions, mode }">
-        <button type="button" :disabled="mode !== 'design'" @click="actions.validate()">校验</button>
-        <button type="button" :disabled="mode !== 'design'" @click="saveDraft(actions.exportXml())">保存</button>
-        <button type="button" :disabled="mode !== 'design'" @click="publishProcess(actions)">发布</button>
-      </template>
-    </BpmnStudio>
-
-    <DxProcessProperties
-      v-if="selectedElement"
-      :element-id="selectedElement.id"
-    />
-  </div>
-</template>
-```
-
-`header-start` 与 `header-actions` 使用 Vue Teleport 在当前应用内渲染，因此保留 provide/inject、响应式状态与组件生命周期。`header-actions` 只替换默认“校验 / 导入 / 导出”动作组，完整 `header` 的优先级更高。默认 Header 的最佳视图只保留在底部缩放区；若整个 Header 都不需要，配置 `regions.header = 'hidden'`。
-
-`actions.validate()` 以 `toolbar` 来源先更新 Nova 默认状态栏，再发送 `validation` 事件并返回 issues；Expose `validate()` 使用 `api` 来源。事件的 `valid` 仅在存在 error 时为 `false`，warning 不默认阻止发布。保存与发布仍由宿主负责。
-
-```js
-async function publishProcess(actions) {
-  const issues = actions.validate()
-  if (issues.some((issue) => issue.level === 'error')) return
-  await publishXml(actions.exportXml())
-}
-```
-
-编辑器属性面板应订阅 `selection-change`，该事件覆盖节点、连线、多选、清空和键盘选择。`element-click` 是点击观察事件，不能代替选择状态。宿主使用稳定 BPMN Element ID 关联业务配置，并自行拥有保存、发布、权限和服务端事务。
-
-## Mode 双向同步与副标题刷新
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-const studioRef = ref(null)
-const mode = ref('design')
-const summaries = new Map()
-const resolveSubtitle = ({ node }) => summaries.has(node.id)
-  ? summaries.get(node.id)
-  : undefined
-
-function updateSummary() {
-  summaries.set('ServiceTask_Archive', '归档到采购系统')
-  studioRef.value?.refreshPresentation()
-}
-</script>
-
-<template>
-  <BpmnStudio
-    ref="studioRef"
-    v-model:mode="mode"
-    :allowed-modes="['design', 'viewer']"
-    :node-subtitle-resolver="resolveSubtitle"
-    @mode-change="event => console.log(event.source)"
-  >
-    <template #header-start="{ mode: actualMode }">
-      <HostHeader :mode="actualMode" />
-    </template>
-  </BpmnStudio>
-</template>
-```
-
-Expose 的 `getMode()` / `setMode()` 使用 Shell 实际状态。Resolver 返回 `undefined` 保留默认值、`null` 移除副标题行、字符串替换显示；函数引用变化会自动刷新，稳定闭包内部数据变化需显式调用 `refreshPresentation()`。Resolver 只影响 Design/Viewer 标准卡片和 SVG，不覆盖 Instance Runtime Presentation，也不修改 XML、History、Selection 或 Viewport。
-
-## 只读展示与审批轨迹
-
-```vue
-<script setup>
-import { BpmnViewer } from '@bpmn-nova/vue'
-import '@bpmn-nova/vue/styles.css'
-
-defineProps({
-  xml: String,
-  runtime: Object,
-  runtimeAssetResolver: Function,
-})
-</script>
-
-<template>
-  <div style="height: 720px">
-    <BpmnViewer
-      :xml="xml"
-      engine="flowable"
-      :runtime="runtime"
-      projection="compact"
-      responsive
-      theme="auto"
-      :runtime-asset-resolver="runtimeAssetResolver"
-      @trace-click="event => console.log(event)"
-    />
-  </div>
-</template>
-```
-
-- `approval`：实际发生的有效路径。
-- `compact`：移动时间线、审批动作、图片和附件。
-- `standard`：完整 BPMN 叠加运行状态。
-
-![BPMN Nova Vue 移动审批时间线](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 runtimeAssetResolver = 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 导出
-
-```vue
-<BpmnStudio
-  ref="studioRef"
-  :xml="xml"
-  :theme="{
-    mode: 'auto',
-    dark: {
-      colors: {
-        canvas: '#0b1018',
-        surface: '#18202b',
-      },
-    },
-  }"
-/>
-```
-
-```js
-studioRef.value?.openSvgExportPreview({
-  theme: 'current',
-  filename: '采购申请审批流程.svg',
-})
-```
-
-主题属性变化会更新现有实例，不会重新挂载画布、清除选择或关闭详情。
-
-## Properties 与自定义 Renderer
-
-本包还导出：
-
-- `BpmnDesigner`、`BpmnCanvas`、`BpmnPalettePanel`、`BpmnPropertiesPanel`
-- `useBpmnStudio`
-- `createVuePropertyComponent`
-- `createVueRuntimeDetailsComponent`
-- `createVueRuntimeTransitionDetailsComponent`
-- `createVueRuntimeTimelineComponent`
-- `createStudioController`、`createEmptyProcess`、`importBpmn`、`exportBpmn`
-- Palette、Properties、Context Menu、Icon 和 Template Registry 的公开创建函数
-
-完整工作台可通过 `allowedNodeTypes` 与 `allowedEdgeTypes` 限制宿主支持的图元类型，通过 `allowedModes` 限制可切换的工作台模式。图元限制同时作用于 XML 导入、Palette、连接、快捷新增、模板和节点类型转换。
-
-## 常见问题
+`initialXml` 由宿主提供。组件负责实例生命周期；SSR 应用只在客户端挂载。`xml` / `model` 用于外部替换输入，事件中的 XML 是草稿输出。
 
-- **无高度：** 为外层容器设置明确高度。
-- **无样式：** 导入一次 `@bpmn-nova/vue/styles.css`。
-- **Vue 重复：** Vue 应由宿主提供并保持单实例。
-- **SSR：** 将可视组件放到客户端挂载阶段。
-- **包选择：** Vue 项目只直接安装 `@bpmn-nova/vue`。
+## 完整文档
 
-## 文档与 AI
+- [官网与文档](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/index.md)
+- [Vue 接入、宿主组合和完整示例](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/vue.md)
+- [组件参数与事件](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/components/index.md)、[公开 API](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/api/index.md)
+- [审批轨迹接入](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/guide/runtime.md)、[自定义扩展](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/customization/index.md)
+- [更新日志](https://github.com/daxiangme/bpmn-nova/blob/dev/docs/src/changelog.md)
 
-- npm 包内 `llms.txt`：可执行安装入口
-- npm 包内 `llms-full.txt`：完整 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 接入从随包的 `llms.txt` 开始；`llms-full.txt` 提供完整离线上下文，两份文件都包含在 npm tarball 中。
 
 ## License
 

package/dist/index.d.ts

@@ -14,6 +14,7 @@ import type { ProcessInstanceSnapshot } from '@bpmn-nova/studio/runtime'
 import type { SvgExportArtifact, SvgExportOptions, SvgExportPreviewController } from '@bpmn-nova/studio/export-svg'
 import type {
   BpmnCanvas as CanvasInstance,
+  BpmnStudioConfig,
   BpmnStudioController,
   BpmnStudioShell,
   ContextMenuRegistry,
@@ -22,6 +23,10 @@ import type {
   StudioCommands,
   StudioMode,
   StudioModeChangeEvent,
+  StudioPanelSelection,
+  StudioSidebarChangeEvent,
+  StudioSidebarSide,
+  StudioSidebarState,
   StudioValidationEvent,
   StudioValidationIssue,
   StudioShellActions,
@@ -29,6 +34,7 @@ import type {
   StudioShellRegions,
   StudioShellSlots,
   StudioState,
+  StudioUiContext,
   TemplateRegistry,
 } from '@bpmn-nova/studio'
 import type { NovaThemeInput, NovaThemeState, RuntimeAppearanceOptions } from '@bpmn-nova/studio/theme'
@@ -53,13 +59,58 @@ export type {
   ProcessModel,
 } from '@bpmn-nova/studio'
 export type {
+  BpmnStudioConfig,
   NodeSubtitleResolver,
   NodeSubtitleResolverContext,
+  StudioControlSize,
+  StudioModelingConfig,
+  StudioPanelSelection,
+  StudioRightPanelConfig,
+  StudioSidebarChangeEvent,
+  StudioSidebarChangeSource,
+  StudioSidebarConfig,
+  StudioSidebarSide,
+  StudioSidebarState,
+  StudioSvgExportOptions,
+  StudioUiConfig,
+  StudioUiContext,
   StudioValidationEvent,
   StudioValidationIssue,
   StudioValidationSource,
+  StudioViewerConfig,
 } from '@bpmn-nova/studio'
 
+/** Runtime integration facade. Types since 0.3.5-preview; inspectRuntime / formatRuntimeInstant since 0.3.6-preview. */
+export type {
+  ActivityInstance,
+  ActivityStatus,
+  ActivityVisitState,
+  ProcessInstanceSnapshot,
+  RuntimeApprovalAction,
+  RuntimeApprovalActionType,
+  RuntimeApprovalContent,
+  RuntimeApprovalContentBlock,
+  RuntimeAssetRef,
+  RuntimeDiagnostic,
+  RuntimeEdgeVisit,
+  RuntimeInstant,
+  RuntimeParticipant,
+  RuntimeTransition,
+} from '@bpmn-nova/studio/runtime'
+export {
+  activityState,
+  createRuntimePresentation,
+  formatRuntimeInstant,
+  inspectRuntime,
+  normalizeRuntime,
+  parseRuntimeInstant,
+} from '@bpmn-nova/studio/runtime'
+export type {
+  RuntimeAssetPurpose,
+  RuntimeAssetResolver,
+  RuntimeTraceClickEvent,
+} from '@bpmn-nova/studio/viewer'
+
 export {
   createContextMenuRegistry,
   createDefaultContextMenuRegistry,
@@ -86,7 +137,16 @@ export interface BpmnNovaVisualProps {
   onThemeChange?: (state: NovaThemeState) => void
 }
 export interface BpmnModelProps { model?: ProcessModel; xml?: string; engine?: EngineId }
-export interface UseBpmnStudioOptions extends BpmnModelProps { studio?: BpmnStudioController; propertiesProfile?: 'business' | 'developer'; allowedNodeTypes?: NodeType[]; allowedEdgeTypes?: EdgeType[] }
+export interface UseBpmnStudioOptions extends BpmnModelProps {
+  studio?: BpmnStudioController
+  config?: BpmnStudioConfig
+  /** @deprecated Use config.modeling.propertiesProfile. */
+  propertiesProfile?: 'business' | 'developer'
+  /** @deprecated Use config.modeling.allowedNodeTypes. */
+  allowedNodeTypes?: NodeType[]
+  /** @deprecated Use config.modeling.allowedEdgeTypes. */
+  allowedEdgeTypes?: EdgeType[]
+}
 export interface UseBpmnStudioResult { studio: BpmnStudioController; state: StudioState; commands: StudioCommands }
 export function useBpmnStudio(options?: UseBpmnStudioOptions): UseBpmnStudioResult
 
@@ -130,8 +190,12 @@ export const BpmnPalettePanel: DefineComponent<BpmnPalettePanelProps>
 
 export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   studio?: BpmnStudioController
+  config?: BpmnStudioConfig
+  /** @deprecated Use config.modeling.propertiesProfile. */
   propertiesProfile?: 'business' | 'developer'
+  /** @deprecated Use config.modeling.allowedNodeTypes. */
   allowedNodeTypes?: NodeType[]
+  /** @deprecated Use config.modeling.allowedEdgeTypes. */
   allowedEdgeTypes?: EdgeType[]
   iconRegistry?: IconRegistry
   paletteRegistry?: PaletteRegistry
@@ -143,39 +207,56 @@ export interface BpmnStudioProps extends BpmnNovaVisualProps, BpmnModelProps {
   nodeSubtitleResolver?: NodeSubtitleResolver
   slotsConfig?: StudioShellSlots
   layout?: StudioShellOptions['layout']
+  /** @deprecated Use config.ui.regions. */
   regions?: StudioShellRegions
+  /** @deprecated Use config.ui.sidebarWidth.left. */
   leftWidth?: number
+  /** @deprecated Use config.ui.sidebarWidth.right. */
   rightWidth?: number
   runtime?: ProcessInstanceSnapshot | null
   runtimePresenter?: ViewerOptions['runtimePresenter']
   runtimeTraceProjector?: ViewerOptions['runtimeTraceProjector']
   runtimeAssetResolver?: ViewerOptions['runtimeAssetResolver']
   runtimeTimelineRenderer?: RuntimeTimelineRenderer
+  /** @deprecated Use config.export. */
   svgExport?: ViewerOptions['svgExport']
   onRuntimeTraceItemClick?: ViewerOptions['onRuntimeTraceItemClick']
   runtimeDetailsRenderer?: RuntimeDetailsRenderer | null
   onRuntimeDetailsOpen?: ViewerOptions['onRuntimeDetailsOpen']
   runtimeTransitionDetailsRenderer?: RuntimeTransitionDetailsRenderer | null
   onRuntimeTransitionDetailsOpen?: ViewerOptions['onRuntimeTransitionDetailsOpen']
+  /** @deprecated Use config.viewer.timeline. */
   timeline?: ViewerOptions['timeline']
+  /** @deprecated Use config.viewer.runtimeDetails. */
   runtimeDetails?: ViewerOptions['runtimeDetails']
+  /** @deprecated Use config.viewer.runtimeTraceOptions. */
   runtimeTraceOptions?: ViewerOptions['runtimeTraceOptions']
   onTraceClick?: (event: RuntimeTraceClickEvent) => void
   onElementClick?: ViewerOptions['onElementClick']
   mode?: StudioMode
   allowedModes?: readonly StudioMode[]
   projection?: ViewerProjection
+  /** @deprecated Use config.viewer.responsive. */
   responsive?: boolean
+  /** @deprecated Use config.viewer.projectionOptions. */
   projectionOptions?: Array<{ value: ViewerProjection; label: string }>
+  onSidebarChange?: (event: StudioSidebarChangeEvent) => void
 }
 export interface BpmnStudioExposed {
   getStudio(): BpmnStudioController
   getShell(): BpmnStudioShell | null
   getActions(): StudioShellActions | null
+  getConfig(): Readonly<BpmnStudioConfig> | undefined
+  setConfig(config?: BpmnStudioConfig): Readonly<BpmnStudioConfig> | undefined
   getMode(): StudioMode | undefined
   getAllowedModes(): readonly StudioMode[]
   setMode(mode: StudioMode): boolean
   setAllowedModes(modes: readonly StudioMode[]): readonly StudioMode[]
+  getSidebarState(): StudioSidebarState | undefined
+  setSidebarCollapsed(side: StudioSidebarSide, collapsed: boolean): boolean
+  subscribeSidebarChange(listener: (event: StudioSidebarChangeEvent) => void): () => void
+  getPanelSelection(): StudioPanelSelection | undefined
+  subscribePanelSelection(listener: (selection: StudioPanelSelection) => void): () => void
   refreshPresentation(): void
   validate(): StudioValidationIssue[]
   exportXml(engine?: EngineId): string
@@ -190,11 +271,14 @@ export interface BpmnStudioSlotContext {
   readonly actions: StudioShellActions
   readonly state: Readonly<StudioState>
   readonly mode: StudioMode
+  readonly ui: StudioUiContext
+  readonly panelSelection: StudioPanelSelection
 }
 export interface BpmnStudioSlots {
   'header-start'?(context: BpmnStudioSlotContext): VNodeChild
   'header-actions'?(context: BpmnStudioSlotContext): VNodeChild
   header?(context: BpmnStudioSlotContext): VNodeChild
+  right?(context: BpmnStudioSlotContext): VNodeChild
 }
 export const BpmnStudio: DefineComponent<BpmnStudioProps> & {
   new(): { $slots: BpmnStudioSlots }
@@ -263,6 +347,7 @@ export interface BpmnStudioEmits {
   'update:mode': [mode: StudioMode]
   'mode-change': [event: StudioModeChangeEvent]
   validation: [event: StudioValidationEvent]
+  'sidebar-change': [event: StudioSidebarChangeEvent]
 }
 export interface BpmnDesignerEmits {
   change: [model: ProcessModel, reason: string, xml: string]