@adia-ai/web-modules 0.8.36 → 0.8.37

package/billing/plan-picker/plan-picker.class.js

@@ -0,0 +1,635 @@
+/**
+ * <plan-picker-ui> — Form-participating chooser of one of N billing plans.
+ *
+ * The canonical plan-card grid used by both in-app upgrade flows AND the
+ * marketing pricing page (SPEC-012). Each plan card is composed from
+ * <option-card-ui> (radio semantics) decorated with a price block,
+ * feature list, and CTA button derived from the plan record. The
+ * optional cycle toggle is a <segmented-ui> that swaps monthly /
+ * annual prices in place across every card.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.md
+ * WAI-APG: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   This composite stamps a four-region skeleton once on first connect:
+ *     [data-toggle] · [data-plans] · [data-skeleton] · [data-empty]
+ *   Then mutates per-card DOM by id-keyed in-place diff on every
+ *   `plans` / `value` / `current` / `cycle` change. The diff preserves
+ *   focus-within during re-render (replacing children would break the
+ *   radiogroup keyboard model — see the FLIP-via-in-place-diff memory).
+ *
+ * Form participation:
+ *   Extends UIFormElement. `value` (selected plan id) serializes under
+ *   `name` via ElementInternals. Per ADR-0025 no native radio is
+ *   rendered — the selected card's [checked] state is the sole source
+ *   of truth.
+ *
+ * Public API:
+ *   .setValue(id)    — select a plan by id; returns true on hit.
+ *   .setCycle(cycle) — switch the billing cycle; returns true on hit.
+ *   .refresh()       — re-fetch from data-stream-src when configured.
+ */
+
+import { UIFormElement } from '@adia-ai/web-components/core/form';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+const KNOWN_CYCLES = new Set(['monthly', 'annual']);
+
+const CYCLE_LABELS = {
+  monthly: 'Monthly',
+  annual: 'Annual',
+};
+
+const CYCLE_SUFFIX = {
+  monthly: '/month',
+  annual: '/year',
+};
+
+/**
+ * Format an amount with Intl.NumberFormat for the given currency + locale.
+ * Returns a string like "$25" or "€20"; falls back to "$N" on failure.
+ */
+function formatAmount(amount, currency, locale) {
+  const value = Number.isFinite(amount) ? amount : 0;
+  try {
+    return new Intl.NumberFormat(locale || undefined, {
+      style: 'currency',
+      currency: currency || 'USD',
+      maximumFractionDigits: Number.isInteger(value) ? 0 : 2,
+    }).format(value);
+  } catch {
+    return `${currency || '$'}${value}`;
+  }
+}
+
+/**
+ * Derive the CTA label for a plan relative to the host's `current`.
+ * - Same id as current → "Manage"
+ * - rank > currentRank  → "Upgrade"
+ * - rank < currentRank  → "Downgrade"
+ * - otherwise            → "Choose {name}"
+ * Consumer can override per-record via plans[].cta.
+ */
+function deriveCtaLabel(plan, plans, current) {
+  if (plan.cta) return plan.cta;
+  if (!current) return `Choose ${plan.name || ''}`.trim();
+  if (plan.id === current) return 'Manage';
+  const cur = plans.find((p) => p.id === current);
+  if (cur && Number.isFinite(cur.rank) && Number.isFinite(plan.rank)) {
+    if (plan.rank > cur.rank) return 'Upgrade';
+    if (plan.rank < cur.rank) return 'Downgrade';
+  }
+  return `Switch to ${plan.name || ''}`.trim();
+}
+
+export class PlanPicker extends UIFormElement {
+  // `label` is NOT first-class here — host carries aria-label directly.
+  static labelDeprecated = true;
+
+  static get properties() {
+    return {
+      ...UIFormElement.properties,
+      // `plans` is the source of truth — array via prop OR JSON attribute.
+      plans:        { type: Array,   default: [] },
+      // Currently selected plan id. Mirrors UIFormElement.value.
+      value:        { type: String,  default: '', reflect: true },
+      // Anchor id — the user's current plan.
+      current:      { type: String,  default: '', reflect: true },
+      cycle:        { type: String,  default: 'monthly', reflect: true },
+      cycleToggle:  { type: Boolean, default: false, reflect: true, attribute: 'cycle-toggle' },
+      currency:     { type: String,  default: 'USD' },
+      locale:       { type: String,  default: '' },
+      layout:       { type: String,  default: 'grid', reflect: true },
+      disabled:     { type: Boolean, default: false, reflect: true },
+    };
+  }
+
+  // No template — the composite stamps a fixed region skeleton once
+  // (toggle · plans · skeleton · empty) and mutates per-region nodes
+  // across renders. Returning html`` would trigger stamp() →
+  // replaceChildren() and wipe authored slot children + zap the
+  // <option-card-ui> radiogroup state.
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #toggleHost = null;        // <div data-toggle> wrapper
+  #toggleSegmented = null;   // <segmented-ui> inside toggle host
+  #plansHost = null;         // <div data-plans role=radiogroup>
+  #skeletonHost = null;      // <div data-skeleton>
+  #emptyHost = null;         // <empty-state-ui data-empty>
+  #cardsById = new Map();    // id → <option-card-ui>
+  #internalUpdate = false;
+  #warnedCycle = false;
+  #warnedRecommend = false;
+  #loadCount = 0;            // monotonic — detects out-of-order fetches
+
+  // ── Public imperative API (SPEC §4 Methods) ───────────────────────
+
+  /** Select a plan by id. Returns true on hit. */
+  setValue(id) {
+    if (!id) return false;
+    return untracked(() => {
+      const found = (this.plans || []).find((p) => p.id === id);
+      if (!found) return false;
+      if (found.disabled) {
+        this.dispatchEvent(new CustomEvent('error', {
+          bubbles: true,
+          detail: { reason: 'plan-disabled' },
+        }));
+        return false;
+      }
+      if (this.value === id) return true;
+      const previous = this.value || '';
+      this.value = id;
+      this.syncValue();
+      this.#emitChange(id, previous);
+      return true;
+    });
+  }
+
+  /** Switch the billing cycle. Returns true on hit. */
+  setCycle(cycle) {
+    if (!KNOWN_CYCLES.has(cycle)) return false;
+    return untracked(() => {
+      if (this.cycle === cycle) return true;
+      const previous = this.cycle;
+      this.cycle = cycle;
+      this.dispatchEvent(new CustomEvent('cycle-change', {
+        bubbles: true,
+        detail: { cycle, previous },
+      }));
+      return true;
+    });
+  }
+
+  /** Re-fetch plans from `data-stream-src`. */
+  async refresh() {
+    const src = this.getAttribute('data-stream-src');
+    if (!src) return;
+    const tag = ++this.#loadCount;
+    this.setAttribute('loading', '');
+    this.removeAttribute('error');
+    try {
+      const res = await fetch(src);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      if (tag !== this.#loadCount) return; // stale
+      this.removeAttribute('loading');
+      const list = Array.isArray(data) ? data : (Array.isArray(data?.plans) ? data.plans : []);
+      this.plans = list;
+      this.dispatchEvent(new CustomEvent('load', {
+        bubbles: true,
+        detail: { count: list.length },
+      }));
+    } catch (err) {
+      if (tag !== this.#loadCount) return;
+      this.removeAttribute('loading');
+      this.setAttribute('error', '');
+      this.dispatchEvent(new CustomEvent('error', {
+        bubbles: true,
+        detail: { reason: 'fetch-failed', message: String(err?.message || err) },
+      }));
+    }
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'radiogroup');
+    if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+      this.setAttribute('aria-label', 'Choose a plan');
+    }
+
+    if (!this.#stamped) {
+      // Attempt to absorb a <script type="application/json" data-plans>
+      // child before stamping wipes the host's children. Authors can
+      // write the plans array declaratively this way (the in-band JSON
+      // pattern shipped by chart-ui + table-ui).
+      this.#absorbInlinePlansScript();
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    // Trigger first render after the registry has had a chance to
+    // upgrade the composed primitives.
+    untracked(() => this.render());
+
+    // Fetch on connect when configured.
+    if (this.getAttribute('data-stream-src')) {
+      this.refresh();
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    for (const fn of this.#cleanups) {
+      try { fn(); } catch { /* ignore stale */ }
+    }
+    this.#cleanups.length = 0;
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+    if (!this.#stamped || this.#internalUpdate) return;
+    if (name === 'data-stream-src' && oldVal !== newVal && newVal) {
+      this.refresh();
+    }
+  }
+
+  // ── Form participation ────────────────────────────────────────────
+
+  /** Selected plan id is the form value. */
+  syncValue(_val) {
+    this.internals.setFormValue(this.value || '');
+  }
+
+  // ── Render — narrow; mutates per-region nodes only ────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const plans = Array.isArray(this.plans) ? this.plans : [];
+
+    // Coerce unknown cycle to monthly (one-shot warn).
+    if (!KNOWN_CYCLES.has(this.cycle)) {
+      if (!this.#warnedCycle) {
+        this.#warnedCycle = true;
+        // eslint-disable-next-line no-console
+        console.warn(`[plan-picker-ui] unknown cycle "${this.cycle}" — coercing to "monthly".`);
+      }
+      this.#internalUpdate = true;
+      try { this.cycle = 'monthly'; } finally { this.#internalUpdate = false; }
+    }
+
+    // Warn on multiple recommended (one-shot).
+    const recommended = plans.filter((p) => p.recommended);
+    if (recommended.length > 1 && !this.#warnedRecommend) {
+      this.#warnedRecommend = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[plan-picker-ui] ${recommended.length} plans carry recommended:true — ` +
+        `using the first ("${recommended[0].id}"); ignoring the rest.`,
+      );
+    }
+    const recommendedId = recommended[0]?.id || '';
+
+    // Empty / non-empty state attribute (CSS-gated reveal).
+    if (plans.length === 0) {
+      this.setAttribute('empty', '');
+    } else {
+      this.removeAttribute('empty');
+    }
+
+    // Toggle visibility / contents.
+    if (this.#toggleHost) {
+      const show = this.cycleToggle && plans.length > 0;
+      this.#toggleHost.hidden = !show;
+      if (show) this.#renderToggle();
+    }
+
+    // Diff plan cards by id.
+    this.#renderCards(plans, recommendedId);
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #absorbInlinePlansScript() {
+    const script = this.querySelector(':scope > script[type="application/json"][data-plans]');
+    if (!script) return;
+    try {
+      const parsed = JSON.parse(script.textContent || '[]');
+      if (Array.isArray(parsed)) this.plans = parsed;
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('[plan-picker-ui] failed to parse <script data-plans> JSON:', err?.message);
+    } finally {
+      script.remove();
+    }
+  }
+
+  #stamp() {
+    // Toggle host — initially hidden; #renderToggle stamps its content
+    // when cycle-toggle is set.
+    const toggle = document.createElement('div');
+    toggle.setAttribute('data-toggle', '');
+    toggle.hidden = true;
+    this.appendChild(toggle);
+    this.#toggleHost = toggle;
+
+    // Plans host — the radiogroup container the option-card-ui kids
+    // live in. We give it role="presentation" because the OUTER host
+    // already carries role="radiogroup" and nesting two radiogroups
+    // would confuse AT.
+    const plansHost = document.createElement('div');
+    plansHost.setAttribute('data-plans', '');
+    plansHost.setAttribute('role', 'presentation');
+    this.appendChild(plansHost);
+    this.#plansHost = plansHost;
+
+    // Skeleton host — placeholder during data-stream loading.
+    const skeleton = document.createElement('div');
+    skeleton.setAttribute('data-skeleton', '');
+    skeleton.hidden = true;
+    this.appendChild(skeleton);
+    this.#skeletonHost = skeleton;
+
+    // Default empty-state — overridable via slot="empty".
+    if (!this.querySelector(':scope > [slot="empty"]')) {
+      const empty = document.createElement('empty-state-ui');
+      empty.setAttribute('data-empty', '');
+      empty.setAttribute('icon', 'package');
+      empty.setAttribute('heading', 'No plans available');
+      empty.setAttribute('description', 'Plans will appear here once configured.');
+      this.appendChild(empty);
+      this.#emptyHost = empty;
+    }
+  }
+
+  #renderToggle() {
+    if (!this.#toggleHost) return;
+    let seg = this.#toggleSegmented;
+    if (!seg) {
+      seg = document.createElement('segmented-ui');
+      seg.setAttribute('aria-label', 'Billing cycle');
+      this.#toggleHost.appendChild(seg);
+      this.#toggleSegmented = seg;
+      // Stamp segments — known cycles in display order.
+      for (const cycleKey of ['monthly', 'annual']) {
+        const s = document.createElement('segment-ui');
+        s.setAttribute('value', cycleKey);
+        s.setAttribute('text', CYCLE_LABELS[cycleKey]);
+        seg.appendChild(s);
+      }
+    }
+    if (seg.value !== this.cycle) {
+      seg.value = this.cycle;
+    }
+  }
+
+  #renderCards(plans, recommendedId) {
+    if (!this.#plansHost) return;
+
+    const next = new Map();
+
+    for (const plan of plans) {
+      if (!plan?.id) continue;
+      let card = this.#cardsById.get(plan.id);
+      if (!card) {
+        card = document.createElement('option-card-ui');
+        card.setAttribute('layout', 'tile');
+        this.#plansHost.appendChild(card);
+      }
+      this.#decorateCard(card, plan, recommendedId);
+      next.set(plan.id, card);
+    }
+
+    // Remove dropped cards (was in #cardsById but not in next).
+    for (const [id, card] of this.#cardsById) {
+      if (!next.has(id)) {
+        try { card.remove(); } catch { /* ignore */ }
+      }
+    }
+
+    // Reorder DOM to match the input array order (in-place move via
+    // appendChild semantics — preserves identity + focus).
+    for (const plan of plans) {
+      const card = next.get(plan.id);
+      if (card) this.#plansHost.appendChild(card);
+    }
+
+    this.#cardsById = next;
+  }
+
+  #decorateCard(card, plan, recommendedId) {
+    // Identity + form wiring.
+    card.setAttribute('name', `${this.name || 'plan'}__${this.id || 'pp'}`);
+    card.setAttribute('value', plan.id);
+
+    // Heading + tagline (the first becomes the option-card heading
+    // attribute, the second its description).
+    card.setAttribute('heading', plan.name || '');
+    card.setAttribute('description', plan.tagline || '');
+    if (plan.icon) card.setAttribute('icon', plan.icon);
+    else card.removeAttribute('icon');
+
+    // State attributes the CSS scope keys off.
+    const isCurrent = !!(this.current && plan.id === this.current);
+    const isRecommended = plan.id === recommendedId;
+    if (isCurrent) card.setAttribute('data-current', '');
+    else card.removeAttribute('data-current');
+    if (isRecommended) card.setAttribute('data-recommended', '');
+    else card.removeAttribute('data-recommended');
+
+    // Plan-disabled state (per-plan); rendered alongside host disabled.
+    if (plan.disabled || this.disabled) card.setAttribute('disabled', '');
+    else card.removeAttribute('disabled');
+
+    // Selection: current plan defaults to checked unless host value
+    // overrides; otherwise the host value chooses.
+    const isChecked =
+      (this.value && this.value === plan.id) ||
+      (!this.value && isCurrent);
+    if (isChecked) card.setAttribute('checked', '');
+    else card.removeAttribute('checked');
+
+    // Stamp the price + features + CTA block as the spillover (default
+    // slot) — option-card-ui shows un-slotted children only when the
+    // card is [checked]; we override that via our own CSS so plan
+    // bodies show always.
+    let body = card.querySelector(':scope > [data-plan-body]');
+    if (!body) {
+      body = document.createElement('div');
+      body.setAttribute('data-plan-body', '');
+      card.appendChild(body);
+    }
+    this.#decorateBody(body, plan);
+
+    // Tags region (recommended / current pill).
+    let tags = card.querySelector(':scope > [data-plan-tags]');
+    if (!tags) {
+      tags = document.createElement('div');
+      tags.setAttribute('data-plan-tags', '');
+      tags.setAttribute('slot', 'heading-suffix');
+      card.appendChild(tags);
+    }
+    tags.replaceChildren();
+    if (isCurrent) {
+      const t = document.createElement('tag-ui');
+      t.setAttribute('text', 'Current plan');
+      // `muted` is not in tag's `variant` enum and matches no rule — the
+      // pill already renders the solid-neutral base pair (gh#794), and a
+      // bare tag renders the same pair, so dropping the call is a
+      // zero-change edit; NB the pill is a solid stamp, not quiet chrome.
+      tags.appendChild(t);
+    } else if (isRecommended) {
+      const t = document.createElement('tag-ui');
+      t.setAttribute('text', 'Recommended');
+      t.setAttribute('variant', 'primary');
+      tags.appendChild(t);
+    }
+  }
+
+  #decorateBody(body, plan) {
+    // Wipe + restamp body (small DOM; cycle / feature-list / cta).
+    body.replaceChildren();
+
+    // Price row.
+    const priceRow = document.createElement('div');
+    priceRow.setAttribute('data-price-row', '');
+    const cycle = KNOWN_CYCLES.has(this.cycle) ? this.cycle : 'monthly';
+    const prices = plan.prices || {};
+    const priceRec = prices[cycle] || prices.monthly || null;
+
+    if (priceRec) {
+      const amountEl = document.createElement('span');
+      amountEl.setAttribute('data-price', '');
+      const currency = priceRec.currency || this.currency || 'USD';
+      amountEl.textContent = formatAmount(priceRec.amount, currency, this.locale);
+      priceRow.appendChild(amountEl);
+
+      const suffix = document.createElement('span');
+      suffix.setAttribute('data-cycle', '');
+      const unit = priceRec.unit ? `/${priceRec.unit}` : CYCLE_SUFFIX[cycle];
+      suffix.textContent = unit;
+      priceRow.appendChild(suffix);
+    } else {
+      const fallback = document.createElement('span');
+      fallback.setAttribute('data-price', '');
+      fallback.textContent = 'Contact sales';
+      priceRow.appendChild(fallback);
+    }
+    body.appendChild(priceRow);
+
+    // Price note (e.g. "billed annually").
+    if (priceRec?.note) {
+      const note = document.createElement('span');
+      note.setAttribute('data-price-note', '');
+      note.textContent = priceRec.note;
+      body.appendChild(note);
+    }
+
+    // Feature list.
+    if (Array.isArray(plan.features) && plan.features.length) {
+      const list = document.createElement('ul');
+      list.setAttribute('data-features', '');
+      for (const feature of plan.features) {
+        const li = document.createElement('li');
+        const icon = document.createElement('icon-ui');
+        icon.setAttribute('name', 'check');
+        icon.setAttribute('aria-hidden', 'true');
+        li.appendChild(icon);
+        const label = document.createElement('span');
+        label.textContent = String(feature);
+        li.appendChild(label);
+        list.appendChild(li);
+      }
+      body.appendChild(list);
+    }
+
+    // CTA button (skipped when this IS the current plan and the plan
+    // record didn't override `cta`).
+    const isCurrent = !!(this.current && plan.id === this.current);
+    if (!isCurrent || plan.cta) {
+      const cta = document.createElement('button-ui');
+      cta.setAttribute('data-cta', '');
+      cta.setAttribute(
+        'variant',
+        plan.recommended ? 'primary' : 'outline',
+      );
+      cta.setAttribute('text', deriveCtaLabel(plan, Array.isArray(this.plans) ? this.plans : [], this.current));
+      if (plan.disabled || this.disabled) cta.setAttribute('disabled', '');
+      body.appendChild(cta);
+    }
+  }
+
+  #wireListeners() {
+    // ── Cycle toggle ──
+    const onCycleChange = (e) => {
+      const cycle = e?.detail?.value;
+      if (!KNOWN_CYCLES.has(cycle)) return;
+      if (this.cycle === cycle) return;
+      e.stopPropagation();
+      const previous = this.cycle;
+      this.cycle = cycle;
+      this.dispatchEvent(new CustomEvent('cycle-change', {
+        bubbles: true,
+        detail: { cycle, previous },
+      }));
+    };
+    this.#toggleHost.addEventListener('change', onCycleChange);
+    this.#cleanups.push(() => this.#toggleHost.removeEventListener('change', onCycleChange));
+
+    // ── Card selection (option-card-ui `change`) ──
+    const onCardChange = (e) => {
+      const target = e.target?.closest?.('option-card-ui');
+      if (!target || !this.#plansHost.contains(target)) return;
+      const planId = target.getAttribute('value') || '';
+      if (!planId) return;
+      const plan = (this.plans || []).find((p) => p.id === planId);
+      if (!plan) return;
+      if (plan.disabled || this.disabled) {
+        // Revert the underlying card and notify.
+        target.removeAttribute('checked');
+        this.dispatchEvent(new CustomEvent('error', {
+          bubbles: true,
+          detail: { reason: 'plan-disabled' },
+        }));
+        return;
+      }
+      e.stopPropagation();
+      const previous = this.value || '';
+      if (previous === planId) return;
+      this.#internalUpdate = true;
+      try { this.value = planId; } finally { this.#internalUpdate = false; }
+      this.syncValue();
+      this.#emitChange(planId, previous);
+    };
+    this.#plansHost.addEventListener('change', onCardChange);
+    this.#cleanups.push(() => this.#plansHost.removeEventListener('change', onCardChange));
+
+    // ── CTA click / press → `select` ──
+    const onCtaPress = (e) => {
+      const cta = e.target?.closest?.('button-ui[data-cta]');
+      if (!cta || !this.#plansHost.contains(cta)) return;
+      const card = cta.closest('option-card-ui');
+      if (!card) return;
+      const planId = card.getAttribute('value') || '';
+      if (!planId) return;
+      const plan = (this.plans || []).find((p) => p.id === planId);
+      if (!plan || plan.disabled || this.disabled) return;
+      e.stopPropagation();
+      // Selecting the plan on CTA press is part of the commit
+      // (otherwise users can click an unselected card's CTA and the
+      // value doesn't update). Mirror option-card-ui's keyboard model.
+      const previous = this.value || '';
+      if (previous !== planId) {
+        this.#internalUpdate = true;
+        try { this.value = planId; } finally { this.#internalUpdate = false; }
+        this.syncValue();
+        this.#emitChange(planId, previous);
+      }
+      this.dispatchEvent(new CustomEvent('select', {
+        bubbles: true,
+        detail: { value: planId, cycle: this.cycle },
+      }));
+    };
+    // Listen for both `press` (button-ui's custom event) and `click`
+    // (covers default-button activation paths in happy-dom).
+    this.#plansHost.addEventListener('press', onCtaPress);
+    this.#plansHost.addEventListener('click', onCtaPress);
+    this.#cleanups.push(() => this.#plansHost.removeEventListener('press', onCtaPress));
+    this.#cleanups.push(() => this.#plansHost.removeEventListener('click', onCtaPress));
+  }
+
+  #emitChange(value, previous) {
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value, previous, cycle: this.cycle },
+    }));
+  }
+}