@adia-ai/web-modules 0.8.35 → 0.8.37

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

@@ -0,0 +1,128 @@
+/* ═══════════════════════════════════════════════════════════════
+   <payment-method-list-ui> — Saved payment methods (cards / bank /
+   wallet) rendered as a 1-of-N radiogroup list.
+
+   Composite over <card-ui> + <icon-ui> + <tag-ui> + <button-ui> +
+   <empty-state-ui>. Each row is a <card-ui data-row> with a single
+   <header> child carrying the canonical card-ui slot composition:
+     slot=icon       brand mark
+     slot=heading    "Visa ···· 4242" + inline <tag-ui> when default
+     slot=description "Expires 05/27"
+     slot=action     set-default / edit / remove buttons
+   card-ui's @scope rules own the 3-column grid + slot positioning;
+   this file styles only the inter-row stack, default-row chrome,
+   hover/focus, empty/disabled states, and the add CTA.
+
+   SPEC: docs/specs/implementation-ready/SPEC-010-payment-method-list.md
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   Zero raw color values (repo hard rule); zero raw px ≥ 3 (rem only).
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ───────────────────────────────── */
+
+payment-method-list-ui {
+  --payment-method-list-bg:                  transparent;
+  --payment-method-list-gap:                 var(--a-space-2);
+
+  --payment-method-list-row-bg:      var(--md-sys-color-primary-container);
+  --payment-method-list-row-border:  1px solid var(--md-sys-color-primary);
+
+  --payment-method-list-add-justify:         flex-start;
+
+  --payment-method-list-disabled-opacity:    var(--a-opacity-disabled, 0.5);
+}
+
+/* ── Block 2: SCOPED LAYOUT ────────────────────────────────────── */
+
+@scope (payment-method-list-ui) {
+
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-4);
+    background: var(--payment-method-list-bg);
+  }
+
+  /* ── Rows host — column stack of <card-ui> rows ── */
+  :scope > [data-rows] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--payment-method-list-gap);
+  }
+
+  /* ── Per-row card — chrome only; card-ui owns layout via <header>. ── */
+  :scope > [data-rows] > [data-row] {
+    cursor: pointer;
+    transition:
+      background var(--a-duration-fast, 120ms) var(--a-easing, ease),
+      box-shadow var(--a-duration-fast, 120ms) var(--a-easing, ease);
+  }
+
+  :scope > [data-rows] > [data-row]:hover {
+    box-shadow: var(--a-shadow-sm);
+  }
+
+  :scope > [data-rows] > [data-row]:focus-visible {
+    outline: var(--a-focus-ring, 2px solid var(--md-sys-color-primary));
+    outline-offset: 2px;
+    border-color: transparent;
+  }
+
+  /* Default row — accent border + tinted background, applied via card-ui's
+     consumer-extension tokens (--card-bg / --card-border per card-ui.css
+     OD-5 token-shadowing pattern). */
+  :scope > [data-rows] > [data-row][data-default] {
+    --card-bg:     var(--payment-method-list-row-bg);
+    --card-border: var(--payment-method-list-row-border);
+  }
+
+  /* ── Empty-state — gated by [empty] attribute ──
+     Hide [data-empty] when host is NOT empty; do NOT set a display
+     value when shown (that would clobber empty-state-ui's intrinsic
+     flex-column-centered layout from its own @scope). */
+  :scope:not([empty]) > [data-empty] {
+    display: none;
+  }
+  :scope[empty] > [data-rows] {
+    display: none;
+  }
+
+  /* ── Add CTA row ── */
+  :scope > [data-add] {
+    display: flex;
+    justify-content: var(--payment-method-list-add-justify);
+  }
+  :scope > [data-add][hidden] {
+    display: none;
+  }
+
+  /* ── Disabled state ── */
+  :scope[disabled] {
+    opacity: var(--payment-method-list-disabled-opacity);
+    pointer-events: none;
+  }
+
+  /* gh#1079 — the host opacity above already reads as disabled; each child
+     button ALSO painting its own [disabled] surface stacked pale pill blobs
+     onto the dimmed rows ("weird color effects"). Flatten the buttons'
+     chrome — the host-level dim is the one disabled treatment. */
+  :scope[disabled] button-ui {
+    --button-bg: transparent;
+    --button-bg-disabled: transparent;
+    --button-border: transparent;
+    --button-border-disabled: transparent;
+  }
+
+  /* gh#1079 — rows read as table-like entries: icon and actions center
+     against the WHOLE two-row card (card-ui's default anchors the icon to
+     the heading row and actions to row 1, which reads top-heavy here).
+     Consumer-extension via card-ui's own grid, scoped to this list. */
+  :scope > [data-rows] > [data-row] > header > [data-pml-icon] {
+    grid-row: 1 / span 2;
+    align-self: center;
+  }
+  :scope > [data-rows] > [data-row] > header > [data-pml-action] {
+    grid-row: 1 / span 2;
+    align-self: center;
+  }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * `<payment-method-list-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-list.class.js`:
+ *
+ *   import { PaymentMethodList } from '@adia-ai/web-modules/billing/payment-method-list/class';
+ */
+
+import { PaymentMethodList } from './payment-method-list.class.js';
+
+if (!customElements.get('payment-method-list-ui')) {
+  customElements.define('payment-method-list-ui', PaymentMethodList);
+}
+
+export { PaymentMethodList };

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

