@stigmer/react 0.0.36 → 0.0.40

package/src/attachment/useAttachments.ts

@@ -0,0 +1,293 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { UploadAttachmentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { AttachmentInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import {
+  detectContentType,
+  formatFileSize,
+  validateAttachmentSize,
+} from "./attachment-utils";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle phase of a single attachment managed by {@link useAttachments}.
+ *
+ * - `uploading` — bytes are being sent to the server
+ * - `ready` — upload succeeded, `storageKey` is available
+ * - `error` — upload failed, `error` describes the failure
+ */
+export type AttachmentPhase = "uploading" | "ready" | "error";
+
+/**
+ * State for a single file being managed by the hook.
+ *
+ * The `id` is a stable string generated at add-time, used as a React
+ * key and for removal. The same `File` added twice produces two
+ * independent entries with distinct IDs.
+ */
+export interface AttachmentEntry {
+  readonly id: string;
+  readonly file: File;
+  readonly phase: AttachmentPhase;
+  readonly contentType: string;
+  /** Set when `phase` is `"ready"`. */
+  readonly storageKey: string | null;
+  /** Set when `phase` is `"error"`. */
+  readonly error: string | null;
+}
+
+export interface UseAttachmentsOptions {
+  /**
+   * Called when a file is rejected during `addFiles` (e.g., exceeds
+   * the size limit). Consumers can use this for toast notifications.
+   */
+  readonly onValidationError?: (message: string) => void;
+}
+
+export interface UseAttachmentsReturn {
+  /** Current attachment entries (uploading, ready, or errored). */
+  readonly entries: readonly AttachmentEntry[];
+  /** True when at least one entry is in the `"uploading"` phase. */
+  readonly isUploading: boolean;
+  /** Number of entries that are ready for submission. */
+  readonly readyCount: number;
+  /** True when there are entries and all are ready (none uploading or errored). */
+  readonly allReady: boolean;
+  /** True when there is at least one entry (in any phase). */
+  readonly hasEntries: boolean;
+  /**
+   * Add one or more files. Each file is validated and uploaded
+   * immediately. Invalid files (e.g., too large) are rejected via
+   * `onValidationError` and not added.
+   */
+  readonly addFiles: (files: FileList | File[]) => void;
+  /** Remove an entry by its stable ID. Aborts in-flight uploads. */
+  readonly removeEntry: (id: string) => void;
+  /** Retry a failed upload. */
+  readonly retryEntry: (id: string) => void;
+  /** Clear all entries and abort any in-flight uploads. */
+  readonly clear: () => void;
+  /**
+   * Produces the `AttachmentInput[]` suitable for execution creation.
+   * Only includes entries in the `"ready"` phase.
+   */
+  readonly toAttachmentInputs: () => AttachmentInput[];
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+let nextId = 0;
+function generateId(): string {
+  return `attachment-${++nextId}-${Date.now()}`;
+}
+
+/**
+ * Behavior hook that manages file attachments for agent executions.
+ *
+ * Handles the full lifecycle: file validation, upload via
+ * `stigmer.agentExecution.uploadAttachment()`, progress tracking,
+ * error handling, and retry. Produces `AttachmentInput[]` ready
+ * for execution creation.
+ *
+ * Files are uploaded immediately on selection so the `storageKey`
+ * is available by the time the user submits their message.
+ *
+ * Platform builders who want custom attachment UI import this hook
+ * directly. The {@link SessionComposer} styled component uses it
+ * internally.
+ *
+ * @example
+ * ```tsx
+ * function CustomComposer() {
+ *   const attachments = useAttachments({
+ *     onValidationError: (msg) => toast.error(msg),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="file"
+ *         multiple
+ *         onChange={(e) => {
+ *           if (e.target.files) attachments.addFiles(e.target.files);
+ *         }}
+ *       />
+ *       {attachments.entries.map((entry) => (
+ *         <div key={entry.id}>
+ *           {entry.file.name} — {entry.phase}
+ *           {entry.phase === "error" && (
+ *             <button onClick={() => attachments.retryEntry(entry.id)}>
+ *               Retry
+ *             </button>
+ *           )}
+ *           <button onClick={() => attachments.removeEntry(entry.id)}>
+ *             Remove
+ *           </button>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAttachments(
+  options?: UseAttachmentsOptions,
+): UseAttachmentsReturn {
+  const stigmer = useStigmer();
+  const [entries, setEntries] = useState<AttachmentEntry[]>([]);
+  const abortControllers = useRef<Map<string, AbortController>>(new Map());
+
+  const uploadFile = useCallback(
+    async (id: string, file: File, contentType: string) => {
+      const controller = new AbortController();
+      abortControllers.current.set(id, controller);
+
+      try {
+        const bytes = new Uint8Array(await file.arrayBuffer());
+
+        if (controller.signal.aborted) return;
+
+        const response = await stigmer.agentExecution.uploadAttachment(
+          create(UploadAttachmentRequestSchema, {
+            filename: file.name,
+            content: bytes,
+            contentType,
+          }),
+        );
+
+        if (controller.signal.aborted) return;
+
+        setEntries((prev) =>
+          prev.map((e) =>
+            e.id === id
+              ? { ...e, phase: "ready" as const, storageKey: response.storageKey, error: null }
+              : e,
+          ),
+        );
+      } catch (err) {
+        if (controller.signal.aborted) return;
+
+        const message = toError(err).message;
+        setEntries((prev) =>
+          prev.map((e) =>
+            e.id === id
+              ? { ...e, phase: "error" as const, error: message }
+              : e,
+          ),
+        );
+      } finally {
+        abortControllers.current.delete(id);
+      }
+    },
+    [stigmer],
+  );
+
+  const addFiles = useCallback(
+    (files: FileList | File[]) => {
+      const fileArray = Array.from(files);
+      const validEntries: AttachmentEntry[] = [];
+
+      for (const file of fileArray) {
+        const sizeError = validateAttachmentSize(file);
+        if (sizeError) {
+          options?.onValidationError?.(sizeError);
+          continue;
+        }
+
+        const id = generateId();
+        const contentType = detectContentType(file);
+
+        validEntries.push({
+          id,
+          file,
+          phase: "uploading",
+          contentType,
+          storageKey: null,
+          error: null,
+        });
+
+        uploadFile(id, file, contentType);
+      }
+
+      if (validEntries.length > 0) {
+        setEntries((prev) => [...prev, ...validEntries]);
+      }
+    },
+    [options, uploadFile],
+  );
+
+  const removeEntry = useCallback((id: string) => {
+    const controller = abortControllers.current.get(id);
+    if (controller) {
+      controller.abort();
+      abortControllers.current.delete(id);
+    }
+    setEntries((prev) => prev.filter((e) => e.id !== id));
+  }, []);
+
+  const retryEntry = useCallback(
+    (id: string) => {
+      setEntries((prev) => {
+        const entry = prev.find((e) => e.id === id);
+        if (!entry || entry.phase !== "error") return prev;
+
+        uploadFile(id, entry.file, entry.contentType);
+
+        return prev.map((e) =>
+          e.id === id
+            ? { ...e, phase: "uploading" as const, error: null }
+            : e,
+        );
+      });
+    },
+    [uploadFile],
+  );
+
+  const clear = useCallback(() => {
+    for (const controller of abortControllers.current.values()) {
+      controller.abort();
+    }
+    abortControllers.current.clear();
+    setEntries([]);
+  }, []);
+
+  const toAttachmentInputs = useCallback((): AttachmentInput[] => {
+    return entries
+      .filter(
+        (e): e is AttachmentEntry & { storageKey: string } =>
+          e.phase === "ready" && e.storageKey !== null,
+      )
+      .map((e) => ({
+        filename: e.file.name,
+        storageKey: e.storageKey,
+        contentType: e.contentType,
+      }));
+  }, [entries]);
+
+  const isUploading = entries.some((e) => e.phase === "uploading");
+  const readyCount = entries.filter((e) => e.phase === "ready").length;
+  const hasEntries = entries.length > 0;
+  const allReady = hasEntries && readyCount === entries.length;
+
+  return {
+    entries,
+    isUploading,
+    readyCount,
+    allReady,
+    hasEntries,
+    addFiles,
+    removeEntry,
+    retryEntry,
+    clear,
+    toAttachmentInputs,
+  };
+}

package/src/composer/ComposerToolbar.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { ContextPopover } from "./ContextPopover";
+import { ConfigureMenu, type ConfigureMenuItem } from "./ConfigureMenu";
+import { ModelSelector } from "../models/ModelSelector";
+import {
+  PaperclipIcon,
+  WorkspaceIcon,
+  ArrowUpIcon,
+  SpinnerIcon,
+} from "./icons";
+
+export interface ComposerToolbarProps {
+  readonly disabled: boolean;
+  readonly isSubmitting: boolean;
+  readonly canSend: boolean;
+  readonly onSend: () => void;
+
+  // -- Tier 1: Attach -------------------------------------------------------
+
+  readonly showAttach: boolean;
+  readonly attachmentCount: number;
+  readonly onAttachClick: () => void;
+
+  // -- Tier 1: Workspace ----------------------------------------------------
+
+  readonly showWorkspace: boolean;
+  readonly workspaceCount: number;
+  /** Pre-built workspace editor content for the popover. */
+  readonly workspaceContent: React.ReactNode;
+
+  // -- Tier 2: Configure menu -----------------------------------------------
+
+  readonly configureItems: readonly ConfigureMenuItem[];
+  readonly configOpen: boolean;
+  readonly onConfigOpenChange: (open: boolean) => void;
+  readonly configActivePanel: string | null;
+  readonly onConfigActivePanelChange: (panel: string | null) => void;
+  /** Render the picker content for a given configure panel id. */
+  readonly renderConfigPanel: (itemId: string) => React.ReactNode;
+
+  // -- Model selector -------------------------------------------------------
+
+  readonly showModelSelector: boolean;
+  readonly modelId?: string;
+  readonly onModelChange: (id: string) => void;
+}
+
+/**
+ * Composer toolbar — Zone 3 of the SessionComposer.
+ *
+ * Renders a two-tier toolbar following the frequency-of-interaction principle:
+ *
+ * **Tier 1 (always visible):** Attach, Workspace
+ * **Tier 2 (behind Configure menu):** Agent, MCP, Skills, Secrets
+ * **Right edge:** Model Selector, Send
+ *
+ * Separators are placed between conceptual groups using Gestalt proximity.
+ */
+export function ComposerToolbar({
+  disabled,
+  isSubmitting,
+  canSend,
+  onSend,
+  showAttach,
+  attachmentCount,
+  onAttachClick,
+  showWorkspace,
+  workspaceCount,
+  workspaceContent,
+  configureItems,
+  configOpen,
+  onConfigOpenChange,
+  configActivePanel,
+  onConfigActivePanelChange,
+  renderConfigPanel,
+  showModelSelector,
+  modelId,
+  onModelChange,
+}: ComposerToolbarProps) {
+  const hasTier1 = showAttach || showWorkspace;
+  const hasTier2 = configureItems.length > 0;
+
+  return (
+    <div className="flex items-center justify-between gap-2 border-t border-border/50 px-3 py-2">
+      <div className="flex items-center gap-1.5">
+        {/* ---- Tier 1: Input augmentation ---- */}
+
+        {showAttach && (
+          <button
+            type="button"
+            disabled={disabled}
+            onClick={onAttachClick}
+            className={cn(
+              "inline-flex items-center gap-1 rounded-md px-2 py-1.5 text-xs transition-colors",
+              "text-muted-foreground hover:text-foreground hover:bg-accent/50",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+            aria-label="Attach files"
+          >
+            <PaperclipIcon />
+            <span>Attach</span>
+            {attachmentCount > 0 && (
+              <span className="rounded-full bg-primary/15 px-1.5 text-[0.6rem] font-medium text-primary">
+                {attachmentCount}
+              </span>
+            )}
+          </button>
+        )}
+
+        {showWorkspace && (
+          <ContextPopover
+            icon={<WorkspaceIcon />}
+            label="Workspace"
+            count={workspaceCount}
+            disabled={disabled}
+          >
+            {workspaceContent}
+          </ContextPopover>
+        )}
+
+        {/* ---- Separator between Tier 1 and Tier 2 ---- */}
+
+        {hasTier1 && hasTier2 && (
+          <div className="mx-0.5 h-4 w-px bg-border/50" aria-hidden="true" />
+        )}
+
+        {/* ---- Tier 2: Agent configuration (behind Configure menu) ---- */}
+
+        <ConfigureMenu
+          open={configOpen}
+          onOpenChange={onConfigOpenChange}
+          activePanel={configActivePanel}
+          onActivePanelChange={onConfigActivePanelChange}
+          items={configureItems}
+          renderPanel={renderConfigPanel}
+          disabled={disabled}
+        />
+
+        {/* ---- Separator before model selector ---- */}
+
+        {(hasTier1 || hasTier2) && showModelSelector && (
+          <div className="mx-0.5 h-4 w-px bg-border/50" aria-hidden="true" />
+        )}
+
+        {showModelSelector && (
+          <ModelSelector
+            value={modelId}
+            onValueChange={onModelChange}
+            disabled={disabled}
+          />
+        )}
+      </div>
+
+      {/* ---- Send button ---- */}
+
+      <button
+        type="button"
+        disabled={!canSend}
+        onClick={onSend}
+        className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground transition-colors hover:bg-primary/90 disabled:pointer-events-none disabled:opacity-40"
+        aria-label="Send message"
+      >
+        {isSubmitting ? <SpinnerIcon /> : <ArrowUpIcon />}
+      </button>
+    </div>
+  );
+}

package/src/composer/ConfigureMenu.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { Popover } from "@base-ui/react/popover";
+import { ConfigureIcon } from "./icons";
+
+export interface ConfigureMenuItem {
+  readonly id: string;
+  readonly icon: React.ReactNode;
+  readonly label: string;
+  readonly count: number;
+  /** Show a warning indicator (e.g., MCP server needs setup). */
+  readonly hasWarning?: boolean;
+}
+
+export interface ConfigureMenuProps {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  /**
+   * Which panel is currently drilled into.
+   * `null` shows the menu list; a string shows that panel's content.
+   */
+  readonly activePanel: string | null;
+  readonly onActivePanelChange: (panel: string | null) => void;
+  readonly items: readonly ConfigureMenuItem[];
+  /**
+   * Render the content for a given panel id.
+   * Called only when `activePanel` matches an item id.
+   */
+  readonly renderPanel: (itemId: string) => React.ReactNode;
+  readonly disabled?: boolean;
+}
+
+/**
+ * Tier 2 configuration affordance for the composer toolbar.
+ *
+ * Renders a trigger button with an optional badge and warning indicator.
+ * Opens a popover that either shows a menu list (when no panel is active)
+ * or drills into the selected item's picker (when a panel is active).
+ *
+ * Uses a single popover with content switching rather than nested popovers,
+ * avoiding z-index and focus-trap issues.
+ */
+export function ConfigureMenu({
+  open,
+  onOpenChange,
+  activePanel,
+  onActivePanelChange,
+  items,
+  renderPanel,
+  disabled,
+}: ConfigureMenuProps) {
+  const totalCount = items.reduce((sum, item) => sum + item.count, 0);
+  const hasWarning = items.some((item) => item.hasWarning);
+
+  const handleOpenChange = (nextOpen: boolean) => {
+    onOpenChange(nextOpen);
+    if (!nextOpen) {
+      onActivePanelChange(null);
+    }
+  };
+
+  if (items.length === 0) return null;
+
+  const activePanelItem = activePanel
+    ? items.find((i) => i.id === activePanel)
+    : null;
+
+  return (
+    <Popover.Root open={open} onOpenChange={handleOpenChange}>
+      <Popover.Trigger
+        disabled={disabled}
+        className={cn(
+          "inline-flex items-center gap-1 rounded-md px-2 py-1.5 text-xs transition-colors",
+          "text-muted-foreground hover:text-foreground hover:bg-accent/50",
+          "disabled:pointer-events-none disabled:opacity-50",
+        )}
+        aria-label="Configure agent, tools, and skills"
+      >
+        <ConfigureIcon />
+        <span>Configure</span>
+        {totalCount > 0 && (
+          <span className="rounded-full bg-primary/15 px-1.5 text-[0.6rem] font-medium text-primary">
+            {totalCount}
+          </span>
+        )}
+        {hasWarning && totalCount === 0 && (
+          <span
+            className="inline-block h-1.5 w-1.5 shrink-0 rounded-full bg-warning"
+            aria-label="Configuration needed"
+          />
+        )}
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Positioner sideOffset={8} align="start">
+          <Popover.Popup
+            className={cn(
+              "z-popover overflow-x-hidden overflow-y-auto rounded-lg border border-border",
+              "bg-popover shadow-md text-popover-foreground",
+              "max-h-[80vh]",
+            )}
+          >
+            {activePanelItem ? (
+              <PanelView
+                item={activePanelItem}
+                onBack={() => onActivePanelChange(null)}
+              >
+                {renderPanel(activePanel!)}
+              </PanelView>
+            ) : (
+              <MenuList items={items} onSelect={onActivePanelChange} />
+            )}
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Menu list — shown when no panel is drilled into
+// ---------------------------------------------------------------------------
+
+function MenuList({
+  items,
+  onSelect,
+}: {
+  items: readonly ConfigureMenuItem[];
+  onSelect: (id: string) => void;
+}) {
+  return (
+    <div className="py-1" role="menu">
+      {items.map((item) => (
+        <button
+          key={item.id}
+          type="button"
+          role="menuitem"
+          onClick={() => onSelect(item.id)}
+          className={cn(
+            "flex w-full items-center gap-2.5 px-3 py-2 text-sm transition-colors",
+            "text-foreground hover:bg-accent/50",
+          )}
+        >
+          <span className="shrink-0 text-muted-foreground">{item.icon}</span>
+          <span className="flex-1 text-left">{item.label}</span>
+          {item.hasWarning && (
+            <span
+              className="inline-block h-1.5 w-1.5 shrink-0 rounded-full bg-warning"
+              aria-label="Needs configuration"
+            />
+          )}
+          {item.count > 0 && (
+            <span className="rounded-full bg-primary/15 px-1.5 text-[0.6rem] font-medium text-primary">
+              {item.count}
+            </span>
+          )}
+          <ChevronRightIcon />
+        </button>
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Panel view — shown when a specific item is drilled into
+// ---------------------------------------------------------------------------
+
+function PanelView({
+  item,
+  onBack,
+  children,
+}: {
+  item: ConfigureMenuItem;
+  onBack: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <div>
+      <div className="flex items-center gap-2 border-b border-border/50 px-3 py-2">
+        <button
+          type="button"
+          onClick={onBack}
+          className="shrink-0 rounded p-0.5 text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground"
+          aria-label="Back to configuration menu"
+        >
+          <ChevronLeftIcon />
+        </button>
+        <span className="shrink-0 text-muted-foreground">{item.icon}</span>
+        <span className="text-sm font-medium text-foreground">
+          {item.label}
+        </span>
+      </div>
+      <div className="p-3">{children}</div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons — local to ConfigureMenu
+// ---------------------------------------------------------------------------
+
+function ChevronRightIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M6 4l4 4-4 4" />
+    </svg>
+  );
+}
+
+function ChevronLeftIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M10 4l-4 4 4 4" />
+    </svg>
+  );
+}