ezux 1.0.0

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

@@ -0,0 +1,44 @@
+/**
+ * Row selection event callbacks shared across components.
+ */
+export interface RowSelectionCallbacks<TData = any> {
+    onRowSelect?: (args: {
+        row: any;
+        data: TData;
+        rowIndex: number;
+        originalEvent?: React.SyntheticEvent;
+    }) => void;
+    onRowDeselect?: (args: {
+        row: any;
+        data: TData;
+        rowIndex: number;
+    }) => void;
+    onSelectionChange?: (selection: {
+        selectedIds: (string | number)[];
+        mode?: 'single' | 'multiple';
+    }) => void;
+}
+/**
+ * Row selection state for tracking changes
+ */
+export interface RowSelectionState {
+    [key: string]: boolean;
+}
+/**
+ * Shared hook for row selection events.
+ * Tracks selection changes and emits per-row select/deselect events.
+ * Used by EzTable, EzScheduler, EzTreeView.
+ *
+ * @example
+ * const { handleSelectionChange } = useRowSelectionEvents(props, getRowData);
+ *
+ * // On selection state change
+ * handleSelectionChange(newSelection, event);
+ */
+export declare const useRowSelectionEvents: <TData = any>(callbacks: RowSelectionCallbacks<TData>, getRowData: (rowId: string | number, index: number) => {
+    row: any;
+    data: TData;
+} | undefined) => {
+    handleSelectionChange: (newSelection: RowSelectionState, originalEvent?: React.SyntheticEvent) => void;
+    getPreviousSelection: () => RowSelectionState;
+};

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

@@ -0,0 +1,73 @@
+/**
+ * Configuration for the useSelection hook.
+ * @group Properties
+ */
+export interface SelectionConfig<TData = any> {
+    /** Selection mode: single, multiple, or range. @default 'multiple' @group Properties */
+    mode?: 'single' | 'multiple' | 'range';
+    /** Whether to enable keyboard interaction support. @group Properties */
+    enableKeyboardNavigation?: boolean;
+    /** Callback triggered when selection changes. @group Events */
+    onSelectionChange?: (selectedIds: (string | number)[], selectedItems: TData[]) => void;
+    /** Function to extract a unique ID from an item. @group Data */
+    getItemId?: (item: TData) => string | number;
+}
+/**
+ * Internal selection state.
+ * @group State
+ */
+export interface SelectionState {
+    /** Set of currently selected unique identifiers. @group State */
+    selectedIds: Set<string | number>;
+    /** ID of the node currently receiving focus. @group State */
+    focusedId: string | number | null;
+    /** ID of the node acting as the anchor for range selection. @group State */
+    anchorId: string | number | null;
+}
+/**
+ * Public API for selection management.
+ * @group Methods
+ */
+export interface SelectionAPI<TData = any> {
+    /** Selects a single item by ID. @group Methods */
+    selectItem: (id: string | number) => void;
+    /** Selects multiple items by ID. @group Methods */
+    selectItems: (ids: (string | number)[]) => void;
+    /** Deselects a single item by ID. @group Methods */
+    deselectItem: (id: string | number) => void;
+    /** Deselects multiple items by ID. @group Methods */
+    deselectItems: (ids: (string | number)[]) => void;
+    /** Toggles the selection state of an item. @group Methods */
+    toggleItem: (id: string | number) => void;
+    /** Selects all available items (multi-mode only). @group Methods */
+    selectAll: () => void;
+    /** Clears all current selections. @group Methods */
+    clearSelection: () => void;
+    /** Selects a range of items between two IDs. @group Methods */
+    selectRange: (startId: string | number, endId: string | number) => void;
+    /** Checks if a specific ID is selected. @group Methods */
+    isSelected: (id: string | number) => boolean;
+    /** Returns an array of all selected IDs. @group Methods */
+    getSelectedIds: () => (string | number)[];
+    /** Returns an array of all selected data items. @group Methods */
+    getSelectedItems: () => TData[];
+    /** Returns the total number of selected items. @group Methods */
+    getSelectionCount: () => number;
+    /** Returns whether any items are currently selected. @group Methods */
+    hasSelection: () => boolean;
+    /** Sets the focused item ID. @group Methods */
+    setFocusedId: (id: string | number | null) => void;
+    /** Gets the currently focused item ID. @group Methods */
+    getFocusedId: () => string | number | null;
+}
+/**
+ * Shared selection hook for table, tree, and scheduler components.
+ *
+ * Provides standardized selection management (single/multiple/range) with support for
+ * keyboard navigation and persistent focus.
+ *
+ * @param items The list of items to manage selection for.
+ * @param config Selection behavior configuration.
+ * @group Hooks
+ */
+export declare const useSelection: <TData = any>(items: TData[], config?: SelectionConfig<TData>) => SelectionAPI<TData>;

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

@@ -0,0 +1,12 @@
+import { IService, ServiceRegistry } from '../services/ServiceRegistry';
+/**
+ * Hook for standardized service access.
+ * Abstracts service registration and access patterns.
+ * Ensures the service is registered and provides a stable reference.
+ *
+ * @param serviceName Unique name of the service
+ * @param factory Factory function to create the service if not registered
+ * @param registry Optional service registry to use (defaults to global)
+ * @returns The requested service instance
+ */
+export declare const useService: <T extends IService>(serviceName: string, factory: () => T, registry?: ServiceRegistry | null) => T;

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

@@ -0,0 +1,12 @@
+/**
+ * Hook for subscribing to a service's state in a reactive way.
+ *
+ * Automatically handles subscriptions to any service extending `BaseService`.
+ * Returns the latest state and triggers re-renders on service updates.
+ *
+ * @template TState The shape of the service's state.
+ * @param serviceName The name of the service to subscribe to.
+ * @returns The current state of the service.
+ * @group Hooks
+ */
+export declare const useServiceState: <TState>(serviceName: string) => TState | undefined;

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,56 @@
+import { IService } from './ServiceRegistry';
+/**
+ * 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;
+    protected state: TState;
+    private subscribers;
+    private isUpdating;
+    private updateQueue;
+    protected cleanupTasks: (() => void)[];
+    constructor(initialState: 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 and notifies subscribers.
+     * Supports both partial objects and functional updaters.
+     * @group Methods
+     */
+    protected setState(updater: Partial<TState> | ((prev: TState) => Partial<TState>)): void;
+    private debounceTimer;
+    protected debounceMs: number;
+    /**
+     * 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;
+    private notifySubscribers;
+    private broadcast;
+    /**
+     * 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,65 @@
+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";
+    /**
+     * 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;
+    setLocale(_locale: string): void;
+    registerTranslations(_locale: string, _da: Record<string, string>): void;
+    t(_key: string): string;
+}