@shellui/core 0.0.4

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@shellui/core",
+  "version": "0.0.4",
+  "description": "ShellUI Core - Core React application runtime",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./constants/urls": {
+      "types": "./dist/constants/urls.d.ts",
+      "import": "./dist/constants/urls.js",
+      "default": "./dist/constants/urls.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "postcss.config.js",
+    "tailwind.config.js",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "shellui",
+    "core",
+    "react",
+    "microfrontend"
+  ],
+  "author": "ShellUI",
+  "license": "MIT",
+  "dependencies": {
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@sentry/react": "^8.0.0",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "i18next": "^23.15.0",
+    "react-i18next": "^15.1.0",
+    "react-router": "^7.12.0",
+    "roarr": "^7.21.2",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.4.0",
+    "vaul": "^1.1.2",
+    "workbox-window": "^7.1.0",
+    "workbox-precaching": "^7.1.0",
+    "workbox-routing": "^7.1.0",
+    "workbox-strategies": "^7.1.0",
+    "workbox-cacheable-response": "^7.1.0",
+    "workbox-expiration": "^7.1.0",
+    "@shellui/sdk": "0.0.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@tailwindcss/typography": "^0.5.19",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "autoprefixer": "^10.4.23",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.0.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "rm -rf dist",
+    "test": "echo \"No tests specified for @shellui/core\""
+  }
+}

package/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+    autoprefixer: {},
+  },
+};

package/src/app.tsx

@@ -0,0 +1,119 @@
+import { useMemo, useLayoutEffect, useState, useEffect } from 'react';
+import { RouterProvider } from 'react-router';
+import { shellui } from '@shellui/sdk';
+import { useConfig } from './features/config/useConfig';
+import { ConfigProvider } from './features/config/ConfigProvider';
+import { createAppRouter } from './router/router';
+import { SettingsProvider } from './features/settings/SettingsProvider';
+import { ThemeProvider } from './features/theme/ThemeProvider';
+import { I18nProvider } from './i18n/I18nProvider';
+import { DialogProvider } from './features/alertDialog/DialogContext';
+import { CookieConsentModal } from './features/cookieConsent/CookieConsentModal';
+import './features/sentry/initSentry';
+import './i18n/config'; // Initialize i18n
+import './index.css';
+import { registerServiceWorker, unregisterServiceWorker, isTauri } from './service-worker/register';
+import { useSettings } from './features/settings/hooks/useSettings';
+
+const AppContent = () => {
+  const { config } = useConfig();
+  const { settings } = useSettings();
+
+  // Apply favicon from config when available (allows projects to override default)
+  useEffect(() => {
+    if (config?.favicon) {
+      const link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
+      if (link) link.href = config.favicon;
+    }
+  }, [config?.favicon]);
+
+  // Register or unregister service worker based on setting
+  useEffect(() => {
+    if (isTauri()) {
+      unregisterServiceWorker();
+      return;
+    }
+    const serviceWorkerEnabled = settings?.serviceWorker?.enabled ?? true; // Default to enabled
+
+    // Don't register service worker if navigation is empty or undefined
+    // This helps prevent issues in development or misconfigured apps
+    if (!config?.navigation || config.navigation.length === 0) {
+      if (serviceWorkerEnabled) {
+        // eslint-disable-next-line no-console
+        console.warn('[Service Worker] Disabled: No navigation items configured');
+        unregisterServiceWorker();
+      }
+      return;
+    }
+
+    if (serviceWorkerEnabled) {
+      registerServiceWorker({
+        enabled: true,
+      });
+    } else {
+      unregisterServiceWorker();
+    }
+  }, [settings?.serviceWorker?.enabled, config?.navigation]);
+
+  // Create router from config using data mode
+  const router = useMemo(() => {
+    if (!config) {
+      return null;
+    }
+    return createAppRouter(config);
+  }, [config]);
+
+  // If no navigation, show simple layout
+  if (!config.navigation || config.navigation.length === 0) {
+    return (
+      <>
+        <CookieConsentModal />
+        <div style={{ fontFamily: 'system-ui, sans-serif', padding: '2rem' }}>
+          <h1>{config.title || 'ShellUI'}</h1>
+          <p>No navigation items configured.</p>
+        </div>
+      </>
+    );
+  }
+
+  if (!router) {
+    return null;
+  }
+
+  return (
+    <>
+      <CookieConsentModal />
+      <RouterProvider router={router} />
+    </>
+  );
+};
+
+const App = () => {
+  const [isLoading, setIsLoading] = useState(true);
+  // Initialize ShellUI SDK to support recursive nesting
+  useLayoutEffect(() => {
+    shellui.init().then(() => {
+      setIsLoading(false);
+    });
+  }, []);
+
+  if (isLoading) {
+    return null;
+  }
+
+  return (
+    <ConfigProvider>
+      <SettingsProvider>
+        <ThemeProvider>
+          <I18nProvider>
+            <DialogProvider>
+              <AppContent />
+            </DialogProvider>
+          </I18nProvider>
+        </ThemeProvider>
+      </SettingsProvider>
+    </ConfigProvider>
+  );
+};
+
+export default App;

package/src/components/ContentView.tsx

@@ -0,0 +1,258 @@
+/* eslint-disable no-console */
+import type { NavigationItem } from '@/features/config/types';
+import {
+  addIframe,
+  removeIframe,
+  shellui,
+  getLogger,
+  type ShellUIUrlPayload,
+  type ShellUIMessage,
+} from '@shellui/sdk';
+import { useEffect, useRef, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { LoadingOverlay } from './LoadingOverlay';
+
+const logger = getLogger('shellcore');
+
+interface ContentViewProps {
+  url: string;
+  pathPrefix: string;
+  ignoreMessages?: boolean;
+  navItem: NavigationItem;
+}
+
+export const ContentView = ({
+  url,
+  pathPrefix,
+  ignoreMessages = false,
+  navItem,
+}: ContentViewProps) => {
+  const navigate = useNavigate();
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const isInternalNavigation = useRef(false);
+  const [initialUrl] = useState(url);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    if (!iframeRef.current) {
+      return;
+    }
+    const iframeId = addIframe(iframeRef.current);
+    return () => {
+      removeIframe(iframeId);
+    };
+  }, []);
+
+  // Sync parent URL when iframe notifies us of a change
+  useEffect(() => {
+    const cleanup = shellui.addMessageListener(
+      'SHELLUI_URL_CHANGED',
+      (data: ShellUIMessage, event: MessageEvent) => {
+        if (ignoreMessages) {
+          return;
+        }
+
+        // Ignore URL CHANGE from other than ContentView iframe
+        if (event.source !== iframeRef.current?.contentWindow) {
+          return;
+        }
+
+        const { pathname, search, hash } = data.payload as ShellUIUrlPayload;
+        // Remove leading slash and trailing slashes from iframe pathname
+        let cleanPathname = pathname.startsWith(navItem.url)
+          ? pathname.slice(navItem.url.length)
+          : pathname;
+        cleanPathname = cleanPathname.startsWith('/') ? cleanPathname.slice(1) : cleanPathname;
+        cleanPathname = cleanPathname.replace(/\/+$/, ''); // Remove trailing slashes
+        // Construct the new path without trailing slashes
+        let newShellPath = cleanPathname
+          ? `/${pathPrefix}/${cleanPathname}${search}${hash}`
+          : `/${pathPrefix}${search}${hash}`;
+
+        // Normalize: remove trailing slashes from pathname part only (preserve query/hash)
+        const urlParts = newShellPath.match(/^([^?#]*)([?#].*)?$/);
+        if (urlParts) {
+          const pathnamePart = urlParts[1].replace(/\/+$/, '') || '/';
+          const queryHashPart = urlParts[2] || '';
+          newShellPath = pathnamePart + queryHashPart;
+        }
+
+        // Normalize current path for comparison (remove trailing slashes from pathname)
+        const currentPathname = window.location.pathname.replace(/\/+$/, '') || '/';
+        const currentPath = currentPathname + window.location.search + window.location.hash;
+
+        // Normalize new path for comparison
+        const newPathParts = newShellPath.match(/^([^?#]*)([?#].*)?$/);
+        const normalizedNewPathname = newPathParts?.[1]?.replace(/\/+$/, '') || '/';
+        const normalizedNewPath = normalizedNewPathname + (newPathParts?.[2] || '');
+
+        if (currentPath !== normalizedNewPath) {
+          // Mark this navigation as internal so we don't try to "push" it back to the iframe
+          isInternalNavigation.current = true;
+          navigate(newShellPath, { replace: true });
+
+          // Reset the flag after a short delay to allow the render cycle to complete
+          setTimeout(() => {
+            isInternalNavigation.current = false;
+          }, 100);
+        }
+      },
+    );
+
+    return () => {
+      cleanup();
+    };
+  }, [pathPrefix, navigate]);
+
+  // Hide loading overlay when iframe sends SHELLUI_INITIALIZED
+  useEffect(() => {
+    const cleanup = shellui.addMessageListener(
+      'SHELLUI_INITIALIZED',
+      (_data: ShellUIMessage, event: MessageEvent) => {
+        if (event.source === iframeRef.current?.contentWindow) {
+          setIsLoading(false);
+        }
+      },
+    );
+    return () => cleanup();
+  }, []);
+
+  // Fallback: hide overlay after 400ms if SHELLUI_INITIALIZED was not received
+  useEffect(() => {
+    if (!isLoading) return;
+    const timeoutId = setTimeout(() => {
+      logger.info('ContentView: Timeout expired, hiding loading overlay');
+      setIsLoading(false);
+    }, 400);
+    return () => clearTimeout(timeoutId);
+  }, [isLoading]);
+
+  // Handle external URL changes (e.g. from Sidebar)
+  useEffect(() => {
+    if (iframeRef.current && !isInternalNavigation.current) {
+      // Only update iframe src if it's actually different from its current src
+      // to avoid unnecessary reloads
+      if (iframeRef.current.src !== url) {
+        iframeRef.current.src = url;
+        setIsLoading(true);
+      }
+    }
+  }, [url]);
+
+  // Inject script to prevent "Layout was forced" warning by deferring layout until stylesheets load
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+
+    const handleLoad = () => {
+      try {
+        const iframeWindow = iframe.contentWindow;
+        const iframeDoc = iframe.contentDocument || iframeWindow?.document;
+        if (!iframeDoc || !iframeWindow) return;
+
+        // Inject a script that waits for stylesheets before allowing layout calculations
+        const script = iframeDoc.createElement('script');
+        script.textContent = `
+          (function() {
+            // Wait for all stylesheets to load
+            function waitForStylesheets() {
+              const styleSheets = Array.from(document.styleSheets);
+              const pendingSheets = styleSheets.filter(function(sheet) {
+                try {
+                  return sheet.cssRules === null;
+                } catch (e) {
+                  return false; // Cross-origin stylesheets, assume loaded
+                }
+              });
+              
+              if (pendingSheets.length === 0) {
+                // All stylesheets loaded
+                return;
+              }
+              
+              // Check again after a short delay
+              setTimeout(waitForStylesheets, 10);
+            }
+            
+            // Start checking after DOM is ready
+            if (document.readyState === 'complete') {
+              waitForStylesheets();
+            } else {
+              window.addEventListener('load', waitForStylesheets);
+            }
+          })();
+        `;
+        iframeDoc.head.appendChild(script);
+      } catch (error) {
+        // Cross-origin or other errors - ignore (this is expected for some iframes)
+        logger.debug('Could not inject stylesheet wait script:', { error });
+      }
+    };
+
+    // Wait for iframe to load before injecting script
+    iframe.addEventListener('load', handleLoad);
+
+    // Also try immediately if already loaded
+    if (iframe.contentDocument?.readyState === 'complete') {
+      handleLoad();
+    }
+
+    return () => {
+      iframe.removeEventListener('load', handleLoad);
+    };
+  }, [initialUrl]);
+
+  // Suppress browser warnings that are expected and acceptable
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      const originalWarn = console.warn;
+      console.warn = (...args: unknown[]) => {
+        const message = String(args[0] ?? '');
+        // Suppress the specific sandbox warning
+        if (
+          message.includes('allow-scripts') &&
+          message.includes('allow-same-origin') &&
+          message.includes('sandbox')
+        ) {
+          return;
+        }
+        // Suppress "Layout was forced" warning from iframe content
+        // This is a performance warning that occurs when iframe content calculates layout before stylesheets load
+        // It's harmless and common in iframe scenarios, especially with React apps
+        if (
+          message.includes('Layout was forced') &&
+          message.includes('before the page was fully loaded')
+        ) {
+          return;
+        }
+        originalWarn.apply(console, args);
+      };
+      return () => {
+        console.warn = originalWarn;
+      };
+    }
+  }, []);
+
+  return (
+    <div style={{ width: '100%', height: '100%', display: 'flex', position: 'relative' }}>
+      {/* Note: allow-same-origin is required for same-origin iframe content (e.g., Vite dev server, cookies, localStorage).
+          While this allows the iframe to remove its own sandboxing, it's acceptable here because the iframe content
+          is trusted microfrontend content from the same application origin.
+          Browser security warnings about this combination cannot be suppressed programmatically. */}
+      <iframe
+        ref={iframeRef}
+        src={initialUrl}
+        style={{
+          width: '100%',
+          height: '100%',
+          border: 'none',
+          display: 'block',
+        }}
+        title="Content Frame"
+        sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
+        referrerPolicy="no-referrer-when-downgrade"
+      />
+      {isLoading && <LoadingOverlay />}
+    </div>
+  );
+};

package/src/components/HomeView.tsx

@@ -0,0 +1,19 @@
+import { useTranslation } from 'react-i18next';
+import { useConfig } from '../features/config/useConfig';
+
+export const HomeView = () => {
+  const { t } = useTranslation('common');
+  const { config } = useConfig();
+
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8 md:p-10">
+      <h1
+        className="m-0 text-3xl font-light text-foreground"
+        style={{ fontFamily: 'var(--heading-font-family, inherit)' }}
+      >
+        {t('welcome', { title: config.title })}
+      </h1>
+      <p className="mt-4 text-lg text-muted-foreground">{t('getStarted')}</p>
+    </div>
+  );
+};

package/src/components/LoadingOverlay.tsx

@@ -0,0 +1,12 @@
+export function LoadingOverlay() {
+  return (
+    <div className="absolute inset-0 z-10 flex flex-col bg-background">
+      <div className="h-1 w-full overflow-hidden bg-muted/30">
+        <div
+          className="h-full w-0 bg-muted-foreground/50"
+          style={{ animation: 'loading-bar-slide 400ms linear infinite' }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/NotFoundView.tsx

@@ -0,0 +1,84 @@
+import { useTranslation } from 'react-i18next';
+import { shellui } from '@shellui/sdk';
+import { useConfig } from '@/features/config/useConfig';
+import type { NavigationItem, NavigationGroup } from '@/features/config/types';
+
+const flattenNavigationItems = (
+  navigation: (NavigationItem | NavigationGroup)[],
+): NavigationItem[] => {
+  if (navigation.length === 0) return [];
+  return navigation.flatMap((item) => {
+    if ('title' in item && 'items' in item) {
+      return (item as NavigationGroup).items;
+    }
+    return item as NavigationItem;
+  });
+};
+
+export const NotFoundView = () => {
+  const { config } = useConfig();
+  const { i18n } = useTranslation();
+  const currentLanguage = i18n.language || 'en';
+
+  const resolveLocalizedString = (
+    value: string | { en: string; fr: string; [key: string]: string },
+    lang: string,
+  ): string => {
+    if (typeof value === 'string') return value;
+    return value[lang] || value.en || value.fr || Object.values(value)[0] || '';
+  };
+
+  const navItems =
+    config?.navigation && config.navigation.length > 0
+      ? flattenNavigationItems(config.navigation)
+          .filter((item) => !item.hidden)
+          .filter((item, index, self) => index === self.findIndex((i) => i.path === item.path))
+      : [];
+
+  const handleNavigate = (path: string) => {
+    shellui.navigate(path.startsWith('/') ? path : `/${path}`);
+  };
+
+  return (
+    <div className="flex flex-col min-h-full">
+      <div className="flex-1 flex flex-col items-center justify-center px-6 py-12 text-muted-foreground">
+        <span className="text-6xl font-light tracking-tighter text-foreground/80 select-none">
+          404
+        </span>
+        <p className="mt-3 text-lg text-muted-foreground">Page not found</p>
+      </div>
+
+      {navItems.length > 0 && (
+        <footer className="border-t border-border py-4 px-6 mt-auto bg-muted/30">
+          <nav
+            className="flex flex-row flex-wrap justify-center items-center gap-x-2 gap-y-1 text-sm text-muted-foreground"
+            aria-label="Available pages"
+          >
+            {navItems.map((item, index) => (
+              <span
+                key={item.path}
+                className="inline-flex items-center gap-x-2"
+              >
+                {index > 0 && (
+                  <span
+                    className="text-border select-none"
+                    aria-hidden
+                  >
+                    ·
+                  </span>
+                )}
+                <button
+                  type="button"
+                  onClick={() => handleNavigate(`/${item.path}`)}
+                  className="text-muted-foreground hover:text-foreground hover:underline underline-offset-2 cursor-pointer bg-transparent border-0 p-0 font-normal"
+                >
+                  {resolveLocalizedString(item.label, currentLanguage)}
+                </button>
+              </span>
+            ))}
+          </nav>
+        </footer>
+      )}
+    </div>
+  );
+};

package/src/components/RouteErrorBoundary.tsx

@@ -0,0 +1,95 @@
+import { useRouteError, isRouteErrorResponse } from 'react-router';
+import { useTranslation } from 'react-i18next';
+import { shellui } from '@shellui/sdk';
+import { Button } from '@/components/ui/button';
+
+function isChunkLoadError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return (
+      msg.includes('loading dynamically imported module') ||
+      msg.includes('chunk') ||
+      msg.includes('failed to fetch dynamically imported module')
+    );
+  }
+  return false;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (isRouteErrorResponse(error)) {
+    return error.data?.message ?? error.statusText ?? 'Something went wrong';
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function getErrorStack(error: unknown): string | null {
+  if (error instanceof Error && error.stack) {
+    return error.stack;
+  }
+  return null;
+}
+
+function getErrorDetailsText(error: unknown): string {
+  const message = getErrorMessage(error);
+  const stack = getErrorStack(error);
+  if (stack) {
+    return `Message:\n${message}\n\nStack:\n${stack}`;
+  }
+  return message;
+}
+
+export function RouteErrorBoundary() {
+  const error = useRouteError();
+  const { t } = useTranslation('common');
+  const isChunkError = isChunkLoadError(error);
+  const detailsText = getErrorDetailsText(error);
+
+  return (
+    <div
+      className="flex min-h-screen flex-col items-center justify-center bg-background px-4 py-12"
+      style={{ fontFamily: 'var(--heading-font-family, system-ui, sans-serif)' }}
+    >
+      <div className="w-full max-w-md space-y-6 text-center">
+        <div className="space-y-2">
+          <h1 className="text-xl font-semibold text-foreground">
+            {isChunkError ? t('errorBoundary.titleChunk') : t('errorBoundary.titleGeneric')}
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            {isChunkError
+              ? t('errorBoundary.descriptionChunk')
+              : t('errorBoundary.descriptionGeneric')}
+          </p>
+        </div>
+
+        <div className="flex flex-col gap-3 sm:flex-row sm:justify-center">
+          <Button
+            variant="default"
+            onClick={() => window.location.reload()}
+            className="shrink-0"
+          >
+            {t('errorBoundary.tryAgain')}
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => shellui.navigate('/')}
+            className="shrink-0"
+          >
+            {t('errorBoundary.goToHome')}
+          </Button>
+        </div>
+
+        <details className="rounded-lg border border-border bg-muted/30 text-left">
+          <summary className="cursor-pointer px-4 py-3 text-xs font-medium text-muted-foreground hover:text-foreground">
+            {t('errorBoundary.errorDetails')}
+          </summary>
+          <pre className="max-h-64 overflow-auto whitespace-pre-wrap break-all px-4 pb-3 pt-1 text-xs text-muted-foreground font-mono">
+            {detailsText}
+          </pre>
+        </details>
+      </div>
+    </div>
+  );
+}