ezux 1.1.13 → 1.1.18

package/dist/shared/hooks/useStateChangeEvents.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Sort/Filter/Page event callbacks shared across components.
+ */
+export interface StateChangeCallbacks {
+    onSort?: (args: {
+        columns: {
+            field: string;
+            direction: 'asc' | 'desc';
+        }[];
+    }) => void;
+    onPageChange?: (args: {
+        currentPage: number;
+        pageSize: number;
+    }) => void;
+    onFilter?: (args: {
+        columns: {
+            field: string;
+            operator: string;
+            value: any;
+        }[];
+    }) => void;
+    onSearch?: (term: string) => void;
+}
+/**
+ * Sort state from TanStack
+ */
+export interface SortingState {
+    id: string;
+    desc: boolean;
+}
+/**
+ * Pagination state from TanStack
+ */
+export interface PaginationState {
+    pageIndex: number;
+    pageSize: number;
+}
+/**
+ * Filter state from TanStack
+ */
+export interface ColumnFilterState {
+    id: string;
+    value: any;
+}
+/**
+ * Shared hook for state change events (sort, page, filter).
+ * Creates wrappers that emit aliased events alongside native TanStack callbacks.
+ * Used by EzTable, EzScheduler, EzTreeView.
+ *
+ * @example
+ * const { wrapSortingChange, wrapPaginationChange } = useStateChangeEvents(props);
+ *
+ * // Use in table config
+ * onSortingChange: wrapSortingChange(setSorting)
+ */
+export declare const useStateChangeEvents: (callbacks: StateChangeCallbacks) => {
+    wrapSortingChange: <T extends (SortingState[] | ((old: SortingState[]) => SortingState[]))>(setter: (updater: T) => void, nativeCallback?: (state: SortingState[]) => void) => (updater: T) => void;
+    wrapPaginationChange: (setter: (updater: PaginationState | ((old: PaginationState) => PaginationState)) => void, nativeCallback?: (state: PaginationState) => void) => (updater: PaginationState | ((old: PaginationState) => PaginationState)) => void;
+    emitSort: (sorting: SortingState[]) => void;
+    emitPageChange: (pagination: PaginationState) => void;
+};

package/dist/shared/hooks/useTheme.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hook for accessing and managing theme state
+ * Integrates with the global UI store for theme management
+ */
+export declare const useTheme: () => {
+    theme: "light" | "dark" | "system";
+    rtl: boolean;
+    setTheme: (newTheme: "light" | "dark" | "system") => void;
+    toggleTheme: () => void;
+    setRTL: (newRtl: boolean) => void;
+    isDark: boolean;
+    isLight: boolean;
+};

package/dist/shared/hooks/useVirtualization.d.ts

