@nextclaw/ui 0.15.22 → 0.15.23

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

@@ -8,6 +8,7 @@ import type {
   DocBrowserTab,
 } from "@/shared/components/doc-browser/doc-browser-context";
 import { PANEL_APPS_DOC_BROWSER_RENDERERS } from "@/features/panel-apps";
+import { PANEL_APP_SCROLL_RESTORATION_CONTRACT } from "@nextclaw/shared";
 
 const { navigateMock } = vi.hoisted(() => ({
   navigateMock: vi.fn(),
@@ -460,7 +461,72 @@ describe("DocBrowser", () => {
 
     expect(screen.getByTitle("Local App").getAttribute("tabindex")).toBeNull();
   });
+});
 
+describe("DocBrowser scroll restoration", () => {
+  beforeEach(() => {
+    resetDocBrowserTestState();
+    installDocBrowserPointerTestEnvironment();
+  });
+
+  it("restores the active Panel App scroll surface after refresh", () => {
+    const panelAppTab: DocBrowserTab = {
+      id: "piano",
+      kind: "panel-app" as const,
+      title: "Piano",
+      currentUrl: "/api/panel-apps/piano/content",
+      history: ["/api/panel-apps/piano/content"],
+      historyIndex: 0,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [panelAppTab];
+    docBrowserState.activeTabId = panelAppTab.id;
+    docBrowserState.currentTab = panelAppTab;
+
+    const { container } = render(<DocBrowser customTabRenderers={PANEL_APPS_DOC_BROWSER_RENDERERS} />);
+
+    const initialIframe = container.querySelector('iframe[title="Piano"]') as HTMLIFrameElement;
+    const initialWindow = {} as Window;
+    Object.defineProperty(initialIframe, "contentWindow", {
+      configurable: true,
+      value: initialWindow,
+    });
+    window.dispatchEvent(new MessageEvent("message", {
+      data: {
+        type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType,
+        version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+        target: {
+          kind: "element",
+          path: [{ index: 0, tagName: "main" }],
+        },
+        x: 24,
+        y: 360,
+      },
+      source: initialWindow,
+    }));
+
+    fireEvent.click(screen.getByRole("button", { name: "Refresh current panel app" }));
+
+    const refreshedIframe = container.querySelector('iframe[title="Piano"]') as HTMLIFrameElement;
+    const refreshedPostMessage = vi.fn();
+    Object.defineProperty(refreshedIframe, "contentWindow", {
+      configurable: true,
+      value: { postMessage: refreshedPostMessage },
+    });
+    fireEvent.load(refreshedIframe);
+
+    expect(refreshedIframe).not.toBe(initialIframe);
+    expect(refreshedPostMessage).toHaveBeenCalledWith({
+      type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.restoreScrollMessageType,
+      version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+      target: {
+        kind: "element",
+        path: [{ index: 0, tagName: "main" }],
+      },
+      x: 24,
+      y: 360,
+    }, "*");
+  });
 });
 
 describe("DocBrowser floating interactions", () => {

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

@@ -1,4 +1,4 @@
-import type { PointerEventHandler, ReactNode, Ref } from 'react';
+import type { PointerEventHandler, ReactNode, Ref, ReactEventHandler } from 'react';
 import {
   RefreshCw,
   Search,
@@ -30,6 +30,7 @@ type DocBrowserFrameContentProps = {
   iframeSandbox?: string;
   isDragging: boolean;
   isResizing: boolean;
+  onIframeLoad?: ReactEventHandler<HTMLIFrameElement>;
   onIframePointerOver?: PointerEventHandler<HTMLIFrameElement>;
 };
 
@@ -76,6 +77,7 @@ export function DocBrowserFrameContent({
   iframeSandbox,
   isDragging,
   isResizing,
+  onIframeLoad,
   onIframePointerOver,
 }: DocBrowserFrameContentProps) {
   return (
@@ -92,6 +94,7 @@ export function DocBrowserFrameContent({
           title={currentTab?.title || 'NextClaw Docs'}
           sandbox={iframeSandbox}
           tabIndex={onIframePointerOver ? 0 : undefined}
+          onLoad={onIframeLoad}
           onPointerOver={onIframePointerOver}
           allow="clipboard-read; clipboard-write"
           allowFullScreen

package/src/shared/components/doc-browser/doc-browser-renderer.types.ts

@@ -24,6 +24,7 @@ export type DocBrowserCustomTabRenderer = {
   renderContent?: (params: DocBrowserCustomTabRenderParams) => ReactNode;
   renderIcon?: (tab: DocBrowserTab) => ReactNode;
   renderToolbar?: (params: DocBrowserCustomTabRenderParams) => ReactNode;
+  supportsScrollRestoration?: boolean;
 };
 
 export type DocBrowserCustomTabRenderers = Record<string, DocBrowserCustomTabRenderer>;

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

@@ -10,6 +10,7 @@ import {
 } from './doc-browser-context';
 import { normalizeDocUrl } from './utils/doc-browser-url.utils';
 import { DocBrowserHomePage } from './doc-browser-home-page';
+import { useDocBrowserScrollRestoration } from './hooks/use-doc-browser-scroll-restoration';
 import type { DocBrowserCustomTabRenderers } from './doc-browser-renderer.types';
 import {
   DocBrowserAddressToolbar,
@@ -200,6 +201,13 @@ export function DocBrowser({ customTabRenderers = {}, displayMode = 'desktop', d
   const dockState = dockControls?.getDockState(currentTab);
   const isContentTab = currentTab?.kind === 'content';
   const isAddressToolbarTab = isDocsTab || isContentTab;
+  const supportsScrollRestoration = customRenderer?.supportsScrollRestoration === true;
+  const restoreScroll = useDocBrowserScrollRestoration({
+    currentTab,
+    iframeRef,
+    isEnabled: supportsScrollRestoration,
+    tabs,
+  });
   const { handleUrlSubmit, setUrlInput, urlInput } = useDocBrowserAddressBar({
     activeTabId,
     currentUrl,
@@ -381,6 +389,7 @@ export function DocBrowser({ customTabRenderers = {}, displayMode = 'desktop', d
         iframeSandbox={iframeSandbox}
         isDragging={floatInteraction?.kind === 'drag'}
         isResizing={floatInteraction?.kind === 'resize'}
+        onIframeLoad={restoreScroll}
         onIframePointerOver={customRenderer?.onIframePointerOver}
       />
 

package/src/shared/components/doc-browser/hooks/use-doc-browser-scroll-restoration.ts

@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useRef, type RefObject } from 'react';
+import { PANEL_APP_SCROLL_RESTORATION_CONTRACT } from '@nextclaw/shared';
+import type { DocBrowserTab } from '@/shared/components/doc-browser/doc-browser-context';
+
+type ScrollTarget =
+  | { kind: 'document' }
+  | { kind: 'element'; path: Array<{ index: number; tagName: string }> };
+
+type ScrollPosition = {
+  currentUrl: string;
+  target: ScrollTarget;
+  x: number;
+  y: number;
+};
+
+type UseDocBrowserScrollRestorationParams = {
+  currentTab?: DocBrowserTab;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  isEnabled: boolean;
+  tabs: DocBrowserTab[];
+};
+
+function isScrollTarget(value: unknown): value is ScrollTarget {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const candidate = value as Partial<ScrollTarget>;
+  if (candidate.kind === 'document') {
+    return true;
+  }
+  return candidate.kind === 'element'
+    && Array.isArray(candidate.path)
+    && candidate.path.length > 0
+    && candidate.path.length <= 30
+    && candidate.path.every((segment) => (
+      typeof segment?.index === 'number'
+      && Number.isInteger(segment.index)
+      && segment.index >= 0
+      && segment.index <= 1000
+      && typeof segment.tagName === 'string'
+      && segment.tagName.length > 0
+      && segment.tagName.length <= 32
+    ));
+}
+
+function isScrollMessage(value: unknown): value is {
+  target: ScrollTarget;
+  type: string;
+  version: number;
+  x: number;
+  y: number;
+} {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const candidate = value as Partial<{
+    target: unknown;
+    type: string;
+    version: number;
+    x: number;
+    y: number;
+  }>;
+  return candidate.type === PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType
+    && candidate.version === PANEL_APP_SCROLL_RESTORATION_CONTRACT.version
+    && isScrollTarget(candidate.target)
+    && typeof candidate.x === 'number'
+    && Number.isFinite(candidate.x)
+    && candidate.x >= 0
+    && typeof candidate.y === 'number'
+    && Number.isFinite(candidate.y)
+    && candidate.y >= 0;
+}
+
+export function useDocBrowserScrollRestoration({
+  currentTab,
+  iframeRef,
+  isEnabled,
+  tabs,
+}: UseDocBrowserScrollRestorationParams) {
+  const positionsRef = useRef(new Map<string, ScrollPosition>());
+
+  useEffect(() => {
+    const activeTabIds = new Set(tabs.map((tab) => tab.id));
+    for (const tabId of positionsRef.current.keys()) {
+      if (!activeTabIds.has(tabId)) {
+        positionsRef.current.delete(tabId);
+      }
+    }
+  }, [tabs]);
+
+  useEffect(() => {
+    if (!currentTab || !isEnabled) {
+      return;
+    }
+    const onMessage = (event: MessageEvent) => {
+      if (event.source !== iframeRef.current?.contentWindow || !isScrollMessage(event.data)) {
+        return;
+      }
+      positionsRef.current.set(currentTab.id, {
+        currentUrl: currentTab.currentUrl,
+        target: event.data.target,
+        x: event.data.x,
+        y: event.data.y,
+      });
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [currentTab, iframeRef, isEnabled]);
+
+  return useCallback(() => {
+    if (!currentTab || !isEnabled) {
+      return;
+    }
+    const position = positionsRef.current.get(currentTab.id);
+    if (!position || position.currentUrl !== currentTab.currentUrl) {
+      return;
+    }
+    iframeRef.current?.contentWindow?.postMessage({
+      type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.restoreScrollMessageType,
+      version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+      target: position.target,
+      x: position.x,
+      y: position.y,
+    }, '*');
+  }, [currentTab, iframeRef, isEnabled]);
+}

package/src/shared/components/settings/settings-page.tsx

@@ -27,7 +27,7 @@ export function SettingsPage({
         className
       )}
     >
-      <PageHeader title={title} description={description} actions={actions} className='mb-0' />
+      <PageHeader title={title} description={description} actions={actions} />
       {children}
     </PageLayout>
   );

package/src/shared/components/ui/context-menu/__tests__/context-menu.test.tsx

@@ -0,0 +1,103 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+  ContextMenu,
+  ContextMenuTrigger,
+} from "@/shared/components/ui/context-menu/context-menu";
+
+describe("ContextMenu", () => {
+  it("opens at the trigger and supports keyboard selection", async () => {
+    const onSelect = vi.fn();
+    render(
+      <ContextMenu
+        label="File actions"
+        groups={[
+          {
+            key: "file",
+            items: [
+              { key: "open", label: "Open", onSelect: vi.fn() },
+              { key: "copy", label: "Copy path", onSelect },
+            ],
+          },
+        ]}
+      >
+        <button type="button">README.md</button>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByRole("button", { name: "README.md" }), {
+      clientX: 120,
+      clientY: 80,
+    });
+
+    expect(screen.getByRole("menu", { name: "File actions" })).toBeTruthy();
+    expect(document.activeElement).toBe(
+      screen.getByRole("menuitem", { name: "Open" }),
+    );
+    await userEvent.keyboard("{ArrowDown}{Enter}");
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("menu")).toBeNull();
+  });
+
+  it("opens the same menu from an explicit trigger", async () => {
+    const onSelect = vi.fn();
+    render(
+      <ContextMenu
+        label="File actions"
+        groups={[
+          {
+            key: "file",
+            items: [{ key: "add", label: "Add to chat", onSelect }],
+          },
+        ]}
+      >
+        <div>
+          <span>README.md</span>
+          <ContextMenuTrigger>
+            <button type="button" aria-label="More actions" />
+          </ContextMenuTrigger>
+        </div>
+      </ContextMenu>,
+    );
+
+    await userEvent.click(screen.getByRole("button", { name: "More actions" }));
+    expect(screen.getByRole("menu", { name: "File actions" })).toBeTruthy();
+    await userEvent.click(screen.getByRole("menuitem", { name: "Add to chat" }));
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not steal focus back when an action focuses the composer", async () => {
+    render(
+      <div>
+        <button type="button" data-testid="composer">Composer</button>
+        <ContextMenu
+          label="File actions"
+          groups={[
+            {
+              key: "chat",
+              items: [
+                {
+                  key: "add",
+                  label: "Add to chat",
+                  restoreFocus: false,
+                  onSelect: () => screen.getByTestId("composer").focus(),
+                },
+              ],
+            },
+          ]}
+        >
+          <button type="button">README.md</button>
+        </ContextMenu>
+      </div>,
+    );
+
+    fireEvent.contextMenu(screen.getByRole("button", { name: "README.md" }));
+    await userEvent.click(screen.getByRole("menuitem", { name: "Add to chat" }));
+
+    await waitFor(() => {
+      expect(document.activeElement).toBe(screen.getByTestId("composer"));
+    });
+  });
+});

package/src/shared/components/ui/context-menu/context-menu.tsx

@@ -0,0 +1,263 @@
+import {
+  cloneElement,
+  createContext,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { cn } from "@/shared/lib/utils";
+
+export type ContextMenuItem = {
+  key: string;
+  label: string;
+  icon?: ReactNode;
+  disabled?: boolean;
+  restoreFocus?: boolean;
+  onSelect: () => void;
+};
+
+export type ContextMenuGroup = {
+  key: string;
+  items: readonly ContextMenuItem[];
+};
+
+type ContextMenuPosition = {
+  align: "start" | "end";
+  x: number;
+  y: number;
+  trigger: HTMLElement;
+};
+
+type ContextMenuController = {
+  isOpen: boolean;
+  toggleFromButton: (trigger: HTMLElement) => void;
+};
+
+const ContextMenuControllerContext = createContext<ContextMenuController | null>(null);
+
+const CONTEXT_MENU_EDGE_GAP = 8;
+
+function ContextMenuSurface({
+  groups,
+  label,
+  onClose,
+  position,
+}: {
+  groups: readonly ContextMenuGroup[];
+  label: string;
+  onClose: (restoreFocus: boolean) => void;
+  position: ContextMenuPosition;
+}) {
+  const menuRef = useRef<HTMLDivElement | null>(null);
+
+  useLayoutEffect(() => {
+    const menu = menuRef.current;
+    if (!menu) {
+      return;
+    }
+    const rect = menu.getBoundingClientRect();
+    const preferredLeft = position.align === "end"
+      ? position.x - rect.width
+      : position.x;
+    const left = Math.max(
+      CONTEXT_MENU_EDGE_GAP,
+      Math.min(preferredLeft, window.innerWidth - rect.width - CONTEXT_MENU_EDGE_GAP),
+    );
+    const top = Math.max(
+      CONTEXT_MENU_EDGE_GAP,
+      Math.min(position.y, window.innerHeight - rect.height - CONTEXT_MENU_EDGE_GAP),
+    );
+    menu.style.left = `${left}px`;
+    menu.style.top = `${top}px`;
+    menu.querySelector<HTMLButtonElement>('[role="menuitem"]:not(:disabled)')?.focus();
+  }, [position]);
+
+  const moveFocus = (direction: 1 | -1) => {
+    const items = Array.from(
+      menuRef.current?.querySelectorAll<HTMLButtonElement>(
+        '[role="menuitem"]:not(:disabled)',
+      ) ?? [],
+    );
+    if (items.length === 0) {
+      return;
+    }
+    const currentIndex = items.indexOf(document.activeElement as HTMLButtonElement);
+    const nextIndex = currentIndex < 0
+      ? 0
+      : (currentIndex + direction + items.length) % items.length;
+    items[nextIndex]?.focus();
+  };
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[var(--z-tooltip)]"
+      onContextMenu={(event) => event.preventDefault()}
+      onPointerDown={() => onClose(true)}
+    >
+      <div
+        ref={menuRef}
+        role="menu"
+        aria-label={label}
+        className="fixed min-w-52 max-w-72 overflow-hidden rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-[0_18px_48px_-20px_rgba(15,23,42,0.42)]"
+        style={{ left: position.x, top: position.y }}
+        onPointerDown={(event) => event.stopPropagation()}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onClose(true);
+          } else if (event.key === "ArrowDown") {
+            event.preventDefault();
+            moveFocus(1);
+          } else if (event.key === "ArrowUp") {
+            event.preventDefault();
+            moveFocus(-1);
+          } else if (event.key === "Home" || event.key === "End") {
+            event.preventDefault();
+            const items = menuRef.current?.querySelectorAll<HTMLButtonElement>(
+              '[role="menuitem"]:not(:disabled)',
+            );
+            items?.[event.key === "Home" ? 0 : items.length - 1]?.focus();
+          }
+        }}
+      >
+        {groups.map((group, groupIndex) => (
+          <div key={group.key} role="group">
+            {groupIndex > 0 ? <div className="my-1 h-px bg-border" /> : null}
+            {group.items.map((item) => (
+              <button
+                key={item.key}
+                type="button"
+                role="menuitem"
+                disabled={item.disabled}
+                className={cn(
+                  "flex h-8 w-full items-center gap-2 rounded-lg px-2.5 text-left text-[13px] font-medium text-foreground outline-none transition-colors",
+                  "hover:bg-muted focus-visible:bg-muted disabled:pointer-events-none disabled:opacity-45",
+                )}
+                onClick={() => {
+                  item.onSelect();
+                  onClose(item.restoreFocus !== false);
+                }}
+              >
+                {item.icon ? (
+                  <span className="inline-flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+                    {item.icon}
+                  </span>
+                ) : null}
+                <span className="min-w-0 flex-1 truncate">{item.label}</span>
+              </button>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+export function ContextMenu({
+  children,
+  groups,
+  label,
+}: {
+  children: ReactElement<{
+    "data-context-menu-open"?: string;
+    onContextMenu?: (event: MouseEvent) => void;
+  }>;
+  groups: readonly ContextMenuGroup[];
+  label: string;
+}) {
+  const [position, setPosition] = useState<ContextMenuPosition | null>(null);
+  const visibleGroups = groups.filter((group) => group.items.length > 0);
+  const closeMenu = (restoreFocus: boolean) => {
+    const trigger = position?.trigger;
+    setPosition(null);
+    if (restoreFocus && trigger) {
+      window.setTimeout(() => trigger.isConnected && trigger.focus(), 0);
+    }
+  };
+
+  const toggleFromButton = (trigger: HTMLElement) => {
+    if (position?.trigger === trigger) {
+      closeMenu(true);
+      return;
+    }
+    if (visibleGroups.length === 0) {
+      return;
+    }
+    const bounds = trigger.getBoundingClientRect();
+    setPosition({
+      align: "end",
+      x: bounds.right,
+      y: bounds.bottom,
+      trigger,
+    });
+  };
+
+  const child = cloneElement(children, {
+    "data-context-menu-open": position ? "" : undefined,
+    onContextMenu: (event: MouseEvent) => {
+      children.props.onContextMenu?.(event);
+      if (event.defaultPrevented || visibleGroups.length === 0) {
+        return;
+      }
+      event.preventDefault();
+      const trigger = event.currentTarget as HTMLElement;
+      const bounds = trigger.getBoundingClientRect();
+      setPosition({
+        align: "start",
+        x: event.clientX || bounds.left,
+        y: event.clientY || bounds.bottom,
+        trigger,
+      });
+    },
+  });
+
+  return (
+    <ContextMenuControllerContext.Provider
+      value={{ isOpen: Boolean(position), toggleFromButton }}
+    >
+      {child}
+      {position ? (
+        <ContextMenuSurface
+          groups={visibleGroups}
+          label={label}
+          position={position}
+          onClose={closeMenu}
+        />
+      ) : null}
+    </ContextMenuControllerContext.Provider>
+  );
+}
+
+export function ContextMenuTrigger({
+  children,
+}: {
+  children: ReactElement<{
+    "aria-expanded"?: boolean;
+    "aria-haspopup"?: "menu";
+    onClick?: (event: MouseEvent) => void;
+  }>;
+}) {
+  const controller = useContext(ContextMenuControllerContext);
+  if (!controller) {
+    throw new Error("ContextMenuTrigger must be rendered inside ContextMenu");
+  }
+
+  return cloneElement(children, {
+    "aria-expanded": controller.isOpen,
+    "aria-haspopup": "menu",
+    onClick: (event: MouseEvent) => {
+      children.props.onClick?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+      event.stopPropagation();
+      controller.toggleFromButton(event.currentTarget as HTMLElement);
+    },
+  });
+}

package/src/shared/components/ui/tab-strip/__tests__/compact-tab-strip.test.tsx

@@ -141,12 +141,18 @@ describe("CompactTabStrip", () => {
             label: "index.html",
             active: true,
             menuLabel: "File actions",
-            menuActions: [
+            menuGroups: [
               {
-                key: "preview",
-                icon: <span />,
-                label: "Open preview",
-                onClick: onAction,
+                key: "file",
+                items: [
+                  {
+                    key: "preview",
+                    icon: <span />,
+                    label: "Open preview",
+                    restoreFocus: false,
+                    onSelect: onAction,
+                  },
+                ],
               },
             ],
             onSelect,
@@ -160,7 +166,14 @@ describe("CompactTabStrip", () => {
     await user.click(menuTrigger);
     await user.click(screen.getByRole("menuitem", { name: "Open preview" }));
 
-    expect(onAction).toHaveBeenCalledTimes(1);
+    const tabItem = screen
+      .getByRole("button", { name: "index.html" })
+      .closest("[data-compact-tab-item]");
+    expect(tabItem).not.toBeNull();
+    fireEvent.contextMenu(tabItem!);
+    await user.click(screen.getByRole("menuitem", { name: "Open preview" }));
+
+    expect(onAction).toHaveBeenCalledTimes(2);
     expect(onSelect).not.toHaveBeenCalled();
     expect(document.activeElement).not.toBe(menuTrigger);
   });