@foblex/flow 18.6.1 → 19.1.0

package/AI.md

@@ -5,54 +5,178 @@ 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
+
+Three files must be correct at the same time. Missing any one produces a blank or inert canvas, usually without errors.
+
+```typescript
+// component — FFlowModule is required: fNode, fConnector, f-connection are not standalone
+import { FFlowModule } from '@foblex/flow';
+
+@Component({
+  standalone: true,
+  imports: [FFlowModule],
+  templateUrl: './flow.html',
+  styleUrl: './flow.scss',
+})
+export class Flow {}
+```
+
+```html
+<!-- template — the hierarchy f-flow > f-canvas > fNode/f-connection is mandatory -->
+<f-flow fDraggable>
+  <f-canvas>
+    <f-connection fSourceId="out-1" fTargetId="in-1"></f-connection>
+
+    <div fNode fDragHandle [fNodePosition]="{ x: 100, y: 100 }">
+      Node A
+      <div fConnector fConnectorType="source" fConnectorId="out-1"></div>
+    </div>
+    <div fNode fDragHandle [fNodePosition]="{ x: 320, y: 100 }">
+      Node B
+      <div fConnector fConnectorType="target" fConnectorId="in-1"></div>
+    </div>
+  </f-canvas>
+</f-flow>
+```
+
+```scss
+/* styles — f-flow must have a nonzero height or nothing is visible */
+f-flow {
+  display: block;
+  height: 600px;
+}
+```
+
+The default theme is wired by `ng add @foblex/flow` (adds `node_modules/@foblex/flow/styles/default.scss` to `angular.json`). Without a theme, nodes and connections render unstyled or invisible.
 
 ## Verified Building Blocks
 
 - `<f-flow>`: root flow host.
 - `<f-canvas>`: canvas/viewport container.
 - `[fNode]` and `[fGroup]`: place nodes and groups in the template.
