@foblex/flow 19.0.0 → 19.1.0

package/AI.md

@@ -5,16 +5,13 @@ Use this file as a strict control layer for code generation. Prefer verified pac
 ## What This Library Is
 
 `@foblex/flow` is an Angular-native library for building node-based editors, workflow builders, and interactive graph UIs.
-It provides rendering, connectors, interactions, selection, zoom, and connection drawing. Your app still owns the graph data.
+It provides rendering, connectors, interactions, selection, zoom, and connection drawing. By default your app owns the graph data; the optional `withFlowState()` feature can own the data bookkeeping and undo/redo for an editor.
 
 ## Core Mental Model
 
-- The library does **not** own your graph state.
-- Your app owns nodes, groups, connections, ids, validation, and persistence.
-- Angular templates render the current state.
-- User actions emit events from `fDraggable` or model outputs.
-- Your app updates state.
-- Angular rerenders.
+- **Classic mode (default):** your app owns nodes, groups, connections, validation and persistence. User actions emit events; your handlers update app state; Angular rerenders.
+- **Managed mode (opt-in):** `provideFFlow(withFlowState())` provides `FFlowState`; supported completed gestures update its signals and history automatically. Your app still owns domain fields, validation policy and persistence.
+- Both modes render records through normal Angular templates. `withFlowState()` is optional and does not change classic event behavior when absent.
 
 ## Minimal Working Setup
 
