Skip to content

APPLAYOUT_IMPLEMENTATION.md

Latest commit

 

History

History
339 lines (266 loc) · 9.09 KB

APPLAYOUT_IMPLEMENTATION.md

File metadata and controls

339 lines (266 loc) · 9.09 KB
Raw

Global Layout & Responsive Sidebar - Implementation Summary

Overview

Implemented a global application shell (AppLayout) with a responsive sidebar system that adapts to both desktop and mobile viewports. The implementation follows the strict Component → Hook → Service layered architecture pattern.

Implementation Details

Architecture: Component → Hook → Service Pattern ✓

1. Service Layer (services/layoutService.ts)

  • Responsibility: Manages all layout-related API communication and configuration
  • Key Features:
    • Fetches layout configuration from backend API
    • Retrieves navigation items based on user context
    • Manages user layout preferences (sidebar collapsed state, theme)
    • Provides fallback default configuration when API fails
    • Type-safe interfaces for all data structures
  • Key Methods:
    • getLayoutConfig(): Fetches branding and theme config
    • getNavigationItems(): Retrieves personalized nav items
    • getUserLayoutPreferences(): Gets user-specific preferences
    • saveUserLayoutPreferences(): Persists user preferences

2. Custom Hook (hooks/useAppLayout.ts)

  • Responsibility: Manages React component state and lifecycle
  • Key Features:
    • Detects mobile vs desktop (breakpoint: lg = 1024px)
    • Manages sidebar visibility state
    • Manages sidebar collapse state (desktop)
    • Handles window resize events
    • Provides method to filter nav items by role
    • Automatically initializes on mount
  • Exposed API:
    • state: Layout state (isLoading, error, isMobile, sidebarOpen, etc.)
    • toggleSidebar(): Toggle sidebar visibility on mobile
    • closeSidebar(): Close sidebar
    • openSidebar(): Open sidebar
    • toggleSidebarCollapse(): Toggle collapse state on desktop
    • getVisibleNavItems(): Get filtered navigation items

3. UI Component (components/layout/AppLayout.tsx)

  • Responsibility: Renders the application shell with responsive behavior
  • Structure:
    • DesktopSidebar: Fixed left sidebar (hidden on mobile)
    • MobileBottomSheet: Bottom-sheet menu (mobile only)
    • NavLink: Reusable navigation link component
    • Main layout wrapper with responsive margins
  • Key Features:
    • Responsive breakpoint: lg (1024px)
    • Mobile first approach with progressive enhancement
    • Dark mode support throughout
    • Loading state with spinner
    • Smooth transitions and animations
    • Accessibility features (ARIA labels, semantic HTML)

Files Created

File Purpose Lines
services/layoutService.ts API integration & config 186
hooks/useAppLayout.ts State management & logic 142
components/layout/AppLayout.tsx UI rendering 268

Responsive Design

Desktop (1024px+)

  • Sidebar: Fixed left sidebar, 256px wide (or 80px when collapsed)
  • Layout: Main content shifts right based on sidebar state
  • Interaction: Click toggle button to collapse/expand sidebar
  • Features:
    • Collapsible sidebar with smooth transition
    • Full navigation items visible
    • Descriptions shown under nav labels

Mobile (< 1024px, tested at 375px)

  • Header: Sticky top header with hamburger menu icon
  • Navigation: Bottom-sheet drawer (slides up from bottom)
  • Layout: Full width main content
  • Interactions:
    • Tap hamburger to open bottom-sheet
    • Tap X or backdrop to close
    • Auto-closes when navigating to a link
  • Features:
    • Non-blocking bottom-sheet (draggable area at top)
    • Smooth slide-in animation
    • Dark overlay backdrop
    • Full navigation items visible in sheet

Component Usage

import AppLayout from '@/components/layout/AppLayout';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AppLayout>{children}</AppLayout>
      </body>
    </html>
  );
}

Data Flow

Backend API
    ↓
layoutService (fetch & format)
    ↓
useAppLayout Hook (state management)
    ↓
AppLayout Component (render)
    ↓
NavLink Components (interactive)

API Integration

Expected Backend Endpoints

  1. GET /api/layout/config

    {
  "success": true,
  "data": {
    "branding": {
      "appName": "SwiftChain",
      "logo": "/logo.svg",
      "logoDark": "/logo-dark.svg"
    },
    "navigation": [...],
    "theme": {
      "primaryColor": "#3b82f6",
      "sidebarCollapsible": true
    }
  }
}

  2. GET /api/layout/navigation

    {
  "success": true,
  "data": [
    {
      "id": "dashboard",
      "label": "Dashboard",
      "href": "/dashboard",
      "icon": "📊",
      "description": "Overview and stats",
      "roles": ["customer", "driver", "admin"]
    },
    ...
  ]
}

  3. GET /api/layout/preferences

    {
  "success": true,
  "data": {
    "sidebarCollapsed": false,
    "theme": "light",
    "sidebarWidth": 256
  }
}

  4. PATCH /api/layout/preferences

    • Request: { "sidebarCollapsed": boolean, "theme": "light" | "dark" }
    • Response: Same as GET

