@sybilion/uilib 1.2.4 → 1.2.6

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.
 
@@ -15,6 +15,25 @@ yarn add react react-dom react-router-dom @auth0/auth0-react @sybilion/uilib @sy
 yarn add -D vite @vitejs/plugin-react
 ```
 
+**React ecosystem versions (avoid collisions):** declare **`react`**, **`react-dom`**, **`react-router-dom`**, and **`@auth0/auth0-react`** as **direct** dependencies and align them with **`@sybilion/uilib`**, not arbitrary latest majors.
+
+1. After installing uilib, open **`node_modules/@sybilion/uilib/package.json`** (or this repo’s root **`package.json`** at the release you pin).
+2. **`peerDependencies`** — satisfy these ranges in your app (`react` / `react-dom`, `react-router-dom`, `@auth0/auth0-react`, and **`vite`** when you use the Vite helpers).
+3. **`devDependencies`** — for **`react`**, **`react-dom`**, and **`react-router-dom`**, prefer **the same versions uilib lists there** (what its docs build and tests run against). Re-read this file whenever you bump **`@sybilion/uilib`** so your app does not drift to another React major while uilib does not.
+
+Mismatched or duplicated React (two copies in the bundle) causes **invalid hook call** / subtle runtime bugs — and specifically causes **Radix UI interactive widgets** (dropdowns, dialogs, tooltips) to **silently fail** (context broken across the module boundary). If Yarn/npm hoists a second React, fix upstream ranges or use **`resolutions`** (Yarn) / **`overrides`** (npm) so the tree resolves to **one** `react` / `react-dom` pair matching (3). Also add `dedupe` + `@radix-ui/` alias in `vite.config.ts` (see **Local dev: Vite API proxy**).
+
+**Current required versions (as of uilib 1.2.x):** `react` / `react-dom` **`^19`**, `@types/react` / `@types/react-dom` **`^19`**. Add resolutions so nested copies stay aligned:
+
+```json
+{
+  "resolutions": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
+  }
+}
+```
+
 Import tokens/fonts once (typically `src/main.tsx`):
 
 ```ts
@@ -41,12 +60,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:
 
@@ -99,21 +118,52 @@ Package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk)
 
 ## Local dev: Vite API proxy
 