@@ -0,0 +1,355 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: PaymentMethodList
+tag: payment-method-list-ui
+status: experimental
+component: PaymentMethodList
+category: input
+version: 1
+description: |
+  Compound billing primitive that renders the user's saved payment
+  methods (cards, bank accounts, wallets) as a vertical list with one
+  row designated as the default. Each row shows a brand mark, the
+  last-4 / account identifier, an optional expiry, and per-row actions
+  (set-default / edit / remove). A trailing "Add payment method" CTA
+  emits `add` so consumers can route the consumer flow.
+
+  Default is a strict 1-of-N radiogroup — exactly one row carries the
+  default state when the list is non-empty. The primitive does NOT
+  mutate the data source; all changes flow as events (`change`,
+  `add`, `remove`, `select`) and the consumer applies the side
+  effect against their billing API.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-010-payment-method-list.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:
+  - card-ui
+  - button-ui
+  - icon-ui
+  - tag-ui
+  - text-ui
+  - empty-state-ui
+
+props:
+  methods:
+    description: |
+      Array of saved payment-method records. Source of truth for the
+      rendered rows. Shape per record:
+      {id, brand, last4?, expiry?, holder?, type, default?, status?}.
+      Empty array renders the empty-state.
+    type: array
+    default: []
+    dynamic: true
+    required: false
+
+  value:
+    description: |
+      Id of the row currently marked default (the form value). When
+      both `value` and `methods[].default` are set, `value` wins and
+      the primitive emits `change` to reconcile.
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+  name:
+    description: |
+      Form field name for the default-method id. Serialized via
+      ElementInternals; mirrors UIFormElement conventions.
+    type: string
+    default: ""
+    reflect: true
+
+  add-label:
+    description: Label for the trailing add CTA.
+    type: string
+    default: "Add payment method"
+    attribute: add-label
+
+  add-icon:
+    description: Phosphor icon name for the add CTA.
+    type: string
+    default: "plus"
+    attribute: add-icon
+
+  no-add:
+    description: |
+      Hide the trailing "Add payment method" CTA (read-only flow,
+      checkout drawer, etc.).
+    type: boolean
+    default: false
+    reflect: true
+    attribute: no-add
+
+  no-remove:
+    description: Hide per-row remove buttons.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: no-remove
+
+  disabled:
+    description: Block all interaction; rows remain visible.
+    type: boolean
+    default: false
+    reflect: true
+
+events:
+  change:
+    description: |
+      Fired when the default method changes — via row activation or
+      programmatic value set. Bubbles.
+    detail:
+      value:
+        type: string
+        description: Id of the new default.
+      previous:
+        type: string
+        description: Id of the previous default (empty string when none).
+      method:
+        type: object
+        description: The full method record now marked default.
+
+  add:
+    description: |
+      Fired when the user activates the trailing add CTA. Consumer
+      routes to its add-method flow (drawer / modal / page). Bubbles.
+
+  remove:
+    description: |
+      Fired when the user activates a row's remove affordance. Consumer
+      removes the method on its end and writes back via `.remove(id)`
+      or by mutating `methods`. Bubbles.
+    detail:
+      id:
+        type: string
+        description: Method id targeted for removal.
+      method:
+        type: object
+        description: The full method record.
+
+  select:
+    description: |
+      Fired when the user activates a row without changing the default
+      (e.g. an "Edit" action). Bubbles.
+    detail:
+      id:
+        type: string
+        description: Method id.
+      method:
+        type: object
+        description: The full method record.
+
+slots:
+  empty:
+    description: |
+      Custom empty-state shown when `methods` is empty. Falls back to a
+      default <empty-state-ui icon="credit-card"> when omitted.
+
+  add:
+    description: |
+      Custom add-CTA replacement. When absent the primitive stamps a
+      default `<button-ui variant="outline" icon="plus">`. Hidden
+      entirely when `[no-add]` is set.
+
+states:
+  - name: idle
+    description: Default — rows rendered, ready for interaction.
+  - name: empty
+    description: No methods to render.
+    attribute: empty
+  - name: disabled
+    description: All rows non-interactive.
+    attribute: disabled
+
+traits:
+  - focusable
+
+tokens:
+  --payment-method-list-bg:
+    description: Host background. Defaults to transparent.
+    default: transparent
+  --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-hover:
+    description: Row hover background.
+    default: var(--a-bg-muted)
+  --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-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-radius:
+    description: Row corner radius.
+    default: var(--a-radius-lg)
+  --payment-method-list-row-py:
+    description: Row vertical padding.
+    default: var(--a-space-3)
+  --payment-method-list-row-px:
+    description: Row horizontal padding.
+    default: var(--a-space-4)
+  --payment-method-list-row-gap:
+    description: Gap between brand mark, meta, and actions cells.
+    default: var(--a-space-3)
+  --payment-method-list-brand-size:
+    description: Brand-mark frame size.
+    default: 2.5rem
+  --payment-method-list-brand-radius:
+    description: Brand-mark frame radius.
+    default: var(--a-radius-md)
+  --payment-method-list-brand-frame:
+    description: Brand-mark frame background.
+    default: var(--a-bg-strong)
+  --payment-method-list-add-justify:
+    description: Justification of the trailing add CTA row.
+    default: flex-start
+  --payment-method-list-disabled-opacity:
+    description: Opacity applied when the host is disabled.
+    default: 0.5
+
+requiredIcons:
+  - plus
+  - trash
+  - credit-card
+  - check-circle
+  - bank
+  - pencil
+
+a2ui:
+  rules:
+    - >-
+      PaymentMethodList.methods MUST be an array. Empty array is valid
+      and renders the empty-state.
+    - >-
+      methods[].id MUST be unique within the list. Duplicate ids cause
+      row collision at diff time.
+    - >-
+      Exactly one record in `methods` MAY have `default: true`. If
+      none does, the primitive marks the first row as default on
+      connect.
+    - >-
+      methods[].brand SHOULD be from the enumerated set
+      (visa | mastercard | amex | discover | jcb | unionpay | diners |
+      paypal | apple-pay | google-pay | ach | sepa). Unknown brands
+      fall back to a generic credit-card mark.
+    - >-
+      methods[].type MUST be `card`, `bank`, or `wallet`. Drives the
+      brand-icon fallback when `brand` is unknown.
+    - >-
+      `value` wins on conflict with methods[].default — if both are
+      set and disagree, value is the source of truth and the
+      primitive emits `change` to reconcile.
+    - >-
+      Mutations are events, not props. Wire `change` / `add` /
+      `remove` / `select` to your billing API; the primitive does NOT
+      write to the underlying data source.
+
+anti_patterns:
+  - wrong: |
+      <payment-method-list-ui methods='[
+        {"id":"pm_1","default":true},
+        {"id":"pm_2","default":true}
+      ]'></payment-method-list-ui>
+    why: |
+      Two rows marked default. The primitive clears all but the first
+      and emits a corrective `change` event; this is wasted round-trips.
+      Source of truth should mark exactly one row.
+    fix: |
+      <payment-method-list-ui methods='[
+        {"id":"pm_1","default":true},
+        {"id":"pm_2"}
+      ]'></payment-method-list-ui>
+  - wrong: |
+      A <col-ui> of bespoke <card-ui> rows with manual radio markup
+      and a per-row "make default" button.
+    why: |
+      Reinvents 1-of-N default semantics. Drops radiogroup a11y.
+      Re-derives the brand-icon dictionary per consumer.
+    fix: |
+      <payment-method-list-ui methods="..."></payment-method-list-ui>
+  - wrong: |
+      <payment-method-list-ui methods='[{"id":"pm_1","brand":"discover-it","type":"card"}]'>
+      </payment-method-list-ui>
+    why: |
+      "discover-it" is a card product, not a brand from the enumerated
+      set. The primitive renders the generic credit-card fallback.
+    fix: |
+      <payment-method-list-ui methods='[{"id":"pm_1","brand":"discover","type":"card"}]'>
+      </payment-method-list-ui>
+
+examples:
+  - name: settings-list
+    description: Saved payment methods in a billing settings panel.
+    a2ui: |
+      [
+        {
+          "id": "pml-settings",
+          "component": "PaymentMethodList",
+          "name": "default-method",
+          "value": "pm_1",
+          "methods": [
+            {"id":"pm_1","brand":"visa","last4":"4242","expiry":"2027-05-01","holder":"Ada Lovelace","type":"card","default":true},
+            {"id":"pm_2","brand":"mastercard","last4":"0009","expiry":"2026-06-01","holder":"Ada Lovelace","type":"card"},
+            {"id":"pm_3","brand":"ach","last4":"6789","holder":"Chase ••6789","type":"bank"}
+          ]
+        }
+      ]
+  - name: checkout-drawer
+    description: Checkout-drawer picker — no add CTA; read-only-ish.
+    a2ui: |
+      [
+        {
+          "id": "pml-checkout",
+          "component": "PaymentMethodList",
+          "name": "checkout-method",
+          "noAdd": true,
+          "methods": [
+            {"id":"pm_1","brand":"visa","last4":"4242","expiry":"2027-05-01","type":"card","default":true},
+            {"id":"pm_2","brand":"mastercard","last4":"0009","expiry":"2026-06-01","type":"card"}
+          ]
+        }
+      ]
+
+keywords:
+  - payment-method
+  - payment-methods
+  - saved-cards
+  - billing
+  - cards
+  - payment-card
+  - credit-card
+  - default-card
+  - wallet
+  - bank-account
+  - ach
+  - method-list
+
+synonyms:
+  payment:
+    - billing
+    - charge
+  card:
+    - credit-card
+    - debit-card
+    - payment-method
+  saved:
+    - stored
+
+related:
+  - PlanPicker
+  - Card
+  - Button
+  - Tag
+  - Icon
+  - EmptyState