mtrl 0.3.8 → 0.4.0

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

@@ -0,0 +1,361 @@
+import { Collection } from '../collection';
+/**
+ * Configuration for list manager
+ */
+export interface ListManagerConfig {
+    /**
+     * Transform function for items
+     */
+    transform?: (item: any) => any;
+    /**
+     * Base URL for API requests
+     */
+    baseUrl?: string | null;
+    /**
+     * Function to render an item
+     */
+    renderItem: (item: any, index: number, recycledElement?: HTMLElement) => HTMLElement;
+    /**
+     * Callback after load operations
+     */
+    afterLoad?: (result: LoadStatus) => void;
+    /**
+     * Items for static mode
+     */
+    staticItems?: any[] | null;
+    /**
+     * Number of extra items to render outside viewport
+     */
+    renderBufferSize?: number;
+    /**
+     * Number of items to keep in DOM but invisible
+     */
+    overscanCount?: number;
+    /**
+     * Default height for items
+     */
+    itemHeight?: number;
+    /**
+     * Whether items can have varying heights
+     * When false (default), all items use the same height for better performance
+     * When true, each item's height is measured individually
+     */
+    dynamicItemSize?: boolean;
+    /**
+     * Whether to measure initial items
+     */
+    measureItemsInitially?: boolean;
+    /**
+     * Number of items per page
+     */
+    pageSize?: number;
+    /**
+     * Threshold for loading more (0.0-1.0)
+     */
+    loadThreshold?: number;
+    /**
+     * Throttle time for scroll events (ms)
+     */
+    throttleMs?: number;
+    /**
+     * Whether to deduplicate items by ID
+     */
+    dedupeItems?: boolean;
+    /**
+     * Scroll detection strategy
+     */
+    scrollStrategy?: ScrollStrategy;
+    /**
+     * Legacy support for static items
+     */
+    items?: any[];
+    /**
+     * Collection name
+     */
+    collection?: string;
+    /**
+     * Pagination configuration
+     */
+    pagination?: {
+        /**
+         * Pagination strategy to use ('cursor', 'page', or 'offset')
+         * @default 'cursor'
+         */
+        strategy?: 'cursor' | 'page' | 'offset';
+        /**
+         * Parameter name for page size (for page-based pagination)
+         * @default 'per_page'
+         */
+        perPageParamName?: string;
+        /**
+         * Parameter name for limit (for cursor/offset pagination)
+         * @default 'limit'
+         */
+        limitParamName?: string;
+    };
+}
+/**
+ * Scroll tracking strategies
+ */
+export type ScrollStrategy = 'scroll' | 'intersection' | 'hybrid';
+/**
+ * List manager interface
+ */
+export interface ListManager {
+    /**
+     * Loads items from API or static data
+     */
+    loadItems: (params?: any) => Promise<{
+        items: any[];
+        meta: PaginationMeta;
+    }>;
+    /**
+     * Loads more items (next page)
+     */
+    loadMore: () => Promise<{
+        hasNext: boolean;
+        items: any[];
+    }>;
+    /**
+     * Refreshes the list
+     */
+    refresh: () => Promise<void>;
+    /**
+     * Updates visible items based on scroll position
+     */
+    updateVisibleItems: (scrollTop?: number) => void;
+    /**
+     * Scrolls to a specific item by ID
+     */
+    scrollToItem: (itemId: string, position?: ScrollToPosition) => void;
+    /**
+     * Sets custom heights for items
+     */
+    setItemHeights: (heightsMap: Record<string, number>) => boolean;
+    /**
+     * Gets the underlying collection
+     */
+    getCollection: () => Collection<any>;
+    /**
+     * Gets currently visible items
+     */
+    getVisibleItems: () => any[];
+    /**
+     * Gets all items
+     */
+    getAllItems: () => any[];
+    /**
+     * Checks if list is loading
+     */
+    isLoading: () => boolean;
+    /**
+     * Checks if there are more items to load
+     */
+    hasNextPage: () => boolean;
+    /**
+     * Checks if list is in API mode
+     */
+    isApiMode: () => boolean;
+    /**
+     * Sets a hook function for rendering
+     */
+    setRenderHook?: (hookFn: (item: any, element: HTMLElement) => void) => void;
+    /**
+     * Destroys the list manager
+     */
+    destroy: () => void;
+}
+/**
+ * Position for scrolling to an item
+ */
+export type ScrollToPosition = 'start' | 'center' | 'end';
+/**
+ * Pagination metadata
+ */
+export interface PaginationMeta {
+    cursor: string | null;
+    hasNext: boolean;
+    total?: number;
+}
+/**
+ * Load operation status
+ */
+export interface LoadStatus {
+    loading: boolean;
+    hasNext: boolean;
+    hasPrev: boolean;
+    items: any[];
+    allItems: any[];
+}
+/**
+ * List interface
+ */
+export interface List {
+    component: HTMLElement;
+    items: any[];
+    setItems: (items: any[]) => void;
+}
+/**
+ * Page loader configuration
+ */
+export interface PageLoaderConfig {
+    onLoad?: (status: LoadStatus) => void;
+    pageSize?: number;
+}
+/**
+ * Page loader interface
+ */
+export interface PageLoader {
+    load: (cursor?: string | null, addToHistory?: boolean) => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    loadNext: () => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    loadPrev: () => Promise<{
+        hasNext: boolean;
+        hasPrev: boolean;
+    }>;
+    loading: boolean;
+    cursor: string | null;
+}
+/**
+ * Item interface
+ */
+export interface ListItem {
+    id: string;
+    headline: string;
+    supportingText: string;
+    meta: string;
+}
+/**
+ * Internal list manager state
+ */
+/**
+ * Internal list manager state
+ */
+export interface ListManagerState {
+    /**
+     * All items
+     */
+    items: any[];
+    /**
+     * Currently visible items
+     */
+    visibleItems: any[];
+    /**
+     * Visible range indices
+     */
+    visibleRange: {
+        start: number;
+        end: number;
+    };
+    /**
+     * Total height of all items
+     */
+    totalHeight: number;
+    /**
+     * Whether total height needs recalculation
+     */
+    totalHeightDirty: boolean;
+    /**
+     * Map of item heights (legacy - use itemMeasurement)
+     */
+    itemHeights: Map<string, number>;
+    /**
+     * Whether list is currently loading
+     */
+    loading: boolean;
+    /**
+     * Current pagination cursor
+     */
+    cursor: string | null;
+    /**
+     * Current page number (when using page-based pagination)
+     */
+    page?: number;
+    /**
+     * Pagination strategy being used
+     */
+    paginationStrategy?: string;
+    /**
+     * Whether there are more items to load
+     */
+    hasNext: boolean;
+    /**
+     * Map of item elements for DOM recycling
+     */
+    itemElements: Map<string, HTMLElement>;
+    /**
+     * Current scroll position
+     */
+    scrollTop: number;
+    /**
+     * Container height
+     */
+    containerHeight: number;
+    /**
+     * RequestAnimationFrame ID for scroll updates
+     */
+    scrollRAF: number | null;
+    /**
+     * RequestAnimationFrame ID for resize updates
+     */
+    resizeRAF: number | null;
+    /**
+     * Whether component is mounted
+     */
+    mounted: boolean;
+    /**
+     * Total item count (may differ from items.length)
+     */
+    itemCount: number;
+    /**
+     * Whether list is in static mode
+     */
+    useStatic: boolean;
+    /**
+     * Custom render hook function
+     */
+    renderHook: ((item: any, element: HTMLElement) => void) | null;
+}
+/**
+ * DOM elements used by the list manager
+ */
+export interface ListManagerElements {
+    /**
+     * Container element
+     */
+    container: HTMLElement;
+    /**
+     * Content container element
+     */
+    content: HTMLElement;
+    /**
+     * Spacer element for scroll height
+     */
+    spacer: HTMLElement;
+    /**
+     * Top sentinel for intersection detection
+     */
+    topSentinel?: HTMLElement | null;
+    /**
+     * Bottom sentinel for intersection detection
+     */
+    bottomSentinel?: HTMLElement | null;
+}
+/**
+ * Visible range calculation result
+ */
+export interface VisibleRange {
+    /**
+     * Start index
+     */
+    start: number;
+    /**
+     * End index
+     */
+    end: number;
+}