Fallback Strategy

  • If API calls fail, service returns default configuration
  • Navigation items still functional with default items
  • User preferences default to: sidebar expanded, light theme, 256px width
  • No breaking UI changes due to API failures

Responsive Breakpoints

Breakpoint Width Sidebar
Mobile (xs-sm) < 1024px Bottom-sheet
Tablet (md) 768px - 1023px Bottom-sheet
Desktop (lg) ≥ 1024px Fixed sidebar

Styling & Theme

Color Scheme

  • Primary: Uses Tailwind primary color (#3b82f6)
  • Light Mode: Slate-50 background, white sidebar
  • Dark Mode: Slate-950 background, slate-900 sidebar
  • Hover States: Slate-100/800 backgrounds
  • Borders: Slate-200/800 colors

Animations

  • Sidebar Toggle: 300ms ease transitions
  • Bottom Sheet: 300ms ease translate animations
  • Nav Items: 200ms ease color/background transitions
  • Loading Spinner: Continuous rotation animation

Accessibility

  • Semantic HTML (header, nav, main, aside)
  • ARIA labels on all interactive elements
  • Proper heading hierarchy
  • Keyboard navigation support
  • Color contrast compliance (WCAG AA)
  • Focus management

Key Features

✅ Responsive Design

  • Tested at 375px (mobile) and 1024px (desktop)
  • Smooth transitions between breakpoints
  • Touch-friendly mobile interactions

✅ Dark Mode Support

  • Full dark mode styling throughout
  • Automatic theme switching via Tailwind

✅ Accessibility

  • ARIA labels and semantic HTML
  • Keyboard navigation
  • Proper focus states

✅ Performance

  • Lazy loads navigation data
  • Efficient state management
  • Minimal re-renders

✅ Error Handling

  • Graceful fallback to default config
  • Error state display
  • Network error recovery

✅ Backend Integration

  • Real API data source (no mocks)
  • User preference persistence
  • Role-based navigation (ready for filtering)

Testing Recommendations

Mobile Testing (375px)

  1. ✓ Hamburger menu appears at top
  2. ✓ Tap hamburger opens bottom-sheet
  3. ✓ Bottom-sheet animates from bottom
  4. ✓ Navigation items visible and tappable
  5. ✓ Backdrop click closes bottom-sheet
  6. ✓ X button closes bottom-sheet
  7. ✓ Automatic close on navigation
  8. ✓ Responsive text sizing

Desktop Testing (1024px+)

  1. ✓ Fixed sidebar appears on left (256px)
  2. ✓ Main content shifts right (margin-left: 256px)
  3. ✓ Collapse button works
  4. ✓ Sidebar collapses to 80px
  5. ✓ Navigation items remain visible when collapsed
  6. ✓ Hover states work on nav items
  7. ✓ Active route highlighted correctly
  8. ✓ Smooth transitions on all state changes

API Integration Testing

  1. ✓ Verify API endpoints return proper format
  2. ✓ Test fallback when API is down
  3. ✓ Test preferences persistence
  4. ✓ Test user role-based filtering
  5. ✓ Test network error recovery

Cross-browser Testing

  • Chrome/Edge (Chromium)
  • Firefox
  • Safari
  • Mobile browsers (Chrome, Safari)

Future Enhancements

  • Add nested navigation support
  • Implement breadcrumb integration
  • Add keyboard shortcuts
  • Persistent sidebar state per device
  • Animation preferences (respects prefers-reduced-motion)
  • Multi-language support
  • Custom icon support (SVG components)
  • Search/filter navigation items

Code Quality

✅ TypeScript strict mode compliant ✅ ESLint formatted ✅ Prettier compliant ✅ No console warnings ✅ Comprehensive JSDoc comments ✅ Proper error handling and guards ✅ Follows project conventions ✅ Mobile-first responsive approach

Related Issues

Closes #[issue_id]

PR Submission Checklist

  • All tests pass (mobile + desktop)
  • API endpoints verified
  • Screenshots included (mobile & desktop)
  • Documentation updated
  • No console errors or warnings
  • Dark mode tested
  • Accessibility verified
  • PR description includes this summary