mtrl 0.3.8 → 0.4.0

package/dist/core/canvas/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canvas utilities module
+ * Provides common utilities for working with HTML Canvas elements
+ */
+export { observeCanvasResize } from './resize';

package/dist/core/canvas/resize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canvas resize utilities
+ * Provides utilities for observing and handling canvas resize events
+ */
+/**
+ * Observes resize events on an element and triggers a callback
+ * Watches the specified element and debounces resize events
+ *
+ * @param element - The element to observe for size changes
+ * @param canvas - The canvas element (for context)
+ * @param onResize - Callback to execute when the element resizes
+ * @returns Cleanup function to stop observing
+ */
+export declare const observeCanvasResize: (element: HTMLElement, canvas: HTMLCanvasElement, onResize: () => void) => (() => void);

package/dist/core/collection/adapters/base.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Query operators for filtering data
+ */
+export declare const OPERATORS: {
+    readonly EQ: "eq";
+    readonly NE: "ne";
+    readonly GT: "gt";
+    readonly GTE: "gte";
+    readonly LT: "lt";
+    readonly LTE: "lte";
+    readonly IN: "in";
+    readonly NIN: "nin";
+    readonly CONTAINS: "contains";
+    readonly STARTS_WITH: "startsWith";
+    readonly ENDS_WITH: "endsWith";
+};
+/**
+ * Type for query operators
+ */
+export type Operator = keyof typeof OPERATORS;
+/**
+ * Configuration for base adapter
+ */
+export interface BaseAdapterConfig {
+    /**
+     * Error handler function
+     */
+    onError?: (error: Error, context?: any) => void;
+}
+/**
+ * Base adapter interface
+ */
+export interface BaseAdapter {
+    /**
+     * Handles errors in adapter operations
+     * @param error - The error that occurred
+     * @param context - Optional context information about the error
+     * @throws The original error after processing
+     */
+    handleError(error: Error, context?: any): never;
+}
+/**
+ * Creates a base adapter with error handling
+ * @param config - Adapter configuration
+ * @returns Base adapter with error handling
+ */
+export declare const createBaseAdapter: (config?: BaseAdapterConfig) => BaseAdapter;

package/dist/core/collection/adapters/route.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Pagination strategies supported by the route adapter
+ */
+export type PaginationStrategy = 'cursor' | 'offset' | 'page';
+/**
+ * Pagination configuration
+ */
+export interface PaginationConfig {
+    /**
+     * Pagination strategy to use
+     * @default 'cursor'
+     */
+    strategy: PaginationStrategy;
+    /**
+     * Parameter name for pagination cursor
+     * @default 'cursor'
+     */
+    cursorParamName?: string;
+    /**
+     * Parameter name for page number
+     * @default 'page'
+     */
+    pageParamName?: string;
+    /**
+     * Parameter name for page size / items per page
+     * @default 'per_page'
+     */
+    perPageParamName?: string;
+    /**
+     * Parameter name for offset
+     * @default 'offset'
+     */
+    offsetParamName?: string;
+    /**
+     * Parameter name for limit
+     * @default 'limit'
+     */
+    limitParamName?: string;
+    /**
+     * Default page size for pagination
+     * @default 20
+     */
+    defaultPageSize?: number;
+}
+/**
+ * Route adapter configuration interface
+ */
+export interface RouteAdapterConfig {
+    /**
+     * Base URL for API requests
+     */
+    base?: string;
+    /**
+     * API endpoints
+     */
+    endpoints?: {
+        create?: string;
+        list?: string;
+        update?: string;
+        delete?: string;
+    };
+    /**
+     * HTTP headers to include with requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to enable response caching
+     */
+    cache?: boolean;
+    /**
+     * Error handler function
+     */
+    onError?: (error: Error, context?: any) => void;
+    /**
+     * Custom adapter options
+     */
+    adapter?: {
+        /**
+         * Custom response parser
+         */
+        parseResponse?: (response: any) => any;
+    };
+    /**
+     * Pagination configuration
+     */
+    pagination?: PaginationConfig;
+}
+/**
+ * Response metadata interface
+ */
+export interface ResponseMeta {
+    /**
+     * Cursor for next page (cursor-based pagination)
+     */
+    cursor: string | null;
+    /**
+     * Whether there are more items available
+     */
+    hasNext: boolean;
+    /**
+     * Total number of items (if available)
+     */
+    total?: number;
+    /**
+     * Current page number (page-based pagination)
+     */
+    page?: number;
+    /**
+     * Total number of pages (page-based pagination)
+     */
+    pages?: number;
+    /**
+     * Current offset (offset-based pagination)
+     */
+    offset?: number;
+}
+/**
+ * Parsed response interface
+ */
+export interface ParsedResponse<T = any> {
+    /**
+     * Items returned in the response
+     */
+    items: T[];
+    /**
+     * Pagination metadata
+     */
+    meta: ResponseMeta;
+}
+export declare const createRouteAdapter: (config?: RouteAdapterConfig) => {
+    create: (items: any[]) => Promise<ParsedResponse>;
+    read: (query?: Record<string, any>, options?: Record<string, any>) => Promise<ParsedResponse>;
+    update: (items: any[]) => Promise<ParsedResponse>;
+    delete: (ids: string[]) => Promise<ParsedResponse>;
+    query: (query?: Record<string, any>, options?: Record<string, any>) => Promise<ParsedResponse>;
+    /**
+     * Change the pagination strategy
+     * @param strategy - New pagination strategy
+     * @returns Updated adapter
+     */
+    setPaginationStrategy: (strategy: PaginationStrategy) => void;
+    /**
+     * Get the current pagination configuration
+     * @returns Current pagination config
+     */
+    getPaginationConfig: () => Required<PaginationConfig>;
+    disconnect: () => void;
+    handleError(error: Error, context?: any): never;
+};

