@pixel-point/toolcraft 0.0.16 → 0.0.18

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

@@ -1,10 +1,29 @@
 import { getToolcraftSegmentedStaticFitError } from "../contracts/segmented-control-fit";
 import { normalizeToolcraftModelFileDrop } from "../model-import/model-import-limits";
+import { isToolcraftCollectionItemControlType } from "./collection-item-controls";
+import { resolveToolcraftControlApplicability } from "./control-applicability";
 import type {
   ResolvedToolcraftControlSchema,
+  ToolcraftModelFileDropSchema,
+  ToolcraftNonModelControlSchema,
+  ToolcraftResolvedControlApplicabilitySchema,
   ToolcraftControlSchema,
 } from "./types";
 
+type ControlWithResolvedApplicability =
+  | (Omit<
+      ToolcraftNonModelControlSchema,
+      "applicability" | "visibleWhen"
+    > & {
+      applicability: ToolcraftResolvedControlApplicabilitySchema;
+    })
+  | (Omit<
+      ToolcraftModelFileDropSchema,
+      "applicability" | "visibleWhen"
+    > & {
+      applicability: ToolcraftResolvedControlApplicabilitySchema;
+    });
+
 const modelOnlyControlFieldNames = [
   "modelFormats",
   "modelLimits",
@@ -82,6 +101,117 @@ function assertFileDropHardMaxItems(control: ToolcraftControlSchema): void {
   }
 }
 
