@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/react/panel-host/panel-host-geometry.ts

@@ -6,6 +6,7 @@ import {
 import type {
   PanelDimensions,
   PanelPoint,
+  PanelSnapPlacement,
   PanelSnapEdge,
   PanelViewport,
 } from "./panel-host-types";
@@ -67,7 +68,7 @@ function getPanelSnapEdge(
   ).edge;
 }
 
-export function resolvePanelSnapPosition({
+export function resolvePanelSnapPlacement({
   dimensions,
   edges,
   margin = panelSnapMarginPx,
@@ -83,7 +84,7 @@ export function resolvePanelSnapPosition({
   velocity: PanelPoint;
   viewport: PanelViewport;
   zone?: number;
-}): PanelPoint | null {
+}): Required<PanelSnapPlacement> | null {
   const projectedPosition = getProjectedPanelPosition(position, velocity);
   const edge = getPanelSnapEdge(projectedPosition, dimensions, viewport, edges, zone);
   const minX = viewport.offsetLeft + margin;
@@ -97,13 +98,70 @@ export function resolvePanelSnapPosition({
 
   if (edge === "top" || edge === "bottom") {
     return {
-      x: clampPanelValue(projectedPosition.x, minX, maxX),
-      y: edge === "top" ? minY : maxY,
+      offset: {
+        x: clampPanelValue(projectedPosition.x, minX, maxX),
+        y: edge === "top" ? minY : maxY,
+      },
+      snapEdge: edge,
     };
   }
 
   return {
-    x: edge === "left" ? minX : maxX,
-    y: clampPanelValue(projectedPosition.y, minY, maxY),
+    offset: {
+      x: edge === "left" ? minX : maxX,
+      y: clampPanelValue(projectedPosition.y, minY, maxY),
+    },
+    snapEdge: edge,
+  };
+}
+
+export function resolvePanelSnapPosition(
+  input: Parameters<typeof resolvePanelSnapPlacement>[0],
+): PanelPoint | null {
+  return resolvePanelSnapPlacement(input)?.offset ?? null;
+}
+
+export function clampPanelPlacementToViewport({
+  dimensions,
+  margin = panelSnapMarginPx,
+  origin,
+  placement,
+  viewport,
+}: {
+  dimensions: PanelDimensions;
+  margin?: number;
+  origin: PanelPoint;
+  placement: PanelSnapPlacement;
+  viewport: PanelViewport;
+}): PanelSnapPlacement {
+  const minX = viewport.offsetLeft + margin;
+  const maxX = viewport.offsetLeft + viewport.width - dimensions.width - margin;
+  const minY = viewport.offsetTop + margin;
+  const maxY = viewport.offsetTop + viewport.height - dimensions.height - margin;
+  const absolutePosition = {
+    x: origin.x + placement.offset.x,
+    y: origin.y + placement.offset.y,
+  };
+  const clampedPosition = {
+    x:
+      placement.snapEdge === "left"
+        ? minX
+        : placement.snapEdge === "right"
+          ? maxX
+          : clampPanelValue(absolutePosition.x, minX, maxX),
+    y:
+      placement.snapEdge === "top"
+        ? minY
+        : placement.snapEdge === "bottom"
+          ? maxY
+          : clampPanelValue(absolutePosition.y, minY, maxY),
+  };
+
+  return {
+    offset: {
+      x: clampedPosition.x - origin.x,
+      y: clampedPosition.y - origin.y,
+    },
+    ...(placement.snapEdge ? { snapEdge: placement.snapEdge } : {}),
   };
 }

package/templates/runtime/react/panel-host/panel-host-runtime-placement.test.tsx

@@ -0,0 +1,228 @@
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("motion/react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("motion/react")>();
+  type TestDragInfo = { velocity: { x: number; y: number } };
+  type TestMotionDivProps = Omit<
+    React.HTMLAttributes<HTMLDivElement>,
+    "onDragEnd" | "style"
+  > & {
+    animate?: unknown;
+    drag?: unknown;
+    dragControls?: unknown;
+    dragElastic?: unknown;
+    dragListener?: unknown;
+    dragMomentum?: unknown;
+    dragTransition?: unknown;
+    initial?: unknown;
+    onDragEnd?: (event: Event, info: TestDragInfo) => void;
+    onDragStart?: () => void;
+    style?: React.CSSProperties & {
+      x?: { set: (value: number) => void };
+      y?: { set: (value: number) => void };
+    };
+    transition?: unknown;
+  };
+  const MotionDiv = React.forwardRef<HTMLDivElement, TestMotionDivProps>(
+    function MotionDiv(
+      {
+        animate: _animate,
+        children,
+        drag: _drag,
+        dragControls: _dragControls,
+        dragElastic: _dragElastic,
+        dragListener: _dragListener,
+        dragMomentum: _dragMomentum,
+        dragTransition: _dragTransition,
+        initial: _initial,
+        onDragEnd,
+        onDragStart,
+        style,
+        transition: _transition,
+        ...props
+      },
+      ref,
+    ) {
+      return (
+        <div
+          {...props}
+          onDragEnd={(event) => {
+            const detail: unknown = Reflect.get(event.nativeEvent, "detail");
+
+            if (
+              typeof detail !== "object" ||
+              detail === null ||
+              !("x" in detail) ||
+              typeof detail.x !== "number" ||
+              !("y" in detail) ||
+              typeof detail.y !== "number"
+            ) {
+              throw new Error("Expected a numeric test drag position.");
+            }
+
+            style?.x?.set(detail.x);
+            style?.y?.set(detail.y);
+            onDragEnd?.(event.nativeEvent, {
+              velocity: { x: 0, y: 0 },
+            });
+          }}
+          onDragStart={onDragStart}
+          ref={ref}
+        >
+          {children}
+        </div>
+      );
+    },
+  );
+
+  return {
+    ...actual,
+    motion: { ...actual.motion, div: MotionDiv },
+  };
+});
+
+import { defineToolcraft } from "../../schema/define-toolcraft";
+import { ToolcraftRoot } from "../app-shell/toolcraft-root";
+import { useToolcraft } from "../app-shell/use-toolcraft";
+import { ToolcraftPanelHost } from "./panel-host";
+
+const schema = defineToolcraft({ canvas: { enabled: true }, panels: {} });
+
+function ToolbarPlacementProbe(): React.JSX.Element {
+  const { state } = useToolcraft();
+  const { offset, snapEdge } = state.panels.toolbar;
+
+  return (
+    <span data-testid="toolbar-placement">
+      {offset.x},{offset.y},{snapEdge ?? "free"}
+    </span>
+  );
+}
+
+function renderToolbar(offset = { x: 0, y: 0 }) {
+  return render(
+    <ToolcraftRoot
+      initialState={{ panels: { toolbar: { offset } } }}
+      schema={schema}
+    >
+      <ToolbarPlacementProbe />
+      <ToolcraftPanelHost panelType="toolbar">
+        <div>Toolbar</div>
+      </ToolcraftPanelHost>
+    </ToolcraftRoot>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+  vi.restoreAllMocks();
+});
+
+describe("ToolcraftPanelHost runtime placement", () => {
+  it("commits the final free drag position through runtime panel state", async () => {
+    const { container } = renderToolbar();
+    const host = container.querySelector<HTMLElement>(
+      "[data-slot='toolcraft-runtime-panel-host']",
+    );
+
+    if (!host) {
+      throw new Error("Expected the toolbar panel host to render.");
+    }
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      bottom: 300,
+      height: 100,
+      left: 200,
+      right: 300,
+      top: 200,
+      width: 100,
+      x: 200,
+      y: 200,
+      toJSON: () => ({}),
+    });
+
+    fireEvent(
+      host,
+      new CustomEvent("dragend", {
+        bubbles: true,
+        detail: { x: 40, y: 80 },
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("toolbar-placement").textContent).toBe(
+        "40,80,free",
+      );
+    });
+  });
+
+  it("clamps restored runtime placement after a viewport resize", async () => {
+    Object.defineProperty(window, "innerWidth", {
+      configurable: true,
+      value: 800,
+    });
+    Object.defineProperty(window, "innerHeight", {
+      configurable: true,
+      value: 500,
+    });
+    const { container } = renderToolbar({ x: 900, y: -200 });
+    const host = container.querySelector<HTMLElement>(
+      "[data-slot='toolcraft-runtime-panel-host']",
+    );
+
+    if (!host) {
+      throw new Error("Expected the toolbar panel host to render.");
+    }
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      bottom: -50,
+      height: 100,
+      left: 1000,
+      right: 1200,
+      top: -150,
+      width: 200,
+      x: 1000,
+      y: -150,
+      toJSON: () => ({}),
+    });
+
+    fireEvent(window, new Event("resize"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("toolbar-placement").textContent).toBe(
+        "490,-40,free",
+      );
+    });
+  });
+
+  it("keeps the CSS-anchored default placement during viewport resize", async () => {
+    const { container } = renderToolbar();
+    const host = container.querySelector<HTMLElement>(
+      "[data-slot='toolcraft-runtime-panel-host']",
+    );
+
+    if (!host) {
+      throw new Error("Expected the toolbar panel host to render.");
+    }
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      bottom: 900,
+      height: 100,
+      left: 1_500,
+      right: 1_700,
+      top: 800,
+      width: 200,
+      x: 1_500,
+      y: 800,
+      toJSON: () => ({}),
+    });
+
+    fireEvent(window, new Event("resize"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("toolbar-placement").textContent).toBe(
+        "0,0,free",
+      );
+    });
+  });
+});

