@nextclaw/ui 0.12.35-beta.5 → 0.12.35-beta.7

package/src/shared/components/doc-browser/doc-browser-tab-strip.tsx

@@ -1,4 +1,5 @@
-import { Plus, X } from 'lucide-react';
+import type { PointerEvent } from 'react';
+import { ArrowLeft, ArrowRight, Maximize2, PanelRightOpen, Plus, X } from 'lucide-react';
 import type { DocBrowserTab } from './doc-browser-context';
 import { cn } from '@/shared/lib/utils';
 import { t } from '@/shared/lib/i18n';
@@ -6,62 +7,134 @@ import { t } from '@/shared/lib/i18n';
 type DocBrowserTabStripProps = {
   tabs: DocBrowserTab[];
   activeTabId: string;
-  onOpenDocs: () => void;
+  canGoBack: boolean;
+  canGoForward: boolean;
+  isDocked: boolean;
+  isFullscreen: boolean;
+  onGoBack: () => void;
+  onGoForward: () => void;
+  onOpenNewTab: () => void;
   onSetActiveTab: (tabId: string) => void;
   onCloseTab: (tabId: string) => void;
+  onClose: () => void;
+  onDragStart: (event: PointerEvent<HTMLElement>) => void;
+  onToggleMode: () => void;
 };
 
 export function DocBrowserTabStrip({
   tabs,
   activeTabId,
-  onOpenDocs,
+  canGoBack,
+  canGoForward,
+  isDocked,
+  isFullscreen,
+  onGoBack,
+  onGoForward,
+  onOpenNewTab,
   onSetActiveTab,
   onCloseTab,
+  onClose,
+  onDragStart,
+  onToggleMode,
 }: DocBrowserTabStripProps) {
   return (
-    <div className="flex items-center gap-1.5 px-2.5 py-2 bg-background border-b border-[#f1e7d4] overflow-x-auto custom-scrollbar">
-      {tabs.map((tab) => {
-        const isActive = tab.id === activeTabId;
-        return (
-          <div
-            key={tab.id}
-            className={cn(
-              'inline-flex items-center gap-1 h-7 px-1.5 rounded-lg text-xs border max-w-[220px] shrink-0 transition-colors',
-              isActive
-                ? 'bg-amber-50/80 border-amber-200 text-amber-900 shadow-[0_1px_2px_rgba(30,20,10,0.04)]'
-                : 'bg-[#f9f8f5] border-[#eee3d1] text-[#78644d] hover:bg-[#fff7ea] hover:text-[#2f2212]',
-            )}
-          >
-            <button
-              type="button"
-              onClick={() => onSetActiveTab(tab.id)}
-              className="truncate text-left px-1"
-              title={tab.title}
-            >
-              {tab.title || t('docBrowserTabUntitled')}
-            </button>
-            <button
-              type="button"
-              onClick={(event) => {
-                event.stopPropagation();
-                onCloseTab(tab.id);
-              }}
-              className="rounded p-0.5 hover:bg-black/10"
-              aria-label={t('docBrowserCloseTab')}
+    <div
+      data-testid="doc-browser-tab-strip"
+      className={cn(
+        'flex h-11 items-stretch gap-2 px-2.5 bg-background border-b border-[#f1e7d4] shrink-0 select-none',
+        isFullscreen && 'h-[calc(env(safe-area-inset-top,0px)+2.75rem)] pt-[env(safe-area-inset-top,0px)]',
+      )}
+      onPointerDown={!isDocked && !isFullscreen ? onDragStart : undefined}
+    >
+      <div
+        className="doc-browser-tab-scrollbar flex h-full min-w-0 flex-1 items-center gap-1.5 overflow-x-auto"
+        onPointerDown={(event) => event.stopPropagation()}
+      >
+        {tabs.map((tab) => {
+          const isActive = tab.id === activeTabId;
+          return (
+            <div
+              key={tab.id}
+              className={cn(
+                'inline-flex items-center gap-1 h-7 px-1.5 rounded-lg text-xs border max-w-[220px] shrink-0 transition-colors',
+                isActive
+                  ? 'bg-amber-50/80 border-amber-200 text-amber-900 shadow-[0_1px_2px_rgba(30,20,10,0.04)]'
+                  : 'bg-[#f9f8f5] border-[#eee3d1] text-[#78644d] hover:bg-[#fff7ea] hover:text-[#2f2212]',
+              )}
             >
-              <X className="w-3 h-3" />
-            </button>
-          </div>
-        );
-      })}
-      <button
-        type="button"
-        onClick={onOpenDocs}
-        className="inline-flex items-center justify-center w-7 h-7 rounded-lg border border-[#eee3d1] bg-white text-[#78644d] hover:bg-[#fff7ea] hover:text-[#2f2212] shrink-0"
-        title={t('docBrowserNewTab')}
+              <button
+                type="button"
+                onClick={() => onSetActiveTab(tab.id)}
+                className="truncate text-left px-1"
+                title={tab.title}
+              >
+                {tab.title || t('docBrowserTabUntitled')}
+              </button>
+              <button
+                type="button"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onCloseTab(tab.id);
+                }}
+                className="rounded p-0.5 hover:bg-black/10"
+                aria-label={t('docBrowserCloseTab')}
+              >
+                <X className="w-3 h-3" />
+              </button>
+            </div>
+          );
+        })}
+      </div>
+      <div
+        className="flex h-full items-center gap-1 shrink-0"
+        data-testid="doc-browser-tab-actions"
+        onPointerDown={(event) => event.stopPropagation()}
       >