+function assertFileDropVariant(control: ToolcraftControlSchema): void {
+  if (
+    control.type !== "fileDrop" ||
+    control.variant !== "collection-actions"
+  ) {
+    return;
+  }
+
+  if (control.assetKind !== "file" || control.multiple !== true) {
+    throw new Error(
+      'Toolcraft fileDrop validation [filedrop-collection-actions]: variant "collection-actions" requires assetKind: "file" with multiple: true.',
+    );
+  }
+}
+
+type ItemControlsOwner = Readonly<{
+  minimumFields: number;
+  name: "collectionActions" | "fileDrop";
+}>;
+
+function getItemControlsOwner(
+  control: ToolcraftControlSchema,
+): ItemControlsOwner | null {
+  if (control.type === "collectionActions") {
+    return { minimumFields: 2, name: "collectionActions" };
+  }
+
+  if (
+    control.type === "fileDrop" &&
+    control.variant === "collection-actions" &&
+    control.assetKind === "file" &&
+    control.multiple === true
+  ) {
+    return { minimumFields: 1, name: "fileDrop" };
+  }
+
+  return null;
+}
+
+function isPlainRecord(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function assertItemControls(control: ToolcraftControlSchema): void {
+  if (!control.itemControls) {
+    return;
+  }
+
+  const owner = getItemControlsOwner(control);
+
+  if (!owner) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-controls] for target "${control.target}": itemControls require collectionActions or a multiple file-kind collection-actions fileDrop.`,
+    );
+  }
+
+  if (control.itemControl) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-template] for target "${control.target}": itemControl and itemControls are mutually exclusive.`,
+    );
+  }
+
+  if (Object.prototype.hasOwnProperty.call(control, "itemDefaultValue")) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-default] for target "${control.target}": itemDefaultValue cannot be used with itemControls; field defaults own the new record.`,
+    );
+  }
+
+  const entries = Object.entries(control.itemControls);
+  if (entries.length < owner.minimumFields) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-controls] for target "${control.target}": ${owner.name} itemControls require at least ${owner.minimumFields === 1 ? "one" : "two"} built-in field${owner.minimumFields === 1 ? "" : "s"}.`,
+    );
+  }
+
+  for (const [id, itemControl] of entries) {
+    if (!id.trim() || !isToolcraftCollectionItemControlType(itemControl.type)) {
+      throw new Error(
+        `Toolcraft control validation [collection-item-controls] for target "${control.target}" itemControls.${id}: unsupported built-in field.`,
+      );
+    }
+    if (!Object.prototype.hasOwnProperty.call(itemControl, "defaultValue")) {
+      throw new Error(
+        `Toolcraft control validation [collection-item-controls] for target "${control.target}" itemControls.${id}: defaultValue is required.`,
+      );
+    }
+
+    const fitError = getToolcraftSegmentedStaticFitError(itemControl);
+    if (fitError) {
+      throw new Error(
+        `Toolcraft control validation [segmented-control-fit] for target "${control.target}" itemControls.${id}: ${fitError}`,
+      );
+    }
+  }
+
+  if (
+    owner.name === "collectionActions" &&
+    Array.isArray(control.defaultValue) &&
+    control.defaultValue.some((item) => !isPlainRecord(item))
+  ) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-value] for target "${control.target}": every initial compound item must be a plain record.`,
+    );
+  }
+}
+
 function assertSegmentedControlFit(control: ToolcraftControlSchema): void {
   const fitError = getToolcraftSegmentedStaticFitError(control);
 
@@ -92,13 +222,29 @@ function assertSegmentedControlFit(control: ToolcraftControlSchema): void {
   }
 }
 
-function assertCollectionItemSegmentedControlFit(
-  control: ToolcraftControlSchema,
-): void {
-  if (control.type !== "collectionActions" || !control.itemControl) {
+function assertCollectionItemControl(control: ToolcraftControlSchema): void {
+  if (
+    control.type !== "collectionActions" &&
+    control.type !== "sourceCollection"
+  ) {
+    return;
+  }
+
+  if (!control.itemControl) {
+    if (control.type === "sourceCollection") {
+      throw new Error(
+        `Toolcraft control validation [source-collection-item-control] for target "${control.target}": itemControl is required.`,
+      );
+    }
     return;
   }
 
+  if (!isToolcraftCollectionItemControlType(control.itemControl.type)) {
+    throw new Error(
+      `Toolcraft control validation [collection-item-control] for target "${control.target}": unsupported collection item control "${String(control.itemControl.type)}".`,
+    );
+  }
+
   const fitError = getToolcraftSegmentedStaticFitError(control.itemControl);
 
   if (fitError) {
@@ -108,11 +254,15 @@ function assertCollectionItemSegmentedControlFit(
   }
 }
 
-function isSliderLikeControl(control: ToolcraftControlSchema): boolean {
+function isSliderLikeControl(
+  control: ControlWithResolvedApplicability,
+): boolean {
   return control.type === "slider" || control.type === "rangeSlider";
 }
 
-function getStepMarkerCount(control: ToolcraftControlSchema): number | undefined {
+function getStepMarkerCount(
+  control: ControlWithResolvedApplicability,
+): number | undefined {
   if (
     typeof control.step !== "number" ||
     typeof control.min !== "number" ||
@@ -137,8 +287,8 @@ function getStepMarkerCount(control: ToolcraftControlSchema): number | undefined
 }
 
 function normalizeSliderControlSchema(
-  control: ToolcraftControlSchema,
-): ToolcraftControlSchema {
+  control: ControlWithResolvedApplicability,
+): ControlWithResolvedApplicability {
   if (
     !isSliderLikeControl(control) ||
     typeof control.step !== "number" ||
@@ -155,7 +305,7 @@ function normalizeSliderControlSchema(
 }
 
 function normalizeFileDropControlSchema(
-  control: ToolcraftControlSchema,
+  control: ControlWithResolvedApplicability,
 ): ResolvedToolcraftControlSchema {
   if (control.assetKind === "model") {
     return normalizeToolcraftModelFileDrop(control);
@@ -180,10 +330,26 @@ function normalizeControlSchema(
   assertRequiredControlStringField(controlSnapshot, "target");
   assertControlRuntimeBoundary(controlSnapshot);
   assertFileDropHardMaxItems(controlSnapshot);
+  assertFileDropVariant(controlSnapshot);
+  assertItemControls(controlSnapshot);
   assertSegmentedControlFit(controlSnapshot);
-  assertCollectionItemSegmentedControlFit(controlSnapshot);
+  assertCollectionItemControl(controlSnapshot);
+
+  const {
+    applicability: authoredApplicability,
+    visibleWhen,
+    ...controlWithoutApplicability
+  } = controlSnapshot;
+  const applicability = resolveToolcraftControlApplicability({
+    applicability: authoredApplicability,
+    visibleWhen,
+  });
+
   return normalizeFileDropControlSchema(
-    normalizeSliderControlSchema(controlSnapshot),
+    normalizeSliderControlSchema({
+      ...controlWithoutApplicability,
+      applicability,
+    }),
   );
 }
 

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

@@ -7,15 +7,15 @@ import {
 import type {
   ResolvedToolcraftControlSchema,
   ResolvedToolcraftControlSectionSchema,
+  ResolvedToolcraftNonModelControlSchema,
   ToolcraftControlSchema,
-  ToolcraftNonModelControlSchema,
 } from "./types";
 
 type ToolcraftControlActionSchema = NonNullable<
   ToolcraftControlSchema["actions"]
 >[number];
 
-type ToolcraftPanelActionsControl = ToolcraftNonModelControlSchema & {
+type ToolcraftPanelActionsControl = ResolvedToolcraftNonModelControlSchema & {
   type: "panelActions";
 };
 

package/templates/runtime/schema/controls-panel-section-id.test.ts

@@ -140,7 +140,7 @@ describe("Toolcraft control section identity", () => {
       )?.id,
     ).toBe(legacyId);
     expect(
-      defineToolcraft(resolved as ToolcraftAppSchema).panels.controls?.sections.find(
+      defineToolcraft(resolved as unknown as ToolcraftAppSchema).panels.controls?.sections.find(
         (section) => section.id.startsWith("legacy."),
       )?.id,
     ).toBe(legacyId);

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

@@ -9,14 +9,16 @@ import {
   registerToolcraftInternalControlSection,
 } from "./controls-panel-section-id";
 import { withImplicitStandaloneSectionTitle } from "./controls-panel-section-titles";
+import {
+  getToolcraftApplicabilityTargets,
+} from "./control-applicability";
 import type {
   ResolvedToolcraftControlSchema,
   ResolvedToolcraftControlSectionSchema,
-  ToolcraftControlSchema,
 } from "./types";
 
 function getControlDefaultSectionLayout(
-  control: ToolcraftControlSchema,
+  control: ResolvedToolcraftControlSchema,
 ): "grouped" | "standalone" {
   const contract = (
     TOOLCRAFT_COMPONENT_CONTRACTS as Record<
@@ -31,12 +33,15 @@ function getControlDefaultSectionLayout(
 }
 
 function isControlGatedBySameSectionControl(
-  control: ToolcraftControlSchema,
-  entries: readonly [string, ToolcraftControlSchema][],
+  control: ResolvedToolcraftControlSchema,
+  entries: readonly [string, ResolvedToolcraftControlSchema][],
 ): boolean {
-  const gateTargets = [control.visibleWhen?.target, control.disabledWhen?.target].filter(
-    (target): target is string => Boolean(target),
-  );
+  const gateTargets = [
+    ...getToolcraftApplicabilityTargets(
+      control.applicability,
+    ),
+    ...(control.disabledWhen ? [control.disabledWhen.target] : []),
+  ];
 
   if (gateTargets.length === 0) {
     return false;
@@ -49,8 +54,8 @@ function isControlGatedBySameSectionControl(
 }
 
 function getControlSectionLayout(
-  control: ToolcraftControlSchema,
-  entries: readonly [string, ToolcraftControlSchema][],
+  control: ResolvedToolcraftControlSchema,
+  entries: readonly [string, ResolvedToolcraftControlSchema][],
 ): "grouped" | "standalone" {
   if (isControlGatedBySameSectionControl(control, entries)) {
     return "grouped";

package/templates/runtime/schema/controls-panel-section-roundtrip.test.ts

@@ -13,6 +13,65 @@ const opacityControl = {
 } as const;
 
 describe("Toolcraft control section identity roundtrips", () => {
+  it("preserves explicit, legacy, and implicit applicability origins", () => {
+    const resolved = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                explicit: {
+                  applicability: { mode: "always" },
+                  target: "appearance.explicit",
+                  type: "switch",
+                },
+                implicit: {
+                  target: "appearance.implicit",
+                  type: "switch",
+                },
+                legacy: {
+                  target: "appearance.legacy",
+                  type: "slider",
+                  visibleWhen: {
+                    equals: true,
+                    target: "appearance.explicit",
+                  },
+                },
+              },
+              id: "appearance",
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const roundTripped = defineToolcraft(
+      resolved as unknown as ToolcraftAppSchema,
+    );
+    const readApplicability = (schema: typeof resolved) =>
+      Object.fromEntries(
+        schema.panels.controls?.sections
+          .filter((section) => section.id.startsWith("appearance"))
+          .flatMap((section) => Object.entries(section.controls))
+          .map(([id, control]) => [id, control.applicability]) ?? [],
+      );
+
+    expect(readApplicability(resolved)).toEqual({
+      explicit: { mode: "always", origin: "explicit" },
+      implicit: { mode: "always", origin: "implicit" },
+      legacy: {
+        all: [{ equals: true, target: "appearance.explicit" }],
+        mode: "conditional",
+        origin: "legacy",
+      },
+    });
+    expect(readApplicability(roundTripped)).toEqual(
+      readApplicability(resolved),
+    );
+  });
+
   it("round-trips resolved legacy and runtime section ids without duplicating runtime sections", () => {
     const resolved = defineToolcraft({
       canvas: { enabled: true },
@@ -38,7 +97,7 @@ describe("Toolcraft control section identity roundtrips", () => {
         },
       },
     });
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const resolvedIds = resolved.panels.controls?.sections.map((section) => section.id);
     const roundTrippedIds = roundTripped.panels.controls?.sections.map(
       (section) => section.id,
@@ -101,7 +160,7 @@ describe("Toolcraft control section identity roundtrips", () => {
     const productIds = resolved.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const roundTrippedProductIds = roundTripped.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));
@@ -147,7 +206,7 @@ describe("Toolcraft control section identity roundtrips", () => {
       productIds?.every((id) => (id.match(/\.part-/gu) ?? []).length === 2),
     ).toBe(true);
 
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const roundTrippedProductIds = roundTripped.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));

package/templates/runtime/schema/define-toolcraft.collection-actions-item-controls.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "./define-toolcraft";
+import type { ToolcraftControlSchema } from "./types";
+
+function createSchema(control: ToolcraftControlSchema) {
+  return {
+    canvas: { enabled: false },
+    panels: {
+      controls: {
+        sections: [{ controls: { layers: control }, title: "Layers" }],
+        title: "Controls",
+      },
+    },
+  };
+}
+
+function compoundCollection(
+  overrides: Record<string, unknown> = {},
+): ToolcraftControlSchema {
+  return {
+    defaultValue: [{ invert: false, strength: 0.4 }],
+    itemControls: {
+      strength: {
+        defaultValue: 0.5,
+        label: "Strength",
+        max: 1,
+        min: 0,
+        step: 0.01,
+        type: "slider",
+      },
+      invert: {
+        defaultValue: false,
+        label: "Invert",
+        type: "switch",
+      },
+    },
+    itemLabel: "Layer",
+    minItems: 1,
+    target: "surface.layers",
+    type: "collectionActions",
+    ...overrides,
+  } as ToolcraftControlSchema;
+}
+
+describe("defineToolcraft compound collectionActions items", () => {
+  it("accepts one logical record made from several built-in fields", () => {
+    const app = defineToolcraft(createSchema(compoundCollection()));
+    const control = app.panels.controls?.sections.find(
+      (section) => section.title === "Layers",
+    )?.controls.layers;
+
+    expect(Object.keys(control?.itemControls ?? {})).toEqual([
+      "strength",
+      "invert",
+    ]);
+  });
+
+  it("rejects competing scalar and record templates", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(
+          compoundCollection({
+            itemControl: { defaultValue: 0, type: "slider" },
+          }),
+        ),
+      ),
+    ).toThrow(/collection-item-template.*itemControl.*itemControls/u);
+  });
+
+  it("requires at least two fields in a compound collection item", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(
+          compoundCollection({
+            itemControls: {
+              strength: { defaultValue: 0.5, type: "slider" },
+            },
+          }),
+        ),
+      ),
+    ).toThrow(/collection-item-controls.*at least two/u);
+  });
+
+  it("requires one default source per compound field", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(
+          compoundCollection({
+            itemControls: {
+              invert: { defaultValue: false, type: "switch" },
+              strength: { type: "slider" },
+            },
+          }),
+        ),
+      ),
+    ).toThrow(/itemControls\.strength.*defaultValue/u);
+  });
+
+  it("rejects a competing itemDefaultValue", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(
+          compoundCollection({
+            itemDefaultValue: { invert: true, strength: 1 },
+          }),
+        ),
+      ),
+    ).toThrow(/collection-item-default.*itemDefaultValue/u);
+  });
+
+  it("rejects non-record initial compound items", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(compoundCollection({ defaultValue: [new Date()] })),
+      ),
+    ).toThrow(/collection-item-value.*plain record/u);
+  });
+
+  it("keeps sourceCollection single-field only", () => {
+    expect(() =>
+      defineToolcraft(
+        createSchema(compoundCollection({ type: "sourceCollection" })),
+      ),
+    ).toThrow(/collection-item-controls.*collectionActions.*fileDrop/u);
+  });
+});

package/templates/runtime/schema/define-toolcraft.control-sections.test.ts

@@ -4,7 +4,7 @@ import { defineToolcraft } from "./define-toolcraft";
 import { getProductSections } from "./define-toolcraft-test-utils";
 
 describe("defineToolcraft control section semantics", () => {
-  it("preserves conditional visibility on sections and controls", () => {
+  it("preserves section visibility and resolves legacy control visibility", () => {
     const app = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -38,9 +38,15 @@ describe("defineToolcraft control section semantics", () => {
       equals: "co-brand",
       target: "cover.templateId",
     });
-    expect(section?.controls.partnerLogo?.visibleWhen).toEqual({
-      equals: "logo",
-      target: "coBrand.identityMode",
+    expect(section?.controls.partnerLogo?.applicability).toEqual({
+      all: [
+        {
+          equals: "logo",
+          target: "coBrand.identityMode",
+        },
+      ],
+      mode: "conditional",
+      origin: "legacy",
     });
   });
 

package/templates/runtime/schema/define-toolcraft.file-drop-item-controls.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "./define-toolcraft";
+import type { ToolcraftControlSchema } from "./types";
+
+function createAppSchema(control: ToolcraftControlSchema) {
+  return {
+    canvas: { enabled: false },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: { bumpMaps: control },
+            title: "Bump Maps",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  };
+}
+
+function createFileDrop(
+  overrides: Record<string, unknown> = {},
+): ToolcraftControlSchema {
+  return {
+    assetKind: "file",
+    defaultValue: [],
+    itemControls: {
+      depth: { defaultValue: 0.2, max: 1, min: 0, type: "slider" },
+      levels: {
+        defaultValue: [0, 1],
+        max: 1,
+        min: 0,
+        step: 0.01,
+        type: "rangeSlider",
+      },
+      invert: { defaultValue: false, type: "switch" },
+      offset: {
+        coordinateMode: "cartesian",
+        defaultValue: { x: "0", y: "0" },
+        type: "vector",
+      },
+    },
+    multiple: true,
+    target: "media.bumpMaps",
+    type: "fileDrop",
+    variant: "collection-actions",
+    ...overrides,
+  } as ToolcraftControlSchema;
+}
+
+describe("defineToolcraft fileDrop item controls", () => {
+  it("accepts built-in settings owned by each attached file", () => {
+    const app = defineToolcraft(createAppSchema(createFileDrop()));
+    const control = app.panels.controls?.sections.find(
+      (section) => section.title === "Bump Maps",
+    )?.controls.bumpMaps;
+
+    expect(control?.itemControls?.depth?.defaultValue).toBe(0.2);
+    expect(control?.itemControls?.levels?.type).toBe("rangeSlider");
+    expect(control?.itemControls?.offset?.type).toBe("vector");
+  });
+
+  it("requires the file collection-actions variant", () => {
+    expect(() =>
+      defineToolcraft(
+        createAppSchema(createFileDrop({ variant: undefined })),
+      ),
+    ).toThrow(/collection-item-controls.*collectionActions.*fileDrop/u);
+  });
+
+  it("requires every nested setting to declare a reset default", () => {
+    expect(() =>
+      defineToolcraft(
+        createAppSchema(
+          createFileDrop({ itemControls: { depth: { type: "slider" } } }),
+        ),
+      ),
+    ).toThrow(/itemControls\.depth.*defaultValue/u);
+  });
+
+  it("rejects an empty nested settings declaration", () => {
+    expect(() =>
+      defineToolcraft(createAppSchema(createFileDrop({ itemControls: {} }))),
+    ).toThrow(/itemControls require at least one built-in field/u);
+  });
+
+  it("rejects itemDefaultValue beside per-file field defaults", () => {
+    expect(() =>
+      defineToolcraft(
+        createAppSchema(
+          createFileDrop({ itemDefaultValue: { depth: 1 } }),
+        ),
+      ),
+    ).toThrow(/collection-item-default.*itemDefaultValue/u);
+  });
+});