​

Frontend Context Providers Documentation

​

Context Architecture Overview

​

Context Providers

​

1. AdminContext

​

Location: src/context/AdminContext.tsx

​

Purpose

​

Features

• Admin Status Checking: Verifies if the current user has admin privileges
• Authentication Integration: Works with Supabase authentication
• Real-time Updates: Automatically updates when authentication state changes
• Role Validation: Checks user role from the profiles table

​

Context Interface

interface AdminContextType {
  isAdmin: boolean;           // Current admin status
  isAdminChecked: boolean;    // Whether admin check is complete
}

​

Implementation Details

• Provider Component: AdminProvider
• Custom Hook: useAdmin()
• Error Handling: Throws error if used outside provider
• Auto-subscription: Listens to Supabase auth state changes

​

Usage Example

import { useAdmin } from '../context/AdminContext';

function MyComponent() {
  const { isAdmin, isAdminChecked } = useAdmin();
  
  if (!isAdminChecked) {
    return <LoadingSpinner />;
  }
  
  return (
    <div>
      {isAdmin && <AdminPanel />}
    </div>
  );
}

​

Dependencies

• Supabase: For authentication and user data
• React: Core React hooks and context

​

Security Features

• Row Level Security: Leverages Supabase RLS policies
• Server-side Validation: Admin status verified on backend
• Session Management: Automatic session validation

​

2. CartContext

​

Location: src/context/CartContext.tsx

​

Purpose

​

Features

• Cart Management: Add, remove, and manage cart items
• Total Calculation: Automatic total price calculation
• Currency Support: Multi-currency support (defaults to EGP)
• Duplicate Prevention: Prevents duplicate items in cart
• State Persistence: Cart state management with reducer pattern

​

Context Interface

interface CartContextType {
  state: CartState;
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  clearCart: () => void;
  getItemCount: () => number;
  getTotal: () => number;
}

interface CartState {
  items: CartItem[];
  total: number;
  currency: string;
}

interface CartItem {
  id: string;
  teacher_mark_scheme_id: string;
  original_filename: string;
  subject_id: string;
  exam_category: string;
  paper_year: string;
  paper_season: string;
  paper_category: string;
  teacher_explanation: string;
  file_url: string;
  price: number;
  currency: string;
}

​

Implementation Details

• Provider Component: CartProvider
• Custom Hook: useCart()
• Reducer Pattern: Uses useReducer for complex state management
• Action Types: ADD_ITEM, REMOVE_ITEM, CLEAR_CART, UPDATE_QUANTITY

​

Usage Example

import { useCart } from '../context/CartContext';

function ProductCard({ product }) {
  const { addItem, getItemCount } = useCart();
  
  const handleAddToCart = () => {
    addItem(product);
  };
  
  return (
    <div>
      <h3>{product.name}</h3>
      <button onClick={handleAddToCart}>
        Add to Cart ({getItemCount()})
      </button>
    </div>
  );
}

​

Cart Actions

• ADD_ITEM: Adds item to cart (prevents duplicates)
• REMOVE_ITEM: Removes item by ID
• CLEAR_CART: Empties entire cart
• UPDATE_QUANTITY: Updates item quantity (not used for mark schemes)

​

Business Logic

• Mark Scheme Focus: Optimized for teacher mark scheme purchases
• Quantity Limitation: Each item has quantity of 1
• Price Calculation: Automatic total calculation
• Currency Handling: Default EGP currency support

​

3. LayoutContext

​

Location: src/context/LayoutContext.tsx

​

Purpose

​

Features

• Sidebar Management: Controls sidebar visibility and collapse state
• Responsive Design: Adapts to different screen sizes
• State Synchronization: Keeps layout state consistent across components
• Toggle Functionality: Smart toggle behavior for sidebar

​

Context Interface

