@mostrom/app-shell 0.1.0

package/src/AppShell.tsx

@@ -0,0 +1,847 @@
+/**
+ * AppShell Component
+ *
+ * The primary layout wrapper for all platform services. Implements AWS Cloudscape
+ * design system patterns to ensure visual and behavioral consistency.
+ *
+ * LAYOUT STRUCTURE:
+ * ┌─────────────────────────────────────────────────────────────────────────────┐
+ * │ GLOBAL HEADER (TopNavigation)                                               │
+ * │ ┌─────────────┬──────────────────────────────┬────────────────────────────┐ │
+ * │ │ Identity    │ All Services | Search Bar    │ Settings | Theme | User   │ │
+ * │ │ (Logo/Name) │ (9-dot grid)   (Global)      │ (Dropdowns)                │ │
+ * │ └─────────────┴──────────────────────────────┴────────────────────────────┘ │
+ * ├─────────────────────────────────────────────────────────────────────────────┤
+ * │ MAIN LAYOUT (AppLayoutToolbar)                                              │
+ * │ ┌────────────┬────────────────────────────────────────────┬───────────────┐ │
+ * │ │ Side Nav   │ Content Area                               │ Drawers       │ │
+ * │ │ (Service   │ ┌────────────────────────────────────────┐ │ (Chatbot,     │ │
+ * │ │  pages)    │ │ Breadcrumbs                            │ │  Tools)       │ │
+ * │ │            │ ├────────────────────────────────────────┤ │               │ │
+ * │ │            │ │ Notifications (Flashbar)               │ │               │ │
+ * │ │            │ ├────────────────────────────────────────┤ │               │ │
+ * │ │            │ │ Content Header                         │ │               │ │
+ * │ │            │ ├────────────────────────────────────────┤ │               │ │
+ * │ │            │ │ Main Content (children)                │ │               │ │
+ * │ │            │ │                                        │ │               │ │
+ * │ │            │ └────────────────────────────────────────┘ │               │ │
+ * │ └────────────┴────────────────────────────────────────────┴───────────────┘ │
+ * └─────────────────────────────────────────────────────────────────────────────┘
+ *
+ * KEY COMPONENTS:
+ * - Global Header: Persistent top bar with platform branding and global actions
+ * - All Services Button: 9-dot grid icon for accessing all platform services
+ * - Global Search: Search bar for finding services, features, and documentation
+ * - Side Navigation: Collapsible left panel for service-specific page navigation
+ * - Content Area: Main area for page content with breadcrumbs and notifications
+ * - Drawers: Slide-in panels from the right (e.g., AI chatbot assistant)
+ *
+ * USAGE:
+ * Wrap your service's pages with AppShell to inherit the standard platform layout.
+ * Pass service-specific navigation items and content through props.
+ */
+
+import React from "react";
+
+import "@cloudscape-design/global-styles/index.css";
+import "./styles.css";
+
+import { AppFlashbar, type FlashbarMessage } from "./components/layout/AppFlashbar";
+import type { NavigationItem, NavigationFollowEvent } from "./components/layout/AppNavigation";
+import { AppBreadcrumb, type BreadcrumbItem } from "./components/layout/AppBreadcrumb";
+
+// Type aliases for navigation - maintaining export names for backward compatibility
+export type CompatibleNavigationItem = NavigationItem;
+export type CompatibleNavigationFollowEvent = NavigationFollowEvent;
+import { AppNavigation } from "./components/layout/AppNavigation";
+import { AppLayout } from "./components/layout/AppLayout";
+import type {
+  MenuDropdownItems,
+  MenuItemClickHandler,
+} from "./components/global-header/ServicesMenu";
+import {
+  getServiceCatalog,
+  getServiceCatalogSync,
+  groupServicesByCategory,
+  searchServices,
+  type ServiceItem,
+} from "@platform/service-catalog";
+import { basePath } from "./urls";
+import { GlobalHeader, type GlobalHeaderIdentity } from "./components/global-header/GlobalHeader";
+import { GlobalHeaderSearch } from "./components/global-header/GlobalHeaderSearch";
+import { type SearchOption } from "./components/search/GlobalSearch";
+import { HeaderUtilities } from "./components/global-header/HeaderUtilities";
+
+/** Local drawer type (replaces Cloudscape AppLayoutToolbarProps.Drawer) */
+interface Drawer {
+  id: string;
+  ariaLabels?: {
+    drawerName?: string;
+    triggerButton?: string;
+    closeButton?: string;
+  };
+  trigger?: {
+    iconName?: string;
+    iconSvg?: React.ReactNode;
+  };
+  content?: React.ReactNode;
+  defaultSize?: number;
+}
+
+export interface AppShellProps {
+  /** The name of the current service, displayed in the side navigation header */
+  serviceName: string;
+
+  /** Main content to render in the content area */
+  children: React.ReactNode;
+
+  /** Platform identity/branding shown in the top-left of the global header */
+  identity?: GlobalHeaderIdentity;
+
+  /** Breadcrumb trail for hierarchical navigation within the service */
+  breadcrumbs?: BreadcrumbItem[];
+
+  /** Navigation items for the left side navigation panel */
+  navigationItems?: ReadonlyArray<CompatibleNavigationItem>;
+
+  /** Link destination when clicking the service name in side navigation */
+  navigationHeaderHref?: string;
+
+  /** Currently active navigation item href for highlighting */
+  navigationActiveHref?: string;
+
+  /** Callback when a navigation item is clicked */
+  onNavigationFollow?: (event: CompatibleNavigationFollowEvent) => void;
+
+  /** Callback when a breadcrumb is clicked */
+  onBreadcrumbFollow?: (event: React.MouseEvent, item: BreadcrumbItem) => void;
+
+  /** Optional header content displayed above the main content */
+  contentHeader?: React.ReactNode;
+
+  /** Tools panel content (right side panel) */
+  tools?: React.ReactNode;
+
+  /** Content for the chatbot/assistant drawer */
+  drawerContent?: React.ReactNode;
+
+  /** Flash notifications to display at the top of the content area */
+  notifications?: FlashbarMessage[];
+
+  /** Whether to disable default content padding */
+  disableContentPaddings?: boolean;
+
+  /** Maximum width of the content area in pixels */
+  maxContentWidth?: number;
+
+  /** Minimum width of the content area in pixels */
+  minContentWidth?: number;
+
+  /**
+   * Callback when the user types in the global search bar.
+   * Search results should display available services matching the query.
+   */
+  onSearch?: (value: string) => void;
+
+  /** Callback when a search result is selected */
+  onSearchSelect?: (service: ServiceItem) => void;
+
+  /** Controlled value for the search input */
+  searchValue?: string;
+
+  /** Placeholder text for the search input */
+  searchPlaceholder?: string;
+
+  /**
+   * Menu items for the All Services button (9-dot grid icon).
+   * Displays all available platform services and recently visited services.
+   */
+  appsMenuItems?: MenuDropdownItems;
+
+  /**
+   * Menu items for the Categories button.
+   * Displays the available service categories.
+   */
+  categoriesMenuItems?: MenuDropdownItems;
+
+  /**
+   * Menu items for the Settings dropdown.
+   * Contains user preferences, notifications settings, and integrations.
+   */
+  settingsMenuItems?: MenuDropdownItems;
+
+  /**
+   * Menu items for the User Profile dropdown.
+   * Contains account settings, profile info, and sign out option.
+   */
+  userMenuItems?: MenuDropdownItems;
+
+  /** Callback when an item in the All Services menu is clicked */
+  onAppsMenuItemClick?: MenuItemClickHandler;
+
+  /** Callback when an item in the Categories menu is clicked */
+  onCategoriesMenuItemClick?: MenuItemClickHandler;
+
+  /** Callback when an item in the Settings menu is clicked */
+  onSettingsMenuItemClick?: MenuItemClickHandler;
+
+  /** Callback when an item in the User menu is clicked */
+  onUserMenuItemClick?: MenuItemClickHandler;
+
+  /** Callback to toggle between light and dark theme */
+  onThemeToggle?: () => void;
+
+  /** Current theme mode */
+  theme?: "light" | "dark";
+
+  /** Show the theme toggle button in the global header */
+  showThemeToggle?: boolean;
+
+  /** Icons to display for theme toggle button in each mode (as React nodes) */
+  themeIcons?: {
+    light: React.ReactNode;
+    dark: React.ReactNode;
+  };
+
+  /** Default open state for left navigation when no persisted state exists */
+  defaultNavigationOpen?: boolean;
+
+  /** Default open state for right drawer when no persisted state exists */
+  defaultDrawerOpen?: boolean;
+
+  /** Default drawer id to open when no persisted state exists */
+  defaultDrawerId?: string | null;
+}
+
+/** Default placeholder menu items when no items are provided */
+const EMPTY_MENU_ITEMS: MenuDropdownItems = [
+  { id: "empty", text: "No items", disabled: true },
+];
+
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+
+const THEME_ICON_SUN = (
+  <svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
+    <circle cx="8" cy="8" r="3" fill="none" stroke="currentColor" strokeWidth="1.5" />
+    <path
+      d="M8 1.5v2M8 12.5v2M1.5 8h2M12.5 8h2M3.1 3.1l1.4 1.4M11.5 11.5l1.4 1.4M12.9 3.1l-1.4 1.4M4.5 11.5l-1.4 1.4"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+    />
+  </svg>
+);
+
+const THEME_ICON_MOON = (
+  <svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
+    <path
+      d="M11.5 10.5A5.5 5.5 0 0 1 5.5 4.5a5 5 0 1 0 6 6Z"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+type PanelState = {
+  version: number;
+  navigationOpen: boolean;
+  toolsOpen: boolean;
+  drawerOpen: boolean;
+  drawerId: string | null;
+  timestamp: number;
+};
+
+const PANEL_STATE_STORAGE_KEY = "app-shell.panelState";
+const PANEL_STATE_VERSION = 1;
+
+const isPanelState = (value: unknown): value is PanelState => {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.version === "number" &&
+    typeof record.navigationOpen === "boolean" &&
+    typeof record.toolsOpen === "boolean" &&
+    typeof record.drawerOpen === "boolean" &&
+    (typeof record.drawerId === "string" || record.drawerId === null) &&
+    typeof record.timestamp === "number"
+  );
+};
+
+const panelStateStore = {
+  read(): PanelState | null {
+    if (typeof window === "undefined") return null;
+    try {
+      const raw = window.localStorage.getItem(PANEL_STATE_STORAGE_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return isPanelState(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  },
+  write(state: PanelState) {
+    if (typeof window === "undefined") return;
+    try {
+      window.localStorage.setItem(PANEL_STATE_STORAGE_KEY, JSON.stringify(state));
+    } catch {
+      // Ignore storage failures (private mode, quota, etc.)
+    }
+  },
+};
+
+export function AppShell({
+  serviceName,
+  children,
+  identity,
+  breadcrumbs,
+  navigationItems,
+  navigationHeaderHref,
+  navigationActiveHref,
+  onNavigationFollow,
+  onBreadcrumbFollow,
+  contentHeader,
+  tools,
+  drawerContent,
+  notifications,
+  disableContentPaddings,
+  maxContentWidth,
+  minContentWidth,
+  onSearch,
+  onSearchSelect,
+  searchValue,
+  searchPlaceholder,
+  appsMenuItems,
+  categoriesMenuItems,
+  settingsMenuItems,
+  userMenuItems,
+  onAppsMenuItemClick,
+  onCategoriesMenuItemClick,
+  onSettingsMenuItemClick,
+  onUserMenuItemClick,
+  onThemeToggle,
+  theme = "light",
+  showThemeToggle = true,
+  themeIcons,
+  defaultNavigationOpen = true,
+  defaultDrawerOpen = false,
+  defaultDrawerId = null,
+}: AppShellProps) {
+  const isThemeControlled = Boolean(onThemeToggle);
+  const [internalTheme, setInternalTheme] = React.useState<"light" | "dark">(
+    theme ?? "light",
+  );
+  const resolvedTheme = isThemeControlled ? (theme ?? "light") : internalTheme;
+
+  // Apply theme mode (light/dark) to the document before paint
+  useIsomorphicLayoutEffect(() => {
+    if (resolvedTheme === "dark") {
+      document.documentElement.classList.add("dark");
+    } else {
+      document.documentElement.classList.remove("dark");
+    }
+  }, [resolvedTheme]);
+
+  // Inject global styles to force dark dropdown backgrounds
+  // CRITICAL: Only target dropdown portals that are DIRECT children of body
+  // to avoid affecting table cells which also use "interior" class patterns
+  React.useEffect(() => {
+    const styleId = 'app-shell-dropdown-overrides';
+    if (document.getElementById(styleId)) return;
+
+    const style = document.createElement('style');
+    style.id = styleId;
+    // SCOPED: Use body > div[class*="awsui_dropdown"] to ONLY target dropdown portals
+    // NOT body > div[class*="awsui"] which is too broad
+    style.textContent = `
+      /* Force dark background ONLY on dropdown portals (direct children of body with dropdown class) */
+      body > div[class*="awsui_dropdown"] [class*="awsui_dropdown-content-wrapper"],
+      body > div[class*="awsui_dropdown"] [class*="awsui_interior"],
+      body > div[class*="awsui_dropdown"] [class*="awsui_options-list"],
+      body > div[class*="awsui_dropdown"] [class*="awsui_items-list-container"],
+      body > div[class*="awsui_dropdown"] ul {
+        background-color: #171717 !important;
+        background: #171717 !important;
+        color: #f5f5f5 !important;
+      }
+      body > div[class*="awsui_dropdown"] [class*="awsui_option"],
+      body > div[class*="awsui_dropdown"] [class*="awsui_item-element"],
+      body > div[class*="awsui_dropdown"] li {
+        background-color: transparent !important;
+        background: transparent !important;
+        color: #f5f5f5 !important;
+      }
+      body > div[class*="awsui_dropdown"] [class*="awsui_option"]:hover,
+      body > div[class*="awsui_dropdown"] [class*="awsui_item-element"]:hover,
+      body > div[class*="awsui_dropdown"] [class*="awsui_highlighted"],
+      body > div[class*="awsui_dropdown"] li:hover {
+        background-color: transparent !important;
+        background: transparent !important;
+        color: #26c6ff !important;
+      }
+    `;
+    document.head.appendChild(style);
+
+    return () => {
+      const el = document.getElementById(styleId);
+      if (el) el.remove();
+    };
+  }, []);
+
+  // Use MutationObserver to forcibly remove border-radius from dropdown elements
+  // CRITICAL: Only target dropdown portals that are DIRECT children of body
+  // to avoid affecting table cells which also use similar class patterns
+  React.useEffect(() => {
+    // Helper to check if element is inside a dropdown portal that's a DIRECT child of body
+    const isInsideBodyDropdownPortal = (element: Element): boolean => {
+      let current: Element | null = element;
+      while (current && current !== document.body) {
+        const parentElement: Element | null = current.parentElement;
+        if (parentElement === document.body) {
+          // current is a direct child of body - check if it's a dropdown portal
+          const className = current.className || "";
+          // Only match if the direct body child has "dropdown" in its class
+          return className.includes("awsui") && className.includes("dropdown");
+        }
+        current = parentElement;
+      }
+      return false;
+    };
+
+    const styleDropdownElement = (element: Element) => {
+      if (!(element instanceof HTMLElement)) return;
+
+      // CRITICAL: Only process elements inside dropdown portals that are direct children of body
+      // This prevents styling table cells which are NOT direct children of body
+      if (!isInsideBodyDropdownPortal(element)) return;
+
+      const className = element.className || "";
+
+      // Remove border-radius from elements inside dropdown portal
+      element.style.setProperty('border-radius', '0', 'important');
+
+      // Force dark background for dropdown containers
+      if (className.includes("content-wrapper") ||
+          className.includes("interior") ||
+          className.includes("options-list") ||
+          className.includes("items-list")) {
+        element.style.setProperty('background-color', '#171717', 'important');
+        element.style.setProperty('color', '#f5f5f5', 'important');
+        element.style.setProperty('border', 'none', 'important');
+      }
+
+      // Force dark background on ul elements
+      if (element.tagName === "UL") {
+        element.style.setProperty('background-color', '#171717', 'important');
+        element.style.setProperty('color', '#f5f5f5', 'important');
+      }
+    };
+
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node instanceof Element) {
+            // Only process if element is a body > div dropdown portal or inside one
+            if (node.parentElement === document.body) {
+              const className = node.className || "";
+              if (className.includes("awsui") && className.includes("dropdown")) {
+                styleDropdownElement(node);
+                node.querySelectorAll("*").forEach(styleDropdownElement);
+              }
+            } else if (isInsideBodyDropdownPortal(node)) {
+              styleDropdownElement(node);
+              node.querySelectorAll("*").forEach(styleDropdownElement);
+            }
+          }
+        });
+      });
+    });
+
+    // Only observe direct children of body for efficiency
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+
+    // Process any existing dropdown portals that are direct children of body
+    // Note: Use document.body.querySelectorAll so :scope resolves to <body>, not <html>
+    document.body.querySelectorAll(':scope > div[class*="awsui"][class*="dropdown"]').forEach((portal) => {
+      styleDropdownElement(portal);
+      portal.querySelectorAll("*").forEach(styleDropdownElement);
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  // State for collapsible panels (hydrated from persisted storage when available)
+  const fallbackDrawerId = defaultDrawerId ?? (drawerContent ? "chatbot" : tools ? "tools" : null);
+  const initialPanelState = React.useMemo(() => {
+    const stored = panelStateStore.read();
+    return {
+      navigationOpen: stored?.navigationOpen ?? defaultNavigationOpen,
+      toolsOpen: stored?.toolsOpen ?? false,
+      drawerOpen: stored?.drawerOpen ?? defaultDrawerOpen,
+      drawerId: stored?.drawerId ?? fallbackDrawerId,
+    };
+  }, [defaultNavigationOpen, defaultDrawerOpen, fallbackDrawerId]);
+
+  const [navigationOpen, setNavigationOpen] = React.useState(
+    initialPanelState.navigationOpen,
+  );
+  const [toolsOpen, setToolsOpen] = React.useState(
+    initialPanelState.toolsOpen,
+  );
+  const [activeDrawerId, setActiveDrawerId] = React.useState<string | null>(
+    initialPanelState.drawerOpen ? initialPanelState.drawerId ?? null : null,
+  );
+  const lastDrawerIdRef = React.useRef<string | null>(
+    initialPanelState.drawerId ?? fallbackDrawerId,
+  );
+
+  React.useEffect(() => {
+    if (activeDrawerId) {
+      lastDrawerIdRef.current = activeDrawerId;
+    }
+  }, [activeDrawerId]);
+
+  const [serviceCatalog, setServiceCatalog] = React.useState(() =>
+    getServiceCatalogSync(),
+  );
+
+  React.useEffect(() => {
+    if (!serviceCatalog) {
+      getServiceCatalog()
+        .then((catalog) => setServiceCatalog(catalog))
+        .catch(() => {
+          // Swallow catalog loading errors for now (mock data only).
+        });
+    }
+  }, [serviceCatalog]);
+
+  // Internal search state for uncontrolled mode
+  const [internalSearch, setInternalSearch] = React.useState("");
+
+  // Support both controlled and uncontrolled search input
+  const isSearchControlled = typeof searchValue === "string";
+  const searchInputValue = isSearchControlled ? searchValue : internalSearch;
+
+  const serviceGroups = React.useMemo(
+    () => (serviceCatalog ? groupServicesByCategory(serviceCatalog) : []),
+    [serviceCatalog],
+  );
+
+  const serviceById = React.useMemo(() => {
+    if (!serviceCatalog) return new Map<string, ServiceItem>();
+    return new Map(serviceCatalog.services.map((service) => [service.id, service]));
+  }, [serviceCatalog]);
+
+  const categoryLabels = React.useMemo(() => {
+    if (!serviceCatalog) return new Map<string, string>();
+    return new Map(
+      serviceCatalog.categories.map((category) => [category.id, category.label]),
+    );
+  }, [serviceCatalog]);
+
+  const catalogMenuItems = React.useMemo<MenuDropdownItems>(() => {
+    if (!serviceCatalog) {
+      return [{ id: "loading", text: "Loading services", disabled: true }];
+    }
+
+    return serviceGroups.map((group) => ({
+      type: "group",
+      text: group.category.label,
+      items: group.services.map((service) => ({
+        id: service.id,
+        text: service.name,
+        description: service.summary,
+        href: service.href,
+      })),
+    }));
+  }, [serviceCatalog, serviceGroups]);
+
+  const catalogCategoryMenuItems = React.useMemo<MenuDropdownItems>(() => {
+    if (!serviceCatalog) {
+      return [{ id: "loading", text: "Loading categories", disabled: true }];
+    }
+
+    const categoryHrefById = new Map<string, string>();
+
+    for (const group of serviceGroups) {
+      const serviceHref = group.services[0]?.href;
+      if (serviceHref && serviceHref.startsWith("/")) {
+        const rootSegment = serviceHref.split("/").filter(Boolean)[0];
+        if (rootSegment) {
+          categoryHrefById.set(group.category.id, `/${rootSegment}/`);
+        }
+      }
+    }
+
+    return serviceCatalog.categories.map((category) => ({
+      id: category.id,
+      text: category.label,
+      description: category.description,
+      href: categoryHrefById.get(category.id),
+    }));
+  }, [serviceCatalog, serviceGroups]);
+
+  const hasSearchQuery = searchInputValue.trim().length > 0;
+
+  const searchResults = React.useMemo(() => {
+    if (!serviceCatalog || !hasSearchQuery) return [];
+    return searchServices(serviceCatalog, searchInputValue);
+  }, [serviceCatalog, searchInputValue, hasSearchQuery]);
+
+  const searchOptions = React.useMemo<SearchOption[]>(() => {
+    if (!serviceCatalog || !hasSearchQuery) return [];
+    return searchResults.map((service) => ({
+      value: service.id,
+      label: service.name,
+      description: service.summary,
+      tags: [categoryLabels.get(service.categoryId) ?? "Service"],
+    }));
+  }, [serviceCatalog, searchResults, categoryLabels, hasSearchQuery]);
+
+  const handleSearchValueChange = (value: string) => {
+    if (!isSearchControlled) {
+      setInternalSearch(value);
+    }
+    onSearch?.(value);
+  };
+
+  const handleSearchSelect = (option: SearchOption) => {
+    const selectedService = serviceById.get(option.value);
+    if (!selectedService) {
+      return;
+    }
+
+    if (!isSearchControlled) {
+      setInternalSearch(selectedService.name);
+    }
+
+    onSearch?.(selectedService.name);
+
+    if (onSearchSelect) {
+      onSearchSelect(selectedService);
+      return;
+    }
+
+    if (selectedService.href) {
+      window.location.assign(selectedService.href);
+    }
+  };
+
+  /*
+   * Side Navigation Panel
+   * ---------------------
+   * Left-side collapsible panel containing service-specific navigation.
+   * Shows the service name in the header and hierarchical navigation items.
+   */
+  // Cast to internal type - both Cloudscape and custom types share the same shape
+  const normalizedNavigationItems = (navigationItems ?? []) as ReadonlyArray<NavigationItem>;
+
+  // Adapter to normalize Cloudscape CustomEvent to our NavigationFollowEvent
+  const handleNavigationFollow = onNavigationFollow
+    ? (event: NavigationFollowEvent) => {
+        onNavigationFollow(event as CompatibleNavigationFollowEvent);
+      }
+    : undefined;
+
+  const navigation = (
+    <AppNavigation
+      serviceName={serviceName}
+      headerHref={navigationHeaderHref ?? "#"}
+      items={normalizedNavigationItems}
+      activeHref={navigationActiveHref}
+      onFollow={handleNavigationFollow}
+      onClose={() => setNavigationOpen(false)}
+      basePath={basePath()}
+    />
+  );
+
+  // Breadcrumb navigation for hierarchical page structure
+  const breadcrumbsItems: BreadcrumbItem[] = breadcrumbs ?? [];
+  const breadcrumbsNode = breadcrumbsItems.length ? (
+    <AppBreadcrumb items={breadcrumbsItems} onFollow={onBreadcrumbFollow} />
+  ) : undefined;
+
+  const resolvedAppsMenuItems = appsMenuItems ?? catalogMenuItems ?? EMPTY_MENU_ITEMS;
+  const resolvedCategoriesMenuItems =
+    categoriesMenuItems ?? catalogCategoryMenuItems ?? EMPTY_MENU_ITEMS;
+  const resolvedIdentity =
+    identity ?? {
+      logo: {
+        src: "https://reactrouter.com/_brand/React%20Router%20Brand%20Assets/React%20Router%20Lockup/Dark.svg",
+        alt: "Untitled",
+      },
+      href: "/",
+    };
+
+  /*
+   * Top Navigation Utilities (Right Side)
+   * -------------------------------------
+   * Utility buttons displayed on the right side of the global header:
+   * 1. Settings - User preferences, notifications, integrations
+   * 2. Theme Toggle - Switch between light and dark mode (optional)
+   * 3. User Profile - Account settings, profile, sign out
+   */
+  const handleThemeToggle = onThemeToggle ?? (() => {
+    setInternalTheme((prev) => (prev === "dark" ? "light" : "dark"));
+  });
+
+  // Pass through the click handlers directly - they now use the same signature
+  const handleSettingsItemClick = onSettingsMenuItemClick;
+  const handleUserItemClick = onUserMenuItemClick;
+
+  const utilitiesContent = (
+    <HeaderUtilities
+      settingsItems={settingsMenuItems ?? EMPTY_MENU_ITEMS}
+      onSettingsItemClick={handleSettingsItemClick}
+      userItems={userMenuItems ?? EMPTY_MENU_ITEMS}
+      onUserItemClick={handleUserItemClick}
+      showThemeToggle={showThemeToggle}
+      theme={resolvedTheme}
+      onThemeToggle={handleThemeToggle}
+      themeIcons={themeIcons ?? {
+        light: THEME_ICON_SUN,
+        dark: THEME_ICON_MOON,
+      }}
+    />
+  );
+
+  /*
+   * Search Area Content (Center of Global Header)
+   * ----------------------------------------------
+   * Contains:
+   * 1. Visual separator (|)
+   * 2. Services Menu (9-dot grid) - Combined dropdown with categories on the
+   *    left and all services on the right for quick navigation
+   * 3. Global Search Bar - Allows users to search for services, features,
+   *    or content across the platform
+   */
+  const searchContent = (
+    <GlobalHeaderSearch
+      appsMenuItems={resolvedAppsMenuItems}
+      onAppsMenuItemClick={onAppsMenuItemClick}
+      categoriesMenuItems={resolvedCategoriesMenuItems}
+      onCategoriesMenuItemClick={onCategoriesMenuItemClick}
+      searchValue={searchInputValue}
+      onSearchChange={handleSearchValueChange}
+      onSearchSelect={handleSearchSelect}
+      searchPlaceholder={searchPlaceholder ?? "Search"}
+      searchOptions={searchOptions}
+      empty={hasSearchQuery ? "No matches" : undefined}
+      loading={!serviceCatalog && hasSearchQuery}
+    />
+  );
+
+  const drawers: Drawer[] = [];
+
+  if (tools) {
+    drawers.push({
+      id: "tools",
+      ariaLabels: {
+        drawerName: "Tools",
+        triggerButton: "Open tools",
+        closeButton: "Close tools",
+      },
+      trigger: { iconName: "settings" },
+      content: tools,
+    });
+  }
+
+  if (drawerContent) {
+    drawers.push({
+      id: "chatbot",
+      ariaLabels: {
+        drawerName: "Chatbot",
+        triggerButton: "Open chatbot",
+        closeButton: "Close chatbot",
+      },
+      defaultSize: 420,
+      trigger: {
+        iconSvg: (
+          <svg width="24" height="24" viewBox="0 0 24 24" fill="white">
+            <path d="M20 2H4C2.9 2 2 2.9 2 4V16C2 17.1 2.9 18 4 18H18L22 22V4C22 2.9 21.1 2 20 2Z" />
+          </svg>
+        ),
+      },
+      content: activeDrawerId === "chatbot" ? drawerContent : null,
+    });
+  }
+
+
+
+  React.useEffect(() => {
+    if (!activeDrawerId) return;
+    const isValidDrawer = drawers.some((drawer) => drawer.id === activeDrawerId);
+    if (!isValidDrawer) {
+      setActiveDrawerId(null);
+    }
+  }, [activeDrawerId, drawers]);
+
+  React.useEffect(() => {
+    const drawerIdForStorage = activeDrawerId ?? lastDrawerIdRef.current ?? null;
+    panelStateStore.write({
+      version: PANEL_STATE_VERSION,
+      navigationOpen,
+      toolsOpen,
+      drawerOpen: Boolean(activeDrawerId),
+      drawerId: drawerIdForStorage,
+      timestamp: Date.now(),
+    });
+  }, [navigationOpen, toolsOpen, activeDrawerId]);
+
+  return (
+    // suppressHydrationWarning is needed because browser extensions (Dashlane, 1Password, etc.)
+    // inject data attributes before React hydrates, causing hydration mismatches
+    <div className="app-shell" suppressHydrationWarning>
+      {/*
+       * Global Header
+       * -------------
+       * Sticky header at the top of the page containing:
+       * - Platform identity/branding (left)
+       * - All Services button and search bar (center)
+       * - Settings, theme toggle, and user profile (right)
+       */}
+      <GlobalHeader
+        identity={resolvedIdentity}
+        search={searchContent}
+        utilities={utilitiesContent}
+      />
+
+      {/*
+       * Main Application Layout
+       * -----------------------
+       * Custom layout with shadcn Sidebar:
+       * - Collapsible side navigation (left)
+       * - Main content area (center)
+       */}
+      <AppLayout
+        navigation={navigation}
+        navigationOpen={navigationOpen}
+        onNavigationChange={setNavigationOpen}
+        tools={tools}
+        toolsOpen={toolsOpen}
+        onToolsChange={setToolsOpen}
+        copilot={drawerContent}
+        copilotOpen={activeDrawerId === "chatbot"}
+        onCopilotChange={(open) => {
+          setActiveDrawerId(open ? "chatbot" : null);
+        }}
+        copilotHide={!drawerContent}
+        breadcrumbs={breadcrumbsNode}
+        notifications={notifications ? <AppFlashbar items={notifications} /> : undefined}
+        contentHeader={contentHeader}
+        disableContentPaddings={disableContentPaddings}
+        maxContentWidth={maxContentWidth}
+        minContentWidth={minContentWidth}
+      >
+        {children}
+      </AppLayout>
+    </div>
+  );
+}