@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScProfileImageUpdate.md

@@ -0,0 +1,261 @@
+---
+component: ScProfileImageUpdate
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [avatar, profile, picture, upload, delete, initials, settings, image]
+related: [ScDp, ScIntialProfileCover, ScImageField, ScFileField, ScProfileSettingsComp]
+do_not_confuse_with: [ScImageField, ScDp, ScIntialProfileCover, ScProfile, ScProfileSettingsComp]
+used_by: [cxo]
+---
+
+# ScProfileImageUpdate
+
+**The avatar editor block at the top of a profile settings screen.** A 100px circle
+(the image, or initials on a grey disc) with an upload / delete icon-button pair
+underneath, split by a vertical divider. Nothing else — no label, no filename, no
+crop.
+
+## TL;DR for agents
+
+- **Reach for it when:** a **profile settings** screen needs "change your picture" —
+  circle above, two icon buttons below.
+- **Don't reach for it when:** you want a labelled rectangular image field in a form
+  (→ `ScImageField`), any non-image file (→ `ScFileField`), or you're only *showing*
+  an avatar (→ `ScDp`).
+- **Four things that will bite you:**
+  1. The **delete button always renders**, even with no image. Gate `onDelete`
+     yourself or the user "deletes" nothing and you fire a request.
+  2. Both buttons are **unlabelled** `ScButton`s → `div[role="button"]` with no
+     `aria-label`. Add your own via a wrapper; you can't pass one through.
+  3. `accept="image/*"` is **hardcoded**; there is no `accept`, no size limit, no
+     loading/uploading state.
+  4. **Fixed 7.5rem wide / 6.25rem circle.** No `size` prop (unlike `ScDp`).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfileImageUpdate } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScProfileImageUpdate
+  imageUrl={profileImage}
+  initials={profileInitials}
+  onUpload={handleProfileImageUpload}
+  onDelete={handleProfileImageDelete}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `imageUrl` | `string` | – | Remote URL or blob URL. Truthy → `<img alt="profile">`; falsy → the initials disc. **No `onError` fallback** — a broken URL shows a broken image, it does not fall back to initials (`ScDp` does). |
+| `initials` | `string` | `""` | Shown only when `imageUrl` is falsy. Default is an **empty grey circle** — pass 1–2 characters. |
+| `onUpload` | `(file: File) => void` | – | Fires with the chosen `File`. The input's value is reset afterwards, so re-picking the same file fires again. |
+| `onDelete` | `() => void` | – | The trash button. **Always clickable** — see Gotcha 1. |
+| `className` | `string` | – | Concatenated after the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div` — `style`, `data-*`, `aria-*`, `onClick` all work. (This one *does* extend `HTMLAttributes`; `ScImageField` and `ScFileField` do not.) |
+
+### What renders in each state
+
+| `imageUrl` | Circle | Buttons |
+|---|---|---|
+| truthy | `<img>` cropped `object-fit: cover` to a 6.25rem circle | ⬆ upload · │ · 🗑 delete |
+| falsy | `initials` centred on `--alias-fill-neutral-neutralselected`, 1.75rem / weight 500 | ⬆ upload · │ · 🗑 delete (still) |
+
+### Recipes
+
+```tsx
+// The standard settings pattern: local preview, server persist
+const [preview, setPreview] = useState<string | null>(null);
+
+<ScProfileImageUpdate
+  imageUrl={preview ?? user.avatarUrl}
+  initials={initialsOf(user.fullName)}
+  onUpload={async (file) => {
+    setPreview(URL.createObjectURL(file));   // instant feedback
+    await api.uploadAvatar(file);            // then persist
+  }}
+  onDelete={async () => {
+    if (preview) { URL.revokeObjectURL(preview); setPreview(null); }
+    await api.deleteAvatar();
+  }}
+/>
+
+// Guard the delete so it can't fire on an empty avatar
+<ScProfileImageUpdate
+  imageUrl={avatar}
+  initials={initials}
+  onUpload={upload}
+  onDelete={avatar ? remove : undefined}   // button still shows, but does nothing
+/>
+
+// Validate before you accept the file (there is no accept/size prop)
+<ScProfileImageUpdate
+  imageUrl={avatar}
+  initials={initials}
+  onUpload={(f) => {
+    if (f.size > 2_000_000) return toast("Keep it under 2 MB");
+    upload(f);
+  }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile settings → Profile tab**, centred at the top of the field stack, above
+  the `ScTextField`s for name and email. That is its only live consumer.
+- Any **"My profile" / "Account" settings screen** in a host app: it is the intended
+  partner for `ScProfileSettingsComp`'s name/email rows.
+- Only for a **person's** avatar. A workspace/brand logo is a rectangle in a form —
+  that is `ScImageField`.
+
+Internally it composes `ScButton` (×2, `styleVariant="icon-only"`,
+`variant="tertiary"`, `size="md"`) and `ScVDivider`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The image is a **person's avatar**, round, and the affordances should be two small
+  icon buttons rather than a dropzone.
+- You have both operations: set a new picture **and** remove the current one.
+- The layout is a centred column — it is a fixed 7.5rem-wide block, not a
+  full-width form row.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A labelled, full-width, rectangular image field inside a form (workspace logo, brand mark) | `ScImageField` |
+| Any non-image file, or you need progress / an error line | `ScFileField` |
+| Only **displaying** an avatar (header, sidebar, table row, switcher) | `ScDp` — has `size`, `variant="workspace" \| "profile"`, and a real image-error fallback to initials |
+| Only displaying **initials** at an arbitrary size | `ScIntialProfileCover` |
+| The whole profile settings form (name, email rows) | `ScProfileSettingsComp` |
+| The profile *menu* / popover in the header | `ScProfile`, `ScProfileOptions`, `ScProfilePopup` |
+| A different avatar size | `ScDp` — this component has no `size` prop |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScImageField` — labelled 120px **rectangle**, thumbnail + filename + one red delete icon, `onFileSelect(file)` | `ScProfileImageUpdate` is a 100px **circle** with two icon buttons and no label or filename |
+| `ScDp` — read-only avatar with `size`, `type="initial" \| "image"`, `variant`, and `onError` → initials | This component uploads but cannot resize and has no error fallback |
+| `ScIntialProfileCover` — initials-only disc, takes `intial` (note the spelling) and `size` | Not an editor |
+| `ScProfile` / `ScProfileOptions` / `ScProfilePopup` / `ScProfileSettingsComp` | Menu/row/form components, nothing to do with picking an image |
+
+Prop-name trap across the family: this one takes **`imageUrl`**, `ScImageField`
+takes **`imagePreview`**, `ScDp` takes **`imageUrl`** + **`initial`** (singular),
+`ScIntialProfileCover` takes **`intial`** (sic). None are interchangeable.
+
+---
+
+## 4. Why to use it
+
+- **The Figma block, exactly.** 7.5rem column, 6.25rem circle, 0.5rem gap, 0.625rem
+  between buttons, a 1.5rem-tall divider, 1.25rem icons — all pinned so every
+  product's profile screen looks identical.
+- **Initials fallback is already tokenised** (`fill-neutral-neutralselected` disc,
+  `text-and-icons-primary` glyphs at 1.75rem/500), so an avatar-less user doesn't
+  get a blank hole or a light-mode contrast bug.
+- **The file input is reset after every pick**, so the "user re-selects the same
+  file and nothing happens" bug is already handled.
+- **Buttons inherit `ScButton`** — so hover, `tabIndex={0}`, Enter/Space activation
+  and the tertiary token set come for free, and a future button restyle reaches this
+  component automatically. (There is no focus *ring*: `ScButton.module.css` has no
+  `:focus` rule, so the buttons are focusable but invisibly so.)
+
+---
+
+## Gotchas
+
+**1. Delete is never disabled.** There is no `canDelete`/`state` prop and no gate on
+`imageUrl`. A user with no picture can still click the trash.
+
+```tsx
+// WRONG — fires a DELETE for an avatar that isn't there
+<ScProfileImageUpdate initials="NS" onDelete={() => api.deleteAvatar()} />
+
+// RIGHT — no-op when there's nothing to remove
+<ScProfileImageUpdate initials="NS" imageUrl={avatar} onDelete={avatar ? remove : undefined} />
+```
+
+**2. Neither button has an accessible name.** Both are `ScButton`
+`styleVariant="icon-only"` with no `aria-label`, and `ScButton` renders
+`div[role="button"]` (with `tabIndex={0}` and its own Enter/Space handler, but no
+visible focus style). A screen reader announces two unnamed buttons. You cannot pass
+labels through — the props stop at `onUpload`/`onDelete`. Wrap the component and
+label the region, or fix the DS:
+
+```tsx
+<div role="group" aria-label="Profile picture">
+  <ScProfileImageUpdate … />
+</div>
+```
+
+**3. `className` is concatenated with `" " + className` unguarded**, so when you omit
+it the root's class list literally contains `undefined`:
+`class="scProfileImageUpdate undefined"`. Cosmetic, but never assert on the exact
+`className` string, and don't write a global `.undefined` rule (it would hit dozens
+of DS components that do this).
+
+**4. `accept="image/*"` is hardcoded.** No `accept`, no `maxSize`, no type filter.
+Validate inside `onUpload` — after the picker has already closed.
+
+**5. No loading / uploading state.** Nothing indicates an in-flight upload and
+nothing blocks a second click. Set `imageUrl` to a blob preview immediately and
+disable your own surrounding UI if the request is slow.
+
+**6. A broken `imageUrl` does not fall back to initials.** There is no `onError`
+handler (`ScDp` has one). A 404 avatar URL renders the browser's broken-image glyph
+inside the circle. If your URLs can 404, prefer `ScDp` for display and keep this
+component for the edit affordance only, or pre-validate the URL.
+
+**7. Fixed size, and the image is cropped.** `width: 7.5rem` on the root,
+`6.25rem` square + `border-radius: full` + `object-fit: cover` on the image. A
+non-square upload is centre-cropped with no crop UI. There is no `size` prop.
+
+**8. `initials` defaults to `""`.** Forget it and an avatar-less user gets a blank
+grey circle. Also: only 1–2 characters fit at 1.75rem inside 100px.
+
+**9. It reports nothing back about the delete.** `onDelete` takes no argument and the
+component keeps no state, so the circle only clears when *you* clear `imageUrl`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-settings-content.tsx:252
+<ScProfileImageUpdate
+  imageUrl={profileImage}
+  initials={profileInitials}
+  onUpload={handleProfileImageUpload}
+  onDelete={handleProfileImageDelete}
+/>
+```
+
+---
+
+## Related
+
+- `ScDp` — the read-only avatar with `size`, `variant` and an image-error fallback; use it everywhere you only display.
+- `ScIntialProfileCover` — initials-only disc (`intial`, `size`).
+- `ScImageField` — the labelled rectangular image field for logos inside forms.
+- `ScFileField` — non-image uploads, with progress and error.
+- `ScProfileSettingsComp` — the name/email rows this block sits above.
+- `ScButton` / `ScVDivider` — what it composes internally.

package/dist/docs/ScProfileOptions.md

@@ -0,0 +1,245 @@
+---
+component: ScProfileOptions
+package: "@streamoid/ui"
+category: profile
+status: legacy
+renders: div
+tags: [profile-menu, profile-dropdown, account-menu, logout, theme-switcher, figma-export, static]
+related: [ScProfilePopup, ScProfile, ScWorkspace, ScMenuOptions, ScTabSwitcher]
+do_not_confuse_with: [ScProfilePopup, ScProfileSettingsComp, ScProfile, ScPopUpMenu, ScMenuOptions]
+---
+
+# ScProfileOptions
+
+**Superseded — use `ScProfilePopup`.** This is the untouched Figma export of the
+profile dropdown (`SC-Profile options`, node 6666:25516): a 264px panel with a
+profile header, workspace + credits badge, four menu rows, a logout row and a
+three-way theme switcher — **all values hardcoded and nothing wired**. Its only prop
+is `className`. `ScProfilePopup` is the same design node rebuilt with real props,
+slots, keyboard handling and a forwarded ref.
+
+## TL;DR for agents
+
+- **Reach for it when:** never, in new code. Keep it only to avoid breaking an
+  existing import.
+- **Don't reach for it when:** you need a working profile menu → **`ScProfilePopup`**.
+- **Four things that will bite you:**
+  1. There are **no data props**. Name, email, workspace, credits, labels and version
+     are all literal strings inside the component.
+  2. There are **no callbacks**. Logout, Billing, Settings, Switch workspace and the
+     theme tabs do nothing at all.
+  3. The first menu row renders `ScMenuOptions`' own default label — literally
+     **"Menu Option"** — because it is passed an `icon` but no `text`.
+  4. It shows "Chris Hemsworth", "Kepler workspace" and "1000 credits left" to your
+     real users.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfilePopup } from "@streamoid/ui"; // ← the replacement
+import { ScProfileOptions } from "@streamoid/ui"; // legacy, className-only
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+The whole API:
+
+```tsx
+<ScProfileOptions />
+```
+
+The migration — same panel, real data:
+
+```tsx
+<ScProfilePopup
+  name={user.name}
+  email={user.email}
+  avatar={user.avatarUrl}
+  workspaceName={ws.name}
+  userRole={ws.role}
+  credits={credits}
+  version={`v${APP_VERSION}`}
+  themeMode={themePreference}
+  onThemeModeChange={setThemePreference}
+  onLogout={logout}
+  onSwitchWorkspace={openSwitcher}
+  onTeams={() => go("team")}
+  onBilling={() => go("billing")}
+  onSettings={() => go("account")}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended (concatenated unconditionally — you get a literal `undefined` class when omitted). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. An `onClick` here fires for the whole panel, which is not useful. |
+
+That is the entire public surface.
+
+### What it renders (all hardcoded)
+
+| Region | Fixed content |
+|---|---|
+| Header | `ScProfile` with **no props** → "Chris Hemsworth" / "Kepler workspace" / broken `profile-image0.png` |
+| Workspace | `ScWorkspace` with **no props** → "Kepler" / "Admin" / broken image, plus `ScBadges` "1000 credits left" (`success`, `opaque`) |
+| Menu row 1 | `SiconTeam` + **"Menu Option"** (the `ScMenuOptions` default label) |
+| Menu row 2 | `SiconBilling` + "Billing" |
+| Button | `ScButton` "Switch workspace", `variant="secondary"`, `size="md"`, `SiconHome` icon |
+| Menu row 3 | `SiconBolt` + "What's new", `variant="with-v"` → shows `ScMenuOptions`' default version **"v2.0.21"** |
+| Menu row 4 | `SiconSettings` + "All settings" |
+| Logout | `SiconLogout` + "Logout", `variant="error"` — a div, not a button |
+| Theme | `ScTabSwitcher` with 3 icon-only `ScTabComp`s; **System is hardcoded active** |
+
+### Recipes
+
+There is nothing to configure. The only useful recipe is the replacement above.
+
+---
+
+## 2. Where to use it
+
+Nowhere new. It is the design-time artefact of the profile dropdown; the shipped
+surface is `ScProfilePopup`:
+
+- **Catalogix** — `app/components/AppSettingsPopup` renders `ScProfilePopup` and
+  notes in its own header comment that it replaced ~430 lines of hand-assembled
+  panel.
+- **CXO / Photogenix / Artifax** — profile menus live in their sidebar shells.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never in product code. Legitimate uses are: a Figma-parity screenshot of the
+  original node, or keeping an old import compiling until it is migrated.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A working profile dropdown with real identity, callbacks and slots | `ScProfilePopup` |
+| Only the identity row | `ScProfile` |
+| Only one menu row | `ScMenuOptions` |
+| A generic popover of options anchored to a trigger | `ScPopUpMenu` + `ScMenuOptions` |
+| The theme switcher on its own | `ScTabSwitcher` + `ScTabComp` (`type="icon-only"`) |
+| The account settings **form** | compose `ScProfileImageUpdate` + `ScTextField` (see `ScProfileSettingsComp`) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfilePopup` — the live, propped panel built from the same Figma node | `ScProfileOptions` is the static export of it |
+| `ScProfileSettingsComp` — the account **form** scaffold (first/last/email) | this is the **menu** |
+| `ScProfile` — the identity row alone | this is the whole panel |
+| `ScPopUpMenu` — generic anchored popover | this is the profile-specific panel body |
+
+`ScProfileOptions` vs `ScProfilePopup` vs `ScProfileSettingsComp` vs `ScProfile` is
+the highest-traffic mis-pick in this folder: **menu (static) / menu (live) / form /
+row**.
+
+---
+
+## 4. Why to use it
+
+Honestly: you shouldn't. What `ScProfilePopup` gives you over it —
+
+- **Real props and callbacks** for every row, plus `show*` flags to drop rows.
+- **Four nesting slots** (`headerActions`, `workspaceContent`, `menuContent`,
+  `preFooterContent`) with a stretch rule so nested DS components lay out correctly.
+- **Keyboard access** — Enter/Space on the div-based rows, `role="radiogroup"` +
+  `role="radio"` + `aria-checked` on the theme tabs, focus-visible rings everywhere.
+- **A forwarded ref** on the panel root, for positioning and outside-click dismissal.
+- **Icon colour fixed** — `ScMenuOptions` colours only its label, so the built-in
+  icons inherit whatever the host happened to set; the popup drives them from
+  `--alias-text-and-icons-primary`.
+
+The one thing this component still documents well is the **panel shell recipe**:
+`surface-subtle` + `radius-4xl` + `0.03125rem border-subtle` + `backdrop-filter:
+blur(2.625rem)`, 264px wide. `ScProfilePopup` reproduces it at 320px using an inset
+box-shadow instead of a border (a real border eats a pixel of the content width).
+
+---
+
+## Gotchas
+
+**1. `ScProfile` and `ScWorkspace` are rendered with no props.** Both fall back to
+their placeholder identity **and** to `profileImage="profile-image0.png"`, so the
+panel shows two broken-image glyphs in any host.
+
+**2. "Menu Option" ships to production.** The first row passes only an `icon`:
+
+```tsx
+// what the component actually does — text is omitted, so ScMenuOptions' default wins
+<ScMenuOptions icon={<SiconTeam />} />   // renders "Menu Option"
+```
+
+The intended label was "Teams" (`ScProfilePopup` fixes it with `teamsLabel="Teams"`).
+
+**3. The version stamp is a lie.** The "What's new" row uses `variant="with-v"`
+without a `version`, so `ScMenuOptions`' default `"v2.0.21"` renders regardless of
+your app version.
+
+**4. Nothing is interactive.** Every row is a bare `<div>` with no `onClick`, no
+`role`, no `tabIndex`. Not clickable, not focusable, invisible to screen readers as a
+menu.
+
+**5. The theme switcher's active tab is hardcoded.** `active="true"` sits on the
+System tab literally; clicking Light or Dark does nothing.
+
+**6. The `scTabComp*` props passed to `ScTabSwitcher` are dead.**
+`scTabCompicon` / `scTabCompactive` / `scTabComptype` are destructured to `_`-prefixed
+names inside `ScTabSwitcher` and never used. Only `component`…`component5` render.
+
+**7. Fixed 264px width** (`width: 16.5rem`) with `backdrop-filter: blur(42px)` — the
+blur is invisible over an opaque background, and the panel will not stretch to a
+host container.
+
+**8. A real `border-width: 0.03125rem`** (0.5px) is used here, so the panel's outer
+box is 1px wider and taller than the Figma frame. `ScProfilePopup` switched to
+`box-shadow: inset` for exactly this reason.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+No app imports it. Its live replacement is rendered here:
+
+```jsx
+// catalogix/dashboard  app/components/AppSettingsPopup/index.jsx:75
+<ScProfilePopup
+  data-theme="Mode 1"
+  role="menu"
+  aria-label="Profile menu"
+  name={(userData && (userData.name || userData.email)) || ""}
+  email={(userData && userData.email) || ""}
+  avatar={userData?.imageUrl || undefined}
+  onProfileClick={() => goSettings("account")}
+  workspaceName={selectedWorkspace?.name || ""}
+  userRole={selectedWorkspace?.role || ""}
+  credits={creditsLabel}
+  onSwitchWorkspace={() => showWorkspaceList()}
+  themeMode={themePreference}
+  onThemeModeChange={setThemePreference}
+/>
+```
+
+---
+
+## Related
+
+- `ScProfilePopup` — **the replacement.** Same design node, real API.
+- `ScProfile` / `ScWorkspace` — the two identity rows it stacks.
+- `ScMenuOptions` — one menu row (`variant="with-v" | "error" | "default"`).
+- `ScTabSwitcher` / `ScTabComp` — the theme switcher pair.
+- `ScBadges` — the credits chip it uses (the popup inlines its own credits pill instead).