@pixel-point/toolcraft 0.0.17 → 0.0.18

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

@@ -0,0 +1,332 @@
+import {
+  areToolcraftPredicatesProvablyExclusive,
+  areToolcraftValuesEqual,
+  doesToolcraftPredicateMatchValue,
+  getToolcraftApplicabilityPredicates,
+  type ResolvedToolcraftControlSchema,
+  type ToolcraftControlPredicateSchema,
+} from "@repo/toolcraft-runtime";
+
+import type { ToolcraftAcceptanceValidationContext } from "./validation-pipeline";
+
+export type ToolcraftApplicabilitySelectorValue = boolean | number | string;
+
+export type ToolcraftApplicabilitySelectorDomain =
+  | Readonly<{
+      status: "supported";
+      values: readonly ToolcraftApplicabilitySelectorValue[];
+    }>
+  | Readonly<{
+      reason: string;
+      status: "unsupported";
+    }>;
+
+const numericOperators = [
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+] as const;
+
+function addUniqueValue(
+  values: ToolcraftApplicabilitySelectorValue[],
+  value: unknown,
+): void {
+  if (
+    (typeof value === "boolean" ||
+      typeof value === "number" ||
+      typeof value === "string") &&
+    !values.some((existing) => areToolcraftValuesEqual(existing, value))
+  ) {
+    values.push(value);
+  }
+}
+
+function getPredicateFiniteValues(
+  predicate: ToolcraftControlPredicateSchema,
+): unknown[] {
+  return [
+    ...(Object.prototype.hasOwnProperty.call(predicate, "equals")
+      ? [predicate.equals]
+      : []),
+    ...(Object.prototype.hasOwnProperty.call(predicate, "notEquals")
+      ? [predicate.notEquals]
+      : []),
+    ...(predicate.oneOf ?? []),
+    ...(predicate.notOneOf ?? []),
+  ];
+}
+
+function getDiscreteSliderDomain(
+  control: ResolvedToolcraftControlSchema,
+  predicates: readonly ToolcraftControlPredicateSchema[],
+): ToolcraftApplicabilitySelectorDomain {
+  if (
+    control.type !== "slider" ||
+    control.variant !== "discrete" ||
+    typeof control.min !== "number" ||
+    typeof control.max !== "number" ||
+    typeof control.step !== "number" ||
+    !Number.isFinite(control.min) ||
+    !Number.isFinite(control.max) ||
+    !Number.isFinite(control.step) ||
+    control.max < control.min ||
+    control.step <= 0
+  ) {
+    return {
+      reason: `${control.target} is not a bounded discrete scalar slider`,
+      status: "unsupported",
+    };
+  }
+
+  const { max, min, step } = control;
+  const candidates: number[] = [];
+  const clampAligned = (value: number): number => {
+    const clamped = Math.min(max, Math.max(min, value));
+    const stepIndex = Math.round((clamped - min) / step);
+    const aligned = Math.min(max, Math.max(min, min + stepIndex * step));
+    return Number(aligned.toFixed(12));
+  };
+  const addCandidate = (value: unknown): void => {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      return;
+    }
+
+    for (const candidate of [value - step, value, value + step]) {
+      const aligned = clampAligned(candidate);
+
+      if (!candidates.includes(aligned)) {
+        candidates.push(aligned);
+      }
+    }
+  };
+
+  addCandidate(min);
+  addCandidate(max);
+  addCandidate(control.defaultValue);
+
+  for (const predicate of predicates) {
+    for (const value of getPredicateFiniteValues(predicate)) {
+      addCandidate(value);
+    }
+    for (const operator of numericOperators) {
+      addCandidate(predicate[operator]);
+    }
+  }
+
+  return {
+    status: "supported",
+    values: candidates.sort((left, right) => left - right),
+  };
+}
+
+export function getToolcraftApplicabilitySelectorDomain(
+  control: ResolvedToolcraftControlSchema,
+  predicates: readonly ToolcraftControlPredicateSchema[],
+): ToolcraftApplicabilitySelectorDomain {
+  if (
+    control.type === "select" ||
+    control.type === "segmented" ||
+    control.type === "tabs"
+  ) {
+    const values: ToolcraftApplicabilitySelectorValue[] = [];
+
+    for (const option of control.options ?? []) {
+      addUniqueValue(values, option.value);
+    }
+
+    return values.length > 0
+      ? { status: "supported", values }
+      : {
+          reason: `${control.target} has no declared selector options`,
+          status: "unsupported",
+        };
+  }
+
+  if (control.type === "imagePicker") {
+    const values: ToolcraftApplicabilitySelectorValue[] = [];
+
+    for (const item of control.items ?? []) {
+      addUniqueValue(values, item.value);
+    }
+
+    return values.length > 0
+      ? { status: "supported", values }
+      : {
+          reason: `${control.target} has no declared image picker items`,
+          status: "unsupported",
+        };
+  }
+
+  if (control.type === "switch" || control.type === "checkbox") {
+    return { status: "supported", values: [false, true] };
+  }
+
+  return getDiscreteSliderDomain(control, predicates);
+}
+
+function getInvalidFinitePredicateValues(
+  predicates: readonly ToolcraftControlPredicateSchema[],
+  domain: readonly ToolcraftApplicabilitySelectorValue[],
+): unknown[] {
+  const values: unknown[] = [];
+
+  for (const predicate of predicates) {
+    for (const value of getPredicateFiniteValues(predicate)) {
+      if (
+        !domain.some((candidate) =>
+          areToolcraftValuesEqual(candidate, value),
+        ) &&
+        !values.some((candidate) =>
+          areToolcraftValuesEqual(candidate, value),
+        )
+      ) {
+        values.push(value);
+      }
+    }
+  }
+
+  return values;
+}
+
+function predicatesArePairwiseExclusive(
+  predicates: readonly ToolcraftControlPredicateSchema[],
+): boolean {
+  for (let leftIndex = 0; leftIndex < predicates.length; leftIndex += 1) {
+    for (
+      let rightIndex = leftIndex + 1;
+      rightIndex < predicates.length;
+      rightIndex += 1
+    ) {
+      const left = predicates[leftIndex];
+      const right = predicates[rightIndex];
+
+      if (
+        left &&
+        right &&
+        areToolcraftPredicatesProvablyExclusive(left, right)
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function getToolcraftControlApplicabilityErrors({
+  controls,
+  productReadiness,
+}: Pick<
+  ToolcraftAcceptanceValidationContext,
+  "controls" | "productReadiness"
+>): string[] {
+  if (productReadiness.mode !== "product") {
+    return [];
+  }
+
+  const errors: string[] = [];
+  const controlsByTarget = new Map(
+    controls.map(({ control }) => [control.target, control] as const),
+  );
+
+  for (const { control } of controls) {
+    const { applicability } = control;
+
+    if (applicability.origin === "implicit") {
+      errors.push(
+        `${control.target} must declare explicit applicability as always or conditional.`,
+      );
+      continue;
+    }
+
+    if (applicability.origin === "legacy") {
+      errors.push(
+        `${control.target} uses legacy visibleWhen; product controls must declare explicit applicability.`,
+      );
+    }
+
+    const predicates = getToolcraftApplicabilityPredicates(applicability);
+    const predicatesByTarget = new Map<
+      string,
+      ToolcraftControlPredicateSchema[]
+    >();
+
+    for (const predicate of predicates) {
+      const selector = controlsByTarget.get(predicate.target);
+
+      if (!selector) {
+        errors.push(
+          `${control.target} predicate target "${predicate.target}" does not exist.`,
+        );
+        continue;
+      }
+
+      if (selector.target === control.target) {
+        errors.push(`${control.target} applicability cannot gate itself.`);
+        continue;
+      }
+
+      const targetPredicates = predicatesByTarget.get(predicate.target) ?? [];
+      targetPredicates.push(predicate);
+      predicatesByTarget.set(predicate.target, targetPredicates);
+    }
+
+    for (const [selectorTarget, targetPredicates] of predicatesByTarget) {
+      const selector = controlsByTarget.get(selectorTarget);
+
+      if (!selector) {
+        continue;
+      }
+
+      const domain = getToolcraftApplicabilitySelectorDomain(
+        selector,
+        targetPredicates,
+      );
+
+      if (domain.status === "unsupported") {
+        errors.push(
+          `${selector.target} is not a supported applicability selector: ${domain.reason}.`,
+        );
+        continue;
+      }
+
+      if (
+        selector.type === "select" ||
+        selector.type === "segmented" ||
+        selector.type === "tabs" ||
+        selector.type === "imagePicker" ||
+        selector.type === "switch" ||
+        selector.type === "checkbox"
+      ) {
+        for (const invalidValue of getInvalidFinitePredicateValues(
+          targetPredicates,
+          domain.values,
+        )) {
+          errors.push(
+            `${control.target} applicability value ${JSON.stringify(invalidValue)} is not an option of ${selector.target}.`,
+          );
+        }
+      }
+
+      if (predicatesArePairwiseExclusive(targetPredicates)) {
+        errors.push(`${control.target} applicability is unsatisfiable.`);
+        continue;
+      }
+
+      if (
+        !domain.values.some((value) =>
+          targetPredicates.every((predicate) =>
+            doesToolcraftPredicateMatchValue(predicate, value),
+          ),
+        )
+      ) {
+        errors.push(
+          `${control.target} has no satisfying value in ${selector.target}.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/control-layout-dependency-rules.ts

@@ -1,6 +1,9 @@
 import type {
   ToolcraftControlConditionSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+import {
+  getToolcraftApplicabilityPredicates,
 } from "@repo/toolcraft-runtime";
 
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
@@ -17,7 +20,7 @@ function normalizeToolcraftConditionValue(value: unknown): string | null {
 
 function getToolcraftConditionBranchTexts(
   condition: ToolcraftControlConditionSchema,
-  gateControl: ToolcraftControlSchema,
+  gateControl: ResolvedToolcraftControlSchema,
 ): string[] {
   const rawValues =
     "equals" in condition
@@ -44,7 +47,7 @@ function sectionTitleLooksLikeDependencyBranch({
   sectionTitle,
 }: {
   condition: ToolcraftControlConditionSchema;
-  gateControl: ToolcraftControlSchema;
+  gateControl: ResolvedToolcraftControlSchema;
   sectionTitle: string | undefined;
 }): boolean {
   const sectionText = normalizeToolcraftSemanticText(sectionTitle);
@@ -68,10 +71,18 @@ export function getToolcraftControlDependencyGroupingErrors(
   const errors: string[] = [];
 
   for (const item of facts.visibleControls) {
-    for (const [conditionName, condition] of [
-      ["visibleWhen", item.control.visibleWhen],
-      ["disabledWhen", item.control.disabledWhen],
-    ] as const) {
+    const conditions = [
+      ...getToolcraftApplicabilityPredicates(
+        item.control.applicability,
+      ).map(
+        (condition) => ["applicability", condition] as const,
+      ),
+      ...(item.control.disabledWhen
+        ? [["disabledWhen", item.control.disabledWhen] as const]
+        : []),
+    ];
+
+    for (const [conditionName, condition] of conditions) {
       if (!condition || !item.loosePrefix) {
         continue;
       }
@@ -86,7 +97,7 @@ export function getToolcraftControlDependencyGroupingErrors(
         gateControl.loosePrefix !== null &&
         gateControl.loosePrefix === item.loosePrefix;
       const looksLikeBranchSection =
-        conditionName === "visibleWhen" &&
+        conditionName === "applicability" &&
         sectionTitleLooksLikeDependencyBranch({
           condition,
           gateControl: gateControl.control,
@@ -98,7 +109,7 @@ export function getToolcraftControlDependencyGroupingErrors(
       }
 
       errors.push(
-        `${item.sectionLabel} / ${item.controlId} is gated by ${conditionName} target "${condition.target}" in ${gateControl.sectionLabel}, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.`,
+        `${item.sectionLabel} / ${item.controlId} is gated by ${conditionName} target "${condition.target}" in ${gateControl.sectionLabel}, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use conditional applicability for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.`,
       );
     }
   }

package/templates/starter/src/app/acceptance/control-layout-entity-rules.ts

@@ -2,10 +2,8 @@ import {
   getToolcraftFontPickerOwnedTypographyPart,
 } from "./control-labels";
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
-import {
-  getToolcraftSectionInventoryById,
-  hasToolcraftInventorySplitEvidence,
-} from "./control-section-inventory";
+import { hasToolcraftInventoryEntityAgreement } from "./control-section-entity-cohesion";
+import { getToolcraftSectionInventoryById } from "./control-section-inventory";
 import { getControlLabelText } from "./controls";
 import type { ToolcraftControlSectionInventoryEntry } from "./types";
 
@@ -60,13 +58,13 @@ function getToolcraftProductEntitySplitErrors({
   for (const [prefix, sections] of facts.strictPrefixSections) {
     if (
       sections.size > 1 &&
-      !hasToolcraftInventorySplitEvidence({ sectionInventoryById, sections })
+      !hasToolcraftInventoryEntityAgreement({ sectionInventoryById, sections })
     ) {
       const sectionLabels = [...sections].map(
         (sectionId) => facts.sectionLabelsById.get(sectionId) ?? sectionId,
       );
       errors.push(
-        `Controls for product entity "${prefix}" are split across sections: ${sectionLabels.join(", ")}. Keep controls for the same product entity in one semantic section unless the Control Section Inventory declares workflowStage and splitReason for every split section.`,
+        `Controls for target family "${prefix}" are split across sections: ${sectionLabels.join(", ")}. Assign one shared entityId when the sections edit one logical entity; the entity cohesion validator decides whether that split is allowed.`,
       );
     }
   }

package/templates/starter/src/app/acceptance/control-layout-model.ts

@@ -1,6 +1,6 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
 } from "@repo/toolcraft-runtime";
 
 import { isToolcraftProductSectionControl } from "./controls";
@@ -12,7 +12,7 @@ import {
 } from "./semantic";
 
 export type ToolcraftControlLayoutControlEntry = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   loosePrefix: string | null;
   sectionLabel: string;
@@ -21,7 +21,7 @@ export type ToolcraftControlLayoutControlEntry = {
 };
 
 export type ToolcraftControlLayoutSectionFact = {
-  controls: readonly [string, ToolcraftControlSchema][];
+  controls: readonly [string, ResolvedToolcraftControlSchema][];
   sectionLabel: string;
   sectionId: string;
   sectionLoosePrefixes: ReadonlySet<string>;
@@ -41,7 +41,7 @@ export type ToolcraftControlLayoutFacts = {
 };
 
 function getToolcraftControlSemanticCluster(
-  control: ToolcraftControlSchema,
+  control: ResolvedToolcraftControlSchema,
 ): string {
   return (
     control.semanticGroup?.trim() ||

package/templates/starter/src/app/acceptance/control-layout-section-rules.ts

@@ -7,6 +7,7 @@ import {
   getToolcraftGenericControlLabelError,
 } from "./control-labels";
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
+import { TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS } from "./control-section-entity-cohesion";
 import {
   controlTypeSectionTitlePattern,
   genericControlSectionTitlePattern,
@@ -15,9 +16,6 @@ import {
 const broadControlSectionTitlePattern =
   /^(animation|export|flow|icon|logo|motion|output|scene|shape|shapes|text|typography|visual|visuals)$/i;
 
-const maxPreferredControlsPerSection = 7;
-const maxHardControlsPerSection = 10;
-
 export function getToolcraftControlLayoutSectionInvariantErrors(
   facts: ToolcraftControlLayoutFacts,
 ): string[] {
@@ -55,7 +53,7 @@ export function getToolcraftControlLayoutSectionInvariantErrors(
       .map(([controlId]) => controlId);
 
     if (
-      controls.length > maxPreferredControlsPerSection &&
+      controls.length >= TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS &&
       missingSemanticGroups.length > 0
     ) {
       errors.push(
@@ -135,7 +133,7 @@ export function getToolcraftControlLayoutSectionHeuristicErrors(
       sectionTitle !== undefined && broadControlSectionTitlePattern.test(sectionTitle);
 
     if (
-      controls.length > maxPreferredControlsPerSection &&
+      controls.length >= TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS &&
       hasBroadSectionTitle &&
       semanticClusters.size >= 3
     ) {
@@ -144,11 +142,6 @@ export function getToolcraftControlLayoutSectionHeuristicErrors(
       );
     }
 
-    if (controls.length > maxHardControlsPerSection && semanticClusters.size > 1) {
-      errors.push(
-        `${sectionLabel} has ${controls.length} controls across ${semanticClusters.size} semantic clusters (${clusterList}). Controls-panel sections should stay discrete; split sections that grow past ${maxHardControlsPerSection} controls unless every control edits one tightly scoped entity.`,
-      );
-    }
   }
 
   return errors;

package/templates/starter/src/app/acceptance/control-parts.ts

@@ -10,6 +10,12 @@ export function getRequiredToolcraftControlPartCoverage(
       return ["anchorGrid.position"];
     case "channelMixer":
       return ["channelMixer.activeChannel", "channelMixer.values"];
+    case "collectionActions":
+      return [
+        "collectionActions.add",
+        "collectionActions.remove",
+        "collectionActions.items",
+      ];
     case "curves":
       return control.variant === "single"
         ? ["curves.points"]
@@ -39,6 +45,8 @@ export function getRequiredToolcraftControlPartCoverage(
       return ["rangeInput.start", "rangeInput.end"];
     case "rangeSlider":
       return ["rangeSlider.lower", "rangeSlider.upper"];
+    case "sourceCollection":
+      return ["sourceCollection.items"];
     case "vector":
       return ["vector.x", "vector.y"];
     default: