@sybilion/uilib 1.2.1 → 1.2.4

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/dist/standalone/vite-sybilion-standalone-dev.d.ts

@@ -0,0 +1,13 @@
+import type { UserConfig } from 'vite';
+export type SybilionStandaloneViteDevOptions = {
+    mode: string;
+    /** Directory containing `.env*` files. @default process.cwd() */
+    envDir?: string;
+    /** Prefix proxied to Sybilion API (SDK `apiPrefix`). @default `/api` */
+    apiPrefix?: string;
+};
+/**
+ * Vite `server` + `preview` fragment for standalone Sybilion SPAs: same-origin `/api` in dev,
+ * proxied to `VITE_SYBILION_API_BASE_URL`. Uses `PORT` from env (default `3000`).
+ */
+export declare function sybilionStandaloneViteDev(options: SybilionStandaloneViteDevOptions): Pick<UserConfig, 'server' | 'preview'>;

package/dist/standalone/vite-sybilion-standalone-dev.js

@@ -0,0 +1,49 @@
+import { loadEnv } from 'vite';
+
+const DEFAULT_PORT = 3000;
+const SYBILION_API_ENV = 'VITE_SYBILION_API_BASE_URL';
+let warnedMissingApiUrl = false;
+function parsePort(raw) {
+    if (raw == null || raw === '')
+        return DEFAULT_PORT;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0 || n > 65_535)
+        return DEFAULT_PORT;
+    return n;
+}
+function normalizeApiPrefix(apiPrefix) {
+    return apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}`;
+}
+/**
+ * Vite `server` + `preview` fragment for standalone Sybilion SPAs: same-origin `/api` in dev,
+ * proxied to `VITE_SYBILION_API_BASE_URL`. Uses `PORT` from env (default `3000`).
+ */
+function sybilionStandaloneViteDev(options) {
+    const envDir = options.envDir ?? process.cwd();
+    const apiPrefix = normalizeApiPrefix(options.apiPrefix ?? '/api');
+    const env = loadEnv(options.mode, envDir, '');
+    const port = parsePort(env.PORT);
+    const target = (env[SYBILION_API_ENV] ?? '').replace(/\/$/, '');
+    const proxy = {};
+    if (target) {
+        proxy[apiPrefix] = {
+            target,
+            changeOrigin: true,
+            secure: true,
+        };
+    }
+    else if (options.mode === 'development' && !warnedMissingApiUrl) {
+        warnedMissingApiUrl = true;
+        console.warn(`[@sybilion/uilib] ${SYBILION_API_ENV} is not set; API dev proxy disabled.`);
+    }
+    const serverPreview = {
+        port,
+        proxy,
+    };
+    return {
+        server: serverPreview,
+        preview: serverPreview,
+    };
+}
+
+export { sybilionStandaloneViteDev };

package/docs/standalone-apps.md

@@ -1,26 +1,212 @@
 # 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.
+
+**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.
 
 ## 1. Dependencies and global CSS
 
+Vite-based apps (recommended for new standalone SPAs):
+
 ```bash
 yarn add react react-dom react-router-dom @auth0/auth0-react @sybilion/uilib @sybilion/sdk
+yarn add -D vite @vitejs/plugin-react
 ```
 
-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).
+
+### `package.json` scripts (required)
+
+Add a **`dev`** script so the app is runnable immediately after clone. Typical Vite setup:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
+```
+
+### `.env.example`
+
+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). |
+
+Example **`.env.example`** content for the app root:
+
+```env
+# Copy to `.env` and fill in values. Do not commit `.env`.
+# PORT: Vite dev/preview bind (sybilionStandaloneViteDev reads this). 3000 matches Auth0 test tenant localhost URLs.
+PORT=3000
+
+VITE_SYBILION_API_BASE_URL=https://api-dev.sybilion.com
+VITE_AUTH0_DOMAIN=your-tenant.eu.auth0.com
+VITE_AUTH0_CLIENT_ID=your-spa-client-id
+```
+
+## 2. SDK (`@sybilion/sdk`)
+
+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.DEV
+    ? ''
+    : (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) **in production**; in **development** use `''` so requests stay **same-origin** (`/api/v1/...`) and the Vite dev server **proxies `/api`** to `VITE_SYBILION_API_BASE_URL` (see **Local dev: Vite API proxy** below). `apiPrefix` — default `'/api'` so calls go to `{baseUrl}/api/v1/...`. `getToken` — must read the same key you pass as `sybilionTokenStorageKey` on `SybilionAuthProvider` (§3).
 
-### Minimal example
+```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`.
 
