@bpmn-nova/react 0.3.1-preview → 0.3.2-preview

package/llms.txt

@@ -0,0 +1,225 @@
+# BPMN Nova integration runbook
+
+> BPMN Nova is a framework-neutral BPMN 2.0 design, viewing, approval-trace, theme, and pure SVG export toolkit for Flowable and Activiti applications. The current release is Preview.
+
+Use this file as the executable starting point for installing BPMN Nova. Complete the steps in order. Read the co-located `llms-full.txt` only when the selected branch needs advanced customization or complete Interface reference.
+
+## 1. Resolve the target application
+
+Before installing or editing code:
+
+1. Locate the target application's `package.json`, source entry, and build configuration.
+2. In a monorepo, select the concrete Web application instead of the workspace root.
+3. Determine whether that application uses Vue, React, or another browser JavaScript/TypeScript stack.
+4. Determine its existing package manager from `packageManager` and lockfiles. Preserve that package manager.
+5. Inspect the application lifecycle and layout so the visual component is mounted only in the browser and receives a computable height.
+
+This step is complete only when one application root, one framework branch, and one package manager are unambiguous. If any is ambiguous, stop before installing and ask the user to identify the target application and framework. Missing framework evidence is not evidence of a Vanilla application.
+
+## 2. Select exactly one public package
+
+| Target application | Public package | Minimum host version |
+| --- | --- | --- |
+| Vue or Nuxt | `@bpmn-nova/vue` | Vue 3.3 |
+| React, Next.js, or Remix | `@bpmn-nova/react` | React 18 |
+| Another confirmed browser JavaScript/TypeScript stack | `@bpmn-nova/studio` | Node 18 for installation/build |
+
+Preserve an already installed public package when it matches the target stack. Do not install historical internal packages such as Core, Designer, Viewer, Runtime, Theme, Export SVG, Properties, or engine profiles. Studio exposes supported `/designer`, `/viewer`, `/runtime`, `/theme`, `/export-svg`, `/flowable`, and `/activiti` subpaths.
+
+Install with the application's existing package manager:
+
+```bash
+npm install @bpmn-nova/vue@preview
+pnpm add @bpmn-nova/vue@preview
+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.
+
+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
+
+Choose the smallest Interface that owns the required experience:
+
+| Requirement | Interface |
+| --- | --- |
+| Complete workbench with Palette, Canvas, Properties, history, import/export, and optional viewing modes | `BpmnStudio` or `createStudioShell()` |
+| Embeddable design canvas without the complete workbench | `BpmnDesigner` |
+| Read-only BPMN, approval path, or mobile timeline | `BpmnViewer` |
+| Custom host layout with official Controller, Canvas, Palette, and Properties modules | external Studio Controller plus adapter components/registries |
+
+Use `engine="flowable"` or `engine="activiti"` explicitly from the host workflow engine. Do not infer the engine from BPMN XML namespace declarations alone.
+
+## 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.
+
+### Vue
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { BpmnStudio } from '@bpmn-nova/vue'
+import '@bpmn-nova/vue/styles.css'
+
+const props = defineProps({ initialXml: String })
+const emit = defineEmits(['change'])
+const studioRef = ref(null)
+
+function handleChange(model, reason, xml) {
+  emit('change', xml)
+}
+</script>
+
+<template>
+  <div style="height: min(760px, calc(100vh - 96px)); min-height: 520px">
+    <BpmnStudio
+      ref="studioRef"
+      :xml="props.initialXml"
+      engine="flowable"
+      mode="design"
+      :allowed-edge-types="['sequenceFlow']"
+      :allowed-modes="['design']"
+      theme="auto"
+      @change="handleChange"
+    />
+  </div>
+</template>
+```
+
+### React
+
+```jsx
+import { useRef } from 'react'
+import { BpmnStudio } from '@bpmn-nova/react'
+import '@bpmn-nova/react/styles.css'
+
+export function WorkflowEditor({ initialXml, saveDraft }) {
+  const studioRef = useRef(null)
+  return (
+    <div style={{ height: 'min(760px, calc(100vh - 96px))', minHeight: 520 }}>
+      <BpmnStudio
+        ref={studioRef}
+        xml={initialXml}
+        engine="flowable"
+        mode="design"
+        allowedEdgeTypes={['sequenceFlow']}
+        allowedModes={['design']}
+        theme="auto"
+        onChange={(model, reason, xml) => saveDraft(xml)}
+      />
+    </div>
+  )
+}
+```
+
+### Vanilla JavaScript/TypeScript
+
+```js
+import {
+  createEmptyProcess,
+  createStudioController,
+  createStudioShell,
+} from '@bpmn-nova/studio'
+import '@bpmn-nova/studio/styles.css'
+
+const studio = createStudioController({
+  model: createEmptyProcess('flowable'),
+  allowedEdgeTypes: ['sequenceFlow'],
+})
+const shell = createStudioShell({
+  container: document.querySelector('#workflow-studio'),
+  studio,
+  mode: 'design',
+  allowedModes: ['design'],
+  theme: 'auto',
+})
+
+const unsubscribe = studio.subscribe((event) => {
+  if (event.type === 'modelChanged') saveDraft(studio.exportXml())
+})
+
+export function disposeWorkflowStudio() {
+  unsubscribe()
+  shell.destroy()
+  studio.destroy()
+}
+```
+
+The Vanilla container needs the same explicit height as the framework examples.
+
+This step is complete when the workbench is visible, the initial XML is rendered, and one edit produces a non-empty exported XML value.
+
+### 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:
+
+```vue
+<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"
+>
+  <template #header-start="{ state, actions }">
+    <!-- Host back action, business icon, process name, and type -->
+  </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.
+- `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.
+
+## 5. Keep model ownership deterministic
+
+- Treat `xml` and `model` as external replacement inputs. Use the emitted/exported XML as the draft output.
+- A local edit followed by the host echoing the same exported XML must not re-import the model or clear Undo/Redo history.
+- Replace `xml` when the host intentionally loads another server revision or another process.
+- For a custom host layout, create one external Studio Controller and pass the same instance to Canvas, Palette, and Properties. The creator owns that Controller and destroys it.
+- Use stable BPMN element IDs as the join key for host business configuration. BPMN Nova does not own the host's persistence transaction.
+
+This step is complete when edit, undo, redo, save, reload, and intentional external XML replacement all produce the expected model without duplicate remounts.
+
+## 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.
+
+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.
+
+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.
+
+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
+
+Run the target application's existing non-destructive quality commands, including its type check and production build. Then verify in a real browser:
+
+1. The component fills its intended container and has complete styles.
+2. Existing BPMN XML imports without losing IDs, names, topology, or DI positions.
+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.
+7. Theme changes update the existing instance.
+8. Unmount/remount leaves no duplicate listeners, overlays, or framework instances.
+9. Browser Console has no errors.
+
+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.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmn-nova/react",
-  "version": "0.3.1-preview",
+  "version": "0.3.2-preview",
   "description": "React components and hooks for BPMN Nova Designer, Viewer, Studio and Properties.",
   "keywords": [
     "bpmn",
@@ -26,13 +26,15 @@
   "files": [
     "dist",
     "README.md",
+    "llms.txt",
+    "llms-full.txt",
     "LICENSE"
   ],
   "sideEffects": [
     "./dist/styles.css"
   ],
   "scripts": {
-    "prepack": "node ../../scripts/build-packages.mjs --package react",
+    "prepack": "node ../../scripts/check-public-package-versions.mjs && node ../../scripts/build-ai-docs.mjs --check && node ../../scripts/build-packages.mjs --package react",
     "prepublishOnly": "node ../../scripts/guard-preview-publish.mjs"
   },
   "peerDependencies": {
@@ -40,7 +42,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@bpmn-nova/studio": "0.3.1-preview"
+    "@bpmn-nova/studio": "0.3.2-preview"
   },
   "engines": {
     "node": ">=18"