@stigmer/react 0.4.8 → 0.5.0

package/src/dependency-graph/DependencyGraph.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import { useCallback, useRef, type KeyboardEvent } from "react";
+import { cn } from "@stigmer/theme";
+import type { DependencyGraphProps } from "./types";
+import { DependencyTreeNode } from "./DependencyTreeNode";
+
+/**
+ * Accessible CSS-based tree visualization of an agent's dependencies.
+ *
+ * Renders `MCP Servers`, `Skills`, and `Sub-Agents` (with recursive
+ * sub-agent children) as a nested tree with visual connector lines.
+ * The root node represents the agent itself.
+ *
+ * Implements the WAI-ARIA TreeView pattern:
+ * - `role="tree"` on the root list
+ * - `role="treeitem"` on each node (via {@link DependencyTreeNode})
+ * - Arrow-key navigation between visible nodes (roving tabindex)
+ * - `Home`/`End` to jump to first/last visible node
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const { tree } = useDependencyGraph({
+ *   agentName: "pr-review-agent",
+ *   agentOrg: "acme",
+ *   spec: agent.spec,
+ * });
+ *
+ * {tree && (
+ *   <DependencyGraph
+ *     tree={tree}
+ *     onNodeClick={(node) => {
+ *       if (node.kind === "mcp-server") navigateTo(`/mcp-servers/${node.ref!.slug}`);
+ *     }}
+ *   />
+ * )}
+ * ```
+ */
+export function DependencyGraph({
+  tree,
+  onNodeClick,
+  defaultExpanded = true,
+  className,
+}: DependencyGraphProps) {
+  const treeRef = useRef<HTMLUListElement>(null);
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLUListElement>) => {
+      const container = treeRef.current;
+      if (!container) return;
+
+      const items = Array.from(
+        container.querySelectorAll<HTMLElement>(
+          "[role='treeitem'] > button, [role='treeitem'] > div",
+        ),
+      ).filter((el) => {
+        let parent = el.closest("[role='treeitem']")?.parentElement?.closest("[role='treeitem']");
+        while (parent) {
+          if (parent.getAttribute("aria-expanded") === "false") return false;
+          parent = parent.parentElement?.closest("[role='treeitem']");
+        }
+        return true;
+      });
+
+      if (items.length === 0) return;
+
+      const activeEl = document.activeElement as HTMLElement | null;
+      const currentIndex = activeEl ? items.indexOf(activeEl) : -1;
+
+      let nextIndex: number | null = null;
+
+      switch (e.key) {
+        case "ArrowDown":
+          nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0;
+          break;
+        case "ArrowUp":
+          nextIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1;
+          break;
+        case "Home":
+          nextIndex = 0;
+          break;
+        case "End":
+          nextIndex = items.length - 1;
+          break;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      items[nextIndex].focus();
+    },
+    [],
+  );
+
+  const { root } = tree;
+
+  return (
+    <div className={cn("py-2", className)}>
+      <div className="mb-3 flex items-center gap-2 px-2">
+        <TreeIcon className="size-4 text-muted-foreground" />
+        <h3 className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+          Dependency Tree
+        </h3>
+        <span className="text-xs text-muted-foreground">
+          {tree.nodeCount} {tree.nodeCount === 1 ? "node" : "nodes"}
+        </span>
+      </div>
+
+      <ul
+        ref={treeRef}
+        role="tree"
+        aria-label={`Dependencies of ${root.label}`}
+        onKeyDown={handleKeyDown}
+        className="rounded-lg border border-border p-2"
+      >
+        <DependencyTreeNode
+          node={root}
+          depth={0}
+          onNodeClick={onNodeClick}
+          defaultExpanded={defaultExpanded}
+        />
+      </ul>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Header icon
+// ---------------------------------------------------------------------------
+
+function TreeIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M8 2v4M8 6 4 10M8 6l4 4" />
+      <circle cx="8" cy="2" r="1" fill="currentColor" stroke="none" />
+      <circle cx="4" cy="11" r="1.5" />
+      <circle cx="8" cy="11" r="1.5" />
+      <circle cx="12" cy="11" r="1.5" />
+    </svg>
+  );
+}