interface LayoutContextType {
  isSidebarCollapsed: boolean;      // Sidebar collapsed state
  isSidebarHidden: boolean;         // Sidebar hidden state
  setSidebarCollapsed: (collapsed: boolean) => void;
  setSidebarHidden: (hidden: boolean) => void;
  toggleSidebar: () => void;        // Smart toggle function
  hideSidebar: () => void;          // Hide sidebar
  showSidebar: () => void;          // Show sidebar (uncollapsed)
}

​

Implementation Details

• Provider Component: LayoutProvider
• Custom Hook: useLayout()
• State Management: Uses useState for simple state
• Smart Toggle: Intelligent toggle behavior based on current state

​

Usage Example

import { useLayout } from '../context/LayoutContext';

function SidebarToggle() {
  const { 
    isSidebarCollapsed, 
    isSidebarHidden, 
    toggleSidebar 
  } = useLayout();
  
  return (
    <button onClick={toggleSidebar}>
      {isSidebarHidden ? 'Show' : 'Hide'} Sidebar
    </button>
  );
}

​

Toggle Logic

const toggleSidebar = () => {
  if (isSidebarHidden) {
    // If hidden, show it (uncollapsed)
    setIsSidebarHidden(false);
    setIsSidebarCollapsed(false);
  } else {
    // If visible, hide it completely
    setIsSidebarHidden(true);
  }
};

​

Layout States

• Visible + Expanded: Normal sidebar state
• Visible + Collapsed: Sidebar visible but minimized
• Hidden: Sidebar completely hidden

​

4. PageContentContext

​

Location: src/context/PageContentContext.tsx

​

Purpose

​

Features

• Dynamic Content: Editable page content management
• Auto-initialization: Automatically initializes content if none exists
• Real-time Updates: Live content updates without page refresh
• Admin-only Editing: Content editing restricted to admin users
• Content Persistence: Automatic saving to Supabase database
• Loading States: Proper loading state management

​

Context Interface

interface PageContentContextType {
  content: PageContentItem;                    // Current page content
  isLoading: boolean;                          // Loading state
  updateContent: (key: string, value: string) => Promise<void>;
  getContent: (key: string, defaultValue: string) => string;
  saveAllContent: () => Promise<number>;       // Save all content on page
}

interface PageContentItem {
  [key: string]: string;                       // Key-value content pairs
}

​

Implementation Details

• Provider Component: PageContentProvider
• Custom Hook: usePageContent()
• Page-specific: Each page has its own content context
• Auto-save: Background saving of content changes

​

Usage Example

import { usePageContent } from '../context/PageContentContext';

function EditableText({ contentKey, defaultValue }) {
  const { getContent, updateContent, isLoading } = usePageContent();
  
  if (isLoading) {
    return <div>Loading...</div>;
  }
  
  const content = getContent(contentKey, defaultValue);
  
  return (
    <div
      contentEditable={isAdmin}
      onBlur={(e) => updateContent(contentKey, e.target.textContent)}
    >
      {content}
    </div>
  );
}

​

Content Management Features

• DOM Scanning: Automatically scans page for content elements
• Data Attributes: Uses data-content-key for content identification
• Image Support: Supports editable images with data-image-key
• Batch Operations: Can save all content at once

​

Content Initialization Process

1. Load Existing Content: Fetches content from database
2. Check for Empty State: Detects if no content exists
3. Auto-initialization: Creates default content if needed
4. DOM Scanning: Scans page for content elements
5. Content Mapping: Maps DOM elements to content keys
6. Database Save: Saves content to Supabase

​

Loading State Management

// Loading state with smooth transition
{isLoading ? (
  <div className="min-h-screen bg-white dark:bg-[#051220] flex items-center justify-center">
    <div className="animate-pulse text-primary dark:text-neutral-light text-center">
      <div className="w-16 h-16 mx-auto border-4 border-current border-t-transparent rounded-full animate-spin mb-4"></div>
      <p className="text-lg">Loading content...</p>
    </div>
  </div>
) : (
  children
)}

​

Content Saving Strategy

• Immediate Update: Local state updated immediately
• Background Save: Database save happens in background
• Error Handling: Graceful error handling for save failures
• Optimistic Updates: UI updates before database confirmation

