ezux 1.1.13 → 1.1.18

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

@@ -0,0 +1,52 @@
+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;
+    /** Subscribes to registry state changes (e.g. services added or removed). @group Methods */
+    subscribe(listener: (state: ServiceRegistryState) => void): () => 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 {};

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, never>;
+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,17 @@
+import { ServiceRegistry } from '../services/ServiceRegistry';
+import { BaseComponentProps, ComponentEventCallbacks } from './common';
+export interface SharedBaseProps<TData = unknown> extends BaseComponentProps, ComponentEventCallbacks<TData> {
+    /**
+     * 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,373 @@
+import { default as React } from 'react';
+/**
+ * Base Component Types
+ */
+export interface BaseComponentProps {
+    /** Unique identifier for the component instance @group Properties */
+    id?: string;
+    /** Custom class names for styling @group Properties */
+    className?: string;
+    /** Inline styles @group Properties */
+    style?: React.CSSProperties;
+    /** Data attribute for testing @group Properties */
+    dataTestId?: string;
+    /** Direction of the text (ltr, rtl, auto) @group Properties */
+    dir?: 'ltr' | 'rtl' | 'auto';
+}
+/**
+ * Common class names for component styling
+ */
+export interface ComponentClassNames<TData = unknown> {
+    root?: string;
+    header?: string;
+    body?: string;
+    footer?: string;
+    toolbar?: string;
+    row?: string | ((row: TData) => string);
+    cell?: string | ((cell: unknown) => string);
+}
+/**
+ * Common slots for component customization
+ */
+export interface ComponentSlots<TData = unknown> {
+    header?: React.ComponentType<{
+        data?: TData;
+        [key: string]: unknown;
+    }>;
+    footer?: React.ComponentType<{
+        data?: TData;
+        [key: string]: unknown;
+    }>;
+    toolbar?: React.ComponentType<{
+        data?: TData;
+        [key: string]: unknown;
+    }>;
+    noData?: React.ComponentType<{
+        [key: string]: unknown;
+    }>;
+    loading?: React.ComponentType<{
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * 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;
+/**
+ * Filter Utilities Types
+ */
+export type FilterOperator = 'contains' | 'doesNotContain' | 'shouldContain' | 'equals' | 'notEquals' | 'doesNotEqual' | 'startsWith' | 'endsWith' | 'empty' | 'notEmpty' | 'gt' | 'greaterThan' | 'lt' | 'lessThan' | 'gte' | 'greaterThanOrEqual' | 'lte' | 'lessThanOrEqual' | 'between' | 'in' | 'notIn';
+export interface FilterRule<TValue = unknown> {
+    kind?: 'rule';
+    id?: string;
+    field: string;
+    operator: FilterOperator;
+    value: TValue;
+    condition?: 'and' | 'or';
+}
+export interface FilterGroup {
+    kind?: 'group';
+    id?: string;
+    logic: 'AND' | 'OR';
+    filters: (FilterRule | FilterGroup)[];
+}
+/**
+ * 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>;
+}
+/**
+ * Represents a structured request for data fetching/filtering.
+ */
+export interface DataQuery {
+    filters?: FilterRule[] | FilterGroup;
+    sort?: SortModel[];
+    pagination?: PaginationModel;
+    search?: string;
+    [key: string]: any;
+}
+/**
+ * State Types
+ */
+export interface State<T> {
+    data: T;
+    loading: boolean;
+    error: Error | null;
+    initialized: boolean;
+}
+/**
+ * Event Types
+ */
+export interface BaseEvent {
+    timestamp: Date;
+    source: string;
+}
+export interface SelectionEvent<T> extends BaseEvent {
+    selected: T[];
+    deselected: T[];
+    changed: boolean;
+}
+/**
+ * Service Types
+ */
+export interface Service<T> {
+    name: string;
+    initialize(): Promise<void>;
+    cleanup(): void;
+    getState(): T;
+    setState(state: T): void;
+}
+/**
+ * Utility Types
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+export type PickPartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Tree Manipulation Types
+ */
+export interface TreeNode {
+    id: string;
+    label: string;
+    children?: TreeNode[];
+    icon?: React.ReactNode;
+    level?: number;
+    parentId?: string;
+    isLeaf?: boolean;
+    isLoading?: boolean;
+    isLoaded?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * 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 = unknown> {
+    /**
+     * 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: DataQuery) => 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?: TData;
+    }) => 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: Error | unknown) => 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 = unknown> {
+    data: TData;
+    action: 'copy' | 'cut';
+    timestamp: number;
+}
+/**
+ * Common drag and drop data
+ */
+export interface DragDropData<TData = unknown> {
+    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;
+}

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

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './BaseProps';

package/dist/shared/utils/canvasUtils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Helper to convert stroke points to SVG path data (Quadratic Bezier).
+ */
+export declare function getSvgPathFromStroke(stroke: number[][]): string;
+/**
+ * Standardized way to get a stroke path string from an outline or points with options.
+ */
+export declare function getStrokePath(stroke: number[][], options?: {
+    size?: number;
+    thinning?: number;
+    smoothing?: number;
+    streamline?: number;
+    simulatePressure?: boolean;
+    start?: any;
+    end?: any;
+}): string;

package/dist/shared/utils/commonUtils.d.ts

@@ -0,0 +1,28 @@
+import { TreeNode, FilterGroup, FilterRule } from '../types/common';
+import * as formatters from './formatUtils';
+/**
+ * Data Transformation Utilities
+ */
+export declare function transformData<T>(data: any[], transformFn: (item: any) => T): T[];
+/**
+ * Validation Utilities
+ */
+export declare const validateRequired: (value: any) => import('./validationUtils').ValidationResult;
+/**
+ * Formatting Utilities
+ */
+export declare const currencyFormatter: Intl.NumberFormat;
+export declare const numberFormatter: Intl.NumberFormat;
+export declare const percentFormatter: Intl.NumberFormat;
+export declare const formatNumber: typeof formatters.formatNumber;
+export declare const formatDate: typeof formatters.formatDate;
+/**
+ * Tree Manipulation Utilities
+ */
+export declare const findNodeById: (nodes: TreeNode[], id: string) => TreeNode | undefined;
+export declare const updateNodeInNodes: (nodes: TreeNode[], id: string, updates: Partial<TreeNode>) => TreeNode[];
+/**
+ * Filter Utilities
+ */
+export declare const checkRule: (rule: FilterRule, getValue: (field: string) => any) => boolean;
+export declare const checkGroup: (group: FilterGroup, getValue: (field: string) => any) => boolean;

package/dist/shared/utils/csvUtils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility to convert an array of objects to a CSV string.
+ */
+export declare function convertToCSV(data: any[], columns: {
+    id: string;
+    header: string;
+}[]): string;

package/dist/shared/utils/dateUtils.d.ts

@@ -0,0 +1,5 @@
+export declare const dateUtils: {
+    formatDate: (date: Date | string | number | null | undefined, formatStr?: string) => string;
+    formatDateTime: (date: Date | string | number | null | undefined, formatStr?: string) => string;
+    isValidDate: (date: any) => boolean;
+};

package/dist/shared/utils/dndUtils.d.ts

@@ -0,0 +1,16 @@
+import { DragEndEvent } from '@dnd-kit/core';
+/**
+ * Shared DnD utilities for components.
+ */
+/**
+ * Basic arrayMove implementation to avoid dependency on @dnd-kit/sortable
+ */
+export declare const arrayMove: <T>(array: T[], from: number, to: number) => T[];
+/**
+ * Helper to handle basic array reordering after drag and drop
+ */
+export declare const reorderArray: <T>(items: T[], event: DragEndEvent) => T[];
+/**
+ * Checks if a drop is valid based on types
+ */
+export declare const isValidDrop: (activeType: string, overType: string, allowedTypes: string[]) => boolean;

package/dist/shared/utils/formatUtils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standard formatters with fallback to en-US.
+ * These are static - use the functional versions for dynamic locale support.
+ */
+export declare const currencyFormatter: Intl.NumberFormat;
+export declare const numberFormatter: Intl.NumberFormat;
+export declare const percentFormatter: Intl.NumberFormat;
+export declare function formatNumber(value: number | null | undefined, options?: {
+    format?: 'integer' | 'float' | 'currency' | 'percentage';
+    decimals?: number;
+    locale?: string;
+    currency?: string;
+}): string;
+export declare function formatDate(value: Date | string | null | undefined, options?: {
+    format?: 'short' | 'long' | 'relative' | 'iso';
+    locale?: string;
+}): string;
+export declare const formatCurrency: (value: number, locale?: string, currency?: string) => string;
+export declare const formatPercent: (value: number, locale?: string) => string;
+export declare const formatDateTime: (date: Date | string, locale?: string) => string;