package/dist/core/collection/collection.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Event types for collection changes
+ */
+export declare const COLLECTION_EVENTS: {
+    readonly CHANGE: "change";
+    readonly ADD: "add";
+    readonly UPDATE: "update";
+    readonly REMOVE: "remove";
+    readonly ERROR: "error";
+    readonly LOADING: "loading";
+};
+/**
+ * Collection event type
+ */
+export type CollectionEvent = typeof COLLECTION_EVENTS[keyof typeof COLLECTION_EVENTS];
+/**
+ * Observer callback type for collection events
+ */
+export type CollectionObserver<T> = (payload: {
+    event: CollectionEvent;
+    data: any;
+}) => void;
+/**
+ * Query operators for filtering
+ */
+export declare const OPERATORS: {
+    readonly EQ: "eq";
+    readonly NE: "ne";
+    readonly GT: "gt";
+    readonly GTE: "gte";
+    readonly LT: "lt";
+    readonly LTE: "lte";
+    readonly IN: "in";
+    readonly NIN: "nin";
+    readonly CONTAINS: "contains";
+    readonly STARTS_WITH: "startsWith";
+    readonly ENDS_WITH: "endsWith";
+};
+/**
+ * Type for all collection items
+ */
+export interface CollectionItem {
+    id: string;
+    [key: string]: any;
+}
+/**
+ * Collection configuration
+ */
+export interface CollectionConfig<T extends CollectionItem> {
+    /**
+     * Transform function for items
+     */
+    transform?: (item: any) => T;
+    /**
+     * Validation function for items
+     */
+    validate?: (item: any) => boolean;
+    /**
+     * Initial capacity for collection
+     */
+    initialCapacity?: number;
+}
+/**
+ * Collection interface
+ */
+export interface Collection<T extends CollectionItem> {
+    /**
+     * Subscribe to collection changes
+     * @param observer - Observer callback
+     * @returns Unsubscribe function
+     */
+    subscribe: (observer: CollectionObserver<T>) => () => void;
+    /**
+     * Get collection items based on current query and sort
+     * @returns Collection items
+     */
+    getItems: () => readonly T[];
+    /**
+     * Get collection size
+     * @returns Number of items
+     */
+    getSize: () => number;
+    /**
+     * Get loading state
+     * @returns Loading state
+     */
+    isLoading: () => boolean;
+    /**
+     * Get error state
+     * @returns Error object
+     */
+    getError: () => Error | null;
+    /**
+     * Set query filter
+     * @param queryFn - Query function
+     */
+    query: (queryFn: ((item: T) => boolean) | null) => void;
+    /**
+     * Set sort function
+     * @param sortFn - Sort function
+     */
+    sort: (sortFn: ((a: T, b: T) => number) | null) => void;
+    /**
+     * Add items to collection
+     * @param items - Items to add
+     * @returns Added items
+     */
+    add: (items: T | readonly T[]) => Promise<readonly T[]>;
+    /**
+     * Update items in collection
+     * @param items - Items to update
+     * @returns Updated items
+     */
+    update: (items: T | readonly T[]) => Promise<readonly T[]>;
+    /**
+     * Remove items from collection
+     * @param ids - Item IDs to remove
+     * @returns Removed item IDs
+     */
+    remove: (ids: string | readonly string[]) => Promise<readonly string[]>;
+    /**
+     * Clear all items from collection
+     */
+    clear: () => void;
+}
+/**
+ * Creates a collection for managing items
+ * @param config - Collection configuration
+ * @returns Collection interface
+ */
+export declare const createCollection: <T extends CollectionItem>(config?: CollectionConfig<T>) => Collection<T>;

