@pixel-point/toolcraft 0.0.2

package/templates/runtime/react/toolcraft-app.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import * as React from "react";
+
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import { CanvasShell } from "./canvas-shell";
+import {
+  ControlsPanel,
+  type ToolcraftPanelActionHandler,
+} from "./controls-panel";
+import type { ToolcraftControlRendererMap } from "./control-renderers";
+import { ToolcraftRoot } from "./toolcraft-root";
+import { LayersPanel } from "./layers-panel";
+import { TimelinePanel } from "./timeline-panel";
+import { ToolbarPanel } from "./toolbar-panel";
+
+export type ToolcraftAppProps = {
+  canvasContent?: React.ReactNode;
+  className?: string;
+  controlRenderers?: ToolcraftControlRendererMap;
+  onPanelAction?: ToolcraftPanelActionHandler;
+  renderDefaultCanvasMedia?: boolean;
+  schema: ResolvedToolcraftAppSchema;
+  style?: React.CSSProperties;
+};
+
+const toolcraftMinAppWidthPx = 1024;
+
+function cn(...classNames: Array<string | false | null | undefined>): string {
+  return classNames.filter(Boolean).join(" ");
+}
+
+export function ToolcraftApp({
+  canvasContent,
+  className,
+  controlRenderers,
+  onPanelAction,
+  renderDefaultCanvasMedia = true,
+  schema,
+  style,
+}: ToolcraftAppProps): React.JSX.Element {
+  const surfaces = schema.assembly.surfaces;
+
+  return (
+    <ToolcraftRoot schema={schema}>
+      <div
+        className={cn(
+          "relative min-h-[640px] w-full overflow-hidden bg-[color:var(--background)]",
+          className,
+        )}
+        data-slot="toolcraft-runtime-app"
+        style={{
+          ...style,
+          minWidth: toolcraftMinAppWidthPx,
+        }}
+      >
+        {surfaces.canvas.enabled ? (
+          <CanvasShell renderDefaultMedia={renderDefaultCanvasMedia}>
+            {canvasContent}
+          </CanvasShell>
+        ) : null}
+        {surfaces.panels.layers?.enabled ? (
+          <LayersPanel panelPlacement="floating" />
+        ) : null}
+        {surfaces.panels.controls?.enabled ? (
+          <ControlsPanel
+            controlRenderers={controlRenderers}
+            onPanelAction={onPanelAction}
+            panelPlacement="floating"
+          />
+        ) : null}
+        {surfaces.panels.timeline?.enabled ? (
+          <TimelinePanel panelPlacement="floating" />
+        ) : null}
+        {surfaces.panels.toolbar.enabled ? (
+          <ToolbarPanel panelPlacement="floating" />
+        ) : null}
+      </div>
+    </ToolcraftRoot>
+  );
+}

package/templates/runtime/react/toolcraft-root.test.tsx

