@nextclaw/ui 0.25.4 → 0.26.0

package/src/shared/components/workbench/utils/workbench-surface-geometry.utils.ts

@@ -0,0 +1,46 @@
+import type {
+  WorkbenchRect,
+  WorkbenchResizeEdge,
+  WorkbenchViewport,
+} from "@/shared/components/workbench/types/workbench-surface.types";
+
+const MARGIN = 12;
+const clamp = (value: number, min: number, max: number) =>
+  Math.max(min, Math.min(max, value));
+
+export function constrainWorkbenchRect(
+  rect: WorkbenchRect,
+  viewport: WorkbenchViewport,
+): WorkbenchRect {
+  const maxWidth = Math.max(1, viewport.width - MARGIN * 2);
+  const maxHeight = Math.max(1, viewport.height - MARGIN * 2);
+  const w = clamp(rect.w, Math.min(320, maxWidth), maxWidth);
+  const h = clamp(rect.h, Math.min(240, maxHeight), maxHeight);
+  return {
+    w,
+    h,
+    x: clamp(rect.x, MARGIN, viewport.width - w - MARGIN),
+    y: clamp(rect.y, MARGIN, viewport.height - h - MARGIN),
+  };
+}
+
+export function resizeWorkbenchRect(
+  rect: WorkbenchRect,
+  edge: WorkbenchResizeEdge,
+  dx: number,
+  dy: number,
+  viewport: WorkbenchViewport,
+): WorkbenchRect {
+  const parts = edge.split("-");
+  const right = rect.x + rect.w;
+  const bottom = rect.y + rect.h;
+  const x = parts.includes("left")
+    ? clamp(rect.x + dx, MARGIN, right - Math.min(320, rect.w))
+    : rect.x;
+  const y = parts.includes("top")
+    ? clamp(rect.y + dy, MARGIN, bottom - Math.min(240, rect.h))
+    : rect.y;
+  const w = parts.includes("right") ? rect.w + dx : right - x;
+  const h = parts.includes("bottom") ? rect.h + dy : bottom - y;
+  return constrainWorkbenchRect({ x, y, w, h }, viewport);
+}

package/src/shared/components/workbench/workbench-surface-toolbar.tsx

@@ -0,0 +1,102 @@
+import {
+  ArrowUpRight,
+  Maximize2,
+  Minimize2,
+  Minus,
+  PanelRight,
+  PictureInPicture2,
+  X,
+} from "lucide-react";
+import { IconActionButton } from "@/shared/components/ui/actions/icon-action-button";
+import { t } from "@/shared/lib/i18n";
+import type { WorkbenchSurfaceState } from "./types/workbench-surface.types";
+
+export function WorkbenchSurfaceToolbar({
+  state,
+  compact,
+  onPlace,
+  onMinimize,
+  onRestore,
+  onMaximize,
+  onClose,
+  closeLabel,
+  onOpenMain,
+}: {
+  state: WorkbenchSurfaceState;
+  compact: boolean;
+  onPlace?: () => void;
+  onMinimize: () => void;
+  onRestore: () => void;
+  onMaximize: () => void;
+  onClose: () => void;
+  closeLabel: string;
+  onOpenMain?: () => void;
+}) {
+  return (
+    <div
+      className="flex shrink-0 items-center gap-0.5"
+      data-workbench-actions=""
+    >
+      {onOpenMain && (
+        <IconActionButton
+          size="sm"
+          icon={<ArrowUpRight className="h-4 w-4" />}
+          label={t("workbenchOpenMain")}
+          onClick={onOpenMain}
+        />
+      )}
+      {!compact && onPlace && (
+        <IconActionButton
+          size="sm"
+          icon={
+            state.placement === "floating" ? (
+              <PanelRight className="h-4 w-4" />
+            ) : (
+              <PictureInPicture2 className="h-4 w-4" />
+            )
+          }
+          label={t(
+            state.placement === "floating"
+              ? "workbenchDock"
+              : "workbenchFloatGroup",
+          )}
+          onClick={onPlace}
+        />
+      )}
+      <IconActionButton
+        size="sm"
+        icon={
+          state.minimized ? (
+            <Maximize2 className="h-4 w-4" />
+          ) : (
+            <Minus className="h-4 w-4" />
+          )
+        }
+        label={t(state.minimized ? "workbenchExpand" : "workbenchCollapse")}
+        onClick={state.minimized ? onRestore : onMinimize}
+      />
+      {!compact && !state.minimized && (
+        <IconActionButton
+          size="sm"
+          icon={
+            state.maximized ? (
+              <Minimize2 className="h-4 w-4" />
+            ) : (
+              <Maximize2 className="h-4 w-4" />
+            )
+          }
+          label={t(
+            state.maximized ? "workbenchRestoreSize" : "workbenchMaximize",
+          )}
+          onClick={onMaximize}
+        />
+      )}
+      <IconActionButton
+        size="sm"
+        icon={<X className="h-4 w-4" />}
+        label={closeLabel}
+        onClick={onClose}
+      />
+    </div>
+  );
+}

