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

package/src/features/settings/SettingsView.tsx

@@ -15,7 +15,6 @@ import {
   SidebarMenu,
   SidebarMenuButton,
   SidebarMenuItem,
-  SidebarProvider,
 } from '../../components/ui/sidebar';
 import { Route, Routes, useLocation, useNavigate, Navigate } from 'react-router';
 import { useTranslation } from 'react-i18next';
@@ -184,78 +183,30 @@ export const SettingsView = () => {
   // Navigate back to settings root
   const handleBackToSettings = useCallback(() => {
     // Navigate to settings root, replacing current history entry
-    navigate(urls.settings, { replace: true });
+    navigate(urls.settings);
   }, [navigate]);
 
   return (
-    <SidebarProvider>
-      <div className="flex h-full w-full overflow-hidden items-start">
-        {/* Desktop Sidebar */}
-        <Sidebar className="hidden md:flex">
-          <SidebarContent>
-            {groupedRoutes.map((group) => (
-              <SidebarGroup key={group.title}>
-                <SidebarGroupLabel>{group.title}</SidebarGroupLabel>
-                <SidebarGroupContent>
-                  <SidebarMenu>
-                    {group.routes.map((item) => (
-                      <SidebarMenuItem key={item.name}>
-                        <SidebarMenuButton
-                          asChild
-                          isActive={item.name === selectedItem?.name}
+    <div className="flex h-full w-full overflow-hidden items-start">
+      {/* Desktop Sidebar */}
+      <Sidebar className="hidden md:flex">
+        <SidebarContent>
+          {groupedRoutes.map((group) => (
+            <SidebarGroup key={group.title}>
+              <SidebarGroupLabel>{group.title}</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  {group.routes.map((item) => (
+                    <SidebarMenuItem key={item.name}>
+                      <SidebarMenuButton
+                        asChild
+                        isActive={item.name === selectedItem?.name}
+                      >
+                        <button
+                          onClick={() => navigate(`${urls.settings}/${item.path}`)}
+                          className="cursor-pointer"
                         >
-                          <button
-                            onClick={() => navigate(`${urls.settings}/${item.path}`)}
-                            className="cursor-pointer"
-                          >
-                            {'icon' in item && item.icon ? (
-                              <item.icon />
-                            ) : 'iconSrc' in item && item.iconSrc ? (
-                              <img
-                                src={item.iconSrc}
-                                alt=""
-                                className="h-4 w-4 shrink-0"
-                              />
-                            ) : (
-                              <span className="h-4 w-4 shrink-0" />
-                            )}
-                            <span>{item.name}</span>
-                          </button>
-                        </SidebarMenuButton>
-                      </SidebarMenuItem>
-                    ))}
-                  </SidebarMenu>
-                </SidebarGroupContent>
-              </SidebarGroup>
-            ))}
-          </SidebarContent>
-        </Sidebar>
-
-        {/* Mobile List View */}
-        <div className="md:hidden flex h-full w-full flex-col overflow-hidden">
-          {isSettingsRoot ? (
-            // Show list of settings pages
-            <div className="flex flex-1 flex-col overflow-y-auto bg-background">
-              <header className="flex h-16 shrink-0 items-center justify-center px-4 border-b">
-                <h1 className="text-lg font-semibold">{t('title')}</h1>
-              </header>
-              <div className="flex flex-1 flex-col p-4 gap-6">
-                {groupedRoutes.map((group) => (
-                  <div
-                    key={group.title}
-                    className="flex flex-col gap-2"
-                  >
-                    <h2
-                      className="text-xs font-semibold text-foreground/60 uppercase tracking-wider px-2"
-                      style={{ fontFamily: 'var(--heading-font-family, inherit)' }}
-                    >
-                      {group.title}
-                    </h2>
-                    <div className="flex flex-col bg-card rounded-lg overflow-hidden border border-border">
-                      {group.routes.map((item, itemIndex) => {
-                        const isLast = itemIndex === group.routes.length - 1;
-                        const iconEl =
-                          'icon' in item && item.icon ? (
+                          {'icon' in item && item.icon ? (
                             <item.icon />
                           ) : 'iconSrc' in item && item.iconSrc ? (
                             <img
@@ -265,127 +216,173 @@ export const SettingsView = () => {
                             />
                           ) : (
                             <span className="h-4 w-4 shrink-0" />
-                          );
-                        return (
-                          <div
-                            key={item.name}
-                            className="relative"
-                          >
-                            {!isLast && (
-                              <div className="absolute left-0 right-0 bottom-0 h-[1px] bg-border" />
-                            )}
-                            <button
-                              onClick={() => navigate(`${urls.settings}/${item.path}`)}
-                              className="w-full flex items-center justify-between px-4 py-3 bg-transparent hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground transition-colors cursor-pointer rounded-none"
-                            >
-                              <div className="flex items-center gap-2 flex-1 min-w-0">
-                                <div className="flex-shrink-0 text-foreground/70">{iconEl}</div>
-                                <span className="text-sm font-normal text-foreground">
-                                  {item.name}
-                                </span>
-                              </div>
-                              <div className="flex-shrink-0 ml-2 text-foreground/40">
-                                <ChevronRightIcon />
-                              </div>
-                            </button>
-                          </div>
+                          )}
+                          <span>{item.name}</span>
+                        </button>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  ))}
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ))}
+        </SidebarContent>
+      </Sidebar>
+
+      {/* Mobile List View */}
+      <div className="md:hidden flex h-full w-full flex-col overflow-hidden">
+        {isSettingsRoot ? (
+          // Show list of settings pages
+          <div className="flex flex-1 flex-col overflow-y-auto bg-background">
+            <header className="flex h-16 shrink-0 items-center justify-center px-4 border-b">
+              <h1 className="text-lg font-semibold">{t('title')}</h1>
+            </header>
+            <div className="flex flex-1 flex-col p-4 gap-6">
+              {groupedRoutes.map((group) => (
+                <div
+                  key={group.title}
+                  className="flex flex-col gap-2"
+                >
+                  <h2
+                    className="text-xs font-semibold text-foreground/60 uppercase tracking-wider px-2"
+                    style={{ fontFamily: 'var(--heading-font-family, inherit)' }}
+                  >
+                    {group.title}
+                  </h2>
+                  <div className="flex flex-col bg-card rounded-lg overflow-hidden border border-border">
+                    {group.routes.map((item, itemIndex) => {
+                      const isLast = itemIndex === group.routes.length - 1;
+                      const iconEl =
+                        'icon' in item && item.icon ? (
+                          <item.icon />
+                        ) : 'iconSrc' in item && item.iconSrc ? (
+                          <img
+                            src={item.iconSrc}
+                            alt=""
+                            className="h-4 w-4 shrink-0"
+                          />
+                        ) : (
+                          <span className="h-4 w-4 shrink-0" />
                         );
-                      })}
-                    </div>
+                      return (
+                        <div
+                          key={item.name}
+                          className="relative"
+                        >
+                          {!isLast && (
+                            <div className="absolute left-0 right-0 bottom-0 h-[1px] bg-border" />
+                          )}
+                          <button
+                            onClick={() => navigate(`${urls.settings}/${item.path}`)}
+                            className="w-full flex items-center justify-between px-4 py-3 bg-transparent hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground transition-colors cursor-pointer rounded-none"
+                          >
+                            <div className="flex items-center gap-2 flex-1 min-w-0">
+                              <div className="flex-shrink-0 text-foreground/70">{iconEl}</div>
+                              <span className="text-sm font-normal text-foreground">
+                                {item.name}
+                              </span>
+                            </div>
+                            <div className="flex-shrink-0 ml-2 text-foreground/40">
+                              <ChevronRightIcon />
+                            </div>
+                          </button>
+                        </div>
+                      );
+                    })}
                   </div>
-                ))}
-              </div>
+                </div>
+              ))}
             </div>
-          ) : (
-            // Show selected settings page with back button
-            <div className="flex h-full flex-1 flex-col overflow-hidden">
-              <header className="flex h-16 shrink-0 items-center gap-2 px-4 border-b">
-                <Button
-                  variant="ghost"
-                  size="icon"
-                  onClick={handleBackToSettings}
-                  className="mr-2"
-                >
-                  <ChevronLeftIcon />
-                </Button>
-                <h1 className="text-lg font-semibold">{selectedItem?.name}</h1>
-              </header>
-              <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4 pt-4">
-                <Routes>
+          </div>
+        ) : (
+          // Show selected settings page with back button
+          <div className="flex h-full flex-1 flex-col overflow-hidden">
+            <header className="flex h-16 shrink-0 items-center gap-2 px-4 border-b">
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={handleBackToSettings}
+                className="mr-2"
+              >
+                <ChevronLeftIcon />
+              </Button>
+              <h1 className="text-lg font-semibold">{selectedItem?.name}</h1>
+            </header>
+            <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4 pt-4">
+              <Routes>
+                <Route
+                  index
+                  element={
+                    allRoutes.length > 0 ? (
+                      <Navigate
+                        to={`${urls.settings}/${allRoutes[0].path}`}
+                        replace
+                      />
+                    ) : null
+                  }
+                />
+                {allRoutes.map((item) => (
                   <Route
-                    index
-                    element={
-                      allRoutes.length > 0 ? (
-                        <Navigate
-                          to={`${urls.settings}/${allRoutes[0].path}`}
-                          replace
-                        />
-                      ) : null
-                    }
+                    key={item.path}
+                    path={item.path}
+                    element={item.element}
                   />
-                  {allRoutes.map((item) => (
-                    <Route
-                      key={item.path}
-                      path={item.path}
-                      element={item.element}
-                    />
-                  ))}
-                </Routes>
-              </div>
+                ))}
+              </Routes>
             </div>
-          )}
-        </div>
+          </div>
+        )}
+      </div>
 
-        {/* Desktop Main Content */}
-        <main className="hidden md:flex h-full flex-1 flex-col overflow-hidden">
-          {selectedItem && (
-            <header className="flex h-16 shrink-0 items-center gap-2 transition-[width,height] ease-linear">
-              <div className="flex items-center gap-2 px-4">
-                <Breadcrumb>
-                  <BreadcrumbList>
-                    <BreadcrumbItem>{t('title')}</BreadcrumbItem>
-                    <BreadcrumbSeparator />
-                    <BreadcrumbItem>
-                      <BreadcrumbPage>{selectedItem.name}</BreadcrumbPage>
-                    </BreadcrumbItem>
-                  </BreadcrumbList>
-                </Breadcrumb>
-              </div>
-            </header>
+      {/* Desktop Main Content */}
+      <main className="hidden md:flex h-full flex-1 flex-col overflow-hidden">
+        {selectedItem && (
+          <header className="flex h-16 shrink-0 items-center gap-2 transition-[width,height] ease-linear">
+            <div className="flex items-center gap-2 px-4">
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>{t('title')}</BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbPage>{selectedItem.name}</BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+            </div>
+          </header>
+        )}
+        <div
+          className={cn(
+            'flex flex-1 flex-col gap-4 overflow-y-auto',
+            !selectedItem?.path?.startsWith('app-') && 'p-4 pt-0',
           )}
-          <div
-            className={cn(
-              'flex flex-1 flex-col gap-4 overflow-y-auto',
-              !selectedItem?.path?.startsWith('app-') && 'p-4 pt-0',
-            )}
-          >
-            <Routes>
-              <Route
-                index
-                element={
-                  <div className="flex flex-1 flex-col items-center justify-center p-8 text-center">
-                    <div className="max-w-md">
-                      <h2 className="text-lg font-semibold mb-2">{t('title')}</h2>
-                      <p className="text-sm text-muted-foreground">
-                        {t('selectCategory', {
-                          defaultValue: 'Select a category from the sidebar to get started.',
-                        })}
-                      </p>
-                    </div>
+        >
+          <Routes>
+            <Route
+              index
+              element={
+                <div className="flex flex-1 flex-col items-center justify-center p-8 text-center">
+                  <div className="max-w-md">
+                    <h2 className="text-lg font-semibold mb-2">{t('title')}</h2>
+                    <p className="text-sm text-muted-foreground">
+                      {t('selectCategory', {
+                        defaultValue: 'Select a category from the sidebar to get started.',
+                      })}
+                    </p>
                   </div>
-                }
+                </div>
+              }
+            />
+            {allRoutes.map((item) => (
+              <Route
+                key={item.path}
+                path={item.path}
+                element={item.element}
               />
-              {allRoutes.map((item) => (
-                <Route
-                  key={item.path}
-                  path={item.path}
-                  element={item.element}
-                />
-              ))}
-            </Routes>
-          </div>
-        </main>
-      </div>
-    </SidebarProvider>
+            ))}
+          </Routes>
+        </div>
+      </main>
+    </div>
   );
 };

package/src/{components → routes/components}/HomeView.tsx

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useConfig } from '../features/config/useConfig';
+import { useConfig } from '../../features/config/useConfig';
 
 export const HomeView = () => {
   const { t } = useTranslation('common');

package/src/{components → routes/components}/IndexRoute.tsx

@@ -1,8 +1,8 @@
 import { Navigate } from 'react-router';
-import { useConfig } from '../features/config/useConfig';
-import { flattenNavigationItems } from '../features/layouts/utils';
+import { useConfig } from '../../features/config/useConfig';
+import { flattenNavigationItems } from '../../features/layouts/utils';
 import { HomeView } from './HomeView';
-import { ViewRoute } from './ViewRoute';
+import { NavigationItemRoute } from './NavigationItemRoute';
 
 /**
  * Renders the root path "/":
@@ -29,7 +29,7 @@ export const IndexRoute = () => {
     const navigationItems = flattenNavigationItems(navigation);
     const rootNavItem = navigationItems.find((item) => item.path === '' || item.path === '/');
     if (rootNavItem) {
-      return <ViewRoute navigation={navigationItems} />;
+      return <NavigationItemRoute />;
     }
   }
 

package/src/routes/components/NavigationItemRoute.tsx

@@ -0,0 +1,19 @@
+import { ContentView } from '../../components/ContentView';
+import { useNavigationItems } from '../hooks/useNavigationItems';
+import { NotFoundView } from './NotFoundView';
+
+export const NavigationItemRoute = () => {
+  const { url, currentItem } = useNavigationItems();
+
+  if (!currentItem) {
+    return <NotFoundView />;
+  }
+
+  return (
+    <ContentView
+      url={url}
+      pathPrefix={currentItem.path}
+      navItem={currentItem}
+    />
+  );
+};

package/src/{components → routes/components}/NotFoundView.tsx

@@ -1,8 +1,8 @@
 import { useTranslation } from 'react-i18next';
 import { shellui } from '@shellui/sdk';
-import { useConfig } from '../features/config/useConfig';
-import { getNavPathPrefix } from '../features/layouts/utils';
-import type { NavigationItem, NavigationGroup } from '../features/config/types';
+import { useConfig } from '../../features/config/useConfig';
+import { getNavPathPrefix } from '../../features/layouts/utils';
+import type { NavigationItem, NavigationGroup } from '../../features/config/types';
 
 const flattenNavigationItems = (
   navigation: (NavigationItem | NavigationGroup)[],
@@ -37,7 +37,12 @@ export const NotFoundView = () => {
       : [];
 
   const handleNavigate = (path: string) => {
-    shellui.navigate(path.startsWith('/') ? path : `/${path}`);
+    const targetPath = path.startsWith('/') ? path : `/${path}`;
+    if (window.self !== window.top) {
+      shellui.navigate(targetPath);
+    } else {
+      window.location.href = targetPath;
+    }
   };
 
   return (

package/src/{components → routes/components}/RouteErrorBoundary.tsx

@@ -1,7 +1,7 @@
 import { useRouteError, isRouteErrorResponse } from 'react-router';
 import { useTranslation } from 'react-i18next';
 import { shellui } from '@shellui/sdk';
-import { Button } from './ui/button';
+import { Button } from '../../components/ui/button';
 
 function isChunkLoadError(error: unknown): boolean {
   if (error instanceof Error) {

package/src/routes/components/RouteFallback.tsx

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

package/src/routes/hooks/useNavigationItems.ts

@@ -0,0 +1,84 @@
+import { useMemo } from 'react';
+import { useConfig } from '../../features/config/useConfig';
+import {
+  flattenNavigationItems,
+  getBaseUrlWithoutHash,
+  getHashPathFromUrl,
+  getNavPathPrefix,
+  isHashRouterNavItem,
+} from '../../features/layouts/utils';
+import { useLocation } from 'react-router';
+
+export function useNavigationItems() {
+  const { config } = useConfig();
+  const location = useLocation();
+
+  const navigationItems = useMemo(() => {
+    return flattenNavigationItems(config?.navigation ?? []);
+  }, [config]);
+
+  const navigationItem = useMemo(() => {
+    return navigationItems.find((item) => {
+      const pathPrefix = getNavPathPrefix(item);
+      return location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`);
+    });
+  }, [navigationItems, location.pathname]);
+
+  // When no nav matches (e.g. /layout on refresh): use root item (path '' or '/') with pathname as hash subpath to avoid 404
+  const rootItem = useMemo(
+    () => navigationItems.find((item) => item.path === '' || item.path === '/'),
+    [navigationItems],
+  );
+
+  /**
+   * Constructs the final URL for the iframe based on the navigation item and the pathname.
+   * If the navigation item is a hash router item, it preserves the hash path and appends the subpath.
+   * If the navigation item is not a hash router item, it appends the subpath to the base URL.
+   * If the navigation item is not found, it returns an empty string.
+   */
+  const url = useMemo(() => {
+    const pathname = location.pathname;
+
+    const useRootFallback = !navigationItem && rootItem && pathname !== '/';
+    const actualNavItem = navigationItem ?? (useRootFallback ? rootItem : null);
+
+    if (!actualNavItem) {
+      return '';
+    }
+    const actualSubPath = useRootFallback
+      ? pathname.replace(/^\//, '')
+      : actualNavItem
+        ? pathname.length > getNavPathPrefix(actualNavItem).length
+          ? pathname.slice(getNavPathPrefix(actualNavItem).length + 1)
+          : ''
+        : '';
+
+    const subPath = actualSubPath;
+    // Construct the final URL for the iframe (non-hash: base + path; hash app: preserve nav url hash path + subPath)
+    let finalUrl: string;
+    if (isHashRouterNavItem(actualNavItem)) {
+      const base = getBaseUrlWithoutHash(actualNavItem.url).replace(/\/$/, '');
+      const navHashPath = getHashPathFromUrl(actualNavItem.url).replace(/^\/+|\/+$/g, '');
+      const segments = [navHashPath, subPath].filter(Boolean);
+      const fullHashPath = `/${segments.join('/')}`;
+      finalUrl = `${base}#${fullHashPath}`;
+    } else {
+      finalUrl = actualNavItem.url;
+      if (subPath) {
+        const baseUrl = actualNavItem.url.endsWith('/')
+          ? actualNavItem.url
+          : `${actualNavItem.url}/`;
+        finalUrl = `${baseUrl}${subPath}`;
+      }
+    }
+    return finalUrl;
+  }, [navigationItem, rootItem, location.pathname]);
+
+  return {
+    url: url,
+    rootItem: rootItem,
+    currentItem: navigationItem || rootItem,
+    navigationItem: navigationItem || rootItem,
+    navigationItems: navigationItems,
+  };
+}

package/src/{router → routes}/routes.tsx

@@ -1,10 +1,11 @@
 import { lazy, Suspense } from 'react';
 import { Outlet, type RouteObject } from 'react-router';
 import type { ShellUIConfig } from '../features/config/types';
-import { RouteErrorBoundary } from '../components/RouteErrorBoundary';
+import { RouteErrorBoundary } from './components/RouteErrorBoundary';
 import { AppLayout } from '../features/layouts/AppLayout';
 import { flattenNavigationItems } from '../features/layouts/utils';
 import urls from '../constants/urls';
+import { RouteFallback } from './components/RouteFallback';
 
 // Lazy load route components
 const SettingsView = lazy(() =>
@@ -15,25 +16,16 @@ const CookiePreferencesView = lazy(() =>
     default: m.CookiePreferencesView,
   })),
 );
-const ViewRoute = lazy(() =>
-  import('../components/ViewRoute').then((m) => ({ default: m.ViewRoute })),
+const NavigationItemRoute = lazy(() =>
+  import('./components/NavigationItemRoute').then((m) => ({ default: m.NavigationItemRoute })),
 );
 const IndexRoute = lazy(() =>
-  import('../components/IndexRoute').then((m) => ({ default: m.IndexRoute })),
+  import('./components/IndexRoute').then((m) => ({ default: m.IndexRoute })),
 );
 const NotFoundView = lazy(() =>
-  import('../components/NotFoundView').then((m) => ({ default: m.NotFoundView })),
+  import('./components/NotFoundView').then((m) => ({ default: m.NotFoundView })),
 );
 
-function RouteFallback() {
-  return (
-    <div
-      className="min-h-screen bg-background"
-      aria-hidden
-    />
-  );
-}
-
 export const createRoutes = (config: ShellUIConfig): RouteObject[] => {
   const routes: RouteObject[] = [
     {
@@ -104,13 +96,23 @@ export const createRoutes = (config: ShellUIConfig): RouteObject[] => {
         path: `/${item.path}/*`,
         element: (
           <Suspense fallback={<RouteFallback />}>
-            <ViewRoute navigation={navigationItems} />
+            <NavigationItemRoute />
           </Suspense>
         ),
       });
     });
+    // Catch-all: no nav match (e.g. /layout) → NavigationItemRoute can use root item with pathname as hash subpath to avoid 404
+    (layoutRoute.children as RouteObject[]).push({
+      path: '*',
+      element: (
+        <Suspense fallback={<RouteFallback />}>
+          <NavigationItemRoute />
+        </Suspense>
+      ),
+    });
   }
-  (routes[0].children as RouteObject[]).push(layoutRoute);
+  // Layout must be before the catch-all (*) so paths like /layout are handled by layout → NavigationItemRoute (root fallback), not 404
+  (routes[0].children as RouteObject[]).unshift(layoutRoute);
 
   return routes;
 };