mtrl-addons 0.2.2 → 0.2.4

package/src/core/viewport/types.ts

@@ -1,133 +0,0 @@
-// src/core/viewport/types.ts
-
-/**
- * Core type definitions for Viewport
- * Virtual scrolling and rendering types
- */
-
-import type { CollectionComponent } from "./features/collection";
-
-/**
- * Core Range and Item Types
- */
-export interface ItemRange {
-  start: number;
-  end: number;
-}
-
-export interface ViewportInfo {
-  containerSize: number;
-  totalVirtualSize: number;
-  visibleRange: ItemRange;
-  virtualScrollPosition: number;
-}
-
-/**
- * Viewport context interface - provides context for viewport features
- */
-export interface ViewportContext {
-  element: HTMLElement;
-  items: any[];
-  totalItems: number;
-  template?: (item: any, index: number) => string | HTMLElement;
-  emit?: (event: string, data?: any) => void;
-  on?: (event: string, handler: Function) => () => void;
-  once?: (event: string, handler: Function) => () => void;
-  off?: (event: string, handler: Function) => void;
-  getClass?: (name: string) => string;
-}
-
-/**
- * Viewport configuration - Feature-oriented structure
- */
-export interface ViewportConfig {
-  // Basic configuration
-  element?: HTMLElement;
-  className?: string;
-  debug?: boolean;
-
-  // Template for rendering items
-  template?: (
-    item: any,
-    index: number,
-  ) => string | HTMLElement | any[] | Record<string, any>;
-
-  // Collection/data source configuration
-  collection?: {
-    adapter?: any; // Data adapter
-    transform?: (item: any) => any; // Transform items before rendering
-  };
-
-  // Pagination configuration
-  pagination?: {
-    strategy?: "page" | "offset" | "cursor";
-    limit?: number; // Items per page/range
-  };
-
-  // Virtual scrolling configuration
-  virtual?: {
-    itemSize?: number;
-    overscan?: number; // Extra items to render outside viewport
-    autoDetectItemSize?: boolean; // Auto-detect item size from first render
-  };
-
-  // Scrolling configuration
-  scrolling?: {
-    orientation?: "vertical" | "horizontal";
-    animation?: boolean; // Smooth scrolling
-    sensitivity?: number; // Scroll sensitivity
-  };
-
-  // Scrollbar configuration
-  scrollbar?: {
-    enabled?: boolean;
-    autoHide?: boolean;
-  };
-
-  // Performance configuration
-  performance?: {
-    maxConcurrentRequests?: number;
-    cancelLoadThreshold?: number; // Velocity threshold for cancelling loads
-    enableRequestQueue?: boolean;
-    recycleElements?: boolean;
-    bufferSize?: number;
-    renderDebounce?: number;
-  };
-
-  // Placeholder configuration
-  placeholders?: {
-    enabled?: boolean;
-    template?: (index: number) => string | HTMLElement;
-    maskCharacter?: string;
-    analyzeFirstLoad?: boolean;
-  };
-}
-
-/**
- * Enhanced component after viewport is applied
- */
-export interface ViewportComponent extends ViewportContext {
-  viewport: {
-    // Core API
-    initialize(): boolean | void;
-    destroy(): void;
-    updateViewport(): void;
-
-    // Scrolling
-    scrollToIndex(index: number, alignment?: "start" | "center" | "end"): void;
-    scrollToPosition(position: number): void;
-    getScrollPosition(): number;
-    scrollBy(delta: number): void;
-    getVelocity(): number;
-
-    // Collection feature (optional)
-    collection?: CollectionComponent["collection"];
-
-    // Info
-    getVisibleRange(): ItemRange;
-    getViewportInfo(): ViewportInfo;
-
-    // Rendering
-    renderItems(): void;
-  };
-}

package/src/core/viewport/utils/speed-tracker.ts

