@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/runtime/schema/assembly-contract.ts

@@ -0,0 +1,271 @@
+import { TOOLCRAFT_COMPONENT_CONTRACTS } from "../contracts/component-contracts";
+import type {
+  ResolvedToolcraftAppSchema,
+  ResolvedToolcraftPanelsSchema,
+  ToolcraftAssemblyCapability,
+  ToolcraftAssemblyCommand,
+  ToolcraftAssemblyComponentId,
+  ToolcraftAssemblyContract,
+  ToolcraftAssemblyPanelContract,
+  ToolcraftToolbarSchema,
+} from "./types";
+
+type PanelContract = {
+  capabilities?: readonly string[];
+  defaultPlacement: ToolcraftAssemblyPanelContract["defaultPlacement"];
+  snapEdges: ToolcraftAssemblyPanelContract["snapEdges"];
+  visualComponent: string;
+};
+
+function unique<const Value extends string>(values: readonly Value[]): Value[] {
+  return Array.from(new Set(values));
+}
+
+function getPanelDragMode(
+  contract: { capabilities?: readonly string[] },
+): ToolcraftAssemblyPanelContract["dragMode"] {
+  return contract.capabilities?.includes("dragMode:handle") ? "handle" : "panel";
+}
+
+function createPanelAssemblyContract({
+  capabilities = [],
+  commands = [],
+  contract,
+  enabled,
+}: {
+  capabilities?: readonly ToolcraftAssemblyCapability[];
+  commands?: readonly ToolcraftAssemblyCommand[];
+  contract: PanelContract;
+  enabled: boolean;
+}): ToolcraftAssemblyPanelContract {
+  const panelCapabilities = enabled
+    ? unique<ToolcraftAssemblyCapability>([
+        "panels.draggable",
+        "panels.snap",
+        "panels.doubleClickReset",
+        ...capabilities,
+      ])
+    : [];
+  const panelCommands = enabled
+    ? unique<ToolcraftAssemblyCommand>([
+        "panels.setOffset",
+        "panels.setHidden",
+        "panels.resetOffset",
+        ...commands,
+      ])
+    : [];
+
+  return {
+    capabilities: panelCapabilities,
+    commands: panelCommands,
+    defaultPlacement: contract.defaultPlacement,
+    dragMode: getPanelDragMode(contract),
+    enabled,
+    requiredWrapper: "PanelHost",
+    snapEdges: contract.snapEdges,
+    visualComponent: contract.visualComponent,
+  };
+}
+
+export function createToolcraftAssemblyContract({
+  canvas,
+  panels,
+  toolbar,
+}: {
+  canvas: ResolvedToolcraftAppSchema["canvas"];
+  panels: ResolvedToolcraftPanelsSchema;
+  toolbar: Required<ToolcraftToolbarSchema>;
+}): ToolcraftAssemblyContract {
+  const components: ToolcraftAssemblyComponentId[] = [];
+  const capabilities: ToolcraftAssemblyCapability[] = [];
+  const commands: ToolcraftAssemblyCommand[] = [];
+  const toolbarEnabled = toolbar.history || toolbar.radar || toolbar.theme || toolbar.zoom;
+  const canvasEditableSize = canvas.sizing.mode === "editable-output";
+
+  if (canvas.enabled) {
+    components.push("canvas");
+
+    if (canvasEditableSize) {
+      capabilities.push("canvas.editableSize");
+      commands.push("canvas.setSize");
+    }
+
+    if (canvas.renderScale.enabled) {
+      capabilities.push("canvas.renderScale");
+    }
+
+    if (canvas.draggable) {
+      capabilities.push("canvas.draggable");
+      commands.push("canvas.panBy", "canvas.setOffset", "canvas.setViewport");
+    }
+
+    if (canvas.upload) {
+      capabilities.push("canvas.upload");
+      commands.push("media.delete", "media.import", "media.reorder", "media.transform");
+    }
+  }
+
+  const controlsPanel = panels.controls
+    ? createPanelAssemblyContract({
+        capabilities: ["controls.panel", "controls.defaults"],
+        commands: [
+          "controls.apply",
+          "controls.reset",
+          "controls.resetTargets",
+          "controls.setValue",
+        ],
+        contract: TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel,
+        enabled: true,
+      })
+    : undefined;
+
+  if (controlsPanel) {
+    components.push("controlsPanel");
+    capabilities.push(...controlsPanel.capabilities);
+    commands.push(...controlsPanel.commands);
+  }
+
+  const layersPanel = panels.layers
+    ? createPanelAssemblyContract({
+        capabilities: [
+          "layers.groups",
+          "layers.panel",
+          "layers.selection",
+          "layers.visibility",
+        ],
+        commands: [
+          "layers.add",
+          "layers.delete",
+          "layers.moveToGroup",
+          "layers.rename",
+          "layers.reorder",
+          "layers.select",
+          "layers.toggleCollapsed",
+          "layers.toggleVisibility",
+        ],
+        contract: TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel,
+        enabled: true,
+      })
+    : undefined;
+
+  if (layersPanel) {
+    components.push("layersPanel");
+    capabilities.push(...layersPanel.capabilities);
+    commands.push(...layersPanel.commands);
+  }
+
+  const timelineKeyframesEnabled = panels.timeline?.mode === "keyframes";
+  const timelinePanel = panels.timeline?.enabled
+    ? createPanelAssemblyContract({
+        capabilities: [
+          "timeline.duration",
+          "timeline.panel",
+          "timeline.playback",
+          ...(timelineKeyframesEnabled ? (["timeline.keyframes"] as const) : []),
+        ],
+        commands: [
+          "timeline.setCurrentTime",
+          "timeline.setDuration",
+          "timeline.setPlaying",
+          "timeline.toggleLoop",
+          "timeline.togglePlayback",
+          ...(timelineKeyframesEnabled
+            ? ([
+                "timeline.changeKeyframeEasing",
+                "timeline.deleteControlKeyframes",
+                "timeline.deleteKeyframe",
+                "timeline.moveKeyframe",
+                "timeline.selectKeyframe",
+                "timeline.setExpanded",
+                "timeline.toggleControlKeyframes",
+                "timeline.toggleExpanded",
+              ] as const)
+            : []),
+        ],
+        contract: TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel,
+        enabled: true,
+      })
+    : undefined;
+
+  if (timelinePanel) {
+    components.push("timelinePanel");
+    capabilities.push(...timelinePanel.capabilities);
+    commands.push(...timelinePanel.commands);
+  }
+
+  const toolbarCommands: ToolcraftAssemblyCommand[] = [];
+  const toolbarCapabilities: ToolcraftAssemblyCapability[] = [];
+
+  if (toolbar.history) {
+    toolbarCapabilities.push("history.undoRedo", "toolbar.history");
+    toolbarCommands.push("history.redo", "history.undo");
+  }
+
+  if (toolbar.radar) {
+    toolbarCapabilities.push("toolbar.radar");
+    toolbarCommands.push("canvas.center");
+  }
+
+  if (toolbar.theme) {
+    toolbarCapabilities.push("toolbar.theme");
+  }
+
+  if (toolbar.zoom) {
+    toolbarCapabilities.push("toolbar.zoom");
+    toolbarCommands.push("canvas.zoomIn", "canvas.zoomOut", "canvas.zoomReset");
+  }
+
+  const toolbarPanel = createPanelAssemblyContract({
+    capabilities: toolbarCapabilities,
+    commands: toolbarCommands,
+    contract: TOOLCRAFT_COMPONENT_CONTRACTS.toolbar,
+    enabled: toolbarEnabled,
+  });
+
+  if (toolbarEnabled) {
+    components.push("toolbar");
+    capabilities.push(...toolbarPanel.capabilities);
+    commands.push(...toolbarPanel.commands);
+  }
+
+  return {
+    capabilities: unique(capabilities),
+    commands: unique(commands),
+    components: unique(components),
+    surfaces: {
+      canvas: {
+        capabilities: canvas.enabled
+          ? unique<ToolcraftAssemblyCapability>([
+              ...(canvasEditableSize ? (["canvas.editableSize"] as const) : []),
+              ...(canvas.draggable ? (["canvas.draggable"] as const) : []),
+              ...(canvas.upload ? (["canvas.upload"] as const) : []),
+            ])
+          : [],
+        commands: canvas.enabled
+          ? unique<ToolcraftAssemblyCommand>([
+              ...(canvasEditableSize ? (["canvas.setSize"] as const) : []),
+              ...(canvas.draggable
+                ? (["canvas.panBy", "canvas.setOffset", "canvas.setViewport"] as const)
+                : []),
+              ...(canvas.upload
+                ? ([
+                    "media.delete",
+                    "media.import",
+                    "media.reorder",
+                    "media.transform",
+                  ] as const)
+                : []),
+            ])
+          : [],
+        enabled: canvas.enabled,
+        visualComponent: "CanvasShell",
+      },
+      panels: {
+        controls: controlsPanel,
+        layers: layersPanel,
+        timeline: timelinePanel,
+        toolbar: toolbarPanel,
+      },
+    },
+  };
+}