@@ -0,0 +1,85 @@
+import { Virtualizer, Range } from '@tanstack/react-virtual';
+/**
+ * Configuration for the useVirtualization hook.
+ * @group Properties
+ */
+export interface VirtualizationConfig {
+    /** Total number of rows in the dataset. @group Data */
+    rowCount: number;
+    /** Fixed height or dynamic accessor for row height. @group Appearance */
+    rowHeight?: number | ((index: number) => number);
+    /** Number of rows to render outside the visible area. @group Performance */
+    overscanCount?: number;
+    /** Whether row virtualization is enabled. @default true @group Properties */
+    enableRowVirtualization?: boolean;
+    /** Unique ID for service registration. @group Properties */
+    id?: string;
+    /** Total number of columns (for 2D virtualization). @group Data */
+    columnCount?: number;
+    /** Fixed width or dynamic accessor for column width. @group Appearance */
+    columnWidth?: number | ((index: number) => number);
+    /** Whether column virtualization is enabled. @group Properties */
+    enableColumnVirtualization?: boolean;
+    /** Margin to add to the scroll container's size. @group Appearance */
+    scrollMargin?: number;
+    /** Padding at the start of the scrollable area. @group Appearance */
+    scrollPaddingStart?: number;
+    /** Padding at the end of the scrollable area. @group Appearance */
+    scrollPaddingEnd?: number;
+    /** Reduces overscan during active scrolling for performance. @group Performance */
+    progressiveRendering?: boolean;
+    /** Distance in rows to trigger pre-fetching. @group Performance */
+    prefetchDistance?: number;
+    /** Automatically adjusts sizes based on content. @group Performance */
+    adaptiveSizing?: boolean;
+    /** Text direction (ltr or rtl). @group Appearance */
+    languageDirection?: 'ltr' | 'rtl';
+    /** Enables debug logging. @group Properties */
+    debug?: boolean;
+    /** Custom logic to determine which items to render. @group Performance */
+    customRangeExtractor?: (range: Range) => number[];
+    /** Callback triggered when scroll offset changes. @group Events */
+    onScroll?: (offset: number) => void;
+    /** Callback triggered when scrolling begins. @group Events */
+    onScrollStart?: () => void;
+    /** Callback triggered when scrolling stops. @group Events */
+    onScrollStop?: () => void;
+}
+/**
+ * Result object for the useVirtualization hook.
+ * @group Methods
+ */
+export interface VirtualizationResult {
+    /** Ref to attach to the scroll container. @group Properties */
+    parentRef: React.RefObject<HTMLDivElement | null>;
+    /** The TanStack virtualizer instance for rows. @group Properties */
+    rowVirtualizer: Virtualizer<HTMLDivElement, Element>;
+    /** The TanStack virtualizer instance for columns (if enabled). @group Properties */
+    columnVirtualizer?: Virtualizer<HTMLDivElement, Element>;
+    /** Scrolls to a specific index (alias for scrollToRow). @group Methods */
+    scrollToIndex: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }) => void;
+    /** Scrolls to a specific row index. @group Methods */
+    scrollToRow: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }) => void;
+    /** Scrolls to a specific column index. @group Methods */
+    scrollToColumn?: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }) => void;
+    /** Returns the list of items to currently render. @group Methods */
+    getVirtualItems: () => any[];
+    /** Current vertical scroll offset. @group State */
+    scrollOffset: number;
+}
+/**
+ * Shared virtualization hook for table, tree, and scheduler components.
+ *
+ * Provides standardized row and column virtualization using TanStack Virtual.
+ * Includes optimized progressive rendering, service integration, and pre-fetching support.
+ *
+ * @param config Virtualization configuration.
+ * @group Hooks
+ */
+export declare const useVirtualization: (config: VirtualizationConfig) => VirtualizationResult;

package/dist/shared/services/BaseService.d.ts

@@ -0,0 +1,57 @@
+import { IService } from './ServiceRegistry';
+import { Store } from '@tanstack/store';
+/**
+ * Abstract base class for all reactive services in EzUX.
+ *
+ * Provides built-in reactive state management with debouncing,
+ * automatic subscription handling, and a standardized cleanup lifecycle.
+ *
+ * @template TState The shape of the service's internal state.
+ * @group Services
+ */
+export declare abstract class BaseService<TState> implements IService {
+    abstract name: string;
+    store: Store<TState>;
+    protected cleanupTasks: (() => void)[];
+    protected debounceMs: number;
+    private debounceTimer;
+    constructor(initialState: TState);
+    /**
+     * Allows accessing the current state directly via getter
+     * to maintain backward compatibility.
+     */
+    protected get state(): TState;
+    /** Returns the current active state of the service. @group Methods */
+    getState(): TState;
+    /**
+     * Registers a task to be executed during service cleanup.
+     * Useful for clearing timers, removing event listeners, or closing connections.
+     * @group Methods
+     */
+    protected registerCleanup(task: () => void): void;
+    /**
+     * Subscribes to service state changes.
+     * @param listener Callback triggered on state updates.
+     * @returns Unsubscribe function.
+     * @group Methods
+     */
+    subscribe(listener: (state: TState) => void): () => void;
+    /**
+     * Updates the service state.
+     * Supports both partial objects and functional updaters.
+     * @group Methods
+     */
+    protected setState(updater: Partial<TState> | ((prev: TState) => Partial<TState>)): void;
+    /**
+     * Sets a debounce time for notifications to prevent rapid re-renders in components.
+     * @param ms Delay in milliseconds. Set to 0 to disable (immediate).
+     * @group Methods
+     */
+    setDebounce(ms: number): void;
+    /**
+     * Performs final cleanup for the service.
+     * Triggers all registered cleanup tasks and clears all subscribers.
+     * @group Methods
+     */
+    cleanup(): void;
+}

