@streamoid/ui 0.6.30 → 0.6.32

package/dist/docs/AGENTS.md

@@ -166,7 +166,7 @@ theme-aware (dark on `:root`, light override) — never hardcode a colour.
 
 - **`CreditWarningBanner`** — use when you need the "you're nearly out of credits" nudge in a sidebar rail, in either expanded or collapsed form.
 - **`ScAppSwitchPanel`** — use when you need the "go to another Streamoid product" list — in `StreamoidSidebar`'s `switchPanel`, or in your own portalled flyout.
-  - also documented here: `ScAppSwitchRow`, `createStreamoidAppSwitchUtilities`, `streamoidAppSwitchTagline`, `streamoidChangelogUrl`, `STREAMOID_CHANGELOG_URLS`, `STREAMOID_CHANGELOG_URL`, `STREAMOID_STATUS_PAGE_URL`
+  - also documented here: `ScAppSwitchRow`, `scAppSwitchOrder`, `createStreamoidAppSwitchUtilities`, `streamoidAppSwitchTagline`, `formatStreamoidAppVersion`, `streamoidChangelogUrl`, `STREAMOID_CHANGELOG_URLS`, `STREAMOID_CHANGELOG_URL`, `STREAMOID_STATUS_PAGE_URL`
 - **`ScArtifaxSidebar`** — use when you are working on the Artifax (or Tactix) shell, or you need a sidebar whose sections the user can collapse.
 - **`ScAskAgentButton`** — use when you need the assistant-panel CTA **outside** a DS sidebar. Inside one, use the sidebar's `assistantCta` prop instead.
   - also documented here: `ScAskAgentSlot`, `AssistantCta`
@@ -180,8 +180,8 @@ 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. - Use `useStreamoidSidebarPopoverPosition` for the upper-right workspace menu and lower-right app switcher instead of hard-coded host coordinates.
-  - also documented here: `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, `ScSidebarAppIdentity`, `useStreamoidThemePreference`, `useStreamoidSidebarPreference`, `useStreamoidSidebarPopoverPosition`
+- **`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. - Use `useStreamoidSidebarPopoverPosition` for a panel that belongs to the whole rail (the upper-right workspace menu) instead of hard-coded host coordinates. - Use `useStreamoidAnchoredPopoverPosition` for a panel that belongs to a BUTTON — the app switcher's grid trigger, a row's overflow menu. Pinning one of those to the sidebar card's edge leaves it floating mid-canvas with nothing connecting it to what was clicked; in Artifax it landed over the chat composer and its Send button.
+  - also documented here: `ScSidebarWorkspaceTrigger`, `ScSidebarSearchTrigger`, `ScSidebarAppIdentity`, `ScPopoverArrow`, `useStreamoidThemePreference`, `useStreamoidSidebarPreference`, `useStreamoidSidebarPopoverPosition`, `useStreamoidAnchoredPopover`, `useStreamoidAnchoredPopoverPosition`, `resolveAnchoredPopoverArrow`, `resolveAnchoredPopoverPosition`
 - **`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`
 

package/dist/docs/ScAppSwitchPanel.md

@@ -1,6 +1,6 @@
 ---
 component: ScAppSwitchPanel
-also_exports: [ScAppSwitchRow, createStreamoidAppSwitchUtilities, streamoidAppSwitchTagline, streamoidChangelogUrl, STREAMOID_CHANGELOG_URLS, STREAMOID_CHANGELOG_URL, STREAMOID_STATUS_PAGE_URL]
+also_exports: [ScAppSwitchRow, scAppSwitchOrder, createStreamoidAppSwitchUtilities, streamoidAppSwitchTagline, formatStreamoidAppVersion, streamoidChangelogUrl, STREAMOID_CHANGELOG_URLS, STREAMOID_CHANGELOG_URL, STREAMOID_STATUS_PAGE_URL]
 package: "@streamoid/ui"
 category: sidebar
 status: stable
@@ -16,8 +16,13 @@ required_props: [apps]
 
 **The cross-product "switch app" list — one identical implementation for all four
 apps.** A bare column of 60px rows, each showing the target product's wordmark
-(gray, brightening to white on hover) and a `>` chevron that fades in. It has no
-card, no border and no background: the surrounding sidebar or flyout supplies those.
+(gray, brightening to white on hover) under an **Apps** group label, with the
+utility rows under a **Help** one. It has no card, no border and no background:
+the surrounding sidebar or flyout supplies those.
+
+No chevrons: every product row navigates, so an arrow on each of them
+distinguishes nothing. The only trailing glyph is the check on the row you are
+already on.
 
 ## TL;DR for agents
 
