@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScCounter.md

@@ -0,0 +1,235 @@
+---
+component: ScCounter
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [counter, stepper, number, quantity, increment, decrement, plus-minus, clamp, min, max]
+related: [ScTextField, ScOnlyField, ScSlider, ScFieldButton]
+do_not_confuse_with: [ScSlider, ScTextField, ScBadges, ScProgressBar]
+used_by: [catalogix]
+required_props: [count, onChange]
+---
+
+# ScCounter
+
+**A −/value/＋ numeric stepper with a click-to-edit inline input.** The value is a
+click target: tap it and it becomes a `<input type="number">` that closes on blur.
+Optional `min`/`max` clamp both the buttons and typed input.
+
+## TL;DR for agents
+
+- **Reach for it when:** the user nudges a small bounded integer — page size, image
+  count, retry limit, a PLP range bound.
+- **Don't reach for it when:** the number is free-form or large (→ `ScTextField`),
+  it's a continuous range (→ native `<input type="range">`; `ScSlider` does not
+  work), or it's a read-only count (→ `ScBadges`).
+- **Four things that will bite you:**
+  1. `min`/`max` are **opt-in**. Omit them and −/＋ walk into negatives / infinity.
+  2. Typing in the inline input can hand your `onChange` **`0`** (empty field) or
+     **`NaN`** — guard it.
+  3. The −/＋ hit areas are plain `<div onClick>`: no keyboard, no `aria-label`,
+     no `disabled`.
+  4. The root is `width: 100%` — it fills its parent unless you constrain it.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCounter } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCounter count={qty} onChange={setQty} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `count` | `number` | — | **Required.** Fully controlled; the component keeps no value state. |
+| `onChange` | `(next: number) => void` | — | **Required.** Receives the already-clamped value from the buttons, and `Number(input.value)` from typing. |
+| `label` | `ReactNode` | – | Trailing unit, rendered *inside* the value as `{count} {label}` (e.g. `5 images`). In edit mode it moves to the right of the input. |
+| `min` | `number` | – | Opt-in lower clamp (`Math.max`). Omit for unbounded. |
+| `max` | `number` | – | Opt-in upper clamp (`Math.min`). Omit for unbounded. |
+| `className` | `string` | – | Properly joined (`filter(Boolean).join(" ")`) — no stray `undefined` here, unlike most DS components. |
+| `style` | `React.CSSProperties` | – | Applied to the root. The **only** styling escape hatch. |
+
+⚠️ `IScCounterProps` does **not** extend `HTMLAttributes`. There is no `id`,
+`onClick`, `data-*`, `aria-*` or `ref` passthrough — `className` and `style` only.
+
+### What renders in each mode
+
+| Mode | Middle region | Entered by | Left by |
+|---|---|---|---|
+| Display (default) | `<div>{count} {label}</div>`, `cursor: pointer` | initial render | clicking it |
+| Edit | `<input type="number" autoFocus>` + `<div>{label}</div>` | clicking the value | `onBlur` |
+
+### Recipes
+
+```tsx
+// Bounded quantity with a unit
+<ScCounter count={imageCount} onChange={setImageCount} min={1} max={20} label="images" />
+
+// Guard the typed path against "" → 0 and non-numeric → NaN
+<ScCounter
+  count={pageSize}
+  min={10}
+  max={200}
+  onChange={(next) => {
+    if (Number.isNaN(next)) return;
+    setPageSize(next);
+  }}
+/>
+
+// Constrain the width — the root is width:100%
+<div style={{ width: 180 }}>
+  <ScCounter count={qty} onChange={setQty} min={0} />
+</div>
+
+// Legacy wrapper shape (Catalogix): customStyle → style
+<ScCounter count={props.count} onChange={props.onChange} label={props.label} style={props.customStyle} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix**, via `app/components/CounterInput` — the PLP range/count inputs and
+  anywhere a small integer is nudged. That shim exists only to keep the legacy
+  `customStyle` prop name.
+- **Inside modals and drawers** where a bounded quantity sits beside other fields.
+  Because it has no caption of its own, pair it with your own label or a
+  `ScTextField`-style caption if it must match a field stack.
+
+No other DS component composes it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The value is a **small integer** the user adjusts by ±1 more often than they type.
+- Bounds matter and you want them enforced in **one** place for both buttons and
+  keyboard entry (`min`/`max` clamp both).
+- You want the compact pill look (hardcoded `16px` radius / `12px 16px` padding,
+  `--alias-fill-neutral-neutralplus` fill) rather than a full text field.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Free-form or large numbers, or numbers needing validation messages | `ScTextField` (with a caption + helper text) |
+| A number with no caption but full field chrome | `ScOnlyField` |
+| Continuous value (opacity, strength) | native `<input type="range">` — **not** `ScSlider`, which is non-functional |
+| Read-only count/badge ("12 items") | `ScBadges` |
+| Progress toward a total | `ScProgressBar` |
+| An action button beside a field | `ScFieldButton` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSlider` — looks like a range control but is a static 5-segment graphic with a dead callback | `ScCounter` is the only DS control with working numeric clamping |
+| `ScTextField` — captioned text input, `value`/`onChange(event)` | `ScCounter`'s `onChange` receives a **number**, not an event |
+| `ScBadges` — non-interactive count chip | This one mutates |
+
+---
+
+## 4. Why to use it
+
+- **Clamping in one place.** `min`/`max` are applied inside `set()`, so the buttons
+  *and* the typed input obey the same bounds. Hand-rolled steppers routinely clamp
+  the buttons and forget the keyboard path.
+- **Click-to-edit without the state machine.** The display↔input swap, `autoFocus`
+  and blur-to-close are already wired; you only own the number.
+- **The pill themes.** Fill `--alias-fill-neutral-neutralplus`, border
+  `--alias-surface-infohover`, and the inline input re-declares the same fill plus
+  `color: inherit`, so the field doesn't flash white in dark mode — the classic
+  hand-rolled bug. (Note: unlike most DS components its radius and padding are
+  hardcoded `16px` / `12px 16px`, not tokens.)
+- **Correct icons.** `SiconMinus`/`SiconPlus` at 24px with
+  `--alias-text-and-icons-primary`, matching every other icon pair in the product.
+
+---
+
+## Gotchas
+
+**1. `min`/`max` are optional and default to unbounded.** The comment in the source
+calls this "legacy behavior". Without them, − takes you to `-1`, `-2`, …
+
+```tsx
+// WRONG — reaches negative quantities
+<ScCounter count={qty} onChange={setQty} />
+
+// RIGHT
+<ScCounter count={qty} onChange={setQty} min={0} max={99} />
+```
+
+**2. Typed input can produce `0` or `NaN`.** The handler is
+`onChange(Number(e.target.value))`. Clearing the field gives `Number("") === 0`
+(then clamped to `min` if set); a `type="number"` field can also hold intermediate
+junk like `"-"` or `"1e"`, yielding `NaN` straight into your state.
+
+```tsx
+// RIGHT — reject NaN at the boundary
+onChange={(next) => Number.isNaN(next) || setQty(next)}
+```
+
+**3. The steppers are not buttons.** `<div className={styles.step} onClick=…>` with
+decorative icons: no `tabIndex`, no `role="button"`, no keyboard, no `aria-label`,
+and **no way to disable them at the bounds** — at `max` the ＋ still looks live, it
+just clamps. There is no `disabled` prop for the whole control either.
+
+**4. The inline input is `width: 30%`** of its flex container, so 4+ digit values get
+visually cropped while editing. Constrain the root narrower, or don't use this for
+large numbers.
+
+**5. `width: 100%` on the root.** It stretches to its parent and distributes children
+with `justify-content: space-around`, so in a wide parent the − and ＋ drift far
+apart. Wrap it in a fixed-width box.
+
+**6. `label` is inside the value, not a caption.** It renders as `{count} {label}` on
+the same click target, and there is no field caption. If you need "Quantity" above
+the control, render that yourself.
+
+**7. Icon colours have no fallback.** `color="var(--alias-text-and-icons-primary)"`
+is passed without a literal fallback, so without `@streamoid/ui/dist/index.css` (or
+`@streamoid/tokens`) loaded the icons render with no colour.
+
+**8. No `HTMLAttributes` passthrough.** `id`, `data-testid`, `aria-*`, `onClick` and
+`ref` are all unavailable. Wrap it in a div if a test or a tooltip needs a hook.
+
+**9. Blur closes the editor unconditionally** — including when the field is empty.
+Combined with Gotcha 2 that means "clear and click away" silently commits `0`
+(or `min`).
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/CounterInput/index.jsx:9
+<ScCounter
+  count={props.count}
+  onChange={props.onChange}
+  label={props.label}
+  style={props.customStyle}
+/>
+```
+
+---
+
+## Related
+
+- `ScTextField` / `ScOnlyField` — captioned/plain inputs for free-form values.
+- `ScSlider` — looks like the continuous sibling; it is non-functional, don't reach for it.
+- `ScProgressBar` — display-only progress.
+- `ScFieldButton` — field-height action button if the counter needs an "Apply" beside it.

package/dist/docs/ScCreditsUsageCard.md

@@ -0,0 +1,247 @@
+---
+component: ScCreditsUsageCard
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [credits, usage, meter, progress, quota, buy-credits, billing, remaining]
+related: [ScCreditsUsageCardMobile, ScPlanDetailsCard, ScProgressBar, CreditWarningBanner, ScPairtext]
+do_not_confuse_with: [ScCreditsUsageCardMobile, ScPlanDetailsCard, ScProgressBar, CreditWarningBanner]
+used_by: [cxo]
+---
+
+# ScCreditsUsageCard
+
+**The credits meter on the Billing overview.** A `Credits used` header with a
+credits icon and the `8,450 / 30,000` count on the right, a divider, then a
+progress bar, a remaining-credits caption and a fixed-width "Buy credits" button
+that can swap its own label on hover (used as a cheap "Pro plan required" tooltip).
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the credits-consumed meter, normally to the right
+  of `ScPlanDetailsCard`.
+- **Don't reach for it when:** you want the plan summary (→ `ScPlanDetailsCard`),
+  a bare bar (→ `ScProgressBar`), the low-credits sidebar warning
+  (→ `CreditWarningBanner`), or the mobile billing screen
+  (→ `ScCreditsUsageCardMobile`).
+- **Four things that will bite you:**
+  1. `progress`, `usageText` and `remainingText` are **three unrelated props**.
+     Nothing derives one from another; they will disagree if you let them.
+  2. In live usage `progress` is the **percent used** (the bar fills up) while
+     `remainingText` states the percent **remaining** — the component's own
+     defaults (`progress={60}` + `"60% Remaining"`) contradict that convention.
+  3. The button is pinned to **7.5rem wide, 2.5rem tall, `overflow: hidden`**, so a
+     long `buyButtonHoverText` clips.
+  4. `buyButtonHoverText` still swaps while `buyButtonState="disabled"` — that is
+     the whole point, but it means "disabled" is not inert.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCreditsUsageCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCreditsUsageCard
+  usageText="8,450 / 30,000"
+  remainingText="21,550 (72%) Remaining"
+  progress={28}
+  onBuyClick={() => setShowBuyCreditsModal(true)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `usageLabel` | `string` | `"Credits usage"` | ⚠️ Real default. Header text beside the credits icon. Live CXO passes `"Credits used"`. |
+| `usageText` | `string` | `"8,450 / 30,000"` | ⚠️ Real default. Right-aligned `used / total`. Pre-formatted by you. |
+| `remainingText` | `string` | `"60% Remaining"` | ⚠️ Real default. Caption right of the bar. `white-space: nowrap`. |
+| `buyButtonText` | `string` | `"Buy credits"` | ⚠️ Real default. CTA label. |
+| `buyButtonState` | `"default"` \| `"disabled"` | `"default"` | Forwarded to `ScButton.state`; `disabled` → `pointer-events: none`, `aria-disabled`, `tabIndex={-1}`. |
+| `buyButtonHoverText` | `string` | – | Replaces the label while the pointer is over the button wrapper. Works even when disabled. |
+| `onBuyClick` | `() => void` | – | CTA click. Blocked by `buyButtonState="disabled"`. |
+| `progress` | `number` | `60` | ⚠️ Real default. Bar fill percentage. Clamped to 0–100 by `ScProgressBar`. |
+| `className` | `string` | – | Appended to the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. |
+
+### Recipes
+
+```tsx
+// The live CXO idiom: bar = % used, caption = credits + % remaining,
+// and the CTA is gated on the plan with a hover explanation.
+<ScCreditsUsageCard
+  usageLabel="Credits used"
+  usageText={`${formatCredits(used)} / ${formatCredits(total)}`}
+  remainingText={`${formatCredits(available)} (${100 - pctUsed}%) Remaining`}
+  progress={pctUsed}
+  buyButtonText="Buy credits"
+  buyButtonState={isFreePlan ? "disabled" : "default"}
+  buyButtonHoverText={isFreePlan ? "Pro plan required" : undefined}
+  className="flex-1 min-w-0"
+  onBuyClick={() => setShowBuyCreditsModal(true)}
+/>
+
+// Unknown quota (data still loading / no subscription): keep the three props
+// consistent rather than letting the defaults leak through.
+<ScCreditsUsageCard usageText="— / —" remainingText="—" progress={0} buyButtonState="disabled" />
+
+// Paired with the plan card in one row
+<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-right card of the Billing overview**, beside `ScPlanDetailsCard`. One per
+  page.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`), which **CXO** mounts through
+  `src/app/components/settings-content.tsx`.
+- This card does not adapt: `.progressContainer` is a fixed 2.875rem tall, the
+  button is a fixed 7.5rem wide and `.remainingText` is `nowrap`. Below `md` you are
+  expected to switch to `ScCreditsUsageCardMobile`. 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:171`, reached from CXO's orphaned
+  local `billing-content.tsx`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are showing **consumption against a quota** with a single "top up" action.
+- The numbers are already formatted (thousands separators, locale) — this card does
+  no maths beyond clamping `progress`.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Current plan name / price / status badge | `ScPlanDetailsCard` |
+| Just a bar, no card chrome | `ScProgressBar` |
+| A "you're nearly out of credits" alert in the sidebar | `CreditWarningBanner` |
+| Mobile billing screen | `ScCreditsUsageCardMobile` |
+| A real tooltip (rich content, keyboard accessible, positioned) | Your own tooltip — `buyButtonHoverText` is only a label swap |
+| A second action next to "Buy credits" | Not supported; there is exactly one CTA |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCreditsUsageCardMobile` — narrower prop list (**no `buyButtonState`, no `buyButtonHoverText`**) | Do not assume prop parity with the desktop card |
+| `CreditWarningBanner` — sidebar warning strip with its own "Buy credits" CTA | This is the billing-page meter, not the alert |
+| `ScPlanDetailsCard` — visually near-identical shell (1.5rem padding, header row, divider, right-hand CTA) | Easy to confuse in a diff; different props entirely |
+
+---
+
+## 4. Why to use it
+
+- **The bar is clamped and tokenised.** `ScProgressBar` pins the fill to 0–100 and
+  colours it from the alias tokens, so a bad `progress` value can't paint outside
+  the track or pick a hardcoded green.
+- **Hover-explained disabled CTA in one prop.** Free-plan users need to be told
+  *why* "Buy credits" is dead; `buyButtonHoverText` does that without a tooltip
+  library or a second element.
+- **Shares its shell with `ScPlanDetailsCard`** (same padding, radius, divider,
+  header `ScPairtext`), so the two cards read as a matched pair in the billing row.
+
+---
+
+## Gotchas
+
+**1. The three numbers can lie to each other.** `progress` does not derive from
+`usageText`, and `remainingText` is free text. Compute all three from one source.
+
+```tsx
+// WRONG — bar says 60% full while the caption says 60% left
+<ScCreditsUsageCard usageText="12,000 / 30,000" remainingText="60% Remaining" progress={60} />
+
+// RIGHT — one source of truth
+const pctUsed = Math.round((used / total) * 100);
+<ScCreditsUsageCard
+  usageText={`${used} / ${total}`}
+  remainingText={`${100 - pctUsed}% Remaining`}
+  progress={pctUsed}
+/>
+```
+
+**2. `progress` means "used" in production.** The live call site passes
+`progressPct = % used` while the caption shows `remainingPct`. The DS defaults
+(`60` + `"60% Remaining"`) imply the opposite — don't copy the defaults as a spec.
+
+**3. Long hover labels clip.** `.scButtonInstance` forces `width: 7.5rem` and
+`ScButton` is `height: 2.5rem; overflow: hidden` with no `white-space: nowrap`, so
+a long label wraps inside a 1.5rem-tall content box and gets cut. Keep
+`buyButtonHoverText` about as short as `"Buy credits"` (`"Pro plan required"` is
+already at the edge).
+
+**4. Disabled is not inert.** `buyButtonState="disabled"` stops the click, but the
+hover wrapper still fires `mouseenter`/`mouseleave`, so the label still swaps
+(intended) — don't rely on `disabled` to freeze the card visually.
+
+**5. `remainingText` is `nowrap` and squeezes the bar.** The bar is `flex: 1`; a
+long caption steals its width instead of wrapping. Keep it terse.
+
+**6. You cannot change the header or button icon.** `SiconCredits` is hardcoded in
+the header `ScPairtext`, and the `SiconHome` handed to `ScButton` never renders
+(no `styleVariant`), so the CTA is label-only.
+
+**7. `.buttonTooltip` in the CSS module is dead.** The stylesheet still carries a
+real absolutely-positioned tooltip (`opacity` transition, `z-index: 10`) that the
+TSX never renders — the component implements the label swap instead. Don't try to
+activate it from host CSS; nothing applies that class.
+
+**8. Missing `className` leaks `"undefined"` into the class list** (root is
+`styles.scCreditsUsageCard + " " + className`). Cosmetic, but visible in snapshots.
+
+**9. Trailing spaces in the DOM.** `usageText` and `remainingText` are rendered as
+`{value}` followed by a literal space; exact-match text assertions should trim.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:2052
+<ScCreditsUsageCard
+  usageLabel="Credits used"
+  usageText={usageText}
+  remainingText={
+    availableCredits != null
+      ? `${formatCredits(availableCredits)} (${remainingPct}%) Remaining`
+      : `${remainingPct}% Remaining`
+  }
+  buyButtonText="Buy credits"
+  buyButtonState={isFreePlan ? "disabled" : "default"}
+  buyButtonHoverText={isFreePlan ? "Pro plan required" : undefined}
+  progress={progressPct}
+  className="flex-1 min-w-0"
+  onBuyClick={() => setShowBuyCreditsModal(true)}
+/>
+```
+
+---
+
+## Related
+
+- `ScCreditsUsageCardMobile` — the mobile twin (fewer props: no button state, no
+  hover text).
+- `ScPlanDetailsCard` — the card it sits beside.
+- `ScProgressBar` — the bar it renders; use directly if you don't need the card.
+- `CreditWarningBanner` — the sidebar low-credits alert. ⚠️ Note the export has
+  **no `Sc` prefix** (`import { CreditWarningBanner } from "@streamoid/ui"`);
+  `ScCreditWarningBanner` does not exist.