@@ -1,79 +0,0 @@
-// src/core/viewport/utils/speed-tracker.ts
-
-/**
- * Speed tracking utility for viewport
- * Measures velocity and determines loading strategies
- */
-
-import { VIEWPORT_CONSTANTS } from "../constants";
-
-export interface SpeedTracker {
-  velocity: number;
-  direction: "forward" | "backward";
-  isAccelerating: boolean;
-  lastMeasurement: number;
-}
-
-/**
- * Create a new speed tracker instance
- */
-export function createSpeedTracker(): SpeedTracker {
-  return {
-    velocity: 0,
-    direction: "forward",
-    isAccelerating: false,
-    lastMeasurement: Date.now(),
-  };
-}
-
-/**
- * Update speed tracker with new scroll position
- */
-export function updateSpeedTracker(
-  tracker: SpeedTracker,
-  newPosition: number,
-  previousPosition: number
-): SpeedTracker {
-  const now = Date.now();
-  const deltaTime = now - tracker.lastMeasurement;
-  const deltaPosition = newPosition - previousPosition;
-
-  // Calculate velocity (px/ms)
-  const currentVelocity =
-    deltaTime > 0 ? Math.abs(deltaPosition) / deltaTime : 0;
-
-  // Determine direction
-  const direction = deltaPosition >= 0 ? "forward" : "backward";
-
-  // Check if accelerating
-  const isAccelerating = currentVelocity > tracker.velocity;
-
-  // Apply smoothing for more stable velocity tracking
-  const smoothingFactor = 0.85;
-  const smoothedVelocity =
-    tracker.velocity * smoothingFactor +
-    currentVelocity * (1 - smoothingFactor);
-
-  return {
-    velocity: smoothedVelocity,
-    direction,
-    isAccelerating,
-    lastMeasurement: now,
-  };
-}
-
-/**
- * Determine if scroll speed is fast (should defer loading)
- */
-export function isFastScrolling(tracker: SpeedTracker): boolean {
-  return tracker.velocity > VIEWPORT_CONSTANTS.LOADING.CANCEL_THRESHOLD;
-}
-
-/**
- * Get loading strategy based on current speed
- */
-export function getLoadingStrategy(
-  tracker: SpeedTracker
-): "defer" | "immediate" {
-  return isFastScrolling(tracker) ? "defer" : "immediate";
-}

package/src/core/viewport/viewport.ts

