@stigmer/react 0.4.8 → 0.5.0

package/src/resource-detail/Section.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { ReactNode } from "react";
+
+export interface SectionProps {
+  readonly title: string;
+  readonly count?: number;
+  readonly onEdit?: () => void;
+  readonly children: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * Shared section layout for resource detail views.
+ *
+ * Renders a labeled section with an optional count badge and edit affordance
+ * in the header row. The content is wrapped in a bordered card.
+ *
+ * Used uniformly by AgentDetailView, McpServerDetailView, and SkillDetailView.
+ */
+export function Section({
+  title,
+  count,
+  onEdit,
+  children,
+  className,
+}: SectionProps) {
+  return (
+    <section className={className}>
+      <div className="mb-2 flex items-center gap-2">
+        <h3 className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+          {title}
+        </h3>
+        {count != null && count > 0 && (
+          <span className="inline-flex size-5 items-center justify-center rounded-full bg-muted text-[10px] font-semibold text-muted-foreground">
+            {count}
+          </span>
+        )}
+        {onEdit && (
+          <button
+            type="button"
+            onClick={onEdit}
+            aria-label={`Edit ${title.toLowerCase()}`}
+            className={cn(
+              "ml-auto inline-flex size-6 items-center justify-center rounded-md text-muted-foreground",
+              "hover:bg-accent-hover hover:text-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "transition-colors",
+            )}
+          >
+            <PencilIcon className="size-3.5" />
+          </button>
+        )}
+      </div>
+      <div className="overflow-hidden rounded-lg border border-border">
+        {children}
+      </div>
+    </section>
+  );
+}
+
+function PencilIcon({ 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="M11.5 1.5a2.121 2.121 0 0 1 3 3L5 14l-4 1 1-4Z" />
+    </svg>
+  );
+}

package/src/resource-detail/index.ts

@@ -0,0 +1,34 @@
+// Types
+export type {
+  AdditionalTab,
+  DetailAction,
+  ResourceHeaderMeta,
+  ConfirmOptions,
+  ConfirmState,
+  ResourceDetailShellProps,
+} from "./types";
+
+// Hooks
+export { useCopyResource } from "./useCopyResource";
+export type { UseCopyResourceReturn } from "./useCopyResource";
+
+export { useConfirmAction } from "./useConfirmAction";
+export type { UseConfirmActionReturn } from "./useConfirmAction";
+
+export { useDeleteResource } from "./useDeleteResource";
+export type {
+  DeletableResourceKind,
+  UseDeleteResourceReturn,
+} from "./useDeleteResource";
+
+// Components
+export { ResourceActionBar } from "./ResourceActionBar";
+export type { ResourceActionBarProps } from "./ResourceActionBar";
+
+export { ResourceDetailShell } from "./ResourceDetailShell";
+
+export { ConfirmDialog } from "./ConfirmDialog";
+export type { ConfirmDialogProps } from "./ConfirmDialog";
+
+export { Section } from "./Section";
+export type { SectionProps } from "./Section";

package/src/resource-detail/types.ts

@@ -0,0 +1,177 @@
+import type { ReactNode } from "react";
+import type { StatusPhase } from "../resource-workbench/types";
+import type { TabItem } from "../tabs/Tabs";
+
+// ---------------------------------------------------------------------------
+// Additional tab — consumer-provided extension tabs for detail views
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a consumer-provided tab that extends a detail view's built-in
+ * tabs. Used by {@link AgentDetailView} and {@link SkillDetailView} to let
+ * platform builders (or the Console) add custom tabs without forking the
+ * component.
+ *
+ * The SDK component defines its own built-in tabs (e.g., "Overview" for
+ * agents, "Content" for skills). Consumers extend via `additionalTabs` —
+ * providing both the tab metadata and the content to render.
+ *
+ * @example
+ * ```tsx
+ * <AgentDetailView
+ *   org="acme"
+ *   slug="my-agent"
+ *   additionalTabs={[
+ *     { id: "dependencies", label: "Dependencies", content: <DependencyGraph /> },
+ *   ]}
+ * />
+ * ```
+ */
+export interface AdditionalTab extends TabItem {
+  /** Content rendered in the tab panel when this tab is active. */
+  readonly content: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Detail action — a single operation available on the detail page
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes an action that can be performed on the currently viewed
+ * resource. Used by {@link ResourceActionBar} and the kebab overflow menu.
+ *
+ * Unlike the workbench's `ResourceAction<TData>`, this is not generic —
+ * the detail page already knows what resource it is showing.
+ */
+export interface DetailAction {
+  /** Stable action identifier. */
+  readonly id: string;
+  /** Display label (e.g. "Edit", "Copy ID", "Delete"). */
+  readonly label: string;
+  /** Optional icon rendered before the label. */
+  readonly icon?: ReactNode;
+  /** Optional keyboard shortcut hint. */
+  readonly shortcut?: string;
+  /**
+   * Visual variant.
+   * - `"default"` — standard item
+   * - `"destructive"` — danger styling for delete, revoke, etc.
+   * @default "default"
+   */
+  readonly variant?: "default" | "destructive";
+  /** Fires when the action is selected. */
+  readonly onAction: () => void;
+  /** When `true`, the action is shown but non-interactive. */
+  readonly disabled?: boolean;
+  /**
+   * Group identifier for organizing actions in the overflow menu.
+   * Actions with the same group are visually grouped with separators.
+   */
+  readonly group?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Resource header metadata — what the shell renders in the header area
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata rendered in the {@link ResourceDetailShell} header.
+ *
+ * This is the shared shape for all resource types — agent, skill,
+ * MCP server, runner. Each detail page maps its resource-specific
+ * protobuf to this shape before passing it to the shell.
+ */
+export interface ResourceHeaderMeta {
+  /** Display name of the resource. */
+  readonly name: string;
+  /** Resource ID (opaque string). */
+  readonly id: string;
+  /** Organization slug that owns the resource. */
+  readonly org?: string;
+  /** URL-friendly slug. */
+  readonly slug?: string;
+  /** Resource description. */
+  readonly description?: string;
+  /** Optional icon URL (e.g. agent icon). */
+  readonly iconUrl?: string;
+  /** Optional custom icon element to render instead of `iconUrl`. */
+  readonly icon?: ReactNode;
+  /** Resource creation timestamp. */
+  readonly createdAt?: Date | null;
+  /** Last update timestamp. */
+  readonly updatedAt?: Date | null;
+  /** Resource status phase for the status badge. */
+  readonly status?: StatusPhase;
+  /** Custom status label (overrides the default phase label). */
+  readonly statusLabel?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Confirm action state — managed by useConfirmAction
+// ---------------------------------------------------------------------------
+
+/** Options passed to `confirm()` to show a confirmation prompt. */
+export interface ConfirmOptions {
+  /** Dialog title (e.g. "Delete agent?"). */
+  readonly title: string;
+  /** Descriptive body text explaining the consequences. */
+  readonly description: string;
+  /** Label for the confirm button. @default "Confirm" */
+  readonly confirmLabel?: string;
+  /** Label for the cancel button. @default "Cancel" */
+  readonly cancelLabel?: string;
+  /** Visual variant for the confirm button. @default "destructive" */
+  readonly variant?: "default" | "destructive";
+}
+
+/** Internal state of a pending confirmation. */
+export interface ConfirmState extends ConfirmOptions {
+  /** Resolves the promise returned by `confirm()`. */
+  readonly resolve: (confirmed: boolean) => void;
+}
+
+// ---------------------------------------------------------------------------
+// ResourceDetailShell props
+// ---------------------------------------------------------------------------
+
+export interface ResourceDetailShellProps {
+  /** Header metadata extracted from the resource. */
+  readonly header: ResourceHeaderMeta;
+
+  /**
+   * Visibility control rendered in the header.
+   * Typically a `<VisibilityToggle />` from the library module.
+   * Rendered inline after the resource name.
+   */
+  readonly visibilityControl?: ReactNode;
+
+  /**
+   * Primary action rendered as a visible button in the header area.
+   * Use for the most common action (e.g. "Edit" for agents).
+   */
+  readonly primaryAction?: DetailAction;
+
+  /**
+   * Secondary actions rendered in the kebab overflow menu.
+   * Grouped by the `group` field — groups are separated visually.
+   */
+  readonly actions?: readonly DetailAction[];
+
+  /**
+   * Optional tabs to render below the header.
+   * When omitted, children are rendered directly without a tab strip.
+   */
+  readonly tabs?: readonly TabItem[];
+  /** Active tab ID (required when `tabs` is provided). */
+  readonly activeTab?: string;
+  /** Tab change handler (required when `tabs` is provided). */
+  readonly onTabChange?: (tabId: string) => void;
+  /** Accessible label for the tab strip. */
+  readonly tabsAriaLabel?: string;
+
+  /** Content area — tab panel content or direct children. */
+  readonly children: ReactNode;
+
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}

package/src/resource-detail/useConfirmAction.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { ConfirmOptions, ConfirmState } from "./types";
+
+export interface UseConfirmActionReturn {
+  /**
+   * The pending confirmation state, or `null` when no confirmation
+   * is active. Pass this to a `ConfirmDialog` component to render
+   * the dialog UI.
+   */
+  readonly confirmState: ConfirmState | null;
+
+  /**
+   * Trigger a confirmation prompt. Returns a promise that resolves
+   * to `true` when confirmed, `false` when cancelled.
+   *
+   * @example
+   * ```tsx
+   * const confirmed = await confirm({
+   *   title: "Delete agent?",
+   *   description: "This action cannot be undone.",
+   *   confirmLabel: "Delete",
+   *   variant: "destructive",
+   * });
+   * if (confirmed) await deleteAgent();
+   * ```
+   */
+  readonly confirm: (options: ConfirmOptions) => Promise<boolean>;
+
+  /** Accept the pending confirmation. */
+  readonly handleConfirm: () => void;
+  /** Dismiss the pending confirmation. */
+  readonly handleCancel: () => void;
+}
+
+/**
+ * State management hook for confirmation dialogs.
+ *
+ * Provides an imperative `confirm()` function that returns a promise,
+ * paired with `confirmState` for rendering a `ConfirmDialog`.
+ *
+ * Separates the state logic (this hook) from the visual presentation
+ * (ConfirmDialog component) following the headless-first architecture
+ * (DD-003).
+ */
+export function useConfirmAction(): UseConfirmActionReturn {
+  const [confirmState, setConfirmState] = useState<ConfirmState | null>(null);
+
+  const confirm = useCallback((options: ConfirmOptions): Promise<boolean> => {
+    return new Promise<boolean>((resolve) => {
+      setConfirmState({ ...options, resolve });
+    });
+  }, []);
+
+  const handleConfirm = useCallback(() => {
+    confirmState?.resolve(true);
+    setConfirmState(null);
+  }, [confirmState]);
+
+  const handleCancel = useCallback(() => {
+    confirmState?.resolve(false);
+    setConfirmState(null);
+  }, [confirmState]);
+
+  return useMemo(
+    () => ({ confirmState, confirm, handleConfirm, handleCancel }),
+    [confirmState, confirm, handleConfirm, handleCancel],
+  );
+}

package/src/resource-detail/useCopyResource.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { toast } from "../feedback/toast";
+
+export interface UseCopyResourceReturn {
+  /** Copy arbitrary text to the clipboard with toast feedback. */
+  readonly copy: (text: string, label: string) => Promise<void>;
+  /** Shortcut: copies `id` and toasts "ID copied". */
+  readonly copyId: (id: string) => Promise<void>;
+  /** Shortcut: copies `slug` and toasts "Slug copied". */
+  readonly copySlug: (slug: string) => Promise<void>;
+  /** Shortcut: copies the qualified slug (`org/slug`) and toasts. */
+  readonly copyQualifiedSlug: (org: string, slug: string) => Promise<void>;
+}
+
+/**
+ * Clipboard helper for resource detail pages.
+ *
+ * Wraps `navigator.clipboard.writeText` with toast feedback so every
+ * copy action is confirmed visually (Nielsen heuristic #1 — visibility
+ * of system status). Falls back to a hidden textarea for older browsers.
+ *
+ * @example
+ * ```tsx
+ * const { copyId, copySlug, copy } = useCopyResource();
+ *
+ * <ActionMenu.Item onSelect={() => copyId(resource.id)}>
+ *   Copy ID
+ * </ActionMenu.Item>
+ * ```
+ */
+export function useCopyResource(): UseCopyResourceReturn {
+  const copy = useCallback(async (text: string, label: string) => {
+    try {
+      await navigator.clipboard.writeText(text);
+      toast.success(`${label} copied`);
+    } catch {
+      fallbackCopy(text);
+      toast.success(`${label} copied`);
+    }
+  }, []);
+
+  const copyId = useCallback(
+    (id: string) => copy(id, "ID"),
+    [copy],
+  );
+
+  const copySlug = useCallback(
+    (slug: string) => copy(slug, "Slug"),
+    [copy],
+  );
+
+  const copyQualifiedSlug = useCallback(
+    (org: string, slug: string) => copy(`${org}/${slug}`, "Qualified slug"),
+    [copy],
+  );
+
+  return useMemo(
+    () => ({ copy, copyId, copySlug, copyQualifiedSlug }),
+    [copy, copyId, copySlug, copyQualifiedSlug],
+  );
+}
+
+function fallbackCopy(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}

package/src/resource-detail/useDeleteResource.ts

@@ -0,0 +1,110 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { toast } from "../feedback/toast";
+
+/** Resource types that support deletion from detail pages. */
+export type DeletableResourceKind = "agent" | "skill" | "mcpServer" | "runner";
+
+export interface UseDeleteResourceReturn {
+  /**
+   * Delete the resource. Resolves on success, rejects on failure.
+   * Shows a success toast on completion and an error toast on failure.
+   */
+  readonly deleteResource: () => Promise<void>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Mutation hook for deleting a resource from its detail page.
+ *
+ * Wraps the type-specific delete RPC with loading state, toast
+ * feedback, and error handling. The `resourceId` may be `null`
+ * when the resource hasn't loaded yet — `deleteResource` becomes
+ * a no-op in that case.
+ *
+ * @example
+ * ```tsx
+ * const { deleteResource, isDeleting } = useDeleteResource(
+ *   "agent",
+ *   resourceId,
+ *   "PR Review Agent",
+ * );
+ *
+ * const handleDelete = async () => {
+ *   const confirmed = await confirm({ ... });
+ *   if (confirmed) {
+ *     await deleteResource();
+ *     router.push("/library/agents");
+ *   }
+ * };
+ * ```
+ */
+export function useDeleteResource(
+  kind: DeletableResourceKind,
+  resourceId: string | null,
+  resourceName?: string,
+): UseDeleteResourceReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const deleteResource = useCallback(async () => {
+    if (!resourceId) return;
+
+    setIsDeleting(true);
+    setError(null);
+
+    try {
+      switch (kind) {
+        case "agent":
+          await stigmer.agent.delete(resourceId);
+          break;
+        case "skill":
+          await stigmer.skill.delete(resourceId);
+          break;
+        case "mcpServer":
+          await stigmer.mcpServer.delete({ resourceId });
+          break;
+        case "runner":
+          await stigmer.runner.delete(resourceId);
+          break;
+      }
+      toast.success(
+        resourceName
+          ? `${resourceName} deleted`
+          : `${kindLabel(kind)} deleted`,
+      );
+    } catch (err) {
+      const wrapped = toError(err);
+      setError(wrapped);
+      toast.error(`Failed to delete ${kindLabel(kind)}`);
+      throw wrapped;
+    } finally {
+      setIsDeleting(false);
+    }
+  }, [stigmer, kind, resourceId, resourceName]);
+
+  return useMemo(
+    () => ({ deleteResource, isDeleting, error }),
+    [deleteResource, isDeleting, error],
+  );
+}
+
+function kindLabel(kind: DeletableResourceKind): string {
+  switch (kind) {
+    case "agent":
+      return "agent";
+    case "skill":
+      return "skill";
+    case "mcpServer":
+      return "MCP server";
+    case "runner":
+      return "runner";
+  }
+}

package/src/resource-detail/useDetailTabs.ts

@@ -0,0 +1,93 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { TabItem } from "../tabs/Tabs";
+import type { AdditionalTab } from "./types";
+
+/**
+ * Return type for the internal detail tabs hook.
+ *
+ * When `effectiveTabs` is `undefined`, the consumer should NOT render
+ * a tab bar (single-tab suppression per DD-T05A-002).
+ */
+export interface UseDetailTabsReturn {
+  /** Tab items to pass to ResourceDetailShell. `undefined` = suppress tab bar. */
+  readonly effectiveTabs: readonly TabItem[] | undefined;
+  /** The currently active tab ID. */
+  readonly effectiveActiveTab: string;
+  /** Handler to pass to ResourceDetailShell's `onTabChange`. */
+  readonly effectiveOnTabChange: (tabId: string) => void;
+  /** The additional tab whose content should be rendered, or `undefined` if a built-in tab is active. */
+  readonly activeAdditionalTab: AdditionalTab | undefined;
+}
+
+interface UseDetailTabsOptions {
+  /** Built-in tabs defined by the SDK component (e.g., [{ id: "overview", label: "Overview" }]). */
+  readonly builtInTabs: readonly TabItem[];
+  /** Consumer-provided extension tabs. */
+  readonly additionalTabs?: readonly AdditionalTab[];
+  /** Controlled active tab (enables controlled mode when paired with `onTabChange`). */
+  readonly activeTab?: string;
+  /** Controlled tab change handler (enables controlled mode when paired with `activeTab`). */
+  readonly onTabChange?: (tabId: string) => void;
+  /** Default tab to show when in uncontrolled mode. Defaults to the first built-in tab's ID. */
+  readonly defaultTab?: string;
+}
+
+/**
+ * Internal hook that manages tab state for detail view components.
+ *
+ * Implements the uncontrolled-by-default / controlled-when-specified
+ * pattern (DD-T05A-001):
+ * - When both `activeTab` and `onTabChange` are provided, the component
+ *   operates in controlled mode (consumer owns the state).
+ * - Otherwise, the component manages its own internal tab state.
+ *
+ * Single-tab suppression (DD-T05A-002):
+ * - When only one tab exists (no additionalTabs), `effectiveTabs` is
+ *   `undefined` so the consumer skips rendering the tab bar entirely.
+ */
+export function useDetailTabs({
+  builtInTabs,
+  additionalTabs,
+  activeTab,
+  onTabChange,
+  defaultTab,
+}: UseDetailTabsOptions): UseDetailTabsReturn {
+  const isControlled = activeTab !== undefined && onTabChange !== undefined;
+
+  const allTabs = useMemo<readonly TabItem[]>(() => {
+    if (!additionalTabs || additionalTabs.length === 0) return builtInTabs;
+    return [...builtInTabs, ...additionalTabs];
+  }, [builtInTabs, additionalTabs]);
+
+  const initialTab = defaultTab ?? builtInTabs[0]?.id ?? "";
+  const [internalTab, setInternalTab] = useState(initialTab);
+
+  const effectiveActiveTab = isControlled ? activeTab : internalTab;
+
+  const effectiveOnTabChange = useCallback(
+    (tabId: string) => {
+      if (isControlled) {
+        onTabChange(tabId);
+      } else {
+        setInternalTab(tabId);
+      }
+    },
+    [isControlled, onTabChange],
+  );
+
+  const effectiveTabs = allTabs.length > 1 ? allTabs : undefined;
+
+  const activeAdditionalTab = useMemo(() => {
+    if (!additionalTabs) return undefined;
+    return additionalTabs.find((t) => t.id === effectiveActiveTab);
+  }, [additionalTabs, effectiveActiveTab]);
+
+  return {
+    effectiveTabs,
+    effectiveActiveTab,
+    effectiveOnTabChange,
+    activeAdditionalTab,
+  };
+}