@streamoid/ui 0.6.18 → 0.6.20

package/dist/docs/AGENTS.md

@@ -1,6 +1,6 @@
 # @streamoid/ui — component router (for AI agents)
 
-124 components. Full docs for each live beside this file as `<ScName>.md`;
+125 components. Full docs for each live beside this file as `<ScName>.md`;
 the same metadata is machine-readable in `components.json`.
 
 **How to use this file:** scan for the job you need below, then open only that
@@ -178,7 +178,10 @@ theme-aware (dark on `:root`, light override) — never hardcode a colour.
 - **`ScSidebarProfile`** _(legacy)_ — use when never. There is no way to pass a real user through it.
 - **`ScSidebarSwitchMenu`** — use when you're building a "switch to another product" list inside a sidebar and each entry needs a name **and** a subtitle.
 - **`ScVersion`** _(legacy)_ — use when never. `StreamoidSidebar` renders its own version footer inline from `versionText`.
+- **`ScWorkspaceAccountMenu`** — use when building the standard workspace menu opened from the top-left of a Streamoid application sidebar. - Use `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, and `ScSidebarAppIdentity` for the matching constant rail controls. - Use the two preference hooks so theme and expanded/collapsed state survive an app switch across Streamoid subdomains.
+  - also documented here: `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, `ScSidebarAppIdentity`, `useStreamoidThemePreference`, `useStreamoidSidebarPreference`
 - **`StreamoidSidebar`** — use when you are building (or fixing) a desktop app's primary left navigation and you want the same chrome CXO, Photogenix and Catalogix use.
+  - also documented here: `ScSidebarResizeHandle`, `advanceSidebarResizeGesture`, `SIDEBAR_RESIZE_THRESHOLD_PX`
 
 ## tables
 
@@ -265,6 +268,7 @@ theme-aware (dark on `:root`, light override) — never hardcode a colour.
 | `ScSidebarMenu` | `ScSidebarSwitchMenu`, `ScSidebar`, `ScMenuOptions`, `ScSettingsTabComp` |
 | `ScSidebarProfile` | `ScProfile`, `ScProfileOptions`, `ScProfilePopup`, `ScProfileSettingsComp`, `ScProfileV2Mobile`, `ScIntialProfileCover` |
 | `StreamoidSidebar` | `ScSidebar`, `ScArtifaxSidebar`, `ScCatalogixSidebar`, `ScSidebarMenu`, `ScLogoUnit` |
+| `ScWorkspaceAccountMenu` | `ScProfilePopup`, `ScWorkspaceSwitcher`, `ScAppSwitchPanel` |
 | `ScSlider` | `ScProgressBar`, `ScCounter`, `ScSelectionPillGroup`, `ScTabSwitcher` |
 | `ScStoreCard` | `ScCatalogixStoreTableList`, `ScDefaultCard`, `ScAppListingCard`, `ScWorkspaceCard` |
 | `ScSubAgent` | `ScInChatList`, `ScBadges`, `ScTaxonomyPill`, `ScSelectionPill` |

package/dist/docs/ScHDivider.md

@@ -23,9 +23,9 @@ semantics — it exists so nobody hand-rolls a `border-top` with a hex colour ag
 - **Don't reach for it when:** the rule runs vertically between two columns
   (→ `ScVDivider`), or you need a semantic `<hr>` in prose.
 - **Three things that will bite you:**
-  1. `IScHDividerProps` only declares `className`. `style`, `onClick`, `data-*`
-     are **TypeScript errors** even though they are spread onto the div at runtime.
-  2. It has **no margin**. Two sections separated by it will look cramped unless the
+  1. `fullBleed` is sized for the standard 8px (`--spacing-md`) card/sidebar
+     padding; use a custom class for a different inset.
+  2. By default it has **no margin**. Two sections separated by it will look cramped unless the
      parent supplies the gap.
   3. In a **flex-row** parent it vanishes (0.5px tall, no width). It needs a block
      or flex-column parent.
