@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScPopUpMenu.md

@@ -0,0 +1,224 @@
+---
+component: ScPopUpMenu
+package: "@streamoid/ui"
+category: overlays
+status: legacy
+tags: [menu, menu-row, popup, kebab, context-menu, option, legacy]
+renders: div
+related: [ScMenuOptions, ScProfilePopup, ScProfileOptions, ScModal]
+do_not_confuse_with: [ScMenuOptions, ScProfilePopup, ScModal, ScInfoPopup]
+---
+
+# ScPopUpMenu
+
+**A single 242px-wide menu *row* — despite the name, not a popup and not a menu.**
+It renders one `<div>` with an optional icon and a label, plus a `state="clicked"`
+background flag. It creates no overlay, no list, no positioning and no dismissal.
+
+> **status: legacy.** `ScMenuOptions` is the row every app actually renders (CXO,
+> Photogenix, Artifax, and `ScProfilePopup`/`ScProfileOptions` internally), and it
+> has hover states, an `error` variant, a version slot and a props spread that this
+> one lacks. `ScPopUpMenu` has **no call site anywhere** — host repos or DS
+> internals. **Use `ScMenuOptions`.** It is documented here only so an agent that
+> greps the name is redirected instead of adopting it.
+
+## TL;DR for agents
+
+- **Reach for it when:** never, in new code.
+- **Reach for this instead:** `ScMenuOptions` for the row, `ScProfilePopup` /
+  `ScProfileOptions` for the panel that contains the rows, `ScModal` / `ScDrawer`
+  if you actually wanted an overlay.
+- **Three things that will bite you:**
+  1. The name promises a popover. There is none — this is one row of chrome.
+  2. The label prop is `menu`, not `text` or `label`, and it defaults to
+     `"Options"` ⚠️.
+  3. There is **no `:hover` rule in its CSS at all.** The row gives zero pointer
+     feedback unless you drive `state="clicked"` yourself.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPopUpMenu } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPopUpMenu menu="Duplicate" icon={<SiconCopy size={24} />} onClick={duplicate} />
+```
+
+The `ScMenuOptions` equivalent, which is what you should ship:
+
+```tsx
+<ScMenuOptions
+  text="Duplicate"
+  icon={<SiconCopy size={24} />}
+  variant="default"
+  style={{ width: "100%", cursor: "pointer" }}
+  role="button"
+  tabIndex={0}
+  onClick={duplicate}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `menu` | `string` | `"Options"` | ⚠️ The label — note the prop name, and the real default. `ScMenuOptions` calls the same thing `text`. |
+| `state` | `"default"` \| `"clicked"` | `"default"` | `"clicked"` paints `--alias-surface-canvas` behind the row. Purely a style flag — the component never sets it itself. |
+| `icon` | `JSX.Element` | – | No default (unlike `ScMenuOptions`, which defaults to `SiconTeam`). Rendered in a 24×24 `flex-shrink: 0` box **only when truthy** — no reserved gutter when absent. |
+| `onClick` | `(e: React.MouseEvent) => void` | – | Plain click on the root `<div>`. |
+| `className` | `string` | – | Concatenated unconditionally — see Gotcha 4. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div (`style`, `role`, `tabIndex`, `data-*`, `aria-*`, `onKeyDown`). |
+
+### What it actually renders
+
+```html
+<div class="scPopUpMenu state-default {className}">
+  <!-- width:242px · display:flex · gap:12px · padding:12px 4px · radius:8px · cursor:pointer -->
+  <span class="icon">{icon}</span>        <!-- only when icon is truthy; 24×24 -->
+  <p class="menuText">{menu}</p>          <!-- 16px/24 medium; --alias-text-and-icons-secondary; nowrap -->
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere new. The surfaces it was drawn for are all served by other parts:
+
+| Surface | What actually ships there |
+|---|---|
+| Profile / account flyout rows | `ScMenuOptions` inside `ScProfilePopup` (CXO `profile-popup.tsx`, Artifax `DashboardSidebar.tsx`) |
+| Sidebar settings rows (Teams / Billing / Settings / What's new) | `ScMenuOptions` (`variant="with-v"` for the version row) |
+| Kebab / row-overflow menus | `ScMenuOptions` in an app-positioned container (Photogenix `studio/BatchList.tsx`) |
+| The container/overlay itself | `ScProfilePopup` (panel body), or `ScModal` / `ScDrawer` |
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never in new code. If you are maintaining something that already imports it,
+  migrating to `ScMenuOptions` is a rename of `menu` → `text` plus dropping
+  `state` (real `:hover` replaces it).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A row in any menu, flyout or sidebar list | `ScMenuOptions` |
+| The profile/account flyout panel itself | `ScProfilePopup` (body only) or `ScProfileOptions` |
+| An actual popover/overlay container | `ScModal` (centered) or `ScDrawer` (edge) |
+| A contextual help bubble | `ScInfoPopup` — the only thing here that really pops up |
+| A destructive row ("Delete", "Log out") | `ScMenuOptions variant="error"` (this component has no error variant) |
+| A row that needs a trailing version/meta string | `ScMenuOptions variant="with-v"` + `version` |
+| A button | `ScButton` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScMenuOptions` — the current menu row: hover fills, `error` variant, `with-v` version slot, 200px wide, `text` prop | `ScPopUpMenu` — 242px, no hover, no variants, `menu` prop |
+| `ScProfilePopup` — the panel that holds menu rows | `ScPopUpMenu` holds nothing |
+| `ScInfoPopup` — an actual click-to-open popover | `ScPopUpMenu` never opens anything |
+| `ScModal` / `ScDrawer` — the overlay primitives | `ScPopUpMenu` renders no overlay |
+
+---
+
+## 4. Why to use it
+
+You shouldn't. What you'd be giving up by picking it over `ScMenuOptions`:
+
+- **Hover feedback.** `ScMenuOptions` has real `:hover` fills
+  (`--alias-fill-neutral-neutralhover`, and `--alias-fill-error-secondary` for the
+  error variant). `ScPopUpMenu.module.css` contains no `:hover` rule, so the row is
+  inert under the pointer.
+- **Semantic variants.** No `error` colouring, no version/meta slot.
+- **Truncation.** `ScMenuOptions`'s label is `flex: 1` with
+  `text-overflow: ellipsis`; this one is `white-space: nowrap` with no ellipsis and
+  no flex, so a long label overflows the fixed 242px box.
+- **Battle-tested defaults.** Every app already passes the same
+  `style={{ width: "100%", cursor: "pointer" }}` to `ScMenuOptions`; that idiom, and
+  the Enter/Space `onKeyDown` helper in `ScProfilePopup`, exist for the row that is
+  actually in use.
+
+Both use `--alias-*` tokens, so theme correctness is not the differentiator — reach
+is.
+
+---
+
+## Gotchas
+
+**1. The name is wrong.** It is a row, not a popup and not a menu. It has no
+`open`, no anchor, no portal, no outside-click. If you were looking for the thing
+that pops up, you want `ScProfilePopup` (panel), `ScModal` / `ScDrawer` (overlay),
+or `ScInfoPopup` (bubble).
+
+**2. `menu` defaults to `"Options"`.** Forget the prop — or reach for `text` out of
+`ScMenuOptions` habit — and the row silently reads "Options".
+
+```tsx
+// WRONG — `text` is not a prop here; renders "Options"
+<ScPopUpMenu text="Duplicate" />
+
+// RIGHT (but prefer ScMenuOptions)
+<ScPopUpMenu menu="Duplicate" />
+```
+
+**3. No hover styling exists.** `.state-default` is `background: transparent` and
+there is no `:hover` selector, so `state="clicked"` is the only way to show any
+fill — and you have to drive it from your own state.
+
+**4. `className` is concatenated unconditionally.** The class attribute becomes
+`scPopUpMenu state-default undefined` when you omit it. Harmless in the browser,
+but it shows up in the DOM and breaks exact-match snapshot tests.
+
+**5. Fixed `width: 242px`.** Not responsive, and different from `ScMenuOptions`'
+200px — mixing the two in one list gives you two row widths. Override via `style`.
+
+**6. Asymmetric padding: `12px 4px`.** 12px vertical, 4px horizontal, so any
+background you paint via `state="clicked"` hugs the text almost edge-to-edge.
+
+**7. `icon` has no reserved gutter.** When `icon` is falsy the 24px box is not
+rendered at all, so labels in a mixed list of rows with and without icons do not
+line up. Pass a spacer element if you need alignment.
+
+**8. Plain `<div>` with `onClick` — no a11y.** No `role`, no `tabIndex`, no
+keyboard activation. Add `role="menuitem" tabIndex={0}` plus an Enter/Space
+`onKeyDown` via the spread (this is exactly what `ScProfilePopup` does for its
+`ScMenuOptions` rows).
+
+**9. `icon` is rendered raw.** No `cloneElement`, no size normalisation, no
+`currentColor` — unlike `ScButton`, your icon keeps its own size and colour, and it
+will not track the label's `--alias-text-and-icons-secondary`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it is used by **nothing** — not the four host dashboards, not the
+chat/agent runtime, and not any other component in `packages/ui`. Every surface it
+looks like it belongs to (profile flyout rows, sidebar settings rows, kebab menus)
+already ships `ScMenuOptions` instead — see
+`cxo-dashboard/src/app/components/profile-popup.tsx:298` and
+`artifax/packages/shared/src/components/DashboardSidebar.tsx:927`.
+
+---
+
+## Related
+
+- `ScMenuOptions` — **the replacement.** Same job, hover states, `error`/`with-v` variants, and it is what all four apps render.
+- `ScProfilePopup` — the profile flyout panel body that hosts menu rows.
+- `ScProfileOptions` — the older profile-options block, also built from `ScMenuOptions`.
+- `ScModal` / `ScDrawer` — the real overlay primitives.
+- `ScInfoPopup` — the only component in this category that actually opens a popover.