@@ -0,0 +1,347 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { ToolcraftRoot } from "./toolcraft-root";
+import { useToolcraft } from "./use-toolcraft";
+
+const previousToolcraftNamespace = ["creative", "apps", "kit"].join("-");
+
+function Probe() {
+  const { dispatch, state } = useToolcraft();
+
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        dispatch({
+          target: "selectedLayer.opacity",
+          type: "controls.setValue",
+          value: 50,
+        })
+      }
+    >
+      {String(state.values["selectedLayer.opacity"])}
+    </button>
+  );
+}
+
+function ResetProbe() {
+  const { dispatch, state } = useToolcraft();
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() =>
+          dispatch({
+            target: "selectedLayer.opacity",
+            type: "controls.setValue",
+            value: 50,
+          })
+        }
+      >
+        {String(state.values["selectedLayer.opacity"])}
+      </button>
+      <button type="button" onClick={() => dispatch({ type: "controls.reset" })}>
+        Reset
+      </button>
+    </div>
+  );
+}
+
+function PanelPersistenceProbe() {
+  const { dispatch, state } = useToolcraft();
+
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        dispatch({
+          offset: { x: 72, y: -24 },
+          panelId: "controls",
+          type: "panels.setOffset",
+        })
+      }
+    >
+      {state.panels.controls.offset.x},{state.panels.controls.offset.y}
+    </button>
+  );
+}
+
+function createPersistentSchema() {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              opacity: {
+                defaultValue: 75,
+                target: "selectedLayer.opacity",
+                type: "slider",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+    },
+    persistence: {
+      include: ["values", "panels"],
+      key: "toolcraft:root-test:state:v1",
+      storage: "localStorage",
+      version: 1,
+    },
+  });
+}
+
+function createHistorySchema(history = true) {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              opacity: {
+                defaultValue: 75,
+                target: "selectedLayer.opacity",
+                type: "slider",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+    },
+    toolbar: { history },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+});
+
+describe("ToolcraftRoot", () => {
+  it("provides editor state and dispatch to children", async () => {
+    render(
+      <ToolcraftRoot
+        schema={defineToolcraft({
+          canvas: { enabled: true },
+          panels: {
+            controls: {
+              sections: [
+                {
+                  controls: {
+                    opacity: {
+                      defaultValue: 75,
+                      target: "selectedLayer.opacity",
+                      type: "slider",
+                    },
+                  },
+                },
+              ],
+              title: "Controls",
+            },
+          },
+        })}
+      >
+        <Probe />
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "75" }));
+
+    expect(await screen.findByRole("button", { name: "50" })).toBeTruthy();
+  });
+
+  it("restores persisted values before first render", () => {
+    const schema = createPersistentSchema();
+
+    window.localStorage.setItem(
+      "toolcraft:root-test:state:v1",
+      JSON.stringify({
+        state: { values: { "selectedLayer.opacity": 33 } },
+        version: 1,
+      }),
+    );
+
+    render(
+      <ToolcraftRoot schema={schema}>
+        <Probe />
+      </ToolcraftRoot>,
+    );
+
+    expect(screen.getByRole("button", { name: "33" })).toBeTruthy();
+  });
+
+  it("migrates persisted values from the previous storage namespace", () => {
+    const schema = createPersistentSchema();
+    const previousStorageKey = `${previousToolcraftNamespace}:root-test:state:v1`;
+
+    window.localStorage.setItem(
+      previousStorageKey,
+      JSON.stringify({
+        state: { values: { "selectedLayer.opacity": 44 } },
+        version: 1,
+      }),
+    );
+
+    render(
+      <ToolcraftRoot schema={schema}>
+        <Probe />
+      </ToolcraftRoot>,
+    );
+
+    expect(screen.getByRole("button", { name: "44" })).toBeTruthy();
+    expect(window.localStorage.getItem("toolcraft:root-test:state:v1")).toBe(
+      JSON.stringify({
+        state: { values: { "selectedLayer.opacity": 44 } },
+        version: 1,
+      }),
+    );
+    expect(window.localStorage.getItem(previousStorageKey)).toBeNull();
+  });
+
+  it("persists runtime values and reset results through schema policy", async () => {
+    const schema = createPersistentSchema();
+
+    render(
+      <ToolcraftRoot schema={schema}>
+        <ResetProbe />
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "75" }));
+
+    await waitFor(() => {
+      expect(
+        JSON.parse(window.localStorage.getItem("toolcraft:root-test:state:v1") ?? "{}"),
+      ).toMatchObject({
+        state: { values: { "selectedLayer.opacity": 50 } },
+        version: 1,
+      });
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Reset" }));
+
+    await waitFor(() => {
+      expect(
+        JSON.parse(window.localStorage.getItem("toolcraft:root-test:state:v1") ?? "{}"),
+      ).toMatchObject({
+        state: { values: { "selectedLayer.opacity": 75 } },
+        version: 1,
+      });
+    });
+  });
+
+  it("restores dragged panel offsets from the app persistence policy before first render", async () => {
+    const schema = createPersistentSchema();
+    const firstRender = render(
+      <ToolcraftRoot schema={schema}>
+        <PanelPersistenceProbe />
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "0,0" }));
+
+    await waitFor(() => {
+      expect(
+        JSON.parse(window.localStorage.getItem("toolcraft:root-test:state:v1") ?? "{}"),
+      ).toMatchObject({
+        state: { panels: { controls: { offset: { x: 72, y: -24 } } } },
+        version: 1,
+      });
+    });
+
+    firstRender.unmount();
+
+    render(
+      <ToolcraftRoot schema={schema}>
+        <PanelPersistenceProbe />
+      </ToolcraftRoot>,
+    );
+
+    expect(screen.getByRole("button", { name: "72,-24" })).toBeTruthy();
+  });
+
+  it("binds runtime undo and redo to keyboard shortcuts when history is enabled", async () => {
+    render(
+      <ToolcraftRoot schema={createHistorySchema()}>
+        <Probe />
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "75" }));
+    expect(await screen.findByRole("button", { name: "50" })).toBeTruthy();
+
+    fireEvent.keyDown(document, { key: "z", metaKey: true });
+    expect(screen.getByRole("button", { name: "75" })).toBeTruthy();
+
+    fireEvent.keyDown(document, { key: "z", metaKey: true, shiftKey: true });
+    expect(screen.getByRole("button", { name: "50" })).toBeTruthy();
+
+    fireEvent.keyDown(document, { key: "z", ctrlKey: true });
+    expect(screen.getByRole("button", { name: "75" })).toBeTruthy();
+
+    fireEvent.keyDown(document, { key: "y", ctrlKey: true });
+    expect(screen.getByRole("button", { name: "50" })).toBeTruthy();
+  });
+
+  it("does not hijack undo shortcuts while the user is typing into editable controls", async () => {
+    render(
+      <ToolcraftRoot schema={createHistorySchema()}>
+        <div>
+          <Probe />
+          <input aria-label="Text value" defaultValue="hello" />
+          <span
+            aria-label="Editable value"
+            contentEditable
+            role="textbox"
+            suppressContentEditableWarning
+          >
+            editable
+          </span>
+        </div>
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "75" }));
+    expect(await screen.findByRole("button", { name: "50" })).toBeTruthy();
+
+    fireEvent.keyDown(screen.getByRole("textbox", { name: "Text value" }), {
+      key: "z",
+      metaKey: true,
+    });
+    expect(screen.getByRole("button", { name: "50" })).toBeTruthy();
+
+    fireEvent.keyDown(screen.getByRole("textbox", { name: "Editable value" }), {
+      key: "z",
+      metaKey: true,
+    });
+    expect(screen.getByRole("button", { name: "50" })).toBeTruthy();
+  });
+
+  it("does not register history shortcuts when toolbar history is disabled", async () => {
+    render(
+      <ToolcraftRoot schema={createHistorySchema(false)}>
+        <Probe />
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "75" }));
+    expect(await screen.findByRole("button", { name: "50" })).toBeTruthy();
+
+    fireEvent.keyDown(document, { key: "z", metaKey: true });
+    expect(screen.getByRole("button", { name: "50" })).toBeTruthy();
+  });
+});

