@shellui/core 0.1.0 → 0.2.0-alpha.1

package/src/features/layouts/AppBarLayout.tsx

@@ -0,0 +1,260 @@
+import { useMemo, useEffect, type ReactNode } from 'react';
+import { Link, useLocation, Outlet, useNavigate } from 'react-router';
+import { useTranslation } from 'react-i18next';
+import { shellui } from '@shellui/sdk';
+import type { NavigationItem, NavigationGroup } from '../config/types';
+import {
+  filterNavigationByViewport,
+  flattenNavigationItems,
+  getEffectiveUrl,
+  getNavPathPrefix,
+  resolveLocalizedString as resolveNavLabel,
+  splitNavigationByPosition,
+  withHomepageWhenNoRoot,
+} from './utils';
+import { LayoutProviders } from './LayoutProviders';
+import { OverlayShell } from './OverlayShell';
+import { Select } from '../../components/ui/select';
+import { AppBarTooltip, TooltipProvider } from '../../components/ui/tooltip';
+import { cn } from '../../lib/utils';
+
+const TOP_BAR_MAX_HEIGHT = 42;
+
+interface AppBarLayoutProps {
+  title?: string;
+  appIcon?: string;
+  logo?: string;
+  navigation: (NavigationItem | NavigationGroup)[];
+}
+
+const getExternalFaviconUrl = (url: string): string | null => {
+  try {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname;
+    if (!hostname) return null;
+    return `https://icons.duckduckgo.com/ip3/${hostname}.ico`;
+  } catch {
+    return null;
+  }
+};
+
+const isAppIcon = (src: string) => src.startsWith('/icons/');
+
+function resolveLocalizedLabel(
+  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] || '';
+}
+
+/** End link: icon-only or first-letter badge with themed tooltip. */
+function TopBarEndItem({ item, label }: { item: NavigationItem; label: string }) {
+  const pathPrefix = getNavPathPrefix(item);
+  const isOverlay = item.openIn === 'modal' || item.openIn === 'drawer';
+  const isExternal = item.openIn === 'external';
+  const location = useLocation();
+  const isActive =
+    !isOverlay &&
+    !isExternal &&
+    (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
+
+  const faviconUrl = isExternal && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
+  const iconSrc = item.icon ?? faviconUrl ?? null;
+  const firstLetter = label ? label.charAt(0).toUpperCase() : '?';
+
+  const iconEl = iconSrc ? (
+    <img
+      src={iconSrc}
+      alt=""
+      className={cn(
+        'size-5 shrink-0 rounded-sm object-cover',
+        isAppIcon(iconSrc) && 'opacity-90 dark:opacity-100 dark:invert',
+      )}
+    />
+  ) : (
+    <span
+      className="size-6 shrink-0 rounded-md bg-muted flex items-center justify-center text-xs font-medium text-muted-foreground"
+      aria-hidden
+    >
+      {firstLetter}
+    </span>
+  );
+
+  const buttonClass = cn(
+    'flex items-center justify-center size-8 rounded-md transition-colors cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+    isActive
+      ? 'bg-sidebar-accent text-sidebar-accent-foreground'
+      : 'text-muted-foreground hover:bg-sidebar-accent/50 hover:text-sidebar-foreground',
+  );
+
+  const wrap = (node: ReactNode) => <AppBarTooltip label={label}>{node}</AppBarTooltip>;
+
+  if (item.openIn === 'modal') {
+    return wrap(
+      <button
+        type="button"
+        onClick={() => shellui.openModal(getEffectiveUrl(item))}
+        className={buttonClass}
+        aria-label={label}
+      >
+        {iconEl}
+      </button>,
+    );
+  }
+  if (item.openIn === 'drawer') {
+    return wrap(
+      <button
+        type="button"
+        onClick={() => shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition })}
+        className={buttonClass}
+        aria-label={label}
+      >
+        {iconEl}
+      </button>,
+    );
+  }
+  if (item.openIn === 'external') {
+    return wrap(
+      <a
+        href={getEffectiveUrl(item)}
+        target="_blank"
+        rel="noopener noreferrer"
+        className={buttonClass}
+        aria-label={label}
+      >
+        {iconEl}
+      </a>,
+    );
+  }
+  return wrap(
+    <Link
+      to={pathPrefix}
+      className={buttonClass}
+      aria-label={label}
+    >
+      {iconEl}
+    </Link>,
+  );
+}
+
+export function AppBarLayout({ title, logo, navigation }: AppBarLayoutProps) {
+  const { i18n } = useTranslation();
+  const location = useLocation();
+  const navigate = useNavigate();
+  const currentLanguage = i18n.language || 'en';
+
+  const { endNavItems, navigationItems, displayStartItems } = useMemo(() => {
+    const desktopNav = filterNavigationByViewport(navigation, 'desktop');
+    const { start, end } = splitNavigationByPosition(desktopNav);
+    const startItems = flattenNavigationItems(start).filter((i) => !i.hidden);
+    return {
+      endNavItems: flattenNavigationItems(end).filter((i) => !i.hidden),
+      navigationItems: flattenNavigationItems(navigation),
+      displayStartItems: withHomepageWhenNoRoot(startItems),
+    };
+  }, [navigation]);
+
+  useEffect(() => {
+    if (!title) return;
+    const pathname = location.pathname.replace(/^\/+|\/+$/g, '') || '';
+    const segment = pathname.split('/')[0];
+    if (!segment) {
+      const rootNavItem = navigationItems.find((item) => item.path === '' || item.path === '/');
+      document.title = rootNavItem
+        ? `${resolveLocalizedLabel(rootNavItem.label, currentLanguage)} | ${title}`
+        : title;
+      return;
+    }
+    const navItem = navigationItems.find((item) => item.path === segment);
+    if (navItem) {
+      const label = resolveLocalizedLabel(navItem.label, currentLanguage);
+      document.title = `${label} | ${title}`;
+    } else {
+      document.title = title;
+    }
+  }, [location.pathname, title, navigationItems, currentLanguage]);
+
+  const currentPathPrefix =
+    location.pathname === '/'
+      ? '/'
+      : `/${location.pathname.replace(/^\/+|\/+$/g, '').split('/')[0]}`;
+
+  return (
+    <LayoutProviders>
+      <OverlayShell navigationItems={navigationItems}>
+        <div className="flex flex-col h-screen overflow-hidden bg-background">
+          {/* Top bar: max 42px */}
+          <header
+            className="flex items-center gap-3 px-3 border-b border-border bg-sidebar-background shrink-0"
+            style={{ minHeight: 32, maxHeight: TOP_BAR_MAX_HEIGHT }}
+            data-layout="app-bar"
+          >
+            {/* Logo / title (home link) */}
+            <Link
+              to="/"
+              className="flex items-center gap-2 shrink-0 min-w-0 py-1.5 pr-2 text-sidebar-foreground hover:text-sidebar-foreground/80 transition-colors"
+            >
+              {logo && logo.trim() ? (
+                <img
+                  src={logo}
+                  alt={title || 'Logo'}
+                  className="h-5 w-auto max-h-6 object-contain app-bar-logo m-1.5"
+                />
+              ) : title ? (
+                <span className="text-sm font-semibold truncate">{title}</span>
+              ) : null}
+            </Link>
+
+            {/* Start links: select menu (includes synthetic Homepage when nav has no "/" path) */}
+            {displayStartItems.length > 0 && (
+              <Select
+                className="h-8 max-w-[200px] text-sm leading-tight py-1.5 border-sidebar-border bg-sidebar-background"
+                value={currentPathPrefix}
+                onChange={(e) => {
+                  const path = e.target.value;
+                  if (path) {
+                    navigate(path.startsWith('/') ? path : `/${path}`);
+                  }
+                }}
+              >
+                {displayStartItems.map((item) => (
+                  <option
+                    key={item.path || 'root'}
+                    value={getNavPathPrefix(item)}
+                  >
+                    {resolveNavLabel(item.label, currentLanguage) || item.path || 'Home'}
+                  </option>
+                ))}
+              </Select>
+            )}
+
+            <div className="flex-1 min-w-0" />
+
+            {/* End links: icon-only or first letter + tooltip */}
+            {endNavItems.length > 0 && (
+              <TooltipProvider
+                delayDuration={200}
+                skipDelayDuration={0}
+              >
+                <div className="flex items-center gap-0.5 shrink-0">
+                  {endNavItems.map((item) => (
+                    <TopBarEndItem
+                      key={item.path}
+                      item={item}
+                      label={resolveNavLabel(item.label, currentLanguage) || item.path || ''}
+                    />
+                  ))}
+                </div>
+              </TooltipProvider>
+            )}
+          </header>
+
+          <main className="flex-1 flex flex-col overflow-auto min-h-0">
+            <Outlet />
+          </main>
+        </div>
+      </OverlayShell>
+    </LayoutProviders>
+  );
+}

