@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/forms/seed/SEED.md

@@ -0,0 +1,225 @@
+# Forms — seed contract
+
+`seed-forms.mjs` takes a plain-data plan and creates the site's forms. You write labels and
+kinds; the seed derives everything the API demands — per-field UUIDs, the two-level options
+nesting, the validation block that must exist even when empty, the choice enum that has to
+agree with the component's options, the per-component prefill key, the immutable `target`, a
+layout referencing every field, and rules keyed by field id. Those are the rules a hand-built
+payload gets wrong while still returning `200`.
+
+**Seed BEFORE building the form UI.** This is the one vertical that does not run in parallel
+with the client: the page renders the fields this creates, and imports the id it returns.
+
+**Additive only** — an existing form with the same name is left exactly as it is and reported
+with `created: false`. Re-running never makes a second copy and never edits one.
+
+## Run
+
+```bash
+node <SKILL_ROOT>/templates/forms/seed/seed-forms.mjs plan.json    # from the project root
+```
+
+## Plan
+
+```json
+{
+  "forms": [
+    {
+      "name": "Contact",
+      "submitText": "Send enquiry",
+      "thankYou": "Thanks, we will reply within two working days.",
+      "fields": [
+        { "label": "Your name",  "kind": "text",     "required": true },
+        { "label": "Email",      "kind": "email",    "required": true },
+        { "label": "Phone",      "kind": "phone",    "country": "GB" },
+        { "label": "Project type", "kind": "select", "choices": ["Brand identity", "Website redesign"], "other": true },
+        { "label": "Tell us more", "kind": "textarea", "hidden": true },
+        { "label": "Services",   "kind": "multi",    "choices": ["SEO", "Copywriting"] },
+        { "label": "Budget",     "kind": "number",   "min": 500, "max": 50000, "step": 100 },
+        { "label": "Start date", "kind": "date",     "min": "$now" },
+        { "label": "I accept the terms", "kind": "checkbox", "required": true }
+      ],
+      "rules": [
+        { "when": { "field": "Project type", "isNot": "Brand identity" }, "show": ["Tell us more"] }
+      ]
+    },
+    {
+      "name": "Application",
+      "submitText": "Apply",
+      "nextText": "Continue",
+      "previousText": "Back",
+      "steps": [
+        { "name": "About you", "fields": ["First name", "Last name", "Email"] },
+        { "name": "Your work", "fields": ["Portfolio", "CV"] }
+      ],
+      "deadline": "2026-12-31T23:59:59Z",
+      "redirect": "https://example.com/thanks",
+      "fields": [
+        { "label": "First name", "kind": "firstName", "required": true },
+        { "label": "Last name",  "kind": "lastName",  "required": true },
+        { "label": "Email",      "kind": "email",     "required": true },
+        { "label": "Portfolio",  "kind": "url" },
+        { "label": "CV",         "kind": "file", "required": true, "formats": ["DOCUMENT"], "fileLimit": 2 }
+      ]
+    }
+  ]
+}
+```
+
+### Form keys
+
+| key | meaning |
+|---|---|
+| `name` | the form's name in the owner's dashboard, and the idempotency key |
+| `submitText` | the submit button's wording (default `"Submit"`) |
+| `nextText` · `previousText` | multi-step: the next / back button wording |
+| `steps` | `[{ name, fields: [labels] }]` — one page per entry, in order; a field named on no step lands on the last page. Omit for a single page |
+| `rules` | `[{ when, show?, hide?, require? }]` — see Rules |
+| `thankYou` · `thankYouSeconds` | the owner's thank-you text shown after a submit; optional auto-hide seconds |
+| `redirect` | send the visitor to this URL after a submit instead (same tab) |
+| `deadline` | ISO date-time after which the form stops accepting submissions |
+| `maxSubmissions` · `perVisitor` | close the form after this many submissions in total / per visitor |
+| `requiredIndicator` | how required fields are marked: `ASTERISK` (default) · `TEXT` · `NONE` |
+
+### Field keys
+
+| key | meaning |
+|---|---|
+| `label` | what the visitor reads — also the basis of the storage key |
+| `kind` | one of the kinds below |
+| `required` | default `false`; on a `checkbox` it means "must be ticked" |
+| `placeholder` · `description` | optional; passed to the control (description renders as help text). A placeholder is at most 100 characters |
+| `default` | the prefill: text, a number, `true` for a checkbox, a choice value (or an array of them for `multi` / `tags`), a date (`"2026-01-31"` or `"$now+2d"`) |
+| `hidden` | start hidden — for a field a rule shows |
+| `choices` | `select` · `radio` · `multi` · `tags` — strings, or `{ value, label }` |
+| `other` · `otherPlaceholder` | a free-text "Other" entry on a choice field: `true` (labelled "Other") or the label |
+| `min` · `max` | `number` · `rating` bounds; on `date` · `time` · `datetime` an ISO value or `$now`, `$now+2d`, `$now-1M` (units `y M d h m`) |
+| `step` | `number`: the allowed increment (`0.01` for money, `1` for whole numbers) |
+| `minLength` · `maxLength` | text length bounds |
+| `pattern` · `patternMessage` | a regex the text must match, and the owner's wording when it does not |
+| `minItems` · `maxItems` | `multi` · `tags` bounds |
+| `fileLimit` · `formats` | `file` — how many files (default 1, max 30); allowed families out of `IMAGE` `DOCUMENT` `VIDEO` `AUDIO` `ARCHIVE` |
+| `buttonText` | `file` — the upload button's wording |
+| `country` · `countries` | `phone`: default country (ISO-2) and the allowed countries; `address`: `countries` restricts the country list |
+| `parts` | `address`: per-subfield required flags, e.g. `{ "postalCode": false, "addressLine2": false }` (`addressLine2: false` also hides it) |
+
+### Kinds
+
+`text` · `textarea` · `email` · `phone` · `url` · `firstName` · `lastName` · `company` ·
+`date` · `time` · `datetime` · `number` · `rating` · `select` · `radio` · `multi` · `tags` ·
+`checkbox` · `file` · `address`
+
+`email`, `phone`, `firstName`, `lastName`, `company` are the CONTACTS kinds — Wix maps them
+onto the owner's CRM contact, so prefer them over a plain `text` field for those.
+
+A required `address` requires country, address line, city and postal code; `parts` overrides
+that per subfield.
+
+### Limits
+
+**The site's plan caps the forms.** A free site allows 4 forms, 10 fields per form, 3 steps and 3
+rules; a paid plan lifts them. The seed reads the live limits (Get Restrictions) and checks the
+whole plan against them before creating anything, naming each form and the cap it breaks; nothing
+is created. Trim the form, or the owner upgrades the plan
+(`https://www.wix.com/upgrade/website?metaSiteId=<siteId>`) and the same plan runs unchanged. Do
+not split one form in two to fit: it spends a form slot and splits a visitor's answers across two
+records. The example above sits at nine fields on purpose.
+
+**`file` needs a paid site plan.** Verified live: on a free site the create fails as a whole with
+`FILE_UPLOAD_RESTRICTIONS_ERROR` (the seed reports it by field label; nothing is created). No API
+call lifts it — the owner upgrades the site in the dashboard, then the same plan runs unchanged.
+When the brief needs the upload now and the site is free, use a `url` kind for that field and add a
+`capabilities.mediaUpload` policy to the plan with `"audience": "visitors"` (Astro stack only; a
+policy admits logged-in members only unless it says so): the site uploads the file itself
+through the shared endpoint and submits the uploaded file's URL as the field's value. Say which way
+you went in the closing message; a "link to your CV" text field is not a substitute for an upload.
+
+### Rules
+
+A rule shows, hides or requires fields while a condition on another field holds — the
+dashboard's Rules tab, written as data. `when` names the deciding field by label and ONE test:
+
+| test | holds when |
+|---|---|
+| `"is": value` · `"isNot": value` | the field equals / does not equal the value (a choice value, text, a number) |
+| `"in": [values]` | the field's value is one of the list |
+| `"includes": value` | a `multi` / `tags` selection contains the value (or text contains it) |
+| `"checked": true` | a `checkbox` is ticked |
+| `"isEmpty": true` · `"isNotEmpty": true` | the field is empty / filled |
+
+Effects: `show: [labels]` (those fields are created hidden and appear while the condition
+holds), `hide: [labels]`, `require: [labels]`. A field a rule hides is cleared and not submitted.
+
+## Result
+
+```json
+{ "forms": [ { "name": "Contact",
+               "formId": "0e0…",
+               "created": true,
+               "fields": [ { "target": "your_name_k3f9x2", "label": "Your name" }, … ],
+               "fieldsLive": 9,
+               "steps": 1,
+               "rules": 1,
+               "degraded": [] } ] }
+```
+
+**`formId` is what the page imports.** `fields[].target` is each input's `name` — the page
+does not need them (it renders `form.fields` from the live schema), but they are the keys the
+owner's submissions are stored under.
+
+**`degraded` must be empty.** It is the read-back check: the seed re-reads the created form and
+compares each field's `componentType` against what it sent, and the step and rule counts. A
+non-empty list means something was accepted and then stored as something else — almost always a
+choice field that lost its options and became a plain text box. Fix the plan, delete nothing, and
+create the form again under a new name; a `200` on create does not mean the field survived.
+
+## What the seed does
+
+1. Installs the Wix Forms app (idempotent).
+2. Lists existing forms in the `wix.form_app.form` namespace — a name match is skipped.
+3. Expands each field, builds the steps and rules, creates the form, reads it back and checks
+   every `componentType`, the step count and the rule count.
+
+## Traps this seed already handles
+
+Listed because a hand-rolled payload hits all of them, and each returns `200` first:
+
+- **A choice field declares its options twice** — the component's `options[]` and the
+  validation `enum` (or `items: { itemType, stringOptions.enum }` for a multi). Disagree and the
+  field is created as a plain text box. With an `other` entry no enum is written: the free text
+  is by definition outside the list. For a multi, `itemType` sits inside `items` beside the
+  options block; one level up the create is a `400` whose message blames the options block.
+- **A rule's expression root is an `and` / `or` group**, even for one condition. A bare
+  condition at the root is a `400` (`UNGROUPED_RULE_EXPRESSION_ROOT`). Every condition carries a
+  `value`, `isEmpty` / `isNotEmpty` / `checked` included (`RULE_CONDITION_VALUE_MISSING` without).
+- **`validation` must be present even when empty**, nested under the *input-type* block, not
+  the component one. Absent, the target is not registered as an accepted value and every
+  submission is rejected with `UNKNOWN_VALUE_ERROR` on a key that IS in the schema.
+- **`required` lives at `inputOptions.required`**, never inside a validation block. A checkbox
+  that must be ticked additionally needs `validation.enum: [true]` — `required` alone only checks
+  that a value is present, and `false` is a value.
+- **The prefill key differs per component**: `options[].default` on a choice, `checked` on a
+  checkbox, `defaultValue` on a rating, `default` elsewhere. The wrong key is silently ignored.
+- **Date bounds live under the format's own block** (`dateOptions` / `timeOptions` /
+  `dateTimeOptions`), as strings, and accept `$now±N`.
+- **`steps` must reference every field, the submit button included.** A field missing from the
+  layout never appears in the owner's dashboard — they cannot edit what the site renders.
+- **Rules reference fields by id** (`fieldOptions.fieldId`, condition `target`), so a rule
+  written by hand against labels never fires.
+- **`target` is immutable** and must be unique within the form: letters, digits and single
+  underscores, starting with a letter.
+- **A checkbox label is rich content** (Ricos), not a string — the owner may put a link to the
+  terms in it. The app flattens it to text.
+- **Use `formFields`, never `fields`** — the latter is the legacy API.
+- **A `file` field fails the whole create on a free site** (`FILE_UPLOAD_RESTRICTIONS_ERROR`, a
+  plan restriction, not a payload bug); the seed names the field and the two ways out.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For forms the user usually hands
+over the form itself: a list of questions, or a PDF or screenshot of the form they use today. Each
+question becomes a field, with the `kind` its answer implies (an email address → `email`, a fixed set
+of answers → `select`, `radio` or `multi`, a long answer → `textarea`, an attachment → `file`); a
+required mark becomes `required`; "if yes, …" becomes a rule; page breaks become `steps`; the
+button label becomes `submitText`; the confirmation wording becomes `thankYou`. Question wording
+verbatim.

