@pixel-point/toolcraft 0.0.17 → 0.0.19

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" },
   });
 }
@@ -47,6 +73,7 @@ export const contractSectionInventoryFixture: readonly ToolcraftControlSectionIn
 export const contractTransferModeFixture: ToolcraftTransferMode = {
   animationIntent: { mode: "none" },
   mode: "new-toolcraft-app",
+  referenceInputs: [],
 };
 
 export const contractProductReadinessFixture: ToolcraftProductReadiness = {
@@ -54,28 +81,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,225 @@
+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" },
+    svg: { mode: "not-requested" },
+    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-label-context.test.ts

@@ -52,6 +52,7 @@ describe("starter acceptance control label context contract", () => {
             reason: "The motion speed is a decorative self-running effect and does not expose product time transport.",
           },
           mode: "new-toolcraft-app",
+          referenceInputs: [],
         },
       }),
     ).toEqual([]);

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

@@ -259,8 +259,81 @@ describe("starter acceptance control label contract", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        'Accent Shades / accent1 uses visible label "Color 1" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
-        'Accent Shades / accent2 uses visible label "Color 2" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
+        'Accent Shades / accent1 uses visible label "Color 1" for one of multiple sibling colors. Set label: false when the colors form one shared bank, or use a distinct user-facing role such as Fill, Stroke, Background, Connector, or Object color.',
+        'Accent Shades / accent2 uses visible label "Color 2" for one of multiple sibling colors. Set label: false when the colors form one shared bank, or use a distinct user-facing role such as Fill, Stroke, Background, Connector, or Object color.',
+      ]),
+    );
+  });
+
+  it("rejects sequential labels for sibling colors without palette keywords", () => {
+    const schemaWithSpectrumColors = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                spectrum: {
+                  defaultValue: "custom",
+                  label: "Spectrum",
+                  options: [{ label: "Custom", value: "custom" }],
+                  target: "dispersion.spectrum",
+                  type: "select",
+                },
+                customColorA: {
+                  defaultValue: { hex: "#A65F15" },
+                  label: "Color 1",
+                  semanticGroup: "custom-spectrum",
+                  target: "dispersion.customColorA",
+                  type: "color",
+                },
+                customColorB: {
+                  defaultValue: { hex: "#371C4D" },
+                  label: "Color 2",
+                  semanticGroup: "custom-spectrum",
+                  target: "dispersion.customColorB",
+                  type: "color",
+                },
+                customColorC: {
+                  defaultValue: { hex: "#375B75" },
+                  label: "Color 3",
+                  semanticGroup: "custom-spectrum",
+                  target: "dispersion.customColorC",
+                  type: "color",
+                },
+                customColorD: {
+                  defaultValue: { hex: "#2A343E" },
+                  label: "Color 4",
+                  semanticGroup: "custom-spectrum",
+                  target: "dispersion.customColorD",
+                  type: "color",
+                },
+              },
+              title: "Spectrum",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithSpectrumColors,
+        acceptance: [
+          makeControlAcceptance("dispersion.spectrum", "select"),
+          makeControlAcceptance("dispersion.customColorA", "color"),
+          makeControlAcceptance("dispersion.customColorB", "color"),
+          makeControlAcceptance("dispersion.customColorC", "color"),
+          makeControlAcceptance("dispersion.customColorD", "color"),
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('customColorA uses visible label "Color 1"'),
+        expect.stringContaining('customColorB uses visible label "Color 2"'),
+        expect.stringContaining('customColorC uses visible label "Color 3"'),
+        expect.stringContaining('customColorD uses visible label "Color 4"'),
       ]),
     );
   });
@@ -312,7 +385,7 @@ describe("starter acceptance control label contract", () => {
     ).toEqual(
       expect.arrayContaining([
         "Accent Shades mixes labeled and unlabeled color items in one palette variation group. Decide label visibility for the whole group: omit all per-item labels when colors only add variety, or label every item only when each color has a distinct user-facing role.",
-        'Accent Shades / accent2 uses visible label "Color 2" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
+        'Accent Shades / accent2 uses visible label "Color 2" for one of multiple sibling colors. Set label: false when the colors form one shared bank, or use a distinct user-facing role such as Fill, Stroke, Background, Connector, or Object color.',
       ]),
     );
   });
@@ -328,12 +401,14 @@ describe("starter acceptance control label contract", () => {
                 accent1: {
                   defaultValue: { hex: "#9CE6FF" },
                   label: false,
+                  semanticGroup: "accent-palette",
                   target: "palette.accent1",
                   type: "color",
                 },
                 accent2: {
                   defaultValue: { hex: "#FF7A90" },
                   label: false,
+                  semanticGroup: "accent-palette",
                   target: "palette.accent2",
                   type: "color",
                 },

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

@@ -128,12 +128,88 @@ describe("starter acceptance control naming rules", () => {
     ).toEqual(
       expect.arrayContaining([
         expect.stringContaining(
-          'export.includeBackground) toggle label "Background" duplicates section title "Background". Use a shorter contextual label such as "Include" or rename the toggle to a more specific setting.',
+          'Background / includeBackground visible label "Background" duplicates section title "Background". Set label: false when the section supplies the complete visible context, or use a more specific label for a distinct setting.',
         ),
       ]),
     );
   });
 
+  it("rejects visible select labels that duplicate their section title", () => {
+    const schemaWithDuplicateSelectLabel = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                spectrum: {
+                  defaultValue: "custom",
+                  label: "Spectrum",
+                  options: [{ label: "Custom", value: "custom" }],
+                  target: "dispersion.spectrum",
+                  type: "select",
+                },
+              },
+              title: "Spectrum",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithDuplicateSelectLabel,
+        acceptance: [
+          makeControlAcceptance("dispersion.spectrum", "select"),
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          'Spectrum / spectrum visible label "Spectrum" duplicates section title "Spectrum". Set label: false when the section supplies the complete visible context, or use a more specific label for a distinct setting.',
+        ),
+      ]),
+    );
+  });
+
+  it("allows tabs accessibility names that match their section title", () => {
+    const schemaWithMatchingTabsName = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                spectrum: {
+                  defaultValue: "custom",
+                  label: "Spectrum",
+                  options: [{ label: "Custom", value: "custom" }],
+                  target: "dispersion.spectrum",
+                  type: "tabs",
+                },
+              },
+              title: "Spectrum",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateContractAcceptance({
+      schema: schemaWithMatchingTabsName,
+      acceptance: [makeControlAcceptance("dispersion.spectrum", "tabs")],
+    });
+
+    expect(errors).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("duplicates section title"),
+      ]),
+    );
+  });
+
   it("rejects single Actions controls that duplicate their only button label", () => {
     const schemaWithDuplicateActionLabel = defineContractSchemaFixture({
       canvas: { enabled: true },

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({