@sybilion/uilib 1.1.0 → 1.2.1

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

@@ -0,0 +1,11 @@
+import { type SidebarDatasetsItemsGroupBy, type SidebarDatasetsItemsGroupedDataset } from './groupSidebarDatasets';
+export type SidebarDatasetsItemsGroupedProps = {
+    groupBy: SidebarDatasetsItemsGroupBy;
+    datasets: SidebarDatasetsItemsGroupedDataset[];
+    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;

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

@@ -0,0 +1,8 @@
+import type { SybilionDatasetSnapshot } from '#uilib/types/sybilionDatasetSnapshots';
+export type SidebarDatasetsItemsGroupedDataset = SybilionDatasetSnapshot;
+export type SidebarDatasetsItemsGroupBy = 'target_type' | 'regions' | 'categories';
+export type GroupedSidebarDatasetsEntry = readonly [
+    groupName: string,
+    datasets: SidebarDatasetsItemsGroupedDataset[]
+];
+export declare function groupSidebarDatasets(datasets: SidebarDatasetsItemsGroupedDataset[], groupBy: SidebarDatasetsItemsGroupBy): GroupedSidebarDatasetsEntry[];

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

@@ -0,0 +1,3 @@
+export { SidebarDatasetsItemsGrouped, type SidebarDatasetsItemsGroupedProps, } from './SidebarDatasetsItemsGrouped';
+export type { GroupedSidebarDatasetsEntry, SidebarDatasetsItemsGroupBy, SidebarDatasetsItemsGroupedDataset, } from './groupSidebarDatasets';
+export { groupSidebarDatasets } from './groupSidebarDatasets';

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

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

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

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

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

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

package/dist/esm/types/src/index.d.ts

@@ -1,4 +1,5 @@
-export * from './mini-app';
+export * from './sybilion-auth';
+export * from './types/sybilionDatasetSnapshots';
 export * from './contexts/chat-context';
 export * from './types/chat-api.types';
 export * from './components/ui/AnalysesSelector';
@@ -30,6 +31,7 @@ export * from './components/ui/LabelWithId';
 export * from './components/ui/LegacyPlatformLink';
 export * from './components/ui/Logo';
 export * from './components/ui/MobileAdaptiveSelector';
+export * from './components/ui/NavUserHeader';
 export * from './components/ui/NumberControl';
 export * from './components/ui/Page';
 export * from './components/ui/Progress';
@@ -53,3 +55,4 @@ export * from './components/ui/Toggle';
 export * from './components/ui/ToggleGroup';
 export * from './components/ui/Tooltip';
 export * from './components/ui/VimeoEmbed';
+export * from './components/widgets/SidebarDatasetsItemsGrouped';

package/dist/esm/types/src/sybilion-auth/SybilionAuthProvider.d.ts

@@ -0,0 +1,42 @@
+import { type RedirectLoginOptions } from '@auth0/auth0-react';
+import type { SybilionSDK } from '@sybilion/sdk';
+import type { JSX, ReactNode } from 'react';
+/** Origin (`scheme://host:port`) for paths like `/api/v1/...`; derived from SDK URL layout. */
+export declare function getSybilionApiOriginFromSdk(sdk: SybilionSDK): string;
+export type SybilionAuthProviderProps = {
+    children: ReactNode;
+    sdk: SybilionSDK;
+    auth0Domain: string;
+    auth0ClientId: string;
+    redirectUri: string;
+    /**
+     * Defaults match sybilion-client AuthProvider (Management API audience + metadata scope).
+     * Override if your Auth0 SPA app uses a Resource Server audience for `/v1/auth/login`.
+     */
+    authorizationParams?: {
+        audience?: string;
+        scope?: string;
+        redirect_uri?: string;
+    };
+    sybilionTokenStorageKey?: string;
+    logoutReturnTo?: string;
+};
+export type SybilionAuthContextValue = {
+    apiBaseUrl: string;
+    isLoading: boolean;
+    /** Auth0 authenticated and Sybilion JWT present. */
+    isAuthenticated: boolean;
+    sybilionAccessToken: string | null;
+    error: string | null;
+    loginWithRedirect: (options?: RedirectLoginOptions) => Promise<void>;
+    logout: () => void;
+    getAuth0AccessToken: () => Promise<string | undefined>;
+    getSybilionAccessToken: () => Promise<string | null>;
+};
+export declare function useSybilionAuth(): SybilionAuthContextValue;
+/** fetch() relative to Sybilion API base with Bearer Sybilion JWT. */
+export declare function sybilionApiFetch(apiBaseUrl: string, bearerToken: string, path: string, init?: RequestInit): Promise<Response>;
+export declare function createSybilionApiFetch(apiBaseUrl: string, getSybilionAccessToken: () => Promise<string | null>): (path: string, init?: RequestInit) => Promise<Response>;
+/** Authenticated fetch using {@link useSybilionAuth} context. */
+export declare function useSybilionApiFetch(): (path: string, init?: RequestInit) => Promise<Response>;
+export declare function SybilionAuthProvider({ children, sdk, auth0Domain, auth0ClientId, redirectUri, authorizationParams, sybilionTokenStorageKey, logoutReturnTo, }: SybilionAuthProviderProps): JSX.Element;

package/dist/esm/types/src/sybilion-auth/authPaths.d.ts

@@ -0,0 +1,3 @@
+/** Sybilion platform auth exchange route (joined with trimmed API base URL). */
+export declare const SYBILION_AUTH_LOGIN_PATH = "/v1/auth/login";
+export declare function normalizeApiBaseUrl(url: string): string;

package/dist/esm/types/src/sybilion-auth/exchangeSybilionToken.d.ts

@@ -0,0 +1,4 @@
+/** POST `{ identity: auth0AccessToken, type: 'auth0' }` → Sybilion API JWT string. */
+export declare function exchangeAuth0AccessTokenForSybilionJwt(
+/** API origin only (no trailing slash), same as SDK `baseUrl`. */
+apiBaseUrl: string, auth0AccessToken: string): Promise<string>;

package/dist/esm/types/src/sybilion-auth/index.d.ts

@@ -0,0 +1,4 @@
+export type { SybilionAuthProviderProps, SybilionAuthContextValue, } from '#uilib/sybilion-auth/SybilionAuthProvider';
+export { SybilionAuthProvider, getSybilionApiOriginFromSdk, useSybilionAuth, sybilionApiFetch, createSybilionApiFetch, useSybilionApiFetch, } from '#uilib/sybilion-auth/SybilionAuthProvider';
+export { SYBILION_AUTH_LOGIN_PATH, normalizeApiBaseUrl, } from '#uilib/sybilion-auth/authPaths';
+export { exchangeAuth0AccessTokenForSybilionJwt } from '#uilib/sybilion-auth/exchangeSybilionToken';

package/dist/esm/types/src/{mini-app/miniAppDataTypes.d.ts → types/sybilionDatasetSnapshots.d.ts}

@@ -1,8 +1,7 @@
 /**
- * Serializable shapes returned by the shell for mini-app data getters.
- * Subset of Sybilion `Dataset` / API types — use `unknown` where payloads are large or evolving.
+ * Loose JSON shapes aligned with Sybilion dataset payloads (standalone apps / widgets).
  */
-export type MiniAppDataset = {
+export type SybilionDatasetSnapshot = {
     id: number;
     user_id?: number;
     name: string;
@@ -34,14 +33,12 @@ export type MiniAppDataset = {
     version?: number;
 };
 /** `forecastData` slice: analysis id (string) → forecast series blob. */
-export type MiniAppForecastMap = Record<string, unknown>;
-export type MiniAppPerformanceBundle = {
-    /** Cached Performance-tab API payload, or null if user never opened Performance / cache empty. */
+export type SybilionForecastMap = Record<string, unknown>;
+export type SybilionPerformanceSnapshot = {
     table: unknown;
-    /** In-memory spaghetti lines from shell context, or null. */
     spaghetti: unknown;
 };
-export type MiniAppDriversComparisonSnapshot = {
+export type SybilionDriversComparisonSnapshot = {
     byRegion: unknown;
     byCountry: unknown;
     byCategory: unknown;

package/docs/standalone-apps.md

@@ -0,0 +1,181 @@
+# 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.
+
+**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
+
+```bash
+yarn add react react-dom react-router-dom @auth0/auth0-react @sybilion/uilib @sybilion/sdk
+```
+
+Import tokens/fonts once:
+
+```ts
+import '@sybilion/uilib/standalone-global.css';
+```
+
+## 2. Layout (AppShell)
+
+### Minimal example
+
+`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.
+
+```tsx
+import type { ReactNode } from 'react';
+
+import {
+  AppHeaderHost,
+  AppHeaderPortal,
+  AppShell,
+  AppShellMainContent,
+  Gap,
+  NavUserHeader,
+  PageFooter,
+  PageScroll,
+} from '@sybilion/uilib';
+
+export function AppLayout({ children }: { children: ReactNode }) {
+  return (
+    <PageScroll>
+      <AppShell>
+        {/* Optional: sidebar as a sibling before main, e.g. <Sidebar … /> */}
+        <AppShellMainContent
+          header={<AppHeaderHost />}
+          footer={<PageFooter versionLink="/releases" versionLabel="0.0.0" />}
+        >
+          <AppHeaderPortal>
+            <Gap />
+            <NavUserHeader
+              theme="light"
+              onThemeToggle={() => undefined}
+              onLogout={() => undefined}
+              isAuthenticated={false}
+            />
+          </AppHeaderPortal>
+          {children}
+        </AppShellMainContent>
+      </AppShell>
+    </PageScroll>
+  );
+}
+```
+
+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`)
+
+Use inside `BrowserRouter` if redirects hit a callback route.
+
+Env vars depend on bundler—for **Vite** only `import.meta.env.VITE_` is exposed client-side:
+
+```tsx
+import { useMemo, type ReactNode } from 'react';
+
+import { SybilionAuthProvider } from '@sybilion/uilib';
+import { createSybilionSDK } from '@sybilion/sdk';
+
+const sybilionJwtKey = 'sybilion.standalone.jwt';
+
+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;
+
+  const sdk = useMemo(
+    () =>
+      createSybilionSDK({
+        baseUrl: apiBaseUrl,
+        apiPrefix: '/api',
+        getToken: () =>
+          typeof localStorage !== 'undefined'
+            ? localStorage.getItem(sybilionJwtKey) ?? undefined
+            : undefined,
+      }),
+    [apiBaseUrl],
+  );
+
+  return (
+    <SybilionAuthProvider
+      sdk={sdk}
+      sybilionTokenStorageKey={sybilionJwtKey}
+      auth0Domain={auth0Domain}
+      auth0ClientId={auth0ClientId}
+      redirectUri={window.location.origin}
+    >
+      {children}
+    </SybilionAuthProvider>
+  );
+}
+```
+
+**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).
+
+## 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
+```
+
+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.
+
+See the package README: [`@sybilion/sdk`](https://www.npmjs.com/package/@sybilion/sdk) — in this monorepo, [`../../sdk/README.md`](../../sdk/README.md).
+
+## Related
+
+- [auth0-configuration-guide.md](https://github.com/Mir-Insight/sybilion-client/blob/main/docs/auth0-configuration-guide.md)
+- [server-auth-verification.md](https://github.com/Mir-Insight/sybilion-client/blob/main/docs/server-auth-verification.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",
@@ -30,7 +30,7 @@
       "default": "./src/index.ts"
     },
     "./src/*": "./src/*",
-    "./mini-app-global.css": "./assets/mini-app-global.css"
+    "./standalone-global.css": "./assets/standalone-global.css"
   },
   "files": [
     "assets",
@@ -76,6 +76,7 @@
   },
   "homepage": "https://github.com/Mir-Insight/uilib#readme",
   "dependencies": {
+    "@homecode/ui": "^4.17.0",
     "@phosphor-icons/react": "^2.1.10",
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-checkbox": "^1.3.3",
@@ -104,12 +105,23 @@
     "vaul": "^1.1.2"
   },
   "peerDependencies": {
-    "@homecode/ui": ">=4.17.0",
+    "@auth0/auth0-react": "^2.3.1",
+    "@sybilion/sdk": ">=0.0.1",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-router-dom": ">=6.0.0"
   },
+  "peerDependenciesMeta": {
+    "@auth0/auth0-react": {
+      "optional": true
+    },
+    "@sybilion/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@auth0/auth0-react": "^2.3.1",
+    "@sybilion/sdk": "file:../sdk",
     "@babel/core": "^7.20.12",
     "@babel/preset-typescript": "^7.21.0",
     "@homecode/ui": "^4.30.6",

package/src/components/ui/Image/Image.styl

@@ -3,6 +3,7 @@
   display inline-block
   width 100%
   height 100%
+  background-color var(--muted-50)
 
 .image
   display block

package/src/components/ui/NavUserHeader/NavUserHeader.styl

@@ -0,0 +1,125 @@
+.loadingButton
+  gap 0.5rem
+
+.avatarSkeleton
+  height 2rem
+  width 2rem
+  border-radius 9999px
+  background-color var(--color-muted)
+  animation pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite
+
+.textSkeleton
+  height 1rem
+  width 5rem
+  border-radius 0.25rem
+  background-color var(--color-muted)
+  animation pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite
+
+.loginButton
+  gap 0.5rem
+
+.iconLg
+  height 1.25rem
+  width 1.25rem
+
+.iconSm
+  height 0.75rem
+  width 0.75rem
+
+.menuIcon
+  margin-right 0.5rem
+  height 1rem
+  width 1rem
+
+.dropdownContent
+  width 14rem
+
+.userButton
+  gap 0.5rem
+  height 52px
+  padding var(--p-2)
+
+  &.compact
+    padding 0
+    background-color transparent !important
+    transition transform 0.2s ease-in-out
+
+    &:hover
+      transform scale(1.1)
+
+.avatar
+  height 2rem
+  width 2rem
+
+.avatarImage
+  width 100%
+  height 100%
+  object-fit cover
+  border-radius inherit
+
+.avatarFallback
+  background-color var(--color-primary)
+  color var(--color-primary-foreground)
+  background url('./avatar.svg') no-repeat center center
+  width 100%
+  height 100%
+  border-radius inherit
+
+.userInfo
+  display flex
+  flex-direction column
+  align-items flex-start
+  text-align left
+  gap 0.25rem
+
+.userName
+  font-size var(--text-sm)
+  font-weight 400
+  line-height 1
+  text-overflow ellipsis
+  overflow hidden
+  white-space nowrap
+  max-width 7.5rem
+
+.userEmail
+  font-size var(--text-xs)
+  color var(--sb-slate-500)
+  line-height 1
+
+.userLabel
+  padding 0
+  font-weight normal
+
+.userLabelContent
+  display flex
+  align-items center
+  gap 0.5rem
+  padding 0.5rem
+  text-align left
+  font-size 0.875rem
+
+.userDetails
+  display grid
+  flex 1
+  text-align left
+  font-size 0.875rem
+  line-height 1.25
+
+.userDetailName
+  text-overflow ellipsis
+  overflow hidden
+  white-space nowrap
+  font-weight 500
+
+.userDetailEmail
+  color var(--color-muted-foreground)
+  text-overflow ellipsis
+  overflow hidden
+  white-space nowrap
+  font-size 0.75rem
+
+@keyframes pulse
+  0%, 100%
+    opacity 1
+  50%
+    opacity 0.5

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

@@ -0,0 +1,28 @@
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'avatar': string;
+  'avatarFallback': string;
+  'avatarImage': string;
+  'avatarSkeleton': string;
+  'compact': string;
+  'dropdownContent': string;
+  'iconLg': string;
+  'iconSm': string;
+  'loadingButton': string;
+  'loginButton': string;
+  'menuIcon': string;
+  'pulse': string;
+  'textSkeleton': string;
+  'userButton': string;
+  'userDetailEmail': string;
+  'userDetailName': string;
+  'userDetails': string;
+  'userEmail': string;
+  'userInfo': string;
+  'userLabel': string;
+  'userLabelContent': string;
+  'userName': string;
+}
+export const cssExports: CssExports;
+export default cssExports;