mtrl-addons 0.2.1 → 0.2.2

package/src/components/vlist/index.ts

@@ -7,6 +7,7 @@
 
 export { createVList } from "./vlist";
 export type {
+  RemoveItemOptions,
   VListConfig,
   VListComponent,
   VListItem,

package/src/components/vlist/types.ts

@@ -3,6 +3,14 @@
  */
 
 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;
@@ -18,7 +26,7 @@ export interface CollectionConfig<T = any> {
 export interface Collection<T = any> {
   loadMissingRanges?: (
     range: { start: number; end: number },
-    reason?: string
+    reason?: string,
   ) => Promise<void>;
 }
 import type { ViewportComponent } from "../../core/viewport/types";
@@ -82,7 +90,7 @@ export type ListTemplate = (item: any, index: number) => string | HTMLElement;
  */
 export type ListItemTemplate<T = any> = (
   item: T,
-  index: number
+  index: number,
 ) => string | HTMLElement;
 
 /**
@@ -325,6 +333,19 @@ 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 };
+  };
 }
 
 /**
@@ -347,9 +368,80 @@ export interface ListAPI<T extends ListItem = ListItem> {
   /** 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;
 
@@ -363,7 +455,7 @@ export interface ListAPI<T extends ListItem = ListItem> {
   /** Scroll to item index */
   scrollToIndex(
     index: number,
-    alignment?: "start" | "center" | "end"
+    alignment?: "start" | "center" | "end",
   ): Promise<void>;
 
   /** Scroll to top */
@@ -404,6 +496,32 @@ export interface ListAPI<T extends ListItem = ListItem> {
   /** 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;
@@ -442,7 +560,7 @@ export interface ListAPI<T extends ListItem = ListItem> {
 
   /** Set error template */
   setErrorTemplate(
-    template: string | ((error: Error) => string | HTMLElement)
+    template: string | ((error: Error) => string | HTMLElement),
   ): void;
 
   // Configuration
@@ -482,15 +600,15 @@ export interface ListComponent<T extends ListItem = ListItem>
   /** 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;
 }
 
@@ -532,13 +650,25 @@ export interface VListConfig<T extends ListItem = ListItem> {
   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
+    index: number,
   ) => string | HTMLElement | any[] | Record<string, any>;
 
   // Collection configuration
@@ -572,6 +702,8 @@ export interface VListConfig<T extends ListItem = ListItem> {
     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

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}
@@ -184,7 +184,7 @@ function releaseFragment(fragment: DocumentFragment): void {
  */
 function processClassNames(
   options: Record<string, any>,
-  skipPrefix = false
+  skipPrefix = false,
 ): Record<string, any> {
   if (!options) return options;
 
@@ -231,7 +231,7 @@ function processClassNames(
         .split(/\s+/)
         .filter(Boolean)
         .map((cls) =>
-          cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls
+          cls.startsWith(PREFIX_WITH_DASH) ? cls : PREFIX_WITH_DASH + cls,
         )
         .join(" ");
     }
@@ -271,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;
@@ -379,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
@@ -453,7 +453,7 @@ function createComponentInstance(
             }
           } else {
             for (const [eventName, handler] of Object.entries(
-              finalEventsConfig
+              finalEventsConfig,
             )) {
               if (typeof handler === "function") {
                 element.addEventListener(eventName, handler);
@@ -481,7 +481,7 @@ function createComponentInstance(
  */
 function applyLayoutClasses(
   element: HTMLElement,
-  layoutConfig: LayoutConfig
+  layoutConfig: LayoutConfig,
 ): void {
   if (!element || !layoutConfig) return;
 
@@ -497,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),
       );
     }
   }
@@ -522,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)
@@ -569,7 +569,7 @@ function applyLayoutClasses(
  */
 function applyLayoutItemClasses(
   element: HTMLElement,
-  itemConfig: LayoutItemConfig
+  itemConfig: LayoutItemConfig,
 ): void {
   if (!element || !itemConfig) return;
 
@@ -579,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`);
@@ -638,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"
+        : "";
 }
 
 // ============================================================================
@@ -656,7 +656,7 @@ function processArraySchema(
   schema: SchemaItem[] | any,
   parentElement: HTMLElement | null = null,
   level: number = 0,
-  options: LayoutOptions = {}
+  options: LayoutOptions = {},
 ): LayoutResult {
   level++;
   const layout: Record<string, any> = {};
@@ -678,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;
     }
@@ -774,7 +779,7 @@ function processArraySchema(
 function processObjectSchema(
   schema: Record<string, any> | string,
   parentElement: HTMLElement | null = null,
-  options: LayoutOptions = {}
+  options: LayoutOptions = {},
 ): LayoutResult {
   const layout: Record<string, any> = {};
   const defaultCreator = options.creator || createElement;
@@ -792,7 +797,7 @@ function processObjectSchema(
 
     const rootComponent = createComponentInstance(
       createElementFn,
-      processedOptions
+      processedOptions,
     );
     layout.element = rootComponent;
     if (elementDef.name) layout[elementDef.name] = rootComponent;
@@ -805,7 +810,7 @@ function processObjectSchema(
       const childResult = processObjectSchema(
         elementDef.children,
         rootElement,
-        options
+        options,
       );
       Object.assign(layout, childResult.layout);
     }
@@ -908,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)
@@ -925,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];
+      }
     },
   };
 }
@@ -940,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/viewport/constants.ts

@@ -32,7 +32,7 @@ export const VIEWPORT_CONSTANTS = {
 
   // Loading settings
   LOADING: {
-    CANCEL_THRESHOLD: 2, // px/ms - velocity above which loads cancel
+    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)
@@ -86,6 +86,11 @@ export const VIEWPORT_CONSTANTS = {
     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
@@ -131,7 +136,7 @@ export type ViewportConstants = typeof VIEWPORT_CONSTANTS;
  * Helper function to merge user constants with defaults
  */
 export function mergeConstants(
-  userConstants: Partial<ViewportConstants> = {}
+  userConstants: Partial<ViewportConstants> = {},
 ): ViewportConstants {
   return {
     ...VIEWPORT_CONSTANTS,