@adia-ai/web-modules 0.8.36 → 0.8.37

package/billing/payment-method-form/payment-method-form.css

@@ -0,0 +1,149 @@
+/* ═══════════════════════════════════════════════════════════════
+   <payment-method-form-ui> — Form-participating payment-method composite.
+
+   Stamps a grid of <field-ui> + <input-ui> + <select-ui> sub-controls
+   for collecting card number, expiry, CVC, name, billing address, and
+   country. Form chrome + structured validation; tokenization is the
+   consumer's job (Stripe Elements / Braintree / Adyen).
+
+   SPEC: docs/specs/implementation-ready/SPEC-009-payment-method-form.md
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   Zero raw color values (repo hard rule); rem only.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ───────────────────────────────── */
+
+payment-method-form-ui {
+  --payment-method-form-gap:                  var(--a-space-3);
+  --payment-method-form-grid-template:        "name name" "card card" "expiry cvc" "country postal";
+  --payment-method-form-grid-template-billing:
+    "name name" "card card" "expiry cvc" "address1 address1" "address2 address2" "country postal";
+
+  --payment-method-form-brand-icon-size:      1.25em;
+
+  --payment-method-form-alert-mb:             var(--a-space-3);
+
+  --payment-method-form-summary-bg:           var(--a-bg-muted);
+  --payment-method-form-summary-border:       1px solid var(--md-sys-color-neutral-outline);
+  --payment-method-form-summary-radius:       var(--a-radius-md);
+  --payment-method-form-summary-px:           var(--a-space-4);
+  --payment-method-form-summary-py:           var(--a-space-3);
+
+  --payment-method-form-legal-fg:             var(--a-fg-muted);
+  --payment-method-form-legal-size:           var(--a-text-xs, 0.75rem);
+
+  --payment-method-form-disabled-opacity:     var(--a-opacity-disabled, 0.5);
+}
+
+/* ── Block 2: SCOPED LAYOUT ────────────────────────────────────── */
+
+@scope (payment-method-form-ui) {
+
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--payment-method-form-gap);
+  }
+
+  /* ── Host-level error alert ── */
+  :scope > [data-alert] {
+    margin-block-end: var(--payment-method-form-alert-mb);
+  }
+  :scope > [data-alert][hidden] {
+    display: none;
+  }
+
+  /* ── Saved-card summary row ── */
+  :scope > [data-summary] {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-3);
+    background: var(--payment-method-form-summary-bg);
+    border: var(--payment-method-form-summary-border);
+    border-radius: var(--payment-method-form-summary-radius);
+    padding-inline: var(--payment-method-form-summary-px);
+    padding-block: var(--payment-method-form-summary-py);
+  }
+  :scope > [data-summary][hidden] {
+    display: none;
+  }
+  :scope > [data-summary] > [data-summary-icon] {
+    --a-icon-size: 1.25rem;
+    color: var(--a-fg-muted);
+    flex-shrink: 0;
+  }
+  :scope > [data-summary] > [data-summary-text] {
+    flex: 1;
+    color: var(--md-sys-color-neutral-on-surface);
+    font-size: var(--a-text-sm, 0.875rem);
+  }
+  :scope > [data-summary] > [data-summary-edit] {
+    flex-shrink: 0;
+  }
+
+  /* ── Field grid ── */
+  :scope > [data-grid] {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    grid-template-areas: var(--payment-method-form-grid-template);
+    gap: var(--payment-method-form-gap);
+  }
+  :scope > [data-grid][hidden] {
+    display: none;
+  }
+
+  :scope[require-billing-address] > [data-grid] {
+    grid-template-areas: var(--payment-method-form-grid-template-billing);
+  }
+
+  /* Hidden rows (address lines when require-billing-address is unset)
+     collapse out of the grid without affecting sibling cell flow. */
+  :scope > [data-grid] > field-ui[hidden] {
+    display: none;
+  }
+
+  /* ── Brand badge in card-number trailing slot ── */
+  :scope [data-brand-badge] {
+    display: inline-flex;
+    align-items: center;
+    font-size: var(--payment-method-form-brand-icon-size);
+    color: var(--a-fg-muted);
+    letter-spacing: 0.025em;
+    text-transform: uppercase;
+  }
+  :scope [data-brand-badge] > [data-brand] {
+    font-weight: var(--a-weight-semibold, 600);
+    color: var(--md-sys-color-neutral-on-surface);
+    font-size: var(--a-text-xs, 0.75rem);
+    padding-inline: var(--a-space-2);
+    padding-block: var(--a-space-1);
+    border-radius: var(--a-radius-sm);
+    background: var(--a-bg-muted);
+  }
+  :scope [data-brand-badge] > [data-brand="visa"]       { color: var(--a-info-fg, var(--md-sys-color-neutral-on-surface)); }
+  :scope [data-brand-badge] > [data-brand="mastercard"] { color: var(--a-warning-fg, var(--md-sys-color-neutral-on-surface)); }
+  :scope [data-brand-badge] > [data-brand="amex"]       { color: var(--a-primary-fg, var(--md-sys-color-neutral-on-surface)); }
+  :scope [data-brand-badge] > [data-brand="discover"]   { color: var(--a-success-fg, var(--md-sys-color-neutral-on-surface)); }
+
+  /* ── Slotted legal copy ── */
+  :scope > [data-legal] {
+    color: var(--payment-method-form-legal-fg);
+    font-size: var(--payment-method-form-legal-size);
+    line-height: 1.5;
+  }
+  :scope > [data-legal]:empty {
+    display: none;
+  }
+
+  /* ── Disabled state ── */
+  :scope[disabled] {
+    opacity: var(--payment-method-form-disabled-opacity);
+    pointer-events: none;
+  }
+
+  /* ── Focus-within outline (group-level affordance) ── */
+  :scope:focus-within {
+    /* Visually delegated to per-field controls; the host-level outline
+       would double-up against field-ui's focus styling. */
+  }
+}

