@angflow/angular 0.0.18 → 0.3.1

package/README.md

@@ -118,38 +118,55 @@ The app ships three sections:
 
 ## Custom Nodes
 
-Create any Angular component and register it as a node type. Use the `nodrag` CSS class on interactive elements (inputs, dropdowns) to prevent drag interference.
+Create any Angular component and register it as a node type. The preferred way to read per-node state is `injectNgFlowNode<TData>()`, which returns reactive read-only signals for every property the library tracks (`id`, `data`, `selected`, `dragging`, `zIndex`, `isConnectable`, `position`, `sourcePosition`, `targetPosition`, `dragHandle`, `type`, `collapsed`). Use the `nodrag` CSS class on interactive elements (inputs, dropdowns) to prevent drag interference.
 
 ```typescript
+import { Component, ChangeDetectionStrategy, inject } from '@angular/core';
+import {
+  HandleComponent,
+  Position,
+  NgFlowService,
+  injectNgFlowNode,
+} from '@angflow/angular';
+
+interface FormData { title: string; name: string; type: string }
+
 @Component({
   selector: 'app-form-node',
   standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [HandleComponent],
   template: `
-    <ng-flow-handle type="target" [position]="Position.Top" />
-    <div class="my-node">
-      <h3>{{ data()?.title }}</h3>
+    <ng-flow-handle type="target" [position]="Position.Top" [isConnectable]="node.isConnectable()" />
+    <div class="my-node" [class.selected]="node.selected()">
+      <h3>{{ node.data()?.title }}</h3>
       <div class="nodrag">
-        <input [value]="data()?.name" (input)="onNameChange($event)" />
-        <select [value]="data()?.type" (change)="onTypeChange($event)">
+        <input [value]="node.data()?.name" (input)="onNameChange($event)" />
+        <select [value]="node.data()?.type" (change)="onTypeChange($event)">
           <option value="string">String</option>
           <option value="number">Number</option>
         </select>
       </div>
     </div>
-    <ng-flow-handle type="source" [position]="Position.Bottom" />
+    <ng-flow-handle type="source" [position]="Position.Bottom" [isConnectable]="node.isConnectable()" />
   `,
 })
 export class FormNodeComponent {
   readonly Position = Position;
-  readonly id = input.required<string>();
-  readonly data = input<any>();
-  // ... other standard inputs: type, selected, dragging, zIndex, etc.
+  readonly node = injectNgFlowNode<FormData>();
 
   private flowService = inject(NgFlowService);
 
   onNameChange(event: Event) {
-    this.flowService.updateNodeData(this.id(), { name: (event.target as HTMLInputElement).value });
+    this.flowService.updateNodeData(this.node.id(), {
+      name: (event.target as HTMLInputElement).value,
+    });
+  }
+
+  onTypeChange(event: Event) {
+    this.flowService.updateNodeData(this.node.id(), {
+      type: (event.target as HTMLSelectElement).value,
+    });
   }
 }
 ```
@@ -164,6 +181,24 @@ nodeTypes = { formNode: FormNodeComponent };
 <ng-flow [nodes]="nodes" [edges]="edges" [nodeTypes]="nodeTypes" ...>
 ```
 
+#### Legacy: flat `@Input()`s
+
+The original API — declaring one `@Input()` per tracked property — is still fully supported, so existing custom nodes keep working without changes:
+
+```typescript
+export class FormNodeComponent {
+  readonly Position = Position;
+  readonly id = input.required<string>();
+  readonly data = input<FormData>();
+  readonly selected = input(false);
+  readonly isConnectable = input(true);
+  // ...plus type, dragging, zIndex, positionAbsoluteX/Y,
+  //    sourcePosition, targetPosition, dragHandle as needed
+}
+```
+
+Prefer `injectNgFlowNode()` for new code: one injection call replaces ~13 input declarations, the signals are reactive in the same way, and you only pull the fields you actually use.
+
 ## Programmatic API
 
 Inject `NgFlowService` for viewport control, node/edge manipulation, and spatial queries:
@@ -212,10 +247,30 @@ flow.applyLayout(layoutNodes, { direction: 'LR' });
 ```
 
 Options: `direction` (`'TB' | 'LR' | 'BT' | 'RL'`, default `'TB'`), `nodeSep`
