@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScProfileV2Mobile.md

@@ -0,0 +1,216 @@
+---
+component: ScProfileV2Mobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, profile, avatar, initials, name, email, user, identity]
+related: [ScProfile, ScDp, ScTableListMobile, ScReferralCardMobile, ScProfilePopup]
+do_not_confuse_with: [ScProfile, ScProfileOptions, ScProfilePopup, ScProfileSettingsComp, ScDp, ScTableListMobile]
+---
+
+# ScProfileV2Mobile
+
+**A 40px avatar + name + email, as one mobile identity row.** Purely presentational:
+a circular image (or two-letter initials derived from `name`) on the left or right,
+with a two-line text block beside it. No menu, no chevron, no click behaviour.
+
+## TL;DR for agents
+
+- **Reach for it when:** a mobile sheet or header needs "who is signed in" as an
+  avatar plus name/email, and nothing else.
+- **Don't reach for it when:** you're in the desktop sidebar footer (→ `ScProfile`,
+  which has a `collapsed` mode), you need the profile *menu* (→ `ScProfileOptions` /
+  `ScProfilePopup`), or the row is a team-member list item with role and permission
+  icons (→ `ScTableListMobile`).
+- **Three things that will bite you:**
+  1. **It is `width: 288px`, fixed.** Not `100%`. It will not fill your container
+     and it will overflow anything narrower than 288px.
+  2. **`name` and `email` default to `"Chris Hemsworth"` / `"chris@kepler.com"`.**
+  3. `className` is concatenated unguarded, so omitting it puts the literal class
+     `undefined` on the root element.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfileV2Mobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScProfileV2Mobile name={user.name} email={user.email} imageUrl={user.avatarUrl} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | `"Chris Hemsworth"` | ⚠️ Demo default. Also the source of the initials **and** the `<img alt>`. |
+| `email` | `string` | `"chris@kepler.com"` | ⚠️ Demo default. Rendered as the grey 12px sub-line — it is really "subtitle", any string works. |
+| `imageUrl` | `string` | – | When set, renders `<img src>` (`object-fit: cover`). When unset, renders initials. No error fallback — see Gotcha 4. |
+| `dpPosition` | `"left"` \| `"right"` | `"left"` | Which side the avatar sits on. The text block always stays in the middle/flex-grow slot. |
+| `className` | `string` | – | Appended after internal classes. Unguarded concat — see Gotcha 3. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. This is the only way to attach `onClick`, `role`, `style`. |
+
+### How the initials are derived
+
+`name.split(" ").map(n => n[0]).join("").toUpperCase().slice(0, 2)`
+
+| `name` | Initials |
+|---|---|
+| `"Chris Hemsworth"` | `CH` |
+| `"chris"` | `C` |
+| `"Ana Maria De Souza"` | `AM` (sliced to 2) |
+| `""` | *(empty circle)* |
+| `"  Chris"` | `C` — empty segments contribute nothing |
+
+There is no `initials` prop. If you need to control the initials (workspace codes,
+single-letter avatars), use `ScDp` with `initial=` instead.
+
+### Recipes
+
+```tsx
+// Avatar on the right — e.g. a right-aligned mobile header slot
+<ScProfileV2Mobile
+  name={user.name}
+  email={user.email}
+  imageUrl={user.avatarUrl}
+  dpPosition="right"
+/>
+
+// Make it fill its container (the component is 288px by default)
+<ScProfileV2Mobile name={user.name} email={user.email} className="w-full" />
+
+// Make it tappable — the component gives you no semantics, so add them
+<ScProfileV2Mobile
+  name={user.name}
+  email={user.email}
+  role="button"
+  tabIndex={0}
+  onClick={openProfileSheet}
+  onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && openProfileSheet()}
+  className="w-full cursor-pointer"
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Intended for CXO's mobile surface: the header of a profile bottom sheet, the top of
+a mobile settings screen, or the identity line in a mobile menu — anywhere the
+desktop would use `ScProfile` in the sidebar footer.
+
+It composes nothing from the DS (its avatar is hand-rolled, not `ScDp`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need avatar + two text lines, on mobile, with no interaction.
+- The initials can be mechanically derived from the display name.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop sidebar footer profile (needs an expanded/collapsed mode) | `ScProfile` — has `collapsed`, `subText`, `profileImage` |
+| The profile **menu** (theme toggle, settings, log out) | `ScProfilePopup` / `ScProfileOptions` |
+| A whole profile settings screen | `ScProfileSettingsComp` |
+| Just an avatar, with controllable initials and a workspace/profile shape | `ScDp` (`variant="workspace" \| "profile"`, `size`, `initial`) |
+| Avatar upload / crop | `ScProfileImageUpdate` |
+| A team-member row with role badge + access icons | `ScTableListMobile` |
+| A referral row with a status badge and credits | `ScReferralCardMobile` |
+| A workspace (not a person) identity row | `ScWorkspaceSwitchMobileV2` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfile` — the desktop profile block; `subText` not `email`, `profileImage` not `imageUrl` | `ScProfileV2Mobile` uses different prop names for the same data |
+| `ScProfileOptions` — a single menu row inside a profile menu | Not an identity display |
+| `ScProfilePopup` — the whole floating profile menu | Not an identity display |
+| `ScDp` — the avatar primitive | `ScProfileV2Mobile` re-implements a 40px circle rather than composing `ScDp` |
+| `ScTableListMobile` — `name` + `email` + `role` + icon groups + `onRowClick` | The superset row; use it for lists |
+
+There is **no** `ScProfileV1Mobile`. The "V2" is a design-iteration marker, not a
+version you can choose.
+
+---
+
+## 4. Why to use it
+
+- **The one job it does well:** name/email truncation. Both lines get
+  `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` inside a
+  `flex: 1 0 0; min-width: 0` column, which is the exact combination hand-rolled
+  identity rows get wrong (long emails blowing out the row).
+- **`dpPosition` handles mirrored layouts** without you re-ordering DOM.
+- **Consistent 40px avatar and 14/12px type pair** with the rest of the mobile
+  family (`ScTableListMobile`, `ScReferralCardMobile` use the same metrics).
+
+Given the fixed width, treat this as a thin convenience —
+`ScDp` + two `<p>`s is a legitimate alternative if you need control.
+
+---
+
+## Gotchas
+
+**1. Fixed `width: 288px`.** The root is not fluid.
+
+```tsx
+// WRONG — stays 288px inside a full-width sheet, and overflows a 320px phone
+//         with side padding
+<ScProfileV2Mobile name={n} email={e} />
+
+// RIGHT
+<ScProfileV2Mobile name={n} email={e} className="w-full" />
+```
+
+**2. Demo defaults.** `name="Chris Hemsworth"`, `email="chris@kepler.com"`. Rendering
+it bare in a placeholder screen ships a fake person.
+
+**3. `className` is concatenated with `+ " " + className`, unguarded.** Omit it and
+the root renders `class="ScProfileV2Mobile_scProfileV2Mobile undefined"`. Harmless
+visually, but it breaks exact-`class` snapshot assertions and
+`[class="…"]` selectors.
+
+**4. A broken `imageUrl` shows a broken image, not initials.** There is no `onError`
+fallback — the initials branch is chosen purely on `imageUrl` being truthy. Validate
+the URL, or use `ScDp` (which falls back to `initial`).
+
+**5. No interaction semantics.** It's a plain `div`: no `role`, no `tabIndex`, no
+`cursor: pointer`. Attaching `onClick` via `...props` works but is invisible and
+keyboard-inaccessible until you add the rest yourself.
+
+**6. `email` is unvalidated free text** and is not rendered as a `mailto:` link.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it is exported from `@streamoid/ui` but **no** host app renders it,
+and it is not agent-runtime either — it is currently unused. Where it belongs is
+CXO's mobile settings/profile surface
+(`cxo-dashboard/src/app/components/mobile-settings-content.tsx`), which today shows
+identity with hand-rolled markup, and `mobile-teams-content.tsx`, which uses the
+richer `ScTableListMobile` for member rows.
+
+---
+
+## Related
+
+- `ScProfile` — the desktop sibling with a collapsed mode.
+- `ScDp` — the avatar primitive; use it when you need to control the initials.
+- `ScTableListMobile` — the mobile list-row superset (role + access icons + click).
+- `ScProfilePopup` / `ScProfileOptions` — the profile menu, not the identity block.
+- `ScWorkspaceSwitchMobileV2` — the workspace equivalent of this row.