package/src/features/layouts/AppLayout.tsx

@@ -11,6 +11,9 @@ const FullscreenLayout = lazy(() =>
 const WindowsLayout = lazy(() =>
   import('./WindowsLayout').then((m) => ({ default: m.WindowsLayout })),
 );
+const AppBarLayout = lazy(() =>
+  import('./AppBarLayout').then((m) => ({ default: m.AppBarLayout })),
+);
 
 interface AppLayoutProps {
   layout?: LayoutType;
@@ -50,6 +53,9 @@ export function AppLayout({
   } else if (effectiveLayout === 'windows') {
     LayoutComponent = WindowsLayout;
     layoutProps = { title, appIcon, logo, navigation };
+  } else if (effectiveLayout === 'app-bar') {
+    LayoutComponent = AppBarLayout;
+    layoutProps = { title, appIcon, logo, navigation };
   } else {
     LayoutComponent = DefaultLayout;
     layoutProps = { title, appIcon, logo, navigation };

package/src/features/layouts/DefaultLayout.tsx

@@ -22,6 +22,9 @@ import {
   filterNavigationByViewport,
   filterNavigationForSidebar,
   flattenNavigationItems,
+  getEffectiveUrl,
+  getNavPathPrefix,
+  HOMEPAGE_NAV_ITEM,
   resolveLocalizedString as resolveNavLabel,
   splitNavigationByPosition,
 } from './utils';
@@ -87,7 +90,7 @@ const NavigationContent = ({
 
   // Render a single nav item link or modal/drawer trigger
   const renderNavItem = (navItem: NavigationItem) => {
-    const pathPrefix = `/${navItem.path}`;
+    const pathPrefix = getNavPathPrefix(navItem);
     const isOverlay = navItem.openIn === 'modal' || navItem.openIn === 'drawer';
     const isExternal = navItem.openIn === 'external';
     const isActive =
@@ -95,7 +98,7 @@ const NavigationContent = ({
       !isExternal &&
       (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
     const itemLabel = resolveLocalizedString(navItem.label, currentLanguage);
-    const faviconUrl = isExternal && !navItem.icon ? getExternalFaviconUrl(navItem.url) : null;
+    const faviconUrl = isExternal && !navItem.icon ? getExternalFaviconUrl(getEffectiveUrl(navItem)) : null;
     const iconSrc = navItem.icon ?? faviconUrl ?? null;
     const iconEl = iconSrc ? (
       <img
@@ -120,7 +123,7 @@ const NavigationContent = ({
       navItem.openIn === 'modal' ? (
         <button
           type="button"
-          onClick={() => shellui.openModal(navItem.url)}
+          onClick={() => shellui.openModal(getEffectiveUrl(navItem))}
           className="flex items-center gap-2 w-full cursor-pointer text-left"
         >
           {content}
@@ -128,14 +131,14 @@ const NavigationContent = ({
       ) : navItem.openIn === 'drawer' ? (
         <button
           type="button"
-          onClick={() => shellui.openDrawer({ url: navItem.url, position: navItem.drawerPosition })}
+          onClick={() => shellui.openDrawer({ url: getEffectiveUrl(navItem), position: navItem.drawerPosition })}
           className="flex items-center gap-2 w-full cursor-pointer text-left"
         >
           {content}
         </button>
       ) : navItem.openIn === 'external' ? (
         <a
-          href={navItem.url}
+          href={getEffectiveUrl(navItem)}
           target="_blank"
           rel="noopener noreferrer"
           className="flex items-center gap-2 w-full"
@@ -144,7 +147,7 @@ const NavigationContent = ({
         </a>
       ) : (
         <Link
-          to={`/${navItem.path}`}
+          to={pathPrefix}
           className="flex items-center gap-2 w-full"
         >
           {content}
@@ -273,7 +276,7 @@ const BottomNavItem = ({
   iconSrc: string | null;
   applyIconTheme: boolean;
 }) => {
-  const pathPrefix = `/${item.path}`;
+  const pathPrefix = getNavPathPrefix(item);
   const content = (
     <span className="flex flex-col items-center justify-center gap-1 w-full min-w-0 max-w-full overflow-hidden">
       {iconSrc ? (
@@ -303,7 +306,7 @@ const BottomNavItem = ({
     return (
       <button
         type="button"
-        onClick={() => shellui.openModal(item.url)}
+        onClick={() => shellui.openModal(getEffectiveUrl(item))}
         className={baseClass}
       >
         {content}
@@ -314,7 +317,7 @@ const BottomNavItem = ({
     return (
       <button
         type="button"
-        onClick={() => shellui.openDrawer({ url: item.url, position: item.drawerPosition })}
+        onClick={() => shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition })}
         className={baseClass}
       >
         {content}
@@ -324,7 +327,7 @@ const BottomNavItem = ({
   if (item.openIn === 'external') {
     return (
       <a
-        href={item.url}
+        href={getEffectiveUrl(item)}
         target="_blank"
         rel="noopener noreferrer"
         className={baseClass}
@@ -427,7 +430,7 @@ const HomeIcon = ({ className }: { className?: string }) => (
   </svg>
 );
 
-/** Mobile bottom nav: Home + nav items; More only when not all fit. Dynamic from width. */
+/** Mobile bottom nav: Home + nav items; More only when not all fit. Dynamic from width. Reuses HOMEPAGE_NAV_ITEM for label. */
 const MobileBottomNav = ({
   items,
   currentLanguage,
@@ -477,7 +480,7 @@ const MobileBottomNav = ({
   }, [location.pathname]);
 
   const renderItem = (item: NavigationItem, index: number) => {
-    const pathPrefix = `/${item.path}`;
+    const pathPrefix = getNavPathPrefix(item);
     const isOverlayOrExternal =
       item.openIn === 'modal' || item.openIn === 'drawer' || item.openIn === 'external';
     const isActive =
@@ -485,12 +488,12 @@ const MobileBottomNav = ({
       (location.pathname === pathPrefix || location.pathname.startsWith(`${pathPrefix}/`));
     const label = resolveNavLabel(item.label, currentLanguage);
     const faviconUrl =
-      item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(item.url) : null;
+      item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
     const iconSrc = item.icon ?? faviconUrl ?? null;
     const applyIconTheme = iconSrc ? isAppIcon(iconSrc) : false;
     return (
       <BottomNavItem
-        key={`${item.path}-${item.url}-${index}`}
+        key={`${item.path}-${getEffectiveUrl(item)}-${index}`}
         item={item}
         label={label}
         isActive={isActive}
@@ -519,12 +522,14 @@ const MobileBottomNav = ({
               ? 'bg-sidebar-accent text-sidebar-accent-foreground [&_span]:text-sidebar-accent-foreground'
               : 'text-sidebar-foreground/80 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground [&_span]:inherit',
           )}
-          aria-label="Home"
+          aria-label={resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
         >
           <span className="size-4 shrink-0 flex items-center justify-center [&_svg]:text-current">
             <HomeIcon className="size-4" />
           </span>
-          <span className="text-[11px] leading-tight">Home</span>
+          <span className="text-[11px] leading-tight">
+            {resolveNavLabel(HOMEPAGE_NAV_ITEM.label, currentLanguage) || 'Home'}
+          </span>
         </Link>
         {rowItems.map((item, i) => renderItem(item, i))}
         {hasMore && (
@@ -589,7 +594,10 @@ const DefaultLayoutContent = ({ title, logo, navigation }: DefaultLayoutProps) =
     const pathname = location.pathname.replace(/^\/+|\/+$/g, '') || '';
     const segment = pathname.split('/')[0];
     if (!segment) {
-      document.title = title;
+      const rootNavItem = navigationItems.find((item) => item.path === '' || item.path === '/');
+      document.title = rootNavItem
+        ? `${resolveLocalizedLabel(rootNavItem.label, currentLanguage)} | ${title}`
+        : title;
       return;
     }
     const navItem = navigationItems.find((item) => item.path === segment);

package/src/features/layouts/OverlayShell.tsx

@@ -9,7 +9,7 @@ import { Toaster } from '../../components/ui/sonner';
 import { ContentView } from '../../components/ContentView';
 import { useModal } from '../modal/ModalContext';
 import { useDrawer } from '../drawer/DrawerContext';
-import { resolveLocalizedString } from './utils';
+import { getEffectiveUrl, getNavPathPrefix, normalizeUrlToPathname, resolveLocalizedString } from './utils';
 
 interface OverlayShellProps {
   navigationItems: NavigationItem[];
@@ -60,9 +60,10 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
       const isHomepage = pathname === '/' || pathname === '';
       const isAllowed =
         isHomepage ||
-        navigationItems.some(
-          (item) => pathname === `/${item.path}` || pathname.startsWith(`/${item.path}/`),
-        );
+        navigationItems.some((item) => {
+          const pathPrefix = getNavPathPrefix(item);
+          return pathname === pathPrefix || pathname.startsWith(`${pathPrefix}/`);
+        });
       if (isAllowed) {
         navigate(pathname || '/');
       } else {
@@ -82,14 +83,16 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
       {children}
       <Dialog
         open={isOpen}
-        onOpenChange={closeModal}
+        onOpenChange={(open) => !open && closeModal()}
       >
         <DialogContent className="max-w-4xl w-full h-[80vh] max-h-[680px] flex flex-col p-0 overflow-hidden">
           {modalUrl ? (
             <>
               <DialogTitle className="sr-only">
                 {resolveLocalizedString(
-                  navigationItems.find((item) => item.url === modalUrl)?.label,
+                  navigationItems.find(
+                    (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(modalUrl),
+                  )?.label,
                   currentLanguage,
                 )}
               </DialogTitle>
@@ -104,7 +107,11 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
                   url={modalUrl}
                   pathPrefix="settings"
                   ignoreMessages={true}
-                  navItem={navigationItems.find((item) => item.url === modalUrl) as NavigationItem}
+                  navItem={
+                    navigationItems.find(
+                      (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(modalUrl),
+                    ) ?? undefined
+                  }
                 />
               </div>
             </>
@@ -146,7 +153,11 @@ export function OverlayShell({ navigationItems, children }: OverlayShellProps) {
                 url={drawerUrl}
                 pathPrefix="settings"
                 ignoreMessages={true}
-                navItem={navigationItems.find((item) => item.url === drawerUrl) as NavigationItem}
+                navItem={
+                  navigationItems.find(
+                    (item) => normalizeUrlToPathname(getEffectiveUrl(item)) === normalizeUrlToPathname(drawerUrl),
+                  ) ?? undefined
+                }
               />
             </div>
           ) : (

package/src/features/layouts/WindowsLayout.tsx

@@ -11,6 +11,8 @@ import { shellui } from '@shellui/sdk';
 import type { NavigationItem, NavigationGroup } from '../config/types';
 import {
   flattenNavigationItems,
+  getEffectiveUrl,
+  getNavPathPrefix,
   resolveLocalizedString as resolveNavLabel,
   splitNavigationByPosition,
 } from './utils';
@@ -70,7 +72,7 @@ function getMaximizedBounds(): WindowState['bounds'] {
 }
 
 function buildFinalUrl(baseUrl: string, path: string, pathname: string): string {
-  const pathPrefix = `/${path}`;
+  const pathPrefix = getNavPathPrefix({ path } as NavigationItem);
   const subPath = pathname.length > pathPrefix.length ? pathname.slice(pathPrefix.length + 1) : '';
   if (!subPath) return baseUrl;
   const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
@@ -540,7 +542,7 @@ export function WindowsLayout({
       const label =
         typeof item.label === 'string' ? item.label : resolveNavLabel(item.label, currentLanguage);
       const faviconUrl =
-        item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(item.url) : null;
+        item.openIn === 'external' && !item.icon ? getExternalFaviconUrl(getEffectiveUrl(item)) : null;
       const icon = item.icon ?? faviconUrl ?? null;
       const id = genId();
       const bounds = {
@@ -554,8 +556,8 @@ export function WindowsLayout({
         {
           id,
           path: item.path,
-          pathname: `/${item.path}`,
-          baseUrl: item.url,
+          pathname: getNavPathPrefix(item),
+          baseUrl: getEffectiveUrl(item),
           label,
           icon,
           bounds,
@@ -608,17 +610,17 @@ export function WindowsLayout({
   const handleNavClick = useCallback(
     (item: NavigationItem) => {
       if (item.openIn === 'modal') {
-        shellui.openModal(item.url);
+        shellui.openModal(getEffectiveUrl(item));
         setStartMenuOpen(false);
         return;
       }
       if (item.openIn === 'drawer') {
-        shellui.openDrawer({ url: item.url, position: item.drawerPosition });
+        shellui.openDrawer({ url: getEffectiveUrl(item), position: item.drawerPosition });
         setStartMenuOpen(false);
         return;
       }
       if (item.openIn === 'external') {
-        window.open(item.url, '_blank', 'noopener,noreferrer');
+        window.open(getEffectiveUrl(item), '_blank', 'noopener,noreferrer');
         setStartMenuOpen(false);
         return;
       }
@@ -708,7 +710,7 @@ export function WindowsLayout({
                           : resolveNavLabel(item.label, currentLanguage);
                       const icon =
                         item.icon ??
-                        (item.openIn === 'external' ? getExternalFaviconUrl(item.url) : null);
+                        (item.openIn === 'external' ? getExternalFaviconUrl(getEffectiveUrl(item)) : null);
                       return (
                         <button
                           key={item.path}
@@ -790,7 +792,7 @@ export function WindowsLayout({
                     : resolveNavLabel(item.label, currentLanguage);
                 const icon =
                   item.icon ??
-                  (item.openIn === 'external' ? getExternalFaviconUrl(item.url) : null);
+                  (item.openIn === 'external' ? getExternalFaviconUrl(getEffectiveUrl(item)) : null);
                 return (
                   <button
                     key={item.path}

package/src/features/layouts/utils.ts

@@ -1,4 +1,34 @@
 import type { NavigationItem, NavigationGroup, LocalizedString } from '../config/types';
+import urls from '../../constants/urls';
+
+/** Path prefix for a nav item: "/" for root (path '' or '/'), otherwise "/{path}". */
+export function getNavPathPrefix(item: NavigationItem): string {
+  return item.path === '/' || item.path === '' ? '/' : `/${item.path}`;
+}
+
+/** Effective URL for a nav item: url if set, otherwise app-path URL for component-based items. */
+export function getEffectiveUrl(item: NavigationItem): string {
+  if (item.url != null && item.url !== '') {
+    return item.url;
+  }
+  const base = typeof window !== 'undefined' ? window.location.origin : '';
+  const path = item.path === '/' || item.path === '' ? 'home' : item.path;
+  return `${base}${urls.appPath}/${path}`;
+}
+
+/** Normalize a URL to pathname for comparison (handles full URLs and path-only). */
+export function normalizeUrlToPathname(url: string): string {
+  if (!url || typeof url !== 'string') return '';
+  const s = url.trim();
+  if (s.startsWith('http://') || s.startsWith('https://') || s.startsWith('//')) {
+    try {
+      return new URL(s, 'http://localhost').pathname.replace(/\/+$/, '') || '/';
+    } catch {
+      return s.startsWith('/') ? s.replace(/\/+$/, '') || '/' : `/${s}`.replace(/\/+$/, '') || '/';
+    }
+  }
+  return (s.startsWith('/') ? s : `/${s}`).replace(/\/+$/, '') || '/';
+}
 
 /** Resolve a localized string to a single string for the given language. */
 export function resolveLocalizedString(value: LocalizedString | undefined, lang: string): string {
@@ -74,6 +104,20 @@ export function filterNavigationForSidebar(
     .filter((item): item is NavigationItem | NavigationGroup => item !== null);
 }
 
+/** Synthetic homepage nav item: used when there is no root (path '' or '/') in the list, so users can navigate to "/". Reused by app-bar and sidebar mobile. */
+export const HOMEPAGE_NAV_ITEM: NavigationItem = {
+  path: '/',
+  label: { en: 'Home', fr: 'Accueil' },
+  url: '/',
+};
+
+/** If there is no root item (path '' or '/') in the list, prepend a synthetic Homepage item. Use in app-bar and anywhere that needs a "Home" entry when nav has no "/" path. */
+export function withHomepageWhenNoRoot(items: NavigationItem[]): NavigationItem[] {
+  const hasRoot = items.some((i) => i.path === '' || i.path === '/');
+  if (hasRoot) return items;
+  return [HOMEPAGE_NAV_ITEM, ...items];
+}
+
 /** Split navigation by position: start (main content) and end (footer). */
 export function splitNavigationByPosition(navigation: (NavigationItem | NavigationGroup)[]): {
   start: (NavigationItem | NavigationGroup)[];