-- `[fNodeOutput]` with `fOutputId`: output connector.
-- `[fNodeInput]` with `fInputId`: input connector.
-- `[fNodeOutlet]`: outlet-style connector surface for advanced connection creation patterns.
-- `<f-connection>`: render an existing connection between connectors.
+- `[fConnector]` with `fConnectorId` and `fConnectorType` (`'source' | 'target' | 'source-target' | 'outlet'`): the **unified connector**. Preferred for new code.
+- `[fNodeOutput]` / `[fNodeInput]` / `[fNodeOutlet]`: legacy connectors, still supported, deprecated in favor of `fConnector`.
+- `<f-connection>` with `fSourceId` / `fTargetId`: render an existing connection between connectors (`fOutputId` / `fInputId` are deprecated aliases).
 - `<f-connection-for-create>`: optional preview connection used during drag-to-connect UX.
 - `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(...)` (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()`, or similar patterns.
-- Do **not** assume a built-in graph store. The app owns state.
+- Do **not** assume React Flow style APIs such as `[nodes]`, `[edges]`, `setNodes()`, `addEdge()`, `useNodesState()`, `<Handle>`, `<Background>`, `<Controls>`, or similar patterns.
+- 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 `fOutputId -> fInputId`.
-- Do **not** interpret `[fNodes]` or `[fConnections]` as graph-state inputs. In this package they are content-projection markers used with `ngProjectAs` in some examples.
-- Examples may include app-specific state, layout logic, persistence, undo/redo, toolbars, or validation. Those are example implementations, not built-in package features.
+- 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).
+- **Nested control flow requires `ngProjectAs`.** Nodes, groups, or connections rendered inside nested template blocks (`@for` in `@if`, `@for` in `@for`, `@if` in `@if`, or a wrapper element) are NOT projected into the canvas — Angular creates them detached, geometry collapses to 0×0, and nothing renders, with no error. Wrap such blocks:
+
+  ```html
+  @if (isEditable()) {
+    <ng-container ngProjectAs="[fNodes]">
+      @for (node of nodes(); track node.id) {
+        <div fNode [fNodePosition]="node.position">{{ node.label }}</div>
+      }
+    </ng-container>
+    <ng-container ngProjectAs="[fConnections]">
+      @for (c of connections(); track c.id) {
+        <f-connection [fSourceId]="c.source" [fTargetId]="c.target" />
+      }
+    </ng-container>
+  }
+  ```
+
+  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 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 `fNodeOutput` / `fNodeInput`.
+- Put connectors on the node element itself or on child elements with `fConnector`.
 - Render persisted connections explicitly with `<f-connection>`.
 - Add `fDraggable` to `<f-flow>` when you want drag, selection, connect, reassign, or drop interactions.
 - Handle events such as `fCreateConnection`, `fReassignConnection`, `fMoveNodes`, `fSelectionChange`, `fCreateNode`, `fDropToGroup`, and `fConnectionWaypointsChanged`.
 - 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:
+
+1. **Connection not visible**: `fSourceId` / `fTargetId` does not match any rendered `fConnectorId` exactly (string comparison; `1` vs `'1'` from different sources is a classic mismatch). The connection silently does not render.
+2. **Blank canvas**: `f-flow` has zero height, or the theme SCSS is not wired in `angular.json`.
+3. **`'f-flow' is not a known element`** or connectors not working: `FFlowModule` missing from the component `imports`.
+4. **Nothing is draggable / no events fire**: `fDraggable` missing on `<f-flow>`.
+5. **Wheel does nothing**: `fZoom` missing on `<f-canvas>` (zoom is opt-in).
+6. **Node ignores position**: `[fNodePosition]` must be a property binding to `{ x, y }`, and nodes must be direct content of `<f-canvas>`.
+7. **`[f-flow][FF1003]` error**: a connector is placed outside an `[fNode]` / `[fGroup]` element.
+8. **Nodes/connections exist in state but nothing renders, no errors** (`FF1004` warns in dev mode): flow content sits inside nested `@if`/`@for` blocks without `<ng-container ngProjectAs="[fNodes]">` (`"[fGroups]"` / `"[fConnections]"`) — see the Hard Rules section.
+9. **Handles/selection/connect present but inert** (`FF1005`): `fDraggable` is missing on `<f-flow>` while `fDragHandle` / `f-selection-area` / `f-connection-for-create` / resize / rotate are used.
+10. **Connections attach to the wrong place** (`FF1006`): a connector is hidden with CSS (`display: none`) — its geometry is a 0×0 point. Conditionally render instead of hiding.
+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.
+
+## Additional Rules
+
+- The library runs outside the Angular zone: its events do not trigger change detection. With OnPush or zoneless apps, replace arrays/objects (new references) instead of mutating, and call `markForCheck()` where needed.
+- Always set stable, app-owned ids on nodes and connections; auto-generated ids (`f-connection-3`) cannot be mapped back to your model and break selection/persistence across re-renders.
+- Style flow internals (connection paths, minimap, markers) in global styles or via `::ng-deep` — component-scoped CSS never reaches them. Wire the default theme via `ng add`.
+- Do not combine `fAutoSizeToFitChildren` with restoring a persisted group size in the same render: pass `false` while restoring, enable it afterwards.
+- With several `<f-flow>` instances on one page, keep `fDraggable` enabled only on the active flow.
+- Connections define `SELECTED_START` / `SELECTED_END` marker variants in addition to `START` / `END`, or markers disappear when the connection is selected.
+- An empty `fCanBeConnectedTo` allow-list means "no restriction", not "allow nothing"; category strings must match exactly.
+- Above ~500 nodes enable `[fCache]` on `<f-flow>` and render nodes with `*fVirtualFor` inside `<ng-container ngProjectAs="[fNodes]">`.
+
 ## Naming Distinction
 
-- In templates, connector ids are `fOutputId` and `fInputId`.
+- In templates, connector ids are `fConnectorId` (unified) or legacy `fOutputId` / `fInputId`; connection endpoints are `fSourceId` / `fTargetId`.
 - In `FCreateConnectionEvent`, prefer `sourceId`, `targetId`, and `dropPosition`.
 - `FCreateConnectionEvent` still exposes legacy aliases `fOutputId`, `fInputId`, and `fDropPosition`.
 - In `FReassignConnectionEvent`, prefer `connectionId`, `endpoint`, `previousSourceId`, `nextSourceId`, `previousTargetId`, `nextTargetId`, and `dropPosition`.
@@ -64,6 +188,14 @@ It provides rendering, connectors, interactions, selection, zoom, and connection
 
 See [STYLING.md](./STYLING.md).
 
+## More Documentation
+
+- Full LLM-readable reference: https://flow.foblex.com/llms-full.txt
+- 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
 
 If something cannot be verified from the installed package, answer with: `not found in @foblex/flow`.

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.
@@ -149,6 +176,11 @@ Full guide: [Default Theme and Styling](https://flow.foblex.com/docs/default-the
 - [Roadmap](https://github.com/Foblex/f-flow/blob/main/ROADMAP.md)
 - [Changelog](https://github.com/Foblex/f-flow/blob/main/CHANGELOG.md)
 
+### For AI Agents and LLMs
+
+- [llms.txt](https://flow.foblex.com/llms.txt) — docs index for agents; [llms-full.txt](https://flow.foblex.com/llms-full.txt) — complete LLM-readable API reference
+- [AI usage guide](https://github.com/Foblex/f-flow/blob/main/libs/f-flow/AI.md) — strict code-generation rules, also shipped inside this package at `node_modules/@foblex/flow/AI.md`
+
 ## Community and Support
 
 - [GitHub Repository](https://github.com/Foblex/f-flow)

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.