package/dist/shared/services/ContextMenuService.d.ts

@@ -0,0 +1,58 @@
+import { IService } from './ServiceRegistry';
+/**
+ * Represents an individual item in a context menu.
+ * @group Services
+ */
+export interface MenuItem {
+    /** Unique identifier for the menu item. @group Data */
+    id: string;
+    /** Text label to display. @group Data */
+    label: string;
+    /** Internal action identifier triggered on click. @group Data */
+    action: string;
+    /** Optional icon element. @group Appearance */
+    icon?: React.ReactNode;
+    /** Keyboard shortcut hint (e.g., 'Ctrl+C'). @group Appearance */
+    shortcut?: string;
+    /** Whether the item is non-interactive. @group Properties */
+    disabled?: boolean;
+    /** Whether to render a visual separator below this item. @group Appearance */
+    isSeparator?: boolean;
+    /** Custom CSS class for the item. @group Appearance */
+    className?: string;
+    /** Custom click handler. @group Events */
+    onClick?: (data: any) => void;
+}
+/**
+ * Functional provider that generates menu items for a specific data context.
+ * @group Services
+ */
+export type ContextMenuProvider<T = any> = (data: T) => MenuItem[];
+/**
+ * Service for managing dynamic, context-aware menus across the application.
+ *
+ * Supports registration of menu providers by context ID and retrieval
+ * of localized, state-dependent menu items for specific data targets.
+ *
+ * @group Services
+ */
+export declare class ContextMenuService implements IService {
+    name: string;
+    private providers;
+    /**
+     * Registers a menu provider for a specific context.
+     * @param contextId Unique ID for the context (e.g., 'table-row').
+     * @param provider function that returns menu items based on the target data.
+     * @returns Unsubscribe function to remove the provider.
+     * @group Methods
+     */
+    register<T>(contextId: string, provider: ContextMenuProvider<T>): () => boolean;
+    /**
+     * Retrieves the list of menu items for a specific context and data target.
+     * @param contextId The ID of the context to lookup.
+     * @param data The data object the menu is opening for.
+     * @group Methods
+     */
+    getItems(contextId: string, data: any): MenuItem[];
+    cleanup(): void;
+}

package/dist/shared/services/ExportService.d.ts

@@ -0,0 +1,35 @@
+import { IService } from './ServiceRegistry';
+/**
+ * Options for configuring data exports.
+ * @group Properties
+ */
+export interface ExportOptions {
+    /** Target filename (without extension). @group Properties */
+    fileName?: string;
+    /** Internal sheet name (for Excel). @group Properties */
+    sheetName?: string;
+    /** List of field names to omit from the export. @group Data */
+    excludeColumns?: string[];
+}
+/**
+ * Service for client-side data exportation in various formats.
+ *
+ * Provides efficient CSV and Excel generation using `file-saver` and `xlsx`.
+ *
+ * @group Services
+ */
+export declare class ExportService implements IService {
+    name: string;
+    /**
+     * Exports an array of data to a CSV file.
+     * @param data The row data to export.
+     * @param columns Column definitions for mapping headers and accessors.
+     * @param options Export configuration options.
+     * @group Methods
+     */
+    exportToCSV<T>(data: T[], columns: {
+        header: string;
+        accessorKey?: string;
+        id?: string;
+    }[], options?: ExportOptions): void;
+}

package/dist/shared/services/FocusManagerService.d.ts

