@shellui/core 0.2.0-alpha.4 → 0.2.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-beta.1",
   "description": "ShellUI Core - Core React application runtime",
   "main": "src/index.ts",
   "type": "module",
@@ -58,7 +58,7 @@
     "workbox-strategies": "^7.1.0",
     "workbox-cacheable-response": "^7.1.0",
     "workbox-expiration": "^7.1.0",
-    "@shellui/sdk": "0.2.0-alpha.4"
+    "@shellui/sdk": "0.2.0-beta.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/app.tsx

@@ -3,7 +3,7 @@ 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 { createAppRouter } from './routes/router';
 import { SettingsProvider } from './features/settings/SettingsProvider';
 import { ThemeProvider } from './features/theme/ThemeProvider';
 import { I18nProvider } from './i18n/I18nProvider';
@@ -33,7 +33,7 @@ const AppContent = () => {
       unregisterServiceWorker();
       return;
     }
-    const serviceWorkerEnabled = settings?.serviceWorker?.enabled ?? true; // Default to enabled
+    const serviceWorkerEnabled = settings?.serviceWorker?.enabled ?? false; // Default to enabled
 
     // Don't register service worker if navigation is empty or undefined
     // This helps prevent issues in development or misconfigured apps

package/src/components/ContentView.tsx

@@ -1,5 +1,5 @@
-/* eslint-disable no-console */
 import type { NavigationItem } from '../features/config/types';
