@pixel-point/toolcraft 0.0.17 → 0.0.19

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}`;
+}

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-component-rules.ts

@@ -168,7 +168,6 @@ export function getCurveIntentError(
 
 export function getToggleControlLabelError(
   control: ToolcraftControlSchema,
-  sectionTitle?: string,
 ): string | undefined {
   if (control.type !== "switch" && control.type !== "checkbox") {
     return undefined;
@@ -180,15 +179,6 @@ export function getToggleControlLabelError(
     return `toggle labels must name the setting context only; use "CRT", "Background", "Glow", or "Loop" instead of "${label}".`;
   }
 
-  if (
-    label &&
-    sectionTitle &&
-    normalizeToolcraftSemanticText(label) ===
-      normalizeToolcraftSemanticText(sectionTitle)
-  ) {
-    return `toggle label "${label}" duplicates section title "${sectionTitle}". Use a shorter contextual label such as "Include" or rename the toggle to a more specific setting.`;
-  }
-
   return undefined;
 }
 

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

@@ -1,6 +1,9 @@
 import type { ToolcraftControlSchema } from "@repo/toolcraft-runtime";
 
-import { getControlLabelText } from "./controls";
+import {
+  getControlLabelText,
+  hasVisibleControlLabel,
+} from "./controls";
 import {
   getToolcraftLooseTargetPrefix,
   getToolcraftTargetParts,
@@ -157,6 +160,32 @@ export function getToolcraftFontPickerOwnedTypographyPart(
   return undefined;
 }
 
+export function getToolcraftDuplicateSectionTitleLabelError({
+  control,
+  controlId,
+  sectionLabel,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionLabel: string;
+  sectionTitle: string | undefined;
+}): string | undefined {
+  if (
+    control.type === "tabs" ||
+    !sectionTitle ||
+    !hasVisibleControlLabel(control) ||
+    normalizeToolcraftSemanticText(getControlLabelText(control)) !==
+      normalizeToolcraftSemanticText(sectionTitle)
+  ) {
+    return undefined;
+  }
+
+  const label = getControlLabelText(control).trim();
+
+  return `${sectionLabel} / ${controlId} visible label "${label}" duplicates section title "${sectionTitle}". Set label: false when the section supplies the complete visible context, or use a more specific label for a distinct setting.`;
+}
+
 export function getToolcraftGenericControlLabelError({
   control,
   controlId,