package/templates/runtime/schema/control-schema-normalization.ts

@@ -0,0 +1,55 @@
+import type { ToolcraftControlSchema } from "./types";
+
+function isSliderLikeControl(control: ToolcraftControlSchema): boolean {
+  return control.type === "slider" || control.type === "rangeSlider";
+}
+
+function getStepMarkerCount(control: ToolcraftControlSchema): number | undefined {
+  if (
+    typeof control.step !== "number" ||
+    typeof control.min !== "number" ||
+    typeof control.max !== "number" ||
+    !Number.isFinite(control.step) ||
+    !Number.isFinite(control.min) ||
+    !Number.isFinite(control.max) ||
+    control.step <= 0 ||
+    control.max <= control.min
+  ) {
+    return undefined;
+  }
+
+  const rawStepCount = (control.max - control.min) / control.step;
+  const roundedStepCount = Math.round(rawStepCount);
+  const stepCount =
+    Math.abs(rawStepCount - roundedStepCount) < Number.EPSILON * 100
+      ? roundedStepCount
+      : Math.floor(rawStepCount) + 1;
+
+  return Math.max(2, stepCount + 1);
+}
+
+function normalizeControlSchema(
+  control: ToolcraftControlSchema,
+): ToolcraftControlSchema {
+  if (
+    !isSliderLikeControl(control) ||
+    typeof control.step !== "number" ||
+    control.variant !== "discrete"
+  ) {
+    return control;
+  }
+
+  return {
+    ...control,
+    markerCount: getStepMarkerCount(control) ?? control.markerCount,
+    variant: "discrete",
+  };
+}
+
+export function createNormalizedControlsRecord(
+  entries: readonly [string, ToolcraftControlSchema][],
+): Record<string, ToolcraftControlSchema> {
+  return Object.fromEntries(
+    entries.map(([id, control]) => [id, normalizeControlSchema(control)]),
+  );
+}

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

@@ -0,0 +1,141 @@
+import { createNormalizedControlsRecord } from "./control-schema-normalization";
+import { filterLayoutGroupsForControlIds } from "./controls-panel-layout-groups";
+import type {
+  ToolcraftControlSchema,
+  ToolcraftControlSectionSchema,
+} from "./types";
+
+type ToolcraftControlActionSchema = NonNullable<
+  ToolcraftControlSchema["actions"]
+>[number];
+
+function isPanelActionsControl(control: ToolcraftControlSchema): boolean {
+  return control.type === "panelActions";
+}
+
+function isPrimaryPanelAction(action: ToolcraftControlActionSchema): boolean {
+  return typeof action !== "string" && action.variant !== "outline";
+}
+
+function orderPanelActions(
+  actions: readonly ToolcraftControlActionSchema[],
+): ToolcraftControlActionSchema[] {
+  if (actions.length !== 2) {
+    return [...actions];
+  }
+
+  return [...actions].sort(
+    (left, right) => Number(isPrimaryPanelAction(left)) - Number(isPrimaryPanelAction(right)),
+  );
+}
+
+function createMergedPanelActionsControl(
+  entries: readonly [string, ToolcraftControlSchema][],
+): ToolcraftControlSchema | null {
+  const firstControl = entries[0]?.[1];
+
+  if (!firstControl) {
+    return null;
+  }
+
+  const actions = entries.flatMap(([, control]) => [...(control.actions ?? [])]);
+
+  return {
+    ...firstControl,
+    actions: orderPanelActions(actions),
+    target: firstControl.target || "panel.actions",
+    type: "panelActions",
+  };
+}
+
+function getBodySectionTitleAfterActionSplit(
+  title: ToolcraftControlSectionSchema["title"],
+): ToolcraftControlSectionSchema["title"] {
+  if (!title) {
+    return title;
+  }
+
+  return isActionOrExportSectionTitle(title) ? undefined : title;
+}
+
+function isActionOrExportSectionTitle(title: string): boolean {
+  const normalizedTitle = title.trim().toLowerCase();
+
+  return normalizedTitle === "action" ||
+    normalizedTitle === "actions" ||
+    normalizedTitle === "export" ||
+    normalizedTitle === "exports";
+}
+
+export function splitControlsPanelActionSections(
+  sections: readonly ToolcraftControlSectionSchema[],
+): {
+  bodySections: ToolcraftControlSectionSchema[];
+  stickyFooterSections: ToolcraftControlSectionSchema[];
+} {
+  const bodySections: ToolcraftControlSectionSchema[] = [];
+  const stickyFooterSections: ToolcraftControlSectionSchema[] = [];
+  const stickyFooterActionEntries: [string, ToolcraftControlSchema][] = [];
+
+  for (const section of sections) {
+    if (section.actionGroup) {
+      const entries = Object.entries(section.controls);
+      const actionEntries = entries.filter(([, control]) => isPanelActionsControl(control));
+      const passthroughEntries = entries.filter(([, control]) => !isPanelActionsControl(control));
+
+      stickyFooterActionEntries.push(...actionEntries);
+
+      if (passthroughEntries.length > 0) {
+        stickyFooterSections.push({
+          ...section,
+          controls: createNormalizedControlsRecord(passthroughEntries),
+        });
+      }
+
+      continue;
+    }
+
+    const bodyEntries: [string, ToolcraftControlSchema][] = [];
+    const actionEntries: [string, ToolcraftControlSchema][] = [];
+
+    for (const entry of Object.entries(section.controls)) {
+      const [, control] = entry;
+
+      if (isPanelActionsControl(control)) {
+        actionEntries.push(entry);
+      } else {
+        bodyEntries.push(entry);
+      }
+    }
+
+    if (bodyEntries.length > 0) {
+      const controlIds = new Set(bodyEntries.map(([id]) => id));
+      const layoutGroups = filterLayoutGroupsForControlIds(section.layoutGroups, controlIds);
+      const title = getBodySectionTitleAfterActionSplit(section.title);
+
+      bodySections.push({
+        ...section,
+        controls: createNormalizedControlsRecord(bodyEntries),
+        layoutGroups: layoutGroups.length > 0 ? layoutGroups : undefined,
+        title,
+      });
+    }
+
+    if (actionEntries.length > 0) {
+      stickyFooterActionEntries.push(...actionEntries);
+    }
+  }
+
+  const mergedActionsControl = createMergedPanelActionsControl(stickyFooterActionEntries);
+
+  if (mergedActionsControl) {
+    stickyFooterSections.unshift({
+      actionGroup: "secondary",
+      controls: { footer: mergedActionsControl },
+      layout: "standalone",
+      title: "Export",
+    });
+  }
+
+  return { bodySections, stickyFooterSections };
+}

