cortena-ui 1.4.2 → 1.6.0

package/src/components/agent-chat-popup.tsx

@@ -0,0 +1,289 @@
+"use client";
+
+/**
+ * AgentChatPopup — the extension's own agent, in the corner of every screen.
+ *
+ * §17 of how-to-create-a-cortena-extension, audit rule P-25. Mounted in
+ * `AppShell`'s `agentSlot`, so it stacks above the theme/help cluster rather
+ * than beside it and no extension positions a floating control itself.
+ *
+ * ```tsx
+ * <AppShell
+ *   extension={{ id: "tasks", name: "Tasks" }}
+ *   user={user}
+ *   agentSlot={
+ *     <AgentChatPopup
+ *       extension={{ id: "tasks", name: "Tasks" }}
+ *       client={client}   // createAguiAgentChatClient({ …, agentId: "tasks" })
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * Three states, and the transitions between them are fixed: a collapsed pill,
+ * a panel, and full screen. **Cmd/Ctrl+J** toggles between the pill and the
+ * panel; **Escape** steps full screen -> panel -> pill, except while a run is
+ * streaming, where the composer takes Escape to mean "stop" — the first Escape
+ * during a run is nearly always about the run, not about the window.
+ *
+ * The chat stays mounted in every state, hidden rather than unmounted while
+ * collapsed. That is not an optimisation: a run started before the user
+ * collapsed the pop-up keeps streaming into it, and the unread dot on the pill
+ * is what says so. Unmounting would throw the reply away halfway through.
+ *
+ * State is remembered per window, in `sessionStorage`, alongside the session
+ * key — a second window of the same extension opens its own chat on its own
+ * session rather than inheriting this one's.
+ */
+
+import { Maximize2, Minimize2, X } from "lucide-react";
+import * as React from "react";
+import { BrandMark } from "@/components/app-shell";
+import { Button } from "@/components/button";
+import { AgentChat, type AgentChatProps } from "@/components/agent-chat";
+import { viewStorageKey, windowSessionStorage } from "@/agent-chat/session";
+import type { AgentChatClient } from "@/agent-chat/types";
+import { cn } from "@/lib/cn";
+
+export type AgentChatPopupState = "pill" | "panel" | "full";
+
+export interface AgentChatPopupExtension {
+  /** Registered mark id — the same `x-cortena.icon` the shell draws. */
+  id: string;
+  /** Display name. Also the agent template slug, unless `agentId` overrides it. */
+  name: string;
+}
+
+export interface AgentChatPopupProps
+  extends Omit<
+    AgentChatProps,
+    "agentName" | "storageScope" | "className" | "headerSlot" | "client"
+  > {
+  extension: AgentChatPopupExtension;
+  /** The transport. Its `agentId` is the template slug the sessions belong to. */
+  client: AgentChatClient;
+  /**
+   * Names the `sessionStorage` slots. Defaults to the extension id, which is
+   * what keeps two extensions on one origin out of each other's sessions.
+   */
+  storageScope?: string;
+  /** Start here instead of collapsed; the stored state still wins on reload. */
+  defaultState?: AgentChatPopupState;
+  className?: string;
+}
+
+/** Cmd on a Mac, Ctrl elsewhere. Documented in README.md. */
+function isToggleShortcut(event: KeyboardEvent): boolean {
+  return (event.metaKey || event.ctrlKey) && !event.altKey && event.key.toLowerCase() === "j";
+}
+
+function AgentChatPopup({
+  extension,
+  client,
+  storageScope,
+  defaultState = "pill",
+  className,
+  ...chatProps
+}: AgentChatPopupProps) {
+  const scope = storageScope ?? extension.id;
+  const [state, setState] = React.useState<AgentChatPopupState>(defaultState);
+  const [unread, setUnread] = React.useState(false);
+  const stateRef = React.useRef(state);
+  stateRef.current = state;
+  const pillRef = React.useRef<HTMLButtonElement>(null);
+  const panelRef = React.useRef<HTMLDivElement>(null);
+  /** Whether the user has opened or closed it, as against it starting open. */
+  const moved = React.useRef(false);
+
+  // Restore this window's open/collapsed choice. In an effect rather than a
+  // lazy initialiser so a server render and the first client render agree.
+  React.useEffect(() => {
+    try {
+      const stored = windowSessionStorage()?.getItem(viewStorageKey(scope));
+      if (stored === "pill" || stored === "panel" || stored === "full") {
+        setState(stored);
+      }
+    } catch {
+      // A blocked storage just means the pop-up opens collapsed.
+    }
+  }, [scope]);
+
+  const go = React.useCallback(
+    (next: AgentChatPopupState) => {
+      moved.current = true;
+      setState(next);
+      if (next !== "pill") {
+        setUnread(false);
+      }
+      try {
+        windowSessionStorage()?.setItem(viewStorageKey(scope), next);
+      } catch {
+        // Not remembering the choice is not a reason to refuse the change.
+      }
+    },
+    [scope],
+  );
+
+  // The unread dot. Subscribed here rather than read out of the chat, because
+  // the point is what happened while the surface was not being looked at.
+  React.useEffect(() => {
+    return client.onChat((event) => {
+      if (stateRef.current === "pill" && (event.state === "delta" || event.state === "final")) {
+        setUnread(true);
+      }
+    });
+  }, [client]);
+
+  React.useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!isToggleShortcut(event)) {
+        return;
+      }
+      event.preventDefault();
+      go(stateRef.current === "pill" ? "panel" : "pill");
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [go]);
+
+  /**
+   * Escape steps down one level. It is handled on the panel rather than on the
+   * window so it only fires when focus is inside the pop-up, and it arrives
+   * here only when the composer did not claim it — the composer stops
+   * propagation while a run is streaming, where Escape means "stop the run".
+   */
+  const onKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      event.preventDefault();
+      go(stateRef.current === "full" ? "panel" : "pill");
+    },
+    [go],
+  );
+
+  const open = state !== "pill";
+
+  /**
+   * Focus follows the pop-up.
+   *
+   * The panel is `hidden`, not unmounted, so nothing moves focus by itself.
+   * Opening left focus on the pill — which is now `hidden`, so the browser
+   * resets it to <body> and the next Tab starts at the top of the page rather
+   * than in the chat that was just opened. Closing had the mirror problem:
+   * focus was inside a subtree that had just become hidden.
+   *
+   * Only after the user moves it. A pop-up that starts on `panel`, or one
+   * restored from `sessionStorage` on load, must not steal focus from the page.
+   */
+  React.useEffect(() => {
+    if (!moved.current) {
+      return;
+    }
+    const frame = requestAnimationFrame(() => {
+      if (open) {
+        panelRef.current
+          ?.querySelector<HTMLElement>('[data-slot="agent-chat-input"]')
+          ?.focus({ preventScroll: true });
+      } else {
+        pillRef.current?.focus({ preventScroll: true });
+      }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [open]);
+
+  return (
+    <>
+      <button
+        ref={pillRef}
+        type="button"
+        data-slot="agent-chat-pill"
+        data-state={state}
+        data-unread={unread ? "" : undefined}
+        aria-expanded={open}
+        aria-label={`Ask ${extension.name}`}
+        hidden={open}
+        onClick={() => go("panel")}
+        className={cn(
+          "relative inline-flex h-10 items-center gap-2 rounded-[var(--ds-radius-full)] px-3.5",
+          "border border-[var(--ds-border)] bg-[var(--ds-card)] text-[color:var(--ds-foreground)]",
+          "shadow-[var(--ds-shadow-md)] outline-none",
+          "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+          "hover:bg-[var(--ds-hover)]",
+          "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)] focus-visible:ring-offset-2",
+          "focus-visible:ring-offset-[var(--ds-background)]",
+          className,
+        )}
+      >
+        <span className="flex size-5 items-center justify-center text-[color:var(--ds-primary)]">
+          <BrandMark id={extension.id} name={extension.name} size={16} decorative />
+        </span>
+        <span className="text-[length:var(--ds-text-caption-lg)] font-medium">
+          Ask {extension.name}
+        </span>
+        {unread ? (
+          <span
+            data-slot="agent-chat-pill-unread"
+            aria-label="The agent is replying"
+            className="size-2 rounded-[var(--ds-radius-full)] bg-[var(--ds-primary)]"
+          />
+        ) : null}
+      </button>
+
+      {/* Hidden, not unmounted: a run started before the pop-up was collapsed
+          keeps streaming, and the pill's dot is what reports it. */}
+      <div
+        ref={panelRef}
+        data-slot="agent-chat-panel"
+        data-state={state}
+        role="dialog"
+        aria-label={`${extension.name} agent`}
+        hidden={!open}
+        onKeyDown={onKeyDown}
+        className={cn(
+          "fixed z-50 flex flex-col overflow-hidden border border-[var(--ds-border)]",
+          "bg-[var(--ds-card)] shadow-[var(--ds-shadow-lg)]",
+          state === "full"
+            ? "inset-0 rounded-none"
+            : cn(
+                "right-6 bottom-6 rounded-[var(--ds-radius-lg)]",
+                "h-[min(40rem,calc(100vh-3rem))] w-[min(26.25rem,calc(100vw-3rem))]",
+              ),
+        )}
+      >
+        <AgentChat
+          client={client}
+          agentName={extension.name}
+          storageScope={scope}
+          className="min-h-0 flex-1"
+          headerSlot={
+            <>
+              <Button
+                size="icon-sm"
+                variant="ghost"
+                data-slot="agent-chat-expand"
+                aria-label={state === "full" ? "Restore the panel" : "Expand to full screen"}
+                onClick={() => go(state === "full" ? "panel" : "full")}
+              >
+                {state === "full" ? <Minimize2 aria-hidden /> : <Maximize2 aria-hidden />}
+              </Button>
+              <Button
+                size="icon-sm"
+                variant="ghost"
+                data-slot="agent-chat-collapse"
+                aria-label="Collapse the agent"
+                onClick={() => go("pill")}
+              >
+                <X aria-hidden />
+              </Button>
+            </>
+          }
+          {...chatProps}
+        />
+      </div>
+    </>
+  );
+}
+
+export { AgentChatPopup };