@bpmn-nova/react 0.3.3-preview → 0.3.5-preview

package/llms.txt

@@ -36,6 +36,20 @@ yarn add @bpmn-nova/vue@preview
 
 Replace `vue` with `react` or `studio` only when the selected framework branch requires it. Run one installation command, not all three.
 
+In TypeScript host code, import shared BPMN model types from that same selected public package. Vue and React explicitly re-export `BpmnEdge`, `BpmnNode`, `EdgeType`, `ElementSelection`, `EngineId`, `LayoutOptions`, `NodeType`, and `ProcessModel`; do not add a direct Studio dependency only to obtain these types:
+
+```ts
+import type {
+  BpmnNode,
+  EdgeType,
+  ElementSelection,
+  NodeType,
+  ProcessModel,
+} from '@bpmn-nova/vue'
+```
+
+Use `@bpmn-nova/react` instead in a React application.
+
 This step is complete when the application manifest contains exactly the selected direct BPMN Nova dependency and the package manager finishes without peer-dependency errors.
 
 ## 3. Select the visual Interface
@@ -53,6 +67,8 @@ Use `engine="flowable"` or `engine="activiti"` explicitly from the host workflow
 
 Studio modes are presentation state: `design` means editable process design, `viewer` means read-only process viewing, and `instance` means approval trace. Observe the actual Shell state through `subscribeMode()` or framework mode events; never store it in the BPMN model.
 
