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

package/fesm2022/xui-node-graph.mjs

@@ -752,9 +752,12 @@ class XuiGraphControls {
     step = this.config.zoomStep;
     buttonClass = 'text-foreground-muted hover:bg-hover-overlay hover:text-foreground focus-visible:ring-focus flex h-7 w-7 ' +
         'cursor-pointer items-center justify-center rounded transition-colors focus-visible:ring-2 focus-visible:outline-none';
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
+    /** Show the fit-to-view button. */
     showFit = input(true, { ...(ngDevMode ? { debugName: "showFit" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Show the current zoom as a percentage between the zoom buttons. */
     showZoomLevel = input(true, { ...(ngDevMode ? { debugName: "showZoomLevel" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** Lay the buttons out in a column (default) or a row. */
     orientation = input('vertical', /* @ts-ignore */
@@ -878,8 +881,13 @@ class XuiGraphGroup {
     /** Matches the `group` input on the nodes that belong to this frame. */
     groupId = input.required(/* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "groupId" }] : /* istanbul ignore next */ []));
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
+    /**
+     * The group's caption. An empty label drops the header entirely, and with it the vertical offset it adds to the
+     * group's contents.
+     */
     label = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
     /** Border and title colour; a tint of it fills the frame. Any CSS colour. */
@@ -887,7 +895,11 @@ class XuiGraphGroup {
     ...(ngDevMode ? [{ debugName: "color" }] : /* istanbul ignore next */ []));
     /** Blank margin between the members' bounding box and the frame. */
     padding = input(24, { ...(ngDevMode ? { debugName: "padding" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Let the group be selected by clicking it or by a marquee. */
     selectable = input(true, { ...(ngDevMode ? { debugName: "selectable" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Let the group be dragged, taking the nodes inside it along. A locked group, or a locked graph, overrides this.
+     */
     draggable = input(true, { ...(ngDevMode ? { debugName: "draggable" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** Pins the frame and everything in it. */
     locked = input(false, { ...(ngDevMode ? { debugName: "locked" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
@@ -1058,6 +1070,7 @@ class XuiGraphMinimap {
     store = inject(XuiNodeGraphStore);
     element = inject(ElementRef).nativeElement;
     dragging = false;
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     /** Blank margin around the content, in graph units. */
@@ -1278,6 +1291,7 @@ class XuiGraphPort {
     /** Unique within the owning node — the node id supplies the rest of the identity. */
     portId = input.required(/* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "portId" }] : /* istanbul ignore next */ []));
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     /**
@@ -1287,6 +1301,7 @@ class XuiGraphPort {
      */
     direction = input('input', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "direction" }] : /* istanbul ignore next */ []));
+    /** The port's caption. Also its accessible name, falling back to the port id when empty. */
     label = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
     /**
@@ -1300,6 +1315,7 @@ class XuiGraphPort {
     /** Overrides the colour inherited from {@link dataType}. */
     color = input(/* @ts-ignore */
     ...(ngDevMode ? [undefined, { debugName: "color" }] : /* istanbul ignore next */ []));
+    /** Block connections to and from this port. It stays visible and keeps its existing edges. */
     disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /**
      * Which node edge the connector sits on. Leave unset to take it from
@@ -1307,6 +1323,7 @@ class XuiGraphPort {
      */
     side = input(/* @ts-ignore */
     ...(ngDevMode ? [undefined, { debugName: "side" }] : /* istanbul ignore next */ []));
+    /** Override the port's glyph. Falls back to the shape declared for its type, then to the graph's default. */
     shape = input(/* @ts-ignore */
     ...(ngDevMode ? [undefined, { debugName: "shape" }] : /* istanbul ignore next */ []));
     /**
@@ -1638,11 +1655,13 @@ class XuiGraphNode {
     /** Identifies the node to edges and to the selection. Must be stable and unique. */
     nodeId = input.required(/* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "nodeId" }] : /* istanbul ignore next */ []));
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     /** Top-left corner in graph space. Two-way bound so the host owns the value. */
     position = model({ x: 0, y: 0 }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "position" }] : /* istanbul ignore next */ []));
+    /** The node's caption, shown in its header. */
     label = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
     /** Fixed width in graph units. Leave unset to size to content. */
@@ -1669,8 +1688,14 @@ class XuiGraphNode {
      */
     collapsed = model(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "collapsed" }] : /* istanbul ignore next */ []));
+    /** Add a header toggle that folds the node's body away, leaving its ports and edges intact. */
     collapsible = input(false, { ...(ngDevMode ? { debugName: "collapsible" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Let the node be selected. Also what gives it `role="option"` and `aria-selected`; an unselectable node has
+     * neither.
+     */
     selectable = input(true, { ...(ngDevMode ? { debugName: "selectable" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Let the node be dragged. A locked node, or a locked graph, overrides this. */
     draggable = input(true, { ...(ngDevMode ? { debugName: "draggable" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** Pins the node in place while leaving it selectable. */
     locked = input(false, { ...(ngDevMode ? { debugName: "locked" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
@@ -1945,6 +1970,7 @@ const NON_DRAGGABLE = '[data-xui-graph-port], [data-xui-graph-no-drag], input, t
  * ```
  */
 class XuiGraphNodeHeader {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     computedClass = computed(() => xui('flex min-w-0 flex-1 items-center gap-2 truncate', this.class()), /* @ts-ignore */
@@ -1964,6 +1990,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
         }], propDecorators: { class: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }] } });
 /** Trailing controls in a node header — a menu button, a toggle, a status dot. */
 class XuiGraphNodeActions {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     computedClass = computed(() => xui('flex shrink-0 items-center gap-1', this.class()), /* @ts-ignore */
@@ -1986,6 +2013,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * render, a waveform. Sits above the port rows, as it does in a VFX graph.
  */
 class XuiGraphNodePreview {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     computedClass = computed(() => xui('border-border-muted block overflow-hidden border-b', this.class()), /* @ts-ignore */
@@ -2028,6 +2056,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * ```
  */
 class XuiGraphOverlay {
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     // eslint-disable-next-line local/no-hand-z-index -- slots overlay their own node inside the graph’s stacking context
@@ -2321,6 +2350,7 @@ class XuiNodeGraph {
     ...(ngDevMode ? [{ debugName: "marqueeState" }] : /* istanbul ignore next */ []));
     /** The store for this canvas. Use it to drive the view from a host component. */
     store = inject(XuiNodeGraphStore);
+    /** Extra classes, merged into the component's own rather than replacing them. */
     class = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "class" }] : /* istanbul ignore next */ []));
     /** The wires to draw. Never mutated — see `connect`. */
@@ -2329,26 +2359,48 @@ class XuiNodeGraph {
     /** Pan and zoom. Two-way bindable, so a host can save and restore the view. */
     viewport = model({ x: 0, y: 0, zoom: 1 }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "viewport" }] : /* istanbul ignore next */ []));
+    /**
+     * How edges are drawn between ports: curved (`bezier`), right-angled (`orthogonal`), rounded right angles
+     * (`smoothstep`), or direct (`straight`).
+     */
     routing = input(this.config.routing, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "routing" }] : /* istanbul ignore next */ []));
+    /** The canvas pattern behind the graph, which scales with the zoom. */
     background = input(this.config.background, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "background" }] : /* istanbul ignore next */ []));
+    /** Default end marker on an edge. An edge may override it. */
     marker = input(this.config.marker, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "marker" }] : /* istanbul ignore next */ []));
+    /** Spacing of the background pattern, and the step nodes snap to when `snapToGrid` is on. */
     gridSize = input(this.config.gridSize, { ...(ngDevMode ? { debugName: "gridSize" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /**
+     * Round node positions to `gridSize` as they are dragged. Holding Shift while nudging with the arrow keys does the
+     * same.
+     */
     snapToGrid = input(this.config.snapToGrid, { ...(ngDevMode ? { debugName: "snapToGrid" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** How far the canvas can zoom out, as a scale factor. */
     minZoom = input(this.config.minZoom, { ...(ngDevMode ? { debugName: "minZoom" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** How far the canvas can zoom in, as a scale factor. */
     maxZoom = input(this.config.maxZoom, { ...(ngDevMode ? { debugName: "maxZoom" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Default stroke width for edges, in graph units. An edge may override it. */
     edgeWidth = input(this.config.edgeWidth, { ...(ngDevMode ? { debugName: "edgeWidth" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Default port glyph size, in graph units. */
     portSize = input(this.config.portSize, { ...(ngDevMode ? { debugName: "portSize" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Default port glyph. A port type, or the port itself, may override it. */
     portShape = input(this.config.portShape, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "portShape" }] : /* istanbul ignore next */ []));
+    /** Default port colour. A port type, or the port itself, may override it. */
     portColor = input(this.config.portColor, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "portColor" }] : /* istanbul ignore next */ []));
     /** Data-type registry: colour, glyph and label per `dataType`. */
     portTypes = input(this.config.portTypes, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "portTypes" }] : /* istanbul ignore next */ []));
+    /** Let an edge run from a node back to itself. */
     allowSelfConnection = input(this.config.allowSelfConnection, { ...(ngDevMode ? { debugName: "allowSelfConnection" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Refuse a connection between ports whose declared types do not match. Off by default, which leaves validation to
+     * the host.
+     */
     enforcePortTypes = input(this.config.enforcePortTypes, { ...(ngDevMode ? { debugName: "enforcePortTypes" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** Last say on whether a connection may be made. Runs after the built-in rules. */
     isValidConnection = input(/* @ts-ignore */
@@ -2363,17 +2415,26 @@ class XuiNodeGraph {
      */
     zoomActivation = input('wheel', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "zoomActivation" }] : /* istanbul ignore next */ []));
+    /**
+     * Zoom on wheel. Turn it off inside a scrolling page, where the wheel should scroll past the graph rather than into
+     * it.
+     */
     zoomOnScroll = input(true, { ...(ngDevMode ? { debugName: "zoomOnScroll" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** A connection that passed every rule. The host decides whether to add it. */
     connect = output();
     /** A wire dropped on empty canvas — the hook for "drag out to create a node". */
     connectionDrop = output();
+    /** Emits the edge that was clicked. */
     edgeClick = output();
     /** Fired once per drag, when the pointer is released. */
     nodeMove = output();
+    /** Emits the selected node and edge ids whenever the selection changes. */
     selectionChange = output();
     /** Delete or Backspace over the canvas. The host performs the removal. */
     deleteSelection = output();
+    /**
+     * Emits a right-click on empty canvas, with the position in graph coordinates — the hook for a "new node here" menu.
+     */
     canvasContextMenu = output();
     Math = Math;
     arrowId = `xui-graph-arrow-${this.uid}`;