# `<llumi-bpmn>`

Renders a [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) diagram from a pug-syntax definition string,
with automatic layout, interactive pan/zoom, element markers (highlight, focus, errors, warnings),
and click-to-select events.

## Usage

Pass the BPMN definition as the element's **light-DOM text content** (slot):

```html
<llumi-bpmn>
  doctype xml
  definitions(id="defs1" targetNamespace="http://example.com/simple")
    process(id="proc1" name="Simple Process" isExecutable="true")
      startEvent(id="start1")
      task(id="task1" name="Do Something")
      endEvent(id="end1")
      sequenceFlow(id="f1" sourceRef="start1" targetRef="task1")
      sequenceFlow(id="f2" sourceRef="task1" targetRef="end1")
</llumi-bpmn>
```

The diagram source is re-read whenever the text content changes. Whitespace is
automatically trimmed and dedented.

## Properties / Attributes

| Name | Attribute | Type | Default | Description |
|------|-----------|------|---------|-------------|
| `autoLayout` | `auto-layout` | `boolean` | `true` | Run the built-in layout engine to assign positions. Default is **true** because the pug syntax carries no position data (no BPMNDiagram / Bounds section needed). Set to `false` only when the source already contains a `bpmndi:BPMNDiagram` section with explicit coordinates. |
| `highlight` | — | `string[]` | `[]` | IDs of elements to highlight (blue tint). |
| `focusId` | — | `string \| undefined` | `undefined` | ID of the element that receives the focus marker (strong blue border). Named `focusId` rather than `focus` because a `focus` property would shadow the native `HTMLElement.focus()` method. |
| `errors` | — | `string[]` | `[]` | IDs of elements to mark as errors (red tint). |
| `warnings` | — | `string[]` | `[]` | IDs of elements to mark as warnings (orange tint). |
| `centerOn` | — | `string \| undefined` | `undefined` | ID of the element to animate the viewport to. Animates with a smooth ease-out transition each time the value changes. |

### `auto-layout` details

The pug syntax intentionally omits layout information. The `pugToXml` parser
auto-injects `<incoming>` / `<outgoing>` child elements from `sequenceFlow`
`sourceRef`/`targetRef` attributes so the layout engine has the graph structure it
needs. You do not need to include a `bpmndi:BPMNDiagram` section, any `Bounds`
elements, or a `collaboration` wrapper.

## Events

| Event | Detail | Bubbles | Composed | When |
|-------|--------|---------|----------|------|
| `llumi-bpmn-select` | `{ type: string; id: string }` | yes | yes | User clicks a BPMN element (task, gateway, event, flow, etc.). |
| `llumi-bpmn-deselect` | — | yes | yes | User clicks the process or collaboration root (background click — deselects any selection). |

Both events cross shadow-DOM boundaries (`composed: true`) so parent documents
can listen on a regular ancestor element.

```js
diagram.addEventListener("llumi-bpmn-select", (e) => {
  console.log(e.detail.type, e.detail.id);
});
diagram.addEventListener("llumi-bpmn-deselect", () => {
  console.log("deselected");
});
```

## CSS Parts

| Part | Description |
|------|-------------|
| `fit-button` | The fit-to-viewport button shown in the top-right toolbar when the diagram renders successfully. |
| `error` | The error box shown when the BPMN definition fails to parse or import. |

## Styling

bpmn-js base CSS (`bpmn-js.css`, `diagram-js.css`) and the element-marker CSS are
**automatically injected** into the document when the component connects. No CSS
import is required from the consumer.

## Interaction

- **Pan:** two-finger scroll (trackpad) / left-drag.
- **Zoom:** pinch (trackpad) or ctrl+wheel / scroll.
- **Fit:** the top-right button resets the viewport to fit all elements.
- **Auto-fit:** the diagram fits its container on load and re-fits when the
  container resizes — until you pan or zoom, after which your view is preserved
  (clicking fit re-enables auto-fit).
- **Click element:** fires `llumi-bpmn-select`.
- **Click background:** fires `llumi-bpmn-deselect`.

## Dependencies

`bpmn-js`, `bpmn-moddle`, `character-parser`, `is-expression`, `min-dash`, `graph-by-ivan-tulaev`. The component lazy-loads the bpmn-js viewer on
first render for optimal bundle size.

Consume via:

```js
import "@llumi/design-system/bpmn";
```

## Known limitations

- **Auto-layout + data objects in a collaboration.** When `auto-layout` is on,
  the layout engine cannot place `dataObject`/`dataObjectReference` elements that
  live inside a process belonging to a collaboration (a process with pools) — it
  throws `Element <id> is not associated with any leaf in lane tree`. Data objects
  in a standalone (non-collaboration) process lay out fine. To show data objects
  inside pools, supply pre-computed `bpmndi:` coordinates and set `auto-layout`
  off.

## Pug schema reference

See [`bpmn-specifications.md`](./bpmn-specifications.md) for the full pug-syntax
schema covering all BPMN 2.0 element types, attributes, and nesting rules.