+Node geometry is also presentation, not DI normalization. Loading server XML via the component parses its BPMN DI Bounds; XML export already writes model dimensions. The `0.3.5-preview` gateway/data fix scales standard shells to fit those bounds and docks display endpoints without rewriting model geometry or waypoints. Do not resize stored nodes, recreate them, or patch internal CSS to compensate. See [Node DI and visual geometry](docs/API.md#节点-di-与视觉尺寸) and the customization section in the co-located `llms-full.txt`; `node-geometry` is internal, not another installable package.
+
 ## 4. Mount a minimal integration
 
 Every branch must import its own public `styles.css` exactly once and provide a height through the complete parent layout chain.
@@ -68,6 +84,10 @@ import '@bpmn-nova/vue/styles.css'
 const props = defineProps({ initialXml: String })
 const emit = defineEmits(['change'])
 const studioRef = ref(null)
+const config = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
 
 function handleChange(model, reason, xml) {
   emit('change', xml)
@@ -80,8 +100,8 @@ function handleChange(model, reason, xml) {
       ref="studioRef"
       :xml="props.initialXml"
       engine="flowable"
+      :config="config"
       mode="design"
-      :allowed-edge-types="['sequenceFlow']"
       :allowed-modes="['design', 'viewer']"
       theme="auto"
       @change="handleChange"
@@ -97,6 +117,11 @@ import { useRef } from 'react'
 import { BpmnStudio } from '@bpmn-nova/react'
 import '@bpmn-nova/react/styles.css'
 
+const STUDIO_CONFIG = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
+
 export function WorkflowEditor({ initialXml, saveDraft }) {
   const studioRef = useRef(null)
   return (
@@ -105,8 +130,8 @@ export function WorkflowEditor({ initialXml, saveDraft }) {
         ref={studioRef}
         xml={initialXml}
         engine="flowable"
+        config={STUDIO_CONFIG}
         mode="design"
-        allowedEdgeTypes={['sequenceFlow']}
         allowedModes={['design', 'viewer']}
         theme="auto"
         onChange={(model, reason, xml) => saveDraft(xml)}
@@ -126,13 +151,19 @@ import {
 } from '@bpmn-nova/studio'
 import '@bpmn-nova/studio/styles.css'
 
+const config = {
+  modeling: { allowedEdgeTypes: ['sequenceFlow'] },
+  ui: { controlSize: 'medium' },
+}
+
 const studio = createStudioController({
   model: createEmptyProcess('flowable'),
-  allowedEdgeTypes: ['sequenceFlow'],
+  config,
 })
 const shell = createStudioShell({
   container: document.querySelector('#workflow-studio'),
   studio,
+  config,
   mode: 'design',
   allowedModes: ['design', 'viewer'],
   theme: 'auto',
@@ -155,18 +186,16 @@ This step is complete when the workbench is visible, the initial XML is rendered
 
 ### 4.1 Embed the complete Studio in an existing business workbench
 
-`BpmnStudio` is a complete Header + Palette + Canvas + Properties + Statusbar workbench by default. Preserve that default unless the host already owns a region. To keep the Nova Palette and editing tools, replace only the Header start area and explicitly hide Nova Properties:
+`BpmnStudio` is a complete Header + Palette + Canvas + Properties + Statusbar workbench by default. Preserve that default unless the host already owns a region. Define a stable `studioConfig` object in host code. To keep the Nova Palette and editing tools, replace only the Header start area and explicitly hide Nova Properties:
 
 ```vue
 <BpmnStudio
   ref="studioRef"
   :xml="xml"
   engine="activiti"
+  :config="studioConfig"
   mode="design"
   :allowed-modes="['design']"
-  :allowed-node-types="supportedNodeTypes"
-  :allowed-edge-types="['sequenceFlow']"
-  :regions="{ right: 'hidden' }"
   theme="auto"
   @change="handleChange"
   @selection-change="handleSelectionChange"
@@ -174,23 +203,43 @@ This step is complete when the workbench is visible, the initial XML is rendered
   <template #header-start="{ state, actions }">
     <!-- Host back action, business icon, process name, and type -->
   </template>
-  <template #header-actions="{ actions, mode }">
+  <template #header-actions="{ actions, mode, ui }">
     <!-- Host Validate / Save / Publish actions. Validation calls actions.validate(). -->
   </template>
 </BpmnStudio>
 ```
 
-- Vue uses native `#header-start` / `#header-actions` / `#header` slots. React uses `headerStart` / `headerActions` / `header` render props. Core uses matching DOM Slots.
+- Vue uses native `#header-start` / `#header-actions` / `#header` / `#right` slots. React uses `headerStart` / `headerActions` / `header` / `right` render props. Core uses matching DOM Slots. Native Right support starts in `0.3.5-preview`; inspect the installed declarations before using it.
 - Vue supports `v-model:mode` and `mode-change`; React supports `mode` and `onModeChange`. Framework Header contexts expose the actual reactive `mode`. Core Slots use `getMode()` / `subscribeMode()`.
 - Header Start replaces only the Nova Brand. Header Actions replaces only the default Validate / Import / Export group, so a host can compose Validate / Save / Publish without rebuilding the editing tools. A complete Header replacement calls the public Actions Interface.
 - `actions.validate()` updates Nova's default status summary before emitting a read-only validation result with `source: 'toolbar'`; `shell.validate()` and framework Handle/Expose methods use `source: 'api'`. Vue receives `validation`, React receives `onValidation`, and Core uses `subscribeValidation()`. `valid` means there are no errors; warnings do not block publishing by default.
 - The default Header does not duplicate Fit; use the footer control or `fitView()`.
-- `regions` can hide `header`, `left`, `right`, or `footer` without leaving an empty layout track. Prop changes update the existing Shell; do not rebuild the Canvas.
-- Put a host-owned properties panel beside the Nova root. Use `selection-change` / `onSelectionChange` as its source of truth because it covers nodes, edges, multi-selection, clearing, and keyboard selection. Do not substitute `element-click` / `onElementClick`.
+- `config.ui.regions` can hide `header`, `left`, `right`, or `footer` without leaving an empty layout track. Config changes update the existing Shell; do not rebuild the Canvas.
+- A host panel can replace right content inside Nova, or live beside the Nova root after explicitly hiding the whole region. For an external design panel use `selection-change` / `onSelectionChange`, covering nodes, edges, multi-selection, clearing, and keyboard selection. Do not substitute `element-click` / `onElementClick`. Use the new `panelSelection` context for selection across read-only modes.
 - Join host business configuration by stable BPMN element ID. Saving, publishing, authorization, upload, and server transactions remain host responsibilities.
 - `theme="auto"` explicitly follows the system theme. The compatibility default remains `light`.
 - Vue and React both export standalone `BpmnPalettePanel` for a fully custom layout. Pass the same external Studio Controller to Canvas, Palette, and Properties.
 
+Group static Studio options under `config`: modeling constraints in `config.modeling`, Header layout in `config.ui`, Viewer display defaults in `config.viewer`, and SVG defaults in `config.export`. Keep model/XML, mode/allowedModes/runtime/projection/theme, resolvers, renderers, registries, callbacks, and Slots at the top level. Deprecated top-level configuration aliases remain compatible and explicitly win when the same item is supplied in both places.
+
+`config.ui.controlSize` defaults to `medium` (32px). `small`, `medium`, and `large` map to 28px, 32px, and 40px; Element Plus `default` and Ant Design `middle` both map to Nova `medium`. A host-specific value must be a strict `24px`–`48px` string such as `36px`; numbers, other units, CSS expressions, and out-of-range values are invalid. Header contexts expose read-only `ui.controlSize` and `ui.controlHeight`, while custom actions inherit `--nova-control-height`, `--nova-header-height`, `--nova-control-font-size`, `--nova-control-padding-inline`, `--nova-control-icon-size`, and `--nova-control-radius`. These sizes never change footer zoom, canvas floating controls, Palette, or Properties.
+
+Core Shell and framework handles expose `getConfig()` and `setConfig()`. The setter validates first and updates UI, Viewer, and Export in place without changing Model, XML, History, Selection, Mode, or Viewport. Modeling allowlists are Controller creation invariants; use the existing `setPropertiesProfile()` only for a runtime Profile change.
+
+### 4.2 Sidebar layout and collapse (0.3.5-preview)
+
+Read `SOURCE: docs/CUSTOMIZATION.md`, section `侧栏布局与平滑折叠`, in the co-located `llms-full.txt` before integrating the sidebar interfaces introduced in `0.3.5-preview`. They are not available in the older `0.3.4-preview` package. The host must still provide a computable container height.
+
+- Configure `config.ui.leftPanel/rightPanel.collapsible` (default `true`) and `defaultCollapsed` (wide-layout initialization only, default `false`). `config.ui.rightPanel.layout` defaults to `flex`: Nova supplies a bounded column, the host arranges fixed regions and a `flex: 1; min-height: 0; overflow: auto` body. Use `scroll` for Nova-owned scrolling of the entire content; avoid nested scroll containers unless intentional.
+- Core `slots.right`, Vue `#right`, and React `right` replace only content. Native slots preserve the host application tree and win over same-name Core DOM slots. Do not create another framework root or patch Nova classes. Header/Right contexts share `state`, `mode`, `ui`, and `panelSelection`, plus `studio`, `shell`, and `actions`.
+- Design shows both panels by default; Viewer only the right; Instance hides both. An omitted right region uses mode defaults; explicit `regions.right: 'default'` opts into Instance, while `'hidden'` removes the panel and its toggle. A slot never overrides hidden. Preserve this distinction when reading/updating Config.
+- Collapsed retains an edge toggle; hidden does not. Sidebars animate independently for 200ms and respect reduced motion. The first entry into a Shell container at or below 720px starts collapsible panels collapsed, with separate wide/narrow state memory. Expansion pushes the canvas, never opens a drawer. Content/form/scroll state survives; no automatic Fit occurs. Automatic Viewer projection responds once to the final size.
+- Use `getSidebarState()`, `setSidebarCollapsed(side, collapsed)`, and `subscribeSidebarChange()`. The setter returns `true` only for actual changes; unavailable/redundant requests return `false`. Vue emits `sidebar-change`; React uses `onSidebarChange`. The read-only event contains `side`, `collapsed`, `previousCollapsed`, `mode`, and `source: button | api | responsive | config`.
+- `panelSelection` contains `selection`, `selectedElement`, and `trace`. Core reads/subscribes with `getPanelSelection()` / `subscribePanelSelection()`. Design follows Controller selection; read-only clicks do not rewrite design selection. Do not substitute `state.selection` for the current approval-trace context. Hiding the sidebar does not disable trace clicks, details, or assets.
+- These policies belong to the default Shell, not a complete custom `layout()` or standalone Designer/Viewer. Sidebar UI state must never enter BPMN XML, Model, or History.
+
+### 4.3 Definition-time subtitle presentation
+
 For a host-owned definition-time subtitle, pass `nodeSubtitleResolver` to Studio, Canvas, or Viewer. Return `undefined` for Nova's default subtitle, `null` to remove the row, or a string (including an empty string) as the override. After data inside a stable closure or Map changes, call `refreshPresentation()` on the component handle or Shell. This refresh must not be implemented by mutating a node, re-importing XML, or remounting the component. The resolver applies only to standard Design/Viewer task and container cards and standard SVG fallback; a complete custom renderer wins, and Instance runtime summaries are never overridden.
 
 ## 5. Keep model ownership deterministic
@@ -205,12 +254,16 @@ This step is complete when edit, undo, redo, save, reload, and intentional exter
 
 ## 6. Add host constraints before business use
 
-Production workflow applications usually support a subset of BPMN. Configure `allowedNodeTypes` and `allowedEdgeTypes` on the Studio Controller or framework `BpmnStudio`; these reject unsupported imported models and block node/edge creation outside the host contract. The node allowlist filters Palette entries, but one allowed node type may still have multiple Palette presets. Configure matching Palette and Properties registries when the host needs custom labels or business fields.
+Production workflow applications usually support a subset of BPMN. Configure `config.modeling.allowedNodeTypes` and `config.modeling.allowedEdgeTypes` on the Studio Controller or framework `BpmnStudio`; these reject unsupported imported models and block node/edge creation outside the host contract. The node allowlist filters Palette entries, but one allowed node type may still have multiple Palette presets. Configure matching Palette and Properties registries when the host needs custom labels or business fields.
 
 Use `allowedModes` to expose only host-authorized workbench modes. Runtime changes use `setAllowedModes()` rather than rebuilding the Studio; invalid, empty, or duplicate lists are errors. Pass real Runtime data for instance mode; absence of Runtime data means no approval trace rather than demo business data.
 
 Runtime snapshots store asset references only. The host supplies `runtimeAssetResolver`. BPMN Nova does not execute workflow engines, submit approvals, upload/store attachments, issue permissions, or export PNG/PDF.
 
+For approval-trace integration, read the complete `SOURCE: docs/RUNTIME-INTEGRATION.md` section in the co-located `llms-full.txt` before mapping backend records. It covers instance-bound XML, stable work-item/visit identities, Flowable/Activiti mapping limits, complete approval scenarios, request cancellation, and assets. Runtime data stays top-level; only Studio display configuration belongs in `config.viewer`. Finish this branch only after the guide's relevant integration checks pass; report missing history instead of inventing facts.
+
+Named Runtime type re-exports from the Vue/React facade start in `0.3.5-preview`. Check the installed declarations before using them; the guide gives a Props-based type fallback for older releases. Keep the one-direct-package rule rather than adding Studio for these types.
+
 Read `llms-full.txt` before implementing custom Shell regions, Header composition, Actions, Palette, Properties, Context Menu, Renderer, Runtime, theme, or SVG export behavior. Use only public exports from the one selected package or supported Studio subpaths. `llms-full.txt` is generated by the Nova repository and must not be edited by hand.
 
 ## 7. Verify the integration
@@ -224,13 +277,21 @@ Run the target application's existing non-destructive quality commands, includin
 5. Intentional external XML replacement loads once and resets history once.
 6. Disallowed node types are unavailable and rejected by import/creation commands; disallowed modes are not rendered and `setMode()` returns `false` without changing state.
 7. Theme changes update the existing instance.
-8. Unmount/remount leaves no duplicate listeners, overlays, or framework instances.
-9. Browser Console has no errors.
-10. If a subtitle resolver is used, verify override, `undefined`, `null`, SVG parity, and that `refreshPresentation()` preserves XML, history, selection, scope, zoom, pan, theme, and mode. Verify Instance summaries are unchanged.
+8. Default `medium`, presets, and a custom value such as `36px` resize only Header controls; invalid `config.ui.controlSize` leaves the previous DOM and configuration intact.
+9. Unmount/remount leaves no duplicate listeners, overlays, or framework instances.
+10. Browser Console has no errors.
+11. If a subtitle resolver is used, verify override, `undefined`, `null`, SVG parity, and that `refreshPresentation()` preserves XML, history, selection, scope, zoom, pan, theme, and mode. Verify Instance summaries are unchanged.
+12. If sidebars are used, verify independent collapse, narrow containers, reduced motion, keyboard focus, host form/scroll preservation, Flex/Scroll behavior, native slot updates, Instance defaults, and selection/event consistency. Keep XML, history, and viewport invariant during ordinary collapse; record automatic projection changes separately.
 
 The installation is complete only when the package is present, the production build succeeds, and the relevant browser checks pass. Report any unverified branch explicitly.
 
+## Maintainer release policy
+
+Before changing Nova package versions, publishing, or recovering a partial release, read the complete `SOURCE: docs/NPM-PACKAGES.md` section in the co-located `llms-full.txt` (or that file in the source repository). It defines mandatory lockstep versions and full releases of all three public packages, including unchanged packages, plus Registry completion checks. This is a maintainer rule, not an instruction for host applications to install all three packages or authorization to publish without a user request.
+
 ## Reference
 
 - `README.md`: human-facing product overview and quick start.
 - `llms-full.txt`: complete generated AI context containing setup, component, Interface, customization, publishing, and architecture documentation.
+- `docs/RUNTIME-INTEGRATION.md`: authoritative approval-trace guide in the source repository; the full content also ships inside every public package's `llms-full.txt`.
+- `docs/NPM-PACKAGES.md`: authoritative global version and full-release policy, including partial-release recovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmn-nova/react",
-  "version": "0.3.3-preview",
+  "version": "0.3.5-preview",
   "description": "React components and hooks for BPMN Nova Designer, Viewer, Studio and Properties.",
   "keywords": [
     "bpmn",
@@ -42,7 +42,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@bpmn-nova/studio": "0.3.3-preview"
+    "@bpmn-nova/studio": "0.3.5-preview"
   },
   "engines": {
     "node": ">=18"