@adia-ai/web-modules 0.8.36 → 0.8.38

package/billing/plan-picker/plan-picker.css

@@ -0,0 +1,227 @@
+/* ═══════════════════════════════════════════════════════════════
+   <plan-picker-ui> — Form-participating chooser of one of N plans.
+
+   Composite over <option-card-ui> + <segmented-ui> + <segment-ui> +
+   <tag-ui> + <button-ui> + <icon-ui> + <empty-state-ui>. The host is
+   a column that lays out the toggle row · plans grid · skeleton ·
+   empty-state regions in DOM order. Each plan card is an
+   <option-card-ui> decorated with a price block, feature list, and
+   CTA via per-region L3 tokens.
+
+   SPEC: docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.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 ───────────────────────────────── */
+
+plan-picker-ui {
+  --plan-picker-bg:                       transparent;
+  --plan-picker-grid-gap:                 var(--a-space-4);
+  --plan-picker-grid-min:                 16rem;
+
+  --plan-picker-card-bg:                  var(--md-sys-color-neutral-background);
+  --plan-picker-card-bg-recommended:      var(--md-sys-color-primary-container);
+  --plan-picker-card-bg-current:          var(--a-bg-muted);
+  --plan-picker-card-border:              1px solid var(--md-sys-color-neutral-outline);
+  --plan-picker-card-border-recommended:  2px solid var(--md-sys-color-primary);
+  --plan-picker-card-radius:              var(--a-radius-lg);
+  --plan-picker-card-py:                  var(--a-space-5);
+  --plan-picker-card-px:                  var(--a-space-5);
+  --plan-picker-card-shadow-recommended:  var(--a-shadow-md);
+
+  --plan-picker-price-size:               var(--a-text-3xl, 1.875rem);
+  --plan-picker-price-fg:                 var(--a-fg-strong, var(--md-sys-color-neutral-on-surface));
+  --plan-picker-cycle-fg:                 var(--a-fg-muted);
+
+  --plan-picker-features-gap:             var(--a-space-2);
+  --plan-picker-feature-icon-fg:          var(--md-sys-color-primary);
+
+  --plan-picker-toggle-justify:           center;
+
+  --plan-picker-disabled-opacity:         var(--a-opacity-disabled, 0.5);
+}
+
+/* ── Block 2: SCOPED LAYOUT ────────────────────────────────────── */
+
+@scope (plan-picker-ui) {
+
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-4);
+    background: var(--plan-picker-bg);
+  }
+
+  /* ── Toggle row ── */
+  :scope > [data-toggle] {
+    display: flex;
+    justify-content: var(--plan-picker-toggle-justify);
+  }
+  :scope > [data-toggle][hidden] {
+    display: none;
+  }
+
+  /* ── Plans grid ── */
+  :scope > [data-plans] {
+    display: grid;
+    grid-template-columns: repeat(
+      auto-fit,
+      minmax(var(--plan-picker-grid-min), 1fr)
+    );
+    gap: var(--plan-picker-grid-gap);
+    align-items: stretch;
+  }
+
+  /* List layout — single-column rows for in-app settings. */
+  :scope[layout="list"] > [data-plans] {
+    grid-template-columns: 1fr;
+  }
+
+  /* ── Per-card cascades into option-card-ui L3 tokens ── */
+  :scope > [data-plans] > option-card-ui {
+    --option-card-bg:               var(--plan-picker-card-bg);
+    --option-card-border:           var(--plan-picker-card-border);
+    --option-card-radius:           var(--plan-picker-card-radius);
+    --option-card-padding-block:    var(--plan-picker-card-py);
+    --option-card-padding-inline:   var(--plan-picker-card-px);
+    box-sizing: border-box;
+    /* Equal-height cards across the auto-fit row (the grid sets
+       align-items:stretch); option-card[layout="tile"] supplies the flex
+       column, so we must NOT override its display here — doing so strands
+       the radio indicator in a collapsed 8px grid gutter. */
+    height: 100%;
+  }
+
+  :scope > [data-plans] > option-card-ui[data-recommended] {
+    --option-card-bg:     var(--plan-picker-card-bg-recommended);
+    --option-card-border: var(--plan-picker-card-border-recommended);
+    box-shadow: var(--plan-picker-card-shadow-recommended);
+  }
+
+  :scope > [data-plans] > option-card-ui[data-current] {
+    --option-card-bg:     var(--plan-picker-card-bg-current);
+  }
+
+  /* ── Plan body — price + features + CTA, REVEALED ALWAYS.
+        option-card-ui hides default-slot children unless [checked],
+        but plan cards must show their content regardless. We override
+        with the same `:not([slot])` selector option-card uses
+        internally, scoped to our [data-plan-body] children. flex:1 lets
+        the body absorb the card's free height so the CTA (margin-top:auto
+        below) anchors to the bottom edge — CTAs align across a row of
+        cards with uneven feature lists. ── */
+  :scope > [data-plans] > option-card-ui > [data-plan-body] {
+    flex: 1;
+    display: flex !important;
+    flex-direction: column;
+    gap: var(--a-space-3);
+  }
+
+  /* Recommended / current pill — a standalone tag at the card's top-left
+     (the tile radio sits top-right). order:0 default keeps it ahead of the
+     order:2 heading regardless of DOM position. */
+  :scope > [data-plans] > option-card-ui > [data-plan-tags] {
+    display: flex;
+    align-self: start;
+    align-items: center;
+    gap: var(--a-space-1);
+  }
+  :scope > [data-plans] > option-card-ui > [data-plan-tags]:empty {
+    display: none;
+  }
+
+  /* ── Price row ── */
+  :scope [data-price-row] {
+    display: flex;
+    align-items: baseline;
+    gap: var(--a-space-1);
+  }
+  :scope [data-price] {
+    font-size: var(--plan-picker-price-size);
+    color: var(--plan-picker-price-fg);
+    font-weight: var(--a-weight-bold, 700);
+    line-height: 1;
+  }
+  :scope [data-cycle] {
+    font-size: var(--a-text-sm, 0.875rem);
+    color: var(--plan-picker-cycle-fg);
+  }
+  :scope [data-price-note] {
+    font-size: var(--a-text-xs, 0.75rem);
+    color: var(--plan-picker-cycle-fg);
+  }
+
+  /* ── Features list ── */
+  :scope ul[data-features] {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--plan-picker-features-gap);
+  }
+  :scope ul[data-features] > li {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--a-space-2);
+    /* Override the docs feature-list indent (site.css adds
+       `padding-left: 24px` + a ::before checkmark to ul[data-features] li);
+       the slotted <icon-ui> IS our bullet, so the row aligns flush-left. */
+    padding-inline-start: 0;
+    color: var(--md-sys-color-neutral-on-surface);
+    font-size: var(--a-text-sm, 0.875rem);
+    line-height: 1.4;
+  }
+  :scope ul[data-features] > li > icon-ui {
+    flex-shrink: 0;
+    color: var(--plan-picker-feature-icon-fg);
+    --a-icon-size: 1rem;
+    margin-block-start: 0.125rem;
+  }
+  /* The feature check is the slotted <icon-ui>. Suppress any inherited
+     ::before checkmark (the docs admin-page feature-list style adds a green
+     "✓" to every ul[data-features] li) so the bullet doesn't double up. */
+  :scope ul[data-features] > li::before {
+    content: none;
+  }
+
+  /* ── CTA button — full-width, anchored to the body's bottom edge so a
+        row of cards keeps their CTAs aligned regardless of feature count. ── */
+  :scope button-ui[data-cta] {
+    width: 100%;
+    margin-block-start: auto;
+  }
+
+  /* ── Empty state ── gated by [empty] attribute.
+     Hide [data-empty] when host is NOT empty; do NOT set a display
+     value when shown (would clobber empty-state-ui's flex layout). */
+  :scope:not([empty]) > [data-empty] {
+    display: none;
+  }
+  :scope[empty] > [data-plans] {
+    display: none;
+  }
+
+  /* ── Loading skeleton ── */
+  :scope > [data-skeleton] {
+    display: none;
+  }
+  :scope[loading] > [data-skeleton] {
+    display: grid;
+    grid-template-columns: repeat(
+      auto-fit,
+      minmax(var(--plan-picker-grid-min), 1fr)
+    );
+    gap: var(--plan-picker-grid-gap);
+  }
+  :scope[loading] > [data-plans] {
+    visibility: hidden;
+  }
+
+  /* ── Disabled state ── */
+  :scope[disabled] {
+    opacity: var(--plan-picker-disabled-opacity);
+    pointer-events: none;
+  }
+}

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

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

