mtrl-addons 0.1.1 → 0.2.1

package/src/core/list-manager/list-manager.ts

@@ -1,206 +0,0 @@
-/**
- * List Manager - High-Performance Virtual List Management
- * A clean, composable factory for creating optimized virtual lists
- */
-
-import { pipe } from "../compose";
-import { withCollection } from "./features/collection/collection";
-import { withViewport } from "./features/viewport/viewport";
-import { withPlaceholders } from "./features/viewport/placeholders";
-import { createLoadingManager } from "./features/viewport/loading";
-import { LIST_MANAGER_CONSTANTS } from "./constants";
-import type { ListManagerConfig, ListManagerComponent } from "./types";
-
-/**
- * Default configuration for List Manager
- */
-const DEFAULT_CONFIG: Partial<ListManagerConfig> = {
-  orientation: {
-    orientation: "vertical",
-    reverse: false,
-    crossAxisAlignment: "stretch",
-  },
-  virtual: {
-    estimatedItemSize: LIST_MANAGER_CONSTANTS.VIRTUAL_SCROLL.DEFAULT_ITEM_SIZE,
-    itemSize: LIST_MANAGER_CONSTANTS.VIRTUAL_SCROLL.DEFAULT_ITEM_SIZE,
-    overscan: LIST_MANAGER_CONSTANTS.VIRTUAL_SCROLL.OVERSCAN_BUFFER,
-    enabled: true,
-  },
-  collection: {
-    pageSize: LIST_MANAGER_CONSTANTS.RANGE_LOADING.DEFAULT_RANGE_SIZE,
-    strategy: "page",
-  },
-};
-
-/**
- * Creates a new List Manager component
- */
-export const createListManager = (
-  config: ListManagerConfig
-): ListManagerComponent => {
-  const container = config.container;
-
-  // Merge config with defaults - handle undefined properties
-  const mergedConfig: ListManagerConfig = {
-    ...DEFAULT_CONFIG,
-    ...config,
-    orientation: {
-      ...DEFAULT_CONFIG.orientation,
-      ...(config.orientation || {}),
-    },
-    virtual: {
-      ...DEFAULT_CONFIG.virtual,
-      ...(config.virtual || {}),
-    },
-    collection: {
-      ...DEFAULT_CONFIG.collection,
-      ...(config.collection || {}),
-    },
-  } as ListManagerConfig;
-
-  // Create base component
-  const createBaseComponent = (): ListManagerComponent => {
-    // Simple event system
-    const eventListeners = new Map<string, Function[]>();
-
-    const emit = (event: string, data?: any) => {
-      const listeners = eventListeners.get(event) || [];
-      listeners.forEach((listener) => {
-        try {
-          listener(data);
-        } catch (error) {
-          console.error(`Error in event listener for ${event}:`, error);
-        }
-      });
-    };
-
-    const on = (event: string, listener: Function) => {
-      if (!eventListeners.has(event)) {
-        eventListeners.set(event, []);
-      }
-      eventListeners.get(event)!.push(listener);
-
-      // Return unsubscribe function
-      return () => {
-        const listeners = eventListeners.get(event);
-        if (listeners) {
-          const index = listeners.indexOf(listener);
-          if (index > -1) {
-            listeners.splice(index, 1);
-          }
-        }
-      };
-    };
-
-    return {
-      element: container,
-      config: mergedConfig,
-      componentName: "list-manager",
-      getClass: (name: string) => `mtrl-list-manager__${name}`,
-      items: config.items || [],
-      totalItems: config.collection?.totalItems || config.items?.length || 0,
-      template: config.template?.template || null,
-      isInitialized: false,
-      isDestroyed: false,
-      emit,
-      on,
-      initialize: () => {
-        // console.log("🚀 [LIST-MANAGER] Initializing...");
-      },
-      destroy: () => {
-        // console.log("👋 [LIST-MANAGER] Destroying...");
-      },
-      updateConfig: (update: Partial<ListManagerConfig>) => {
-        Object.assign(mergedConfig, update);
-      },
-      getConfig: () => mergedConfig,
-    };
-  };
-
-  // Create loading manager
-  let loadingManager: ReturnType<typeof createLoadingManager> | null = null;
-
-  // Compose enhancers - CRITICAL: Collection must be applied before viewport
-  // so that viewport can access collection.loadMissingRanges
-  const enhance = pipe(
-    withCollection({
-      collection: config.collection?.adapter,
-      rangeSize: config.collection?.pageSize || 20,
-      strategy: config.collection?.strategy || "page",
-      enablePlaceholders: true,
-    }),
-    withPlaceholders({
-      enabled: true,
-    }),
-    withViewport({
-      orientation: mergedConfig.orientation?.orientation,
-      estimatedItemSize: mergedConfig.virtual?.estimatedItemSize,
-      overscan: mergedConfig.virtual?.overscan,
-      enableScrollbar: true,
-      measureItems: mergedConfig.virtual?.measureItems, // Pass measureItems flag
-      // Pass callback to load data for a specific range
-      loadDataForRange: (
-        range: { start: number; end: number },
-        priority?: "high" | "normal" | "low"
-      ) => {
-        // Use loading manager if available
-        if (loadingManager) {
-          // Check if this range is already being loaded
-          if (!loadingManager.isRangeLoading(range)) {
-            loadingManager.requestLoad(range, priority || "normal");
-          }
-        } else {
-          // Fallback to direct collection loading
-          setTimeout(() => {
-            const collectionComponent = component as any;
-            if (
-              collectionComponent.collection &&
-              typeof collectionComponent.collection.loadMissingRanges ===
-                "function"
-            ) {
-              collectionComponent.collection
-                .loadMissingRanges(range)
-                .catch((error: any) => {
-                  console.error("Failed to load range:", error);
-                });
-            }
-          }, 0);
-        }
-      },
-    })
-  );
-
-  // Create and enhance component
-  const component = enhance(createBaseComponent());
-
-  // Create loading manager after component is enhanced
-  loadingManager = createLoadingManager(component, {
-    maxConcurrentRequests: config.collection?.maxConcurrentRequests,
-  });
-
-  // Wire up velocity updates from scrolling to loading manager
-  if (component.on) {
-    component.on("speed:changed", (data: any) => {
-      if (loadingManager) {
-        loadingManager.updateVelocity(data.speed, data.direction);
-      }
-    });
-  }
-
-  // Initialize component
-  if ((component as any).viewport?.initialize) {
-    (component as any).viewport.initialize();
-  }
-
-  // Return the enhanced component
-  return component;
-};
-
-/**
- * Configuration for list manager enhancers
- */
-export interface ListManagerEnhancerConfig {
-  viewport?: Parameters<typeof withViewport>[0];
-  collection?: Parameters<typeof withCollection>[0];
-  placeholders?: Parameters<typeof withPlaceholders>[0];
-}

