mtrl 0.3.8 → 0.4.0

package/dist/components/list/api.d.ts

@@ -0,0 +1,106 @@
+/**
+ * API configuration options for VirtualList component
+ */
+interface ApiOptions {
+    list: {
+        refresh: () => Promise<void>;
+        loadMore: () => Promise<{
+            hasNext: boolean;
+            items: any[];
+        }>;
+        scrollToItem: (itemId: string, position?: 'start' | 'center' | 'end') => void;
+        getVisibleItems: () => any[];
+        getAllItems: () => any[];
+        isLoading: () => boolean;
+        hasNextPage: () => boolean;
+    };
+    events: {
+        on: (event: string, handler: Function) => any;
+        off: (event: string, handler: Function) => any;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    getSelectedItems?: () => any[];
+    getSelectedItemIds?: () => string[];
+    isItemSelected?: (itemId: string) => boolean;
+    selectItem?: (itemId: string) => any;
+    deselectItem?: (itemId: string) => any;
+    clearSelection?: () => any;
+    setSelection?: (itemIds: string[]) => any;
+}
+/**
+ * Component with required elements and methods for API enhancement
+ */
+interface ComponentWithElements {
+    element: HTMLElement;
+    on?: (event: string, handler: Function) => any;
+    off?: (event: string, handler: Function) => any;
+}
+/**
+ * Enhances a VirtualList component with API methods
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ */
+export declare const withAPI: ({ list, events, lifecycle }: ApiOptions) => (component: ComponentWithElements) => {
+    element: HTMLElement;
+    /**
+     * Refreshes the list with the latest data
+     * @returns {Promise<void>} Promise that resolves when refresh is complete
+     */
+    refresh: () => Promise<ComponentWithElements>;
+    /**
+     * Loads more items
+     * @returns {Promise<Object>} Promise with load result
+     */
+    loadMore: () => Promise<{
+        hasNext: boolean;
+        items: any[];
+    }>;
+    /**
+     * Scrolls to a specific item by ID
+     * @param {string} itemId - Item ID to scroll to
+     * @param {string} position - Position ('start', 'center', 'end')
+     * @returns {Object} Component instance for chaining
+     */
+    scrollToItem: (itemId: string, position?: "start" | "center" | "end") => ComponentWithElements;
+    /**
+     * Gets all currently visible items
+     * @returns {Array} Visible items
+     */
+    getVisibleItems: () => any[];
+    /**
+     * Gets all loaded items
+     * @returns {Array} All loaded items
+     */
+    getAllItems: () => any[];
+    /**
+     * Checks if the list is currently loading
+     * @returns {boolean} True if loading
+     */
+    isLoading: () => boolean;
+    /**
+     * Checks if the list has more items to load
+     * @returns {boolean} True if has more items
+     */
+    hasNextPage: () => boolean;
+    /**
+     * Adds an event listener to the list
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     * @returns {Object} Component instance for chaining
+     */
+    on: (event: any, handler: any) => ComponentWithElements;
+    /**
+     * Removes an event listener from the list
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     * @returns {Object} Component instance for chaining
+     */
+    off: (event: any, handler: any) => ComponentWithElements;
+    /**
+     * Destroys the component and cleans up resources
+     */
+    destroy: () => void;
+};
+export default withAPI;

package/dist/components/list/config.d.ts

@@ -0,0 +1,61 @@
+import { ListConfig } from './types';
+/**
+ * Default configuration for the List component
+ */
+export declare const defaultConfig: {
+    collection: "items";
+    transform: (item: any) => any;
+    baseUrl: "http://localhost:4000/api";
+    items: any[];
+    pageSize: 20;
+    renderBufferSize: 5;
+    renderItem: any;
+    trackSelection: boolean;
+    multiSelect: boolean;
+};
+/**
+ * Creates the base configuration for List component
+ * @param {ListConfig} config - User provided configuration
+ * @returns {Object} Complete configuration with defaults applied
+ */
+export declare const createBaseConfig: (config?: Partial<ListConfig>) => import("../../core/config/component").BaseComponentConfig;
+/**
+ * Generates element configuration for the List component
+ * @param {Object} config - List configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export declare const getElementConfig: (config: any) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+/**
+ * Creates API configuration for the List component
+ * @param {Object} component - Component with list manager
+ * @returns {Object} API configuration object
+ */
+export declare const getApiConfig: (component: any) => {
+    list: {
+        refresh: any;
+        loadMore: any;
+        scrollToItem: any;
+        getVisibleItems: any;
+        getAllItems: any;
+        isLoading: any;
+        hasNextPage: any;
+    };
+    events: {
+        on: any;
+        off: any;
+    };
+    lifecycle: {
+        destroy: any;
+    };
+};
+export default defaultConfig;

package/dist/components/list/constants.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Default list item configuration
+ */
+export declare const LIST_DEFAULTS: {
+    /** Default collection name for API-connected lists */
+    readonly COLLECTION: "items";
+    /** Default API base URL */
+    readonly BASE_URL: "http://localhost:4000/api";
+    /** Default number of items per page */
+    readonly PAGE_SIZE: 20;
+    /** Default number of extra items to render above/below viewport */
+    readonly RENDER_BUFFER_SIZE: 5;
+    /** Default item height in pixels */
+    readonly ITEM_HEIGHT: 48;
+};
+/**
+ * List types for rendering and behavior
+ */
+export declare const LIST_TYPES: {
+    /** Standard list with no selection */
+    readonly DEFAULT: "default";
+    /** List with single-select behavior */
+    readonly SINGLE_SELECT: "single-select";
+    /** List with multi-select behavior */
+    readonly MULTI_SELECT: "multi-select";
+};
+/**
+ * List selection modes
+ */
+export declare const LIST_SELECTION_MODES: {
+    /** No selection allowed */
+    readonly NONE: "none";
+    /** Only one item can be selected at a time */
+    readonly SINGLE: "single";
+    /** Multiple items can be selected */
+    readonly MULTIPLE: "multiple";
+};
+/**
+ * List events
+ */
+export declare const LIST_EVENTS: {
+    /** Fired when an item is selected */
+    readonly SELECT: "select";
+    /** Fired when items are loaded */
+    readonly LOAD: "load";
+    /** Fired when the list is scrolled */
+    readonly SCROLL: "scroll";
+};
+/**
+ * Scroll position options for scrollToItem method
+ */
+export declare const LIST_SCROLL_POSITIONS: {
+    /** Align item at the top of viewport */
+    readonly START: "start";
+    /** Center item in the viewport */
+    readonly CENTER: "center";
+    /** Align item at the bottom of viewport */
+    readonly END: "end";
+};
+/**
+ * CSS classes used in the list component
+ */
+export declare const LIST_CLASSES: {
+    /** Container element */
+    readonly CONTAINER: "list-container";
+    /** List element */
+    readonly LIST: "list";
+    /** List item */
+    readonly ITEM: "list-item";
+    /** Selected list item */
+    readonly SELECTED: "list-item--selected";
+    /** Loading indicator */
+    readonly LOADING: "list--loading";
+    /** Empty state */
+    readonly EMPTY: "list--empty";
+};

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

@@ -0,0 +1,2 @@
+export { default as withListManager } from './listmanager';
+export { default as withSelection } from './selection';

package/dist/components/list/features/listmanager.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Adds list management capabilities to a component
+ * Optimized implementation for better performance
+ *
+ * @param config - Configuration options
+ * @returns Function that enhances a component with list management
+ */
+export declare const withListManager: (config: any) => (component: any) => any;
+export default withListManager;

package/dist/components/list/features/selection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Adds selection management capabilities to a list component
+ * Optimized implementation for better performance
+ *
+ * @param config - Configuration options
+ * @returns Function that enhances a component with selection management
+ */
+export declare const withSelection: (config: any) => (component: any) => any;
+export default withSelection;

package/dist/components/list/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * List Component Module
+ *
+ * The List component provides high-performance rendering of large datasets
+ * with built-in virtualization, pagination, and efficient DOM management.
+ *
+ * @module components/list
+ * @category Components
+ */
+export { default } from './list';
+export { LIST_DEFAULTS, LIST_TYPES, LIST_SELECTION_MODES, LIST_EVENTS, LIST_SCROLL_POSITIONS, LIST_CLASSES } from './constants';
+export type { ListConfig, ListComponent, SelectEvent, LoadEvent, LoadResult } from './types';

package/dist/components/list/list.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a new List component
+ *
+ * The List component provides a high-performance way to render large datasets
+ * with built-in virtualization, pagination, and efficient DOM management.
+ *
+ * @param {Object} config - Configuration options for the list
+ * @returns {Object} List component instance
+ */
+declare const createList: (config?: {}) => any;
+export default createList;

package/dist/components/list/types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Configuration for the List component
+ * @interface ListConfig
+ */
+export interface ListConfig {
+    /**
+     * Collection name to fetch data from
+     * @default 'items'
+     */
+    collection?: string;
+    /**
+     * Transform function for API items
+     * @param {any} item - Raw item from API
+     * @returns {any} Transformed item
+     */
+    transform?: (item: any) => any;
+    /**
+     * Base URL for API requests
+     * @default 'http://localhost:4000/api'
+     */
+    baseUrl?: string;
+    /**
+     * Static array of items to display
+     * @default []
+     */
+    items?: any[];
+    /**
+     * Default height for items in pixels
+     * This is used for calculation before actual measurement
+     * @default 48
+     */
+    itemHeight?: number;
+    /**
+     * Number of items to fetch per page
+     * @default 20
+     */
+    pageSize?: number;
+    /**
+     * Number of extra items to render above/below viewport
+     * Higher values reduce blank spaces during fast scrolling but impact performance
+     * @default 5
+     */
+    renderBufferSize?: number;
+    /**
+     * Function to render an item
+     * @param {any} item - Item to render
+     * @param {number} index - Item index in the list
+     * @returns {HTMLElement} Rendered DOM element
+     */
+    renderItem: (item: any, index: number) => HTMLElement;
+    /**
+     * Callback when items are loaded
+     * @param {Object} data - Load result data
+     */
+    afterLoad?: (data: LoadResult) => void;
+    /**
+     * Whether to track item selection
+     * When true, clicked items will receive a selected class
+     * @default true
+     */
+    trackSelection?: boolean;
+    /**
+     * Whether to allow multiple item selection
+     * @default false
+     */
+    multiSelect?: boolean;
+    /**
+     * Initial selection state (array of item IDs)
+     */
+    initialSelection?: string[];
+    /**
+     * ARIA label for accessibility
+     */
+    ariaLabel?: string;
+    /**
+     * Additional CSS classes
+     */
+    class?: string;
+}
+/**
+ * Result of a load operation
+ * @interface LoadResult
+ */
+export interface LoadResult {
+    /**
+     * Whether the list is currently loading
+     */
+    loading: boolean;
+    /**
+     * Whether there are more items to load
+     */
+    hasNext: boolean;
+    /**
+     * Whether there are previous items (if paginating)
+     */
+    hasPrev: boolean;
+    /**
+     * Newly loaded items
+     */
+    items: any[];
+    /**
+     * All loaded items
+     */
+    allItems: any[];
+}
+/**
+ * Selection event data
+ * @interface SelectEvent
+ */
+export interface SelectEvent {
+    /**
+     * Selected item data
+     */
+    item: any;
+    /**
+     * DOM element for the selected item
+     */
+    element: HTMLElement;
+    /**
+     * Original DOM event
+     */
+    originalEvent: Event;
+    /**
+     * Component instance
+     */
+    component: ListComponent;
+    /**
+     * Prevent default behavior
+     */
+    preventDefault: () => void;
+    /**
+     * Whether default was prevented
+     */
+    defaultPrevented: boolean;
+}
+/**
+ * Load event data
+ * @interface LoadEvent
+ */
+export interface LoadEvent extends LoadResult {
+    /**
+     * Component instance
+     */
+    component: VirtualListComponent;
+    /**
+     * Prevent default behavior
+     */
+    preventDefault: () => void;
+    /**
+     * Whether default was prevented
+     */
+    defaultPrevented: boolean;
+}
+/**
+ * Virtual List component interface - enhanced list with virtual scrolling
+ * @interface VirtualListComponent
+ */
+export interface VirtualListComponent extends ListComponent {
+    /**
+     * Updates the virtual scroll parameters
+     * @returns {VirtualListComponent} Component instance for chaining
+     */
+    updateScrollParams?: () => VirtualListComponent;
+    /**
+     * Gets the scroll position
+     * @returns {number} Current scroll position
+     */
+    getScrollTop?: () => number;
+    /**
+     * Sets the scroll position
+     * @param {number} scrollTop - Scroll position to set
+     * @returns {VirtualListComponent} Component instance for chaining
+     */
+    setScrollTop?: (scrollTop: number) => VirtualListComponent;
+}
+/**
+ * List component interface
+ * @interface ListComponent
+ */
+export interface ListComponent {
+    /**
+     * Component's root DOM element
+     */
+    element: HTMLElement;
+    /**
+     * Refreshes the list with the latest data
+     * @returns {Promise<VirtualListComponent>} Promise that resolves with component
+     */
+    refresh: () => Promise<VirtualListComponent>;
+    /**
+     * Loads more items
+     * @returns {Promise<{hasNext: boolean, items: any[]}>} Promise with load result
+     */
+    loadMore: () => Promise<{
+        hasNext: boolean;
+        items: any[];
+    }>;
+    /**
+     * Scrolls to a specific item by ID
+     * @param {string} itemId - Item ID to scroll to
+     * @param {string} position - Position ('start', 'center', 'end')
+     * @returns {VirtualListComponent} Component instance for chaining
+     */
+    scrollToItem: (itemId: string, position?: 'start' | 'center' | 'end') => VirtualListComponent;
+    /**
+     * Gets all currently visible items
+     * @returns {any[]} Visible items
+     */
+    getVisibleItems: () => any[];
+    /**
+     * Gets all loaded items
+     * @returns {any[]} All loaded items
+     */
+    getAllItems: () => any[];
+    /**
+     * Checks if the list is currently loading
+     * @returns {boolean} True if loading
+     */
+    isLoading: () => boolean;
+    /**
+     * Checks if the list has more items to load
+     * @returns {boolean} True if has more items
+     */
+    hasNextPage: () => boolean;
+    /**
+     * Gets the currently selected items
+     * @returns {any[]} Selected items
+     */
+    getSelectedItems: () => any[];
+    /**
+     * Gets the IDs of currently selected items
+     * @returns {string[]} Selected item IDs
+     */
+    getSelectedItemIds: () => string[];
+    /**
+     * Checks if an item is selected
+     * @param {string} itemId - Item ID to check
+     * @returns {boolean} True if item is selected
+     */
+    isItemSelected: (itemId: string) => boolean;
+    /**
+     * Selects an item
+     * @param {string} itemId - Item ID to select
+     * @returns {ListComponent} Component instance for chaining
+     */
+    selectItem: (itemId: string) => ListComponent;
+    /**
+     * Deselects an item
+     * @param {string} itemId - Item ID to deselect
+     * @returns {ListComponent} Component instance for chaining
+     */
+    deselectItem: (itemId: string) => ListComponent;
+    /**
+     * Clears all selections
+     * @returns {ListComponent} Component instance for chaining
+     */
+    clearSelection: () => ListComponent;
+    /**
+     * Sets the selection to the specified item IDs
+     * @param {string[]} itemIds - Item IDs to select
+     * @returns {ListComponent} Component instance for chaining
+     */
+    setSelection: (itemIds: string[]) => ListComponent;
+    /**
+     * Adds an event listener to the list
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     * @returns {ListComponent} Component instance for chaining
+     */
+    on: <T extends keyof ListEvents>(event: T, handler: ListEvents[T]) => ListComponent;
+    /**
+     * Removes an event listener from the list
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     * @returns {ListComponent} Component instance for chaining
+     */
+    off: <T extends keyof ListEvents>(event: T, handler: ListEvents[T]) => ListComponent;
+    /**
+     * Destroys the component and cleans up resources
+     */
+    destroy: () => void;
+}
+/**
+ * Event handlers for List
+ * @interface ListEvents
+ */
+export interface ListEvents {
+    'select': (event: SelectEvent) => void;
+    'load': (event: LoadEvent) => void;
+    'scroll': (event: {
+        originalEvent: Event;
+        component: VirtualListComponent;
+    }) => void;
+}

package/dist/components/menu/api.d.ts

@@ -0,0 +1,58 @@
+import { MenuComponent, MenuContent, MenuPosition } from './types';
+/**
+ * API configuration options for menu component
+ * @category Components
+ * @internal
+ */
+interface ApiOptions {
+    menu: {
+        open: (event?: Event, interactionType?: 'mouse' | 'keyboard') => any;
+        close: (event?: Event, restoreFocus?: boolean, skipAnimation?: boolean) => any;
+        toggle: (event?: Event, interactionType?: 'mouse' | 'keyboard') => any;
+        isOpen: () => boolean;
+        setItems: (items: MenuContent[]) => any;
+        getItems: () => MenuContent[];
+        setPosition: (position: MenuPosition) => any;
+        getPosition: () => MenuPosition;
+        setSelected: (itemId: string) => any;
+        getSelected: () => string | null;
+    };
+    opener: {
+        setOpener: (opener: HTMLElement | string) => any;
+        getOpener: () => HTMLElement;
+    };
+    submenu?: {
+        hasOpenSubmenu: () => boolean;
+        closeAllSubmenus: () => void;
+    };
+    events?: {
+        on: <T extends string>(event: T, handler: (event: any) => void) => any;
+        off: <T extends string>(event: T, handler: (event: any) => void) => any;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
+interface ComponentWithElements {
+    element: HTMLElement;
+    on?: <T extends string>(event: T, handler: (event: any) => void) => any;
+    off?: <T extends string>(event: T, handler: (event: any) => void) => any;
+    emit?: (event: string, data: any) => void;
+}
+/**
+ * Enhances a menu component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ *
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @category Components
+ * @internal This is an internal utility for the Menu component
+ */
+declare const withAPI: ({ menu, opener, events, lifecycle, submenu }: ApiOptions) => (component: ComponentWithElements) => MenuComponent;
+export { withAPI };