@pixel-point/toolcraft 0.0.13 → 0.0.15

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

@@ -0,0 +1,189 @@
+import { getToolcraftControlKeyframeCapability } from "@repo/toolcraft-runtime";
+
+import { getConditionValidationErrors } from "./conditions";
+import {
+  getCodeTextareaControlError,
+  getCurveIntentError,
+  getSingleActionsControlLabelError,
+  getTimelineTransportControlText,
+  getToggleControlLabelError,
+  shouldUseSingleCurveVariant,
+} from "./control-component-rules";
+import type { ToolcraftControlRuleContext } from "./control-acceptance-context";
+
+const timelineTransportControlPattern =
+  /\b(play|pause|paused|resume|animate|restart)\b/i;
+
+function getControlComponentPolicyErrors({
+  control,
+  controlId,
+  label,
+  sectionTitle,
+}: Pick<
+  ToolcraftControlRuleContext,
+  "control" | "controlId" | "label" | "sectionTitle"
+>): string[] {
+  const errors: string[] = [];
+  const toggleLabelError = getToggleControlLabelError(control, sectionTitle);
+  const singleActionsLabelError = getSingleActionsControlLabelError(control);
+  const codeTextareaError = getCodeTextareaControlError({
+    control,
+    controlId,
+    label,
+  });
+  const curveIntentError = getCurveIntentError(control, label);
+
+  if (toggleLabelError) {
+    errors.push(`${label} ${toggleLabelError}`);
+  }
+
+  if (singleActionsLabelError) {
+    errors.push(`${label} ${singleActionsLabelError}`);
+  }
+
+  if (codeTextareaError) {
+    errors.push(codeTextareaError);
+  }
+
+  if (curveIntentError) {
+    errors.push(curveIntentError);
+  }
+
+  if (
+    control.type === "rangeSlider" &&
+    Array.isArray(control.defaultValue) &&
+    typeof control.defaultValue[0] === "number" &&
+    typeof control.defaultValue[1] === "number" &&
+    control.defaultValue[0] === control.defaultValue[1]
+  ) {
+    errors.push(
+      `${label} rangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.`,
+    );
+  }
+
+  if (shouldUseSingleCurveVariant(control)) {
+    errors.push(
+      `${label} 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.`,
+    );
+  }
+
+  return errors;
+}
+
+function getControlTimelinePolicyErrors({
+  control,
+  controlId,
+  label,
+  timelineMode,
+}: Pick<
+  ToolcraftControlRuleContext,
+  "control" | "controlId" | "label" | "timelineMode"
+>): string[] {
+  const errors: string[] = [];
+  const keyframeCapability = getToolcraftControlKeyframeCapability(control);
+
+  if (
+    control.type !== "panelActions" &&
+    timelineTransportControlPattern.test(getTimelineTransportControlText(controlId, control))
+  ) {
+    errors.push(
+      `${label} looks like an app-wide timeline transport control. Play, Pause, Animate, Resume, and Restart animation belong to the top timeline; keep right-panel controls for renderer parameters, generation/apply actions, and output delivery.`,
+    );
+  }
+
+  if (control.keyframeable === true && !keyframeCapability.capable) {
+    errors.push(
+      `${label} sets keyframeable true, but this control type or runtime-owned target cannot create timeline keyframes.`,
+    );
+  }
+
+  if (
+    timelineMode === "keyframes" &&
+    keyframeCapability.capable &&
+    control.keyframeable === false
+  ) {
+    errors.push(
+      `${label} is keyframe-capable by Toolcraft control type; remove keyframeable: false and provide keyframe evaluator coverage instead of hiding the diamond.`,
+    );
+  }
+
+  return errors;
+}
+
+function getControlLayerPolicyErrors({
+  control,
+  label,
+  layersEnabled,
+}: Pick<
+  ToolcraftControlRuleContext,
+  "control" | "label" | "layersEnabled"
+>): string[] {
+  const errors: string[] = [];
+  const isSelectedLayerTarget = control.target.startsWith("selectedLayer.");
+
+  if (isSelectedLayerTarget && !layersEnabled) {
+    errors.push(
+      `${label} uses reserved selectedLayer.* target without panels.layers enabled. Use an app-specific target for single-layer apps or enable layers with layerCoverage.`,
+    );
+  }
+
+  return errors;
+}
+
+function getControlStatePolicyErrors({
+  control,
+  controlTargets,
+  label,
+}: Pick<
+  ToolcraftControlRuleContext,
+  "control" | "controlTargets" | "label"
+>): string[] {
+  const errors: string[] = [];
+
+  if (control.visibleWhen) {
+    errors.push(
+      ...getConditionValidationErrors({
+        condition: control.visibleWhen,
+        conditionName: "visibleWhen",
+        controlTargets,
+        label,
+      }),
+    );
+  }
+
+  if (control.disabledWhen) {
+    errors.push(
+      ...getConditionValidationErrors({
+        condition: control.disabledWhen,
+        conditionName: "disabledWhen",
+        controlTargets,
+        label,
+      }),
+    );
+  }
+
+  if (control.disabled === true) {
+    errors.push(
+      `${label} sets disabled: true. Generated product panels should show only controls usable in the current state; hide unavailable product controls with visibleWhen instead of rendering disabled controls.`,
+    );
+  }
+
+  if (control.disabledWhen) {
+    errors.push(
+      `${label} uses disabledWhen. Generated product panels should show only controls usable in the current state; hide unavailable product controls with visibleWhen instead of rendering disabled controls.`,
+    );
+  }
+
+  return errors;
+}
+
+export function getControlPreAcceptanceErrors(
+  context: ToolcraftControlRuleContext,
+): string[] {
+  return [
+    ...getControlComponentPolicyErrors(context),
+    ...getControlTimelinePolicyErrors(context),
+    ...getControlLayerPolicyErrors(context),
+    ...getControlStatePolicyErrors(context),
+  ];
+}

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

