@foblex/flow 19.1.4 → 19.1.5

package/AI.md

@@ -5,12 +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. By default your app owns the graph data; the optional `withFlowState()` feature can own the data bookkeeping and undo/redo for an editor.
+It provides rendering, connectors, interactions, selection, zoom, and connection drawing. By default your app owns graph records; the optional `withFlowState()` feature maintains typed records and undo/redo that your app explicitly loads and renders.
 
 ## Core Mental Model
 
-- **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.
+- **Classic mode (default):** your app owns nodes, groups, and connections. User actions emit events; your handlers validate them, update app state, and Angular rerenders.
+- **Managed mode (opt-in):** `provideFFlow(withFlowState())` provides `FFlowState`; supported completed gestures update its typed records and history automatically.
+- **Application responsibility in both modes:** your app defines domain fields and owns validation policy, permissions, persistence, backend integration, and business meaning.
 - Both modes render records through normal Angular templates. `withFlowState()` is optional and does not change classic event behavior when absent.
 
 ## Minimal Working Setup
@@ -136,11 +137,12 @@ export class Editor {
 
 - 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.
+- Node and group geometry emitted through `fNodeSizeChange` / `fGroupSizeChange`, including user resize and auto-expand or auto-fit updates, changes the managed records without creating a separate history step. Arbitrary content measurement that emits neither output is not written to the store. Rotation and connection waypoint editing 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.
+- Use `state.snapshot()` for persistence; it includes graph records, selection, and viewport transform. `load()` restores them and resets history. Snapshots created before selection persistence remain valid and load with an empty selection.
 - `canvasTransformDebounce` defaults to `350ms`. It waits for wheel/pinch zoom events to settle, then records the current canvas transform as one change and one undo item. Setting it to `0` disables batching: every emitted `fCanvasChange` is applied immediately, increments `state.changes()`, and normally creates a separate undo item. Keep the canvas `[debounceTime]` unset when managed state owns viewport history; do not stack canvas and State debounce layers.
 - 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.
+- `canvas.centerGroupOrNode(id)` preserves the current zoom. Use `canvas.resetScaleAndCenterGroupOrNode(id)` when focusing the item must also reset zoom to `1`; both methods emit `fCanvasChange` by default.
 - 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(...)`.
 
 ### Async reflow must stay inside an open transaction
@@ -180,7 +182,7 @@ When the flow compiles but looks wrong, verify in this order:
 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)`.
+13. **Wrong initial viewport** (`FF1009`): `fitToScreen()` / `resetScaleAndCenter()` / `centerGroupOrNode()` / `resetScaleAndCenterGroupOrNode()` 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.
@@ -192,9 +194,9 @@ To verify programmatically: listen to `(fFullRendered)` on `<f-flow>`, then call
 - 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.
+- For custom markers, either provide `SELECTED_START` / `SELECTED_END` alongside `START` / `END`, or use `START_ALL_STATES` / `END_ALL_STATES`; the all-states variants create both normal and selected markers.
 - 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]">`.
+- Start with regular `@for` rendering and measure a production build. Enable `[fCache]` when geometry reads are a demonstrated cost; use `*fVirtualFor` inside `<ng-container ngProjectAs="[fNodes]">` when progressive creation materially improves startup. `fVirtualFor` is not viewport culling.
 
 ## Naming Distinction
 
@@ -217,7 +219,11 @@ See [STYLING.md](./STYLING.md).
 - 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
+- Managed state guide: https://flow.foblex.com/docs/managed-flow-state
 - Managed state + asynchronous reflow recipe: https://flow.foblex.com/examples/state
+- Large-flow performance guide: https://flow.foblex.com/docs/large-flow-performance
+- Shadow DOM and Angular Elements: https://flow.foblex.com/docs/shadow-dom-and-angular-elements
+- Unified connector migration: https://flow.foblex.com/docs/migrating-to-unified-connectors
 
 ## Fallback Rule
 

package/README.md

@@ -30,7 +30,7 @@
 
 Foblex Flow gives Angular teams a simple way to start building graph-based products without adopting a React-first mental model. Begin with `f-flow`, `f-canvas`, nodes, and connections, then add richer editor features only when your product needs them.
 
-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.
+Use it to create workflow builders, AI low-code tools, call-flow editors, UML diagrams, internal back-office tools, and other node-based interfaces. Start with app-owned graph records, or opt into managed records and undo/redo with `withFlowState()`; validation, persistence, permissions, and domain logic remain application concerns in both modes.
 
 <p align="center">
   <a href="https://flow.foblex.com/examples/overview">
@@ -47,7 +47,8 @@ Current `19.x` releases target Angular `17.3+`. If your app is on Angular 12-17.
 - Built for real editor interactions: drag to connect, drag to reassign, selection, zoom, minimap, snapping, alignment helpers, and waypoints.
 - Advanced modules are optional: caching and virtualization are scaling tools, not day-one requirements.
 - Custom nodes, connectors, and connections for domain-specific graph UIs.
-- Your app stays in control of graph state, validation rules, permissions, and persistence.
+- Choose the state boundary that fits your editor: app-owned records by default, or optional typed `FFlowState` records with snapshots and undo/redo.
+- Your app stays in control of validation rules, permissions, persistence, and business meaning in either state mode.
 - Suitable for both lightweight diagrams and full workflow-builder products.
 
 ## Feature Overview
@@ -61,11 +62,19 @@ Current `19.x` releases target Angular `17.3+`. If your app is on Angular 12-17.
 | 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                                |
+| Integration   | Classic event-driven API with app-owned records, or optional `withFlowState()` managed records, snapshots, and undo/redo; 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).
 
