@pixel-point/toolcraft 0.0.13 → 0.0.15

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

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import { makeControlAcceptance } from "./starter-acceptance.test-utils";
+
+describe("starter acceptance curves control rules", () => {
+  it("accepts single curves with points coverage only", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                easing: {
+                  defaultValue: {
+                    activeChannel: "RGB",
+                    points: {
+                      RGB: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                    },
+                  },
+                  curveIntent: "single-value-map",
+                  label: "Easing",
+                  target: "animation.easing",
+                  type: "curves",
+                  variant: "single",
+                },
+              },
+              title: "Motion",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateContractAcceptance({
+      schema: schema,
+      acceptance: [
+        {
+          automated: true,
+          automatedTestName: "easing curve changes motion output",
+          browser: true,
+          browserTestName: "browser: easing curve changes motion output",
+          componentType: "curves",
+          controlPartCoverage: ["curves.points"],
+          evidence: "product-output",
+          expectedObservable: "Changing Easing curve points changes animation timing.",
+          fixture: "motion fixture",
+          id: "animation.easing",
+          kind: "control",
+          target: "animation.easing",
+          userAction: "Drag an Easing curve point.",
+        },
+      ],
+    });
+
+    expect(errors).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("curves.activeChannel"),
+      ]),
+    );
+  });
+
+  it("requires typed one-dimensional curves to use the single variant", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                bendCurve: {
+                  defaultValue: {
+                    activeChannel: "RGB",
+                    points: {
+                      B: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                      G: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                      R: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                      RGB: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                    },
+                  },
+                  curveIntent: "single-value-map",
+                  label: "Curva",
+                  target: "shape.bendCurve",
+                  type: "curves",
+                },
+              },
+              title: "Shape",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateContractAcceptance({
+      schema: schema,
+      acceptance: [
+        {
+          automated: true,
+          automatedTestName: "bend curve changes geometry output",
+          browser: true,
+          browserTestName: "browser: bend curve changes geometry output",
+          componentType: "curves",
+          controlPartCoverage: ["curves.activeChannel", "curves.points"],
+          evidence: "product-output",
+          expectedObservable: "Changing Bend curve points changes the rendered shape bend.",
+          fixture: "shape fixture",
+          id: "shape.bendCurve",
+          kind: "control",
+          target: "shape.bendCurve",
+          userAction: "Drag a Bend curve point.",
+        },
+      ],
+    });
+
+    expect(errors).toEqual(
+      expect.arrayContaining([
+        'Shape / bendCurve (shape.bendCurve) is a semantic single curve and must set variant: "single"; RGB/R/G/B curve tabs are reserved for color-correction or channel-specific curves.',
+      ]),
+    );
+  });
+
+  it("requires every curve to declare language-independent intent", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                response: {
+                  defaultValue: {
+                    activeChannel: "RGB",
+                    points: {
+                      RGB: [
+                        { x: 0, y: 0 },
+                        { x: 1, y: 1 },
+                      ],
+                    },
+                  },
+                  label: "Respuesta",
+                  target: "motion.response",
+                  type: "curves",
+                  variant: "single",
+                },
+              },
+              title: "Movimiento",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema,
+        acceptance: [
+          makeControlAcceptance("motion.response", "curves"),
+        ],
+      }),
+    ).toContain(
+      'Movimiento / response (motion.response) must declare curveIntent "single-value-map" or "color-channels" so the curve composition does not depend on its label.',
+    );
+  });
+});

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

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+
+describe("starter acceptance custom control collection contract", () => {
+  it("requires collection-like custom controls to compare actions and collectionActions", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                maskEditor: {
+                  defaultValue: { items: [], selectedId: null },
+                  label: "Mask shapes",
+                  orderRole: "spatial",
+                  target: "masks",
+                  type: "maskEditor",
+                } as never,
+              },
+              title: "Masks",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "mask editor changes output",
+            browser: true,
+            browserTestName: "browser: mask editor changes output",
+            builtInFitCheck: {
+              capabilities: [
+                "collection",
+                "selection",
+                "commands",
+                "custom-interaction",
+                "custom-value-model",
+              ],
+              checkedBuiltIns: ["select", "vector"],
+              closestBuiltIn: "vector",
+              productObservable: "Adding, selecting, deleting, dragging, and resizing masks changes the composited output.",
+              whyInsufficient: "Vector can edit one point, but this product needs multiple shape commands, selected item state, deletion, drag, and resize handles.",
+            },
+            componentType: "maskEditor",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Adding rectangle, circle, and triangle masks creates selected editable shapes.",
+            fixture: "uploaded image with masks",
+            id: "masks",
+            kind: "control",
+            target: "masks",
+            userAction: "Add each mask shape, select a mask in the list, delete one mask, drag a canvas mask handle, and resize a selected mask.",
+          },
+        ],
+      }),
+    ).toEqual([
+      "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.",
+    ]);
+  });
+
+  it("detects collection-like custom controls from the value model instead of entity names", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                patternSet: {
+                  defaultValue: { entries: [], selectedId: null },
+                  label: "Pattern set",
+                  orderRole: "style",
+                  target: "pattern.set",
+                  type: "patternSetEditor",
+                } as never,
+              },
+              title: "Pattern",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "pattern set changes output",
+            browser: true,
+            browserTestName: "browser: pattern set changes output",
+            builtInFitCheck: {
+              capabilities: ["collection", "selection", "custom-value-model"],
+              checkedBuiltIns: ["select", "vector"],
+              closestBuiltIn: "select",
+              productObservable: "Editing the chosen pattern entry changes the rendered pattern output.",
+              whyInsufficient: "Select can choose one preset, but this product needs runtime entry state with selected item editing.",
+            },
+            componentType: "patternSetEditor",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Editing the pattern set changes the rendered product output.",
+            fixture: "pattern set fixture",
+            id: "pattern.set",
+            kind: "control",
+            target: "pattern.set",
+            userAction: "Edit the selected entry.",
+          },
+        ],
+      }),
+    ).toEqual([
+      "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
+    ]);
+  });
+
+  it("does not treat numeric tuple custom values as collection owners", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                focalPoint: {
+                  defaultValue: [0.5, 0.5],
+                  label: "Focal point",
+                  orderRole: "spatial",
+                  target: "focal.point",
+                  type: "focalPointPad",
+                } as never,
+              },
+              title: "Focus",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "focal point changes output",
+            browser: true,
+            browserTestName: "browser: focal point changes output",
+            builtInFitCheck: {
+              capabilities: ["custom-interaction"],
+              checkedBuiltIns: ["vector"],
+              closestBuiltIn: "vector",
+              productObservable: "Dragging the focal point changes the rendered focus position.",
+              whyInsufficient: "Vector edits x/y, but this product needs a canvas hit target with validation tied to the rendered focal point.",
+            },
+            componentType: "focalPointPad",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Dragging the focal point changes the rendered product output.",
+            fixture: "focus fixture",
+            id: "focal.point",
+            kind: "control",
+            target: "focal.point",
+            userAction: "Drag the focal point.",
+          },
+        ],
+      }),
+    ).toEqual([]);
+  });
+});

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

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+
+describe("starter acceptance custom control coverage contract", () => {
+  it("requires custom controls to explain why they are custom and prove minimal runtime UI", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                glyphRamp: {
+                  defaultValue: [],
+                  label: "Glyph ramp",
+                  orderRole: "input",
+                  target: "glyph.ramp",
+                  type: "glyphRamp",
+                } as never,
+              },
+              title: "Glyphs",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "glyph ramp changes output",
+            browser: true,
+            browserTestName: "browser: glyph ramp changes output",
+            componentType: "glyphRamp",
+            evidence: "product-output",
+            expectedObservable: "Choosing and ordering glyphs changes the rendered product output.",
+            fixture: "glyph ramp fixture",
+            id: "glyph.ramp",
+            kind: "control",
+            target: "glyph.ramp",
+            userAction: "Upload, reorder, and remove glyphs.",
+          },
+        ],
+      }),
+    ).toContain(
+      "Glyphs / glyphRamp (glyph.ramp) is a custom control and must declare customControlCoverage for: built-in-gap, kit-primitives, minimal-ui, product-output, runtime-state.",
+    );
+  });
+
+  it("requires custom controls to include a built-in fit check", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                glyphRamp: {
+                  defaultValue: [],
+                  label: "Glyph ramp",
+                  orderRole: "input",
+                  target: "glyph.ramp",
+                  type: "glyphRamp",
+                } as never,
+              },
+              title: "Glyphs",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "glyph ramp changes output",
+            browser: true,
+            browserTestName: "browser: glyph ramp changes output",
+            componentType: "glyphRamp",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Choosing and ordering glyphs changes the rendered product output.",
+            fixture: "glyph ramp fixture",
+            id: "glyph.ramp",
+            kind: "control",
+            target: "glyph.ramp",
+            userAction: "Upload, reorder, and remove glyphs.",
+          },
+        ],
+      }),
+    ).toContain(
+      "Glyphs / glyphRamp (glyph.ramp) is a custom control and must declare builtInFitCheck with checkedBuiltIns, closestBuiltIn, whyInsufficient, and productObservable.",
+    );
+  });
+});

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

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+
+describe("starter acceptance custom control built-in fit contract", () => {
+  it("rejects custom controls with invalid built-in fit checks", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                glyphRamp: {
+                  defaultValue: [],
+                  label: "Glyph ramp",
+                  orderRole: "input",
+                  target: "glyph.ramp",
+                  type: "glyphRamp",
+                } as never,
+              },
+              title: "Glyphs",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "glyph ramp changes output",
+            browser: true,
+            browserTestName: "browser: glyph ramp changes output",
+            builtInFitCheck: {
+              capabilities: [],
+              checkedBuiltIns: ["imaginaryPicker" as never],
+              closestBuiltIn: "glyphRamp" as never,
+              productObservable: "Ordering uploaded glyphs changes the rendered glyph ramp output.",
+              whyInsufficient: "The built-in controls cannot upload, preview, reorder, and remove a density-ordered glyph set in one runtime value.",
+            },
+            componentType: "glyphRamp",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Choosing and ordering glyphs changes the rendered product output.",
+            fixture: "glyph ramp fixture",
+            id: "glyph.ramp",
+            kind: "control",
+            target: "glyph.ramp",
+            userAction: "Upload, reorder, and remove glyphs.",
+          },
+        ],
+      }),
+    ).toEqual([
+      "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.capabilities must declare the product capabilities that require custom UI; prose labels are not capability evidence.",
+      "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.checkedBuiltIns contains unknown built-in controls: imaginaryPicker.",
+      'Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.closestBuiltIn must be one of the checked built-ins or "none".',
+      "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.capabilities must include custom-interaction, custom-value-model, or custom-visualization; collection or command chrome alone is not enough to justify custom UI.",
+    ]);
+  });
+
+  it("rejects custom controls justified only by visual chrome", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                shapeButtons: {
+                  defaultValue: "rect",
+                  label: "Shape",
+                  orderRole: "style",
+                  target: "shape.kind",
+                  type: "shapeButtons",
+                } as never,
+              },
+              title: "Shape",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "shape buttons change output",
+            browser: true,
+            browserTestName: "browser: shape buttons change output",
+            builtInFitCheck: {
+              capabilities: ["commands"],
+              checkedBuiltIns: ["actions", "segmented", "select"],
+              closestBuiltIn: "segmented",
+              productObservable: "Choosing a shape changes the rendered product geometry.",
+              whyInsufficient: "The custom control uses icon buttons and a compact visual layout.",
+            },
+            componentType: "shapeButtons",
+            customControlCoverage: [
+              "built-in-gap",
+              "kit-primitives",
+              "minimal-ui",
+              "product-output",
+              "runtime-state",
+            ],
+            evidence: "product-output",
+            expectedObservable: "Choosing rectangle, circle, or triangle changes the rendered output.",
+            fixture: "shape fixture",
+            id: "shape.kind",
+            kind: "control",
+            target: "shape.kind",
+            userAction: "Choose each shape icon button.",
+          },
+        ],
+      }),
+    ).toEqual([
+      "Shape / shapeButtons (shape.kind) builtInFitCheck.capabilities must include custom-interaction, custom-value-model, or custom-visualization; collection or command chrome alone is not enough to justify custom UI.",
+    ]);
+  });
+});