package/src/shared/components/workbench/workbench-surface.tsx

@@ -0,0 +1,401 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
+import { useWorkbenchSurfaceStore } from "./stores/workbench-surface.store";
+import {
+  DEFAULT_WORKBENCH_SURFACE,
+  type WorkbenchResizeEdge,
+} from "./types/workbench-surface.types";
+import type { WorkbenchSurfaceManager } from "./managers/workbench-surface.manager";
+import { WorkbenchSurfaceToolbar } from "./workbench-surface-toolbar";
+import { cn } from "@/shared/lib/utils";
+import { t } from "@/shared/lib/i18n";
+
+type WorkbenchSurfaceProps = {
+  id: string;
+  manager: WorkbenchSurfaceManager;
+  title: string;
+  children: ReactNode;
+  navigation?: ReactNode;
+  icon?: ReactNode;
+  onClose: () => void;
+  closeLabel?: string;
+  onPlace?: () => void;
+  onOpenMain?: () => void;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  onWidthCommit?: (width: number) => void;
+  fullscreen?: boolean;
+  hidden?: boolean;
+  testId?: string;
+  className?: string;
+  focusOnOpen?: boolean;
+};
+
+const EDGE_CLASSES: Record<WorkbenchResizeEdge, string> = {
+  left: "left-0 top-3 bottom-3 w-1.5 cursor-ew-resize",
+  right: "right-0 top-3 bottom-3 w-1.5 cursor-ew-resize",
+  top: "top-0 left-3 right-3 h-1.5 cursor-ns-resize",
+  bottom: "bottom-0 left-3 right-3 h-1.5 cursor-ns-resize",
+  "top-left": "left-0 top-0 h-3 w-3 cursor-nwse-resize",
+  "top-right": "right-0 top-0 h-3 w-3 cursor-nesw-resize",
+  "bottom-left": "left-0 bottom-0 h-3 w-3 cursor-nesw-resize",
+  "bottom-right": "right-0 bottom-0 h-3 w-3 cursor-nwse-resize",
+};
+const viewport = () => ({
+  width: window.innerWidth,
+  height: window.innerHeight,
+});
+const blocksDrag = (target: EventTarget | null) =>
+  target instanceof Element &&
+  Boolean(
+    target.closest(
+      'button, a, input, textarea, select, [role="menu"], [data-compact-tab-item]',
+    ),
+  );
+
+/** One stable DOM parent across dock/float/maximize/collapse. Content never owns window mechanics. */
+export function WorkbenchSurface({
+  id,
+  manager,
+  title,
+  icon,
+  navigation,
+  children,
+  onClose,
+  closeLabel = t("workbenchCloseView"),
+  onPlace,
+  onOpenMain,
+  width = 480,
+  minWidth = 320,
+  maxWidth = 960,
+  onWidthCommit,
+  fullscreen = false,
+  hidden = false,
+  testId,
+  className,
+  focusOnOpen = false,
+}: WorkbenchSurfaceProps) {
+  const state = useWorkbenchSurfaceStore(
+    (store) => store.surfaces[id] ?? DEFAULT_WORKBENCH_SURFACE,
+  );
+  const panelRef = useRef<HTMLElement>(null);
+  const interactionCleanup = useRef<(() => void) | null>(null);
+  const openerRef = useRef<HTMLElement | null>(null);
+  const [compact, setCompact] = useState(() => window.innerWidth < 768);
+  const [interacting, setInteracting] = useState(false);
+  const [dragWidth, setDragWidth] = useState<number | null>(null);
+  const isCompact = compact || fullscreen;
+  const floating = state.placement === "floating";
+  const overlay = isCompact || state.maximized;
+
+  useEffect(() => {
+    openerRef.current =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
+    if (focusOnOpen) panelRef.current?.focus();
+    const onResize = () => {
+      setCompact(window.innerWidth < 768);
+      manager.constrain(id, viewport());
+    };
+    onResize();
+    window.addEventListener("resize", onResize);
+    return () => {
+      window.removeEventListener("resize", onResize);
+      interactionCleanup.current?.();
+    };
+  }, [id, manager, focusOnOpen]);
+
+  useEffect(() => {
+    manager.setVisible(id, !hidden);
+    return () => manager.setVisible(id, false);
+  }, [hidden, id, manager]);
+
+  const focusControl = () => panelRef.current?.focus();
+  const close = () => {
+    onClose();
+    if (
+      openerRef.current?.isConnected &&
+      !panelRef.current?.contains(openerRef.current)
+    )
+      openerRef.current.focus();
+  };
+
+  const startInteraction = (
+    event: ReactPointerEvent<HTMLElement>,
+    edge?: WorkbenchResizeEdge | "dock",
+  ) => {
+    if (
+      event.button !== 0 ||
+      overlay ||
+      state.minimized ||
+      (!edge && blocksDrag(event.target))
+    )
+      return;
+    if (!edge && !floating) return;
+    event.preventDefault();
+    event.stopPropagation();
+    event.currentTarget.setPointerCapture?.(event.pointerId);
+    interactionCleanup.current?.();
+    manager.focus(id);
+    setInteracting(true);
+    const start = {
+      x: event.clientX,
+      y: event.clientY,
+      rect: state.rect,
+      width,
+    };
+    let nextWidth = width;
+    const move = (next: PointerEvent) => {
+      const dx = next.clientX - start.x;
+      const dy = next.clientY - start.y;
+      if (edge === "dock") {
+        nextWidth = Math.max(
+          Math.min(minWidth, window.innerWidth),
+          Math.min(maxWidth, window.innerWidth, start.width - dx),
+        );
+        setDragWidth(nextWidth);
+      } else if (edge) manager.resize(id, start.rect, edge, dx, dy, viewport());
+      else manager.move(id, start.rect, dx, dy, viewport());
+    };
+    const cleanup = () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", end);
+      window.removeEventListener("pointercancel", end);
+    };
+    const end = () => {
+      cleanup();
+      interactionCleanup.current = null;
+      setInteracting(false);
+      setDragWidth(null);
+      if (edge === "dock") onWidthCommit?.(nextWidth);
+    };
+    interactionCleanup.current = cleanup;
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", end);
+    window.addEventListener("pointercancel", end);
+  };
+
+  const minimizedIndex = useWorkbenchSurfaceStore((store) =>
+    store.visibleSurfaceIds
+      .filter((key) => store.surfaces[key]?.minimized)
+      .sort()
+      .indexOf(id),
+  );
+  const layer = useWorkbenchSurfaceStore(
+    (store) =>
+      store.visibleSurfaceIds.filter(
+        (key) => (store.surfaces[key]?.layer ?? 0) <= state.layer,
+      ).length,
+  );
+  const style: CSSProperties = state.minimized
+    ? {
+        position: "fixed",
+        bottom: 12 + Math.max(0, minimizedIndex) * 48,
+        right: 12,
+        width: "min(360px, calc(100vw - 24px))",
+        zIndex: 50 + layer,
+      }
+    : overlay
+      ? {
+          position: "fixed",
+          inset: 0,
+          width: "100%",
+          height: "100dvh",
+          zIndex: 50 + layer,
+        }
+      : floating
+        ? {
+            position: "fixed",
+            left: state.rect.x,
+            top: state.rect.y,
+            width: state.rect.w,
+            height: state.rect.h,
+            zIndex: 50 + layer,
+          }
+        : { width: dragWidth ?? width, height: "100%" };
+
+  return (
+    <aside
+      ref={panelRef}
+      role="region"
+      aria-label={title}
+      tabIndex={-1}
+      hidden={hidden}
+      data-testid={testId}
+      data-workbench-surface={id}
+      data-placement={state.placement}
+      data-maximized={state.maximized || undefined}
+      data-minimized={state.minimized || undefined}
+      data-theme-surface="workspace-panel"
+      className={cn(
+        "relative min-h-0 min-w-0 shrink-0 flex-col overflow-hidden bg-card text-card-foreground outline-none",
+        hidden ? "hidden" : "flex",
+        (floating || state.minimized) && !overlay
+          ? "rounded-xl border border-border shadow-2xl"
+          : "border-l border-border",
+        className,
+      )}
+      style={style}
+      onPointerDownCapture={() => manager.focus(id)}
+      onFocusCapture={() => manager.focus(id)}
+      onKeyDown={(event) => {
+        if (
+          event.key !== "Escape" ||
+          event.defaultPrevented ||
+          event.nativeEvent.isComposing
+        )
+          return;
+        if (state.maximized) {
+          event.stopPropagation();
+          manager.toggleMaximize(id);
+          focusControl();
+        } else if (floating && !state.minimized) {
+          event.stopPropagation();
+          manager.minimize(id);
+          focusControl();
+        }
+      }}
+    >
+      <header
+        className="flex min-h-10 shrink-0 select-none items-center gap-2 border-b border-border/60 bg-muted/30 px-2"
+        style={{ touchAction: floating ? "none" : undefined }}
+        onPointerDown={(event) => startInteraction(event)}
+        onDoubleClick={(event) => {
+          if (!isCompact && !blocksDrag(event.target))
+            manager.toggleMaximize(id);
+        }}
+      >
+        <div
+          hidden={state.minimized}
+          className={cn(
+            "min-w-0 flex-1",
+            state.minimized || !navigation ? "hidden" : "flex",
+          )}
+        >
+          {navigation}
+        </div>
+        <span
+          className={cn(
+            "flex min-w-0 flex-1 items-center gap-2 px-1 text-xs font-medium",
+            floating && !overlay && "cursor-grab active:cursor-grabbing",
+            navigation && !state.minimized && "hidden",
+          )}
+        >
+          {icon}
+          <span className="truncate">{title}</span>
+        </span>
+        <WorkbenchSurfaceToolbar
+          state={state}
+          compact={isCompact}
+          onPlace={
+            onPlace ??
+            (() => manager.place(id, floating ? "docked" : "floating"))
+          }
+          onMinimize={() => {
+            manager.minimize(id);
+            focusControl();
+          }}
+          onRestore={() => manager.restore(id)}
+          onMaximize={() => manager.toggleMaximize(id)}
+          onClose={close}
+          closeLabel={closeLabel}
+          onOpenMain={onOpenMain}
+        />
+      </header>
+      <div
+        hidden={state.minimized}
+        className={cn(
+          "min-h-0 min-w-0 flex-1 flex-col",
+          state.minimized ? "hidden" : "flex",
+        )}
+      >
+        {children}
+      </div>
+      {!overlay && !state.minimized && (
+        <WorkbenchResizeHandles
+          floating={floating}
+          width={dragWidth ?? width}
+          minWidth={minWidth}
+          maxWidth={maxWidth}
+          onWidthCommit={onWidthCommit}
+          onPointerDown={startInteraction}
+        />
+      )}
+      {interacting && (
+        <div
+          className="fixed inset-0 z-30"
+          data-workbench-interaction-shield=""
+        />
+      )}
+    </aside>
+  );
+}
+
+function WorkbenchResizeHandles({
+  floating,
+  width,
+  minWidth,
+  maxWidth,
+  onWidthCommit,
+  onPointerDown,
+}: {
+  floating: boolean;
+  width: number;
+  minWidth: number;
+  maxWidth: number;
+  onWidthCommit?: (width: number) => void;
+  onPointerDown: (
+    event: ReactPointerEvent<HTMLElement>,
+    edge: WorkbenchResizeEdge | "dock",
+  ) => void;
+}) {
+  return floating ? (
+    <>
+      {(Object.entries(EDGE_CLASSES) as [WorkbenchResizeEdge, string][]).map(
+        ([edge, classes]) => (
+          <div
+            key={edge}
+            data-workbench-resize={edge}
+            className={cn("absolute z-20 touch-none", classes)}
+            onPointerDown={(event) => onPointerDown(event, edge)}
+          />
+        ),
+      )}
+    </>
+  ) : onWidthCommit ? (
+    <div
+      role="separator"
+      aria-label={t("workbenchResize")}
+      aria-orientation="vertical"
+      aria-valuemin={minWidth}
+      aria-valuemax={maxWidth}
+      aria-valuenow={width}
+      tabIndex={0}
+      data-testid="resizable-right-panel-handle"
+      className="absolute bottom-0 left-0 top-0 z-20 w-1.5 cursor-ew-resize touch-none hover:bg-primary/20 focus-visible:bg-primary/30 focus-visible:outline-none"
+      onPointerDown={(event) => onPointerDown(event, "dock")}
+      onKeyDown={(event) => {
+        if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key))
+          return;
+        event.preventDefault();
+        const next =
+          event.key === "Home"
+            ? minWidth
+            : event.key === "End"
+              ? maxWidth
+              : width + (event.key === "ArrowLeft" ? 24 : -24);
+        onWidthCommit(
+          Math.max(minWidth, Math.min(maxWidth, window.innerWidth, next)),
+        );
+      }}
+    />
+  ) : null;
+}

