@bpmn-nova/react 0.3.2-preview → 0.3.4-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
@@ -51,6 +65,8 @@ Choose the smallest Interface that owns the required experience:
 
 Use `engine="flowable"` or `engine="activiti"` explicitly from the host workflow engine. Do not infer the engine from BPMN XML namespace declarations alone.
 
+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.
+
 ## 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.
@@ -80,7 +96,7 @@ function handleChange(model, reason, xml) {
       engine="flowable"
       mode="design"
       :allowed-edge-types="['sequenceFlow']"
-      :allowed-modes="['design']"
+      :allowed-modes="['design', 'viewer']"
       theme="auto"
       @change="handleChange"
     />
@@ -105,7 +121,7 @@ export function WorkflowEditor({ initialXml, saveDraft }) {
         engine="flowable"
         mode="design"
         allowedEdgeTypes={['sequenceFlow']}
-        allowedModes={['design']}
+        allowedModes={['design', 'viewer']}
         theme="auto"
         onChange={(model, reason, xml) => saveDraft(xml)}
       />
@@ -132,7 +148,7 @@ const shell = createStudioShell({
   container: document.querySelector('#workflow-studio'),
   studio,
   mode: 'design',
-  allowedModes: ['design'],
+  allowedModes: ['design', 'viewer'],
   theme: 'auto',
 })
 
@@ -172,17 +188,25 @@ 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 }">
+    <!-- Host Validate / Save / Publish actions. Validation calls actions.validate(). -->
+  </template>
 </BpmnStudio>
 ```
 
-- Vue uses native `#header-start` / `#header` slots. React uses `headerStart` / `header` render props. Core uses `slots.headerStart` / `slots.header`.
-- Header Start replaces only the Nova Brand. A complete Header replacement calls the public Actions Interface for undo, redo, layout, fit, validation, BPMN import/export, and SVG export.
+- Vue uses native `#header-start` / `#header-actions` / `#header` slots. React uses `headerStart` / `headerActions` / `header` render props. Core uses matching DOM Slots.
+- 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`.
 - 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.
 
+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
 
 - Treat `xml` and `model` as external replacement inputs. Use the emitted/exported XML as the draft output.
@@ -195,9 +219,9 @@ 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. 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 `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.
 
-Use `allowedModes` to expose only host-authorized workbench modes. Pass real Runtime data for instance mode; absence of Runtime data means no approval trace rather than demo business data.
+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.
 
@@ -212,10 +236,11 @@ Run the target application's existing non-destructive quality commands, includin
 3. Create, connect, edit, delete, Undo, and Redo work in design mode.
 4. Change output is persisted and reloads to the same process.
 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()` leaves the current mode unchanged.
+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.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmn-nova/react",
-  "version": "0.3.2-preview",
+  "version": "0.3.4-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.2-preview"
+    "@bpmn-nova/studio": "0.3.4-preview"
   },
   "engines": {
     "node": ">=18"