@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScPlanCard.md

@@ -0,0 +1,302 @@
+---
+component: ScPlanCard
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [plan, pricing, tile, upgrade, subscription, stripe, credits, billing, free, pro, enterprise]
+related: [ScPlanComparison, ScPlanDetailsCard, ScCreditsUsageCard, ScButton]
+do_not_confuse_with: [ScPlanDetailsCard, ScPlanDetailsCardMobile, ScPlanComparison, ScAppCard]
+used_by: [cxo]
+---
+
+# ScPlanCard
+
+**One purchasable plan tile in the Plans grid.** Plan name, a big formatted price
+with a small currency symbol, a tagline, a credits chip, and a full-width CTA at
+the bottom — in three flavours (`free`, `popular`, `custom`) that differ in what
+they render, not just how they look.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the 3-up "choose a plan" grid
+  (Free / Pro / Enterprise) where each tile ends in an Upgrade/Downgrade/Contact CTA.
+- **Don't reach for it when:** you want the *current* plan summary strip on the
+  billing overview (→ `ScPlanDetailsCard`), the feature-by-feature grid under the
+  tiles (→ `ScPlanComparison`), or a product/app tile (→ `ScAppCard`).
+- **Five things that will bite you:**
+  1. `price` must **not** contain `"/ month"` — the card appends `pricePeriod`
+     itself, so you get the suffix twice. (`ScPlanDetailsCard` is the opposite:
+     there you pass the whole string *including* the period.)
+  2. `type="custom"` **drops `price`, `credits`, `creditsDropdown` and the
+     Increase button entirely.** Only name + tagline + button render.
+  3. `buttonVariant` has five values but only **two** looks: `"primary"` =
+     red→orange gradient, everything else = white fill.
+  4. **No prop spread.** `className` and `style` are the only escape hatches —
+     no `onClick`, no `data-testid`, no `aria-*` on the root.
+  5. `features` is `@deprecated` and **renders nothing**. Feature lists moved to
+     `ScPlanComparison`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPlanCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPlanCard
+  planName="Free"
+  price="$0"
+  credits="3,000 credits"
+  type="free"
+  tagline="For trying things out"
+  buttonText="Current plan"
+  buttonState="disabled"
+  buttonVariant="secondary"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `planName` | `string` | `"Pro"` | ⚠️ Real default. Heading, secondary text colour. |
+| `price` | `string` | `"$0"` | ⚠️ Real default. Formatted, **with** currency symbol, **without** the period. Leading non-digits render small, the rest large. |
+| `pricePeriod` | `string` | `"/ month"` | ⚠️ Real default, appended muted after the amount. Only rendered when `price` contains a digit. |
+| `tagline` | `ReactNode` | – | One-line blurb under the price. |
+| `description` | `ReactNode` | – | Back-compat alias. `tagline ?? description` — `tagline` wins. |
+| `credits` | `string` | `"300 Credits"` | ⚠️ Real default. Text of the credits chip. **Not rendered for `type="custom"`.** |
+| `type` | `"free"` \| `"popular"` \| `"custom"` | `"free"` | ⚠️ Defaults to `free`, not `popular`. Gates whole regions — see the table below. |
+| `increaseLabel` | `string` | `"Increase"` | Label on the credit-tier pill. **`popular` only.** |
+| `onIncreaseCredits` | `() => void` | – | Click of that pill. **`popular` only.** |
+| `creditsDropdown` | `ReactNode` | – | **SLOT** rendered inside the (relatively positioned) credits wrapper. Despite the JSDoc saying "popular only", it renders for **`free` and `popular`** — just not `custom`. |
+| `buttonText` | `string` | `"Upgrade"` | ⚠️ Real default. The CTA label. |
+| `buttonState` | `"default"` \| `"disabled"` | `"default"` | `disabled` → native `disabled`, `opacity: .5`, `cursor: default`, `onUpgrade` not wired. |
+| `buttonVariant` | `"primary"` \| `"secondary"` \| `"tertiary"` \| `"outline"` \| `"error"` | `"primary"` | ⚠️ Only `"primary"` is distinct (gradient). The other four all render the same white fill. |
+| `onUpgrade` | `() => void` | – | CTA click. Ignored while `buttonState="disabled"`. |
+| `features` | `PlanFeatureSection[]` | – | ⚠️ `@deprecated`, **never rendered**. Kept only so old imports still typecheck. |
+| `className` | `string` | – | On the root div. |
+| `style` | `CSSProperties` | – | Merged **last** into the card style, so it overrides `background`/`border`. |
+
+There is **no** `...props` rest spread and the interface does **not** extend
+`HTMLAttributes`.
+
+### What renders in each `type`
+
+| Region | `free` | `popular` | `custom` |
+|---|---|---|---|
+| Name + price + `pricePeriod` | ✅ | ✅ | name only, no price |
+| `tagline` / `description` | ✅ | ✅ | ✅ |
+| Credits chip (`credits`) | ✅ | ✅ | — |
+| `increaseLabel` pill + `onIncreaseCredits` | — | ✅ | — |
+| `creditsDropdown` slot | ✅ | ✅ | — |
+| Card edge | 0.5px subtle grey border | red→orange gradient border | 0.5px subtle grey border |
+| CTA button | ✅ | ✅ | ✅ |
+
+### Recipes
+
+```tsx
+// The paid tile with a credit-tier picker in the slot.
+// The card is `overflow: visible` on purpose so this panel can overlay below it.
+<ScPlanCard
+  planName="Pro"
+  type="popular"
+  price={stripMonthly(selected.price)}        // "$49.99", NOT "$49.99 / month"
+  credits={selected.credits}
+  tagline="For teams shipping every week"
+  increaseLabel="Increase"
+  onIncreaseCredits={() => setTierOpen((o) => !o)}
+  creditsDropdown={
+    tierOpen ? (
+      <div style={{ position: "absolute", left: 0, right: 0, top: "calc(100% + 4px)", zIndex: 20 }}>
+        {/* your tier options */}
+      </div>
+    ) : undefined
+  }
+  buttonText="Upgrade"
+  buttonVariant="primary"
+  onUpgrade={() => setConfirmOpen(true)}
+/>
+
+// Enterprise / "talk to us" tile — no price, no credits
+<ScPlanCard
+  planName="Enterprise"
+  type="custom"
+  tagline="Custom volume, custom terms"
+  buttonText="Contact Sales"
+  buttonVariant="secondary"
+  onUpgrade={() => window.open("https://cal.com/streamoid/30min", "_blank")}
+/>
+
+// Equal-height tiles: the card has no intrinsic height — stretch it from outside
+<div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 items-stretch" style={{ gap: 32 }}>
+  {tiles.map((t) => (
+    <div key={t.id} className="h-full">
+      <ScPlanCard {...t} className="h-full" />
+    </div>
+  ))}
+</div>
+
+// A price the API couldn't resolve: no digits ⇒ rendered whole, and the
+// "/ month" suffix is suppressed automatically.
+<ScPlanCard planName="Pro" type="popular" price="—" credits="—" />
+```
+
+---
+
+## 2. Where to use it
+
+- **The Billing → Plans sub-view**, three tiles side by side. That is the only
+  surface it exists for.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`, `PlansView`), which **CXO** mounts
+  through `src/app/components/settings-content.tsx`. CXO has a local
+  `billing-content.tsx` that also calls it, but nothing imports that file — it is
+  dead code. Edit the settings package, not CXO's copy.
+- Pair it with `ScPlanComparison` directly underneath — the tiles carry
+  price/credits/CTA, the comparison grid carries the feature matrix.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The tile is **purchasable**: it ends in an action that changes the subscription.
+- You have a **formatted** price string from the billing API (the card does no
+  currency maths, no locale formatting, no minor-unit division).
+- You need the Pro tile's gradient edge and credit-tier affordance without
+  rebuilding the padding-box/border-box gradient trick.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| "Current plan · 30,000 credits · ₹0.00 / month" summary strip with an Active badge | `ScPlanDetailsCard` (desktop) / `ScPlanDetailsCardMobile` |
+| Feature-by-feature table under the tiles | `ScPlanComparison` |
+| Credits remaining / usage meter | `ScCreditsUsageCard` |
+| A tile for a *product* (Artifax, Photogenix…) rather than a plan | `ScAppCard` / `ScAppCardV3` / `ScAppListingCard` |
+| A standalone CTA anywhere else | `ScButton` |
+| Inline feature bullet lists inside the tile | Not supported — `features` is dead. Move them to `ScPlanComparison`. |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScPlanDetailsCard` — the **one** card describing the plan you already have | `ScPlanCard` is one of **many** tiles describing plans you could buy |
+| `ScPlanComparison` — collapsible feature grid, no price, no CTA | This tile has price + CTA and no feature rows |
+| `ScPlanCard`'s `price` (period **excluded**) | `ScPlanDetailsCard`'s `planPrice` (period **included**) — the two sibling cards take opposite conventions |
+
+---
+
+## 4. Why to use it
+
+- **The price typography is done for you.** Splitting the leading currency symbol
+  to 14px while the amount stays 20px, and suppressing `/ month` when the price
+  is a placeholder, is fiddly regex work you'd otherwise repeat per tile.
+- **The Pro gradient border is not a border colour.** It is a
+  `padding-box`/`border-box` double-background with a 0.5px transparent border.
+  Hand-rolling it usually ends in a 1px gradient *outline* that doesn't follow the
+  24px radius.
+- **`overflow: visible` is deliberate,** so the credit-tier dropdown can hang
+  below the card. A generic card would clip it.
+- **Bottom-pinned CTA.** The content region is `flex: 1 1 auto; min-height: 0`, so
+  every tile's button lines up across a grid row regardless of tagline length.
+
+---
+
+## Gotchas
+
+**1. Strip the period from `price`.** The card renders `pricePeriod` itself.
+
+```tsx
+// WRONG — renders "$49.99 / month / month"
+<ScPlanCard price="$49.99 / month" />
+
+// RIGHT
+<ScPlanCard price={price.replace(/\s*\/\s*month\s*$/i, "")} />
+```
+
+**2. `type="custom"` silently drops props.** `price`, `credits`,
+`creditsDropdown`, `increaseLabel` and `onIncreaseCredits` are not rendered at
+all — a common "why is my Enterprise price missing" bug.
+
+**3. `buttonVariant` collapses to two skins.** `"secondary"`, `"tertiary"`,
+`"outline"` and `"error"` are all the same white fill. If you need a genuinely
+outlined or destructive CTA, this card can't express it.
+
+**4. Nothing is spread onto the root.** No `data-testid`, no `onClick`, no
+`aria-*`, no `id`. Wrap the card in a div if you need any of those.
+
+```tsx
+// WRONG — TS error, and nothing would land on the DOM anyway
+<ScPlanCard data-testid="pro-tile" />
+
+// RIGHT
+<div data-testid="pro-tile"><ScPlanCard /></div>
+```
+
+**5. Every text default is demo copy.** Omit `planName`, `price`,
+`credits` or `buttonText` and you ship `"Pro"`, `"$0"`, `"300 Credits"`,
+`"Upgrade"`. There is no empty state.
+
+**6. The gradient is a raw hex pair, not a token.**
+`linear-gradient(135deg, #d91536, #ee5e3a)` for the CTA and the Pro border tint
+are hardcoded, so they look identical in light and dark mode by design. Don't
+expect them to respond to a theme change.
+
+**7. `style` overrides the card skin.** It is merged after the computed styles, so
+passing `style={{ background: "..." }}` on a `popular` card destroys the gradient
+border (the trick needs both background layers).
+
+**8. `ScPlanCard.module.css` is dead.** The component is 100% inline styles and
+never imports it. Host CSS targeting `.ScPlanCard_scPlanCard` (or any class in
+that file) will not match anything — style via `className` + `style` instead.
+
+**9. `creditsDropdown` is a slot with no state.** No `aria-expanded` is wired on
+the Increase pill, and the card never closes your panel — own the open state and
+the outside-click handler yourself.
+
+**10. No intrinsic height.** In a grid, tiles will be different heights unless you
+pass `className="h-full"` (or equivalent) and stretch the grid items.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:791
+<ScPlanCard
+  planName="Pro"
+  price={stripMonthly(selectedMiddlePlan?.price || "—")}
+  credits={selectedMiddlePlan?.credits || "—"}
+  type="popular"
+  tagline={PLAN_TAGLINES.pro}
+  buttonText={isMiddleActionLoading ? "Processing..." : /* … */ "Upgrade"}
+  buttonState={selectedMiddlePlan?.isCurrent ? "disabled" : "default"}
+  buttonVariant={selectedMiddlePlan?.isCurrent ? "outline" : "primary"}
+  onUpgrade={() => setShowUpgradeConfirmModal(true)}
+  onIncreaseCredits={() => setIsPlanSelectorOpen((prev) => !prev)}
+  creditsDropdown={isPlanSelectorOpen ? (/* absolutely-positioned tier list */) : undefined}
+  className="h-full"
+/>
+```
+
+(The `free` tile is at `:750`, the `custom`/Enterprise tile at `:909`.)
+
+---
+
+## Related
+
+- `ScPlanComparison` — the feature matrix that replaced this card's `features` prop.
+- `ScPlanDetailsCard` / `ScPlanDetailsCardMobile` — the current-plan summary.
+- `ScCreditsUsageCard` — the credits meter beside it on the billing overview.
+- `ScButton` — for any CTA outside a plan tile; note this card renders its own
+  plain `<button>`, not `ScButton`.

package/dist/docs/ScPlanComparison.md

@@ -0,0 +1,264 @@
+---
+component: ScPlanComparison
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [compare-plans, pricing-table, feature-matrix, collapsible, accordion, billing, tabbed, mobile]
+related: [ScPlanCard, ScPlanDetailsCard, ScTabComp, ScTabs]
+do_not_confuse_with: [ScPlanCard, ScTableList, ScTabSwitcher, ScBillingLogsTableHeader]
+used_by: [cxo]
+required_props: [columns, sections]
+---
+
+# ScPlanComparison
+
+**The collapsible "Compare Plans" feature matrix under the plan tiles.** A title
+row with a chevron toggle, then a rounded grid: one label column plus one column
+per plan, grouped into optional full-width section headers, with the Pro column
+tinted and edged in red. `layout="tabbed"` collapses the same data to one plan at
+a time for narrow screens.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have static marketing copy comparing N plans across
+  many features and want it collapsed under the pricing tiles.
+- **Don't reach for it when:** the data is per-row API data with actions
+  (→ `ScTableList`), or you want the price/CTA tile itself (→ `ScPlanCard`).
+- **Four things that will bite you:**
+  1. `columns` and every `row.values` array must be the **same length and order**.
+     A short `values` array silently renders fewer cells and the grid goes crooked.
+  2. `defaultOpen` is **uncontrolled** — the open state lives in `useState`, and
+     there is no `onToggle`. Changing the prop later does nothing.
+  3. `highlightColumnIndex` defaults to **`1`** — it assumes a 3-column
+     Free/Pro/Enterprise layout with Pro in the middle.
+  4. It is **divs, not a `<table>`**. No `<th>`, no row/column association for
+     screen readers, and `layout="tabbed"` has `role="tab"` with no `tabpanel`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPlanComparison } from "@streamoid/ui";
+import type { PlanComparisonSection } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPlanComparison
+  columns={["Free", "Pro", "Enterprise"]}
+  sections={[
+    { rows: [{ label: "Usage volume", values: ["Limited", "Higher limits", "Unlimited"] }] },
+  ]}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `columns` | `string[]` | — | **Required.** Plan column headers, in order. Drives the header row (table) or the tab strip (tabbed). |
+| `sections` | `PlanComparisonSection[]` | — | **Required.** Ordered groups of rows. |
+| `title` | `string` | `"Compare Plans"` | ⚠️ Real default. The collapsible heading. |
+| `firstColumnLabel` | `string` | `"Compare plans"` | ⚠️ Real default. Top-left header cell. **Not rendered in `tabbed` layout.** |
+| `note` | `ReactNode` | – | Centred caption row directly under the header row (or under the tabs). |
+| `highlightColumnIndex` | `number` | `1` | ⚠️ Which value column gets the red left edge + warm tint. Pass an out-of-range index (e.g. `-1`) to highlight nothing. |
+| `defaultOpen` | `boolean` | `true` | Initial open state only — see Gotcha 2. |
+| `layout` | `"table"` \| `"tabbed"` | `"table"` | `table` = full grid; `tabbed` = tab strip + a single value column. You switch it; there is no internal breakpoint. |
+| `className` | `string` | – | On the outer column. |
+| `style` | `CSSProperties` | – | Merged last onto the outer column. |
+
+There is **no** `...props` rest spread — no `id`, `data-*` or `aria-*` on the root.
+
+### Supporting types
+
+```ts
+interface PlanComparisonRow {
+  label?: ReactNode;   // may be omitted/"" for a design sub-row
+  values: ReactNode[]; // one entry per column, in column order
+}
+interface PlanComparisonSection {
+  header?: string;     // omit for an ungrouped leading row
+  rows: PlanComparisonRow[];
+}
+```
+
+### What renders in each layout
+
+| Region | `layout="table"` | `layout="tabbed"` |
+|---|---|---|
+| Title + chevron toggle | ✅ | ✅ |
+| `firstColumnLabel` + `columns` header row | ✅ | — (replaced by the tab strip) |
+| Tab strip over `columns` | — | ✅ (internal `activeCol`, starts at 0) |
+| `note` | full-width centred row inside the grid | centred paragraph above the grid |
+| Section headers | full-width row, canvas background | same |
+| Feature rows | label + **every** value | label + **only** `row.values[activeCol]` |
+
+### Recipes
+
+```tsx
+// Static content module (the real pattern — there is no API for this copy)
+const SECTIONS: PlanComparisonSection[] = [
+  { rows: [{ label: "Usage volume", values: ["Limited", "Higher limits", "Unlimited"] }] },
+  {
+    header: "Photogenix (Imagery & Video)",
+    rows: [
+      { label: "Image generation", values: ["Up to 60 images", "Up to 200 images", "Unlimited"] },
+      { label: "", values: ["Up to 100 styles", "Up to 333 styles", "Unlimited"] }, // sub-row
+    ],
+  },
+];
+
+<ScPlanComparison
+  layout="table"
+  columns={["Free", "Pro", "Enterprise"]}
+  note="Credits roll over monthly and only expire if your plan is no longer active"
+  sections={SECTIONS}
+  highlightColumnIndex={1}
+/>
+
+// Responsive: you own the switch
+<ScPlanComparison
+  layout={isMobile ? "tabbed" : "table"}
+  columns={["Free", "Pro", "Enterprise"]}
+  sections={SECTIONS}
+/>
+
+// Start collapsed (initial value only)
+<ScPlanComparison defaultOpen={false} columns={cols} sections={SECTIONS} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Directly under the `ScPlanCard` grid** on the Billing → Plans sub-view. That
+  is its only surface.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`, `PlansView`), which **CXO** mounts
+  through `settings-content.tsx`. The copy lives in
+  `packages/settings/src/plan-comparison-data.ts` (`PLAN_COMPARISON_COLUMNS`,
+  `PLAN_COMPARISON_NOTE`, `PLAN_COMPARISON_SECTIONS`) — extend that file rather
+  than inlining literals at the call site.
+- Only `layout="table"` is used in production today; `"tabbed"` ships but has no
+  live call site.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The matrix is **static content**: marketing copy, one string per (feature, plan)
+  cell, no interactivity inside cells.
+- You want it **collapsed by default under the tiles** rather than as its own page.
+- One column should be visually promoted (Pro) without you rebuilding the tint +
+  red left-edge treatment.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Rows come from an API and have per-row actions | `ScTableList` / `ScBillingHistoryTableList` + `ScHeader` |
+| You need price + CTA per plan | `ScPlanCard` |
+| The current plan's summary | `ScPlanDetailsCard` |
+| A generic in-page tab bar | `ScTabs` / `ScTabComp` / `ScTabSwitcher` — the tab strip here is internal and not reusable |
+| A sortable data grid | `ScHeader` (`state="up"/"down"`) + your own rows; this component has no sorting |
+| Cells that contain checkmarks/icons | Supported — `values` are `ReactNode`, so pass an `Sicon*`; just keep the row heights consistent |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScPlanCard` — one tile per plan, price + CTA | This is the shared feature matrix below the tiles |
+| `ScBillingLogsTableHeader` / `ScBillingHistoryHeader` — real table header strips with fixed column widths | This component owns its own header row internally |
+| `ScTabSwitcher` / `ScTabComp` — the reusable tab vocabulary | The `tabbed` layout's buttons are private, un-styleable, and report nothing back |
+
+---
+
+## 4. Why to use it
+
+- **One data shape, two layouts.** The same `sections` array drives the desktop
+  grid and the mobile tabbed view, so the copy never forks per breakpoint.
+- **Column emphasis is computed, not hand-painted.** `valueColBg()` gives column 0
+  a raised neutral, the highlighted column a warm tint plus a red left border, and
+  the rest the canvas colour — consistent down every row without per-cell classes.
+- **The rounded clip is right.** A 32px radius with `overflow: hidden` on the grid
+  wrapper means the first and last rows are trimmed to the corners; doing this by
+  hand usually leaves square row corners poking out.
+- **Row text is tokenised** (`--alias-text---icons-secondary`), so the matrix stays
+  readable in light mode, unlike a hardcoded grey.
+
+---
+
+## Gotchas
+
+**1. Ragged `values` arrays break alignment silently.** Every row must have exactly
+`columns.length` entries.
+
+```tsx
+// WRONG — 3 columns, 2 values: the Enterprise cell is missing and the row shifts
+{ label: "Tech packs", values: ["Manual fill", "Up to 5"] }
+
+// RIGHT
+{ label: "Tech packs", values: ["Manual fill", "Up to 5", "Unlimited"] }
+```
+
+**2. Open/closed state is internal.** `defaultOpen` seeds `useState` once. You
+cannot force it open later, and you get no callback when the user toggles it.
+
+**3. `highlightColumnIndex` is not "the current plan".** It is a fixed design
+emphasis (Pro). Don't wire it to the user's active plan unless you actually want
+the tint to move.
+
+**4. In `tabbed` layout, `firstColumnLabel` and the column header row vanish,**
+and the active column is internal state starting at `0` — you cannot preselect
+"Pro" or read the user's choice.
+
+**5. The Pro tint is deliberately theme-agnostic.** `rgba(255,123,71,0.05)` is a
+raw value, not a token, so on a white light-mode surface it reads as a faint peach
+wash rather than flipping.
+
+**6. No table semantics.** Rows are `div`s and cells are `<p>`s. Screen readers get
+a flat run of text with no header association. If you need an accessible pricing
+table for compliance, this component is not it yet.
+
+**7. `overflow: hidden` on the grid.** Nothing inside a cell can escape — no
+tooltips, popovers or dropdowns unless you portal them to `document.body`.
+
+**8. Cell padding is a hardcoded 20px** and rows have no minimum height, so a cell
+with a long string grows only that row. Keep values short or accept ragged row
+heights.
+
+**9. The toggle's `aria-label` is hardcoded English** (`"Collapse"` / `"Expand"`),
+as is the `title` default `"Compare Plans"`. Not localisable without a DS change.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:924
+<ScPlanComparison
+  layout="table"
+  columns={[...PLAN_COMPARISON_COLUMNS]}
+  note={PLAN_COMPARISON_NOTE}
+  sections={PLAN_COMPARISON_SECTIONS}
+  highlightColumnIndex={1}
+/>
+```
+
+---
+
+## Related
+
+- `ScPlanCard` — the tiles above it; its `features` prop is deprecated *because*
+  this component exists.
+- `ScPlanDetailsCard` / `ScCreditsUsageCard` — the billing overview cards.
+- `ScTabComp` — the real tab component used elsewhere on the billing page (the
+  Invoice history / Usage logs switch).