@zengrid/shared 1.0.3 → 1.1.0

package/dist/src/reactive/interfaces.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Reactive Primitives - Interface Abstractions
+ *
+ * @description
+ * Interface-based abstractions for loose coupling and testability.
+ * Enables dependency injection, mocking, and composition.
+ *
+ * @example
+ * ```typescript
+ * // Use interfaces for loose coupling
+ * class ColumnModel {
+ *   constructor(private state: IReactiveState<ColumnState, ColumnEvent>) {}
+ * }
+ *
+ * // Can inject real or mock implementation
+ * const model = new ColumnModel(new ReactiveState());
+ * const testModel = new ColumnModel(new MockReactiveState());
+ * ```
+ */
+/**
+ * Subscriber for state changes
+ */
+export interface ISubscriber<E> {
+    onChange(event: E): void;
+    onBatchChange?(events: E[]): void;
+}
+/**
+ * Reactive state container with targeted subscriptions
+ *
+ * @template T - State value type (not exposed in interface, used internally)
+ * @template E - Event type (used in subscriptions)
+ */
+export interface IReactiveState<T, E> {
+    /**
+     * Subscribe to specific key changes (targeted O(m))
+     */
+    subscribeToKey(key: string, subscriber: ISubscriber<E>): () => void;
+    /**
+     * Subscribe to all state changes (global observer)
+     */
+    subscribeGlobal(subscriber: ISubscriber<E>): () => void;
+    /**
+     * Get subscriber count for debugging
+     */
+    getSubscriberCount(key: string): number;
+    /**
+     * Get global subscriber count
+     */
+    getGlobalSubscriberCount(): number;
+    /**
+     * Get event history (if enabled)
+     */
+    getEventHistory(): E[];
+    /**
+     * Get last N events from history
+     */
+    getLastEvents(count: number): E[];
+    /**
+     * Clear event history
+     */
+    clearEventHistory(): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+    __state?: T;
+}
+/**
+ * Manages subscriptions and notifications
+ */
+export interface ISubscriptionManager<E> {
+    subscribeToKey(key: string, subscriber: ISubscriber<E>): () => void;
+    subscribeGlobal(subscriber: ISubscriber<E>): () => void;
+    notifyKey(key: string, event: E): void;
+    notifyBatch(eventsByKey: Map<string, E[]>): void;
+    getKeySubscriberCount(key: string): number;
+    getGlobalSubscriberCount(): number;
+    hasKeySubscribers(key: string): boolean;
+    clear(): void;
+}
+/**
+ * Manages batch mode and event queuing
+ */
+export interface IBatchManager<E> {
+    isBatching(): boolean;
+    enterBatch(): void;
+    exitBatch(): void;
+    addEvent(key: string, event: E): void;
+    flushEvents(): Array<{
+        key: string;
+        event: E;
+    }>;
+    groupEventsByKey(events: Array<{
+        key: string;
+        event: E;
+    }>): Map<string, E[]>;
+    clear(): void;
+}
+/**
+ * Event handler types
+ */
+export interface IElementEventHandlers {
+    onClick?: (event: MouseEvent) => void;
+    onDblClick?: (event: MouseEvent) => void;
+    onMouseDown?: (event: MouseEvent) => void;
+    onMouseUp?: (event: MouseEvent) => void;
+    onMouseEnter?: (event: MouseEvent) => void;
+    onMouseLeave?: (event: MouseEvent) => void;
+    onContextMenu?: (event: MouseEvent) => void;
+    onFocus?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
+}
+/**
+ * Event delegator options
+ */
+export interface IEventDelegatorOptions {
+    idAttribute?: string;
+    customEvents?: Record<string, {
+        domEvent: string;
+        useCapture: boolean;
+    }>;
+}
+/**
+ * Event delegation for thousands of elements
+ */
+export interface IEventDelegator {
+    registerElement(elementId: string, handlers: IElementEventHandlers): void;
+    unregisterElement(elementId: string): void;
+    updateElement(elementId: string, handlers: IElementEventHandlers, merge?: boolean): void;
+    isRegistered(elementId: string): boolean;
+    getAllRegisteredIds(): string[];
+    getRegisteredCount(): number;
+    destroy(): void;
+}
+/**
+ * Object pool options
+ */
+export interface IObjectPoolOptions<T> {
+    factory: () => T;
+    reset?: (obj: T) => void;
+    validate?: (obj: T) => boolean;
+    initialSize?: number;
+    maxSize?: number;
+    onAcquire?: (obj: T) => void;
+    onRelease?: (obj: T) => void;
+    onEvict?: (obj: T) => void;
+}
+/**
+ * Object pool statistics
+ */
+export interface IObjectPoolStats {
+    available: number;
+    created: number;
+    acquired: number;
+    released: number;
+    hitRate: number;
+    maxSize: number;
+}
+/**
+ * Object pooling for virtual rendering
+ */
+export interface IObjectPool<T> {
+    acquire(): T;
+    release(obj: T): void;
+    acquireMany(count: number): T[];
+    releaseMany(objects: T[]): void;
+    prewarm(count: number): void;
+    size(): number;
+    getStats(): IObjectPoolStats;
+    shrink(targetSize: number): void;
+    clear(): void;
+    destroy(): void;
+}
+/**
+ * Batch processor options
+ */
+export interface IBatchProcessorOptions<T> {
+    process: (items: T[]) => void;
+    delay?: number;
+    maxBatchSize?: number;
+    deduplicate?: (items: T[]) => T[];
+}
+/**
+ * Batch processing for grouped operations
+ */
+export interface IBatchProcessor<T> {
+    add(item: T): void;
+    addMany(items: T[]): void;
+    flush(): void;
+    clear(): void;
+    size(): number;
+    isIdle(): boolean;
+    destroy(): void;
+}
+/**
+ * Event handler storage and lookup
+ */
+export interface IEventHandlerRegistry {
+    register(elementId: string, handlers: IElementEventHandlers): void;
+    unregister(elementId: string): void;
+    update(elementId: string, handlers: IElementEventHandlers, merge: boolean): void;
+    get(elementId: string): IElementEventHandlers | undefined;
+    getHandler(elementId: string, handlerName: keyof IElementEventHandlers): ((event: any) => void) | undefined;
+    size(): number;
+    clear(): void;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/reactive/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/reactive/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;CACnC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAEpE;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAExD;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAExC;;OAEG;IACH,wBAAwB,IAAI,MAAM,CAAC;IAEnC;;OAEG;IACH,eAAe,IAAI,CAAC,EAAE,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IAElC;;OAEG;IACH,iBAAiB,IAAI,IAAI,CAAC;IAE1B;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;IAIhB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACpE,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACxD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACvC,WAAW,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3C,wBAAwB,IAAI,MAAM,CAAC;IACnC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,UAAU,IAAI,OAAO,CAAC;IACtB,UAAU,IAAI,IAAI,CAAC;IACnB,SAAS,IAAI,IAAI,CAAC;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACtC,WAAW,IAAI,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAChD,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7E,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC1C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC1E,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzF,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,mBAAmB,IAAI,MAAM,EAAE,CAAC;IAChC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,CAAC;IACb,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IAChC,WAAW,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,IAAI,MAAM,CAAC;IACf,QAAQ,IAAI,gBAAgB,CAAC;IAC7B,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;IACf,MAAM,IAAI,OAAO,CAAC;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACnE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;IAC1D,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,qBAAqB,GACvC,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACtC,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/src/reactive/object-pool.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ObjectPool - Object pooling for virtual rendering
+ *
+ * @description
+ * Reuses objects instead of creating/destroying (10x faster scroll).
+ * Uses PoolStatsTracker for monitoring.
+ *
+ * @performance
+ * - Traditional: User scrolls → destroy 50 cells → create 50 new (10-15ms)
+ * - Pooling: User scrolls → release 50 → acquire 50 from pool (1-2ms)
+ *
+ * @example
+ * ```typescript
+ * const cellPool = new ObjectPool({
+ *   factory: () => document.createElement('div'),
+ *   reset: (div) => div.innerHTML = '',
+ *   initialSize: 50,
+ * });
+ *
+ * const cell = cellPool.acquire();
+ * cell.textContent = 'Cell content';
+ * document.body.appendChild(cell);
+ *
+ * // Later: release back to pool
+ * document.body.removeChild(cell);
+ * cellPool.release(cell);
+ * ```
+ */
+import { type ObjectPoolStats } from './core/pool-stats';
+export type { ObjectPoolStats };
+export interface ObjectPoolOptions<T> {
+    factory: () => T;
+    reset?: (obj: T) => void;
+    validate?: (obj: T) => boolean;
+    initialSize?: number;
+    maxSize?: number;
+}
+export declare class ObjectPool<T> {
+    private pool;
+    private factory;
+    private reset?;
+    private validate?;
+    private maxSize;
+    private stats;
+    constructor(options: ObjectPoolOptions<T>);
+    /**
+     * Acquire object from pool (reuse or create)
+     *
+     * @performance O(1) - pop from array
+     */
+    acquire(): T;
+    /**
+     * Release object back to pool
+     *
+     * @performance O(1) - push to array + O(reset)
+     */
+    release(obj: T): void;
+    /**
+     * Create new object
+     *
+     * @private
+     */
+    private createNew;
+    /**
+     * Acquire multiple objects from pool
+     */
+    acquireMany(count: number): T[];
+    /**
+     * Release multiple objects back to pool
+     */
+    releaseMany(objects: T[]): void;
+    /**
+     * Prewarm pool with objects
+     */
+    prewarm(count: number): void;
+    /**
+     * Get current pool size
+     */
+    size(): number;
+    /**
+     * Get pool statistics
+     */
+    getStats(): ObjectPoolStats;
+    /**
+     * Shrink pool to target size
+     */
+    shrink(targetSize: number): void;
+    /**
+     * Clear pool
+     */
+    clear(): void;
+    /**
+     * Destroy pool
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=object-pool.d.ts.map

package/dist/src/reactive/object-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-pool.d.ts","sourceRoot":"","sources":["../../../src/reactive/object-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG3E,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAsB;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAWzC;;;;OAIG;IACH,OAAO,IAAI,CAAC;IAqBZ;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAqBrB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAUjB;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE;IAQ/B;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI;IAI/B;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAU5B;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,QAAQ,IAAI,eAAe;IAI3B;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMhC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,IAAI,IAAI;CAIhB"}

package/dist/src/reactive/reactive-state.d.ts

@@ -0,0 +1,132 @@
+/**
+ * ReactiveState - Generic reactive state container
+ *
+ * @description
+ * Observable state with targeted subscriptions (O(m) vs O(n)).
+ * Supports dependency injection for testing and customization.
+ *
+ * @example
+ * ```typescript
+ * // Inheritance (backward compatible)
+ * class ColumnModel extends ReactiveState<ColumnState, ColumnEvent> {
+ *   setWidth(id: string, width: number): void {
+ *     this.setState(id, { ...state, width }, event);
+ *   }
+ * }
+ *
+ * // Composition with DI (new, flexible)
+ * class ColumnModel {
+ *   constructor(private state: IReactiveState<ColumnState, ColumnEvent>) {}
+ * }
+ *
+ * // Can inject custom implementation
+ * const model = new ColumnModel(new ReactiveState());
+ * const testModel = new ColumnModel(mockState);
+ * ```
+ *
+ * @template T - State value type
+ * @template E - Event type
+ */
+import type { IReactiveState, ISubscriber, ISubscriptionManager, IBatchManager } from './interfaces';
+export declare class ReactiveState<T, E> implements IReactiveState<T, E> {
+    private state;
+    private subscriptions;
+    private batching;
+    private eventHistory?;
+    /**
+     * Create ReactiveState with optional dependency injection
+     *
+     * @param subscriptions - Custom subscription manager (default: SubscriptionManager)
+     * @param batching - Custom batch manager (default: BatchManager)
+     * @param historySize - Event history size for debugging (default: 0, disabled)
+     */
+    constructor(subscriptions?: ISubscriptionManager<E>, batching?: IBatchManager<E>, historySize?: number);
+    /**
+     * Subscribe to specific key changes (targeted O(m))
+     */
+    subscribeToKey(key: string, subscriber: ISubscriber<E>): () => void;
+    /**
+     * Subscribe to all state changes (global observer)
+     */
+    subscribeGlobal(subscriber: ISubscriber<E>): () => void;
+    /**
+     * Update state and notify subscribers
+     *
+     * @protected - For subclass use
+     */
+    protected setState(key: string, value: T, event: E): void;
+    /**
+     * Batch multiple updates (single notification)
+     *
+     * @example
+     * ```typescript
+     * columnModel.batch(() => {
+     *   columnModel.setWidth('col-0', 150);
+     *   columnModel.setWidth('col-1', 200);
+     *   columnModel.setWidth('col-2', 180);
+     * });
+     * ```
+     */
+    protected batch(updates: () => void): void;
+    /**
+     * Flush batched events
+     *
+     * @private
+     */
+    private flushBatch;
+    /**
+     * Get state for key
+     */
+    protected getState(key: string): T | undefined;
+    /**
+     * Get all state
+     */
+    protected getAllState(): Map<string, T>;
+    /**
+     * Check if key has state
+     */
+    protected hasState(key: string): boolean;
+    /**
+     * Delete state for key and optionally notify
+     */
+    protected deleteState(key: string, event?: E): void;
+    /**
+     * Get all state keys
+     */
+    protected getKeys(): string[];
+    /**
+     * Get subscriber count for key
+     */
+    getSubscriberCount(key: string): number;
+    /**
+     * Get global subscriber count
+     */
+    getGlobalSubscriberCount(): number;
+    /**
+     * Get event history (if enabled)
+     * Returns [oldest, ..., newest]
+     */
+    getEventHistory(): E[];
+    /**
+     * Get last N events from history
+     */
+    getLastEvents(count: number): E[];
+    /**
+     * Clear event history
+     */
+    clearEventHistory(): void;
+    /**
+     * Clear all state and subscribers
+     */
+    destroy(): void;
+}
+/**
+ * Subscriber interface (backward compatible)
+ * @deprecated Use ISubscriber from interfaces.ts
+ */
+export interface StateSubscriber<E> {
+    onChange(event: E): void;
+    onBatchChange?(events: E[]): void;
+}
+export type { ISubscriber, IReactiveState } from './interfaces';
+//# sourceMappingURL=reactive-state.d.ts.map

package/dist/src/reactive/reactive-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-state.d.ts","sourceRoot":"","sources":["../../../src/reactive/reactive-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,oBAAoB,EACpB,aAAa,EACd,MAAM,cAAc,CAAC;AAKtB,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9D,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,YAAY,CAAC,CAAgB;IAErC;;;;;;OAMG;gBAED,aAAa,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACvC,QAAQ,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAC3B,WAAW,GAAE,MAAU;IAUzB;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAInE;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIvD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAezD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAiB1C;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI9C;;OAEG;IACH,SAAS,CAAC,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAIvC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxC;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI;IASnD;;OAEG;IACH,SAAS,CAAC,OAAO,IAAI,MAAM,EAAE;IAI7B;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIvC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAIlC;;;OAGG;IACH,eAAe,IAAI,CAAC,EAAE;IAItB;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE;IAKjC;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;CACnC;AAGD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,56 @@
+/**
+ * Common types used across ZenGrid algorithms and data structures
+ */
+/**
+ * Comparator function for sorting and ordering
+ * @returns Negative if a < b, zero if a === b, positive if a > b
+ */
+export type Comparator<T> = (a: T, b: T) => number;
+/**
+ * Predicate function for filtering
+ * @returns true if the value matches the condition
+ */
+export type Predicate<T> = (value: T) => boolean;
+/**
+ * Equality function for comparing values
+ * @returns true if values are equal
+ */
+export type EqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Hash function for creating keys from values
+ * @returns string representation of the value
+ */
+export type HashFn<T> = (value: T) => string;
+/**
+ * Generic range interface
+ */
+export interface Range {
+    start: number;
+    end: number;
+}
+/**
+ * 2D rectangle interface
+ */
+export interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 2D point interface
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Bounding box interface
+ */
+export interface BoundingBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+//# sourceMappingURL=common.d.ts.map

package/dist/src/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd"}

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

@@ -0,0 +1,5 @@
+/**
+ * Shared types for ZenGrid
+ */
+export type { Comparator, Predicate, EqualityFn, HashFn, Range, Rectangle, Point, BoundingBox, } from './common';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,EACL,WAAW,GACZ,MAAM,UAAU,CAAC"}

package/dist/src/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Utility functions
+ * @module @zengrid/shared/utils
+ */
+export * from './timing';
+export * from './timing.interface';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

package/dist/src/utils/timing.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Timing utilities for performance optimization
+ * @module @zengrid/shared/utils/timing
+ */
+import type { DebounceOptions, DebouncedFunction, ThrottleOptions, ThrottledFunction, RAFBatchScheduler } from './timing.interface';
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked.
+ *
+ * @param func - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @param options - Options object
+ * @returns Debounced function with cancel and flush methods
+ *
+ * @example
+ * ```typescript
+ * const handleResize = debounce(() => {
+ *   console.log('Window resized');
+ * }, 250);
+ *
+ * window.addEventListener('resize', handleResize);
+ *
+ * // Cancel pending invocations
+ * handleResize.cancel();
+ *
+ * // Immediately invoke
+ * handleResize.flush();
+ * ```
+ */
+export declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number, options?: DebounceOptions): DebouncedFunction<T>;
+/**
+ * Creates a throttled function that only invokes func at most once per every wait milliseconds.
+ *
+ * @param func - The function to throttle
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @param options - Options object
+ * @returns Throttled function with cancel method
+ *
+ * @example
+ * ```typescript
+ * const handleScroll = throttle(() => {
+ *   console.log('Scrolling');
+ * }, 100);
+ *
+ * window.addEventListener('scroll', handleScroll);
+ *
+ * // Cancel pending invocation
+ * handleScroll.cancel();
+ * ```
+ */
+export declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number, options?: ThrottleOptions): ThrottledFunction<T>;
+/**
+ * Creates a RAF (RequestAnimationFrame) batch scheduler that coalesces multiple
+ * updates into a single animation frame.
+ *
+ * Useful for optimizing frequent DOM updates by batching them together.
+ *
+ * @returns RAF batch scheduler
+ *
+ * @example
+ * ```typescript
+ * const scheduler = createRAFBatchScheduler();
+ *
+ * // Multiple calls in same frame will be batched
+ * scheduler.schedule(() => console.log('Update 1'));
+ * scheduler.schedule(() => console.log('Update 2'));
+ * scheduler.schedule(() => console.log('Update 3'));
+ * // All three will run in the same animation frame
+ *
+ * // Cancel all pending
+ * scheduler.cancelAll();
+ * ```
+ */
+export declare function createRAFBatchScheduler(): RAFBatchScheduler;
+/**
+ * Delays execution for specified milliseconds. Returns a promise.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after delay
+ *
+ * @example
+ * ```typescript
+ * await delay(1000); // Wait 1 second
+ * console.log('1 second later');
+ * ```
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Creates a timeout promise that rejects after specified milliseconds
+ *
+ * @param ms - Milliseconds before timeout
+ * @param message - Error message
+ * @returns Promise that rejects after timeout
+ *
+ * @example
+ * ```typescript
+ * const result = await Promise.race([
+ *   fetchData(),
+ *   timeout(5000, 'Request timeout')
+ * ]);
+ * ```
+ */
+export declare function timeout(ms: number, message?: string): Promise<never>;
+//# sourceMappingURL=timing.d.ts.map

package/dist/src/utils/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../../src/utils/timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAAC,CAAC,CAAC,CA0HtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAAC,CAAC,CAAC,CAQtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAoD3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,OAAO,CAAC,KAAK,CAAC,CAIvE"}