@stigmer/react 0.4.8 → 0.5.1

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;
+}

package/src/dependency-graph/useDependencyGraph.ts

@@ -0,0 +1,158 @@
+"use client";
+
+import { useMemo } from "react";
+import type {
+  DependencyNode,
+  DependencyTree,
+  UseDependencyGraphOptions,
+  UseDependencyGraphReturn,
+} from "./types";
+
+/**
+ * Pure transformation hook that converts an `AgentSpec` into a
+ * {@link DependencyTree} for rendering.
+ *
+ * No data fetching, no side effects — the tree is computed entirely
+ * from the spec fields already available via {@link useAgent}. The
+ * result is memoized and only recomputes when the spec reference
+ * changes.
+ *
+ * Returns `null` for `tree` when `spec` is `undefined` (loading state).
+ *
+ * @example
+ * ```tsx
+ * const { tree, isEmpty } = useDependencyGraph({
+ *   agentName: agent.metadata.name,
+ *   agentOrg: agent.metadata.org,
+ *   spec: agent.spec,
+ * });
+ *
+ * if (!isEmpty && tree) {
+ *   return <DependencyGraph tree={tree} onNodeClick={handleClick} />;
+ * }
+ * ```
+ */
+export function useDependencyGraph({
+  agentName,
+  agentOrg,
+  spec,
+}: UseDependencyGraphOptions): UseDependencyGraphReturn {
+  return useMemo(() => {
+    if (!spec) return { tree: null, isEmpty: true };
+
+    const { mcpServerUsages, skillRefs, subAgents } = spec;
+
+    const hasDeps =
+      mcpServerUsages.length > 0 ||
+      skillRefs.length > 0 ||
+      subAgents.length > 0;
+
+    if (!hasDeps) return { tree: null, isEmpty: true };
+
+    let nodeCount = 1; // root
+
+    const mcpNodes: DependencyNode[] = mcpServerUsages
+      .filter((u) => u.mcpServerRef)
+      .map((usage) => {
+        nodeCount++;
+        const ref = usage.mcpServerRef!;
+        const toolCount = usage.enabledTools.length;
+
+        return {
+          id: `mcp-server:${ref.slug}`,
+          kind: "mcp-server" as const,
+          label: ref.slug,
+          qualifiedLabel:
+            ref.org && ref.org !== agentOrg
+              ? `${ref.org}/${ref.slug}`
+              : undefined,
+          metadata: {
+            tools:
+              toolCount > 0
+                ? `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`
+                : "all tools",
+          },
+          children: [],
+          ref: { org: ref.org || agentOrg, slug: ref.slug },
+        };
+      });
+
+    const skillNodes: DependencyNode[] = skillRefs.map((ref) => {
+      nodeCount++;
+      return {
+        id: `skill:${ref.slug}`,
+        kind: "skill" as const,
+        label: ref.slug,
+        qualifiedLabel:
+          ref.org && ref.org !== agentOrg
+            ? `${ref.org}/${ref.slug}`
+            : undefined,
+        children: [],
+        ref: { org: ref.org || agentOrg, slug: ref.slug },
+      };
+    });
+
+    const subAgentNodes: DependencyNode[] = subAgents.map((sa) => {
+      nodeCount++;
+
+      const saMcpNodes: DependencyNode[] = sa.mcpAccess.map((access) => {
+        nodeCount++;
+        const toolCount = access.enabledTools.length;
+        return {
+          id: `sub-agent:${sa.name}:mcp-server:${access.mcpServer}`,
+          kind: "mcp-server" as const,
+          label: access.mcpServer,
+          metadata: {
+            tools:
+              toolCount > 0
+                ? `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`
+                : "all tools",
+          },
+          children: [],
+          ref: { org: agentOrg, slug: access.mcpServer },
+        };
+      });
+
+      const saSkillNodes: DependencyNode[] = sa.skillRefs.map((ref) => {
+        nodeCount++;
+        return {
+          id: `sub-agent:${sa.name}:skill:${ref.slug}`,
+          kind: "skill" as const,
+          label: ref.slug,
+          qualifiedLabel:
+            ref.org && ref.org !== agentOrg
+              ? `${ref.org}/${ref.slug}`
+              : undefined,
+          children: [],
+          ref: { org: ref.org || agentOrg, slug: ref.slug },
+        };
+      });
+
+      const metadata: Record<string, string> = {};
+      if (sa.modelOverride) {
+        metadata.model = sa.modelOverride;
+      }
+
+      return {
+        id: `sub-agent:${sa.name}`,
+        kind: "sub-agent" as const,
+        label: sa.name,
+        description: sa.description || undefined,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        children: [...saMcpNodes, ...saSkillNodes],
+      };
+    });
+
+    const root: DependencyNode = {
+      id: `agent:${agentName}`,
+      kind: "agent",
+      label: agentName,
+      children: [...mcpNodes, ...skillNodes, ...subAgentNodes],
+    };
+
+    return {
+      tree: { root, nodeCount },
+      isEmpty: false,
+    };
+  }, [agentName, agentOrg, spec]);
+}