@@ -1,265 +0,0 @@
-/**
- * Viewport - Core virtual scrolling engine
- */
-
-import type {
-  ViewportConfig,
-  ViewportContext,
-  ViewportComponent,
-  ItemRange,
-  ViewportInfo,
-} from "./types";
-import { pipe } from "mtrl";
-import { withBase } from "./features/base";
-import { withVirtual } from "./features/virtual";
-import { withScrolling } from "./features/scrolling";
-import { withScrollbar } from "./features/scrollbar";
-import { withCollection } from "./features/collection";
-import { withPlaceholders } from "./features/placeholders";
-import { withRendering } from "./features/rendering";
-import { withEvents } from "./features/events";
-
-// Internal viewport state
-interface ViewportState {
-  scrollPosition: number;
-  totalItems: number;
-  itemSize: number;
-  containerSize: number;
-  virtualTotalSize: number;
-  visibleRange: ItemRange;
-  itemsContainer: HTMLElement | null;
-  velocity: number;
-  scrollDirection: "forward" | "backward";
-}
-
-/**
- * Creates a viewport-enhanced component using composition
- *
- * @param config - Viewport configuration
- * @returns Function that enhances a component with viewport capabilities
- */
-export const createViewport = (config: ViewportConfig = {}) => {
-  return <T extends ViewportContext>(component: T): T & ViewportComponent => {
-    // Track if viewport has been initialized to prevent multiple initializations
-    let isInitialized = false;
-
-    // No normalization needed - we'll use the nested structure directly
-
-    // Create shared viewport state
-    const state: ViewportState = {
-      scrollPosition: 0,
-      totalItems: component.totalItems || 0,
-      itemSize: config.virtual?.itemSize || 50,
-      containerSize: 0,
-      virtualTotalSize: 0,
-      visibleRange: { start: 0, end: 0 },
-      itemsContainer: null,
-      velocity: 0,
-      scrollDirection: "forward",
-    };
-
-    // Create base viewport API
-    const viewportAPI = {
-      // Core API
-      initialize: () => {
-        // Prevent multiple initializations
-        if (isInitialized) {
-          return false;
-        }
-        isInitialized = true;
-
-        // console.log("[Viewport] Initializing with state:", {
-        //   element: !!component.element,
-        //   totalItems: component.totalItems,
-        //   itemSize: config.virtual?.itemSize,
-        // });
-
-        // Initialize container size
-        if (component.element) {
-          state.containerSize =
-            config.scrolling?.orientation === "horizontal"
-              ? component.element.offsetWidth
-              : component.element.offsetHeight;
-
-          // console.log("[Viewport] Container size:", state.containerSize);
-        }
-
-        // Calculate initial virtual size
-        state.virtualTotalSize = state.totalItems * state.itemSize;
-
-        // Calculate initial visible range
-        state.visibleRange = calculateVisibleRange(state.scrollPosition);
-
-        // console.log("[Viewport] Initial state:", {
-        //   containerSize: state.containerSize,
-        //   virtualTotalSize: state.virtualTotalSize,
-        //   visibleRange: state.visibleRange,
-        // });
-      },
-
-      destroy: () => {
-        // Cleanup will be handled by features
-      },
-
-      updateViewport: () => {
-        // Will be implemented by rendering feature
-      },
-
-      // Check if already initialized
-      isInitialized: () => isInitialized,
-
-      // Allow features to check if init should proceed
-      _shouldInit: () => !isInitialized,
-
-      // Scrolling API (will be overridden by scrolling feature)
-      scrollToIndex: (
-        index: number,
-        alignment?: "start" | "center" | "end",
-      ) => {
-        // Placeholder - will be implemented by scrolling feature
-      },
-
-      scrollToPosition: (position: number) => {
-        // Will be implemented by scrolling feature
-      },
-
-      getScrollPosition: () => state.scrollPosition,
-
-      // Info API
-      getVisibleRange: () => state.visibleRange,
-
-      getViewportInfo: (): ViewportInfo => ({
-        containerSize: state.containerSize,
-        totalVirtualSize: state.virtualTotalSize,
-        visibleRange: state.visibleRange,
-        virtualScrollPosition: state.scrollPosition,
-      }),
-
-      // Rendering API
-      renderItems: () => {
-        // Will be implemented by rendering feature
-      },
-
-      // Internal state (for features to access)
-      state,
-    };
-
-    // Helper function to calculate visible range
-    const calculateVisibleRange = (scrollPos: number): ItemRange => {
-      const itemSize = state.itemSize;
-      const start = Math.floor(scrollPos / itemSize);
-      const visibleCount = Math.ceil(state.containerSize / itemSize);
-      const end = Math.min(start + visibleCount, state.totalItems - 1);
-
-      return { start: Math.max(0, start), end: Math.max(0, end) };
-    };
-
-    // Add viewport API to component
-    const baseComponent = {
-      ...component,
-      viewport: viewportAPI,
-    };
-
-    // Build the enhancement pipeline
-    const enhancers: Array<(c: any) => any> = [];
-
-    // Events system (always first - provides communication for other features)
-    enhancers.push(
-      withEvents({
-        debug: config.debug,
-      }),
-    );
-
-    // Base setup (creates DOM structure)
-    enhancers.push(
-      withBase({
-        className: config.className,
-        orientation: config.scrolling?.orientation,
-      }),
-    );
-
-    // Virtual scrolling (required for most features)
-    enhancers.push(
-      withVirtual({
-        itemSize: config.virtual?.itemSize,
-        overscan: config.virtual?.overscan,
-        orientation: config.scrolling?.orientation,
-        autoDetectItemSize: config.virtual?.autoDetectItemSize,
-        initialScrollIndex: (config as any).initialScrollIndex,
-      }),
-    );
-
-    // Scrolling behavior
-    enhancers.push(
-      withScrolling({
-        orientation: config.scrolling?.orientation,
-        sensitivity: config.scrolling?.sensitivity,
-        smoothing: config.scrolling?.animation,
-      }),
-    );
-
-    // Scrollbar (optional)
-    if (config.scrollbar?.enabled !== false) {
-      enhancers.push(
-        withScrollbar({
-          enabled: true,
-          autoHide: config.scrollbar?.autoHide,
-        }),
-      );
-    }
-
-    // Add collection if configured
-    if (config.collection?.adapter) {
-      enhancers.push(
-        withCollection({
-          collection: config.collection.adapter,
-          rangeSize: config.pagination?.limit,
-          strategy: config.pagination?.strategy as
-            | "offset"
-            | "page"
-            | "cursor"
-            | undefined,
-          transform: config.collection?.transform,
-          cancelLoadThreshold: config.performance?.cancelLoadThreshold,
-          maxConcurrentRequests: config.performance?.maxConcurrentRequests,
-          enableRequestQueue: config.performance?.enableRequestQueue !== false,
-          initialScrollIndex: (config as any).initialScrollIndex,
-          selectId: (config as any).selectId,
-          autoLoad: (config as any).autoLoad !== false,
-        }),
-      );
-    }
-
-    // Placeholders (optional, requires collection)
-    if (config.collection?.adapter && config.placeholders?.enabled !== false) {
-      enhancers.push(
-        withPlaceholders({
-          enabled: true,
-          analyzeFirstLoad: config.placeholders?.analyzeFirstLoad ?? true,
-          maskCharacter: config.placeholders?.maskCharacter,
-        }),
-      );
-    }
-
-    // Rendering (always last to have access to all features)
-    enhancers.push(
-      withRendering({
-        template: config.template,
-        overscan: config.virtual?.overscan,
-      }),
-    );
-
-    // Compose all enhancers
-    const enhance = pipe(...enhancers);
-
-    // Apply enhancements
-    const enhanced = enhance(baseComponent);
-
-    // Auto-initialize if element is provided
-    if (enhanced.element) {
-      enhanced.viewport.initialize();
-    }
-
-    return enhanced as T & ViewportComponent;
-  };
-};