@stigmer/react 0.4.8 → 0.5.1

package/src/resource-creation/useWizardState.ts

@@ -0,0 +1,223 @@
+"use client";
+
+import { useCallback, useMemo, useReducer } from "react";
+import type { WizardStepDef, WizardState } from "./types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Options for {@link useWizardState}. */
+export interface UseWizardStateOptions<TData> {
+  /** Ordered step definitions — determines wizard length and validation. */
+  readonly steps: readonly WizardStepDef<TData>[];
+  /** Initial form data (empty/default values for all fields). */
+  readonly initialData: TData;
+}
+
+/** Return value of {@link useWizardState}. */
+export interface UseWizardStateReturn<TData> {
+  /** Zero-based index of the current step. */
+  readonly currentStepIndex: number;
+  /** Definition of the current step. */
+  readonly currentStep: WizardStepDef<TData>;
+  /** Accumulated form data across all steps. */
+  readonly data: TData;
+  /** Merges a partial update into the accumulated data. */
+  readonly updateData: (partial: Partial<TData>) => void;
+  /** Whether navigation forward is allowed (current step is valid). */
+  readonly canGoNext: boolean;
+  /** Whether navigation backward is possible (not on first step). */
+  readonly canGoBack: boolean;
+  /** Advance to the next step (validates current step first). */
+  readonly goNext: () => void;
+  /** Return to the previous step. */
+  readonly goBack: () => void;
+  /** Jump directly to a specific step (only allows going backward). */
+  readonly goToStep: (index: number) => void;
+  /** Validation error for the current step, or `null`. */
+  readonly validationError: string | null;
+  /** `true` when on the first step. */
+  readonly isFirstStep: boolean;
+  /** `true` when on the last step. */
+  readonly isLastStep: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+type WizardAction<TData> =
+  | { readonly type: "GO_NEXT" }
+  | { readonly type: "GO_BACK" }
+  | { readonly type: "GO_TO_STEP"; readonly index: number }
+  | { readonly type: "UPDATE_DATA"; readonly partial: Partial<TData> }
+  | { readonly type: "SET_VALIDATION_ERROR"; readonly error: string | null };
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+function createReducer<TData>(steps: readonly WizardStepDef<TData>[]) {
+  return function wizardReducer(
+    state: WizardState<TData>,
+    action: WizardAction<TData>,
+  ): WizardState<TData> {
+    switch (action.type) {
+      case "GO_NEXT": {
+        const step = steps[state.currentStepIndex];
+        const error = step?.validate?.(state.data) ?? null;
+        if (error) {
+          return { ...state, validationError: error };
+        }
+        const nextIndex = Math.min(
+          state.currentStepIndex + 1,
+          steps.length - 1,
+        );
+        return {
+          ...state,
+          currentStepIndex: nextIndex,
+          validationError: null,
+        };
+      }
+
+      case "GO_BACK": {
+        const prevIndex = Math.max(state.currentStepIndex - 1, 0);
+        return {
+          ...state,
+          currentStepIndex: prevIndex,
+          validationError: null,
+        };
+      }
+
+      case "GO_TO_STEP": {
+        if (action.index < 0 || action.index >= steps.length) return state;
+        if (action.index >= state.currentStepIndex) return state;
+        return {
+          ...state,
+          currentStepIndex: action.index,
+          validationError: null,
+        };
+      }
+
+      case "UPDATE_DATA":
+        return {
+          ...state,
+          data: { ...state.data, ...action.partial },
+          validationError: null,
+        };
+
+      case "SET_VALIDATION_ERROR":
+        return { ...state, validationError: action.error };
+
+      default:
+        return state;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Headless state machine for multi-step wizard flows.
+ *
+ * Manages step navigation, per-step validation gating, and accumulated
+ * form data. Generic over the data shape — each wizard defines its own
+ * `TData` type with fields for all steps.
+ *
+ * Navigation forward is gated by the current step's `validate` function.
+ * Navigation backward is always allowed. Direct step jumps only go backward
+ * (prevents skipping required steps).
+ *
+ * Follows the `useReducer` + discriminated union pattern established
+ * by `agentSetupReducer` — pure state transitions, imperative API on top.
+ *
+ * @typeParam TData - Accumulated form data shape.
+ *
+ * @example
+ * ```tsx
+ * const wizard = useWizardState({
+ *   steps: [
+ *     { id: "basics", label: "Basics", validate: (d) => d.name ? null : "Name is required" },
+ *     { id: "review", label: "Review" },
+ *   ],
+ *   initialData: { name: "", description: "" },
+ * });
+ *
+ * // wizard.data.name, wizard.updateData({ name: "My Agent" })
+ * // wizard.goNext(), wizard.goBack()
+ * ```
+ */
+export function useWizardState<TData>(
+  options: UseWizardStateOptions<TData>,
+): UseWizardStateReturn<TData> {
+  const { steps, initialData } = options;
+
+  const reducer = useMemo(() => createReducer(steps), [steps]);
+
+  const [state, dispatch] = useReducer(reducer, {
+    currentStepIndex: 0,
+    data: initialData,
+    validationError: null,
+  });
+
+  const currentStep = steps[state.currentStepIndex]!;
+  const isFirstStep = state.currentStepIndex === 0;
+  const isLastStep = state.currentStepIndex === steps.length - 1;
+
+  const canGoNext = useMemo(() => {
+    const error = currentStep.validate?.(state.data) ?? null;
+    return error === null;
+  }, [currentStep, state.data]);
+
+  const canGoBack = !isFirstStep;
+
+  const goNext = useCallback(() => {
+    dispatch({ type: "GO_NEXT" });
+  }, []);
+
+  const goBack = useCallback(() => {
+    dispatch({ type: "GO_BACK" });
+  }, []);
+
+  const goToStep = useCallback((index: number) => {
+    dispatch({ type: "GO_TO_STEP", index });
+  }, []);
+
+  const updateData = useCallback((partial: Partial<TData>) => {
+    dispatch({ type: "UPDATE_DATA", partial });
+  }, []);
+
+  return useMemo(
+    () => ({
+      currentStepIndex: state.currentStepIndex,
+      currentStep,
+      data: state.data,
+      updateData,
+      canGoNext,
+      canGoBack,
+      goNext,
+      goBack,
+      goToStep,
+      validationError: state.validationError,
+      isFirstStep,
+      isLastStep,
+    }),
+    [
+      state.currentStepIndex,
+      state.data,
+      state.validationError,
+      currentStep,
+      canGoNext,
+      canGoBack,
+      isFirstStep,
+      isLastStep,
+      updateData,
+      goNext,
+      goBack,
+      goToStep,
+    ],
+  );
+}

package/src/resource-detail/ConfirmDialog.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import { cn } from "@stigmer/theme";
+import type { ConfirmState } from "./types";
+
+export interface ConfirmDialogProps {
+  /** Pending confirmation state from {@link useConfirmAction}. */
+  readonly state: ConfirmState | null;
+  /** Accept the pending confirmation. */
+  readonly onConfirm: () => void;
+  /** Dismiss the pending confirmation. */
+  readonly onCancel: () => void;
+}
+
+/**
+ * Accessible confirmation dialog for destructive actions.
+ *
+ * Uses the native `<dialog>` element with `showModal()` for built-in
+ * focus trapping, Escape key handling, and backdrop. Styled via
+ * `--stgm-*` design tokens.
+ *
+ * Pairs with {@link useConfirmAction} which manages the imperative
+ * `confirm()` → Promise pattern.
+ *
+ * @example
+ * ```tsx
+ * const { confirmState, confirm, handleConfirm, handleCancel } = useConfirmAction();
+ *
+ * // Trigger
+ * const handleDelete = async () => {
+ *   const ok = await confirm({
+ *     title: "Delete agent?",
+ *     description: "This cannot be undone.",
+ *     confirmLabel: "Delete",
+ *     variant: "destructive",
+ *   });
+ *   if (ok) await deleteAgent();
+ * };
+ *
+ * // Render
+ * <ConfirmDialog
+ *   state={confirmState}
+ *   onConfirm={handleConfirm}
+ *   onCancel={handleCancel}
+ * />
+ * ```
+ */
+export function ConfirmDialog({
+  state,
+  onConfirm,
+  onCancel,
+}: ConfirmDialogProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (state && !dialog.open) {
+      dialog.showModal();
+    } else if (!state && dialog.open) {
+      dialog.close();
+    }
+  }, [state]);
+
+  const handleDialogCancel = useCallback(
+    (e: React.SyntheticEvent) => {
+      e.preventDefault();
+      onCancel();
+    },
+    [onCancel],
+  );
+
+  if (!state) return null;
+
+  const isDestructive = state.variant === "destructive";
+
+  return (
+    <dialog
+      ref={dialogRef}
+      onCancel={handleDialogCancel}
+      className={cn(
+        "fixed inset-0 z-50 m-auto w-full max-w-sm rounded-lg border border-border bg-popover p-0 text-popover-foreground shadow-lg",
+        "backdrop:bg-black/50",
+        "open:animate-in open:fade-in-0 open:zoom-in-95",
+      )}
+    >
+      <div className="flex flex-col gap-4 p-6">
+        <div className="flex flex-col gap-1.5">
+          <h3 className="text-base font-semibold text-foreground">
+            {state.title}
+          </h3>
+          <p className="text-sm text-muted-foreground">
+            {state.description}
+          </p>
+        </div>
+        <div className="flex justify-end gap-2">
+          <button
+            type="button"
+            onClick={onCancel}
+            className={cn(
+              "rounded-md px-3 py-1.5 text-sm font-medium transition-colors",
+              "border border-input bg-background text-foreground",
+              "hover:bg-accent hover:text-accent-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          >
+            {state.cancelLabel ?? "Cancel"}
+          </button>
+          <button
+            type="button"
+            onClick={onConfirm}
+            className={cn(
+              "rounded-md px-3 py-1.5 text-sm font-medium transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              isDestructive
+                ? "bg-destructive text-destructive-foreground hover:bg-destructive-hover"
+                : "bg-primary text-primary-foreground hover:bg-primary-hover",
+            )}
+          >
+            {state.confirmLabel ?? "Confirm"}
+          </button>
+        </div>
+      </div>
+    </dialog>
+  );
+}

package/src/resource-detail/ResourceActionBar.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import { useMemo } from "react";
+import { cn } from "@stigmer/theme";
+import { ActionMenu } from "../action-menu";
+import type { DetailAction } from "./types";
+
+export interface ResourceActionBarProps {
+  /**
+   * Primary action rendered as a visible button.
+   * Use for the most common action on this resource (e.g. "Edit").
+   */
+  readonly primaryAction?: DetailAction;
+  /**
+   * Secondary and tertiary actions rendered in the overflow (kebab) menu.
+   * Actions with the same `group` are visually grouped with separators.
+   */
+  readonly actions?: readonly DetailAction[];
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Horizontal action bar for resource detail page headers.
+ *
+ * Renders an optional primary action as a visible button and any
+ * remaining actions in a kebab overflow menu (using the SDK's
+ * {@link ActionMenu} compound component).
+ *
+ * When there are no actions at all, renders nothing.
+ *
+ * @example
+ * ```tsx
+ * <ResourceActionBar
+ *   primaryAction={{
+ *     id: "edit",
+ *     label: "Edit",
+ *     icon: <PencilIcon />,
+ *     onAction: () => router.push(editUrl),
+ *   }}
+ *   actions={[
+ *     { id: "copy-id", label: "Copy ID", onAction: () => copyId(id) },
+ *     { id: "delete", label: "Delete", variant: "destructive", onAction: handleDelete },
+ *   ]}
+ * />
+ * ```
+ */
+export function ResourceActionBar({
+  primaryAction,
+  actions,
+  className,
+}: ResourceActionBarProps) {
+  const hasOverflow = actions != null && actions.length > 0;
+  if (!primaryAction && !hasOverflow) return null;
+
+  return (
+    <div className={cn("flex items-center gap-2", className)}>
+      {primaryAction && (
+        <button
+          type="button"
+          onClick={primaryAction.onAction}
+          disabled={primaryAction.disabled}
+          className={cn(
+            "inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm font-medium transition-colors",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "bg-primary text-primary-foreground hover:bg-primary-hover",
+            "disabled:pointer-events-none disabled:opacity-50",
+          )}
+        >
+          {primaryAction.icon}
+          {primaryAction.label}
+        </button>
+      )}
+      {hasOverflow && <OverflowMenu actions={actions} />}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Overflow kebab menu
+// ---------------------------------------------------------------------------
+
+function OverflowMenu({
+  actions,
+}: {
+  readonly actions: readonly DetailAction[];
+}) {
+  const grouped = useGroupedActions(actions);
+
+  return (
+    <ActionMenu>
+      <ActionMenu.Trigger aria-label="More actions">
+        <KebabIcon className="size-4" />
+      </ActionMenu.Trigger>
+      <ActionMenu.Content>
+        {grouped.map((group, groupIndex) => (
+          <ActionMenu.Group key={group.key}>
+            {groupIndex > 0 && <ActionMenu.Separator />}
+            {group.items.map((action) => (
+              <ActionMenu.Item
+                key={action.id}
+                icon={action.icon}
+                shortcut={action.shortcut}
+                variant={action.variant}
+                disabled={action.disabled}
+                onSelect={action.onAction}
+              >
+                {action.label}
+              </ActionMenu.Item>
+            ))}
+          </ActionMenu.Group>
+        ))}
+      </ActionMenu.Content>
+    </ActionMenu>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Action grouping
+// ---------------------------------------------------------------------------
+
+interface ActionGroup {
+  readonly key: string;
+  readonly items: readonly DetailAction[];
+}
+
+function useGroupedActions(actions: readonly DetailAction[]): ActionGroup[] {
+  return useMemo(() => {
+    const map = new Map<string, DetailAction[]>();
+    for (const action of actions) {
+      const key = action.group ?? "__default";
+      const list = map.get(key);
+      if (list) list.push(action);
+      else map.set(key, [action]);
+    }
+    return Array.from(map.entries()).map(([key, items]) => ({ key, items }));
+  }, [actions]);
+}
+
+// ---------------------------------------------------------------------------
+// Kebab icon (inline SVG — no icon library dependency)
+// ---------------------------------------------------------------------------
+
+function KebabIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="3" r="1.25" />
+      <circle cx="8" cy="8" r="1.25" />
+      <circle cx="8" cy="13" r="1.25" />
+    </svg>
+  );
+}

package/src/resource-detail/ResourceDetailShell.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { StatusBadge } from "../resource-workbench/components/StatusBadge";
+import { Tabs } from "../tabs/Tabs";
+import { ResourceActionBar } from "./ResourceActionBar";
+import type { ResourceDetailShellProps } from "./types";
+
+/**
+ * Shared layout shell for resource detail pages.
+ *
+ * Renders a standardized header (icon, name, org, timestamps, status,
+ * visibility control), an action bar (primary button + kebab overflow),
+ * optional tabs, and a content area — all themed via `--stgm-*` tokens.
+ *
+ * The shell receives pre-fetched data via props (DD-T03-001). It does
+ * NOT own data fetching — resource-specific hooks (`useAgent`, `useSkill`,
+ * etc.) handle that. The shell is a layout + behavior coordinator, not
+ * a data-fetching component.
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const { agent } = useAgent(org, slug);
+ *
+ * <ResourceDetailShell
+ *   header={{
+ *     name: agent.metadata.name,
+ *     id: agent.metadata.id,
+ *     org: agent.metadata.org,
+ *     slug: agent.metadata.slug,
+ *     description: agent.spec.description,
+ *   }}
+ *   primaryAction={{ id: "edit", label: "Edit", onAction: handleEdit }}
+ *   actions={[...]}
+ * >
+ *   <AgentOverview agent={agent} />
+ * </ResourceDetailShell>
+ * ```
+ */
+export function ResourceDetailShell({
+  header,
+  visibilityControl,
+  primaryAction,
+  actions,
+  tabs,
+  activeTab,
+  onTabChange,
+  tabsAriaLabel,
+  children,
+  className,
+}: ResourceDetailShellProps) {
+  const hasTabs = tabs != null && tabs.length > 0;
+
+  return (
+    <div className={cn("flex flex-col gap-6", className)}>
+      {/* Header + Action bar row */}
+      <div className="flex items-start justify-between gap-4">
+        <Header
+          header={header}
+          visibilityControl={visibilityControl}
+        />
+        <ResourceActionBar
+          primaryAction={primaryAction}
+          actions={actions}
+          className="shrink-0"
+        />
+      </div>
+
+      {/* Tabs + content or plain content */}
+      {hasTabs && activeTab && onTabChange ? (
+        <Tabs
+          tabs={tabs}
+          activeTab={activeTab}
+          onTabChange={onTabChange}
+          aria-label={tabsAriaLabel}
+        >
+          {children}
+        </Tabs>
+      ) : (
+        children
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Header
+// ---------------------------------------------------------------------------
+
+function Header({
+  header,
+  visibilityControl,
+}: {
+  readonly header: ResourceDetailShellProps["header"];
+  readonly visibilityControl?: ResourceDetailShellProps["visibilityControl"];
+}) {
+  const {
+    name,
+    org,
+    slug,
+    description,
+    iconUrl,
+    icon,
+    createdAt,
+    updatedAt,
+    status,
+    statusLabel,
+  } = header;
+
+  const showSlug = slug && slug !== name;
+
+  return (
+    <div className="flex min-w-0 items-start gap-3">
+      {iconUrl ? (
+        <img
+          src={iconUrl}
+          alt=""
+          className="mt-0.5 size-8 shrink-0 rounded object-cover"
+        />
+      ) : icon ? (
+        <span className="mt-1 shrink-0">{icon}</span>
+      ) : null}
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-2">
+          <h2 className="truncate text-lg font-semibold text-foreground">
+            {name}
+          </h2>
+          {showSlug && (
+            <code className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-xs font-medium text-muted-foreground">
+              {slug}
+            </code>
+          )}
+          {status && (
+            <StatusBadge
+              phase={status}
+              label={statusLabel}
+            />
+          )}
+          {visibilityControl}
+        </div>
+        <div className="mt-0.5 flex flex-wrap items-center gap-x-1.5 text-xs text-muted-foreground">
+          {org && <span>{org}</span>}
+          {createdAt && (
+            <>
+              <Dot />
+              <span>Created {formatDate(createdAt)}</span>
+            </>
+          )}
+          {updatedAt && (
+            <>
+              <Dot />
+              <span>Updated {formatDate(updatedAt)}</span>
+            </>
+          )}
+        </div>
+        {description && (
+          <p className="mt-2 text-sm text-muted-foreground">{description}</p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function Dot() {
+  return (
+    <span className="shrink-0" aria-hidden="true">
+      {"\u00B7"}
+    </span>
+  );
+}
+
+function formatDate(date: Date): string {
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+}