mtrl-addons 0.1.2 → 0.2.2

package/src/components/{list → vlist}/types.ts

@@ -1,28 +1,40 @@
 /**
- * Types for the mtrl-addons list component
- *
- * Extends collection types with list-specific functionality
+ * VList Types - Virtual List with direct viewport integration
  */
 
-import type {
-  CollectionItem,
-  CollectionConfig,
-  Collection,
-  TemplateDefinition,
-} from "../../core/collection";
-import type { BaseComponent, ElementComponent } from "mtrl/src/core/compose";
-import type {
-  ListManager,
-  ListManagerConfig,
-} from "../../core/list-manager/types";
+import type { BaseComponent, ElementComponent } from "mtrl";
+
+/** Options for removeItemById */
+export interface RemoveItemOptions {
+  /** Track as pending removal to filter from future fetches (default: true) */
+  trackPending?: boolean;
+  /** Timeout in ms to clear pending removal (default: 5000) */
+  pendingTimeout?: number;
+}
+// Collection types are not exposed by mtrl; define minimal interfaces locally
+export interface CollectionItem {
+  id: string | number;
+  [key: string]: any;
+}
+
+export interface CollectionConfig<T = any> {
+  adapter?: {
+    read(params?: any): Promise<{ items: T[]; meta?: any; error?: any }>;
+  };
+}
+
+export interface Collection<T = any> {
+  loadMissingRanges?: (
+    range: { start: number; end: number },
+    reason?: string,
+  ) => Promise<void>;
+}
+import type { ViewportComponent } from "../../core/viewport/types";
 
 /**
  * List item interface - extends collection item
  */
-export interface ListItem extends CollectionItem {
-  id: string;
-  [key: string]: any;
-}
+export interface ListItem extends CollectionItem {}
 
 /**
  * List adapter interface - extends collection adapter
@@ -71,14 +83,14 @@ export interface ListAdapterResponse<T extends ListItem = ListItem> {
 /**
  * List template definition
  */
-export type ListTemplate = TemplateDefinition;
+export type ListTemplate = (item: any, index: number) => string | HTMLElement;
 
 /**
  * List item template function
  */
 export type ListItemTemplate<T = any> = (
   item: T,
-  index: number
+  index: number,
 ) => string | HTMLElement;
 
 /**
@@ -89,8 +101,6 @@ export interface ListScrollConfig {
   virtual?: boolean;
   /** Item size (fixed) or 'auto' for dynamic - height for vertical, width for horizontal */
   itemSize?: number | "auto";
-  /** Estimated item size for dynamic sizing */
-  estimatedItemSize?: number;
   /** Number of items to render outside viewport */
   overscan?: number;
   /** Enable scroll animations */
@@ -145,6 +155,8 @@ export interface ListSelectionConfig {
   selectedIndices?: number[];
   /** Selection change callback */
   onSelectionChange?: (selectedItems: any[], selectedIndices: number[]) => void;
+  /** Require keyboard modifiers for multi-select (default: false) */
+  requireModifiers?: boolean;
 }
 
 /**
@@ -174,12 +186,13 @@ export interface ListPaginationConfig {
 /**
  * Complete List component configuration
  */
