mtrl-addons 0.5.3 → 0.5.4

package/dist/components/vlist/features/filter.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Filter feature for VList
+ *
+ * Provides generic, layout-agnostic filter functionality that works with
+ * any layout structure and any filter controls. The feature references
+ * layout elements by name and handles filter state, events, and integration
+ * with the collection adapter.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   layout: [
+ *     ['head', { class: 'head' },
+ *       [createIconButton, 'filter-toggle', { icon: iconFilter, toggle: true }]
+ *     ],
+ *     ['filters', { class: 'filter-panel' },
+ *       [createSelect, 'country-select', { options: countries }],
+ *       [createSelect, 'decade-select', { options: decades }],
+ *       [Button, 'clear-btn', { icon: iconCancel }]
+ *     ],
+ *     ['viewport'],
+ *   ],
+ *
+ *   filter: {
+ *     toggleButton: 'filter-toggle',
+ *     panel: 'filters',
+ *     clearButton: 'clear-btn',
+ *     controls: {
+ *       country: 'country-select',
+ *       decade: 'decade-select',
+ *     },
+ *   },
+ *
+ *   collection: {
+ *     adapter: {
+ *       read: async ({ page, limit, filters }) => {
+ *         let url = `/api/items?page=${page}&limit=${limit}`
+ *         if (filters?.country) url += `&country=${filters.country}`
+ *         if (filters?.decade) url += `&decade=${filters.decade}`
+ *         return fetch(url).then(r => r.json())
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Events
+ * vlist.on('filter:open', () => console.log('Filter panel opened'))
+ * vlist.on('filter:change', ({ name, value, filters }) => console.log('Filter changed:', name, value))
+ * vlist.on('filter:clear', () => console.log('Filters cleared'))
+ *
+ * // API
+ * vlist.setFilter('country', 'FR')
+ * vlist.setFilters({ country: 'FR', decade: '1980' })
+ * vlist.clearFilters()
+ * console.log(vlist.getFilters())
+ * console.log(vlist.getFilter('country'))
+ * console.log(vlist.isFiltered())
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Filter configuration
+ */
+export interface FilterConfig {
+    /** Layout element name for toggle button */
+    toggleButton?: string;
+    /** Layout element name for filter panel container */
+    panel?: string;
+    /** Layout element name for clear all filters button */
+    clearButton?: string;
+    /** Map of filter name to layout element name */
+    controls?: Record<string, string>;
+    /** Automatically reload on filter change (default: true) */
+    autoReload?: boolean;
+}
+/**
+ * Adds filter functionality to VList component
+ *
+ * This feature:
+ * 1. Connects to layout elements by name (toggle button, panel, controls)
+ * 2. Manages filter state
+ * 3. Emits events for app-specific handling
+ * 4. Provides API methods for programmatic control
+ * 5. Triggers list reload on filter changes (configurable)
+ *
+ * @param config - VList configuration with filter options
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withFilter: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    filter?: FilterConfig;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with filter
+ */
+export interface WithFilterComponent {
+    /** Set a single filter value */
+    setFilter(name: string, value: any): void;
+    /** Set multiple filters at once */
+    setFilters(filters: Record<string, any>): void;
+    /** Clear all filters */
+    clearFilters(): void;
+    /** Get all current filters */
+    getFilters(): Record<string, any>;
+    /** Get a single filter value */
+    getFilter(name: string): any;
+    /** Check if any filter is active */
+    isFiltered(): boolean;
+    /** Check if filter panel is open */
+    isFilterOpen(): boolean;
+    /** Open the filter panel */
+    openFilter(): void;
+    /** Close the filter panel */
+    closeFilter(): void;
+    /** Toggle filter panel visibility */
+    toggleFilter(): void;
+}

package/dist/components/vlist/features/index.d.ts

@@ -6,3 +6,15 @@
 export { withViewport } from "./viewport";
 export { withAPI } from "./api";
 export { withSelection } from "./selection";
+export { withLayout } from "./layout";
+export { withSearch } from "./search";
+export { withFilter } from "./filter";
+export { withStats } from "./stats";
+export { withVelocity } from "./velocity";
+export { withScrollRestore } from "./scroll-restore";
+export type { LayoutSchema, LayoutResult, WithLayoutComponent } from "./layout";
+export type { SearchConfig, WithSearchComponent } from "./search";
+export type { FilterConfig, WithFilterComponent } from "./filter";
+export type { StatsConfig, WithStatsComponent } from "./stats";
+export type { VelocityConfig, WithVelocityComponent } from "./velocity";
+export type { ScrollRestoreConfig, PendingScrollPosition, PendingScrollLookup, WithScrollRestoreComponent, } from "./scroll-restore";

package/dist/components/vlist/features/layout.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Layout feature for VList
+ *
+ * Processes a layout schema and builds the complete UI structure around
+ * the virtual scrolling viewport. This enables VList to manage its own
+ * layout (header, filters, search, viewport, footer) without requiring
+ * a complex wrapper with functional composition.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   container: document.getElementById('app'),
+ *   class: 'users',
+ *   layout: [
+ *     ['head', { class: 'head' },
+ *       ['title', { text: 'Users' }]
+ *     ],
+ *     ['viewport'],
+ *     ['foot', { class: 'foot' },
+ *       ['count', { text: '0' }]
+ *     ]
+ *   ],
+ *   template: userTemplate,
+ *   collection: { adapter: { read: fetchUsers } }
+ * })
+ *
+ * // Access layout elements via flat map
+ * vlist.layout.title.textContent = 'Users (1,245)'
+ * vlist.layout.count.textContent = '1,245'
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Layout schema type - array-based schema compatible with createLayout
+ */
+export type LayoutSchema = any[];
+/**
+ * Layout result - flat map of all named elements from the layout
+ */
+export interface LayoutResult {
+    [key: string]: any;
+}
+/**
+ * Adds layout functionality to VList
+ *
+ * This feature:
+ * 1. Processes the layout schema using createLayout
+ * 2. Renders the layout inside the VList's root element
+ * 3. Finds the 'viewport' element where virtual scrolling will render
+ * 4. Exposes all named elements via vlist.layout flat map
+ *
+ * @param config - VList configuration with optional layout schema
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withLayout: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    layout?: LayoutSchema;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with layout
+ */
+export interface WithLayoutComponent {
+    /** Flat map of all named layout elements */
+    layout: LayoutResult;
+    /** Get a specific layout element by name */
+    getLayoutElement(name: string): any;
+}

package/dist/components/vlist/features/scroll-restore.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Scroll Restore feature for VList
+ *
+ * Provides a mechanism to queue a pending scroll position and selection
+ * that gets executed on the next reload. Useful for restoring list state
+ * after navigation, filter changes, or other operations that cause a reload.
+ *
+ * This feature works with VList's `reloadAt()` method, providing a convenient
+ * API for queuing scroll restoration that automatically executes on reload.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   layout: [...],
+ *   scrollRestore: {
+ *     enabled: true,
+ *     // Optional: auto-clear pending after successful restore
+ *     autoClear: true,
+ *   },
+ *   collection: { ... }
+ * })
+ *
+ * // Queue a scroll restoration before triggering a reload
+ * vlist.setPendingScroll({
+ *   position: 100,         // Scroll to index 100
+ *   selectId: 'item-123',  // Select this item after scroll
+ * })
+ *
+ * // On next reload(), the pending scroll will be applied
+ * await vlist.reload()  // Will use reloadAt(100, 'item-123')
+ *
+ * // Alternative: queue scroll with position lookup callback
+ * vlist.setPendingScrollWithLookup({
+ *   id: 'user-456',
+ *   lookupPosition: async (id) => {
+ *     const response = await fetch(`/api/users/position?id=${id}`)
+ *     const data = await response.json()
+ *     return data.position
+ *   }
+ * })
+ *
+ * // Events
+ * vlist.on('scroll-restore:pending', ({ position, selectId }) => {
+ *   console.log('Scroll restore queued')
+ * })
+ *
+ * vlist.on('scroll-restore:applied', ({ position, selectId }) => {
+ *   console.log('Scroll restore applied')
+ * })
+ *
+ * vlist.on('scroll-restore:cleared', () => {
+ *   console.log('Pending scroll cleared')
+ * })
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Scroll restore configuration
+ */
+export interface ScrollRestoreConfig {
+    /** Whether scroll restore is enabled (default: true) */
+    enabled?: boolean;
+    /** Auto-clear pending scroll after successful restore (default: true) */
+    autoClear?: boolean;
+}
+/**
+ * Pending scroll with pre-calculated position
+ */
+export interface PendingScrollPosition {
+    /** The index position to scroll to */
+    position: number;
+    /** Optional ID of item to select after scroll */
+    selectId?: string | number;
+}
+/**
+ * Pending scroll with position lookup
+ */
+export interface PendingScrollLookup {
+    /** The ID to look up position for */
+    id: string | number;
+    /** Alternative ID for position lookup (e.g., different ID format) */
+    altId?: string | number;
+    /** Async function to look up position from ID */
+    lookupPosition: (id: string | number) => Promise<number>;
+    /** Fallback position if lookup fails (default: 0) */
+    fallbackPosition?: number;
+}
+/**
+ * Adds scroll restore functionality to VList component
+ *
+ * This feature:
+ * 1. Provides API to queue pending scroll position/selection
+ * 2. Intercepts reload to apply pending scroll via reloadAt()
+ * 3. Supports both pre-calculated positions and position lookups
+ * 4. Emits events for tracking scroll restore state
+ * 5. Auto-clears pending state after successful restore (configurable)
+ *
+ * @param config - VList configuration with scrollRestore options
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withScrollRestore: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    scrollRestore?: ScrollRestoreConfig;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with scroll restore
+ */
+export interface WithScrollRestoreComponent {
+    /** Set pending scroll with pre-calculated position */
+    setPendingScroll(pending: PendingScrollPosition): void;
+    /** Set pending scroll with position lookup */
+    setPendingScrollWithLookup(pending: PendingScrollLookup): void;
+    /** Clear any pending scroll */
+    clearPendingScroll(): void;
+    /** Check if there's a pending scroll */
+    hasPendingScroll(): boolean;
+    /** Get pending scroll info */
+    getPendingScroll(): PendingScrollPosition | PendingScrollLookup | null;
+    /** Force apply pending scroll immediately */
+    applyPendingScrollNow(): Promise<void>;
+}