@@ -51,8 +51,9 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
-| `className` | `string` | – | Appended after the internal class. **The only typed prop** — it is your hook for margin, colour and width overrides. |
-| `...props` | *(untyped)* | – | ⚠️ Spread onto the root div at runtime, but `IScHDividerProps` does **not** extend `HTMLAttributes`, so passing `style`/`onClick`/`role`/`data-*` is a compile error. See Gotcha 1. |
+| `className` | `string` | – | Appended after the internal classes; use it for custom spacing, colour or width. |
+| `fullBleed` | `boolean` | `false` | Extends through the standard `--spacing-md` padding on both sides. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Native div attributes such as `style`, `role`, `aria-*`, and `data-*`. |
 
 ### What the stylesheet does
 
@@ -79,7 +80,7 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 // Inside a card, edge-to-edge under the header
 <div className={styles.card}>
   <CardHeader />
-  <ScHDivider className={styles.cardRule} />
+  <ScHDivider fullBleed />
   <CardBody />
 </div>
 ```
@@ -144,20 +145,16 @@ Used by all four host apps; it's part of the universal core.
 
 ## Gotchas
 
-**1. The props type is not `HTMLAttributes`.** The component spreads `...props`, but
-the interface declares `className` only — so the compiler rejects everything else.
+**1. `fullBleed` assumes standard padding.** It uses `--spacing-md` on each side.
+For a container with a different inset, provide a custom class instead.
 
 ```tsx