package/src/shared/hooks/use-panel-app-scroll-restoration.test.tsx

@@ -64,3 +64,22 @@ describe("usePanelAppScrollRestoration", () => {
     expect(postMessage).not.toHaveBeenCalled();
   });
 });
+
+it("keeps independent URL positions when navigating A to B and back to A", () => {
+  scrollRestorationManager.clear();
+  const view = render(<PanelAppFrame currentUrl="/a" />);
+  const frame = view.getByTestId('panel-app-frame') as HTMLIFrameElement;
+  const post = vi.spyOn(frame.contentWindow!, 'postMessage');
+  const record = (y: number) => window.dispatchEvent(new MessageEvent('message', {
+    source: frame.contentWindow, data: { type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType, version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version, target: { kind: 'document' }, x: 0, y },
+  }));
+  record(400);
+  view.rerender(<PanelAppFrame currentUrl="/b" />);
+  record(80);
+  view.rerender(<PanelAppFrame currentUrl="/a" />);
+  fireEvent.load(frame);
+  expect(post).toHaveBeenLastCalledWith(expect.objectContaining({ y: 400 }), '*');
+  view.rerender(<PanelAppFrame currentUrl="/b" />);
+  fireEvent.load(frame);
+  expect(post).toHaveBeenLastCalledWith(expect.objectContaining({ y: 80 }), '*');
+});

