@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/forms/app/wix/forms/types.ts

@@ -0,0 +1,284 @@
+// Forms DTOs — the serializable shapes every hook and page consumes. A form is schema-driven
+// (the owner picks the fields in their dashboard), so a FormDto is a LIST of fields rather
+// than a fixed interface: render by mapping `form.fields`, never by naming fields in code.
+//
+// Why a DTO at all, when the schema IS the model: the raw `Form` nests a field's settings two
+// levels deep under blocks named after its own enums
+// (`inputOptions.stringOptions.dropdownOptions.label`), carries Date objects and Ricos
+// rich-content labels that are not island-serializable, and spreads display ORDER across
+// `steps[].layout` rather than `formFields[]`. FormFieldDto is that resolved once, in the data
+// layer, into flat keys — the same rule every other vertical here follows.
+//
+// It is a FLATTENING, not a subset: every setting a renderer needs is carried through. When a
+// field kind needs something not listed here, add the key — never reach past the DTO into the
+// raw form.
+
+/** What the visitor types into. Drives which control your component renders. */
+export type FormControl =
+  | "text"
+  | "textarea"
+  | "password"
+  | "number"
+  | "rating"
+  | "email"
+  | "phone"
+  | "url"
+  | "date"
+  | "time"
+  | "datetime"
+  | "select"
+  | "radio"
+  | "checkbox"
+  | "checkboxGroup"
+  | "tags"
+  | "address"
+  | "file"
+  | "signature"
+  | "payment"
+  /** A bookings slot picker embedded in a form — needs the `bookings` vertical, not an <input>. */
+  | "appointment"
+  | "unknown";
+
+/** One choice in a select / radio / checkbox group. */
+export interface FormChoice {
+  value: string;
+  /** The owner's wording, falling back to `value` so a choice is never blank. */
+  label: string;
+  /** IMAGE_CHOICE only: the option's picture, already a browser-loadable URL. */
+  imageUrl?: string;
+}
+
+/** One subfield of an ADDRESS field — its own control, its own error key (`target/sub`). */
+export interface FormAddressPart {
+  /**
+   * `country`, `addressLine`, `streetName`, `streetNumber`, `city`, `subdivision`, `postalCode`, … —
+   * also the key inside the submitted object. WHICH subfields appear, and in what order, follows
+   * the chosen country (Wix's own per-country address templates: Israel has a street name and
+   * number and no subdivision, the United States one address line and a state), so re-read
+   * `addressParts` from the store after the country changes.
+   */
+  sub: string;
+  /** "Postal code", or the country's own word for its subdivision ("State", "Province", "Region"). */
+  label: string;
+  required: boolean;
+  /**
+   * `country`: ISO-2 codes to offer — the owner's `allowedCountries`, else every country.
+   * `subdivision`: the country's states / provinces / regions (value is the ISO 3166-2 code, "US-NY");
+   * absent when the country has none on record — render a text input then.
+   */
+  choices?: FormChoice[];
+}
+
+/** The owner's address settings, kept on the field so the parts can be recomputed for a country. */
+export interface AddressOverrides {
+  /** `validation.fields[sub].required` */
+  required: Record<string, boolean | undefined>;
+  /** `multilineAddressOptions.fieldSettings[sub].show` */
+  show: Record<string, boolean | undefined>;
+  /** `validation.allowedCountries`; empty means every country. */
+  allowedCountries: string[];
+}
+
+/** The schema's own rules, resolved onto the field. Undefined means the owner set no rule. */
+export interface FormValidation {
+  /** EMAIL | PHONE | URL | DATE | TIME | DATE_TIME — drives both the control type and the format check. */
+  format?: string;
+  minLength?: number;
+  maxLength?: number;
+  /** A regex SOURCE string, not a RegExp — compile it at the call site. */
+  pattern?: string;
+  /** The owner's wording for a `pattern` miss (`validationMessages.pattern`); fall back to yours. */
+  patternMessage?: string;
+  /** NUMBER / rating bounds. */
+  minimum?: number;
+  maximum?: number;
+  /** NUMBER step: 0.01 means two decimals; 1 means whole numbers. */
+  multipleOf?: number;
+  /** date / time / datetime bounds, already resolved to ISO (`$now+2d` becomes a real date at load). */
+  minDate?: string;
+  maxDate?: string;
+  /** WIX_FILE: how many files this field accepts (Wix caps it at 30). */
+  fileLimit?: number;
+  /** WIX_FILE: the owner's format families — VIDEO | IMAGE | AUDIO | DOCUMENT | ARCHIVE; empty = any. */
+  fileFormats?: string[];
+  /** WIX_FILE: those families as an `<input accept>` value; "" when any file goes. */
+  accept?: string;
+  /** Multi-choice bounds, when the owner set them. */
+  minItems?: number;
+  maxItems?: number;
+  /** A consent checkbox that must be ticked (`booleanOptions.validation.enum: [true]`). */
+  mustBeTrue?: boolean;
+  /** PHONE: ISO-2 country codes the number may belong to; empty = any. */
+  allowedCountryCodes?: string[];
+}
+
+/**
+ * One visible input, flattened. `target` is the field's immutable storage key — the input's
+ * `name`, the key in `values`, the key in the submission, and the root of the server's error
+ * paths. Everything is keyed by it, so nothing has to be matched by label or index.
+ */
+export interface FormFieldDto {
+  target: string;
+  /** The owner's label. Never empty — falls back to `target`. Always a string (a consent
+   *  checkbox labels itself with rich content upstream; that is flattened to its plain text). */
+  label: string;
+  /** false when the owner hid the label; keep it for assistive tech (aria-label), not on screen. */
+  showLabel: boolean;
+  control: FormControl;
+  required: boolean;
+  /** The visitor cannot change it; it submits its prefill. Render disabled, skip the required check. */
+  readOnly: boolean;
+  /** Hidden right now — by the owner, or by a rule reacting to the current values. Not rendered, not submitted. */
+  hidden: boolean;
+  /** The step this field is laid out on (`FormDto.steps[].id`). */
+  stepId: string;
+  placeholder?: string;
+  /** Help text shown under the control, when the owner wrote one. */
+  description?: string;
+  /** The owner's prefill: "" / [] / {} / false when unset, so the control is controlled from render one. */
+  defaultValue: string | number | boolean | string[] | Record<string, string>;
+  /** select / radio / checkboxGroup / tags — empty for every other control. After rules: the allowed subset. */
+  choices: FormChoice[];
+  /** A free-text "Other" entry the owner enabled on a choice field. Its submitted value is `otherValue(field, text)`. */
+  otherOption?: { label: string; placeholder?: string };
+  /**
+   * address only — empty for every other control. `country` is always first. The store recomputes
+   * these for the country the visitor picked (`FormState.form.fields`), so take them from there.
+   */
+  addressParts: FormAddressPart[];
+  /** address only: what the recomputation needs. Not for rendering. */
+  addressOverrides?: AddressOverrides;
+  validation: FormValidation;
+  /** phone only: the country whose example to show ("US", "GB", …). */
+  phoneCountry?: string;
+  /** file only: the owner's button wording, and the text shown once a file is picked. */
+  buttonText?: string;
+  explanationText?: string;
+  /**
+   * The field's kind as the owner picked it — TEXT_AREA, IMAGE_CHOICE, CONTACTS_EMAIL,
+   * CONTACTS_BIRTHDATE, CONTACTS_SUBSCRIBE, … Several kinds share one component (short and long
+   * answer are both TEXT_INPUT; image choice and multi choice are both CHECKBOX_GROUP), so this is
+   * what separates them when `control` cannot.
+   */
+  identifier: string;
+  /** The raw `inputType` / `componentType`, for the rare branch the flattening does not cover. */
+  inputType: string;
+  componentType: string;
+}
+
+/** One page of a multi-step form. A single-step form has exactly one. */
+export interface FormStep {
+  id: string;
+  /** The owner's step name, "" when unnamed. */
+  name: string;
+  /** The targets laid out on this step, in display order. */
+  targets: string[];
+}
+
+/**
+ * A condition as the owner built it in the Rules tab, normalized from both schema spellings.
+ * Operators are the v4 names: EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY, CONTAINS, NOT_CONTAINS,
+ * LESS_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS, BEFORE, BEFORE_OR_EQUAL,
+ * AFTER, AFTER_OR_EQUAL, BETWEEN, ANY, ARRAY_EQUAL, ARRAY_NOT_EQUAL, CHECKED, NOT_CHECKED, IN,
+ * NOT_IN, IS_DATE_OLDER_THAN(_OR_EQUAL), IS_DATE_NEWER_THAN(_OR_EQUAL).
+ */
+export type RuleCondition =
+  | { and: RuleCondition[] }
+  | { or: RuleCondition[] }
+  | { target: string; operator: string; value?: unknown };
+
+/** What a rule changes on one field while its condition holds. */
+export interface RuleEffect {
+  target: string;
+  hidden?: boolean;
+  required?: boolean;
+  /** The choice values that stay selectable. */
+  allowedValues?: string[];
+}
+
+export interface FormRule {
+  id: string;
+  when: RuleCondition;
+  then: RuleEffect[];
+}
+
+/** What the owner chose to happen after a successful submit (dashboard: Submit settings). */
+export interface FormSuccess {
+  /** THANK_YOU_MESSAGE | REDIRECT | POPUP | NO_ACTION — NO_ACTION when the owner set nothing. */
+  action: string;
+  /** THANK_YOU_MESSAGE: the owner's text, paragraphs separated by "\n". */
+  message?: string;
+  /** THANK_YOU_MESSAGE: auto-hide the message after this many seconds and show the form again. */
+  durationSeconds?: number;
+  /** REDIRECT: the owner's URL (always https://). */
+  redirectUrl?: string;
+  /** REDIRECT: open in a new tab rather than replacing the page. */
+  newTab?: boolean;
+}
+
+/** One form, ready to render. */
+export interface FormDto {
+  id: string;
+  /** The owner's form name — an internal label, not necessarily page copy. */
+  name: string;
+  /** Every input, in the order the owner laid out (across steps, in step order). Hidden ones carry `hidden: true`. */
+  fields: FormFieldDto[];
+  /** The pages of the form, in order. One entry for a plain form. */
+  steps: FormStep[];
+  /** The owner's rules. The store applies them; a page never evaluates them itself. */
+  rules: FormRule[];
+  /** The owner's submit-button wording, or "" when they left the default. */
+  submitText: string;
+  /** Multi-step: the next / back button wording, "" when default. */
+  nextText: string;
+  previousText: string;
+  /** false when the owner switched the form off. Show `disabledMessage` instead of the form. */
+  enabled: boolean;
+  /** The owner's "form closed" text ("" when unset — write your own). */
+  disabledMessage: string;
+  /** The owner's submission limits. The form closes itself at `deadline`; the counts are enforced server-side. */
+  limits: { deadline?: string; maxSubmissions?: number; perVisitor?: number };
+  /** How the owner marks required fields: ASTERISK | TEXT ("Required") | NONE, and where. */
+  requiredIndicator: string;
+  requiredIndicatorBefore: boolean;
+  success: FormSuccess;
+}
+
+/** `target` → the visitor's current value. Arrays for multi-choice, objects for an address. */
+export type FormValues = Record<string, unknown>;
+
+/**
+ * `target` (or `target/sub`) → a visitor-facing message. The key is the control's `name`, so a
+ * message lands on its own control with no mapping table.
+ */
+export type FormErrors = Record<string, string>;
+
+/** An uploaded attachment as the submission carries it (the WIX_FILE value is a list of these). */
+export interface UploadedFile {
+  fileId: string;
+  displayName: string;
+  fileType: string;
+  url?: string;
+}
+
+/** A created submission. There is nothing to read back — this IS the confirmation. */
+export interface SubmissionDto {
+  id: string;
+  /** CONFIRMED | PENDING | PAYMENT_WAITING — all three mean the submission exists. */
+  status: string;
+  /** PAYMENT_WAITING only: the checkout the visitor must be sent to (`checkoutUrl(checkoutId)`). */
+  checkoutId?: string;
+}
+
+/** What a successful `submit()` resolves to — the owner's submit settings applied to this submission. */
+export interface SubmitOutcome {
+  submission: SubmissionDto;
+  /** CHECKOUT | THANK_YOU_MESSAGE | REDIRECT | POPUP | NO_ACTION. */
+  action: string;
+  /** THANK_YOU_MESSAGE: the owner's text; absent → your own thank-you. */
+  message?: string;
+  durationSeconds?: number;
+  /** CHECKOUT or REDIRECT: navigate the document here. */
+  url?: string;
+  newTab?: boolean;
+}

package/skills/wix-headless-templates/forms/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/forms/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});