@sybilion/uilib 1.2.1 → 1.2.3

package/dist/esm/components/ui/AppHeader/AppHeader.js

@@ -8,11 +8,11 @@ import { PAGE_HEADER_ID } from './appChromeAnchors.js';
 function AppHeaderHost({ className, anchorId = PAGE_HEADER_ID, }) {
     return jsx("header", { className: cn(S.root, className), id: anchorId });
 }
-function AppHeaderPortal({ children }) {
+function AppHeaderPortal({ children, pageHeaderId = PAGE_HEADER_ID, }) {
     const [container, setContainer] = useState(null);
     useLayoutEffect(() => {
-        setContainer(document.getElementById(PAGE_HEADER_ID));
-    }, []);
+        setContainer(document.getElementById(pageHeaderId));
+    }, [pageHeaderId]);
     if (!container) {
         return null;
     }

package/dist/esm/components/ui/Page/AppShell/AppShell.styl.js

@@ -1,6 +1,6 @@
 import styleInject from 'style-inject';
 
-var css_248z = "@media (max-width:768px){:root{--page-x-padding:var(--p-6);--page-y-padding:var(--p-6)}}.AppShell_root__ONlNK{display:grid;flex:1;grid-template-areas:\"main\";grid-template-columns:1fr;min-height:0;width:100%}@media (min-width:768px){.AppShell_root__ONlNK{grid-template-areas:\"sidebar main\";grid-template-columns:var(--sidebar-width) 1fr}[data-slot=sidebar-wrapper][data-state=collapsed] .AppShell_root__ONlNK{grid-template-columns:0 1fr}}.AppShell_mainColumn__Emn1p{display:flex;flex:1;flex-direction:column;grid-area:main;min-height:0;min-width:0}[data-slot=sidebar-wrapper][data-state=collapsed] .AppShell_mainColumn__Emn1p{margin-left:var(--p-3)}.AppShell_mainBody__IoVuy{background-color:var(--page-color);border-radius:var(--p-4);flex:1;min-width:0;padding-bottom:var(--page-y-padding)}";
+var css_248z = "@media (max-width:768px){:root{--page-x-padding:var(--p-6);--page-y-padding:var(--p-6)}}.AppShell_root__ONlNK{display:grid;flex:1;grid-template-areas:\"main\";grid-template-columns:1fr;min-height:0;min-height:100%;width:100%}@media (min-width:768px){.AppShell_root__ONlNK{grid-template-areas:\"sidebar main\";grid-template-columns:var(--sidebar-width) 1fr}[data-slot=sidebar-wrapper][data-state=collapsed] .AppShell_root__ONlNK{grid-template-columns:0 1fr}}.AppShell_mainColumn__Emn1p{display:flex;flex:1;flex-direction:column;grid-area:main;min-height:0;min-width:0}[data-slot=sidebar-wrapper][data-state=collapsed] .AppShell_mainColumn__Emn1p{margin-left:var(--p-3)}.AppShell_mainBody__IoVuy{background-color:var(--page-color);border-radius:var(--p-4);flex:1;min-width:0;padding-bottom:var(--page-y-padding)}";
 var S = {"root":"AppShell_root__ONlNK","mainColumn":"AppShell_mainColumn__Emn1p","mainBody":"AppShell_mainBody__IoVuy"};
 styleInject(css_248z);
 

package/dist/esm/components/ui/Page/PageScroll/PageScroll.js

@@ -6,7 +6,7 @@ import { PageContext } from '../pageContext.js';
 import { Scroll } from '@homecode/ui';
 import S from './PageScroll.styl.js';
 
