mtrl-addons 0.1.1 → 0.2.1

package/src/core/layout/schema.ts

@@ -180,45 +180,80 @@ function releaseFragment(fragment: DocumentFragment): void {
 
 /**
  * Optimized class processing with minimal string operations
- * Handles arrays, strings, and className aliases efficiently
+ * Handles arrays, strings, className aliases, and rawClass efficiently
  */
 function processClassNames(
   options: Record<string, any>,
   skipPrefix = false
 ): Record<string, any> {
-  if (!options || skipPrefix) return { ...options };
+  if (!options) return options;
 
-  const hasClassProps = options.class || options.className;
-  if (!hasClassProps) return { ...options };
+  const hasRawClass = options.rawClass;
+  const hasRegularClass = options.class || options.className;
 
-  const processed = { ...options };
+  // Fast path: no class properties at all
+  if (!hasRawClass && !hasRegularClass) return options;
+
+  // Fast path: only rawClass and skipping prefix (most common rawClass scenario)
+  if (hasRawClass && !hasRegularClass && skipPrefix) {
+    const processed = { ...options };
+    delete processed.rawClass;
 
-  // Combine class sources efficiently
-  let classString = "";
-  if (processed.class) {
-    // Handle arrays by joining first
-    if (Array.isArray(processed.class)) {
-      classString += processed.class.join(" ");
+    // Direct assignment for simple string
+    if (typeof hasRawClass === "string") {
+      processed.class = hasRawClass;
     } else {
-      classString += processed.class;
+      // Handle array case
+      processed.class = hasRawClass.join(" ");
+    }
+    return processed;
+  }
+
+  // Full processing path (only when needed)
+  const processed = { ...options };
+  let finalClasses = "";
+
+  // Handle prefixed classes only if not skipping prefix
+  if (!skipPrefix && hasRegularClass) {
+    let prefixedString = "";
+
+    if (processed.class) {
+      prefixedString += Array.isArray(processed.class)
+        ? processed.class.join(" ")
+        : processed.class;
+    }
+    if (processed.className) {
+      prefixedString += (prefixedString ? " " : "") + processed.className;
+    }
+
+    if (prefixedString) {
+      finalClasses = prefixedString
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((cls) =>
+          cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls
+        )
+        .join(" ");
     }
   }
-  if (processed.className) {
-    classString += (classString ? " " : "") + processed.className;
+
+  // Handle rawClass (always processed when present)
+  if (hasRawClass) {
+    const rawString = Array.isArray(hasRawClass)
+      ? hasRawClass.filter(Boolean).join(" ")
+      : hasRawClass;
+
+    finalClasses += (finalClasses ? " " : "") + rawString;
   }
 
-  if (classString) {
-    // Single pass prefix application
-    processed.class = classString
-      .split(/\s+/)
-      .filter(Boolean)
-      .map((cls) =>
-        cls && !cls.startsWith(PREFIX_WITH_DASH) ? PREFIX_WITH_DASH + cls : cls
-      )
-      .join(" ");
+  if (finalClasses) {
+    processed.class = finalClasses;
   }
 
+  // Clean up in one operation
   delete processed.className;
+  delete processed.rawClass;
+
   return processed;
 }
 
@@ -272,7 +307,7 @@ function extractParameters(
   return {
     creator: creator || defaultCreator,
     name,
-    options: options || {},
+    options: (options || {}) as Record<string, any>,
     consumed,
   };
 }
@@ -618,7 +653,7 @@ function getLayoutType(element: HTMLElement): string {
  * Optimized with parameter extraction and integrated configuration
  */
 function processArraySchema(
-  schema: SchemaItem[],
+  schema: SchemaItem[] | any,
   parentElement: HTMLElement | null = null,
   level: number = 0,
   options: LayoutOptions = {}
@@ -633,7 +668,7 @@ function processArraySchema(
     return createLayoutResult(layout);
   }
 
-  const defaultCreator = options.creator || createElement;
+  const defaultCreator = (options as any).creator || createElement;
 
   for (let i = 0; i < schema.length; i++) {
     const item = schema[i];
@@ -668,12 +703,15 @@ function processArraySchema(
     // Advance index by consumed items minus 1 (loop increment handles the +1)
     i += consumed - 1;
 
-    // Process options with prefix
+    // Process options with prefix - optimized decision logic
     const shouldApplyPrefix =
       "prefix" in itemOptions ? itemOptions.prefix : options.prefix !== false;
-    const processedOptions = shouldApplyPrefix
-      ? processClassNames(itemOptions)
-      : { ...itemOptions };
+
+    // Fast path: process only when needed
+    const processedOptions =
+      shouldApplyPrefix || itemOptions.rawClass
+        ? processClassNames(itemOptions, !shouldApplyPrefix)
+        : itemOptions; // No copy needed if no processing
 
     // Add name to options if needed
     if (
@@ -734,7 +772,7 @@ function processArraySchema(
  * Simplified and optimized for better performance
  */
 function processObjectSchema(
-  schema: Record<string, any>,
+  schema: Record<string, any> | string,
   parentElement: HTMLElement | null = null,
   options: LayoutOptions = {}
 ): LayoutResult {
@@ -742,8 +780,8 @@ function processObjectSchema(
   const defaultCreator = options.creator || createElement;
 
   // Handle root element creation
-  if (schema.element && !parentElement) {
-    const elementDef = schema.element;
+  if ((schema as any).element && !parentElement) {
+    const elementDef = (schema as any).element;
     const createElementFn = elementDef.creator || defaultCreator;
 
     const elementOptions = elementDef.options || {};
@@ -778,8 +816,8 @@ function processObjectSchema(
   // Process normal schema elements
   const fragment = parentElement ? createFragment() : null;
 
-  for (const key in schema) {
-    const def = schema[key];
+  for (const key in schema as Record<string, any>) {
+    const def = (schema as Record<string, any>)[key];
     if (!def) continue;
 
     const elementCreator = def.creator || defaultCreator;

package/src/core/layout/types.ts

@@ -37,12 +37,15 @@ export interface ElementOptions extends Record<string, any> {
   /** Layout item configuration */
   layoutItem?: LayoutItemConfig;
 
-  /** CSS classes to apply */
+  /** CSS classes to apply (with automatic mtrl- prefix) */
   class?: string;
 
   /** Additional CSS classes (alias for class) */
   className?: string;
 
+  /** CSS classes to apply without prefix */
+  rawClass?: string | string[];
+
   /** HTML tag name for createElement */
   tag?: string;
 
@@ -89,4 +92,4 @@ export interface Schema {
 
   /** Additional elements */
   [key: string]: ElementDefinition | undefined;
-}
+}

package/src/core/viewport/constants.ts

@@ -0,0 +1,140 @@
+// src/core/viewport/constants.ts
+
+/**
+ * Viewport Constants
+ * Centralized constants for all viewport functionality
+ * Consolidated from viewport, viewport/features, and list-manager constants
+ */
+
+export const VIEWPORT_CONSTANTS = {
+  // Virtual scrolling defaults
+  VIRTUAL_SCROLL: {
+    DEFAULT_ITEM_SIZE: 48,
+    OVERSCAN_BUFFER: 2,
+    SCROLL_SENSITIVITY: 0.7,
+    MAX_VIRTUAL_SIZE: 100 * 1000 * 1000, // 100M pixels - modern browsers can handle this
+    AUTO_DETECT_ITEM_SIZE: true, // Enable automatic item size detection
+  },
+
+  // Scrolling settings
+  SCROLLING: {
+    OVERSCAN: 1, // From features/constants
+  },
+
+  // Rendering settings
+  RENDERING: {
+    // Element recycling
+    DEFAULT_MAX_POOL_SIZE: 100,
+    CLASSES: {
+      ITEM: "viewport-item",
+    },
+  },
+
+  // Loading settings
+  LOADING: {
+    CANCEL_THRESHOLD: 2, // px/ms - velocity above which loads cancel
+    MAX_CONCURRENT_REQUESTS: 1, // Parallel requests allowed
+    DEFAULT_RANGE_SIZE: 20, // Items per request
+    DEBOUNCE_LOADING: 150, // Debounce delay (ms)
+    MIN_RANGE_SIZE: 10, // Minimum items per load
+    MAX_RANGE_SIZE: 100, // Maximum items per load
+    REQUEST_TIMEOUT: 5000, // Request timeout (ms)
+    RETRY_ATTEMPTS: 2, // Failed request retries
+    RETRY_DELAY: 1000, // Delay between retries (ms)
+  },
+
+  // Request queue configuration (from features/constants)
+  REQUEST_QUEUE: {
+    ENABLED: true, // Enable request queuing
+    MAX_QUEUE_SIZE: 1, // Max queued requests
+    MAX_ACTIVE_REQUESTS: 2, // Max concurrent active requests
+  },
+
+  // Placeholder settings
+  PLACEHOLDER: {
+    MASK_CHARACTER: "X", // Updated from list-manager
+    CLASS: "viewport-item--placeholder",
+    MAX_SAMPLE_SIZE: 20,
+    PLACEHOLDER_FLAG: "_placeholder",
+    RANDOM_LENGTH_VARIANCE: true,
+  },
+
+  // Speed tracking (from list-manager)
+  SPEED_TRACKING: {
+    // Velocity calculation
+    DECELERATION_FACTOR: 0.85, // velocity decay per frame
+  },
+
+  // Momentum settings
+  MOMENTUM: {
+    ENABLED: false, // Enable momentum by default
+    DECELERATION_FACTOR: 0.85, // How quickly velocity decreases per frame
+    MIN_VELOCITY: 0.1, // Minimum velocity before stopping (px/ms)
+    MIN_DURATION: 300, // Maximum gesture duration to trigger momentum (ms)
+    MIN_VELOCITY_THRESHOLD: 0.5, // Minimum velocity to trigger momentum (px/ms)
+    FRAME_TIME: 16, // Assumed frame time for calculations (ms)
+  },
+
+  // Initial load configuration (from list-manager)
+  INITIAL_LOAD: {
+    STRATEGY: "placeholders", // "placeholders" | "direct" | "progressive"
+    VIEWPORT_MULTIPLIER: 1.5, // load 1.5x viewport capacity
+    MIN_ITEMS: 10,
+    MAX_ITEMS: 100,
+    PLACEHOLDER_COUNT: 20, // default placeholder count
+    SHOW_LOADING_STATE: true,
+    LOADING_DELAY: 100, // ms - delay before showing loading state
+  },
+
+  // Scrollbar settings (from list-manager)
+  SCROLLBAR: {
+    // CSS classes
+    CLASSES: {
+      SCROLLBAR: "viewport__scrollbar",
+      SCROLLBAR_TRACK: "viewport__scrollbar-track",
+      SCROLLBAR_THUMB: "viewport__scrollbar-thumb",
+      SCROLLBAR_VISIBLE: "viewport__scrollbar--visible",
+      SCROLLBAR_DRAGGING: "viewport__scrollbar--dragging",
+      SCROLLBAR_THUMB_DRAGGING: "viewport__scrollbar-thumb--dragging",
+    },
+  },
+
+  // Orientation (from list-manager)
+  ORIENTATION: {
+    DEFAULT_ORIENTATION: "vertical",
+    DEFAULT_CROSS_AXIS_ALIGNMENT: "stretch",
+    REVERSE_DIRECTION: false,
+  },
+
+  PAGINATION: {
+    DEFAULT_STRATEGY: "offset" as "offset" | "page" | "cursor",
+    DEFAULT_LIMIT: 20,
+    STRATEGIES: {
+      PAGE: "page" as const,
+      OFFSET: "offset" as const,
+      CURSOR: "cursor" as const,
+    },
+    CURSOR_CLEANUP_INTERVAL: 60000, // Clean up old cursors every minute
+    MAX_CURSOR_MAP_SIZE: 1000, // Maximum number of cursors to keep in memory
+    // Cursor-specific virtual sizing
+    CURSOR_SCROLL_MARGIN_MULTIPLIER: 3, // Multiply rangeSize by this for scroll margin
+    CURSOR_MIN_VIRTUAL_SIZE_MULTIPLIER: 3, // Minimum virtual size as multiplier of rangeSize
+  },
+};
+
+/**
+ * Type for overriding constants at runtime
+ */
+export type ViewportConstants = typeof VIEWPORT_CONSTANTS;
+
+/**
+ * Helper function to merge user constants with defaults
+ */
+export function mergeConstants(
+  userConstants: Partial<ViewportConstants> = {}
+): ViewportConstants {
+  return {
+    ...VIEWPORT_CONSTANTS,
+    ...userConstants,
+  };
+}

package/src/core/viewport/features/base.ts

@@ -0,0 +1,73 @@
+// src/core/viewport/features/base.ts
+
+/**
+ * Base Viewport Feature - Sets up core viewport structure
+ * Provides the foundation for other viewport features
+ */
+
+import type { ViewportContext, ViewportComponent } from "../types";
+import { wrapInitialize, getViewportState } from "./utils";
+
+export interface BaseConfig {
+  className?: string;
+  orientation?: "vertical" | "horizontal";
+}
+
+/**
+ * Base feature for viewport
+ * Sets up the DOM structure and core styles
+ */
+export const withBase = (config: BaseConfig = {}) => {
+  return <T extends ViewportContext & ViewportComponent>(component: T): T => {
+    const { className = "mtrl-viewport", orientation = "vertical" } = config;
+
+    // Use the shared wrapper utility
+    wrapInitialize(component, () => {
+      const element = component.element;
+      if (!element) return;
+
+      // Create viewport structure
+      let viewportElement = element.querySelector(
+        ".mtrl-viewport"
+      ) as HTMLElement;
+
+      if (!viewportElement) {
+        viewportElement = document.createElement("div");
+        viewportElement.className = className;
+        viewportElement.style.cssText = `
+          position: relative;
+          width: 100%;
+          height: 100%;
+          overflow: hidden;
+        `;
+
+        // Set orientation
+        viewportElement.setAttribute("data-orientation", orientation);
+
+        // Create items container
+        const itemsContainer = document.createElement("div");
+        itemsContainer.className = "mtrl-viewport-items";
+        itemsContainer.style.cssText = `
+          position: relative;
+          width: 100%;
+        `;
+
+        viewportElement.appendChild(itemsContainer);
+        element.appendChild(viewportElement);
+
+        // Update viewport state with containers using utility
+        const state = getViewportState(component);
+        if (state) {
+          state.viewportElement = viewportElement;
+          state.itemsContainer = itemsContainer;
+        }
+
+        // Store references on component
+        (component as any).viewportElement = viewportElement;
+        (component as any).itemsContainer = itemsContainer;
+      }
+    });
+
+    return component;
+  };
+};