@data-club/ai-hub 0.0.1

package/src/components/DataClubAIHub/index.tsx

@@ -0,0 +1,300 @@
+/**
+ * `<DataClubAIHub />` — the default monolithic chat component
+ * (Tier 1 / Tier 2 surface).
+ *
+ * Internally a thin composition over `<AIHubProvider>` + `<AuthGate>` +
+ * `<ChatShell>`. The structural budget of ≤50 lines for the body (§7.1)
+ * is honored — the body is a single JSX tree; the prop forwarding is
+ * verbose because TypeScript's `exactOptionalPropertyTypes: true`
+ * forbids passing `prop={undefined}`.
+ *
+ * Step 10 lights up:
+ *
+ * - The remaining slot props (`customMessageActions`,
+ *   `customMessageBubble`, `customInputToolbarItems`).
+ * - The server-toggle precedence (§8.4) — the resolved boolean stack
+ *   is computed inside `ChatShell` from `useAIHub().featureToggles +
+ *   the prop overrides we forward here.
+ * - The theme props (`defaultTheme`, `showThemeSwitcher`) — these flow
+ *   through the provider (theme_default is a server-config override).
+ *
+ * @see SPECIFICATIONS.md §7.3 — `<DataClubAIHub />` props
+ * @see SPECIFICATIONS.md §5 — per-customer wrapper shape
+ * @see ui-sketches/03-chat.md — the chat layout
+ * @see ui-sketches/00-shell.md — the shell chrome
+ */
+
+import { useState, type ReactNode } from "react";
+
+import type {
+  AIHubMessageActionRenderer,
+  AIHubMessageBubbleRenderer,
+} from "../../types.js";
+import { AIHubProvider } from "../../context/AIHubProvider.js";
+import { AuthGate } from "../AuthGate/index.js";
+import { ChatShell } from "../ChatShell/index.js";
+import { DataClubAIHubAdmin } from "../DataClubAIHubAdmin/index.js";
+import type {
+  AIHubLoginClassNames,
+} from "../DataClubAIHubLogin/index.js";
+import type {
+  AIHubChangePasswordClassNames,
+} from "../ChangePassword/index.js";
+import type { AIHubTexts, DeepPartial } from "../../auth/texts.js";
+
+/**
+ * Props for `<DataClubAIHub />`.
+ *
+ * Every `show*` / boolean prop here is a **React-prop default** for the
+ * §8.4 precedence stack: server toggle > React prop > built-in default.
+ * The server toggle is fetched lazily by the provider and applied
+ * inside `ChatShell` via `resolveAffordanceFlags`.
+ */
+export interface DataClubAIHubProps {
+  /**
+   * Base URL the ai-hub-server is mounted at — typically `/api/ai-hub`
+   * for the per-customer wrapper shape (§5). Defaults to `/api/ai-hub`.
+   */
+  baseUrl?: string;
+  /**
+   * Title shown on the login_card *and* used as the default shell
+   * header logo when `customShellHeaderLeft` is unset. Defaults to
+   * `"ai-hub"`. Per-customer wrappers set this to their brand label.
+   */
+  productName?: string;
+  /** Placeholder for the username input on the login card. */
+  usernamePlaceholder?: string;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Per-element class overrides for the login screen. */
+  loginClassNames?: Partial<AIHubLoginClassNames>;
+  /** Per-element class overrides for the change-password screen. */
+  changePasswordClassNames?: Partial<AIHubChangePasswordClassNames>;
+  /** Extra className merged onto the chat shell root. */
+  className?: string;
+
+  /* ── Sessions panel toggles (§7.3 / §8.4) ──────────────────────── */
+  /** Default for sessions_panel_enabled. Default true. */
+  sessions?: boolean;
+  /** Default for sessions_panel_resizable. Default true. */
+  sessionsPanelResizable?: boolean;
+  /** Sessions panel side — not a §8.4 toggle, pure layout prop. */
+  sessionsPanelPosition?: "left" | "right";
+  /** Sessions panel width in percent — not a §8.4 toggle. */
+  sessionsPanelWidthPercent?: number;
+  /** Default for sessions_panel_collapsible. Default true. */
+  sessionsPanelCollapsible?: boolean;
+  /** Default for create_session_button_enabled. Default true. */
+  showCreateSessionButton?: boolean;
+
+  /* ── Input controls (§8.4) ─────────────────────────────────────── */
+  /** Default for user_input_enabled. Default true. */
+  userInput?: boolean;
+  /** Default for effort_control_visible. Default true. */
+  showEffortControl?: boolean;
+  /** Default for stop_button_enabled. Default true. */
+  showStopButton?: boolean;
+
+  /* ── Chat affordances (§8.4) ───────────────────────────────────── */
+  /** Default for tool_calls_visible. Default true. */
+  showToolCalls?: boolean;
+  /** Default for reasoning_visible. Default true. */
+  showReasoning?: boolean;
+  /** Default for system_messages_visible. Default true. */
+  showSystemMessages?: boolean;
+  /** Default for tpm_notice_visible. Default true. */
+  showTpmNotice?: boolean;
+  /** Default for scroll_to_present_visible. Default true. */
+  showScrollToPresentButton?: boolean;
+  /** Default for turn_status_visible. Default true. */
+  showTurnStatus?: boolean;
+
+  /* ── Theming (§7.6) ────────────────────────────────────────────── */
+  /**
+   * Fallback theme used before `/auth/me` resolves (or when no
+   * cache exists). Server's `theme_default` wins after hydration.
+   */
+  defaultTheme?: "light" | "dark";
+  /**
+   * Whether the `ThemeSwitcher` primitive renders in the user menu.
+   * Server's `theme_switcher_enabled` wins (true → switcher; false →
+   * hidden entirely). The React prop is the dev-time fallback.
+   */
+  showThemeSwitcher?: boolean;
+
+  /* ── Agents picker / deep-links ────────────────────────────────── */
+  /** Whether the agents picker is reachable. Default true. */
+  showAgentsPicker?: boolean;
+  /** Open this agent directly on mount (skips the picker). */
+  initialAgentId?: string;
+  /** Open this session directly on mount. */
+  initialSessionId?: string;
+
+  /* ── Slot props ────────────────────────────────────────────────── */
+  /** Left-of-shell-header slot (logo + brand name + nav links). */
+  customShellHeaderLeft?: ReactNode;
+  /** Bottom-of-shell footer strip. Unset → no footer. */
+  customShellFooter?: ReactNode;
+  /** Per-agent header slot (right of agent name + turn-status indicator). */
+  customHeaderContent?: ReactNode;
+  /** Top-of-sessions-panel slot. */
+  customSidebarHeader?: ReactNode;
+  /** Bottom-of-sessions-panel slot. */
+  customSidebarFooter?: ReactNode;
+  /** Per-message action bar renderer — gets every assistant message. */
+  customMessageActions?: AIHubMessageActionRenderer;
+  /** Replaces the entire message bubble. Advanced; Tier 3 only typically. */
+  customMessageBubble?: AIHubMessageBubbleRenderer;
+  /** Extra toolbar items in the input area (next to the effort dropdown). */
+  customInputToolbarItems?: ReactNode;
+}
+
+/**
+ * Renders the monolith.
+ *
+ * @param props - see `DataClubAIHubProps`.
+ * @returns the rendered component.
+ */
+export function DataClubAIHub(props: DataClubAIHubProps): ReactNode {
+  const baseUrl = props.baseUrl ?? "/api/ai-hub";
+  return (
+    <AIHubProvider
+      baseUrl={baseUrl}
+      {...(props.defaultTheme !== undefined ? { defaultTheme: props.defaultTheme } : {})}
+    >
+      <AuthGate
+        {...(props.productName !== undefined ? { productName: props.productName } : {})}
+        {...(props.usernamePlaceholder !== undefined
+          ? { usernamePlaceholder: props.usernamePlaceholder }
+          : {})}
+        {...(props.texts !== undefined ? { texts: props.texts } : {})}
+        {...(props.loginClassNames !== undefined
+          ? { loginClassNames: props.loginClassNames }
+          : {})}
+        {...(props.changePasswordClassNames !== undefined
+          ? { changePasswordClassNames: props.changePasswordClassNames }
+          : {})}
+      >
+        <AuthedShell props={props} />
+      </AuthGate>
+    </AIHubProvider>
+  );
+}
+
+/**
+ * Internal helper that owns the chat-vs-admin route state inside the
+ * authenticated tree. Lives here (rather than in `ChatShell` or
+ * `DataClubAIHubAdmin`) because the admin <-> chat swap is monolith-
+ * specific behavior — Tier-3 wrappers handle navigation themselves and
+ * compose `<AIHub.AdminShell />` directly when needed.
+ *
+ * Kept as a function component so React's hook ordering is well-defined
+ * and the route state survives across AuthGate's children rerenders.
+ *
+ * @param hostProps - destructured component-props wrapper.
+ * @param hostProps.props - the monolith's full prop bag, forwarded to
+ *   ChatShell (and selectively to `DataClubAIHubAdmin` in admin mode).
+ * @returns either the chat shell or the admin shell.
+ */
+function AuthedShell({ props }: { props: DataClubAIHubProps }): ReactNode {
+  const [view, setView] = useState<"chat" | "admin">("chat");
+  if (view === "admin") {
+    return (
+      <DataClubAIHubAdmin
+        {...(props.texts !== undefined ? { texts: props.texts } : {})}
+        {...(props.productName !== undefined
+          ? { productName: props.productName }
+          : {})}
+        {...(props.customShellHeaderLeft !== undefined
+          ? { customShellHeaderLeft: props.customShellHeaderLeft }
+          : {})}
+        onExit={() => setView("chat")}
+      />
+    );
+  }
+  return (
+    <ChatShell
+      onOpenAdmin={() => setView("admin")}
+      {...(props.productName !== undefined ? { productName: props.productName } : {})}
+      {...(props.customShellHeaderLeft !== undefined
+        ? { customShellHeaderLeft: props.customShellHeaderLeft }
+        : {})}
+      {...(props.customShellFooter !== undefined
+        ? { customShellFooter: props.customShellFooter }
+        : {})}
+      {...(props.customHeaderContent !== undefined
+        ? { customHeaderContent: props.customHeaderContent }
+        : {})}
+      {...(props.customSidebarHeader !== undefined
+        ? { customSidebarHeader: props.customSidebarHeader }
+        : {})}
+      {...(props.customSidebarFooter !== undefined
+        ? { customSidebarFooter: props.customSidebarFooter }
+        : {})}
+      {...(props.customMessageActions !== undefined
+        ? { customMessageActions: props.customMessageActions }
+        : {})}
+      {...(props.customMessageBubble !== undefined
+        ? { customMessageBubble: props.customMessageBubble }
+        : {})}
+      {...(props.customInputToolbarItems !== undefined
+        ? { customInputToolbarItems: props.customInputToolbarItems }
+        : {})}
+      {...(props.showAgentsPicker !== undefined
+        ? { showAgentsPicker: props.showAgentsPicker }
+        : {})}
+      {...(props.initialAgentId !== undefined
+        ? { initialAgentId: props.initialAgentId }
+        : {})}
+      {...(props.initialSessionId !== undefined
+        ? { initialSessionId: props.initialSessionId }
+        : {})}
+      {...(props.sessions !== undefined ? { showSessionsPanel: props.sessions } : {})}
+      {...(props.sessionsPanelCollapsible !== undefined
+        ? { sessionsPanelCollapsible: props.sessionsPanelCollapsible }
+        : {})}
+      {...(props.sessionsPanelResizable !== undefined
+        ? { sessionsPanelResizable: props.sessionsPanelResizable }
+        : {})}
+      {...(props.sessionsPanelPosition !== undefined
+        ? { sessionsPanelPosition: props.sessionsPanelPosition }
+        : {})}
+      {...(props.sessionsPanelWidthPercent !== undefined
+        ? { sessionsPanelWidthPercent: props.sessionsPanelWidthPercent }
+        : {})}
+      {...(props.userInput !== undefined ? { showInput: props.userInput } : {})}
+      {...(props.showCreateSessionButton !== undefined
+        ? { showCreateSessionButton: props.showCreateSessionButton }
+        : {})}
+      {...(props.showEffortControl !== undefined
+        ? { showEffortControl: props.showEffortControl }
+        : {})}
+      {...(props.showStopButton !== undefined
+        ? { showStopButton: props.showStopButton }
+        : {})}
+      {...(props.showToolCalls !== undefined
+        ? { showToolCalls: props.showToolCalls }
+        : {})}
+      {...(props.showReasoning !== undefined
+        ? { showReasoning: props.showReasoning }
+        : {})}
+      {...(props.showSystemMessages !== undefined
+        ? { showSystemMessages: props.showSystemMessages }
+        : {})}
+      {...(props.showTpmNotice !== undefined
+        ? { showTpmNotice: props.showTpmNotice }
+        : {})}
+      {...(props.showScrollToPresentButton !== undefined
+        ? { showScrollToPresentButton: props.showScrollToPresentButton }
+        : {})}
+      {...(props.showTurnStatus !== undefined
+        ? { showTurnStatus: props.showTurnStatus }
+        : {})}
+      {...(props.showThemeSwitcher !== undefined
+        ? { showThemeSwitcher: props.showThemeSwitcher }
+        : {})}
+      {...(props.texts !== undefined ? { texts: props.texts } : {})}
+      {...(props.className !== undefined ? { className: props.className } : {})}
+    />
+  );
+}