mtrl-addons 0.1.2 → 0.2.2

package/src/core/viewport/types.ts

@@ -0,0 +1,133 @@
+// 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

@@ -0,0 +1,79 @@
+// 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

@@ -0,0 +1,265 @@
+/**
+ * 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;
+  };
+};

package/src/index.ts

@@ -3,15 +3,8 @@
  * Additional components and utilities for the mtrl system
  */
 
-// Version info
-export const version = "0.1.0";
-
 // === Core System ===
 export * from "./core";
 
 // === Components ===
 export * from "./components";
-
-// // === Default Export ===
-// // Export the main createLayout function for easy access
-// export { createLayout as default } from "./core/layout";