@bpmnkit/docspack 0.0.5 → 1.0.0

package/.llms/chunks/packages.feel.api-reference.md

@@ -0,0 +1,34 @@
+# @bpmnkit/feel — API Reference
+
+| Export | Signature | Description |
+|---|---|---|
+| `parseExpression` | `(src: string) => ParseResult` | Parse an expression |
+| `parseUnaryTests` | `(src: string) => ParseResult` | Parse a DMN input entry |
+| `evaluate` | `(node, ctx: EvalContext) => FeelValue` | Evaluate a parsed expression |
+| `evaluateUnaryTests` | `(node, input, ctx) => boolean` | Test an input against unary tests |
+| `evaluateUnaryTest` | `(node, input, ctx) => boolean` | A single unary test |
+| `tokenize` | `(src: string) => FeelToken[]` | Raw token stream |
+| `formatFeel` | `(node, opts?) => string` | Pretty-print a **parsed node** |
+| `annotate` | `(src: string) => AnnotatedToken[]` | Tokens classified for highlighting |
+| `highlightToHtml` | `(src: string) => string` | Tokens wrapped in `<span>` elements |
+| `highlightFeel` | `(src: string) => string` | Alias for `highlightToHtml` |
+
+### `ParseResult`
+
+```typescript
+interface ParseResult {
+  ast: FeelNode | null;
+  errors: ParseError[]; // { message, start, end }
+}
+```
+
+### Types and guards
+
+`FeelValue` is the union every evaluation produces. The structured members —
+`FeelDate`, `FeelTime`, `FeelDateTime`, `FeelDayTimeDuration`,
+`FeelYearsMonthsDuration`, `FeelRange`, `FeelContext`, `FeelFunction` — each come with a
+type guard (`isFeelDate`, `isFeelRange`, …), plus `getProperty` for path access. Import them
+by name from the package root.
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.feel.formatting-and-highlighting.md

@@ -0,0 +1,24 @@
+# @bpmnkit/feel — Formatting and highlighting
+
+`formatFeel` pretty-prints — note that it takes a **parsed node**, not source text:
+
+```typescript
+import { parseExpression, formatFeel } from "@bpmnkit/feel";
+
+formatFeel(parseExpression("if  x>10 then  1 else 2").ast!);
+```
+
+`annotate` classifies source into typed tokens, which is what an editor wants:
+
+```typescript
+import { annotate } from "@bpmnkit/feel";
+
+annotate("x > 1")[0];
+// { kind: "variable", value: "x", start: 0, end: 1 }
+```
+
+`highlightToHtml` wraps those tokens in `<span class="feel-…">` elements for a ready-made
+highlighter. `highlightFeel` is an alias for it, kept for compatibility.
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.feel.installation.md

@@ -0,0 +1,45 @@
+# @bpmnkit/feel — Installation
+
+```sh
+npm install @bpmnkit/feel
+```
+
+
+## Parsing and evaluating
+
+Parsing and evaluation are separate steps, so you can parse once and evaluate many times, and
+so a syntax error is a value rather than an exception.
+
+```typescript
+import { parseExpression, evaluate } from "@bpmnkit/feel";
+
+const parsed = parseExpression("amount * 1.2 + fee");
+
+if (parsed.errors.length === 0) {
+  const result = evaluate(parsed.ast!, { vars: { amount: 100, fee: 5 } });
+  console.log(result); // 125
+}
+```
+
+`evaluate` takes an **`EvalContext`**, not a bare object — variables live under `vars`:
+
+```typescript
+interface EvalContext {
+  /** The variables the expression may reference. */
+  vars: Record<string, FeelValue>;
+  /** Enclosing scope, searched when `vars` has no match. */
+  parent?: EvalContext;
+  /** The value `?` refers to, used by unary tests. */
+  input?: FeelValue;
+}
+```
+
+Parse errors carry their position, so an editor can underline them:
+
+```typescript
+parseExpression("1 +").errors;
+// [{ message: "Expected expression after '+'", start: 3, end: 4 }]
+```
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.feel.overview.md

@@ -0,0 +1,15 @@
+# @bpmnkit/feel — Overview
+
+`@bpmnkit/feel` is a complete implementation of FEEL (Friendly Enough Expression Language), the
+expression language DMN decision tables and Camunda 8 condition expressions are written in.
+
+It is four things behind one entry point: a **lexer**, a recursive-descent **parser**, an AST
+**evaluator** with 88 built-in functions, and a **formatter** and **syntax highlighter** for
+editors. It has no dependencies and runs unchanged in Node.js and the browser.
+
+Everything else in BPMN Kit that has to understand an expression uses it — gateway conditions
+in `@bpmnkit/core`'s optimizer, the simulator in `@bpmnkit/engine`, the FEEL playground plugin,
+and DMN evaluation.
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.feel.stability.md

