@pixel-point/toolcraft 0.0.13 → 0.0.15

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

@@ -0,0 +1,223 @@
+import type { ToolcraftControlSchema } from "@repo/toolcraft-runtime";
+
+import { getControlLabelText } from "./controls";
+import {
+  getToolcraftLooseTargetPrefix,
+  getToolcraftTargetParts,
+  getToolcraftTargetProperty,
+  humanizeToolcraftLabelPart,
+  lowerCaseToolcraftLabelStart,
+  normalizeToolcraftSemanticText,
+} from "./semantic";
+import {
+  controlTypeSectionTitlePattern,
+  genericControlSectionTitlePattern,
+  weakControlLabelContextSectionTitlePattern,
+} from "./section-title-rules";
+
+const genericControlLabelPattern =
+  /^(angle|amount|blur|brightness|color|contrast|count|density|depth|frequency|height|hue|intensity|offset|opacity|phase|position|quality|radius|rotation|saturation|scale|size|spacing|speed|strength|threshold|tint|width)$/i;
+
+const fontPickerOwnedTypographyPartLabels = new Map<string, string>([
+  ["case", "case"],
+  ["color", "color"],
+  ["colour", "color"],
+  ["family", "font family"],
+  ["fill", "color"],
+  ["fillcolor", "color"],
+  ["fillopacity", "opacity"],
+  ["font", "font family"],
+  ["fontcolor", "color"],
+  ["fontfamily", "font family"],
+  ["fontid", "font family"],
+  ["fontsize", "font size"],
+  ["fontweight", "font weight"],
+  ["foreground", "color"],
+  ["foregroundcolor", "color"],
+  ["leading", "line height"],
+  ["letterspacing", "letter spacing"],
+  ["lineheight", "line height"],
+  ["opacity", "opacity"],
+  ["size", "font size"],
+  ["textcase", "case"],
+  ["textcolor", "color"],
+  ["textfill", "color"],
+  ["textopacity", "opacity"],
+  ["tracking", "letter spacing"],
+  ["typeface", "font family"],
+  ["weight", "font weight"],
+]);
+
+const fontPickerDescriptionOwnedPartPatterns: ReadonlyArray<readonly [string, RegExp]> = [
+  ["font family", /\b(?:font\s+family|family|typeface)\b/i],
+  ["font weight", /\b(?:font\s+weight|weight)\b/i],
+  ["font size", /\b(?:font\s+size|size)\b/i],
+  ["case", /\b(?:text\s+case|case|uppercase|lowercase|capitalize|title\s+case)\b/i],
+  ["color", /\b(?:text\s+color|font\s+color|color|colour|fill)\b/i],
+  ["opacity", /\b(?:text\s+opacity|font\s+opacity|opacity|alpha)\b/i],
+  ["letter spacing", /\b(?:letter\s+spacing|tracking)\b/i],
+  ["line height", /\b(?:line\s+height|leading)\b/i],
+];
+
+function isToolcraftWeakSectionContext(sectionTitle: string | undefined): boolean {
+  if (!sectionTitle) {
+    return true;
+  }
+
+  return (
+    genericControlSectionTitlePattern.test(sectionTitle) ||
+    controlTypeSectionTitlePattern.test(sectionTitle) ||
+    weakControlLabelContextSectionTitlePattern.test(sectionTitle)
+  );
+}
+
+function doesToolcraftSectionMatchTarget(
+  sectionTitle: string | undefined,
+  target: string,
+): boolean {
+  const sectionText = normalizeToolcraftSemanticText(sectionTitle);
+
+  if (!sectionText) {
+    return false;
+  }
+
+  return getToolcraftTargetParts(target).some((part) => {
+    const targetText = normalizeToolcraftSemanticText(part);
+    return (
+      targetText.length > 0 &&
+      (targetText === sectionText ||
+        targetText.includes(sectionText) ||
+        sectionText.includes(targetText))
+    );
+  });
+}
+
+function getToolcraftSuggestedControlLabel(
+  control: ToolcraftControlSchema,
+  sectionTitle: string | undefined,
+): string {
+  const label = getControlLabelText(control).trim();
+  const targetProperty = humanizeToolcraftLabelPart(control.target.split(".").at(-1) ?? "");
+  const normalizedLabel = normalizeToolcraftSemanticText(label);
+  const normalizedTargetProperty = normalizeToolcraftSemanticText(targetProperty);
+
+  if (
+    label &&
+    normalizedTargetProperty &&
+    normalizedTargetProperty !== normalizedLabel &&
+    normalizedTargetProperty.endsWith(normalizedLabel)
+  ) {
+    return targetProperty;
+  }
+
+  const property = label || targetProperty;
+  const loosePrefix = getToolcraftLooseTargetPrefix(control.target);
+  const prefixParts = loosePrefix ? getToolcraftTargetParts(loosePrefix) : [];
+  const prefixEntity = humanizeToolcraftLabelPart(prefixParts.at(-1) ?? "");
+  const sectionEntity =
+    sectionTitle && !isToolcraftWeakSectionContext(sectionTitle)
+      ? humanizeToolcraftLabelPart(sectionTitle)
+      : "";
+  const entity = prefixEntity || sectionEntity;
+
+  if (!entity) {
+    return property;
+  }
+
+  const normalizedEntity = normalizeToolcraftSemanticText(entity);
+  const normalizedProperty = normalizeToolcraftSemanticText(property);
+
+  if (normalizedEntity && normalizedProperty.includes(normalizedEntity)) {
+    return property;
+  }
+
+  return `${entity} ${lowerCaseToolcraftLabelStart(property)}`;
+}
+
+export function getToolcraftFontPickerOwnedTypographyPart(
+  control: ToolcraftControlSchema,
+): string | undefined {
+  if (control.type === "fontPicker") {
+    return undefined;
+  }
+
+  const normalizedCandidates = [
+    getToolcraftTargetProperty(control.target),
+    getControlLabelText(control),
+  ].map(normalizeToolcraftSemanticText);
+
+  for (const candidate of normalizedCandidates) {
+    const ownedPart = fontPickerOwnedTypographyPartLabels.get(candidate);
+
+    if (ownedPart) {
+      return ownedPart;
+    }
+  }
+
+  return undefined;
+}
+
+export function getToolcraftGenericControlLabelError({
+  control,
+  controlId,
+  sectionLabel,
+  sectionLoosePrefixCount,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionLabel: string;
+  sectionLoosePrefixCount: number;
+  sectionTitle: string | undefined;
+}): string | undefined {
+  const label = getControlLabelText(control).trim();
+
+  if (!genericControlLabelPattern.test(label)) {
+    return undefined;
+  }
+
+  const hasWeakContext =
+    isToolcraftWeakSectionContext(sectionTitle) ||
+    (sectionLoosePrefixCount > 1 &&
+      !doesToolcraftSectionMatchTarget(sectionTitle, control.target));
+
+  if (!hasWeakContext) {
+    return undefined;
+  }
+
+  const suggestedLabel = getToolcraftSuggestedControlLabel(control, sectionTitle);
+
+  return `${sectionLabel} / ${controlId} label "${label}" is too generic in this context. Short labels are allowed when the nearest visible section or group clearly names the affected product entity. Rename it to "${suggestedLabel}".`;
+}
+
+export function getToolcraftControlDescriptionError({
+  control,
+  controlId,
+  sectionLabel,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionLabel: string;
+  sectionTitle: string | undefined;
+}): string | undefined {
+  const description = control.description?.trim();
+
+  if (!description) {
+    return undefined;
+  }
+
+  if (control.type !== "fontPicker") {
+    return undefined;
+  }
+
+  const repeatedParts = fontPickerDescriptionOwnedPartPatterns
+    .filter(([, pattern]) => pattern.test(description))
+    .map(([part]) => part);
+
+  if (repeatedParts.length < 2) {
+    return undefined;
+  }
+
+  return `${sectionLabel} / ${controlId} description repeats FontPicker-owned fields (${repeatedParts.join(", ")}). FontPicker help must explain only non-obvious product behavior; use section titles and visible field labels for font family, weight, size, case, color, opacity, letter spacing, and line height, or omit description.`;
+}

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