package/src/shared/hooks/use-panel-app-scroll-restoration.ts

@@ -74,13 +74,15 @@ export function usePanelAppScrollRestoration({
   isEnabled,
   restorationKey,
 }: UsePanelAppScrollRestorationParams) {
+  const routeKey = restorationKey && currentUrl ? JSON.stringify([restorationKey, currentUrl]) : null;
   useEffect(() => {
-    if (!currentUrl || !isEnabled || !restorationKey) return;
+    if (!currentUrl || !isEnabled || !routeKey) return;
+    const key = routeKey;
     const onMessage = (event: MessageEvent) => {
       if (event.source !== iframeRef.current?.contentWindow || !isScrollMessage(event.data)) {
         return;
       }
-      scrollRestorationManager.save(restorationKey, {
+      scrollRestorationManager.save(key, {
         x: event.data.x,
         y: event.data.y,
         payload: { currentUrl, target: event.data.target } satisfies PanelAppScrollSnapshot,
@@ -88,11 +90,11 @@ export function usePanelAppScrollRestoration({
     };
     window.addEventListener("message", onMessage);
     return () => window.removeEventListener("message", onMessage);
-  }, [currentUrl, iframeRef, isEnabled, restorationKey]);
+  }, [currentUrl, iframeRef, isEnabled, routeKey]);
 
   return useCallback(() => {
-    if (!currentUrl || !isEnabled || !restorationKey) return;
-    const position = scrollRestorationManager.read(restorationKey);
+    if (!currentUrl || !isEnabled || !routeKey) return;
+    const position = scrollRestorationManager.read(routeKey);
     if (!position || !isPanelAppScrollSnapshot(position.payload) || position.payload.currentUrl !== currentUrl) {
       return;
     }
@@ -103,5 +105,5 @@ export function usePanelAppScrollRestoration({
       x: position.x,
       y: position.y,
     }, "*");
-  }, [currentUrl, iframeRef, isEnabled, restorationKey]);
+  }, [currentUrl, iframeRef, isEnabled, routeKey]);
 }

package/src/shared/hooks/use-scroll-restoration.test.tsx

@@ -1,5 +1,5 @@
-import { fireEvent, render } from "@testing-library/react";
-import { beforeEach, describe, expect, it } from "vitest";
+import { act, fireEvent, render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useScrollRestoration } from "@/shared/hooks/use-scroll-restoration";
 import { scrollRestorationManager } from "@/shared/lib/navigation-history";
 
@@ -60,3 +60,40 @@ describe("useScrollRestoration", () => {
     expect(scrollRestorationManager.read("page:first")).toEqual({ x: 0, y: 144 });
   });
 });