@@ -0,0 +1,33 @@
+import { IService } from './ServiceRegistry';
+/**
+ * Service for managing keyboard focus and accessibility across the application.
+ *
+ * Handles registration of focusable elements, programmatic focus movement,
+ * and standard ARIA focus trapping for modals and popovers.
+ *
+ * @group Services
+ */
+export declare class FocusManagerService implements IService {
+    name: string;
+    private focusableElements;
+    private currentFocusIndex;
+    constructor();
+    /** Registers an element as focusable and ensures proper tab order. @group Methods */
+    registerFocusable(element: HTMLElement): void;
+    /** Unregisters an element and updates the current focus tracking. @group Methods */
+    unregisterFocusable(element: HTMLElement): void;
+    /** Moves focus to the next element in the registration list. @group Methods */
+    focusNext(): void;
+    /** Moves focus to the previous element in the registration list. @group Methods */
+    focusPrevious(): void;
+    /**
+     * Traps keyboard focus within a specific DOM container.
+     * Common for dialogs and side sheets to maintain focus context.
+     *
+     * @param container The element to trap focus inside.
+     * @returns Cleanup function to release the trap.
+     * @group Methods
+     */
+    trapFocus(container: HTMLElement): () => void;
+    cleanup(): void;
+}

package/dist/shared/services/HierarchyService.d.ts

@@ -0,0 +1,43 @@
+import { IService } from './ServiceRegistry';
+/**
+ * Represents a node in a hierarchical data structure.
+ * @group Services
+ */
+export interface HierarchyNode {
+    /** Unique identifier for the node. @group Data */
+    id: string;
+    /** Array of child node IDs. @group Data */
+    children?: string[];
+    /** ID of the parent node. @group Data */
+    parentId?: string;
+    /** Depth level in the hierarchy (0-indexed). @group Data */
+    level: number;
+}
+/**
+ * Service for managing complex hierarchical relationships between data elements.
+ *
+ * Provides utility methods for traversing parent-child relationships,
+ * finding ancestors/descendants, and managing structural integrity of trees.
+ *
+ * @group Services
+ */
+export declare class HierarchyService implements IService {
+    name: string;
+    private nodeMap;
+    constructor();
+    /** Registers a node in the hierarchy map. @group Methods */
+    registerNode(node: HierarchyNode): void;
+    /** Removes a node and its structural links from the map. @group Methods */
+    unregisterNode(id: string): void;
+    /** Returns the direct parent node of a given node ID. @group Methods */
+    getParent(id: string): HierarchyNode | undefined;
+    /** Returns an array of direct child nodes for a given node ID. @group Methods */
+    getChildren(id: string): HierarchyNode[];
+    /** Returns all descendants (children, grandchildren, etc.) IDs for a node. @group Methods */
+    getDescendants(id: string): string[];
+    /** Returns all ancestor (parent, grandparent, etc.) IDs for a node. @group Methods */
+    getAncestors(id: string): string[];
+    /** Retrieves a specific hierarchy node by ID. @group Methods */
+    getNode(id: string): HierarchyNode | undefined;
+    cleanup(): void;
+}

package/dist/shared/services/I18nService.d.ts

