@sybilion/uilib 1.2.4 → 1.2.5

package/docs/standalone-apps.md

@@ -2,7 +2,7 @@
 
 Greenfield SPA on **your own origin**: `@sybilion/uilib` for layout/UI, `SybilionAuthProvider` + Sybilion API for data—no iframe in the main client.
 
-**Agents / humans:** use `AppShell` + `AppShellMainContent`; stick to uilib spacing primitives (e.g. `Gap`) instead of ad hoc root horizontal gutters.
+**Agents / humans:** `AppShell` + `AppShellMainContent`; spacing via uilib primitives (e.g. `Gap`), not ad hoc gutters. **Each `<Route>` page:** follow **§4 Route page body** (one canonical pattern below); **Discovering** explains how to find other `@sybilion/uilib` exports.
 
 **Local-first:** After scaffolding, the user should run **`yarn dev`** (or `npm run dev`) on **localhost** with **no deploy** (e.g. Vercel) required. Commit **`.env.example`**; the user copies it to **`.env`**. In development, the Sybilion API is reached via a **same-origin `/api` proxy** so the browser avoids CORS; production builds still use `VITE_SYBILION_API_BASE_URL` on the client, and the real API must allow **CORS** for your deployed `Origin` unless you terminate API calls on the same host.
 
@@ -41,12 +41,12 @@ Add a **`dev`** script so the app is runnable immediately after clone. Typical V
 
 Commit **`.env.example`** at the app root (no secrets). Minimum variables:
 
-| Variable | Purpose |
-| -------- | ------- |
-| `PORT` | Vite **dev** and **preview** server port. **`PORT=3000`** matches the current **Auth0 test tenant** (`http://localhost:3000` callback / web origins). Override if your tenant uses another port. |
-| `VITE_SYBILION_API_BASE_URL` | Real Sybilion API origin (no trailing slash). Used as **proxy target** in dev and as SDK `baseUrl` in production builds. |
-| `VITE_AUTH0_DOMAIN` | Auth0 domain (§3). |
-| `VITE_AUTH0_CLIENT_ID` | Auth0 SPA client id (§3). |
+| Variable                     | Purpose                                                                                                                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `PORT`                       | Vite **dev** and **preview** server port. **`PORT=3000`** matches the current **Auth0 test tenant** (`http://localhost:3000` callback / web origins). Override if your tenant uses another port. |
+| `VITE_SYBILION_API_BASE_URL` | Real Sybilion API origin (no trailing slash). Used as **proxy target** in dev and as SDK `baseUrl` in production builds.                                                                         |
+| `VITE_AUTH0_DOMAIN`          | Auth0 domain (§3).                                                                                                                                                                               |
+| `VITE_AUTH0_CLIENT_ID`       | Auth0 SPA client id (§3).                                                                                                                                                                        |
 
 Example **`.env.example`** content for the app root:
 
