@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,317 @@
+// One form as state — schema in, validated submission out, minus the markup. This vertical
+// ships no components: 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 render
+// `form.fields`; see references/forms/INSTRUCTIONS.md.
+//
+// SSR-friendly: pass a server-fetched FormDto as `initialForm` (Astro frontmatter) and no
+// client fetch happens; a SPA passes nothing and the hook loads it.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getForm } from "../../wix/forms/forms";
+import {
+  createSubmission,
+  normalizePhone,
+  submissionErrors,
+  toSubmissionValues,
+  uploadFiles,
+} from "../../wix/forms/submissions";
+import type { FormDto, FormErrors, FormFieldDto, FormValues } from "../../wix/forms/types";
+
+/**
+ * The key in `errors` for a message that belongs to the FORM rather than one field — a schema
+ * that failed to load, or a rejection with no per-field violations. `@` cannot appear in a
+ * form `target`, so this never collides with a field's own error.
+ */
+export const FORM_ERROR = "@form";
+
+/** The empty form: every field at a value of the shape its control binds to. */
+function defaultValues(fields: FormFieldDto[]): FormValues {
+  const values: FormValues = {};
+  for (const f of fields) values[f.target] = Array.isArray(f.defaultValue) ? [...f.defaultValue] : f.defaultValue;
+  return values;
+}
+
+/**
+ * Check one field's value against its own schema. Exported because it is a plain function —
+ * usable outside React, and the place to look when a message needs rewording.
+ *
+ * Every rule comes from the schema, never from a field's NAME. (The classic mistake is keying
+ * the email check on `target === "email"`; deriving it from `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.
+ */
+export function validateValue(field: FormFieldDto, value: unknown): string {
+  const v = String(value ?? "").trim();
+  const rules = field.validation;
+
+  if (field.required && !v) return `${field.label} is required.`;
+  if (!v) return ""; // optional and empty → fine
+
+  if (field.control === "number" || field.control === "rating") {
+    // The control hands back a string, so parse before comparing: "9" > 10 is false but
+    // "9" > "10" is true.
+    const n = Number(v);
+    if (!Number.isFinite(n)) return `${field.label} must be a number.`;
+    if (rules.minimum != null && n < rules.minimum) return `${field.label} must be ${rules.minimum} or more.`;
+    if (rules.maximum != null && n > rules.maximum) return `${field.label} must be ${rules.maximum} or less.`;
+    return "";
+  }
+
+  if (rules.minLength && v.length < rules.minLength)
+    return `${field.label} must be at least ${rules.minLength} characters.`;
+  if (rules.maxLength && v.length > rules.maxLength)
+    return `${field.label} must be at most ${rules.maxLength} characters.`;
+  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. 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, starting with + and the country code.";
+  if (rules.pattern && !new RegExp(rules.pattern).test(v))
+    return `${field.label} is not in the expected format.`;
+  return "";
+}
+
+/**
+ * One field's error entries, keyed the way the controls are named. A plain field yields at most
+ * one (`target`); an ADDRESS yields one per failing subfield (`target/sub`).
+ *
+ * An address subfield gets the `required` check only — `country` and `subdivision` are
+ * country-dependent enums the schema does not enumerate, so their content is the server's call.
+ */
+function errorsForField(field: FormFieldDto, values: FormValues): FormErrors {
+  const errors: FormErrors = {};
+
+  if (field.control === "address") {
+    const parts = (values[field.target] ?? {}) as Record<string, unknown>;
+    for (const { sub, label, required } of field.addressParts) {
+      if (required && !String(parts[sub] ?? "").trim()) errors[`${field.target}/${sub}`] = `${label} is required.`;
+    }
+    return errors;
+  }
+
+  if (field.control === "file" || field.control === "signature") {
+    // Files are File objects, which no string rule can judge — check the count instead.
+    const picked = ([] as unknown[]).concat(values[field.target] ?? []).filter(Boolean);
+    const limit = field.validation.fileLimit;
+    if (field.required && !picked.length) errors[field.target] = `${field.label} is required.`;
+    else if (limit && picked.length > limit)
+      errors[field.target] = `Attach at most ${limit} file${limit === 1 ? "" : "s"}.`;
+    return errors;
+  }
+
+  if (field.inputType === "ARRAY") {
+    const picked = (Array.isArray(values[field.target]) ? (values[field.target] as unknown[]) : []).filter(Boolean);
+    const { minItems, maxItems } = field.validation;
+    if (field.required && !picked.length) errors[field.target] = `${field.label} is required.`;
+    else if (minItems && picked.length < minItems) errors[field.target] = `Choose at least ${minItems}.`;
+    else if (maxItems && picked.length > maxItems) errors[field.target] = `Choose at most ${maxItems}.`;
+    return errors;
+  }
+
+  if (field.control === "checkbox") {
+    if (field.required && values[field.target] !== true) errors[field.target] = `${field.label} is required.`;
+    return errors;
+  }
+
+  const message = validateValue(field, values[field.target]);
+  if (message) errors[field.target] = message;
+  return errors;
+}
+
+function errorsForForm(fields: FormFieldDto[], values: FormValues): FormErrors {
+  const errors: FormErrors = {};
+  for (const field of fields) Object.assign(errors, errorsForField(field, values));
+  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 checking only for an element
+ * silently skips every choice group.
+ */
+function focusControl(formEl: HTMLFormElement | null, name: string): void {
+  const control = formEl?.elements?.namedItem?.(name) as unknown;
+  const node =
+    typeof RadioNodeList !== "undefined" && control instanceof RadioNodeList
+      ? (control[0] as HTMLElement | undefined)
+      : (control as HTMLElement | undefined);
+  node?.focus?.();
+}
+
+export interface UseWixFormOptions {
+  /** Server-fetched form (Astro frontmatter) — skips the client fetch entirely. */
+  initialForm?: FormDto;
+}
+
+export interface UseWixForm {
+  /** null while the schema is loading — render a skeleton, not an empty form. */
+  form: FormDto | null;
+  /** `target` → current value. Arrays for multi-choice and files, objects for an address. */
+  values: FormValues;
+  setValues: (next: FormValues | ((prev: FormValues) => FormValues)) => void;
+  /** Props for a text-ish control, ready to spread: `<input {...bind("email_a1")} />`. */
+  bind: (target: string) => {
+    name: string;
+    value: string;
+    onChange: (e: { target: { value: string } }) => void;
+    onBlur: () => void;
+    "aria-describedby": string;
+    "aria-invalid": true | undefined;
+  };
+  /** `onSubmit`. Resolves TRUE when the submission was created — that IS the success signal. */
+  submit: (event?: { preventDefault?: () => void; currentTarget?: unknown }) => Promise<boolean>;
+  /** One field, one address subfield, or the whole form when called with nothing. */
+  validate: (target?: string) => boolean;
+  errors: FormErrors;
+  /** Loading the schema, or submitting. */
+  loading: boolean;
+}
+
+export function useWixForm(formId: string, options: UseWixFormOptions = {}): UseWixForm {
+  const { initialForm } = options;
+  const [form, setForm] = useState<FormDto | null>(initialForm ?? null);
+  const [values, setValues] = useState<FormValues>({});
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [loading, setLoading] = useState(!initialForm);
+  // The empty form to reset to after a successful submit — the schema's own defaults.
+  const emptyRef = useRef<FormValues>({});
+
+  const fields = useMemo(() => form?.fields ?? [], [form]);
+
+  useEffect(() => {
+    if (initialForm) return; // the SSR pass already answered this
+    let alive = true;
+    if (!formId) {
+      setLoading(false);
+      setErrors({ [FORM_ERROR]: "No formId — pass one from the seed's forms map." });
+      return;
+    }
+    setLoading(true);
+    getForm(formId)
+      .then((loaded) => {
+        if (!alive) return;
+        setForm(loaded);
+        setErrors({});
+        setLoading(false);
+      })
+      .catch((e: unknown) => {
+        if (!alive) return;
+        // Fail loudly. A form that cannot load is a setup problem — never fall back to a
+        // hand-built form, which would drop real enquiries silently.
+        setErrors({ [FORM_ERROR]: e instanceof Error ? e.message : "Could not load the form." });
+        setLoading(false);
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [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?: string) => {
+      if (!target) {
+        const all = errorsForForm(fields, values);
+        setErrors(all);
+        return Object.keys(all).length === 0;
+      }
+      const key = String(target);
+      const field = fields.find((f) => f.target === key.split("/")[0]);
+      if (!field) return true;
+
+      // The keys this call owns, so a re-check CLEARS what it fixed as well as flagging what it
+      // did not: one key for a plain field, or every subfield when an address itself is named.
+      const owned = key.includes("/")
+        ? [key]
+        : field.control === "address"
+          ? field.addressParts.map(({ sub }) => `${field.target}/${sub}`)
+          : [field.target];
+
+      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],
+  );
+
+  // Covers input / textarea / select. A checkbox or radio group carries `checked` instead of
+  // `value`, and a file input cannot be controlled at all — wire those by hand, keeping the
+  // same `name`, `onBlur` and aria contract.
+  const bind = useCallback(
+    (target: string) => ({
+      name: target,
+      value: String(values[target] ?? ""),
+      onChange: (e: { target: { value: string } }) =>
+        setValues((prev) => ({ ...prev, [target]: e.target.value })),
+      onBlur: () => validate(target),
+      "aria-describedby": `err-${target}`,
+      "aria-invalid": errors[target] ? (true as const) : undefined,
+    }),
+    [values, errors, validate],
+  );
+
+  const submit = useCallback(
+    async (event?: { preventDefault?: () => void; currentTarget?: unknown }) => {
+      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) comes back null.
+      const formEl = (event?.currentTarget ?? null) as HTMLFormElement | 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.
+        focusControl(formEl, Object.keys(clientErrors)[0]);
+        return false;
+      }
+
+      setLoading(true);
+      try {
+        // Attachments go up FIRST — a File 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 uploadFiles(form.id, fields, values);
+        setValues(uploaded); // keep the URLs, so a rejection on another field never re-uploads
+        await createSubmission(form.id, toSubmissionValues(fields, uploaded));
+        setErrors({});
+        setValues(emptyRef.current); // back to the schema's defaults, ready for another
+        return true;
+      } catch (e) {
+        const mapped = submissionErrors(e, fields);
+        if (Object.keys(mapped).length) {
+          setErrors(mapped);
+          focusControl(formEl, Object.keys(mapped)[0]);
+        } else {
+          setErrors({
+            [FORM_ERROR]: e instanceof 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 };
+}

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

@@ -0,0 +1,269 @@
+// 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.
+//
+// ⚠️ 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);
+}
+
+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));
+}
+
+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 ?? "",
+  };
+}
+
+/**
+ * Read one form by id. Throws when the id is wrong or the form was deleted — a form that
+ * cannot load is a setup problem, so fail loudly rather than rendering a hand-built fallback
+ * 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);
+}
+
+/**
+ * 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
+ * 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;
+  return ((res?.forms ?? []) as Raw[]).map(toForm);
+}