ezux 1.0.0

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 {};

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

@@ -0,0 +1,51 @@
+import { BaseService } from './BaseService';
+/**
+ * Base interface for all services in the EzUX ecosystem.
+ * @group Services
+ */
+export interface IService {
+    /** Unique name of the service for registration and lookup. @group Data */
+    name: string;
+    /** Optional cleanup logic to run when the service is unregistered. @group Methods */
+    cleanup?: () => void;
+}
+/**
+ * Interface for a service repository that manages service lifecycles and dependency injection.
+ * @group Services
+ */
+export interface ServiceRegistry {
+    /** Registers a service instance by name. @group Methods */
+    register<T extends IService>(name: string, service: T): void;
+    /** Retrieves a service instance by name, if it exists. @group Methods */
+    get<T extends IService>(name: string): T | undefined;
+    /** Retrieves a service or throws an error if not found. @group Methods */
+    getOrThrow<T extends IService>(name: string): T;
+    /** Removes a service from the registry and triggers its cleanup. @group Methods */
+    unregister(name: string): void;
+    /** Triggers cleanup for all registered services. @group Methods */
+    cleanupAll(): void;
+}
+interface ServiceRegistryState {
+    serviceNames: string[];
+}
+/**
+ * A central repository for managing and accessing shared services.
+ *
+ * Supports dependency injection patterns across components and ensures
+ * proper singleton management and cleanup of library resources.
+ *
+ * @group Services
+ */
+export declare class EzServiceRegistry extends BaseService<ServiceRegistryState> implements ServiceRegistry {
+    name: string;
+    private services;
+    constructor();
+    register<T extends IService>(name: string, service: T): void;
+    get<T extends IService>(name: string): T | undefined;
+    getOrThrow<T extends IService>(name: string): T;
+    unregister(name: string): void;
+    cleanupAll(): void;
+    private updateState;
+}
+export declare const globalServiceRegistry: EzServiceRegistry;
+export {};

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

@@ -0,0 +1,49 @@
+import { IService } from './ServiceRegistry';
+import { ThemeName, ThemeMode } from '../themes';
+export type { ThemeMode, ThemeName as ThemeColor };
+/**
+ * A reactive service for managing the library's visual theme.
+ *
+ * Handles switching between light, dark, and system modes, as well as applying
+ * custom color palettes and UI scaling (radius). Persists settings to local storage.
+ *
+ * @group Services
+ */
+export declare class ThemeService implements IService {
+    name: string;
+    private listeners;
+    private state;
+    /**
+     * Directly applies a color theme to the document root bypassing the service instance.
+     * Useful for initial hydration or static branding.
+     *
+     * @param mode Theme mode (light or dark).
+     * @param color The name of the color palette to apply.
+     * @group Methods
+     */
+    static setGlobalColorTheme(mode: ThemeMode, color: ThemeName): void;
+    constructor();
+    /** Toggles between light and dark modes. @group Methods */
+    toggleMode(): void;
+    /** Sets the explicit theme mode. @group Methods */
+    setMode(mode: ThemeMode): void;
+    /** Updates the primary color palette. @group Methods */
+    setThemeColor(color: ThemeName): void;
+    /** Sets the global UI border radius (in rem). @group Methods */
+    setRadius(radius: number): void;
+    /** Returns the current active theme state. @group Methods */
+    getState(): {
+        mode: ThemeMode;
+        themeColor: ThemeName;
+        radius: number;
+    };
+    private applyTheme;
+    /**
+     * Subscribes to theme changes.
+     * @param listener Callback triggered on state updates.
+     * @returns Unsubscribe function.
+     * @group Methods
+     */
+    subscribe(listener: (state: any) => void): () => void;
+    private notify;
+}

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

@@ -0,0 +1,51 @@
+import { IService } from './ServiceRegistry';
+import { Virtualizer } from '@tanstack/virtual-core';
+/**
+ * Options for creating a new virtualizer instance.
+ * @group Properties
+ */
+export interface VirtualizationOptions {
+    /** Total number of items to virtualize. @group Data */
+    count: number;
+    /** Function to retrieve the scroll container element. @group Data */
+    getScrollElement: () => Element | Window | null;
+    /** Function to estimate the size of an item by index. @group Appearance */
+    estimateSize: (index: number) => number;
+    /** Number of items to render outside the visible range. @default 5 @group Performance */
+    overscan?: number;
+    /** Whether virtualization is horizontal (default is vertical). @default false @group Appearance */
+    horizontal?: boolean;
+}
+/**
+ * A central service for managing high-performance virtualization across the library.
+ *
+ * Provides a standardized way to create and register TanStack virtualizers,
+ * enabling coordinated scroll management and performance monitoring.
+ *
+ * @group Services
+ */
+export declare class VirtualizationService implements IService {
+    name: string;
+    private virtualizers;
+    /**
+     * Creates and registers a new virtualizer instance.
+     * @param id Unique identifier for the virtualizer.
+     * @param options Configuration for the virtualizer.
+     * @returns The newly created virtualizer instance.
+     * @group Methods
+     */
+    createVirtualizer(id: string, options: VirtualizationOptions): Virtualizer<Element | Window, Element>;
+    /**
+     * Registers an existing virtualizer instance with the service.
+     * @param id Unique identifier for the virtualizer.
+     * @param virtualizer The virtualizer instance to register.
+     * @group Methods
+     */
+    registerVirtualizer(id: string, virtualizer: Virtualizer<any, any>): void;
+    /**
+     * Retrieves a registered virtualizer instance by its ID.
+     * @group Methods
+     */
+    getVirtualizer(id: string): Virtualizer<Element | Window, Element> | undefined;
+    cleanup(): void;
+}