package/skills/wix-headless-templates/forms/seed/read-site.mjs

@@ -0,0 +1,53 @@
+// What forms the site has, with their fields — read from the v4 schema (`formFields` +
+// `inputOptions`, the same keys the app's forms-core.ts flattens), so this reports the fields
+// the page will render.
+//   node <SKILL_ROOT>/templates/forms/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const FORMS_APP_ID = "225dd912-7dea-4738-8688-4b8c6955ffc2";
+const NAMESPACE = "wix.form_app.form";
+const D = "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas";
+
+// inputType → its options block; the component block is `<componentType in camelCase>Options`.
+const INPUT_BLOCK = {
+  STRING: "stringOptions", NUMBER: "numberOptions", BOOLEAN: "booleanOptions", ARRAY: "arrayOptions",
+  ADDRESS: "addressOptions", WIX_FILE: "wixFileOptions", PAYMENT: "paymentOptions", SCHEDULING: "schedulingOptions",
+};
+const componentBlock = (componentType) =>
+  `${String(componentType ?? "").toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase())}Options`;
+
+/** A label is a string or Ricos rich content; take its text. */
+function plainText(label) {
+  if (typeof label === "string") return label;
+  const walk = (nodes) => (nodes ?? []).map((n) => (n?.textData?.text ?? "") + walk(n?.nodes)).join("");
+  return walk(label?.nodes).trim();
+}
+
+function describeField(f) {
+  const input = f.inputOptions ?? {};
+  const block = input[INPUT_BLOCK[input.inputType]] ?? {};
+  const component = block[componentBlock(block.componentType)] ?? {};
+  const label = plainText(component.label) || input.target || f.id;
+  return `${label} (${f.identifier ?? block.componentType ?? "?"})${input.required ? "*" : ""}${f.hidden ? " [hidden]" : ""}`;
+}
+
+await runReader({
+  vertical: "forms",
+  appId: FORMS_APP_ID,
+  async read(api, { limit }) {
+    const r = await api.call({ method: "GET", path: `/form-schema-service/v4/forms?namespace=${encodeURIComponent(NAMESPACE)}`, docs: `${D}/list-forms` });
+    const forms = (r.forms ?? []).slice(0, limit);
+    return {
+      formCount: (r.forms ?? []).length,
+      forms: forms.map((f) => ({
+        id: f.id,
+        name: f.name,
+        enabled: f.enabled !== false,
+        fields: (f.formFields ?? []).filter((x) => x.fieldType === "INPUT").map(describeField),
+        steps: (f.steps ?? []).length,
+        rules: (f.formRules ?? []).length + (f.rules ?? []).length,
+        submitAction: f.submitSettings?.submitSuccessAction ?? "NO_ACTION",
+      })),
+    };
+  },
+});