@@ -0,0 +1,107 @@
+import type {
+  ToolcraftControlConditionSchema,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+
+import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
+import { normalizeToolcraftSemanticText } from "./semantic";
+
+function normalizeToolcraftConditionValue(value: unknown): string | null {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    const normalized = normalizeToolcraftSemanticText(String(value));
+    return normalized || null;
+  }
+
+  return null;
+}
+
+function getToolcraftConditionBranchTexts(
+  condition: ToolcraftControlConditionSchema,
+  gateControl: ToolcraftControlSchema,
+): string[] {
+  const rawValues =
+    "equals" in condition
+      ? [condition.equals]
+      : Array.isArray(condition.oneOf)
+        ? [...condition.oneOf]
+        : [];
+  const normalizedValues = rawValues
+    .map(normalizeToolcraftConditionValue)
+    .filter((value): value is string => Boolean(value));
+  const optionLabels = (gateControl.options ?? [])
+    .filter((option) =>
+      normalizedValues.includes(normalizeToolcraftSemanticText(option.value)),
+    )
+    .map((option) => normalizeToolcraftSemanticText(option.label))
+    .filter(Boolean);
+
+  return [...new Set([...normalizedValues, ...optionLabels])];
+}
+
+function sectionTitleLooksLikeDependencyBranch({
+  condition,
+  gateControl,
+  sectionTitle,
+}: {
+  condition: ToolcraftControlConditionSchema;
+  gateControl: ToolcraftControlSchema;
+  sectionTitle: string | undefined;
+}): boolean {
+  const sectionText = normalizeToolcraftSemanticText(sectionTitle);
+
+  if (!sectionText) {
+    return false;
+  }
+
+  return getToolcraftConditionBranchTexts(condition, gateControl).some(
+    (branchText) =>
+      branchText.length > 2 &&
+      (sectionText === branchText ||
+        sectionText.includes(branchText) ||
+        branchText.includes(sectionText)),
+  );
+}
+
+export function getToolcraftControlDependencyGroupingErrors(
+  facts: ToolcraftControlLayoutFacts,
+): string[] {
+  const errors: string[] = [];
+
+  for (const item of facts.visibleControls) {
+    for (const [conditionName, condition] of [
+      ["visibleWhen", item.control.visibleWhen],
+      ["disabledWhen", item.control.disabledWhen],
+    ] as const) {
+      if (!condition || !item.loosePrefix) {
+        continue;
+      }
+
+      const gateControl = facts.controlsByTarget.get(condition.target);
+
+      if (!gateControl || gateControl.sectionLabel === item.sectionLabel) {
+        continue;
+      }
+
+      const sharesTargetEntity =
+        gateControl.loosePrefix !== null &&
+        gateControl.loosePrefix === item.loosePrefix;
+      const looksLikeBranchSection =
+        conditionName === "visibleWhen" &&
+        sectionTitleLooksLikeDependencyBranch({
+          condition,
+          gateControl: gateControl.control,
+          sectionTitle: item.sectionTitle,
+        });
+
+      if (!sharesTargetEntity && !looksLikeBranchSection) {
+        continue;
+      }
+
+      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.`,
+      );
+    }
+  }
+
+  return errors;
+}

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

@@ -0,0 +1,104 @@
+import {
+  getToolcraftFontPickerOwnedTypographyPart,
+} from "./control-labels";
+import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
+import {
+  getToolcraftSectionInventoryByTitle,
+  hasToolcraftInventorySplitEvidence,
+} from "./control-section-inventory";
+import { getControlLabelText } from "./controls";
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+function getToolcraftFontPickerOwnershipErrors(
+  facts: ToolcraftControlLayoutFacts,
+): string[] {
+  const errors: string[] = [];
+  const fontPickerControls = facts.visibleControls.filter(
+    (item) => item.control.type === "fontPicker" && item.loosePrefix,
+  );
+
+  for (const item of facts.visibleControls) {
+    if (!item.loosePrefix || item.control.type === "fontPicker") {
+      continue;
+    }
+
+    const ownedTypographyPart =
+      getToolcraftFontPickerOwnedTypographyPart(item.control);
+
+    if (!ownedTypographyPart) {
+      continue;
+    }
+
+    const owningFontPicker = fontPickerControls.find(
+      (fontPicker) => fontPicker.loosePrefix === item.loosePrefix,
+    );
+
+    if (!owningFontPicker) {
+      continue;
+    }
+
+    const label = getControlLabelText(item.control).trim() || item.controlId;
+
+    errors.push(
+      `${item.sectionLabel} / ${item.controlId} splits "${label}" out of the FontPicker-owned typography block for "${item.loosePrefix}". Keep font family, weight, size, case, letter spacing, line height, color, and opacity in the same fontPicker value.`,
+    );
+  }
+
+  return errors;
+}
+
+function getToolcraftProductEntitySplitErrors({
+  facts,
+  sectionInventory,
+}: {
+  facts: ToolcraftControlLayoutFacts;
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
+}): string[] {
+  const errors: string[] = [];
+  const sectionInventoryByTitle = getToolcraftSectionInventoryByTitle(sectionInventory);
+
+  for (const [prefix, sections] of facts.strictPrefixSections) {
+    if (
+      sections.size > 1 &&
+      !hasToolcraftInventorySplitEvidence({ sectionInventoryByTitle, sections })
+    ) {
+      errors.push(
+        `Controls for product entity "${prefix}" are split across sections: ${[...sections].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.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+function getToolcraftSeparatedColorPlacementErrors(
+  facts: ToolcraftControlLayoutFacts,
+): string[] {
+  const errors: string[] = [];
+
+  for (const [prefix, colorControlLabel] of facts.colorSectionLoosePrefixes) {
+    const sections = facts.loosePrefixSections.get(prefix);
+
+    if (sections && sections.size > 1) {
+      errors.push(
+        `${colorControlLabel} is separated from other "${prefix}" controls. A color that configures the same product entity belongs inside that entity section with a concise field label that stays unambiguous in context.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+export function getToolcraftControlEntityGroupingErrors({
+  facts,
+  sectionInventory,
+}: {
+  facts: ToolcraftControlLayoutFacts;
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[];
+}): string[] {
+  return [
+    ...getToolcraftFontPickerOwnershipErrors(facts),
+    ...getToolcraftProductEntitySplitErrors({ facts, sectionInventory }),
+    ...getToolcraftSeparatedColorPlacementErrors(facts),
+  ];
+}

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

@@ -0,0 +1,159 @@
+import type {
+  ResolvedToolcraftAppSchema,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+
+import { isToolcraftProductSectionControl } from "./controls";
+import { getToolcraftSectionLabel } from "./sections";
+import {
+  getToolcraftLooseTargetPrefix,
+  getToolcraftStrictTargetPrefix,
+  normalizeToolcraftSemanticText,
+} from "./semantic";
+
+export type ToolcraftControlLayoutControlEntry = {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  loosePrefix: string | null;
+  sectionLabel: string;
+  sectionTitle: string | undefined;
+};
+
+export type ToolcraftControlLayoutSectionFact = {
+  controls: readonly [string, ToolcraftControlSchema][];
+  sectionLabel: string;
+  sectionLoosePrefixes: ReadonlySet<string>;
+  sectionTitle: string | undefined;
+  semanticClusters: ReadonlySet<string>;
+};
+
+export type ToolcraftControlLayoutFacts = {
+  colorSectionLoosePrefixes: ReadonlyMap<string, string>;
+  controlsByTarget: ReadonlyMap<string, ToolcraftControlLayoutControlEntry>;
+  loosePrefixSections: ReadonlyMap<string, ReadonlySet<string>>;
+  sectionTitleCounts: ReadonlyMap<string, { count: number; label: string }>;
+  sections: readonly ToolcraftControlLayoutSectionFact[];
+  strictPrefixSections: ReadonlyMap<string, ReadonlySet<string>>;
+  visibleControls: readonly ToolcraftControlLayoutControlEntry[];
+};
+
+function getToolcraftControlSemanticCluster(
+  control: ToolcraftControlSchema,
+): string {
+  return (
+    control.semanticGroup?.trim() ||
+    getToolcraftLooseTargetPrefix(control.target) ||
+    control.orderRole ||
+    control.type
+  );
+}
+
+function addSectionToPrefixMap(
+  sectionMap: Map<string, Set<string>>,
+  prefix: string | null,
+  sectionLabel: string,
+): void {
+  if (!prefix) {
+    return;
+  }
+
+  const sections = sectionMap.get(prefix) ?? new Set<string>();
+  sections.add(sectionLabel);
+  sectionMap.set(prefix, sections);
+}
+
+function updateSectionTitleCounts(
+  sectionTitleCounts: Map<string, { count: number; label: string }>,
+  sectionTitle: string | undefined,
+): void {
+  if (!sectionTitle) {
+    return;
+  }
+
+  const normalizedSectionTitle = normalizeToolcraftSemanticText(sectionTitle);
+  const titleCount = sectionTitleCounts.get(normalizedSectionTitle);
+  sectionTitleCounts.set(normalizedSectionTitle, {
+    count: (titleCount?.count ?? 0) + 1,
+    label: titleCount?.label ?? sectionTitle,
+  });
+}
+
+export function buildToolcraftControlLayoutFacts(
+  schema: ResolvedToolcraftAppSchema,
+): ToolcraftControlLayoutFacts {
+  const sections: ToolcraftControlLayoutSectionFact[] = [];
+  const visibleControls: ToolcraftControlLayoutControlEntry[] = [];
+  const strictPrefixSections = new Map<string, Set<string>>();
+  const loosePrefixSections = new Map<string, Set<string>>();
+  const colorSectionLoosePrefixes = new Map<string, string>();
+  const sectionTitleCounts = new Map<string, { count: number; label: string }>();
+  const controlsByTarget = new Map<string, ToolcraftControlLayoutControlEntry>();
+
+  for (const [sectionIndex, section] of (schema.panels.controls?.sections ?? []).entries()) {
+    const sectionTitle = section.title?.trim();
+    const sectionLabel = getToolcraftSectionLabel(sectionTitle, sectionIndex);
+    const controls = Object.entries(section.controls).filter(([, control]) =>
+      isToolcraftProductSectionControl(control),
+    );
+
+    if (controls.length === 0) {
+      continue;
+    }
+
+    updateSectionTitleCounts(sectionTitleCounts, sectionTitle);
+
+    const sectionLoosePrefixes = new Set(
+      controls
+        .map(([, control]) => getToolcraftLooseTargetPrefix(control.target))
+        .filter((prefix): prefix is string => Boolean(prefix)),
+    );
+    const semanticClusters = new Set(
+      controls.map(([, control]) => getToolcraftControlSemanticCluster(control)),
+    );
+    const isColorOnlySection = controls.every(
+      ([, control]) => control.type === "color",
+    );
+
+    sections.push({
+      controls,
+      sectionLabel,
+      sectionLoosePrefixes,
+      sectionTitle,
+      semanticClusters,
+    });
+
+    for (const [controlId, control] of controls) {
+      const strictPrefix = getToolcraftStrictTargetPrefix(control.target);
+      const entry: ToolcraftControlLayoutControlEntry = {
+        control,
+        controlId,
+        loosePrefix: getToolcraftLooseTargetPrefix(control.target),
+        sectionLabel,
+        sectionTitle,
+      };
+
+      visibleControls.push(entry);
+      controlsByTarget.set(control.target, entry);
+      addSectionToPrefixMap(strictPrefixSections, strictPrefix, sectionLabel);
+      addSectionToPrefixMap(loosePrefixSections, entry.loosePrefix, sectionLabel);
+
+      if (
+        control.type === "color" &&
+        isColorOnlySection &&
+        entry.loosePrefix
+      ) {
+        colorSectionLoosePrefixes.set(entry.loosePrefix, `${sectionLabel} / ${controlId}`);
+      }
+    }
+  }
+
+  return {
+    colorSectionLoosePrefixes,
+    controlsByTarget,
+    loosePrefixSections,
+    sectionTitleCounts,
+    sections,
+    strictPrefixSections,
+    visibleControls,
+  };
+}