-(default 50), `rankSep` (default 80). Node dimensions resolve from
-`measured` → `width`/`height` → `initialWidth`/`initialHeight` → 150×40. Any
-function with the same shape plugs
-into `applyLayout` (elk, custom grids, …).
+(default 50), `rankSep` (default 80). Node dimensions resolve from `measured` → `width`/`height` →
+`initialWidth`/`initialHeight` → 150×40, and edge labels reserve dagre space from
+`labelWidth`/`labelHeight` (auto-measured by `applyLayout`) or a default box when an
+edge has a non-empty `label`. Any function with the same shape plugs into
+`applyLayout` (elk, custom grids, …).
+
+### Controlled mode and `measured`
+
+In controlled mode (`[nodes]` bound, re-emitted from `(nodesChange)`), re-emitting
+nodes that don't carry `measured` resets the stored dimensions. `applyLayout` reads
+live DOM sizes so layout stays correct regardless — but floating edges and `fitView`
+read the stored `measured` directly. If your app hand-handles only some changes (e.g.
+keeps `position` authority in a journal), forward dimension changes with
+`applyDimensionChanges` so `measured` stays current:
+
+```ts
+import { applyDimensionChanges } from '@angflow/angular';
+
+onNodesChange(changes: NodeChange[]) {
+  // keep measured flowing back: floating edges, fitView, layout stay correct
+  this.nodes.update((ns) => applyDimensionChanges(changes, ns));
+  // ...your own position/data handling on top...
+}
+```
 
 ## Animations
 
@@ -233,6 +288,44 @@ Animated paths: `setNodePositions`, `applyLayout`, and the agent bridge's
 tween on that node, and everything is disabled under `prefers-reduced-motion`.
 Per-call override: `flow.setNodePositions(positions, { animate: false })`.
 
+## Group Collapse
+
+Set `collapsed: true` on a group/parent node and angflow folds it: descendants stop
+rendering, the box drops to a header strip (`.collapsed` CSS class), and edges crossing
+the boundary reroute onto the box (parallels merge). It is nesting-aware — edges reroute
+to the outermost collapsed ancestor.
+
+```ts
+flow.setNodeCollapsed(groupId, true);   // or toggleNodeCollapsed(groupId)
+```
+
+`collapsed` lives on the node, so in controlled mode it round-trips through
+`(nodesChange)` like any other field. A merged (deduped) display edge is render-only and
+carries its underlying edge ids on `collapsedFrom`; a 1:1 rerouted edge keeps its original
+identity. Rerouted edges attach to the box via the normal edge geometry — cleanest under
+`edgeMode="floating"`. The collapsed box renders at `--xy-node-collapsed-height` (40px
+default); auto-sizing the expanded box to its children is separate.
+
+## Group Auto-Size
+
+Compute a box that wraps a group's members, or have the service size a group for you:
+
+```ts
+import { getGroupBounds } from '@angflow/angular';
+
+// Pure: bounds in the same coordinate space as the members you pass.
+const box = getGroupBounds(members, { padding: 24, headerHeight: 40 });
+
+// Imperative: size + position a group to wrap its children, keeping them pinned.
+await flow.sizeGroupToChildren(groupId, { padding: 24, headerHeight: 40 });
+```
+
+`getGroupBounds` resolves member sizes `measured → width → 0` and applies an asymmetric top
+(`headerHeight`) vs. other-sides (`padding`) inset. `sizeGroupToChildren` sets the group's
+`width`/`height` and moves its top-left to wrap its `parentId` children, re-basing the children so
+they stay visually fixed (nested groups handled via absolute-coordinate translation). It is a no-op
+for a childless group.
+
 ## Architecture
 
 - **Signal-based state** — Angular 17+ signals for fine-grained reactivity (no RxJS in the store)

package/dist/base.css

@@ -955,6 +955,14 @@ svg.xy-flow__connectionline {
 }
 
 
+.xy-flow__node.collapsed {
+  /* Folded group: drop the expanded footprint to a header strip. Overrides an
+     inline style.height set in controlled mode; apps may extend this rule. */
+  height: var(--xy-node-collapsed-height, 40px) !important;
+  overflow: hidden;
+}
+
+
 /* Entry animation — applied by the node renderer when [animate] is enabled.
    Uses the standalone `scale` property so it composes with the inline
    translate() transform instead of overriding it. */

package/dist/esm/index.d.ts

@@ -1,2 +1 @@
 export * from './lib/public-api';
-//# sourceMappingURL=index.d.ts.map

package/dist/esm/lib/agent/agent-bridge.service.d.ts