package/billing/plan-picker/plan-picker.yaml

@@ -0,0 +1,453 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: PlanPicker
+tag: plan-picker-ui
+status: experimental
+component: PlanPicker
+category: input
+version: 1
+description: |
+  A form-participating chooser of one of N billing plans. The canonical
+  plan-card grid used by both in-app upgrade modals and marketing
+  pricing pages (SPEC-012 composes this primitive as its core), so
+  benefit copy, pricing strings, recommendation highlighting, and the
+  billing-cycle toggle never drift between surfaces.
+
+  Each plan record carries a stable id, name, optional tagline + icon,
+  a per-cycle price object, a feature list, and optional flags
+  (recommended, rank, disabled). One plan may carry recommended:true
+  (accent border + tinted bg + shadow); a host-level `current` id
+  marks the user's current plan (muted bg, "Current plan" tag, no
+  Choose CTA, contextual "Upgrade"/"Downgrade" labels on siblings).
+
+  Layout is grid by default (marketing surfaces) and `layout="list"`
+  for in-app settings panels. The optional `cycle-toggle` boolean
+  renders an internal <segmented-ui> that swaps prices between
+  monthly and annual cycles in place across every card.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.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:
+  - option-card-ui
+  - segmented-ui
+  - segment-ui
+  - button-ui
+  - icon-ui
+  - text-ui
+  - tag-ui
+  - empty-state-ui
+
+props:
+  plans:
+    description: |
+      Array of plan records. Source of truth for the rendered cards.
+      Shape per record: {id, name, tagline?, prices: {monthly: {amount,
+      currency?, unit?, note?}, annual?: {...}}, features?: string[],
+      cta?: string, recommended?: boolean, rank?: number, icon?: string,
+      disabled?: boolean}. Empty array renders the empty-state.
+    type: array
+    default: []
+    dynamic: true
+    required: true
+
+  value:
+    description: |
+      Currently selected plan id (form value). Read-write — both the
+      form submission key and the [checked] gate on the matching
+      <option-card-ui>.
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+  current:
+    description: |
+      Id of the user's CURRENT plan. When set, that card renders with
+      a muted background, a "Current plan" <tag-ui>, and either no CTA
+      or a "Manage" CTA. Other plans receive contextual upgrade /
+      downgrade CTA labels derived from rank. Unknown ids fail
+      silently (no anchor row).
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+  name:
+    description: |
+      Form field name for the selected plan id. Mirrors UIFormElement
+      conventions; serialized via ElementInternals.
+    type: string
+    default: ""
+    reflect: true
+
+  cycle:
+    description: |
+      Active billing cycle. Drives which `plans[].prices[cycle]` value
+      renders across every card simultaneously. Toggle via the in-host
+      `cycle-toggle` (when set) or programmatically via setCycle().
+    type: string
+    default: "monthly"
+    enum:
+      - monthly
+      - annual
+    reflect: true
+    dynamic: true
+
+  cycle-toggle:
+    description: |
+      When set, the primitive renders an internal <segmented-ui> with
+      Monthly / Annual options above the plan grid. When unset, the
+      consumer drives [cycle] externally (e.g. from a parent toolbar).
+    type: boolean
+    default: false
+    reflect: true
+    attribute: cycle-toggle
+
+  currency:
+    description: |
+      Default ISO 4217 currency code for price rendering. Overridable
+      per-price via plans[].prices[cycle].currency.
+    type: string
+    default: "USD"
+
+  locale:
+    description: |
+      Locale for Intl.NumberFormat (price) and cycle labels. Defaults
+      to document.documentElement.lang (or "en-US" when absent).
+    type: string
+    default: ""
+
+  layout:
+    description: |
+      Card layout. `grid` (auto-fit columns, minimum 16rem) for
+      marketing surfaces. `list` (single column rows) for in-app
+      settings panels.
+    type: string
+    default: "grid"
+    enum:
+      - grid
+      - list
+    reflect: true
+
+  disabled:
+    description: Block all interaction across the picker.
+    type: boolean
+    default: false
+    reflect: true
+
+  data-stream-src:
+    description: |
+      Optional endpoint returning the `plans` array (universal
+      data-stream-* trait). On successful load, `plans` is replaced
+      and a `load` event fires; on failure an `error` event fires.
+    type: string
+    default: ""
+    attribute: data-stream-src
+
+events:
+  change:
+    description: |
+      Fired when the selected plan id changes — either via user click
+      or programmatic value set. Bubbles.
+    detail:
+      value:
+        type: string
+        description: New plan id.
+      previous:
+        type: string
+        description: Previous plan id (empty string when none).
+      cycle:
+        type: string
+        description: Active billing cycle.
+
+  cycle-change:
+    description: |
+      Fired when the active billing cycle changes (cycle-toggle
+      click or programmatic setCycle). Bubbles.
+    detail:
+      cycle:
+        type: string
+        description: New cycle.
+        enum:
+          - monthly
+          - annual
+      previous:
+        type: string
+        description: Previous cycle.
+
+  select:
+    description: |
+      Fired when the user activates a plan's CTA button — the
+      committing action that consumers wire to a checkout / upgrade
+      flow. Distinct from `change` (selection without commit). Bubbles.
+    detail:
+      value:
+        type: string
+        description: Plan id being committed.
+      cycle:
+        type: string
+        description: Active billing cycle at commit.
+
+  load:
+    description: |
+      Fired when `data-stream-src` finishes a successful fetch and
+      `plans` is populated. Bubbles.
+    detail:
+      count:
+        type: integer
+        description: Number of plans loaded.
+
+  error:
+    description: |
+      Fired when a `data-stream-src` fetch fails OR when a user tries
+      to select a `disabled: true` plan. Bubbles.
+    detail:
+      reason:
+        type: string
+        description: One of `fetch-failed`, `plan-disabled`.
+
+slots:
+  header:
+    description: |
+      Optional content above the plan grid (e.g. a <header> with a
+      title and a custom cycle toggle). When absent and
+      `cycle-toggle` is set, the primitive stamps its own toggle.
+
+  footer:
+    description: |
+      Optional content below the plan grid (compare-plans link, FAQ,
+      fine print).
+
+  empty:
+    description: |
+      Custom empty-state shown when `plans` is empty. Falls back to a
+      default <empty-state-ui> when not provided.
+
+states:
+  - name: idle
+    description: Default — plans rendered, ready for interaction.
+  - name: loading
+    description: A `data-stream-src` fetch is in flight.
+    attribute: loading
+  - name: empty
+    description: No plans to render.
+    attribute: empty
+  - name: error
+    description: Last `data-stream-src` fetch failed.
+    attribute: error
+  - name: disabled
+    description: All cards non-interactive.
+    attribute: disabled
+
+traits:
+  - focusable
+
+tokens:
+  --plan-picker-bg:
+    description: Host background. Defaults to transparent.
+    default: transparent
+  --plan-picker-grid-gap:
+    description: Gap between plan cards in grid layout.
+    default: var(--a-space-4)
+  --plan-picker-grid-min:
+    description: Minimum column width in auto-fit grid.
+    default: 16rem
+  --plan-picker-card-bg:
+    description: Card background (cascades to option-card --option-card-bg).
+    default: var(--a-bg)
+  --plan-picker-card-bg-recommended:
+    description: Recommended-card background.
+    default: var(--md-sys-color-primary-container)
+  --plan-picker-card-bg-current:
+    description: Current-plan card background.
+    default: var(--a-bg-muted)
+  --plan-picker-card-border:
+    description: Default card border.
+    default: 1px solid var(--a-border)
+  --plan-picker-card-border-recommended:
+    description: Recommended-card accent border.
+    default: 2px solid var(--md-sys-color-primary)
+  --plan-picker-card-radius:
+    description: Card corner radius.
+    default: var(--a-radius-lg)
+  --plan-picker-card-py:
+    description: Card vertical padding.
+    default: var(--a-space-5)
+  --plan-picker-card-px:
+    description: Card horizontal padding.
+    default: var(--a-space-5)
+  --plan-picker-card-shadow-recommended:
+    description: Shadow elevation on the recommended card.
+    default: var(--a-shadow-md)
+  --plan-picker-price-size:
+    description: Price font size.
+    default: var(--a-text-3xl, 1.875rem)
+  --plan-picker-price-fg:
+    description: Price color.
+    default: var(--a-fg-strong, var(--a-fg))
+  --plan-picker-cycle-fg:
+    description: "Per-unit / cycle suffix color (e.g. \"/month\")."
+    default: var(--a-fg-muted)
+  --plan-picker-features-gap:
+    description: Gap between feature list rows.
+    default: var(--a-space-2)
+  --plan-picker-feature-icon-fg:
+    description: Feature-row check icon color.
+    default: var(--md-sys-color-primary)
+  --plan-picker-toggle-justify:
+    description: |
+      Justification of the internal cycle toggle row. `center` for
+      marketing layouts; `start` for in-app settings panels.
+    default: center
+
+requiredIcons:
+  - check
+  - package
+
+a2ui:
+  rules:
+    - >-
+      PlanPicker.plans MUST be a non-empty array on commit. Empty
+      arrays render the empty-state but cannot be the submission
+      state.
+    - >-
+      At most ONE plans[] record may carry `recommended: true`. Two
+      recommended plans are visually ambiguous and defeat the
+      treatment's purpose.
+    - >-
+      `current` MUST match a plans[].id or be empty. Unknown ids
+      fail silently — no anchor row renders, no current-state
+      contextualization on siblings.
+    - >-
+      plans[].prices.monthly is REQUIRED on every record. annual is
+      optional; if absent and cycle="annual" the card renders the
+      monthly price with the annual cycle suffix and no `note`.
+    - >-
+      `cycle` MUST be `monthly` or `annual`. Other values are
+      coerced to `monthly` and a one-shot console.warn fires.
+    - >-
+      Use `layout="list"` for in-app settings panels where the picker
+      sits inside a <card-ui> and width is constrained. Use the
+      default `layout="grid"` for marketing pricing pages.
+    - >-
+      Wire `select` (not `change`) to the actual commit handler —
+      change fires on selection without commit (keyboard focus
+      traversal, programmatic value-set); select fires when the user
+      clicks the CTA inside a card.
+
+anti_patterns:
+  - wrong: |
+      <plan-picker-ui plans='[
+        {"id":"p1","name":"Free","price":0},
+        {"id":"p2","name":"Pro","price":20}
+      ]'></plan-picker-ui>
+    why: |
+      `price` is a top-level shortcut not in the schema. Prices are
+      keyed by cycle (monthly / annual). Without a cycle key, the
+      cycle toggle has nothing to switch and annual pricing is
+      invisible to consumers.
+    fix: |
+      <plan-picker-ui plans='[
+        {"id":"p1","name":"Free","prices":{"monthly":{"amount":0}}},
+        {"id":"p2","name":"Pro","prices":{"monthly":{"amount":20}}}
+      ]'></plan-picker-ui>
+  - wrong: |
+      <plan-picker-ui plans='[
+        {"id":"t","name":"Team","recommended":true,"prices":{"monthly":{"amount":10}}},
+        {"id":"p","name":"Pro","recommended":true,"prices":{"monthly":{"amount":20}}}
+      ]'></plan-picker-ui>
+    why: |
+      Two recommended plans cancel each other visually — there is no
+      "the" recommendation. Pick one.
+    fix: |
+      <plan-picker-ui plans='[
+        {"id":"t","name":"Team","prices":{"monthly":{"amount":10}}},
+        {"id":"p","name":"Pro","recommended":true,"prices":{"monthly":{"amount":20}}}
+      ]'></plan-picker-ui>
+  - wrong: |
+      A <col-ui> of bespoke <card-ui> plan cards with manual radio
+      markup and a per-plan cycle pill.
+    why: |
+      Reinvents the radiogroup keyboard model and the cycle-toggle
+      semantics; pricing strings drift between this surface and the
+      marketing pricing page that uses the canonical primitive.
+    fix: |
+      <plan-picker-ui plans="..." cycle-toggle></plan-picker-ui>
+
+examples:
+  - name: in-app-upgrade
+    description: In-app upgrade modal with three plans + annual default + cycle toggle.
+    a2ui: |
+      [
+        {
+          "id": "pp-upgrade",
+          "component": "PlanPicker",
+          "name": "plan",
+          "current": "plan_team",
+          "cycle": "annual",
+          "cycleToggle": true,
+          "plans": [
+            {"id":"plan_free","name":"Free","prices":{"monthly":{"amount":0}},"features":["3 projects","Community support"],"rank":1},
+            {"id":"plan_team","name":"Team","prices":{"monthly":{"amount":10,"unit":"seat"},"annual":{"amount":8,"unit":"seat","note":"billed annually"}},"features":["Unlimited projects","Email support"],"rank":2},
+            {"id":"plan_pro","name":"Pro","prices":{"monthly":{"amount":25,"unit":"seat"},"annual":{"amount":20,"unit":"seat","note":"billed annually"}},"features":["Everything in Team","Priority support"],"recommended":true,"rank":3}
+          ]
+        }
+      ]
+  - name: settings-list
+    description: Settings-page plan picker — single-column list inside a card.
+    a2ui: |
+      [
+        {
+          "id": "pp-settings",
+          "component": "PlanPicker",
+          "name": "plan",
+          "current": "plan_team",
+          "layout": "list",
+          "plans": [
+            {"id":"plan_team","name":"Team","prices":{"monthly":{"amount":10,"unit":"seat"}},"features":["Unlimited projects"],"rank":2},
+            {"id":"plan_pro","name":"Pro","prices":{"monthly":{"amount":25,"unit":"seat"}},"features":["Everything in Team","Priority support"],"recommended":true,"rank":3}
+          ]
+        }
+      ]
+
+keywords:
+  - plan-picker
+  - plans
+  - pricing
+  - upgrade
+  - billing
+  - tier
+  - tiers
+  - subscription
+  - subscribe
+  - paywall
+  - choose-plan
+  - select-plan
+  - plan-selection
+
+synonyms:
+  plan:
+    - tier
+    - subscription
+    - package
+  pricing:
+    - plan
+    - price
+    - tier
+  upgrade:
+    - plan-change
+    - subscribe
+    - choose-plan
+
+related:
+  - OptionCard
+  - Segmented
+  - Segment
+  - Tag
+  - Button
+  - Card
+  - EmptyState
+  - Skeleton