@@ -0,0 +1,70 @@
+import { getToolcraftCanvasHandleAcceptanceErrors } from "./canvas-handle-acceptance";
+import { getControlAcceptanceCoverageErrors } from "./control-acceptance-coverage";
+import {
+  getAcceptanceEntryTargetErrors,
+  getControlAcceptanceByTarget,
+  getControlTargets,
+  type ToolcraftControlAcceptanceContext,
+} from "./control-acceptance-context";
+import { getControlKindAcceptanceErrors } from "./control-acceptance-kind-rules";
+import { getControlPreAcceptanceErrors } from "./control-acceptance-policy";
+
+export function getToolcraftControlAcceptanceErrors({
+  acceptance,
+  controls,
+  layersEnabled,
+  schema,
+  timelineMode,
+}: ToolcraftControlAcceptanceContext): string[] {
+  const errors: string[] = [];
+  const controlAcceptance = getControlAcceptanceByTarget(acceptance);
+  const controlTargets = getControlTargets(controls);
+
+  for (const { control, controlId, sectionTitle } of controls) {
+    const label = `${sectionTitle ? `${sectionTitle} / ` : ""}${controlId} (${control.target})`;
+    const entry = controlAcceptance.get(control.target);
+
+    errors.push(
+      ...getControlPreAcceptanceErrors({
+        control,
+        controlId,
+        controlTargets,
+        label,
+        layersEnabled,
+        sectionTitle,
+        timelineMode,
+      }),
+    );
+
+    if (!entry) {
+      errors.push(`${label} is missing an acceptance entry.`);
+      continue;
+    }
+
+    errors.push(
+      ...getControlAcceptanceCoverageErrors({
+        control,
+        controlId,
+        entry,
+        label,
+        layersEnabled,
+        schema,
+        sectionTitle,
+        timelineMode,
+      }),
+    );
+    errors.push(
+      ...getControlKindAcceptanceErrors({
+        control,
+        controlId,
+        entry,
+        label,
+      }),
+    );
+  }
+
+  errors.push(...getAcceptanceEntryTargetErrors({ acceptance, controlTargets }));
+  errors.push(...getToolcraftCanvasHandleAcceptanceErrors({ acceptance, controlTargets }));
+
+  return errors;
+}

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