package/dist/docs/ScProgressBar.md

@@ -0,0 +1,267 @@
+---
+component: ScProgressBar
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div (track) > div (fill)
+tags: [progress, progressbar, meter, percent, loading, upload, credits, determinate]
+related: [ScCreditsUsageCard, ScBadges, ScBeacon, ScSlider, ScButton]
+do_not_confuse_with: [ScSlider, ScBadges, ScCounter]
+used_by: [photogenix]
+---
+
+# ScProgressBar
+
+**The determinate progress track.** A pill-shaped 310px track with 8px of inner
+padding and a 6px amber fill whose width is set inline from `progress` (a
+percentage, clamped 0–100). That's the whole component — no label, no percentage
+text, no tone, no indeterminate mode.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have a known-percentage operation to show — an upload,
+  a batch render, credits consumed.
+- **Don't reach for it when:** the value is user-adjustable (→ `ScSlider`), you
+  don't know the percentage (there is no indeterminate mode — use a spinner, e.g.
+  `ScButton loading`), or you want the credits meter with its labels and CTA
+  (→ `ScCreditsUsageCard`, which already renders one).
+- **Four things that will bite you:**
+  1. `progress` defaults to **`50`** ⚠️ — forget it and the bar looks half-done.
+  2. Fixed `width: 19.375rem` (310px). It will **not** fill its parent until you
+     override the width.
+  3. The fill is **always amber** (`--alias-fill-warning-solid`). There is no
+     `tone` / `variant` — no green "complete", no red "failed".
+  4. No `role="progressbar"` and no `aria-value*`. Add them yourself via the spread.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProgressBar } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScProgressBar progress={72} />
+```
+
+Filling its container (what you almost always want):
+
+```tsx
+<ScProgressBar progress={72} style={{ width: "100%" }} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `progress` | `number` | `50` | ⚠️ Real default. A **percentage 0–100**, clamped internally with `Math.min(100, Math.max(0, progress))`. `NaN` produces `width: NaN%` (nothing painted). |
+| `className` | `string` | – | Concatenated unconditionally — see Gotcha 8. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the **track** div: `style`, `role`, `aria-*`, `title`, `data-*`, `onClick`. |
+
+### What it actually renders
+
+```html
+<div class="scProgressBar {className}" {...props}>
+  <!-- background --alias-fill-neutral-neutral · radius full · padding 8px
+       width 19.375rem (310px) · overflow:hidden -->
+  <div class="progressFill" style="width: {clamped}%">
+    <!-- background --alias-fill-warning-solid · radius full · height 0.375rem (6px) -->
+  </div>
+</div>
+```
+
+Total height is 22px (6px fill + 8px padding top and bottom).
+
+### Recipes
+
+```tsx
+// Percentage text beside the bar, bar flexes (the Photogenix idiom)
+<div className="flex items-center gap-2 w-[160px]">
+  <div className="flex-1 min-w-0">
+    <ScProgressBar progress={pct} style={{ width: "100%" }} />
+  </div>
+  <span className="w-10 text-right">{Math.round(pct)}%</span>
+</div>
+
+// Derive the percentage — pass 0–100, never a fraction
+<ScProgressBar progress={total > 0 ? Math.round((done / total) * 100) : 0} />
+
+// Accessible progress (the component gives you none of this)
+<ScProgressBar
+  progress={pct}
+  role="progressbar"
+  aria-valuenow={Math.round(pct)}
+  aria-valuemin={0}
+  aria-valuemax={100}
+  aria-label="Importing images"
+  style={{ width: "100%" }}
+/>
+
+// Recolour on completion — there is no `tone` prop, so do it in CSS
+<ScProgressBar progress={pct} className={pct >= 100 ? "done" : undefined} style={{ width: "100%" }} />
+// .done > div { background: var(--alias-fill-success-solid) !important; }
+```
+
+---
+
+## 2. Where to use it
+
+- **Photogenix batch + upload flows** — `studio/UploadZipModal` (import progress),
+  `studio/batchDetail/BatchExportDrawer` (export), `SPhComps/SPHCXBatchList`
+  (per-row render progress in the Shopify app). Photogenix is the only host consumer.
+- **`ScCreditsUsageCard`** composes one internally for the credits meter — that card
+  is the right entry point for anything credits-shaped, and it neutralises the fixed
+  width with `flex: 1 !important; width: unset !important`.
+- **Any long-running determinate job row** — feed imports, exports, bulk edits.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You know the **percentage complete** and it will change over time.
+- The operation is long enough that the user needs reassurance (uploads, renders,
+  imports).
+- You want the track/fill radius, height and neutral track colour to match the
+  credits meter.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The value is a control the user drags | `ScSlider` |
+| A bounded numeric input with −/+ | `ScCounter` |
+| You don't know the percentage (spinner / indeterminate) | `ScButton loading`, or your app's spinner — this bar has no indeterminate mode |
+| Credits remaining with labels + a "Buy credits" CTA | `ScCreditsUsageCard` / `ScCreditsUsageCardMobile` |
+| A pass/fail or state marker | `ScBadges` / `ScBeacon` |
+| A multi-step wizard indicator | `ScGuide`'s `stepLabel`, or `ScTabs` |
+| A count that isn't out of a total | `ScBadges` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSlider` — interactive range input | `ScProgressBar` is read-only output |
+| `ScCreditsUsageCard` — the whole credits meter (label + bar + remaining text + CTA) | `ScProgressBar` is just the bar |
+| A styled `<progress>` element | This is two divs with an inline width; no native semantics |
+
+---
+
+## 4. Why to use it
+
+- **Clamping is already done.** `Math.min(100, Math.max(0, progress))` means a
+  server sending `104` or `-3` cannot overflow the track or produce a negative
+  width — the classic hand-rolled-bar bug.
+- **Tokenised track and fill.** `--alias-fill-neutral-neutral` behind
+  `--alias-fill-warning-solid` stay distinguishable in both themes; a hardcoded
+  `#eee` track vanishes in dark mode and a hardcoded dark track vanishes in light.
+- **`overflow: hidden` + `border-radius: full` on the track** means the fill's own
+  rounded ends are clipped correctly at both extremes, instead of the fill's corners
+  poking outside the track.
+- **It matches the credits meter for free** — the same component is inside
+  `ScCreditsUsageCard`, so an upload bar and a credits bar look like siblings.
+- **One line of change surface.** Height, radius and colour live in one CSS module,
+  not scattered across every progress UI in three apps.
+
+---
+
+## Gotchas
+
+**1. `progress` defaults to 50.** A bar rendered with no props reads "half done".
+
+**2. It's a percentage, not a fraction.** `progress={0.75}` renders a 0.75% sliver.
+
+```tsx
+// WRONG
+<ScProgressBar progress={done / total} />
+
+// RIGHT
+<ScProgressBar progress={total > 0 ? (done / total) * 100 : 0} />
+```
+
+**3. Fixed `width: 19.375rem` — it does not fill its parent.** This is the most
+common complaint. Two fixes, both in use:
+
+```tsx
+// via the spread
+<ScProgressBar progress={pct} style={{ width: "100%" }} />
+```
+
+```css
+/* via className, when the bar must flex inside a row (what ScCreditsUsageCard does) */
+.barInstance { flex: 1 !important; width: unset !important; }
+```
+
+The `!important` is needed because the module's `width` is on the same element.
+
+**4. `progress={100}` never looks completely full.** The inline width is a
+percentage of the **padded content box**, and the track carries `padding: 0.5rem`,
+so 8px of track always remains visible at each end. Don't use "the bar is flush" as
+your completion cue — show a label or swap in a `ScBadges` / `ScBeacon`.
+
+**5. The fill is amber for every value.** `--alias-fill-warning-solid`, hardcoded.
+There is no `tone`, `variant` or `color` prop, so a green "complete" or a red
+"failed" bar requires your own CSS override on the child div.
+
+**6. No a11y whatsoever.** Plain divs — no `role="progressbar"`, no `aria-valuenow`,
+no accessible name. Screen readers announce nothing. Pass the aria via the spread
+(see Recipes); it lands on the track, which is the right element.
+
+**7. No transition on `width`.** Values jump. If you poll progress at long
+intervals, add `transition: width .3s ease` to the fill via a `className`
+descendant selector.
+
+**8. `className` is concatenated unconditionally.** Omit it and the class attribute
+contains the literal string `undefined`. Cosmetic; breaks exact-match snapshots.
+
+**9. Fixed 22px total height, no `size` prop.** A thin 2px inline bar is not
+available; override `padding` and the child's `height` if you need one.
+
+**10. `NaN` renders nothing, silently.** `total = 0` in a naive
+`done / total * 100` gives `NaN`, `Math.min/max` propagate it, and the fill gets
+`width: NaN%`. Guard the divisor.
+
+---
+
+## In the wild
+
+```tsx
+// photogenix_v2  shopify/client/src/components/SPhComps/SPHCXBatchList.tsx:181
+<div className="shrink-0 w-[160px] flex items-center gap-2">
+  <div className="flex-1 min-w-0">
+    <ScProgressBar
+      progress={progressPercent}
+      style={{ width: '100%' }}
+    />
+  </div>
+  <span className="w-10 shrink-0 text-right text-[14px] leading-[20px]">
+    {Math.round(progressPercent)}%
+  </span>
+</div>
+```
+
+```tsx
+// photogenix_v2  dashboard/client/src/components/studio/UploadZipModal.tsx:513
+<ScProgressBar
+  progress={importProgress.total > 0
+    ? Math.round((importProgress.completed / importProgress.total) * 100)
+    : 0}
+/>
+```
+
+---
+
+## Related
+
+- `ScCreditsUsageCard` / `ScCreditsUsageCardMobile` — the credits meter; embeds this bar and shows how to unpin its width.
+- `ScSlider` — the interactive range sibling.
+- `ScCounter` — bounded numeric stepper.
+- `ScBadges` / `ScBeacon` — for the terminal state once progress hits 100.
+- `ScButton` (`loading`) — the indeterminate case this component doesn't cover.