-        <Plus className="w-3.5 h-3.5" />
-      </button>
+        <button
+          type="button"
+          onClick={onGoBack}
+          disabled={!canGoBack}
+          className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-700 disabled:cursor-not-allowed disabled:text-gray-300 disabled:opacity-60 disabled:hover:bg-transparent disabled:hover:text-gray-300"
+          title={t('docBrowserBack')}
+        >
+          <ArrowLeft className="w-3.5 h-3.5" />
+        </button>
+        <button
+          type="button"
+          onClick={onGoForward}
+          disabled={!canGoForward}
+          className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-700 disabled:cursor-not-allowed disabled:text-gray-300 disabled:opacity-60 disabled:hover:bg-transparent disabled:hover:text-gray-300"
+          title={t('docBrowserForward')}
+        >
+          <ArrowRight className="w-3.5 h-3.5" />
+        </button>
+        <button
+          type="button"
+          onClick={onOpenNewTab}
+          className="hover:bg-gray-100 rounded-md p-1.5 text-gray-500 hover:text-gray-700 transition-colors"
+          title={t('docBrowserNewTab')}
+        >
+          <Plus className="w-3.5 h-3.5" />
+        </button>
+        {!isFullscreen ? (
+          <button
+            type="button"
+            onClick={onToggleMode}
+            className="hover:bg-gray-100 rounded-md p-1.5 text-gray-500 hover:text-gray-700 transition-colors"
+            title={isDocked ? t('docBrowserFloatMode') : t('docBrowserDockMode')}
+          >
+            {isDocked ? <Maximize2 className="w-3.5 h-3.5" /> : <PanelRightOpen className="w-3.5 h-3.5" />}
+          </button>
+        ) : null}
+        <button
+          type="button"
+          onClick={onClose}
+          className="hover:bg-gray-100 rounded-md p-1.5 text-gray-500 hover:text-gray-700 transition-colors"
+          title={t('docBrowserClose')}
+        >
+          <X className="w-3.5 h-3.5" />
+        </button>
+      </div>
     </div>
   );
 }

package/src/shared/components/doc-browser/doc-browser.test.tsx

