@data-club/ai-hub 0.0.1

package/src/components/ChatShell/UserMenu.tsx

@@ -0,0 +1,196 @@
+/**
+ * `<UserMenu />` — the right-side identity affordance in the shell
+ * header.
+ *
+ * Step 9 ships the minimal version: avatar circle + username, click
+ * opens a dropdown with the role label and a `Sign out` item. Step 10
+ * adds the `Theme: Light ↔ Dark` item. **Step 11 adds the `Admin` and
+ * `Open Letta ADE ↗` items**, both gated to `role >= power_user` per
+ * §8.3 / [00-shell.md]. Step 12 wires the voluntary `Change Password`
+ * item via the shell's shell-aware framing.
+ *
+ * `Open Letta ADE` opens the deployment's ADE in a new tab
+ * (`target="_blank" rel="noopener noreferrer"`); the URL comes from the
+ * `deployment.letta_ade_url` field on `/auth/me` (only present for
+ * `power_user` and above by design — see `AIHubDeployment` JSDoc).
+ *
+ * The right side of the shell header is **library-owned** and not
+ * customizable — per-customer wrappers can theme via CSS but cannot
+ * replace this component.
+ *
+ * @see ui-sketches/00-shell.md — user_menu_button + user_menu_dropdown
+ * @see SPECIFICATIONS.md §8.3 — Open Letta ADE link
+ */
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+import type { AIHubChatTexts } from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+import { useAIHubAuth } from "../../context/useAIHubAuth.js";
+import type { AIHubRole } from "../../types.js";
+
+import { ThemeSwitcher } from "../ThemeSwitcher/index.js";
+
+/**
+ * Returns true when the given role can see the admin-only menu items
+ * (`Admin` + `Open Letta ADE`). Mirrors the §8.2 matrix.
+ *
+ * @param role - the caller's role, or `null` when not authenticated.
+ * @returns whether the items should render.
+ */
+function canSeeAdminItems(role: AIHubRole | null): boolean {
+  return role === "power_user" || role === "admin" || role === "super_admin";
+}
+
+/**
+ * Props for the internal `<UserMenu />` helper.
+ */
+export interface UserMenuProps {
+  /** Resolved chat texts (the menu copy lives under `texts.chat`). */
+  texts: AIHubChatTexts;
+  /**
+   * Fired when the user clicks the `Admin` item. The host (chat shell)
+   * decides what to do — typically swap the main area for
+   * `<DataClubAIHubAdmin />`. Omitted when the host doesn't support an
+   * in-shell admin route (a Tier-3 wrapper that mounts admin on its own
+   * Next.js page can omit this and rely on its own nav instead).
+   */
+  onOpenAdmin?: () => void;
+}
+
+/**
+ * Renders the user menu (button + dropdown).
+ *
+ * @param props - see `UserMenuProps`.
+ * @returns the rendered menu, or `null` when unauthenticated.
+ */
+export function UserMenu(props: UserMenuProps): ReactNode {
+  const { texts } = props;
+  const auth = useAIHubAuth();
+  const { themeSwitcherEnabled } = useAIHub();
+  const [open, setOpen] = useState(false);
+  const wrapRef = useRef<HTMLDivElement | null>(null);
+  const showAdminItems = canSeeAdminItems(auth.role);
+  const lettaAdeUrl = auth.deployment?.letta_ade_url ?? null;
+
+  // Close on outside-click + Escape so the menu can't be left open
+  // accidentally over the chat below.
+  useEffect(() => {
+    if (!open) return;
+    function handleClick(e: MouseEvent): void {
+      const node = wrapRef.current;
+      if (node && !node.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    function handleKey(e: KeyboardEvent): void {
+      if (e.key === "Escape") setOpen(false);
+    }
+    document.addEventListener("mousedown", handleClick);
+    document.addEventListener("keydown", handleKey);
+    return () => {
+      document.removeEventListener("mousedown", handleClick);
+      document.removeEventListener("keydown", handleKey);
+    };
+  }, [open]);
+
+  if (!auth.user) return null;
+
+  const displayName = auth.user.display_name ?? auth.user.username;
+
+  return (
+    <div
+      className="data-club-ai-hub__user-menu"
+      ref={wrapRef}
+      data-testid="user-menu"
+    >
+      <button
+        type="button"
+        className="data-club-ai-hub__user-menu__button"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen((o) => !o)}
+        data-testid="user-menu-button"
+      >
+        <span
+          className="data-club-ai-hub__user-menu__avatar"
+          aria-hidden="true"
+        >
+          {displayName.slice(0, 1).toUpperCase()}
+        </span>
+        <span className="data-club-ai-hub__user-menu__username">
+          {auth.user.username}
+        </span>
+      </button>
+      {open ? (
+        <div
+          className="data-club-ai-hub__user-menu__dropdown"
+          role="menu"
+          data-testid="user-menu-dropdown"
+        >
+          <div className="data-club-ai-hub__user-menu__header">
+            <div className="data-club-ai-hub__user-menu__username-large">
+              {displayName}
+            </div>
+            <div className="data-club-ai-hub__user-menu__role">
+              {auth.role ?? ""}
+            </div>
+          </div>
+          {showAdminItems && props.onOpenAdmin ? (
+            <button
+              type="button"
+              role="menuitem"
+              className="data-club-ai-hub__user-menu__item"
+              data-testid="user-menu-admin"
+              onClick={() => {
+                setOpen(false);
+                props.onOpenAdmin?.();
+              }}
+            >
+              ⚙ {texts.adminMenuItem}
+            </button>
+          ) : null}
+          {showAdminItems && lettaAdeUrl !== null && lettaAdeUrl.length > 0 ? (
+            <a
+              role="menuitem"
+              className="data-club-ai-hub__user-menu__item data-club-ai-hub__user-menu__item--link"
+              data-testid="user-menu-open-letta-ade"
+              href={lettaAdeUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={() => setOpen(false)}
+            >
+              ↗ {texts.openLettaAdeMenuItem}
+            </a>
+          ) : null}
+          {themeSwitcherEnabled ? (
+            <div
+              className="data-club-ai-hub__user-menu__item"
+              role="none"
+              data-testid="user-menu-theme-row"
+            >
+              <ThemeSwitcher />
+            </div>
+          ) : null}
+          <button
+            type="button"
+            role="menuitem"
+            className="data-club-ai-hub__user-menu__item"
+            onClick={() => {
+              setOpen(false);
+              void auth.logout();
+            }}
+            data-testid="user-menu-sign-out"
+          >
+            ⏻ {texts.signOutMenuItem}
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/ChatShell/index.tsx

@@ -0,0 +1,307 @@
+/**
+ * `<ChatShell />` — the authenticated chrome wrapping the chat layout.
+ *
+ * Step 10 lights up the §8.4 server-toggle precedence here: this is the
+ * one place that calls `resolveAffordanceFlags(serverToggles, propStack)`
+ * and then forwards the resolved booleans to the child primitives so
+ * each primitive doesn't have to re-implement the merge.
+ *
+ * `ChatShell` is internal to `<DataClubAIHub />` — Tier-3 wrappers
+ * compose primitives directly and don't render this component.
+ *
+ * @see SPECIFICATIONS.md §7.3, §8.4
+ * @see ui-sketches/00-shell.md, ui-sketches/03-chat.md
+ */
+
+import { useEffect, useMemo, type ReactNode } from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+import {
+  resolveAffordanceFlags,
+  type AIHubAffordanceFlags,
+} from "../../state/affordances.js";
+import type {
+  AIHubMessageActionRenderer,
+  AIHubMessageBubbleRenderer,
+} from "../../types.js";
+import { AgentsPicker } from "../AgentsPicker/index.js";
+import { Layout } from "../Layout/index.js";
+import { MainColumn } from "../MainColumn/index.js";
+import { MessageInput } from "../MessageInput/index.js";
+import { MessageList } from "../MessageList/index.js";
+import { SessionsPanel } from "../SessionsPanel/index.js";
+
+import { ShellHeader } from "./ShellHeader.js";
+
+/**
+ * Props for `<ChatShell />` — a strict subset of `<DataClubAIHub />` props
+ * the shell actually reads.
+ */
+export interface ChatShellProps {
+  /** Product name shown when `customShellHeaderLeft` is unset. */
+  productName?: string;
+  /** Wrapper-supplied left-of-header slot. */
+  customShellHeaderLeft?: ReactNode;
+  /** Wrapper-supplied below-main-area footer slot. */
+  customShellFooter?: ReactNode;
+  /** Wrapper-supplied per-agent header slot (right of agent name). */
+  customHeaderContent?: ReactNode;
+  /** Top-of-sessions-panel slot. */
+  customSidebarHeader?: ReactNode;
+  /** Bottom-of-sessions-panel slot. */
+  customSidebarFooter?: ReactNode;
+  /** Per-message action bar renderer (Tier-2 slot). */
+  customMessageActions?: AIHubMessageActionRenderer;
+  /** Override the entire bubble (Tier-3 escape hatch). */
+  customMessageBubble?: AIHubMessageBubbleRenderer;
+  /** Extra toolbar items in the input area. */
+  customInputToolbarItems?: ReactNode;
+  /** Whether the agents picker is reachable. Defaults to true. */
+  showAgentsPicker?: boolean;
+  /** Skip the picker entirely and open this agent. */
+  initialAgentId?: string;
+  /** Deep-link a session inside `initialAgentId`. */
+  initialSessionId?: string;
+
+  /* ── §8.4 React-prop defaults — server toggles override at runtime. ── */
+  /** sessions_panel_enabled default. */
+  showSessionsPanel?: boolean;
+  /** sessions_panel_collapsible default. */
+  sessionsPanelCollapsible?: boolean;
+  /** sessions_panel_resizable default. */
+  sessionsPanelResizable?: boolean;
+  /** Layout-only (not a §8.4 toggle). */
+  sessionsPanelPosition?: "left" | "right";
+  /** Layout-only (not a §8.4 toggle). */
+  sessionsPanelWidthPercent?: number;
+  /** user_input_enabled default. */
+  showInput?: boolean;
+  /** create_session_button_enabled default. */
+  showCreateSessionButton?: boolean;
+  /** effort_control_visible default. */
+  showEffortControl?: boolean;
+  /** stop_button_enabled default. */
+  showStopButton?: boolean;
+  /** tool_calls_visible default. */
+  showToolCalls?: boolean;
+  /** reasoning_visible default. */
+  showReasoning?: boolean;
+  /** system_messages_visible default. */
+  showSystemMessages?: boolean;
+  /** tpm_notice_visible default. */
+  showTpmNotice?: boolean;
+  /** scroll_to_present_visible default. */
+  showScrollToPresentButton?: boolean;
+  /** turn_status_visible default. */
+  showTurnStatus?: boolean;
+  /** Whether the ThemeSwitcher renders in the user menu (server override wins). */
+  showThemeSwitcher?: boolean;
+
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra className merged on the shell root. */
+  className?: string;
+  /**
+   * Fired when the user clicks the `Admin` item in the user-menu. Step 11
+   * — the monolith uses this to swap the main area for
+   * `<DataClubAIHubAdmin />`. Omitted by Tier-3 wrappers that mount admin
+   * on a separate Next.js route.
+   */
+  onOpenAdmin?: () => void;
+}
+
+/**
+ * Builds the prop-override record consumed by `resolveAffordanceFlags`.
+ *
+ * Note that some props on `ChatShellProps` use slightly different names
+ * than the `AIHubAffordanceFlags` field names (e.g. `showInput` vs.
+ * `userInputEnabled`); this function maps them. Adding a new flag
+ * requires touching this function alongside `AIHubAffordanceFlags`.
+ */
+function buildPropOverrides(
+  props: ChatShellProps,
+): Partial<AIHubAffordanceFlags> {
+  const out: Partial<AIHubAffordanceFlags> = {};
+  if (props.showSessionsPanel !== undefined)
+    out.sessionsPanelEnabled = props.showSessionsPanel;
+  if (props.sessionsPanelResizable !== undefined)
+    out.sessionsPanelResizable = props.sessionsPanelResizable;
+  if (props.sessionsPanelCollapsible !== undefined)
+    out.sessionsPanelCollapsible = props.sessionsPanelCollapsible;
+  if (props.showCreateSessionButton !== undefined)
+    out.createSessionButtonEnabled = props.showCreateSessionButton;
+  if (props.showInput !== undefined) out.userInputEnabled = props.showInput;
+  if (props.showStopButton !== undefined)
+    out.stopButtonEnabled = props.showStopButton;
+  if (props.showToolCalls !== undefined)
+    out.toolCallsVisible = props.showToolCalls;
+  if (props.showReasoning !== undefined)
+    out.reasoningVisible = props.showReasoning;
+  if (props.showSystemMessages !== undefined)
+    out.systemMessagesVisible = props.showSystemMessages;
+  if (props.showTpmNotice !== undefined)
+    out.tpmNoticeVisible = props.showTpmNotice;
+  if (props.showEffortControl !== undefined)
+    out.effortControlVisible = props.showEffortControl;
+  if (props.showScrollToPresentButton !== undefined)
+    out.scrollToPresentVisible = props.showScrollToPresentButton;
+  if (props.showTurnStatus !== undefined)
+    out.turnStatusVisible = props.showTurnStatus;
+  return out;
+}
+
+/**
+ * Renders the chat shell.
+ *
+ * @param props - see `ChatShellProps`.
+ * @returns the rendered shell.
+ */
+export function ChatShell(props: ChatShellProps): ReactNode {
+  const {
+    agents,
+    agentsLoading,
+    activeAgentId,
+    setActiveAgent,
+    activeSessionId,
+    setActiveSession,
+    featureToggles,
+  } = useAIHub();
+  const texts = resolveAIHubTexts(props.texts);
+  const productName = props.productName ?? "ai-hub";
+  const showAgentsPicker = props.showAgentsPicker ?? true;
+  const sessionsPanelPosition = props.sessionsPanelPosition ?? "left";
+  const sessionsPanelWidthPercent = props.sessionsPanelWidthPercent ?? 25;
+
+  // Compose the §8.4 precedence stack once. `featureToggles === null`
+  // (still loading) → fall through to prop / default; we treat it as
+  // an empty blob so the precedence rule reduces to "prop > default".
+  const propOverrides = useMemo(() => buildPropOverrides(props), [props]);
+  const flags = useMemo(
+    () => resolveAffordanceFlags(featureToggles, propOverrides),
+    [featureToggles, propOverrides],
+  );
+
+  // Deep-link: open `initialAgentId` and `initialSessionId` on first
+  // mount (and whenever those props change).
+  useEffect(() => {
+    if (props.initialAgentId && activeAgentId !== props.initialAgentId) {
+      setActiveAgent(props.initialAgentId);
+    }
+  }, [props.initialAgentId]);
+
+  useEffect(() => {
+    if (
+      props.initialSessionId &&
+      activeSessionId !== props.initialSessionId
+    ) {
+      setActiveSession(props.initialSessionId);
+    }
+  }, [props.initialSessionId]);
+
+  const autoSelectOnlyAgent = useMemo(
+    () =>
+      showAgentsPicker && !activeAgentId && !agentsLoading && agents.length === 1,
+    [showAgentsPicker, activeAgentId, agentsLoading, agents],
+  );
+  useEffect(() => {
+    if (autoSelectOnlyAgent && agents[0]) {
+      setActiveAgent(agents[0].id);
+    }
+  }, [autoSelectOnlyAgent, agents, setActiveAgent]);
+
+  const inPicker = showAgentsPicker && !activeAgentId;
+
+  const rootClass = props.className
+    ? `data-club-ai-hub__shell ${props.className}`
+    : "data-club-ai-hub__shell";
+
+  return (
+    <div className={rootClass} data-testid="chat-shell">
+      <ShellHeader
+        productName={productName}
+        texts={texts.chat}
+        {...(props.customShellHeaderLeft !== undefined
+          ? { customShellHeaderLeft: props.customShellHeaderLeft }
+          : {})}
+        {...(props.onOpenAdmin !== undefined
+          ? { onOpenAdmin: props.onOpenAdmin }
+          : {})}
+      />
+      <main
+        className="data-club-ai-hub__shell-main"
+        data-testid="shell-main"
+      >
+        {inPicker ? (
+          <AgentsPicker
+            {...(props.texts !== undefined ? { texts: props.texts } : {})}
+          />
+        ) : (
+          <Layout
+            panelPosition={sessionsPanelPosition}
+            panelWidthPercent={sessionsPanelWidthPercent}
+          >
+            {flags.sessionsPanelEnabled ? (
+              <SessionsPanel
+                showCreateButton={flags.createSessionButtonEnabled}
+                collapsible={flags.sessionsPanelCollapsible}
+                {...(props.texts !== undefined ? { texts: props.texts } : {})}
+                {...(props.customSidebarHeader !== undefined
+                  ? { customHeader: props.customSidebarHeader }
+                  : {})}
+                {...(props.customSidebarFooter !== undefined
+                  ? { customFooter: props.customSidebarFooter }
+                  : {})}
+              />
+            ) : null}
+            <MainColumn
+              showBackToAgents={showAgentsPicker}
+              showTurnStatus={flags.turnStatusVisible}
+              {...(props.texts !== undefined ? { texts: props.texts } : {})}
+              {...(props.customHeaderContent !== undefined
+                ? { customHeaderContent: props.customHeaderContent }
+                : {})}
+            >
+              <MessageList
+                showSystemMessages={flags.systemMessagesVisible}
+                showTpmNotice={flags.tpmNoticeVisible}
+                showScrollToPresentButton={flags.scrollToPresentVisible}
+                showReasoning={flags.reasoningVisible}
+                showToolCalls={flags.toolCallsVisible}
+                {...(props.texts !== undefined ? { texts: props.texts } : {})}
+                {...(props.customMessageActions !== undefined
+                  ? { renderMessageActions: props.customMessageActions }
+                  : {})}
+                {...(props.customMessageBubble !== undefined
+                  ? { renderMessageBubble: props.customMessageBubble }
+                  : {})}
+              />
+              {flags.userInputEnabled ? (
+                <MessageInput
+                  showEffortControl={flags.effortControlVisible}
+                  stopButtonEnabled={flags.stopButtonEnabled}
+                  {...(props.texts !== undefined ? { texts: props.texts } : {})}
+                  {...(props.customInputToolbarItems !== undefined
+                    ? { toolbar: props.customInputToolbarItems }
+                    : {})}
+                />
+              ) : null}
+            </MainColumn>
+          </Layout>
+        )}
+      </main>
+      {props.customShellFooter ? (
+        <footer
+          className="data-club-ai-hub__shell-footer"
+          data-testid="shell-footer"
+        >
+          {props.customShellFooter}
+        </footer>
+      ) : null}
+    </div>
+  );
+}