+import { isHashRouterNavItem, getHashPathFromUrl } from '../features/layouts/utils';
 import {
   addIframe,
   removeIframe,
@@ -10,6 +10,7 @@ import {
 } from '@shellui/sdk';
 import { useEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
+import { LOADING_OVERLAY_DURATION_MS } from '../constants/loading';
 import { LoadingOverlay } from './LoadingOverlay';
 
 const logger = getLogger('shellcore');
@@ -29,11 +30,21 @@ export const ContentView = ({
 }: ContentViewProps) => {
   const navigate = useNavigate();
   const iframeRef = useRef<HTMLIFrameElement>(null);
-  const isInternalNavigation = useRef(false);
   const cancelRevealRef = useRef<(() => void) | null>(null);
   const mountTimeRef = useRef(Date.now());
-  const [initialUrl] = useState(url);
-  const [isLoading, setIsLoading] = useState(true);
+  /** Real history methods; stored once so we never restore our no-ops after a second effect run. */
+  const historyOriginalsRef = useRef<{
+    pushState: History['pushState'];
+    replaceState: History['replaceState'];
+  } | null>(null);
+
+  const [isLoading, setIsLoading] = useState(() => {
+    // Skip overlay when same app URL was just loaded (e.g. switching App ↔ Root with same url)
+    if (!ignoreMessages) return false;
+    return true;
+  });
+
+  const [iframeUrl, setIframeUrl] = useState(url);
 
   const MIN_LOADING_MS = 80; // Don't reveal before this, reduces blink from theme/layout paint
 
@@ -47,6 +58,18 @@ export const ContentView = ({
     };
   }, []);
 
+  useEffect(() => {
+    if (ignoreMessages) return;
+    if (isLoading) return;
+    if (iframeRef.current) {
+      setIsLoading(true);
+      setIframeUrl('about:blank');
+      setTimeout(() => {
+        setIframeUrl(url);
+      }, 60);
+    }
+  }, [navItem]);
+
   // Sync parent URL when iframe notifies us of a change
   useEffect(() => {
     const cleanup = shellui.addMessageListener(
@@ -56,29 +79,52 @@ export const ContentView = ({
           return;
         }
 
+        if (isLoading) 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)
+        // Shell URL is always path + search only (no hash) so it's transparent whether the sub-app uses hash routing or not
+        let pathSegment: string;
+        if (isHashRouterNavItem(navItem) && hash) {
+          // Hash-router app: use path relative to nav item's hash (e.g. nav #/themes, iframe #/themes → segment ''; iframe #/themes/foo → segment 'foo')
+          const iframeHashPath = hash.replace(/^#\/?/, '').replace(/\/+$/, '') || '';
+          const navHashPath = getHashPathFromUrl(navItem.url).replace(/^\/+|\/+$/g, '');
+          const relative = navHashPath
+            ? iframeHashPath === navHashPath || iframeHashPath.startsWith(`${navHashPath}/`)
+              ? iframeHashPath.slice(navHashPath.length).replace(/^\//, '')
+              : iframeHashPath
+            : iframeHashPath;
+          pathSegment = relative;
+        } else {
+          // Non-hash app: route is pathname
+          let cleanPathname = pathname.startsWith(navItem.url)
+            ? pathname.slice(navItem.url.length)
+            : pathname;
+          cleanPathname = cleanPathname.startsWith('/') ? cleanPathname.slice(1) : cleanPathname;
+          pathSegment = cleanPathname.replace(/\/+$/, '');
+        }
+        // Root (pathPrefix '' or '/') must produce /segment not //segment
+        const isRoot = pathPrefix === '' || pathPrefix === '/';
+        let newShellPath = isRoot
+          ? pathSegment
+            ? `/${pathSegment}${search}`
+            : search
+              ? `/${search}`
+              : '/'
+          : pathSegment
+            ? `/${pathPrefix}/${pathSegment}${search}`
+            : `/${pathPrefix}${search}`;
+
+        // Normalize: remove trailing slashes from pathname part only (preserve query)
         const urlParts = newShellPath.match(/^([^?#]*)([?#].*)?$/);
         if (urlParts) {
           const pathnamePart = urlParts[1].replace(/\/+$/, '') || '/';
-          const queryHashPart = urlParts[2] || '';
-          newShellPath = pathnamePart + queryHashPart;
+          const queryPart = urlParts[2] || '';
+          newShellPath = pathnamePart + queryPart;
         }
 
         // Normalize current path for comparison (remove trailing slashes from pathname)
@@ -91,14 +137,7 @@ export const ContentView = ({
         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);
         }
       },
     );
@@ -106,7 +145,7 @@ export const ContentView = ({
     return () => {
       cleanup();
     };
-  }, [pathPrefix, navigate]);
+  }, [pathPrefix, navigate, navItem]);
 
   const scheduleReveal = (reveal: () => void) => {
     const doReveal = () => {
@@ -126,6 +165,7 @@ export const ContentView = ({
 
   // Hide loading overlay when iframe sends SHELLUI_INITIALIZED.
   // Defer reveal (double rAF + min time) so the iframe has time to apply theme and paint.
+  // Remember this URL so we can skip the overlay when navigating to the same app (e.g. App ↔ Root).
   useEffect(() => {
     const cleanup = shellui.addMessageListener(
       'SHELLUI_INITIALIZED',
@@ -148,9 +188,9 @@ export const ContentView = ({
       cancelRevealRef.current = null;
       cleanup();
     };
-  }, []);
+  }, [ignoreMessages]);
 
-  // Fallback: hide overlay after 400ms if SHELLUI_INITIALIZED was not received.
+  // Fallback: hide overlay after LOADING_OVERLAY_DURATION_MS if SHELLUI_INITIALIZED was not received.
   useEffect(() => {
     if (!isLoading) return;
     const timeoutId = setTimeout(() => {
@@ -165,115 +205,10 @@ export const ContentView = ({
         if (!cancelled) setIsLoading(false);
         cancelRevealRef.current = null;
       });
-    }, 400);
+    }, LOADING_OVERLAY_DURATION_MS);
     return () => clearTimeout(timeoutId);
   }, [isLoading]);
 
-  // Handle external URL changes (e.g. from Sidebar)
-  useEffect(() => {
-    if (iframeRef.current && !isInternalNavigation.current) {
-      if (iframeRef.current.src !== url) {
-        iframeRef.current.src = url;
-        setIsLoading(true);
-        mountTimeRef.current = Date.now(); // apply min delay for this load too
-      }
-    }
-  }, [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' }}
@@ -289,7 +224,7 @@ export const ContentView = ({
           - Reveal is instant (no transition) after deferred double-rAF to avoid blink */}
       <iframe
         ref={iframeRef}
-        src={initialUrl}
+        src={iframeUrl}
         loading="eager"
         style={{
           width: '100%',

package/src/components/LoadingOverlay.tsx

@@ -1,10 +1,14 @@
+import { LOADING_OVERLAY_DURATION_MS } from '../constants/loading';
+
 export function LoadingOverlay() {
   return (
     <div className="absolute inset-x-0 top-0 z-10">
       <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' }}
+          style={{
+            animation: `loading-bar-slide ${LOADING_OVERLAY_DURATION_MS}ms linear infinite`,
+          }}
         />
       </div>
     </div>

package/src/components/ui/sidebar.tsx

@@ -1,10 +1,5 @@
 import {
-  createContext,
-  useContext,
-  useState,
-  useCallback,
   forwardRef,
-  type ReactNode,
   type HTMLAttributes,
   type ButtonHTMLAttributes,
   type AnchorHTMLAttributes,
@@ -12,47 +7,16 @@ import {
 import { Slot } from '@radix-ui/react-slot';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../lib/utils';
-import { Z_INDEX } from '../../lib/z-index';
-
-type SidebarContextValue = {
-  isCollapsed: boolean;
-  toggle: () => void;
-};
-
-const SidebarContext = createContext<SidebarContextValue | undefined>(undefined);
-
-const useSidebar = () => {
-  const context = useContext(SidebarContext);
-  if (!context) {
-    throw new Error('useSidebar must be used within a SidebarProvider');
-  }
-  return context;
-};
-
-const SidebarProvider = ({ children }: { children: ReactNode }) => {
-  const [isCollapsed, setIsCollapsed] = useState(false);
-
-  const toggle = useCallback(() => {
-    setIsCollapsed((prev) => !prev);
-  }, []);
-
-  return (
-    <SidebarContext.Provider value={{ isCollapsed, toggle }}>{children}</SidebarContext.Provider>
-  );
-};
 
 const Sidebar = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
   ({ className, ...props }, ref) => {
-    const { isCollapsed } = useSidebar();
-
     return (
       <div
         ref={ref}
         data-sidebar="sidebar"
-        data-collapsed={isCollapsed}
         className={cn(
           'flex h-full flex-col gap-2 border-r bg-sidebar-background p-2 text-sidebar-foreground transition-all duration-300 ease-in-out overflow-hidden',
-          isCollapsed ? 'w-0 border-r-0 p-0' : 'w-64',
+          'w-64',
           className,
         )}
         {...props}
@@ -62,83 +26,6 @@ const Sidebar = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
 );
 Sidebar.displayName = 'Sidebar';
 
-/** Inline SVG: panel-left-open (expand sidebar) */
-const PanelLeftOpenIcon = () => (
-  <svg
-    xmlns="http://www.w3.org/2000/svg"
-    width="24"
-    height="24"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="2"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-    className="h-5 w-5 transition-transform duration-300"
-    aria-hidden
-  >
-    <rect
-      width="18"
-      height="18"
-      x="3"
-      y="3"
-      rx="2"
-    />
-    <path d="M9 3v18" />
-    <path d="m14 9 3 3-3 3" />
-  </svg>
-);
-
-/** Inline SVG: panel-left-close (collapse sidebar) */
-const PanelLeftCloseIcon = () => (
-  <svg
-    xmlns="http://www.w3.org/2000/svg"
-    width="24"
-    height="24"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="2"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-    className="h-5 w-5 transition-transform duration-300"
-    aria-hidden
-  >
-    <rect
-      width="18"
-      height="18"
-      x="3"
-      y="3"
-      rx="2"
-    />
-    <path d="M9 3v18" />
-    <path d="m16 15-3-3 3-3" />
-  </svg>
-);
-
-const SidebarTrigger = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
-  ({ className, ...props }, ref) => {
-    const { toggle, isCollapsed } = useSidebar();
-
-    return (
-      <button
-        ref={ref}
-        onClick={toggle}
-        className={cn(
-          'relative flex items-center justify-center rounded-md p-2 text-foreground transition-colors hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring shadow-lg backdrop-blur-md cursor-pointer bg-background/95 border border-border',
-          className,
-        )}
-        aria-label={isCollapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-        style={{ zIndex: Z_INDEX.SIDEBAR_TRIGGER }}
-        {...props}
-      >
-        {isCollapsed ? <PanelLeftOpenIcon /> : <PanelLeftCloseIcon />}
-      </button>
-    );
-  },
-);
-SidebarTrigger.displayName = 'SidebarTrigger';
-
 const SidebarHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
   ({ className, ...props }, ref) => {
     return (
@@ -271,19 +158,13 @@ const SidebarMenuButton = forwardRef<
       isActive?: boolean;
     }
 >(({ className, variant, size, asChild = false, isActive, children, ...props }, ref) => {
-  const { isCollapsed } = useSidebar();
   const Comp = asChild ? Slot : 'button';
 
   return (
     <Comp
       ref={ref}
       data-active={isActive}
-      data-collapsed={isCollapsed}
-      className={cn(
-        sidebarMenuButtonVariants({ variant, size }),
-        isCollapsed && 'justify-center',
-        className,
-      )}
+      className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
       {...props}
     >
       {children}
@@ -434,8 +315,6 @@ SidebarMenuSubItem.displayName = 'SidebarMenuSubItem';
 
 export {
   Sidebar,
-  SidebarProvider,
-  SidebarTrigger,
   SidebarHeader,
   SidebarContent,
   SidebarFooter,
@@ -452,5 +331,4 @@ export {
   SidebarMenuSub,
   SidebarMenuSubButton,
   SidebarMenuSubItem,
-  useSidebar,
 };

package/src/constants/loading.ts

@@ -0,0 +1,2 @@
+/** Duration (ms) for loading overlay: fallback timeout and bar animation. */
+export const LOADING_OVERLAY_DURATION_MS = 1000;

package/src/features/config/types.ts

@@ -26,6 +26,8 @@ export interface NavigationItem {
   hiddenOnDesktop?: boolean;
   /** How to open this link: 'default' (navigate in main area), 'modal', 'drawer', or 'external' (target="_blank"). */
   openIn?: 'default' | 'modal' | 'drawer' | 'external';
+  /** When true, the app uses hash-based routing (e.g. /#/path). If omitted, inferred from url containing /#/. */
+  useHashRouter?: boolean;
   /** Optional drawer position when openIn === 'drawer'. Default is 'right' if omitted. */
   drawerPosition?: DrawerPosition;
   /** Sidebar position: 'start' (default) or 'end'. End items are rendered in the sidebar footer. */

package/src/features/layouts/AppLayout.tsx

@@ -1,18 +1,23 @@
 import { lazy, Suspense, type LazyExoticComponent, type ComponentType } from 'react';
 import type { LayoutType, NavigationItem, NavigationGroup } from '../config/types';
 import { useSettings } from '../settings/SettingsContext';
+import { SonnerProvider } from '../sonner/SonnerContext';
+import { ModalProvider } from '../modal/ModalContext';
+import { DrawerProvider } from '../drawer/DrawerContext';
+import { OverlayShell } from './OverlayShell';
+import { LayoutFallback } from './LayoutFallback';
 
-const DefaultLayout = lazy(() =>
-  import('./DefaultLayout').then((m) => ({ default: m.DefaultLayout })),
+const SidebarLayout = lazy(() =>
+  import('./sidebar/SidebarLayout').then((m) => ({ default: m.SidebarLayout })),
 );
 const FullscreenLayout = lazy(() =>
-  import('./FullscreenLayout').then((m) => ({ default: m.FullscreenLayout })),
+  import('./fullscreen/FullscreenLayout').then((m) => ({ default: m.FullscreenLayout })),
 );
 const WindowsLayout = lazy(() =>
-  import('./WindowsLayout').then((m) => ({ default: m.WindowsLayout })),
+  import('./windows/WindowsLayout').then((m) => ({ default: m.WindowsLayout })),
 );
 const AppBarLayout = lazy(() =>
-  import('./AppBarLayout').then((m) => ({ default: m.AppBarLayout })),
+  import('./appbar/AppBarLayout').then((m) => ({ default: m.AppBarLayout })),
 );
 
 interface AppLayoutProps {
@@ -23,15 +28,6 @@ interface AppLayoutProps {
   navigation: (NavigationItem | NavigationGroup)[];
 }
 
-function LayoutFallback() {
-  return (
-    <div
-      className="min-h-screen bg-background"
-      aria-hidden
-    />
-  );
-}
-
 /** Renders the layout based on settings.layout (override) or config.layout: 'sidebar' (default), 'fullscreen', or 'windows'. Lazy-loads only the active layout. */
 export function AppLayout({
   layout = 'sidebar',
@@ -57,13 +53,20 @@ export function AppLayout({
     LayoutComponent = AppBarLayout;
     layoutProps = { title, appIcon, logo, navigation };
   } else {
-    LayoutComponent = DefaultLayout;
+    LayoutComponent = SidebarLayout;
     layoutProps = { title, appIcon, logo, navigation };
   }
-
   return (
-    <Suspense fallback={<LayoutFallback />}>
-      <LayoutComponent {...layoutProps} />
-    </Suspense>
+    <ModalProvider>
+      <DrawerProvider>
+        <SonnerProvider>
+          <OverlayShell>
+            <Suspense fallback={<LayoutFallback />}>
+              <LayoutComponent {...layoutProps} />
+            </Suspense>
+          </OverlayShell>
+        </SonnerProvider>
+      </DrawerProvider>
+    </ModalProvider>
   );
 }

package/src/features/layouts/LayoutFallback.tsx

@@ -0,0 +1,8 @@
+export function LayoutFallback() {
+  return (
+    <div
+      className="min-h-screen bg-background"
+      aria-hidden
+    />
+  );
+}