@@ -0,0 +1,84 @@
+import { BaseService } from './BaseService';
+/**
+ * Current state of the internationalization service.
+ * @group State
+ */
+export interface I18nState {
+    /** Current locale code (e.g., 'en', 'fr'). @group Data */
+    locale: string;
+    /** Text direction associated with the locale (ltr or rtl). @group Data */
+    dir: 'ltr' | 'rtl';
+    /** Map of all registered translations. @group Data */
+    translations: Record<string, Record<string, string>>;
+}
+/**
+ * A reactive internationalization service for EzUX.
+ *
+ * Manages locale changes, text direction (RTL support), and translation lookups.
+ * Supports dynamic registration of component-specific translation strings.
+ *
+ * @group Services
+ */
+export declare class I18nService extends BaseService<I18nState> {
+    name: string;
+    readonly supportedLanguages: {
+        code: string;
+        name: string;
+        country: string;
+    }[];
+    private initialTranslations;
+    private _locale;
+    private _translations;
+    constructor(defaultLocale?: string);
+    get locale(): string;
+    get dir(): "ltr" | "rtl";
+    /**
+     * Sets the active locale and updates text direction.
+     * @param locale The locale code to switch to.
+     * @group Methods
+     */
+    setLocale: (locale: string) => void;
+    /**
+     * Dynamically registers custom translations for a specific locale.
+     * @param locale The locale to add translations for.
+     * @param da Key-value pairs of translation strings.
+     * @group Methods
+     */
+    registerTranslations: (locale: string, da: Record<string, string>) => void;
+    /**
+     * Translates a key based on the current active locale.
+     * Falls back to the provided defaultValue, then to English, then returns the key itself.
+     * @param key The translation key to lookup.
+     * @param defaultValue Optional fallback string if the key is not found.
+     * @returns The localized string or the fallback/key if not found.
+     * @group Methods
+     */
+    t: (key: string, defaultValue?: string) => string;
+    /**
+     * Formats a date based on the current active locale.
+     * @param value The date to format.
+     * @param options Formatting options.
+     * @group Formatting
+     */
+    formatDate: (value: Date | string | null | undefined, options?: {
+        format?: "short" | "long" | "relative" | "iso";
+    }) => string;
+    /**
+     * Formats a number based on the current active locale.
+     * @param value The number to format.
+     * @param options Formatting options.
+     * @group Formatting
+     */
+    formatNumber: (value: number | null | undefined, options?: {
+        format?: "integer" | "float" | "currency" | "percentage";
+        decimals?: number;
+        currency?: string;
+    }) => string;
+    /**
+     * Formats a currency based on the current active locale.
+     * @param value The amount to format.
+     * @param currency The currency code (default: USD).
+     * @group Formatting
+     */
+    formatCurrency: (value: number, currency?: string) => string;
+}

package/dist/shared/services/LayoutService.d.ts

@@ -0,0 +1,80 @@
+import { BaseService } from './BaseService';
+type LayoutMode = 'dashboard' | 'auth' | 'minimal';
+/**
+ * Reactive state for the application layout system.
+ * @group State
+ */
+export interface LayoutState {
+    /** Whether the primary sidebar is visible. @group State */
+    sidebarOpen: boolean;
+    /** Current high-level layout mode. @group Properties */
+    mode: LayoutMode;
+    /** Fixed height of the application header. @group Appearance */
+    headerHeight: number;
+    /** Fixed width of the application sidebar. @group Appearance */
+    sidebarWidth: number;
+    /** Viewport width threshold for mobile behavior (in px). @group Properties */
+    breakpoint: number;
+    /** Current tracked height of the viewport. @group State */
+    viewportHeight: number;
+    /** Whether the current viewport is considered mobile. @group State */
+    isMobile: boolean;
+    /** Active page in the auth flow. @group State */
+    authPage: 'signin' | 'signup';
+    /** Dynamic overlay or side panels currently active. @group State */
+    panels: {
+        id: string;
+        content: any;
+        position: 'left' | 'right' | 'bottom';
+    }[];
+}
+/**
+ * Service for managing the application's shell, responsiveness, and dynamic panels.
+ *
+ * Centralizes layout configuration, viewport tracking, and provides a reactive
+ * API for controlling the UI frame from anywhere in the application.
+ *
+ * @group Services
+ */
+export declare class LayoutService extends BaseService<LayoutState> {
+    name: string;
+    constructor();
+    private handleResize;
+    /**
+     * Updates the core layout dimensions and breakpoints.
+     * @group Methods
+     */
+    updateConfig(config: {
+        headerHeight?: number;
+        sidebarWidth?: number;
+        breakpoint?: number;
+    }): void;
+    /**
+     * Toggles the sidebar visibility.
+     * @param open Optional explicit state to set.
+     * @group Methods
+     */
+    toggleSidebar(open?: boolean): void;
+    /** Sets the active layout mode. @group Methods */
+    setMode(mode: LayoutMode): void;
+    /** Switches the active auth page view. @group Methods */
+    setAuthPage(page: 'signin' | 'signup'): void;
+    /** Registers a new floating or docked panel. @group Methods */
+    addPanel(panel: {
+        id: string;
+        content: any;
+        position: 'left' | 'right' | 'bottom';
+    }): void;
+    /** Removes a registered panel by ID. @group Methods */
+    removePanel(id: string): void;
+    /**
+     * Helper to get CSS styles for the main content area based on layout state.
+     * @group Methods
+     */
+    getMainContentStyle(): {
+        height: string;
+        marginLeft: string;
+        transition: string;
+    };
+}
+export {};