package/dist/components/vlist/features/search.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Search feature for VList
+ *
+ * Provides generic, layout-agnostic search functionality that works with
+ * any layout structure. The feature references layout elements by name
+ * and handles search state, events, and integration with the collection adapter.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   layout: [
+ *     ['head', { class: 'head' },
+ *       [createIconButton, 'search-toggle', { icon: iconSearch, toggle: true }]
+ *     ],
+ *     [createSearch, 'search-input', { placeholder: 'Search...' }],
+ *     ['viewport'],
+ *   ],
+ *
+ *   search: {
+ *     toggleButton: 'search-toggle',
+ *     searchBar: 'search-input',
+ *     debounce: 300,
+ *   },
+ *
+ *   collection: {
+ *     adapter: {
+ *       read: async ({ page, limit, search }) => {
+ *         let url = `/api/items?page=${page}&limit=${limit}`
+ *         if (search) url += `&q=${encodeURIComponent(search)}`
+ *         return fetch(url).then(r => r.json())
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Events
+ * vlist.on('search:open', () => console.log('Search opened'))
+ * vlist.on('search:change', ({ query }) => console.log('Searching:', query))
+ *
+ * // API
+ * vlist.search('john')
+ * vlist.clearSearch()
+ * console.log(vlist.getSearchQuery())
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Search configuration
+ */
+export interface SearchConfig {
+    /** Layout element name for toggle button */
+    toggleButton?: string;
+    /** Layout element name for search input/bar */
+    searchBar?: string;
+    /** Automatically reload on search change (default: true) */
+    autoReload?: boolean;
+    /** Debounce input in ms (default: 300) */
+    debounce?: number;
+    /** Minimum query length to trigger search (default: 1) */
+    minLength?: number;
+}
+/**
+ * Adds search functionality to VList component
+ *
+ * This feature:
+ * 1. Connects to layout elements by name (toggle button, search bar)
+ * 2. Manages search state (query, open/closed)
+ * 3. Emits events for app-specific handling
+ * 4. Provides API methods for programmatic control
+ * 5. Triggers list reload on search changes (configurable)
+ *
+ * @param config - VList configuration with search options
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withSearch: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    search?: SearchConfig;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with search
+ */
+export interface WithSearchComponent {
+    /** Set search query programmatically */
+    search(query: string): void;
+    /** Clear search query */
+    clearSearch(): void;
+    /** Get current search query */
+    getSearchQuery(): string;
+    /** Check if currently in search mode */
+    isSearching(): boolean;
+    /** Check if search bar is open */
+    isSearchOpen(): boolean;
+    /** Open the search bar */
+    openSearch(): void;
+    /** Close the search bar */
+    closeSearch(): void;
+    /** Toggle search bar visibility */
+    toggleSearch(): void;
+}

package/dist/components/vlist/features/stats.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Stats feature for VList
+ *
+ * Tracks list statistics (count, position, progress) and automatically
+ * updates layout elements. Provides a clean API for accessing stats and
+ * emits events when stats change.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   layout: [
+ *     ['head', { class: 'head' },
+ *       ['title', { text: 'Users' }]
+ *     ],
+ *     ['viewport'],
+ *     ['foot', { class: 'foot' },
+ *       ['position', { text: '0' }],
+ *       ['slash', { text: '/' }],
+ *       ['count', { text: '0' }],
+ *       ['progress', { text: '0%' }]
+ *     ]
+ *   ],
+ *
+ *   stats: {
+ *     elements: {
+ *       count: 'count',
+ *       position: 'position',
+ *       progress: 'progress'
+ *     },
+ *     format: {
+ *       count: (n) => n.toLocaleString(),
+ *       position: (n) => n.toLocaleString(),
+ *       progress: (p) => `${p}%`
+ *     }
+ *   },
+ *
+ *   collection: {
+ *     adapter: {
+ *       read: async ({ page, limit }) => {
+ *         const response = await fetch(`/api/items?page=${page}&limit=${limit}`)
+ *         return response.json()
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Events
+ * vlist.on('stats:change', ({ count, position, progress }) => {
+ *   console.log(`Viewing ${position} of ${count} (${progress}%)`)
+ * })
+ *
+ * // API
+ * const stats = vlist.getStats()
+ * console.log(stats.count, stats.position, stats.progress)
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Stats configuration
+ */
+export interface StatsConfig {
+    /** Layout element names to update */
+    elements?: {
+        /** Element name for total count display */
+        count?: string;
+        /** Element name for current position display */
+        position?: string;
+        /** Element name for progress percentage display */
+        progress?: string;
+    };
+    /** Format functions for display values */
+    format?: {
+        /** Format count value (default: toLocaleString) */
+        count?: (count: number) => string;
+        /** Format position value (default: toLocaleString) */
+        position?: (position: number) => string;
+        /** Format progress value (default: `${p}%`) */
+        progress?: (percent: number) => string;
+    };
+}
+/**
+ * Stats state
+ */
+interface StatsState {
+    count: number;
+    position: number;
+    progress: number;
+}
+/**
+ * Adds stats tracking functionality to VList component
+ *
+ * This feature:
+ * 1. Tracks count (total items), position (first visible item), and progress (scroll %)
+ * 2. Automatically updates layout elements when stats change
+ * 3. Emits 'stats:change' event for app-specific handling
+ * 4. Provides getStats() API for programmatic access
+ *
+ * @param config - VList configuration with stats options
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withStats: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    stats?: StatsConfig;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with stats
+ */
+export interface WithStatsComponent {
+    /** Get all current stats */
+    getStats(): StatsState;
+    /** Get total item count */
+    getCount(): number;
+    /** Get current position (1-based) */
+    getPosition(): number;
+    /** Get current progress percentage (0-100) */
+    getProgress(): number;
+    /** Manually set the total count */
+    setStatsCount(count: number): void;
+}
+export {};

package/dist/components/vlist/features/velocity.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Velocity feature for VList
+ *
+ * Displays scroll velocity in layout elements. Listens to viewport velocity
+ * events and updates designated layout elements with formatted velocity values.
+ *
+ * This feature provides the display mechanism. Application-specific features
+ * like global averaging across lists and localStorage persistence should be
+ * handled at the application level.
+ *
+ * @example
+ * ```typescript
+ * const vlist = createVList({
+ *   layout: [
+ *     ['head', { class: 'head' },
+ *       ['title', { text: 'Users' }]
+ *     ],
+ *     ['viewport'],
+ *     ['foot', { class: 'foot' },
+ *       ['velocity', { class: 'velocity' },
+ *         ['velocity-current', { text: '0.00' }],
+ *         ['velocity-sep', { text: '/' }],
+ *         ['velocity-avg', { text: '0.00' }],
+ *         ['velocity-label', { text: 'px/ms' }]
+ *       ]
+ *     ]
+ *   ],
+ *
+ *   velocity: {
+ *     elements: {
+ *       current: 'velocity-current',
+ *       average: 'velocity-avg'
+ *     },
+ *     format: (v) => v.toFixed(2),
+ *     // Optional: track average within this list instance
+ *     trackAverage: true,
+ *     // Optional: max velocity to include in average (filters out scrollbar drag)
+ *     maxVelocityForAverage: 50
+ *   },
+ *
+ *   collection: { ... }
+ * })
+ *
+ * // Events
+ * vlist.on('velocity:change', ({ velocity, direction, average }) => {
+ *   console.log(`Velocity: ${velocity} px/ms (avg: ${average})`)
+ * })
+ *
+ * // API
+ * const velocity = vlist.getVelocity()
+ * const average = vlist.getAverageVelocity()
+ * vlist.resetVelocityAverage()
+ * ```
+ */
+import type { VListConfig, VListItem } from "../types";
+/**
+ * Velocity configuration
+ */
+export interface VelocityConfig {
+    /** Layout element names to update */
+    elements?: {
+        /** Element name for current velocity display */
+        current?: string;
+        /** Element name for average velocity display */
+        average?: string;
+    };
+    /** Format function for velocity values (default: toFixed(2)) */
+    format?: (velocity: number) => string;
+    /** Whether to track average velocity within this instance (default: false) */
+    trackAverage?: boolean;
+    /**
+     * Maximum velocity to include in average calculation (default: 50)
+     * Higher velocities (e.g., from scrollbar dragging) are excluded
+     */
+    maxVelocityForAverage?: number;
+    /**
+     * Minimum velocity to include in average calculation (default: 0.1)
+     * Filters out noise from near-zero velocities
+     */
+    minVelocityForAverage?: number;
+    /**
+     * Callback for external average tracking (e.g., global across lists)
+     * When provided, allows the app to manage its own averaging logic
+     */
+    onVelocityUpdate?: (velocity: number) => void;
+}
+/**
+ * Adds velocity display functionality to VList component
+ *
+ * This feature:
+ * 1. Listens to viewport:velocity-changed events
+ * 2. Updates layout elements with formatted velocity values
+ * 3. Optionally tracks average velocity within the instance
+ * 4. Emits 'velocity:change' event for app-specific handling
+ * 5. Provides API for getting velocity and average
+ *
+ * @param config - VList configuration with velocity options
+ * @returns Feature function that enhances the VList component
+ */
+export declare const withVelocity: <T extends VListItem = VListItem>(config: VListConfig<T> & {
+    velocity?: VelocityConfig;
+}) => (component: any) => any;
+/**
+ * Type helper for VList with velocity
+ */
+export interface WithVelocityComponent {
+    /** Get current velocity in px/ms */
+    getVelocity(): number;
+    /** Get current scroll direction */
+    getVelocityDirection(): "forward" | "backward";
+    /** Get average velocity in px/ms */
+    getAverageVelocity(): number;
+    /** Get velocity statistics */
+    getVelocityStats(): {
+        current: number;
+        direction: "forward" | "backward";
+        average: number;
+        sampleCount: number;
+    };
+    /** Reset average velocity tracking */
+    resetVelocityAverage(): void;
+    /** Manually update average display (for external tracking) */
+    setAverageVelocityDisplay(average: number): void;
+}

package/dist/components/vlist/features/viewport.d.ts

@@ -1,9 +1,17 @@
 /**
  * Viewport feature for VList
  * Integrates the core viewport functionality with VList component
+ *
+ * When used with withLayout, this feature respects the viewport container
+ * defined in the layout schema, rendering virtual scrolling content inside it.
  */
 import type { VListConfig, VListItem } from "../types";
 /**
  * Adds viewport functionality to VList
+ *
+ * This feature:
+ * 1. Configures the viewport for virtual scrolling
+ * 2. When withLayout is used, renders into the layout's viewport container
+ * 3. Handles parent/container attachment for standalone usage
  */
 export declare const withViewport: <T extends VListItem = VListItem>(config: VListConfig<T>) => (component: any) => any;