@sybilion/uilib 1.2.3 → 1.2.5

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

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

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

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

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

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

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

@@ -0,0 +1,34 @@
+import type { WorkspaceAppEntry } from './workspaceApp.types';
+import { WORKSPACE_APP_SLUG_BASE_PATH } from './workspaceApp.types';
+
+export function workspaceAppSlugPath(id: string): string {
+  return `${WORKSPACE_APP_SLUG_BASE_PATH}/${id}`;
+}
+
+function pathnameMatchesPrefix(pathname: string, prefix: string): boolean {
+  return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+function pathnameMatchesSlugApp(pathname: string, id: string): boolean {
+  const base = workspaceAppSlugPath(id);
+  return pathname === base || pathname.startsWith(`${base}/`);
+}
+
+export function findWorkspaceAppByPathname(
+  pathname: string,
+  apps: readonly WorkspaceAppEntry[],
+): WorkspaceAppEntry | null {
+  for (const app of apps) {
+    const prefixes = app.matchPathPrefixes;
+    if (prefixes && prefixes.length > 0) {
+      if (prefixes.some(prefix => pathnameMatchesPrefix(pathname, prefix))) {
+        return app;
+      }
+      continue;
+    }
+    if (pathnameMatchesSlugApp(pathname, app.id)) {
+      return app;
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,2 @@
+/** localStorage key for workspace app list JSON (shared by host app + demos). */
+export const WORKSPACE_APPS_LS_KEY = 'sybilion.workspaceApps.v1';

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

@@ -0,0 +1,95 @@
+import type { WorkspaceAppEntry } from './workspaceApp.types';
+import { isWorkspaceAppIconKey } from './workspaceAppIcons';
+
+function parseEntry(raw: unknown): WorkspaceAppEntry | null {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const o = raw as Record<string, unknown>;
+  const idRaw = o.id ?? o.nativeId;
+  const displayName = o.displayName;
+  const subtitle = o.subtitle;
+  const iconKey = o.iconKey;
+  const accent = o.accent;
+  const accentMuted = o.accentMuted;
+  const href = o.href;
+  const prefixesRaw = o.matchPathPrefixes;
+
+  if (
+    typeof idRaw !== 'string' ||
+    !idRaw ||
+    typeof displayName !== 'string' ||
+    typeof subtitle !== 'string' ||
+    typeof iconKey !== 'string' ||
+    !isWorkspaceAppIconKey(iconKey) ||
+    typeof accent !== 'string' ||
+    typeof accentMuted !== 'string' ||
+    typeof href !== 'string' ||
+    !href
+  ) {
+    return null;
+  }
+
+  let matchPathPrefixes: WorkspaceAppEntry['matchPathPrefixes'];
+  if (prefixesRaw != null) {
+    if (!Array.isArray(prefixesRaw)) {
+      return null;
+    }
+    const prefixes = prefixesRaw.filter(
+      (p): p is string => typeof p === 'string',
+    );
+    if (prefixes.length > 0) {
+      matchPathPrefixes = prefixes;
+    }
+  }
+
+  return {
+    id: idRaw,
+    displayName,
+    subtitle,
+    iconKey,
+    accent,
+    accentMuted,
+    href,
+    matchPathPrefixes,
+  };
+}
+
+/**
+ * Read validated workspace apps JSON from localStorage; returns null if missing or invalid.
+ */
+export function readWorkspaceAppsFromLocalStorage(
+  key: string,
+): WorkspaceAppEntry[] | null {
+  try {
+    const raw = localStorage.getItem(key);
+    if (raw == null || raw === '') {
+      return null;
+    }
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+      return null;
+    }
+    const apps: WorkspaceAppEntry[] = [];
+    for (const item of parsed) {
+      const entry = parseEntry(item);
+      if (entry) {
+        apps.push(entry);
+      }
+    }
+    return apps.length > 0 ? apps : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeWorkspaceAppsToLocalStorage(
+  key: string,
+  apps: WorkspaceAppEntry[],
+): void {
+  try {
+    localStorage.setItem(key, JSON.stringify(apps));
+  } catch {
+    // ignore quota / private mode
+  }
+}

package/src/components/widgets/SybilionAppHeader/SybilionAppHeader.styl

@@ -0,0 +1,7 @@
+@import '../../../lib/theme.styl'
+
+.actionsAnchor
+  display flex
+  align-items center
+  gap var(--p-4)
+  flex-shrink 0

package/src/components/widgets/SybilionAppHeader/SybilionAppHeader.styl.d.ts

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

package/src/components/widgets/SybilionAppHeader/SybilionAppHeader.tsx

@@ -0,0 +1,51 @@
+import cn from 'classnames';
+
+import { AppHeaderPortal } from '#uilib/components/ui/AppHeader/AppHeader';
+import { PAGE_HEADER_ACTIONS_ID } from '#uilib/components/ui/AppHeader/appChromeAnchors';
+import { Gap } from '#uilib/components/ui/Gap/Gap';
+import { NavUserHeader } from '#uilib/components/ui/NavUserHeader';
+import type { NavUserHeaderProps } from '#uilib/components/ui/NavUserHeader';
+import {
+  WorkspaceAppSwitcher,
+  type WorkspaceAppSwitcherProps,
+} from '#uilib/components/ui/WorkspaceAppSwitcher';
+
+import S from './SybilionAppHeader.styl';
+
+export type SybilionAppHeaderProps = WorkspaceAppSwitcherProps &
+  NavUserHeaderProps & {
+    pageHeaderId?: string;
+    actionsAnchorId?: string;
+    actionsAnchorClassName?: string;
+  };
+
+export function SybilionAppHeader({
+  pageHeaderId,
+  actionsAnchorId = PAGE_HEADER_ACTIONS_ID,
+  actionsAnchorClassName,
+  pathname,
+  onNavigate,
+  authenticated,
+  defaultApps,
+  appsStorageKey,
+  ...navUserHeaderProps
+}: SybilionAppHeaderProps) {
+  return (
+    <AppHeaderPortal pageHeaderId={pageHeaderId}>
+      <WorkspaceAppSwitcher
+        pathname={pathname}
+        onNavigate={onNavigate}
+        authenticated={authenticated}
+        defaultApps={defaultApps}
+        appsStorageKey={appsStorageKey}
+      />
+      <Gap />
+      <div
+        id={actionsAnchorId}
+        className={cn(S.actionsAnchor, actionsAnchorClassName)}
+      >
+        <NavUserHeader {...navUserHeaderProps} />
+      </div>
+    </AppHeaderPortal>
+  );
+}

package/src/components/widgets/SybilionAppHeader/index.ts

@@ -0,0 +1,4 @@
+export {
+  SybilionAppHeader,
+  type SybilionAppHeaderProps,
+} from './SybilionAppHeader';

package/src/docs/pages/StandaloneAppLayoutPage.tsx

@@ -1,29 +1,31 @@
 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 { AppHeaderHost } from '#uilib/components/ui/AppHeader';
+import { DropdownMenuItem } from '#uilib/components/ui/DropdownMenu';
 import {
   AppShell,
   AppShellMainContent,
+  PageContent,
   PageContentSection,
+  PageHeader,
 } 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 type { WorkspaceAppEntry } from '#uilib/components/ui/WorkspaceAppSwitcher';
 import {
   SidebarDatasetsItemsGrouped,
   type SidebarDatasetsItemsGroupedDataset,
 } from '#uilib/components/widgets/SidebarDatasetsItemsGrouped';
+import { SybilionAppHeader } from '#uilib/components/widgets/SybilionAppHeader';
+import { GearSixIcon, UserCircleIcon } from '@phosphor-icons/react';
 import { House } from 'lucide-react';
 
 import { AppPageHeader } from '../components/AppPageHeader/AppPageHeader';
@@ -91,6 +93,40 @@ type PreviewPanel = 'home' | 'datasets';
 
 const TEST_HEADER_ID = 'test-header-id';
 
+const DOCS_WORKSPACE_APPS_LS_KEY = 'uilib.docs.workspaceApps';
+
+const DOCS_PREVIEW_APPS: WorkspaceAppEntry[] = [
+  {
+    id: 'docs-home',
+    displayName: 'Datasets Dashboard',
+    subtitle: 'Data analysis tools',
+    iconKey: 'grid-four',
+    accent: '#0d9488',
+    accentMuted: 'rgba(13, 148, 136, 0.12)',
+    href: '/docs-preview/home',
+    matchPathPrefixes: ['/docs-preview/home'],
+  },
+  {
+    id: 'docs-datasets',
+    displayName: 'Datasets',
+    subtitle: 'Dataset library',
+    iconKey: 'package',
+    accent: '#6366f1',
+    accentMuted: 'rgba(99, 102, 241, 0.12)',
+    href: '/docs-preview/datasets',
+    matchPathPrefixes: ['/docs-preview/datasets'],
+  },
+  {
+    id: 'my-custom-app',
+    displayName: 'Custom app',
+    subtitle: 'Slug-only app (sybilion.io/apps/…)',
+    iconKey: 'boat',
+    accent: '#0ea5e9',
+    accentMuted: 'rgba(14, 165, 233, 0.12)',
+    href: '/apps/my-custom-app',
+  },
+];
+
 function DemoAppSidebar({
   panel,
   onSelectPanel,
@@ -138,31 +174,49 @@ function DemoAppSidebar({
 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>
+      <>
+        <PageHeader
+          breadcrumbs={[{ label: 'Home' }]}
+          title="Home"
+          subheader="Greenfield shell preview (no SDK or auth in this embed)."
+        />
+        <PageContent>
+          <PageContentSection>
+            <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>
+          </PageContentSection>
+        </PageContent>
+      </>
     );
   }
 
   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>
+    <>
+      <PageHeader
+        breadcrumbs={[{ label: 'Datasets' }]}
+        title="Datasets"
+        subheader="Sidebar + dataset list use local state (not Router)."
+      />
+      <PageContent>
+        <PageContentSection>
+          <p style={{ margin: 0, color: 'var(--muted-foreground)' }}>
+            Use sidebar links and dataset rows; panel state stays inside this
+            box.
+          </p>
+        </PageContentSection>
+      </PageContent>
+    </>
   );
 }
 
 function StandaloneLayoutPreview() {
   const [theme, setTheme] = useState<'light' | 'dark'>('light');
   const [panel, setPanel] = useState<PreviewPanel>('home');
+  const [previewPath, setPreviewPath] = useState('/docs-preview/home');
   const [selectedDatasetId, setSelectedDatasetId] = useState<
     number | undefined
   >();
@@ -191,20 +245,34 @@ function StandaloneLayoutPreview() {
               />
             }
           >
-            <AppHeaderPortal pageHeaderId={TEST_HEADER_ID}>
-              <SidebarTrigger />
-              <Gap />
-              <NavUserHeader
-                user={{
-                  name: 'Preview User',
-                  email: 'preview@example.com',
-                  avatar: '',
-                }}
-                theme={theme}
-                onThemeToggle={onThemeToggle}
-                onLogout={() => undefined}
-              />
-            </AppHeaderPortal>
+            <SybilionAppHeader
+              pageHeaderId={TEST_HEADER_ID}
+              pathname={previewPath}
+              onNavigate={setPreviewPath}
+              authenticated
+              appsStorageKey={DOCS_WORKSPACE_APPS_LS_KEY}
+              defaultApps={DOCS_PREVIEW_APPS}
+              user={{
+                name: 'Preview User',
+                email: 'preview@example.com',
+                avatar: '',
+              }}
+              theme={theme}
+              onThemeToggle={onThemeToggle}
+              onLogout={() => undefined}
+              menuItems={
+                <>
+                  <DropdownMenuItem>
+                    <UserCircleIcon />
+                    Account (preview)
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <GearSixIcon />
+                    Settings (preview)
+                  </DropdownMenuItem>
+                </>
+              }
+            />
             <DemoMainBody panel={panel} />
           </AppShellMainContent>
         </AppShell>

package/src/index.ts

@@ -55,4 +55,6 @@ export * from './components/ui/Toggle';
 export * from './components/ui/ToggleGroup';
 export * from './components/ui/Tooltip';
 export * from './components/ui/VimeoEmbed';
+export * from './components/ui/WorkspaceAppSwitcher';
 export * from './components/widgets/SidebarDatasetsItemsGrouped';
+export * from './components/widgets/SybilionAppHeader';

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,
+  };
+}