@dskripchenko/flow 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# @dskripchenko/flow
+
+## 1.0.0 — 2026-10-26
+
+First release: process and state-machine graphs — a viewer with live
+monitoring, drill-down and enable/disable switches, and a visual editor. The
+core has no runtime dependencies; the Vue components are built on
+`@dskripchenko/ui`.
+
+**Core (`@dskripchenko/flow`)**
+
+- A versioned JSON model (`version: 1`) with nodes, edges, ports, groups and
+  inline or referenced sub-processes; `parseGraph` with JSON-pointer errors,
+  `stringifyGraph`; JSON Schemas for the model and the monitoring snapshot.
+- Built-in node types `start`, `end`, `state`, `task`, `decision`,
+  `subprocess`, `note` and a registry for custom types (shape, size, ports,
+  icon, locked).
+- `validateGraph`: errors for duplicate ids and broken references or ports,
+  warnings for missing start/end, unreachable steps, dead ends and empty labels.
+- `layoutGraph`: a deterministic layered layout (LR/TB) that keeps fixed
+  positions and places the rest; orthogonal routing by default (or smooth
+  curves over the same corridors) that never passes through other nodes or
+  foreign groups; back edges in lanes of a channel beside the graph; edge
+  labels kept off nodes and off each other; ports, spread anchors, self
+  loops and group frames.
+- Monitoring: the snapshot format, `reduceMonitor` / `mergeSnapshot`,
+  `isStale`, `pathEdges`, `statusSummary`; `createPoller` with visibility
+  pause, exponential backoff and cancellation.
+- Editing: `applyCommand` over serialisable commands, `History` with undo,
+  redo and merging, copy/paste fragments, align, distribute, auto layout as a
+  command.
+- Viewport helpers: `fitView`, `zoomAt`, `nearestInDirection`.
+
+**Mermaid (`@dskripchenko/flow/mermaid`)**
+
+- `fromMermaid` for `stateDiagram-v2` (composites become sub-processes, notes
+  become note nodes) and `flowchart` (shapes map to types, subgraphs to
+  groups), through `@dskripchenko/diagrams`' parser.
+
+**Vue (`@dskripchenko/flow/vue`)**
+
+- `FlowView`: pan, zoom, pinch, fit, minimap; opens at 100 % on the current
+  step (or whole when it fits at 85 % or more), keeping nodes clear of the
+  overlays; `edgeStyle: 'orthogonal' | 'smooth'`;
+  monitoring from `state` or `poll` with the active step, the instance path,
+  counters, error badges, a status line with last update, staleness and a
+  summary; enable/disable switches with optimistic update and rollback;
+  drill-down with a breadcrumb and `loadSubgraph`; a details drawer with
+  slots; custom node renderers; keyboard navigation and ARIA labels; en/ru.
+- `FlowEditor`: palette, drag-to-connect with snapping, reconnect and
+  detach, grid snapping, multi-select, align/distribute, undo/redo and
+  clipboard shortcuts, a properties panel, a validation panel, context menus,
+  JSON and Mermaid import, JSON export, in-place sub-process editing, locked
+  types, a narrow-screen layout.
+- `mountFlow`, `mountFlowEditor`, with an optional `appContext` to render
+  inside a host app (its providers reach the component).
+- Host integration: `state` is the initial value when `poll` is set (polled
+  snapshots replace it); `pollParams` reach `poll.fetch` as
+  `context.params` and restart polling at once when they change;
+  `FlowEditor`'s `locked: string[]` locks node types; nodes added from the
+  palette land on the nearest free grid spot (next along the flow from the
+  selection, else mid-view), scrolled into view and selected
+  (`findFreeSpot` in the core).
+
+**Standalone** — `dist/standalone.js` with `DskFlow.mountFlow` and
+`DskFlow.mountFlowEditor`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Skripchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @dskripchenko/flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/dskripchenko/flow/actions/workflows/ci.yml/badge.svg)](https://github.com/dskripchenko/flow/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@dskripchenko/flow.svg)](https://www.npmjs.com/package/@dskripchenko/flow)
+[![license](https://img.shields.io/npm/l/@dskripchenko/flow.svg)](LICENSE)
+
+Process and state-machine graphs: draw them, watch running instances move
+through them, switch steps on and off, drill into sub-processes, and edit them
+visually. The core has **no runtime dependencies**; the Vue components are
+built on [`@dskripchenko/ui`](https://github.com/dskripchenko/ui).
+
+```vue
+<script setup lang="ts">
+import { FlowView } from '@dskripchenko/flow/vue'
+import '@dskripchenko/ui/styles/all.css'
+import '@dskripchenko/flow/style.css'
+
+const poll = {
+  intervalMs: 5000,
+  fetch: (signal: AbortSignal) => fetch('/api/orders/42/state', { signal }).then((r) => r.json()),
+}
+</script>
+
+<template>
+  <FlowView :graph="orderProcess" :poll="poll" toggleable :on-toggle="saveToggle" style="height: 600px" />
+</template>
+```
+
+## What is inside
+
+**Core** (`@dskripchenko/flow`, plain TypeScript, no DOM)
+
+- A versioned JSON model: nodes (`start`, `end`, `state`, `task`, `decision`,
+  `subprocess`, `note`, or your own types), edges with labels, conditions and
+  ports, groups, inline or referenced sub-processes. JSON Schemas included.
+- Validation: duplicate ids, broken references and ports (errors); missing
+  start/end, unreachable steps, dead ends (warnings). Cycles are fine.
+- Layout: a layered (Sugiyama) layout, left-to-right or top-to-bottom,
+  deterministic, around nodes you have placed yourself; orthogonal (or
+  smooth) edges that never cut through other nodes or groups, with back
+  edges (retries, resends) in their own lanes beside the graph.
+- Monitoring: a snapshot format, a pure reducer, stale detection, and a poller
+  that pauses in hidden tabs, backs off on errors and cancels requests.
+- Editing: undoable commands, history with merging, copy/paste, align,
+  distribute, auto layout as one step.
+
+**Vue** (`@dskripchenko/flow/vue`)
+
+- `FlowView` — pan, zoom, pinch, fit, minimap; live state with the active
+  step, the instance's path, counters, error badges, last-updated and stale
+  indicators; enable/disable switches with rollback on failure; drill-down
+  with a breadcrumb; a details drawer with a slot for your content; custom
+  node components; keyboard navigation and ARIA labels; light and dark.
+- `FlowEditor` — palette (drag or press), drag-to-connect with snapping,
+  reconnecting, moving on a grid, multi-select, align/distribute, undo/redo
+  with shortcuts, a properties panel, a validation panel, context menus,
+  JSON and Mermaid import, sub-process editing, locked node types.
+
+**Mermaid** (`@dskripchenko/flow/mermaid`) — a model from `stateDiagram-v2` or
+`flowchart` source (composite states become sub-processes).
+
+**Standalone** — one `<script>`: `DskFlow.mountFlow('#el', { graph, poll })`.
+
+## Documentation
+
+| | English | Русский | Deutsch | 中文 |
+|---|---|---|---|---|
+| Getting started | [en](docs/en/getting-started.md) | [ru](docs/ru/getting-started.md) | [de](docs/de/getting-started.md) | [zh](docs/zh/getting-started.md) |
+| Model | [en](docs/en/model.md) | [ru](docs/ru/model.md) | [de](docs/de/model.md) | [zh](docs/zh/model.md) |
+| Monitoring and polling | [en](docs/en/monitoring.md) | [ru](docs/ru/monitoring.md) | [de](docs/de/monitoring.md) | [zh](docs/zh/monitoring.md) |
+| Vue components | [en](docs/en/vue.md) | [ru](docs/ru/vue.md) | [de](docs/de/vue.md) | [zh](docs/zh/vue.md) |
+| Editor | [en](docs/en/editor.md) | [ru](docs/ru/editor.md) | [de](docs/de/editor.md) | [zh](docs/zh/editor.md) |
+| Host integration | [en](docs/en/integration.md) | [ru](docs/ru/integration.md) | [de](docs/de/integration.md) | [zh](docs/zh/integration.md) |
+| Standalone | [en](docs/en/standalone.md) | [ru](docs/ru/standalone.md) | [de](docs/de/standalone.md) | [zh](docs/zh/standalone.md) |
+
+## Development
+
+```bash
+pnpm install
+pnpm dev              # playground: ?view=monitor | editor | large | empty, &theme=dark, &locale=ru
+pnpm test             # unit and component tests
+pnpm check:browser    # Playwright: rendering, geometry, interactions, screenshots
+pnpm lint && pnpm typecheck && pnpm build
+```
+
+## License
+
+[MIT](LICENSE)