@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/src/app/starter-acceptance.contract-fixtures.ts

@@ -1,5 +1,7 @@
 import {
   defineToolcraft,
+  resolveToolcraftControlApplicability,
+  type ResolvedToolcraftAppSchema,
   type ToolcraftAppSchema,
 } from "@repo/toolcraft-runtime";
 
@@ -16,8 +18,32 @@ import {
 } from "./acceptance/validate-coverage";
 
 export function defineContractSchemaFixture(schema: ToolcraftAppSchema) {
+  const controls = schema.panels.controls
+    ? {
+        ...schema.panels.controls,
+        sections: schema.panels.controls.sections.map((section) => ({
+          ...section,
+          controls: Object.fromEntries(
+            Object.entries(section.controls).map(([controlId, control]) => [
+              controlId,
+              control.applicability || control.visibleWhen
+                ? control
+                : {
+                    ...control,
+                    applicability: { mode: "always" as const },
+                  },
+            ]),
+          ),
+        })),
+      }
+    : undefined;
+
   return defineToolcraft({
     ...schema,
+    panels: {
+      ...schema.panels,
+      ...(controls ? { controls } : {}),
+    },
     persistence: { storage: "none" },
   });
 }
@@ -54,28 +80,98 @@ export const contractProductReadinessFixture: ToolcraftProductReadiness = {
   reason: "Neutral contract fixture without a product-owned spatial scene.",
 };
 