@@ -48,6 +48,7 @@ export declare class AngflowAgentBridge {
     private readonly history;
     private readonly handlers;
     private readonly injector;
+    private readonly destroyRef;
     private readonly layoutFn;
     private started;
     private nextInProcessId;
@@ -82,6 +83,8 @@ export declare class AngflowAgentBridge {
      */
     callTool(method: string, params?: Record<string, unknown>): Promise<unknown>;
     private start;
+    /** Stop all transports. Invoked automatically when the owning injector is destroyed. */
+    private stop;
     private dispatch;
     private findFlowId;
     private emitHistory;
@@ -92,4 +95,3 @@ export declare class AngflowAgentBridge {
     static ɵfac: i0.ɵɵFactoryDeclaration<AngflowAgentBridge, [{ optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AngflowAgentBridge>;
 }
-//# sourceMappingURL=agent-bridge.service.d.ts.map

package/dist/esm/lib/agent/agent-bridge.service.js

@@ -1,4 +1,4 @@
-import { Inject, Injectable, InjectionToken, Injector, Optional, effect, inject, runInInjectionContext, signal, } from '@angular/core';
+import { DestroyRef, Inject, Injectable, InjectionToken, Injector, Optional, effect, inject, runInInjectionContext, signal, } from '@angular/core';
 import { AgentHistory } from './history';
 import { AGENT_TOOL_SCHEMAS } from './tool-schemas';
 import * as i0 from "@angular/core";
@@ -27,6 +27,9 @@ const MUTATING_TOOLS = new Set([
     'set_nodes',
     'set_edges',
 ]);
+// apply_changes is treated specially — see dispatch logic.
+/** Max flow.state emission rate while any node drag is in progress. */
+const DRAG_STATE_EMIT_INTERVAL_MS = 100;
 /**
  * Routes JSON-RPC requests from one or more transports to registered
  * `NgFlowService` instances, and pushes change events back to the agent.
@@ -58,6 +61,7 @@ export class AngflowAgentBridge {
         this.flows = new Map();
         this.handlers = new Map();
         this.injector = inject(Injector);
+        this.destroyRef = inject(DestroyRef);
         this.started = false;
         this.nextInProcessId = 1;
         this.warnedOnBeforeDeleteBypass = false;
@@ -70,6 +74,7 @@ export class AngflowAgentBridge {
         this.layoutFn = layoutFn ?? null;
         this.installHandlers();
         this.start();
+        this.destroyRef.onDestroy(() => this.stop());
     }
     reportError(err, ctx) {
         if (!this.onError)
@@ -161,6 +166,20 @@ export class AngflowAgentBridge {
             }
         }
     }
+    /** Stop all transports. Invoked automatically when the owning injector is destroyed. */
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        for (const t of this.transports) {
+            try {
+                t.stop();
+            }
+            catch {
+                // A transport that throws during teardown must not break the others.
+            }
+        }
+    }
     async dispatch(req) {
         const handler = this.handlers.get(req.method);
         if (!handler) {
@@ -172,6 +191,7 @@ export class AngflowAgentBridge {
         try {
             const params = req.params ?? {};
             if (req.method === 'list_flows') {
+                // list_flows ignores the service arg; null stub avoids resolving a flow.
                 const result = await handler(null, params);
                 return { id: req.id, result };
             }
@@ -297,6 +317,35 @@ export class AngflowAgentBridge {
         let pending = false;
         let destroyed = false;
         let lastSignature = '';
+        let lastEmitTime = Number.NEGATIVE_INFINITY;
+        let trailingTimer = null;
+        const emitState = (isDrag) => {
+            // Re-read at emit time so coalesced/throttled bursts see the latest state.
+            const params = {
+                flowId: id,
+                nodes: flow.getNodes(),
+                edges: flow.getEdges(),
+                viewport: flow.getViewport(),
+                selection: {
+                    nodeIds: flow.selectedNodes().map((n) => n.id),
+                    edgeIds: flow.selectedEdges().map((e) => e.id),
+                },
+            };
+            const sig = signatureOf(params);
+            if (sig === lastSignature)
+                return;
+            lastSignature = sig;
+            // Only record the drag-emission timestamp when actually in a drag — so a
+            // non-drag emission (register, mutation tool) does not push back the next
+            // drag frame's throttle window.
+            if (isDrag) {
+                lastEmitTime = Date.now();
+            }
+            else {
+                lastEmitTime = Number.NEGATIVE_INFINITY;
+            }
+            this.emit({ event: 'flow.state', params });
+        };
         const ref = runInInjectionContext(this.injector, () => effect(() => {
             // Touch every signal we want to broadcast so the effect re-runs on change.
             flow.nodes();
@@ -314,29 +363,39 @@ export class AngflowAgentBridge {
                 // push state for a flowId that's no longer registered.
                 if (destroyed)
                     return;
-                // Re-read on flush so coalesced bursts see the latest state.
-                const params = {
-                    flowId: id,
-                    nodes: flow.getNodes(),
-                    edges: flow.getEdges(),
-                    viewport: flow.getViewport(),
-                    selection: {
-                        nodeIds: flow.selectedNodes().map((n) => n.id),
-                        edgeIds: flow.selectedEdges().map((e) => e.id),
-                    },
-                };
-                // Suppress duplicate emissions when controlled-mode round-trips bounce
-                // identical state through the store twice. See signatureOf for the
-                // field set; it must cover anything a mutating tool can change.
-                const sig = signatureOf(params);
-                if (sig === lastSignature)
-                    return;
-                lastSignature = sig;
-                this.emit({ event: 'flow.state', params });
+                // While a drag is in flight the store re-emits nodes per pointer
+                // frame; serializing the whole graph at that rate floods every
+                // transport. Throttle to one emission per interval with a trailing
+                // emit so the final drag state is never lost. The timer only
+                // schedules the emission — no view state is written here.
+                const dragging = flow.getNodes().some((n) => n.dragging === true);
+                if (dragging) {
+                    const elapsed = Date.now() - lastEmitTime;
+                    if (elapsed < DRAG_STATE_EMIT_INTERVAL_MS) {
+                        if (trailingTimer === null) {
+                            trailingTimer = setTimeout(() => {
+                                trailingTimer = null;
+                                if (destroyed)
+                                    return;
+                                emitState(true);
+                            }, DRAG_STATE_EMIT_INTERVAL_MS - elapsed);
+                        }
+                        return;
+                    }
+                }
+                if (trailingTimer !== null) {
+                    clearTimeout(trailingTimer);
+                    trailingTimer = null;
+                }
+                emitState(dragging);
             });
         }));
         return () => {
             destroyed = true;
+            if (trailingTimer !== null) {
+                clearTimeout(trailingTimer);
+                trailingTimer = null;
+            }
             ref.destroy();
         };
     }
@@ -586,7 +645,6 @@ export class AngflowAgentBridge {
                 const hasDelete = ops.some((o) => o['op'] === 'delete_elements');
                 if (hasDelete) {
                     this.warnedOnBeforeDeleteBypass = true;
-                    // eslint-disable-next-line no-console
                     console.warn('[angflow] apply_changes/delete_elements bypasses onBeforeDelete. ' +
                         'Call the standalone `delete_elements` tool if you need the veto hook.');
                 }
@@ -740,6 +798,10 @@ export class AngflowAgentBridge {
                     width: internal?.measured?.width ?? n.width ?? 150,
                     height: internal?.measured?.height ?? n.height ?? 40,
                     position: { x: n.position.x, y: n.position.y },
+                    // Forward parentId only when the parent is also being laid out, so the
+                    // layout fn clusters grouped children within their group. Excluding the
+                    // parent (e.g. via nodeIds) drops it — the child is then a free node.
+                    parentId: n.parentId != null && idSet.has(n.parentId) ? n.parentId : undefined,
                 };
             });
             // Induced subgraph: only edges with BOTH endpoints in the target set.
@@ -774,7 +836,6 @@ export class AngflowAgentBridge {
                 applied[id] = { x: pos.x, y: pos.y };
             }
             if (unknownIds.length > 0) {
-                // eslint-disable-next-line no-console
                 console.warn(`[angflow] layout_nodes: layout function returned positions for unknown node ids ` +
                     `(ignored): ${unknownIds.join(', ')}`);
             }
@@ -789,7 +850,10 @@ export class AngflowAgentBridge {
             }
             // Honors the host's [animate] input: positions tween when it's on, and
             // the await keeps the subsequent fitView measuring settled positions.
-            await flow.setNodePositions(actuallyApplied);
+            // Layout fns emit flow-absolute coordinates, so apply in absolute space:
+            // setNodePositions resolves each parented child against its parent's new
+            // position, keeping grouped children inside their group.
+            await flow.setNodePositions(actuallyApplied, { coordinateSpace: 'absolute' });
             const shouldFit = params['fitView'] !== false;
             if (shouldFit && Object.keys(actuallyApplied).length > 0) {
                 try {
@@ -899,6 +963,9 @@ function executeOp(flow, op) {
             const nodes = op['nodes'];
             if (!Array.isArray(nodes))
                 throw new InvalidParamsError('add_nodes: "nodes" must be an array.');
+            if (nodes.length > MAX_BULK_ELEMENTS) {
+                throw new InvalidParamsError(`add_nodes: "nodes" exceeds the maximum of ${MAX_BULK_ELEMENTS} elements per call (got ${nodes.length}).`);
+            }
             const validated = nodes.map((n, i) => validateNodeShape(n, `apply_changes/add_nodes[${i}]`));
             flow.addNodes(validated);
             return validated.map((n) => flow.getNode(n.id)).filter((n) => !!n);
@@ -912,6 +979,9 @@ function executeOp(flow, op) {
             const edges = op['edges'];
             if (!Array.isArray(edges))
                 throw new InvalidParamsError('add_edges: "edges" must be an array.');
+            if (edges.length > MAX_BULK_ELEMENTS) {
+                throw new InvalidParamsError(`add_edges: "edges" exceeds the maximum of ${MAX_BULK_ELEMENTS} elements per call (got ${edges.length}).`);
+            }
             const validated = edges.map((e, i) => validateEdgeShape(e, `apply_changes/add_edges[${i}]`));
             flow.addEdges(validated);
             return validated.map((e) => flow.getEdge(e.id)).filter((e) => !!e);
@@ -1020,10 +1090,15 @@ function requireObject(params, key) {
     }
     return value;
 }
+/** Hard cap on elements per bulk call (nodes, edges, apply_changes ops). */
+const MAX_BULK_ELEMENTS = 5000;
 function requireArray(params, key) {
     const value = params[key];
     if (!Array.isArray(value))
         throw new InvalidParamsError(`Param "${key}" must be an array.`);
+    if (value.length > MAX_BULK_ELEMENTS) {
+        throw new InvalidParamsError(`Param "${key}" exceeds the maximum of ${MAX_BULK_ELEMENTS} elements per call (got ${value.length}).`);
+    }
     return value;
 }
 function optionalStringArray(params, key) {
@@ -1033,6 +1108,9 @@ function optionalStringArray(params, key) {
     if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
         throw new InvalidParamsError(`Param "${key}" must be an array of strings.`);
     }
+    if (value.length > MAX_BULK_ELEMENTS) {
+        throw new InvalidParamsError(`Param "${key}" exceeds the maximum of ${MAX_BULK_ELEMENTS} elements per call (got ${value.length}).`);
+    }
     return value;
 }
 const BADGE_COLOR_SET = new Set(['slate', 'indigo', 'emerald', 'amber', 'rose']);
@@ -1116,6 +1194,33 @@ function validateTemplateSpec(value, ctx) {
     }
     return value;
 }
+/**
+ * CSS values that can fetch remote resources (`url(`) or execute in legacy
+ * engines (`expression(`). Angular's style sanitization already blocks
+ * script execution, so this is a narrow redressing/beaconing guard rather
+ * than a full CSS allowlist.
+ */
+const CSS_VALUE_BLOCKLIST = /url\s*\(|expression\s*\(/i;
+/** Shared style/className validation for agent-supplied nodes and edges. */
+function validateStyleAndClassName(o, ctx, kind) {
+    const style = o['style'];
+    if (style !== undefined) {
+        if (!style || typeof style !== 'object' || Array.isArray(style)) {
+            throw new InvalidParamsError(`${ctx}: ${kind}.style must be a plain object of CSS property/value pairs.`);
+        }
+        for (const [prop, raw] of Object.entries(style)) {
+            if (typeof raw !== 'string' && typeof raw !== 'number') {
+                throw new InvalidParamsError(`${ctx}: ${kind}.style["${prop}"] must be a string or number.`);
+            }
+            if (typeof raw === 'string' && CSS_VALUE_BLOCKLIST.test(raw)) {
+                throw new InvalidParamsError(`${ctx}: ${kind}.style["${prop}"] must not contain "url(" or "expression(".`);
+            }
+        }
+    }
+    if (o['className'] !== undefined && typeof o['className'] !== 'string') {
+        throw new InvalidParamsError(`${ctx}: ${kind}.className must be a string.`);
+    }
+}
 /** Validate that `value` is a structurally valid Node payload for add_*. */
 function validateNodeShape(value, ctx) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -1136,6 +1241,7 @@ function validateNodeShape(value, ctx) {
     if (!Number.isFinite(p['x']) || !Number.isFinite(p['y'])) {
         throw new InvalidParamsError(`${ctx}: node.position.{x,y} must be finite (no NaN/Infinity).`);
     }
+    validateStyleAndClassName(n, ctx, 'node');
     return value;
 }
 /** Validate that `value` is a structurally valid Edge payload for add_*. */
@@ -1153,6 +1259,7 @@ function validateEdgeShape(value, ctx) {
     if (typeof e['target'] !== 'string' || e['target'].length === 0) {
         throw new InvalidParamsError(`${ctx}: edge.target must be a non-empty string.`);
     }
+    validateStyleAndClassName(e, ctx, 'edge');
     return value;
 }
 //# sourceMappingURL=agent-bridge.service.js.map