@pixel-point/toolcraft 0.0.2

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

@@ -0,0 +1,353 @@
+"use client";
+
+import * as React from "react";
+import {
+  animate,
+  motion,
+  useDragControls,
+  useMotionValue,
+  type MotionValue,
+  type PanInfo,
+} from "motion/react";
+
+import {
+  panelDragHandleSelector,
+  panelDragIgnoredTargetSelector,
+  panelDragTransition,
+  panelHostConfig,
+  panelSnapAnimation,
+} from "./panel-host-config";
+import { resolvePanelSnapPosition } from "./panel-host-geometry";
+import type {
+  ToolcraftPanelHostProps,
+  PanelContainerProps,
+  PanelHostProps,
+  PanelPoint,
+  PanelStageProps,
+  PanelViewport,
+} from "./panel-host-types";
+import { useToolcraft } from "./use-toolcraft";
+
+function cn(...classNames: Array<string | false | null | undefined>): string {
+  return classNames.filter(Boolean).join(" ");
+}
+
+function isPanelDragHandleTarget(target: EventTarget | null, currentTarget: HTMLElement): boolean {
+  if (!(target instanceof Element)) {
+    return false;
+  }
+
+  const handleTarget = target.closest(panelDragHandleSelector);
+
+  return handleTarget !== null && currentTarget.contains(handleTarget);
+}
+
+function shouldIgnorePanelTarget(target: EventTarget | null, currentTarget: HTMLElement): boolean {
+  if (!(target instanceof Element)) {
+    return false;
+  }
+
+  const ignoredTarget = target.closest(panelDragIgnoredTargetSelector);
+
+  return ignoredTarget !== null && currentTarget.contains(ignoredTarget);
+}
+
+function shouldIgnorePanelDrag(event: React.PointerEvent<HTMLElement>): boolean {
+  return shouldIgnorePanelTarget(event.target, event.currentTarget);
+}
+
+function getPanelVisualViewport(): PanelViewport {
+  const visualViewport = window.visualViewport;
+
+  if (visualViewport) {
+    return {
+      height: visualViewport.height,
+      offsetLeft: visualViewport.offsetLeft,
+      offsetTop: visualViewport.offsetTop,
+      width: visualViewport.width,
+    };
+  }
+
+  return {
+    height: window.innerHeight,
+    offsetLeft: 0,
+    offsetTop: 0,
+    width: window.innerWidth,
+  };
+}
+
+function animatePanelMotionValue(value: MotionValue<number>, target: number): void {
+  void animate(value, target, panelSnapAnimation);
+}
+
+function usePanelSnapControls({
+  onPositionChange,
+  onResetPosition,
+  position = { x: 0, y: 0 },
+  snap,
+}: Pick<PanelHostProps, "onPositionChange" | "onResetPosition" | "position" | "snap">) {
+  const panelRef = React.useRef<HTMLDivElement>(null);
+  const x = useMotionValue(position.x);
+  const y = useMotionValue(position.y);
+
+  React.useEffect(() => {
+    animatePanelMotionValue(x, position.x);
+    animatePanelMotionValue(y, position.y);
+  }, [position.x, position.y, x, y]);
+
+  const publishPosition = (nextPosition: PanelPoint): void => {
+    onPositionChange?.(nextPosition);
+  };
+
+  const publishCurrentPosition = (): void => {
+    publishPosition({ x: x.get(), y: y.get() });
+  };
+
+  const handleDragEnd = (info: PanInfo): void => {
+    if (!snap || snap.edges.length === 0) {
+      publishCurrentPosition();
+      return;
+    }
+
+    const panel = panelRef.current;
+
+    if (!panel) {
+      publishCurrentPosition();
+      return;
+    }
+
+    const rect = panel.getBoundingClientRect();
+    const offset = { x: x.get(), y: y.get() };
+    const target = resolvePanelSnapPosition({
+      dimensions: { height: rect.height, width: rect.width },
+      edges: snap.edges,
+      margin: snap.margin,
+      position: { x: rect.left, y: rect.top },
+      velocity: { x: info.velocity.x / 1000, y: info.velocity.y / 1000 },
+      viewport: getPanelVisualViewport(),
+      zone: snap.zone,
+    });
+
+    if (!target) {
+      publishCurrentPosition();
+      return;
+    }
+
+    const nextPosition = {
+      x: target.x - (rect.left - offset.x),
+      y: target.y - (rect.top - offset.y),
+    };
+
+    animatePanelMotionValue(x, nextPosition.x);
+    animatePanelMotionValue(y, nextPosition.y);
+    publishPosition(nextPosition);
+  };
+
+  const resetPosition = (): void => {
+    animatePanelMotionValue(x, 0);
+    animatePanelMotionValue(y, 0);
+    publishPosition({ x: 0, y: 0 });
+    onResetPosition?.();
+  };
+
+  return { handleDragEnd, panelRef, resetPosition, x, y };
+}
+
+export function PanelHost({
+  children,
+  className,
+  dragMode,
+  innerClassName,
+  onPositionChange,
+  onResetPosition,
+  panelId,
+  panelType,
+  position,
+  snap,
+  style,
+}: PanelHostProps): React.JSX.Element {
+  const config = panelHostConfig[panelType];
+  const resolvedDragMode = dragMode ?? config.dragMode;
+  const resolvedSnap = snap ?? { edges: config.snapEdges };
+  const resolvedPanelId = panelId ?? config.panelId;
+  const dragControls = useDragControls();
+  const {
+    handleDragEnd: handleSnapDragEnd,
+    panelRef,
+    resetPosition,
+    x,
+    y,
+  } = usePanelSnapControls({
+    onPositionChange,
+    onResetPosition,
+    position,
+    snap: resolvedSnap,
+  });
+  const [isDragging, setIsDragging] = React.useState(false);
+
+  const handlePointerDown: React.PointerEventHandler<HTMLElement> = (event) => {
+    if (event.button !== 0) {
+      return;
+    }
+
+    if (
+      resolvedDragMode === "handle" &&
+      !isPanelDragHandleTarget(event.target, event.currentTarget)
+    ) {
+      return;
+    }
+
+    if (event.defaultPrevented || shouldIgnorePanelDrag(event)) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    dragControls.start(event);
+  };
+
+  const handleDragEnd = (_event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo): void => {
+    setIsDragging(false);
+    handleSnapDragEnd(info);
+  };
+
+  const handleDoubleClick: React.MouseEventHandler<HTMLElement> = (event) => {
+    if (
+      !resolvedSnap ||
+      event.defaultPrevented ||
+      (resolvedDragMode === "handle" &&
+        !isPanelDragHandleTarget(event.target, event.currentTarget)) ||
+      shouldIgnorePanelTarget(event.target, event.currentTarget)
+    ) {
+      return;
+    }
+
+    resetPosition();
+  };
+
+  return (
+    <div className={cn("pointer-events-none", config.wrapperClassName, className)} style={style}>
+      <motion.div
+        className={cn("pointer-events-auto", isDragging && "cursor-grabbing", innerClassName)}
+        data-dragging={isDragging ? "true" : "false"}
+        data-drag-mode={resolvedDragMode}
+        data-panel-id={resolvedPanelId}
+        data-panel-type={panelType}
+        data-slot="toolcraft-runtime-panel-host"
+        data-snap-edges={resolvedSnap?.edges.join(" ")}
+        drag
+        dragControls={dragControls}
+        dragElastic={0}
+        dragListener={false}
+        dragMomentum={false}
+        dragTransition={panelDragTransition}
+        onDoubleClick={handleDoubleClick}
+        onDragEnd={handleDragEnd}
+        onDragStart={() => setIsDragging(true)}
+        onPointerDown={handlePointerDown}
+        ref={panelRef}
+        style={{ x, y }}
+      >
+        {children}
+      </motion.div>
+    </div>
+  );
+}
+
+export function ToolcraftPanelHost({
+  onPositionChange,
+  onResetPosition,
+  panelType,
+  position,
+  ...props
+}: ToolcraftPanelHostProps): React.JSX.Element {
+  const { dispatch, state } = useToolcraft();
+  const panelState = state.panels[panelType];
+
+  return (
+    <PanelHost
+      {...props}
+      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}
+    />
+  );
+}
+
+export function PanelStage({
+  children,
+  className,
+  ...props
+}: PanelStageProps): React.JSX.Element {
+  return (
+    <div
+      {...props}
+      className={cn(
+        "relative w-full min-w-0 overflow-hidden rounded-lg bg-[color:var(--background)]",
+        className,
+      )}
+      data-toolcraft-panel-stage=""
+    >
+      {children}
+    </div>
+  );
+}
+
+export function PanelContainer({
+  children,
+  className,
+  dragMode,
+  onPanelStateChange,
+  panelClassName,
+  panelState,
+  panelType,
+  placement,
+  ...props
+}: PanelContainerProps): React.JSX.Element {
+  const config = panelHostConfig[panelType];
+
+  if (placement === "surface") {
+    return <>{children}</>;
+  }
+
+  if (placement === "floating") {
+    return (
+      <PanelHost
+        className={panelClassName}
+        dragMode={dragMode}
+        onPositionChange={(offset) => onPanelStateChange?.({ offset })}
+        panelType={panelType}
+        position={panelState?.offset}
+        snap={{ edges: config.snapEdges }}
+      >
+        {children}
+      </PanelHost>
+    );
+  }
+
+  return (
+    <PanelStage
+      {...props}
+      className={cn(config.stageClassName, className)}
+      data-panel-type={panelType}
+    >
+      <PanelHost
+        className={panelClassName}
+        dragMode={dragMode}
+        onPositionChange={(offset) => onPanelStateChange?.({ offset })}
+        panelType={panelType}
+        position={panelState?.offset}
+        snap={{ edges: config.snapEdges }}
+      >
+        {children}
+      </PanelHost>
+    </PanelStage>
+  );
+}