package/dist/core/collection/index.d.ts

@@ -0,0 +1,10 @@
+export { createCollection } from './collection';
+export { COLLECTION_EVENTS } from './collection';
+export { OPERATORS as COLLECTION_OPERATORS } from './collection';
+export type { CollectionItem, CollectionConfig, CollectionEvent, CollectionObserver, Collection } from './collection';
+export { createListManager, transforms } from './list-manager';
+export type { ListManager, ListManagerConfig, ListItem, List, PageLoader, PageLoaderConfig, LoadStatus, PaginationMeta } from './list-manager';
+export { createBaseAdapter, OPERATORS } from './adapters/base';
+export type { BaseAdapter, BaseAdapterConfig, Operator } from './adapters/base';
+export { createRouteAdapter } from './adapters/route';
+export type { RouteAdapterConfig, ParsedResponse } from './adapters/route';

package/dist/core/collection/list-manager/config.d.ts

@@ -0,0 +1,29 @@
+import { ListManagerConfig } from './types';
+/**
+ * Default configuration for list manager
+ */
+export declare const DEFAULT_CONFIG: Partial<ListManagerConfig>;
+/**
+ * Merges user configuration with default configuration
+ * @param config User configuration
+ * @returns Merged configuration
+ */
+export declare function mergeConfig(config: ListManagerConfig): ListManagerConfig;
+/**
+ * Validates configuration and sets up defaults
+ * @param config User configuration
+ * @returns Validated configuration object
+ */
+export declare function validateConfig(config: ListManagerConfig): ListManagerConfig;
+/**
+ * Determines if the list manager should use API mode
+ * @param config User configuration
+ * @returns Whether to use API mode
+ */
+export declare function determineApiMode(config: ListManagerConfig): boolean;
+/**
+ * Gets all static items from config
+ * @param config User configuration
+ * @returns Static items array or empty array
+ */
+export declare function getStaticItems(config: ListManagerConfig): any[];

package/dist/core/collection/list-manager/dom-elements.d.ts

@@ -0,0 +1,30 @@
+import { ListManagerElements } from './types';
+/**
+ * Creates and initializes the DOM elements needed by the list manager
+ * @param container Container element
+ * @returns Initialized DOM elements
+ */
+export declare function createDomElements(container: HTMLElement): ListManagerElements;
+/**
+ * Creates sentinel elements for intersection observer
+ * @param elements List manager elements
+ * @returns The DOM elements with sentinels added
+ */
+export declare function createSentinels(elements: ListManagerElements): ListManagerElements;
+/**
+ * Updates the position of the bottom sentinel based on total height
+ * @param elements List manager elements
+ * @param totalHeight Total height of list
+ */
+export declare function updateSentinelPositions(elements: ListManagerElements, totalHeight: number): void;
+/**
+ * Updates the spacer element height
+ * @param elements List manager elements
+ * @param totalHeight Total height to set
+ */
+export declare function updateSpacerHeight(elements: ListManagerElements, totalHeight: number): void;
+/**
+ * Cleans up DOM elements
+ * @param elements List manager elements
+ */
+export declare function cleanupDomElements(elements: ListManagerElements): void;

package/dist/core/collection/list-manager/index.d.ts

