@pixel-point/toolcraft 0.0.13 → 0.0.15

package/templates/runtime/react/controls-panel/__tests__/controls-panel.vector-layout.test.tsx

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineToolcraft,
+  renderControlsPanelWithSchema,
+} from "../testing/controls-panel-test-utils";
+
+describe("ControlsPanel vector pad layout", () => {
+  it("uses a square vector pad when vector is the only vector control in the panel", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                position: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Position",
+                  target: "geometry.position",
+                  type: "vector",
+                },
+              },
+              title: "Geometry",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema);
+
+    expect(
+      container
+        .querySelector('[aria-label="Position X/Y pad"]')
+        ?.getAttribute("data-vector-pad-shape"),
+    ).toBe("square");
+  });
+
+  it("keeps compact vector pads when the panel has multiple vector controls", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                origin: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Origin",
+                  target: "geometry.origin",
+                  type: "vector",
+                },
+                target: {
+                  defaultValue: { x: "0.50", y: "-0.50" },
+                  label: "Target",
+                  target: "geometry.target",
+                  type: "vector",
+                },
+              },
+              title: "Geometry",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema);
+
+    expect(
+      [...container.querySelectorAll("[data-vector-pad-shape]")].map((pad) =>
+        pad.getAttribute("data-vector-pad-shape"),
+      ),
+    ).toEqual(["compact", "compact"]);
+  });
+
+  it("passes supported vector pad variants from schema to the vector pad", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                whiteBalance: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "White Balance",
+                  target: "color.whiteBalance",
+                  type: "vector",
+                  variant: "whiteBalance",
+                },
+                colorBalance: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Color Balance",
+                  target: "color.balance",
+                  type: "vector",
+                  variant: "colorBalance",
+                },
+                chromaOffset: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Chroma Offset",
+                  target: "effect.chromaOffset",
+                  type: "vector",
+                  variant: "chromaOffset",
+                },
+                toneBias: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Tone Bias",
+                  target: "tone.bias",
+                  type: "vector",
+                  variant: "toneBias",
+                },
+                unknown: {
+                  defaultValue: { x: "0.00", y: "0.00" },
+                  label: "Unknown",
+                  target: "effect.unknown",
+                  type: "vector",
+                  variant: "unknown",
+                },
+              },
+              title: "Color",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema);
+
+    expect(
+      [...container.querySelectorAll("[data-vector-pad-variant]")].map((pad) =>
+        pad.getAttribute("data-vector-pad-variant"),
+      ),
+    ).toEqual([
+      "whiteBalance",
+      "colorBalance",
+      "chromaOffset",
+      "toneBias",
+      "default",
+    ]);
+    expect(
+      [...container.querySelectorAll("[data-vector-pad-coordinate-mode]")].map((pad) =>
+        pad.getAttribute("data-vector-pad-coordinate-mode"),
+      ),
+    ).toEqual([
+      "cartesian",
+      "cartesian",
+      "cartesian",
+      "cartesian",
+      "screen",
+    ]);
+  });
+});

package/templates/runtime/react/controls-panel/actions/controls-panel-actions.ts

