mtrl-addons 0.2.1 → 0.2.2

package/src/components/vlist/features/api.ts

@@ -3,13 +3,13 @@
  * Provides a clean public API for the VList component
  */
 
-import type { VListConfig, VListItem } from "../types";
+import type { VListConfig, VListItem, RemoveItemOptions } from "../types";
+
+// Re-export for convenience
+export type { RemoveItemOptions } from "../types";
 
-/**
- * Adds public API methods to VList
- */
 export const withAPI = <T extends VListItem = VListItem>(
-  config: VListConfig<T>
+  config: VListConfig<T>,
 ) => {
   return (component: any) => {
     // Initialize viewport on creation
@@ -23,6 +23,10 @@ export const withAPI = <T extends VListItem = VListItem>(
     let isLoading = false;
     let selectedIds = new Set<string | number>();
 
+    // Track pending removals to filter out items from stale server responses
+    // This prevents race conditions where server returns old data before updates are committed
+    const pendingRemovals = new Set<string | number>();
+
     // Listen for collection events
     component.on?.("collection:range-loaded", () => {
       isLoading = false;
@@ -69,12 +73,276 @@ export const withAPI = <T extends VListItem = VListItem>(
         return component.totalItems || component.items?.length || 0;
       },
 
+      /**
+       * Get item at a specific index
+       * @param index - The index of the item to retrieve
+       * @returns The item at the index, or undefined if not found
+       */
+      getItem(index: number): T | undefined {
+        if ((component as any).collection?.getItem) {
+          return (component as any).collection.getItem(index);
+        }
+        const items = this.getItems();
+        return items[index];
+      },
+
+      /**
+       * Update item at a specific index
+       * @param index - The index of the item to update
+       * @param item - The new item data (full replacement)
+       */
+      updateItem(index: number, item: T): void {
+        const items = this.getItems();
+
+        if (index < 0 || index >= items.length) {
+          console.warn(`[VList] updateItem: index ${index} out of bounds`);
+          return;
+        }
+
+        const previousItem = items[index];
+
+        // Update in collection items array
+        if ((component as any).collection?.items) {
+          (component as any).collection.items[index] = item;
+        }
+
+        // Emit event for rendering feature to handle DOM update
+        component.emit?.("item:update-request", {
+          index,
+          item,
+          previousItem,
+        });
+      },
+
+      /**
+       * 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 {
+        const { replace = false } = options;
+        const items = this.getItems();
+
+        // Find the item by ID (handle sparse arrays from pagination)
+        // Check all possible ID fields since items may have different ID structures
+        const index = items.findIndex((item: any) => {
+          if (!item) return false;
+          // Check all possible ID fields - user_id is important for profile/contact items
+          const idsToCheck = [item.id, item._id, item.user_id].filter(
+            (v) => v !== undefined && v !== null,
+          );
+          return idsToCheck.some(
+            (itemId) => itemId === id || String(itemId) === String(id),
+          );
+        });
+
+        if (index === -1) {
+          console.warn(`[VList] updateItemById: item with id ${id} not found`);
+          return false;
+        }
+
+        const previousItem = items[index];
+
+        // Create updated item - either replace entirely or merge
+        let updatedItem: T;
+        if (replace) {
+          updatedItem = { ...data, id: previousItem.id ?? id } as T;
+        } else {
+          // Only merge properties that have actual values (not undefined)
+          // This prevents partial updates from overwriting existing data
+          updatedItem = { ...previousItem } as T;
+          for (const [key, value] of Object.entries(data)) {
+            if (value !== undefined) {
+              (updatedItem as any)[key] = value;
+            }
+          }
+        }
+
+        // Update in collection items array
+        if ((component as any).collection?.items) {
+          (component as any).collection.items[index] = updatedItem;
+        }
+
+        // Emit event for rendering feature to handle DOM update
+        component.emit?.("item:update-request", {
+          index,
+          item: updatedItem,
+          previousItem,
+        });
+
+        return true;
+      },
+
+      /**
+       * 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 {
+        const items = this.getItems();
+        const collection = (component as any).collection;
+
+        if (index < 0 || index >= items.length) {
+          console.warn(`[VList] removeItem: index ${index} out of bounds`);
+          return false;
+        }
+
+        const removedItem = items[index];
+
+        // Remove from collection items array (component.collection.items is the actual array)
+        if ((component as any).collection?.items) {
+          (component as any).collection.items.splice(index, 1);
+        }
+
+        // IMPORTANT: Emit item:remove-request FIRST so rendering feature rebuilds collectionItems
+        // BEFORE setTotalItems triggers a render via viewport:total-items-changed
+        component.emit?.("item:remove-request", {
+          index,
+          item: removedItem,
+        });
+
+        // Update totalItems - this will trigger viewport:total-items-changed which calls renderItems
+        // By now, collectionItems has been rebuilt by the item:remove-request handler
+        if (collection?.getTotalItems && collection?.setTotalItems) {
+          const currentTotal = collection.getTotalItems();
+          collection.setTotalItems(Math.max(0, currentTotal - 1));
+        } else if (component.viewport?.collection?.setTotalItems) {
+          // Fallback to viewport.collection if available
+          const currentTotal = component.viewport.collection.getTotalItems();
+          component.viewport.collection.setTotalItems(
+            Math.max(0, currentTotal - 1),
+          );
+        } else {
+          // Last resort: update component.totalItems directly
+          if (component.totalItems !== undefined) {
+            component.totalItems = Math.max(0, component.totalItems - 1);
+          }
+        }
+
+        return true;
+      },
+
+      /**
+       * 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 {
+        const { trackPending = true, pendingTimeout = 5000 } = options;
+
+        if (id === undefined || id === null) {
+          console.warn(`[VList] removeItemById: invalid id`);
+          return false;
+        }
+
+        // Add to pending removals to filter from future server responses
+        if (trackPending) {
+          pendingRemovals.add(id);
+
+          // Clear from pending removals after timeout (server should have updated by then)
+          setTimeout(() => {
+            pendingRemovals.delete(id);
+          }, pendingTimeout);
+        }
+
+        const items = this.getItems();
+
+        // Find the item by ID (handle sparse arrays from pagination)
+        // Check all possible ID fields since items may have different ID structures
+        const index = items.findIndex((item: any) => {
+          if (!item) return false;
+          // Check all possible ID fields
+          const idsToCheck = [item.id, item._id, item.user_id].filter(
+            (v) => v !== undefined && v !== null,
+          );
+          return idsToCheck.some(
+            (itemId) => itemId === id || String(itemId) === String(id),
+          );
+        });
+
+        if (index === -1) {
+          return false;
+        }
+
+        return this.removeItem(index);
+      },
+
+      /**
+       * 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 {
+        return pendingRemovals.has(id);
+      },
+
+      /**
+       * Get all pending removal IDs
+       * @returns Set of pending removal IDs
+       */
+      getPendingRemovals(): Set<string | number> {
+        return new Set(pendingRemovals);
+      },
+
+      /**
+       * Clear a specific pending removal
+       * @param id - The item ID to clear from pending removals
+       */
+      clearPendingRemoval(id: string | number): void {
+        pendingRemovals.delete(id);
+      },
+
+      /**
+       * Clear all pending removals
+       */
+      clearAllPendingRemovals(): void {
+        pendingRemovals.clear();
+      },
+
+      /**
+       * 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[] {
+        if (pendingRemovals.size === 0) return items;
+
+        return items.filter((item) => {
+          const id = item._id || item.id;
+          return !pendingRemovals.has(id);
+        });
+      },
+
       // Loading operations
       async loadRange(
         page: number,
         limit: number,
         strategy: string = "page",
-        alignment?: string
+        alignment?: string,
       ) {
         isLoading = true;
 
@@ -118,7 +386,7 @@ export const withAPI = <T extends VListItem = VListItem>(
           if (nextOffset < totalItems) {
             await component.viewport.collection.loadRange(
               nextOffset,
-              config.pagination?.limit || 20
+              config.pagination?.limit || 20,
             );
           }
         }
@@ -201,7 +469,7 @@ export const withAPI = <T extends VListItem = VListItem>(
       scrollToIndex: (
         index: number,
         alignment: "start" | "center" | "end" = "start",
-        animate?: boolean
+        animate?: boolean,
       ) => {
         if (component.viewport) {
           component.viewport.scrollToIndex(index, alignment);
@@ -209,14 +477,50 @@ export const withAPI = <T extends VListItem = VListItem>(
         return Promise.resolve();
       },
 
+      /**
+       * Scroll to index and select item after data loads
+       * Useful for runtime scroll+select when VList is already created
+       */
+      scrollToIndexAndSelect: async function (
+        index: number,
+        selectId: string | number,
+        alignment: "start" | "center" | "end" = "start",
+      ) {
+        if (component.viewport) {
+          component.viewport.scrollToIndex(index, alignment);
+        }
+
+        // Listen for range load to complete, then select
+        const onRangeLoaded = () => {
+          component.off?.("viewport:range-loaded", onRangeLoaded);
+          requestAnimationFrame(() => {
+            if (component.selectById) {
+              component.selectById(selectId);
+            }
+          });
+        };
+
+        component.on?.("viewport:range-loaded", onRangeLoaded);
+
+        // Fallback timeout in case event doesn't fire (data already loaded)
+        setTimeout(() => {
+          component.off?.("viewport:range-loaded", onRangeLoaded);
+          if (component.selectById) {
+            component.selectById(selectId);
+          }
+        }, 300);
+
+        return Promise.resolve();
+      },
+
       scrollToItem: async function (
         itemId: string,
         alignment: "start" | "center" | "end" = "start",
-        animate?: boolean
+        animate?: boolean,
       ) {
         const items = this.getItems();
         const index = items.findIndex(
-          (item: any) => String(item.id) === String(itemId)
+          (item: any) => String(item.id) === String(itemId),
         );
 
         if (index >= 0) {
@@ -242,7 +546,7 @@ export const withAPI = <T extends VListItem = VListItem>(
       scrollToPage: async function (
         pageNum: number,
         alignment: "start" | "center" | "end" = "start",
-        animate?: boolean
+        animate?: boolean,
       ) {
         // console.log(`[VList] scrollToPage(${pageNum})`);
 
@@ -262,7 +566,7 @@ export const withAPI = <T extends VListItem = VListItem>(
                 `[VList] Cannot jump to page ${pageNum} in cursor mode. ` +
                   `Loading pages sequentially from ${
                     highestLoadedPage + 1
-                  } to ${pageNum}`
+                  } to ${pageNum}`,
               );
             }
           }