package/templates/runtime/schema/controls-panel-layout-groups.ts

@@ -0,0 +1,144 @@
+import type {
+  ToolcraftControlLayoutGroupSchema,
+  ToolcraftControlSchema,
+  ToolcraftControlSectionSchema,
+} from "./types";
+
+const maxAutoInlineControlLabelLength = 18;
+
+export function filterLayoutGroupsForControlIds(
+  layoutGroups: readonly ToolcraftControlLayoutGroupSchema[] | undefined,
+  controlIds: ReadonlySet<string>,
+): ToolcraftControlLayoutGroupSchema[] {
+  return (layoutGroups ?? [])
+    .map((layoutGroup) => ({
+      ...layoutGroup,
+      controls: layoutGroup.controls.filter((controlId) => controlIds.has(controlId)),
+    }))
+    .filter((layoutGroup) => layoutGroup.controls.length > 1);
+}
+
+function isShortControlLabel(id: string, control: ToolcraftControlSchema): boolean {
+  const label = typeof control.label === "string" ? control.label : id;
+
+  return label.length <= maxAutoInlineControlLabelLength;
+}
+
+function isNumericTextControl(control: ToolcraftControlSchema): boolean {
+  if (control.type !== "text") {
+    return false;
+  }
+
+  if (typeof control.defaultValue === "number") {
+    return Number.isFinite(control.defaultValue);
+  }
+
+  return (
+    typeof control.defaultValue === "string" &&
+    /^-?\d+(?:\.\d+)?(?:px|%|s)?$/u.test(control.defaultValue.trim())
+  );
+}
+
+function isColorValueControl(control: ToolcraftControlSchema): boolean {
+  return control.type === "color" || control.type === "colorOpacity";
+}
+
+function hasVisibleControlLabel(control: ToolcraftControlSchema): boolean {
+  return typeof control.label === "string" && control.label.trim().length > 0;
+}
+
+function shouldAutoInlineMixedFieldControls(
+  first: [string, ToolcraftControlSchema],
+  second: [string, ToolcraftControlSchema],
+): boolean {
+  const [firstId, firstControl] = first;
+  const [secondId, secondControl] = second;
+  const isNumericColorPair =
+    (isNumericTextControl(firstControl) && isColorValueControl(secondControl)) ||
+    (isColorValueControl(firstControl) && isNumericTextControl(secondControl));
+
+  return (
+    isNumericColorPair &&
+    hasVisibleControlLabel(firstControl) &&
+    hasVisibleControlLabel(secondControl) &&
+    isShortControlLabel(firstId, firstControl) &&
+    isShortControlLabel(secondId, secondControl)
+  );
+}
+
+function shouldAutoInlineControls(
+  first: [string, ToolcraftControlSchema],
+  second: [string, ToolcraftControlSchema],
+): boolean {
+  const [firstId, firstControl] = first;
+  const [secondId, secondControl] = second;
+
+  if (
+    isNumericTextControl(firstControl) &&
+    isNumericTextControl(secondControl) &&
+    isShortControlLabel(firstId, firstControl) &&
+    isShortControlLabel(secondId, secondControl)
+  ) {
+    return true;
+  }
+
+  return shouldAutoInlineMixedFieldControls(first, second);
+}
+
+export function addAutoLayoutGroupsToSection(
+  section: ToolcraftControlSectionSchema,
+): ToolcraftControlSectionSchema {
+  if (section.layout === "standalone" || section.actionGroup) {
+    return section;
+  }
+
+  const entries = Object.entries(section.controls);
+  const explicitLayoutGroups = section.layoutGroups ?? [];
+  const groupedControlIds = new Set<string>();
+
+  for (const layoutGroup of explicitLayoutGroups) {
+    for (const controlId of layoutGroup.controls) {
+      groupedControlIds.add(controlId);
+    }
+  }
+
+  const autoLayoutGroups: ToolcraftControlLayoutGroupSchema[] = [];
+
+  for (let index = 0; index < entries.length - 1; index += 1) {
+    const firstEntry = entries[index];
+    const secondEntry = entries[index + 1];
+
+    if (!firstEntry || !secondEntry) {
+      continue;
+    }
+
+    const [firstId] = firstEntry;
+    const [secondId] = secondEntry;
+
+    if (groupedControlIds.has(firstId) || groupedControlIds.has(secondId)) {
+      continue;
+    }
+
+    if (!shouldAutoInlineControls(firstEntry, secondEntry)) {
+      continue;
+    }
+
+    autoLayoutGroups.push({
+      columns: 2,
+      controls: [firstId, secondId],
+      layout: "inline",
+    });
+    groupedControlIds.add(firstId);
+    groupedControlIds.add(secondId);
+    index += 1;
+  }
+
+  const layoutGroups = [...explicitLayoutGroups, ...autoLayoutGroups];
+
+  return layoutGroups.length > 0
+    ? {
+        ...section,
+        layoutGroups,
+      }
+    : section;
+}

package/templates/runtime/schema/controls-panel-normalization.ts

@@ -0,0 +1,19 @@
+import { splitControlsPanelActionSections } from "./controls-panel-actions";
+import { normalizeMixedSectionLayout } from "./controls-panel-section-layout";
+import type { ToolcraftControlsPanelSchema } from "./types";
+
+export function normalizeControlsPanelLayout(
+  controls: ToolcraftControlsPanelSchema,
+): ToolcraftControlsPanelSchema {
+  const { bodySections, stickyFooterSections } = splitControlsPanelActionSections(
+    controls.sections,
+  );
+
+  return {
+    ...controls,
+    sections: [
+      ...bodySections.flatMap(normalizeMixedSectionLayout),
+      ...stickyFooterSections.flatMap(normalizeMixedSectionLayout),
+    ],
+  };
+}