@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/forms/app/wix/forms/forms.ts

@@ -1,246 +1,31 @@
-// Wix Forms schema reads (@wix/forms `forms`) — the only file that touches a raw Form.
-// Returns flat FormDto / FormFieldDto from ./types. Copy as-is; extend by adding functions.
+// Wix Forms schema reads — the only file that touches a raw Form on this transport. Returns flat
+// FormDto / FormFieldDto from ./types. The flattening rules live in ./forms-core (shared with the
+// REST twin in references/forms/rest/); this file is the transport only. Copy as-is; extend by
+// adding functions.
 //
-// ⚠️ The visitor token is enough, and the spec says otherwise. Every schema read is listed
-// under the owner scope `SCOPE.FORMS.VIEW-FORM`, and returns 200 on an anonymous visitor:
-// Wix grants implicit visitor access so a published site can render its own forms. Do NOT add
-// a backend, a connector token, or auth.elevate to make a form load.
+// The reads go over `wixFetch` (the SDK's own authenticated fetch), NOT the `forms` module of
+// @wix/forms: that generated module is 15 MB. Bundled server-side it pushes a Wix deploy past its
+// size limit (HTTP 413 on release); bundled client-side every visitor downloads it. The
+// submissions module (./submissions.ts) is 100 KB and stays on the SDK.
+//
+// The visitor token is enough, and the spec says otherwise. Every schema read is listed under
+// the owner scope `SCOPE.FORMS.VIEW-FORM`, and returns 200 on an anonymous visitor: Wix grants
+// implicit visitor access so a published site can render its own forms. Do NOT add a backend, a
+// connector token, or auth.elevate to make a form load.
 //
 // docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/get-form.md
 // docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/list-forms.md
 // docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
-import { forms as formsModule } from "@wix/forms";
-import { wixModule } from "../sdk";
-import type {
-  FormAddressPart,
-  FormChoice,
-  FormControl,
-  FormDto,
-  FormFieldDto,
-  FormValidation,
-} from "./types";
-
-const forms = wixModule(formsModule);
-
-/** The Wix Forms app namespace. Every form this vertical touches lives here. */
-export const FORMS_NAMESPACE = "wix.form_app.form";
-
-type Raw = Record<string, any>;
-
-// A field's settings nest TWO levels deep, under blocks named after its own enums:
-//   inputOptions.<inputType block>.<componentType block>.label
-// These tables resolve those names. Spelling them at a call site is one typo away from
-// silently reading back no label at all — which is the whole reason this file exists.
-const INPUT_BLOCK: Record<string, string> = {
-  STRING: "stringOptions",
-  NUMBER: "numberOptions",
-  BOOLEAN: "booleanOptions",
-  ARRAY: "arrayOptions",
-  ADDRESS: "addressOptions",
-  WIX_FILE: "wixFileOptions",
-  PAYMENT: "paymentOptions",
-  SCHEDULING: "schedulingOptions",
-};
-
-const COMPONENT_BLOCK: Record<string, string> = {
-  TEXT_INPUT: "textInputOptions",
-  NUMBER_INPUT: "numberInputOptions",
-  RATING_INPUT: "ratingInputOptions",
-  PHONE_INPUT: "phoneInputOptions",
-  DATE_INPUT: "dateInputOptions",
-  DATE_PICKER: "datePickerOptions",
-  DATE_TIME: "dateTimeOptions",
-  TIME_INPUT: "timeInputOptions",
-  CHECKBOX: "checkboxOptions",
-  CHECKBOX_GROUP: "checkboxGroupOptions",
-  RADIO_GROUP: "radioGroupOptions",
-  DROPDOWN: "dropdownOptions",
-  TAGS: "tagsOptions",
-  MULTILINE_ADDRESS: "multilineAddressOptions",
-  FILE_UPLOAD: "fileUploadOptions",
-  SIGNATURE: "signatureOptions",
-  FIXED_PAYMENT: "fixedPaymentOptions",
-  PAYMENT_INPUT: "paymentInputOptions",
-  DONATION_INPUT: "donationInputOptions",
-  APPOINTMENT: "appointmentOptions",
-  SERVICES_DROPDOWN: "servicesDropdownOptions",
-  SERVICES_CHECKBOX_GROUP: "servicesCheckboxGroupOptions",
-};
-
-// componentType → the control to render. Several field kinds share one component (short and
-// long answer are both TEXT_INPUT), so `format` and `inputType` refine it below.
-const CONTROL: Record<string, FormControl> = {
-  TEXT_INPUT: "text",
-  NUMBER_INPUT: "number",
-  RATING_INPUT: "rating",
-  PHONE_INPUT: "phone",
-  DATE_INPUT: "date",
-  DATE_PICKER: "date",
-  DATE_TIME: "datetime",
-  TIME_INPUT: "time",
-  CHECKBOX: "checkbox",
-  CHECKBOX_GROUP: "checkboxGroup",
-  RADIO_GROUP: "radio",
-  DROPDOWN: "select",
-  TAGS: "tags",
-  MULTILINE_ADDRESS: "address",
-  FILE_UPLOAD: "file",
-  SIGNATURE: "signature",
-  FIXED_PAYMENT: "payment",
-  PAYMENT_INPUT: "payment",
-  DONATION_INPUT: "payment",
-  SERVICES_DROPDOWN: "select",
-  SERVICES_CHECKBOX_GROUP: "checkboxGroup",
-  APPOINTMENT: "appointment",
-};
-
-// An enum missing from a table means Wix added a type. Say so ONCE — a silent empty block
-// renders a field labelled by its storage key with none of its settings.
-const warned = new Set<string>();
-function blockName(table: Record<string, string>, key: string | undefined, what: string): string | undefined {
-  const name = key ? table[key] : undefined;
-  if (!name && key && !warned.has(what + key)) {
-    warned.add(what + key);
-    console.warn(
-      `forms: no ${what} block mapped for "${key}" — that field renders without its label or ` +
-        `options. Add it to the table in app/wix/forms/forms.ts.`,
-    );
-  }
-  return name;
-}
-
-/** A BOOLEAN consent field labels itself with Ricos rich content; take its plain text. */
-function plainText(label: unknown): string {
-  if (typeof label === "string") return label;
-  const nodes = (label as Raw)?.nodes;
-  if (!Array.isArray(nodes)) return "";
-  const walk = (list: Raw[]): string =>
-    list
-      .map((n) => (n?.textData?.text ?? "") + (Array.isArray(n?.nodes) ? walk(n.nodes) : ""))
-      .join("");
-  return walk(nodes).trim();
-}
-
-/** `postalCode` → "Postal code". A subfield is a key; the schema carries no label for it. */
-function humanizeSub(sub: string): string {
-  const words = sub.replace(/([A-Z])|(\d+)/g, " $1$2").toLowerCase().trim();
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
+import { wixFetch } from "../sdk";
+import { FORMS_NAMESPACE, toForm, type Raw } from "./forms-core";
+import type { FormDto } from "./types";
 
-function toField(raw: Raw): FormFieldDto {
-  const input = raw.inputOptions ?? {};
-  const inputType: string = input.inputType ?? "";
-  const optionsBlock: Raw = input[blockName(INPUT_BLOCK, inputType, "inputType") ?? ""] ?? {};
-  const componentType: string = optionsBlock.componentType ?? "";
-  const component: Raw = optionsBlock[blockName(COMPONENT_BLOCK, componentType, "componentType") ?? ""] ?? {};
-  const rules: Raw = optionsBlock.validation ?? {};
-
-  const validation: FormValidation = {
-    ...(rules.format ? { format: rules.format } : {}),
-    ...(rules.minLength != null ? { minLength: rules.minLength } : {}),
-    ...(rules.maxLength != null ? { maxLength: rules.maxLength } : {}),
-    ...(rules.pattern ? { pattern: rules.pattern } : {}),
-    // JSON-Schema spelling everywhere else in this block; minValue/maxValue is read too since
-    // the public reference documents neither and an older schema may carry them.
-    ...((rules.minimum ?? rules.minValue) != null ? { minimum: rules.minimum ?? rules.minValue } : {}),
-    ...((rules.maximum ?? rules.maxValue) != null ? { maximum: rules.maximum ?? rules.maxValue } : {}),
-    ...(rules.fileLimit != null ? { fileLimit: rules.fileLimit } : {}),
-    ...(rules.minItems != null ? { minItems: rules.minItems } : {}),
-    ...(rules.maxItems != null ? { maxItems: rules.maxItems } : {}),
-  };
-
-  // TEXT_INPUT covers short answer, long answer, email, url and phone — and a long answer is
-  // NOT flagged on the component (no `multiline`, no `numberOfLines`). Only `identifier` says
-  // TEXT_AREA, which is why it is carried on the DTO.
-  const identifier: string = raw.identifier ?? "";
-  let control: FormControl = CONTROL[componentType] ?? "unknown";
-  // A product list is a PAYMENT field wearing a CHECKBOX_GROUP component — typed by its
-  // component it would look like a multi-choice and be bound to an array of strings, when what
-  // it submits is a payment structure. The input type wins.
-  if (inputType === "PAYMENT") control = "payment";
-  if (control === "text") {
-    if (identifier === "TEXT_AREA" || component.multiline || component.numberOfLines > 1) control = "textarea";
-    else if (rules.format === "EMAIL") control = "email";
-    else if (rules.format === "URL") control = "url";
-    else if (rules.format === "PHONE") control = "phone";
-  }
-
-  const choices: FormChoice[] = Array.isArray(component.options)
-    ? component.options.map((o: Raw) => ({ value: String(o.value), label: String(o.label ?? o.value) }))
-    : [];
-
-  const addressParts: FormAddressPart[] = Object.entries((rules.fields ?? {}) as Raw)
-    // Only addressLine2 carries a visibility setting; hide it when the owner turned it off.
-    .filter(([sub]) => component.fieldSettings?.[sub]?.show !== false)
-    .map(([sub, cfg]) => ({ sub, label: humanizeSub(sub), required: (cfg as Raw)?.required ?? false }));
-
-  const target: string = input.target ?? "";
-  const label = plainText(component.label) || target;
-
-  // Every control is controlled from the first render, so each field starts at a value of the
-  // right SHAPE — [] for multi-choice and files, {} for an address, the owner's prefill else "".
-  // Wix spells the prefill `default` on most components and `defaultValue` on a rating.
-  const prefill = component.default ?? component.defaultValue;
-  const defaultValue =
-    control === "address" ? {} :
-    inputType === "ARRAY" || inputType === "WIX_FILE" ? [] :
-    // a consent checkbox is a BOOLEAN: "" would bind to `checked` as false and work by
-    // accident, but the DTO promises the shape its control writes back
-    inputType === "BOOLEAN" ? ((prefill as boolean | undefined) ?? false) :
-    (prefill as string | number | boolean | undefined) ?? "";
-
-  return {
-    target,
-    label,
-    control,
-    required: input.required ?? false,
-    ...(component.placeholder ? { placeholder: String(component.placeholder) } : {}),
-    ...(component.description ? { description: plainText(component.description) } : {}),
-    defaultValue,
-    choices,
-    addressParts,
-    validation,
-    ...(component.defaultCountryCode || rules.phoneOptions?.allowedCountryCodes?.[0]
-      ? { phoneCountry: component.defaultCountryCode ?? rules.phoneOptions.allowedCountryCodes[0] }
-      : {}),
-    identifier,
-    inputType,
-    componentType,
-  };
-}
-
-/**
- * Display order comes from `steps[].layout`, NOT from `formFields[]` array order. Sort WITHIN
- * each step and concatenate in step order: `row` restarts at 0 in every step, so one sort
- * across the flattened list interleaves them. A field the owner never placed sorts LAST — it
- * still stores values. The submit button is `fieldType: "DISPLAY"`, so filtering to INPUT
- * drops it automatically.
- */
-function orderedInputs(raw: Raw): Raw[] {
-  const order = new Map<string, number>(
-    ((raw.steps ?? []) as Raw[])
-      .flatMap((s) =>
-        ((s.layout?.large?.items ?? s.layout?.medium?.items ?? s.layout?.small?.items ?? []) as Raw[])
-          .slice()
-          .sort((a, b) => a.row - b.row || a.column - b.column),
-      )
-      .map((item, i) => [item.fieldId as string, i] as const),
-  );
-  return ((raw.formFields ?? []) as Raw[])
-    .filter((f) => f.fieldType === "INPUT" && !f.hidden)
-    .sort((a, b) => (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity));
-}
+export { FORMS_NAMESPACE };
 
-function toForm(raw: Raw): FormDto {
-  const submit = ((raw.formFields ?? []) as Raw[]).find((f) => f.identifier === "SUBMIT_BUTTON");
-  return {
-    id: raw._id ?? raw.id,
-    name: raw.name ?? "",
-    fields: orderedInputs(raw).map(toField),
-    // The submit wording lives on a DISPLAY field, nested under pageNavigationOptions because
-    // one control drives both multi-page navigation and the final submit.
-    submitText: submit?.displayOptions?.pageNavigationOptions?.submitText ?? "",
-  };
+async function getJson(path: string): Promise<Raw> {
+  const res = await wixFetch(path);
+  if (!res.ok) throw new Error(`forms: GET ${path} failed (${res.status}).`);
+  return (await res.json()) as Raw;
 }
 
 /**
@@ -249,21 +34,21 @@ function toForm(raw: Raw): FormDto {
  * that would drop real enquiries silently.
  */
 export async function getForm(formId: string): Promise<FormDto> {
-  const raw = (await forms.getForm(formId)) as Raw;
-  if (!raw) throw new Error(`forms: form "${formId}" not found.`);
-  return toForm(raw);
+  // GET /form-schema-service/v4/forms/{formId} → { form }; 404 FORM_NOT_FOUND on a wrong id.
+  const res = await getJson(`/form-schema-service/v4/forms/${encodeURIComponent(formId)}`);
+  if (!res?.form) throw new Error(`forms: form "${formId}" not found.`);
+  return toForm(res.form as Raw);
 }
 
 /**
  * Every form on the site, in the Wix Forms namespace. Use ONE call for several forms on a page
  * rather than a getForm each.
  *
- * ⚠️ Returns only ENABLED forms — a form the owner disabled vanishes from the listing rather
+ * Returns only ENABLED forms — a form the owner disabled vanishes from the listing rather
  * than erroring. That is usually right for a public site.
  */
 export async function listForms(): Promise<FormDto[]> {
-  // The namespace is POSITIONAL — an options object here is a type error, and untyped it would
-  // silently list nothing.
-  const res = (await forms.listForms(FORMS_NAMESPACE)) as Raw;
+  // GET /form-schema-service/v4/forms?namespace=… → { forms }; the namespace is required (400 without).
+  const res = await getJson(`/form-schema-service/v4/forms?namespace=${encodeURIComponent(FORMS_NAMESPACE)}`);
   return ((res?.forms ?? []) as Raw[]).map(toForm);
 }

package/skills/wix-headless-fast/references/forms/app/wix/forms/submissions-core.ts

@@ -0,0 +1,216 @@
+// Submission rules — transport-agnostic, imported by BOTH transports: ./submissions.ts (the SDK)
+// and the REST twin in references/forms/rest/submissions.ts. What a visitor's values become on
+// the wire, which statuses mean "created", how a rejection maps back onto controls, and how an
+// attachment is uploaded — all HERE, once. A created submission may arrive wrapped (`{ submission }`,
+// REST) or bare (SDK), with `_id` (SDK) or `id` (REST); the mapper accepts both.
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
+import type { Raw } from "./forms-core";
+import type { FormFieldDto, FormValues, SubmissionDto } from "./types";
+
+/**
+ * Statuses that mean the submission EXISTS — show the thank-you for all three. `CONFIRMED` is
+ * recorded, `PENDING` is created but not recorded yet, `PAYMENT_WAITING` is created on a form
+ * that also collects payment. Treating one as a failure invites the visitor to submit again,
+ * which costs the owner duplicate entries for a submission that already exists.
+ *
+ * An allowlist rather than a catch-all, so a status added to the enum later cannot silently
+ * render a thank-you for something that is not a submission.
+ */
+export const SUBMITTED_OK = new Set(["CONFIRMED", "PENDING", "PAYMENT_WAITING"]);
+
+/** Strip visitor-added formatting from a phone number — submit this, not the raw control text. */
+export const normalizePhone = (v: unknown): string => String(v ?? "").replace(/[\s()\-.]/g, "");
+
+/** Uploads a File to a pre-signed URL and resolves to the value to submit for its field. */
+export type UploadOne = (formId: string, file: File) => Promise<string>;
+
+/**
+ * A browser leaves `type` empty for extensions it does not recognize; the generic type keeps
+ * the upload-URL call valid (Media Manager rejects a mime type that contradicts the extension).
+ */
+export const uploadMimeType = (file: File): string => file.type || "application/octet-stream";
+
+/**
+ * PUT the bytes to the generated upload URL and return the value to submit for the field.
+ *
+ * The submission value IS the generated upload URL — not the CDN URL the upload responds with,
+ * and not a file id. The PUT goes to a pre-signed host with plain `fetch`, never through the SDK
+ * or the REST client: adding the visitor's Authorization header to a pre-signed URL turns a
+ * working upload into a 400.
+ */
+export async function putUpload(uploadUrl: string, file: File, mimeType: string = uploadMimeType(file)): Promise<string> {
+  const put = await fetch(`${uploadUrl}?filename=${encodeURIComponent(file.name)}`, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: file,
+  });
+  if (!put.ok) {
+    // Media Manager's own codes land here: FILE_SIZE_OVER_LIMIT, UNSUPPORTED_FILE_FORMAT,
+    // MISMATCH_MIME_TYPE, ZERO_FILE_SIZE, SITE_QUOTA_EXCEEDED.
+    throw new Error(`forms: could not upload "${file.name}" (${put.status}). Check its size and type.`);
+  }
+  return uploadUrl;
+}
+
+/**
+ * Upload every File sitting in the form's values and return a copy with each file field
+ * replaced by its uploaded URL(s). Values already holding URLs (a retry after the server
+ * rejected some OTHER field) are kept as they are, so a retry never re-uploads. `uploadOne` is
+ * the transport's getMediaUploadUrl + putUpload.
+ */
+export async function uploadFilesWith(
+  uploadOne: UploadOne,
+  formId: string,
+  fields: FormFieldDto[],
+  values: FormValues,
+): Promise<FormValues> {
+  const next: FormValues = { ...values };
+  for (const field of fields) {
+    if (field.control !== "file" && field.control !== "signature") continue;
+    const picked = ([] as unknown[]).concat(values[field.target] ?? []);
+    const done: string[] = [];
+    // Sequential on purpose: a visitor's uplink is the bottleneck, and a failed file should
+    // stop the submit rather than race more uploads it will throw away.
+    for (const item of picked) {
+      if (typeof item === "string" && item) done.push(item);
+      else if (typeof File !== "undefined" && item instanceof File) done.push(await uploadOne(formId, item));
+    }
+    next[field.target] = done;
+  }
+  return next;
+}
+
+/**
+ * Turn the visitor's values into the map `createSubmission` expects, keyed by each field's
+ * `target` — the same key the controls are bound to, so the keys come out right by
+ * construction with no hand-maintained list to drift.
+ *
+ * Walks the FIELDS, not the values object: a stray key can never reach the API, and a field
+ * the owner just added shows up the moment the schema does.
+ *
+ * Three value shapes: a flat value (text/choice/date), an ARRAY (multi-choice, several files),
+ * an OBJECT (an address, keyed by subfield — the shape behind `address/city` error paths). An
+ * empty optional field is OMITTED rather than sent as "": the server validates what it is given.
+ */
+export function toSubmissionValues(fields: FormFieldDto[], values: FormValues): Record<string, unknown> {
+  const filled = (v: unknown) => v !== undefined && v !== null && String(v).trim() !== "";
+  const out: Record<string, unknown> = {};
+
+  for (const field of fields) {
+    const raw = values?.[field.target];
+
+    if (field.control === "address") {
+      const parts: Record<string, string> = {};
+      const held = (raw ?? {}) as Record<string, unknown>;
+      for (const { sub } of field.addressParts) {
+        if (filled(held[sub])) parts[sub] = String(held[sub]).trim();
+      }
+      if (Object.keys(parts).length) out[field.target] = parts;
+      continue;
+    }
+
+    if (field.control === "file" || field.control === "signature") {
+      // Whatever the upload produced. A stray File that never went through the upload is
+      // dropped rather than sent, since it would 400 the whole form.
+      const urls = ([] as unknown[]).concat(raw ?? []).filter((v): v is string => typeof v === "string" && !!v);
+      if (urls.length) out[field.target] = urls.length === 1 ? urls[0] : urls;
+      continue;
+    }
+
+    if (field.inputType === "ARRAY") {
+      const picked = (Array.isArray(raw) ? raw : []).filter(filled);
+      if (picked.length) out[field.target] = picked;
+      continue;
+    }
+
+    if (field.control === "checkbox") {
+      // A consent checkbox submits a boolean. Unchecked AND optional is omitted; unchecked and
+      // required fails validation before it gets here.
+      if (raw === true) out[field.target] = true;
+      continue;
+    }
+
+    if (!filled(raw)) continue;
+    const value = typeof raw === "string" ? raw.trim() : raw;
+    out[field.target] =
+      field.control === "number" || field.control === "rating" ? Number(value) :
+      field.control === "phone" ? normalizePhone(value) :
+      value;
+  }
+  return out;
+}
+
+/**
+ * The created submission as a DTO. Accepts the REST envelope (`{ submission }`) and the SDK's bare
+ * entity; throws when nothing came back or the status is not one that means "created", so a
+ * caller never shows a thank-you for something that is not a submission.
+ */
+export function toSubmission(created: Raw | null | undefined): SubmissionDto {
+  const submission: Raw | undefined = created?.submission ?? created;
+  const id: string | undefined = submission?._id ?? submission?.id;
+  if (!id) throw new Error("forms: submission failed (nothing returned).");
+  const status: string = submission?.status ?? "";
+  if (!SUBMITTED_OK.has(status)) {
+    throw new Error(
+      `forms: submission status is "${status}" — not one of the statuses that mean the submission ` +
+        `was created (${[...SUBMITTED_OK].join(", ")}), so do not show a success state.`,
+    );
+  }
+  return { id, status };
+}
+
+/**
+ * Pull per-field violations out of a failed create, keyed by input NAME so each message lands
+ * on its own control. `errorPath` is the field's `target`, or a nested path like
+ * `address/subdivision` — exactly how the controls are named, so it maps straight across.
+ *
+ * The documented entries arrive under `details.validationError.fieldViolations[]`, each with
+ * its own nested `data.errors[]` — two levels deeper than the docs' shape. This flattens that.
+ * The SDK error and the REST client's WixApiError both carry that block as `details`.
+ *
+ * Two rejections here are SEED bugs, not frontend bugs — fix them in `seed/SEED.md`, never
+ * by mangling the key or the value:
+ *   - UNKNOWN_VALUE_ERROR on a key that IS in the schema → the field was seeded with no
+ *     `validation` block, and that block is what registers the target as an accepted value.
+ *   - NOT_ALLOWED_VALUE_ERROR on a choice field → the seed's `options[].value` and its
+ *     validation enum disagree; the two declarations must match.
+ */
+export function submissionErrors(err: unknown, fields: FormFieldDto[]): Record<string, string> {
+  const body = (err as Raw)?.details ?? (err as Raw)?.body?.details ?? {};
+  const violations: Raw[] = body?.validationError?.fieldViolations ?? [];
+  const byTarget = new Map(fields.map((f) => [f.target, f]));
+  const out: Record<string, string> = {};
+
+  for (const entry of violations.flatMap((v) => v.data?.errors ?? [v])) {
+    const path: string | undefined = entry?.errorPath;
+    if (!path) continue;
+    const field = byTarget.get(path.split("/")[0]);
+    if (!field) continue;
+    // Wix's own errorMessage is the validator's internal wording — debug only.
+    console.debug("forms: server violation", path, entry.errorType, entry.errorMessage);
+    out[path] = messageFor(entry.errorType, field);
+  }
+  return out;
+}
+
+/** errorType → visitor-facing copy, written from the field's own schema. */
+export function messageFor(errorType: string, f: FormFieldDto): string {
+  const v = f.validation;
+  switch (errorType) {
+    case "REQUIRED_VALUE_ERROR": return `${f.label} is required.`;
+    case "MIN_LENGTH_ERROR": return `${f.label} must be at least ${v.minLength} characters.`;
+    case "MAX_LENGTH_ERROR": return `${f.label} must be at most ${v.maxLength} characters.`;
+    case "MIN_VALUE_ERROR": return `${f.label} must be ${v.minimum ?? "higher"} or more.`;
+    case "MAX_VALUE_ERROR": return `${f.label} must be ${v.maximum ?? "lower"} or less.`;
+    case "PATTERN_ERROR": return `${f.label} is not in the expected format.`;
+    case "NOT_ALLOWED_VALUE_ERROR": return `Choose one of the listed options for ${f.label}.`;
+    case "FORMAT_ERROR":
+      return v.format === "EMAIL" ? "Enter a valid email address."
+        : v.format === "PHONE" ? "Use international format, starting with +."
+        : v.format === "URL" ? "Enter a full URL starting with https://"
+        : `Please check ${f.label}.`;
+    // The enum grows: MIN/MAX_ITEMS_ERROR and DISABLED_FORM_ERROR are reachable without being
+    // listed, so an unmapped type degrades to safe copy rather than showing nothing.
+    default: return `Please check ${f.label}.`;
+  }
+}