package/dist/shared/state/store.d.ts

@@ -0,0 +1,10 @@
+import { Store } from '@tanstack/store';
+export interface UIState {
+    theme: 'light' | 'dark' | 'system';
+    rtl: boolean;
+    locale: string;
+}
+export declare const uiStore: Store<UIState, (cb: UIState) => UIState>;
+export declare const updateTheme: (theme: UIState["theme"]) => void;
+export declare const toggleRTL: () => void;
+export declare const setLocale: (locale: string) => void;

package/dist/shared/themes.d.ts

@@ -0,0 +1,25 @@
+export type ThemeMode = 'light' | 'dark';
+export interface ThemeVariables {
+    "background": string;
+    "foreground": string;
+    "card": string;
+    "card-foreground": string;
+    "popover": string;
+    "popover-foreground": string;
+    "primary": string;
+    "primary-foreground": string;
+    "secondary": string;
+    "secondary-foreground": string;
+    "muted": string;
+    "muted-foreground": string;
+    "accent": string;
+    "accent-foreground": string;
+    "destructive": string;
+    "destructive-foreground": string;
+    "border": string;
+    "input": string;
+    "ring": string;
+    "radius"?: string;
+}
+export type ThemeName = 'Orange' | 'Blue' | 'Green' | 'Rose' | 'Zinc';
+export declare const themes: Record<ThemeName, Record<ThemeMode, Partial<ThemeVariables>>>;

package/dist/shared/types/BaseProps.d.ts

@@ -0,0 +1,18 @@
+import { ServiceRegistry } from '../services/ServiceRegistry';
+import { BaseComponentProps } from './commonTypes';
+import { ComponentEventCallbacks } from './common';
+export interface SharedBaseProps extends BaseComponentProps, ComponentEventCallbacks {
+    /**
+     * The shared service registry instance.
+     * This is required to access shared services like HierarchyService, FocusManagerService, etc.
+     * @group Services
+     */
+    serviceRegistry?: ServiceRegistry;
+}
+/**
+ * Base interface for data that can be rendered in a table or tree.
+ */
+export interface TableRowData {
+    id: string;
+    [key: string]: any;
+}