@@ -0,0 +1,7 @@
+# @bpmnkit/feel — Stability
+
+`@bpmnkit/feel` carries the [1.0 stability promise](/docs/getting-started/stability): its
+exports will not change shape without a major version.
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.feel.unary-tests.md

@@ -0,0 +1,46 @@
+# @bpmnkit/feel — Unary tests
+
+A DMN input entry is not an expression but a **unary test** — `> 5`, `"gold","silver"`,
+`[1..10]` — evaluated against an input value. They have their own parse and evaluate pair.
+
+```typescript
+import { parseUnaryTests, evaluateUnaryTests } from "@bpmnkit/feel";
+
+const test = parseUnaryTests('"gold","silver"');
+
+evaluateUnaryTests(test.ast!, "gold", { vars: {} });   // true
+evaluateUnaryTests(test.ast!, "bronze", { vars: {} }); // false
+```
+
+
+## What the language covers
+
+```typescript
+const run = (src: string, vars = {}) =>
+  evaluate(parseExpression(src).ast!, { vars });
+
+run('upper case("abc")');            // "ABC"
+run('contains("foobar", "oo")');     // true
+run("sum([1, 2, 3])");               // 6
+run("[1, 2, 3, 4][item > 2]");       // [3, 4]  — list filter
+run("{ a: 1, b: { c: 2 } }.b.c");    // 2       — context literal and path
+run("[1..10]");                      // a range value
+run('string length("héllo")');       // 5       — code points, not bytes
+```
+
+- **Temporal types** — `date`, `time`, `date and time`, `duration` and
+  `years and months duration`, as structured values rather than strings:
+
+  ```typescript
+  run('date and time("2026-01-01T10:00:00")');
+  // { type: "date-time", date: { type: "date", year: 2026, month: 1, day: 1 },
+  //   time: { type: "time", hour: 10, minute: 0, second: 0 } }
+  ```
+
+- **Ranges** — `[1..10]`, `(0..1)`, and the fourteen DMN range functions that compare them
+  (`before`, `after`, `meets`, `met by`, `overlaps`, `during`, `includes`, `coincides`, …).
+- **88 built-in functions** across strings, numbers, lists, contexts and temporals.
+- **Context literals and paths**, including nested access and filters.
+
+---
+Source: https://bpmnkit.com/docs/packages/feel

package/.llms/chunks/packages.plugins.installation.md

@@ -0,0 +1,28 @@
+# @bpmnkit/plugins — Installation
+
+```sh
+npm install @bpmnkit/plugins @bpmnkit/canvas
+```
+
+
+## Using a plugin
+
+Most plugins are a factory you call and hand to the canvas:
+
+```typescript
+import { BpmnCanvas } from "@bpmnkit/canvas";
+import { createMinimapPlugin } from "@bpmnkit/plugins/minimap";
+import { createZoomControlsPlugin } from "@bpmnkit/plugins/zoom-controls";
+
+const canvas = new BpmnCanvas({
+  container: document.getElementById("app")!,
+  xml,
+  plugins: [createMinimapPlugin(), createZoomControlsPlugin()],
+});
+```
+
+Plugins compose: they are independent, order-insensitive unless they say otherwise, and each
+one cleans up after itself when the canvas is destroyed.
+
+---
+Source: https://bpmnkit.com/docs/packages/plugins

package/.llms/chunks/packages.plugins.overview.md

@@ -0,0 +1,18 @@
+# @bpmnkit/plugins — Overview
+
+`@bpmnkit/plugins` is the capability layer above `@bpmnkit/canvas` and `@bpmnkit/editor`. The
+canvas draws a diagram and exposes a `CanvasApi`; a plugin is anything that takes that API and
+adds something — an overlay, a panel, a keyboard mode, a side effect on save.
+
+Every plugin ships behind **its own entry point**, so a viewer that wants a minimap and
+nothing else pays for a minimap and nothing else:
+
+```typescript
+import { createMinimapPlugin } from "@bpmnkit/plugins/minimap";
+```
+
+There is deliberately **no root export**. `import … from "@bpmnkit/plugins"` does not resolve,
+because a barrel would pull all thirty-four into every bundle that wanted one.
+
+---
+Source: https://bpmnkit.com/docs/packages/plugins

package/.llms/chunks/packages.plugins.styles.md