@@ -30,13 +35,16 @@ card, no border and no background: the surrounding sidebar or flyout supplies th
 - **Four things that will bite you:**
   1. It **re-sorts your array** into a canonical product order. Your ordering is
      discarded.
-  2. Known products render the **canonical tagline** (e.g. "for buyers and
+  2. Known products render the **canonical tagline** (e.g. "Buyers and
      planners"), not `description` and not the product `name`. Do not copy that
-     map into a host.
+     map into a host. Taglines name what the product is; none of them start with
+     "for".
   3. Matching is a **substring** test over `` `${key} ${name}`.toLowerCase() ``. A key
      containing `"cxo"` or `"streamoid"` gets the **CXO** wordmark — but the four
      product names are matched first, so `"Streamoid Catalogix"` is Catalogix.
-  4. It does **not** exclude the current app. That's the host's job.
+  4. **Pass every product, including the one you are in**, marked `current`.
+     Omitting it (which hosts used to do) changes the list's length per surface,
+     so rows move between apps and the hub has no row in its own switcher.
 
 ---
 
@@ -59,8 +67,13 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 ```tsx
 <ScAppSwitchPanel
   apps={[
-    { key: "artifax",    name: "Artifax",    onSelect: () => open(artifaxUrl) },
+    // Every product, always, in every app. `current` marks where you are; its
+    // `onSelect` is never called, so a no-op is fine.
+    { key: "cxo",        name: "CXO",        onSelect: () => open(cxoUrl) },
+    { key: "tactix",     name: "Tactix",     onSelect: () => open(tactixUrl) },
+    { key: "artifax",    name: "Artifax",    current: true, onSelect: () => {} },
     { key: "photogenix", name: "Photogenix", onSelect: () => open(photogenixUrl) },
+    { key: "catalogix",  name: "Catalogix",  onSelect: () => open(catalogixUrl) },
   ]}
   utilities={{
     appVersion: APP_VERSION,
@@ -75,8 +88,11 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 | Prop | Type | Default | Notes |
 |---|---|---|---|
 | `apps` | `ScAppSwitchItem[]` | — | **Required.** ⚠️ **Re-sorted internally** into canonical order; unknown products keep their relative order and go last. |
-| `utilities` | `ScAppSwitchUtilities` | – | Adds the standard Changelog + app version, Status Page, and Help and Support rows. |
+| `utilities` | `ScAppSwitchUtilities` | – | Adds the standard **What's new** + version, **Status**, and **Help and Support** rows. |
 | `systemItems` | `ScAppSwitchSystemItem[]` | – | Fully custom utility rows. Overrides `utilities` when supplied. |
+| `title` | `string \| null` | `null` | Off by default. It used to read "Switch Apps" above a list of apps, inside a panel opened by a button of the same name. |
+| `appsLabel` | `string \| null` | `"Apps"` | Group label above the products. |
+| `systemLabel` | `string \| null` | `"Help"` | Group label above the utility rows. |
 | `className` | `string` | – | On the root column. |
 | `style` | `CSSProperties` | – | Merged **after** the base inline styles, so it can override `paddingBottom`. |
 
@@ -86,6 +102,19 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 |---|---|---|---|
 | `item` | `ScAppSwitchItem` | — | **Required.** The only prop — no `className`, no `style`. Rarely used directly; the panel renders one per app. |
 
+### `formatStreamoidAppVersion(raw)`
+
+What the **What's new** row shows, from whatever the host's build stamped.
+Returns `v2.4` for `2.4`/`v2.4`, `v0.1.1` for `v0.1.1-dev`, and **`undefined`**
+for anything that is not a version — a commit hash (Artifax was showing
+`7f79e00`) or a bare `dev` (Tactix, `Vdev`). `utilities` applies it; hosts do
+not need to.
+
+### `scAppSwitchOrder(apps)`
+
+The canonical ordering, exported so a host (or a test) can assert the row order
+without rendering. The panel applies it already — hosts do not need to sort.
+
 ### `ScAppSwitchItem`
 
 | Field | Type | Notes |
@@ -93,7 +122,8 @@ import "@streamoid/ui/dist/index.css"; // once, at your app root
 | `key` | `string` | React key **and** half of the wordmark-matching string. |
 | `name` | `string` | Matching input, and the fallback label. ⚠️ **Not rendered** when a wordmark matches. Always used for the row's `aria-label` (`"Switch to {name}"`). |
 | `description` | `string` | Optional. Ignored for known products (the panel uses the canonical tagline). Shown only for unknown products. |
-| `onSelect` | `() => void` | Row click. |
+| `current` | `boolean` | Optional. This is the app you are in: the row is filled (`--alias-fill-neutral-neutralselected`), carries a **check** instead of the chevron, gets `aria-current="true"` + `aria-disabled`, and does **not** call `onSelect`. It stays focusable on purpose — it is the answer to "where am I". |
+| `onSelect` | `() => void` | Row click. Never called on the `current` row. |
 
 ### Wordmark matching + canonical order
 

package/dist/docs/ScWorkspaceAccountMenu.md

@@ -9,7 +9,7 @@ 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, useStreamoidSidebarPopoverPosition]
+also_exports: [ScSidebarWorkspaceTrigger, ScSidebarSearchTrigger, ScSidebarAppIdentity, ScPopoverArrow, useStreamoidThemePreference, useStreamoidSidebarPreference, useStreamoidSidebarPopoverPosition, useStreamoidAnchoredPopover, useStreamoidAnchoredPopoverPosition, resolveAnchoredPopoverArrow, resolveAnchoredPopoverPosition]
 ---
 
 # Shared Streamoid sidebar shell
@@ -27,8 +27,14 @@ shared popover-position hook keeps the desktop anchors consistent.
   `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.
-- Use `useStreamoidSidebarPopoverPosition` for the upper-right workspace menu
-  and lower-right app switcher instead of hard-coded host coordinates.
+- Use `useStreamoidSidebarPopoverPosition` for a panel that belongs to the
+  whole rail (the upper-right workspace menu) instead of hard-coded host
+  coordinates.
+- Use `useStreamoidAnchoredPopoverPosition` for a panel that belongs to a
+  BUTTON — the app switcher's grid trigger, a row's overflow menu. Pinning one
+  of those to the sidebar card's edge leaves it floating mid-canvas with nothing
+  connecting it to what was clicked; in Artifax it landed over the chat
+  composer and its Send button.
 
 ## 1. How to use it
 
@@ -50,12 +56,33 @@ const workspaceMenuPosition = useStreamoidSidebarPopoverPosition(sidebarRef, {
   placement: "top-right",
   width: 320,
 });
-const appSwitcherPosition = useStreamoidSidebarPopoverPosition(sidebarRef, {
-  placement: "bottom-right",
-  width: 240,
-});
+// Tethered to the trigger, flipping only to stay on screen: beside the button
+// and running down from its top edge, to the button's other side when that side
+// has no room, and upward (bottom aligned to the trigger) when there is no room
+// below — which is what a footer grid button gets.
+const appSwitcherPosition = useStreamoidAnchoredPopoverPosition(
+  triggerRef,
+  panelRef,
+  { width: 240 },
+);
 ```
 
+### `useStreamoidAnchoredPopoverPosition(anchorRef, panelRef, options)`
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `width` | `number` | — | **Required.** Panel width; narrowed to the viewport when it cannot fit. |
+| `gap` | `number` | `8` | Distance between the trigger and the panel. |
+| `inset` | `number` | `16` | Keep-out margin from the viewport edges. |
+
+Pass a ref to the panel as well as the trigger: the vertical flip needs the
+panel's measured height, so the first frame opens downward and settles once
+measured. Re-measures on resize, on scroll (capture phase — a rail can scroll
+without bubbling), and while either element changes size.
+
+`resolveAnchoredPopoverPosition(geometry)` is the same rules as a pure
+function, exported for hosts that position their own portal and for tests.
+
 | Prop | Type | Default | Purpose |
 |---|---|---|---|
 | `workspaceName` | `string` | required | Current workspace label. |
@@ -132,3 +159,44 @@ CXO dashboard sidebar integration shipped with this release.
 - `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.
+
+## `useStreamoidAnchoredPopover` + `ScPopoverArrow`
+
+A popover tethered to the control that opened it, **with the caret that proves
+it**. Same placement rules as `useStreamoidAnchoredPopoverPosition` (beside the
+trigger, collision-flip only) and it additionally returns where the caret goes:
+
+```tsx
+const { style, arrow } = useStreamoidAnchoredPopover(anchorRef, panelRef, {
+  width: 260,
+});
+
+return createPortal(
+  <div
+    ref={panelRef}
+    style={{ ...style, background: SURFACE, border: `1px solid ${BORDER}`, borderRadius: 16 }}
+  >
+    <ScPopoverArrow arrow={arrow} background={SURFACE} borderColor={BORDER} />
+    <div style={{ borderRadius: 16, overflow: "hidden" }}>{children}</div>
+  </div>,
+  document.body,
+);
+```
+
+Two things will bite you:
+
+1. **`overflow: hidden` on the card clips the caret off.** The caret hangs
+   half outside the panel by design. Round and clip an INNER box instead, as
+   above.
+2. **The caret is not decoration.** A tall panel opened from a button at the
+   foot of a rail flips upward — its bottom edge level with the button — and
+   without the caret it reads as a card floating mid-canvas that happens to be
+   nearby. That was reported twice as "the popover still isn't tethered".
+
+`arrow` is `null` until the panel has been measured; `ScPopoverArrow` renders
+nothing for it, so there is no flash of a caret in the wrong place.
+
+Use the same hook for **every** popover a rail owns. Mixing it with
+`useStreamoidSidebarPopoverPosition` (which pins to the sidebar CARD's edge)
+puts two menus from the same rail in visibly different places — one tethered to
+its button, one parked against a container edge.

package/dist/docs/components.json

@@ -162,8 +162,10 @@
       ],
       "alsoExports": [
         "ScAppSwitchRow",
+        "scAppSwitchOrder",
         "createStreamoidAppSwitchUtilities",
         "streamoidAppSwitchTagline",
+        "formatStreamoidAppVersion",
         "streamoidChangelogUrl",
         "STREAMOID_CHANGELOG_URLS",
         "STREAMOID_CHANGELOG_URL",
@@ -2757,7 +2759,7 @@
       "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. - Use `useStreamoidSidebarPopoverPosition` for the upper-right workspace menu and lower-right app switcher instead of hard-coded host coordinates.",
+      "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. - Use `useStreamoidSidebarPopoverPosition` for a panel that belongs to the whole rail (the upper-right workspace menu) instead of hard-coded host coordinates. - Use `useStreamoidAnchoredPopoverPosition` for a panel that belongs to a BUTTON — the app switcher's grid trigger, a row's overflow menu. Pinning one of those to the sidebar card's edge leaves it floating mid-canvas with nothing connecting it to what was clicked; in Artifax it landed over the chat composer and its Send button.",
       "tags": [
         "sidebar",
         "workspace",
@@ -2791,9 +2793,14 @@
         "ScSidebarWorkspaceTrigger",
         "ScSidebarSearchTrigger",
         "ScSidebarAppIdentity",
+        "ScPopoverArrow",
         "useStreamoidThemePreference",
         "useStreamoidSidebarPreference",
-        "useStreamoidSidebarPopoverPosition"
+        "useStreamoidSidebarPopoverPosition",
+        "useStreamoidAnchoredPopover",
+        "useStreamoidAnchoredPopoverPosition",
+        "resolveAnchoredPopoverArrow",
+        "resolveAnchoredPopoverPosition"
       ],
       "exported": true
     },
@@ -4912,6 +4919,10 @@
       "documentedIn": "ScAppSwitchPanel",
       "doc": "ScAppSwitchPanel.md"
     },
+    "scAppSwitchOrder": {
+      "documentedIn": "ScAppSwitchPanel",
+      "doc": "ScAppSwitchPanel.md"
+    },
     "createStreamoidAppSwitchUtilities": {
       "documentedIn": "ScAppSwitchPanel",
       "doc": "ScAppSwitchPanel.md"
@@ -4920,6 +4931,10 @@
       "documentedIn": "ScAppSwitchPanel",
       "doc": "ScAppSwitchPanel.md"
     },
+    "formatStreamoidAppVersion": {
+      "documentedIn": "ScAppSwitchPanel",
+      "doc": "ScAppSwitchPanel.md"
+    },
     "streamoidChangelogUrl": {
       "documentedIn": "ScAppSwitchPanel",
       "doc": "ScAppSwitchPanel.md"
@@ -5012,6 +5027,10 @@
       "documentedIn": "ScWorkspaceAccountMenu",
       "doc": "ScWorkspaceAccountMenu.md"
     },
+    "ScPopoverArrow": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
     "useStreamoidThemePreference": {
       "documentedIn": "ScWorkspaceAccountMenu",
       "doc": "ScWorkspaceAccountMenu.md"
@@ -5024,6 +5043,22 @@
       "documentedIn": "ScWorkspaceAccountMenu",
       "doc": "ScWorkspaceAccountMenu.md"
     },
+    "useStreamoidAnchoredPopover": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "useStreamoidAnchoredPopoverPosition": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "resolveAnchoredPopoverArrow": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
+    "resolveAnchoredPopoverPosition": {
+      "documentedIn": "ScWorkspaceAccountMenu",
+      "doc": "ScWorkspaceAccountMenu.md"
+    },
     "formatSubAgentLabel": {
       "documentedIn": "ScSubAgent",
       "doc": "ScSubAgent.md"