package/templates/runtime/react/panel-host/panel-host-types.ts

@@ -1,12 +1,21 @@
 import type * as React from "react";
 
-import type { ToolcraftPanelId, ToolcraftPanelState } from "../../state/types";
+import type {
+  ToolcraftPanelId,
+  ToolcraftPanelState,
+} from "../../state/types";
+import type { ToolcraftPanelSnapEdge } from "../../contracts/types";
 
 export type { ToolcraftPanelState } from "../../state/types";
 
 export type ToolcraftPanelType = ToolcraftPanelId;
 
-export type PanelSnapEdge = "bottom" | "left" | "right" | "top";
+export type PanelSnapEdge = ToolcraftPanelSnapEdge;
+
+export type PanelSnapPlacement = {
+  offset: PanelPoint;
+  snapEdge?: PanelSnapEdge;
+};
 
 export type PanelDragMode = "handle" | "panel";
 
@@ -40,12 +49,14 @@ export type PanelHostProps = {
   className?: string;
   dragMode?: PanelDragMode;
   innerClassName?: string;
+  onPlacementChange?: (placement: PanelSnapPlacement) => void;
   onPositionChange?: (position: PanelPoint) => void;
   onResetPosition?: () => void;
   panelId?: string;
   panelType: ToolcraftPanelType;
   position?: PanelPoint;
   snap?: PanelSnapConfig;
+  snapEdge?: PanelSnapEdge;
   style?: React.CSSProperties;
 };
 