package/templates/runtime/react/runtime-public-api.test.tsx

@@ -0,0 +1,132 @@
+import type * as React from "react";
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { CanvasShell } from "./canvas-shell";
+import { ControlsPanel } from "./controls-panel";
+import { ToolcraftApp } from "./toolcraft-app";
+import { ToolcraftRoot } from "./toolcraft-root";
+import { LayersPanel } from "./layers-panel";
+import { PanelContainer, PanelHost, PanelStage } from "./panel-host";
+import { TimelinePanel } from "./timeline-panel";
+import { ToolbarPanel } from "./toolbar-panel";
+
+const runtimePublicApiSchema = defineToolcraft({
+  canvas: { enabled: true },
+  panels: {},
+});
+
+describe("Toolcraft template runtime public API", () => {
+  it("keeps app assembly props narrow", () => {
+    expectTypeOf<
+      keyof React.ComponentProps<typeof ToolcraftApp>
+    >().toEqualTypeOf<
+      | "canvasContent"
+      | "className"
+      | "controlRenderers"
+      | "onPanelAction"
+      | "renderDefaultCanvasMedia"
+      | "schema"
+      | "style"
+    >();
+    expectTypeOf<
+      keyof React.ComponentProps<typeof ToolcraftRoot>
+    >().toEqualTypeOf<"children" | "initialState" | "schema">();
+  });
+
+  it("keeps runtime panel props focused on host integration", () => {
+    type RuntimePanelKeys =
+      | "className"
+      | "framed"
+      | "onPanelStateChange"
+      | "panelPlacement"
+      | "panelState";
+    type ControlsPanelKeys = RuntimePanelKeys | "controlRenderers" | "onPanelAction";
+
+    expectTypeOf<
+      keyof React.ComponentProps<typeof ControlsPanel>
+    >().toEqualTypeOf<ControlsPanelKeys>();
+    expectTypeOf<
+      keyof React.ComponentProps<typeof TimelinePanel>
+    >().toEqualTypeOf<RuntimePanelKeys | "defaultExpanded">();
+    expectTypeOf<
+      keyof React.ComponentProps<typeof ToolbarPanel>
+    >().toEqualTypeOf<RuntimePanelKeys>();
+    expectTypeOf<
+      keyof React.ComponentProps<typeof LayersPanel>
+    >().toEqualTypeOf<RuntimePanelKeys | "groupCreation">();
+  });
+
+  it("keeps shell and panel host props separate", () => {
+    expectTypeOf<
+      keyof React.ComponentProps<typeof CanvasShell>
+    >().toEqualTypeOf<"children" | "renderDefaultMedia">();
+    expectTypeOf<React.ComponentProps<typeof PanelHost>>().toHaveProperty(
+      "panelType",
+    );
+    expectTypeOf<React.ComponentProps<typeof PanelContainer>>().toHaveProperty(
+      "placement",
+    );
+    expectTypeOf<React.ComponentProps<typeof PanelStage>>().toHaveProperty(
+      "children",
+    );
+  });
+
+  it("rejects hidden runtime wiring props at compile time", () => {
+    expect(<ToolcraftApp schema={runtimePublicApiSchema} />).toBeTruthy();
+    expect(<CanvasShell />).toBeTruthy();
+    expect(<ToolbarPanel />).toBeTruthy();
+
+    const appWithInitialStateProps: React.ComponentProps<
+      typeof ToolcraftApp
+    > = {
+      // @ts-expect-error Runtime state seeding belongs to ToolcraftRoot, not the app shell.
+      initialState: {},
+      schema: runtimePublicApiSchema,
+    };
+    const appWithChildrenProps: React.ComponentProps<typeof ToolcraftApp> =
+      {
+        // @ts-expect-error ToolcraftApp is assembled from schema and does not accept children.
+        children: "Child",
+        schema: runtimePublicApiSchema,
+      };
+    const appWithToolbarThemeToggleProps: React.ComponentProps<
+      typeof ToolcraftApp
+    > = {
+      schema: runtimePublicApiSchema,
+      // @ts-expect-error Toolbar theme visibility belongs to schema.toolbar.theme.
+      toolbarThemeToggle: false,
+    };
+    const appWithCanvasSlotProps: React.ComponentProps<typeof ToolcraftApp> =
+      {
+        canvasContent: <div />,
+        onPanelAction: ({ action }) => {
+          void action.value;
+        },
+        renderDefaultCanvasMedia: false,
+        schema: runtimePublicApiSchema,
+      };
+    const canvasWithSlotProps: React.ComponentProps<typeof CanvasShell> = {
+      children: <div />,
+      renderDefaultMedia: false,
+    };
+    // @ts-expect-error Canvas upload belongs to schema.canvas.upload.
+    const canvasWithUpload = <CanvasShell upload />;
+    // @ts-expect-error CanvasShell is a runtime-owned shell, not a styled wrapper.
+    const styledCanvas = <CanvasShell className="custom" />;
+    // @ts-expect-error Toolbar history visibility belongs to schema.toolbar.history.
+    const toolbarWithHistory = <ToolbarPanel history />;
+    // @ts-expect-error Toolbar theme visibility belongs to schema.toolbar.theme.
+    const toolbarWithThemeToggle = <ToolbarPanel themeToggle={false} />;
+
+    expect(appWithInitialStateProps).toBeTruthy();
+    expect(appWithChildrenProps).toBeTruthy();
+    expect(appWithToolbarThemeToggleProps).toBeTruthy();
+    expect(appWithCanvasSlotProps).toBeTruthy();
+    expect(canvasWithSlotProps).toBeTruthy();
+    expect(canvasWithUpload).toBeTruthy();
+    expect(styledCanvas).toBeTruthy();
+    expect(toolbarWithHistory).toBeTruthy();
+    expect(toolbarWithThemeToggle).toBeTruthy();
+  });
+});

