mtrl-addons 0.1.0 → 0.1.2

package/src/components/list/api.ts

@@ -0,0 +1,314 @@
+import type { ListComponent, ListConfig, ListAPI } from "./types";
+
+/**
+ * API configuration interface
+ */
+export interface ApiConfig<T = any> {
+  component: ListComponent<T>;
+  config: ListConfig<T>;
+}
+
+/**
+ * Creates the public API layer for the List component
+ * Following mtrl's withAPI pattern
+ */
+export const withAPI =
+  <T = any>(apiConfig: ApiConfig<T>) =>
+  <C extends Partial<ListComponent<T>>>(component: C): C & ListAPI<T> => {
+    const { config } = apiConfig;
+
+    // Store references to orchestration methods before API overwrites them
+    const orchestrationMethods = {
+      scrollToIndex: component.scrollToIndex,
+      scrollToTop: component.scrollToTop,
+      scrollToBottom: component.scrollToBottom,
+      loadData: component.loadData,
+      reload: component.reload,
+      clear: component.clear,
+    };
+
+    // Create clean public API interface
+    const api: ListAPI<T> = {
+      // Data management API
+      async loadData(): Promise<void> {
+        try {
+          if (orchestrationMethods.loadData) {
+            await orchestrationMethods.loadData();
+          } else {
+            await component.collection?.loadPage?.(1);
+          }
+        } catch (error) {
+          console.error("List: Failed to load data", error);
+          throw error;
+        }
+      },
+
+      async reload(): Promise<void> {
+        try {
+          if (orchestrationMethods.reload) {
+            await orchestrationMethods.reload();
+          } else {
+            await component.collection?.refresh?.();
+          }
+        } catch (error) {
+          console.error("List: Failed to reload data", error);
+          throw error;
+        }
+      },
+
+      clear(): void {
+        if (orchestrationMethods.clear) {
+          orchestrationMethods.clear();
+        } else {
+          component.collection?.clearItems?.();
+          component.clearSelection?.();
+        }
+      },
+
+      addItems(items: T[], position: "start" | "end" = "end"): void {
+        if (!Array.isArray(items)) {
+          throw new Error("Items must be an array");
+        }
+        component.addItems?.(items, position);
+      },
+
+      removeItems(indices: number[]): void {
+        if (!Array.isArray(indices)) {
+          throw new Error("Indices must be an array");
+        }
+        component.removeItems?.(indices);
+      },
+
+      updateItem(index: number, item: T): void {
+        if (typeof index !== "number" || index < 0) {
+          throw new Error("Index must be a non-negative number");
+        }
+        component.updateItem?.(index, item);
+      },
+
+      getItem(index: number): T | undefined {
+        if (typeof index !== "number") {
+          return undefined;
+        }
+        return component.getItem?.(index);
+      },
+
+      getItems(): T[] {
+        return component.getItems?.() || [];
+      },
+
+      getItemCount(): number {
+        return component.collection?.getSize?.() || 0;
+      },
+
+      // Scrolling API
+      async scrollToIndex(
+        index: number,
+        alignment: "start" | "center" | "end" = "start"
+      ): Promise<void> {
+        if (typeof index !== "number" || index < 0) {
+          throw new Error("Index must be a non-negative number");
+        }
+
+        // For virtual scrolling with infinite data, don't do strict bounds checking
+        // The orchestration layer will handle loading data as needed
+        try {
+          if (orchestrationMethods.scrollToIndex) {
+            await orchestrationMethods.scrollToIndex(index, alignment);
+          } else {
+            console.warn("scrollToIndex not available");
+          }
+        } catch (error) {
+          console.error("List: Failed to scroll to index", error);
+          throw error;
+        }
+      },
+
+      async scrollToTop(): Promise<void> {
+        try {
+          if (orchestrationMethods.scrollToTop) {
+            await orchestrationMethods.scrollToTop();
+          } else {
+            console.warn("scrollToTop not available");
+          }
+        } catch (error) {
+          console.error("List: Failed to scroll to top", error);
+          throw error;
+        }
+      },
+
+      async scrollToBottom(): Promise<void> {
+        try {
+          if (orchestrationMethods.scrollToBottom) {
+            await orchestrationMethods.scrollToBottom();
+          } else {
+            console.warn("scrollToBottom not available");
+          }
+        } catch (error) {
+          console.error("List: Failed to scroll to bottom", error);
+          throw error;
+        }
+      },
+
+      getScrollPosition(): number {
+        return component.getScrollPosition?.() || 0;
+      },
+
+      // Selection API
+      selectItems(indices: number[]): void {
+        if (!config.selection?.enabled) {
+          console.warn("List: Selection is not enabled");
+          return;
+        }
+
+        if (!Array.isArray(indices)) {
+          throw new Error("Indices must be an array");
+        }
+
+        const itemCount = this.getItemCount();
+        const validIndices = indices.filter(
+          (index) =>
+            typeof index === "number" && index >= 0 && index < itemCount
+        );
+
+        if (config.selection.mode === "single" && validIndices.length > 1) {
+          console.warn("List: Single selection mode allows only one item");
+          component.selectItems?.([validIndices[0]]);
+        } else {
+          component.selectItems?.(validIndices);
+        }
+      },
+
+      deselectItems(indices: number[]): void {
+        if (!config.selection?.enabled) {
+          console.warn("List: Selection is not enabled");
+          return;
+        }
+
+        if (!Array.isArray(indices)) {
+          throw new Error("Indices must be an array");
+        }
+
+        component.deselectItems?.(indices);
+      },
+
+      clearSelection(): void {
+        if (!config.selection?.enabled) {
+          console.warn("List: Selection is not enabled");
+          return;
+        }
+
+        component.clearSelection?.();
+      },
+
+      getSelectedItems(): T[] {
+        return component.getSelectedItems?.() || [];
+      },
+
+      getSelectedIndices(): number[] {
+        return component.getSelectedIndices?.() || [];
+      },
+
+      isSelected(index: number): boolean {
+        if (typeof index !== "number") {
+          return false;
+        }
+        return component.isSelected?.(index) || false;
+      },
+
+      // State API
+      getState() {
+        return (
+          component.getState?.() || {
+            isLoading: false,
+            error: null,
+            isEmpty: true,
+            scrollTop: 0,
+            visibleRange: { start: 0, end: 0, count: 0 },
+            renderRange: { start: 0, end: 0, count: 0 },
+            selectedIndices: [],
+            totalItems: 0,
+            isVirtual: false,
+          }
+        );
+      },
+
+      isLoading(): boolean {
+        return component.isLoading?.() || false;
+      },
+
+      hasError(): boolean {
+        return component.hasError?.() || false;
+      },
+
+      isEmpty(): boolean {
+        return component.isEmpty?.() || true;
+      },
+
+      // Rendering API
+      render(): void {
+        component.render?.();
+      },
+
+      updateViewport(): void {
+        component.updateViewport?.();
+      },
+
+      getVisibleRange() {
+        return component.getVisibleRange?.() || { start: 0, end: 0, count: 0 };
+      },
+
+      getRenderRange() {
+        return component.getRenderRange?.() || { start: 0, end: 0, count: 0 };
+      },
+
+      // Template API
+      setTemplate(template) {
+        if (typeof template !== "function") {
+          throw new Error("Template must be a function");
+        }
+        component.setTemplate?.(template);
+      },
+
+      setLoadingTemplate(template) {
+        // Store in config for future use
+        config.loadingTemplate = template;
+      },
+
+      setEmptyTemplate(template) {
+        // Store in config for future use
+        config.emptyTemplate = template;
+      },
+
+      setErrorTemplate(template) {
+        // Store in config for future use
+        config.errorTemplate = template;
+      },
+
+      // Configuration API
+      updateConfig(newConfig: Partial<ListConfig<T>>): void {
+        if (typeof newConfig !== "object" || newConfig === null) {
+          throw new Error("Config must be an object");
+        }
+
+        component.updateConfig?.(newConfig);
+      },
+
+      getConfig(): ListConfig<T> {
+        return component.getConfig?.() || config;
+      },
+    };
+
+    // Return component with API methods
+    return Object.assign(component, api) as C & ListAPI<T>;
+  };
+
+/**
+ * Helper to get API configuration
+ */
+export const getApiConfig = <T = any>(
+  component: ListComponent<T>
+): ApiConfig<T> => ({
+  component,
+  config: component.config,
+});