-function PageScrollInner({ className, children, }) {
+function PageScrollInner({ className, rootClassName, children, }) {
     // const { setIsScrolled } = useContext(PageContext);
     // const prevScrollTop = useRef(0);
     const location = useLocation();
@@ -25,13 +25,13 @@ function PageScrollInner({ className, children, }) {
     // };
     return (jsx(Scroll, { y: true, 
         // fadeSize="l"
-        offset: { y: { before: 120, after: 130 } }, className: S.root, autoHide: true, innerClassName: cn(S.inner, className), yScrollbarClassName: S.scrollbar, onInnerRef: el => {
+        offset: { y: { before: 120, after: 130 } }, className: cn(S.root, rootClassName), autoHide: true, innerClassName: cn(S.inner, className), yScrollbarClassName: S.scrollbar, onInnerRef: el => {
             scrollInnerRef.current = el;
         }, children: children }));
 }
-const PageScroll = ({ children, className, }) => {
+const PageScroll = ({ children, className, rootClassName, }) => {
     const [isScrolled, setIsScrolled] = useState(false);
-    return (jsx(PageContext.Provider, { value: { isScrolled, setIsScrolled }, children: jsx(PageScrollInner, { className: className, children: children }) }));
+    return (jsx(PageContext.Provider, { value: { isScrolled, setIsScrolled }, children: jsx(PageScrollInner, { className: className, rootClassName: rootClassName, children: children }) }));
 };
 
 export { PageScroll };

package/dist/esm/components/widgets/SidebarDatasetsItemsGrouped/SidebarDatasetsItemsGrouped.js

@@ -6,7 +6,7 @@ import { PackageOpen, ChevronDown, ChevronRight } from 'lucide-react';
 import S from './SidebarDatasetsItemsGrouped.styl.js';
 import { groupSidebarDatasets } from './groupSidebarDatasets.js';
 
-function SidebarDatasetsItemsGrouped({ groupBy, datasets, selectedDatasetId, onDatasetClick, defaultExpandedGroupNames, className, }) {
+function SidebarDatasetsItemsGrouped({ groupBy, datasets, preItems, postItems, selectedDatasetId, onDatasetClick, defaultExpandedGroupNames, className, }) {
     const grouped = useMemo(() => groupSidebarDatasets(datasets, groupBy), [datasets, groupBy]);
     const [expanded, setExpanded] = useState(new Set());
     useEffect(() => {
@@ -35,14 +35,14 @@ function SidebarDatasetsItemsGrouped({ groupBy, datasets, selectedDatasetId, onD
             return next;
         });
     };
-    return (jsx(SidebarGroup, { className: className, children: jsx(SidebarMenu, { children: grouped.map(([groupName, groupDatasets]) => {
-                const isExpanded = expanded.has(groupName);
-                const parentActive = groupDatasets.some(d => d.id === selectedDatasetId);
-                return (jsxs(SidebarMenuItem, { children: [jsxs(SidebarMenuButton, { type: "button", isActive: parentActive, onClick: () => toggleGroup(groupName), children: [jsx(PackageOpen, { strokeWidth: 1.5, size: 16 }), jsx(SmartTextTruncate, { children: groupName }), jsx("div", { className: S.chevronContainer, children: isExpanded ? (jsx(ChevronDown, { size: 12 })) : (jsx(ChevronRight, { size: 12 })) })] }), isExpanded && (jsxs(SidebarMenuSub, { className: S.subMenuContainer, children: [jsx("div", { className: S.subMenuBorder }), groupDatasets.map(dataset => (jsx(SidebarMenuSubItem, { className: S.subMenuItem, children: jsx(SidebarMenuSubButton, { href: `#dataset-${dataset.id}`, isActive: dataset.id === selectedDatasetId, onClick: e => {
-                                            e.preventDefault();
-                                            onDatasetClick?.(dataset.id);
-                                        }, children: jsx(SmartTextTruncate, { children: dataset.name }) }) }, dataset.id)))] }))] }, groupName));
-            }) }) }));
+    return (jsx(SidebarGroup, { className: className, children: jsxs(SidebarMenu, { children: [preItems, grouped.map(([groupName, groupDatasets]) => {
+                    const isExpanded = expanded.has(groupName);
+                    const parentActive = groupDatasets.some(d => d.id === selectedDatasetId);
+                    return (jsxs(SidebarMenuItem, { children: [jsxs(SidebarMenuButton, { type: "button", isActive: parentActive, onClick: () => toggleGroup(groupName), children: [jsx(PackageOpen, { strokeWidth: 1.5, size: 16 }), jsx(SmartTextTruncate, { children: groupName }), jsx("div", { className: S.chevronContainer, children: isExpanded ? (jsx(ChevronDown, { size: 12 })) : (jsx(ChevronRight, { size: 12 })) })] }), isExpanded && (jsxs(SidebarMenuSub, { className: S.subMenuContainer, children: [jsx("div", { className: S.subMenuBorder }), groupDatasets.map(dataset => (jsx(SidebarMenuSubItem, { className: S.subMenuItem, children: jsx(SidebarMenuSubButton, { href: `#dataset-${dataset.id}`, isActive: dataset.id === selectedDatasetId, onClick: e => {
+                                                e.preventDefault();
+                                                onDatasetClick?.(dataset.id);
+                                            }, children: jsx(SmartTextTruncate, { children: dataset.name }) }) }, dataset.id)))] }))] }, groupName));
+                }), postItems] }) }));
 }
 
 export { SidebarDatasetsItemsGrouped };

package/dist/esm/types/src/components/ui/AppHeader/AppHeader.d.ts

@@ -7,5 +7,6 @@ export type AppHeaderProps = {
 export declare function AppHeaderHost({ className, anchorId, }: AppHeaderProps): import("react/jsx-runtime").JSX.Element;
 export type AppHeaderPortalProps = {
     children: ReactNode;
+    pageHeaderId?: string;
 };
-export declare function AppHeaderPortal({ children }: AppHeaderPortalProps): import("react").ReactPortal;
+export declare function AppHeaderPortal({ children, pageHeaderId, }: AppHeaderPortalProps): import("react").ReactPortal;

package/dist/esm/types/src/components/ui/Page/PageScroll/PageScroll.d.ts

@@ -1,4 +1,5 @@
-export declare const PageScroll: ({ children, className, }: {
+export declare const PageScroll: ({ children, className, rootClassName, }: {
     children: React.ReactNode;
     className?: string;
+    rootClassName?: string;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/components/widgets/SidebarDatasetsItemsGrouped/SidebarDatasetsItemsGrouped.d.ts

@@ -2,10 +2,12 @@ import { type SidebarDatasetsItemsGroupBy, type SidebarDatasetsItemsGroupedDatas
 export type SidebarDatasetsItemsGroupedProps = {
     groupBy: SidebarDatasetsItemsGroupBy;
     datasets: SidebarDatasetsItemsGroupedDataset[];
+    preItems?: React.ReactNode;
+    postItems?: React.ReactNode;
     selectedDatasetId?: number;
     onDatasetClick?: (datasetId: number) => void;
     /** When omitted, all groups start expanded. */
     defaultExpandedGroupNames?: string[];
     className?: string;
 };
-export declare function SidebarDatasetsItemsGrouped({ groupBy, datasets, selectedDatasetId, onDatasetClick, defaultExpandedGroupNames, className, }: SidebarDatasetsItemsGroupedProps): import("react/jsx-runtime").JSX.Element;
+export declare function SidebarDatasetsItemsGrouped({ groupBy, datasets, preItems, postItems, selectedDatasetId, onDatasetClick, defaultExpandedGroupNames, className, }: SidebarDatasetsItemsGroupedProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/docs/pages/StandaloneAppLayoutPage.d.ts

@@ -0,0 +1 @@
+export default function StandaloneAppLayoutPage(): import("react/jsx-runtime").JSX.Element;

package/docs/standalone-apps.md

@@ -1,8 +1,8 @@
 # Standalone Sybilion apps (@sybilion/uilib)
 
-Greenfield SPA on **your own origin**: `@sybilion/uilib` for layout/UI, **SybilionAuthProvider** + Sybilion API for data—no iframe in the main client.
+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:** use `AppShell` + `AppShellMainContent`; stick to uilib spacing primitives (e.g. `Gap`) instead of ad hoc root horizontal gutters.
 
 ## 1. Dependencies and global CSS
 
@@ -10,17 +10,138 @@ Greenfield SPA on **your own origin**: `@sybilion/uilib` for layout/UI, **Sybili
 yarn add react react-dom react-router-dom @auth0/auth0-react @sybilion/uilib @sybilion/sdk
 ```
 
-Import tokens/fonts once:
+Import tokens/fonts once (typically `src/main.tsx`):
 
 ```ts
 import '@sybilion/uilib/standalone-global.css';
 ```
 
-## 2. Layout (AppShell)
+Mount the tree with `ReactDOM.createRoot` → `App` (wrap with `StrictMode` if you want).
 
-### Minimal example
+## 2. SDK (`@sybilion/sdk`)
 
-`AppHeaderHost` is the empty header bar; put triggers and `NavUserHeader` (a.k.a. the user / account menu) inside `AppHeaderPortal` so they render in that bar.
+Typed HTTP client for the Sybilion API. Env vars depend on bundler; for Vite, only `import.meta.env.VITE_*` reaches the client.
+
+Create **one** instance at module scope (e.g. `src/libs/sybilion-sdk.ts`) so React never reconstructs the client (`useMemo` not needed), and reuse it for auth + data:
+
+```ts
+import { createSybilionSDK } from '@sybilion/sdk';
+
+export const sybilionJwtStorageKey = 'sybilion.standalone.jwt';
+
+export const sybilionSdk = createSybilionSDK({
+  baseUrl: import.meta.env.VITE_SYBILION_API_BASE_URL as string,
+  apiPrefix: '/api',
+  getToken: () =>
+    typeof localStorage !== 'undefined'
+      ? (localStorage.getItem(sybilionJwtStorageKey) ?? undefined)
+      : undefined,
+});
+```
+
+**Options:** `baseUrl` — API origin only (no trailing slash). `apiPrefix` — default `'/api'` so calls go to `{baseUrl}/api/v1/...`. `getToken` — must read the same key you pass as `sybilionTokenStorageKey` on `SybilionAuthProvider` (§3).
+
+```ts
+import { sybilionSdk } from './libs/sybilion-sdk';
+
+await sybilionSdk.raw.datasets.getById(datasetId);
+```
+
+- `sybilionSdk.auth` — `loginWithAuth0Identity`, `getMe`, `updateMe` (Auth0 bootstrap + user profile).
+- `sybilionSdk.raw` — thin `GET`/`POST`/… wrappers for `/v1/...` paths (e.g. `raw.analyses.driversMapOnce`; parsed JSON, no app-specific shaping).
+- `sybilionSdk.resources` — higher-level helpers (datasets, drivers, subscriptions) on top of `raw`.
+
+Package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk) — monorepo: [`../../sdk/README.md`](../../sdk/README.md).
+
+## 3. Auth (`SybilionAuthProvider`)
+
+Use inside `BrowserRouter` if redirects hit a callback route.
+
+Wire the SDK module from §2 — no second `createSybilionSDK` here:
+
+```tsx
+import type { ReactNode } from 'react';
+
+import { SybilionAuthProvider } from '@sybilion/uilib';
+
+import { sybilionJwtStorageKey, sybilionSdk } from './libs/sybilion-sdk';
+
+export function AppProviders({ children }: { children: ReactNode }) {
+  const auth0Domain = import.meta.env.VITE_AUTH0_DOMAIN as string;
+  const auth0ClientId = import.meta.env.VITE_AUTH0_CLIENT_ID as string;
+
+  return (
+    <SybilionAuthProvider
+      sdk={sybilionSdk}
+      sybilionTokenStorageKey={sybilionJwtStorageKey}
+      auth0Domain={auth0Domain}
+      auth0ClientId={auth0ClientId}
+      redirectUri={window.location.origin}
+    >
+      {children}
+    </SybilionAuthProvider>
+  );
+}
+```
+
+**Flow:** Auth0 SPA → `sybilionSdk.auth.loginWithAuth0Identity(<Auth0 AT>)` → Sybilion JWT (`data.token` / `token`) persisted → same `sybilionSdk` + `getToken` attach Bearer on requests; `useSybilionApiFetch()` uses `getSybilionApiOriginFromSdk(sdk)` for URLs (paths like `/api/v1/...`).
+
+**Defaults** for `authorizationParams` match sybilion-client (Management audience + `openid profile email offline_access …`); override if your Auth0 SPA needs a Resource Server audience (backend confirms).
+
+| Layer            | Configure                                                                                                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auth0**        | Callback, logout, and web origins → your URLs (+ previews).                                                                                                                  |
+| **Sybilion API** | CORS → your deploy `Origin`.                                                                                                                                                 |
+| **App**          | §2 SDK module (`baseUrl`, `apiPrefix`, `getToken`); pass `sdk` + matching `sybilionTokenStorageKey`; Auth0 `domain` / `clientId`; redirect usually `window.location.origin`. |
+
+**Hooks:** `useSybilionAuth()`, `useSybilionApiFetch()` (or `createSybilionApiFetch` / `sybilionApiFetch` helpers).
+
+## 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.
+
+### Root wiring (`App.tsx`)
+
+Order outside → in: `BrowserRouter` (callbacks) → `AppProviders` (§3) → `SidebarProvider` (sidebar width / open state for `Sidebar` primitives) → `AppLayout` → `Routes`.
+
+`AppLayout` renders the persistent chrome (sidebar, header, footer) and the active route renders inside its main column via `children`. Add `HomePage` / `DatasetsPage` as your own page components; register an Auth0 callback route here if `SybilionAuthProvider` uses a dedicated path.
+
+```tsx
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+
+import { SidebarProvider } from '@sybilion/uilib';
+
+import { AppLayout } from './AppLayout';
+import { AppProviders } from './AppProviders';
+import { DatasetsPage } from './pages/DatasetsPage';
+import { HomePage } from './pages/HomePage';
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <AppProviders>
+        <SidebarProvider
+          sidebarWidthStorageKey="myapp.sidebarWidthPx"
+          persistSidebarWidthWithoutConsent
+        >
+          <AppLayout>
+            <Routes>
+              <Route path="/" element={<HomePage />} />
+              <Route path="/datasets" element={<DatasetsPage />} />
+            </Routes>
+          </AppLayout>
+        </SidebarProvider>
+      </AppProviders>
+    </BrowserRouter>
+  );
+}
+```
+
+`SidebarProvider`: pass only the props you need. `sidebarWidthStorageKey` namespaces width in localStorage. For production apps with cookie-based consent, drop `persistSidebarWidthWithoutConsent` and pass `userId` so width persistence follows your consent rules.
+
+### `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.
 
 ```tsx
 import type { ReactNode } from 'react';
@@ -34,18 +155,23 @@ import {
   NavUserHeader,
   PageFooter,
   PageScroll,
+  SidebarTrigger,
 } from '@sybilion/uilib';
 
+import { AppSidebar } from './AppSidebar';
+
 export function AppLayout({ children }: { children: ReactNode }) {
   return (
     <PageScroll>
       <AppShell>
-        {/* Optional: sidebar as a sibling before main, e.g. <Sidebar … /> */}
+        <AppSidebar />
+
         <AppShellMainContent
           header={<AppHeaderHost />}
-          footer={<PageFooter versionLink="/releases" versionLabel="0.0.0" />}
+          footer={<PageFooter versionLink="/releases" versionLabel="0.0.1" />}
         >
           <AppHeaderPortal>
+            <SidebarTrigger />
             <Gap />
             <NavUserHeader
               theme="light"
@@ -62,118 +188,115 @@ export function AppLayout({ children }: { children: ReactNode }) {
 }
 ```
 
-Wire `NavUserHeader` to real auth (`useSybilionAuth`, theme context, etc.). Demo page in repo: `src/docs/pages/NavUserHeaderPage.tsx` (slug `nav-user-header`).
-
-### Full pattern
-
-Reference: `[src/docs/DocsShell.tsx](https://github.com/Mir-Insight/uilib/blob/main/src/docs/DocsShell.tsx)` — `PageScroll` → `AppShell` → sidebar → `AppShellMainContent` with `AppHeaderHost`, `PageFooter`, and routed body (`Outlet`). Add `Theme` and optional `SidebarProvider` from `@homecode/ui`.
-
-### 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; typically holds a sidebar (optional) + main column.                                        |
-| `**AppShellMainContent**`                   | Main column with slots: `header`, scrollable body (`children`), `footer`.                                         |
-| `**AppHeaderHost**`                         | Renders the top header anchor (DOM id `page-header`); stays empty on purpose.                                     |
-| `**AppHeaderPortal**`                       | Portals children into `AppHeaderHost` — put header actions, `NavUserHeader`, theme toggle here.                   |
-| `**NavUserHeader**`                         | Header user menu: avatar, account dropdown, theme row, logout; **not** a bare `DropdownMenu`.                     |
-| `**Sidebar`\*\*                             | Collapsible app sidebar / nav rail (pair with `SidebarProvider` from `@homecode/ui` when needed).                 |
-| `**PageFooter**`                            | Standard app footer (logo, links, version badge). Requires `versionLink` + `versionLabel`.                        |
-| `**Gap**`                                   | Horizontal or vertical spacing primitive between flex children (prefer over raw margins).                         |
-| `**SybilionAuthProvider**`                  | Auth0 + Sybilion JWT bootstrap for the whole app (see §3).                                                        |
-| `**useSybilionAuth**`                       | Current user, tokens, login/logout inside the provider tree.                                                      |
-| `**useSybilionApiFetch**`                   | Authenticated `fetch` to the Sybilion API using the stored JWT.                                                   |
-| `**Breadcrumb**`, `**BreadcrumbList`, …\*\* | Accessible breadcrumb trail for the page header (compose `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage`). |
-| `**Button`**, `**Card\*\*`                  | Primary actions and grouped content blocks—default building blocks for screens inside the layout body.            |
-
-## 3. Auth (`SybilionAuthProvider`)
+Wire `NavUserHeader` to real auth (`useSybilionAuth`, theme context, etc.; §3). Demo in repo: `src/docs/pages/NavUserHeaderPage.tsx` (slug `nav-user-header`).
 
-Use inside `BrowserRouter` if redirects hit a callback route.
+#### Sidebar (`AppSidebar.tsx`)
 
-Env vars depend on bundler—for **Vite** only `import.meta.env.VITE_` is exposed client-side:
+App-specific sidebar component — keeps the navigation surface out of `AppLayout` so the shell stays generic. Compose your nav from `@sybilion/uilib` primitives (`Sidebar` + `SidebarContent` + `SidebarGroup` + `SidebarMenu*`) and product widgets like `SidebarDatasetsItemsGrouped` (collapsible groups + nested rows for datasets — see demo `src/docs/pages/SidebarDatasetsItemsGroupedPage.tsx`, slug `sidebar-datasets-items-grouped`).
 
 ```tsx
-import { useMemo, type ReactNode } from 'react';
+import { useEffect, useState } from 'react';
+import { NavLink, useNavigate } from 'react-router-dom';
 
-import { SybilionAuthProvider } from '@sybilion/uilib';
-import { createSybilionSDK } from '@sybilion/sdk';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarDatasetsItemsGrouped,
+  type SidebarDatasetsItemsGroupedDataset,
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from '@sybilion/uilib';
 
-const sybilionJwtKey = 'sybilion.standalone.jwt';
+import { sybilionSdk } from './libs/sybilion-sdk';
 
-export function AppProviders({ children }: { children: ReactNode }) {
-  const apiBaseUrl = import.meta.env.VITE_SYBILION_API_BASE_URL as string;
-  const auth0Domain = import.meta.env.VITE_AUTH0_DOMAIN as string;
-  const auth0ClientId = import.meta.env.VITE_AUTH0_CLIENT_ID as string;
+export function AppSidebar() {
+  const navigate = useNavigate();
+  const [datasets, setDatasets] = useState<
+    SidebarDatasetsItemsGroupedDataset[]
+  >([]);
+  const [selectedDatasetId, setSelectedDatasetId] = useState<number>();
 
-  const sdk = useMemo(
-    () =>
-      createSybilionSDK({
-        baseUrl: apiBaseUrl,
-        apiPrefix: '/api',
-        getToken: () =>
-          typeof localStorage !== 'undefined'
-            ? localStorage.getItem(sybilionJwtKey) ?? undefined
-            : undefined,
-      }),
-    [apiBaseUrl],
-  );
+  useEffect(() => {
+    sybilionSdk.raw.datasetsIndex(1, 50).then(res => {
+      setDatasets(res?.data?.datasets ?? []);
+    });
+  }, []);
 
   return (
-    <SybilionAuthProvider
-      sdk={sdk}
-      sybilionTokenStorageKey={sybilionJwtKey}
-      auth0Domain={auth0Domain}
-      auth0ClientId={auth0ClientId}
-      redirectUri={window.location.origin}
-    >
-      {children}
-    </SybilionAuthProvider>
+    <Sidebar variant="inset" collapsible="offcanvas">
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <NavLink to="/" end>
+                  Home
+                </NavLink>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <NavLink to="/datasets">Datasets</NavLink>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroup>
+
+        <SidebarDatasetsItemsGrouped
+          groupBy="regions"
+          datasets={datasets}
+          selectedDatasetId={selectedDatasetId}
+          onDatasetClick={id => {
+            setSelectedDatasetId(id);
+            navigate(`/datasets/${id}`);
+          }}
+        />
+      </SidebarContent>
+    </Sidebar>
   );
 }
 ```
 
-**Flow:** Auth0 SPA → `sdk.auth.loginWithAuth0Identity(<Auth0 AT>)` → Sybilion JWT (`data.token` / `token`) persisted → same `sdk` + `getToken` supply Bearer on API calls; `useSybilionApiFetch()` uses `getSybilionApiOriginFromSdk(sdk)` for URLs (paths like `/api/v1/...`).
-
-**Defaults** for `authorizationParams` match sybilion-client (Management audience + `openid profile email offline_access …`); override if your Auth0 SPA needs a Resource Server audience (backend confirms).
-
-| Layer            | Configure                                                                             |
-| ---------------- | ------------------------------------------------------------------------------------- |
-| **Auth0**        | Callback, logout, and web origins → your URLs (+ previews).                           |
-| **Sybilion API** | CORS → your deploy `Origin`.                                                          |
-| **App**          | `createSybilionSDK` (`baseUrl`, `apiPrefix`), pass **`sdk`** to `SybilionAuthProvider`; align `sybilionTokenStorageKey` with `getToken`; Auth0 `domain` / `clientId`; redirect usually `window.location.origin`. |
-
-**Hooks:** `useSybilionAuth()`, `useSybilionApiFetch()` (or `createSybilionApiFetch` / `sybilionApiFetch` helpers).
+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`.
 
-## 4. Data
-
-Fetch the Sybilion API with the JWT above (e.g. via `useSybilionApiFetch`).
+### Full pattern
 
-### `@sybilion/sdk`
+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.
 
-Install the typed client alongside uilib:
+### Greenfield checklist (agents)
 
-```bash
-yarn add @sybilion/sdk
-```
+| Step  | Deliverable                                                                                                                                              |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Env   | `VITE_SYBILION_API_BASE_URL`, `VITE_AUTH0_DOMAIN`, `VITE_AUTH0_CLIENT_ID` (names mirror §2–§3).                                                          |
+| Files | `src/libs/sybilion-sdk.ts`, `AppProviders.tsx`, `AppLayout.tsx`, `AppSidebar.tsx`, `App.tsx`, `main.tsx`, route `element` pages under e.g. `src/pages/`. |
+| Auth0 | SPA callback / logout URLs + allowed web origins → your deploy URLs (and previews).                                                                      |
+| API   | Sybilion backend CORS → same `Origin` values.                                                                                                            |
 
-Configure **`createSybilionSDK`** with the same instance you pass to **`SybilionAuthProvider`** (`sdk` prop). Use **`baseUrl`**: API origin only (no trailing slash), default **`apiPrefix: '/api'`** so requests hit `{baseUrl}/api/v1/...`. **`getToken`** should read the same storage key as **`sybilionTokenStorageKey`** on the provider (default `sybilion.standalone.jwt`).
-
-```ts
-import { createSybilionSDK } from '@sybilion/sdk';
-
-const sdk = createSybilionSDK({
-  baseUrl: apiBaseUrl,
-  apiPrefix: '/api',
-  getToken: () => localStorage.getItem('sybilion.standalone.jwt') ?? undefined,
-});
-```
-
-- **`sdk.auth`** — `loginWithAuth0Identity`, `getMe`, `updateMe` (Auth0 bootstrap + user profile).
-- **`sdk.raw`** — thin `GET`/`POST`/… wrappers for `/v1/...` paths (e.g. `raw.analyses.driversMapOnce`; returns parsed JSON, no app-specific shaping).
-- **`sdk.resources`** — higher-level helpers (datasets, drivers, subscriptions) that compose `raw` calls with parsing where applicable.
+### Glossary (high-use pieces)
 
-See the package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk) — in this monorepo, [`../../sdk/README.md`](../../sdk/README.md).
+| 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.                                                                                                                  |
+
+## 5. Data
+
+Inside `SybilionAuthProvider`, use `useSybilionApiFetch()` for authenticated `fetch`, or import `sybilionSdk` from §2 for `raw` / `resources` — same JWT storage and API origin either way.
 
 ## Related
 

package/package.json

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

package/src/components/ui/AppHeader/AppHeader.tsx

@@ -20,14 +20,18 @@ export function AppHeaderHost({
 
 export type AppHeaderPortalProps = {
   children: ReactNode;
+  pageHeaderId?: string;
 };
 
-export function AppHeaderPortal({ children }: AppHeaderPortalProps) {
+export function AppHeaderPortal({
+  children,
+  pageHeaderId = PAGE_HEADER_ID,
+}: AppHeaderPortalProps) {
   const [container, setContainer] = useState<HTMLElement | null>(null);
 
   useLayoutEffect(() => {
-    setContainer(document.getElementById(PAGE_HEADER_ID));
-  }, []);
+    setContainer(document.getElementById(pageHeaderId));
+  }, [pageHeaderId]);
 
   if (!container) {
     return null;

package/src/components/ui/Page/AppShell/AppShell.styl

@@ -5,6 +5,7 @@
   flex 1
   min-height 0
   width 100%
+  min-height 100%
   grid-template-columns 1fr
   grid-template-areas "main"
 

package/src/components/ui/Page/PageScroll/PageScroll.tsx

@@ -9,9 +9,12 @@ import S from './PageScroll.styl';
 
 function PageScrollInner({
   className,
+  rootClassName,
   children,
 }: {
   className?: string;
+  /** Merged onto the outer Scroll root (e.g. embed previews that must not use `100vh`). */
+  rootClassName?: string;
   children: React.ReactNode;
 }) {
   // const { setIsScrolled } = useContext(PageContext);
@@ -38,7 +41,7 @@ function PageScrollInner({
       y
       // fadeSize="l"
       offset={{ y: { before: 120, after: 130 } }}
-      className={S.root}
+      className={cn(S.root, rootClassName)}
       autoHide
       innerClassName={cn(S.inner, className)}
       yScrollbarClassName={S.scrollbar}
@@ -55,15 +58,19 @@ function PageScrollInner({
 export const PageScroll = ({
   children,
   className,
+  rootClassName,
 }: {
   children: React.ReactNode;
   className?: string;
+  rootClassName?: string;
 }) => {
   const [isScrolled, setIsScrolled] = useState(false);
 
   return (
     <PageContext.Provider value={{ isScrolled, setIsScrolled }}>
-      <PageScrollInner className={className}>{children}</PageScrollInner>
+      <PageScrollInner className={className} rootClassName={rootClassName}>
+        {children}
+      </PageScrollInner>
     </PageContext.Provider>
   );
 };

package/src/components/widgets/SidebarDatasetsItemsGrouped/SidebarDatasetsItemsGrouped.tsx

@@ -22,6 +22,8 @@ import {
 export type SidebarDatasetsItemsGroupedProps = {
   groupBy: SidebarDatasetsItemsGroupBy;
   datasets: SidebarDatasetsItemsGroupedDataset[];
+  preItems?: React.ReactNode;
+  postItems?: React.ReactNode;
   selectedDatasetId?: number;
   onDatasetClick?: (datasetId: number) => void;
   /** When omitted, all groups start expanded. */
@@ -32,6 +34,8 @@ export type SidebarDatasetsItemsGroupedProps = {
 export function SidebarDatasetsItemsGrouped({
   groupBy,
   datasets,
+  preItems,
+  postItems,
   selectedDatasetId,
   onDatasetClick,
   defaultExpandedGroupNames,
@@ -74,6 +78,8 @@ export function SidebarDatasetsItemsGrouped({
   return (
     <SidebarGroup className={className}>
       <SidebarMenu>
+        {preItems}
+
         {grouped.map(([groupName, groupDatasets]) => {
           const isExpanded = expanded.has(groupName);
           const parentActive = groupDatasets.some(
@@ -97,6 +103,7 @@ export function SidebarDatasetsItemsGrouped({
                   )}
                 </div>
               </SidebarMenuButton>
+
               {isExpanded && (
                 <SidebarMenuSub className={S.subMenuContainer}>
                   <div className={S.subMenuBorder} />
@@ -122,6 +129,8 @@ export function SidebarDatasetsItemsGrouped({
             </SidebarMenuItem>
           );
         })}
+
+        {postItems}
       </SidebarMenu>
     </SidebarGroup>
   );

package/src/docs/pages/StandaloneAppLayoutPage.styl

@@ -0,0 +1,46 @@
+@import '../../lib/theme.styl'
+
+// Embed preview: Sidebar uses position:fixed + viewport top/height; PageScroll uses 100vh.
+// Transform creates a containing block for `fixed` children; overrides stop bleed into docs chrome.
+.preview
+  position relative
+  overflow hidden
+  transform translateZ(0)
+  border-radius var(--p-4)
+  border 1px solid var(--border)
+  background-color var(--background)
+  height min(720px, 80vh)
+  min-height 0
+  display flex
+  flex-direction column
+
+.previewScrollRoot
+  flex 1
+  min-height 0
+  height 100% !important
+  max-height 100% !important
+
+  @media (max-width MOBILE)
+    height auto !important
+    flex 1
+
+.preview aside[data-side="left"]
+  top 0 !important
+  left 0 !important
+  height 100% !important
+  min-height 0 !important
+
+  @media (min-width MOBILE)
+    height 100% !important
+
+.preview aside[data-side="left"] > div:first-child
+  height 100% !important
+  max-height 100% !important
+
+  @media (min-width MOBILE)
+    height 100% !important
+
+.preview [data-slot="sidebar-resize-handle"]
+  top 0 !important
+  height 100% !important
+  max-height 100%

package/src/docs/pages/StandaloneAppLayoutPage.styl.d.ts

@@ -0,0 +1,8 @@
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'preview': string;
+  'previewScrollRoot': string;
+}
+export const cssExports: CssExports;
+export default cssExports;

package/src/docs/pages/StandaloneAppLayoutPage.tsx

@@ -0,0 +1,242 @@
+import { useCallback, useState } from 'react';
+
+import { AppHeaderHost, AppHeaderPortal } from '#uilib/components/ui/AppHeader';
+import { Gap } from '#uilib/components/ui/Gap/Gap';
+import { NavUserHeader } from '#uilib/components/ui/NavUserHeader/NavUserHeader';
+import {
+  AppShell,
+  AppShellMainContent,
+  PageContentSection,
+} from '#uilib/components/ui/Page';
+import { PageFooter } from '#uilib/components/ui/Page/PageFooter/PageFooter';
+import { PageScroll } from '#uilib/components/ui/Page/PageScroll/PageScroll';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from '#uilib/components/ui/Sidebar/Sidebar';
+import {
+  SidebarDatasetsItemsGrouped,
+  type SidebarDatasetsItemsGroupedDataset,
+} from '#uilib/components/widgets/SidebarDatasetsItemsGrouped';
+import { House } from 'lucide-react';
+
+import { AppPageHeader } from '../components/AppPageHeader/AppPageHeader';
+import { DocsHeaderActions } from '../docsHeaderActions';
+import S from './StandaloneAppLayoutPage.styl';
+
+const MOCK_DATASETS: SidebarDatasetsItemsGroupedDataset[] = [
+  {
+    id: 1,
+    name: 'Acetic Acid Price - China - Dollar/MT',
+    status: 'active',
+    created_at: '2024-01-01',
+    updated_at: '2024-01-02',
+    keywords: '',
+    category: { id: 10, name: 'Chemicals' },
+    target_type_id: 1,
+    target_type: { id: 1, name: 'Commodity price' },
+    trend: 0,
+    regular_price: '0',
+    sale_price: '0',
+    regions: [
+      { id: 1, name: 'Asia' },
+      { id: 2, name: 'China' },
+    ],
+    unit: { id: 1, name: 'USD/MT' },
+  },
+  {
+    id: 2,
+    name: 'Freight index — spot volume (China)',
+    status: 'active',
+    created_at: '2024-01-01',
+    updated_at: '2024-01-02',
+    keywords: '',
+    category: { id: 10, name: 'Chemicals' },
+    target_type_id: 2,
+    target_type: { id: 2, name: 'Freight index' },
+    trend: 0,
+    regular_price: '0',
+    sale_price: '0',
+    regions: [
+      { id: 1, name: 'Asia' },
+      { id: 2, name: 'China' },
+    ],
+    unit: { id: 1, name: 'Index' },
+  },
+  {
+    id: 3,
+    name: 'Ethanol Price Europe Per Kg In USD',
+    status: 'active',
+    created_at: '2024-01-01',
+    updated_at: '2024-01-02',
+    keywords: '',
+    category: { id: 11, name: 'Energy' },
+    target_type_id: 1,
+    target_type: { id: 1, name: 'Commodity price' },
+    trend: 0,
+    regular_price: '0',
+    sale_price: '0',
+    regions: [{ id: 5, name: 'Europe' }],
+    unit: { id: 1, name: 'USD/kg' },
+  },
+];
+
+type PreviewPanel = 'home' | 'datasets';
+
+const TEST_HEADER_ID = 'test-header-id';
+
+function DemoAppSidebar({
+  panel,
+  onSelectPanel,
+  selectedDatasetId,
+  onSelectDatasetId,
+}: {
+  panel: PreviewPanel;
+  onSelectPanel: (p: PreviewPanel) => void;
+  selectedDatasetId: number | undefined;
+  onSelectDatasetId: (id: number | undefined) => void;
+}) {
+  return (
+    <Sidebar
+      variant="inset"
+      collapsible="offcanvas"
+      style={{ maxHeight: '100%', height: '100%' }}
+    >
+      <SidebarContent>
+        <SidebarDatasetsItemsGrouped
+          preItems={
+            <SidebarMenuItem>
+              <SidebarMenuButton
+                type="button"
+                isActive={panel === 'home'}
+                onClick={() => onSelectPanel('home')}
+              >
+                <House size={16} strokeWidth={1.75} aria-hidden />
+                Home
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          }
+          groupBy="regions"
+          datasets={MOCK_DATASETS}
+          selectedDatasetId={selectedDatasetId}
+          onDatasetClick={id => {
+            onSelectDatasetId(id);
+            onSelectPanel('datasets');
+          }}
+        />
+      </SidebarContent>
+    </Sidebar>
+  );
+}
+
+function DemoMainBody({ panel }: { panel: PreviewPanel }) {
+  if (panel === 'home') {
+    return (
+      <div style={{ padding: 'var(--p-6)' }}>
+        <h2 style={{ margin: '0 0 0.5rem', fontSize: '1.125rem' }}>Home</h2>
+        <p style={{ margin: 0, color: 'var(--muted-foreground)' }}>
+          Preview: greenfield shell layout only (no SDK or auth). Real SPA uses
+          one top-level Router; this embed cannot nest MemoryRouter under docs
+          BrowserRouter — sidebar uses local state instead of{' '}
+          <code>NavLink</code> / <code>Routes</code>.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ padding: 'var(--p-6)' }}>
+      <h2 style={{ margin: '0 0 0.5rem', fontSize: '1.125rem' }}>Datasets</h2>
+      <p style={{ margin: 0, color: 'var(--muted-foreground)' }}>
+        Use sidebar links and dataset rows; panel state stays inside this box.
+      </p>
+    </div>
+  );
+}
+
+function StandaloneLayoutPreview() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  const [panel, setPanel] = useState<PreviewPanel>('home');
+  const [selectedDatasetId, setSelectedDatasetId] = useState<
+    number | undefined
+  >();
+
+  const onThemeToggle = useCallback(() => {
+    setTheme(t => (t === 'dark' ? 'light' : 'dark'));
+  }, []);
+
+  return (
+    <div className={S.preview}>
+      <PageScroll rootClassName={S.previewScrollRoot}>
+        <AppShell>
+          <DemoAppSidebar
+            panel={panel}
+            onSelectPanel={setPanel}
+            selectedDatasetId={selectedDatasetId}
+            onSelectDatasetId={setSelectedDatasetId}
+          />
+
+          <AppShellMainContent
+            header={<AppHeaderHost anchorId={TEST_HEADER_ID} />}
+            footer={
+              <PageFooter
+                versionLink="#standalone-layout-preview"
+                versionLabel="0.0.0-preview"
+              />
+            }
+          >
+            <AppHeaderPortal pageHeaderId={TEST_HEADER_ID}>
+              <SidebarTrigger />
+              <Gap />
+              <NavUserHeader
+                user={{
+                  name: 'Preview User',
+                  email: 'preview@example.com',
+                  avatar: '',
+                }}
+                theme={theme}
+                onThemeToggle={onThemeToggle}
+                onLogout={() => undefined}
+              />
+            </AppHeaderPortal>
+            <DemoMainBody panel={panel} />
+          </AppShellMainContent>
+        </AppShell>
+      </PageScroll>
+    </div>
+  );
+}
+
+export default function StandaloneAppLayoutPage() {
+  return (
+    <>
+      <AppPageHeader
+        breadcrumbs={[{ label: 'Standalone app layout' }]}
+        title="Standalone app layout"
+        subheader={
+          <>
+            Live preview of AppShell + Sidebar + main column from
+            docs/standalone-apps.md §4. <br />
+            Full greenfield setup (deps, global CSS, SybilionAuthProvider, SDK)
+            lives in that doc — this page is layout only.
+          </>
+        }
+        actions={<DocsHeaderActions />}
+      />
+      <PageContentSection title="Embedded mini-app (layout preview)">
+        <SidebarProvider
+          sidebarWidthStorageKey="uilib.docs.standaloneLayout.sidebarWidthPx"
+          persistSidebarWidthWithoutConsent
+        >
+          <StandaloneLayoutPreview />
+        </SidebarProvider>
+      </PageContentSection>
+    </>
+  );
+}

package/src/docs/registry.ts

@@ -216,6 +216,12 @@ export const DOC_REGISTRY: DocEntry[] = [
     section: 'Layout',
     load: () => import('./pages/PagePage'),
   },
+  {
+    slug: 'standalone-app-layout',
+    title: 'Standalone app layout',
+    section: 'Layout',
+    load: () => import('./pages/StandaloneAppLayoutPage'),
+  },
   {
     slug: 'progress',
     title: 'Progress',