@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScCreditsUsageCardMobile.md

@@ -0,0 +1,224 @@
+---
+component: ScCreditsUsageCardMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, billing, credits, usage, meter, buy-credits, card, cxo]
+related: [ScCreditsUsageCard, ScPlanDetailsCardMobile, ScButton, CreditWarningBanner]
+do_not_confuse_with: [ScCreditsUsageCard, ScPlanDetailsCardMobile, CreditWarningBanner]
+used_by: [cxo]
+---
+
+# ScCreditsUsageCardMobile
+
+**The credits-remaining block on CXO's mobile billing screen.** A bordered
+full-width card: credits icon + "Credits usage" label, a divider, the
+`used / total` figure with a "remaining" sub-line, and a full-width
+**secondary** `ScButton` for buying credits.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are laying out the mobile (narrow, single-column)
+  billing screen and need the credits meter above the invoice/usage tabs.
+- **Don't reach for it when:** you're on desktop (→ `ScCreditsUsageCard`, which
+  additionally has a `progress` bar and a disable-able buy button), or you want a
+  low-credits *alert* rather than a summary (→ `CreditWarningBanner`).
+- **Four things that will bite you:**
+  1. **Every text prop has a real demo default.** Render it bare and you ship
+     `"8,450 / 30,000"` and `"21,550 (60%) Remaining"`.
+  2. **There is no progress bar.** The desktop card's `progress` prop does not
+     exist here — the percentage lives inside the `remainingText` string you build.
+  3. **There is no way to disable the buy button.** The desktop card's
+     `buyButtonState` is absent; omit `onBuyClick` and the button still looks live.
+  4. The card is already `width: 100%`; `usageText`/`remainingText` are opaque
+     strings — the card does no formatting, no maths, no locale handling.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCreditsUsageCardMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCreditsUsageCardMobile
+  usageText={`${used.toLocaleString()} / ${total.toLocaleString()}`}
+  remainingText={`${remaining.toLocaleString()} (${pct}%) Remaining`}
+  onBuyClick={openBuyCredits}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `usageLabel` | `string` | `"Credits usage"` | ⚠️ Header label beside the credits icon. Hardcoded English default. |
+| `usageText` | `string` | `"8,450 / 30,000"` | ⚠️ Demo default. The big `used / total` line. You build the whole string. |
+| `remainingText` | `string` | `"21,550 (60%) Remaining"` | ⚠️ Demo default. The grey sub-line. Includes the percentage — the card computes nothing. |
+| `buyButtonText` | `string` | `"Buy credits"` | ⚠️ Hardcoded English default. |
+| `onBuyClick` | `() => void` | – | Wired to the internal `ScButton`'s `onClick`. |
+| `className` | `string` | – | Appended after internal classes (safely — this card uses `className ?? ""`). |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the card root. `style`, `data-*`, `onClick` land on the **card**, not the button. |
+
+### What the card renders, top to bottom
+
+| Region | Content | Configurable? |
+|---|---|---|
+| Header | `SiconCredits` (24×24, tertiary token) + `usageLabel` | label only — the icon is fixed |
+| Divider | 0.5px `--alias-border-divider` | no |
+| Usage | `usageText` (18px/500 primary) then `remainingText` (14px/500 tertiary) | text only |
+| Action | `ScButton variant="secondary" size="md"`, forced to `width: 100% !important` | `buyButtonText`, `onBuyClick` |
+
+### Recipes
+
+```tsx
+// The CXO idiom: caller owns all formatting
+const pct = Math.round((remaining / total) * 100);
+
+<ScCreditsUsageCardMobile
+  usageLabel="Credits usage"
+  usageText={`${used.toLocaleString("en-US")} / ${total.toLocaleString("en-US")}`}
+  remainingText={`${remaining.toLocaleString("en-US")} (${pct}%) Remaining`}
+  buyButtonText="Buy credits"
+  onBuyClick={() => setShowBuyCredits(true)}
+/>
+
+// Loading — this card has NO isLoading prop (unlike ScPlanDetailsCardMobile).
+// Either render your own skeleton, or pass placeholder strings:
+<ScCreditsUsageCardMobile usageText="—" remainingText="Loading…" onBuyClick={undefined} />
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile billing screen**, stacked directly under `ScPlanDetailsCardMobile`
+  and above the `ScTabSwitcher` that toggles Invoice history / Usage history.
+- Any narrow single-column surface (mobile drawer, bottom sheet) that needs a
+  credits summary with a single CTA.
+
+It composes `SiconCredits` and one `ScButton` internally. Do **not** nest your own
+button — pass `buyButtonText` / `onBuyClick`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is the mobile breakpoint and the card must be full-width.
+- A single "Buy credits" action is the only affordance you need.
+- You already have the numbers formatted as display strings.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop billing page | `ScCreditsUsageCard` — same prop names **plus** `progress`, `buyButtonState`, `buyButtonHoverText` |
+| You need a visual usage bar | `ScCreditsUsageCard` (has `progress`), or compose `ScProgressBar` yourself |
+| Low-credits warning / nudge in a sidebar | `CreditWarningBanner` |
+| Current-plan summary (name, price, Upgrade) | `ScPlanDetailsCardMobile` |
+| A plan tile in a pricing grid | `ScPlanCard` |
+| A row of the usage-log list | `UsageHistoryMobile` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCreditsUsageCard` — the desktop twin, with a progress bar and a disable-able button | This mobile twin has neither |
+| `CreditWarningBanner` — takes numbers (`availableCredits`, `remainingPct`) and decides its own tone | This card takes pre-built strings and never changes colour |
+| `ScPlanDetailsCardMobile` — visually near-identical card, one slot down the screen | Different content and a *gradient* button |
+
+---
+
+## 4. Why to use it
+
+- **Matches its desktop twin's anatomy prop-for-prop** (`usageLabel`,
+  `usageText`, `remainingText`, `buyButtonText`, `onBuyClick`), so a responsive
+  screen can swap components at the breakpoint without reshaping its data.
+- **Correct token usage.** Unlike most of the `*Mobile` family, this card uses the
+  real `--alias-text-and-icons-*` names, so it genuinely flips between dark and
+  light themes.
+- **The CTA is a real `ScButton`**, so it inherits the shared button shape, focus
+  behaviour and theme flip — the `width: 100% !important` override is the only
+  mobile-specific bit, and it's already done for you.
+- **One place to change** the card chrome (radius `--radius-3xl`, 1px
+  `--alias-border-subtle`, `backdrop-filter: blur(4px)`) shared with
+  `ScPlanDetailsCardMobile`.
+
+---
+
+## Gotchas
+
+**1. All four text props have shipping-quality demo defaults.** There is no
+"empty" state — forget a prop and you ship believable wrong numbers.
+
+```tsx
+// WRONG — renders "Credits usage / 8,450 / 30,000 / 21,550 (60%) Remaining"
+<ScCreditsUsageCardMobile onBuyClick={buy} />
+
+// RIGHT
+<ScCreditsUsageCardMobile
+  usageText={`${used} / ${total}`}
+  remainingText={`${remaining} (${pct}%) Remaining`}
+  onBuyClick={buy}
+/>
+```
+
+**2. No `progress` prop.** The desktop `ScCreditsUsageCard` draws a bar; this one
+does not. The only percentage the user sees is the one you typed into
+`remainingText`, so keep it consistent with `usageText` yourself.
+
+**3. No `buyButtonState`.** You cannot disable the CTA through the card. If the
+user must not buy (no permission, no payment method), don't render the card's
+action path — conditionally render your own `ScButton` outside the card, or gate
+inside `onBuyClick`.
+
+**4. No `isLoading` / skeleton.** Its sibling `ScPlanDetailsCardMobile` *does*
+have one. Passing `isLoading` here is a type error; render your own placeholder.
+
+**5. `style` and `onClick` go to the card, not the button.** `...props` is spread
+on the root `div`, so `onClick` makes the whole card clickable *in addition to*
+the button. That is almost never what you want.
+
+**6. `backdrop-filter: blur(4px)` on the root creates a containing block.** Any
+`position: fixed` descendant (a portal-less popover, a sticky footer) will be
+positioned against this card instead of the viewport.
+
+**7. The header icon is not swappable.** `SiconCredits` is hardcoded, with its
+colour pinned to `--alias-text-and-icons-tertiary`. There is no `icon` prop.
+
+**8. `usageLabel` / `buyButtonText` are the only localisable strings.** Everything
+else you supply, so a localised surface must format numbers and the word
+"Remaining" itself.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-billing-content.tsx:171
+<ScCreditsUsageCardMobile
+  usageText={usageText}
+  remainingText={remainingText}
+  onBuyClick={onBuyCredits}
+  className="w-full"
+/>
+```
+
+---
+
+## Related
+
+- `ScCreditsUsageCard` — the desktop twin; has `progress` and `buyButtonState`.
+- `ScPlanDetailsCardMobile` — the card directly above it on the same screen.
+- `CreditWarningBanner` — the alert form, driven by numbers not strings.
+- `ScButton` — what the CTA actually is; `variant="secondary"`, `size="md"`.
+- `UsageHistoryMobile` / `InvoiceHistoryMobile` — the list rows below the tabs.

package/dist/docs/ScDefaultCard.md

@@ -0,0 +1,269 @@
+---
+component: ScDefaultCard
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [card, option, choice, picker, default, hover, title, description, centered, catalogix]
+related: [ScMappingCard, ScStoreCard, ScAppListingCard, ScRadio, ScTabField, ScModal, ScDrawer]
+do_not_confuse_with: [ScAppListingCard, ScStoreCard, ScMappingCard, ScBriefCard, ScRadio]
+used_by: [catalogix]
+---
+
+# ScDefaultCard
+
+**The generic "pick this option" card.** A full-width bordered box with a centred
+title and an optional smaller description underneath. Two visual states — default
+and hover — and nothing else: no icon, no badge, no button, no state machine.
+
+## TL;DR for agents
+
+- **Reach for it when:** a screen asks "which of these routes do you want?" and each
+  route is a title plus a one-line cost/time hint — stacked vertically, often with
+  "or" separators between them.
+- **Don't reach for it when:** the card needs an icon and lives in a grid
+  (→ `ScAppListingCard`), it carries a mapping lifecycle
+  (→ `ScMappingCard`), it's a store summary (→ `ScStoreCard`), or the choice is a
+  **form value you will save** (→ `ScRadio` / `ScTabField`).
+- **Three things that will bite you:**
+  1. `title` defaults to `"Title"` and `description` to `"Description"` — forget
+     either and you ship placeholder copy.
+  2. `cursor: pointer` is baked in, but there is **no `role`, `tabIndex` or key
+     handling**. Every Catalogix call site hand-adds `role="button" tabIndex={0}`;
+     only the Products/taxonomy ones also add `onKeyDown` (ConnectOptions forgets
+     it — copy the Products version, not that one).
+  3. `state="hover"` force-renders the hover skin. It is for Figma parity /
+     screenshots, **not** for wiring your own mouse handlers — real `:hover`
+     already works.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScDefaultCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScDefaultCard
+  title="Use Catalogix taxonomy"
+  description="Average Time : Instant."
+  role="button"
+  tabIndex={0}
+  onClick={choose}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | `"Title"` | ⚠️ Real default. `text-md-regular`, primary, centred, `word-break: break-word`. |
+| `description` | `string` | `"Description"` | ⚠️ Real default. `text-xs-regular`, tertiary, centred. Only rendered when `showDescription` is true **and** the string is non-empty. |
+| `showDescription` | `boolean` | `true` | ⚠️ Defaults to **true**, so the description renders unless you opt out. `false` → title-only card. |
+| `state` | `"default"` \| `"hover"` | `"default"` | Forces the visual state. `"hover"` applies the same skin as real `:hover`. |
+| `className` | `string` | – | Appended after the internal classes, so it wins on equal specificity. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `role`, `tabIndex`, `onKeyDown`, `style`, `aria-*`, `data-*` all land on the root div. |
+
+### What renders in each state
+
+| Region | `state="default"` | `state="hover"` (or real `:hover`) |
+|---|---|---|
+| Background | `--alias-surface-base` | `--alias-surface-basesubtle` — ⚠️ **identical (`#ffffff`) in light mode** |
+| Border | `--alias-border-subtle` | `--alias-border-default` — the only hover cue that survives light mode |
+| Content | title (+ description if `showDescription && description`) | same |
+
+### Recipes
+
+```tsx
+// The Catalogix idiom: a stack of routes with "or" separators, fully accessible
+{OPTIONS.map((option, idx) => (
+  <Fragment key={option.key}>
+    <ScDefaultCard
+      title={option.title}
+      description={option.desc}
+      showDescription
+      role="button"
+      tabIndex={0}
+      onClick={() => setSelectedOption(option.key)}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") { e.preventDefault(); setSelectedOption(option.key); }
+      }}
+    />
+    {idx < OPTIONS.length - 1 && <div className="or-separator">or</div>}
+  </Fragment>
+))}
+
+// Title-only card
+<ScDefaultCard title="Start from scratch" showDescription={false} role="button" tabIndex={0} onClick={go} />
+
+// Design-parity screenshot of the hover skin (never wire this to onMouseEnter)
+<ScDefaultCard title="Use your own taxonomy" description="Average Time : 30 mins." state="hover" />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix "Choose your store taxonomy"** — three stacked cards ("Use Catalogix
+  taxonomy" / "Use your own taxonomy" / "Copy from existing store"), separated by
+  "or".
+- **Catalogix "Add Active Feed" → Connect options** — the same control, reused for
+  feed connection methods. The call site's own comment records that this card
+  *replaced* a hand-rolled `.option` + `.hr-divider-sm` block.
+- Any **empty state or drawer that offers 2–4 mutually exclusive routes**, inside
+  `ScModal` / `ScDrawer` or a page-level empty state.
+
+It composes nothing from the DS and is composed by nothing — you always place it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The card is a **navigation/branching choice**, and clicking it immediately does
+  something (opens a modal, pushes a route, selects a method).
+- The content is exactly **title + optional one-line hint**, centred.
+- Cards are stacked full-width, not tiled in a grid.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Tile with an icon chip in a product grid | `ScAppListingCard` |
+| Tile in the app-switcher grid (gradient border, `active`) | `ScAppCardV3` |
+| Store summary (name, product count, status beacon) | `ScStoreCard` |
+| A source→target mapping row with confirm/ignore lifecycle | `ScMappingCard` |
+| A value-mapping/curation row with an "updated" dot | `ScValueMappingL1` |
+| A **saved** single-choice form value | `ScRadio` (list) or `ScTabField` (segmented) |
+| A filter/segmented view switch | `ScSelectionPill` / `ScSelectionPillGroup` |
+| A row in a table | `ScTableList` / `ScCatalogixStoreTableList` |
+| An agent quick-prompt card | `ScBriefCard` (via `ScQuickPrompt`) |
+| The card needs a CTA button inside it | `ScPlanCard` / `ScWorkspaceSwitchCard`, or compose your own with `ScButton` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScAppListingCard` — icon + left-aligned title + description, scale-up hover, grid tile | `ScDefaultCard` is centred, full-width, chrome-light |
+| `ScBriefCard` — centred description-only card with a coral gradient border (agent runtime) | This card has a plain subtle border and a title |
+| `ScMappingCard` — three-status lifecycle + action footer | This card has no states beyond default/hover |
+| `ScRadio` — a real form control with a selected state | This card has **no selected state at all** (see Gotcha 4) |
+
+---
+
+## 4. Why to use it
+
+- **It removes a hand-rolled pattern that already existed twice.** The Catalogix
+  connect-options screen and the choose-taxonomy screen had independently built the
+  same box; both now render this card, so the padding, radius, hairline border and
+  hover feel are identical.
+- **Light-mode-safe hover.** The hover recipe changes *both* the background and the
+  border. Because light mode collapses all `surface-*` tokens to white, the border
+  step is what keeps the hover legible — a hand-rolled card that only changes
+  background loses its hover entirely in light mode.
+- **The hairline border is 0.5px** (`0.03125rem`), matching `ScStoreCard` and the
+  divider family rather than the 1px used by the app cards — consistent with the
+  Catalogix card language.
+- **`state="hover"` gives you deterministic screenshots** for Figma parity checks
+  without simulating pointer events (headless Chrome cannot force `:hover`
+  reliably).
+- **`word-break: break-word` on both lines**, so a long taxonomy name never blows
+  out the card width.
+
+---
+
+## Gotchas
+
+**1. Placeholder defaults ship.** `title="Title"` and `description="Description"`
+are real strings.
+
+```tsx
+// WRONG — renders "Title" / "Description"
+<ScDefaultCard onClick={go} />
+
+// RIGHT
+<ScDefaultCard title="Copy from existing store" description="Average Time : 1 min." onClick={go} />
+```
+
+**2. Not keyboard accessible on its own.** `cursor: pointer` says "click me" but
+there is no `role`, `tabIndex`, `onKeyDown` or focus ring. Always add:
+
+```tsx
+<ScDefaultCard
+  title={o.title}
+  description={o.desc}
+  role="button"
+  tabIndex={0}
+  onClick={pick}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); pick(); } }}
+/>
+```
+
+**3. `description=""` hides the line even with `showDescription` true.** The guard is
+`showDescription && Boolean(description)`. That is usually what you want, but it
+means an empty string and `showDescription={false}` are indistinguishable, and the
+card's height changes between them — watch out in equal-height rows.
+
+**4. There is no selected/active state.** `state` only has `default` and `hover`. If
+your flow needs to show which option is currently chosen, you must add it via
+`className` (or use `ScRadio` / `ScTabField` / `ScSelectionPill` instead). Both
+Catalogix screens dodge this by navigating away on click.
+
+**5. Hover's background change is invisible in light mode.** `surface-base` and
+`surface-basesubtle` are both `#ffffff` in the light theme; only the border darkens.
+Do not rely on the fill to communicate hover.
+
+**6. `width: 100%` is baked in.** The card always fills its parent. To get a narrower
+card, constrain the parent — setting `width` via `className` fights the module class
+at equal specificity (yours wins because it is appended, but inline `style` is safer).
+
+**7. `state="hover"` is design parity, not interaction.** Never drive it from
+`onMouseEnter`; you would double up on the real `:hover` and break touch devices.
+
+**8. No icon slot.** If your design shows a glyph above the title, this is the wrong
+card — use `ScAppListingCard`, or render your own icon above a `ScDefaultCard`
+(the Catalogix taxonomy screen puts `SiconStores` *outside* the cards, above the
+heading).
+
+---
+
+## In the wild
+
+```tsx
+// catalogix/dashboard  app/containers/Products/index.jsx:1684
+<ScDefaultCard
+  title="Use Catalogix taxonomy"
+  description="Average Time : Instant."
+  role="button"
+  tabIndex={0}
+  onClick={() => {
+    setShowCurationModal(true);
+  }}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      setShowCurationModal(true);
+    }
+  }}
+/>
+```
+
+Also at `app/containers/StoreSettingsV2/FeedImport/Feed/ConnectOptions/index.jsx:67`
+(feed connect methods) and twice more in `Products/index.jsx` (lines 1703, 1728).
+
+---
+
+## Related
+
+- `ScMappingCard` — the feed-mapping card when you need a confirm/ignore lifecycle.
+- `ScStoreCard` — the store-listing card (name + beacon + counts).
+- `ScAppListingCard` / `ScAppCardV3` — icon-bearing product tiles for grids.
+- `ScRadio` / `ScTabField` / `ScSelectionPillGroup` — when the choice is a saved value.
+- `ScModal` / `ScDrawer` — the containers these cards usually sit in.