-// WRONG — TS error (Property 'style' does not exist on type 'IScHDividerProps')
-<ScHDivider style={{ margin: "8px 0" }} />
-
-// RIGHT — spacing via a class
-<ScHDivider className="my-2" />
+<ScHDivider fullBleed />
+<ScHDivider className={styles.customBleed} />
 ```
 
-**2. `className` is concatenated unconditionally.** Omitting it produces
-`class="scHDivider undefined"`. Harmless in a browser, but exact-`className`
-assertions in tests will fail.
+**2. Native div attributes are supported.** `style`, `role`, `aria-*`, and
+`data-*` are typed and forwarded to the root divider.
 
 **3. It disappears in a flex-row parent.** `height: 0.5px` beats `align-self:
 stretch`, and there is no `width`, so a row-direction parent gives it zero area.
@@ -174,8 +171,8 @@ stretch`, and there is no `width`, so a row-direction parent gives it zero area.
 </div>
 ```
 
-**4. No margin, ever.** The parent owns the rhythm. Use the parent's `gap`, or pass
-a spacing class.
+**4. No vertical margin.** The parent owns the rhythm. `fullBleed` only adds
+negative inline margins; use the parent's `gap` or a spacing class vertically.
 
 **5. No `color` prop.** Its sibling `ScVDivider` has one; this doesn't. To recolour,
 override `background-color` from your own class.

package/dist/docs/ScWorkspaceAccountMenu.md

@@ -0,0 +1,115 @@
+---
+component: ScWorkspaceAccountMenu
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [sidebar, workspace, account, app-switcher, theme, persistence]
+related: [StreamoidSidebar, ScArtifaxSidebar, ScAppSwitchPanel, ScProfilePopup]
+do_not_confuse_with: [ScProfilePopup, ScWorkspaceSwitcher, ScAppSwitchPanel]
+used_by: [cxo, artifax, catalogix, photogenix]
+required_props: [workspaceName, accountName]
+also_exports: [ScSidebarWorkspaceTrigger, ScSidebarSearchTrigger, ScSidebarAppIdentity, useStreamoidThemePreference, useStreamoidSidebarPreference]
+---
+
+# Shared Streamoid sidebar shell
+
+`ScWorkspaceAccountMenu` and its companion rail controls keep the constant
+sidebar chrome identical across Streamoid applications. The host still owns
+routes, navigation data, user/workspace data, positioning, and dialogs.
+
+## TL;DR for agents
+
+- **Reach for it when:** building the standard workspace menu opened from the
+  top-left of a Streamoid application sidebar.
+- Use `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, and
+  `ScSidebarAppIdentity` for the matching constant rail controls.
+- Use the two preference hooks so theme and expanded/collapsed state survive an
+  app switch across Streamoid subdomains.
+
+## 1. How to use it
+
+```tsx
+import {
+  ScWorkspaceAccountMenu,
+  useStreamoidSidebarPreference,
+  useStreamoidThemePreference,
+} from "@streamoid/ui";
+
+const sidebar = useStreamoidSidebarPreference({
+  legacyCollapsedKeys: ["my-app-sidebar-collapsed"],
+});
+const theme = useStreamoidThemePreference({
+  legacyStorageKeys: ["canvas_theme"],
+});
+```
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| `workspaceName` | `string` | required | Current workspace label. |
+| `workspaceRole` | `string` | `"Member"` | Role shown below the workspace. |
+| `workspaceImage` | `string` | none | Optional square workspace image. |
+| `credits` | `ReactNode` | none | Value shown as credits left beside Billing & Usage. |
+| `onSwitchWorkspace` | `() => void` | none | Opens the workspace switch/create flow. |
+| `onInviteMembers` | `() => void` | none | Opens workspace members. |
+| `onBilling` | `() => void` | none | Opens billing and usage. |
+| `organizationName` | `string` | none | Current organization name. |
+| `onOrganizationClick` | `() => void` | none | Opens organization settings. |
+| `accountName` | `string` | required | Signed-in user name. |
+| `accountEmail` | `string` | none | Signed-in email. |
+| `onAccountClick` | `() => void` | none | Opens account/profile settings. |
+| `themeMode` | `light \| dark \| system` | `system` | Selected theme icon. |
+| `onThemeModeChange` | `(mode) => void` | none | Updates the host theme. |
+
+```tsx
+<ScWorkspaceAccountMenu
+  workspaceName={workspace.name}
+  workspaceRole={workspace.role}
+  credits={workspace.credits}
+  organizationName={organization.name}
+  accountName={user.name}
+  accountEmail={user.email}
+  themeMode={theme.preference}
+  onThemeModeChange={theme.setPreference}
+/>
+```
+
+## 2. Where to use it
+
+Render the panel beside the top workspace trigger. Render the app identity at
+the bottom of the sidebar and open `ScAppSwitchPanel` from that row.
+
+## 3. When to use it
+
+Use it in authenticated application shells. Login pages, standalone settings
+screens, and embedded widgets should not render the full sidebar menu.
+
+## 4. Why to use it
+
+The package fixes layout, copy, theme selection, and app-switch affordances in
+one release. Apps only supply data and routing callbacks, avoiding five drifting
+copies of the same shell.
+
+## Gotchas
+
+- The menu is a panel body only; the host owns open state, placement, overlay,
+  outside-click dismissal, and mobile presentation.
+- The preference hooks write a parent-domain cookie on `.test.streamoid.com`
+  and `.streamoid.com`. On localhost the cookie is host-only and works across
+  ports.
+- Legacy sidebar keys describe the collapsed state, while the hook exposes the
+  positive `expanded` state. Both hooks continue mirroring supplied legacy keys
+  so older code in the same host stays synchronized during migration.
+
+## In the wild
+
+No host render site found before the `0.6.19` rollout. The first consumer is the
+CXO dashboard sidebar integration shipped with this release.
+
+## Related
+
+- `StreamoidSidebar` — the common config-driven rail.
+- `ScArtifaxSidebar` — the sectioned rail used by Artifax and Tactix.
+- `ScAppSwitchPanel` — the app list opened from the bottom app identity.
+- `ScProfilePopup` — the previous profile-first menu; do not use it for the new
+  workspace-first shell.

package/dist/docs/ScWorkspaceSwitchCard.md

