mtrl 0.3.5 → 0.3.7

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

@@ -0,0 +1,333 @@
+// src/core/collection/list-manager.ts
+
+import { createRouteAdapter, RouteAdapter, QueryDefinition } from './adapters/route';
+
+/**
+ * List item interface
+ */
+export interface ListItem {
+  id: string;
+  [key: string]: any;
+}
+
+/**
+ * List with items setter
+ */
+export interface List {
+  setItems: (items: any[]) => void;
+}
+
+/**
+ * Metadata for pagination
+ */
+export interface PaginationMeta {
+  cursor: string | null;
+  hasNext: boolean;
+}
+
+/**
+ * Response format from loadItems
+ */
+export interface LoadItemsResponse<T = any> {
+  items: T[];
+  meta: PaginationMeta;
+}
+
+/**
+ * Load status callback data
+ */
+export interface LoadStatus<T = any> {
+  loading: boolean;
+  hasNext?: boolean;
+  hasPrev?: boolean;
+  items?: T[];
+}
+
+/**
+ * Page loader configuration
+ */
+export interface PageLoaderConfig<T = any> {
+  onLoad?: (status: LoadStatus<T>) => void;
+  pageSize?: number;
+}
+
+/**
+ * Page loader interface
+ */
+export interface PageLoader<T = any> {
+  /**
+   * Load a specific page by cursor
+   * @param cursor - Cursor pointing to the page
+   * @param addToHistory - Whether to add current cursor to history
+   * @returns Page status
+   */
+  load: (cursor?: string | null, addToHistory?: boolean) => Promise<{
+    hasNext: boolean;
+    hasPrev: boolean;
+  } | undefined>;
+
+  /**
+   * Load next page
+   * @returns Page status
+   */
+  loadNext: () => Promise<{
+    hasNext: boolean;
+    hasPrev: boolean;
+  } | undefined>;
+
+  /**
+   * Load previous page
+   * @returns Page status
+   */
+  loadPrev: () => Promise<{
+    hasNext: boolean;
+    hasPrev: boolean;
+  } | undefined>;
+
+  /**
+   * Current loading state
+   */
+  readonly loading: boolean;
+
+  /**
+   * Current cursor
+   */
+  readonly cursor: string | null;
+}
+
+/**
+ * List manager config
+ */
+export interface ListManagerConfig<T = any> {
+  /**
+   * Transform function to convert API items to app format
+   */
+  transform?: (item: any) => T;
+  
+  /**
+   * Base URL for API requests
+   */
+  baseUrl?: string;
+}
+
+/**
+ * List manager interface
+ */
+export interface ListManager<T = any> {
+  /**
+   * Load items with optional parameters
+   * @param params - Query parameters
+   * @returns Loaded items with pagination metadata
+   */
+  loadItems: (params?: Record<string, any>) => Promise<LoadItemsResponse<T>>;
+  
+  /**
+   * Create a page loader for the specified list
+   * @param list - List to manage
+   * @param config - Page loader configuration
+   * @returns Page loader
+   */
+  createPageLoader: (list: List, config?: PageLoaderConfig<T>) => PageLoader<T>;
+}
+
+/**
+ * Creates a list manager for a specific collection
+ * @param collection - Collection name
+ * @param config - Configuration options
+ * @returns List manager methods
+ */
+export const createListManager = <T = any>(
+  collection: string, 
+  config: ListManagerConfig<T> = {}
+): ListManager<T> => {
+  const {
+    transform = (item: any) => item as T,
+    baseUrl = 'http://localhost:4000/api'
+  } = config;
+
+  // Initialize route adapter
+  const adapter: RouteAdapter = createRouteAdapter({
+    base: baseUrl,
+    endpoints: {
+      list: `/${collection}`
+    },
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+
+  /**
+   * Load items with cursor pagination
+   * @param params - Query parameters
+   * @returns Loaded items with pagination metadata
+   */
+  const loadItems = async (params: Record<string, any> = {}): Promise<LoadItemsResponse<T>> => {
+    try {
+      const response = await adapter.read(params as QueryDefinition);
+
+      return {
+        items: response.items.map(transform),
+        meta: response.meta as PaginationMeta
+      };
+    } catch (error) {
+      console.error(`Error loading ${collection}:`, error);
+      return {
+        items: [],
+        meta: {
+          cursor: null,
+          hasNext: false
+        }
+      };
+    }
+  };
+
+  /**
+   * Create a page loader for the specified list
+   * @param list - List to manage
+   * @param config - Page loader configuration
+   * @returns Page loader
+   */
+  const createPageLoader = (
+    list: List, 
+    { onLoad, pageSize = 20 }: PageLoaderConfig<T> = {}
+  ): PageLoader<T> => {
+    let currentCursor: string | null = null;
+    let loading = false;
+    const pageHistory: Array<string | null> = [];
+
+    /**
+     * Load a specific page by cursor
+     * @param cursor - Cursor pointing to the page
+     * @param addToHistory - Whether to add current cursor to history
+     * @returns Page status
+     */
+    const load = async (
+      cursor: string | null = null, 
+      addToHistory = true
+    ): Promise<{ hasNext: boolean; hasPrev: boolean } | undefined> => {
+      if (loading) return;
+
+      loading = true;
+      onLoad?.({ loading: true });
+
+      const { items, meta } = await loadItems({
+        limit: pageSize,
+        cursor
+      });
+
+      if (addToHistory && cursor) {
+        pageHistory.push(currentCursor);
+      }
+      currentCursor = meta.cursor;
+
+      list.setItems(items);
+      loading = false;
+
+      const status = {
+        loading: false,
+        hasNext: meta.hasNext,
+        hasPrev: pageHistory.length > 0,
+        items
+      };
+      
+      onLoad?.(status);
+
+      return {
+        hasNext: meta.hasNext,
+        hasPrev: pageHistory.length > 0
+      };
+    };
+
+    /**
+     * Load next page
+     * @returns Page status
+     */
+    const loadNext = (): Promise<{ hasNext: boolean; hasPrev: boolean } | undefined> => 
+      load(currentCursor);
+
+    /**
+     * Load previous page
+     * @returns Page status
+     */
+    const loadPrev = (): Promise<{ hasNext: boolean; hasPrev: boolean } | undefined> => {
+      const previousCursor = pageHistory.pop();
+      return load(previousCursor, false);
+    };
+
+    return {
+      load,
+      loadNext,
+      loadPrev,
+      get loading(): boolean { return loading; },
+      get cursor(): string | null { return currentCursor; }
+    };
+  };
+
+  return {
+    loadItems,
+    createPageLoader
+  };
+};
+
+/**
+ * Transform functions for common collections
+ */
+export const transforms = {
+  /**
+   * Transform track data
+   * @param track - Raw track data
+   * @returns Formatted track data
+   */
+  track: (track: any): ListItem => ({
+    id: track._id,
+    headline: track.title || 'Untitled',
+    supportingText: track.artist || 'Unknown Artist',
+    meta: track.year?.toString() || ''
+  }),
+
+  /**
+   * Transform playlist data
+   * @param playlist - Raw playlist data
+   * @returns Formatted playlist data
+   */
+  playlist: (playlist: any): ListItem => ({
+    id: playlist._id,
+    headline: playlist.name || 'Untitled Playlist',
+    supportingText: `${playlist.tracks?.length || 0} tracks`,
+    meta: playlist.creator || ''
+  }),
+
+  /**
+   * Transform country data
+   * @param country - Raw country data
+   * @returns Formatted country data
+   */
+  country: (country: any): ListItem => ({
+    id: country._id,
+    headline: country.name || country.code,
+    supportingText: country.continent || '',
+    meta: country.code || ''
+  })
+};
+
+/**
+ * Usage example:
+ *
+ * const trackManager = createListManager<TrackItem>('track', {
+ *   transform: transforms.track
+ * });
+ *
+ * const loader = trackManager.createPageLoader(list, {
+ *   onLoad: ({ loading, hasNext, items }) => {
+ *     updateNavigation({ loading, hasNext });
+ *     logEvent(`Loaded ${items.length} tracks`);
+ *   }
+ * });
+ *
+ * // Initial load
+ * await loader.load();
+ *
+ * // Navigation
+ * nextButton.onclick = () => loader.loadNext();
+ * prevButton.onclick = () => loader.loadPrev();
+ */

package/src/core/dom/classes.ts

@@ -1,60 +1,132 @@
 // src/core/dom/classes.ts
 /**
  * @module core/dom
- * @description DOM manipulation utilities
+ * @description DOM manipulation utilities optimized for performance
  */
 
 import { normalizeClasses } from '../utils';
+import { PREFIX } from '../config';
+
+// Constant for prefix with dash for better performance
+const PREFIX_WITH_DASH = `${PREFIX}-`;
 
 /**
  * Adds multiple classes to an element
+ * Automatically adds prefix to classes that don't already have it
+ * Optimized for minimal array operations and DOM interactions
+ * 
  * @param {HTMLElement} element - Target element
  * @param {...(string | string[])} classes - Classes to add
  * @returns {HTMLElement} Modified element
  */
 export const addClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
   const normalizedClasses = normalizeClasses(...classes);
-  if (normalizedClasses.length) {
-    element.classList.add(...normalizedClasses);
+  
+  // Early return for empty classes
+  if (!normalizedClasses.length) return element;
+  
+  // Using DOMTokenList's add() with multiple arguments is faster than multiple add() calls
+  // But we need to handle prefixing first
+  const prefixedClasses: string[] = [];
+  
+  for (let i = 0; i < normalizedClasses.length; i++) {
+    const cls = normalizedClasses[i];
+    if (!cls) continue;
+    
+    prefixedClasses.push(
+      cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls
+    );
+  }
+  
+  // Add all classes in a single operation if possible
+  if (prefixedClasses.length) {
+    element.classList.add(...prefixedClasses);
   }
+  
   return element;
 };
 
 /**
  * Removes multiple classes from an element
+ * Handles only exact class names as specified (no automatic prefixing)
+ * For better performance, clients should know exactly which classes to remove
+ * 
  * @param {HTMLElement} element - Target element
  * @param {...(string | string[])} classes - Classes to remove
  * @returns {HTMLElement} Modified element
  */
 export const removeClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
   const normalizedClasses = normalizeClasses(...classes);
-  if (normalizedClasses.length) {
-    element.classList.remove(...normalizedClasses);
+  
+  // Early return for empty classes
+  if (!normalizedClasses.length) return element;
+  
+  // Prepare prefixed class names
+  const prefixedClasses: string[] = [];
+  
+  for (let i = 0; i < normalizedClasses.length; i++) {
+    const cls = normalizedClasses[i];
+    if (!cls) continue;
+    
+    // Only add the prefixed version
+    prefixedClasses.push(
+      cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls
+    );
+  }
+  
+  // Remove all classes in a single operation if possible
+  if (prefixedClasses.length) {
+    element.classList.remove(...prefixedClasses);
   }
+  
   return element;
 };
 
 /**
  * Toggles multiple classes on an element
+ * Automatically adds prefix to classes that don't already have it
+ * 
  * @param {HTMLElement} element - Target element
  * @param {...(string | string[])} classes - Classes to toggle
  * @returns {HTMLElement} Modified element
  */
 export const toggleClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
   const normalizedClasses = normalizeClasses(...classes);
-  normalizedClasses.forEach(cls => {
-    element.classList.toggle(cls);
-  });
+  
+  for (let i = 0; i < normalizedClasses.length; i++) {
+    const cls = normalizedClasses[i];
+    if (!cls) continue;
+    
+    const prefixedClass = cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls;
+    element.classList.toggle(prefixedClass);
+  }
+  
   return element;
 };
 
 /**
  * Checks if an element has all specified classes
+ * Automatically adds prefix to classes that don't already have it
+ * 
  * @param {HTMLElement} element - Target element
  * @param {...(string | string[])} classes - Classes to check
  * @returns {boolean} True if element has all specified classes
  */
 export const hasClass = (element: HTMLElement, ...classes: (string | string[])[]): boolean => {
   const normalizedClasses = normalizeClasses(...classes);
-  return normalizedClasses.every(cls => element.classList.contains(cls));
+  
+  // Early return for empty classes (technically all are present)
+  if (!normalizedClasses.length) return true;
+  
+  for (let i = 0; i < normalizedClasses.length; i++) {
+    const cls = normalizedClasses[i];
+    if (!cls) continue;
+    
+    const prefixedClass = cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls;
+    if (!element.classList.contains(prefixedClass)) {
+      return false;
+    }
+  }
+  
+  return true;
 };

package/src/core/dom/create.ts

@@ -7,6 +7,7 @@
 import { setAttributes } from './attributes';
 import { normalizeClasses } from '../utils';
 import { PREFIX } from '../config';
+import { addClass } from './classes'; // Import addClass
 
 /**
  * Event handler function type
@@ -58,9 +59,22 @@ export interface CreateElementOptions {
   data?: Record<string, string>;
   
   /**
-   * CSS classes
+   * CSS classes (will be automatically prefixed with 'mtrl-')
+   * Alias for 'className'
    */
-  className?: string | string[] | null;
+  class?: string | string[];
+  
+  /**
+   * CSS classes (will be automatically prefixed with 'mtrl-')
+   * Alias for 'class'
+   */
+  className?: string | string[];
+  
+  /**
+   * CSS classes that will NOT be prefixed
+   * Added as-is to the element
+   */
+  rawClass?: string | string[];
   
   /**
    * HTML attributes
@@ -95,9 +109,6 @@ export interface EventHandlerStorage {
   [eventName: string]: EventHandler;
 }
 
-// Constant for prefix with dash
-const PREFIX_WITH_DASH = `${PREFIX}-`;
-
 /**
  * Creates a DOM element with the specified options
  *
@@ -112,7 +123,9 @@ export const createElement = (options: CreateElementOptions = {}): HTMLElement =
     text = '',
     id = '',
     data = {},
+    class: classOption,
     className,
+    rawClass,
     attrs = {},
     forwardEvents = {},
     onCreate,
@@ -127,14 +140,17 @@ export const createElement = (options: CreateElementOptions = {}): HTMLElement =
   if (text) element.textContent = text;
   if (id) element.id = id;
 
-  // Handle classes
-  if (className) {
-    const classes = normalizeClasses(className);
-    if (classes.length) {
-      // Apply prefix to classes in a single operation
-      element.classList.add(...classes.map(cls => 
-        cls && !cls.startsWith(PREFIX_WITH_DASH) ? PREFIX_WITH_DASH + cls : cls
-      ).filter(Boolean));
+  // 1. Handle prefixed classes using addClass
+  const prefixedClassSource = classOption || className;
+  if (prefixedClassSource) {
+    addClass(element, prefixedClassSource);
+  }
+  
+  // 2. Handle raw classes (no prefix)
+  if (rawClass) {
+    const rawClasses = normalizeClasses(rawClass);
+    if (rawClasses.length) {
+      element.classList.add(...rawClasses);
     }
   }
 
@@ -230,12 +246,7 @@ export const withAttributes = (attrs: Record<string, any>) =>
  */
 export const withClasses = (...classes: (string | string[])[]) => 
   (element: HTMLElement): HTMLElement => {
-    const normalizedClasses = normalizeClasses(...classes);
-    if (normalizedClasses.length) {
-      element.classList.add(...normalizedClasses.map(cls => 
-        cls && !cls.startsWith(PREFIX_WITH_DASH) ? PREFIX_WITH_DASH + cls : cls
-      ).filter(Boolean));
-    }
+    addClass(element, ...classes);
     return element;
   };