-export function validateContractAcceptance(
-  overrides: Partial<ToolcraftAcceptanceValidationInput> = {},
-): string[] {
-  return validateToolcraftAcceptanceCoverage({
+type ContractAcceptanceOverrides = Omit<
+  Partial<ToolcraftAcceptanceValidationInput>,
+  "schema"
+> & {
+  schema?: ContractValidationSchemaFixture;
+};
+
+type ContractValidationSchemaFixture = Omit<
+  ResolvedToolcraftAppSchema,
+  "panels"
+> & {
+  panels: Omit<ResolvedToolcraftAppSchema["panels"], "controls"> & {
+    controls?: ToolcraftAppSchema["panels"]["controls"];
+  };
+};
+
+function resolveContractValidationSchemaFixture(
+  schema: ContractValidationSchemaFixture,
+): ResolvedToolcraftAppSchema {
+  const {
+    controls: _fixtureControls,
+    ...panelsWithoutFixtureControls
+  } = schema.panels;
+  const controls = schema.panels.controls
+    ? {
+        ...schema.panels.controls,
+        sections: schema.panels.controls.sections.map((section) => ({
+          ...section,
+          controls: Object.fromEntries(
+            Object.entries(section.controls).map(([controlId, control]) => {
+              const {
+                applicability: authoredApplicability,
+                visibleWhen,
+                ...controlWithoutApplicability
+              } = control;
+
+              return [
+                controlId,
+                {
+                  ...controlWithoutApplicability,
+                  applicability: resolveToolcraftControlApplicability({
+                    applicability:
+                      authoredApplicability ??
+                      (visibleWhen ? undefined : { mode: "always" }),
+                    visibleWhen,
+                  }),
+                },
+              ];
+            }),
+          ),
+        })),
+      }
+    : undefined;
+
+  // Contract tests deliberately preserve malformed post-normalization fields so
+  // the matching acceptance validator, rather than defineToolcraft, reports them.
+  return {
+    ...schema,
+    panels: {
+      ...panelsWithoutFixtureControls,
+      ...(controls ? { controls } : {}),
+    },
+  } as ResolvedToolcraftAppSchema;
+}
+
+function resolveContractAcceptanceInput(
+  overrides: ContractAcceptanceOverrides,
+): ToolcraftAcceptanceValidationInput {
+  const { schema = contractSchemaFixture, ...remainingOverrides } = overrides;
+
+  return {
     acceptance: contractAcceptanceFixture,
     productReadiness: contractProductReadinessFixture,
-    schema: contractSchemaFixture,
+    schema: resolveContractValidationSchemaFixture(schema),
     sectionInventory: contractSectionInventoryFixture,
     transferMode: contractTransferModeFixture,
-    ...overrides,
-  });
+    ...remainingOverrides,
+  };
+}
+
+export function validateContractAcceptance(
+  overrides: ContractAcceptanceOverrides = {},
+): string[] {
+  return validateToolcraftAcceptanceCoverage(
+    resolveContractAcceptanceInput(overrides),
+  );
 }
 
 export function validateContractAcceptanceDiagnostics(
-  overrides: Partial<ToolcraftAcceptanceValidationInput> = {},
+  overrides: ContractAcceptanceOverrides = {},
 ) {
-  return validateToolcraftAcceptanceDiagnostics({
-    acceptance: contractAcceptanceFixture,
-    productReadiness: contractProductReadinessFixture,
-    schema: contractSchemaFixture,
-    sectionInventory: contractSectionInventoryFixture,
-    transferMode: contractTransferModeFixture,
-    ...overrides,
-  });
+  return validateToolcraftAcceptanceDiagnostics(
+    resolveContractAcceptanceInput(overrides),
+  );
 }

package/templates/starter/src/app/starter-acceptance.control-applicability.test.ts

@@ -0,0 +1,224 @@
+import {
+  defineToolcraft,
+  type ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftControlApplicabilityErrors } from "./acceptance/control-applicability";
+import type { ToolcraftProductReadiness } from "./acceptance/types";
+import { collectToolcraftVisibleAcceptanceControls } from "./acceptance/validate-coverage";
+
+const productReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    video: { mode: "not-requested" },
+  },
+  interactionOwnership: [],
+  mode: "product",
+  productName: "Shape fixture",
+  productSummary: "Neutral applicability contract fixture.",
+  requestedBehavior: "Show only controls that apply to the selected shape.",
+  viewInteraction: { mode: "non-spatial", reason: "Schema-only fixture." },
+};
+
+const shapeKind: ToolcraftControlSchema = {
+  applicability: { mode: "always" },
+  defaultValue: "circle",
+  options: [
+    { label: "Circle", value: "circle" },
+    { label: "Square", value: "square" },
+    { label: "Polygon", value: "polygon" },
+    { label: "Star", value: "star" },
+  ],
+  target: "shape.kind",
+  type: "segmented",
+};
+
+const alwaysControls: Record<string, ToolcraftControlSchema> = {
+  kind: shapeKind,
+  cornerRadius: {
+    applicability: {
+      all: [
+        {
+          oneOf: ["square", "polygon", "star"],
+          target: "shape.kind",
+        },
+      ],
+      mode: "conditional",
+    },
+    target: "shape.cornerRadius",
+    type: "slider",
+  },
+  depth: {
+    applicability: {
+      all: [{ equals: "star", target: "shape.kind" }],
+      mode: "conditional",
+    },
+    target: "shape.depth",
+    type: "slider",
+  },
+  sides: {
+    applicability: {
+      all: [
+        { oneOf: ["polygon", "star"], target: "shape.kind" },
+      ],
+      mode: "conditional",
+    },
+    target: "shape.sides",
+    type: "slider",
+  },
+};
+
+function validateProduct(
+  controls: Record<string, ToolcraftControlSchema>,
+): string[] {
+  const schema = defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [{ controls, id: "shape", title: "Shape" }],
+        title: "Controls",
+      },
+    },
+  });
+
+  return getToolcraftControlApplicabilityErrors({
+    controls: collectToolcraftVisibleAcceptanceControls(schema),
+    productReadiness,
+  });
+}
+
+describe("starter product control applicability", () => {
+  it("requires explicit product applicability and rejects legacy visibility", () => {
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: { target: "shape.sides", type: "slider" },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides must declare explicit applicability"),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          target: "shape.sides",
+          type: "slider",
+          visibleWhen: { equals: "star", target: "shape.kind" },
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides uses legacy visibleWhen"),
+    );
+  });
+
+  it("rejects missing, invalid, contradictory, and unsupported selectors", () => {
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [{ equals: true, target: "shape.missing" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining('predicate target "shape.missing" does not exist'),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [{ equals: "triangle", target: "shape.kind" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining(
+        'value "triangle" is not an option of shape.kind',
+      ),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [
+              { equals: "polygon", target: "shape.kind" },
+              { equals: "star", target: "shape.kind" },
+            ],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides applicability is unsatisfiable"),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        name: {
+          applicability: { mode: "always" },
+          target: "shape.name",
+          type: "text",
+        },
+        sides: {
+          applicability: {
+            all: [{ equals: "named", target: "shape.name" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining(
+        "shape.name is not a supported applicability selector",
+      ),
+    );
+  });
+
+  it("rejects numeric gates with no satisfying selector value", () => {
+    expect(
+      validateProduct({
+        count: {
+          applicability: { mode: "always" },
+          defaultValue: 2,
+          max: 3,
+          min: 1,
+          step: 1,
+          target: "shape.count",
+          type: "slider",
+          variant: "discrete",
+        },
+        sides: {
+          applicability: {
+            all: [{ greaterThan: 10, target: "shape.count" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides has no satisfying value in shape.count"),
+    );
+  });
+
+  it("accepts a complete finite applicability declaration", () => {
+    expect(validateProduct(alwaysControls)).toEqual([]);
+  });
+});

package/templates/starter/src/app/starter-acceptance.control-order.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   getToolcraftSegmentedStaticFitError,
+  type ToolcraftCollectionItemControlType,
 } from "@repo/toolcraft-runtime";
 
 import {
@@ -18,7 +19,7 @@ const SCREENSHOT_LABELS = ["Default", "Ink Drops", "Solar", "Background"];
 const BOUNDARY_LABELS = ["Ink Drops", "Default", "Solar", "RGB"];
 
 function createRawCollectionModesSchema(
-  itemControlType: string,
+  itemControlType: ToolcraftCollectionItemControlType,
   labels: readonly string[],
 ) {
   return {
@@ -64,6 +65,11 @@ const collectionModesAcceptance = [
     browser: true,
     browserTestName: "browser: collection modes update rendered output",
     componentType: "collectionActions",
+    controlPartCoverage: [
+      "collectionActions.add",
+      "collectionActions.remove",
+      "collectionActions.items",
+    ] as const,
     evidence: "rendered-pixels" as const,
     expectedObservable: "Adding and editing modes changes rendered output.",
     fixture: "collection modes fixture",
@@ -339,7 +345,7 @@ describe("starter acceptance control order contract", () => {
   it("reports canonical fit guidance for an overwide collectionActions itemControl", () => {
     const itemControl = {
       options: SCREENSHOT_LABELS.map((label) => ({ label })),
-      type: "segmented",
+      type: "segmented" as const,
     };
     const fitGuidance = getToolcraftSegmentedStaticFitError(itemControl);
 
@@ -359,10 +365,59 @@ describe("starter acceptance control order contract", () => {
     );
   });
 
+  it("reports canonical fit guidance for every compound itemControls field", () => {
+    const schema = createRawCollectionModesSchema("segmented", SCREENSHOT_LABELS);
+    const modes = schema.panels.controls.sections[0]!.controls.modes;
+    const compoundSchema = {
+      ...schema,
+      panels: {
+        ...schema.panels,
+        controls: {
+          ...schema.panels.controls,
+          sections: [
+            {
+              ...schema.panels.controls.sections[0],
+              controls: {
+                modes: {
+                  ...modes,
+                  defaultValue: [{ enabled: true, mode: "default" }],
+                  itemControl: undefined,
+                  itemControls: {
+                    enabled: {
+                      defaultValue: true,
+                      label: "Enabled",
+                      type: "switch" as const,
+                    },
+                    mode: modes.itemControl,
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+    };
+    const fitGuidance = getToolcraftSegmentedStaticFitError(
+      modes.itemControl,
+    );
+
+    expect(fitGuidance).not.toBeNull();
+    expect(
+      validateContractAcceptance({
+        schema: compoundSchema,
+        acceptance: collectionModesAcceptance,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        `Style / modes (appearance.modes) itemControls.mode ${fitGuidance}`,
+      ]),
+    );
+  });
+
   it.each([
     { labels: BOUNDARY_LABELS, type: "segmented" },
     { labels: SCREENSHOT_LABELS, type: "select" },
-  ])(
+  ] as const)(
     "does not report itemControl fit guidance for nested $type",
     ({ labels, type }) => {
       const errors = validateContractAcceptance({

package/templates/starter/src/app/starter-acceptance.control-state.test.ts

@@ -160,115 +160,4 @@ describe("starter acceptance control state contract", () => {
     );
   });
 
-  it("requires visibleWhen controls to reference a real target and prove hidden behavior", () => {
-    const schemaWithVisibleDependency = defineContractSchemaFixture({
-      canvas: { enabled: true },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                shadeCount: {
-                  defaultValue: 2,
-                  label: "Shades",
-                  max: 5,
-                  min: 1,
-                  step: 1,
-                  target: "shapes.shadeCount",
-                  type: "slider",
-                  variant: "discrete",
-                },
-                shade3: {
-                  defaultValue: { hex: "#BBBBBB" },
-                  label: "Shade 3",
-                  target: "shapes.color3",
-                  type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 3,
-                    target: "shapes.count",
-                  },
-                },
-              },
-              title: "Shapes",
-            },
-          ],
-          title: "Controls",
-        },
-      },
-    });
-
-    expect(
-      validateContractAcceptance({
-        schema: schemaWithVisibleDependency,
-        acceptance: [
-          makeControlAcceptance("shapes.shadeCount", "slider"),
-          makeControlAcceptance("shapes.color3", "color"),
-        ],
-      }),
-    ).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining(
-          "visibleWhen target shapes.count does not match another schema control target",
-        ),
-        expect.stringContaining(
-          "uses visibleWhen and must declare visibilityCoverage",
-        ),
-      ]),
-    );
-
-    const schemaWithValidVisibleDependency = defineContractSchemaFixture({
-      canvas: { enabled: true },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                shadeCount: {
-                  defaultValue: 2,
-                  label: "Shades",
-                  max: 5,
-                  min: 1,
-                  step: 1,
-                  target: "shapes.shadeCount",
-                  type: "slider",
-                  variant: "discrete",
-                },
-                shade3: {
-                  defaultValue: { hex: "#BBBBBB" },
-                  label: "Shade 3",
-                  target: "shapes.color3",
-                  type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 3,
-                    target: "shapes.shadeCount",
-                  },
-                },
-              },
-              title: "Shapes",
-            },
-          ],
-          title: "Controls",
-        },
-      },
-    });
-    const errors = validateContractAcceptance({
-      schema: schemaWithValidVisibleDependency,
-      acceptance: [
-        makeControlAcceptance("shapes.shadeCount", "slider"),
-        {
-          ...makeControlAcceptance("shapes.color3", "color"),
-          expectedObservable: "Третий цвет доступен только для соответствующего состояния продукта.",
-          userAction: "Переключить количество оттенков и проверить оба состояния.",
-          visibilityCoverage: ["hidden", "visible"],
-        },
-      ],
-    });
-
-    expect(errors).not.toEqual(
-      expect.arrayContaining([
-        expect.stringContaining("visibleWhen target"),
-        expect.stringContaining("uses visibleWhen and must declare visibilityCoverage"),
-      ]),
-    );
-  });
 });

package/templates/starter/src/app/starter-acceptance.custom-control-collections.test.ts

@@ -6,7 +6,7 @@ import {
 } from "./starter-acceptance.contract-fixtures";
 
 describe("starter acceptance custom control collection contract", () => {
-  it("requires collection-like custom controls to compare actions and collectionActions", () => {
+  it("requires collection-like custom controls to compare both cardinality owners and actions", () => {
     const schema = defineContractSchemaFixture({
       canvas: { enabled: true },
       panels: {
@@ -71,6 +71,7 @@ describe("starter acceptance custom control collection contract", () => {
         ],
       }),
     ).toEqual([
+      "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include sourceCollection when the custom control owns a repeated runtime item set whose cardinality could be source-owned.",
       "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
       "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include actions when the custom control exposes local command buttons such as add, remove, delete, duplicate, sort, normalize, or clear.",
     ]);
@@ -135,6 +136,7 @@ describe("starter acceptance custom control collection contract", () => {
         ],
       }),
     ).toEqual([
+      "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include sourceCollection when the custom control owns a repeated runtime item set whose cardinality could be source-owned.",
       "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
     ]);
   });

package/templates/starter/src/app/starter-acceptance.custom-control-valid.test.ts

@@ -48,7 +48,7 @@ describe("starter acceptance valid custom control contract", () => {
                 "reorder",
                 "selection",
               ],
-              checkedBuiltIns: ["actions", "collectionActions", "fileDrop", "imagePicker", "select"],
+              checkedBuiltIns: ["actions", "collectionActions", "fileDrop", "imagePicker", "select", "sourceCollection"],
               closestBuiltIn: "fileDrop",
               productObservable: "Ordering uploaded glyphs changes the rendered glyph ramp output.",
               whyInsufficient: "FileDrop imports source files, but it does not provide density ordering, per-glyph preview, reorder, and remove behavior in one runtime value.",