retail/lib/core/constants/performance_constants.dart

/// Performance-related constants for the retail POS app
///
/// This file contains all performance tuning parameters:
/// - List/Grid performance settings
/// - Cache configurations
/// - Debounce/Throttle timings
/// - Memory limits
/// - Scroll performance settings

class PerformanceConstants {
  // Private constructor to prevent instantiation
  PerformanceConstants._();

  // ==================== List/Grid Performance ====================

  /// Cache extent for ListView/GridView (pixels to preload)
  static const double listCacheExtent = 500.0;

  /// Number of items to preload in infinite scroll
  static const int preloadItemThreshold = 5;

  /// Maximum items to render at once in very large lists
  static const int maxVisibleItems = 100;

  /// Grid crossAxisCount for different screen widths
  static int getGridColumnCount(double screenWidth) {
    if (screenWidth < 600) return 2; // Mobile portrait
    if (screenWidth < 900) return 3; // Mobile landscape / Small tablet
    if (screenWidth < 1200) return 4; // Tablet
    return 5; // Desktop
  }

  /// Grid childAspectRatio for product cards
  static const double productCardAspectRatio = 0.75;

  /// Grid childAspectRatio for category cards
  static const double categoryCardAspectRatio = 1.0;

  /// Grid spacing
  static const double gridSpacing = 12.0;

  // ==================== Debounce/Throttle Timings ====================

  /// Search input debounce (ms) - wait before executing search
  static const int searchDebounceDuration = 300;

  /// Filter input debounce (ms)
  static const int filterDebounceDuration = 200;

  /// Auto-save debounce (ms)
  static const int autoSaveDebounceDuration = 1000;

  /// Scroll position throttle (ms)
  static const int scrollThrottleDuration = 100;

  /// Network retry debounce (ms)
  static const int retryDebounceDuration = 500;

  // ==================== Animation Durations ====================

  /// Standard animation duration
  static const int animationDuration = 300;

  /// Fast animation duration
  static const int fastAnimationDuration = 150;

  /// Image fade-in duration
  static const int imageFadeDuration = 300;

  /// Shimmer animation duration
  static const int shimmerDuration = 1500;

  // ==================== Memory Management ====================

  /// Maximum image cache size in memory (MB)
  static const int maxImageMemoryCacheMB = 50;

  /// Maximum image cache count in memory
  static const int maxImageMemoryCacheCount = 100;

  /// Maximum disk cache size (MB)
  static const int maxDiskCacheMB = 200;

  /// Database cache size limit (number of items)
  static const int maxDatabaseCacheItems = 1000;

  // ==================== Network Performance ====================

  /// Network request timeout (seconds)
  static const int networkTimeoutSeconds = 30;

  /// Network connect timeout (seconds)
  static const int networkConnectTimeoutSeconds = 15;

  /// Network receive timeout (seconds)
  static const int networkReceiveTimeoutSeconds = 30;

  /// Maximum concurrent image downloads
  static const int maxConcurrentImageDownloads = 3;

  /// Retry attempts for failed requests
  static const int maxRetryAttempts = 3;

  /// Retry delay (seconds)
  static const int retryDelaySeconds = 2;

  // ==================== Batch Operations ====================

  /// Batch size for database operations
  static const int databaseBatchSize = 50;

  /// Batch size for image preloading
  static const int imagePreloadBatchSize = 10;

  /// Pagination page size
  static const int paginationPageSize = 20;

  // ==================== Build Optimization ====================

  /// Whether to use RepaintBoundary for grid items
  static const bool useRepaintBoundaryForGridItems = true;

  /// Whether to use const constructors aggressively
  static const bool useConstConstructors = true;

  /// Whether to enable performance overlay in debug mode
  static const bool enablePerformanceOverlay = false;

  // ==================== Hive Database Performance ====================

  /// Compact database after this many operations
  static const int databaseCompactThreshold = 100;

  /// Use lazy box for large datasets
  static const bool useLazyBoxForProducts = true;

  /// Cache database queries
  static const bool cacheQueries = true;

  /// Maximum database file size (MB) before warning
  static const int maxDatabaseSizeMB = 100;

  // ==================== Scroll Performance ====================

  /// Physics for better scroll performance
  static const bool useBouncingScrollPhysics = true;

  /// Scroll controller jump threshold (prevent jarring jumps)
  static const double scrollJumpThreshold = 1000.0;

  /// Enable scroll momentum
  static const bool enableScrollMomentum = true;

  // ==================== State Management Performance ====================

  /// Provider auto-dispose delay (seconds)
  static const int providerAutoDisposeDelay = 60;

  /// Keep alive duration for cached providers (seconds)
  static const int providerKeepAliveDuration = 300;

  /// Use provider.select() for granular rebuilds
  static const bool useGranularRebuild = true;

  // ==================== Image Loading Performance ====================

  /// Image loading placeholder height
  static const double placeholderHeight = 200.0;

  /// Use progressive JPEG loading
  static const bool useProgressiveLoading = true;

  /// Preload images for next page
  static const bool preloadNextPageImages = true;

  /// Maximum image resolution (width x height)
  static const int maxImageWidth = 1920;
  static const int maxImageHeight = 1920;

  // ==================== Frame Rate Targets ====================

  /// Target frame rate
  static const int targetFPS = 60;

  /// Budget per frame (milliseconds)
  static const double frameBudgetMs = 16.67; // 60 FPS

  /// Warning threshold for long frames (ms)
  static const double longFrameThresholdMs = 32.0;

  // ==================== Cart Performance ====================

  /// Maximum cart items before pagination
  static const int maxCartItemsBeforePagination = 50;

  /// Cart calculation debounce (ms)
  static const int cartCalculationDebounce = 100;

  // ==================== Responsive Breakpoints ====================

  /// Mobile breakpoint
  static const double mobileBreakpoint = 600.0;

  /// Tablet breakpoint
  static const double tabletBreakpoint = 900.0;

  /// Desktop breakpoint
  static const double desktopBreakpoint = 1200.0;

  // ==================== Helper Methods ====================

  /// Get appropriate cache extent based on device
  static double getCacheExtent(double screenHeight) {
    // Cache 1.5x screen height
    return screenHeight * 1.5;
  }

  /// Get appropriate batch size based on memory
  static int getDynamicBatchSize(int totalItems) {
    if (totalItems < 100) return 20;
    if (totalItems < 500) return 50;
    if (totalItems < 1000) return 100;
    return 200;
  }

  /// Check if device can handle high performance mode
  static bool shouldUseHighPerformanceMode(double screenWidth) {
    return screenWidth >= tabletBreakpoint;
  }
}