@pixel-point/toolcraft 0.0.17 → 0.0.18

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

@@ -0,0 +1,321 @@
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import {
+  getToolcraftApplicabilityRequirementId,
+  getToolcraftControlApplicabilityCases,
+} from "./control-applicability-cases";
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+const sectionInventory: readonly ToolcraftControlSectionInventoryEntry[] = [
+  {
+    entity: "Shape",
+    entityId: "shape",
+    groupingReason: "Source and shape selectors gate shape parameters.",
+    id: "shape",
+    targets: ["source.mode", "shape.kind", "shape.sides"],
+    title: "Shape",
+  },
+];
+
+function shapeSchema({
+  applicability = {
+    all: [
+      { equals: "create", target: "source.mode" },
+      { oneOf: ["polygon", "star"], target: "shape.kind" },
+    ],
+    mode: "conditional" as const,
+  },
+}: {
+  applicability?: {
+    all: readonly {
+      equals?: unknown;
+      oneOf?: readonly unknown[];
+      target: string;
+    }[];
+    mode: "conditional";
+  } | { mode: "always" };
+} = {}) {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              sourceMode: {
+                applicability: { mode: "always" },
+                defaultValue: "create",
+                options: [
+                  { label: "Upload", value: "upload" },
+                  { label: "Create", value: "create" },
+                ],
+                target: "source.mode",
+                type: "segmented",
+              },
+              shapeKind: {
+                applicability: { mode: "always" },
+                defaultValue: "polygon",
+                options: [
+                  { label: "Circle", value: "circle" },
+                  { label: "Polygon", value: "polygon" },
+                  { label: "Star", value: "star" },
+                ],
+                target: "shape.kind",
+                type: "segmented",
+              },
+              sides: {
+                applicability,
+                defaultValue: 6,
+                target: "shape.sides",
+                type: "slider",
+              },
+            },
+            id: "shape",
+            title: "Shape",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+describe("Toolcraft control applicability cases", () => {
+  it("derives deterministic pairwise cases from semantic inventory", () => {
+    const cases = getToolcraftControlApplicabilityCases({
+      schema: shapeSchema(),
+      sectionInventory,
+      target: "shape.sides",
+    });
+
+    expect(cases.map(({ expectation, selectorTarget, selectorValue, target }) => ({
+      expectation,
+      selectorTarget,
+      selectorValue,
+      target,
+    }))).toEqual([
+      {
+        expectation: "hidden",
+        selectorTarget: "source.mode",
+        selectorValue: "upload",
+        target: "shape.sides",
+      },
+      {
+        expectation: "visible",
+        selectorTarget: "source.mode",
+        selectorValue: "create",
+        target: "shape.sides",
+      },
+      {
+        expectation: "hidden",
+        selectorTarget: "shape.kind",
+        selectorValue: "circle",
+        target: "shape.sides",
+      },
+      {
+        expectation: "visible",
+        selectorTarget: "shape.kind",
+        selectorValue: "polygon",
+        target: "shape.sides",
+      },
+      {
+        expectation: "visible",
+        selectorTarget: "shape.kind",
+        selectorValue: "star",
+        target: "shape.sides",
+      },
+    ]);
+    expect(cases[0]).toEqual(
+      expect.objectContaining({
+        selectorControlType: "segmented",
+        selectorLabel: "sourceMode",
+        selectorOptionLabel: "Upload",
+      }),
+    );
+  });
+
+  it("treats omitted finite siblings as visible claims", () => {
+    const cases = getToolcraftControlApplicabilityCases({
+      schema: shapeSchema({
+        applicability: {
+          all: [{ oneOf: ["polygon", "star"], target: "shape.kind" }],
+          mode: "conditional",
+        },
+      }),
+      sectionInventory,
+      target: "shape.sides",
+    });
+
+    expect(cases.slice(0, 2)).toEqual([
+      expect.objectContaining({
+        expectation: "visible",
+        selectorTarget: "source.mode",
+        selectorValue: "upload",
+        target: "shape.sides",
+      }),
+      expect.objectContaining({
+        expectation: "visible",
+        selectorTarget: "source.mode",
+        selectorValue: "create",
+        target: "shape.sides",
+      }),
+    ]);
+  });
+
+  it("uses one path for always controls and stable encoded requirement ids", () => {
+    const cases = getToolcraftControlApplicabilityCases({
+      schema: shapeSchema({ applicability: { mode: "always" } }),
+      sectionInventory,
+      target: "shape.sides",
+    });
+
+    expect(cases.every((entry) => entry.expectation === "visible")).toBe(true);
+    expect(getToolcraftApplicabilityRequirementId("shape-sides", cases[0]!)).toBe(
+      "shape-sides#applicability:source.mode=%22upload%22:visible",
+    );
+  });
+
+  it("derives bounded numeric boundary cases without enumerating a range", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                count: {
+                  applicability: { mode: "always" },
+                  defaultValue: 2,
+                  max: 3,
+                  min: 1,
+                  step: 1,
+                  target: "shade.count",
+                  type: "slider",
+                  variant: "discrete",
+                },
+                thirdShade: {
+                  applicability: {
+                    all: [
+                      {
+                        greaterThanOrEqual: 3,
+                        target: "shade.count",
+                      },
+                    ],
+                    mode: "conditional",
+                  },
+                  target: "shade.third",
+                  type: "color",
+                },
+              },
+              id: "shades",
+              title: "Shades",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      getToolcraftControlApplicabilityCases({
+        schema,
+        sectionInventory: [
+          {
+            entity: "Shades",
+            entityId: "shades",
+            groupingReason: "Count controls the available shade colors.",
+            id: "shades",
+            targets: ["shade.count", "shade.third"],
+            title: "Shades",
+          },
+        ],
+        target: "shade.third",
+      }).map(({ expectation, selectorTarget, selectorValue, target }) => ({
+        expectation,
+        selectorTarget,
+        selectorValue,
+        target,
+      })),
+    ).toEqual([
+      {
+        expectation: "hidden",
+        selectorTarget: "shade.count",
+        selectorValue: 1,
+        target: "shade.third",
+      },
+      {
+        expectation: "hidden",
+        selectorTarget: "shade.count",
+        selectorValue: 2,
+        target: "shade.third",
+      },
+      {
+        expectation: "visible",
+        selectorTarget: "shade.count",
+        selectorValue: 3,
+        target: "shade.third",
+      },
+    ]);
+  });
+
+  it("uses the resolved Setup product subset only as the inventory fallback", () => {
+    const schema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                background: {
+                  applicability: { mode: "always" },
+                  defaultValue: "#101010",
+                  target: "appearance.background",
+                  type: "color",
+                },
+                includeBackground: {
+                  applicability: { mode: "always" },
+                  defaultValue: true,
+                  target: "export.includeBackground",
+                  type: "switch",
+                },
+              },
+              id: "background",
+              title: "Background",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      getToolcraftControlApplicabilityCases({
+        schema,
+        sectionInventory: [],
+        target: "appearance.background",
+      }).map(({ expectation, selectorTarget, selectorValue, target }) => ({
+        expectation,
+        selectorTarget,
+        selectorValue,
+        target,
+      })),
+    ).toEqual([
+      {
+        expectation: "visible",
+        selectorTarget: "export.includeBackground",
+        selectorValue: false,
+        target: "appearance.background",
+      },
+      {
+        expectation: "visible",
+        selectorTarget: "export.includeBackground",
+        selectorValue: true,
+        target: "appearance.background",
+      },
+    ]);
+  });
+});

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