package/src/core/list-manager/types.ts

@@ -1,439 +0,0 @@
-/**
- * Core type definitions for List Manager
- * Performance and UI management layer types
- */
-
-import type { ListManagerConstants } from "./constants";
-
-/**
- * Core Range and Item Types
- */
-export interface ItemRange {
-  start: number;
-  end: number;
-}
-
-export interface ViewportInfo {
-  containerSize: number;
-  totalVirtualSize: number;
-  visibleRange: ItemRange;
-  virtualScrollPosition: number;
-}
-
-export interface SpeedTracker {
-  velocity: number; // px/ms
-  direction: "forward" | "backward"; // scroll direction (vertical: down/up, horizontal: right/left)
-  isAccelerating: boolean; // velocity increasing
-  lastMeasurement: number; // timestamp of last measurement
-}
-
-/**
- * Feature Interfaces for Simplified Architecture
- */
-
-/**
- * Viewport Feature - Complete Virtual Scrolling
- */
-export interface ViewportFeature {
-  // Orientation handling
-  orientation: "vertical" | "horizontal";
-
-  // Virtual scrolling (orientation-agnostic)
-  virtualScrollPosition: number;
-  totalVirtualSize: number;
-  containerSize: number;
-
-  // Item sizing (orientation-agnostic)
-  estimatedItemSize: number;
-  measuredSizes: Map<number, number>;
-
-  // Custom scrollbar
-  scrollbarThumb: HTMLElement | null;
-  scrollbarTrack: HTMLElement | null;
-  thumbPosition: number;
-
-  // Methods
-  handleWheel(event: WheelEvent): void;
-  updateContainerPosition(): void;
-  updateScrollbar(): void;
-  calculateVisibleRange(): ItemRange;
-  measureItemSize(element: HTMLElement, index: number): void;
-  initialize(): void;
-  destroy(): void;
-}
-
-/**
- * Collection Feature - Data Management Integration
- */
-export interface CollectionFeature {
-  // Speed tracking
-  speedTracker: SpeedTracker;
-
-  // Range management
-  loadedRanges: Set<number>;
-  pendingRanges: Set<number>;
-
-  // Collection integration
-  collection: any;
-
-  // Pagination strategy
-  paginationStrategy: "page" | "offset" | "cursor";
-
-  // Placeholder system
-  placeholderStructure: Map<string, { min: number; max: number }> | null;
-  placeholderTemplate:
-    | ((item: any, index: number) => string | HTMLElement)
-    | null;
-
-  // Methods
-  loadMissingRanges(visibleRange: ItemRange): void;
-  showPlaceholders(range: ItemRange): void;
-  updateLoadedData(items: any[], offset: number): void;
-  adaptPaginationStrategy(strategy: "page" | "offset" | "cursor"): void;
-  analyzeDataStructure(items: any[]): void;
-  generatePlaceholderItem(index: number): any;
-  initialize(): void;
-  destroy(): void;
-}
-
-/**
- * Configuration Types
- */
-export interface CollectionConfig {
-  adapter?: any;
-  pageSize?: number; // becomes rangeSize
-  strategy?: "page" | "offset" | "cursor";
-  [key: string]: any;
-}
-
-export interface TemplateConfig {
-  template: (item: any, index: number) => string | HTMLElement;
-}
-
-export interface VirtualConfig {
-  enabled: boolean;
-  itemSize: number | "auto";
-  estimatedItemSize: number;
-  overscan: number;
-  measureItems?: boolean; // Optional flag to enable/disable item measurement (default: false)
-}
-
-export interface OrientationConfig {
-  orientation: "vertical" | "horizontal";
-  reverse: boolean;
-  crossAxisAlignment: "start" | "center" | "end" | "stretch";
-}
-
-export interface InitialLoadConfig {
-  strategy: "placeholders" | "direct";
-  viewportMultiplier: number;
-  minItems: number;
-  maxItems: number;
-}
-
-export interface ErrorHandlingConfig {
-  timeout: number;
-  showErrorItems: boolean;
-  retryAttempts: number;
-  preserveScrollOnError: boolean;
-}
-
-export interface PositioningConfig {
-  precisePositioning: boolean;
-  allowPartialItems: boolean;
-  snapToItems: boolean;
-}
-
-export interface BoundariesConfig {
-  preventOverscroll: boolean;
-  maintainEdgeRanges: boolean;
-  boundaryResistance: number;
-}
-
-export interface RecyclingConfig {
-  enabled: boolean;
-  maxPoolSize: number;
-  minPoolSize: number;
-}
-
-export interface PerformanceConfig {
-  frameScheduling: boolean;
-  memoryCleanup: boolean;
-}
-
-export interface IntersectionConfig {
-  pagination: {
-    enabled: boolean;
-    rootMargin: string;
-    threshold: number;
-  };
-  loading: {
-    enabled: boolean;
-  };
-}
-
-/**
- * Main List Manager Configuration
- */
-export interface ListManagerConfig {
-  // Container
-  container: HTMLElement;
-
-  // Collection integration
-  collection?: CollectionConfig;
-  items?: any[];
-
-  // Template
-  template?: TemplateConfig;
-
-  // Virtual scrolling
-  virtual: VirtualConfig;
-
-  // Orientation
-  orientation: OrientationConfig;
-
-  // Initial loading
-  initialLoad: InitialLoadConfig;
-
-  // Error handling
-  errorHandling: ErrorHandlingConfig;
-
-  // Positioning
-  positioning: PositioningConfig;
-
-  // Boundaries
-  boundaries: BoundariesConfig;
-
-  // Element recycling (Phase 2)
-  recycling: RecyclingConfig;
-
-  // Performance
-  performance: PerformanceConfig;
-
-  // Intersection observers
-  intersection: IntersectionConfig;
-
-  // Debug
-  debug: boolean;
-  prefix: string;
-  componentName: string;
-
-  // Constants override
-  constants?: Partial<ListManagerConstants>;
-}
-
-/**
- * Event System
- */
-export enum ListManagerEvents {
-  // Virtual scrolling
-  VIEWPORT_CHANGED = "viewport:changed",
-  SCROLL_POSITION_CHANGED = "scroll:position:changed",
-  VIRTUAL_RANGE_CHANGED = "virtual:range:changed",
-  RANGE_RENDERED = "range:rendered",
-
-  // Collection coordination
-  LOADING_TRIGGERED = "loading:triggered",
-  SPEED_CHANGED = "speed:changed",
-  RANGE_LOADED = "range:loaded",
-
-  // Orientation
-  ORIENTATION_CHANGED = "orientation:changed",
-  DIMENSIONS_CHANGED = "orientation:dimensions:changed",
-
-  // Placeholder system
-  STRUCTURE_ANALYZED = "placeholder:structure:analyzed",
-  PLACEHOLDERS_SHOWN = "placeholder:shown",
-  PLACEHOLDERS_REPLACED = "placeholder:replaced",
-
-  // Element recycling events
-  ELEMENT_RENDERED = "element:rendered",
-  ELEMENT_UPDATED = "element:updated",
-  ELEMENT_RECYCLED = "element:recycled",
-  RECYCLING_INITIALIZED = "recycling:initialized",
-  RECYCLING_DESTROYED = "recycling:destroyed",
-
-  // Error handling
-  ERROR_OCCURRED = "error:occurred",
-  ERROR_RECOVERED = "error:recovered",
-
-  // Lifecycle
-  INITIALIZED = "lifecycle:initialized",
-  DESTROYED = "lifecycle:destroyed",
-}
-
-export interface ListManagerEventData {
-  [ListManagerEvents.VIEWPORT_CHANGED]: ViewportInfo;
-  [ListManagerEvents.SCROLL_POSITION_CHANGED]: {
-    position: number;
-    direction: "forward" | "backward";
-  };
-  [ListManagerEvents.VIRTUAL_RANGE_CHANGED]: ItemRange;
-  [ListManagerEvents.RANGE_RENDERED]: { range: ItemRange };
-  [ListManagerEvents.LOADING_TRIGGERED]: { range: ItemRange; strategy: string };
-  [ListManagerEvents.SPEED_CHANGED]: {
-    speed: number;
-    direction: "forward" | "backward";
-  };
-  [ListManagerEvents.RANGE_LOADED]: { range: ItemRange; items: any[] };
-  [ListManagerEvents.ORIENTATION_CHANGED]: {
-    orientation: "vertical" | "horizontal";
-  };
-  [ListManagerEvents.DIMENSIONS_CHANGED]: {
-    containerSize: number;
-    totalVirtualSize: number;
-  };
-  [ListManagerEvents.STRUCTURE_ANALYZED]: {
-    structure: Map<string, { min: number; max: number }>;
-  };
-  [ListManagerEvents.PLACEHOLDERS_SHOWN]: { range: ItemRange; count: number };
-  [ListManagerEvents.PLACEHOLDERS_REPLACED]: { range: ItemRange; items: any[] };
-  [ListManagerEvents.ELEMENT_RENDERED]: { element: HTMLElement };
-  [ListManagerEvents.ELEMENT_UPDATED]: { element: HTMLElement };
-  [ListManagerEvents.ELEMENT_RECYCLED]: { element: HTMLElement };
-  [ListManagerEvents.RECYCLING_INITIALIZED]: { config: ListManagerConfig };
-  [ListManagerEvents.RECYCLING_DESTROYED]: { reason?: string };
-  [ListManagerEvents.ERROR_OCCURRED]: { error: Error; context: string };
-  [ListManagerEvents.ERROR_RECOVERED]: {
-    previousError: Error;
-    context: string;
-  };
-  [ListManagerEvents.INITIALIZED]: { config: ListManagerConfig };
-  [ListManagerEvents.DESTROYED]: { reason?: string };
-}
-
-export interface ListManagerObserver {
-  <T extends ListManagerEvents>(event: T, data: ListManagerEventData[T]): void;
-}
-
-export type ListManagerUnsubscribe = () => void;
-
-/**
- * Main List Manager Interface
- */
-export interface ListManager {
-  // Virtual scrolling (orientation-agnostic)
-  scrollToIndex(index: number, alignment?: "start" | "center" | "end"): void;
-  scrollToPage(page: number, alignment?: "start" | "center" | "end"): void;
-  getScrollPosition(): number;
-
-  // Viewport management
-  getVisibleRange(): ItemRange;
-  getViewportInfo(): ViewportInfo;
-  updateViewport(): void;
-
-  // Collection integration
-  setItems(items: any[]): void;
-  setTotalItems(total: number): void;
-  getItems(): any[];
-  getTotalItems(): number;
-
-  // Pagination strategy
-  setPaginationStrategy(strategy: "page" | "offset" | "cursor"): void;
-  getPaginationStrategy(): "page" | "offset" | "cursor";
-
-  // Configuration
-  updateConfig(config: Partial<ListManagerConfig>): void;
-  getConfig(): ListManagerConfig;
-
-  // Events
-  subscribe(observer: ListManagerObserver): ListManagerUnsubscribe;
-  emit<T extends ListManagerEvents>(
-    event: T,
-    data: ListManagerEventData[T]
-  ): void;
-
-  // Lifecycle
-  initialize(): void;
-  destroy(): void;
-}
-
-/**
- * Utility Types
- */
-export type ListManagerConfigUpdate = Partial<ListManagerConfig>;
-
-export interface FeatureContext {
-  config: ListManagerConfig;
-  constants: ListManagerConstants;
-  emit: <T extends ListManagerEvents>(
-    event: T,
-    data: ListManagerEventData[T]
-  ) => void;
-}
-
-export interface RangeCalculationResult {
-  visibleRange: ItemRange;
-  loadedRanges: Set<number>;
-  missingRanges: ItemRange[];
-  bufferRanges: ItemRange[];
-}
-
-/**
- * Type for the base List Manager component
- */
-export interface ListManagerComponent {
-  // mtrl base properties
-  element: HTMLElement;
-  config: ListManagerConfig;
-  componentName: string;
-  getClass: (name: string) => string;
-  emit?: (event: string, data?: any) => void;
-  on?: (event: string, handler: Function) => () => void;
-
-  // List Manager specific
-  items: any[];
-  totalItems: number;
-  template: ((item: any, index: number) => string | HTMLElement) | null;
-  isInitialized: boolean;
-  isDestroyed: boolean;
-
-  // Core methods
-  initialize(): void;
-  destroy(): void;
-  updateConfig(config: Partial<ListManagerConfig>): void;
-  getConfig(): ListManagerConfig;
-}
-
-export interface TemplateFunction {
-  (item: any, index: number): string | HTMLElement;
-}
-
-export interface CollectionComponent extends ListManagerComponent {
-  collection: {
-    // Data management
-    setItems: (items: any[]) => void;
-    getItems: () => any[];
-    setTotalItems: (total: number) => void;
-    getTotalItems: () => number;
-
-    // Range management
-    loadRange: (offset: number, limit: number) => Promise<any[]>;
-    loadMissingRanges: (visibleRange: ItemRange) => Promise<void>;
-    getLoadedRanges: () => Set<number>;
-    getPendingRanges: () => Set<number>;
-    getFailedRanges: () => Map<
-      number,
-      { attempts: number; lastError: Error; timestamp: number }
-    >;
-    clearFailedRanges: () => void;
-    retryFailedRange: (rangeId: number) => Promise<any[]>;
-
-    // Pagination strategy
-    setPaginationStrategy: (strategy: "page" | "offset" | "cursor") => void;
-    getPaginationStrategy: () => string;
-
-    // Placeholder system
-    analyzeDataStructure: (items: any[]) => void;
-    generatePlaceholderItem: (index: number) => any;
-    showPlaceholders: (count: number) => void;
-    getPlaceholderStructure: () => Map<
-      string,
-      { min: number; max: number }
-    > | null;
-
-    // State
-    isInitialized: () => boolean;
-    updateLoadedData: (items: any[], offset: number) => void;
-  };
-}