@@ -102,9 +102,9 @@ Package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk)
 Avoid browser CORS in development by serving the SPA from Vite and proxying **`/api`** to the real API. Use **`sybilionStandaloneViteDev`** from `@sybilion/uilib/vite-standalone-dev` in **`vite.config.ts`**: it reads **`PORT`** (defaults to **3000** if unset or invalid) for **`server`** / **`preview`**, and sets **`proxy['/api']`** → **`VITE_SYBILION_API_BASE_URL`** with `changeOrigin` and `secure: true`.
 
 ```ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
 import { sybilionStandaloneViteDev } from '@sybilion/uilib/vite-standalone-dev';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
 
 export default defineConfig(({ mode }) => ({
   ...sybilionStandaloneViteDev({ mode }),
@@ -114,6 +114,14 @@ export default defineConfig(({ mode }) => ({
 
 Combine with an **empty `baseUrl` in dev** in the SDK module (§2). In **`preview`** builds, keep **`.env`** with **`VITE_SYBILION_API_BASE_URL`** so `vite preview` can still proxy API calls locally.
 
+## Discovering `@sybilion/uilib` components (agents)
+
+Prefer **`@sybilion/uilib`** over bespoke layout/controls.
+
+1. **Barrel:** uilib repo `src/index.ts`, or **`node_modules/@sybilion/uilib/dist/esm/types/index.d.ts`** after install — scan `export * from './components/ui/...'`.
+2. **Page cluster:** `PageScroll`, `AppShell`, `PageHeader`, `PageFooter`, tabs/columns, **`SybilionAppHeader`** (workspace switcher + **`NavUserHeader`**), etc. come from the same package; **what to compose and when** lives only in **§4 Route page body** (not repeated here).
+3. **Examples:** `src/docs/pages/*Page.tsx`; **`PagePage`** (`slug page`) — minimal **`PageContent` + `PageContentSection`**.
+
 ## Local dev: apps with a Go server
 
 Some templates include a **Go** server. This repo does **not** provide Go middleware. The contract: whatever serves the **same origin the browser uses for the SPA** must **reverse-proxy** path prefix **`/api`** (or your SDK `apiPrefix`) to the Sybilion API. Use **`baseUrl: ''`** in dev when those requests are same-origin. Name and document server-side env vars (e.g. API upstream URL) in the Go project.
@@ -206,26 +214,32 @@ export function App() {
 
 ### `AppLayout` (sidebar + main + `children`)
 
-`AppHeaderHost` is the header anchor; put `SidebarTrigger` (collapses / opens rail), `NavUserHeader`, etc. inside `AppHeaderPortal`. `AppSidebar` (next subsection) is a sibling of `AppShellMainContent` inside `AppShell`. The matched route (the `<Routes>` subtree from `App.tsx`) arrives as `children` and renders inside the main column.
+`AppSidebar` is a sibling of `AppShellMainContent` inside `AppShell`. The matched route (`<Routes>` from `App.tsx`) renders as `{children}` in the main column.
+
+**Header row:** pass **`header={<AppHeaderHost />}`** to **`AppShellMainContent`**, then **`SybilionAppHeader`** as the **first** child before `{children}`. **`SybilionAppHeader`** portals workspace switcher + embedded **`NavUserHeader`** into that shell header (and **`page-header-actions`** so **`PageHeader`** toolbars line up).
+
+Props: all **`WorkspaceAppSwitcher`** props plus all **`NavUserHeader`** props (`user`, **`menuItems`** as **`DropdownMenuItem`** rows, **`theme`**, **`onLogout`**, etc.), and optional **`pageHeaderId`**, **`actionsAnchorId`**, **`actionsAnchorClassName`**.
 
 ```tsx
 import type { ReactNode } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
 
 import {
   AppHeaderHost,
-  AppHeaderPortal,
   AppShell,
   AppShellMainContent,
-  Gap,
-  NavUserHeader,
+  DropdownMenuItem,
   PageFooter,
   PageScroll,
-  SidebarTrigger,
+  SybilionAppHeader,
 } from '@sybilion/uilib';
 
 import { AppSidebar } from './AppSidebar';
 
 export function AppLayout({ children }: { children: ReactNode }) {
+  const location = useLocation();
+  const navigate = useNavigate();
+
   return (
     <PageScroll>
       <AppShell>
@@ -235,16 +249,24 @@ export function AppLayout({ children }: { children: ReactNode }) {
           header={<AppHeaderHost />}
           footer={<PageFooter versionLink="/releases" versionLabel="0.0.1" />}
         >
-          <AppHeaderPortal>
-            <SidebarTrigger />
-            <Gap />
-            <NavUserHeader
-              theme="light"
-              onThemeToggle={() => undefined}
-              onLogout={() => undefined}
-              isAuthenticated={false}
-            />
-          </AppHeaderPortal>
+          <SybilionAppHeader
+            pathname={location.pathname}
+            onNavigate={href => navigate(href)}
+            authenticated={false}
+            appsStorageKey="myapp.workspaceApps"
+            defaultApps={[]}
+            user={{ name: 'Analyst', email: 'you@example.com', avatar: '' }}
+            theme="light"
+            onThemeToggle={() => undefined}
+            onLogout={() => undefined}
+            isAuthenticated={false}
+            menuItems={
+              <>
+                <DropdownMenuItem>Account</DropdownMenuItem>
+                <DropdownMenuItem>Settings</DropdownMenuItem>
+              </>
+            }
+          />
           {children}
         </AppShellMainContent>
       </AppShell>
@@ -253,7 +275,7 @@ export function AppLayout({ children }: { children: ReactNode }) {
 }
 ```
 
-Wire `NavUserHeader` to real auth (`useSybilionAuth`, theme context, etc.; §3). Demo in repo: `src/docs/pages/NavUserHeaderPage.tsx` (slug `nav-user-header`).
+Wire **`authenticated`**, **`user`** / **`isAuthenticated`**, **`theme`** / **`onLogout`**, **`menuItems`**, and **`defaultApps`** / **`appsStorageKey`** to real auth and workspace config (`useSybilionAuth`, §3). **`NavUserHeader`** behavior reference: `src/docs/pages/NavUserHeaderPage.tsx` (slug `nav-user-header`). Full shell preview: `src/docs/pages/StandaloneAppLayoutPage.tsx` (slug **`standalone-app-layout`**).
 
 #### Sidebar (`AppSidebar.tsx`)
 
@@ -326,41 +348,80 @@ export function AppSidebar() {
 
 Data loading uses §2 `sybilionSdk` directly — for production swap the inline `useEffect` for your data layer (React Query, SWR, context, etc.). `groupBy` accepts `'regions' | 'target_type' | 'categories'`; the widget owns its expand state and notifies on selection via `onDatasetClick`.
 
+### Route page body (`PageHeader`, `PageContent`, `PageContentSection`)
+
+**Canonical rule for this doc:** the shell (`AppLayout`) owns **global** chrome only. Every **route** (component under `<Routes>`) builds the main column with **`PageHeader` → `PageContent` → `PageContentSection`** (and other uilib primitives inside sections)—not a padded root `<div>`/`<main>` unless nothing fits.
+
+Pieces:
+
+| Piece                    | Role                                                                                                                                                                                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`PageHeader`**         | Route title (`h1`), optional **breadcrumbs**, **subheader**, **actions** (toolbar). Renders the shared header chrome (collapsing title on scroll uses `PageContext` from `PageScroll`).                                                                                    |
+| **`PageContent`**        | Outer wrapper for the scrollable main column body. Use **`variant="clean"`** when you need the alternate spacing preset.                                                                                                                                                   |
+| **`PageContentSection`** | Vertical **section** blocks inside the page (group related UI; stack multiple sections). Accepts normal `div` props (e.g. `className`, `style`; HTML **`title`** is the native tooltip attribute, not a section heading—pass a real heading element as a child if needed). |
+
+**Example — `HomePage.tsx` (fragment inside `AppShellMainContent` / `<Routes>`):**
+
+```tsx
+import { PageContent, PageContentSection, PageHeader } from '@sybilion/uilib';
+
+export function HomePage() {
+  return (
+    <>
+      <PageHeader
+        breadcrumbs={[{ label: 'Home', href: '/' }]}
+        title="Home"
+        subheader="Short route description."
+      />
+      <PageContent>
+        <PageContentSection>
+          {/* tables, cards, charts — use uilib components where they exist */}
+        </PageContentSection>
+      </PageContent>
+    </>
+  );
+}
+```
+
+Set **`breadcrumbSidebarTrigger={false}`** on `PageHeader` only when **no** `SidebarProvider` wraps the tree (rare for standalone apps; default is fine when the sidebar exists).
+
 ### Full pattern
 
-Composition: `PageScroll` → `AppShell` → `AppSidebar` → `AppShellMainContent` with `AppHeaderHost`, `PageFooter`, and the active route as `children`. `SidebarProvider` wraps `AppLayout`. Add `Theme` from `@homecode/ui` only when your product uses those primitives alongside uilib.
+Composition: `PageScroll` → `AppShell` → `AppSidebar` → `AppShellMainContent` with **`AppHeaderHost`** + **`SybilionAppHeader`**, `PageFooter`, and the active route as `children`. **`SidebarProvider`** wraps `AppLayout`. **Route main column:** subsection **Route page body** above. Add `Theme` from `@homecode/ui` only when your product uses those primitives alongside uilib.
 
 ### Greenfield checklist (agents)
 
-| Step | Deliverable |
-| ---- | ----------- |
-| Env files | **`.env.example`** (committed) + **`.env`** locally; **`PORT=3000`** recommended for Auth0 test tenant; **`VITE_*`** as in §1 table. |
-| Scripts | **`package.json`** includes mandatory **`dev`** (e.g. `"vite"`); optional **`build`**, **`preview`**. |
-| Vite proxy | **`vite.config.ts`** spreads **`sybilionStandaloneViteDev({ mode })`**; SDK **`baseUrl`** empty in dev (§2). |
-| Files | `src/libs/sybilion-sdk.ts`, `AppProviders.tsx`, `AppLayout.tsx`, `AppSidebar.tsx`, `App.tsx`, `main.tsx`, route pages under e.g. `src/pages/`. |
-| Auth0 | SPA callback / logout URLs + allowed web origins → **`http://localhost:<PORT>`** for local dev and deploy URLs (and previews). |
-| API | **Dev:** proxy handles API traffic (no browser CORS to API). **Prod:** Sybilion backend **CORS** → your deploy `Origin`, unless API is same-origin. |
-| Go (if applicable) | Server proxies **`/api`** to Sybilion; SPA dev **`baseUrl`** stays `''` when same-origin. |
+| Step               | Deliverable                                                                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Env files          | **`.env.example`** (committed) + **`.env`** locally; **`PORT=3000`** recommended for Auth0 test tenant; **`VITE_*`** as in §1 table.                |
+| Scripts            | **`package.json`** includes mandatory **`dev`** (e.g. `"vite"`); optional **`build`**, **`preview`**.                                               |
+| Vite proxy         | **`vite.config.ts`** spreads **`sybilionStandaloneViteDev({ mode })`**; SDK **`baseUrl`** empty in dev (§2).                                        |
+| Files              | `src/libs/sybilion-sdk.ts`, `AppProviders.tsx`, `AppLayout.tsx`, `AppSidebar.tsx`, `App.tsx`, `main.tsx`, route pages under e.g. `src/pages/`.      |
+| Pages + UI         | **§4 Route page body** (mandatory stack) + **Discovering** (barrel-first; bespoke markup only when no export fits).                                 |
+| Auth0              | SPA callback / logout URLs + allowed web origins → **`http://localhost:<PORT>`** for local dev and deploy URLs (and previews).                      |
+| API                | **Dev:** proxy handles API traffic (no browser CORS to API). **Prod:** Sybilion backend **CORS** → your deploy `Origin`, unless API is same-origin. |
+| Go (if applicable) | Server proxies **`/api`** to Sybilion; SPA dev **`baseUrl`** stays `''` when same-origin.                                                           |
 
 ### Glossary (high-use pieces)
 