@@ -0,0 +1,172 @@
+"use client";
+
+import * as React from "react";
+
+import type {
+  ToolcraftActionCommand,
+  ToolcraftActionSchema,
+} from "../../../schema/types";
+import type {
+  ToolcraftCommand,
+  ToolcraftState,
+} from "../../../state/types";
+import type { ActionControlRunAction } from "../renderers/controls-panel-action-renderer";
+
+export type ToolcraftPanelActionContext = {
+  action: ToolcraftActionSchema;
+  dispatch: React.Dispatch<ToolcraftCommand>;
+  reportProgress: (progress: number) => void;
+  state: ToolcraftState;
+};
+
+export type ToolcraftPanelActionHandler = (
+  context: ToolcraftPanelActionContext,
+) => PromiseLike<unknown> | void;
+
+type FooterActionProgressEntry = {
+  id: number;
+  progress: number | null;
+};
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function noopReportProgress(): void {}
+
+function clampFooterActionProgress(progress: number): number {
+  if (!Number.isFinite(progress)) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(1, progress));
+}
+
+function getActionCommand(action: ToolcraftActionSchema): ToolcraftActionCommand | null {
+  if (action.command) {
+    return action.command;
+  }
+
+  switch (action.value.toLowerCase()) {
+    case "apply":
+      return "controls.apply";
+    case "reset":
+      return "controls.reset";
+    default:
+      return null;
+  }
+}
+
+export function useControlsPanelActions({
+  dispatch,
+  onPanelAction,
+  state,
+}: {
+  dispatch: React.Dispatch<ToolcraftCommand>;
+  onPanelAction?: ToolcraftPanelActionHandler;
+  state: ToolcraftState;
+}): {
+  runAction: ActionControlRunAction;
+  stickyFooterActive: boolean;
+  stickyFooterProgress: number | null;
+} {
+  const nextFooterActionIdRef = React.useRef(0);
+  const [footerActionProgressEntries, setFooterActionProgressEntries] =
+    React.useState<readonly FooterActionProgressEntry[]>([]);
+  const stickyFooterProgress = React.useMemo(() => {
+    for (let index = footerActionProgressEntries.length - 1; index >= 0; index -= 1) {
+      const progress = footerActionProgressEntries[index]?.progress;
+
+      if (typeof progress === "number") {
+        return progress;
+      }
+    }
+
+    return null;
+  }, [footerActionProgressEntries]);
+
+  function createFooterActionProgressTracker(): {
+    reportProgress: (progress: number) => void;
+    trackResult: (result: PromiseLike<unknown> | void) => void;
+  } {
+    const id = nextFooterActionIdRef.current;
+    nextFooterActionIdRef.current += 1;
+
+    let latestProgress: number | null = null;
+    let isTracked = false;
+
+    function reportProgress(progress: number): void {
+      latestProgress = clampFooterActionProgress(progress);
+
+      if (!isTracked) {
+        return;
+      }
+
+      setFooterActionProgressEntries((entries) =>
+        entries.map((entry) =>
+          entry.id === id ? { ...entry, progress: latestProgress } : entry,
+        ),
+      );
+    }
+
+    function trackResult(result: PromiseLike<unknown> | void): void {
+      if (!isPromiseLike(result)) {
+        return;
+      }
+
+      isTracked = true;
+      setFooterActionProgressEntries((entries) => [
+        ...entries,
+        { id, progress: latestProgress },
+      ]);
+
+      void Promise.resolve(result)
+        .catch((error: unknown) => {
+          console.error("Toolcraft panel action failed.", error);
+        })
+        .finally(() => {
+          setFooterActionProgressEntries((entries) =>
+            entries.filter((entry) => entry.id !== id),
+          );
+        });
+    }
+
+    return { reportProgress, trackResult };
+  }
+
+  function runAction(
+    action: ToolcraftActionSchema,
+    options: { trackFooterPending?: boolean } = {},
+  ): void {
+    const command = action.command ?? (onPanelAction ? null : getActionCommand(action));
+
+    if (command) {
+      dispatch({ type: command });
+      return;
+    }
+
+    const footerActionProgressTracker = options.trackFooterPending
+      ? createFooterActionProgressTracker()
+      : null;
+    const result = onPanelAction?.({
+      action,
+      dispatch,
+      reportProgress:
+        footerActionProgressTracker?.reportProgress ?? noopReportProgress,
+      state,
+    });
+
+    footerActionProgressTracker?.trackResult(result);
+  }
+
+  return {
+    runAction,
+    stickyFooterActive: footerActionProgressEntries.length > 0,
+    stickyFooterProgress,
+  };
+}

package/templates/runtime/react/{control-conditions.ts → controls-panel/conditions/control-conditions.ts}