+## Choose Your State Integration
+
+The default **classic mode** renders arrays or signals owned by your application. Foblex Flow emits final interaction events such as `fCreateConnection` and `fMoveNodes`; your handlers validate them and update application state.
+
+The optional **managed mode** installs `provideFFlow(withFlowState())`. Its typed `FFlowState` records apply supported gestures automatically and provide batching, snapshots, undo, and redo. Your application still defines domain fields and decides how records are validated and persisted.
+
+[Managed Flow State guide](https://flow.foblex.com/docs/managed-flow-state) · [Live state example](https://flow.foblex.com/examples/state)
+
 ## What You Can Build
 
 - Angular node editors
@@ -157,7 +166,7 @@ Full guide: [Default Theme and Styling](https://flow.foblex.com/docs/default-the
 </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.
+That is the rendering mental model: `f-flow` hosts the editor, `f-canvas` pans and zooms, any element becomes a node with `fNode`, and `fConnector` endpoints attach connections. State management and every advanced feature remain explicit choices.
 
 ## Quick FAQ
 
@@ -169,6 +178,10 @@ That is the whole mental model: `f-flow` hosts the editor, `f-canvas` pans and z
 
 - [Get Started](https://flow.foblex.com/docs/get-started)
 - [Angular Version Compatibility](https://flow.foblex.com/docs/angular-version-compatibility)
+- [Managed Flow State](https://flow.foblex.com/docs/managed-flow-state)
+- [Large Flow Performance](https://flow.foblex.com/docs/large-flow-performance)
+- [Shadow DOM and Angular Elements](https://flow.foblex.com/docs/shadow-dom-and-angular-elements)
+- [Migrating to Unified Connectors](https://flow.foblex.com/docs/migrating-to-unified-connectors)
 - [Documentation](https://flow.foblex.com/docs/intro)
 - [Examples](https://flow.foblex.com/examples/overview)
 - [Articles](https://flow.foblex.com/blog/overview)

package/fesm2022/foblex-flow.mjs

@@ -925,11 +925,13 @@ class CenterGroupOrNodeRequest {
     id;
     animated;
     emitCanvasChange;
+    resetScale;
     static fToken = Symbol('CenterGroupOrNodeRequest');
-    constructor(id, animated, emitCanvasChange = true) {
+    constructor(id, animated, emitCanvasChange = true, resetScale = false) {
         this.id = id;
         this.animated = animated;
         this.emitCanvasChange = emitCanvasChange;
+        this.resetScale = resetScale;
     }
 }
 
@@ -942,17 +944,21 @@ let CenterGroupOrNode = class CenterGroupOrNode {
     get _transform() {
         return this._store.transform;
     }
-    handle({ id, animated, emitCanvasChange }) {
+    handle({ id, animated, emitCanvasChange, resetScale }) {
         const node = this._store.nodes.get(id);
         if (!node) {
             return;
         }
-        this._toCenter(this._getNodeRect(node), this._getFlowRect(), node._position);
+        this._toCenter(this._getNodeRect(node), this._getFlowRect(), node._position, resetScale);
         this._mediator.execute(new RedrawCanvasWithAnimationRequest(animated, ECanvasRedrawContext.VIEWPORT_ONLY, emitCanvasChange));
     }
-    _toCenter(fNodeRect, fFlowRect, position) {
+    _toCenter(fNodeRect, fFlowRect, position, resetScale) {
+        const currentScale = this._transform.scale;
+        const targetScale = resetScale ? 1 : currentScale;
+        const sizeScale = currentScale === 0 ? 1 : targetScale / currentScale;
         this._transform.scaledPosition = PointExtensions.initialize();
-        this._transform.position = PointExtensions.initialize((fFlowRect.width - fNodeRect.width) / 2 - position.x * this._transform.scale, (fFlowRect.height - fNodeRect.height) / 2 - position.y * this._transform.scale);
+        this._transform.scale = targetScale;
+        this._transform.position = PointExtensions.initialize((fFlowRect.width - fNodeRect.width * sizeScale) / 2 - position.x * targetScale, (fFlowRect.height - fNodeRect.height * sizeScale) / 2 - position.y * targetScale);
     }
     _getNodeRect(fNode) {
         return RectExtensions.fromElement(fNode.hostElement);
@@ -21013,9 +21019,17 @@ class FCanvasComponent extends FCanvasBase {
     }
     centerGroupOrNode(groupOrNodeId, animated = true, emitCanvasChange = true) {
         this._warnWhenCalledBeforeNodesRender('centerGroupOrNode()');
-        this._afterRedraw(() => {
-            this._mediator.execute(new CenterGroupOrNodeRequest(groupOrNodeId, animated, emitCanvasChange));
-        });
+        this._centerGroupOrNode(groupOrNodeId, animated, emitCanvasChange, false);
+    }
+    /**
+     * Resets the canvas scale to `1` and centers the specified group or node.
+     * @param groupOrNodeId - The ID of the group or node to center.
+     * @param animated - If true, the centering will be animated; otherwise, it will be instantaneous.
+     * @param emitCanvasChange - If false, does not emit `fCanvasChange` for this programmatic move.
+     */
+    resetScaleAndCenterGroupOrNode(groupOrNodeId, animated = true, emitCanvasChange = true) {
+        this._warnWhenCalledBeforeNodesRender('resetScaleAndCenterGroupOrNode()');
+        this._centerGroupOrNode(groupOrNodeId, animated, emitCanvasChange, true);
     }
     /**
      * Fits the canvas to the screen by adjusting the scale and position.
@@ -21072,6 +21086,11 @@ class FCanvasComponent extends FCanvasBase {
     _afterRedraw(callback) {
         this._mediator.execute(new WaitForConnectionsRenderedRequest(this._components.connectionsRevision, this._components.nodesRevision, () => afterNextRender(callback, { injector: this._injector }), this.destroyRef));
     }
+    _centerGroupOrNode(groupOrNodeId, animated, emitCanvasChange, resetScale) {
+        this._afterRedraw(() => {
+            this._mediator.execute(new CenterGroupOrNodeRequest(groupOrNodeId, animated, emitCanvasChange, resetScale));
+        });
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.9", ngImport: i0, type: FCanvasComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.9", type: FCanvasComponent, isStandalone: true, selector: "f-canvas", inputs: { position: { classPropertyName: "position", publicName: "position", isSignal: true, isRequired: false, transformFunction: null }, scale: { classPropertyName: "scale", publicName: "scale", isSignal: true, isRequired: false, transformFunction: null }, debounceTime: { classPropertyName: "debounceTime", publicName: "debounceTime", isSignal: true, isRequired: false, transformFunction: null }, fLayers: { classPropertyName: "fLayers", publicName: "fLayers", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { fCanvasChange: "fCanvasChange" }, host: { classAttribute: "f-component f-canvas" }, providers: [{ provide: F_CANVAS, useExisting: FCanvasComponent }], viewQueries: [{ propertyName: "fGroupsContainer", first: true, predicate: ["fGroupsContainer"], descendants: true, isSignal: true }, { propertyName: "fNodesContainer", first: true, predicate: ["fNodesContainer"], descendants: true, isSignal: true }, { propertyName: "fConnectionsContainer", first: true, predicate: ["fConnectionsContainer"], descendants: true, isSignal: true }], usesInheritance: true, ngImport: i0, template: "<ng-container>\n  @for (layer of resolvedLayers(); track layer) {\n    @switch (layer) {\n      @case ('groups') {\n        <div #fGroupsContainer class=\"f-groups-container\">\n          <ng-content select=\"[fGroup], [fGroups]\" />\n        </div>\n      }\n      @case ('connections') {\n        <div #fConnectionsContainer class=\"f-connections-container\">\n          <ng-content select=\"f-snap-connection\" />\n          <ng-content select=\"f-connection, [fConnections]\" />\n          <ng-content select=\"f-connection-for-create\" />\n        </div>\n      }\n      @case ('nodes') {\n        <div #fNodesContainer class=\"f-nodes-container\">\n          <ng-content select=\"[fNode], [fNodes]\" />\n        </div>\n      }\n    }\n  }\n</ng-container>\n", styles: [":host{position:absolute;overflow:visible;width:100%;height:100%;left:0;top:0;transform-origin:0 0;pointer-events:none}:host.f-canvas-dragging,:host.canvas-dragging{transform:translateZ(0)}.f-groups-container,.f-connections-container,.f-nodes-container{isolation:isolate}.f-connections-container{position:absolute}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
@@ -21780,6 +21799,7 @@ class FA11yController {
         const direction = ARROW_DIRECTIONS[event.key];
         if (direction) {
             event.preventDefault();
+            this._syncActiveItemFromSelection();
             event.ctrlKey || event.metaKey
                 ? this._walkConnections(direction, event.shiftKey)
                 : this._navigate(direction, event.shiftKey);
@@ -21855,6 +21875,49 @@ class FA11yController {
             !!target.closest('[fLockedContext]'));
     }
     // ------------------------------------------------------------------ navigation
+    /**
+     * Selection can be restored from state or replaced by a pointer-driven render before
+     * this layer receives a stable DOM target. In that case there is no active descendant,
+     * so use the single selected item as the spatial-navigation anchor.
+     */
+    _syncActiveItemFromSelection() {
+        const selection = this._selection();
+        const selectedNodeIds = [...selection.fNodeIds, ...selection.fGroupIds];
+        if (selectedNodeIds.length + selection.fConnectionIds.length !== 1) {
+            return;
+        }
+        const selectedNodeId = selectedNodeIds[0];
+        if (selectedNodeId) {
+            if (this._activeNodeId === selectedNodeId && this._activeNode()) {
+                return;
+            }
+            const node = this._store.nodes.getAll().find((x) => x.fId() === selectedNodeId);
+            if (!node) {
+                return;
+            }
+            this._activeNodeId = selectedNodeId;
+            this._activeConnectionId = undefined;
+            this._walkTargetNodeId = undefined;
+            this._lastMove = undefined;
+            this._setActiveDescendant(node.hostElement);
+            return;
+        }
+        const selectedConnectionId = selection.fConnectionIds[0];
+        if (this._activeConnectionId === selectedConnectionId && this._activeConnection()) {
+            return;
+        }
+        const connection = this._store.connections
+            .getAll()
+            .find((x) => x.fId() === selectedConnectionId);
+        if (!connection) {
+            return;
+        }
+        this._activeConnectionId = selectedConnectionId;
+        this._activeNodeId = undefined;
+        this._walkTargetNodeId = undefined;
+        this._lastMove = undefined;
+        this._setActiveDescendant(connection.hostElement);
+    }
     /**
      * Plain arrows travel over nodes AND connections as equal stops — a connection is
      * represented by its midpoint, so walking a chain reads node → connection → node.
@@ -22644,14 +22707,15 @@ class FFlowState {
         this._undoStack.length = 0;
         this._redoStack.length = 0;
         this._batchDirty = false;
+        const selection = _copySelection(data.selection ?? EMPTY_SELECTION);
         const transform = _copyTransform(data.transform ?? DEFAULT_TRANSFORM);
-        this._liveSelection.set(EMPTY_SELECTION);
+        this._liveSelection.set(selection);
         this._liveTransform.set(transform);
         this._shape.set({
             nodes: _byId(data.nodes ?? []),
             groups: _byId(data.groups ?? []),
             connections: _byId(data.connections ?? []),
-            selection: EMPTY_SELECTION,
+            selection,
             transform,
         });
         this._syncHistorySignals();
@@ -22667,6 +22731,7 @@ class FFlowState {
             nodes: Object.values(nodes).map(_copyBox),
             groups: Object.values(groups).map(_copyBox),
             connections: Object.values(connections).map((connection) => ({ ...connection })),
+            selection: _copySelection(this.selection()),
             transform: _copyTransform(this.transform()),
         };
     }
@@ -23167,6 +23232,13 @@ function _copyBox(box) {
         size: box.size ? { ...box.size } : undefined,
     };
 }
+function _copySelection(selection) {
+    return {
+        nodeIds: [...selection.nodeIds],
+        groupIds: [...selection.groupIds],
+        connectionIds: [...selection.connectionIds],
+    };
+}
 /** Clears `parentId` on records that pointed at a removed group. */
 function _clearParent(records, removedGroups) {
     if (!removedGroups.size) {
@@ -23262,9 +23334,7 @@ class FFlowStateController {
             this._wireCanvasEvents();
             this._wireSizeChanges();
         }));
-        if (this._config.selectionInHistory) {
-            this._wireSelectionRestore();
-        }
+        this._wireSelectionRestore();
     }
     destroy() {
         this._disposers.forEach((dispose) => dispose());
@@ -23472,9 +23542,9 @@ class FFlowStateController {
         }
     }
     /**
-     * When selection is part of the history, `undo`/`redo` land on a shape with
-     * its own selection — push it back into the flow so the highlight follows.
-     * `isSelectedChanged: false` keeps this from re-emitting a selection change.
+     * Pushes state selection into the flow after `load`, `undo` or `redo` so the
+     * rendered highlight follows the persisted state. `isSelectedChanged: false`
+     * keeps this from re-emitting a selection change.
      */
     _wireSelectionRestore() {
         const state = this._state;
@@ -23531,7 +23601,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.9", ngImpor
  * connection, node moves, drops into groups, external-item drops, delete
  * requests) are applied to the state automatically, each as one undoable
  * step. `undo()`/`redo()` with `canUndo`/`canRedo` signals come built in;
- * `snapshot()` returns the graph as plain arrays for persistence.
+ * `snapshot()` returns the graph, selection and viewport for persistence.
  *
  * Every store behavior is overridable: subclass `FFlowState` (any CRUD
  * method, any `apply*` gesture handler, any protected building block) and