package/dist/core/collection/list-manager/utils/recycling.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Creates a recycling pool manager for better performance
+ * Reduces DOM creation by reusing elements
+ */
+export declare const createRecyclingPool: () => {
+    /**
+     * Gets a recycled element of the appropriate type if available
+     * @param item Item to get recycled element for
+     * @returns Recycled element or null if none available
+     */
+    getRecycledElement: (item: any) => HTMLElement | null;
+    /**
+     * Adds an element to the recycling pool
+     * @param element Element to recycle
+     * @param forceRecycle Whether to force recycling even for small elements
+     */
+    recycleElement: (element: HTMLElement, forceRecycle?: boolean) => void;
+    /**
+     * Get all recycled elements in a pool
+     * @param itemType Type of items to get
+     * @returns Array of recycled elements
+     */
+    getPool: (itemType: string) => HTMLElement[];
+    /**
+     * Clears all recycling pools
+     */
+    clear: () => void;
+    /**
+     * Gets the total number of recycled elements
+     * @returns Total count of recycled elements
+     */
+    getSize: () => number;
+};
+export type RecyclingPool = ReturnType<typeof createRecyclingPool>;

package/dist/core/collection/list-manager/utils/visibility.d.ts

@@ -0,0 +1,45 @@
+import { ItemMeasurement } from '../item-measurement';
+import { VisibleRange, ListManagerConfig } from '../types';
+/**
+ * Optimized visible range calculation for fixed height items
+ * Used as a fast path when all items have the same height
+ *
+ * @param scrollTop Current scroll position
+ * @param itemHeight Fixed item height
+ * @param containerHeight Container height
+ * @param totalItems Total number of items
+ * @param config List manager configuration
+ * @returns Visible range with start and end indices
+ */
+export declare function calculateVisibleRangeOptimized(scrollTop: number, itemHeight: number, containerHeight: number, totalItems: number, config: ListManagerConfig): VisibleRange;
+/**
+ * Determines which items are visible within the viewport
+ * @param scrollTop Current scroll position
+ * @param items Array of items
+ * @param containerHeight Container height
+ * @param itemMeasurement Item measurement instance
+ * @param config List manager configuration
+ * @returns Visible range with start and end indices
+ */
+export declare function calculateVisibleRange(scrollTop: number, items: any[], containerHeight: number, itemMeasurement: ItemMeasurement, config: ListManagerConfig): VisibleRange;
+/**
+ * Calculate the position for each visible item
+ * @param items All items
+ * @param visibleRange Visible range with start and end indices
+ * @param itemMeasurement Item measurement instance
+ * @returns Array of positions with index, item, and offset
+ */
+export declare function calculateItemPositions(items: any[], visibleRange: VisibleRange, itemMeasurement: ItemMeasurement): Array<{
+    index: number;
+    item: any;
+    offset: number;
+}>;
+/**
+ * Checks if load threshold has been reached
+ * @param scrollTop Current scroll top position
+ * @param containerHeight Container height
+ * @param totalHeight Total content height
+ * @param loadThreshold Load threshold as fraction (0-1)
+ * @returns Whether load threshold has been reached
+ */
+export declare function isLoadThresholdReached(scrollTop: number, containerHeight: number, totalHeight: number, loadThreshold: number): boolean;