@@ -73,13 +70,13 @@ The default theme is wired by `ng add @foblex/flow` (adds `node_modules/@foblex/
 - `fDraggable` on `<f-flow>`: enables pointer interactions and emits interaction events.
 - `fZoom` on `<f-canvas>`: opt-in wheel / double-click / pinch zoom.
 - `<f-selection-area>`: opt-in rectangle multi-select.
-- `provideFFlow(...)` with features: `withConnectionFlow('click')` (click-to-connect gesture alongside drag; custom gestures implement `IFConnectionFlow` and drive `FCreateConnectionSession`), `withControlScheme(...)` (gesture-to-action mapping, presets `F_DEFAULT_CONTROL_SCHEME`, `F_SCROLL_PAN_CONTROL_SCHEME`, `F_DRAG_SELECT_CONTROL_SCHEME`), `withReflowOnResize(...)` (auto layout on node resize), `withFCanvas(...)` (canvas defaults such as layer order), `withA11y(...)` (enables the keyboard accessibility layer — spatial arrow navigation, grab-move, keyboard connection creation, `Delete` emits `fDeleteSelected`; configurable steps, key bindings `IFA11yKeys`, localizable announcements `IFA11yMessages`; ARIA semantics and the live region are always on even without the feature).
+- `provideFFlow(...)` with features: `withConnectionFlow('click')` (click-to-connect gesture alongside drag; custom gestures implement `IFConnectionFlow` and drive `FCreateConnectionSession`), `withControlScheme(...)` (gesture-to-action mapping, presets `F_DEFAULT_CONTROL_SCHEME`, `F_SCROLL_PAN_CONTROL_SCHEME`, `F_DRAG_SELECT_CONTROL_SCHEME`), `withReflowOnResize(...)` (auto layout on node resize), `withFCanvas(...)` (canvas defaults such as layer order), `withA11y(...)` (keyboard accessibility), and `withFlowState(...)` (managed records plus undo/redo).
 
 ## Hard Rules
 
 - Never invent Inputs, Outputs, methods, directives, or selectors.
 - Do **not** assume React Flow style APIs such as `[nodes]`, `[edges]`, `setNodes()`, `addEdge()`, `useNodesState()`, `<Handle>`, `<Background>`, `<Controls>`, or similar patterns.
-- Do **not** assume a built-in graph store. The app owns state.
+- Do **not** assume managed state unless the component explicitly installs `provideFFlow(withFlowState())`. Without it, the app owns state and handles events.
 - Connections are connector-to-connector, not generic node-to-node edges.
 - Template connections use `fSourceId -> fTargetId` referencing `fConnectorId` values (legacy: `fOutputId -> fInputId` referencing output/input ids).
 - Do **not** interpret `[fNodes]` or `[fConnections]` as graph-state inputs. They are content-projection slot markers used with `ngProjectAs` (see the nested control flow rule below).
@@ -102,11 +99,11 @@ The default theme is wired by `ng add @foblex/flow` (adds `node_modules/@foblex/
 
   Use `"[fNodes]"` for nodes, `"[fGroups]"` for groups, `"[fConnections]"` for connections. A single top-level `@for` / `@if` directly inside `<f-canvas>` needs no wrapper.
 
-- Examples may include app-specific state, layout logic, persistence, undo/redo, toolbars, or validation. Those are example implementations, not built-in package features.
+- Examples may include app-specific layout logic, persistence, toolbars, or validation. Undo/redo is built in only when `withFlowState()` is installed; otherwise it remains application code.
 - Some exports are low-level, compatibility-oriented, or testing-oriented. Do not treat every export from `@foblex/flow` as the recommended app-facing API.
 - If a symbol, selector, event, or behavior is not confirmed in the installed package, say: `not found in @foblex/flow`.
 
-## Correct Usage Pattern
+## Classic State Pattern
 
 - Render nodes and groups from your Angular state using normal Angular templates.
 - Put connectors on the node element itself or on child elements with `fConnector`.
@@ -116,6 +113,35 @@ The default theme is wired by `ng add @foblex/flow` (adds `node_modules/@foblex/
 - Update your own state in those handlers, then let Angular rerender.
 - Use node/group position bindings and change outputs to keep positions in app state when needed.
 
+## Managed State Pattern
+
+Install the state feature at the same component injector as `provideFFlow`, load plain records, and render its signals:
+
+```typescript
+interface EditorNode extends IFStateNode {
+  text: string;
+}
+
+@Component({
+  providers: [provideFFlow(withFlowState())],
+})
+export class Editor {
+  protected readonly state = injectFlowState<EditorNode>();
+
+  constructor() {
+    this.state.load({ nodes: [], groups: [], connections: [] });
+  }
+}
+```
+
+- Bind `state.nodes()`, `state.groups()` and `state.connections()` with `@for`; bind canvas `[position]` and `[scale]` to `state.transform()` when viewport undo/redo is enabled.
+- Supported v1 gestures: create/reassign connection, move nodes/groups, delete selection, external-item creation, optional drop-to-group, selection, and canvas pan/zoom.
+- Rotation, connection waypoint editing, and user resize are not captured by managed state in v1.
+- `state.changes()` increments once when a standalone mutation or outer batch settles. A drag can emit selection at start and move/drop at end while remaining one history step and one `changes()` increment.
+- Use `state.snapshot()` for persistence; `load()` replaces data and resets history.
+- For initial or other application-driven viewport positioning, suppress the event at the canvas helper: `canvas.resetScaleAndCenter(false, false)`. The second `false` means `emitCanvasChange = false`, so managed history is untouched.
+- Connection endpoints are connector ids. Automatic cascade from node/group deletion uses the rendered connector registry; before connectors render, remove known attached connection ids explicitly in the same `state.batch(...)`.
+
 ## Common Silent Failures — Check These First
 
 When the flow compiles but looks wrong, verify in this order:
@@ -133,6 +159,7 @@ When the flow compiles but looks wrong, verify in this order:
 11. **Node moves but its bindings never fire** (`FF1007`): an `fNode` element is nested inside another node element. One `fNode` per node; hierarchy is id-based (`fNodeParentId`), not DOM-based.
 12. **Group behaviors don't apply** (`FF1008`): `fNodeParentId` / `fGroupParentId` references an id no rendered group has.
 13. **Wrong initial viewport** (`FF1009`): `fitToScreen()` / `resetScaleAndCenter()` / `centerGroupOrNode()` called before nodes were rendered — call them from `(fNodesRendered)` (earliest safe) or `(fFullRendered)`.
+14. **Initial centering appears in managed undo history**: call `resetScaleAndCenter(false, false)` (or pass `emitCanvasChange: false` to another viewport helper) for an application-driven transform.
 
 To verify programmatically: listen to `(fFullRendered)` on `<f-flow>`, then call `flow.getState()` and assert every declared connection resolved to existing connectors.
 
@@ -167,6 +194,7 @@ See [STYLING.md](./STYLING.md).
 - Docs index for agents: https://flow.foblex.com/llms.txt
 - Human docs: https://flow.foblex.com/docs/get-started
 - Live examples with source: https://flow.foblex.com/examples/overview
+- Managed state example and contract: https://flow.foblex.com/examples/state
 
 ## Fallback Rule
 

package/README.md

@@ -11,6 +11,15 @@
   <a href="https://github.com/Foblex/f-flow/actions/workflows/tests-ci.yml">
     <img src="https://github.com/Foblex/f-flow/actions/workflows/tests-ci.yml/badge.svg" alt="Build Status"/>
   </a>
+  <a href="https://www.npmjs.com/package/@foblex/flow">
+    <img src="https://img.shields.io/npm/dw/@foblex/flow.svg?label=Downloads&color=blue" alt="NPM Weekly Downloads"/>
+  </a>
+  <a href="https://github.com/Foblex/f-flow/stargazers">
+    <img src="https://img.shields.io/github/stars/Foblex/f-flow.svg?label=Stars&color=gold" alt="GitHub Stars"/>
+  </a>
+  <a href="https://github.com/Foblex/f-flow/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/@foblex/flow.svg?label=License&color=green" alt="MIT License"/>
+  </a>
 </p>
 
 <h1 align="center">Foblex Flow</h1>
@@ -23,7 +32,13 @@ Foblex Flow gives Angular teams a simple way to start building graph-based produ
 
 Use it to create workflow builders, AI low-code tools, call-flow editors, UML diagrams, internal back-office tools, and other node-based interfaces while keeping your own state, validation, persistence, and domain logic.
 
-Current `18.x` releases target Angular `17.3+`. If your app is on Angular 12-17.2, check the [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility) guide first and pin the matching Foblex Flow line before installing.
+<p align="center">
+  <a href="https://flow.foblex.com/examples/overview">
+    <img src="https://flow.foblex.com/previews/examples/reflow-on-resize.light.png" alt="Foblex Flow — Angular node editor with draggable nodes and connections" width="720"/>
+  </a>
+</p>
+
+Current `19.x` releases target Angular `17.3+`. If your app is on Angular 12-17.2, check the [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility) guide first and pin the matching Foblex Flow line before installing.
 
 ## Why Foblex Flow
 
@@ -35,6 +50,22 @@ Current `18.x` releases target Angular `17.3+`. If your app is on Angular 12-17.
 - Your app stays in control of graph state, validation rules, permissions, and persistence.
 - Suitable for both lightweight diagrams and full workflow-builder products.
 
+## Feature Overview
+
+| Area          | What ships out of the box                                                                                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Editing       | Drag & drop nodes and groups, drag/click/keyboard connection creation, reassign, waypoints, resize, rotate, snap & alignment guides, magnetic lines                       |
+| Navigation    | Pan, wheel/pinch/double-click zoom, minimap, auto-pan at edges, fit-to-screen, configurable control schemes (Miro-like, draw.io-like presets)                             |
+| Selection     | Click, marquee, multi-select, select-all, selection events — your app decides what selection means                                                                        |
+| Accessibility | ARIA semantics by default; opt-in keyboard layer: spatial navigation, move, delete, and connection creation without a mouse, screen-reader announcements, remappable keys |
+| Layout        | Dagre and ELK auto-layout packages, reflow-on-resize, layer ordering                                                                                                      |
+| Scale         | Node virtualization, render caching, background workers — optional, for large scenes                                                                                      |
+| Customization | Fully templated nodes/connections/connectors, themable via CSS tokens/SCSS mixins, custom markers, connection gradients and labels                                        |
+| Integration   | Event-driven API (`fCreateConnection`, `fMoveNodes`, `fDeleteSelected`, …) — the library never mutates your data; SSR-safe, zoneless-ready                                |
+| AI tooling    | `llms.txt`, bundled `AI.md`, `ng add` writes agent rules, dev diagnostics with stable `FFxxxx` error codes                                                                |
+
+Coming from React Flow? Read the honest comparison: [React Flow vs Foblex Flow for Angular teams](https://flow.foblex.com/docs/react-flow-vs-foblex-flow-for-angular-teams).
+
 ## What You Can Build
 
 - Angular node editors
@@ -52,9 +83,15 @@ Current `18.x` releases target Angular `17.3+`. If your app is on Angular 12-17.
 - [Tournament Bracket](https://flow.foblex.com/examples/tournament-bracket) - A specialized bracket UI built on the same node-based primitives.
 - [All Examples](https://flow.foblex.com/examples/overview) - Focused examples for connections, selection, minimap, layout, alignment, and other editor features.
 
+## Try It Online
+
+No local setup needed — the minimal starter runs in the browser:
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/Foblex/f-flow/tree/main/starters/minimal-flow)
+
 ## Install
 
-These install commands are for the current `18.x` line. For Angular 12-17.2 apps, use the [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility) guide first so you do not accidentally install a newer incompatible line.
+These install commands are for the current `19.x` line. For Angular 12-17.2 apps, use the [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility) guide first so you do not accidentally install a newer incompatible line.
 
 ```bash
 ng add @foblex/flow
@@ -105,33 +142,23 @@ Full guide: [Default Theme and Styling](https://flow.foblex.com/docs/default-the
 ```html
 <f-flow fDraggable>
   <f-canvas>
-    <f-connection fOutputId="output1" fInputId="input1"></f-connection>
-
-    <div
-      fNode
-      fDragHandle
-      [fNodePosition]="{ x: 24, y: 24 }"
-      fNodeOutput
-      fOutputId="output1"
-      fOutputConnectableSide="right"
-    >
+    <f-connection fSourceId="a-out" fTargetId="b-in"></f-connection>
+
+    <div fNode fDragHandle [fNodePosition]="{ x: 24, y: 24 }">
       Drag me
+      <div fConnector fConnectorType="source" fConnectorId="a-out"></div>
     </div>
 
-    <div
-      fNode
-      fDragHandle
-      [fNodePosition]="{ x: 244, y: 24 }"
-      fNodeInput
-      fInputId="input1"
-      fInputConnectableSide="left"
-    >
-      Drag me
+    <div fNode fDragHandle [fNodePosition]="{ x: 244, y: 24 }">
+      Drag me too
+      <div fConnector fConnectorType="target" fConnectorId="b-in"></div>
     </div>
   </f-canvas>
 </f-flow>
 ```
 
+That is the whole mental model: `f-flow` hosts the editor, `f-canvas` pans and zooms, any element becomes a node with `fNode`, connectors attach edges. Everything below is opt-in.
+
 ## Quick FAQ
 
 - **Is Foblex Flow hard to use?** No. The core setup is small and Angular-native.

package/STYLING.md

@@ -14,6 +14,7 @@ Observed host/base classes in source include `.f-flow`, `.f-canvas`, `.f-node`,
 - Observed in source: `.f-node-output-connected` and `.f-node-input-connected` mark connectors that are currently connected.
 - Observed in source: `.f-node-output-not-connectable` and `.f-node-input-not-connectable` mark connectors that are present but currently not connectable.
 - Observed in source: `.f-grouping-drop-active` and `.f-grouping-over-boundary` are applied during drop-to-group interactions.
+- Observed in source: `.f-drop-to-group` is a host modifier class applied to the flow while the drop-to-group gesture is enabled (the default; toggled by the `fDropToGroup` input). The `.f-grouping-drop-active` / `.f-grouping-over-boundary` highlight is scoped under it.
 - Observed in source: `.f-node-dragging-disabled`, `.f-node-selection-disabled`, `.f-group-dragging-disabled`, `.f-group-selection-disabled`, `.f-connection-reassign-disabled`, and `.f-connection-selection-disabled` are host modifier classes for disabled interaction states.
 - Observed in source: `.f-node-input-disabled`, `.f-node-output-disabled`, and `.f-node-outlet-disabled` are connector/outlet disabled-state classes.
 - Observed in source: `.f-node-input-multiple`, `.f-node-output-multiple`, and `.f-node-output-self-connectable` are connector capability/modifier classes.