@@ -0,0 +1,61 @@
+import { ListManagerConfig, ListManager, LoadStatus } from './types';
+/**
+ * Creates a list manager for a specific collection
+ * @param {string} collection - Collection name
+ * @param {HTMLElement} container - Container element
+ * @param {ListManagerConfig} config - Configuration options
+ * @returns {ListManager} List manager methods
+ */
+export declare const createListManager: (collection: string, container: HTMLElement, config: ListManagerConfig) => ListManager;
+/**
+ * Utility to create a cursor-based page loader
+ * @param list List interface
+ * @param listManager List manager instance
+ * @param config Page loader configuration
+ * @returns Page loader interface
+ */
+export declare const createPageLoader: (list: {
+    setItems: (items: any[]) => void;
+}, listManager: ReturnType<typeof createListManager>, config?: {
+    onLoad?: (status: LoadStatus) => void;
+    pageSize?: number;
+}) => {
+    load: (cursor?: any, addToHistory?: boolean) => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    loadNext: () => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    loadPrev: () => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    readonly loading: boolean;
+    readonly cursor: string;
+};
+/**
+ * Transform functions for common collections
+ */
+export declare const transforms: {
+    track: (track: any) => {
+        id: any;
+        headline: any;
+        supportingText: any;
+        meta: any;
+    };
+    playlist: (playlist: any) => {
+        id: any;
+        headline: any;
+        supportingText: string;
+        meta: any;
+    };
+    country: (country: any) => {
+        id: any;
+        headline: any;
+        supportingText: any;
+        meta: any;
+    };
+};
+export * from './types';

package/dist/core/collection/list-manager/item-measurement.d.ts

@@ -0,0 +1,91 @@
+import { ListManagerConfig } from './types';
+/**
+ * Create item height measurement utilities
+ * @param defaultHeight Default height for items with no measurement
+ * @returns Object containing measurement functions
+ */
+export declare const createItemMeasurement: (defaultHeight?: number) => {
+    /**
+     * Setup measurement system with configuration options
+     * Should be called on initialization
+     * @param config List configuration options
+     */
+    setup: (config?: ListManagerConfig) => void;
+    /**
+     * Measures the height of an item using its DOM element
+     * @param item Item to measure
+     * @param element DOM element of the item
+     * @returns The measured height
+     */
+    measureItemHeight: (item: any, element: HTMLElement) => number;
+    /**
+     * Gets the height of an item, using cached value if available
+     * @param item Item to get height for
+     * @returns Item height in pixels
+     */
+    getItemHeight: (item: any) => number;
+    /**
+     * Set custom heights for specific items
+     * Only applied when in dynamic measurement mode
+     * @param heightsMap Map of item IDs to heights
+     * @returns Whether any heights were updated
+     */
+    setItemHeights: (heightsMap: Record<string, number>) => boolean;
+    /**
+     * Calculates total height of all items
+     * @param items Array of items
+     * @returns Total height in pixels
+     */
+    calculateTotalHeight: (items: any[]) => number;
+    /**
+     * Get offset of an item from the top of the list
+     * @param items List of all items
+     * @param itemId ID of item to find offset for
+     * @returns Offset in pixels or -1 if not found
+     */
+    getItemOffset: (items: any[], itemId: string) => number;
+    /**
+     * Get the offset at a specific index
+     * @param index Index to get offset for
+     * @returns Offset in pixels
+     */
+    getOffsetAtIndex: (index: number) => number;
+    /**
+     * Measures elements that have been marked for measurement
+     * Only takes effect in dynamic measurement mode
+     * @param container Container element
+     * @param items List of all items
+     * @returns Whether any heights were updated
+     */
+    measureMarkedElements: (container: HTMLElement, items: any[]) => boolean;
+    /**
+     * Check if offsets are currently cached
+     * @returns Whether offsets are cached
+     */
+    hasCachedOffsets: () => boolean;
+    /**
+     * Cache offsets for all items
+     * @param items Array of all items
+     */
+    calculateOffsets: (items: any[]) => void;
+    /**
+     * Clears all cached heights and offsets
+     */
+    clear: () => void;
+    /**
+     * Gets all cached heights
+     * @returns Map of item IDs to heights
+     */
+    getAllHeights: () => Map<string, number>;
+    /**
+     * Gets current default height
+     * @returns Current default height
+     */
+    getDefaultHeight: () => number;
+    /**
+     * Checks if using uniform height mode
+     * @returns Whether using uniform height
+     */
+    isUsingUniformHeight: () => boolean;
+};
+export type ItemMeasurement = ReturnType<typeof createItemMeasurement>;

package/dist/core/collection/list-manager/renderer.d.ts

