mtrl-addons 0.1.2 → 0.2.1

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

@@ -1,28 +1,32 @@
 /**
- * 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";
+// 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,7 +75,7 @@ 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
@@ -89,8 +93,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 +147,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 +178,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;
@@ -325,7 +330,7 @@ export interface ListEvents<T = any> {
 /**
  * List component API
  */
-export interface ListAPI<T = any> {
+export interface ListAPI<T extends ListItem = ListItem> {
   // Data management
   /** Load data */
   loadData(): Promise<void>;
@@ -451,7 +456,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 +464,7 @@ export interface ListComponent<T = any>
   collection: Collection<T>;
 
   /** List manager instance (performance layer) */
-  listManager: ListManager;
+  listManager: any;
 
   /** Current list state */
   state: ListState;
@@ -511,3 +516,76 @@ 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;
+
+  // 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;
+  };
+
+  // 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;
+      },
+    };
+  };