mtrl-addons 0.1.2 → 0.2.2

package/src/core/layout/schema.ts

@@ -129,7 +129,7 @@ const PREFIX_WITH_DASH = `${PREFIX}-`;
 function getCachedClassName(
   type: string,
   property: string,
-  value: string | number
+  value: string | number,
 ): string {
   const key = `${type}-${property}-${value}`;
   if (!classCache.has(key)) {
@@ -138,7 +138,7 @@ function getCachedClassName(
         key,
         property === ""
           ? `layout__item--${value}`
-          : `layout__item--${property}-${value}`
+          : `layout__item--${property}-${value}`,
       );
     } else {
       // For layout classes, align uses layout--{type}-{value}
@@ -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
+  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;
   }
-  if (processed.className) {
-    classString += (classString ? " " : "") + processed.className;
+
+  // 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 (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(" ");
+  // Handle rawClass (always processed when present)
+  if (hasRawClass) {
+    const rawString = Array.isArray(hasRawClass)
+      ? hasRawClass.filter(Boolean).join(" ")
+      : hasRawClass;
+
+    finalClasses += (finalClasses ? " " : "") + rawString;
+  }
+
+  if (finalClasses) {
+    processed.class = finalClasses;
   }
 
+  // Clean up in one operation
   delete processed.className;
+  delete processed.rawClass;
+
   return processed;
 }
 
@@ -236,7 +271,7 @@ interface ExtractedParameters {
 function extractParameters(
   schema: SchemaItem[],
   startIndex: number,
-  defaultCreator: Function
+  defaultCreator: Function,
 ): ExtractedParameters {
   const items = schema.slice(startIndex, startIndex + 3);
   let creator, name, options;
@@ -272,7 +307,7 @@ function extractParameters(
   return {
     creator: creator || defaultCreator,
     name,
-    options: options || {},
+    options: (options || {}) as Record<string, any>,
     consumed,
   };
 }
@@ -344,7 +379,7 @@ function hasClass(element: HTMLElement, className: string): boolean {
  */
 function createComponentInstance(
   Component: any,
-  options: Record<string, any> = {}
+  options: Record<string, any> = {},
 ): any {
   try {
     // Destructure special configs in one operation
@@ -418,7 +453,7 @@ function createComponentInstance(
             }
           } else {
             for (const [eventName, handler] of Object.entries(
-              finalEventsConfig
+              finalEventsConfig,
             )) {
               if (typeof handler === "function") {
                 element.addEventListener(eventName, handler);
@@ -446,7 +481,7 @@ function createComponentInstance(
  */
 function applyLayoutClasses(
   element: HTMLElement,
-  layoutConfig: LayoutConfig
+  layoutConfig: LayoutConfig,
 ): void {
   if (!element || !layoutConfig) return;
 
@@ -462,21 +497,21 @@ function applyLayoutClasses(
       addClass(
         element,
         PREFIX_WITH_DASH +
-          getCachedClassName(layoutType, "gap", layoutConfig.gap)
+          getCachedClassName(layoutType, "gap", layoutConfig.gap),
       );
     }
     if (layoutConfig.align) {
       addClass(
         element,
         PREFIX_WITH_DASH +
-          getCachedClassName(layoutType, "align", layoutConfig.align)
+          getCachedClassName(layoutType, "align", layoutConfig.align),
       );
     }
     if (layoutConfig.justify) {
       addClass(
         element,
         PREFIX_WITH_DASH +
-          getCachedClassName(layoutType, "justify", layoutConfig.justify)
+          getCachedClassName(layoutType, "justify", layoutConfig.justify),
       );
     }
   }
@@ -487,17 +522,17 @@ function applyLayoutClasses(
       addClass(
         element,
         PREFIX_WITH_DASH +
-          getCachedClassName("grid", "cols", layoutConfig.columns)
+          getCachedClassName("grid", "cols", layoutConfig.columns),
       );
     } else if (layoutConfig.columns === "auto-fill") {
       addClass(
         element,
-        PREFIX_WITH_DASH + getCachedClassName("grid", "fill", "auto")
+        PREFIX_WITH_DASH + getCachedClassName("grid", "fill", "auto"),
       );
     } else if (layoutConfig.columns === "auto-fit") {
       addClass(
         element,
-        PREFIX_WITH_DASH + getCachedClassName("grid", "cols", "auto-fit")
+        PREFIX_WITH_DASH + getCachedClassName("grid", "cols", "auto-fit"),
       );
     }
     if (layoutConfig.dense)
@@ -534,7 +569,7 @@ function applyLayoutClasses(
  */
 function applyLayoutItemClasses(
   element: HTMLElement,
-  itemConfig: LayoutItemConfig
+  itemConfig: LayoutItemConfig,
 ): void {
   if (!element || !itemConfig) return;
 
@@ -544,53 +579,53 @@ function applyLayoutItemClasses(
   if (itemConfig.width && itemConfig.width >= 1 && itemConfig.width <= 12) {
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "", itemConfig.width)
+      PREFIX_WITH_DASH + getCachedClassName("item", "", itemConfig.width),
     );
   }
   if (itemConfig.sm)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "sm", itemConfig.sm)
+      PREFIX_WITH_DASH + getCachedClassName("item", "sm", itemConfig.sm),
     );
   if (itemConfig.md)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "md", itemConfig.md)
+      PREFIX_WITH_DASH + getCachedClassName("item", "md", itemConfig.md),
     );
   if (itemConfig.lg)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "lg", itemConfig.lg)
+      PREFIX_WITH_DASH + getCachedClassName("item", "lg", itemConfig.lg),
     );
   if (itemConfig.xl)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "xl", itemConfig.xl)
+      PREFIX_WITH_DASH + getCachedClassName("item", "xl", itemConfig.xl),
     );
 
   // Grid span classes
   if (itemConfig.span)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "span", itemConfig.span)
+      PREFIX_WITH_DASH + getCachedClassName("item", "span", itemConfig.span),
     );
   if (itemConfig.rowSpan)
     addClass(
       element,
       PREFIX_WITH_DASH +
-        getCachedClassName("item", "row-span", itemConfig.rowSpan)
+        getCachedClassName("item", "row-span", itemConfig.rowSpan),
     );
 
   // Order and alignment
   if (itemConfig.order)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "order", itemConfig.order)