-| Component / API               | What it is for                                                                                                                                           |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PageScroll`                  | Page-level vertical scroll wrapper; usual outer shell for the app body.                                                                                  |
-| `AppShell`                    | Layout grid container; `Sidebar` + `AppShellMainContent` as siblings inside it.                                                                          |
-| `AppShellMainContent`         | Main column: `header`, scrollable body (`children`), `footer`.                                                                                           |
-| `AppHeaderHost`               | Top header anchor (DOM id `page-header`); stays empty until `AppHeaderPortal` portals into it.                                                           |
-| `AppHeaderPortal`             | Portals into `AppHeaderHost` — `SidebarTrigger`, `NavUserHeader`, theme toggle.                                                                          |
-| `NavUserHeader`               | Header user menu (avatar, account, theme, logout).                                                                                                       |
-| `Sidebar`, `SidebarProvider`  | Collapsible rail + context (`@sybilion/uilib`). Wrap `SidebarProvider` above `AppLayout`; render `Sidebar` inside `AppShell` (usually via `AppSidebar`). |
-| `AppSidebar`                  | App-specific component (`src/AppSidebar.tsx`) composing `Sidebar` + nav links + product widgets. Keeps `AppLayout` generic.                              |
-| `SidebarDatasetsItemsGrouped` | Dataset list widget for the sidebar: collapsible groups (`regions` / `target_type` / `categories`) with nested rows + selection callback.                |
-| `SidebarTrigger`              | Toggle sidebar visibility (especially mobile / `offcanvas`).                                                                                             |
-| `PageFooter`                  | Standard footer; requires `versionLink` + `versionLabel`.                                                                                                |
-| `Gap`                         | Spacing primitive between flex children.                                                                                                                 |
-| `SybilionAuthProvider`        | Auth0 + Sybilion JWT (§3).                                                                                                                               |
-| `useSybilionAuth`             | User session + login/logout under provider.                                                                                                              |
-| `useSybilionApiFetch`         | Authenticated `fetch` using stored JWT.                                                                                                                  |
+| Component / API                                      | What it is for                                                                                                                                                                                                                                                                    |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PageScroll`                                         | Page-level vertical scroll wrapper; usual outer shell for the app body.                                                                                                                                                                                                           |
+| `AppShell`                                           | Layout grid container; `Sidebar` + `AppShellMainContent` as siblings inside it.                                                                                                                                                                                                   |
+| `AppShellMainContent`                                | Main column: `header`, scrollable body (`children`), `footer`.                                                                                                                                                                                                                    |
+| `SybilionAppHeader`                                  | **Default** standalone top header: **`AppShellMainContent`** `header` = **`AppHeaderHost`**, first body child = **`SybilionAppHeader`** — workspace switcher + embedded **`NavUserHeader`** (props incl. **`menuItems`**); aligns **`PageHeader`** via **`page-header-actions`**. |
+| `WorkspaceAppSwitcher`                               | Dropdown of workspace apps (`WorkspaceAppEntry[]`); composed inside **`SybilionAppHeader`**.                                                                                                                                                                                      |
+| `NavUserHeader`                                      | Header user menu (avatar, account, theme, logout).                                                                                                                                                                                                                                |
+| `Sidebar`, `SidebarProvider`                         | Collapsible rail + context (`@sybilion/uilib`). Wrap `SidebarProvider` above `AppLayout`; render `Sidebar` inside `AppShell` (usually via `AppSidebar`).                                                                                                                          |
+| `AppSidebar`                                         | App-specific component (`src/AppSidebar.tsx`) composing `Sidebar` + nav links + product widgets. Keeps `AppLayout` generic.                                                                                                                                                       |
+| `SidebarDatasetsItemsGrouped`                        | Dataset list widget for the sidebar: collapsible groups (`regions` / `target_type` / `categories`) with nested rows + selection callback.                                                                                                                                         |
+| `SidebarTrigger`                                     | Toggle sidebar visibility (especially mobile / `offcanvas`).                                                                                                                                                                                                                      |
+| `PageFooter`                                         | Standard footer; requires `versionLink` + `versionLabel`.                                                                                                                                                                                                                         |
+| `Gap`                                                | Spacing primitive between flex children.                                                                                                                                                                                                                                          |
+| `PageHeader`, `PageContent`, `PageContentSection`, … | **§4 Route page body** (roles, `breadcrumbSidebarTrigger`, example). Same barrel also has `PageTabs`, `PageColumns`, `SectionHeader`, `PageEmptyCanvas`, …                                                                                                                        |
+| `SybilionAuthProvider`                               | Auth0 + Sybilion JWT (§3).                                                                                                                                                                                                                                                        |
+| `useSybilionAuth`                                    | User session + login/logout under provider.                                                                                                                                                                                                                                       |
+| `useSybilionApiFetch`                                | Authenticated `fetch` using stored JWT.                                                                                                                                                                                                                                           |
 
 ## 5. Data
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",