@@ -0,0 +1,277 @@
+import type {
+  ToolcraftActionSchema,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+
+import {
+  getActionLabelText,
+  getActionSearchText,
+  getControlActions,
+} from "./actions";
+import { getControlLabelText } from "./controls";
+import { normalizeToolcraftSemanticText } from "./semantic";
+import type { ToolcraftVisibleControl } from "./types";
+
+const MAX_VISUAL_DISCRETE_POSITION_COUNT = 32;
+
+function getStepPositionCount(control: ToolcraftControlSchema): number | undefined {
+  if (
+    typeof control.step !== "number" ||
+    typeof control.min !== "number" ||
+    typeof control.max !== "number" ||
+    !Number.isFinite(control.step) ||
+    !Number.isFinite(control.min) ||
+    !Number.isFinite(control.max) ||
+    control.step <= 0 ||
+    control.max <= control.min
+  ) {
+    return undefined;
+  }
+
+  const rawStepCount = (control.max - control.min) / control.step;
+  const roundedStepCount = Math.round(rawStepCount);
+  const intervalCount =
+    Math.abs(rawStepCount - roundedStepCount) < Number.EPSILON * 100
+      ? roundedStepCount
+      : Math.floor(rawStepCount) + 1;
+
+  return Math.max(2, intervalCount + 1);
+}
+
+export function getStepMarkerCount(control: ToolcraftControlSchema): number | undefined {
+  return getStepPositionCount(control);
+}
+
+function isIntegerStepDomain(control: ToolcraftControlSchema): boolean {
+  return (
+    typeof control.min === "number" &&
+    typeof control.max === "number" &&
+    typeof control.step === "number" &&
+    Number.isInteger(control.min) &&
+    Number.isInteger(control.max) &&
+    Number.isInteger(control.step)
+  );
+}
+
+function shouldUseVisualDiscreteSlider(
+  control: ToolcraftControlSchema,
+): boolean {
+  const positionCount = getStepPositionCount(control);
+
+  if (
+    control.sliderValueKind !== "discrete" ||
+    !positionCount ||
+    !isIntegerStepDomain(control)
+  ) {
+    return false;
+  }
+  return positionCount <= MAX_VISUAL_DISCRETE_POSITION_COUNT;
+}
+
+export function getSliderVariantClassificationErrors({
+  control,
+  label,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  label: string;
+}): string[] {
+  const errors: string[] = [];
+  const positionCount = getStepPositionCount(control);
+
+  if (!positionCount) {
+    return errors;
+  }
+
+  if (
+    shouldUseVisualDiscreteSlider(control) &&
+    control.variant !== "discrete"
+  ) {
+    errors.push(
+      `${label} has ${positionCount} semantic integer positions and must use variant "discrete" so Toolcraft renders tick markers.`,
+    );
+  }
+
+  if (
+    control.variant === "discrete" &&
+    control.sliderValueKind !== "discrete"
+  ) {
+    errors.push(
+      `${label} uses variant "discrete" and must declare sliderValueKind "discrete" so tick semantics are explicit and language-independent.`,
+    );
+  }
+
+  if (
+    control.variant === "discrete" &&
+    positionCount > MAX_VISUAL_DISCRETE_POSITION_COUNT
+  ) {
+    errors.push(
+      `${label} declares variant "discrete" with ${positionCount} positions, which would overload tick markers. Keep it stepped continuous or use a different control.`,
+    );
+  }
+
+  return errors;
+}
+
+export function getCodeTextareaControlError({
+  control,
+  label,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  label: string;
+}): string | undefined {
+  if (control.type !== "code" && control.type !== "text") {
+    return undefined;
+  }
+
+  if (!control.textValueKind) {
+    return `${label} must declare textValueKind "single-line", "multiline", or "structured" so TextInput versus CodeTextarea selection does not depend on labels or prose.`;
+  }
+
+  if (control.type === "code" && control.textValueKind === "single-line") {
+    return `${label} declares textValueKind "single-line" and must use type "text"; reserve type "code" for multiline or structured values.`;
+  }
+
+  if (control.type === "text" && control.textValueKind !== "single-line") {
+    return `${label} declares textValueKind "${control.textValueKind}" and must use type "code" for multiline or structured values.`;
+  }
+
+  return undefined;
+}
+
+export function shouldUseSingleCurveVariant(
+  control: ToolcraftControlSchema,
+): boolean {
+  return (
+    control.type === "curves" &&
+    control.curveIntent === "single-value-map" &&
+    control.variant !== "single"
+  );
+}
+
+export function getCurveIntentError(
+  control: ToolcraftControlSchema,
+  label: string,
+): string | undefined {
+  if (control.type !== "curves") {
+    return undefined;
+  }
+  if (!control.curveIntent) {
+    return `${label} must declare curveIntent "single-value-map" or "color-channels" so the curve composition does not depend on its label.`;
+  }
+  if (control.curveIntent === "color-channels" && control.variant === "single") {
+    return `${label} declares curveIntent "color-channels" and must use the channel curve composition instead of variant "single".`;
+  }
+  return undefined;
+}
+
+export function getToggleControlLabelError(
+  control: ToolcraftControlSchema,
+  sectionTitle?: string,
+): string | undefined {
+  if (control.type !== "switch" && control.type !== "checkbox") {
+    return undefined;
+  }
+
+  const label = getControlLabelText(control).trim();
+
+  if (/^(enable|disable)\b/i.test(label)) {
+    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;
+}
+
+export function getSingleActionsControlLabelError(
+  control: ToolcraftControlSchema,
+): string | undefined {
+  if (control.type !== "actions") {
+    return undefined;
+  }
+
+  const actions = getControlActions(control);
+
+  if (actions.length !== 1) {
+    return undefined;
+  }
+
+  const label = getControlLabelText(control).trim();
+  const actionLabel = getActionLabelText(actions[0] as ToolcraftActionSchema | string).trim();
+
+  if (
+    label &&
+    actionLabel &&
+    normalizeToolcraftSemanticText(label) === normalizeToolcraftSemanticText(actionLabel)
+  ) {
+    return `single Actions control label "${label}" duplicates its only button label "${actionLabel}". Keep the button as the command and use a short context label such as "Ink wash", "Palette action", or "Current layer".`;
+  }
+
+  return undefined;
+}
+
+export function getTimelineTransportControlText(
+  controlId: string,
+  control: ToolcraftControlSchema,
+): string {
+  return [
+    controlId,
+    control.target,
+    getControlLabelText(control),
+    ...getControlActions(control).map(getActionSearchText),
+  ].join(" ");
+}
+
+export function getAnimationIntentControlText({
+  control,
+  controlId,
+  sectionTitle,
+}: ToolcraftVisibleControl): string {
+  return [
+    sectionTitle ?? "",
+    controlId,
+    control.target,
+    getControlLabelText(control),
+  ].join(" ");
+}
+
+const SEGMENTED_CONTROL_MAX_OPTIONS = 4;
+const SEGMENTED_CONTROL_MAX_OPTION_LABEL_LENGTH = 9;
+const SEGMENTED_CONTROL_MAX_TOTAL_LABEL_LENGTH = 24;
+
+export function getSegmentedControlLayoutError(
+  control: ToolcraftControlSchema,
+): string | null {
+  if (control.type !== "segmented") {
+    return null;
+  }
+
+  const labels = control.options?.map((option) => option.label.trim()) ?? [];
+  const totalLabelLength = labels.reduce((total, label) => total + label.length, 0);
+  const longLabels = labels.filter(
+    (label) => label.length > SEGMENTED_CONTROL_MAX_OPTION_LABEL_LENGTH,
+  );
+
+  if (
+    labels.length > SEGMENTED_CONTROL_MAX_OPTIONS ||
+    longLabels.length > 0 ||
+    totalLabelLength > SEGMENTED_CONTROL_MAX_TOTAL_LABEL_LENGTH
+  ) {
+    return [
+      `segmented controls must preserve cell padding: use at most ${SEGMENTED_CONTROL_MAX_OPTIONS} short options`,
+      `(max ${SEGMENTED_CONTROL_MAX_OPTION_LABEL_LENGTH} characters per label and ${SEGMENTED_CONTROL_MAX_TOTAL_LABEL_LENGTH} total)`,
+      "or shorten labels first; if the compact names still exceed the budget, use a select dropdown instead.",
+    ].join(" ");
+  }
+
+  return null;
+}