package/src/dependency-graph/DependencyTreeNode.tsx

@@ -0,0 +1,282 @@
+"use client";
+
+import { useCallback, useState, type KeyboardEvent } from "react";
+import { cn } from "@stigmer/theme";
+import type { DependencyNode, NodeKind } from "./types";
+
+interface DependencyTreeNodeProps {
+  readonly node: DependencyNode;
+  readonly depth: number;
+  readonly onNodeClick?: (node: DependencyNode) => void;
+  readonly defaultExpanded: boolean;
+}
+
+const KIND_LABELS: Record<NodeKind, string> = {
+  agent: "Agent",
+  "mcp-server": "MCP",
+  skill: "Skill",
+  "sub-agent": "Sub-Agent",
+};
+
+/**
+ * Renders a single node in the dependency tree: icon, kind badge,
+ * label, metadata, and (for expandable nodes) an expand/collapse
+ * chevron with nested children.
+ *
+ * Leaf nodes (MCP servers, skills) with a `ref` are clickable —
+ * firing `onNodeClick` for consumer-wired navigation.
+ *
+ * Sub-agent nodes are collapsible containers, and the root agent
+ * node always renders its children expanded. Both recurse using
+ * the same component, keeping the ARIA tree structure correct
+ * (`<li role="treeitem">` wrapping a nested `<ul role="group">`).
+ */
+export function DependencyTreeNode({
+  node,
+  depth,
+  onNodeClick,
+  defaultExpanded,
+}: DependencyTreeNodeProps) {
+  const hasChildren = node.children.length > 0;
+  const isRoot = node.kind === "agent";
+  const isCollapsible = node.kind === "sub-agent" && hasChildren;
+  const isAlwaysExpanded = isRoot && hasChildren;
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  const isNavigable = node.ref != null && onNodeClick != null;
+
+  const showChildren = isAlwaysExpanded || (isCollapsible && expanded);
+
+  const handleClick = useCallback(() => {
+    if (isCollapsible) {
+      setExpanded((v) => !v);
+    } else if (isNavigable) {
+      onNodeClick(node);
+    }
+  }, [isCollapsible, isNavigable, onNodeClick, node]);
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      if (!isCollapsible) return;
+
+      if (e.key === "ArrowRight" && !expanded) {
+        e.preventDefault();
+        setExpanded(true);
+      } else if (e.key === "ArrowLeft" && expanded) {
+        e.preventDefault();
+        setExpanded(false);
+      }
+    },
+    [isCollapsible, expanded],
+  );
+
+  const content = (
+    <div className="flex min-w-0 items-center gap-2">
+      {isCollapsible && (
+        <ChevronIcon
+          className={cn(
+            "size-3.5 shrink-0 text-muted-foreground transition-transform",
+            expanded && "rotate-90",
+          )}
+        />
+      )}
+      <NodeIcon kind={node.kind} className="size-4 shrink-0 text-muted-foreground" />
+      {!isRoot && (
+        <span
+          className={cn(
+            "shrink-0 rounded px-1.5 py-px text-[10px] font-medium leading-tight",
+            kindBadgeClasses(node.kind),
+          )}
+        >
+          {KIND_LABELS[node.kind]}
+        </span>
+      )}
+      <span className="min-w-0 truncate text-sm font-medium text-foreground">
+        {node.qualifiedLabel ?? node.label}
+      </span>
+      {node.metadata &&
+        Object.entries(node.metadata).map(([key, value]) => (
+          <span
+            key={key}
+            className="shrink-0 text-xs text-muted-foreground"
+          >
+            {value}
+          </span>
+        ))}
+    </div>
+  );
+
+  const isInteractive = isCollapsible || isNavigable;
+
+  const isChild = depth > 0;
+
+  return (
+    <li
+      role="treeitem"
+      aria-expanded={isCollapsible ? expanded : isAlwaysExpanded ? true : undefined}
+      className={cn(
+        "list-none",
+        isChild && "relative before:absolute before:left-[-12px] before:top-[14px] before:h-px before:w-3 before:bg-border before:content-['']",
+      )}
+    >
+      {isInteractive ? (
+        <button
+          type="button"
+          onClick={handleClick}
+          onKeyDown={handleKeyDown}
+          tabIndex={-1}
+          className={cn(
+            "flex w-full items-center rounded-md px-2 py-1.5 text-left transition-colors",
+            "hover:bg-accent-hover",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+          )}
+        >
+          {content}
+        </button>
+      ) : (
+        <div className="flex items-center px-2 py-1.5">
+          {content}
+        </div>
+      )}
+
+      {node.description && !isRoot && (
+        <p
+          className={cn(
+            "px-2 pb-1 text-xs text-muted-foreground",
+            isCollapsible ? "ml-[calc(0.5rem+14px+0.5rem)]" : "ml-2",
+          )}
+        >
+          {node.description}
+        </p>
+      )}
+
+      {showChildren && (
+        <ul
+          role="group"
+          className="relative ml-[11px] border-l border-border pl-3"
+        >
+          {node.children.map((child) => (
+            <DependencyTreeNode
+              key={child.id}
+              node={child}
+              depth={depth + 1}
+              onNodeClick={onNodeClick}
+              defaultExpanded={defaultExpanded}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Kind badge styling — uses --stgm-* tokens, no hardcoded colors
+// ---------------------------------------------------------------------------
+
+function kindBadgeClasses(kind: NodeKind): string {
+  switch (kind) {
+    case "mcp-server":
+      return "bg-[var(--stgm-status-running-subtle)] text-[var(--stgm-status-running)]";
+    case "skill":
+      return "bg-[var(--stgm-status-pending-subtle)] text-[var(--stgm-status-pending)]";
+    case "sub-agent":
+      return "bg-[var(--stgm-status-ready-subtle)] text-[var(--stgm-status-ready)]";
+    case "agent":
+      return "bg-muted text-muted-foreground";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Icons — inline SVGs, consistent with AgentDetailView pattern
+// ---------------------------------------------------------------------------
+
+function NodeIcon({
+  kind,
+  className,
+}: {
+  readonly kind: NodeKind;
+  readonly className?: string;
+}) {
+  switch (kind) {
+    case "agent":
+    case "sub-agent":
+      return <AgentIcon className={className} />;
+    case "mcp-server":
+      return <McpServerIcon className={className} />;
+    case "skill":
+      return <SkillIcon className={className} />;
+  }
+}
+
+function AgentIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="3" y="5" width="10" height="8" rx="1.5" />
+      <path d="M6 9h.01M10 9h.01" strokeWidth="2" />
+      <path d="M8 2v3" />
+    </svg>
+  );
+}
+
+function McpServerIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="2" y="2" width="12" height="5" rx="1" />
+      <rect x="2" y="9" width="12" height="5" rx="1" />
+      <circle cx="5" cy="4.5" r="0.75" fill="currentColor" stroke="none" />
+      <circle cx="5" cy="11.5" r="0.75" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
+function SkillIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M9 1.5 4 9h4l-1 5.5L12 7H8l1-5.5Z" />
+    </svg>
+  );
+}
+
+function ChevronIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m6 3 5 5-5 5" />
+    </svg>
+  );
+}

package/src/dependency-graph/index.ts

@@ -0,0 +1,15 @@
+// Types
+export type {
+  NodeKind,
+  DependencyNode,
+  DependencyTree,
+  DependencyGraphProps,
+  UseDependencyGraphOptions,
+  UseDependencyGraphReturn,
+} from "./types";
+
+// Hooks
+export { useDependencyGraph } from "./useDependencyGraph";
+
+// Components
+export { DependencyGraph } from "./DependencyGraph";

package/src/dependency-graph/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Resource kind in a dependency tree.
+ *
+ * - `"agent"` — the root agent (always the tree root)
+ * - `"mcp-server"` — an MCP server referenced via `mcpServerUsages` or `mcpAccess`
+ * - `"skill"` — a skill referenced via `skillRefs`
+ * - `"sub-agent"` — an inline sub-agent definition with its own dependencies
+ */
+export type NodeKind = "agent" | "mcp-server" | "skill" | "sub-agent";
+
+/**
+ * A single node in the agent dependency tree.
+ *
+ * The tree is recursive: sub-agent nodes contain their own children
+ * (MCP servers and skills they access). Edges are implicit in the
+ * parent-child relationship — no separate edge type is needed.
+ *
+ * Nodes are navigable when `ref` is defined (MCP servers, skills).
+ * Sub-agent nodes have no `ref` because they are inline definitions
+ * within the agent spec, not standalone resources.
+ */
+export interface DependencyNode {
+  /**
+   * Deterministic identifier. Format: `{kind}:{slug}` for referenced
+   * resources, `sub-agent:{name}` for sub-agents, or `agent:{slug}`
+   * for the root.
+   */
+  readonly id: string;
+  /** What kind of resource this node represents. */
+  readonly kind: NodeKind;
+  /** Primary display label (slug for resources, name for sub-agents). */
+  readonly label: string;
+  /**
+   * Qualified label shown when the resource belongs to a different org
+   * than the agent (e.g., `"other-org/shared-server"`). Undefined when
+   * the resource is in the same org as the parent agent.
+   */
+  readonly qualifiedLabel?: string;
+  /** Short description (sub-agent description, if available). */
+  readonly description?: string;
+  /**
+   * Key-value metadata displayed as secondary info.
+   * Examples: `{ tools: "3 tools" }`, `{ model: "gpt-4" }`.
+   */
+  readonly metadata?: Readonly<Record<string, string>>;
+  /** Child nodes. Empty array for leaf nodes (MCP servers, skills). */
+  readonly children: readonly DependencyNode[];
+  /**
+   * Navigation reference for clickable nodes. Defined for MCP servers
+   * and skills (standalone resources). Undefined for sub-agents (inline
+   * definitions) and the root agent.
+   */
+  readonly ref?: { readonly org: string; readonly slug: string };
+}
+
+/**
+ * Complete dependency tree for an agent, rooted at the agent itself.
+ */
+export interface DependencyTree {
+  /** The agent node with all dependencies as descendants. */
+  readonly root: DependencyNode;
+  /** Total number of nodes in the tree (including root). */
+  readonly nodeCount: number;
+}
+
+/** Props for {@link DependencyGraph}. */
+export interface DependencyGraphProps {
+  /** The dependency tree to render. */
+  readonly tree: DependencyTree;
+  /**
+   * Called when a navigable node is clicked. The `node.ref` field
+   * contains the `org` and `slug` for routing. Only fired for nodes
+   * where `ref` is defined (MCP servers, skills).
+   */
+  readonly onNodeClick?: (node: DependencyNode) => void;
+  /**
+   * Whether sub-agent subtrees start expanded.
+   * @default true
+   */
+  readonly defaultExpanded?: boolean;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/** Options for {@link useDependencyGraph}. */
+export interface UseDependencyGraphOptions {
+  /** Display name of the agent (used as the root node label). */
+  readonly agentName: string;
+  /** Organization slug of the agent (used for cross-org label detection). */
+  readonly agentOrg: string;
+  /**
+   * The agent's spec containing dependency references.
+   * Pass `undefined` while the agent is loading — the hook returns
+   * `null` for `tree` and `true` for `isEmpty`.
+   */
+  readonly spec: {
+    readonly mcpServerUsages: readonly {
+      readonly mcpServerRef?: {
+        readonly org: string;
+        readonly slug: string;
+      };
+      readonly enabledTools: readonly string[];
+      readonly toolApprovalOverrides: readonly unknown[];
+    }[];
+    readonly skillRefs: readonly {
+      readonly org: string;
+      readonly slug: string;
+    }[];
+    readonly subAgents: readonly {
+      readonly name: string;
+      readonly description: string;
+      readonly mcpAccess: readonly {
+        readonly mcpServer: string;
+        readonly enabledTools: readonly string[];
+      }[];
+      readonly skillRefs: readonly {
+        readonly org: string;
+        readonly slug: string;
+      }[];
+      readonly modelOverride: string;
+    }[];
+  } | undefined;
+}
+
+/** Return value of {@link useDependencyGraph}. */
+export interface UseDependencyGraphReturn {
+  /** The computed tree, or `null` when spec is undefined. */
+  readonly tree: DependencyTree | null;
+  /** `true` when the agent has zero dependencies (or spec is undefined). */
+  readonly isEmpty: boolean;
+}