@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScPlanDetailsCard.md

@@ -0,0 +1,246 @@
+---
+component: ScPlanDetailsCard
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [current-plan, plan-summary, billing, subscription, active, badge, skeleton, loading, upgrade]
+related: [ScPlanDetailsCardMobile, ScCreditsUsageCard, ScPlanCard, ScBadges, ScPairtext]
+do_not_confuse_with: [ScPlanCard, ScPlanDetailsCardMobile, ScCreditsUsageCard, ScPlanComparison]
+used_by: [cxo]
+---
+
+# ScPlanDetailsCard
+
+**The "this is the plan you're on" card at the top of the Billing page.** A
+`Current plan` label with a billing icon, a green status badge, a divider, then
+`Free · 30,000 credits` over `₹0.00 / month`, with a right-aligned CTA — plus a
+built-in shimmer skeleton for while the subscription is still loading.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the single current-subscription summary strip,
+  usually side by side with `ScCreditsUsageCard`.
+- **Don't reach for it when:** you're rendering a *buyable* plan tile
+  (→ `ScPlanCard`), the mobile billing screen (→ `ScPlanDetailsCardMobile`), or the
+  credits meter (→ `ScCreditsUsageCard`).
+- **Four things that will bite you:**
+  1. `planPrice` must be the **whole** string including the period
+     (`"₹0.00 / month"`). `ScPlanCard.price` is the exact opposite — no period.
+  2. The badge is **always `variant="success"` (green)** and is pinned to a
+     **53px width**. `"Active"` fits; `"Past due"` and `"Cancelled"` render green
+     and overflow that fixed width (`ScBadges` sets no `overflow: hidden` and no
+     `nowrap`, so the label wraps and the pill grows taller).
+  3. `isLoading` replaces the badge, the text and the button with skeletons, so
+     `onUpgrade` is unreachable while loading.
+  4. Its CTA is a default-`variant`/`type` `ScButton`, which paints a
+     `Math.random()` canvas noise texture — non-deterministic in snapshots, blank
+     in SSR.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPlanDetailsCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPlanDetailsCard
+  planName="Pro"
+  planCredits="30,000 credits"
+  planPrice="₹4,999.00 / month"
+  upgradeButtonText="Manage Plan"
+  onUpgrade={() => setShowPlans(true)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `planName` | `string` | `"Free"` | ⚠️ Real default. Left half of the dotted name row. |
+| `planCredits` | `string` | `"30,000 credits"` | ⚠️ Real default. Right half of the dotted row. Pre-formatted by you. |
+| `planPrice` | `string` | `"₹0.00 / month"` | ⚠️ Real default. Rendered verbatim — **include the period yourself**. |
+| `badgeText` | `string` | `"Active"` | ⚠️ Real default. Badge label. Colour is fixed to success — see Gotcha 2. |
+| `badgeSubText` | `string` | – | Optional muted text after a dot separator, e.g. `"Downgrades on 12 Aug"`. `nowrap`. |
+| `currentPlanLabel` | `string` | `"Current plan"` | ⚠️ Real default. Header text beside the billing icon. |
+| `upgradeButtonText` | `string` | `"Upgrade"` | ⚠️ Real default. CTA label. |
+| `isLoading` | `boolean` | `false` | Swaps badge / name row / price / button for shimmer pills. |
+| `onUpgrade` | `() => void` | – | CTA click. Not reachable while `isLoading`. |
+| `className` | `string` | – | Appended to the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div (`style`, `onClick`, `data-*`, `aria-*`). |
+
+### What renders in each state
+
+| Region | `isLoading={false}` | `isLoading={true}` |
+|---|---|---|
+| Header | billing icon + `currentPlanLabel` | same (never skeletonised) |
+| Badge area | `ScBadges` + optional dot + `badgeSubText` | one 53×28 shimmer pill |
+| Name row | `planName` · dot · `planCredits` | two shimmer pills, `aria-label="Loading plan details"` |
+| Price | `planPrice` | one shimmer pill |
+| CTA | `ScButton` (`size="md"`) | one 120×40 shimmer pill |
+
+### Recipes
+
+```tsx
+// Live plan + a scheduled-downgrade note, loading-aware (the real CXO idiom)
+<ScPlanDetailsCard
+  planName={planName}
+  planCredits={planCreditsText}                 // "30,000 credits"
+  planPrice={planAmount}                        // "₹4,999.00 / month"
+  badgeText="Active"
+  badgeSubText={scheduledDowngradeText}         // undefined ⇒ dot + text omitted
+  currentPlanLabel="Current plan"
+  upgradeButtonText={downgradeScheduled ? "Cancel downgrade" : "Manage Plan"}
+  isLoading={isPlanDetailsLoading}
+  className="flex-1 min-w-0"
+  onUpgrade={handlePrimaryAction}
+/>
+
+// Side by side with the credits meter — both must be flex-1 min-w-0 or the
+// nowrap text inside will blow the row out
+<div className="flex items-start w-full" style={{ gap: "var(--spacing-6xl)" }}>
+  <ScPlanDetailsCard className="flex-1 min-w-0" {...plan} />
+  <ScCreditsUsageCard className="flex-1 min-w-0" {...credits} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Top-left card of the Billing overview**, paired with `ScCreditsUsageCard` in a
+  two-column row. One per page.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`), which **CXO** mounts via
+  `src/app/components/settings-content.tsx`.
+- This card does not adapt on its own — `.planInfo` is a fixed 2.875rem tall and its
+  text is `nowrap`. Below `md` you are expected to swap to
+  `ScPlanDetailsCardMobile`. Note that the shared settings billing page has **no
+  mobile branch** today: the only wiring of the mobile twin is CXO's
+  `src/app/components/mobile-billing-content.tsx:161`, reached from CXO's orphaned
+  local `billing-content.tsx`. Treat mobile billing as unwired until that moves
+  into `@streamoid/settings`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need to state the **one** subscription currently in force, with a status
+  badge and a single primary action ("Manage Plan" / "Cancel downgrade").
+- The data arrives async and you want the shimmer skeleton for free.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A plan the user could switch to, with a price and an Upgrade CTA | `ScPlanCard` |
+| Mobile/narrow billing screen | `ScPlanDetailsCardMobile` |
+| Credits remaining / progress meter | `ScCreditsUsageCard` |
+| Feature comparison between plans | `ScPlanComparison` |
+| A generic titled card with a slot | `ScDefaultCard` |
+| A status pill on its own | `ScBadges` |
+| A non-success status ("Past due", "Cancelled") | Nothing here fits — the badge is hardcoded green. Render your own `ScBadges` above the card, or fix the DS first. |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScPlanCard` — a buyable tile, price parsed, gradient Pro border | This is the read-only current-plan strip |
+| `ScPlanDetailsCardMobile` — an identical prop list on a narrow, stacked layout | Not a responsive mode of this card; it is a separate export you must switch to yourself |
+| `ScCreditsUsageCard` — same visual shell, same `ScPairtext` header, but a progress bar and a "Buy credits" CTA | Easy to mix up in a diff: both are 1.5rem-padded bordered cards with a header row and a divider |
+
+---
+
+## 4. Why to use it
+
+- **The skeleton is already correct.** Five shimmer pills at the exact widths of
+  the real content, so the card doesn't reflow when data lands — a common source
+  of layout jank on billing pages.
+- **The dotted `name · credits` row** uses a `::after` pseudo-dot in a 24px box,
+  matching the same separator used in the badge row and in the mobile twin.
+- **Composed from DS parts** (`ScPairtext`, `ScBadges`, `ScHDivider`, `ScButton`),
+  so icon sizing, badge radius, divider colour and button height all track the
+  tokens rather than local guesses.
+
+---
+
+## Gotchas
+
+**1. `planPrice` includes the period; `ScPlanCard.price` must not.** The two
+sibling cards take opposite conventions.
+
+```tsx
+// RIGHT here
+<ScPlanDetailsCard planPrice="₹4,999.00 / month" />
+// RIGHT there
+<ScPlanCard price="₹4,999.00" />   // card appends "/ month"
+```
+
+**2. The badge is green and 53px wide, always.** `variant="success"` is hardcoded
+in the JSX and `.scBadgesInstance` sets `width: 3.3125rem !important`. `ScBadges`
+has no `overflow: hidden` and no `white-space: nowrap`, so anything longer than
+`"Active"` wraps inside that 53px box and makes the pill taller than the 28px
+skeleton it replaces; nothing you pass makes it red or amber.
+Use `badgeSubText` for the nuance ("Downgrades on 12 Aug") instead of trying to
+recolour the badge.
+
+**3. `isLoading` hides the CTA.** The button is replaced by a skeleton, so guard
+against users being unable to act if a fetch hangs.
+
+**4. Long text does not truncate — it overflows.** `.planName` is
+`white-space: nowrap` with no `overflow: hidden`, and `.planInfo` is a fixed
+2.875rem tall. Give the card `min-width: 0` and keep `planCredits` short.
+
+**5. You cannot add or change the CTA icon.** The JSX passes
+`icon={<SiconHome />}` to `ScButton` without a `styleVariant`, so `ScButton`
+renders label-only and the icon is dead code. There is no icon prop.
+
+**6. The CTA is a `primary`/`primary` `ScButton`.** That combination generates a
+canvas noise texture with `Math.random()` and needs a DOM — expect snapshot churn
+and nothing painted during SSR. (See `SC-Button/README.md` Gotcha 7.)
+
+**7. Missing `className` leaks the string `"undefined"` into the class list.** The
+root is `styles.scPlanDetailsCard + " " + className`. Harmless visually, but it
+shows up in DOM snapshots and breaks naive `class="…"` equality assertions.
+
+**8. `onUpgrade` is not the only click target.** Because `...props` is spread onto
+the root, a stray `onClick` you pass fires for clicks anywhere in the card,
+including the CTA.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:2027
+<ScPlanDetailsCard
+  planName={planName}
+  planCredits={planCreditsText}
+  planPrice={planAmount}
+  badgeText="Active"
+  badgeSubText={scheduledDowngradeText}
+  currentPlanLabel="Current plan"
+  upgradeButtonText={subscription?.downgradeScheduled ? "Cancel downgrade" : "Manage Plan"}
+  isLoading={isPlanDetailsLoading}
+  className="flex-1 min-w-0"
+  onUpgrade={() => { /* log + open plans, or cancel the downgrade */ }}
+/>
+```
+
+---
+
+## Related
+
+- `ScPlanDetailsCardMobile` — the mobile twin, same prop names.
+- `ScCreditsUsageCard` — the card that sits next to it.
+- `ScPlanCard` — the buyable tiles the CTA navigates to.
+- `ScBadges` / `ScPairtext` / `ScHDivider` / `ScButton` — the parts it composes.

