@jmruthers/pace-core 0.2.4

package/docs/implementation-guides/app-layout.md

@@ -0,0 +1,983 @@
+# App Layout Implementation Guide
+
+This guide covers how to implement application layouts using PACE Core's layout components with permission enforcement and responsive design.
+
+## Overview
+
+PACE Core provides comprehensive layout components that include:
+
+- **PaceAppLayout** - Complete application layout with header, navigation, and content
+- **Header** - Application header with navigation and user menu
+- **Footer** - Application footer component
+- **Permission-based layouts** - Different layouts for different user roles
+- **Responsive design** - Mobile-first responsive layouts
+- **Accessibility** - WCAG 2.1 AA compliant layouts
+
+## Basic Layout Setup
+
+### 1. Simple App Layout
+
+```tsx
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/" element={
+          <PaceAppLayout
+            appName="My Application"
+            navItems={navigationItems}
+          />
+        }>
+          <Route index element={<HomePage />} />
+          <Route path="dashboard" element={<DashboardPage />} />
+          <Route path="settings" element={<SettingsPage />} />
+        </Route>
+      </Routes>
+    </Router>
+  );
+}
+
+function HomePage() {
+  return (
+    <div className="p-6">
+      <h1>Welcome to My App</h1>
+      <p>Your application content goes here.</p>
+    </div>
+  );
+}
+```
+
+### 2. Layout with Custom Header
+
+```tsx
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+import { 
+  PaceAppLayout, 
+  Button 
+} from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/" element={
+          <PaceAppLayout
+            appName="My Application"
+            navItems={navigationItems}
+            headerActions={
+              <div className="flex items-center gap-2">
+                <Button variant="outline" size="sm">
+                  Help
+                </Button>
+              </div>
+            }
+          />
+        }>
+          <Route index element={<HomePage />} />
+          <Route path="dashboard" element={<DashboardPage />} />
+        </Route>
+      </Routes>
+    </Router>
+  );
+}
+
+function HomePage() {
+  return (
+    <div className="p-6">
+      <h1>Welcome to My App</h1>
+      <p>Your application content goes here.</p>
+    </div>
+  );
+}
+```
+
+## Advanced Layout Patterns
+
+### 1. Role-Based Layouts
+
+```tsx
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+import { PaceAppLayout, useRBAC } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/" element={<RoleBasedLayout />}>
+          <Route index element={<HomePage />} />
+          <Route path="dashboard" element={<DashboardPage />} />
+          <Route path="system-admin/*" element={<SystemAdminRoutes />} />
+          <Route path="org-admin/*" element={<OrgAdminRoutes />} />
+        </Route>
+      </Routes>
+    </Router>
+  );
+}
+
+function RoleBasedLayout() {
+  const { globalRole, organisationRole } = useRBAC();
+  
+  const getNavigationItems = () => {
+    const baseItems = [
+      { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: 'Home' }
+    ];
+
+    if (globalRole === 'super_admin') {
+      baseItems.push({
+        id: 'system-admin',
+        label: 'System Admin',
+        href: '/system-admin',
+        icon: 'Shield'
+      });
+    }
+
+    if (organisationRole === 'admin' || organisationRole === 'owner') {
+      baseItems.push({
+        id: 'org-admin',
+        label: 'Organisation Admin',
+        href: '/org-admin',
+        icon: 'Settings'
+      });
+    }
+
+    return baseItems;
+  };
+
+  return (
+    <PaceAppLayout
+      appName="My Application"
+      navItems={getNavigationItems()}
+    />
+  );
+}
+```
+
+### 2. Event-Aware Layout
+
+```tsx
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+import { 
+  PaceAppLayout, 
+  EventSelector,
+  useEvents 
+} from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/" element={<EventAwareLayout />}>
+          <Route index element={<EventDashboard />} />
+          <Route path="participants" element={<ParticipantsPage />} />
+          <Route path="schedule" element={<SchedulePage />} />
+          <Route path="settings" element={<EventSettingsPage />} />
+        </Route>
+      </Routes>
+    </Router>
+  );
+}
+
+function EventAwareLayout() {
+  const { selectedEvent, events } = useEvents();
+  
+  const eventNavigation = [
+    {
+      id: 'dashboard',
+      label: 'Event Dashboard',
+      href: '/',
+      icon: 'Home'
+    },
+    {
+      id: 'participants',
+      label: 'Participants',
+      href: '/participants',
+      icon: 'Users'
+    },
+    {
+      id: 'schedule',
+      label: 'Schedule',
+      href: '/schedule',
+      icon: 'Calendar'
+    },
+    {
+      id: 'settings',
+      label: 'Settings',
+      href: '/settings',
+      icon: 'Settings'
+    }
+  ];
+
+  return (
+    <PaceAppLayout
+      appName="Event Management"
+      navItems={eventNavigation}
+      showEventSelector={true}
+    />
+  );
+}
+
+function EventDashboard() {
+  const { selectedEvent } = useEvents();
+  
+  return (
+    <div className="p-6">
+      <h1>Event: {selectedEvent?.name}</h1>
+      <p>Event management content goes here.</p>
+    </div>
+  );
+}
+```
+
+### 3. Organisation-Aware Layout
+
+```tsx
+import { 
+  PaceAppLayout, 
+  OrganisationSelector,
+  useOrganisations 
+} from '@jmruthers/pace-core';
+
+function OrganisationAwareLayout() {
+  const { selectedOrganisation, organisations } = useOrganisations();
+  
+  const orgNavigation = [
+    {
+      label: 'Organisation Dashboard',
+      href: `/organisations/${selectedOrganisation?.id}/dashboard`,
+      icon: 'Home'
+    },
+    {
+      label: 'Members',
+      href: `/organisations/${selectedOrganisation?.id}/members`,
+      icon: 'Users'
+    },
+    {
+      label: 'Events',
+      href: `/organisations/${selectedOrganisation?.id}/events`,
+      icon: 'Calendar'
+    },
+    {
+      label: 'Settings',
+      href: `/organisations/${selectedOrganisation?.id}/settings`,
+      icon: 'Settings'
+    }
+  ];
+
+  return (
+    <PaceAppLayout
+      title="Organisation Management"
+      user={user}
+      onLogout={handleLogout}
+      navigation={orgNavigation}
+      headerActions={
+        <OrganisationSelector
+          organisations={organisations}
+          selectedOrganisation={selectedOrganisation}
+          onOrganisationChange={setSelectedOrganisation}
+        />
+      }
+    >
+      <div className="p-6">
+        <h1>Organisation: {selectedOrganisation?.name}</h1>
+        <p>Organisation management content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+## Responsive Layouts
+
+### 1. Mobile-First Layout
+
+```tsx
+import { 
+  PaceAppLayout, 
+  Button,
+  Dialog,
+  DialogTrigger,
+  DialogContent 
+} from '@jmruthers/pace-core';
+import { Menu, X } from 'lucide-react';
+
+function MobileFirstLayout() {
+  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
+
+  const mobileHeader = (
+    <Header
+      title="My App"
+      user={user}
+      onLogout={handleLogout}
+      actions={
+        <div className="flex items-center gap-2">
+          <Dialog open={isMobileMenuOpen} onOpenChange={setIsMobileMenuOpen}>
+            <DialogTrigger asChild>
+              <Button variant="ghost" size="icon" className="lg:hidden">
+                <Menu className="h-6 w-6" />
+              </Button>
+            </DialogTrigger>
+            <DialogContent className="w-80">
+              <div className="p-4">
+                <NavigationMenu
+                  items={navigationItems}
+                  currentPath={pathname}
+                  onNavigate={(href) => {
+                    router.push(href);
+                    setIsMobileMenuOpen(false);
+                  }}
+                  orientation="vertical"
+                />
+              </div>
+            </DialogContent>
+          </Dialog>
+        </div>
+      }
+    />
+  );
+
+  return (
+    <PaceAppLayout
+      header={mobileHeader}
+      navigation={navigationItems}
+      className="lg:flex lg:flex-row"
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 2. Sidebar Layout
+
+```tsx
+import { PaceAppLayout, Card } from '@jmruthers/pace-core';
+
+function SidebarLayout() {
+  return (
+    <div className="flex h-screen">
+      <aside className="w-64 bg-sec-50 border-r">
+        <Card className="h-full rounded-none border-0">
+          <div className="p-4">
+            <h2 className="text-lg font-semibold mb-4">Navigation</h2>
+            <NavigationMenu
+              items={navigationItems}
+              currentPath={pathname}
+              onNavigate={(href) => router.push(href)}
+              orientation="vertical"
+              showIcons={true}
+            />
+          </div>
+        </Card>
+      </aside>
+      
+      <main className="flex-1 overflow-auto">
+        <PaceAppLayout
+          title="My Application"
+          user={user}
+          onLogout={handleLogout}
+          hideNavigation={true}
+        >
+          <div className="p-6">
+            <h1>Welcome to My App</h1>
+            <p>Your application content goes here.</p>
+          </div>
+        </PaceAppLayout>
+      </main>
+    </div>
+  );
+}
+```
+
+### 3. Collapsible Sidebar
+
+```tsx
+import { PaceAppLayout, Button, Card } from '@jmruthers/pace-core';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+
+function CollapsibleSidebarLayout() {
+  const [isCollapsed, setIsCollapsed] = useState(false);
+
+  return (
+    <div className="flex h-screen">
+      <aside className={`transition-all duration-300 ${isCollapsed ? 'w-16' : 'w-64'} bg-sec-50 border-r`}>
+        <Card className="h-full rounded-none border-0">
+          <div className="p-4">
+            <div className="flex items-center justify-between mb-4">
+              {!isCollapsed && <h2 className="text-lg font-semibold">Navigation</h2>}
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={() => setIsCollapsed(!isCollapsed)}
+              >
+                {isCollapsed ? <ChevronRight /> : <ChevronLeft />}
+              </Button>
+            </div>
+            
+            <NavigationMenu
+              items={navigationItems}
+              currentPath={pathname}
+              onNavigate={(href) => router.push(href)}
+              orientation="vertical"
+              showIcons={isCollapsed}
+              className={isCollapsed ? 'px-2' : 'px-4'}
+            />
+          </div>
+        </Card>
+      </aside>
+      
+      <main className="flex-1 overflow-auto">
+        <PaceAppLayout
+          title="My Application"
+          user={user}
+          onLogout={handleLogout}
+          hideNavigation={true}
+        >
+          <div className="p-6">
+            <h1>Welcome to My App</h1>
+            <p>Your application content goes here.</p>
+          </div>
+        </PaceAppLayout>
+      </main>
+    </div>
+  );
+}
+```
+
+## Layout with Permission Enforcement
+
+### 1. Page-Level Permissions
+
+```tsx
+import { 
+  PaceAppLayout, 
+  PagePermissionGuard 
+} from '@jmruthers/pace-core';
+
+function ProtectedLayout() {
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+    >
+      <PagePermissionGuard
+        pageName="dashboard"
+        requiredPermissions={['read:dashboard']}
+        fallback={<div>You don't have permission to access this page.</div>}
+      >
+        <div className="p-6">
+          <h1>Dashboard</h1>
+          <p>Protected dashboard content goes here.</p>
+        </div>
+      </PagePermissionGuard>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 2. Component-Level Permissions
+
+```tsx
+import { 
+  PaceAppLayout, 
+  PermissionEnforcer 
+} from '@jmruthers/pace-core';
+
+function ComponentProtectedLayout() {
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+    >
+      <div className="p-6">
+        <h1>Dashboard</h1>
+        
+        <PermissionEnforcer
+          operation="read"
+          resource="dashboard"
+          fallback={<div>You don't have permission to view the dashboard.</div>}
+        >
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+            <Card>
+              <CardHeader>
+                <CardTitle>Overview</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <p>Dashboard overview content</p>
+              </CardContent>
+            </Card>
+            
+            <PermissionEnforcer
+              operation="read"
+              resource="analytics"
+              fallback={<div>Analytics not available</div>}
+            >
+              <Card>
+                <CardHeader>
+                  <CardTitle>Analytics</CardTitle>
+                </CardHeader>
+                <CardContent>
+                  <p>Analytics content</p>
+                </CardContent>
+              </Card>
+            </PermissionEnforcer>
+          </div>
+        </PermissionEnforcer>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 3. Conditional Layout Elements
+
+```tsx
+import { 
+  PaceAppLayout, 
+  useCan 
+} from '@jmruthers/pace-core';
+
+function ConditionalLayout() {
+  const { hasPermission } = useCan();
+  
+  const getHeaderActions = () => {
+    const actions = [];
+    
+    if (hasPermission('create', 'users')) {
+      actions.push(
+        <Button key="add-user" variant="outline" size="sm">
+          Add User
+        </Button>
+      );
+    }
+    
+    if (hasPermission('read', 'settings')) {
+      actions.push(
+        <Button key="settings" variant="ghost" size="sm">
+          Settings
+        </Button>
+      );
+    }
+    
+    return actions;
+  };
+
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+      headerActions={getHeaderActions()}
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+## Layout State Management
+
+### 1. Layout Context
+
+```tsx
+import { createContext, useContext, useState } from 'react';
+
+interface LayoutContextType {
+  isSidebarOpen: boolean;
+  toggleSidebar: () => void;
+  isMobileMenuOpen: boolean;
+  toggleMobileMenu: () => void;
+  activePage: string | null;
+  setActivePage: (page: string | null) => void;
+}
+
+const LayoutContext = createContext<LayoutContextType | null>(null);
+
+export function LayoutProvider({ children }: { children: React.ReactNode }) {
+  const [isSidebarOpen, setIsSidebarOpen] = useState(true);
+  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
+  const [activePage, setActivePage] = useState<string | null>(null);
+
+  const toggleSidebar = () => setIsSidebarOpen(!isSidebarOpen);
+  const toggleMobileMenu = () => setIsMobileMenuOpen(!isMobileMenuOpen);
+
+  return (
+    <LayoutContext.Provider value={{
+      isSidebarOpen,
+      toggleSidebar,
+      isMobileMenuOpen,
+      toggleMobileMenu,
+      activePage,
+      setActivePage
+    }}>
+      {children}
+    </LayoutContext.Provider>
+  );
+}
+
+export function useLayout() {
+  const context = useContext(LayoutContext);
+  if (!context) {
+    throw new Error('useLayout must be used within LayoutProvider');
+  }
+  return context;
+}
+```
+
+### 2. Layout with State
+
+```tsx
+import { PaceAppLayout, useLayout } from '@jmruthers/pace-core';
+
+function StatefulLayout() {
+  const { isSidebarOpen, toggleSidebar, activePage, setActivePage } = useLayout();
+
+  const handleNavigate = (href: string) => {
+    setActivePage(href);
+    router.push(href);
+  };
+
+  return (
+    <div className="flex h-screen">
+      <aside className={`transition-all duration-300 ${isSidebarOpen ? 'w-64' : 'w-16'} bg-sec-50 border-r`}>
+        <Card className="h-full rounded-none border-0">
+          <div className="p-4">
+            <div className="flex items-center justify-between mb-4">
+              {isSidebarOpen && <h2 className="text-lg font-semibold">Navigation</h2>}
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={toggleSidebar}
+              >
+                {isSidebarOpen ? <ChevronLeft /> : <ChevronRight />}
+              </Button>
+            </div>
+            
+            <NavigationMenu
+              items={navigationItems}
+              currentPath={activePage || pathname}
+              onNavigate={handleNavigate}
+              orientation="vertical"
+              showIcons={!isSidebarOpen}
+              className={isSidebarOpen ? 'px-4' : 'px-2'}
+            />
+          </div>
+        </Card>
+      </aside>
+      
+      <main className="flex-1 overflow-auto">
+        <PaceAppLayout
+          title="My Application"
+          user={user}
+          onLogout={handleLogout}
+          hideNavigation={true}
+        >
+          <div className="p-6">
+            <h1>Welcome to My App</h1>
+            <p>Your application content goes here.</p>
+          </div>
+        </PaceAppLayout>
+      </main>
+    </div>
+  );
+}
+```
+
+## Layout Customization
+
+### 1. Custom Styling
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function CustomStyledLayout() {
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+      className="bg-sec-50"
+      headerClassName="bg-main-50 shadow-sm"
+      navigationClassName="bg-sec-100"
+      contentClassName="bg-main-50"
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 2. Custom Header Component
+
+```tsx
+import { PaceAppLayout, Header, UserMenu, Button } from '@jmruthers/pace-core';
+
+function CustomHeaderLayout() {
+  const customHeader = (
+    <Header
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      className="bg-gradient-to-r from-main-600 to-sec-600 text-main-50"
+      actions={
+        <div className="flex items-center gap-2">
+          <Button variant="ghost" size="sm" className="text-main-50 hover:bg-main-50/20">
+            Help
+          </Button>
+          <Button variant="ghost" size="sm" className="text-main-50 hover:bg-main-50/20">
+            Support
+          </Button>
+          <UserMenu
+            user={user}
+            onLogout={handleLogout}
+            onProfile={handleProfile}
+            className="text-main-50"
+          />
+        </div>
+      }
+    />
+  );
+
+  return (
+    <PaceAppLayout
+      header={customHeader}
+      navigation={navigationItems}
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 3. Custom Footer Component
+
+```tsx
+import { PaceAppLayout, Footer, Button } from '@jmruthers/pace-core';
+
+function CustomFooterLayout() {
+  const customFooter = (
+    <Footer className="bg-sec-900 text-main-50">
+      <div className="container mx-auto px-6 py-4">
+        <div className="flex items-center justify-between">
+          <div>
+            <p>&copy; 2024 My App. All rights reserved.</p>
+          </div>
+          <div className="flex items-center gap-4">
+            <Button variant="ghost" size="sm" className="text-main-50 hover:bg-main-50/20">
+              Privacy Policy
+            </Button>
+            <Button variant="ghost" size="sm" className="text-main-50 hover:bg-main-50/20">
+              Terms of Service
+            </Button>
+            <Button variant="ghost" size="sm" className="text-main-50 hover:bg-main-50/20">
+              Contact
+            </Button>
+          </div>
+        </div>
+      </div>
+    </Footer>
+  );
+
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+      footer={customFooter}
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+## Accessibility
+
+### 1. Skip Links
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function AccessibleLayout() {
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+      skipLinks={
+        <div className="sr-only focus:not-sr-only">
+          <a href="#main" className="block p-2 bg-main-600 text-main-50">
+            Skip to main content
+          </a>
+          <a href="#navigation" className="block p-2 bg-main-600 text-main-50">
+            Skip to navigation
+          </a>
+          <a href="#footer" className="block p-2 bg-main-600 text-main-50">
+            Skip to footer
+          </a>
+        </div>
+      }
+    >
+      <main id="main" className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </main>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 2. Focus Management
+
+```tsx
+import { PaceAppLayout, useLayout } from '@jmruthers/pace-core';
+
+function FocusManagedLayout() {
+  const { isMobileMenuOpen, toggleMobileMenu } = useLayout();
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape' && isMobileMenuOpen) {
+      toggleMobileMenu();
+    }
+  };
+
+  useEffect(() => {
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isMobileMenuOpen]);
+
+  return (
+    <PaceAppLayout
+      title="My Application"
+      user={user}
+      onLogout={handleLogout}
+      navigation={navigationItems}
+      onKeyDown={handleKeyDown}
+    >
+      <div className="p-6">
+        <h1>Welcome to My App</h1>
+        <p>Your application content goes here.</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+## Testing Layouts
+
+### 1. Unit Testing
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+test('renders layout with title and navigation', () => {
+  const navigationItems = [
+    { label: 'Dashboard', href: '/dashboard' },
+    { label: 'Users', href: '/users' }
+  ];
+
+  render(
+    <PaceAppLayout
+      title="My App"
+      user={mockUser}
+      onLogout={jest.fn()}
+      navigation={navigationItems}
+    >
+      <div>Test content</div>
+    </PaceAppLayout>
+  );
+
+  expect(screen.getByText('My App')).toBeInTheDocument();
+  expect(screen.getByText('Dashboard')).toBeInTheDocument();
+  expect(screen.getByText('Users')).toBeInTheDocument();
+  expect(screen.getByText('Test content')).toBeInTheDocument();
+});
+```
+
+### 2. Responsive Testing
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+test('renders mobile layout correctly', () => {
+  // Mock mobile viewport
+  Object.defineProperty(window, 'innerWidth', {
+    writable: true,
+    configurable: true,
+    value: 375,
+  });
+
+  render(
+    <PaceAppLayout
+      title="My App"
+      user={mockUser}
+      onLogout={jest.fn()}
+      navigation={navigationItems}
+    >
+      <div>Test content</div>
+    </PaceAppLayout>
+  );
+
+  // Check that mobile-specific elements are rendered
+  expect(screen.getByRole('button', { name: /menu/i })).toBeInTheDocument();
+});
+```
+
+## Best Practices
+
+### 1. Layout Structure
+
+- Use semantic HTML elements (header, nav, main, aside, footer)
+- Implement proper heading hierarchy
+- Provide clear navigation structure
+- Use consistent spacing and typography
+
+### 2. Responsive Design
+
+- Design mobile-first
+- Use flexible layouts that adapt to different screen sizes
+- Test on various devices and screen sizes
+- Implement proper touch targets for mobile
+
+### 3. Performance
+
+- Lazy load navigation items when possible
+- Use proper memoization for expensive operations
+- Optimize images and assets
+- Implement proper loading states
+
+### 4. Accessibility
+
+- Provide proper ARIA labels and roles
+- Implement keyboard navigation
+- Ensure sufficient color contrast
+- Test with screen readers
+
+For more advanced layout patterns and examples, see the [Layout Examples](../examples/layouts.md) guide.