@@ -0,0 +1,26 @@
+# @bpmnkit/plugins — Styles
+
+Plugins that render their own UI export their CSS as a string and an injector — for example
+`FORM_VIEWER_CSS` and `injectFormViewerStyles` from `form-viewer`. The injectors are
+id-guarded, so calling one twice is free, and a host that would rather ship the CSS itself can
+take the string instead.
+
+Brand colours come from `@bpmnkit/ui` tokens with hex fallbacks, so a plugin looks right
+standalone and themes correctly inside an app that sets them.
+
+
+## Stability
+
+`@bpmnkit/plugins` carries the [1.0 stability promise](/docs/getting-started/stability): the
+entry points listed above, and the exports and option types they name, will not change shape
+without a major version.
+
+Two clarifications, because a plugin package is where the edges are:
+
+- **Adding a plugin is a minor.** A new entry point breaks nobody.
+- **Rendered DOM and class names are not API.** How a panel is laid out, which elements it
+  builds, and the class names inside it are presentation. Style through the documented CSS
+  custom properties rather than by reaching into the markup.
+
+---
+Source: https://bpmnkit.com/docs/packages/plugins

package/.llms/chunks/packages.plugins.what-is-available.md

@@ -0,0 +1,68 @@
+# @bpmnkit/plugins — What is available
+
+**Navigation and view**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `minimap` | `createMinimapPlugin` | Overview panel; click to pan |
+| `zoom-controls` | `createZoomControlsPlugin` | Zoom in/out/fit buttons |
+| `flow-navigation` | `createFlowNavigationPlugin` | Keyboard cursor that walks the sequence flows |
+| `model-navigation` | `createModelNavigationPlugin` | Drill into sub-processes and call activities |
+| `presentation` | `createPresentationPlugin` | Step through a process as slides |
+| `story-view` | `createStoryViewPlugin` | The process as readable prose cards |
+| `ascii-view` | `createAsciiViewPlugin` | The diagram as text, via `@bpmnkit/ascii` |
+| `watermark` | `createWatermarkPlugin` | A mark over the canvas |
+
+**Editing**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `config-panel` | `createConfigPanelPlugin` | Property panel shell |
+| `config-panel-bpmn` | `createConfigPanelBpmnPlugin` | The BPMN property editors themselves |
+| `command-palette` | `createCommandPalettePlugin` | ⌘K palette for a viewer |
+| `command-palette-editor` | `createCommandPaletteEditorPlugin` | The editor's own commands |
+| `main-menu` | `createMainMenuPlugin` | Menu bar |
+| `tabs` | `createTabsPlugin`, `InMemoryFileResolver` | Multi-file tabs |
+| `history` | `saveCheckpoint`, `listCheckpoints`, `createHistoryPanel` | Named checkpoints |
+| `storage` | `createStoragePlugin` | Persistence, with a host-supplied backend |
+| `storage-tabs-bridge` | `createStorageTabsBridge` | Wires those two together |
+| `element-docs` | `createElementDocsPlugin` | Inline BPMN reference for the selected element |
+
+**Correctness**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `lint` | `createLintPlugin` | Findings on the canvas |
+| `optimize` | `createOptimizePlugin` | The `@bpmnkit/core` optimizer, on the diagram |
+| `pattern-advisor` | `createPatternAdvisorPlugin` | Fifteen pattern rules, with fixes |
+| `variable-flow` | `createVariableFlowPlugin` | Producers and consumers per variable |
+| `diff` | `createBpmnDiff` | Visual diff of two models |
+
+**Execution**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `process-runner` | `createProcessRunnerPlugin` | Simulate, step, chaos mode, scenario tests |
+| `token-highlight` | `createTokenHighlightPlugin` | Token positions on the canvas |
+| `live-mode` | `createLiveModePlugin` | Auto-deploy and live instance overlay |
+| `deploy` | `createDeployPlugin` | Deploy to a cluster, guarded by the optimizer |
+
+**DMN, forms and FEEL**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `dmn-viewer` | `DmnViewer`, `injectDmnViewerStyles` | Render a decision table |
+| `dmn-editor` | `DmnEditor` | Edit one |
+| `form-viewer` | `FormViewer`, `injectFormViewerStyles` | Render a Camunda Form |
+| `form-editor` | `FormEditor` | Edit one |
+| `feel-playground` | `createFeelPlaygroundPlugin`, `buildFeelPlaygroundPanel` | Evaluate FEEL against live variables |
+
+**Integration**
+
+| Entry point | Export | What it adds |
+|---|---|---|
+| `ai-bridge` | `createAiBridgePlugin` | Natural-language edits over the compact model |
+| `connector-catalog` | `createConnectorCatalogPlugin` | Browse and apply `@bpmnkit/connectors` |
+
+---
+Source: https://bpmnkit.com/docs/packages/plugins