@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScWorkspace.md

@@ -0,0 +1,233 @@
+---
+component: ScWorkspace
+exported: false
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [workspace, identity, workspace-name, role, internal, not-exported, tenant]
+related: [ScProfile, ScProfilePopup, ScWorkspaceSwitchCard, ScWorkspaceCard, ScDp]
+do_not_confuse_with: [ScProfile, ScWorkspaceCard, ScWorkspaceSwitchCard, StreamoidWorkspaceSwitcher, ScWorkspaceSwitchMobileV2]
+---
+
+# ScWorkspace
+
+**The workspace identity row — and it is not part of the public API.**
+Rounded-rect logo + workspace name + grey role line, 200px wide. `packages/ui/src/index.ts`
+does **not** re-export it, so `import { ScWorkspace } from "@streamoid/ui"` fails to
+compile. It exists only as an internal part of `ScProfilePopup` and `ScProfileOptions`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are editing a component **inside** `packages/ui/src`
+  and need the workspace identity row. Import it by relative path.
+- **Don't reach for it when:** you are writing host-app code — it is unreachable
+  from `@streamoid/ui`. Use `ScProfilePopup` (which renders it for you) or
+  `ScWorkspaceSwitchCard` (the standalone workspace row).
+- **Three things that will bite you:**
+  1. **Not exported.** Not in `index.ts`, not in `dist/index.d.ts`, not in the
+     package's export list.
+  2. `profileImage` defaults to **`"profile-image0.png"`** — a 404 with no initials
+     fallback.
+  3. `collapsed` is the **string** `"false" | "true"`, and `"true"` hides the text
+     entirely.
+
+---
+
+## 1. How to use it
+
+### Import
+
+From a host app you cannot import it. Reach for the exported parents instead:
+
+```tsx
+import { ScProfilePopup, ScWorkspaceSwitchCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+From **inside the `ui` package** (the only place it is usable):
+
+```tsx
+import { ScWorkspace } from "../SC-Workspace/ScWorkspace";
+```
+
+### Minimal usage
+
+```tsx
+<ScWorkspace
+  workspaceName={ws.name}
+  userRole={ws.role}
+  profileImage={ws.imageUrl}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `workspaceName` | `string` | `"Kepler"` | ⚠️ Real default. First line, `text-sm/medium`, single line + ellipsis. |
+| `userRole` | `string` | `"Admin"` | ⚠️ Real default — a **free string**, not the `"admin" \| "member"` union `ScRole` uses. No colour semantics. |
+| `collapsed` | `"false"` \| `"true"` | `"false"` | ⚠️ String union, not boolean. `"true"` hides both lines and shrinks the logo 40px → 32px. |
+| `profileImage` | `string` | `"profile-image0.png"` | ⚠️ Broken relative default. No initials fallback. |
+| `className` | `string` | – | Appended (concatenated unconditionally — see Gotcha 4). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. No button semantics. |
+
+### What renders in each `collapsed` value
+
+| Region | `"false"` | `"true"` |
+|---|---|---|
+| Root width | fixed `12.5rem` (200px) | `width: unset` |
+| Logo | 2.5rem, `radius-md` (rounded rect) | 2rem, `radius-md` |
+| `workspaceName` / `userRole` | rendered | **not rendered at all** |
+
+### Recipes
+
+```tsx
+// Inside the ui package: the workspace block of a panel
+<ScWorkspace
+  workspaceName={workspaceName}
+  userRole={userRole}
+  {...(workspaceImage ? { profileImage: workspaceImage } : {})}
+  className={styles.scWorkspaceInstance}   /* flex:1 !important; width:unset !important; min-width:0 !important */
+/>
+
+// From a host app — this is the supported path
+<ScProfilePopup
+  workspaceName={ws.name}
+  userRole={ws.role}
+  workspaceImage={ws.imageUrl}
+  credits={credits}
+  onSwitchWorkspace={openSwitcher}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Only inside `packages/ui`. Two parents render it today:
+
+| Parent | Role |
+|---|---|
+| `ScProfilePopup` | the workspace block above "Switch workspace"; overrides the logo to 32px and stretches the row |
+| `ScProfileOptions` | the same block in the legacy static menu (rendered with **no props**, so it shows "Kepler / Admin" placeholders) |
+
+Host apps reach it through `ScProfilePopup` — Catalogix's `AppSettingsPopup` is the
+live example.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are adding a DS component in `packages/ui/src` that needs the workspace
+  identity row and want it to match the profile popup exactly.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Host-app code of any kind | `ScProfilePopup` (composes it) or `ScWorkspaceSwitchCard` |
+| A full workspace row with role / plan / owner and hover actions | `ScWorkspaceSwitchCard` |
+| A workspace card with a user count and a CTA button | `ScWorkspaceCard` |
+| A whole "switch workspace" modal | hand-roll around `ScWorkspaceSwitchCard` (what all three hosts do) or `StreamoidWorkspaceSwitcher` |
+| Mobile workspace rows | `ScWorkspaceSwitchMobileV2` / `ScWorkspaceSwitchMobile` / `ScWorkspaceSettingsMobile` |
+| The **person** identity row | `ScProfile` |
+| Just the workspace logo tile | `ScDp` with `variant="workspace"`, or `ScIntialProfileCover` |
+| A coloured role pill | `ScRole` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfile` — the person twin: `name`/`subText`, **circular** avatar | `ScWorkspace` is `workspaceName`/`userRole` with a **rounded-rect** logo |
+| `ScWorkspaceCard` — `workspaceName`/`role`/`userCount`/`ownerEmail`/`buttonText` card | this is a bare two-line row |
+| `ScWorkspaceSwitchCard` — the current/other workspace row with Switch / Settings / Leave | this has no actions |
+| `StreamoidWorkspaceSwitcher` — a full modal listing workspaces | this is one line of identity |
+| `ScWorkspaceSwitchMobileV2` — the mobile row | different props, mobile surface |
+
+The four `ScWorkspace*` names are the single biggest mis-pick in this family:
+`ScWorkspace` (internal row) → `ScWorkspaceCard` (card + CTA) →
+`ScWorkspaceSwitchCard` (switcher row with actions) → `StreamoidWorkspaceSwitcher`
+(the modal that lists them).
+
+---
+
+## 4. Why to use it
+
+- **It keeps the popup's workspace block identical to its profile block.** Same gap,
+  same type ramp, same collapse step as `ScProfile` — the two rows are meant to read
+  as a pair, and they only do because they are two copies of one layout.
+- **Rounded-rect vs circle is the workspace/person signal** in the design language,
+  and this component encodes it (`radius-md` logo) so composites don't re-decide it.
+- **Both lines ellipsise**, so long tenant names degrade instead of wrapping.
+
+What breaks if you hand-roll it: the logo radius drifts to a circle (making a
+workspace look like a person), and the role line loses `text-and-icons-tertiary`.
+
+---
+
+## Gotchas
+
+**1. It is not exported.** This is the whole story of the component.
+
+```tsx
+// WRONG — does not compile; ScWorkspace is absent from dist/index.d.ts
+import { ScWorkspace } from "@streamoid/ui";
+
+// RIGHT (host app)
+import { ScProfilePopup } from "@streamoid/ui";
+<ScProfilePopup workspaceName={ws.name} userRole={ws.role} workspaceImage={ws.imageUrl} />
+```
+
+If a host genuinely needs the bare row, add
+`export * from "./SC-Workspace/ScWorkspace";` to `packages/ui/src/index.ts` and
+publish — do not copy the component into the host.
+
+**2. `profileImage` defaults to `"profile-image0.png"`.** Broken image glyph, no
+initials fallback. `ScProfilePopup` guards this by spreading the prop only when
+`workspaceImage` is truthy; do the same.
+
+**3. `collapsed` is the string `"true"`/`"false"`**, and `"true"` removes the text
+rather than truncating it.
+
+**4. `className` is concatenated unconditionally,** so the DOM gets
+`class="scWorkspace undefined collapsed-false"` when you pass none.
+
+**5. Fixed 200px width.** `.scWorkspace { width: 12.5rem }`. Both parents override it:
+`ScProfilePopup` with `flex: 1 !important; width: unset !important; min-width: 0 !important`,
+`ScProfileOptions` with only the first two. The `min-width: 0` is what makes the ellipsis
+work inside a flex row — copy all three, not just the popup's first two.
+
+**6. `userRole` is unstyled free text.** Unlike `ScRole` there is no admin/member
+colour semantics; whatever string you pass renders in tertiary grey. Capitalise it
+yourself.
+
+**7. The `<img>` has no `alt` attribute** (absent, not empty).
+
+**8. Trailing spaces** in both text nodes (`{workspaceName} `), a Figma-export
+artefact — `trim()` before asserting.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is not exported, so a host render site is impossible. Composed at
+`src/SC-ProfilePopup/ScProfilePopup.tsx:287` and
+`src/SC-Profile options/ScProfileOptions.tsx:33`. The host-facing equivalent is
+Catalogix's `app/components/AppSettingsPopup/index.jsx:75`, which passes
+`workspaceName` / `userRole` / `workspaceImage` into `ScProfilePopup` and lets it
+render this row.
+
+---
+
+## Related
+
+- `ScProfilePopup` — the exported parent; pass `workspaceName`/`userRole`/`workspaceImage`.
+- `ScProfile` — the person twin, same layout, circular avatar.
+- `ScWorkspaceSwitchCard` — the exported standalone workspace row with actions.
+- `ScWorkspaceCard` — workspace card with user count and a CTA.
+- `ScRole` — the coloured admin/member pill this row deliberately does not use.

