@adia-ai/web-modules 0.8.36 → 0.8.37

package/billing/payment-method-form/payment-method-form.a2ui.json

@@ -0,0 +1,310 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/PaymentMethodForm.json",
+  "title": "PaymentMethodForm",
+  "description": "Form-participating composite for capturing a payment method —\ncard number, expiry, CVC, name on card, billing address (optional),\nand country. The form chrome + structured validation + a single\nnormalized emit event; it does NOT integrate with Stripe Elements\nor a tokenization SDK directly (consumer responsibility).\n\nEach sub-field is a <field-ui> wrapper around an <input-ui> (or\n<select-ui> for country). Card number is Luhn-validated; expiry is\nparsed as MM/YY with month + year bounds; CVC is 3-4 digits.\nBrand detection (visa / mastercard / amex / discover) runs against\na small regex map and surfaces via the `change` event detail.\n\nForm value is a JSON-encoded payload of normalized field values\nserialized through ElementInternals under [name] (default\n\"paymentMethod\"). On submit, the host fires\n`submit-payment-method` with a flat detail\n`{ token, last4, brand, expMonth, expYear, name, country }`.\n`token` is a synthetic local-mode token (sha-like opaque string);\nconsumers integrating with a real processor handle tokenization\nin their own submit listener using `last4` / `brand` / etc.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-009-payment-method-form.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "required": {
+      "description": "Form-validation gate. When set, an empty composite fails\ncheckValidity() with \"Payment method required.\".\n",
+      "type": "boolean",
+      "default": false
+    },
+    "autofocus": {
+      "description": "When set, the first sub-field (Name on card) receives focus on\nfirst connect. Convention parity with native form elements.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "PaymentMethodForm"
+    },
+    "countries": {
+      "description": "Allowed billing countries, ISO 3166-1 alpha-2 codes. Drives\nthe <select-ui> dropdown's options. Empty array uses a\ndefault short list (US, CA, GB, DE, FR, AU).\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "default-country": {
+      "description": "Default selected country (ISO 3166-1 alpha-2). Falls back to\nthe first entry in `countries` (or \"US\" when empty).\n",
+      "type": "string",
+      "default": "US"
+    },
+    "disabled": {
+      "description": "Forwarded to every sub-control. Pointer-events:none on the\ncomposite host as a belt-and-suspenders.\n",
+      "$ref": "common_types.json#/$defs/DynamicBoolean"
+    },
+    "error": {
+      "description": "Externally-set error message (e.g. server-rejected card). When\nnon-empty, the composite renders an <alert-ui variant=\"danger\">\nat the top of the form and sets aria-invalid=true on the host.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "name": {
+      "description": "Form field name. The composite's serialized form value lives\nunder this key in any wrapping <form>. Defaults to\n\"paymentMethod\".\n",
+      "type": "string",
+      "default": "paymentMethod"
+    },
+    "prefill": {
+      "description": "JSON-encoded prefill payload `{last4, brand, expMonth, expYear,\nname, country}`. When set, the summary row renders with the\nsaved-card chrome and the rest of the form is hidden behind an\n\"Edit card\" button. Useful for \"update saved payment method\"\nflows.\n",
+      "type": "string",
+      "default": ""
+    },
+    "require-billing-address": {
+      "description": "When set, renders the billing-address sub-fields (address line\n1, optional line 2, postal code). When unset, only postal code\n+ country are collected for the address-verification check.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "tokenizing": {
+      "description": "tokenize() in flight — set internally by the composite (and\ncleared on settle), same read-only-externally convention as\n`value`. Declared here (mirroring the `states:` entry below) so\nthe in-flight visual state is representable in authored/generated\nmarkup for documentation and storyboard fixtures.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "value": {
+      "description": "Resolved payment-method token. Read-only externally — the\ncomposite writes it after a successful tokenize() call. Setting\nthis to a non-empty string is treated as \"prefilled from a\nsaved payment method\" and renders the form in\nread-only-summary mode (last4 + brand + expiry shown).\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<payment-method-form-ui name=\"paymentMethod\" required></payment-method-form-ui>\n",
+        "why": "Raw card digits in `value`. The composite's value is the\ntokenized output, never the input. Raw digits leak through\nreflection back to the attribute and end up in DOM snapshots /\nbrowser history / analytics.\n",
+        "wrong": "<payment-method-form-ui value=\"4242 4242 4242 4242\"></payment-method-form-ui>\n"
+      },
+      {
+        "fix": "<payment-method-form-ui aria-label=\"Card details\"></payment-method-form-ui>\n",
+        "why": "PaymentMethodForm IS itself a labeled field group; nesting in\nField duplicates the label and breaks the internal grid\nlayout. Field's auto-id stamping confuses the composite's\nfirst-focusable lookup.\n",
+        "wrong": "<field-ui label=\"Card details\">\n  <payment-method-form-ui></payment-method-form-ui>\n</field-ui>\n"
+      },
+      {
+        "fix": "<form>\n  <payment-method-form-ui id=\"pm\"></payment-method-form-ui>\n  <button-ui type=\"submit\" text=\"Save\"></button-ui>\n</form>\n<script>\n  form.addEventListener('submit', async (e) => {\n    e.preventDefault();\n    const detail = await pm.tokenize();\n    // Hand `detail.last4` / `detail.brand` to your processor SDK\n    // to mint a real token; POST the resulting token to /charge.\n  });\n</script>\n",
+        "why": "Posting the form's serialized token directly to /charge skips\ntokenization — the synthetic local-mode token is opaque but\nNOT a real payment token. A real processor must mint the\ntoken before the charge call.\n",
+        "wrong": "<form>\n  <payment-method-form-ui></payment-method-form-ui>\n  <button-ui type=\"submit\" text=\"Save\"></button-ui>\n</form>\n<script>\n  form.addEventListener('submit', (e) => fetch('/charge', { body: new FormData(form) }));\n</script>\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "field-ui",
+      "input-ui",
+      "select-ui",
+      "alert-ui",
+      "icon-ui",
+      "button-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired on every sub-field input. Detail carries a snapshot of\nthe current form validity + detected card brand. Bubbles.\n",
+        "detail": {
+          "brand": {
+            "description": "Detected brand (`visa` / `mastercard` / `amex` / `discover` / `unknown`).",
+            "type": "string"
+          },
+          "valid": {
+            "description": "Whether the form currently passes all constraints.",
+            "type": "boolean"
+          }
+        }
+      },
+      "payment-method-error": {
+        "description": "Fired when tokenize() fails — either constraint validation\nsurfaced one or more field errors, or a Luhn / expiry / CVC\ncheck failed. Bubbles.\n",
+        "detail": {
+          "code": {
+            "description": "Error code — one of `validation-failed`, `card-invalid`, `expired`, `cvc-invalid`.",
+            "type": "string"
+          },
+          "field": {
+            "description": "Field name that surfaced the error (`cardNumber` / `expiry` / `cvc` / `name` / `postalCode` / `country` / null).",
+            "type": "string"
+          },
+          "message": {
+            "description": "Human-readable error message.",
+            "type": "string"
+          }
+        }
+      },
+      "submit-payment-method": {
+        "description": "Fired when tokenize() resolves — either via an outer <form>\nsubmission or an explicit tokenize() call. Detail carries the\nnormalized payload that downstream code POSTs to the billing\nservice. Bubbles.\n",
+        "detail": {
+          "brand": {
+            "description": "Detected brand — `visa`, `mastercard`, `amex`, `discover`, or `unknown`.",
+            "type": "string"
+          },
+          "country": {
+            "description": "ISO 3166-1 alpha-2 billing country.",
+            "type": "string"
+          },
+          "expMonth": {
+            "description": "Expiry month (1-12).",
+            "type": "integer"
+          },
+          "expYear": {
+            "description": "Expiry year (4-digit).",
+            "type": "integer"
+          },
+          "last4": {
+            "description": "Last 4 digits of the card number.",
+            "type": "string"
+          },
+          "name": {
+            "description": "Name on card.",
+            "type": "string"
+          },
+          "token": {
+            "description": "Synthetic local-mode token (sha-like opaque string).",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Empty form, all sub-fields visible, required.",
+        "a2ui": "[\n  {\n    \"id\": \"pm-1\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"required\": true\n  }\n]\n",
+        "name": "default"
+      },
+      {
+        "description": "Edit-saved-card flow — summary row renders with the saved\ncard; \"Edit card\" CTA reveals the full form.\n",
+        "a2ui": "[\n  {\n    \"id\": \"pm-2\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"prefill\": \"{\\\"last4\\\":\\\"4242\\\",\\\"brand\\\":\\\"visa\\\",\\\"expMonth\\\":12,\\\"expYear\\\":2027,\\\"name\\\":\\\"Pat Doe\\\",\\\"country\\\":\\\"US\\\"}\"\n  }\n]\n",
+        "name": "prefilled-saved-card"
+      },
+      {
+        "description": "Full form including billing address lines + postal + country.\n",
+        "a2ui": "[\n  {\n    \"id\": \"pm-3\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"requireBillingAddress\": true,\n    \"countries\": [\"US\", \"CA\", \"GB\", \"DE\"]\n  }\n]\n",
+        "name": "with-billing-address"
+      }
+    ],
+    "keywords": [
+      "payment-method",
+      "card",
+      "billing",
+      "checkout",
+      "card-capture",
+      "payment",
+      "credit-card",
+      "debit-card",
+      "save-payment-method",
+      "update-payment-method",
+      "add-card"
+    ],
+    "name": "UIPaymentMethodForm",
+    "related": [
+      "Form",
+      "Field",
+      "Input",
+      "Select",
+      "Alert",
+      "PlanPicker",
+      "Button"
+    ],
+    "slots": {
+      "legal": {
+        "description": "Optional content rendered below the form fields — typically a\nterms-of-storage acknowledgement string with link(s).\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default; ready for input.",
+        "name": "idle"
+      },
+      {
+        "description": "tokenize() in flight.",
+        "attribute": "tokenizing",
+        "name": "tokenizing"
+      },
+      {
+        "description": "A field-level or host-level error is present.",
+        "attribute": "error",
+        "name": "error"
+      },
+      {
+        "description": "A saved payment method is displayed; form is hidden.",
+        "attribute": "prefilled",
+        "name": "prefilled"
+      },
+      {
+        "description": "All sub-fields non-interactive.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "billing": [
+        "billing-info",
+        "payment-method",
+        "card"
+      ],
+      "card": [
+        "payment-card",
+        "credit-card",
+        "debit-card"
+      ],
+      "payment-method": [
+        "card",
+        "card-on-file",
+        "billing"
+      ]
+    },
+    "tag": "payment-method-form-ui",
+    "tokens": {
+      "--payment-method-form-alert-mb": {
+        "description": "Margin-block-end on the host-level error alert.",
+        "default": "var(--a-space-3)"
+      },
+      "--payment-method-form-brand-icon-size": {
+        "description": "Inline brand-badge icon size in the card-number suffix.",
+        "default": "1.25em"
+      },
+      "--payment-method-form-disabled-opacity": {
+        "description": "Opacity applied to the host when [disabled].",
+        "default": "var(--a-opacity-disabled, 0.5)"
+      },
+      "--payment-method-form-gap": {
+        "description": "Gap between rows of the form grid.",
+        "default": "var(--a-space-3)"
+      },
+      "--payment-method-form-grid-template": {
+        "description": "Grid-template-areas for the field layout. Defaults to a\n4-row template — name spans both columns, card number spans\nboth, expiry + cvc share row 3, country + postal share row 4.\nAddress rows append when `require-billing-address` is set.\n",
+        "default": "\"name name\" \"card card\" \"expiry cvc\" \"country postal\""
+      },
+      "--payment-method-form-legal-fg": {
+        "description": "Foreground color of the slotted legal copy.",
+        "default": "var(--a-fg-muted)"
+      },
+      "--payment-method-form-legal-size": {
+        "description": "Font size of the slotted legal copy.",
+        "default": "var(--a-text-xs, 0.75rem)"
+      },
+      "--payment-method-form-summary-bg": {
+        "description": "Background of the saved-card summary row.",
+        "default": "var(--a-bg-muted)"
+      },
+      "--payment-method-form-summary-border": {
+        "description": "Border on the saved-card summary row.",
+        "default": "1px solid var(--a-border)"
+      },
+      "--payment-method-form-summary-px": {
+        "description": "Horizontal padding inside the saved-card summary row.",
+        "default": "var(--a-space-4)"
+      },
+      "--payment-method-form-summary-py": {
+        "description": "Vertical padding inside the saved-card summary row.",
+        "default": "var(--a-space-3)"
+      },
+      "--payment-method-form-summary-radius": {
+        "description": "Corner radius on the saved-card summary row.",
+        "default": "var(--a-radius-md)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}