package/templates/runtime/react/toolcraft-root.tsx

@@ -0,0 +1,203 @@
+"use client";
+
+import * as React from "react";
+
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import { createToolcraftState } from "../state/create-template-state";
+import {
+  createToolcraftPersistenceSnapshot,
+  getToolcraftPersistenceKey,
+  mergeToolcraftInitialState,
+  parseToolcraftPersistenceSnapshot,
+} from "../state/persistence";
+import { toolcraftReducer } from "../state/reducer";
+import type {
+  ToolcraftCommand,
+  ToolcraftInitialState,
+  ToolcraftState,
+} from "../state/types";
+import { readToolcraftLocalStorageValue } from "./storage-key-migration";
+import { ToolcraftThemeProvider } from "./theme-runtime";
+
+export type ToolcraftContextValue = {
+  dispatch: React.Dispatch<ToolcraftCommand>;
+  state: ToolcraftState;
+};
+
+export const ToolcraftContext = React.createContext<ToolcraftContextValue | null>(null);
+
+export type ToolcraftRootProps = {
+  children: React.ReactNode;
+  initialState?: ToolcraftInitialState;
+  schema: ResolvedToolcraftAppSchema;
+};
+
+function readPersistedInitialState(
+  schema: ResolvedToolcraftAppSchema,
+): ToolcraftInitialState | undefined {
+  const storageKey = getToolcraftPersistenceKey(schema.persistence);
+
+  if (!storageKey || typeof window === "undefined") {
+    return undefined;
+  }
+
+  try {
+    return parseToolcraftPersistenceSnapshot(
+      schema,
+      readToolcraftLocalStorageValue(storageKey),
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function writePersistedState(
+  schema: ResolvedToolcraftAppSchema,
+  state: ToolcraftState,
+): void {
+  const storageKey = getToolcraftPersistenceKey(schema.persistence);
+
+  if (!storageKey || typeof window === "undefined") {
+    return;
+  }
+
+  const snapshot = createToolcraftPersistenceSnapshot(state, schema.persistence);
+
+  if (!snapshot) {
+    return;
+  }
+
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify(snapshot));
+  } catch {
+    // Persistence is best-effort; runtime state stays authoritative when storage is unavailable.
+  }
+}
+
+function isEditableKeyboardTarget(target: EventTarget | null): boolean {
+  if (!target || typeof target !== "object") {
+    return false;
+  }
+
+  const candidate = target as {
+    closest?: (selector: string) => Element | null;
+    isContentEditable?: boolean;
+    tagName?: string;
+  };
+
+  if (candidate.isContentEditable) {
+    return true;
+  }
+
+  if (typeof candidate.closest === "function" && candidate.closest("[contenteditable='true']")) {
+    return true;
+  }
+
+  const tagName = candidate.tagName?.toLowerCase();
+
+  return tagName === "input" || tagName === "textarea" || tagName === "select";
+}
+
+function isUndoShortcut(event: KeyboardEvent): boolean {
+  return (
+    (event.metaKey || event.ctrlKey) &&
+    !event.shiftKey &&
+    !event.altKey &&
+    event.key.toLowerCase() === "z"
+  );
+}
+
+function isRedoShortcut(event: KeyboardEvent): boolean {
+  const key = event.key.toLowerCase();
+
+  return (
+    (event.metaKey || event.ctrlKey) &&
+    !event.altKey &&
+    ((event.shiftKey && key === "z") || (!event.metaKey && event.ctrlKey && key === "y"))
+  );
+}
+
+export function ToolcraftRoot({
+  children,
+  initialState,
+  schema,
+}: ToolcraftRootProps) {
+  const [state, dispatch] = React.useReducer(
+    toolcraftReducer,
+    { initialState, schema },
+    ({ initialState, schema }) =>
+      createToolcraftState(
+        schema,
+        mergeToolcraftInitialState(readPersistedInitialState(schema), initialState),
+      ),
+  );
+  const latestStateRef = React.useRef(state);
+  const value = React.useMemo(() => ({ dispatch, state }), [dispatch, state]);
+
+  React.useEffect(() => {
+    latestStateRef.current = state;
+  }, [state]);
+
+  React.useEffect(() => {
+    if (!schema.toolbar.history || typeof document === "undefined") {
+      return undefined;
+    }
+
+    const handleDocumentKeyDown = (event: KeyboardEvent): void => {
+      if (event.defaultPrevented || isEditableKeyboardTarget(event.target)) {
+        return;
+      }
+
+      if (isUndoShortcut(event)) {
+        event.preventDefault();
+        dispatch({ type: "history.undo" });
+        return;
+      }
+
+      if (isRedoShortcut(event)) {
+        event.preventDefault();
+        dispatch({ type: "history.redo" });
+      }
+    };
+
+    document.addEventListener("keydown", handleDocumentKeyDown);
+
+    return () => {
+      document.removeEventListener("keydown", handleDocumentKeyDown);
+    };
+  }, [dispatch, schema.toolbar.history]);
+
+  React.useEffect(() => {
+    if (schema.persistence.storage !== "localStorage") {
+      return undefined;
+    }
+
+    const persistTimer = window.setTimeout(() => {
+      writePersistedState(schema, state);
+    }, 120);
+
+    return () => window.clearTimeout(persistTimer);
+  }, [schema, state]);
+
+  React.useEffect(() => {
+    if (schema.persistence.storage !== "localStorage") {
+      return undefined;
+    }
+
+    const handlePageHide = () => {
+      writePersistedState(schema, latestStateRef.current);
+    };
+
+    window.addEventListener("pagehide", handlePageHide);
+
+    return () => {
+      window.removeEventListener("pagehide", handlePageHide);
+    };
+  }, [schema]);
+
+  return (
+    <ToolcraftThemeProvider>
+      <ToolcraftContext.Provider value={value}>{children}</ToolcraftContext.Provider>
+    </ToolcraftThemeProvider>
+  );
+}

package/templates/runtime/react/use-toolcraft.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import * as React from "react";
+
+import {
+  evaluateToolcraftTimelineValue,
+  evaluateToolcraftTimelineValues,
+} from "../state/keyframe-evaluation";
+import { ToolcraftContext } from "./toolcraft-root";
+
+export function useToolcraft() {
+  const context = React.useContext(ToolcraftContext);
+
+  if (!context) {
+    throw new Error("useToolcraft must be used inside ToolcraftRoot");
+  }
+
+  return context;
+}
+
+export function useToolcraftValue(target: string): unknown {
+  return useToolcraft().state.values[target];
+}
+
+export function useToolcraftEvaluatedValues(timeSeconds?: number): Record<string, unknown> {
+  const { state } = useToolcraft();
+
+  return React.useMemo(
+    () => evaluateToolcraftTimelineValues(state, timeSeconds),
+    [state, timeSeconds],
+  );
+}
+
+export function useToolcraftEvaluatedValue(target: string, timeSeconds?: number): unknown {
+  const { state } = useToolcraft();
+
+  return React.useMemo(
+    () => evaluateToolcraftTimelineValue(state, target, timeSeconds),
+    [state, target, timeSeconds],
+  );
+}