-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`.
+Avoid browser CORS in development by serving the SPA from Vite and proxying **`/api`** to the real API.
+
+**Reference `vite.config.ts` (minimal standalone Sybilion SPA):** merge your own `plugins` / options into this shape; keep `resolve.dedupe` and the `@radix-ui/` alias unless you know the dependency tree dedupes React and Radix correctly on its own.
+
+- **`sybilionStandaloneViteDev`** (`@sybilion/uilib/vite-standalone-dev`) — reads **`PORT`** (defaults **3000** if unset or invalid) for **`server`** and **`preview`** bind; sets **`proxy['/api']`** → **`VITE_SYBILION_API_BASE_URL`** with `changeOrigin` and `secure: true`. Pass Vite’s **`mode`** so env (including `VITE_*`) and proxy target resolve the same way as `vite` / `vite build`.
+- **`defineConfig(({ mode }) => …)`** — callback form gives `mode` per command (`development` / `production` / …); forward it into `sybilionStandaloneViteDev`.
+- **`plugins: [react()]`** — add other plugins (e.g. SVGR) in the same array.
+- **`resolve.dedupe`** — force one physical copy of `react`, `react-dom`, `react-router`, and `react-router-dom`. If the app and `@sybilion/uilib` resolve different copies, React context and router state break (`Invalid hook call`, blank subtree, Radix menus that never open). `react-router` is listed because it is a shared transitive dependency of the router packages and can duplicate independently.
+- **`resolve.alias` for `@radix-ui/*`** — uilib’s published bundle uses bare `@radix-ui/react-*` imports. Yarn/npm can still place those packages under `node_modules/@sybilion/uilib/node_modules/@radix-ui/…`, so Vite may bundle two Radix trees and split React context across them. The regex alias rewrites every `@radix-ui/…` import to **`./node_modules/@radix-ui/`** (project root). **`path.resolve(… ) + '/'`** is required so subpaths like `@radix-ui/react-dialog` resolve under that folder.
+- **`path`** — Node built-in `node:path`; only used at config evaluation time.
 
 ```ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
+// vite.config.ts — reference config for a standalone app using @sybilion/uilib + proxy.
 import { sybilionStandaloneViteDev } from '@sybilion/uilib/vite-standalone-dev';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+import { defineConfig } from 'vite';
 
+// Pass `mode` into sybilionStandaloneViteDev so proxy + VITE_* match the active Vite command.
 export default defineConfig(({ mode }) => ({
   ...sybilionStandaloneViteDev({ mode }),
   plugins: [react()],
+  resolve: {
+    // One copy of React + Router across app and uilib (avoids invalid hook call / dead Radix UI).
+    dedupe: ['react', 'react-dom', 'react-router', 'react-router-dom'],
+    alias: [
+      {
+        find: /^@radix-ui\//,
+        // Pin all Radix imports to the app’s root node_modules; trailing slash keeps subpaths working.
+        replacement: path.resolve('./node_modules/@radix-ui/') + '/',
+      },
+    ],
+  },
 }));
 ```
 
 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.
@@ -161,6 +211,44 @@ export function AppProviders({ children }: { children: ReactNode }) {
 
 **Hooks:** `useSybilionAuth()`, `useSybilionApiFetch()` (or `createSybilionApiFetch` / `sybilionApiFetch` helpers).
 
+### Loading the user profile for `SybilionAppHeader`
+
+`useSybilionAuth()` gives you `isAuthenticated` / `logout` but **not** a user object. Fetch it once with `sybilionSdk.auth.getMe()` after authentication. The response shape is:
+
+```ts
+// GET /api/v1/users/me → { data: { user: BackendUser }, message, status }
+// BackendUser includes `picture` (profile image URL from the API). Do not read deprecated `avatar` on the wire.
+```
+
+**Agents:** import **`MeResponse`** (and rely on **`BackendUser`** inside it) from `@sybilion/sdk`. Profile image on the API is **`picture` only**; `NavUserHeader` / `SybilionAppHeader` still expect the prop key **`avatar`**—map with `avatar: u.picture ?? ''`. No `UserProfile` intersections, no `u.avatar` fallback, no manual `res as { data?: … }` once `getMe()` is typed.
+
+`NavUserHeader` (used inside `SybilionAppHeader`) accepts `user: { name, email, avatar? }`.
+
+```ts
+import type { MeResponse } from '@sybilion/sdk';
+
+useEffect(() => {
+  if (!isAuthenticated) {
+    setUser(null);
+    return;
+  }
+  sybilionSdk.auth
+    .getMe()
+    .then((res: MeResponse) => {
+      const u = res.data?.user;
+      if (u)
+        setUser({
+          name: u.name,
+          email: u.email,
+          avatar: u.picture ?? '',
+        });
+    })
+    .catch(() => undefined);
+}, [isAuthenticated]);
+```
+
+Pass `user` (or `null` while loading with `isLoading` on `NavUserHeader`) and `isAuthenticated` to `SybilionAppHeader`.
+
 ## 4. Layout (AppShell)
 
 With §2 `sybilionSdk` and §3 `AppProviders` / `SybilionAuthProvider` defined, compose routing + shell so Auth0 callbacks and JWT-backed hooks wrap the whole UI.
@@ -206,26 +294,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 +329,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 +355,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` (slug **`standalone-app-layout`**).
 
 #### Sidebar (`AppSidebar.tsx`)
 
@@ -326,41 +428,81 @@ 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                                                                                                                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| React / router     | **`react`**, **`react-dom`**, **`react-router-dom`**, **`@auth0/auth0-react`** (and **`vite`** if applicable) aligned with **`@sybilion/uilib`** **`package.json`** — §1 _React ecosystem versions_. |
+| 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.6",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",

package/src/components/ui/AppHeader/AppHeader.styl

@@ -9,6 +9,11 @@
   min-height var(--header-height)
   background-color var(--color-background)
 
+  @media (min-width MOBILE)
+    :global([data-slot='sidebar-wrapper'][data-state='collapsed']) &
+      padding-left 200px
+      max-width 100%
+
 .content
   display flex
   align-items center

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/Sidebar/Sidebar.styl

@@ -64,7 +64,7 @@
   @media (min-width MOBILE)
     &[data-state="expanded"]
       display flex
-      height calc(100vh - var(--gap-top))
+      height calc(100% - var(--gap-top))
       min-height 0
 
   &[data-collapsible="offcanvas"]

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;