@@ -1,8 +1,18 @@
 import { fireEvent, render, screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { DocBrowser } from "@/shared/components/doc-browser/doc-browser";
+import type { DocBrowserContextValue, DocBrowserTab } from "@/shared/components/doc-browser/doc-browser-context";
 
-const { docBrowserState } = vi.hoisted(() => ({
+const { navigateMock } = vi.hoisted(() => ({
+  navigateMock: vi.fn(),
+}));
+
+vi.mock("react-router-dom", async () => ({
+  ...(await vi.importActual("react-router-dom") as object),
+  useNavigate: () => navigateMock,
+}));
+
+const { docBrowserState } = vi.hoisted<{ docBrowserState: DocBrowserContextValue }>(() => ({
   docBrowserState: {
     isOpen: true,
     mode: "docked" as "docked" | "floating",
@@ -18,6 +28,12 @@ const { docBrowserState } = vi.hoisted(() => ({
       },
     ],
     activeTabId: "docs",
+    activeHistory: [{
+      kind: "docs" as const,
+      tabId: "docs",
+      url: "https://docs.nextclaw.io/en/guide/getting-started",
+    }],
+    activeHistoryIndex: 0,
     currentTab: {
       id: "docs",
       kind: "docs" as const,
@@ -27,6 +43,8 @@ const { docBrowserState } = vi.hoisted(() => ({
       historyIndex: 0,
       navVersion: 0,
     },
+    open: vi.fn(),
+    openNewTab: vi.fn(),
     close: vi.fn(),
     toggleMode: vi.fn(),
     goBack: vi.fn(),
@@ -65,7 +83,27 @@ function firePointerEvent(
 
 describe("DocBrowser", () => {
   beforeEach(() => {
+    vi.clearAllMocks();
     docBrowserState.mode = "docked";
+    docBrowserState.tabs = [
+      {
+        id: "docs",
+        kind: "docs" as const,
+        title: "Docs",
+        currentUrl: "https://docs.nextclaw.io/en/guide/getting-started",
+        history: ["https://docs.nextclaw.io/en/guide/getting-started"],
+        historyIndex: 0,
+        navVersion: 0,
+      },
+    ];
+    docBrowserState.activeTabId = "docs";
+    docBrowserState.activeHistory = [{
+      kind: "docs" as const,
+      tabId: "docs",
+      url: "https://docs.nextclaw.io/en/guide/getting-started",
+    }];
+    docBrowserState.activeHistoryIndex = 0;
+    docBrowserState.currentTab = docBrowserState.tabs[0];
     Object.defineProperty(window, "innerWidth", {
       configurable: true,
       value: 1200,
@@ -99,6 +137,126 @@ describe("DocBrowser", () => {
     expect(panel.querySelector(".cursor-se-resize")).toBeNull();
   });
 
+  it("keeps browser window controls on the tab strip", () => {
+    render(<DocBrowser />);
+
+    const tabStrip = screen.getByTestId("doc-browser-tab-strip");
+    const tabActions = screen.getByTestId("doc-browser-tab-actions");
+
+    expect(tabActions.contains(screen.getByTitle("Back"))).toBe(true);
+    expect(tabActions.contains(screen.getByTitle("Forward"))).toBe(true);
+    expect(tabStrip.contains(screen.getByTitle("Float Window"))).toBe(true);
+    expect(tabStrip.contains(screen.getByTitle("Close"))).toBe(true);
+    expect(tabActions.contains(screen.getByTitle("New Tab"))).toBe(true);
+    expect(screen.queryByText("Embedded Browser")).toBeNull();
+  });
+
+  it("uses active history to enable browser back and forward actions", () => {
+    const history = [
+      "https://docs.nextclaw.io/en/guide/getting-started",
+      "https://docs.nextclaw.io/en/guide/channels",
+      "https://docs.nextclaw.io/en/guide/apps",
+    ];
+    const historyTab: DocBrowserTab = {
+      id: "docs",
+      kind: "docs",
+      title: "Docs",
+      currentUrl: history[1],
+      history,
+      historyIndex: 1,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [historyTab];
+    docBrowserState.activeTabId = historyTab.id;
+    docBrowserState.activeHistory = [
+      { kind: "home" as const, tabId: "home", url: "nextclaw://new-tab" },
+      { kind: "docs" as const, tabId: historyTab.id, url: history[1] },
+      { kind: "apps" as const, tabId: "apps", url: "nextclaw://apps" },
+    ];
+    docBrowserState.activeHistoryIndex = 1;
+    docBrowserState.currentTab = historyTab;
+
+    render(<DocBrowser />);
+
+    fireEvent.click(screen.getByTitle("Back"));
+    fireEvent.click(screen.getByTitle("Forward"));
+
+    expect(docBrowserState.goBack).toHaveBeenCalled();
+    expect(docBrowserState.goForward).toHaveBeenCalled();
+  });
+
+  it("disables browser history actions at the active history edges", () => {
+    const history = [
+      "https://docs.nextclaw.io/en/guide/getting-started",
+      "https://docs.nextclaw.io/en/guide/apps",
+    ];
+    const latestTab: DocBrowserTab = {
+      id: "docs",
+      kind: "docs",
+      title: "Docs",
+      currentUrl: history[1],
+      history,
+      historyIndex: 1,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [latestTab];
+    docBrowserState.activeTabId = latestTab.id;
+    docBrowserState.activeHistory = [
+      { kind: "docs" as const, tabId: latestTab.id, url: history[0] },
+      { kind: "docs" as const, tabId: latestTab.id, url: history[1] },
+    ];
+    docBrowserState.activeHistoryIndex = 1;
+    docBrowserState.currentTab = latestTab;
+
+    const { rerender } = render(<DocBrowser />);
+
+    expect(screen.getByTitle("Back")).toHaveProperty("disabled", false);
+    expect(screen.getByTitle("Forward")).toHaveProperty("disabled", true);
+
+    const oldestTab: DocBrowserTab = {
+      ...latestTab,
+      currentUrl: history[0],
+      historyIndex: 0,
+    };
+    docBrowserState.tabs = [oldestTab];
+    docBrowserState.currentTab = oldestTab;
+    docBrowserState.activeHistoryIndex = 0;
+    rerender(<DocBrowser />);
+
+    expect(screen.getByTitle("Back")).toHaveProperty("disabled", true);
+    expect(screen.getByTitle("Forward")).toHaveProperty("disabled", false);
+  });
+
+  it("opens the start page from the fixed new tab action", () => {
+    render(<DocBrowser />);
+
+    fireEvent.click(screen.getByTitle("New Tab"));
+
+    expect(docBrowserState.openNewTab).toHaveBeenCalled();
+  });
+
+  it("renders a start page for home tabs", () => {
+    const homeTab: DocBrowserTab = {
+      id: "home",
+      kind: "home" as const,
+      title: "Start Page",
+      currentUrl: "nextclaw://new-tab",
+      history: ["nextclaw://new-tab"],
+      historyIndex: 0,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [homeTab];
+    docBrowserState.activeTabId = homeTab.id;
+    docBrowserState.currentTab = homeTab;
+
+    render(<DocBrowser />);
+
+    expect(screen.getAllByText("Start Page").length).toBeGreaterThan(0);
+    expect(screen.getByText("Apps")).toBeTruthy();
+    expect(screen.getByText("Service Apps")).toBeTruthy();
+    expect(screen.getByText("Help Docs")).toBeTruthy();
+  });
+
   it("keeps the floating panel left edge stable when resizing from the right", () => {
     docBrowserState.mode = "floating";
 

package/src/shared/components/doc-browser/doc-browser.tsx

@@ -1,14 +1,16 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import {
   DOCS_DEFAULT_BASE_URL,
+  DOC_BROWSER_HOME_TAB_KIND,
   useDocBrowser,
 } from './doc-browser-context';
+import { normalizeDocUrl } from './utils/doc-browser-url.utils';
+import { DocBrowserHomePage } from './doc-browser-home-page';
 import type { DocBrowserCustomTabRenderers } from './doc-browser-renderer.types';
 import {
   DocBrowserDocsToolbar,
   DocBrowserExternalLink,
   DocBrowserFrameContent,
-  DocBrowserPanelHeader,
 } from './doc-browser-panel-parts';
 import { DocBrowserTabStrip } from './doc-browser-tab-strip';
 import { ResizableRightPanel } from '@/shared/components/resizable-right-panel/resizable-right-panel';
@@ -38,6 +40,15 @@ function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value));
 }
 
+function createInitialFloatingPanelRect(): FloatingPanelRect {
+  return {
+    x: Math.max(FLOATING_PANEL_MARGIN, window.innerWidth - 520),
+    y: 80,
+    w: 480,
+    h: 600,
+  };
+}
+
 export function DocBrowser({
   customTabRenderers = {},
   displayMode = 'desktop',
@@ -47,8 +58,11 @@ export function DocBrowser({
     mode,
     tabs,
     activeTabId,
+    activeHistory,
+    activeHistoryIndex,
     currentTab,
     open,
+    openNewTab,
     close,
     toggleMode,
     goBack,
@@ -61,18 +75,17 @@ export function DocBrowser({
 
   const [urlInput, setUrlInput] = useState('');
   const [iframeReloadVersion, setIframeReloadVersion] = useState(0);
-  const [floatRect, setFloatRect] = useState<FloatingPanelRect>(() => ({
-    x: Math.max(FLOATING_PANEL_MARGIN, window.innerWidth - 520),
-    y: 80,
-    w: 480,
-    h: 600,
-  }));
+  const [floatRect, setFloatRect] = useState<FloatingPanelRect>(createInitialFloatingPanelRect);
   const [floatInteraction, setFloatInteraction] = useState<FloatingPanelInteraction | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const currentUrl = currentTab?.currentUrl ?? DOCS_DEFAULT_BASE_URL;
   const navVersion = currentTab?.navVersion ?? 0;
+  const pendingParentDocsUrlRef = useRef<string | null>(null);
   const prevNavVersionRef = useRef(navVersion);
   const isDocsTab = currentTab?.kind === 'docs';
+  const isHomeTab = currentTab?.kind === DOC_BROWSER_HOME_TAB_KIND;
+  const canGoBack = activeHistoryIndex > 0;
+  const canGoForward = activeHistoryIndex < activeHistory.length - 1;
   const customRenderer = currentTab ? customTabRenderers[currentTab.kind] : undefined;
 
   useEffect(() => {
@@ -92,16 +105,19 @@ export function DocBrowser({
   // use postMessage to SPA-navigate inside the iframe instead of remounting.
   useEffect(() => {
     if (!isDocsTab) {
+      pendingParentDocsUrlRef.current = null;
       return;
     }
     if (navVersion !== prevNavVersionRef.current) {
       prevNavVersionRef.current = navVersion;
+      pendingParentDocsUrlRef.current = normalizeDocUrl(currentUrl);
       return;
     }
 
     if (iframeRef.current?.contentWindow) {
       try {
         const path = new URL(currentUrl).pathname;
+        pendingParentDocsUrlRef.current = normalizeDocUrl(currentUrl);
         iframeRef.current.contentWindow.postMessage({ type: 'docs-navigate', path }, '*');
       } catch {
         // ignore postMessage errors
@@ -115,12 +131,17 @@ export function DocBrowser({
         return;
       }
       if (e.data?.type === 'docs-route-change' && typeof e.data.url === 'string') {
+        const eventUrl = normalizeDocUrl(e.data.url);
+        if (pendingParentDocsUrlRef.current && eventUrl !== pendingParentDocsUrlRef.current) {
+          return;
+        }
+        pendingParentDocsUrlRef.current = null;
         syncUrl(e.data.url);
       }
     };
     window.addEventListener('message', handler);
     return () => window.removeEventListener('message', handler);
-  }, [syncUrl, isDocsTab]);
+  }, [currentUrl, syncUrl, isDocsTab]);
 
   useEffect(() => {
     if (!currentTab || !customRenderer?.onIframeMessage) {
@@ -236,36 +257,34 @@ export function DocBrowser({
     tab: currentTab,
   } : undefined;
   const customToolbar = customRenderParams ? customRenderer?.renderToolbar?.(customRenderParams) : null;
-  const customContent = customRenderParams ? customRenderer?.renderContent?.(customRenderParams) : null;
+  const customContent = customRenderParams
+    ? customRenderer?.renderContent?.(customRenderParams) ?? (isHomeTab ? <DocBrowserHomePage open={open} /> : null)
+    : null;
   const iframeSandbox = currentTab
     ? customRenderer?.getIframeSandbox?.(currentTab) ?? 'allow-same-origin allow-scripts allow-popups allow-forms'
     : 'allow-same-origin allow-scripts allow-popups allow-forms';
 
   const panelContent = (
     <>
-      <DocBrowserPanelHeader
-        currentTab={currentTab}
-        customRenderer={customRenderer}
-        isDocked={isDocked}
-        isFullscreen={isFullscreen}
-        onClose={close}
-        onDragStart={startFloatDrag}
-        onToggleMode={toggleMode}
-      />
-
       <DocBrowserTabStrip
         tabs={tabs}
         activeTabId={activeTabId}
-        onOpenDocs={() => open(undefined, { kind: 'docs', newTab: true, title: 'Docs' })}
+        canGoBack={canGoBack}
+        canGoForward={canGoForward}
+        isDocked={isDocked}
+        isFullscreen={isFullscreen}
+        onGoBack={goBack}
+        onGoForward={goForward}
+        onOpenNewTab={openNewTab}
         onSetActiveTab={setActiveTab}
         onCloseTab={closeTab}
+        onClose={close}
+        onDragStart={startFloatDrag}
+        onToggleMode={toggleMode}
       />
 
       <DocBrowserDocsToolbar
-        currentTab={currentTab}
         isDocsTab={isDocsTab}
-        onBack={goBack}
-        onForward={goForward}
         onSubmit={handleUrlSubmit}
         onUrlInputChange={setUrlInput}
         urlInput={urlInput}