package/templates/runtime/react/panel-host/panel-host.test.tsx

@@ -51,8 +51,15 @@ describe("PanelHost", () => {
 
   it("resets a panel on double click", () => {
     const handleReset = vi.fn();
+    const handlePlacementChange = vi.fn();
+    const handlePositionChange = vi.fn();
     const { container } = render(
-      <PanelHost onResetPosition={handleReset} panelType="toolbar">
+      <PanelHost
+        onPlacementChange={handlePlacementChange}
+        onPositionChange={handlePositionChange}
+        onResetPosition={handleReset}
+        panelType="toolbar"
+      >
         <div>Toolbar</div>
       </PanelHost>,
     );
@@ -63,6 +70,11 @@ describe("PanelHost", () => {
     fireEvent.doubleClick(host as Element);
 
     expect(handleReset).toHaveBeenCalledTimes(1);
+    expect(handlePlacementChange).toHaveBeenCalledWith({
+      offset: { x: 0, y: 0 },
+      snapEdge: undefined,
+    });
+    expect(handlePositionChange).toHaveBeenCalledWith({ x: 0, y: 0 });
   });
 
   it("does not reset when double clicking an ignored child control", () => {

package/templates/runtime/react/panel-host/panel-host.tsx

@@ -17,16 +17,20 @@ import {
   panelHostConfig,
   panelSnapAnimation,
 } from "./panel-host-config";
-import { resolvePanelSnapPosition } from "./panel-host-geometry";
+import {
+  clampPanelPlacementToViewport,
+  resolvePanelSnapPlacement,
+} from "./panel-host-geometry";
 import type {
   ToolcraftPanelHostProps,
   PanelContainerProps,
   PanelHostProps,
   PanelPoint,
+  PanelSnapPlacement,
   PanelStageProps,
   PanelViewport,
 } from "./panel-host-types";
-import { useToolcraft } from "../app-shell/use-toolcraft";
+import { useToolcraftPanelBinding } from "./use-toolcraft-panel-binding";
 
 function cn(...classNames: Array<string | false | null | undefined>): string {
   return classNames.filter(Boolean).join(" ");
@@ -81,11 +85,21 @@ function animatePanelMotionValue(value: MotionValue<number>, target: number): vo
 }
 
 function usePanelSnapControls({
+  onPlacementChange,
   onPositionChange,
   onResetPosition,
   position = { x: 0, y: 0 },
   snap,
-}: Pick<PanelHostProps, "onPositionChange" | "onResetPosition" | "position" | "snap">) {
+  snapEdge,
+}: Pick<
+  PanelHostProps,
+  | "onPlacementChange"
+  | "onPositionChange"
+  | "onResetPosition"
+  | "position"
+  | "snap"
+  | "snapEdge"
+>) {
   const panelRef = React.useRef<HTMLDivElement>(null);
   const x = useMotionValue(position.x);
   const y = useMotionValue(position.y);
@@ -95,8 +109,25 @@ function usePanelSnapControls({
     animatePanelMotionValue(y, position.y);
   }, [position.x, position.y, x, y]);
 
+  const publishPlacement = React.useCallback(
+    (placement: PanelSnapPlacement): void => {
+      onPositionChange?.(placement.offset);
+      onPlacementChange?.(placement);
+    },
+    [onPlacementChange, onPositionChange],
+  );
+
+  const setPlacement = React.useCallback(
+    (placement: PanelSnapPlacement): void => {
+      animatePanelMotionValue(x, placement.offset.x);
+      animatePanelMotionValue(y, placement.offset.y);
+      publishPlacement(placement);
+    },
+    [publishPlacement, x, y],
+  );
+
   const publishPosition = (nextPosition: PanelPoint): void => {
-    onPositionChange?.(nextPosition);
+    publishPlacement({ offset: nextPosition, snapEdge: undefined });
   };
 
   const publishCurrentPosition = (): void => {
@@ -118,7 +149,7 @@ function usePanelSnapControls({
 
     const rect = panel.getBoundingClientRect();
     const offset = { x: x.get(), y: y.get() };
-    const target = resolvePanelSnapPosition({
+    const target = resolvePanelSnapPlacement({
       dimensions: { height: rect.height, width: rect.width },
       edges: snap.edges,
       margin: snap.margin,
@@ -134,22 +165,67 @@ function usePanelSnapControls({
     }
 
     const nextPosition = {
-      x: target.x - (rect.left - offset.x),
-      y: target.y - (rect.top - offset.y),
+      x: target.offset.x - (rect.left - offset.x),
+      y: target.offset.y - (rect.top - offset.y),
     };
 
-    animatePanelMotionValue(x, nextPosition.x);
-    animatePanelMotionValue(y, nextPosition.y);
-    publishPosition(nextPosition);
+    setPlacement({ offset: nextPosition, snapEdge: target.snapEdge });
   };
 
   const resetPosition = (): void => {
-    animatePanelMotionValue(x, 0);
-    animatePanelMotionValue(y, 0);
-    publishPosition({ x: 0, y: 0 });
+    setPlacement({ offset: { x: 0, y: 0 }, snapEdge: undefined });
     onResetPosition?.();
   };
 
+  React.useLayoutEffect(() => {
+    const panel = panelRef.current;
+
+    if (!panel) {
+      return undefined;
+    }
+
+    const clampRestoredPlacement = (): void => {
+      const rect = panel.getBoundingClientRect();
+
+      if (rect.width <= 0 || rect.height <= 0) {
+        return;
+      }
+
+      if (x.get() === 0 && y.get() === 0 && snapEdge === undefined) {
+        return;
+      }
+
+      const currentPlacement = {
+        offset: { x: x.get(), y: y.get() },
+        ...(snapEdge ? { snapEdge } : {}),
+      };
+      const nextPlacement = clampPanelPlacementToViewport({
+        dimensions: { height: rect.height, width: rect.width },
+        margin: snap?.margin,
+        origin: {
+          x: rect.left - currentPlacement.offset.x,
+          y: rect.top - currentPlacement.offset.y,
+        },
+        placement: currentPlacement,
+        viewport: getPanelVisualViewport(),
+      });
+
+      if (
+        nextPlacement.offset.x !== currentPlacement.offset.x ||
+        nextPlacement.offset.y !== currentPlacement.offset.y
+      ) {
+        setPlacement(nextPlacement);
+      }
+    };
+
+    clampRestoredPlacement();
+    window.addEventListener("resize", clampRestoredPlacement);
+
+    return () => {
+      window.removeEventListener("resize", clampRestoredPlacement);
+    };
+  }, [setPlacement, snap?.margin, snapEdge, x, y]);
+
   return { handleDragEnd, panelRef, resetPosition, x, y };
 }
 
@@ -159,11 +235,13 @@ export function PanelHost({
   dragMode,
   innerClassName,
   onPositionChange,
+  onPlacementChange,
   onResetPosition,
   panelId,
   panelType,
   position,
   snap,
+  snapEdge,
   style,
 }: PanelHostProps): React.JSX.Element {
   const config = panelHostConfig[panelType];
@@ -179,9 +257,11 @@ export function PanelHost({
     y,
   } = usePanelSnapControls({
     onPositionChange,
+    onPlacementChange,
     onResetPosition,
     position,
     snap: resolvedSnap,
+    snapEdge,
   });
   const [isDragging, setIsDragging] = React.useState(false);
 
@@ -232,6 +312,9 @@ export function PanelHost({
         data-dragging={isDragging ? "true" : "false"}
         data-drag-mode={resolvedDragMode}
         data-panel-id={resolvedPanelId}
+        data-panel-offset-x={position?.x ?? 0}
+        data-panel-offset-y={position?.y ?? 0}
+        data-panel-snap-edge={snapEdge}
         data-panel-type={panelType}
         data-slot="toolcraft-runtime-panel-host"
         data-snap-edges={resolvedSnap?.edges.join(" ")}
@@ -255,28 +338,32 @@ export function PanelHost({
 }
 
 export function ToolcraftPanelHost({
+  onPlacementChange,
   onPositionChange,
   onResetPosition,
   panelType,
   position,
+  snapEdge,
   ...props
 }: ToolcraftPanelHostProps): React.JSX.Element {
-  const { dispatch, state } = useToolcraft();
-  const panelState = state.panels[panelType];
+  const panelBinding = useToolcraftPanelBinding({ panelId: panelType });
 
   return (
     <PanelHost
       {...props}
+      onPlacementChange={(placement) => {
+        onPlacementChange?.(placement);
+        panelBinding.onPanelStateChange(placement);
+      }}
       onPositionChange={(offset) => {
         onPositionChange?.(offset);
-        dispatch({ offset, panelId: panelType, type: "panels.setOffset" });
       }}
       onResetPosition={() => {
         onResetPosition?.();
-        dispatch({ panelId: panelType, type: "panels.resetOffset" });
       }}
       panelType={panelType}
-      position={position ?? panelState.offset}
+      position={position ?? panelBinding.panelState.offset}
+      snapEdge={snapEdge ?? panelBinding.panelState.snapEdge}
     />
   );
 }
@@ -322,10 +409,11 @@ export function PanelContainer({
       <PanelHost
         className={panelClassName}
         dragMode={dragMode}
-        onPositionChange={(offset) => onPanelStateChange?.({ offset })}
+        onPlacementChange={onPanelStateChange}
         panelType={panelType}
         position={panelState?.offset}
         snap={{ edges: config.snapEdges }}
+        snapEdge={panelState?.snapEdge}
       >
         {children}
       </PanelHost>
@@ -341,10 +429,11 @@ export function PanelContainer({
       <PanelHost
         className={panelClassName}
         dragMode={dragMode}
-        onPositionChange={(offset) => onPanelStateChange?.({ offset })}
+        onPlacementChange={onPanelStateChange}
         panelType={panelType}
         position={panelState?.offset}
         snap={{ edges: config.snapEdges }}
+        snapEdge={panelState?.snapEdge}
       >
         {children}
       </PanelHost>