-`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.
+Package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk) — monorepo: [`../../sdk/README.md`](../../sdk/README.md).
+
+## 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`.
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { sybilionStandaloneViteDev } from '@sybilion/uilib/vite-standalone-dev';
+
+export default defineConfig(({ mode }) => ({
+  ...sybilionStandaloneViteDev({ mode }),
+  plugins: [react()],
+}));
+```
+
+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.
+
+## 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.
+
+## 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 +220,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 +253,118 @@ 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)
+Wire `NavUserHeader` to real auth (`useSybilionAuth`, theme context, etc.; §3). Demo in repo: `src/docs/pages/NavUserHeaderPage.tsx` (slug `nav-user-header`).
 
-| 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`)
-
-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).
+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`.
 
-| 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).
-
-## 4. Data
-
-Fetch the Sybilion API with the JWT above (e.g. via `useSybilionApiFetch`).
-
-### `@sybilion/sdk`
-
-Install the typed client alongside uilib:
-
-```bash
-yarn add @sybilion/sdk
-```
+### Full pattern
 
-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`).
+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.
 
-```ts
-import { createSybilionSDK } from '@sybilion/sdk';
+### Greenfield checklist (agents)
 
-const sdk = createSybilionSDK({
-  baseUrl: apiBaseUrl,
-  apiPrefix: '/api',
-  getToken: () => localStorage.getItem('sybilion.standalone.jwt') ?? undefined,
-});
-```
+| 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. |
 
-- **`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.4",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",
@@ -30,7 +30,12 @@
       "default": "./src/index.ts"
     },
     "./src/*": "./src/*",
-    "./standalone-global.css": "./assets/standalone-global.css"
+    "./standalone-global.css": "./assets/standalone-global.css",
+    "./vite-standalone-dev": {
+      "types": "./dist/standalone/vite-sybilion-standalone-dev.d.ts",
+      "import": "./dist/standalone/vite-sybilion-standalone-dev.js",
+      "default": "./dist/standalone/vite-sybilion-standalone-dev.js"
+    }
   },
   "files": [
     "assets",
@@ -109,7 +114,8 @@
     "@sybilion/sdk": ">=0.0.1",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "react-router-dom": ">=6.0.0"
+    "react-router-dom": ">=6.0.0",
+    "vite": "^6.0.0"
   },
   "peerDependenciesMeta": {
     "@auth0/auth0-react": {
@@ -117,6 +123,9 @@
     },
     "@sybilion/sdk": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -178,6 +187,7 @@
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.1",
     "typescript": "^5.3.3",
+    "vite": "^6.0.0",
     "webpack": "^5.75.0",
     "webpack-cli": "^5.0.1",
     "webpack-dev-server": "^5.2.3"

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',

package/src/standalone/vite-sybilion-standalone-dev.ts

@@ -0,0 +1,65 @@
+import type { UserConfig } from 'vite';
+import { loadEnv } from 'vite';
+
+const DEFAULT_PORT = 3000;
+const SYBILION_API_ENV = 'VITE_SYBILION_API_BASE_URL';
+
+export type SybilionStandaloneViteDevOptions = {
+  mode: string;
+  /** Directory containing `.env*` files. @default process.cwd() */
+  envDir?: string;
+  /** Prefix proxied to Sybilion API (SDK `apiPrefix`). @default `/api` */
+  apiPrefix?: string;
+};
+
+let warnedMissingApiUrl = false;
+
+function parsePort(raw: string | undefined): number {
+  if (raw == null || raw === '') return DEFAULT_PORT;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0 || n > 65_535) return DEFAULT_PORT;
+  return n;
+}
+
+function normalizeApiPrefix(apiPrefix: string): string {
+  return apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}`;
+}
+
+/**
+ * Vite `server` + `preview` fragment for standalone Sybilion SPAs: same-origin `/api` in dev,
+ * proxied to `VITE_SYBILION_API_BASE_URL`. Uses `PORT` from env (default `3000`).
+ */
+export function sybilionStandaloneViteDev(
+  options: SybilionStandaloneViteDevOptions,
+): Pick<UserConfig, 'server' | 'preview'> {
+  const envDir = options.envDir ?? process.cwd();
+  const apiPrefix = normalizeApiPrefix(options.apiPrefix ?? '/api');
+  const env = loadEnv(options.mode, envDir, '');
+  const port = parsePort(env.PORT);
+  const target = (env[SYBILION_API_ENV] ?? '').replace(/\/$/, '');
+
+  const proxy: NonNullable<UserConfig['server']>['proxy'] = {};
+
+  if (target) {
+    proxy[apiPrefix] = {
+      target,
+      changeOrigin: true,
+      secure: true,
+    };
+  } else if (options.mode === 'development' && !warnedMissingApiUrl) {
+    warnedMissingApiUrl = true;
+    console.warn(
+      `[@sybilion/uilib] ${SYBILION_API_ENV} is not set; API dev proxy disabled.`,
+    );
+  }
+
+  const serverPreview = {
+    port,
+    proxy,
+  };
+
+  return {
+    server: serverPreview,
+    preview: serverPreview,
+  };
+}