package/src/empty-state/EmptyState.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { useEmptyState } from "./useEmptyState";
+import type { EmptyStateProps } from "./types";
+
+/**
+ * A semantic, accessible empty state component supporting four distinct
+ * variants: first-use, zero-results, permission, and error.
+ *
+ * Each variant provides appropriate default icons, copy, and ARIA roles.
+ * All defaults can be overridden via props. The `icon` prop accepts any
+ * ReactNode for full visual customization.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   variant="first-use"
+ *   resourceLabel="agents"
+ *   action={{ label: "Create agent", onClick: handleCreate }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   variant="error"
+ *   errorMessage="Network request failed"
+ *   action={{ label: "Retry", onClick: handleRetry }}
+ * />
+ * ```
+ */
+export function EmptyState({
+  variant,
+  resourceLabel,
+  icon,
+  title,
+  description,
+  errorMessage,
+  action,
+  children,
+  className,
+}: EmptyStateProps) {
+  const resolved = useEmptyState({
+    variant,
+    resourceLabel,
+    title,
+    description,
+    errorMessage,
+  });
+
+  return (
+    <div
+      role={resolved.role}
+      className={cn(
+        "flex flex-col items-center gap-3 py-12 text-center",
+        className,
+      )}
+    >
+      <div className="text-muted-foreground-faint">
+        {icon ?? resolved.defaultIcon}
+      </div>
+      <div className="flex flex-col gap-1">
+        <p className="text-sm font-medium text-muted-foreground">
+          {resolved.title}
+        </p>
+        <p className="max-w-sm text-xs text-muted-foreground-subtle">
+          {resolved.description}
+        </p>
+      </div>
+      {children
+        ? <div className="mt-1">{children}</div>
+        : action && (
+          <button
+            type="button"
+            onClick={action.onClick}
+            className={cn(
+              "mt-1 inline-flex items-center rounded-md px-3 py-1.5 text-xs font-medium",
+              variant === "error"
+                ? "border border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground"
+                : "bg-primary text-primary-foreground hover:bg-primary-hover",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          >
+            {action.label}
+          </button>
+        )}
+    </div>
+  );
+}

package/src/empty-state/index.ts

@@ -0,0 +1,9 @@
+export { EmptyState } from "./EmptyState";
+export { useEmptyState } from "./useEmptyState";
+export type {
+  EmptyStateVariant,
+  EmptyStateAction,
+  EmptyStateProps,
+  UseEmptyStateOptions,
+  UseEmptyStateReturn,
+} from "./types";

package/src/empty-state/types.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+
+/**
+ * Semantic variant for an empty state, each representing a distinct
+ * reason why no content is visible.
+ */
+export type EmptyStateVariant =
+  | "first-use"
+  | "zero-results"
+  | "permission"
+  | "error";
+
+/** Action rendered as a button within the empty state. */
+export interface EmptyStateAction {
+  /** Button label. */
+  readonly label: string;
+  /** Click handler. */
+  readonly onClick: () => void;
+}
+
+/** Options for the {@link useEmptyState} behavior hook. */
+export interface UseEmptyStateOptions {
+  /** The semantic reason no content is shown. */
+  readonly variant: EmptyStateVariant;
+  /**
+   * Human-readable label for the resource type (e.g. "agents", "skills").
+   * Used to generate contextual default copy.
+   */
+  readonly resourceLabel?: string;
+  /** Custom title override. When provided, replaces the generated default. */
+  readonly title?: string;
+  /** Custom description override. When provided, replaces the generated default. */
+  readonly description?: string;
+  /** Error message to display — relevant for the "error" variant. */
+  readonly errorMessage?: string;
+}
+
+/** Return value of the {@link useEmptyState} behavior hook. */
+export interface UseEmptyStateReturn {
+  /** Resolved title text. */
+  readonly title: string;
+  /** Resolved description text. */
+  readonly description: string;
+  /** Suggested default icon for the variant (as a ReactNode). */
+  readonly defaultIcon: ReactNode;
+  /** The ARIA role appropriate for this variant. */
+  readonly role: "status" | "alert";
+}
+
+/** Props for the styled {@link EmptyState} component. */
+export interface EmptyStateProps {
+  /**
+   * The semantic reason no content is shown.
+   * Determines default icon, copy, and ARIA role.
+   */
+  readonly variant: EmptyStateVariant;
+  /**
+   * Human-readable label for the resource type (e.g. "agents", "skills").
+   * Used to generate contextual default copy.
+   */
+  readonly resourceLabel?: string;
+  /** Custom icon to display. Defaults to a variant-appropriate Lucide icon. */
+  readonly icon?: ReactNode;
+  /** Custom title override. */
+  readonly title?: string;
+  /** Custom description override. */
+  readonly description?: string;
+  /** Error message — only used when variant is "error". */
+  readonly errorMessage?: string;
+  /** Primary action button. */
+  readonly action?: EmptyStateAction;
+  /**
+   * Custom action slot content. When provided, renders in the action
+   * area (centered, below the description) instead of the `action` button.
+   * Use this when you need full control over the CTA element — e.g. a
+   * `<Link>` for client-side routing or a button with an icon.
+   */
+  readonly children?: ReactNode;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}

package/src/empty-state/useEmptyState.ts

@@ -0,0 +1,85 @@
+import { useMemo, createElement } from "react";
+import { Package, SearchX, Lock, AlertCircle } from "lucide-react";
+import type { UseEmptyStateOptions, UseEmptyStateReturn } from "./types";
+
+const ICON_CLASSES = "h-10 w-10";
+
+function resolveDefaults(
+  variant: UseEmptyStateOptions["variant"],
+  resourceLabel: string,
+): { title: string; description: string } {
+  switch (variant) {
+    case "first-use":
+      return {
+        title: `No ${resourceLabel} yet`,
+        description: `Create ${resourceLabel === "agents" ? "an agent" : `a ${resourceLabel.replace(/s$/, "")}`} to get started.`,
+      };
+    case "zero-results":
+      return {
+        title: "No results found",
+        description: "Try adjusting your search or filters.",
+      };
+    case "permission":
+      return {
+        title: `No access to ${resourceLabel}`,
+        description:
+          "You don't have permission to view these resources. Contact your organization admin.",
+      };
+    case "error":
+      return {
+        title: "Something went wrong",
+        description: "We couldn't load this content. Please try again.",
+      };
+  }
+}
+
+function resolveIcon(variant: UseEmptyStateOptions["variant"]) {
+  switch (variant) {
+    case "first-use":
+      return createElement(Package, { className: ICON_CLASSES });
+    case "zero-results":
+      return createElement(SearchX, { className: ICON_CLASSES });
+    case "permission":
+      return createElement(Lock, { className: ICON_CLASSES });
+    case "error":
+      return createElement(AlertCircle, { className: ICON_CLASSES });
+  }
+}
+
+function resolveRole(
+  variant: UseEmptyStateOptions["variant"],
+): "status" | "alert" {
+  return variant === "error" ? "alert" : "status";
+}
+
+/**
+ * Behavior hook that resolves empty state copy, icon, and accessibility
+ * attributes based on the semantic variant and optional overrides.
+ *
+ * Use this hook when you want full rendering control but need the
+ * variant-aware logic (default copy, icons, ARIA roles).
+ *
+ * @example
+ * ```tsx
+ * const { title, description, defaultIcon, role } = useEmptyState({
+ *   variant: "first-use",
+ *   resourceLabel: "agents",
+ * });
+ * ```
+ */
+export function useEmptyState(options: UseEmptyStateOptions): UseEmptyStateReturn {
+  const { variant, resourceLabel = "resources", title, description, errorMessage } = options;
+
+  return useMemo(() => {
+    const defaults = resolveDefaults(variant, resourceLabel);
+    return {
+      title: title ?? defaults.title,
+      description:
+        variant === "error" && errorMessage
+          ? errorMessage
+          : (description ?? defaults.description),
+      defaultIcon: resolveIcon(variant),
+      role: resolveRole(variant),
+    };
+  }, [variant, resourceLabel, title, description, errorMessage]);
+}

package/src/environment/usePersonalEnvironment.ts

@@ -184,6 +184,7 @@ export function usePersonalEnvironment(
           data,
         });
 
+        environmentRef.current = created;
         refetch();
         return created;
       } catch (err) {

package/src/feedback/StigmerToaster.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { Toaster } from "sonner";
+import { useColorMode } from "../color-mode";
+import type { StigmerToasterProps } from "./types";
+
+/**
+ * Themed toast container for Stigmer SDK components.
+ *
+ * Uses `data-stgm-color-mode` (via {@link useColorMode}) instead of
+ * `next-themes` so it works identically in the Stigmer Console and in
+ * any third-party host application.
+ *
+ * Mount once near your `<StigmerProvider />`:
+ * ```tsx
+ * <StigmerProvider client={client}>
+ *   <App />
+ *   <StigmerToaster />
+ * </StigmerProvider>
+ * ```
+ */
+export function StigmerToaster(props: StigmerToasterProps) {
+  const colorMode = useColorMode();
+
+  return (
+    <Toaster
+      theme={colorMode}
+      position="top-right"
+      richColors
+      className="toaster group"
+      toastOptions={{
+        classNames: {
+          toast:
+            "group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg",
+          description: "group-[.toast]:text-muted-foreground",
+          actionButton:
+            "group-[.toast]:bg-primary group-[.toast]:text-primary-foreground",
+          cancelButton:
+            "group-[.toast]:bg-muted group-[.toast]:text-muted-foreground",
+        },
+      }}
+      {...props}
+    />
+  );
+}

package/src/feedback/index.ts

@@ -0,0 +1,3 @@
+export { StigmerToaster } from "./StigmerToaster";
+export { toast } from "./toast";
+export type { StigmerToasterProps } from "./types";

package/src/feedback/toast.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-export of Sonner's `toast` function with Stigmer defaults.
+ *
+ * Platform builders use this as their primary feedback mechanism:
+ * ```tsx
+ * import { toast } from "@stigmer/react";
+ *
+ * toast.success("Agent created");
+ * toast.error("Failed to save");
+ * toast("Skill removed", { action: { label: "Undo", onClick: undo } });
+ * ```
+ */
+export { toast } from "sonner";

package/src/feedback/types.ts

@@ -0,0 +1,7 @@
+import type { Toaster } from "sonner";
+
+/** Props for the {@link StigmerToaster} component. */
+export type StigmerToasterProps = Omit<
+  React.ComponentProps<typeof Toaster>,
+  "theme"
+>;