-export interface ListConfig<T = any> extends ListStyleConfig {
+export interface ListConfig<T extends ListItem = ListItem>
+  extends ListStyleConfig {
   // Data layer (Collection) configuration
   collection?: Partial<CollectionConfig<T>>;
 
   // Performance layer (List Manager) configuration
-  listManager?: Partial<ListManagerConfig>;
+  listManager?: Partial<any>;
 
   // Pagination configuration
   pagination?: ListPaginationConfig;
@@ -320,12 +333,25 @@ export interface ListEvents<T = any> {
   "render:complete": {
     renderRange: { start: number; end: number; count: number };
   };
+
+  /** Item updated */
+  "item:updated": {
+    item: T;
+    index: number;
+    previousItem: T;
+    wasVisible: boolean;
+  };
+
+  /** Viewport range loaded (data available for range) */
+  "viewport:range-loaded": {
+    range: { start: number; end: number };
+  };
 }
 
 /**
  * List component API
  */
-export interface ListAPI<T = any> {
+export interface ListAPI<T extends ListItem = ListItem> {
   // Data management
   /** Load data */
   loadData(): Promise<void>;
@@ -342,9 +368,80 @@ export interface ListAPI<T = any> {
   /** Remove items by indices */
   removeItems(indices: number[]): void;
 
+  /**
+   * Remove item at a specific index
+   * Removes the item from the collection, updates totalItems, and triggers re-render
+   * @param index - The index of the item to remove
+   * @returns true if item was found and removed, false otherwise
+   */
+  removeItem(index: number): boolean;
+
+  /**
+   * Remove item by ID
+   * Finds the item in the collection by its ID and removes it
+   * Updates totalItems and triggers re-render of visible items
+   * Optionally tracks as pending removal to filter from future fetches
+   * @param id - The item ID to find and remove
+   * @param options - Remove options (trackPending, pendingTimeout)
+   * @returns true if item was found and removed, false otherwise
+   */
+  removeItemById(id: string | number, options?: RemoveItemOptions): boolean;
+
+  /**
+   * Check if an item ID is pending removal
+   * @param id - The item ID to check
+   * @returns true if the item is pending removal
+   */
+  isPendingRemoval(id: string | number): boolean;
+
+  /**
+   * Get all pending removal IDs
+   * @returns Set of pending removal IDs
+   */
+  getPendingRemovals(): Set<string | number>;
+
+  /**
+   * Clear a specific pending removal
+   * @param id - The item ID to clear from pending removals
+   */
+  clearPendingRemoval(id: string | number): void;
+
+  /**
+   * Clear all pending removals
+   */
+  clearAllPendingRemovals(): void;
+
+  /**
+   * Filter items array to exclude pending removals
+   * Utility method for use in collection adapters
+   * @param items - Array of items to filter
+   * @returns Filtered array without pending removal items
+   */
+  filterPendingRemovals<I extends { id?: any; _id?: any }>(items: I[]): I[];
+
   /** Update item at index */
   updateItem(index: number, item: T): void;
 
+  /**
+   * Update item by ID
+   * Finds the item in the collection by its ID and updates it with new data
+   * Re-renders the item if currently visible in the viewport
+   * @param id - The item ID to find
+   * @param data - Partial data to merge with existing item, or full item replacement
+   * @param options - Update options
+   * @returns true if item was found and updated, false otherwise
+   */
+  updateItemById(
+    id: string | number,
+    data: Partial<T>,
+    options?: {
+      /** If true, replace the entire item instead of merging (default: false) */
+      replace?: boolean;
+      /** If true, re-render even if not visible (default: false) */
+      forceRender?: boolean;
+    },
+  ): boolean;
+
   /** Get item at index */
   getItem(index: number): T | undefined;
 
@@ -358,7 +455,7 @@ export interface ListAPI<T = any> {
   /** Scroll to item index */
   scrollToIndex(
     index: number,
-    alignment?: "start" | "center" | "end"
+    alignment?: "start" | "center" | "end",
   ): Promise<void>;
 
   /** Scroll to top */
@@ -399,6 +496,32 @@ export interface ListAPI<T = any> {
   /** Check if item is selected */
   isSelected(index: number): boolean;
 
+  /** Select an item by its ID
+   * @param id - The ID of the item to select
+   * @param silent - If true, selection won't emit change event (default: false)
+   */
+  selectById(id: string | number, silent?: boolean): boolean;
+
+  /**
+   * Select item at index, scrolling and waiting for data if needed
+   * Handles virtual scrolling by loading data before selecting
+   */
+  selectAtIndex(index: number): Promise<boolean>;
+
+  /**
+   * Select next item relative to current selection
+   * Handles virtual scrolling by loading data before selecting
+   * @returns Promise resolving to true if selection changed, false if at end
+   */
+  selectNext(): Promise<boolean>;
+
+  /**
+   * Select previous item relative to current selection
+   * Handles virtual scrolling by loading data before selecting
+   * @returns Promise resolving to true if selection changed, false if at start
+   */
+  selectPrevious(): Promise<boolean>;
+
   // State
   /** Get current list state */
   getState(): ListState;
@@ -437,7 +560,7 @@ export interface ListAPI<T = any> {
 
   /** Set error template */
   setErrorTemplate(
-    template: string | ((error: Error) => string | HTMLElement)
+    template: string | ((error: Error) => string | HTMLElement),
   ): void;
 
   // Configuration
@@ -451,7 +574,7 @@ export interface ListAPI<T = any> {
 /**
  * List component interface (extends mtrl component patterns)
  */
-export interface ListComponent<T = any>
+export interface ListComponent<T extends ListItem = ListItem>
   extends BaseComponent,
     ElementComponent,
     ListAPI<T> {
@@ -459,7 +582,7 @@ export interface ListComponent<T = any>
   collection: Collection<T>;
 
   /** List manager instance (performance layer) */
-  listManager: ListManager;
+  listManager: any;
 
   /** Current list state */
   state: ListState;
@@ -477,15 +600,15 @@ export interface ListComponent<T = any>
   /** Event system (inherited from BaseComponent) */
   on<K extends keyof ListEvents<T>>(
     event: K,
-    handler: (payload: ListEvents<T>[K]) => void
+    handler: (payload: ListEvents<T>[K]) => void,
   ): void;
   emit<K extends keyof ListEvents<T>>(
     event: K,
-    payload: ListEvents<T>[K]
+    payload: ListEvents<T>[K],
   ): void;
   off<K extends keyof ListEvents<T>>(
     event: K,
-    handler?: (payload: ListEvents<T>[K]) => void
+    handler?: (payload: ListEvents<T>[K]) => void,
   ): void;
 }
 
@@ -511,3 +634,90 @@ export interface ListFeatures {
   styling?: boolean;
   performance?: boolean;
 }
+
+/**
+ * VList configuration interface
+ */
+export interface VListConfig<T extends ListItem = ListItem> {
+  // Container
+  parent?: HTMLElement | string;
+  container?: HTMLElement | string; // Also support container
+
+  // Basic properties
+  class?: string;
+  className?: string; // Also support className
+  prefix?: string;
+  ariaLabel?: string;
+  debug?: boolean;
+
+  // Initial scroll position (0-based index)
+  // When set, VList will start loading from this position instead of 0
+  initialScrollIndex?: number;
+
+  // ID of item to select after initial load completes
+  // Works with initialScrollIndex to scroll to position and then select the item
+  selectId?: string | number;
+
+  // Whether to automatically load data on initialization (default: true)
+  // Set to false to defer loading until manually triggered
+  autoLoad?: boolean;
+
+  // Data source
+  items?: T[];
+
+  // Template for rendering items
+  template?: (
+    item: T,
+    index: number,
+  ) => string | HTMLElement | any[] | Record<string, any>;
+
+  // Collection configuration
+  collection?: {
+    adapter?: ListAdapter<T>;
+    transform?: (item: T) => T;
+  };
+
+  // Pagination configuration
+  pagination?: {
+    strategy?: "page" | "offset" | "cursor";
+    limit?: number;
+  };
+
+  // Virtual scrolling configuration
+  virtual?: {
+    itemSize?: number;
+    overscan?: number;
+  };
+
+  // Scrolling configuration
+  scrolling?: {
+    orientation?: "vertical" | "horizontal";
+    animation?: boolean;
+    measureItems?: boolean;
+  };
+
+  // Performance settings
+  performance?: {
+    recycleElements?: boolean;
+    bufferSize?: number;
+    renderDebounce?: number;
+    maxConcurrentRequests?: number;
+    /** Velocity threshold (px/ms) above which data loading is cancelled and placeholders are shown. Default: 2 */
+    cancelLoadThreshold?: number;
+  };
+
+  // Selection configuration
+  selection?: ListSelectionConfig;
+
+  // Event handlers
+  on?: ListEventHandlers<T>;
+}
+
+export type VListComponent<T extends ListItem = ListItem> = ListComponent<T> & {
+  viewport: ViewportComponent["viewport"];
+};
+
+export type VListItem = ListItem;
+export type VListAPI<T extends ListItem = ListItem> = ListAPI<T>;
+export type VListState = ListState;
+export type VListEvents<T = any> = ListEvents<T>;

package/src/components/vlist/vlist.ts

@@ -0,0 +1,92 @@
+// src/components/vlist/vlist.ts
+
+/**
+ * VList Component - Virtual List with direct viewport integration
+ *
+ * A simplified virtual list that uses the viewport feature directly
+ * without the list-manager abstraction layer.
+ */
+
+import type { VListConfig, VListComponent, VListItem } from "./types";
+
+// Import mtrl compose system
+import { pipe } from "mtrl";
+import { createBase, withElement } from "mtrl";
+import { withEvents, withLifecycle } from "mtrl";
+
+// Import viewport feature
+import { withViewport } from "./features/viewport";
+import { withAPI } from "./features/api";
+import { withSelection } from "./features/selection";
+
+/**
+ * Creates a new VList component using direct viewport integration
+ *
+ * @param {VListConfig} config - List configuration options
+ * @returns {VListComponent} A fully configured virtual list component
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   container: '#my-list',
+ *   collection: myAdapter,
+ *   rangeSize: 20,
+ *   paginationStrategy: 'page',
+ *   template: (item, index) => [
+ *     { class: 'viewport-item', attributes: { 'data-id': item.id }},
+ *     [{ class: 'viewport-item__name', text: item.name }],
+ *     [{ class: 'viewport-item__value', text: item.value }]
+ *   ]
+ * });
+ * ```
+ */
+export const createVList = <T extends VListItem = VListItem>(
+  config: VListConfig<T> = {}
+): VListComponent<T> => {
+  try {
+    // console.log(`📋 Creating VList component with direct viewport integration`);
+
+    // Note: Transform should be applied by the collection feature in viewport
+    // VList should not intercept collection reads as it bypasses the loading manager
+
+    // Create the component through functional composition
+    const enhancers = [
+      // 1. Foundation layer
+      createBase,
+      withEvents(),
+      withElement({
+        tag: "div",
+        className: config.className || "mtrl-vlist",
+        attributes: {
+          role: "list",
+          "aria-label": config.ariaLabel || "Virtual List",
+        },
+      }),
+
+      // 2. Viewport integration
+      withViewport(config),
+
+      // 3. Component lifecycle
+      withLifecycle(),
+
+      // 4. Public API layer
+      withAPI(config),
+    ];
+
+    // 4.5. Selection capabilities (if enabled) - must be after API
+    if (config.selection?.enabled) {
+      enhancers.push(withSelection(config));
+    }
+
+    const component = pipe(...enhancers)({
+      ...config,
+      componentName: "vlist",
+      prefix: config.prefix || "mtrl",
+    });
+
+    return component as VListComponent<T>;
+  } catch (error) {
+    console.error("❌ [VLIST] Failed to create VList component:", error);
+    throw error;
+  }
+};

package/src/core/compose/features/gestures/index.ts

@@ -0,0 +1,227 @@
+// src/core/compose/features/gestures.ts
+/**
+ * @module core/compose/features
+ * @description Adds gesture recognition capabilities to components
+ */
+
+import { BaseComponent, ElementComponent } from "mtrl";
+import {
+  createGestureManager,
+  GestureManager,
+  GestureConfig,
+  GestureHandler,
+  AnyGestureEvent,
+} from "../../../gestures";
+import { hasLifecycle, hasEmit } from "mtrl";
+
+/**
+ * Configuration for gestures feature
+ */
+export interface GesturesFeatureConfig extends GestureConfig {
+  /**
+   * Whether to enable gesture recognition immediately
+   * @default true
+   */
+  enableGestures?: boolean;
+
+  /**
+   * Initial gesture event handlers
+   */
+  gestureHandlers?: Record<string, GestureHandler>;
+
+  [key: string]: any;
+}
+
+/**
+ * Component with gesture recognition capabilities
+ */
+export interface GesturesComponent extends BaseComponent {
+  /**
+   * Gesture manager instance
+   */
+  gestures: GestureManager;
+
+  /**
+   * Add a gesture event handler
+   * @param eventType - Type of gesture event
+   * @param handler - Event handler function
+   * @returns GesturesComponent for chaining
+   */
+  onGesture: (eventType: string, handler: GestureHandler) => GesturesComponent;
+
+  /**
+   * Remove a gesture event handler
+   * @param eventType - Type of gesture event
+   * @param handler - Event handler function
+   * @returns GesturesComponent for chaining
+   */
+  offGesture: (eventType: string, handler: GestureHandler) => GesturesComponent;
+
+  /**
+   * Check if a gesture type is supported on the current device
+   * @param gestureType - Type of gesture to check
+   * @returns Whether the gesture is supported
+   */
+  isGestureSupported: (gestureType: string) => boolean;
+
+  /**
+   * Enable gesture recognition
+   * @returns GesturesComponent for chaining
+   */
+  enableGestures: () => GesturesComponent;
+
+  /**
+   * Disable gesture recognition
+   * @returns GesturesComponent for chaining
+   */
+  disableGestures: () => GesturesComponent;
+}
+
+/**
+ * Adds gesture recognition capabilities to a component.
+ * This is a comprehensive gesture feature that adds support for all gesture types.
+ * For more lightweight, specific gestures, use the individual gesture features.
+ *
+ * @param config - Configuration object containing gesture settings
+ * @returns Function that enhances a component with gesture capabilities
+ *
+ * @example
+ * ```ts
+ * // Add gesture recognition to a component
+ * const component = pipe(
+ *   createBase,
+ *   withElement(...),
+ *   withGestures({
+ *     swipeThreshold: 50,
+ *     gestureHandlers: {
+ *       'tap': (e) => handleTap(e),
+ *       'swipeleft': (e) => navigateForward(e),
+ *       'swiperight': (e) => navigateBack(e)
+ *     }
+ *   })
+ * )(config);
+ * ```
+ */
+export const withGestures =
+  (config: GesturesFeatureConfig = {}) =>
+  <C extends ElementComponent>(component: C): C & GesturesComponent => {
+    if (!component.element) {
+      console.warn("Cannot add gesture recognition: missing element");
+      return component as C & GesturesComponent;
+    }
+
+    // Default configuration
+    const {
+      enableGestures = true,
+      gestureHandlers = {},
+      ...gestureConfig
+    } = config;
+
+    // Create gesture manager
+    const gestureManager = createGestureManager(
+      component.element,
+      gestureConfig
+    );
+
+    // Add initial gesture handlers
+    Object.entries(gestureHandlers).forEach(([eventType, handler]) => {
+      gestureManager.on(eventType, handler);
+    });
+
+    // Enable/disable based on config
+    if (!enableGestures) {
+      gestureManager.disable();
+    }
+
+    // Connect with existing event system if available
+    if (hasEmit(component)) {
+      // Forward gesture events to the component's event system
+      const forwardGestureEvents = (event: AnyGestureEvent) => {
+        component.emit(event.type, event);
+      };
+
+      // Register forwarder for common gesture types
+      [
+        "tap",
+        "swipe",
+        "swipeleft",
+        "swiperight",
+        "swipeup",
+        "swipedown",
+        "longpress",
+        "pinch",
+        "rotate",
+        "pan",
+      ].forEach((type) => {
+        gestureManager.on(type, forwardGestureEvents);
+      });
+    }
+
+    // Handle lifecycle integration
+    if (hasLifecycle(component)) {
+      const originalDestroy = component.lifecycle.destroy;
+
+      component.lifecycle.destroy = () => {
+        // Clean up gesture manager
+        gestureManager.destroy();
+
+        // Call original destroy method
+        originalDestroy.call(component.lifecycle);
+      };
+    }
+
+    // Create enhanced component
+    return {
+      ...component,
+      gestures: gestureManager,
+
+      /**
+       * Add a gesture event handler
+       * @param eventType - Type of gesture event
+       * @param handler - Event handler function
+       * @returns GesturesComponent for chaining
+       */
+      onGesture(eventType: string, handler: GestureHandler) {
+        gestureManager.on(eventType, handler);
+        return this;
+      },
+
+      /**
+       * Remove a gesture event handler
+       * @param eventType - Type of gesture event
+       * @param handler - Event handler function
+       * @returns GesturesComponent for chaining
+       */
+      offGesture(eventType: string, handler: GestureHandler) {
+        gestureManager.off(eventType, handler);
+        return this;
+      },
+
+      /**
+       * Check if a gesture type is supported on the current device
+       * @param gestureType - Type of gesture to check
+       * @returns Whether the gesture is supported
+       */
+      isGestureSupported(gestureType: string) {
+        return gestureManager.isSupported(gestureType);
+      },
+
+      /**
+       * Enable gesture recognition
+       * @returns GesturesComponent for chaining
+       */
+      enableGestures() {
+        gestureManager.enable();
+        return this;
+      },
+
+      /**
+       * Disable gesture recognition
+       * @returns GesturesComponent for chaining
+       */
+      disableGestures() {
+        gestureManager.disable();
+        return this;
+      },
+    };
+  };