@xui/node-graph 2.0.0-alpha.20 → 2.0.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xui/node-graph",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.21",
   "description": "Modern Angular 22 UI Library based on TailwindCSS",
   "keywords": [
     "angular",
@@ -38,7 +38,7 @@
   "peerDependencies": {
     "@angular/cdk": "22",
     "@angular/core": "22",
-    "@xui/core": "2.0.0-alpha.20",
+    "@xui/core": "2.0.0-alpha.21",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1"
   },

package/types/xui-node-graph.d.ts

@@ -559,8 +559,11 @@ declare class XuiGraphControls {
     protected readonly store: XuiNodeGraphStore;
     protected readonly step: number;
     protected readonly buttonClass: string;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
+    /** Show the fit-to-view button. */
     readonly showFit: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Show the current zoom as a percentage between the zoom buttons. */
     readonly showZoomLevel: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** Lay the buttons out in a column (default) or a row. */
     readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
@@ -599,13 +602,22 @@ declare class XuiGraphGroup implements XuiGraphGroupHandle, OnInit {
     private readonly dragOrigin;
     /** Matches the `group` input on the nodes that belong to this frame. */
     readonly groupId: _angular_core.InputSignal<string>;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
+    /**
+     * The group's caption. An empty label drops the header entirely, and with it the vertical offset it adds to the
+     * group's contents.
+     */
     readonly label: _angular_core.InputSignal<string>;
     /** Border and title colour; a tint of it fills the frame. Any CSS colour. */
     readonly color: _angular_core.InputSignal<string>;
     /** Blank margin between the members' bounding box and the frame. */
     readonly padding: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /** Let the group be selected by clicking it or by a marquee. */
     readonly selectable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Let the group be dragged, taking the nodes inside it along. A locked group, or a locked graph, overrides this.
+     */
     readonly draggable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** Pins the frame and everything in it. */
     readonly locked: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
@@ -665,6 +677,7 @@ declare class XuiGraphMinimap {
     private readonly store;
     private readonly element;
     private dragging;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     /** Blank margin around the content, in graph units. */
     readonly padding: _angular_core.InputSignalWithTransform<number, NumberInput>;
@@ -734,6 +747,7 @@ declare class XuiGraphPort implements XuiGraphPortHandle, OnInit {
     key: string;
     /** Unique within the owning node — the node id supplies the rest of the identity. */
     readonly portId: _angular_core.InputSignal<string>;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     /**
      * Which way data flows. `inout` covers terminals that are neither source nor
@@ -741,6 +755,7 @@ declare class XuiGraphPort implements XuiGraphPortHandle, OnInit {
      * drawn first.
      */
     readonly direction: _angular_core.InputSignal<XuiGraphPortDirection>;
+    /** The port's caption. Also its accessible name, falling back to the port id when empty. */
     readonly label: _angular_core.InputSignal<string>;
     /**
      * The compatibility key. Two ports may only be wired together when their data
@@ -751,12 +766,14 @@ declare class XuiGraphPort implements XuiGraphPortHandle, OnInit {
     readonly dataType: _angular_core.InputSignal<string | undefined>;
     /** Overrides the colour inherited from {@link dataType}. */
     readonly color: _angular_core.InputSignal<string | undefined>;
+    /** Block connections to and from this port. It stays visible and keeps its existing edges. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /**
      * Which node edge the connector sits on. Leave unset to take it from
      * {@link direction} — inputs on the left, outputs on the right.
      */
     readonly side: _angular_core.InputSignal<XuiGraphPortSide | undefined>;
+    /** Override the port's glyph. Falls back to the shape declared for its type, then to the graph's default. */
     readonly shape: _angular_core.InputSignal<XuiGraphPortShape | undefined>;
     /**
      * How many wires may terminate here. Defaults to 1 for an input — the usual
@@ -849,9 +866,11 @@ declare class XuiGraphNode implements XuiGraphNodeHandle, OnInit {
     readonly element: HTMLElement;
     /** Identifies the node to edges and to the selection. Must be stable and unique. */
     readonly nodeId: _angular_core.InputSignal<string>;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     /** Top-left corner in graph space. Two-way bound so the host owns the value. */
     readonly position: _angular_core.ModelSignal<XuiGraphPoint>;
+    /** The node's caption, shown in its header. */
     readonly label: _angular_core.InputSignal<string>;
     /** Fixed width in graph units. Leave unset to size to content. */
     readonly width: _angular_core.InputSignalWithTransform<number | undefined, NumberInput>;
@@ -873,8 +892,14 @@ declare class XuiGraphNode implements XuiGraphNodeHandle, OnInit {
      * subtree can be folded away without breaking its wiring.
      */
     readonly collapsed: _angular_core.ModelSignal<boolean>;
+    /** Add a header toggle that folds the node's body away, leaving its ports and edges intact. */
     readonly collapsible: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Let the node be selected. Also what gives it `role="option"` and `aria-selected`; an unselectable node has
+     * neither.
+     */
     readonly selectable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Let the node be dragged. A locked node, or a locked graph, overrides this. */
     readonly draggable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** Pins the node in place while leaving it selectable. */
     readonly locked: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
@@ -920,6 +945,7 @@ declare class XuiGraphNode implements XuiGraphNodeHandle, OnInit {
  * ```
  */
 declare class XuiGraphNodeHeader {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     protected readonly computedClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<XuiGraphNodeHeader, never>;
@@ -927,6 +953,7 @@ declare class XuiGraphNodeHeader {
 }
 /** Trailing controls in a node header — a menu button, a toggle, a status dot. */
 declare class XuiGraphNodeActions {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     protected readonly computedClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<XuiGraphNodeActions, never>;
@@ -937,6 +964,7 @@ declare class XuiGraphNodeActions {
  * render, a waveform. Sits above the port rows, as it does in a VFX graph.
  */
 declare class XuiGraphNodePreview {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     protected readonly computedClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<XuiGraphNodePreview, never>;
@@ -967,6 +995,7 @@ declare class XuiGraphNodePreview {
  * ```
  */
 declare class XuiGraphOverlay {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     protected readonly computedClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<XuiGraphOverlay, never>;
@@ -1032,25 +1061,48 @@ declare class XuiNodeGraph {
     private readonly marqueeState;
     /** The store for this canvas. Use it to drive the view from a host component. */
     readonly store: XuiNodeGraphStore;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     readonly class: _angular_core.InputSignal<ClassValue>;
     /** The wires to draw. Never mutated — see `connect`. */
     readonly edges: _angular_core.InputSignal<readonly XuiGraphEdge[]>;
     /** Pan and zoom. Two-way bindable, so a host can save and restore the view. */
     readonly viewport: _angular_core.ModelSignal<XuiGraphViewport>;
+    /**
+     * How edges are drawn between ports: curved (`bezier`), right-angled (`orthogonal`), rounded right angles
+     * (`smoothstep`), or direct (`straight`).
+     */
     readonly routing: _angular_core.InputSignal<XuiGraphRouting>;
+    /** The canvas pattern behind the graph, which scales with the zoom. */
     readonly background: _angular_core.InputSignal<XuiGraphBackground>;
+    /** Default end marker on an edge. An edge may override it. */
     readonly marker: _angular_core.InputSignal<XuiGraphMarker>;
+    /** Spacing of the background pattern, and the step nodes snap to when `snapToGrid` is on. */
     readonly gridSize: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /**
+     * Round node positions to `gridSize` as they are dragged. Holding Shift while nudging with the arrow keys does the
+     * same.
+     */
     readonly snapToGrid: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** How far the canvas can zoom out, as a scale factor. */
     readonly minZoom: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /** How far the canvas can zoom in, as a scale factor. */
     readonly maxZoom: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /** Default stroke width for edges, in graph units. An edge may override it. */
     readonly edgeWidth: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /** Default port glyph size, in graph units. */
     readonly portSize: _angular_core.InputSignalWithTransform<number, NumberInput>;
+    /** Default port glyph. A port type, or the port itself, may override it. */
     readonly portShape: _angular_core.InputSignal<XuiGraphPortShape>;
+    /** Default port colour. A port type, or the port itself, may override it. */
     readonly portColor: _angular_core.InputSignal<string>;
     /** Data-type registry: colour, glyph and label per `dataType`. */
     readonly portTypes: _angular_core.InputSignal<Record<string, XuiGraphPortType>>;
+    /** Let an edge run from a node back to itself. */
     readonly allowSelfConnection: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Refuse a connection between ports whose declared types do not match. Off by default, which leaves validation to
+     * the host.
+     */
     readonly enforcePortTypes: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** Last say on whether a connection may be made. Runs after the built-in rules. */
     readonly isValidConnection: _angular_core.InputSignal<XuiGraphConnectionValidator | undefined>;
@@ -1063,14 +1115,20 @@ declare class XuiNodeGraph {
      * bare wheel for panning and zooms only with the modifier, as design tools do.
      */
     readonly zoomActivation: _angular_core.InputSignal<"wheel" | "ctrl-wheel">;
+    /**
+     * Zoom on wheel. Turn it off inside a scrolling page, where the wheel should scroll past the graph rather than into
+     * it.
+     */
     readonly zoomOnScroll: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** A connection that passed every rule. The host decides whether to add it. */
     readonly connect: _angular_core.OutputEmitterRef<XuiGraphConnection>;
     /** A wire dropped on empty canvas — the hook for "drag out to create a node". */
     readonly connectionDrop: _angular_core.OutputEmitterRef<XuiGraphConnectionDrop>;
+    /** Emits the edge that was clicked. */
     readonly edgeClick: _angular_core.OutputEmitterRef<XuiGraphEdge>;
     /** Fired once per drag, when the pointer is released. */
     readonly nodeMove: _angular_core.OutputEmitterRef<XuiGraphNodeMove>;
+    /** Emits the selected node and edge ids whenever the selection changes. */
     readonly selectionChange: _angular_core.OutputEmitterRef<{
         nodes: string[];
         edges: string[];
@@ -1080,6 +1138,9 @@ declare class XuiNodeGraph {
         nodes: string[];
         edges: string[];
     }>;
+    /**
+     * Emits a right-click on empty canvas, with the position in graph coordinates — the hook for a "new node here" menu.
+     */
     readonly canvasContextMenu: _angular_core.OutputEmitterRef<{
         event: MouseEvent;
         position: XuiGraphPoint;