package/src/components/ui/AppHeader/appChromeAnchors.ts

@@ -1,2 +1,5 @@
 /** DOM anchor id for portaling page-level header actions into `AppHeader`. */
 export const PAGE_HEADER_ID = 'page-header';
+
+/** DOM id for `#page-header-actions`; `AppHeaderActions` portaling target. */
+export const PAGE_HEADER_ACTIONS_ID = 'page-header-actions';

package/src/components/ui/AppHeader/index.ts

@@ -1,3 +1,3 @@
 export type { AppHeaderProps, AppHeaderPortalProps } from './AppHeader';
 export { AppHeaderHost, AppHeaderPortal } from './AppHeader';
-export { PAGE_HEADER_ID } from './appChromeAnchors';
+export { PAGE_HEADER_ACTIONS_ID, PAGE_HEADER_ID } from './appChromeAnchors';

package/src/components/ui/WorkspaceAppSwitcher/WorkspaceAppSwitcher.styl

@@ -0,0 +1,91 @@
+@import '../../../lib/theme.styl'
+
+.trigger
+  display flex
+  align-items center
+  gap var(--p-2)
+  max-width 320px
+  height auto
+  padding var(--p-1) !important
+  padding-right var(--p-3) !important
+  margin-left var(--p-3) !important
+
+  border-radius 12px
+  border none
+  background transparent
+  cursor pointer
+  color inherit
+  font inherit
+  text-align left
+
+  &:hover
+    background-color var(--muted)
+
+.iconTile
+  position relative
+  display flex
+  align-items center
+  justify-content center
+  flex-shrink 0
+  width 40px
+  height 40px
+  border-radius 10px
+  color var(--fg-color)
+
+  &::before
+  &::after
+    position absolute
+    content ''
+    display block
+    width 100%
+    height 100%
+    border-radius inherit
+  &::before
+    background-color var(--background)
+  &::after
+    background-color var(--bg-color)
+
+.icon
+  z-index 1
+  width 22px !important
+  height 22px !important
+  color var(--fg-color) !important
+
+.textCol
+  display flex
+  flex-direction column
+  min-width 0
+  flex 1
+  gap 2px
+
+.name
+  font-weight 600
+  font-size var(--text-sm)
+  line-height 1.2
+  color var(--foreground)
+  white-space nowrap
+  overflow hidden
+  text-overflow ellipsis
+
+.sub
+  font-size var(--text-xs)
+  line-height 1.2
+  color var(--muted-foreground)
+  white-space nowrap
+  overflow hidden
+  text-overflow ellipsis
+
+.menuContent
+  min-width 280px
+  max-width 360px
+
+.item
+  display flex
+  align-items center
+  gap var(--p-3)
+  padding var(--p-3)
+  cursor pointer
+  outline none
+
+.itemActive
+  background-color var(--muted)