package/templates/runtime/react/settings-transfer.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import { toolcraftReducer } from "../state/reducer";
+import type { ToolcraftCommand, ToolcraftState } from "../state/types";
+import {
+  applyToolcraftSettingsPayload,
+  createToolcraftSettingsPayload,
+  parseToolcraftSettingsPayload,
+} from "./settings-transfer";
+
+function createSettingsSchema() {
+  return defineToolcraft({
+    canvas: { enabled: true, size: { height: 720, unit: "px", width: 1280 } },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              prompt: {
+                defaultValue: "Initial prompt",
+                label: "Prompt",
+                target: "generation.prompt",
+                type: "text",
+              },
+              opacity: {
+                defaultValue: 75,
+                label: "Opacity",
+                target: "style.opacity",
+                type: "slider",
+              },
+            },
+            title: "Generation",
+          },
+        ],
+        title: "Settings Test",
+      },
+      timeline: { mode: "playback" },
+    },
+    settingsTransfer: {
+      appId: "Settings Test",
+      enabled: true,
+    },
+  });
+}
+
+function reduceWithCommands(
+  initialState: ToolcraftState,
+  run: (dispatch: (command: ToolcraftCommand) => void) => void,
+): ToolcraftState {
+  let state = initialState;
+
+  run((command) => {
+    state = toolcraftReducer(state, command);
+  });
+
+  return state;
+}
+
+describe("settings transfer", () => {
+  it("creates and parses a versioned app-specific payload", () => {
+    const schema = createSettingsSchema();
+    const state = createToolcraftState(schema, {
+      values: {
+        "generation.prompt": "Exported prompt",
+        "style.opacity": 24,
+      },
+    });
+
+    const payload = createToolcraftSettingsPayload(state);
+
+    expect(payload).toMatchObject({
+      appId: "settings-test",
+      canvas: {
+        size: { height: 720, unit: "px", width: 1280 },
+      },
+      source: "toolcraft-settings",
+      values: {
+        "generation.prompt": "Exported prompt",
+        "style.opacity": 24,
+      },
+      version: 1,
+    });
+    expect(parseToolcraftSettingsPayload(schema, payload)).toEqual(payload);
+    expect(
+      parseToolcraftSettingsPayload(
+        schema,
+        { ...payload, appId: "other-app" },
+      ),
+    ).toBeNull();
+  });
+
+  it("applies imported values, canvas size, and timeline through runtime commands", () => {
+    const schema = createSettingsSchema();
+    const initialState = createToolcraftState(schema, {
+      timeline: {
+        currentTimeSeconds: 0,
+        durationSeconds: 8,
+        expanded: false,
+        isLooping: true,
+        isPlaying: true,
+      },
+      values: {
+        "generation.prompt": "Initial prompt",
+        "style.opacity": 75,
+      },
+    });
+    const payload = {
+      ...createToolcraftSettingsPayload(initialState),
+      canvas: {
+        size: { height: 900, unit: "px" as const, width: 1600 },
+      },
+      timeline: {
+        currentTimeSeconds: 3,
+        durationSeconds: 12,
+        expanded: true,
+        isLooping: false,
+        isPlaying: false as const,
+      },
+      values: {
+        "generation.prompt": "Imported prompt",
+        "unknown.target": "Ignored",
+      },
+    };
+
+    const state = reduceWithCommands(initialState, (dispatch) => {
+      applyToolcraftSettingsPayload({ dispatch, state: initialState }, payload);
+    });
+
+    expect(state.values["generation.prompt"]).toBe("Imported prompt");
+    expect(state.values["unknown.target"]).toBeUndefined();
+    expect(state.canvas.size).toEqual({ height: 900, unit: "px", width: 1600 });
+    expect(state.timeline).toMatchObject({
+      currentTimeSeconds: 3,
+      durationSeconds: 12,
+      expanded: true,
+      isLooping: false,
+      isPlaying: false,
+    });
+    expect(state.history.undo).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          group: "settings.import",
+          label: "Import settings",
+        }),
+      ]),
+    );
+  });
+});