@stigmer/react 0.4.7 → 0.5.0

package/src/action-menu/ActionMenu.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import {
+  Menu,
+  MenuTrigger,
+  MenuContent as InternalMenuContent,
+  MenuItem as InternalMenuItem,
+  MenuSeparator as InternalMenuSeparator,
+  MenuGroup as InternalMenuGroup,
+  MenuLabel,
+} from "../internal/menu";
+import type {
+  ActionMenuProps,
+  ActionMenuTriggerProps,
+  ActionMenuContentProps,
+  ActionMenuItemProps,
+  ActionMenuSeparatorProps,
+  ActionMenuGroupProps,
+} from "./types";
+
+/**
+ * Compound menu component for resource item actions.
+ *
+ * Built on top of the SDK's internal Base UI menu primitives with
+ * opinionated conventions for resource management UX:
+ * - Icon + label + optional shortcut hint layout
+ * - Destructive variant for dangerous actions
+ * - Grouped sections with labels
+ * - Keyboard navigation (arrows, Enter, Esc) via Base UI
+ * - Portal rendering with theme inheritance
+ *
+ * @example
+ * ```tsx
+ * <ActionMenu>
+ *   <ActionMenu.Trigger>
+ *     <button aria-label="Agent actions">
+ *       <MoreHorizontal className="h-4 w-4" />
+ *     </button>
+ *   </ActionMenu.Trigger>
+ *   <ActionMenu.Content>
+ *     <ActionMenu.Item icon={<Edit />} onSelect={handleEdit}>
+ *       Edit
+ *     </ActionMenu.Item>
+ *     <ActionMenu.Item icon={<Copy />} onSelect={handleDuplicate}>
+ *       Duplicate
+ *     </ActionMenu.Item>
+ *     <ActionMenu.Separator />
+ *     <ActionMenu.Item
+ *       icon={<Trash2 />}
+ *       variant="destructive"
+ *       onSelect={handleDelete}
+ *     >
+ *       Delete
+ *     </ActionMenu.Item>
+ *   </ActionMenu.Content>
+ * </ActionMenu>
+ * ```
+ */
+function ActionMenuRoot({ children }: ActionMenuProps) {
+  return <Menu>{children}</Menu>;
+}
+
+function Trigger({
+  children,
+  className,
+  "aria-label": ariaLabel = "Actions",
+}: ActionMenuTriggerProps) {
+  return (
+    <MenuTrigger
+      className={cn(
+        "inline-flex items-center justify-center rounded-md p-1",
+        "text-muted-foreground hover:text-foreground hover:bg-accent",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "data-popup-open:bg-accent data-popup-open:text-foreground",
+        className,
+      )}
+      aria-label={ariaLabel}
+    >
+      {children}
+    </MenuTrigger>
+  );
+}
+
+function Content({ children, align = "end", className }: ActionMenuContentProps) {
+  return (
+    <InternalMenuContent align={align} className={cn("min-w-44", className)}>
+      {children}
+    </InternalMenuContent>
+  );
+}
+
+function Item({
+  children,
+  onSelect,
+  icon,
+  shortcut,
+  variant = "default",
+  disabled,
+  className,
+}: ActionMenuItemProps) {
+  return (
+    <InternalMenuItem
+      variant={variant}
+      disabled={disabled}
+      onClick={onSelect}
+      className={cn("justify-between", className)}
+    >
+      <span className="flex items-center gap-2">
+        {icon}
+        <span>{children}</span>
+      </span>
+      {shortcut && (
+        <kbd className="ml-auto text-[11px] tracking-widest text-muted-foreground-subtle">
+          {shortcut}
+        </kbd>
+      )}
+    </InternalMenuItem>
+  );
+}
+
+function Separator({ className }: ActionMenuSeparatorProps) {
+  return <InternalMenuSeparator className={className} />;
+}
+
+function Group({ children, label, className }: ActionMenuGroupProps) {
+  return (
+    <InternalMenuGroup className={className}>
+      {label && <MenuLabel>{label}</MenuLabel>}
+      {children}
+    </InternalMenuGroup>
+  );
+}
+
+/**
+ * Public compound component for resource item action menus.
+ *
+ * Subcomponents:
+ * - `ActionMenu.Trigger` — the element that opens the menu
+ * - `ActionMenu.Content` — the menu panel container
+ * - `ActionMenu.Item` — a single action (with icon, shortcut, destructive variant)
+ * - `ActionMenu.Separator` — a visual divider between items/groups
+ * - `ActionMenu.Group` — a labeled section of items
+ */
+export const ActionMenu = Object.assign(ActionMenuRoot, {
+  Trigger,
+  Content,
+  Item,
+  Separator,
+  Group,
+});