package/src/components/ui/WorkspaceAppSwitcher/WorkspaceAppSwitcher.styl.d.ts

@@ -0,0 +1,15 @@
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'icon': string;
+  'iconTile': string;
+  'item': string;
+  'itemActive': string;
+  'menuContent': string;
+  'name': string;
+  'sub': string;
+  'textCol': string;
+  'trigger': string;
+}
+export const cssExports: CssExports;
+export default cssExports;

package/src/components/ui/WorkspaceAppSwitcher/WorkspaceAppSwitcher.tsx

@@ -0,0 +1,163 @@
+import cn from 'classnames';
+import type { CSSProperties } from 'react';
+import { useEffect, useState } from 'react';
+
+import { Button } from '#uilib/components/ui/Button/Button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '#uilib/components/ui/DropdownMenu';
+import type { WorkspaceAppEntry } from '#uilib/components/ui/WorkspaceAppSwitcher/workspaceApp.types';
+import { WORKSPACE_APP_ICONS } from '#uilib/components/ui/WorkspaceAppSwitcher/workspaceAppIcons';
+import { findWorkspaceAppByPathname } from '#uilib/components/ui/WorkspaceAppSwitcher/workspaceAppPaths';
+import { readWorkspaceAppsFromLocalStorage } from '#uilib/components/ui/WorkspaceAppSwitcher/workspaceAppsLocalStorage';
+import { ChevronDown } from 'lucide-react';
+
+import S from './WorkspaceAppSwitcher.styl';
+
+export type WorkspaceAppSwitcherProps = {
+  pathname: string;
+  onNavigate: (href: string) => void;
+  /** When false, renders nothing (host maps from auth Loading + signed-in). */
+  authenticated?: boolean;
+  /** Fallback when localStorage missing/invalid/unset — keep referentially stable across renders where possible */
+  defaultApps?: WorkspaceAppEntry[];
+  /** When set, read apps from localStorage (`readWorkspaceAppsFromLocalStorage`). */
+  appsStorageKey?: string;
+};
+
+function entryKey(entry: WorkspaceAppEntry): string {
+  return entry.id;
+}
+
+function IconTile({
+  iconKey,
+  accentMuted,
+  accent,
+}: {
+  iconKey: WorkspaceAppEntry['iconKey'];
+  accentMuted: string;
+  accent: string;
+}) {
+  const IconComponent = WORKSPACE_APP_ICONS[iconKey];
+  return (
+    <span
+      className={S.iconTile}
+      style={
+        {
+          '--bg-color': accentMuted,
+          '--fg-color': accent,
+        } as CSSProperties
+      }
+    >
+      <IconComponent className={S.icon} aria-hidden />
+    </span>
+  );
+}
+
+function useResolvedApps(
+  appsStorageKey: string | undefined,
+  defaultApps: WorkspaceAppEntry[] | undefined,
+): WorkspaceAppEntry[] {
+  const [apps, setApps] = useState<WorkspaceAppEntry[]>(() => {
+    if (
+      typeof localStorage !== 'undefined' &&
+      appsStorageKey != null &&
+      appsStorageKey !== ''
+    ) {
+      const fromLs = readWorkspaceAppsFromLocalStorage(appsStorageKey);
+      if (fromLs != null && fromLs.length > 0) {
+        return fromLs;
+      }
+    }
+    return defaultApps ?? [];
+  });
+
+  useEffect(() => {
+    if (!appsStorageKey || typeof localStorage === 'undefined') {
+      setApps(defaultApps ?? []);
+      return;
+    }
+    const fromLs = readWorkspaceAppsFromLocalStorage(appsStorageKey);
+    setApps(fromLs != null && fromLs.length > 0 ? fromLs : (defaultApps ?? []));
+  }, [appsStorageKey, defaultApps]);
+
+  return apps;
+}
+
+export function WorkspaceAppSwitcher({
+  pathname,
+  onNavigate,
+  authenticated = true,
+  defaultApps,
+  appsStorageKey,
+}: WorkspaceAppSwitcherProps) {
+  const apps = useResolvedApps(appsStorageKey, defaultApps);
+
+  const current = findWorkspaceAppByPathname(pathname, apps);
+
+  if (!authenticated || apps.length === 0) {
+    return null;
+  }
+
+  const displayApp = current ?? apps[0];
+  if (!displayApp) {
+    return null;
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          className={S.trigger}
+          aria-label="Select workspace app"
+        >
+          <IconTile
+            iconKey={displayApp.iconKey}
+            accentMuted={displayApp.accentMuted}
+            accent={displayApp.accent}
+          />
+          <span className={S.textCol}>
+            <span className={S.name}>{displayApp.displayName}</span>
+            <span className={S.sub}>{displayApp.subtitle}</span>
+          </span>
+          <ChevronDown size={12} />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        className={S.menuContent}
+        align="start"
+        sideOffset={8}
+        elevation="md"
+      >
+        {apps.map(entry => {
+          const active =
+            current != null ? entryKey(entry) === entryKey(current) : false;
+
+          return (
+            <DropdownMenuItem
+              key={entry.id}
+              className={cn(S.item, active && S.itemActive)}
+              onSelect={() => {
+                onNavigate(entry.href);
+              }}
+            >
+              <IconTile
+                iconKey={entry.iconKey}
+                accentMuted={entry.accentMuted}
+                accent={entry.accent}
+              />
+              <span className={S.textCol}>
+                <span className={S.name}>{entry.displayName}</span>
+                <span className={S.sub}>{entry.subtitle}</span>
+              </span>
+            </DropdownMenuItem>
+          );
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/ui/WorkspaceAppSwitcher/index.ts

@@ -0,0 +1,20 @@
+export {
+  WorkspaceAppSwitcher,
+  type WorkspaceAppSwitcherProps,
+} from './WorkspaceAppSwitcher';
+export type { WorkspaceAppEntry } from './workspaceApp.types';
+export { WORKSPACE_APP_SLUG_BASE_PATH } from './workspaceApp.types';
+export { WORKSPACE_APPS_LS_KEY } from './workspaceAppsConstants';
+export {
+  readWorkspaceAppsFromLocalStorage,
+  writeWorkspaceAppsToLocalStorage,
+} from './workspaceAppsLocalStorage';
+export {
+  WORKSPACE_APP_ICONS,
+  type WorkspaceAppIconKey,
+  isWorkspaceAppIconKey,
+} from './workspaceAppIcons';
+export {
+  findWorkspaceAppByPathname,
+  workspaceAppSlugPath,
+} from './workspaceAppPaths';

package/src/components/ui/WorkspaceAppSwitcher/workspaceApp.types.ts

@@ -0,0 +1,21 @@
+import type { WorkspaceAppIconKey } from './workspaceAppIcons';
+
+/** Path segment for slug apps: pathname matches `/apps/{id}` */
+export const WORKSPACE_APP_SLUG_BASE_PATH = '/apps';
+
+/** One surface in the workspace app switcher (serializable for localStorage). */
+export type WorkspaceAppEntry = {
+  /** Slug (e.g. `my-custom-app` → `https://sybilion.io/apps/my-custom-app` via `href`). */
+  id: string;
+  displayName: string;
+  subtitle: string;
+  iconKey: WorkspaceAppIconKey;
+  accent: string;
+  accentMuted: string;
+  href: string;
+  /**
+   * Optional. Native / multi-route shells: match current app by pathname prefix.
+   * Omit for custom apps deployed under a single slug (`/apps/{id}` only).
+   */
+  matchPathPrefixes?: readonly string[];
+};

package/src/components/ui/WorkspaceAppSwitcher/workspaceAppIcons.ts

@@ -0,0 +1,27 @@
+import type { ComponentType } from 'react';
+
+import { Boat, Package, TreeStructure } from '@phosphor-icons/react';
+import { ClockAlert, LayoutDashboard } from 'lucide-react';
+
+type IconLike = ComponentType<{ className?: string; 'aria-hidden'?: boolean }>;
+
+export type WorkspaceAppIconKey =
+  | 'grid-four'
+  | 'clock'
+  | 'boat'
+  | 'package'
+  | 'tree-structure';
+
+export const WORKSPACE_APP_ICONS: Record<WorkspaceAppIconKey, IconLike> = {
+  'grid-four': LayoutDashboard as IconLike,
+  clock: ClockAlert as IconLike,
+  boat: Boat as IconLike,
+  package: Package as IconLike,
+  'tree-structure': TreeStructure as IconLike,
+};
+
+const ICON_KEYS = Object.keys(WORKSPACE_APP_ICONS) as WorkspaceAppIconKey[];
+
+export function isWorkspaceAppIconKey(v: string): v is WorkspaceAppIconKey {
+  return (ICON_KEYS as string[]).includes(v);
+}