package/billing/payment-method-form/payment-method-form.js

@@ -0,0 +1,16 @@
+/**
+ * `<payment-method-form-ui>` — auto-registers the tag on import.
+ *
+ * For a non-side-effect class import (test isolation, tag override),
+ * use the class export from `./payment-method-form.class.js`:
+ *
+ *   import { UIPaymentMethodForm } from '@adia-ai/web-modules/billing/payment-method-form/class';
+ */
+
+import { UIPaymentMethodForm } from './payment-method-form.class.js';
+
+if (!customElements.get('payment-method-form-ui')) {
+  customElements.define('payment-method-form-ui', UIPaymentMethodForm);
+}
+
+export { UIPaymentMethodForm };

package/billing/payment-method-form/payment-method-form.yaml

@@ -0,0 +1,430 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIPaymentMethodForm
+tag: payment-method-form-ui
+status: experimental
+component: PaymentMethodForm
+category: input
+version: 1
+description: |
+  Form-participating composite for capturing a payment method —
+  card number, expiry, CVC, name on card, billing address (optional),
+  and country. The form chrome + structured validation + a single
+  normalized emit event; it does NOT integrate with Stripe Elements
+  or a tokenization SDK directly (consumer responsibility).
+
+  Each sub-field is a <field-ui> wrapper around an <input-ui> (or
+  <select-ui> for country). Card number is Luhn-validated; expiry is
+  parsed as MM/YY with month + year bounds; CVC is 3-4 digits.
+  Brand detection (visa / mastercard / amex / discover) runs against
+  a small regex map and surfaces via the `change` event detail.
+
+  Form value is a JSON-encoded payload of normalized field values
+  serialized through ElementInternals under [name] (default
+  "paymentMethod"). On submit, the host fires
+  `submit-payment-method` with a flat detail
+  `{ token, last4, brand, expMonth, expYear, name, country }`.
+  `token` is a synthetic local-mode token (sha-like opaque string);
+  consumers integrating with a real processor handle tokenization
+  in their own submit listener using `last4` / `brand` / etc.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-009-payment-method-form.md.
+
+# Per ADR-0027 — composites do NOT auto-import the primitives they
+# stamp in connected()/render(). The consumer (or this primitive's
+# .html demo shell) must explicitly side-effect-import each one.
+composes:
+  - field-ui
+  - input-ui
+  - select-ui
+  - alert-ui
+  - icon-ui
+  - button-ui
+
+props:
+  name:
+    description: |
+      Form field name. The composite's serialized form value lives
+      under this key in any wrapping <form>. Defaults to
+      "paymentMethod".
+    type: string
+    default: "paymentMethod"
+    reflect: true
+
+  value:
+    description: |
+      Resolved payment-method token. Read-only externally — the
+      composite writes it after a successful tokenize() call. Setting
+      this to a non-empty string is treated as "prefilled from a
+      saved payment method" and renders the form in
+      read-only-summary mode (last4 + brand + expiry shown).
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+  prefill:
+    description: |
+      JSON-encoded prefill payload `{last4, brand, expMonth, expYear,
+      name, country}`. When set, the summary row renders with the
+      saved-card chrome and the rest of the form is hidden behind an
+      "Edit card" button. Useful for "update saved payment method"
+      flows.
+    type: string
+    default: ""
+    attribute: prefill
+
+  countries:
+    description: |
+      Allowed billing countries, ISO 3166-1 alpha-2 codes. Drives
+      the <select-ui> dropdown's options. Empty array uses a
+      default short list (US, CA, GB, DE, FR, AU).
+    type: array
+    default: []
+    dynamic: true
+
+  default-country:
+    description: |
+      Default selected country (ISO 3166-1 alpha-2). Falls back to
+      the first entry in `countries` (or "US" when empty).
+    type: string
+    default: "US"
+    reflect: true
+    attribute: default-country
+
+  require-billing-address:
+    description: |
+      When set, renders the billing-address sub-fields (address line
+      1, optional line 2, postal code). When unset, only postal code
+      + country are collected for the address-verification check.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: require-billing-address
+
+  disabled:
+    description: |
+      Forwarded to every sub-control. Pointer-events:none on the
+      composite host as a belt-and-suspenders.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+
+  required:
+    description: |
+      Form-validation gate. When set, an empty composite fails
+      checkValidity() with "Payment method required.".
+    type: boolean
+    default: false
+    reflect: true
+
+  error:
+    description: |
+      Externally-set error message (e.g. server-rejected card). When
+      non-empty, the composite renders an <alert-ui variant="danger">
+      at the top of the form and sets aria-invalid=true on the host.
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+  tokenizing:
+    description: |
+      tokenize() in flight — set internally by the composite (and
+      cleared on settle), same read-only-externally convention as
+      `value`. Declared here (mirroring the `states:` entry below) so
+      the in-flight visual state is representable in authored/generated
+      markup for documentation and storyboard fixtures.
+    type: boolean
+    default: false
+    reflect: true
+
+  autofocus:
+    description: |
+      When set, the first sub-field (Name on card) receives focus on
+      first connect. Convention parity with native form elements.
+    type: boolean
+    default: false
+    reflect: true
+
+events:
+  submit-payment-method:
+    description: |
+      Fired when tokenize() resolves — either via an outer <form>
+      submission or an explicit tokenize() call. Detail carries the
+      normalized payload that downstream code POSTs to the billing
+      service. Bubbles.
+    detail:
+      token:
+        type: string
+        description: Synthetic local-mode token (sha-like opaque string).
+      last4:
+        type: string
+        description: Last 4 digits of the card number.
+      brand:
+        type: string
+        description: Detected brand — `visa`, `mastercard`, `amex`, `discover`, or `unknown`.
+      expMonth:
+        type: integer
+        description: Expiry month (1-12).
+      expYear:
+        type: integer
+        description: Expiry year (4-digit).
+      name:
+        type: string
+        description: Name on card.
+      country:
+        type: string
+        description: ISO 3166-1 alpha-2 billing country.
+
+  payment-method-error:
+    description: |
+      Fired when tokenize() fails — either constraint validation
+      surfaced one or more field errors, or a Luhn / expiry / CVC
+      check failed. Bubbles.
+    detail:
+      message:
+        type: string
+        description: Human-readable error message.
+      code:
+        type: string
+        description: Error code — one of `validation-failed`, `card-invalid`, `expired`, `cvc-invalid`.
+      field:
+        type: string
+        description: Field name that surfaced the error (`cardNumber` / `expiry` / `cvc` / `name` / `postalCode` / `country` / null).
+
+  change:
+    description: |
+      Fired on every sub-field input. Detail carries a snapshot of
+      the current form validity + detected card brand. Bubbles.
+    detail:
+      valid:
+        type: boolean
+        description: Whether the form currently passes all constraints.
+      brand:
+        type: string
+        description: Detected brand (`visa` / `mastercard` / `amex` / `discover` / `unknown`).
+
+slots:
+  legal:
+    description: |
+      Optional content rendered below the form fields — typically a
+      terms-of-storage acknowledgement string with link(s).
+
+states:
+  - name: idle
+    description: Default; ready for input.
+  - name: tokenizing
+    description: tokenize() in flight.
+    attribute: tokenizing
+  - name: error
+    description: A field-level or host-level error is present.
+    attribute: error
+  - name: prefilled
+    description: A saved payment method is displayed; form is hidden.
+    attribute: prefilled
+  - name: disabled
+    description: All sub-fields non-interactive.
+    attribute: disabled
+
+traits: []
+
+tokens:
+  --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
+      4-row template — name spans both columns, card number spans
+      both, expiry + cvc share row 3, country + postal share row 4.
+      Address rows append when `require-billing-address` is set.
+    default: '"name name" "card card" "expiry cvc" "country postal"'
+  --payment-method-form-brand-icon-size:
+    description: Inline brand-badge icon size in the card-number suffix.
+    default: 1.25em
+  --payment-method-form-alert-mb:
+    description: Margin-block-end on the host-level error alert.
+    default: var(--a-space-3)
+  --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-radius:
+    description: Corner radius on the saved-card summary row.
+    default: var(--a-radius-md)
+  --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-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-disabled-opacity:
+    description: Opacity applied to the host when [disabled].
+    default: var(--a-opacity-disabled, 0.5)
+
+requiredIcons:
+  - credit-card
+  - lock-key
+  - warning-circle
+
+a2ui:
+  rules:
+    - >-
+      PaymentMethodForm SHOULD be wrapped in a <Form> so its
+      form-value (the resolved token) is delivered on submission.
+      Standalone use requires the consumer wire `tokenize()` from a
+      custom submit handler.
+    - >-
+      PaymentMethodForm MUST NOT receive a `value` prop carrying raw
+      card digits. The form value is the tokenized output; raw card
+      digits live only inside the form's sub-fields and are never
+      mirrored to `value`.
+    - >-
+      PaymentMethodForm SHOULD only be used in test / demo / non-PCI
+      surfaces. Production card-capture flows MUST tokenize via a
+      real payment processor (Stripe Elements, Braintree, Adyen)
+      and consume only the resulting token — this primitive is the
+      form chrome + structured validation, not a tokenization
+      provider.
+    - >-
+      Wrapping PaymentMethodForm inside <Field> duplicates the label
+      and corrupts the grid layout. PaymentMethodForm IS a field
+      group; the host carries `aria-label` directly.
+    - >-
+      `countries` SHOULD list every ISO 3166-1 alpha-2 code your
+      product accepts. Empty arrays fall back to a default short
+      list (US, CA, GB, DE, FR, AU) suitable for early-stage demos
+      only — production deployments should set this explicitly.
+
+anti_patterns:
+  - wrong: |
+      <payment-method-form-ui value="4242 4242 4242 4242"></payment-method-form-ui>
+    why: |
+      Raw card digits in `value`. The composite's value is the
+      tokenized output, never the input. Raw digits leak through
+      reflection back to the attribute and end up in DOM snapshots /
+      browser history / analytics.
+    fix: |
+      <payment-method-form-ui name="paymentMethod" required></payment-method-form-ui>
+  - wrong: |
+      <field-ui label="Card details">
+        <payment-method-form-ui></payment-method-form-ui>
+      </field-ui>
+    why: |
+      PaymentMethodForm IS itself a labeled field group; nesting in
+      Field duplicates the label and breaks the internal grid
+      layout. Field's auto-id stamping confuses the composite's
+      first-focusable lookup.
+    fix: |
+      <payment-method-form-ui aria-label="Card details"></payment-method-form-ui>
+  - wrong: |
+      <form>
+        <payment-method-form-ui></payment-method-form-ui>
+        <button-ui type="submit" text="Save"></button-ui>
+      </form>
+      <script>
+        form.addEventListener('submit', (e) => fetch('/charge', { body: new FormData(form) }));
+      </script>
+    why: |
+      Posting the form's serialized token directly to /charge skips
+      tokenization — the synthetic local-mode token is opaque but
+      NOT a real payment token. A real processor must mint the
+      token before the charge call.
+    fix: |
+      <form>
+        <payment-method-form-ui id="pm"></payment-method-form-ui>
+        <button-ui type="submit" text="Save"></button-ui>
+      </form>
+      <script>
+        form.addEventListener('submit', async (e) => {
+          e.preventDefault();
+          const detail = await pm.tokenize();
+          // Hand `detail.last4` / `detail.brand` to your processor SDK
+          // to mint a real token; POST the resulting token to /charge.
+        });
+      </script>
+
+examples:
+  - name: default
+    description: Empty form, all sub-fields visible, required.
+    a2ui: |
+      [
+        {
+          "id": "pm-1",
+          "component": "PaymentMethodForm",
+          "name": "paymentMethod",
+          "required": true
+        }
+      ]
+  - name: prefilled-saved-card
+    description: |
+      Edit-saved-card flow — summary row renders with the saved
+      card; "Edit card" CTA reveals the full form.
+    a2ui: |
+      [
+        {
+          "id": "pm-2",
+          "component": "PaymentMethodForm",
+          "name": "paymentMethod",
+          "prefill": "{\"last4\":\"4242\",\"brand\":\"visa\",\"expMonth\":12,\"expYear\":2027,\"name\":\"Pat Doe\",\"country\":\"US\"}"
+        }
+      ]
+  - name: with-billing-address
+    description: |
+      Full form including billing address lines + postal + country.
+    a2ui: |
+      [
+        {
+          "id": "pm-3",
+          "component": "PaymentMethodForm",
+          "name": "paymentMethod",
+          "requireBillingAddress": true,
+          "countries": ["US", "CA", "GB", "DE"]
+        }
+      ]
+
+keywords:
+  - payment-method
+  - card
+  - billing
+  - checkout
+  - card-capture
+  - payment
+  - credit-card
+  - debit-card
+  - save-payment-method
+  - update-payment-method
+  - add-card
+
+synonyms:
+  payment-method:
+    - card
+    - card-on-file
+    - billing
+  card:
+    - payment-card
+    - credit-card
+    - debit-card
+  billing:
+    - billing-info
+    - payment-method
+    - card
+
+related:
+  - Form
+  - Field
+  - Input
+  - Select
+  - Alert
+  - PlanPicker
+  - Button