package/dist/docs/ScWorkspaceCard.md

@@ -0,0 +1,234 @@
+---
+component: ScWorkspaceCard
+package: "@streamoid/ui"
+category: cards
+status: legacy
+renders: div
+tags: [card, workspace, team, role, owner, switch, leave, legacy, superseded]
+related: [ScWorkspaceSwitchCard, StreamoidWorkspaceSwitcher, ScWorkspaceSwitchMobileV2, ScWorkspaceSettingsMobile, ScIntialProfileCover]
+do_not_confuse_with: [ScWorkspaceSwitchCard, StreamoidWorkspaceSwitcher, ScSidebarSwitchMenu, ScWorkspaceSwitchMobile, ScWorkspaceSwitchMobileV2]
+# used_by deliberately omitted: nothing renders this anywhere — see "In the wild".
+---
+
+# ScWorkspaceCard
+
+**⚠️ Legacy — superseded by `ScWorkspaceSwitchCard` (single card) and
+`StreamoidWorkspaceSwitcher` (the whole overlay).** A full-width row showing a
+workspace's initials cover, name, role badge, user count and owner email, plus two
+buttons — one permanently disabled, the other unlabelled. **It accepts no
+callbacks**, so nothing it renders can be wired up.
+
+## TL;DR for agents
+
+- **Reach for it when:** essentially never in new code. Use
+  `ScWorkspaceSwitchCard`, or `StreamoidWorkspaceSwitcher` if you want the whole
+  switch-workspace overlay.
+- **Why it's legacy:** it is a Figma-parity static render, not a functional card:
+  - **No `onSwitch` / `onLeave` / `onClick` props.** There is no way to handle either
+    button. The only handler you can attach is a bubbling `onClick` on the card root.
+  - The "Current workspace" button is **hardcoded `state="disabled"`** — it can never
+    be pressed, and it can never be switched to any other state.
+  - The avatar is **hardcoded to the initials `"WS"`** (`ScIntialProfileCover` is
+    rendered with no `intial` prop), so it never shows the real workspace initials.
+  - The "Leave workspace" button is `styleVariant="icon-only"`, so its label is
+    **never rendered** and it carries **no `aria-label`** — an unnamed button.
+  - `ownerEmail` defaults to a **real person's address**
+    (`rohan@streamoid.com`).
+- **If you must use it:** treat it as a display-only row, put your handler on the
+  card root, and accept that the two buttons are decoration.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScWorkspaceCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Display only — this is genuinely all it can do.
+<ScWorkspaceCard
+  workspaceName="Kepler"
+  role="Admin"
+  userCount="12 Users"
+  ownerEmail="owner@example.com"
+  buttonText="Current workspace"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `workspaceName` | `string` | `"Stores"` | ⚠️ Real default. `text-md-medium`, `flex: 1`, single-line ellipsised. No `title` tooltip. |
+| `role` | `string` | `"Admin"` | ⚠️ Real default. Rendered by `ScBadges` with a hardcoded `variant="info"` and a **CSS-forced `width: 3.3125rem !important`** — anything longer than ~"Admin"/"Member" clips. |
+| `userCount` | `string` | `"12 Users"` | ⚠️ Real default, **including the unit word**. Rendered via `ScPairtext` with a `SiconTeam`. |
+| `ownerEmail` | `string` | `"rohan@streamoid.com"` | ⚠️ Real default — **a real Streamoid address**. Rendered via `ScPairtext` with a `SiconCrown`. Not truncated. |
+| `buttonText` | `string` | `"Current workspace"` | ⚠️ Real default. The label of the **permanently disabled** outline button (fixed `width: 12.5rem`). |
+| `className` | `string` | – | Concatenated unguarded — see Gotcha 7. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. This is the **only** way to attach behaviour. |
+
+### What is *not* a prop (and therefore cannot be done)
+
+| You probably want | Reality |
+|---|---|
+| `onSwitch` | Does not exist. The switch button is `state="disabled"`. |
+| `onLeave` | Does not exist. The leave button has no handler and no label. |
+| `initials` / `imageUrl` | Does not exist. The avatar is always `"WS"`. |
+| `isCurrent` / `type` | Does not exist. The card has no current-vs-other variant (dead CSS for it exists — see Gotcha 8). |
+| `plan` | Does not exist. Use `ScWorkspaceSwitchCard`, which has `plan`. |
+
+---
+
+## 2. Where to use it
+
+Nowhere, currently. **No host render site exists in CXO, Photogenix, Catalogix or
+Artifax.** Its role has been taken over by:
+
+| Surface | Current component |
+|---|---|
+| A single workspace row (current or other), with switch / settings / leave | `ScWorkspaceSwitchCard` |
+| The whole "Switch workspace" overlay, list + loading + empty | `StreamoidWorkspaceSwitcher` |
+| Mobile workspace switcher | `ScWorkspaceSwitchMobileV2` (older: `ScWorkspaceSwitchMobile`) |
+| Mobile workspace settings | `ScWorkspaceSettingsMobile` |
+| Sidebar workspace/switch strip (expanded + collapsed) | `ScSidebarSwitchMenu` (fed by `StreamoidSidebar`) |
+
+It composes `ScIntialProfileCover`, `ScBadges`, `ScPairtext`, `ScVDivider` and two
+`ScButton`s — so if you are looking for how those fit together, this file is still a
+useful reference even though the card itself is retired.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are maintaining an old screen that already renders it and you only need to
+  change strings.
+- You want a purely **static** workspace summary row and will supply your own
+  interaction on the root.
+
+Otherwise: don't.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A workspace row the user can switch to | `ScWorkspaceSwitchCard` (`type="otherWS"`, `onSwitch`) |
+| The current workspace with settings + leave actions | `ScWorkspaceSwitchCard` (`type="currentWS"`, `onSettings`, `onLeave`) |
+| The full switch-workspace modal/overlay | `StreamoidWorkspaceSwitcher` (`open`, `workspaces`, `onSwitchWorkspace`) |
+| Mobile workspace switching | `ScWorkspaceSwitchMobileV2` |
+| Mobile workspace settings screen | `ScWorkspaceSettingsMobile` |
+| The sidebar's workspace/switch strip | `ScSidebarSwitchMenu` |
+| A workspace **avatar** only | `ScDp` (image or initials) or `ScIntialProfileCover` |
+| A store, not a workspace | `ScStoreCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScWorkspaceSwitchCard` — `wsName`, `role`, `plan`, `ownerId`, `initials`, `imageUrl`, `type: "currentWS" \| "otherWS"`, `onSwitch`, `onSettings`, `onLeave`, derives initials from the name | `ScWorkspaceCard` has none of that |
+| `StreamoidWorkspaceSwitcher` — the whole overlay (`open`, `workspaces`, `loading`, `config`) | This is one static row |
+| `ScSidebarSwitchMenu` — the sidebar switch strip with `expanded`/`collapsed` variants | Different surface entirely |
+| `ScWorkspaceSwitchMobile` / `…MobileV2` — the mobile twins | This is desktop-shaped |
+| `NscWorkspaceSwitch` — an `@deprecated` alias of `ScWorkspaceSwitchCard` | Not related to this card |
+
+---
+
+## 4. Why to use it
+
+Honestly: you shouldn't. What it *does* give you, if you are stuck with it:
+
+- **Consistent identity row composition** — initials cover, name, role badge, and two
+  `ScPairtext` metrics separated by a `ScVDivider`, at the same spacing as the rest of
+  the workspace family.
+- **Tokenised surface and border** (`--alias-surface-base`, `--alias-border-subtle`,
+  `radius-3xl`, 24px padding) plus a `blur(0.25rem)` backdrop, so it sits correctly on
+  both themes.
+
+Everything else — real initials, a working switch action, a labelled leave action, a
+current-vs-other variant, a plan chip — is in `ScWorkspaceSwitchCard`.
+
+---
+
+## Gotchas
+
+**1. The switch button is permanently disabled.** `state="disabled"` is hardcoded in
+the component, which means `pointer-events: none`, `tabIndex={-1}` and
+`aria-disabled`. `buttonText` changes its label but never its state.
+
+```tsx
+// POINTLESS — there is no prop that enables this button
+<ScWorkspaceCard buttonText="Switch to this workspace" />
+
+// RIGHT — use the card that has the handler
+<ScWorkspaceSwitchCard wsName={ws.name} type="otherWS" onSwitch={() => switchTo(ws)} />
+```
+
+**2. The leave button renders no text and has no accessible name.** It is
+`styleVariant="icon-only"`, and `ScButton` only renders `text` on the
+`default`/`icon-left`/`icon-right` paths — so `"Leave workspace"` never appears. With
+no `aria-label`, screen readers announce an unnamed button.
+
+**3. The avatar always says "WS".** `ScIntialProfileCover` is rendered with no
+`intial`, so it falls back to its own default. There is no prop to pass the real
+workspace initials.
+
+**4. `ownerEmail` defaults to `rohan@streamoid.com`.** A real address. Never let this
+default reach a screen.
+
+**5. The role badge is width-clamped to 53px.** `.scBadgesInstance` sets
+`width: 3.3125rem !important`, sized for "Admin". "Owner", "Member" or a localised
+role will clip.
+
+**6. The `SiconSwitch` you can see in the source is never painted.** It is passed as
+`icon` to a `ScButton` whose `styleVariant` is left at `"default"`, and `ScButton`
+only renders the icon for `icon-left` / `icon-right` / `icon-only`. Dead code.
+
+**7. `className` is concatenated unguarded** (`styles.scWorkspaceCard + " " +
+className`), so omitting it puts a literal `undefined` class in the DOM.
+
+**8. There is dead CSS for a variant that does not exist.** The module defines
+`.current-workspace-true` / `.current-workspace-false` rules and a
+`.siconSwitchInstance2` size override; the component never applies any of those class
+names. Do not infer a `currentWorkspace` prop from them — there isn't one.
+
+**9. Clicks are ambiguous.** With `onClick` on the root: the disabled outline button
+has `pointer-events: none` so clicks fall through to the card, and the error
+icon-button does not stop propagation, so its clicks also reach the card. You cannot
+tell "leave" from "open".
+
+**10. Fixed-width children in a flexible row.** `.scButtonInstance` is
+`width: 12.5rem !important` and `flex-shrink: 0`; the card is `align-self: stretch`.
+On narrow containers the middle metrics block is what gets squeezed, so the owner
+email (not truncated) will overflow before the buttons shrink.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+More precisely: it is rendered nowhere at all — not in CXO, Photogenix, Catalogix or
+Artifax, and not by any other DS component. The surfaces it was drawn for (the
+workspace switcher list and the workspace settings row) are served by
+`ScWorkspaceSwitchCard` and `StreamoidWorkspaceSwitcher` today. If you are hunting for
+a real workspace-card call site, look at CXO's workspace switcher, which uses those.
+
+---
+
+## Related
+
+- `ScWorkspaceSwitchCard` — **the replacement**: current/other variants, real initials, `onSwitch`/`onSettings`/`onLeave`.
+- `StreamoidWorkspaceSwitcher` — the whole overlay built from those cards.
+- `ScWorkspaceSwitchMobileV2` / `ScWorkspaceSettingsMobile` — the mobile surfaces.
+- `ScSidebarSwitchMenu` — the sidebar workspace/switch strip. (Note: the unexported
+  `SC-Workspace/ScWorkspace` folder is *not* reachable from `@streamoid/ui` — don't
+  import it.)
+- `ScIntialProfileCover` / `ScDp` — the avatar primitives.
+- `ScPairtext` / `ScBadges` / `ScVDivider` — the parts this card composes.