@adia-ai/web-modules 0.8.36 → 0.8.38

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

@@ -0,0 +1,283 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/PaymentMethodList.json",
+  "title": "PaymentMethodList",
+  "description": "Compound billing primitive that renders the user's saved payment\nmethods (cards, bank accounts, wallets) as a vertical list with one\nrow designated as the default. Each row shows a brand mark, the\nlast-4 / account identifier, an optional expiry, and per-row actions\n(set-default / edit / remove). A trailing \"Add payment method\" CTA\nemits `add` so consumers can route the consumer flow.\n\nDefault is a strict 1-of-N radiogroup — exactly one row carries the\ndefault state when the list is non-empty. The primitive does NOT\nmutate the data source; all changes flow as events (`change`,\n`add`, `remove`, `select`) and the consumer applies the side\neffect against their billing API.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-010-payment-method-list.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "add-icon": {
+      "description": "Phosphor icon name for the add CTA.",
+      "type": "string",
+      "default": "plus"
+    },
+    "add-label": {
+      "description": "Label for the trailing add CTA.",
+      "type": "string",
+      "default": "Add payment method"
+    },
+    "component": {
+      "const": "PaymentMethodList"
+    },
+    "disabled": {
+      "description": "Block all interaction; rows remain visible.",
+      "type": "boolean",
+      "default": false
+    },
+    "methods": {
+      "description": "Array of saved payment-method records. Source of truth for the\nrendered rows. Shape per record:\n{id, brand, last4?, expiry?, holder?, type, default?, status?}.\nEmpty array renders the empty-state.\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "name": {
+      "description": "Form field name for the default-method id. Serialized via\nElementInternals; mirrors UIFormElement conventions.\n",
+      "type": "string",
+      "default": ""
+    },
+    "no-add": {
+      "description": "Hide the trailing \"Add payment method\" CTA (read-only flow,\ncheckout drawer, etc.).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "no-remove": {
+      "description": "Hide per-row remove buttons.",
+      "type": "boolean",
+      "default": false
+    },
+    "value": {
+      "description": "Id of the row currently marked default (the form value). When\nboth `value` and `methods[].default` are set, `value` wins and\nthe primitive emits `change` to reconcile.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<payment-method-list-ui methods='[\n  {\"id\":\"pm_1\",\"default\":true},\n  {\"id\":\"pm_2\"}\n]'></payment-method-list-ui>\n",
+        "why": "Two rows marked default. The primitive clears all but the first\nand emits a corrective `change` event; this is wasted round-trips.\nSource of truth should mark exactly one row.\n",
+        "wrong": "<payment-method-list-ui methods='[\n  {\"id\":\"pm_1\",\"default\":true},\n  {\"id\":\"pm_2\",\"default\":true}\n]'></payment-method-list-ui>\n"
+      },
+      {
+        "fix": "<payment-method-list-ui methods=\"...\"></payment-method-list-ui>\n",
+        "why": "Reinvents 1-of-N default semantics. Drops radiogroup a11y.\nRe-derives the brand-icon dictionary per consumer.\n",
+        "wrong": "A <col-ui> of bespoke <card-ui> rows with manual radio markup\nand a per-row \"make default\" button.\n"
+      },
+      {
+        "fix": "<payment-method-list-ui methods='[{\"id\":\"pm_1\",\"brand\":\"discover\",\"type\":\"card\"}]'>\n</payment-method-list-ui>\n",
+        "why": "\"discover-it\" is a card product, not a brand from the enumerated\nset. The primitive renders the generic credit-card fallback.\n",
+        "wrong": "<payment-method-list-ui methods='[{\"id\":\"pm_1\",\"brand\":\"discover-it\",\"type\":\"card\"}]'>\n</payment-method-list-ui>\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "card-ui",
+      "button-ui",
+      "icon-ui",
+      "tag-ui",
+      "text-ui",
+      "empty-state-ui"
+    ],
+    "events": {
+      "add": {
+        "description": "Fired when the user activates the trailing add CTA. Consumer\nroutes to its add-method flow (drawer / modal / page). Bubbles.\n"
+      },
+      "change": {
+        "description": "Fired when the default method changes — via row activation or\nprogrammatic value set. Bubbles.\n",
+        "detail": {
+          "method": {
+            "description": "The full method record now marked default.",
+            "type": "object"
+          },
+          "previous": {
+            "description": "Id of the previous default (empty string when none).",
+            "type": "string"
+          },
+          "value": {
+            "description": "Id of the new default.",
+            "type": "string"
+          }
+        }
+      },
+      "remove": {
+        "description": "Fired when the user activates a row's remove affordance. Consumer\nremoves the method on its end and writes back via `.remove(id)`\nor by mutating `methods`. Bubbles.\n",
+        "detail": {
+          "id": {
+            "description": "Method id targeted for removal.",
+            "type": "string"
+          },
+          "method": {
+            "description": "The full method record.",
+            "type": "object"
+          }
+        }
+      },
+      "select": {
+        "description": "Fired when the user activates a row without changing the default\n(e.g. an \"Edit\" action). Bubbles.\n",
+        "detail": {
+          "id": {
+            "description": "Method id.",
+            "type": "string"
+          },
+          "method": {
+            "description": "The full method record.",
+            "type": "object"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Saved payment methods in a billing settings panel.",
+        "a2ui": "[\n  {\n    \"id\": \"pml-settings\",\n    \"component\": \"PaymentMethodList\",\n    \"name\": \"default-method\",\n    \"value\": \"pm_1\",\n    \"methods\": [\n      {\"id\":\"pm_1\",\"brand\":\"visa\",\"last4\":\"4242\",\"expiry\":\"2027-05-01\",\"holder\":\"Ada Lovelace\",\"type\":\"card\",\"default\":true},\n      {\"id\":\"pm_2\",\"brand\":\"mastercard\",\"last4\":\"0009\",\"expiry\":\"2026-06-01\",\"holder\":\"Ada Lovelace\",\"type\":\"card\"},\n      {\"id\":\"pm_3\",\"brand\":\"ach\",\"last4\":\"6789\",\"holder\":\"Chase ••6789\",\"type\":\"bank\"}\n    ]\n  }\n]\n",
+        "name": "settings-list"
+      },
+      {
+        "description": "Checkout-drawer picker — no add CTA; read-only-ish.",
+        "a2ui": "[\n  {\n    \"id\": \"pml-checkout\",\n    \"component\": \"PaymentMethodList\",\n    \"name\": \"checkout-method\",\n    \"noAdd\": true,\n    \"methods\": [\n      {\"id\":\"pm_1\",\"brand\":\"visa\",\"last4\":\"4242\",\"expiry\":\"2027-05-01\",\"type\":\"card\",\"default\":true},\n      {\"id\":\"pm_2\",\"brand\":\"mastercard\",\"last4\":\"0009\",\"expiry\":\"2026-06-01\",\"type\":\"card\"}\n    ]\n  }\n]\n",
+        "name": "checkout-drawer"
+      }
+    ],
+    "keywords": [
+      "payment-method",
+      "payment-methods",
+      "saved-cards",
+      "billing",
+      "cards",
+      "payment-card",
+      "credit-card",
+      "default-card",
+      "wallet",
+      "bank-account",
+      "ach",
+      "method-list"
+    ],
+    "name": "PaymentMethodList",
+    "related": [
+      "PlanPicker",
+      "Card",
+      "Button",
+      "Tag",
+      "Icon",
+      "EmptyState"
+    ],
+    "slots": {
+      "add": {
+        "description": "Custom add-CTA replacement. When absent the primitive stamps a\ndefault `<button-ui variant=\"outline\" icon=\"plus\">`. Hidden\nentirely when `[no-add]` is set.\n"
+      },
+      "empty": {
+        "description": "Custom empty-state shown when `methods` is empty. Falls back to a\ndefault <empty-state-ui icon=\"credit-card\"> when omitted.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — rows rendered, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "No methods to render.",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "All rows non-interactive.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "card": [
+        "credit-card",
+        "debit-card",
+        "payment-method"
+      ],
+      "payment": [
+        "billing",
+        "charge"
+      ],
+      "saved": [
+        "stored"
+      ]
+    },
+    "tag": "payment-method-list-ui",
+    "tokens": {
+      "--payment-method-list-add-justify": {
+        "description": "Justification of the trailing add CTA row.",
+        "default": "flex-start"
+      },
+      "--payment-method-list-bg": {
+        "description": "Host background. Defaults to transparent.",
+        "default": "transparent"
+      },
+      "--payment-method-list-brand-frame": {
+        "description": "Brand-mark frame background.",
+        "default": "var(--a-bg-strong)"
+      },
+      "--payment-method-list-brand-radius": {
+        "description": "Brand-mark frame radius.",
+        "default": "var(--a-radius-md)"
+      },
+      "--payment-method-list-brand-size": {
+        "description": "Brand-mark frame size.",
+        "default": "2.5rem"
+      },
+      "--payment-method-list-disabled-opacity": {
+        "description": "Opacity applied when the host is disabled.",
+        "default": 0.5
+      },
+      "--payment-method-list-gap": {
+        "description": "Gap between rows.",
+        "default": "var(--a-space-2)"
+      },
+      "--payment-method-list-row-bg": {
+        "description": "Default row background.",
+        "default": "var(--a-bg)"
+      },
+      "--payment-method-list-row-bg-default": {
+        "description": "Background tint applied to the default row.",
+        "default": "var(--md-sys-color-primary-container)"
+      },
+      "--payment-method-list-row-bg-hover": {
+        "description": "Row hover background.",
+        "default": "var(--a-bg-muted)"
+      },
+      "--payment-method-list-row-border": {
+        "description": "Row border.",
+        "default": "1px solid var(--a-border-subtle)"
+      },
+      "--payment-method-list-row-border-default": {
+        "description": "Border on the default row.",
+        "default": "1px solid var(--md-sys-color-primary)"
+      },
+      "--payment-method-list-row-gap": {
+        "description": "Gap between brand mark, meta, and actions cells.",
+        "default": "var(--a-space-3)"
+      },
+      "--payment-method-list-row-px": {
+        "description": "Row horizontal padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--payment-method-list-row-py": {
+        "description": "Row vertical padding.",
+        "default": "var(--a-space-3)"
+      },
+      "--payment-method-list-row-radius": {
+        "description": "Row corner radius.",
+        "default": "var(--a-radius-lg)"
+      }
+    },
+    "traits": [
+      "focusable"
+    ],
+    "version": 1
+  }
+}