package/src/action-menu/index.ts

@@ -0,0 +1,9 @@
+export { ActionMenu } from "./ActionMenu";
+export type {
+  ActionMenuProps,
+  ActionMenuTriggerProps,
+  ActionMenuContentProps,
+  ActionMenuItemProps,
+  ActionMenuSeparatorProps,
+  ActionMenuGroupProps,
+} from "./types";

package/src/action-menu/types.ts

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+
+/** Props for the {@link ActionMenu} root. */
+export interface ActionMenuProps {
+  /** Menu content (Trigger + Content). */
+  readonly children: ReactNode;
+}
+
+/** Props for the `ActionMenu.Trigger` element. */
+export interface ActionMenuTriggerProps {
+  /** The trigger element (typically an icon button). */
+  readonly children: ReactNode;
+  /** Additional CSS classes for the trigger wrapper. */
+  readonly className?: string;
+  /** Accessible label for the trigger. @default "Actions" */
+  readonly "aria-label"?: string;
+}
+
+/** Props for the `ActionMenu.Content` panel. */
+export interface ActionMenuContentProps {
+  /** Menu items, groups, and separators. */
+  readonly children: ReactNode;
+  /**
+   * Horizontal alignment relative to the trigger.
+   * @default "end"
+   */
+  readonly align?: "start" | "center" | "end";
+  /** Additional CSS classes for the menu popup. */
+  readonly className?: string;
+}
+
+/** Props for the `ActionMenu.Item`. */
+export interface ActionMenuItemProps {
+  /** Item label text. */
+  readonly children: ReactNode;
+  /** Click handler. */
+  readonly onSelect?: () => void;
+  /** Optional icon rendered before the label. */
+  readonly icon?: ReactNode;
+  /** Optional keyboard shortcut hint rendered after the label. */
+  readonly shortcut?: string;
+  /**
+   * Visual variant.
+   * - `"default"` — standard item styling
+   * - `"destructive"` — red/danger styling for delete, remove, revoke actions
+   *
+   * @default "default"
+   */
+  readonly variant?: "default" | "destructive";
+  /** Whether the item is disabled. */
+  readonly disabled?: boolean;
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+/** Props for the `ActionMenu.Separator`. */
+export interface ActionMenuSeparatorProps {
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+/** Props for the `ActionMenu.Group`. */
+export interface ActionMenuGroupProps {
+  /** Group items. */
+  readonly children: ReactNode;
+  /** Optional label shown above the group. */
+  readonly label?: string;
+  /** Additional CSS classes. */
+  readonly className?: string;
+}

package/src/agent/AgentCreationWizard.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import type { WizardStepDef } from "../resource-creation/types";
+import { useWizardState } from "../resource-creation/useWizardState";
+import { WizardShell } from "../resource-creation/WizardShell";
+import { useCreateAgent } from "./useCreateAgent";
+import { IdentityStep } from "./steps/IdentityStep";
+import { CapabilitiesStep } from "./steps/CapabilitiesStep";
+import { ReviewStep, buildAgentInput } from "./steps/ReviewStep";
+import { createInitialWizardData } from "./steps/types";
+import type { AgentWizardData } from "./steps/types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Result passed to `onComplete` after successful agent creation. */
+export interface AgentCreationResult {
+  /** Organization slug of the created agent. */
+  readonly org: string;
+  /** Agent slug (for URL construction). */
+  readonly slug: string;
+  /** Agent display name. */
+  readonly name: string;
+}
+
+/** Props for {@link AgentCreationWizard}. */
+export interface AgentCreationWizardProps {
+  /** Organization to create the agent in. */
+  readonly org: string;
+  /**
+   * Optional partial data to pre-fill the wizard with.
+   *
+   * Merged with defaults via `{ ...createInitialWizardData(), ...initialData }`.
+   * Use this for template-based creation, resource duplication, or any
+   * flow that starts the wizard with pre-populated fields.
+   */
+  readonly initialData?: Partial<AgentWizardData>;
+  /** Called after the agent is successfully created. */
+  readonly onComplete: (result: AgentCreationResult) => void;
+  /** Called when the user cancels the wizard. */
+  readonly onCancel?: () => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Step definitions
+// ---------------------------------------------------------------------------
+
+const STEPS: WizardStepDef<AgentWizardData>[] = [
+  {
+    id: "identity",
+    label: "Identity & Instructions",
+    validate: (data) => {
+      if (!data.name.trim()) return "Name is required";
+      return null;
+    },
+  },
+  {
+    id: "capabilities",
+    label: "Capabilities",
+  },
+  {
+    id: "review",
+    label: "Review & Create",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * Multi-step wizard for creating a new agent blueprint.
+ *
+ * Three condensed steps:
+ * 1. **Identity & Instructions** — name, slug, description, visibility, system prompt
+ * 2. **Capabilities** — MCP servers + tools, skills, env var declarations (all optional)
+ * 3. **Review & Create** — YAML preview + submission
+ *
+ * Uses the shared `WizardShell` layout and `useWizardState` hook for
+ * navigation. Form data accumulates in the wizard state; on the final
+ * step the user reviews and confirms creation.
+ *
+ * This component is an SDK-first, embeddable wizard with zero Console
+ * dependencies. Platform builders can mount it anywhere.
+ *
+ * @example
+ * ```tsx
+ * <AgentCreationWizard
+ *   org="acme"
+ *   onComplete={({ org, slug }) => navigate(`/agents/${org}/${slug}`)}
+ *   onCancel={() => navigate("/agents")}
+ * />
+ * ```
+ */
+export function AgentCreationWizard({
+  org,
+  initialData,
+  onComplete,
+  onCancel,
+  className,
+}: AgentCreationWizardProps) {
+  const mergedInitialData = useMemo(
+    () => ({ ...createInitialWizardData(), ...initialData }),
+    // initialData is consumed once at mount — not reactive by design
+    [initialData],
+  );
+
+  const wizard = useWizardState({
+    steps: STEPS,
+    initialData: mergedInitialData,
+  });
+
+  const { create, isCreating, error, clearError } = useCreateAgent();
+
+  const handleNext = useCallback(() => {
+    if (wizard.isLastStep) {
+      handleSubmit();
+    } else {
+      clearError();
+      wizard.goNext();
+    }
+  }, [wizard.isLastStep, wizard.goNext, clearError]);
+
+  const handleSubmit = useCallback(async () => {
+    clearError();
+    const input = buildAgentInput(org, wizard.data);
+
+    try {
+      const agent = await create(input);
+      onComplete({
+        org: agent.metadata?.org ?? org,
+        slug: agent.metadata?.slug ?? input.slug ?? input.name,
+        name: agent.metadata?.name ?? input.name,
+      });
+    } catch {
+      // Error is captured by useCreateAgent and displayed in ReviewStep
+    }
+  }, [org, wizard.data, create, clearError, onComplete]);
+
+  const currentStepContent = useMemo(() => {
+    switch (wizard.currentStep.id) {
+      case "identity":
+        return (
+          <IdentityStep
+            data={wizard.data}
+            updateData={wizard.updateData}
+            validationError={wizard.validationError}
+          />
+        );
+      case "capabilities":
+        return (
+          <CapabilitiesStep
+            org={org}
+            data={wizard.data}
+            updateData={wizard.updateData}
+          />
+        );
+      case "review":
+        return (
+          <ReviewStep
+            org={org}
+            data={wizard.data}
+            isCreating={isCreating}
+            error={error}
+          />
+        );
+      default:
+        return null;
+    }
+  }, [
+    wizard.currentStep.id,
+    wizard.data,
+    wizard.updateData,
+    wizard.validationError,
+    org,
+    isCreating,
+    error,
+  ]);
+
+  return (
+    <WizardShell
+      steps={STEPS}
+      currentStepIndex={wizard.currentStepIndex}
+      submitLabel="Create agent"
+      isSubmitting={isCreating}
+      canGoNext={wizard.canGoNext}
+      canGoBack={wizard.canGoBack}
+      onNext={handleNext}
+      onBack={wizard.goBack}
+      onGoToStep={wizard.goToStep}
+      onCancel={onCancel}
+      className={className}
+    >
+      {currentStepContent}
+    </WizardShell>
+  );
+}