package/dist/docs/ScPlanDetailsCardMobile.md

@@ -0,0 +1,240 @@
+---
+component: ScPlanDetailsCardMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, billing, plan, current-plan, upgrade, skeleton, loading, card, cxo]
+related: [ScPlanDetailsCard, ScCreditsUsageCardMobile, ScPlanCard, ScBadges, ScButton]
+do_not_confuse_with: [ScPlanDetailsCard, ScPlanCard, ScPlanComparison, ScCreditsUsageCardMobile]
+used_by: [cxo]
+---
+
+# ScPlanDetailsCardMobile
+
+**The current-plan summary on CXO's mobile billing screen.** A bordered full-width
+card: billing icon + "Current plan" label with a green `ScBadges` status on the
+right, a divider, `planName · planCredits` with the price under it, and a
+full-width **blue-gradient** Upgrade button. Has a built-in shimmer skeleton state.
+
+## TL;DR for agents
+
+- **Reach for it when:** the mobile billing screen needs the "what plan am I on"
+  block at the top.
+- **Don't reach for it when:** you're on desktop (→ `ScPlanDetailsCard`, identical
+  prop surface), you're rendering *purchasable* plans (→ `ScPlanCard`), or you want
+  a feature-by-plan grid (→ `ScPlanComparison`).
+- **Five things that will bite you:**
+  1. **The Upgrade button's gradient is a hardcoded inline `style`** — raw
+     `rgb()` blue, not tokens. It overrides `variant="primary"` and you cannot
+     change or theme it from outside.
+  2. **The badge is always `variant="success"`.** There is no way to show a red
+     "Past due" or amber "Trialing" — `badgeText` only changes the words.
+  3. **Every text prop has a demo default**, including `planPrice = "₹0.00 / month"`
+     — a rupee price on an app that bills in dollars.
+  4. `isLoading` replaces the badge, the plan lines **and the button** with
+     skeletons, so `onUpgrade` is unreachable while loading.
+  5. Its prop *types* are identical to the desktop `ScPlanDetailsCard` (only the
+     `planName` default differs: `"Pro"` here, `"Free"` there), which makes picking
+     the wrong one silent.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPlanDetailsCardMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPlanDetailsCardMobile
+  planName={plan.name}
+  planCredits={`${plan.credits.toLocaleString()} credits`}
+  planPrice={`$${plan.price} / month`}
+  badgeText="Active"
+  onUpgrade={openUpgrade}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `planName` | `string` | `"Pro"` | ⚠️ Demo default. First half of the `name · credits` line. |
+| `planCredits` | `string` | `"30,000 credits"` | ⚠️ Demo default. Second half, after a dot separator. You append the word "credits". |
+| `planPrice` | `string` | `"₹0.00 / month"` | ⚠️ Demo default **in rupees**. Grey sub-line. You format currency and period. |
+| `badgeText` | `string` | `"Active"` | ⚠️ Text of the badge. The badge is hardwired to `variant="success"` / `styleVariant="opaque"`. |
+| `badgeSubText` | `string` | – | Optional extra grey text after the badge, preceded by a 4px dot. Renders only when truthy. |
+| `currentPlanLabel` | `string` | `"Current plan"` | ⚠️ Header label beside the billing icon. |
+| `upgradeButtonText` | `string` | `"Upgrade"` | ⚠️ CTA label. |
+| `isLoading` | `boolean` | `false` | Swaps badge, plan lines and button for shimmer skeletons. See the state table. |
+| `onUpgrade` | `() => void` | – | The CTA's `onClick`. Unreachable while `isLoading`. |
+| `className` | `string` | – | Appended after internal classes (safely — uses `className ?? ""`). |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the card root, **not** the button. |
+
+### What renders in each state
+
+| Region | `isLoading={false}` | `isLoading={true}` |
+|---|---|---|
+| Header left | `SiconBilling` + `currentPlanLabel` | unchanged — always visible |
+| Header right | `ScBadges` (success/opaque) + optional dot + `badgeSubText` | one 53×28 shimmer pill |
+| Plan info | `planName` · `planCredits`, then `planPrice` | two inline pills (`aria-label="Loading plan details"`) + a price pill |
+| Action | gradient `ScButton` with `upgradeButtonText` | one full-width 40px shimmer pill |
+
+### Recipes
+
+```tsx
+// Real load-then-show, the CXO shape
+<ScPlanDetailsCardMobile
+  isLoading={!plan}
+  planName={plan?.name ?? ""}
+  planCredits={plan ? `${plan.credits.toLocaleString("en-US")} credits` : ""}
+  planPrice={plan ? `$${plan.amount.toFixed(2)} / month` : ""}
+  badgeText={plan?.status === "active" ? "Active" : "Inactive"}
+  onUpgrade={() => setShowPlans(true)}
+/>
+
+// Add a renewal note after the badge
+<ScPlanDetailsCardMobile
+  planName="Pro"
+  planCredits="30,000 credits"
+  planPrice="$49.00 / month"
+  badgeText="Active"
+  badgeSubText="Renews Aug 12"
+  onUpgrade={openUpgrade}
+/>
+
+// You want a non-green status? The badge can't do it — render your own beside the card.
+// (badgeText="Past due" still renders GREEN.)
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile billing screen**, the first block on the page, directly above
+  `ScCreditsUsageCardMobile` and the invoice/usage `ScTabSwitcher`.
+- Any narrow single-column surface that needs a "your current subscription" summary
+  with one upgrade path.
+
+It composes `SiconBilling`, one `ScBadges` and one `ScButton` internally. Don't nest
+your own badge or button — use `badgeText` / `upgradeButtonText`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is the mobile breakpoint and the card must be full-width.
+- The plan is a **fact to display**, with exactly one forward action (Upgrade).
+- You want a skeleton state for free while the subscription request is in flight.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop billing page | `ScPlanDetailsCard` — same props, desktop metrics |
+| A tile in a "choose a plan" grid (price, features, CTA) | `ScPlanCard` |
+| Feature-by-plan comparison table | `ScPlanComparison` |
+| Credits remaining / buy credits | `ScCreditsUsageCardMobile` |
+| A status chip on its own, any colour | `ScBadges` directly |
+| Non-green plan status (past due, canceled) | `ScBadges` beside a plain card — this component can't recolour its badge |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScPlanDetailsCard` — the desktop twin with an **identical** prop list | Nothing in the types tells you which one you imported; check the `Mobile` suffix |
+| `ScPlanCard` — a purchasable plan tile (formatted price, feature list) | This card describes the plan you already have |
+| `ScCreditsUsageCardMobile` — same chrome, one slot lower on the screen | Credits, not plan; secondary button, not gradient |
+
+---
+
+## 4. Why to use it
+
+- **The skeleton is already built.** Five separately-sized shimmer pills with a
+  shared 1.1s `skeletonShimmer` keyframe, and an `aria-label` on the plan row.
+  Hand-rolling that is where mobile billing screens usually look cheap.
+- **Prop-identical to the desktop card**, so a responsive screen can pick the
+  component at the breakpoint and pass the same view-model object to both.
+- **Card chrome is shared with `ScCreditsUsageCardMobile`** — `--radius-3xl`, 1px
+  `--alias-border-subtle`, `backdrop-filter: blur(4px)`, 16px padding — so the two
+  stacked cards line up exactly.
+- **Correct token usage** (`--alias-text-and-icons-*`, `--alias-surface-base`), so
+  the card body genuinely flips light/dark — the gradient button is the one
+  exception (see Gotcha 1).
+
+---
+
+## Gotchas
+
+**1. The Upgrade button's colour is an inline style you cannot reach.** The
+component renders `variant="primary"` *and then* overrides its background with a
+literal gradient:
+
+```tsx
+style={{ backgroundImage: "linear-gradient(154deg, rgb(18, 57, 255) 0%, rgb(73, 206, 255) 100%)" }}
+```
+
+Raw `rgb()`, no tokens, so it is the same blue in light and dark mode, and
+`className` on the card can't win against an inline style on the button. If the
+brand blue must change, change the DS.
+
+**2. The badge is always green.** `variant="success"` is hardcoded.
+
+```tsx
+// MISLEADING — renders "Past due" in success green
+<ScPlanDetailsCardMobile badgeText="Past due" />
+```
+
+**3. Demo defaults everywhere, and the price default is in rupees.** Rendering the
+card bare gives you `Pro · 30,000 credits` / `₹0.00 / month` / `Active`, which looks
+like real data in a screenshot.
+
+**4. `isLoading` hides the CTA.** While loading there is no button at all, so
+`onUpgrade` cannot fire. Don't rely on the button existing for focus management.
+
+**5. `planCredits` is not a number.** You append the word "credits" (and do the
+locale grouping). The card only inserts the dot separator.
+
+**6. `badgeSubText` is dropped when falsy.** Empty string means "no dot, no text" —
+which is usually what you want, but means you can't render a deliberate blank.
+
+**7. `...props` lands on the card root.** `onClick` makes the *whole card*
+clickable in addition to the Upgrade button; `style` restyles the card, never the
+button.
+
+**8. `backdrop-filter: blur(4px)` creates a containing block,** so any
+`position: fixed` descendant anchors to this card rather than the viewport.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-billing-content.tsx:161
+<ScPlanDetailsCardMobile
+  planName={planName}
+  planCredits={planCredits}
+  planPrice={planPrice}
+  badgeText={badgeText}
+  onUpgrade={onUpgrade}
+  className="w-full"
+/>
+```
+
+---
+
+## Related
+
+- `ScPlanDetailsCard` — the desktop twin; identical props.
+- `ScCreditsUsageCardMobile` — the credits card immediately below it.
+- `ScPlanCard` / `ScPlanComparison` — the "choose a plan" surfaces.
+- `ScBadges` — the status chip it renders; use directly if you need another colour.
+- `ScButton` — the CTA, here with its background overridden.