@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-vibe-headless/references/forms/app/hooks/useWixForm.js

@@ -0,0 +1,425 @@
+// useWixForm — one form, minus the markup. It loads the LIVE schema, validates against it, submits,
+// and lands the server's violations on the right controls. What it does NOT do is render: this
+// vertical ships no UI, because a form is schema-driven (the owner picks the fields), so every form
+// has a different field set and no "contact form" component could ship for it. You build the markup
+// — see `references/forms/INSTRUCTIONS.md`, "Build the UI".
+//
+//   const { form, values, setValues, bind, submit, validate, errors, loading, read } =
+//     useWixForm(WIX_FORMS.contact.formId);
+//
+// The fields to render are the RAW field objects Wix returned — no projection, nothing hidden. Take
+// them off `form` with the same accessors the hook uses internally (`read` is the module
+// `lib/wix-form-schema-utils.js`, handed back so the UI needs one import):
+//
+//   read.orderedInputs(form).map((field) => <label key={read.targetOf(field)}>{read.labelOf(field)}…</label>)
+//
+// The controls are CONTROLLED: `values` (keyed by each field's `target`) is the form's state, so
+// validate and submit read it directly — there is no FormData pass and no ref to hand over.
+//
+// Reading the live schema rather than a hardcoded field list is what makes an owner's dashboard edit
+// (add, relabel, reorder, require, constrain a field) show up on the site with no code change, and
+// what keeps the submission map from desyncing.
+//
+// Not on React? `validateField` below and everything in `lib/wix-form-schema-utils.js` are plain
+// functions — port the ~80 lines of state around them.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getForm, phoneExample, normalizePhone } from "@/rest/wix-forms";
+import {
+  uploadFormFiles,
+  toSubmissionValues,
+  createSubmission,
+  submissionViolations,
+} from "@/rest/wix-forms-submissions";
+import * as read from "@/lib/wix-form-schema-utils";
+import {
+  targetOf, labelOf, isRequired, isMulti, isFile, isNumber, isAddress,
+  addressPartsOf, validationOf, phoneCountryOf, orderedInputs,
+} from "@/lib/wix-form-schema-utils";
+
+/**
+ * The key in `errors` for a message that belongs to the FORM rather than one field — a schema that
+ * failed to load, or a submit rejection with no per-field violations. `@` can't appear in a Wix
+ * form `target`, so this can never collide with a field's own error.
+ */
+export const FORM_ERROR = "@form";
+
+/**
+ * The empty form: one entry per field, in the shape that field's control binds to — `[]` for a
+ * multi-choice field, `{}` for an address, and the owner's `default` prefill (else `""`) for the
+ * rest. Dropping `defaultValue` here would silently discard a dashboard setting.
+ */
+function defaultValues(fields) {
+  const values = {};
+  for (const field of fields) {
+    values[targetOf(field)] =
+      isAddress(field) ? {} :
+      isMulti(field) || isFile(field) ? [] : // a file field holds File objects
+      // The owner's prefill. Wix spells it `default` on most components and `defaultValue` on a
+      // rating, so read both — picking one silently drops a dashboard setting on the other.
+      read.componentOf(field).default ?? read.componentOf(field).defaultValue ?? "";
+  }
+  return values;
+}
+
+/**
+ * Client-side validation for one field — the rules behind `validate(target)`. It lives here rather
+ * than in `rest/` because nothing about it is a REST call: it's the UI's own read of the schema.
+ * Derives EVERY check from that schema — never from the field's name. (The classic mistake is keying the email check on `target === "email"`; doing it
+ * off `format` means an owner-added PHONE/URL/length rule is honored with no code change.)
+ *
+ * ⚠️ A client check LAXER than the server's is worse than none — the visitor then learns about the
+ * problem only after a round trip, in the server's wording rather than yours. Keep these at least
+ * as strict as the server, and submit the NORMALIZED value the check passed.
+ *
+ * @param {object} field  One raw field, from `fields`.
+ * @param {unknown} value  The control's current value.
+ * @returns {string}  A visitor-facing message, or "" when it passes.
+ */
+export function validateField(field, value) {
+  const rules = validationOf(field);
+  const label = labelOf(field);
+  const v = String(value ?? "").trim();
+  if (isRequired(field) && !v) return `${label} is required.`;
+  if (!v) return ""; // optional + empty → ok
+  if (rules.minLength && v.length < rules.minLength) return `${label} must be at least ${rules.minLength} characters.`;
+  if (rules.maxLength && v.length > rules.maxLength) return `${label} must be at most ${rules.maxLength} characters.`;
+  // A NUMBER field carries no `format`; its rules are the bounds, and the control hands back a
+  // string, so parse before comparing — `"9" > 10` is false but `"9" > "10"` is true.
+  if (isNumber(field)) {
+    const n = Number(v);
+    if (!Number.isFinite(n)) return `${label} must be a number.`;
+    const min = minimumOf(field);
+    const max = maximumOf(field);
+    if (min != null && n < min) return `${label} must be ${min} or more.`;
+    if (max != null && n > max) return `${label} must be ${max} or less.`;
+    return "";
+  }
+  if (rules.format === "EMAIL" && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return "Please enter a valid email address.";
+  if (rules.format === "URL" && !/^https?:\/\/.+/.test(v)) return "Please enter a valid URL.";
+  // PHONE is E.164 server-side: leading +, country code, digits only. Strip formatting first —
+  // visitors add spaces, dashes and parens, and rejecting those is a UX bug, not validation.
+  if (rules.format === "PHONE" && !/^\+[1-9]\d{6,14}$/.test(normalizePhone(v)))
+    return `Use international format, e.g. ${phoneExample(phoneCountryOf(field))}.`;
+  if (rules.pattern && !new RegExp(rules.pattern).test(v)) return `${label} is not in the expected format.`;
+  return "";
+}
+
+/**
+ * A NUMBER field's bounds. The validation block is JSON-Schema shaped everywhere else
+ * (`minLength`, `maxLength`, `pattern`, `format`, `enum`), so the numeric pair is `minimum` /
+ * `maximum`; `minValue` / `maxValue` are read too, since the public reference documents neither
+ * spelling and an older schema may carry them. Undefined when the owner set no bound.
+ */
+const minimumOf = (field) => validationOf(field).minimum ?? validationOf(field).minValue;
+const maximumOf = (field) => validationOf(field).maximum ?? validationOf(field).maxValue;
+
+/** `postalCode` → "Postal code" — an address subfield is a key, not a label the schema carries. */
+function humanizeSub(sub) {
+  const words = sub.replace(/([A-Z])|(\d+)/g, " $1$2").toLowerCase().trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * The error entries one field currently has, keyed by input NAME — the same keys the controls and
+ * the server's error paths use. (Distinct from `validateField` above, which judges a single VALUE
+ * against one field's rules and returns one message; this maps that onto the form's keys, and an
+ * address has several.) A plain field yields at most one entry (`target`); an ADDRESS
+ * yields one per failing subfield (`target/sub`).
+ *
+ * Every rule comes from the schema (`validateField` above): `required`,
+ * `minLength`/`maxLength`, `pattern`, and `format` — EMAIL, PHONE (E.164), URL. Nothing is keyed off
+ * a field's NAME, so an owner-added constraint is honored with no code change.
+ *
+ * An address subfield gets the `required` check only: `country` and `subdivision` are
+ * country-dependent enums the schema doesn't enumerate, so their content is the server's call.
+ */
+function errorsForField(field, values) {
+  const errors = {};
+  const target = targetOf(field);
+
+  if (isAddress(field)) {
+    const parts = values[target] ?? {};
+    for (const { sub, required } of addressPartsOf(field)) {
+      // Only `required` is checkable here: country/subdivision are country-dependent enums the
+      // schema doesn't enumerate, so their content is the server's call.
+      if (required && !String(parts[sub] ?? "").trim())
+        errors[`${target}/${sub}`] = `${humanizeSub(sub)} is required.`;
+    }
+    return errors;
+  }
+
+  // A file field holds File objects, which no string rule can judge — check the count instead.
+  if (isFile(field)) {
+    const limit = validationOf(field).fileLimit;
+    const picked = [].concat(values[target] ?? []).filter(Boolean);
+    if (isRequired(field) && !picked.length) errors[target] = `${labelOf(field)} is required.`;
+    else if (limit && picked.length > limit)
+      errors[target] = `Attach at most ${limit} file${limit === 1 ? "" : "s"}.`;
+    return errors;
+  }
+
+  const message = validateField(field, values[target]);
+  if (message) errors[target] = message;
+  return errors;
+}
+
+/** Every field's error entries, merged into one `name → message` map. */
+function errorsForForm(fields, values) {
+  const errors = {};
+  for (const field of fields) Object.assign(errors, errorsForField(field, values));
+  return errors;
+}
+
+/** `format` → the copy for a FORMAT_ERROR, since "wrong shape" means something different per format. */
+const FORMAT_COPY = {
+  EMAIL: () => "Enter a valid email address.",
+  PHONE: (f) => `Use international format, e.g. ${phoneExample(phoneCountryOf(f))}.`,
+  URL: () => "Enter a full URL starting with https://",
+  DATE: () => "Choose a valid date.",
+};
+
+/** errorType → visitor-facing copy, written from the field's own schema. */
+const ERROR_COPY = {
+  REQUIRED_VALUE_ERROR: (f) => `${labelOf(f)} is required.`,
+  MIN_LENGTH_ERROR: (f) => `${labelOf(f)} must be at least ${validationOf(f).minLength} characters.`,
+  MAX_LENGTH_ERROR: (f) => `${labelOf(f)} must be at most ${validationOf(f).maxLength} characters.`,
+  MIN_VALUE_ERROR: (f) => `${labelOf(f)} must be ${minimumOf(f) ?? "higher"} or more.`,
+  MAX_VALUE_ERROR: (f) => `${labelOf(f)} must be ${maximumOf(f) ?? "lower"} or less.`,
+  FORMAT_ERROR: (f) => FORMAT_COPY[validationOf(f).format]?.(f) ?? `Please check ${labelOf(f)}.`,
+  PATTERN_ERROR: (f) => `${labelOf(f)} is not in the expected format.`,
+  NOT_ALLOWED_VALUE_ERROR: (f) => `Choose one of the listed options for ${labelOf(f)}.`,
+  TYPE_ERROR: (f) => `Please check ${labelOf(f)}.`,
+  UNKNOWN_VALUE_ERROR: (f) => `Please check ${labelOf(f)}.`,
+};
+
+/**
+ * Turn a failed `createSubmission` into per-control messages, keyed by input NAME — so each message
+ * lands on its own control instead of only a form-level banner. An address subfield's server path
+ * (`address/subdivision`) is exactly how its control is named, so it maps straight through.
+ *
+ * The copy is written from `errorType` plus the field's own schema; Wix's `errorMessage` is the
+ * validator's internal wording, so it goes to `console.debug` only. An unmapped `errorType` degrades
+ * to safe copy — the enum grows, and MIN/MAX_VALUE_ERROR, MIN/MAX_ITEMS_ERROR and
+ * DISABLED_FORM_ERROR are all reachable without being listed above.
+ *
+ * ⚠️ Two rejections here are SEED bugs, not frontend bugs — do NOT mangle the key or the value to
+ * work around them (fix them in `seed/SEED.md`):
+ *   • `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.
+ *
+ * @param {Error & { body?: object }} err
+ * @param {object[]} fields  The raw fields being rendered.
+ * @returns {Record<string, string>}  Empty when the failure wasn't a validation error.
+ */
+export function mapSubmissionErrors(err, fields) {
+  const byTarget = new Map(fields.map((f) => [targetOf(f), f]));
+  const errors = {};
+  for (const violation of submissionViolations(err)) {
+    const field = byTarget.get(violation.errorPath.split("/")[0]);
+    if (!field) continue;
+    console.debug("wix-forms: server violation", violation.errorPath, violation.errorType, violation.errorMessage);
+    errors[violation.errorPath] = ERROR_COPY[violation.errorType]?.(field) ?? `Please check ${labelOf(field)}.`;
+  }
+  return errors;
+}
+
+/**
+ * Move focus to a control by input name. ⚠️ `namedItem` returns a `RadioNodeList` for a radio or
+ * checkbox group and an element for everything else — a guard that checks only for an element
+ * silently skips every choice group.
+ */
+function focusControl(formEl, name) {
+  const control = formEl?.elements?.namedItem?.(name);
+  const node =
+    typeof RadioNodeList !== "undefined" && control instanceof RadioNodeList ? control[0] : control;
+  node?.focus?.();
+}
+
+/**
+ * @param {string} formId  The form's GUID — read it from `WIX_FORMS` in `rest/wix-forms.config.js`
+ *                         (written by the seed); never type a literal id into a component.
+ * @returns {{
+ *   form: object|null,
+ *     // The Form exactly as Wix returned it, once loaded. Nothing is stripped or renamed: the
+ *     // fields to render are `read.orderedInputs(form)`, the submit wording
+ *     // `read.submitTextOf(form)`. Never hardcode a field list.
+ *   values: Record<string, unknown>,
+ *     // The form's state, keyed by each field's `target`: a string for text/choice/date, an ARRAY
+ *     // for a multi-choice field, an OBJECT for an address. Bind every control's `value` to it.
+ *   setValues: (next: object | ((prev: object) => object)) => void,
+ *     // The plain React setter — `setValues((v) => ({ ...v, [name]: value }))` from onChange.
+ *   bind: (target: string) => object,
+ *     // The props a text-ish control needs, ready to spread: name, value, onChange, onBlur and the
+ *     // two aria attributes. `<input {...bind(target)} type="email" required />`.
+ *   submit: (event?: SubmitEvent) => Promise<boolean>,
+ *     // Use as `onSubmit`. Validates, submits, and resolves TRUE when the submission was created —
+ *     // that resolved true IS the success signal (a visitor can't read submissions back), so flip
+ *     // your own thank-you state on it. FALSE means `errors` now says why.
+ *   validate: (target?: string) => boolean,
+ *     // `validate("email")` checks that one field, `validate("address/city")` one address subfield,
+ *     // `validate()` the whole form. Every rule comes from the schema — `required`,
+ *     // `minLength`/`maxLength`, `pattern`, `format` (EMAIL/PHONE/URL) — never from a field's name.
+ *     // Writes `errors` (clearing what now passes) and returns whether what it checked passed.
+ *   errors: Record<string, string>,
+ *     // input name → visitor-facing message. The name is the field's `target`, or `target/sub` for
+ *     // an address subfield. `errors[FORM_ERROR]` holds a form-level message (load or submit).
+ *   loading: boolean,
+ *     // Busy: loading the schema (`form` still null) or submitting (`form` set).
+ *   read: typeof import("@/lib/wix-form-schema-utils"),
+ *     // The schema accessors — functions, not data: `read.labelOf(field)`, `read.choicesOf(field)`,
+ *     // `read.submitTextOf(form)`, … Handed back so the UI needs one import.
+ * }}
+ */
+export function useWixForm(formId) {
+  const [form, setForm] = useState(null);
+  const [values, setValues] = useState({});
+  const [errors, setErrors] = useState({});
+  const [loading, setLoading] = useState(true);
+  // The empty form to fall back to after a successful submit — the schema's own defaults.
+  const emptyRef = useRef({});
+
+  // Every visible INPUT the schema lays out, in the owner's order — the list the hook seeds values
+  // from, validates and submits. The UI gets it the same way (`read.orderedInputs(form)`), so there
+  // is no second copy to keep in sync and no filtered subset to explain.
+  const fields = useMemo(() => orderedInputs(form), [form]);
+
+  useEffect(() => {
+    let live = true;
+    if (!formId) {
+      setLoading(false);
+      setErrors({ [FORM_ERROR]: "No formId — pass one from WIX_FORMS (the seed writes it)." });
+      return;
+    }
+    setLoading(true);
+    getForm(formId)
+      .then((loaded) => {
+        if (!live) return;
+        setForm(loaded);
+        setErrors({});
+        setLoading(false);
+      })
+      .catch((e) => {
+        if (!live) return;
+        // Fail loudly. A form that can't load is a setup problem (wrong id, Forms app missing) —
+        // never fall back to a hand-built form, which would drop real enquiries silently.
+        setErrors({ [FORM_ERROR]: e.message || "Could not load the form." });
+        setLoading(false);
+      });
+    return () => {
+      live = false;
+    };
+  }, [formId]);
+
+  // Seed the controls once the schema is in: every control is controlled from the first render, so
+  // each `target` must hold a value of the right shape before any of them mount.
+  useEffect(() => {
+    const empty = defaultValues(fields);
+    emptyRef.current = empty;
+    setValues(empty);
+  }, [fields]);
+
+  const validate = useCallback(
+    (target) => {
+      // No target → the whole form. This is what `submit` runs before it sends anything.
+      if (!target) {
+        const all = errorsForForm(fields, values);
+        setErrors(all);
+        return Object.keys(all).length === 0;
+      }
+
+      const key = String(target);
+      const field = fields.find((f) => targetOf(f) === key.split("/")[0]);
+      if (!field) return true;
+
+      // The error keys this call owns, so a re-check CLEARS what it fixed as well as flagging what
+      // it didn't: one key for a plain field, or all of an address's subfields (`target/sub`) when
+      // the address itself is named. Naming a single subfield scopes it to that one.
+      const owned = key.includes("/")
+        ? [key]
+        : isAddress(field)
+          ? addressPartsOf(field).map(({ sub }) => `${targetOf(field)}/${sub}`)
+          : [targetOf(field)];
+
+      const found = errorsForField(field, values);
+      setErrors((prev) => {
+        const next = { ...prev };
+        for (const k of owned) {
+          delete next[k];
+          if (found[k]) next[k] = found[k];
+        }
+        return next;
+      });
+      return owned.every((k) => !found[k]);
+    },
+    [fields, values],
+  );
+
+  // Everything a text-ish control needs, in one spread: `<input {...bind("email_a1b2")} type="email" />`.
+  // Covers input / textarea / select. A checkbox or radio group carries `checked` instead of `value`
+  // and a file input can't be controlled at all — wire those two by hand (INSTRUCTIONS.md, step 2),
+  // keeping the same `name`, `onBlur` and `aria-*` contract.
+  const bind = useCallback(
+    (target) => ({
+      name: target,
+      value: values[target] ?? "",
+      onChange: (event) => setValues((prev) => ({ ...prev, [target]: event.target.value })),
+      onBlur: () => validate(target),
+      "aria-describedby": `err-${target}`,
+      "aria-invalid": errors[target] ? true : undefined,
+    }),
+    [values, errors, validate],
+  );
+
+  const submit = useCallback(
+    async (event) => {
+      event?.preventDefault?.();
+      // Capture the <form> now: React clears `currentTarget` once the handler returns, so reading it
+      // after the await below (to focus a server-rejected control) would come back null.
+      const formEl = event?.currentTarget ?? null;
+      if (!form) return false;
+
+      // Client pass first, so the visitor gets inline feedback in OUR wording before a round trip.
+      const clientErrors = errorsForForm(fields, values);
+      if (Object.keys(clientErrors).length) {
+        setErrors(clientErrors);
+        // FOCUS the first invalid control — `scrollIntoView` moves the viewport and nothing else,
+        // leaving a keyboard or screen-reader user where they were. The <form> comes from the event,
+        // and each control is found by its `name` (which is its `target`).
+        focusControl(formEl, Object.keys(clientErrors)[0]);
+        return false;
+      }
+
+      setLoading(true);
+      try {
+        // Any picked files go up FIRST — a `File` object is not something the submission API takes,
+        // and its value is the upload URL this hands back. No file fields → nothing happens here.
+        const uploaded = await uploadFormFiles(form.id, fields, values);
+        // Resolves on CONFIRMED, PENDING or PAYMENT_WAITING — all three are created submissions.
+        // There is nothing to read back, so this is the only confirmation there is. (A form that
+        // collects payment leaves the visitor a payment step; call createSubmission directly if you
+        // need its `status` to surface that inside your success state.)
+        await createSubmission(form.id, toSubmissionValues(fields, uploaded));
+        setErrors({});
+        setValues(emptyRef.current); // back to the schema's defaults, ready for another
+        return true;
+      } catch (e) {
+        // Per-field violations land on their controls; anything else is a form-level message.
+        const mapped = mapSubmissionErrors(e, fields);
+        if (Object.keys(mapped).length) {
+          setErrors(mapped);
+          focusControl(formEl, Object.keys(mapped)[0]);
+        } else {
+          setErrors({ [FORM_ERROR]: e.message || "Could not send the form. Please try again." });
+        }
+        return false;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [fields, form, values],
+  );
+
+  return { form, values, setValues, bind, submit, validate, errors, loading, read };
+}

package/skills/wix-vibe-headless/references/forms/app/lib/wix-form-schema-utils.js

@@ -0,0 +1,187 @@
+// Reading a Wix Form schema — plain functions over the RAW `Form` and its `formFields[]`. No React,
+// no REST, no projection: the field object Wix returns IS the model the UI renders from, and these
+// are the accessors that make it readable.
+//
+//   import * as read from "@/lib/wix-form-schema-utils";
+//   read.orderedInputs(form).map((field) => <Field key={read.targetOf(field)} field={field} />)
+//
+// Nothing is guessed, and nothing is dropped — which matters because the schema nests a field's
+// settings TWO levels deep, under blocks named after its own enums:
+//
+//   inputOptions
+//     ├─ target / inputType / required        ← the field's identity
+//     └─ stringOptions | arrayOptions | …     ← named after `inputType`            (`optionsOf`)
+//          ├─ componentType / validation      ← the control, and its rules         (`validationOf`)
+//          └─ dropdownOptions | textInputOptions | …  ← named after `componentType` (`componentOf`)
+//               └─ label / placeholder / options / default
+//
+// ⚠️ Those two block names are the whole reason this file exists. They are looked up in the tables
+// below rather than hand-written at the call site, because `inputOptions.stringOptions.dropdownOptions`
+// spelled out in a component is one typo away from silently reading back no label at all.
+
+/**
+ * `inputType` → the block holding that type's `componentType`, `validation`, and component block.
+ * Every input type the Form Schemas API defines
+ * (https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md).
+ */
+const INPUT_BLOCK = {
+  STRING: "stringOptions",
+  NUMBER: "numberOptions",
+  BOOLEAN: "booleanOptions",
+  ARRAY: "arrayOptions",
+  ADDRESS: "addressOptions",
+  WIX_FILE: "wixFileOptions",
+  PAYMENT: "paymentOptions",
+  SCHEDULING: "schedulingOptions",
+};
+
+/**
+ * `componentType` → the block holding that control's `label`, `placeholder`, `options`, `default`.
+ * Note several fields share one component — short AND long answer are both `TEXT_INPUT`, image
+ * choice and multi choice are both `CHECKBOX_GROUP` — which is why the render branches on
+ * `identifier` too.
+ */
+const COMPONENT_BLOCK = {
+  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",
+};
+
+// An enum missing from a table means Wix added a type — say so ONCE (these run per field per
+// render) instead of quietly handing back an empty block and a field labelled by its target.
+const warned = new Set();
+function blockName(table, key, what) {
+  const name = table[key];
+  if (!name && key && !warned.has(key)) {
+    warned.add(key);
+    console.warn(
+      `wix-forms: no ${what} block mapped for "${key}" — that field will render without its label ` +
+        `or options. Add it to ${what === "inputType" ? "INPUT_BLOCK" : "COMPONENT_BLOCK"} in lib/wix-form-schema-utils.js.`,
+    );
+  }
+  return name;
+}
+
+/** The field's immutable storage key — the input's `name`, and THE submission key. */
+export const targetOf = (field) => field?.inputOptions?.target;
+
+/** STRING | NUMBER | ARRAY | ADDRESS | WIX_FILE | BOOLEAN | PAYMENT | SCHEDULING. */
+export const inputTypeOf = (field) => field?.inputOptions?.inputType;
+
+/** ⚠️ From `inputOptions`, not from `validation`. */
+export const isRequired = (field) => field?.inputOptions?.required ?? false;
+
+/** The input-type block: `componentType`, `validation`, and the component's own sub-block. */
+export const optionsOf = (field) =>
+  field?.inputOptions?.[blockName(INPUT_BLOCK, inputTypeOf(field), "inputType")] ?? {};
+
+/** DROPDOWN | RADIO_GROUP | CHECKBOX_GROUP | TEXT_INPUT | NUMBER_INPUT | FILE_UPLOAD | … */
+export const componentTypeOf = (field) => optionsOf(field).componentType;
+
+/** The component sub-block: `label`, `placeholder`, `options`, `default`, … */
+export const componentOf = (field) =>
+  optionsOf(field)[blockName(COMPONENT_BLOCK, componentTypeOf(field), "componentType")] ?? {};
+
+/** `format`, `minLength`, `maxLength`, `pattern`, `fields` (address), `fileLimit`, `phoneOptions`, … */
+export const validationOf = (field) => optionsOf(field).validation ?? {};
+
+/**
+ * The owner's label, falling back to the target so a control is never nameless.
+ *
+ * ⚠️ The fallback also covers a label that ISN'T A STRING: a BOOLEAN field (consent checkbox) labels
+ * itself with a Ricos rich-content object, which would otherwise reach the page — and any error copy
+ * built from it — as the text `[object Object]`. Render that field's label from
+ * `componentOf(field).label` yourself if you write a branch for it.
+ */
+export const labelOf = (field) => {
+  const label = componentOf(field).label;
+  return typeof label === "string" && label ? label : targetOf(field);
+};
+
+/** Multi-choice: submits an ARRAY of the checked option values. */
+export const isMulti = (field) => inputTypeOf(field) === "ARRAY";
+
+/** File upload or signature: holds `File` objects until submit swaps them for their upload URLs. */
+export const isFile = (field) => inputTypeOf(field) === "WIX_FILE";
+
+/** NUMBER covers both the number input and a rating — the value goes on the wire as a number. */
+export const isNumber = (field) => inputTypeOf(field) === "NUMBER";
+
+/** An ADDRESS submits a nested OBJECT, so its subfields are their own controls. */
+export const isAddress = (field) => inputTypeOf(field) === "ADDRESS";
+
+/** Choice options as `{ value, label }` — a label is optional in the schema, the value never is. */
+export const choicesOf = (field) =>
+  componentOf(field).options?.map((o) => ({ value: o.value, label: o.label ?? o.value })) ?? [];
+
+/**
+ * An ADDRESS field's subfields as `{ sub, required }`, in schema order. `validation.fields` lists
+ * them; only `addressLine2` carries a visibility setting, so this hides just that one when the owner
+ * turned it off.
+ */
+export const addressPartsOf = (field) =>
+  Object.entries(validationOf(field).fields ?? {})
+    .filter(([sub]) => componentOf(field).fieldSettings?.[sub]?.show !== false)
+    .map(([sub, cfg]) => ({ sub, required: cfg?.required ?? false }));
+
+/** The country a PHONE field's example should use — the FIELD's own before the site's. */
+export const phoneCountryOf = (field) =>
+  componentOf(field).defaultCountryCode ?? validationOf(field).phoneOptions?.allowedCountryCodes?.[0];
+
+/**
+ * Every visible INPUT field, in the order the owner laid out.
+ *
+ * ⚠️ Display order comes from `steps[].layout`, NOT from `formFields[]` array order. Take the order
+ * only — the geometry (`row`/`column`/`width`) is Wix's editor layout, which your own design
+ * replaces. 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.
+ *
+ * @param {object} form  A Form from `getForm` / `listForms`.
+ * @returns {object[]}  Raw field objects — read them with the accessors above.
+ */
+export function orderedInputs(form) {
+  const order = new Map(
+    (form?.steps ?? [])
+      // Sort WITHIN each step, then concatenate in step order: `row` restarts at 0 in every step,
+      // so one sort across the flattened list interleaves them — step 1's second field would land
+      // after step 2's first.
+      .flatMap((s) =>
+        (s.layout?.large?.items ?? s.layout?.medium?.items ?? s.layout?.small?.items ?? [])
+          .slice()
+          .sort((a, b) => a.row - b.row || a.column - b.column),
+      )
+      .map((item, i) => [item.fieldId, i]),
+  );
+  return (form?.formFields ?? [])
+    .filter((f) => f.fieldType === "INPUT" && !f.hidden)
+    .sort((a, b) => (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity));
+}
+
+/**
+ * The owner's submit-button wording, or "" when they didn't set one. It lives on the SUBMIT_BUTTON —
+ * a DISPLAY field, so it never appears in `orderedInputs` — and nests under `pageNavigationOptions`
+ * because one control drives both multi-page navigation and the final submit.
+ */
+export const submitTextOf = (form) =>
+  (form?.formFields ?? []).find((f) => f.identifier === "SUBMIT_BUTTON")
+    ?.displayOptions?.pageNavigationOptions?.submitText ?? "";