package/src/components/list/config.ts

@@ -0,0 +1,352 @@
+/**
+ * mtrl-addons List Component Configuration
+ *
+ * Configuration utilities and defaults for the list component.
+ * Follows mtrl patterns for component configuration.
+ */
+
+import {
+  createComponentConfig,
+  createElementConfig as coreCreateElementConfig,
+} from "mtrl/src/core/config/component";
+import { LIST_DEFAULTS, LIST_CLASSES } from "./constants";
+import type { ListConfig, ListItem } from "./types";
+import type { ListComponent } from "./types";
+import { DATA_PAGINATION } from "../../core/collection/constants";
+import { VIRTUAL_SCROLLING } from "../../core/list-manager/constants";
+import {
+  convertRenderItemToTemplate,
+  getDefaultTemplate,
+} from "../../core/list-manager/features/viewport/template";
+
+/**
+ * Default configuration for the mtrl-addons List component
+ */
+export const defaultConfig: Partial<ListConfig> = {
+  // Collection settings (for API-connected lists)
+  adapter: undefined,
+
+  // Static data (for in-memory lists)
+  items: [],
+
+  // Template settings
+  template: undefined, // Will use default template if not provided
+
+  // Selection settings
+  selection: {
+    enabled: false,
+    mode: "none",
+    selectedIndices: [],
+  },
+
+  // Scroll settings
+  scroll: {
+    virtual: true,
+    itemSize: "auto",
+    estimatedItemSize: 50,
+    overscan: 5,
+    animation: false,
+    restorePosition: false,
+  },
+
+  // Component settings
+  className: LIST_CLASSES.BASE,
+  prefix: "mtrl",
+  componentName: "list",
+  ariaLabel: "List",
+  debug: false,
+};
+
+/**
+ * Creates the base configuration for List component
+ * @param {ListConfig} config - User provided configuration
+ * @returns {ListConfig} Complete configuration with defaults applied
+ */
+export function createBaseConfig<T extends ListItem = ListItem>(
+  config: ListConfig<T> = {}
+): Required<ListConfig<T>> {
+  console.log("🔧 [MTRL-ADDONS-LIST] Creating base configuration");
+
+  // Validate required configuration
+  if (!config.items && !config.adapter) {
+    throw new Error(
+      "List requires either static items or an adapter for data loading"
+    );
+  }
+
+  // Use mtrl core config system for proper merging and validation
+  const mergedConfig = createComponentConfig(defaultConfig, config, "list");
+
+  // Convert renderItem object to template function if provided
+  if (
+    (config as any).renderItem &&
+    typeof (config as any).renderItem === "object" &&
+    !mergedConfig.template
+  ) {
+    mergedConfig.template = convertRenderItemToTemplate(
+      (config as any).renderItem
+    );
+  }
+
+  // Validate selection configuration
+  if (
+    mergedConfig.selection?.enabled &&
+    mergedConfig.selection?.mode === undefined
+  ) {
+    mergedConfig.selection.mode = "single";
+  }
+
+  return mergedConfig as Required<ListConfig<T>>;
+}
+
+/**
+ * Creates element configuration for withElement
+ * @param {ListConfig} config - List configuration
+ * @returns {Object} Element configuration
+ */
+export function getElementConfig<T extends ListItem = ListItem>(
+  config: ListConfig<T>
+): any {
+  const attributes = {
+    "data-component": "list",
+    "data-addons": "true",
+    role: "list",
+    "aria-label": config.ariaLabel || "List",
+  };
+
+  // Create element config using mtrl core system
+  return coreCreateElementConfig(config, {
+    tag: "div",
+    attributes,
+    className: [LIST_CLASSES.BASE, LIST_CLASSES.ADDONS], // Clean: list list-addons
+  });
+}
+
+/**
+ * Creates API configuration for the List component
+ * @param {Object} component - Component with list functionality
+ * @returns {Object} API configuration object for withApi
+ */
+export function getApiConfig<T extends ListItem = ListItem>(component: any) {
+  return {
+    // Data operations
+    data: {
+      add: component.add,
+      update: component.update,
+      remove: component.remove,
+      clear: component.clear,
+      refresh: component.refresh,
+      getItems: component.getItems,
+      getItem: component.getItem,
+      query: component.query,
+      sort: component.sort,
+      getSize: component.getSize,
+      isEmpty: component.isEmpty,
+      isLoading: component.isLoading,
+      getError: component.getError,
+    },
+
+    // Selection operations (if enabled)
+    selection: component.config?.selection?.enabled
+      ? {
+          selectItem: component.selectItem,
+          deselectItem: component.deselectItem,
+          selectAll: component.selectAll,
+          deselectAll: component.deselectAll,
+          getSelectedItems: component.getSelectedItems,
+          getSelectedIds: component.getSelectedIds,
+        }
+      : undefined,
+
+    // Scrolling operations
+    scrolling: {
+      scrollToItem: component.scrollToItem,
+      scrollToIndex: component.scrollToIndex,
+      scrollToPage: component.scrollToPage,
+    },
+
+    // Performance operations
+    performance: {
+      getMetrics: component.getMetrics,
+      resetMetrics: component.resetMetrics,
+    },
+
+    // Template operations
+    template: {
+      setTemplate: component.setTemplate,
+      getTemplate: component.getTemplate,
+    },
+
+    // Events system
+    events: {
+      on: component.on,
+      off: component.off,
+      emit: component.emit,
+      subscribe: component.subscribe,
+    },
+
+    // Lifecycle operations
+    lifecycle: {
+      destroy: component.destroy,
+    },
+
+    // Configuration access
+    config: {
+      selection: component.config?.selection,
+      scroll: component.config?.scroll,
+    },
+  };
+}
+
+/**
+ * Validates list configuration
+ */
+export const validateConfig = (config: ListConfig): void => {
+  // Validate container
+  if (config.container) {
+    if (typeof config.container === "string") {
+      const element = document.querySelector(config.container);
+      if (!element) {
+        throw new Error(
+          `List container element not found: ${config.container}`
+        );
+      }
+    } else if (!(config.container instanceof HTMLElement)) {
+      throw new Error(
+        "List container must be an HTMLElement or CSS selector string"
+      );
+    }
+  }
+
+  // Validate template
+  if (config.template && typeof config.template !== "function") {
+    throw new Error("List template must be a function");
+  }
+
+  // Validate items
+  if (config.items && !Array.isArray(config.items)) {
+    throw new Error("List items must be an array");
+  }
+
+  // Validate selection mode
+  if (
+    config.selection?.mode &&
+    !["single", "multiple", "none"].includes(config.selection.mode)
+  ) {
+    throw new Error(
+      'List selection mode must be "single", "multiple", or "none"'
+    );
+  }
+
+  // Validate scroll configuration
+  if (
+    config.scroll?.itemSize !== "auto" &&
+    typeof config.scroll?.itemSize === "number" &&
+    config.scroll.itemSize <= 0
+  ) {
+    throw new Error('List item size must be positive number or "auto"');
+  }
+
+  // Validate density
+  if (
+    config.density &&
+    !["default", "compact", "comfortable"].includes(config.density)
+  ) {
+    throw new Error(
+      'List density must be "default", "compact", or "comfortable"'
+    );
+  }
+
+  // Validate variant
+  if (
+    config.variant &&
+    !["default", "dense", "comfortable"].includes(config.variant)
+  ) {
+    throw new Error(
+      'List variant must be "default", "dense", or "comfortable"'
+    );
+  }
+};
+
+/**
+ * Creates Collection configuration from List config
+ */
+export const getCollectionConfig = (config: ListConfig) => ({
+  adapter: config.adapter,
+  items: config.items,
+  pageSize: config.collection?.limit || DATA_PAGINATION.DEFAULT_PAGE_SIZE,
+  cache: config.collection?.cache || {
+    enabled: true,
+    maxSize: 1000,
+    ttl: 300000, // 5 minutes
+  },
+});
+
+/**
+ * Creates List Manager configuration from List config
+ */
+export const getListManagerConfig = (config: ListConfig) => ({
+  // Container
+  container: config.container,
+
+  // Collection configuration
+  collection: getCollectionConfig(config),
+
+  // Template configuration
+  template: {
+    template: config.template,
+  },
+
+  // Component prefix
+  prefix: config.prefix || "mtrl",
+
+  // Orientation configuration
+  orientation: {
+    orientation: config.orientation?.orientation || "vertical",
+    autoDetect: config.orientation?.autoDetect || false,
+    reverse: config.orientation?.reverse || false,
+    crossAxisAlignment: config.orientation?.crossAxisAlignment || "stretch",
+  },
+
+  // Virtual scrolling
+  virtual: {
+    enabled: config.scroll?.virtual ?? true,
+    itemSize: config.scroll?.itemSize ?? "auto",
+    estimatedItemSize: config.scroll?.estimatedItemSize ?? 50,
+    overscan: config.scroll?.overscan ?? VIRTUAL_SCROLLING.DEFAULT_OVERSCAN,
+    ...config.listManager?.virtual,
+  },
+
+  // Element recycling
+  recycling: {
+    enabled: config.listManager?.recycling?.enabled ?? true,
+    maxPoolSize: config.listManager?.recycling?.maxPoolSize ?? 100,
+    minPoolSize: config.listManager?.recycling?.minPoolSize ?? 10,
+    ...config.listManager?.recycling,
+  },
+
+  // Intersection observers
+  intersection: {
+    pagination: {
+      enabled: true,
+      rootMargin: "200px",
+      threshold: 0.1,
+      ...config.listManager?.intersection?.pagination,
+    },
+    loading: {
+      enabled: true,
+      ...config.listManager?.intersection?.loading,
+    },
+  },
+
+  // Performance configuration
+  performance: {
+    frameScheduling: true,
+    memoryCleanup: true,
+    ...config.listManager?.performance,
+  },
+
+  // Debug and styling
+  debug: config.debug || false,
+  componentName: "list-manager",
+});

