@nocobase/portal-template-default 1.0.9 → 1.0.10

package/{registry → src/extensions}/nocobase-ai/demo/index.tsx

@@ -1,8 +1,7 @@
 import {
   AIChatWindow,
-  ChatDialog,
+  ChatSurface,
   ChatSurfaceActions,
-  ChatSidePanelLayout,
   useAIPageElementPicker,
   type AIChatComposerAction,
   type AIChatWindowProps,
@@ -19,7 +18,7 @@ import {
 } from "@/components/ui/table";
 import { AIChatProvider, useAIChatBase } from "../providers";
 import { Globe2, MousePointer2 } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useMemo, useState, type CSSProperties } from "react";
 import { ContainerShowcase, type ChatContainer } from "./container-showcase";
 import { InteractionShowcase } from "./interaction-showcase";
 import { AIConfigurationGate } from "./configuration-gate";
@@ -106,6 +105,46 @@ const propRows = [
   ],
 ];
 
+const surfacePropRows = [
+  [
+    "variant",
+    '"side-panel" | "dialog"',
+    "required",
+    "Changes only the outer presentation while keeping the same chat window mounted.",
+  ],
+  ["open", "boolean", "required", "Controls whether the surface is open."],
+  [
+    "onOpenChange",
+    "(open: boolean) => void",
+    "required",
+    "Receives close requests from Escape, the dialog backdrop, or surface actions.",
+  ],
+  [
+    "side",
+    '"left" | "right"',
+    '"right"',
+    "Chooses the side used by the side-panel variant.",
+  ],
+  [
+    "width",
+    "number | string",
+    "450",
+    "Sets the width used by the side-panel variant.",
+  ],
+  [
+    "closeOnEscape",
+    "boolean",
+    "true",
+    "Allows Escape to close the active surface.",
+  ],
+  [
+    "showCloseHandle",
+    "boolean",
+    "false",
+    "Shows an outside close handle for the side-panel variant.",
+  ],
+];
+
 export function AIChatPage() {
   return (
     <AIConfigurationGate>
@@ -118,8 +157,7 @@ export function AIChatPage() {
 
 function AIChatPageContent() {
   const [container, setContainer] = useState<ChatContainer>("embedded");
-  const [sidePanelOpen, setSidePanelOpen] = useState(false);
-  const [dialogOpen, setDialogOpen] = useState(false);
+  const [surfaceOpen, setSurfaceOpen] = useState(false);
   const [webSearch, setWebSearch] = useState(false);
   const { id: chatId, addWorkContext, focusComposer } = useAIChatBase();
   const { registeredCount, startPicking } = useAIPageElementPicker();
@@ -132,9 +170,7 @@ function AIChatPageContent() {
         icon: <MousePointer2 />,
         disabled: registeredCount === 0,
         onClick: () => {
-          if (dialogOpen) {
-            setDialogOpen(false);
-            setSidePanelOpen(true);
+          if (surfaceOpen && container === "dialog") {
             setContainer("side-panel");
           }
           startPicking({
@@ -159,10 +195,11 @@ function AIChatPageContent() {
     [
       addWorkContext,
       chatId,
-      dialogOpen,
+      container,
       focusComposer,
       registeredCount,
       startPicking,
+      surfaceOpen,
       webSearch,
     ]
   );
@@ -178,35 +215,16 @@ function AIChatPageContent() {
   );
 
   const closeSurface = () => {
-    setSidePanelOpen(false);
-    setDialogOpen(false);
+    setSurfaceOpen(false);
   };
 
-  const sidePanelWindowProps: AIChatWindowProps = {
+  const surfaceWindowProps: AIChatWindowProps = {
     ...windowProps,
     headerActions: (
       <ChatSurfaceActions
-        expanded={false}
+        expanded={container === "dialog"}
         onExpandedChange={(expanded) => {
-          if (!expanded) return;
-          setSidePanelOpen(false);
-          setDialogOpen(true);
-        }}
-        onClose={closeSurface}
-      />
-    ),
-  };
-
-  const dialogWindowProps: AIChatWindowProps = {
-    ...windowProps,
-    headerActions: (
-      <ChatSurfaceActions
-        expanded={true}
-        onExpandedChange={(nextExpanded) => {
-          if (nextExpanded) return;
-          setDialogOpen(false);
-          setSidePanelOpen(true);
-          setContainer("side-panel");
+          setContainer(expanded ? "dialog" : "side-panel");
         }}
         onClose={closeSurface}
       />
@@ -215,17 +233,21 @@ function AIChatPageContent() {
 
   const selectContainer = (nextContainer: ChatContainer) => {
     setContainer(nextContainer);
-    setSidePanelOpen(nextContainer === "side-panel");
-    setDialogOpen(nextContainer === "dialog");
+    setSurfaceOpen(
+      nextContainer === "side-panel" || nextContainer === "dialog"
+    );
   };
 
   return (
-    <ChatSidePanelLayout
-      open={sidePanelOpen}
-      onOpenChange={setSidePanelOpen}
-      width={450}
-      panel={<AIChatWindow {...sidePanelWindowProps} />}
-      showCloseHandle={false}
+    <div
+      data-open={surfaceOpen && container === "side-panel"}
+      data-side="right"
+      className="chat-side-panel-layout @container min-w-0"
+      style={
+        {
+          "--chat-side-panel-width": "450px",
+        } as CSSProperties
+      }
     >
       <div className="space-y-14 pb-12">
         <section className="flex flex-wrap items-start justify-between gap-5 border-b pb-8">
@@ -277,49 +299,69 @@ function AIChatPageContent() {
           <PromptGenerator />
         </section>
 
+        <section className="space-y-5">
+          <SectionTitle
+            eyebrow="Component API"
+            title="ChatSurface props"
+            description="Use variant as the single presentation switch. The child AIChatWindow remains the same React instance while the surface changes shape."
+          />
+          <PropsTable rows={surfacePropRows} />
+        </section>
+
         <section className="space-y-5">
           <SectionTitle
             eyebrow="Component API"
             title="AIChatWindow props"
             description="The core window stays reusable while business pages provide placement, composer actions, and tool-approval behavior."
           />
-          <Card className="gap-0 overflow-hidden py-0">
-            <Table>
-              <TableHeader>
-                <TableRow>
-                  <TableHead>Prop</TableHead>
-                  <TableHead>Type</TableHead>
-                  <TableHead>Default</TableHead>
-                  <TableHead>Description</TableHead>
-                </TableRow>
-              </TableHeader>
-              <TableBody>
-                {propRows.map(([name, type, defaultValue, description]) => (
-                  <TableRow key={name}>
-                    <TableCell className="font-mono text-xs font-medium">
-                      {name}
-                    </TableCell>
-                    <TableCell className="font-mono text-xs text-muted-foreground">
-                      {type}
-                    </TableCell>
-                    <TableCell className="font-mono text-xs text-muted-foreground">
-                      {defaultValue}
-                    </TableCell>
-                    <TableCell className="min-w-80 whitespace-normal text-muted-foreground">
-                      {description}
-                    </TableCell>
-                  </TableRow>
-                ))}
-              </TableBody>
-            </Table>
-          </Card>
+          <PropsTable rows={propRows} />
         </section>
 
-        <ChatDialog open={dialogOpen} onOpenChange={setDialogOpen}>
-          <AIChatWindow {...dialogWindowProps} />
-        </ChatDialog>
       </div>
-    </ChatSidePanelLayout>
+      <ChatSurface
+        open={surfaceOpen}
+        variant={container === "dialog" ? "dialog" : "side-panel"}
+        onOpenChange={setSurfaceOpen}
+        width={450}
+      >
+        <AIChatWindow {...surfaceWindowProps} />
+      </ChatSurface>
+    </div>
+  );
+}
+
+function PropsTable({ rows }: { rows: string[][] }) {
+  return (
+    <Card className="gap-0 overflow-hidden py-0">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Prop</TableHead>
+            <TableHead>Type</TableHead>
+            <TableHead>Default</TableHead>
+            <TableHead>Description</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map(([name, type, defaultValue, description]) => (
+            <TableRow key={name}>
+              <TableCell className="font-mono text-xs font-medium">
+                {name}
+              </TableCell>
+              <TableCell className="font-mono text-xs text-muted-foreground">
+                {type}
+              </TableCell>
+              <TableCell className="font-mono text-xs text-muted-foreground">
+                {defaultValue}
+              </TableCell>
+              <TableCell className="min-w-80 whitespace-normal text-muted-foreground">
+                {description}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </Card>
   );
 }
 

package/{registry → src/extensions}/nocobase-ai/demo/prompt-generator.tsx

@@ -141,9 +141,9 @@ function PromptGeneratorContent() {
       embedded:
         "Render ChatInline inside the target content region and keep its width fluid within the parent container.",
       page: "Create a dedicated route and render ChatPage with AIChatWindow filling the available page content.",
-      "side-panel": `Use ChatSidePanelLayout on the right with a ${panelWidth}px panel. Opening chat must push the page narrower instead of covering it on desktop; mobile may use an overlay.`,
+      "side-panel": `Use ChatSurface with variant="side-panel" on the right and a ${panelWidth}px width. Opening chat must push the page narrower instead of covering it on desktop; mobile may use an overlay.`,
       dialog:
-        "Open ChatDialog from a page action. Keep conversation state in AIProvider/AIChatProvider so closing the dialog does not discard it.",
+        "Open ChatSurface with variant=\"dialog\" from a page action. Keep conversation state in AIProvider/AIChatProvider so closing the dialog does not discard it.",
       mobile:
         "Render ChatInline in the target region with a mobile-first width around 390px and preserve the same responsive AIChatWindow API.",
     }[placement];
@@ -181,7 +181,7 @@ Implementation requirements:
 - Wrap the application content with AIPageElementProvider when page-element picking is enabled.
 - Register selectable React components with useAIPageElement and return serializable business context from getContext.
 - Reuse AIChatWindow and the existing providers; do not duplicate message, streaming, reasoning, or tool-call state.
-- When the right panel is expandable, keep one AIChatProvider mounted while switching between ChatSidePanel and ChatDialog. Put ChatSurfaceActions in the window header.
+- When the right panel is expandable, render one AIChatWindow inside ChatSurface and change only its variant between "side-panel" and "dialog". Put ChatSurfaceActions in the window header.
 - Keep the generic Tool Call shell responsible for status, ASK approval, errors, and disclosure. Register business-specific bodies through AIToolRendererProvider.
 - Include the built-in specialized Tool Card renderers. This is part of the standard AI chat capability, not an optional page setting.
 - Register browser-side tool implementations through AIProvider.toolInvokers. After all interrupted calls are approved, the provider executes these handlers and sends their results when resuming the NocoBase conversation.

package/{registry → src/extensions}/nocobase-ai/demo/tool-cards.tsx

@@ -402,9 +402,8 @@ Implementation requirements:
 - Export any public renderer types or components from registry/nocobase-ai/components/index.ts when application code needs them.
 
 Verification:
-- Run pnpm registry:preview.
-- Run pnpm exec tsc --noEmit.
-- Run the scoped ESLint check and pnpm registry:build.
+- Run pnpm build from the Registry source repository.
+- Run the relevant regression checks and a scoped ESLint check.
 - Verify the card in light and dark themes, narrow chat panels, expanded dialogs, pending approval, completed, and error states.`;
 
   return (

package/src/extensions/nocobase-ai/extension.tsx

@@ -0,0 +1,160 @@
+import { NocoBaseAIExtensionProvider } from "./global-ai-chat";
+import type { AppExtension } from "@/app/extensions";
+import { LoadingState } from "@/components/app-shell/loading-state";
+import {
+  Bot,
+  MessageSquare,
+  MousePointer2,
+  PanelRight,
+  Sparkles,
+  Wrench,
+} from "lucide-react";
+import { lazy, Suspense, type ReactNode } from "react";
+import { Outlet, Route } from "react-router";
+
+const AIChatPage = lazy(() =>
+  import("./demo").then((module) => ({ default: module.AIChatPage }))
+);
+const FloatingChatPage = lazy(() =>
+  import("./demo/floating").then((module) => ({
+    default: module.FloatingChatPage,
+  }))
+);
+const ShortcutPage = lazy(() =>
+  import("./demo/shortcut").then((module) => ({
+    default: module.ShortcutPage,
+  }))
+);
+const PageContextPage = lazy(() =>
+  import("./demo/page-context").then((module) => ({
+    default: module.PageContextPage,
+  }))
+);
+const ToolCardsPage = lazy(() =>
+  import("./demo/tool-cards").then((module) => ({
+    default: module.ToolCardsPage,
+  }))
+);
+
+function LazyDemoRoute({ children }: { children: ReactNode }) {
+  return (
+    <Suspense fallback={<LoadingState className="min-h-[320px]" />}>
+      {children}
+    </Suspense>
+  );
+}
+
+const nocobaseAIExtension: AppExtension = {
+  id: "nocobase-ai",
+  Provider: NocoBaseAIExtensionProvider,
+  dev: {
+    resources: [
+      {
+        name: "ai-components",
+        meta: {
+          label: "AI Components",
+          icon: <Bot />,
+          acl: { type: "authenticated" },
+        },
+      },
+      {
+        name: "ai-chat-window",
+        list: "ai-chat",
+        meta: {
+          parent: "ai-components",
+          label: "Chat window",
+          icon: <MessageSquare />,
+          description:
+            "Build freely with AI while NocoBase keeps the application reliable.",
+          acl: { type: "authenticated" },
+        },
+      },
+      {
+        name: "ai-floating-chat",
+        list: "ai-chat/floating",
+        meta: {
+          parent: "ai-components",
+          label: "Floating chat",
+          icon: <PanelRight />,
+          acl: { type: "authenticated" },
+        },
+      },
+      {
+        name: "ai-employee-tasks",
+        list: "ai-chat/shortcut",
+        meta: {
+          parent: "ai-components",
+          label: "Employee tasks",
+          icon: <Sparkles />,
+          acl: { type: "authenticated" },
+        },
+      },
+      {
+        name: "ai-page-context",
+        list: "ai-chat/context",
+        meta: {
+          parent: "ai-components",
+          label: "Page context",
+          icon: <MousePointer2 />,
+          acl: { type: "authenticated" },
+        },
+      },
+      {
+        name: "ai-tool-cards",
+        list: "ai-chat/tools",
+        meta: {
+          parent: "ai-components",
+          label: "Tool cards",
+          icon: <Wrench />,
+          acl: { type: "authenticated" },
+        },
+      },
+    ],
+    routes: (
+      <Route key="nocobase-ai" path="ai-chat" element={<Outlet />}>
+        <Route
+          index
+          element={
+            <LazyDemoRoute>
+              <AIChatPage />
+            </LazyDemoRoute>
+          }
+        />
+        <Route
+          path="floating"
+          element={
+            <LazyDemoRoute>
+              <FloatingChatPage />
+            </LazyDemoRoute>
+          }
+        />
+        <Route
+          path="shortcut"
+          element={
+            <LazyDemoRoute>
+              <ShortcutPage />
+            </LazyDemoRoute>
+          }
+        />
+        <Route
+          path="context"
+          element={
+            <LazyDemoRoute>
+              <PageContextPage />
+            </LazyDemoRoute>
+          }
+        />
+        <Route
+          path="tools"
+          element={
+            <LazyDemoRoute>
+              <ToolCardsPage />
+            </LazyDemoRoute>
+          }
+        />
+      </Route>
+    ),
+  },
+};
+
+export default nocobaseAIExtension;

package/{registry → src/extensions}/nocobase-ai/global-ai-chat.tsx

@@ -14,8 +14,7 @@ import {
   type AIChatComposerAction,
 } from "./components";
 import { AIChatWindow } from "./components/chat/chat-window";
-import { ChatDialog } from "./components/surfaces/chat-dialog";
-import { ChatSidePanel } from "./components/surfaces/chat-side-panel";
+import { ChatSurface } from "./components/surfaces/chat-surface";
 import { ChatSurfaceActions } from "./components/surfaces/chat-surface-actions";
 import {
   AIChatProvider,
@@ -51,8 +50,7 @@ function NocoBaseAIGlobalEntry({ children }: PropsWithChildren) {
   const [expanded, setExpanded] = useState(false);
   const ready =
     ai.configurationStatus === "ready" &&
-    ai.employees.length > 0 &&
-    ai.hasEnabledModels;
+    ai.employees.length > 0;
 
   return (
     <div
@@ -166,38 +164,24 @@ function StarterGlobalAIChat({
     setExpanded(false);
     onOpenChange(false);
   };
+  const handleSurfaceOpenChange = (nextOpen: boolean) => {
+    if (!nextOpen) setExpanded(false);
+    onOpenChange(nextOpen);
+  };
 
   return (
     <>
-      <ChatSidePanel
-        open={open && !expanded}
-        onOpenChange={onOpenChange}
+      <ChatSurface
+        open={open}
+        variant={expanded ? "dialog" : "side-panel"}
+        onOpenChange={handleSurfaceOpenChange}
         width={DEFAULT_SIDE_PANEL_WIDTH}
         showCloseHandle={false}
       >
         <AIChatWindow
           headerActions={
             <ChatSurfaceActions
-              expanded={false}
-              onExpandedChange={setExpanded}
-              onClose={closeChat}
-            />
-          }
-          composerActions={composerActions}
-          enableAttachments
-          attachmentActionIndex={1}
-        />
-      </ChatSidePanel>
-      <ChatDialog
-        open={open && expanded}
-        onOpenChange={(nextOpen) => {
-          if (!nextOpen) closeChat();
-        }}
-      >
-        <AIChatWindow
-          headerActions={
-            <ChatSurfaceActions
-              expanded
+              expanded={expanded}
               onExpandedChange={setExpanded}
               onClose={closeChat}
             />
@@ -206,7 +190,7 @@ function StarterGlobalAIChat({
           enableAttachments
           attachmentActionIndex={1}
         />
-      </ChatDialog>
+      </ChatSurface>
       <AIChatFloatingTrigger unreadCount={unreadCount} />
     </>
   );

package/{registry → src/extensions}/nocobase-ai/providers/ai-provider.tsx

@@ -125,7 +125,20 @@ function AIProviderRuntime({
     status: AIConfigurationStatus;
     error?: Error;
     modelError?: Error;
-  }>({ employees: [], models: [], status: "loading" });
+  }>(() =>
+    providedEmployees && providedModels
+      ? {
+          employees: providedEmployees,
+          models: providedModels.length
+            ? providedModels
+            : [UNCONFIGURED_MODEL],
+          status: "ready",
+          modelError: providedModels.length
+            ? undefined
+            : new Error("No enabled AI models were provided."),
+        }
+      : { employees: [], models: [], status: "loading" }
+  );
   const internalGlobalController = useAIChatController();
   const globalController = providedGlobalController ?? internalGlobalController;
 

package/{registry → src/extensions}/nocobase-ai/providers/chat-context.tsx

@@ -20,6 +20,7 @@ export type AIChatContextValue = {
   models: AIModel[];
   currentEmployee: AIEmployee;
   currentModel: AIModel;
+  canSend: boolean;
   activeConversation?: AIConversation;
   activeConversationId: string;
   conversations: AIConversation[];

package/{registry → src/extensions}/nocobase-ai/providers/chat-provider.tsx

@@ -52,14 +52,27 @@ import {
   type AIChatMessage,
   type AIChatTaskRuntime,
   type AIConversation,
+  type AIEmployee,
   type AIEmployeeTask,
   type AIEmployeeTasks,
   type AIEmployeeTaskTrigger,
+  type AIModel,
   type AIWorkContextItem,
 } from "./types";
 
 const EMPTY_TASKS: AIEmployeeTask[] = [];
 const EMPTY_EMPLOYEE_TASKS: AIEmployeeTasks = {};
+const UNAVAILABLE_EMPLOYEE: AIEmployee = {
+  username: "__unavailable__",
+  nickname: "AI employee",
+  position: "Not configured",
+  greeting: "Configure an AI employee and model to start chatting.",
+};
+const UNAVAILABLE_MODEL: AIModel = {
+  value: "__unavailable__",
+  label: "No enabled model",
+  configured: false,
+};
 
 export type AIChatProviderProps = PropsWithChildren<{
   id: string;
@@ -197,16 +210,19 @@ export function AIChatProvider({
     dispatch,
   });
 
-  const currentEmployee =
+  const configuredEmployee =
     ai.employees.find(
       (employee) => employee.username === state.selectedEmployeeUsername
     ) ?? ai.employees[0];
-  const currentModel =
+  const configuredModel =
     findAIModel(ai.models, state.selectedModel) ?? ai.models[0];
-
-  if (!currentEmployee || !currentModel) {
-    throw new Error("AIProvider requires at least one employee and model");
-  }
+  const currentEmployee = configuredEmployee ?? UNAVAILABLE_EMPLOYEE;
+  const currentModel = configuredModel ?? UNAVAILABLE_MODEL;
+  const canSend = Boolean(
+    configuredEmployee &&
+      configuredModel &&
+      configuredModel.configured !== false
+  );
 
   const getActiveConversationId = useCallback(
     () => stateRef.current.activeConversationId,
@@ -271,7 +287,7 @@ export function AIChatProvider({
       const conversation = currentState.conversations.find(
         (item) => item.id === currentId
       );
-      if (!employee || !model) return;
+      if (!employee || !model || model.configured === false) return;
       const currentAttachments = getConversationAttachments(currentId);
       const unresolvedWorkContext = getConversationWorkContext(currentId);
       if (
@@ -712,6 +728,7 @@ export function AIChatProvider({
       models: ai.models,
       currentEmployee,
       currentModel,
+      canSend,
       activeConversation,
       activeConversationId: state.activeConversationId,
       conversations: state.conversations,
@@ -797,7 +814,9 @@ export function AIChatProvider({
       startEditingMessage,
       cancelEditingMessage,
       saveUserPrompt: (prompt) =>
-        ai.updateEmployeeUserPrompt(currentEmployee.username, prompt),
+        configuredEmployee
+          ? ai.updateEmployeeUserPrompt(configuredEmployee.username, prompt)
+          : Promise.resolve(),
       triggerTask,
       runTask,
       focusComposer: requestComposerFocus,
@@ -818,6 +837,8 @@ export function AIChatProvider({
       editingMessageId,
       currentEmployee,
       currentModel,
+      canSend,
+      configuredEmployee,
       getConfiguredTaskSet,
       invalidateConversationHistory,
       invalidatePendingInteraction,

package/{registry → src/extensions}/nocobase-ai/providers/use-chat-attachments.ts

@@ -179,8 +179,13 @@ export function useChatAttachments(activeConversationId: string) {
       }),
     []
   );
+  // Falls back to the shared EMPTY_ATTACHMENTS rather than a fresh `[]`: callers compare the
+  // result by identity across an await to detect "the user changed the attachments mid-send", and
+  // a new array each call would make that check fire on every send from a conversation with no
+  // attachments.
   const getConversationAttachments = useCallback(
-    (conversationId: string) => draftsRef.current[conversationId] ?? [],
+    (conversationId: string) =>
+      draftsRef.current[conversationId] ?? EMPTY_ATTACHMENTS,
     []
   );
   const attachments = drafts[activeConversationId] ?? EMPTY_ATTACHMENTS;