package/dist/docs/ScProfile.md

@@ -0,0 +1,234 @@
+---
+component: ScProfile
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [profile, identity, avatar-with-name, name-subtext, sidebar-footer, user-row]
+related: [ScWorkspace, ScProfilePopup, ScDp, ScProfileV2Mobile, ScSidebarProfile]
+do_not_confuse_with: [ScWorkspace, ScProfileOptions, ScProfilePopup, ScProfileSettingsComp, ScProfileV2Mobile]
+---
+
+# ScProfile
+
+**The person identity row: circular avatar + name + one grey sub-line.** 200px wide,
+two ellipsised text lines, and a `collapsed` variant that drops the text and shrinks
+the avatar to 32px. It is a presentation row — it owns no menu, no click behaviour
+and no state.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need "avatar, name, second line" as one unit inside a
+  DS composite you are building.
+- **Don't reach for it when:** you want the whole profile menu (→ `ScProfilePopup`),
+  a **workspace** identity row (→ `ScWorkspace`), the mobile profile block
+  (→ `ScProfileV2Mobile`), or just the avatar (→ `ScDp`).
+- **Four things that will bite you:**
+  1. `profileImage` defaults to the literal string **`"profile-image0.png"`** — a
+     relative path that 404s and renders a broken-image glyph. There is no initials
+     fallback anywhere in this component.
+  2. `collapsed` is the **string** `"false" | "true"`, not a boolean.
+  3. Defaults are placeholder identity: **"Chris Hemsworth" / "Kepler workspace"**.
+  4. `className` is concatenated unconditionally, so omitting it puts the literal
+     class `undefined` on the root. Harmless, but it shows up in snapshots.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScProfile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScProfile name={user.name} subText={user.email} profileImage={user.avatarUrl} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | `"Chris Hemsworth"` | ⚠️ Real default. First line, `text-sm/medium`, single line + ellipsis. |
+| `subText` | `string` | `"Kepler workspace"` | ⚠️ Real default. Second line, `text-xs/regular`, tertiary colour. `ScProfilePopup` feeds the **email** here. |
+| `collapsed` | `"false"` \| `"true"` | `"false"` | ⚠️ A **string** union, not a boolean. `"true"` hides both text lines and shrinks the avatar 40px → 32px. |
+| `profileImage` | `string` | `"profile-image0.png"` | ⚠️ Real default that resolves relative to the page and 404s. Always pass a real URL. |
+| `className` | `string` | – | Appended (see Gotcha 4). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `aria-*`, `data-*` are spread onto the root div — but you get **no** button semantics. |
+
+### What renders in each `collapsed` value
+
+| Region | `"false"` | `"true"` |
+|---|---|---|
+| Root width | fixed `12.5rem` (200px) | `width: unset` — shrinks to the avatar |
+| Avatar | 2.5rem circle | 2rem circle |
+| `name` / `subText` | rendered | **not rendered at all** |
+
+### Recipes
+
+```tsx
+// Sidebar footer identity, driven by the shell's collapse state
+<ScProfile
+  name={user.name}
+  subText={user.email}
+  profileImage={user.avatarUrl ?? FALLBACK_AVATAR_URL}
+  collapsed={sidebarCollapsed ? "true" : "false"}
+/>
+
+// Full-width inside a flex column (it is 200px by default — override to stretch)
+<ScProfile
+  name={member.name}
+  subText={member.email}
+  profileImage={member.avatarUrl}
+  style={{ flex: 1, width: "auto", minWidth: 0 }}
+/>
+
+// Interactive: give it real semantics yourself
+<button type="button" onClick={openMenu} style={{ all: "unset", cursor: "pointer" }}>
+  <ScProfile name={user.name} subText={user.email} profileImage={user.avatarUrl} />
+</button>
+```
+
+---
+
+## 2. Where to use it
+
+Almost always **inside** another DS component rather than directly in a host screen.
+It is composed by:
+
+| Parent | Role |
+|---|---|
+| `ScProfilePopup` | the panel header identity (name + email), avatar forced to 32px |
+| `ScProfileOptions` | the legacy static profile menu header |
+| `ScSidebarProfile` | the pre-`StreamoidSidebar` sidebar footer |
+| `ScTableList` | the member cell of a team-table row |
+| `ScReferralTableList` | the referred-user cell |
+
+If you are building a host screen, you almost certainly want one of those parents.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are composing a **new DS component** that needs the standard person identity
+  row and want the type ramp, the 12px gap and the ellipsis behaviour for free.
+- You need an expanded/collapsed identity pair that matches the sidebar shells.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The whole profile dropdown (identity + workspace + menu + theme) | `ScProfilePopup` |
+| A **workspace** identity row (rounded-rect logo, name + role) | `ScWorkspace` — but it is **not exported**; use `ScProfilePopup`/`ScWorkspaceSwitchCard` |
+| Mobile profile block with left/right avatar placement | `ScProfileV2Mobile` |
+| Just the avatar, with an initials fallback | `ScDp` |
+| Editable avatar with upload/delete | `ScProfileImageUpdate` |
+| A team-table member row | `ScTableList` (it already renders a `ScProfile`) |
+| The account settings form (first/last/email) | compose `ScProfileImageUpdate` + `ScTextField`; see `ScProfileSettingsComp` for why not that |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScWorkspace` — same layout, **workspace** semantics: `workspaceName`/`userRole`, `radius-md` logo | `ScProfile` is the person: `name`/`subText`, circular avatar |
+| `ScProfileOptions` — the legacy hardcoded menu panel (className-only API) | `ScProfile` is just the header row of it |
+| `ScProfilePopup` — the current, fully-propped menu panel | `ScProfile` renders no menu |
+| `ScProfileSettingsComp` — a static account-form scaffold | unrelated to this row |
+| `ScProfileV2Mobile` — the mobile twin, `email` + `dpPosition` props | different prop names, mobile surface |
+
+---
+
+## 4. Why to use it
+
+- **The type ramp is the spec.** `text-sm/medium` over `text-xs/regular` with
+  `text-and-icons-primary` over `-tertiary` is the identity pattern used everywhere;
+  restating it by hand is how sidebars end up with mismatched name sizes.
+- **Both lines already ellipsise.** `overflow: hidden` + `text-overflow: ellipsis` +
+  `nowrap` on each line, so long emails degrade instead of wrapping the row.
+- **The collapsed variant is a single prop** and matches the sidebar's 40 → 32px
+  avatar step exactly.
+- **One place to change.** Five DS parents render it, so the identity row stays
+  consistent across the popup, the sidebar footer and both tables.
+
+---
+
+## Gotchas
+
+**1. `profileImage` has a broken default.** `"profile-image0.png"` is a Figma export
+artefact. With no `src` override you ship a broken-image icon — and there is **no
+initials fallback** (that is `ScDp`, which this component does not use).
+
+```tsx
+// WRONG — broken image glyph
+<ScProfile name={user.name} subText={user.email} />
+
+// RIGHT
+<ScProfile name={user.name} subText={user.email} profileImage={user.avatarUrl ?? FALLBACK} />
+```
+
+This is why `ScProfilePopup` spreads `avatar` conditionally: pass no `avatar` to the
+popup and this default leaks through.
+
+**2. `collapsed` is a string.** `collapsed={true}` is a type error, and
+`collapsed={String(isCollapsed)}` widens to `string`. Write the ternary.
+
+```tsx
+// WRONG
+<ScProfile collapsed={isCollapsed} />
+
+// RIGHT
+<ScProfile collapsed={isCollapsed ? "true" : "false"} />
+```
+
+**3. It is 200px wide, always (expanded).** `.scProfile { width: 12.5rem }` is a
+plain class rule. Inside a wider flex row it will not stretch — every DS parent
+overrides it: `flex: 1 !important; width: unset !important` in `ScProfilePopup`
+(plus `min-width: 0 !important`), `ScProfileOptions`, `ScTableList` and
+`ScReferralTableList`; `align-self: stretch !important; width: unset !important` in
+`ScSidebarProfile`. Do the same, or pass
+`style={{ flex: 1, width: "auto", minWidth: 0 }}`.
+
+**4. Unconditional `className` concatenation.** The root class string is
+`` `${styles.scProfile} ${className} ${variantsClassName}` ``, so with no
+`className` the DOM gets `class="scProfile undefined collapsed-false"`. Don't assert
+on the exact class string in tests.
+
+**5. The `<img>` has no `alt` attribute at all.** Not `alt=""` — absent. Screen
+readers may announce the filename. Wrap the row in a labelled element.
+
+**6. It is a `<div>`, and props are spread.** `onClick` will fire, but you get no
+`role`, no `tabIndex`, no keyboard activation and no focus ring. Wrap it in a real
+`<button>` if it opens something.
+
+**7. Trailing spaces in the text nodes.** Both lines render `{name} ` / `{subText} `
+with a literal trailing space (Figma export). Exact-string assertions in tests need
+a `trim()`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is composed inside `ScProfilePopup` (`src/SC-ProfilePopup/ScProfilePopup.tsx:235`),
+`ScTableList`, `ScReferralTableList`, `ScSidebarProfile` and `ScProfileOptions`. The
+nearest host surface is Catalogix's profile menu
+(`app/components/AppSettingsPopup/index.jsx:75`), which reaches it **through**
+`ScProfilePopup` — that is the intended entry point for hosts. Direct host use would
+belong in a bespoke sidebar footer or member row that no app currently hand-rolls.
+
+---
+
+## Related
+
+- `ScProfilePopup` — the current profile menu panel; renders this as its header.
+- `ScWorkspace` — the workspace-flavoured twin (internal, not exported).
+- `ScDp` — avatar only, with an image-error fallback this component lacks.
+- `ScProfileV2Mobile` — the mobile identity block.
+- `ScSidebarProfile` — legacy sidebar footer wrapper (superseded by `StreamoidSidebar`).