​

Context Integration Patterns

​

1. Provider Hierarchy

function App() {
  return (
    <HelmetProvider>
      <AdminProvider>
        <CartProvider>
          <LayoutProvider>
            <Router>
              {/* App content */}
            </Router>
          </LayoutProvider>
        </CartProvider>
      </AdminProvider>
    </HelmetProvider>
  );
}

​

2. Conditional Context Usage

function ConditionalProvider({ children, condition }) {
  if (condition) {
    return (
      <PageContentProvider page="about">
        {children}
      </PageContentProvider>
    );
  }
  
  return children;
}

​

3. Context Composition

function CombinedContext({ children }) {
  return (
    <AdminProvider>
      <LayoutProvider>
        <PageContentProvider page="dashboard">
          {children}
        </PageContentProvider>
      </LayoutProvider>
    </AdminProvider>
  );
}

​

Context Best Practices

​

1. Performance Optimization

• Context Splitting: Separate contexts for different concerns
• Memoization: Use useMemo for expensive context values
• Selective Subscriptions: Only subscribe to needed context values
• Lazy Loading: Load context data only when needed

​

2. Error Handling

• Error Boundaries: Wrap context providers with error boundaries
• Fallback Values: Provide sensible default values
• Validation: Validate context data before use
• Error Recovery: Graceful error recovery mechanisms

​

3. Type Safety

• TypeScript Interfaces: Strong typing for context interfaces
• Generic Types: Use generics for reusable context patterns
• Type Guards: Runtime type checking for context data
• Documentation: Clear type documentation

​

4. Testing Strategy

• Context Testing: Test context providers in isolation
• Hook Testing: Test custom hooks independently
• Integration Testing: Test context integration with components
• Mock Contexts: Mock contexts for component testing

​

Context Security Considerations

​

1. Data Validation

• Input Sanitization: Sanitize all context data
• Type Validation: Runtime type checking
• Access Control: Role-based access to context data
• Audit Logging: Log context data changes

​

2. State Management Security

• Sensitive Data: Avoid storing sensitive data in context
• Session Management: Proper session handling
• Token Management: Secure token storage and refresh
• Permission Checks: Regular permission validation

​

Context Performance Monitoring

​

1. Performance Metrics

• Render Count: Monitor context-related re-renders
• Memory Usage: Track context memory consumption
• Update Frequency: Monitor context update patterns
• Bundle Size: Track context-related bundle size

​

2. Optimization Strategies

• Context Splitting: Split large contexts into smaller ones
• Memoization: Memoize context values and selectors
• Lazy Loading: Load context data on demand
• Caching: Implement context data caching

​

Future Context Enhancements

​

1. Planned Features

• Context Persistence: Local storage integration
• Context Synchronization: Multi-tab context sync
• Context Middleware: Context action middleware
• Context DevTools: Development debugging tools

​

2. Advanced Patterns

• Context Composition: Advanced context composition patterns
• Context Providers: Provider factory patterns
• Context Hooks: Advanced custom hook patterns
• Context Testing: Enhanced testing utilities

​

3. Performance Improvements

• Context Optimization: Advanced optimization strategies
• Memory Management: Better memory management
• Update Batching: Batched context updates
• Selective Rendering: Selective component rendering

​

Context Documentation Standards

​

1. Code Documentation

• JSDoc Comments: Comprehensive context documentation
• Type Definitions: Clear TypeScript interfaces
• Usage Examples: Practical usage examples
• API Reference: Complete API documentation

​

2. User Documentation

• Context Purpose: Clear purpose and use cases
• Integration Guide: Step-by-step integration guide
• Best Practices: Context usage best practices
• Troubleshooting: Common issues and solutions

​

3. Developer Documentation

• Architecture Overview: Context architecture explanation
• Implementation Details: Technical implementation details
• Extension Guide: How to extend existing contexts
• Migration Guide: Context migration strategies