@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/plan-picker/plan-picker.a2ui.json

@@ -0,0 +1,349 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/PlanPicker.json",
+  "title": "PlanPicker",
+  "description": "A form-participating chooser of one of N billing plans. The canonical\nplan-card grid used by both in-app upgrade modals and marketing\npricing pages (SPEC-012 composes this primitive as its core), so\nbenefit copy, pricing strings, recommendation highlighting, and the\nbilling-cycle toggle never drift between surfaces.\n\nEach plan record carries a stable id, name, optional tagline + icon,\na per-cycle price object, a feature list, and optional flags\n(recommended, rank, disabled). One plan may carry recommended:true\n(accent border + tinted bg + shadow); a host-level `current` id\nmarks the user's current plan (muted bg, \"Current plan\" tag, no\nChoose CTA, contextual \"Upgrade\"/\"Downgrade\" labels on siblings).\n\nLayout is grid by default (marketing surfaces) and `layout=\"list\"`\nfor in-app settings panels. The optional `cycle-toggle` boolean\nrenders an internal <segmented-ui> that swaps prices between\nmonthly and annual cycles in place across every card.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "PlanPicker"
+    },
+    "currency": {
+      "description": "Default ISO 4217 currency code for price rendering. Overridable\nper-price via plans[].prices[cycle].currency.\n",
+      "type": "string",
+      "default": "USD"
+    },
+    "current": {
+      "description": "Id of the user's CURRENT plan. When set, that card renders with\na muted background, a \"Current plan\" <tag-ui>, and either no CTA\nor a \"Manage\" CTA. Other plans receive contextual upgrade /\ndowngrade CTA labels derived from rank. Unknown ids fail\nsilently (no anchor row).\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "cycle": {
+      "description": "Active billing cycle. Drives which `plans[].prices[cycle]` value\nrenders across every card simultaneously. Toggle via the in-host\n`cycle-toggle` (when set) or programmatically via setCycle().\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "cycle-toggle": {
+      "description": "When set, the primitive renders an internal <segmented-ui> with\nMonthly / Annual options above the plan grid. When unset, the\nconsumer drives [cycle] externally (e.g. from a parent toolbar).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "data-stream-src": {
+      "description": "Optional endpoint returning the `plans` array (universal\ndata-stream-* trait). On successful load, `plans` is replaced\nand a `load` event fires; on failure an `error` event fires.\n",
+      "type": "string",
+      "default": ""
+    },
+    "disabled": {
+      "description": "Block all interaction across the picker.",
+      "type": "boolean",
+      "default": false
+    },
+    "layout": {
+      "description": "Card layout. `grid` (auto-fit columns, minimum 16rem) for\nmarketing surfaces. `list` (single column rows) for in-app\nsettings panels.\n",
+      "type": "string",
+      "enum": [
+        "grid",
+        "list"
+      ],
+      "default": "grid"
+    },
+    "locale": {
+      "description": "Locale for Intl.NumberFormat (price) and cycle labels. Defaults\nto document.documentElement.lang (or \"en-US\" when absent).\n",
+      "type": "string",
+      "default": ""
+    },
+    "name": {
+      "description": "Form field name for the selected plan id. Mirrors UIFormElement\nconventions; serialized via ElementInternals.\n",
+      "type": "string",
+      "default": ""
+    },
+    "plans": {
+      "description": "Array of plan records. Source of truth for the rendered cards.\nShape per record: {id, name, tagline?, prices: {monthly: {amount,\ncurrency?, unit?, note?}, annual?: {...}}, features?: string[],\ncta?: string, recommended?: boolean, rank?: number, icon?: string,\ndisabled?: boolean}. Empty array renders the empty-state.\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "value": {
+      "description": "Currently selected plan id (form value). Read-write — both the\nform submission key and the [checked] gate on the matching\n<option-card-ui>.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component",
+    "plans"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<plan-picker-ui plans='[\n  {\"id\":\"p1\",\"name\":\"Free\",\"prices\":{\"monthly\":{\"amount\":0}}},\n  {\"id\":\"p2\",\"name\":\"Pro\",\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n",
+        "why": "`price` is a top-level shortcut not in the schema. Prices are\nkeyed by cycle (monthly / annual). Without a cycle key, the\ncycle toggle has nothing to switch and annual pricing is\ninvisible to consumers.\n",
+        "wrong": "<plan-picker-ui plans='[\n  {\"id\":\"p1\",\"name\":\"Free\",\"price\":0},\n  {\"id\":\"p2\",\"name\":\"Pro\",\"price\":20}\n]'></plan-picker-ui>\n"
+      },
+      {
+        "fix": "<plan-picker-ui plans='[\n  {\"id\":\"t\",\"name\":\"Team\",\"prices\":{\"monthly\":{\"amount\":10}}},\n  {\"id\":\"p\",\"name\":\"Pro\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n",
+        "why": "Two recommended plans cancel each other visually — there is no\n\"the\" recommendation. Pick one.\n",
+        "wrong": "<plan-picker-ui plans='[\n  {\"id\":\"t\",\"name\":\"Team\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":10}}},\n  {\"id\":\"p\",\"name\":\"Pro\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n"
+      },
+      {
+        "fix": "<plan-picker-ui plans=\"...\" cycle-toggle></plan-picker-ui>\n",
+        "why": "Reinvents the radiogroup keyboard model and the cycle-toggle\nsemantics; pricing strings drift between this surface and the\nmarketing pricing page that uses the canonical primitive.\n",
+        "wrong": "A <col-ui> of bespoke <card-ui> plan cards with manual radio\nmarkup and a per-plan cycle pill.\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "option-card-ui",
+      "segmented-ui",
+      "segment-ui",
+      "button-ui",
+      "icon-ui",
+      "text-ui",
+      "tag-ui",
+      "empty-state-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired when the selected plan id changes — either via user click\nor programmatic value set. Bubbles.\n",
+        "detail": {
+          "cycle": {
+            "description": "Active billing cycle.",
+            "type": "string"
+          },
+          "previous": {
+            "description": "Previous plan id (empty string when none).",
+            "type": "string"
+          },
+          "value": {
+            "description": "New plan id.",
+            "type": "string"
+          }
+        }
+      },
+      "cycle-change": {
+        "description": "Fired when the active billing cycle changes (cycle-toggle\nclick or programmatic setCycle). Bubbles.\n",
+        "detail": {
+          "cycle": {
+            "description": "New cycle.",
+            "type": "string",
+            "enum": [
+              "monthly",
+              "annual"
+            ]
+          },
+          "previous": {
+            "description": "Previous cycle.",
+            "type": "string"
+          }
+        }
+      },
+      "error": {
+        "description": "Fired when a `data-stream-src` fetch fails OR when a user tries\nto select a `disabled: true` plan. Bubbles.\n",
+        "detail": {
+          "reason": {
+            "description": "One of `fetch-failed`, `plan-disabled`.",
+            "type": "string"
+          }
+        }
+      },
+      "load": {
+        "description": "Fired when `data-stream-src` finishes a successful fetch and\n`plans` is populated. Bubbles.\n",
+        "detail": {
+          "count": {
+            "description": "Number of plans loaded.",
+            "type": "integer"
+          }
+        }
+      },
+      "select": {
+        "description": "Fired when the user activates a plan's CTA button — the\ncommitting action that consumers wire to a checkout / upgrade\nflow. Distinct from `change` (selection without commit). Bubbles.\n",
+        "detail": {
+          "cycle": {
+            "description": "Active billing cycle at commit.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Plan id being committed.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "In-app upgrade modal with three plans + annual default + cycle toggle.",
+        "a2ui": "[\n  {\n    \"id\": \"pp-upgrade\",\n    \"component\": \"PlanPicker\",\n    \"name\": \"plan\",\n    \"current\": \"plan_team\",\n    \"cycle\": \"annual\",\n    \"cycleToggle\": true,\n    \"plans\": [\n      {\"id\":\"plan_free\",\"name\":\"Free\",\"prices\":{\"monthly\":{\"amount\":0}},\"features\":[\"3 projects\",\"Community support\"],\"rank\":1},\n      {\"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},\n      {\"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}\n    ]\n  }\n]\n",
+        "name": "in-app-upgrade"
+      },
+      {
+        "description": "Settings-page plan picker — single-column list inside a card.",
+        "a2ui": "[\n  {\n    \"id\": \"pp-settings\",\n    \"component\": \"PlanPicker\",\n    \"name\": \"plan\",\n    \"current\": \"plan_team\",\n    \"layout\": \"list\",\n    \"plans\": [\n      {\"id\":\"plan_team\",\"name\":\"Team\",\"prices\":{\"monthly\":{\"amount\":10,\"unit\":\"seat\"}},\"features\":[\"Unlimited projects\"],\"rank\":2},\n      {\"id\":\"plan_pro\",\"name\":\"Pro\",\"prices\":{\"monthly\":{\"amount\":25,\"unit\":\"seat\"}},\"features\":[\"Everything in Team\",\"Priority support\"],\"recommended\":true,\"rank\":3}\n    ]\n  }\n]\n",
+        "name": "settings-list"
+      }
+    ],
+    "keywords": [
+      "plan-picker",
+      "plans",
+      "pricing",
+      "upgrade",
+      "billing",
+      "tier",
+      "tiers",
+      "subscription",
+      "subscribe",
+      "paywall",
+      "choose-plan",
+      "select-plan",
+      "plan-selection"
+    ],
+    "name": "PlanPicker",
+    "related": [
+      "OptionCard",
+      "Segmented",
+      "Segment",
+      "Tag",
+      "Button",
+      "Card",
+      "EmptyState",
+      "Skeleton"
+    ],
+    "slots": {
+      "empty": {
+        "description": "Custom empty-state shown when `plans` is empty. Falls back to a\ndefault <empty-state-ui> when not provided.\n"
+      },
+      "footer": {
+        "description": "Optional content below the plan grid (compare-plans link, FAQ,\nfine print).\n"
+      },
+      "header": {
+        "description": "Optional content above the plan grid (e.g. a <header> with a\ntitle and a custom cycle toggle). When absent and\n`cycle-toggle` is set, the primitive stamps its own toggle.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — plans rendered, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "A `data-stream-src` fetch is in flight.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "No plans to render.",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "Last `data-stream-src` fetch failed.",
+        "attribute": "error",
+        "name": "error"
+      },
+      {
+        "description": "All cards non-interactive.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "plan": [
+        "tier",
+        "subscription",
+        "package"
+      ],
+      "pricing": [
+        "plan",
+        "price",
+        "tier"
+      ],
+      "upgrade": [
+        "plan-change",
+        "subscribe",
+        "choose-plan"
+      ]
+    },
+    "tag": "plan-picker-ui",
+    "tokens": {
+      "--plan-picker-bg": {
+        "description": "Host background. Defaults to transparent.",
+        "default": "transparent"
+      },
+      "--plan-picker-card-bg": {
+        "description": "Card background (cascades to option-card --option-card-bg).",
+        "default": "var(--a-bg)"
+      },
+      "--plan-picker-card-bg-current": {
+        "description": "Current-plan card background.",
+        "default": "var(--a-bg-muted)"
+      },
+      "--plan-picker-card-bg-recommended": {
+        "description": "Recommended-card background.",
+        "default": "var(--md-sys-color-primary-container)"
+      },
+      "--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-px": {
+        "description": "Card horizontal padding.",
+        "default": "var(--a-space-5)"
+      },
+      "--plan-picker-card-py": {
+        "description": "Card vertical padding.",
+        "default": "var(--a-space-5)"
+      },
+      "--plan-picker-card-radius": {
+        "description": "Card corner radius.",
+        "default": "var(--a-radius-lg)"
+      },
+      "--plan-picker-card-shadow-recommended": {
+        "description": "Shadow elevation on the recommended card.",
+        "default": "var(--a-shadow-md)"
+      },
+      "--plan-picker-cycle-fg": {
+        "description": "Per-unit / cycle suffix color (e.g. \"/month\").",
+        "default": "var(--a-fg-muted)"
+      },
+      "--plan-picker-feature-icon-fg": {
+        "description": "Feature-row check icon color.",
+        "default": "var(--md-sys-color-primary)"
+      },
+      "--plan-picker-features-gap": {
+        "description": "Gap between feature list rows.",
+        "default": "var(--a-space-2)"
+      },
+      "--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-price-fg": {
+        "description": "Price color.",
+        "default": "var(--a-fg-strong, var(--a-fg))"
+      },
+      "--plan-picker-price-size": {
+        "description": "Price font size.",
+        "default": "var(--a-text-3xl, 1.875rem)"
+      },
+      "--plan-picker-toggle-justify": {
+        "description": "Justification of the internal cycle toggle row. `center` for\nmarketing layouts; `start` for in-app settings panels.\n",
+        "default": "center"
+      }
+    },
+    "traits": [
+      "focusable"
+    ],
+    "version": 1
+  }
+}