@@ -0,0 +1,290 @@
+import {
+  doesToolcraftApplicabilityMatch,
+  doesToolcraftPredicateMatchValue,
+  getToolcraftApplicabilityPredicates,
+  type ResolvedToolcraftAppSchema,
+  type ResolvedToolcraftControlSchema,
+  type ToolcraftControlPredicateSchema,
+} from "@repo/toolcraft-runtime";
+
+import { getToolcraftApplicabilitySelectorDomain } from "./control-applicability";
+import {
+  isToolcraftProductSectionControl,
+  isToolcraftVisibleAcceptanceControl,
+} from "./controls";
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+export type ToolcraftControlApplicabilityCase = Readonly<{
+  expectation: "hidden" | "visible";
+  selectorControlType:
+    | "checkbox"
+    | "imagePicker"
+    | "segmented"
+    | "select"
+    | "slider"
+    | "switch"
+    | "tabs";
+  selectorLabel: string;
+  selectorOptionLabel?: string;
+  selectorTarget: string;
+  selectorValue: boolean | number | string;
+  target: string;
+}>;
+
+type IndexedControl = Readonly<{
+  control: ResolvedToolcraftControlSchema;
+  id: string;
+  sectionId: string;
+}>;
+
+type ApplicabilitySelectorControlType =
+  ToolcraftControlApplicabilityCase["selectorControlType"];
+
+function indexControls(
+  schema: Pick<ResolvedToolcraftAppSchema, "panels">,
+): Map<string, IndexedControl> {
+  const controls = new Map<string, IndexedControl>();
+
+  for (const section of schema.panels.controls?.sections ?? []) {
+    for (const [id, control] of Object.entries(section.controls)) {
+      controls.set(control.target, { control, id, sectionId: section.id });
+    }
+  }
+
+  return controls;
+}
+
+function getApplicabilitySelectorControlType(
+  control: ResolvedToolcraftControlSchema,
+): ApplicabilitySelectorControlType | null {
+  switch (control.type) {
+    case "checkbox":
+    case "imagePicker":
+    case "segmented":
+    case "select":
+    case "slider":
+    case "switch":
+    case "tabs":
+      return control.type;
+    default:
+      return null;
+  }
+}
+
+function getSelectorOptionLabel(
+  control: ResolvedToolcraftControlSchema,
+  value: boolean | number | string,
+): string | undefined {
+  if (
+    control.type === "select" ||
+    control.type === "segmented" ||
+    control.type === "tabs"
+  ) {
+    return control.options?.find((option) => option.value === value)?.label;
+  }
+
+  if (control.type === "imagePicker") {
+    const item = control.items?.find((candidate) => candidate.value === value);
+    return item ? (item.alt ?? item.value) : undefined;
+  }
+
+  return undefined;
+}
+
+function getSemanticPeerTargets({
+  dependent,
+  sectionInventory,
+  schema,
+}: {
+  dependent: IndexedControl;
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
+  schema: Pick<ResolvedToolcraftAppSchema, "panels">;
+}): readonly string[] {
+  const inventoryEntry = sectionInventory.find((entry) =>
+    entry.targets.includes(dependent.control.target),
+  );
+
+  if (inventoryEntry) {
+    return inventoryEntry.targets;
+  }
+
+  if (dependent.sectionId !== "runtime.setup") {
+    return [];
+  }
+
+  const setupSection = schema.panels.controls?.sections.find(
+    (section) => section.id === "runtime.setup",
+  );
+
+  return Object.values(setupSection?.controls ?? {})
+    .filter(isToolcraftProductSectionControl)
+    .map((control) => control.target);
+}
+
+function getPredicatesTargeting(
+  controlsByTarget: ReadonlyMap<string, IndexedControl>,
+  peerTargets: readonly string[],
+  selectorTarget: string,
+): ToolcraftControlPredicateSchema[] {
+  return peerTargets.flatMap((target) => {
+    const applicabilityControl = controlsByTarget.get(target)?.control;
+    const applicability = applicabilityControl?.applicability;
+
+    return applicability
+      ? getToolcraftApplicabilityPredicates(applicability).filter(
+          (predicate) => predicate.target === selectorTarget,
+        )
+      : [];
+  });
+}
+
+function getSatisfyingBaseline(
+  dependent: ResolvedToolcraftControlSchema,
+  controlsByTarget: ReadonlyMap<string, IndexedControl>,
+): Map<string, boolean | number | string> {
+  const baseline = new Map<string, boolean | number | string>();
+  const predicates = getToolcraftApplicabilityPredicates(
+    dependent.applicability,
+  );
+  const predicatesByTarget = new Map<string, ToolcraftControlPredicateSchema[]>();
+
+  for (const predicate of predicates) {
+    const targetPredicates = predicatesByTarget.get(predicate.target) ?? [];
+    targetPredicates.push(predicate);
+    predicatesByTarget.set(predicate.target, targetPredicates);
+  }
+
+  for (const [target, targetPredicates] of predicatesByTarget) {
+    const selector = controlsByTarget.get(target)?.control;
+
+    if (!selector) {
+      continue;
+    }
+
+    const domain = getToolcraftApplicabilitySelectorDomain(
+      selector,
+      targetPredicates,
+    );
+
+    if (domain.status !== "supported") {
+      continue;
+    }
+
+    const value = domain.values.find((candidate) =>
+      targetPredicates.every((predicate) =>
+        doesToolcraftPredicateMatchValue(predicate, candidate),
+      ),
+    );
+
+    if (value !== undefined) {
+      baseline.set(target, value);
+    }
+  }
+
+  return baseline;
+}
+
+export function getToolcraftControlApplicabilityCases(
+  input: Readonly<{
+    schema: Pick<ResolvedToolcraftAppSchema, "panels">;
+    sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
+    target: string;
+  }>,
+): ToolcraftControlApplicabilityCase[] {
+  const controlsByTarget = indexControls(input.schema);
+  const dependent = controlsByTarget.get(input.target);
+
+  if (
+    !dependent ||
+    !isToolcraftVisibleAcceptanceControl(dependent.control)
+  ) {
+    return [];
+  }
+
+  const peerTargets = getSemanticPeerTargets({
+    dependent,
+    schema: input.schema,
+    sectionInventory: input.sectionInventory,
+  });
+  const baseline = getSatisfyingBaseline(dependent.control, controlsByTarget);
+  const cases: ToolcraftControlApplicabilityCase[] = [];
+
+  for (const selectorTarget of peerTargets) {
+    if (selectorTarget === dependent.control.target) {
+      continue;
+    }
+
+    const indexedSelector = controlsByTarget.get(selectorTarget);
+
+    if (!indexedSelector) {
+      continue;
+    }
+    const { control: selector } = indexedSelector;
+
+    const peerPredicates = getPredicatesTargeting(
+      controlsByTarget,
+      peerTargets,
+      selectorTarget,
+    );
+
+    if (selector.type === "slider" && peerPredicates.length === 0) {
+      continue;
+    }
+
+    const domain = getToolcraftApplicabilitySelectorDomain(
+      selector,
+      peerPredicates,
+    );
+
+    if (domain.status !== "supported") {
+      continue;
+    }
+
+    const selectorControlType = getApplicabilitySelectorControlType(selector);
+
+    if (!selectorControlType) {
+      continue;
+    }
+
+    for (const selectorValue of domain.values) {
+      const values = new Map(baseline);
+      values.set(selectorTarget, selectorValue);
+      const selectorOptionLabel = getSelectorOptionLabel(
+        selector,
+        selectorValue,
+      );
+      const matches = doesToolcraftApplicabilityMatch(
+        dependent.control.applicability,
+        (target) =>
+          values.get(target) ??
+          controlsByTarget.get(target)?.control.defaultValue,
+      );
+
+      cases.push({
+        expectation: matches ? "visible" : "hidden",
+        selectorControlType,
+        selectorLabel:
+          typeof selector.label === "string"
+            ? selector.label
+            : indexedSelector.id,
+        ...(selectorOptionLabel ? { selectorOptionLabel } : {}),
+        selectorTarget,
+        selectorValue,
+        target: dependent.control.target,
+      });
+    }
+  }
+
+  return cases;
+}
+
+export function getToolcraftApplicabilityRequirementId(
+  baseRequirementId: string,
+  applicabilityCase: ToolcraftControlApplicabilityCase,
+): string {
+  const serializedValue =
+    JSON.stringify(applicabilityCase.selectorValue) ??
+    String(applicabilityCase.selectorValue);
+
+  return `${baseRequirementId}#applicability:${applicabilityCase.selectorTarget}=${encodeURIComponent(serializedValue)}:${applicabilityCase.expectation}`;
+}