@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScProfilePopup.md

@@ -0,0 +1,396 @@
+---
+component: ScProfilePopup
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [profile-menu, profile-dropdown, account-menu, logout, theme-switcher, credits, switch-workspace, panel, slots]
+related: [ScProfile, ScWorkspace, ScMenuOptions, ScTabSwitcher, ScWorkspaceSwitchCard, StreamoidSidebar]
+do_not_confuse_with: [ScProfileOptions, ScProfileSettingsComp, ScProfile, ScPopUpMenu, ScAppSwitchPanel]
+used_by: [catalogix]
+---
+
+# ScProfilePopup
+
+**The profile dropdown panel — the whole thing, propped and wired.** Identity header
+with a logout button, a workspace block with a credits pill and "Switch workspace", a
+four-row menu (Teams / Billing / All settings / What's new + version), and a
+three-way theme switcher. It is the **panel body only**: it renders no overlay, owns
+no open state, and forwards its ref so the host can position it and detect
+outside clicks — the same split `StreamoidSidebar` uses for `switchPanel`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the app's profile/account menu. This is the one.
+- **Don't reach for it when:** you want the static Figma export of the same node
+  (→ `ScProfileOptions`, legacy), the account **form** (→ `ScProfileImageUpdate` +
+  `ScTextField`), or a generic anchored popover (→ `ScPopUpMenu`).
+- **Five things that will bite you:**
+  1. **No overlay, no open state, no dismissal.** You render it conditionally,
+     position it, and wire outside-click yourself via the forwarded `ref`.
+  2. Omit `avatar` / `workspaceImage` and the nested `ScProfile` / `ScWorkspace`
+     fall back to `profileImage="profile-image0.png"` → **two broken-image glyphs**.
+  3. Identity defaults are placeholders: **"Chris Hemsworth" / "chris@kepler.com" /
+     "Kepler workspace" / "Admin"**.
+  4. `themeMode` is **controlled** — no internal state. Without
+     `onThemeModeChange` the tabs are decorative.
+  5. Width is `20rem` via the `--sc-profile-popup-width` custom property, and every
+     **direct child gets `width: unset !important`** — including whatever you put in
+     the slots.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfilePopup, type ScProfilePopupThemeMode } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScProfilePopup
+  name={user.name}
+  email={user.email}
+  avatar={user.avatarUrl}
+  workspaceName={ws.name}
+  userRole={ws.role}
+  onLogout={logout}
+/>
+```
+
+Wired as a real dropdown (the host owns open/close):
+
+```tsx
+const panelRef = useRef<HTMLDivElement>(null);
+
+useEffect(() => {
+  if (!open) return;
+  const onDown = (e: MouseEvent) => {
+    if (!panelRef.current?.contains(e.target as Node)) setOpen(false);
+  };
+  document.addEventListener("mousedown", onDown);
+  return () => document.removeEventListener("mousedown", onDown);
+}, [open]);
+
+{open && (
+  <div style={{ position: "absolute", bottom: 8, left: 8, zIndex: 50 }}>
+    <ScProfilePopup ref={panelRef} role="menu" aria-label="Profile menu" /* …data… */ />
+  </div>
+)}
+```
+
+### Props
+
+**Identity (header)**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | `"Chris Hemsworth"` | ⚠️ Real default. First header line. |
+| `email` | `string` | `"chris@kepler.com"` | ⚠️ Real default. Second header line (passed as `ScProfile`'s `subText`). |
+| `avatar` | `string` | – | ⚠️ Spread only when truthy; omit it and `ScProfile`'s broken `profile-image0.png` default renders. Forced to 32px. |
+| `onProfileClick` | `() => void` | – | Makes the identity block a real `<button>` **and** enables its hover fill + focus ring. Without it the block is a non-interactive div by design. |
+| `onLogout` | `() => void` | – | The error-coloured icon button top-right. |
+| `logoutLabel` | `string` | `"Log out"` | Its `aria-label` **and** `title`. Not visible text. |
+| `showLogout` | `boolean` | `true` | ⚠️ Defaults on. Set `false` to hide the icon. |
+| `headerActions` | `ReactNode` | – | **SLOT** — extra trailing controls, in a row left of the logout button. |
+
+**Workspace block**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `workspaceName` | `string` | `"Kepler workspace"` | ⚠️ Real default. |
+| `userRole` | `string` | `"Admin"` | ⚠️ Real default. Free text, tertiary grey — no `ScRole` colour semantics. |
+| `workspaceImage` | `string` | – | ⚠️ Spread only when truthy; same broken-default trap as `avatar`. Forced to 32px. |
+| `credits` | `ReactNode` | – | Credits pill (icon + value). **Omit to hide the pill entirely**; `credits={0}` still renders (only `null`/`undefined` hide it). |
+| `onSwitchWorkspace` | `() => void` | – | The "Switch workspace" button. |
+| `switchWorkspaceLabel` | `string` | `"Switch workspace"` | Visible button label. |
+| `showWorkspace` | `boolean` | `true` | Hides the identity+credits row only. |
+| `showSwitchWorkspace` | `boolean` | `true` | Hides the button only. |
+| `workspaceContent` | `ReactNode` | – | **SLOT** — appended below "Switch workspace", inside the 8px inset rail. |
+
+**Menu rows**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `onTeams` / `onBilling` / `onSettings` / `onWhatsNew` | `() => void` | – | Row handlers. A row with no handler still renders and still looks clickable. |
+| `teamsLabel` | `string` | `"Teams"` | |
+| `billingLabel` | `string` | `"Billing"` | |
+| `settingsLabel` | `string` | `"All settings"` | |
+| `whatsNewLabel` | `string` | `"What's new"` | |
+| `version` | `string` | – | Trailing version tag on the What's-new row. Its presence flips that row to `ScMenuOptions` `variant="with-v"`; absent, no version shows. Pass the `"v"` yourself (`` `v${APP_VERSION}` ``). |
+| `showTeams` / `showBilling` / `showSettings` / `showWhatsNew` | `boolean` | `true` | ⚠️ All default **on**. |
+| `menuContent` | `ReactNode` | – | **SLOT** — appended below the built-in rows, same stack and gap. |
+
+**Theme switcher, footer, root**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `themeMode` | `"system"` \| `"light"` \| `"dark"` | `"system"` | Controlled. Exported as `ScProfilePopupThemeMode`. |
+| `onThemeModeChange` | `(mode) => void` | – | Fires on click/Enter/Space. Without it the tabs do nothing. |
+| `showThemeSwitcher` | `boolean` | `true` | |
+| `preFooterContent` | `ReactNode` | – | **SLOT** — between the menu group and the theme switcher (e.g. `CreditWarningBanner`). |
+| `children` | `ReactNode` | – | **SLOT** — after the theme switcher, at the very bottom. |
+| `className` | `string` | – | Appended only when provided (this component does it correctly). |
+| `ref` | `Ref<HTMLDivElement>` | – | The **panel root** — use it for placement and outside-click checks. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `role`, `aria-label`, `style`, `data-*` spread onto the root. |
+
+### Which blocks render
+
+| Block | Rendered when | Divider above it |
+|---|---|---|
+| Header | always | — |
+| Workspace | `showWorkspace \|\| showSwitchWorkspace \|\| workspaceContent` | yes |
+| Menu | `showTeams \|\| showBilling \|\| showSettings \|\| showWhatsNew \|\| menuContent` | yes |
+| `preFooterContent` | when passed | no |
+| Theme switcher | `showThemeSwitcher` | no |
+| `children` | when passed | no |
+
+### Recipes
+
+```tsx
+// Full production wiring
+<ScProfilePopup
+  ref={panelRef}
+  role="menu"
+  aria-label="Profile menu"
+  name={user.name || user.email}
+  email={user.email}
+  avatar={user.imageUrl || undefined}
+  onProfileClick={() => go("account")}
+  onLogout={() => void logout()}
+  workspaceName={ws.name}
+  userRole={ws.role}
+  workspaceImage={ws.imageUrl || undefined}
+  credits={creditsLoading ? "…" : credits.toLocaleString()}
+  onSwitchWorkspace={openWorkspaceSwitcher}
+  onTeams={() => go("team")}
+  onBilling={() => go("billing")}
+  onSettings={() => go("account")}
+  onWhatsNew={() => window.open(CHANGELOG_URL, "_blank")}
+  version={`v${APP_VERSION}`}
+  themeMode={themePreference}
+  onThemeModeChange={setThemePreference}
+/>
+
+// Trimmed panel: identity + logout + theme only
+<ScProfilePopup
+  name={user.name}
+  email={user.email}
+  avatar={user.avatarUrl}
+  showWorkspace={false}
+  showSwitchWorkspace={false}
+  showTeams={false}
+  showBilling={false}
+  showSettings={false}
+  showWhatsNew={false}
+  onLogout={logout}
+  themeMode={theme}
+  onThemeModeChange={setTheme}
+/>
+
+// Extra rows + a banner, via slots (each stack stretches its children)
+<ScProfilePopup
+  /* …identity… */
+  menuContent={<ScMenuOptions icon={<SiconCatalog size={24} />} text="Catalogs" />}
+  preFooterContent={<CreditWarningBanner /* … */ />}
+/>
+
+// Stretch to a container instead of the 320px default
+<ScProfilePopup style={{ ["--sc-profile-popup-width" as string]: "100%" }} /* … */ />
+```
+
+---
+
+## 2. Where to use it
+
+- **Sidebar profile footer** — anchored above the profile row in the desktop shells.
+  Catalogix renders it from `app/components/AppSettingsPopup`, which its own header
+  comment describes as replacing ~430 lines of hand-assembled panel.
+- **Top-bar avatar menus** — same panel, positioned bottom-right of the trigger.
+- Pair `onSwitchWorkspace` with the workspace-switch modal
+  (`ScWorkspaceSwitchCard` rows) rather than nesting a switcher inside the popup.
+
+Composed internally from `ScProfile`, `ScWorkspace`, `ScHDivider`, `ScMenuOptions`,
+`ScButton` and `ScTabSwitcher`/`ScTabComp` — do not rebuild those inside your slots.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need the standard profile menu with any subset of its rows — the `show*` flags
+  let you drop blocks without forking the panel.
+- You want theme switching that matches the tokens contract (write the mode to your
+  own store; the host turns it into `<html data-theme>`).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Static Figma-parity screenshot of this node | `ScProfileOptions` (legacy, className-only) |
+| The account settings **form** | `ScProfileImageUpdate` + `ScTextField` |
+| A generic anchored menu of arbitrary options | `ScPopUpMenu` + `ScMenuOptions` |
+| The cross-product app switcher | `ScAppSwitchPanel` (pass via `StreamoidSidebar`'s `switchPanel`) |
+| A workspace **list/switcher** UI | `ScWorkspaceSwitchCard` rows in your own modal |
+| Just the identity row | `ScProfile` |
+| Mobile profile surface | `ScProfileV2Mobile` + the `*Mobile` family |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfileOptions` — the static export of this very Figma node (no props, no callbacks) | `ScProfilePopup` is the live one |
+| `ScProfileSettingsComp` — the account form card | this is the menu |
+| `ScProfile` — the identity row this renders as its header | this is the whole panel |
+| `ScAppSwitchPanel` — switches **products**, not accounts | different panel, different slot in the sidebar |
+| `ScPopUpMenu` — owns anchoring/positioning | this owns neither; the host positions it |
+
+And on the other axis: this is a **panel body**, not a popover. No `open` prop, no
+portal, no backdrop, no Escape handling. If you wanted something that manages its own
+visibility, you want your own conditional render (or `ScPopUpMenu`).
+
+---
+
+## 4. Why to use it
+
+- **Every row is already keyboard-reachable.** `ScMenuOptions` and `ScTabComp` are
+  divs; this component adds `role="button"`, `tabIndex={0}` and Enter/Space handling to
+  each row, `role="radiogroup"`/`role="radio"`+`aria-checked` to the theme tabs, and
+  `:focus-visible` rings throughout. Hand-assembling the panel loses all of it.
+- **Two icon-colour bugs are fixed here, not in your app.** `ScMenuOptions` colours
+  only its label (its icon is a sibling that inherits `color`), and `ScTabComp`
+  recolours only `.tabText` when active — so a naive assembly renders muted icons
+  beside near-white labels and a light icon on a light active tab. The panel drives
+  both from `currentColor`.
+- **Figma-exact geometry without borders that shift.** The panel, logout button and
+  credits pill use `box-shadow: inset` instead of borders because Figma strokes these
+  frames on the inside — a real border would add a pixel and push every divider out
+  of alignment.
+- **Slots that lay out correctly for free.** `.scProfilePopup > *` and each stack
+  force `align-self: stretch; width: unset`, so nested DS components (which carry
+  intrinsic widths like `ScMenuOptions`' 200px) stretch like the built-in rows with
+  no extra CSS.
+- **One panel, four apps.** Row labels, visibility and version are props, so per-app
+  differences don't need a fork.
+
+---
+
+## Gotchas
+
+**1. It renders no overlay and owns no state.** There is no `open`, no backdrop, no
+Escape key, no portal. Conditionally render it, position the wrapper, and use the
+forwarded ref for outside-click.
+
+```tsx
+// WRONG — always visible, unpositioned, undismissable
+<ScProfilePopup name={user.name} />
+
+// RIGHT
+{open && <div style={{ position: "absolute", bottom: 8, left: 8, zIndex: 50 }}>
+  <ScProfilePopup ref={panelRef} name={user.name} />
+</div>}
+```
+
+**2. Missing `avatar`/`workspaceImage` = broken images.** Both are spread
+conditionally (`{...(avatar ? { profileImage: avatar } : {})}`), so a falsy value
+lets `ScProfile`/`ScWorkspace`'s `"profile-image0.png"` default through. Pass
+`|| undefined` — not `|| ""` — and prefer a real fallback URL.
+
+```tsx
+// WRONG — "" is falsy, so the broken default renders anyway
+<ScProfilePopup avatar={user.imageUrl || ""} />
+
+// RIGHT
+<ScProfilePopup avatar={user.imageUrl || undefined} />
+```
+
+**3. Placeholder identity ships if you forget a prop.** "Chris Hemsworth",
+"chris@kepler.com", "Kepler workspace", "Admin". Pass `""` deliberately when a value
+is genuinely unknown — the hosts do exactly that.
+
+**4. All eight `show*` flags default to `true`.** Every block renders unless you
+explicitly turn it off, and a row with no handler still looks clickable
+(`cursor: pointer` comes from `.menuOptionInstance`, not from the handler). Either
+wire the handler or set the flag to `false`.
+
+**5. `themeMode` is controlled.** No internal state. Clicking a tab calls
+`onThemeModeChange` and nothing else — the active tab only moves when you re-render
+with a new `themeMode`.
+
+**6. `width` overrides need the custom property.** The panel is
+`width: var(--sc-profile-popup-width, 20rem)`. An inline `style={{ width: "100%" }}`
+does win (inline beats the class), but the documented lever is the property:
+`style={{ ["--sc-profile-popup-width"]: "100%" }}`. Note the panel's `> *` rule
+applies `width: unset !important` to **children**, so a child cannot set its own width
+— that is deliberate, but it means a fixed-width component in a slot will stretch.
+
+**7. `credits` uses a `!= null` check.** `credits={0}` renders a pill reading "0";
+only `null`/`undefined` hide it. Pass `undefined` while loading, or a placeholder
+string like `"…"` (what Catalogix does).
+
+**8. `logoutLabel` is not visible text.** It is the `aria-label` and `title` of an
+icon-only button. Setting it does not add a "Log out" row — the design has none.
+
+**9. `userRole` is unstyled free text.** No admin/member colouring here; if you want
+the coloured pill, use `ScRole` in `workspaceContent`.
+
+**10. The "Switch workspace" hover fill is darker than its resting fill.** That is
+per the design node, implemented deliberately (`neutralactive` → `neutralselected`),
+and it is restated with `!important` because the resting `!important` would otherwise
+kill `ScButton`'s own hover. Don't "fix" it without a design decision.
+
+**11. `backdrop-filter: blur(42px)` needs something behind it.** Over an opaque host
+background the blur is invisible; the panel then reads as flat `surface-subtle`.
+
+**12. `role="menu"` is yours to add.** The root is a plain `div` — the hosts pass
+`role="menu"` and `aria-label` through the spread. Note that the rows are
+`role="button"`, not `role="menuitem"`, so a strict `menu`/`menuitem` pairing is not
+what you get.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/AppSettingsPopup/index.jsx:75
+<ScProfilePopup
+  data-theme="Mode 1"
+  role="menu"
+  aria-label="Profile menu"
+  style={{ width: "100%" }}
+  name={(userData && (userData.name || userData.email)) || ""}
+  email={(userData && userData.email) || ""}
+  avatar={userData?.imageUrl || undefined}
+  onProfileClick={() => goSettings("account")}
+  onLogout={() => { logoutUser().then(() => clearUserData()); }}
+  workspaceName={selectedWorkspace?.name || ""}
+  userRole={selectedWorkspace?.role || ""}
+  workspaceImage={selectedWorkspace?.imageUrl || undefined}
+  credits={creditsLabel}
+  onSwitchWorkspace={() => showWorkspaceList()}
+  onTeams={() => goSettings("team")}
+  onBilling={() => goSettings("billing")}
+  onSettings={() => goSettings("account")}
+  onWhatsNew={() => { onClose(); window.open(CHANGELOG_URL, "_blank"); }}
+  version={appVersion ? `v${appVersion}` : ""}
+  themeMode={themePreference}
+  onThemeModeChange={setThemePreference}
+/>
+```
+
+---
+
+## Related
+
+- `ScProfileOptions` — the legacy static export of the same Figma node; migrate off it.
+- `ScProfile` / `ScWorkspace` — the two identity rows it composes (`ScWorkspace` is not exported).
+- `ScMenuOptions` — one menu row; use it in `menuContent` for extra rows.
+- `ScTabSwitcher` / `ScTabComp` — the theme switcher pair.
+- `ScWorkspaceSwitchCard` — the rows for the modal `onSwitchWorkspace` should open.
+- `CreditWarningBanner` — the usual `preFooterContent`.
+- `StreamoidSidebar` — the shell this panel is anchored inside; same host-owns-visibility pattern as `switchPanel`.

package/dist/docs/ScProfileSettingsComp.md

@@ -0,0 +1,250 @@
+---
+component: ScProfileSettingsComp
+package: "@streamoid/ui"
+category: profile
+status: legacy
+renders: div
+tags: [profile-settings, account-form, first-name, last-name, email, figma-export, static, read-only]
+related: [ScProfileImageUpdate, ScTextField, ScSettingsTabComp, ScProfilePopup, ScAppField]
+do_not_confuse_with: [ScProfileOptions, ScProfilePopup, ScProfileImageUpdate, ScProfile, ScSettingsTabComp]
+---
+
+# ScProfileSettingsComp
+
+**A static Figma scaffold of the account-settings card, not a working form.** It
+renders `ScProfileImageUpdate` beside three `ScTextField`s (First Name / Last Name /
+Email ID) — but the three values arrive as **placeholders** on `state="filled"`
+fields, there is no `onChange` anywhere, and `ScProfileImageUpdate` is rendered with
+no props at all. Nothing it renders can be edited or submitted.
+
+## TL;DR for agents
+
+- **Reach for it when:** you want a pixel reference for the account card's layout
+  (24px padding, avatar column + 16px-gapped field stack).
+- **Don't reach for it when:** you are building the real settings screen — compose
+  `ScProfileImageUpdate` + `ScTextField` yourself. That is what CXO and
+  `@streamoid/settings` do.
+- **Four things that will bite you:**
+  1. `firstName` / `lastName` / `email` are passed as `placeholderFilled`, so they
+     are **placeholder text, not input values**. Nothing you type is kept.
+  2. There is **no `onChange`, no `onSubmit`, no `onUpload`, no `onDelete`** — no
+     callback of any kind.
+  3. Defaults are placeholder identity: **"Chris" / "Hemsworth" /
+     "chris@kepler.com"**.
+  4. The email field renders a hardcoded **`SiconLock`** on the right and the two
+     name fields render **no icon at all** (`tfGroup="none"` discards the icons the
+     component passes them). None of it is configurable.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfileImageUpdate, ScTextField } from "@streamoid/ui"; // ← what to build with
+import { ScProfileSettingsComp } from "@streamoid/ui"; // legacy scaffold
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+The whole API:
+
+```tsx
+<ScProfileSettingsComp
+  firstName={user.firstName}
+  lastName={user.lastName}
+  email={user.email}
+/>
+```
+
+The working equivalent — the same layout with real state:
+
+```tsx
+<div style={{
+  display: "flex", gap: "1.5rem", padding: "1.5rem",
+  borderRadius: "1rem", background: "var(--alias-surface-base)",
+}}>
+  <ScProfileImageUpdate
+    imageUrl={user.avatarUrl}
+    initials={initials}
+    onUpload={(file) => void uploadAvatar(file)}
+    onDelete={() => void removeAvatar()}
+  />
+  <div style={{ display: "flex", flexDirection: "column", gap: "1rem", flex: 1 }}>
+    <div style={{ display: "flex", gap: "1rem" }}>
+      <ScTextField
+        label="First Name"
+        value={firstName}
+        onChange={(e) => setFirstName(e.target.value)}
+        style={{ flex: 1 }}
+      />
+      <ScTextField
+        label="Last Name"
+        value={lastName}
+        onChange={(e) => setLastName(e.target.value)}
+        style={{ flex: 1 }}
+      />
+    </div>
+    <ScTextField label="Email ID" value={email} state="disabled" readOnly />
+  </div>
+</div>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `firstName` | `string` | `"Chris"` | ⚠️ Real default. Passed as `placeholderFilled` to the First Name field — **placeholder, not value**. |
+| `lastName` | `string` | `"Hemsworth"` | ⚠️ Real default. Same placeholder treatment. |
+| `email` | `string` | `"chris@kepler.com"` | ⚠️ Real default. Same placeholder treatment. |
+| `className` | `string` | – | Appended (concatenated unconditionally — a literal `undefined` class when omitted). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the card root div. |
+
+No callbacks, no `avatar`/`imageUrl`, no labels, no field state. That is the whole
+surface.
+
+### What it renders (fixed)
+
+| Region | Fixed content |
+|---|---|
+| Left column | `ScProfileImageUpdate` with **no props** → no image, no initials, dead upload/delete |
+| Field row | `ScTextField` "First Name" + "Last Name", `state="filled"`, `tfGroup="none"` → **no icons rendered** |
+| Below | `ScTextField` "Email ID", **no `state`** (so default, not `filled`), `tfGroup` left at its `"icon-right"` default → renders `SiconLock` on the right only |
+| Card | `surface-base`, `radius: 1rem`, `padding: 1.5rem`, row layout, `gap: 1.5rem` |
+
+### Recipes
+
+There is nothing to configure — see the working equivalent above.
+
+---
+
+## 2. Where to use it
+
+Nowhere new. The real account screen lives in **`@streamoid/settings`**, which CXO
+consumes; its avatar control is `ScProfileImageUpdate` used directly (CXO also
+renders `ScProfileImageUpdate` itself in `src/app/components/mobile-settings-content.tsx:252`).
+Keep this component only as a layout reference next to `ScSettingsTabComp` /
+`ScSettingsNav`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need the Figma measurements of the account card and nothing else.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A real, editable account form | `ScProfileImageUpdate` + `ScTextField` composed by hand (see recipe) |
+| Just the avatar upload/delete control | `ScProfileImageUpdate` |
+| A labelled field bound to app config | `ScAppField` |
+| The settings page tab strip / left nav | `ScSettingsTabComp` / `ScSettingsNav` |
+| The profile **dropdown menu** | `ScProfilePopup` |
+| A read-only identity row | `ScProfile` |
+| Mobile settings surface | `ScProfileV2Mobile` + the `*Mobile` field set |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfileOptions` / `ScProfilePopup` — the profile **menu** panel | this is the **form** card |
+| `ScProfileImageUpdate` — the avatar upload control (real callbacks) | this wraps it but passes it nothing |
+| `ScProfile` — avatar + name + subtext row | this is a settings card |
+| `ScSettingsTabComp` — the settings page scaffold (tabs) | this is one card inside such a page |
+
+Four `ScProfile*` names, four different things: **`ScProfile`** = identity row ·
+**`ScProfileOptions`** = static menu · **`ScProfilePopup`** = live menu ·
+**`ScProfileSettingsComp`** = static form card.
+
+---
+
+## 4. Why to use it
+
+The only durable value is the **layout spec** it encodes, which you should copy into
+your own composition:
+
+- Card: `--alias-surface-base`, `border-radius: 1rem`, `padding: var(--spacing-6xl)`
+  (1.5rem), horizontal flex, `gap: 1.5rem`.
+- Avatar column `flex-shrink: 0`; field column `flex: 1`, vertical, `gap: 1rem`.
+- Name fields side by side, each `flex: 1; width: unset`, `gap: var(--spacing-3xl)`
+  (1rem); email field stretched full width.
+
+Everything else — field behaviour, validation, upload — you have to supply, at which
+point composing the two primitives directly is strictly less work than fighting this
+wrapper.
+
+---
+
+## Gotchas
+
+**1. The values are placeholders.** `placeholderFilled={firstName}` puts your data in
+`ScTextField`'s placeholder slot on a `state="filled"` field. It looks like a value
+and behaves like a hint; it is never an input value and it never round-trips.
+
+```tsx
+// WRONG — looks bound, saves nothing, and typing does not update state
+<ScProfileSettingsComp firstName={form.firstName} lastName={form.lastName} email={form.email} />
+
+// RIGHT — own the state
+<ScTextField label="First Name" value={form.firstName} onChange={(e) => set("firstName", e.target.value)} />
+```
+
+**2. `ScProfileImageUpdate` gets no props.** No `imageUrl`, no `initials`, no
+`onUpload`, no `onDelete` — the avatar renders empty and the upload/delete affordances
+are inert.
+
+**3. Placeholder identity ships to users.** Omit all three props and the card reads
+"Chris / Hemsworth / chris@kepler.com".
+
+**4. Most of the icons it passes are dead, and the one that renders is hardcoded.**
+All three fields are handed a `SiconBolt` for both slots, but `ScTextField` gates
+icons on `tfGroup`: the name fields use `tfGroup="none"` so **neither icon renders**,
+and the email field leaves `tfGroup` at its `"icon-right"` default so **only
+`SiconLock`** renders. There is no prop to change or remove it. Passing decorative
+bolts to name fields is itself a sign this is an unfinished export.
+
+**5. Labels are hardcoded English** — "First Name", "Last Name", "Email ID". No label
+props; unusable in a localised surface without changing the DS.
+
+**6. The email field's `state` is inconsistent.** The two name fields are
+`state="filled"`; the email field is left at `ScTextField`'s default. The three fields
+therefore do not render as a matched set.
+
+**7. `className` is concatenated unconditionally** → `class="scProfileSettingsComp undefined"`
+when omitted.
+
+**8. The card has no `max-width` and is a `row` flex.** In a narrow settings column
+the avatar and fields will squeeze rather than wrap.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+No app renders it. The primitive it wraps is used directly:
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-settings-content.tsx:252
+<ScProfileImageUpdate
+```
+
+The real desktop account screen lives in `@streamoid/settings`
+(`packages/settings/src/`), which composes `ScProfileImageUpdate` and `ScTextField`
+itself. If this component is ever revived it belongs there, behind real
+`value`/`onChange` props.
+
+---
+
+## Related
+
+- `ScProfileImageUpdate` — the avatar control, with `imageUrl`/`initials`/`onUpload`/`onDelete`.
+- `ScTextField` — the field primitive; use `value` + `onChange`, not `placeholderFilled`.
+- `ScAppField` — label + control unit for settings/config forms.
+- `ScSettingsTabComp` / `ScSettingsNav` — the settings page scaffold this card sits in.
+- `ScProfilePopup` — the profile menu (different component entirely).