@net-advantage/nabs-ui-graph

Canvas-based graph board control for the Nabs UI library.

Features

• Pan and wheel zoom canvas interactions
• Node creation and drag-move
• Edge creation between selected nodes
• Node and edge labels
• Collapsible toolbox rail
• Pluggable toolbox architecture with toolset definitions

Install

This package is part of the Nabs monorepo and is consumed as a workspace package.

Basic Usage

import { Graph } from "@net-advantage/nabs-ui-graph";
import "@net-advantage/nabs-ui-graph/style.css";

export function Example() {
  return <Graph toolboxLabel="Tools" />;
}

Graph API

Graph props

• toolboxLabel?: string
  • Accessible label for the toolbox toolbar.
• toolset?: "simple" | "agentic-workflow"
  • Selects one of the built-in toolsets. Defaults to "simple".
• toolsets?: GraphToolsetDefinition[]
  • Optional custom toolsets. If provided, this overrides toolset.
• ToolboxComponent?: ComponentType<GraphToolboxProps>
  • Optional custom toolbox renderer. Defaults to SimpleGraphToolset.
• onShapeAdd?: (shape: GraphShape) => void
  • Called when a node is created.
• onShapeMove?: (shape: GraphShape) => void
  • Called when a node is moved.

Exported types

• GraphShape
• GraphNodeType
• GraphToolDefinition
• GraphToolsetDefinition
• GraphToolboxProps

Pluggable Toolsets

Toolsets are independent groups of tools. Each toolset can keep its own active tool state.

import { Graph, type GraphToolsetDefinition } from "@net-advantage/nabs-ui-graph";

const customToolsets: GraphToolsetDefinition[] = [
  {
    id: "simple-graph-toolset",
    label: "Simple Graph Toolset",
    tools: [
      { id: "square", label: "Square", kind: "node", nodeType: "square" },
      { id: "circle", label: "Circle", kind: "node", nodeType: "circle" },
      { id: "edge", label: "Edge", kind: "edge" },
    ],
  },
];

export function Example() {
  return <Graph toolsets={customToolsets} />;
}

Built-in Toolset Selection

import { Graph } from "@net-advantage/nabs-ui-graph";

export function Example() {
  return <Graph toolset="agentic-workflow" toolboxLabel="Workflow Tools" />;
}

agentic-workflow includes:

• Initiative node (rectangle)
• Scenario node (parallelogram)
• Lifecycle node (circle)
• Context node (document)
• Connector tool for straight, labeled links

Connection rules currently enforced in this built-in toolset:

• Initiative -> Scenario uses label ResultIn
• Initiative -> Initiative uses label Extend (single parent and no cycles)
• Scenario -> Lifecycle uses label Use (one lifecycle target per scenario)
• Context -> Lifecycle uses label UsedBy
• Unsupported links are blocked
• Node labels are rendered inside nodes with wrapping/truncation up to four lines

Custom Toolbox Component

You can fully replace toolbox rendering while keeping the graph canvas behavior.

import {
  Graph,
  type GraphToolboxProps,
} from "@net-advantage/nabs-ui-graph";

function MyToolbox(props: GraphToolboxProps) {
  const {
    toolboxLabel,
    toolsets,
    isCollapsed,
    onToggleCollapse,
    onToolClick,
    onToolDoubleClick,
    activeToolIdsBySet,
    isEdgeToolEnabled,
    edgeHint,
  } = props;

  return (
    <div role="toolbar" aria-label={toolboxLabel}>
      <button type="button" onClick={onToggleCollapse}>
        {isCollapsed ? "Expand" : "Collapse"}
      </button>

      {!isCollapsed &&
        toolsets.map((set) => (
          <section key={set.id}>
            {set.label && <h4>{set.label}</h4>}
            {set.tools.map((tool) => {
              const active = activeToolIdsBySet[set.id] === tool.id;
              const disabled = tool.kind === "edge" && !isEdgeToolEnabled;
              return (
                <button
                  key={tool.id}
                  type="button"
                  disabled={disabled}
                  aria-pressed={active}
                  title={tool.kind === "edge" ? edgeHint : tool.label}
                  onClick={() => onToolClick(tool, set.id)}
                  onDoubleClick={() => onToolDoubleClick(tool, set.id)}
                >
                  {tool.label}
                </button>
              );
            })}
          </section>
        ))}
    </div>
  );
}

export function Example() {
  return <Graph ToolboxComponent={MyToolbox} />;
}

Built-in Sample Toolset

The package also exports a sample toolbox renderer and its toolset config:

• SimpleGraphToolset
• simpleGraphToolset
• simpleGraphToolsets

It also exports the agentic workflow toolset definitions:

• agenticWorkflowToolset
• agenticWorkflowToolsets

These live under the package toolsets folder and are intended as a reference implementation for custom toolboxes.