package/dist/core/compose/base.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Configuration for component creation
+ */
+export interface ComponentConfig {
+    [key: string]: any;
+}
+/**
+ * Basic component interface
+ */
+export interface Component {
+    /**
+     * Component element
+     */
+    element: HTMLElement | null;
+    /**
+     * Component configuration
+     */
+    config: ComponentConfig;
+    /**
+     * Setup method
+     * @returns Component for chaining
+     */
+    setup: () => Component;
+}
+/**
+ * Creates a basic component with minimal structure
+ *
+ * @param config - Component configuration
+ * @returns Basic component structure
+ */
+export declare const createComponent: (config?: ComponentConfig) => Component;

package/dist/core/compose/component.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module core/compose/component
+ * @description Core utilities for component composition and creation with built-in mobile support
+ */
+/**
+ * Touch state interface to track touch interactions
+ */
+export interface TouchState {
+    startTime: number;
+    startPosition: {
+        x: number;
+        y: number;
+    };
+    isTouching: boolean;
+    activeTarget: EventTarget | null;
+}
+/**
+ * Base component interface with prefix utilities
+ */
+export interface BaseComponent {
+    config: Record<string, any>;
+    componentName?: string;
+    getClass: (name: string) => string;
+    getModifierClass: (base: string, modifier: string) => string;
+    getElementClass: (base: string, element: string) => string;
+    touchState: TouchState;
+    updateTouchState: (event: Event, status: 'start' | 'end') => void;
+}
+/**
+ * Element component extends base with element
+ */
+export interface ElementComponent extends BaseComponent {
+    element: HTMLElement;
+    addClass: (...classes: string[]) => ElementComponent;
+    destroy: () => void;
+}
+/**
+ * Options for withElement enhancer
+ */
+export interface WithElementOptions {
+    tag?: string;
+    componentName?: string;
+    attributes?: Record<string, any>;
+    className?: string | string[];
+    forwardEvents?: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive?: boolean;
+}
+/**
+ * Creates a base component with configuration and prefix utilities.
+ * This forms the foundation for all components in the system.
+ *
+ * @param {Object} config - Component configuration
+ * @returns {BaseComponent} Base component with prefix utilities
+ */
+export declare const createBase: (config?: Record<string, any>) => BaseComponent;
+/**
+ * Higher-order function that adds a DOM element to a component
+ * @param {WithElementOptions} options - Element creation options
+ * @returns {Function} Component enhancer
+ */
+export declare const withElement: (options?: WithElementOptions) => <T extends BaseComponent>(component: T) => T & ElementComponent;