package/dist/shared/services/NotificationService.d.ts

@@ -0,0 +1,44 @@
+import { IService } from './ServiceRegistry';
+/**
+ * Represents a single user notification item.
+ * @group Services
+ */
+export interface Notification {
+    /** Unique identifier for the notification. @group Data */
+    id: string;
+    /** The alert level: info, success, warning, or error. @group Data */
+    type: 'info' | 'success' | 'warning' | 'error';
+    /** The message content to display. @group Data */
+    message: string;
+    /** Optional auto-dismiss duration in milliseconds (0 for persistent). @group Properties */
+    duration?: number;
+}
+/**
+ * A central service for managing application-wide alerts and feedback.
+ *
+ * Supports multiple concurrent notifications with automatic dismissal and
+ * reactive state synchronization for UI panels.
+ *
+ * @group Services
+ */
+export declare class NotificationService implements IService {
+    name: string;
+    private subscribers;
+    private notifications;
+    /** Adds a new notification to the active queue. @group Methods */
+    add(notification: Omit<Notification, 'id'>): void;
+    /** Direct alias for `add`. @group Methods */
+    show(notification: Omit<Notification, 'id'>): void;
+    /** Manually removes a notification by its ID. @group Methods */
+    remove(id: string): void;
+    /** Clears all active notifications. @group Methods */
+    clearAll(): void;
+    /**
+     * Subscribes to notifications queue changes.
+     * @param callback Callback triggered when notifications are added or removed.
+     * @returns Unsubscribe function.
+     * @group Methods
+     */
+    subscribe(callback: (notifications: Notification[]) => void): () => boolean;
+    private notify;
+}

package/dist/shared/services/PersistenceService.d.ts

@@ -0,0 +1,69 @@
+import { BaseService } from './BaseService';
+/**
+ * Data structure for persisting complex component states.
+ * @group State
+ */
+export interface EzTableStatePersistence {
+    /** Active sorting criteria. @group Data */
+    sorting?: any[];
+    /** Applied column filters. @group Data */
+    columnFilters?: any[];
+    /** Visibility state of columns. @group Appearance */
+    columnVisibility?: Record<string, boolean>;
+    /** Current display order of columns. @group Appearance */
+    columnOrder?: string[];
+    /** Pinning configuration for columns. @group Appearance */
+    columnPinning?: {
+        left?: string[];
+        right?: string[];
+    };
+    /** Data grouping configuration. @group Data */
+    grouping?: string[];
+    /** Pagination state. @group Data */
+    pagination?: {
+        pageIndex: number;
+        pageSize: number;
+    };
+}
+/**
+ * Service for handling local browser persistence of application state.
+ *
+ * Provides a standardized way to save and load serialized state objects to
+ * `localStorage` with error handling and reactive access tracking.
+ *
+ * @group Services
+ */
+/**
+ * Internal state for the Persistence Service.
+ * @group State
+ */
+interface PersistenceState {
+    /** The key of the last state object saved or loaded. @group Data */
+    lastAccessedKey: string | null;
+}
+export declare class PersistenceService extends BaseService<PersistenceState> {
+    name: string;
+    constructor();
+    /**
+     * Saves a state object to the local storage with a specific key.
+     * @param key Unique key for the storage entry.
+     * @param state The state object to persist.
+     * @group Methods
+     */
+    saveState(key: string, state: EzTableStatePersistence): void;
+    /**
+     * Loads a state object from local storage.
+     * @param key Unique key for the storage entry.
+     * @returns The parsed state object or null if not found.
+     * @group Methods
+     */
+    loadState(key: string): EzTableStatePersistence | null;
+    /**
+     * Removes a state entry from local storage.
+     * @param key Unique key to clear.
+     * @group Methods
+     */
+    clearState(key: string): void;
+}
+export declare const globalPersistenceService: PersistenceService;
+export {};