+
+it("retries delayed content, preserves hidden reading, and yields to explicit user scrolling", () => {
+  scrollRestorationManager.clear();
+  let notifyResize = () => {};
+  vi.stubGlobal("ResizeObserver", class { constructor(callback: () => void) { notifyResize = callback; } observe = () => {}; disconnect = () => {}; });
+  let height = 0;
+  let position = 0;
+  const descriptor = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollTop");
+  Object.defineProperty(HTMLElement.prototype, "scrollTop", { configurable: true, get: () => position, set: (value: number) => { position = Math.min(value, height); } });
+  try {
+    scrollRestorationManager.save("delayed", { x: 0, y: 400 });
+    const view = render(<ScrollSurface restorationKey="delayed" />);
+    const element = view.getByTestId("scroll-surface");
+    fireEvent.scroll(element);
+    expect(scrollRestorationManager.read("delayed")?.y).toBe(400);
+    height = 800;
+    act(() => notifyResize());
+    expect(element.scrollTop).toBe(400);
+    element.hidden = true;
+    element.scrollTop = 0;
+    fireEvent.scroll(element);
+    expect(scrollRestorationManager.read("delayed")?.y).toBe(400);
+    view.unmount();
+
+    height = 0;
+    const second = render(<ScrollSurface restorationKey="delayed" />);
+    fireEvent.wheel(second.getByTestId("scroll-surface"));
+    height = 800;
+    act(() => notifyResize());
+    expect(second.getByTestId("scroll-surface").scrollTop).toBe(0);
+    second.unmount();
+  } finally {
+    if (descriptor) Object.defineProperty(HTMLElement.prototype, "scrollTop", descriptor);
+    else Reflect.deleteProperty(HTMLElement.prototype, "scrollTop");
+    vi.unstubAllGlobals();
+  }
+});