@@ -27,17 +27,17 @@ hand-rolled in each.
   CTA (→ `ScWorkspaceCard`), a mobile row (→ `ScWorkspaceSwitchMobileV2`), or a bare
   workspace identity line (→ `ScProfilePopup`'s workspace block).
 - **Five things that will bite you:**
-  1. **Every action is hover-gated.** No hover → no buttons. Touch devices and
-     keyboard users can never reach them. That is why the `*Mobile` twins exist.
+  1. The secondary settings/leave actions are hover-gated. The whole `otherWS`
+     card is clickable and keyboard-activatable when `onSwitch` is supplied.
   2. `role` is a **free string** and drives everything: `role.toLowerCase() === "admin"`
      picks amber text **and** the settings button; anything else (including
      `"owner"`) gets info-blue and the **red leave** button.
-  3. Its props do **not** extend `HTMLAttributes` — no `onClick`, no `style`, no
-     `data-*`, no `aria-*`. Only the 12 listed props.
+  3. Its props do **not** extend `HTMLAttributes` — no custom `style`, `data-*`,
+     or `aria-*`. Use `onSwitch` for the card activation contract.
   4. ⚠️ `ownerId` defaults to a real person's address, **`"rohan@streamoid.com"`**,
      and `wsName` to `"Workspace name is kepler"`.
-  5. `cardOther` sets `cursor: pointer` on the whole card, but the card has **no
-     click handler** — only the buttons do. The cursor lies.
+  5. `onSwitch` is invoked by the whole `otherWS` card and by its hover button;
+     the button stops propagation so it fires only once.
 
 ---
 
@@ -76,7 +76,7 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 | `type` | `"currentWS"` \| `"otherWS"` | `"currentWS"` | ⚠️ Defaults to **current**. Drives surface, border, cursor and whether "Switch Workspace" can appear. |
 | `hover` | `boolean` | – | Controlled override of the internal hover state. `undefined` → the card tracks its own mouse enter/leave. Pass `true` to force the actions visible (Figma parity / tests). |
 | `className` | `string` | – | Appended after the internal classes. |
-| `onSwitch` | `() => void` | – | "Switch Workspace" button. **`otherWS` + hover only.** |
+| `onSwitch` | `() => void` | – | Activates the whole `otherWS` card and its hover button. |
 | `onSettings` | `() => void` | – | Settings icon button. **admin + hover only** (both `type`s). |
 | `onLeave` | `() => void` | – | Red leave button. **non-admin + hover only** (both `type`s). |
 
@@ -90,7 +90,7 @@ Nothing else is accepted — `ScWorkspaceSwitchCardProps` is a plain interface,
 | Surface | `surface-raised` + `border-default`, `cursor: default` | `surface-base` + `border-subtle`, `cursor: pointer`; hover → `surface-basesubtle` |
 | Tile | `ScDp` forced to **90 × 90**, `radius-xl`, bg `neutralactive` | same, bg `neutralselected` |
 | Details | Role · Plan · Workspace Owner, split by two `ScVDivider`s | identical |
-| "Switch Workspace" | **never** | hover only |
+| Switch action | **never** | whole card; labelled button also appears on hover |
 | Settings icon | hover **and** `role` is admin | hover **and** `role` is admin |
 | Leave (red) | hover **and** `role` is not admin | hover **and** `role` is not admin |
 
@@ -133,12 +133,12 @@ Role colour: admin → `text-and-icons-warning` (amber); everything else →
 // Force the actions visible — screenshots, Figma parity, or a touch fallback
 <ScWorkspaceSwitchCard wsName={ws.name} type="otherWS" hover onSwitch={switchTo} />
 
-// Make the whole row keyboard-reachable (the card gives you no semantics)
-<div role="button" tabIndex={0}
-     onClick={() => void switchTo(ws)}
-     onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); void switchTo(ws); } }}>
-  <ScWorkspaceSwitchCard wsName={ws.name} type="otherWS" onSwitch={() => void switchTo(ws)} />
-</div>
+// The other-workspace card is pointer and keyboard reachable by default.
+<ScWorkspaceSwitchCard
+  wsName={ws.name}
+  type="otherWS"
+  onSwitch={() => void switchTo(ws)}
+/>
 ```
 
 ---
@@ -224,10 +224,9 @@ is the DS's own attempt at that modal, but no app uses it (see its README).
 
 ## Gotchas
 
-**1. All actions are hover-only, and they are plain `<div onClick>`s.** No `role`, no
-`tabIndex`, no keyboard activation. A keyboard-only or touch user cannot switch, open
-settings or leave from this card. Provide your own path (a wrapping `role="button"`,
-or `hover` forced on for touch), or use the `*Mobile` twins.
+**1. Settings and leave remain hover/focus actions.** Switching is available by
+clicking or pressing Enter/Space on the whole `otherWS` card. Touch-first layouts
+that need settings/leave should still use the `*Mobile` twins.
 
 **2. `role` is a free string with real consequences.**
 
@@ -250,13 +249,12 @@ treated as a non-admin.
 `"Free" + "rohan@streamoid.com"` because the store's `/workspaces` payload has no
 plan. Always pass real values, or `""`.
 
-**4. No `onClick` / `style` / `data-*` on the card.** The interface lists 12 props and
-does not extend `HTMLAttributes`. To make the whole row clickable, wrap it (and note
-the inner buttons already `stopPropagation`, so a wrapper handler won't double-fire).
+**4. No custom `onClick` / `style` / `data-*` props.** The interface does not
+extend `HTMLAttributes`; use the semantic `onSwitch`, `onSettings`, and `onLeave`
+callbacks.
 
-**5. The `otherWS` cursor implies a click that does not exist.** `.cardOther` sets
-`cursor: pointer` on the whole card, but only the "Switch Workspace" button is wired.
-Either wrap the card in your own click handler or accept the mismatch.
+**5. The whole `otherWS` card switches.** Do not wrap it in a second click handler,
+or the same transition may be requested twice.
 
 **6. `ScDp`'s `size` is overridden.** `.dp` forces `width/height: 90px !important`, so
 the nested tile is always 90px regardless of anything you would pass. The tile's

package/dist/docs/StreamoidSidebar.md

@@ -9,6 +9,7 @@ related: [ScSideBarLogoUnit, ScAppSwitchPanel, ScSidebarMenu, ScAskAgentButton,
 do_not_confuse_with: [ScSidebar, ScArtifaxSidebar, ScCatalogixSidebar, ScSidebarMenu, ScLogoUnit]
 used_by: [cxo, photogenix, catalogix]
 required_props: [expanded, onToggle, config, iconMap]
+also_exports: [ScSidebarResizeHandle, advanceSidebarResizeGesture, SIDEBAR_RESIZE_THRESHOLD_PX]
 ---
 
 # StreamoidSidebar
@@ -80,6 +81,8 @@ const iconMap: SidebarIconMap = { bag: <SiconBag /> };
 |---|---|---|---|
 | `expanded` | `boolean` | — | **Required.** You own the state. `true` → 256px rounded card; `false` → 56px rail. Two completely different render branches. |
 | `onToggle` | `() => void` | — | **Required.** Fired by the collapse toggle (and the mobile close icon). |
+| `resizable` | `boolean` | `false` | Shows the shared 12px right-edge resize handle on desktop. The rail still has only expanded and collapsed widths. |
+| `onExpandedChange` | `(expanded: boolean) => void` | – | Controlled resize callback. One drag may call it more than once as the pointer reverses; omit it to fall back to `onToggle`. |
 | `config` | `SidebarConfig` | — | **Required.** `{ topItem?, sections, bottomItems? }`. Pass `{ sections: [] }` if you drive nav via `bodyContent`. |
 | `iconMap` | `SidebarIconMap` | — | **Required.** `Record<iconKey, ReactNode \| ({item, active, expanded}) => ReactNode>`. A missing key renders **no icon**, silently. |
 | `activeItemId` | `string` | – | Matching item gets `state="active"`. |
@@ -337,6 +340,13 @@ no `<nav>`/`aria-label`; wrap it yourself:
 is `width: 56`. Not responsive, not overridable via props — hosts measure these
 constants themselves.
 
+The optional resize edge is a two-state gesture, not a free-width splitter.
+After either state change it re-anchors at the crossing point, so the user can
+collapse and expand again in the same uninterrupted drag. Hosts should pass a
+controlled setter: `onExpandedChange={setExpanded}`. In the collapsed state,
+the 12px hit target straddles the rail boundary and its blue line renders just
+outside the rail; expanded positioning remains on the wrapper's outside edge.
+
 **12. Tailwind utilities are a hard requirement.** The component's structure is
 `className="flex flex-col flex-1 min-h-0 overflow-y-auto shrink-0 truncate …"` with
 inline styles only for colours/spacing. `dist/index.css` ships the

package/dist/docs/components.json

@@ -1,6 +1,6 @@
 {
   "package": "@streamoid/ui",
-  "count": 124,
+  "count": 125,
   "components": {
     "ScAccess": {
       "doc": "ScAccess.md",
@@ -2691,7 +2691,57 @@
         "photogenix",
         "catalogix"
       ],
-      "alsoExports": [],
+      "alsoExports": [
+        "ScSidebarResizeHandle",
+        "advanceSidebarResizeGesture",
+        "SIDEBAR_RESIZE_THRESHOLD_PX"
+      ],
+      "exported": true
+    },
+    "ScWorkspaceAccountMenu": {
+      "doc": "ScWorkspaceAccountMenu.md",
+      "source": "src/SC-SidebarShell",
+      "category": "sidebar",
+      "status": "stable",
+      "renders": "div",
+      "summary": "Reach for it when:",
+      "reachForWhen": "building the standard workspace menu opened from the top-left of a Streamoid application sidebar. - Use `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, and `ScSidebarAppIdentity` for the matching constant rail controls. - Use the two preference hooks so theme and expanded/collapsed state survive an app switch across Streamoid subdomains.",
+      "tags": [
+        "sidebar",
+        "workspace",
+        "account",
+        "app-switcher",
+        "theme",
+        "persistence"
+      ],
+      "related": [
+        "StreamoidSidebar",
+        "ScArtifaxSidebar",
+        "ScAppSwitchPanel",
+        "ScProfilePopup"
+      ],
+      "doNotConfuseWith": [
+        "ScProfilePopup",
+        "ScWorkspaceSwitcher",
+        "ScAppSwitchPanel"
+      ],
+      "requiredProps": [
+        "workspaceName",
+        "accountName"
+      ],
+      "usedBy": [
+        "cxo",
+        "artifax",
+        "catalogix",
+        "photogenix"
+      ],
+      "alsoExports": [
+        "ScSidebarWorkspaceTrigger",
+        "ScSidebarSearchTrigger",
+        "ScSidebarAppIdentity",
+        "useStreamoidThemePreference",
+        "useStreamoidSidebarPreference"
+      ],
       "exported": true
     },
     "ScSlider": {
@@ -4837,6 +4887,38 @@
       "documentedIn": "ScSideBarLogoUnit",
       "doc": "ScSideBarLogoUnit.md"
     },
+    "ScSidebarResizeHandle": {
+      "documentedIn": "StreamoidSidebar",
+      "doc": "StreamoidSidebar.md"
+    },
+    "advanceSidebarResizeGesture": {
+      "documentedIn": "StreamoidSidebar",
+      "doc": "StreamoidSidebar.md"
+    },
+    "SIDEBAR_RESIZE_THRESHOLD_PX": {
+      "documentedIn": "StreamoidSidebar",
+      "doc": "StreamoidSidebar.md"
+    },
+    "ScSidebarWorkspaceTrigger": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "ScSidebarSearchTrigger": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "ScSidebarAppIdentity": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "useStreamoidThemePreference": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "useStreamoidSidebarPreference": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
     "formatSubAgentLabel": {
       "documentedIn": "ScSubAgent",
       "doc": "ScSubAgent.md"