package/dist/core/compose/features/badge.d.ts

@@ -0,0 +1,43 @@
+import { BaseComponent, ElementComponent } from '../component';
+/**
+ * Configuration for badge feature
+ */
+export interface BadgeConfig {
+    /**
+     * Badge content to display
+     */
+    badge?: string | number;
+    /**
+     * Custom badge configuration
+     */
+    badgeConfig?: {
+        variant?: string;
+        color?: string;
+        size?: string;
+        position?: string;
+        max?: number;
+        [key: string]: any;
+    };
+    /**
+     * CSS class prefix
+     */
+    prefix?: string;
+    [key: string]: any;
+}
+/**
+ * Component with badge capabilities
+ */
+export interface BadgeComponent extends BaseComponent {
+    /**
+     * Badge component instance
+     */
+    badge?: any;
+}
+/**
+ * Adds badge functionality to a component
+ * Creates and configures a badge component attached to the main component
+ *
+ * @param {BadgeConfig} config - Badge configuration
+ * @returns {Function} Component enhancer with badge functionality
+ */
+export declare const withBadge: <T extends BadgeConfig>(config: T) => <C extends ElementComponent>(component: C) => C & BadgeComponent;

package/dist/core/compose/features/checkable.d.ts

@@ -0,0 +1,59 @@
+import { BaseComponent } from '../component';
+/**
+ * Configuration for checkable feature
+ */
+export interface CheckableConfig {
+    checked?: boolean;
+    [key: string]: any;
+}
+/**
+ * Component with input element
+ */
+export interface InputComponent extends BaseComponent {
+    element: HTMLElement;
+    input: HTMLInputElement;
+    emit?: (event: string, data: any) => InputComponent;
+    on?: (event: string, handler: Function) => InputComponent;
+}
+/**
+ * Checkable state manager interface
+ */
+export interface CheckableManager {
+    /**
+     * Sets the checked state to true
+     * Emits change event if state changes
+     * @returns CheckableManager instance for chaining
+     */
+    check: () => CheckableManager;
+    /**
+     * Sets the checked state to false
+     * Emits change event if state changes
+     * @returns CheckableManager instance for chaining
+     */
+    uncheck: () => CheckableManager;
+    /**
+     * Toggles the current checked state
+     * Always emits change event
+     * @returns CheckableManager instance for chaining
+     */
+    toggle: () => CheckableManager;
+    /**
+     * Gets the current checked state
+     * @returns Whether component is checked
+     */
+    isChecked: () => boolean;
+}
+/**
+ * Component with checkable capabilities
+ */
+export interface CheckableComponent extends BaseComponent {
+    checkable: CheckableManager;
+}
+/**
+ * Adds checked state management to a component with an input
+ * Manages visual state and event emission for checked changes
+ *
+ * @param config - Checkable configuration
+ * @returns Function that enhances a component with checkable functionality
+ */
+export declare const withCheckable: <T extends CheckableConfig>(config?: T) => <C extends InputComponent>(component: C) => C & CheckableComponent;

package/dist/core/compose/features/constants.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Animation timing functions for ripple effect
+ */
+export declare enum RIPPLE_TIMING {
+    LINEAR = "linear",
+    EASE = "ease",
+    EASE_IN = "ease-in",
+    EASE_OUT = "ease-out",
+    EASE_IN_OUT = "ease-in-out",
+    MATERIAL = "cubic-bezier(0.4, 0.0, 0.2, 1)"
+}
+/**
+ * Default configuration for ripple effect
+ * Enhanced for better visibility
+ */
+export declare const RIPPLE_CONFIG: {
+    duration: number;
+    timing: RIPPLE_TIMING;
+    opacity: [string, string];
+};
+/**
+ * Validation schema for ripple configuration
+ */
+export declare const RIPPLE_SCHEMA: {
+    duration: {
+        type: string;
+        minimum: number;
+        default: number;
+    };
+    timing: {
+        type: string;
+        enum: RIPPLE_TIMING[];
+        default: RIPPLE_TIMING;
+    };
+    opacity: {
+        type: string;
+        items: {
+            type: string;
+            pattern: string;
+        };
+        minItems: number;
+        maxItems: number;
+        default: [string, string];
+    };
+};