@@ -1,12 +1,14 @@
 import {
   getToolcraftCanvasSizeTargetDimension,
-} from "../schema/runtime-targets";
+  isToolcraftTimelinePanelExtendedTarget,
+  isToolcraftTimelinePanelVisibleTarget,
+} from "../../../schema/runtime-targets";
 import type {
   ToolcraftControlConditionSchema,
   ToolcraftControlSchema,
   ToolcraftControlSectionSchema,
-} from "../schema/types";
-import type { ToolcraftState } from "../state/types";
+} from "../../../schema/types";
+import type { ToolcraftState } from "../../../state/types";
 
 function valuesEqual(first: unknown, second: unknown): boolean {
   if (Object.is(first, second)) {
@@ -80,6 +82,14 @@ export function getToolcraftTargetValue(
 ): unknown {
   const canvasSizeDimension = getToolcraftCanvasSizeTargetDimension(target);
 
+  if (isToolcraftTimelinePanelExtendedTarget(target)) {
+    return state.panels.timeline.extended === true;
+  }
+
+  if (isToolcraftTimelinePanelVisibleTarget(target)) {
+    return state.panels.timeline.hidden !== true;
+  }
+
   return canvasSizeDimension
     ? state.canvas.size[canvasSizeDimension]
     : (state.values[target] ??
@@ -164,3 +174,16 @@ export function isToolcraftControlVisible(
     ? toolcraftConditionMatches(state, control.visibleWhen)
     : true;
 }
+
+export function isToolcraftControlDisabled(
+  state: ToolcraftState,
+  control: ToolcraftControlSchema,
+): boolean {
+  if (control.disabled) {
+    return true;
+  }
+
+  return control.disabledWhen
+    ? toolcraftConditionMatches(state, control.disabledWhen)
+    : false;
+}

package/templates/runtime/react/{control-renderers.ts → controls-panel/control-renderers.ts}

@@ -3,8 +3,8 @@
 import type * as React from "react";
 import type { ControlChangeMeta } from "@repo/ui";
 
-import type { ToolcraftControlSchema } from "../schema/types";
-import type { ToolcraftCommand, ToolcraftState } from "../state/types";
+import type { ToolcraftControlSchema } from "../../schema/types";
+import type { ToolcraftCommand, ToolcraftState } from "../../state/types";
 
 export type ToolcraftCustomControlSetValue<Value = unknown> = (
   value: Value,

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

@@ -0,0 +1,250 @@
+"use client";
+
+import * as React from "react";
+import {
+  Panel,
+  type ControlChangeMeta,
+} from "@repo/ui";
+
+import type {
+  ToolcraftControlSectionSchema,
+  ToolcraftControlSchema,
+} from "../../schema/types";
+import type {
+  ToolcraftCommand,
+  ToolcraftPanelState,
+} from "../../state/types";
+import {
+  getToolcraftTargetValue,
+  isToolcraftControlDisabled,
+  isToolcraftControlVisible,
+  isToolcraftSectionVisible,
+} from "./conditions/control-conditions";
+import {
+  type ToolcraftPanelActionHandler,
+  useControlsPanelActions,
+} from "./actions/controls-panel-actions";
+import { createControlsPanelKeyframeActions } from "./keyframes/controls-panel-keyframes";
+import { renderControlsPanelSection } from "./layout/controls-panel-section";
+import { PanelContainer } from "../panel-host/panel-host";
+import type { PanelPlacement, PanelStateChange } from "../panel-host/panel-host-types";
+import type { ToolcraftControlRendererMap } from "./control-renderers";
+import { formatControlValueLabel } from "./values/controls-panel-values";
+import {
+  type ControlEntry,
+  countControlsByType,
+  getControlName,
+  getControlsRecord,
+} from "./layout/controls-panel-layout";
+import {
+  getControlsPanelSectionCollapseStorageKey,
+  readControlsPanelCollapsedSections,
+  writeControlsPanelCollapsedSections,
+} from "./layout/controls-panel-collapse-storage";
+import { useToolcraft } from "../app-shell/use-toolcraft";
+
+export type {
+  ToolcraftPanelActionContext,
+  ToolcraftPanelActionHandler,
+} from "./actions/controls-panel-actions";
+
+export type ControlsPanelProps = {
+  className?: string;
+  controlRenderers?: ToolcraftControlRendererMap;
+  framed?: boolean;
+  onPanelAction?: ToolcraftPanelActionHandler;
+  onPanelStateChange?: PanelStateChange;
+  panelPlacement?: PanelPlacement;
+  panelState?: ToolcraftPanelState;
+};
+
+function cn(...classNames: Array<string | false | null | undefined>): string {
+  return classNames.filter(Boolean).join(" ");
+}
+
+export function ControlsPanel({
+  className,
+  controlRenderers,
+  framed = true,
+  onPanelAction,
+  onPanelStateChange,
+  panelPlacement,
+  panelState,
+}: ControlsPanelProps): React.JSX.Element | null {
+  const { dispatch, state } = useToolcraft();
+  const {
+    runAction,
+    stickyFooterActive,
+    stickyFooterProgress,
+  } = useControlsPanelActions({ dispatch, onPanelAction, state });
+  const sectionCollapseStorageKey = React.useMemo(
+    () => getControlsPanelSectionCollapseStorageKey(state.schema),
+    [state.schema],
+  );
+  const [collapsedSectionByKey, setCollapsedSectionByKey] = React.useState<
+    Record<string, boolean>
+  >(() => readControlsPanelCollapsedSections(sectionCollapseStorageKey));
+  const controlsPanel = state.schema.panels.controls;
+  const keyframedControlIds = React.useMemo(
+    () => new Set(state.timeline.keyframeGroups.map((group) => group.controlId)),
+    [state.timeline.keyframeGroups],
+  );
+  const keyframeControlsEnabled = Boolean(
+    state.schema.assembly.capabilities.includes("timeline.keyframes") &&
+      state.timeline.expanded,
+  );
+
+  React.useEffect(() => {
+    setCollapsedSectionByKey(readControlsPanelCollapsedSections(sectionCollapseStorageKey));
+  }, [sectionCollapseStorageKey]);
+
+  if (!controlsPanel) {
+    return null;
+  }
+
+  const resolvedControlsPanel = controlsPanel;
+  const placement = panelPlacement ?? (framed ? "frame" : "surface");
+  const lastHistoryPatch = state.history.undo.at(-1);
+  const controlsResetKey =
+    lastHistoryPatch?.label === "Reset controls" ? state.history.undo.length : 0;
+
+  function dispatchCommand(command: ToolcraftCommand): void {
+    dispatch(command);
+  }
+
+  function setControlValue(
+    target: string,
+    value: unknown,
+    label?: string,
+    meta?: ControlChangeMeta,
+  ): void {
+    dispatchCommand({
+      history: meta?.history,
+      historyGroup: meta?.historyGroup,
+      label,
+      target,
+      type: "controls.setValue",
+      value,
+    });
+  }
+
+  function getControlValue(control: ToolcraftControlSchema): unknown {
+    return getToolcraftTargetValue(state, control.target) ?? control.defaultValue;
+  }
+
+  function isControlDisabled(control: ToolcraftControlSchema): boolean {
+    return isToolcraftControlDisabled(state, control);
+  }
+
+  function isControlVisible(control: ToolcraftControlSchema): boolean {
+    return isToolcraftControlVisible(state, control);
+  }
+
+  function isSectionVisible(section: ToolcraftControlSectionSchema): boolean {
+    return isToolcraftSectionVisible(state, section);
+  }
+
+  function getVisibleSectionEntries(
+    section: ToolcraftControlSectionSchema,
+  ): ControlEntry[] {
+    return Object.entries(section.controls).filter(([, control]) =>
+      isControlVisible(control),
+    );
+  }
+
+  const keyframeActions = createControlsPanelKeyframeActions({
+    dispatchCommand,
+    formatValueLabel: formatControlValueLabel,
+    getControlName,
+    getControlValue,
+    keyframeControlsEnabled,
+    keyframedControlIds,
+    keyframeGroups: state.timeline.keyframeGroups,
+    selectedKeyframeId: state.timeline.selectedKeyframeId,
+  });
+
+  function handleSectionCollapsedChange(
+    sectionCollapseKey: string,
+    collapsed: boolean,
+  ): void {
+    setCollapsedSectionByKey((current) => {
+      const next = {
+        ...current,
+        [sectionCollapseKey]: collapsed,
+      };
+
+      writeControlsPanelCollapsedSections(sectionCollapseStorageKey, next);
+
+      return next;
+    });
+  }
+
+  const visibleSections = resolvedControlsPanel.sections
+    .map((section) => ({
+      entries: getVisibleSectionEntries(section),
+      section,
+    }))
+    .filter(({ entries, section }) => isSectionVisible(section) && entries.length > 0);
+  const visibleControlsPanelSections = visibleSections.map(({ entries, section }) => ({
+    ...section,
+    controls: getControlsRecord(entries),
+  }));
+  const vectorControlCount = countControlsByType(visibleControlsPanelSections, "vector");
+  const vectorPadShape = vectorControlCount === 1 ? "square" : "compact";
+
+  const panel = (
+    <Panel
+      className={cn(
+        "shrink-0",
+        placement === "frame" && "max-h-none",
+        className,
+      )}
+      collapsed={panelState?.collapsed}
+      contentTransitionSuppressionKey={
+        keyframeControlsEnabled ? "keyframes" : "plain"
+      }
+      key={controlsResetKey}
+      onCollapsedChange={(collapsed) => onPanelStateChange?.({ collapsed })}
+      onResetControls={() => dispatchCommand({ type: "controls.reset" })}
+      stickyFooterActive={stickyFooterActive}
+      stickyFooterProgress={stickyFooterProgress}
+      title={resolvedControlsPanel.title}
+    >
+      {visibleSections.map(({ entries, section }, sectionIndex) =>
+        renderControlsPanelSection({
+          collapsedSectionByKey,
+          controlRenderers,
+          dispatch,
+          dispatchCommand,
+          entries,
+          getControlValue,
+          isControlDisabled,
+          keyframeActions,
+          onSectionCollapsedChange: handleSectionCollapsedChange,
+          panelSectionKey: `${section.title ?? "section"}-${sectionIndex}`,
+          runAction,
+          section,
+          sectionIndex,
+          setControlValue,
+          state,
+          vectorPadShape,
+        }),
+      )}
+    </Panel>
+  );
+
+  if (placement === "surface") {
+    return panel;
+  }
+
+  return (
+    <PanelContainer
+      onPanelStateChange={onPanelStateChange}
+      panelState={panelState}
+      panelType="controls"
+      placement={placement}
+    >
+      {panel}
+    </PanelContainer>
+  );
+}