package/dist/shared/types/common.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Shared type definitions used across components
+ */
+/**
+ * Common class names for component styling
+ */
+export interface ComponentClassNames {
+    root?: string;
+    header?: string;
+    body?: string;
+    footer?: string;
+    toolbar?: string;
+    row?: string | ((row: any) => string);
+    cell?: string | ((cell: any) => string);
+}
+/**
+ * Common slots for component customization
+ */
+export interface ComponentSlots<TData = any> {
+    header?: React.ComponentType<{
+        data?: TData;
+        [key: string]: any;
+    }>;
+    footer?: React.ComponentType<{
+        data?: TData;
+        [key: string]: any;
+    }>;
+    toolbar?: React.ComponentType<{
+        data?: TData;
+        [key: string]: any;
+    }>;
+    noData?: React.ComponentType<{
+        [key: string]: any;
+    }>;
+    loading?: React.ComponentType<{
+        [key: string]: any;
+    }>;
+}
+/**
+ * Common localization strings
+ */
+export interface ComponentLocalization {
+    noData?: string;
+    loading?: string;
+    search?: string;
+    filter?: string;
+    sort?: string;
+    export?: string;
+    print?: string;
+    refresh?: string;
+    add?: string;
+    edit?: string;
+    delete?: string;
+    save?: string;
+    cancel?: string;
+    selectAll?: string;
+    clearSelection?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Common density options
+ */
+export type Density = 'compact' | 'standard' | 'comfortable';
+/**
+ * Common alignment options
+ */
+export type Alignment = 'left' | 'center' | 'right';
+/**
+ * Common pinned positions
+ */
+export type PinnedPosition = 'left' | 'right' | false;
+/**
+ * Common sort direction
+ */
+export type SortDirection = 'asc' | 'desc' | false;
+/**
+ * Common filter operator
+ */
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'between' | 'in' | 'notIn';
+/**
+ * Common filter model
+ */
+export interface FilterModel {
+    field: string;
+    operator: FilterOperator;
+    value: any;
+    condition?: 'and' | 'or';
+}
+/**
+ * Common sort model
+ */
+export interface SortModel {
+    field: string;
+    direction: SortDirection;
+}
+/**
+ * Common pagination model
+ */
+export interface PaginationModel {
+    pageIndex: number;
+    pageSize: number;
+    totalRows?: number;
+}
+/**
+ * Common selection model
+ */
+export interface SelectionModel {
+    selectedIds: (string | number)[];
+    mode?: 'single' | 'multiple';
+}
+/**
+ * Common edit mode
+ */
+export type EditMode = 'inline' | 'dialog' | 'batch';
+/**
+ * Common edit settings
+ */
+export interface EditSettings {
+    mode?: EditMode;
+    allowAdding?: boolean;
+    allowEditing?: boolean;
+    allowDeleting?: boolean;
+    showDeleteConfirm?: boolean;
+}
+/**
+ * Common validation result
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors?: Record<string, string>;
+}
+/**
+ * Common event callback types
+ * Contains ONLY events that are truly shared across components with identical signatures.
+ * Component-specific events (onCellClick, onRowClick, etc) should be defined in each component's types.
+ */
+export interface ComponentEventCallbacks<TData = any> {
+    /**
+     * Callback when component is created.
+     * @group Events
+     */
+    onCreated?: () => void;
+    /**
+     * Callback when component is destroyed.
+     * @group Events
+     */
+    onDestroyed?: () => void;
+    /**
+     * Callback when grid/component render starts.
+     * @group Events
+     */
+    onGridRenderStart?: () => void;
+    /**
+     * Callback when grid/component render completes.
+     * @group Events
+     */
+    onGridRenderComplete?: () => void;
+    /**
+     * Callback when data changes.
+     * @group Events
+     */
+    onDataChange?: (data: TData[]) => void;
+    /**
+     * Callback when data loads.
+     * @group Events
+     */
+    onDataLoad?: (data: TData[]) => void;
+    /**
+     * Callback when data is requested.
+     * @group Events
+     */
+    onDataRequest?: (query: any) => void;
+    /**
+     * Callback when data change starts.
+     * @group Events
+     */
+    onDataChangeStart?: (args: {
+        action: 'add' | 'edit' | 'delete';
+        data: TData | TData[];
+    }) => void;
+    /**
+     * Callback when data change completes.
+     * @group Events
+     */
+    onDataChangeComplete?: (args: {
+        action: 'add' | 'edit' | 'delete';
+        data: TData | TData[];
+    }) => void;
+    /**
+     * Callback when data change is cancelled.
+     * @group Events
+     */
+    onDataChangeCancel?: (args: {
+        action: 'add' | 'edit' | 'delete';
+        row?: any;
+    }) => void;
+    /**
+     * Callback when data change is requested.
+     * @group Events
+     */
+    onDataChangeRequest?: (args: {
+        action: 'add' | 'edit' | 'delete';
+        data: TData;
+    }) => void;
+    /**
+     * Callback on error.
+     * @group Events
+     */
+    onError?: (error: any) => void;
+    /**
+     * Callback on refresh.
+     * @group Events
+     */
+    onRefresh?: () => void;
+}
+/**
+ * Common export options
+ */
+export interface ExportOptions {
+    filename?: string;
+    format?: 'csv' | 'excel' | 'pdf';
+    includeHeaders?: boolean;
+    selectedOnly?: boolean;
+}
+/**
+ * Common clipboard data
+ */
+export interface ClipboardData<TData = any> {
+    data: TData;
+    action: 'copy' | 'cut';
+    timestamp: number;
+}
+/**
+ * Common drag and drop data
+ */
+export interface DragDropData<TData = any> {
+    item: TData;
+    sourceIndex: number;
+    targetIndex?: number;
+    position?: 'before' | 'after' | 'inside';
+}
+/**
+ * Common context menu item
+ */
+export interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    separator?: boolean;
+    children?: ContextMenuItem[];
+    onClick?: () => void;
+}
+/**
+ * Common keyboard shortcut
+ */
+export interface KeyboardShortcut {
+    key: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    handler: (event: KeyboardEvent) => void;
+}
+/**
+ * Common theme configuration
+ */
+export interface ThemeConfig {
+    mode?: 'light' | 'dark' | 'system';
+    primaryColor?: string;
+    accentColor?: string;
+    borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+}
+/**
+ * Common responsive breakpoints
+ */
+export interface ResponsiveBreakpoints {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+    wide: number;
+}
+/**
+ * Common viewport state
+ */
+export interface ViewportState {
+    width: number;
+    height: number;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+}