package/src/components/list/constants.ts

@@ -0,0 +1,56 @@
+/**
+ * mtrl-addons List Component Constants
+ *
+ * Constants for the addons list component.
+ * Note: Base mtrl list functionality is handled by mtrl core.
+ * These constants are for addons-specific features only.
+ */
+
+/**
+ * CSS class names for List component
+ * Following BEM convention: component__element--modifier
+ * Note: mtrl prefix is added automatically by core DOM classes system
+ */
+export const LIST_CLASSES = {
+  BASE: "list",
+  ADDONS: "list-addons", // Addons-specific class
+} as const;
+
+/**
+ * Default values for List component configuration
+ * These supplement mtrl's base list defaults with addons-specific values
+ */
+export const LIST_DEFAULTS = {
+  // Collection defaults (addons-specific)
+  INITIAL_CAPACITY: 100,
+  RENDER_BUFFER_SIZE: 10,
+  RENDER_DEBOUNCE: 16, // ~1 frame at 60fps
+
+  // Template defaults (addons-specific)
+  TEMPLATE_ENGINE: "object" as const,
+
+  // Performance defaults (addons-specific)
+  PERFORMANCE_TRACKING: true,
+} as const;
+
+/**
+ * Event names for List component
+ * Following mtrl event naming conventions
+ */
+export const LIST_EVENTS = {
+  // Core events (inherited from mtrl base)
+  CREATED: "list:created",
+  DESTROYED: "list:destroyed",
+
+  // Data events (addons-specific)
+  DATA_LOADED: "list:data-loaded",
+  DATA_ERROR: "list:data-error",
+  DATA_UPDATED: "list:data-updated",
+
+  // Selection events (addons-specific enhancements)
+  SELECTION_CHANGED: "list:selection-changed",
+  SELECTION_CLEARED: "list:selection-cleared",
+
+  // Performance events (addons-specific)
+  PERFORMANCE_METRICS: "list:performance-metrics",
+} as const;