@shellui/core 0.2.0-beta.0 → 0.2.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shellui/core",
-  "version": "0.2.0-beta.0",
+  "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-beta.0"
+    "@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';

package/src/components/ContentView.tsx

@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 import type { NavigationItem } from '../features/config/types';
 import { isHashRouterNavItem, getHashPathFromUrl } from '../features/layouts/utils';
 import {
@@ -11,14 +10,11 @@ import {
 } from '@shellui/sdk';
 import { useEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
-import { LOADING_OVERLAY_DURATION_MS } from '../constants';
+import { LOADING_OVERLAY_DURATION_MS } from '../constants/loading';
 import { LoadingOverlay } from './LoadingOverlay';
 
 const logger = getLogger('shellcore');
 
-/** URL of the last main-content iframe that sent SHELLUI_INITIALIZED. Used to skip the loading overlay when navigating between nav items that point to the same app URL. */
-let lastLoadedIframeUrl: string | null = null;
-
 interface ContentViewProps {
   url: string;
   pathPrefix: string;
@@ -36,15 +32,20 @@ export const ContentView = ({
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const cancelRevealRef = useRef<(() => void) | null>(null);
   const mountTimeRef = useRef(Date.now());
-  const urlRef = useRef(url);
-  urlRef.current = url;
-  const [initialUrl] = useState(url);
+  /** 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 && url === lastLoadedIframeUrl) return false;
+    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
 
   useEffect(() => {
@@ -57,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(
@@ -66,6 +79,8 @@ export const ContentView = ({
           return;
         }
 
+        if (isLoading) return;
+
         // Ignore URL CHANGE from other than ContentView iframe
         if (event.source !== iframeRef.current?.contentWindow) {
           return;
@@ -122,7 +137,7 @@ export const ContentView = ({
         const normalizedNewPath = normalizedNewPathname + (newPathParts?.[2] || '');
 
         if (currentPath !== normalizedNewPath) {
-          navigate(newShellPath);
+          navigate(newShellPath, { replace: true });
         }
       },
     );
@@ -156,7 +171,6 @@ export const ContentView = ({
       'SHELLUI_INITIALIZED',
       (_data: ShellUIMessage, event: MessageEvent) => {
         if (event.source !== iframeRef.current?.contentWindow) return;
-        if (!ignoreMessages) lastLoadedIframeUrl = urlRef.current;
         cancelRevealRef.current?.();
         let cancelled = false;
         cancelRevealRef.current = () => {
@@ -195,52 +209,6 @@ export const ContentView = ({
     return () => clearTimeout(timeoutId);
   }, [isLoading]);
 
-  // Handle external URL changes (e.g. from Sidebar)
-  useEffect(() => {
-    if (iframeRef.current) {
-      if (iframeRef.current.src !== url) {
-        iframeRef.current.src = url;
-        // Skip overlay when switching to the same app URL (e.g. App ↔ Root); different app still shows overlay
-        const sameAppAlreadyLoaded = !ignoreMessages;
-        if (!sameAppAlreadyLoaded) {
-          setIsLoading(true);
-          mountTimeRef.current = Date.now(); // apply min delay for this load too
-        }
-      }
-    }
-  }, [url, ignoreMessages]);
-
-  // 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' }}
@@ -256,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,4 +1,4 @@
-import { LOADING_OVERLAY_DURATION_MS } from '../constants';
+import { LOADING_OVERLAY_DURATION_MS } from '../constants/loading';
 
 export function LoadingOverlay() {
   return (

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/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
+    />
+  );
+}

package/src/features/layouts/OverlayShell.tsx

@@ -1,5 +1,5 @@
-import { useEffect, type ReactNode } from 'react';
-import { useNavigate } from 'react-router';
+import { useEffect, useRef, type ReactNode } from 'react';
+import { useLocation, useNavigate } from 'react-router';
 import { useTranslation } from 'react-i18next';
 import { shellui } from '@shellui/sdk';
 import type { NavigationItem } from '../config/types';
@@ -9,21 +9,18 @@ import { Toaster } from '../../components/ui/sonner';
 import { ContentView } from '../../components/ContentView';
 import { useModal } from '../modal/ModalContext';
 import { useDrawer } from '../drawer/DrawerContext';
-import {
-  getNavPathPrefix,
-  getBaseUrlWithoutHash,
-  isHashRouterNavItem,
-  resolveLocalizedString,
-} from './utils';
+import { useNavigationItems } from '../../routes/hooks/useNavigationItems';
+import { getNavPathPrefix, resolveLocalizedString } from './utils';
 
 interface OverlayShellProps {
-  navigationItems: NavigationItem[];
   children: ReactNode;
 }
 
 /** Renders modal, drawer and toaster overlays and handles SHELLUI_OPEN_MODAL / SHELLUI_NAVIGATE. */
-export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
+export const OverlayShell = ({ children }: OverlayShellProps) => {
+  const location = useLocation();
   const navigate = useNavigate();
+  const { navigationItems } = useNavigationItems();
   const { isOpen, modalUrl, closeModal } = useModal();
   const {
     isOpen: isDrawerOpen,
@@ -35,6 +32,17 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
   const { t, i18n } = useTranslation('common');
   const currentLanguage = i18n.language || 'en';
 
+  // Close modal and drawer when app URL changes (navigation, back button) so overlay content stays url-specific
+  const locationKeyRef = useRef(location.pathname + location.search + location.hash);
+  useEffect(() => {
+    const currentKey = location.pathname + location.search + location.hash;
+    if (locationKeyRef.current !== currentKey) {
+      closeModal();
+      closeDrawer();
+      locationKeyRef.current = currentKey;
+    }
+  }, [location.pathname, location.search, location.hash, closeModal, closeDrawer]);
+
   useEffect(() => {
     const cleanup = shellui.addMessageListener('SHELLUI_OPEN_MODAL', () => {
       closeDrawer();
@@ -53,34 +61,7 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
 
       let pathname: string;
 
-      // Hash-based URL (e.g. http://localhost:5173/#/themes/foo): show non-hash path in shell, match by nav item base URL
-      if (rawUrl.includes('/#/')) {
-        try {
-          const parsed = new URL(rawUrl);
-          const hashPart = parsed.hash.slice(1); // strip leading #
-          const hashPath = hashPart.startsWith('/') ? hashPart : `/${hashPart}`;
-          const baseUrl = getBaseUrlWithoutHash(rawUrl);
-          const navItem = navigationItems.find(
-            (item) => isHashRouterNavItem(item) && getBaseUrlWithoutHash(item.url) === baseUrl,
-          );
-          if (!navItem) {
-            shellui.toast({
-              type: 'error',
-              title: t('navigationError') ?? 'Navigation error',
-              description:
-                t('navigationNotAllowed') ?? 'This URL is not configured in the app navigation.',
-            });
-            return;
-          }
-          const pathPrefix = getNavPathPrefix(navItem);
-          pathname =
-            hashPath === '/' || hashPath === ''
-              ? pathPrefix
-              : `${pathPrefix.replace(/\/$/, '')}${hashPath}`;
-        } catch {
-          pathname = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
-        }
-      } else if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+      if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
         try {
           pathname = new URL(rawUrl).pathname;
         } catch {
@@ -110,7 +91,6 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
     });
     return () => cleanup();
   }, [navigate, closeModal, closeDrawer, navigationItems, t]);
-
   return (
     <>
       {children}
@@ -202,4 +182,5 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
       <Toaster />
     </>
   );
-}
+};
+export default OverlayShell;