@@ -0,0 +1,31 @@
+import { ListManagerConfig, ListManagerElements, VisibleRange } from './types';
+import { RecyclingPool } from './utils/recycling';
+import { ItemMeasurement } from './item-measurement';
+/**
+ * Creates a renderer for list items
+ * @param config List manager configuration
+ * @param elements DOM elements used by the list manager
+ * @param itemMeasurement Item measurement utilities
+ * @param recyclePool Element recycling pool
+ * @returns Renderer functions
+ */
+export declare const createRenderer: (config: ListManagerConfig, elements: ListManagerElements, itemMeasurement: ItemMeasurement, recyclePool: RecyclingPool) => {
+    /**
+     * Sets a render hook function that will be called for each rendered item
+     * @param hookFn Hook function
+     */
+    setRenderHook: (hookFn: (item: any, element: HTMLElement) => void) => void;
+    /**
+     * Renders visible items in the viewport
+     * @param items All items
+     * @param visibleRange Visible range with start and end indices
+     * @returns Map of item IDs to rendered elements
+     */
+    renderVisibleItems: (items: any[], visibleRange: VisibleRange) => Map<string, HTMLElement>;
+    /**
+     * Gets all currently rendered item elements
+     * @returns Map of item IDs to elements
+     */
+    getItemElements: () => Map<string, HTMLElement>;
+};
+export type Renderer = ReturnType<typeof createRenderer>;

package/dist/core/collection/list-manager/scroll-tracker.d.ts

@@ -0,0 +1,20 @@
+import { ListManagerElements, ListManagerConfig } from './types';
+/**
+ * Common interface for scroll tracking strategies
+ */
+export interface ScrollTracker {
+    setup(): () => void;
+    getScrollTop(): number;
+}
+/**
+ * Factory to create the appropriate scroll tracker based on strategy
+ * @param container Container element
+ * @param elements DOM elements
+ * @param config List manager configuration
+ * @param callbacks Callbacks for scroll events
+ * @returns ScrollTracker implementation
+ */
+export declare function createScrollTracker(container: HTMLElement, elements: ListManagerElements, config: ListManagerConfig, callbacks: {
+    onScroll: (scrollTop: number) => void;
+    onLoadMore: () => void;
+}): ScrollTracker;

package/dist/core/collection/list-manager/state.d.ts

@@ -0,0 +1,60 @@
+import { ListManagerState, ListManagerConfig } from './types';
+/**
+ * Creates the initial state for a list manager
+ * @param config List manager configuration
+ * @returns Initialized state object
+ */
+export declare function createInitialState(config: ListManagerConfig): ListManagerState;
+/**
+ * Updates the state after a load operation
+ * @param state Current state
+ * @param newItems New items array
+ * @param meta Pagination metadata
+ * @param dedupe Whether to deduplicate items
+ * @returns Updated state
+ */
+export declare function updateStateAfterLoad(state: ListManagerState, newItems: any[], meta: {
+    cursor?: string | null;
+    hasNext?: boolean;
+    total?: number;
+    page?: number;
+}, dedupe?: boolean): Partial<ListManagerState>;
+/**
+ * Updates the visible items in state
+ * @param state Current state
+ * @param visibleItems New visible items array
+ * @param visibleRange New visible range
+ * @returns Updated state
+ */
+export declare function updateVisibleItems(state: ListManagerState, visibleItems: any[], visibleRange: {
+    start: number;
+    end: number;
+}): Partial<ListManagerState>;
+/**
+ * Updates total height in state
+ * @param state Current state
+ * @param totalHeight New total height
+ * @returns Updated state
+ */
+export declare function updateTotalHeight(state: ListManagerState, totalHeight: number): Partial<ListManagerState>;
+/**
+ * Updates loading state
+ * @param state Current state
+ * @param loading New loading state
+ * @returns Updated state
+ */
+export declare function updateLoadingState(state: ListManagerState, loading: boolean): Partial<ListManagerState>;
+/**
+ * Resets the state for a refresh operation
+ * @param state Current state
+ * @param initialItems Initial items array for static mode
+ * @returns Reset state
+ */
+export declare function resetState(state: ListManagerState, initialItems?: any[]): Partial<ListManagerState>;
+/**
+ * Creates load params for the next page based on pagination strategy
+ * @param state Current state
+ * @param paginationStrategy Optional pagination strategy override
+ * @returns Load parameters object
+ */
+export declare function createLoadParams(state: ListManagerState, paginationStrategy?: string): Record<string, any>;