+      PREFIX_WITH_DASH + getCachedClassName("item", "order", itemConfig.order),
     );
   if (itemConfig.align)
     addClass(
       element,
-      PREFIX_WITH_DASH + getCachedClassName("item", "self", itemConfig.align)
+      PREFIX_WITH_DASH + getCachedClassName("item", "self", itemConfig.align),
     );
   if (itemConfig.auto)
     addClass(element, `${PREFIX_WITH_DASH}layout__item--auto`);
@@ -603,10 +638,10 @@ function getLayoutType(element: HTMLElement): string {
   return hasClass(element, `${PREFIX_WITH_DASH}layout--stack`)
     ? "stack"
     : hasClass(element, `${PREFIX_WITH_DASH}layout--row`)
-    ? "row"
-    : hasClass(element, `${PREFIX_WITH_DASH}layout--grid`)
-    ? "grid"
-    : "";
+      ? "row"
+      : hasClass(element, `${PREFIX_WITH_DASH}layout--grid`)
+        ? "grid"
+        : "";
 }
 
 // ============================================================================
@@ -618,10 +653,10 @@ 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 = {}
+  options: LayoutOptions = {},
 ): LayoutResult {
   level++;
   const layout: Record<string, any> = {};
@@ -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];
@@ -643,6 +678,11 @@ function processArraySchema(
     if (Array.isArray(item)) {
       const container = component || parentElement;
       const result = processArraySchema(item, container, level, options);
+      // Merge nested components array instead of overwriting
+      if (Array.isArray(result.layout.components)) {
+        components.push(...result.layout.components);
+        delete result.layout.components;
+      }
       Object.assign(layout, result.layout);
       continue;
     }
@@ -668,12 +708,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,16 +777,16 @@ 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 = {}
+  options: LayoutOptions = {},
 ): LayoutResult {
   const layout: Record<string, any> = {};
   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 || {};
@@ -754,7 +797,7 @@ function processObjectSchema(
 
     const rootComponent = createComponentInstance(
       createElementFn,
-      processedOptions
+      processedOptions,
     );
     layout.element = rootComponent;
     if (elementDef.name) layout[elementDef.name] = rootComponent;
@@ -767,7 +810,7 @@ function processObjectSchema(
       const childResult = processObjectSchema(
         elementDef.children,
         rootElement,
-        options
+        options,
       );
       Object.assign(layout, childResult.layout);
     }
@@ -778,8 +821,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;
@@ -870,14 +913,47 @@ function createLayoutResult(layout: Record<string, any>): LayoutResult {
     },
 
     destroy(): void {
-      // Call destroy on components
-      for (const key in layout) {
-        const component = layout[key];
-        if (component && typeof component.destroy === "function") {
-          component.destroy();
+      // Track destroyed components to avoid double-destroy
+      const destroyed = new Set<any>();
+
+      // Helper to safely destroy a component
+      const destroyComponent = (component: any): void => {
+        if (!component || destroyed.has(component)) return;
+
+        // Skip plain HTML elements and non-objects
+        if (component instanceof HTMLElement || typeof component !== "object")
+          return;
+
+        // Check if it's a component with destroy method
+        if (typeof component.destroy === "function") {
+          destroyed.add(component);
+          try {
+            component.destroy();
+          } catch (e) {
+            // Ignore destroy errors - component may already be cleaned up
+          }
+        }
+      };
+
+      // First destroy components from the components array (if present)
+      // This ensures all named components are destroyed even if nested
+      if (Array.isArray(layout.components)) {
+        for (const [name, component] of layout.components) {
+          destroyComponent(component);
         }
       }
 
+      // Then iterate over all layout keys for any missed components
+      for (const key in layout) {
+        if (key === "element" || key === "components") continue;
+        destroyComponent(layout[key]);
+      }
+
+      // Clear the components array
+      if (Array.isArray(layout.components)) {
+        layout.components.length = 0;
+      }
+
       // Remove root element from DOM
       if (layout.element) {
         const element = isComponent(layout.element)
@@ -887,6 +963,11 @@ function createLayoutResult(layout: Record<string, any>): LayoutResult {
           element.parentNode.removeChild(element);
         }
       }
+
+      // Clear references to help GC
+      for (const key in layout) {
+        delete layout[key];
+      }
     },
   };
 }
@@ -902,7 +983,7 @@ function createLayoutResult(layout: Record<string, any>): LayoutResult {
 export function createLayout(
   schema: any,
   parentElement: HTMLElement | null = null,
-  options: LayoutOptions = {}
+  options: LayoutOptions = {},
 ): LayoutResult {
   // Handle function schemas
   if (typeof schema === "function") {

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,145 @@
+// 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: 25, // 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
+  },
+
+  // Selection settings
+  SELECTION: {
+    SELECTED_CLASS: "viewport-item--selected",
+  },
+
+  // 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,
+  };
+}