@nice2dev/ui-core 1.0.10

package/dist/core/datasource-advanced.d.ts

@@ -0,0 +1,261 @@
+/**
+ * NiceDataSource — Advanced Features
+ * Sprint 5: Server-Side Processing, Caching, Real-Time, Offline
+ */
+import type { NiceDataSource, NiceLoadOptions } from './datasource';
+export interface NiceCacheConfig {
+    /** Time-to-live in milliseconds (default 60000 = 1 min) */
+    ttl?: number;
+    /** Maximum cache entries (default 100) */
+    maxSize?: number;
+    /** Whether to cache load results (default true) */
+    cacheLoads?: boolean;
+    /** Whether to cache byKey results (default true) */
+    cacheByKey?: boolean;
+    /** Custom cache key generator */
+    generateKey?: (options: NiceLoadOptions) => string;
+}
+/**
+ * Creates an LRU cache with TTL support.
+ */
+export declare class NiceDataCache<T = unknown> {
+    private cache;
+    private readonly ttl;
+    private readonly maxSize;
+    constructor(config?: NiceCacheConfig);
+    get(key: string): T | undefined;
+    set(key: string, data: T, ttl?: number): void;
+    has(key: string): boolean;
+    invalidate(key: string): void;
+    invalidateAll(): void;
+    invalidateMatching(pattern: RegExp): void;
+}
+/**
+ * Request deduplication — prevents duplicate concurrent requests.
+ */
+export declare class NiceRequestDeduplicator {
+    private pending;
+    dedupe<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    hasPending(key: string): boolean;
+    cancelAll(): void;
+}
+/**
+ * Wraps a data source with caching and request deduplication.
+ */
+export declare function withCaching<T>(source: NiceDataSource<T>, config?: NiceCacheConfig): NiceDataSource<T> & {
+    cache: NiceDataCache;
+    invalidateCache(): void;
+};
+export interface NiceCursorPaginationConfig<T> {
+    /** Field to use for cursor (usually primary key or timestamp) */
+    cursorField: string;
+    /** Page size */
+    pageSize?: number;
+    /** Sort direction for cursor (default 'asc') */
+    direction?: 'asc' | 'desc';
+}
+export interface NiceCursorPage<T> {
+    data: T[];
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasMore: boolean;
+}
+export interface NiceCursorLoadOptions extends Omit<NiceLoadOptions, 'skip' | 'take'> {
+    cursor?: string;
+    pageSize?: number;
+    direction?: 'forward' | 'backward';
+}
+/**
+ * Creates a cursor-based paginated wrapper around a data source.
+ */
+export declare function withCursorPagination<T extends Record<string, any>>(source: NiceDataSource<T>, config: NiceCursorPaginationConfig<T>): {
+    loadPage(options?: NiceCursorLoadOptions): Promise<NiceCursorPage<T>>;
+    loadAll(options?: Omit<NiceCursorLoadOptions, 'cursor'>): AsyncGenerator<T[], void, unknown>;
+};
+export interface NiceInfiniteScrollState<T> {
+    items: T[];
+    isLoading: boolean;
+    hasMore: boolean;
+    error: Error | null;
+    page: number;
+    totalCount: number;
+}
+export interface NiceInfiniteScrollConfig {
+    /** Items per page (default 50) */
+    pageSize?: number;
+    /** Threshold in pixels to trigger load (default 200) */
+    threshold?: number;
+    /** Initial page (default 0) */
+    initialPage?: number;
+}
+/**
+ * Creates an infinite scroll controller for a data source.
+ */
+export declare function createInfiniteScroll<T>(source: NiceDataSource<T>, config?: NiceInfiniteScrollConfig): {
+    readonly state: NiceInfiniteScrollState<T>;
+    loadMore: () => Promise<void>;
+    reset: (options?: NiceLoadOptions) => void;
+    handleScroll: (event: Event) => void;
+    subscribe(listener: (state: NiceInfiniteScrollState<T>) => void): () => boolean;
+    setOptions(options: NiceLoadOptions): void;
+};
+export type NiceWebSocketMessageType = 'insert' | 'update' | 'remove' | 'refresh' | 'sync';
+export interface NiceWebSocketMessage<T = unknown> {
+    type: NiceWebSocketMessageType;
+    key?: unknown;
+    data?: T;
+    changes?: Partial<T>;
+}
+export interface NiceWebSocketConfig<T> {
+    /** WebSocket URL */
+    url: string;
+    /** Base data source for initial load and writes */
+    baseSource: NiceDataSource<T>;
+    /** Key field name */
+    keyField?: string;
+    /** Parse incoming message */
+    parseMessage?: (event: MessageEvent) => NiceWebSocketMessage<T> | null;
+    /** Serialize outgoing message */
+    serializeMessage?: (msg: NiceWebSocketMessage<T>) => string;
+    /** Reconnect delay in ms (default 3000) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts (default 10) */
+    maxReconnects?: number;
+    /** Heartbeat interval in ms (default 30000) */
+    heartbeatInterval?: number;
+}
+export interface NiceWebSocketDataSource<T> extends NiceDataSource<T> {
+    connect(): void;
+    disconnect(): void;
+    isConnected(): boolean;
+    sendMessage(msg: NiceWebSocketMessage<T>): void;
+}
+/**
+ * Creates a real-time data source using WebSocket.
+ * Syncs changes from server and broadcasts local writes.
+ */
+export declare function createWebSocketDataSource<T extends Record<string, any>>(config: NiceWebSocketConfig<T>): NiceWebSocketDataSource<T>;
+export interface NiceSignalRConfig<T> {
+    /** SignalR hub connection (from @microsoft/signalr) */
+    connection: {
+        on(methodName: string, callback: (...args: any[]) => void): void;
+        off(methodName: string, callback: (...args: any[]) => void): void;
+        invoke(methodName: string, ...args: any[]): Promise<any>;
+        start(): Promise<void>;
+        stop(): Promise<void>;
+        state: string | number;
+    };
+    /** Base data source for initial load and writes */
+    baseSource: NiceDataSource<T>;
+    /** Hub method names */
+    methods?: {
+        onInsert?: string;
+        onUpdate?: string;
+        onRemove?: string;
+        onRefresh?: string;
+        insert?: string;
+        update?: string;
+        remove?: string;
+    };
+}
+/**
+ * Creates a real-time data source using SignalR.
+ */
+export declare function createSignalRDataSource<T extends Record<string, any>>(config: NiceSignalRConfig<T>): NiceDataSource<T> & {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+};
+export interface NiceOptimisticConfig<T> {
+    /** Called when optimistic update is applied */
+    onOptimisticApply?: (item: T, action: 'insert' | 'update' | 'remove') => void;
+    /** Called when update is confirmed */
+    onConfirm?: (item: T, action: 'insert' | 'update' | 'remove') => void;
+    /** Called when update fails and is rolled back */
+    onRollback?: (item: T, action: 'insert' | 'update' | 'remove', error: Error) => void;
+    /** Delay before applying optimistic update (default 0) */
+    delay?: number;
+}
+/**
+ * Wraps a data source with optimistic update support.
+ * Changes are applied immediately, then confirmed or rolled back.
+ */
+export declare function withOptimisticUpdates<T extends Record<string, any>>(source: NiceDataSource<T>, config?: NiceOptimisticConfig<T>): NiceDataSource<T> & {
+    hasPendingChanges(): boolean;
+    getPendingCount(): number;
+};
+export interface NiceDataDiff<T> {
+    inserted: T[];
+    updated: Array<{
+        key: unknown;
+        changes: Partial<T>;
+        oldItem: T;
+        newItem: T;
+    }>;
+    removed: T[];
+    unchanged: T[];
+}
+/**
+ * Calculates the difference between two data arrays.
+ */
+export declare function calculateDataDiff<T extends Record<string, any>>(oldData: T[], newData: T[], keyField: string): NiceDataDiff<T>;
+export interface NicePollingConfig {
+    /** Polling interval in ms (default 5000) */
+    interval?: number;
+    /** Whether to start polling immediately (default false) */
+    autoStart?: boolean;
+    /** Pause polling when tab is hidden (default true) */
+    pauseWhenHidden?: boolean;
+    /** Callback when data changes */
+    onDataChange?: <T>(diff: NiceDataDiff<T>) => void;
+}
+/**
+ * Wraps a data source with automatic polling for updates.
+ */
+export declare function withPolling<T extends Record<string, any>>(source: NiceDataSource<T>, config?: NicePollingConfig): NiceDataSource<T> & {
+    startPolling(): void;
+    stopPolling(): void;
+    isPolling(): boolean;
+    setInterval(ms: number): void;
+};
+export type NiceSSEMessageType = 'insert' | 'update' | 'remove' | 'refresh' | 'snapshot';
+export interface NiceSSEMessage<T = unknown> {
+    type: NiceSSEMessageType;
+    key?: unknown;
+    data?: T;
+    changes?: Partial<T>;
+}
+export interface NiceSSEConfig<T> {
+    /** SSE endpoint URL. */
+    url: string;
+    /** Base data source for initial load (SSE is read-only for pushes). */
+    baseSource: NiceDataSource<T>;
+    /** Key field name. */
+    keyField?: string;
+    /** Parse incoming SSE event into a message. Defaults to JSON.parse(event.data). */
+    parseEvent?: (event: MessageEvent) => NiceSSEMessage<T> | null;
+    /** Custom headers (requires polyfill like eventsource-polyfill for non-standard headers). */
+    headers?: Record<string, string>;
+    /** Reconnect delay in ms (EventSource handles this natively; used for manual fallback). @default 3000 */
+    reconnectDelay?: number;
+    /** Max reconnect attempts before giving up. @default 10 */
+    maxReconnects?: number;
+    /** Whether to include credentials (cookies). @default false */
+    withCredentials?: boolean;
+}
+export interface NiceSSEDataSource<T> extends NiceDataSource<T> {
+    /** Start listening to SSE events. */
+    connect(): void;
+    /** Close the SSE connection. */
+    disconnect(): void;
+    /** Whether the EventSource is currently connected. */
+    isConnected(): boolean;
+}
+/**
+ * Creates a read-only real-time data source using Server-Sent Events (SSE).
+ * Lighter alternative to WebSocket — ideal for server→client unidirectional streaming.
+ *
+ * The SSE endpoint should send JSON messages with { type, key?, data?, changes? }.
+ * Writes (insert/update/remove) are delegated to the base data source.
+ */
+export declare function createSSEDataSource<T extends Record<string, any>>(config: NiceSSEConfig<T>): NiceSSEDataSource<T>;
+//# sourceMappingURL=datasource-advanced.d.ts.map

package/dist/core/datasource-advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource-advanced.d.ts","sourceRoot":"","sources":["../../src/core/datasource-advanced.ts"],"names":[],"mappings":"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"}

package/dist/core/datasource-aggregation.d.ts

@@ -0,0 +1,221 @@
+/**
+ * NiceDataAggregation — Data transformation utilities
+ * Sprint 5.4: Aggregation, Pivot, Calculated Columns
+ */
+export type AggregateFunction = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'first' | 'last' | 'distinct';
+export interface AggregateSpec {
+    field: string;
+    fn: AggregateFunction;
+    alias?: string;
+}
+/**
+ * Applies aggregate functions to a dataset.
+ */
+export declare function aggregate<T extends Record<string, any>>(data: T[], specs: AggregateSpec[]): Record<string, unknown>;
+export interface GroupByOptions<T> {
+    /** Fields to group by */
+    groupBy: string[];
+    /** Aggregate functions to apply */
+    aggregates?: AggregateSpec[];
+    /** Whether to include items in each group */
+    includeItems?: boolean;
+    /** Sort groups by field and direction */
+    sortGroups?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+}
+export interface GroupedResult<T> {
+    /** Group key values */
+    key: Record<string, unknown>;
+    /** Number of items in group */
+    count: number;
+    /** Aggregate results */
+    aggregates: Record<string, unknown>;
+    /** Items in group (if includeItems is true) */
+    items?: T[];
+    /** Nested groups (for multi-level grouping) */
+    groups?: GroupedResult<T>[];
+}
+/**
+ * Groups data by specified fields with optional aggregation.
+ */
+export declare function groupBy<T extends Record<string, any>>(data: T[], options: GroupByOptions<T>): GroupedResult<T>[];
+/**
+ * Creates hierarchical groups (groups within groups).
+ */
+export declare function groupByHierarchical<T extends Record<string, any>>(data: T[], groupFields: string[], aggregates?: AggregateSpec[]): GroupedResult<T>[];
+export interface PivotConfig {
+    /** Row fields */
+    rows: string[];
+    /** Column field (will become column headers) */
+    columns: string;
+    /** Value field to aggregate */
+    values: string;
+    /** Aggregate function (default 'sum') */
+    aggregateFunction?: AggregateFunction;
+    /** Include row totals */
+    rowTotals?: boolean;
+    /** Include column totals */
+    columnTotals?: boolean;
+    /** Include grand total */
+    grandTotal?: boolean;
+}
+export interface PivotResult {
+    /** Column headers (unique values from column field) */
+    columnHeaders: string[];
+    /** Row data with pivot values */
+    rows: Array<{
+        rowKey: Record<string, unknown>;
+        values: Record<string, number | null>;
+        rowTotal?: number;
+    }>;
+    /** Column totals */
+    columnTotals?: Record<string, number>;
+    /** Grand total */
+    grandTotal?: number;
+}
+/**
+ * Transforms data into a pivot table format.
+ */
+export declare function pivot<T extends Record<string, any>>(data: T[], config: PivotConfig): PivotResult;
+export interface CalculatedColumn<T> {
+    /** Name for the new column */
+    name: string;
+    /** Formula function */
+    formula: (item: T, index: number, allItems: T[]) => unknown;
+}
+/**
+ * Adds calculated columns to data.
+ */
+export declare function withCalculatedColumns<T extends Record<string, any>>(data: T[], columns: CalculatedColumn<T>[]): Array<T & Record<string, unknown>>;
+/**
+ * Pre-built formula helpers for common calculations.
+ */
+export declare const ColumnFormulas: {
+    /** Running sum of a field */
+    runningSum: <T>(field: keyof T) => (item: T, index: number, all: T[]) => number;
+    /** Running average of a field */
+    runningAvg: <T>(field: keyof T) => (item: T, index: number, all: T[]) => number;
+    /** Percentage of total */
+    percentOfTotal: <T>(field: keyof T) => (item: T, _: number, all: T[]) => number;
+    /** Rank by field value */
+    rank: <T>(field: keyof T, direction?: "asc" | "desc") => (item: T, _: number, all: T[]) => number;
+    /** Difference from previous row */
+    diffFromPrevious: <T>(field: keyof T) => (item: T, index: number, all: T[]) => number | null;
+    /** Percentage change from previous row */
+    percentChange: <T>(field: keyof T) => (item: T, index: number, all: T[]) => number | null;
+    /** Moving average */
+    movingAverage: <T>(field: keyof T, window: number) => (item: T, index: number, all: T[]) => number;
+    /** Conditional value */
+    conditional: <T, R>(condition: (item: T) => boolean, trueValue: R, falseValue: R) => (item: T) => R;
+    /** Concatenate fields */
+    concat: <T>(...fields: (keyof T)[]) => (item: T) => string;
+    /** Parse date and format */
+    formatDate: <T>(field: keyof T, format?: "short" | "medium" | "long") => (item: T) => string;
+};
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+export interface ValidationRule<T> {
+    /** Rule name */
+    name: string;
+    /** Validation function */
+    validate: (item: T, index: number, all: T[]) => boolean;
+    /** Error message */
+    message: string | ((item: T) => string);
+    /** Severity level */
+    severity?: ValidationSeverity;
+    /** Fields this rule applies to */
+    fields?: string[];
+}
+export interface ValidationError {
+    /** Item index */
+    index: number;
+    /** Rule name */
+    rule: string;
+    /** Error message */
+    message: string;
+    /** Severity */
+    severity: ValidationSeverity;
+    /** Affected fields */
+    fields: string[];
+    /** The invalid item */
+    item: unknown;
+}
+export interface ValidationResult {
+    /** Whether all items are valid */
+    isValid: boolean;
+    /** Total error count */
+    errorCount: number;
+    /** Total warning count */
+    warningCount: number;
+    /** All validation errors */
+    errors: ValidationError[];
+    /** Errors grouped by index */
+    byIndex: Map<number, ValidationError[]>;
+    /** Errors grouped by field */
+    byField: Map<string, ValidationError[]>;
+}
+/**
+ * Validates data against a set of rules.
+ */
+export declare function validateData<T>(data: T[], rules: ValidationRule<T>[]): ValidationResult;
+/**
+ * Pre-built validation rules.
+ */
+export declare const ValidationRules: {
+    required: <T>(field: keyof T) => ValidationRule<T>;
+    minLength: <T>(field: keyof T, min: number) => ValidationRule<T>;
+    maxLength: <T>(field: keyof T, max: number) => ValidationRule<T>;
+    min: <T>(field: keyof T, min: number) => ValidationRule<T>;
+    max: <T>(field: keyof T, max: number) => ValidationRule<T>;
+    email: <T>(field: keyof T) => ValidationRule<T>;
+    pattern: <T>(field: keyof T, regex: RegExp, message?: string) => ValidationRule<T>;
+    unique: <T>(field: keyof T) => ValidationRule<T>;
+    custom: <T>(name: string, validate: (item: T) => boolean, message: string, fields?: string[]) => ValidationRule<T>;
+};
+export interface BatchOperationResult<T> {
+    succeeded: number;
+    failed: number;
+    errors: Array<{
+        index: number;
+        item: T;
+        error: Error;
+    }>;
+}
+/**
+ * Performs batch operations on data.
+ */
+export declare const BatchOperations: {
+    /**
+     * Updates multiple items matching a condition.
+     */
+    updateWhere<T extends Record<string, any>>(items: T[], condition: (item: T) => boolean, changes: Partial<T> | ((item: T) => Partial<T>)): Promise<T[]>;
+    /**
+     * Removes items matching a condition.
+     */
+    removeWhere<T>(items: T[], condition: (item: T) => boolean): Promise<{
+        remaining: T[];
+        removed: T[];
+    }>;
+    /**
+     * Applies a transformation to all items.
+     */
+    transform<T, R>(items: T[], transformer: (item: T, index: number) => R | Promise<R>, options?: {
+        parallel?: boolean;
+        batchSize?: number;
+    }): Promise<BatchOperationResult<T> & {
+        results: R[];
+    }>;
+    /**
+     * Deduplicates items by a key field.
+     */
+    deduplicate<T>(items: T[], keyField: keyof T): T[];
+    /**
+     * Merges two arrays, updating existing items and adding new ones.
+     */
+    merge<T extends Record<string, any>>(existing: T[], incoming: T[], keyField: keyof T, options?: {
+        updateExisting?: boolean;
+        addNew?: boolean;
+    }): T[];
+};
+//# sourceMappingURL=datasource-aggregation.d.ts.map

package/dist/core/datasource-aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource-aggregation.d.ts","sourceRoot":"","sources":["../../src/core/datasource-aggregation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,OAAO,GACP,OAAO,GACP,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,iBAAiB,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,aAAa,EAAE,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsCzB;AAMD,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,yBAAyB;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mCAAmC;IACnC,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,+CAA+C;IAC/C,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnD,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,aAAa,CAAC,CAAC,CAAC,EAAE,CA4DpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/D,IAAI,EAAE,CAAC,EAAE,EACT,WAAW,EAAE,MAAM,EAAE,EACrB,UAAU,GAAE,aAAa,EAAO,GAC/B,aAAa,CAAC,CAAC,CAAC,EAAE,CAuBpB;AAMD,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,yBAAyB;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iCAAiC;IACjC,IAAI,EAAE,KAAK,CAAC;QACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;QACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAkEhG;AAMD,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC;CAC7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjE,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,GAC7B,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQpC;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,6BAA6B;iBAE1B,CAAC,SAAS,MAAM,CAAC,YACX,CAAC,SAAS,MAAM,OAAO,CAAC,EAAE;IAGnC,iCAAiC;iBAE9B,CAAC,SAAS,MAAM,CAAC,YACX,CAAC,SAAS,MAAM,OAAO,CAAC,EAAE;IAKnC,0BAA0B;qBAEvB,CAAC,SAAS,MAAM,CAAC,YACX,CAAC,KAAK,MAAM,OAAO,CAAC,EAAE;IAK/B,0BAA0B;WAEvB,CAAC,SAAS,MAAM,CAAC,cAAa,KAAK,GAAG,MAAM,YACtC,CAAC,KAAK,MAAM,OAAO,CAAC,EAAE;IAQ/B,mCAAmC;uBAEhC,CAAC,SAAS,MAAM,CAAC,YACX,CAAC,SAAS,MAAM,OAAO,CAAC,EAAE;IAOnC,0CAA0C;oBAEvC,CAAC,SAAS,MAAM,CAAC,YACX,CAAC,SAAS,MAAM,OAAO,CAAC,EAAE;IAWnC,qBAAqB;oBAElB,CAAC,SAAS,MAAM,CAAC,UAAU,MAAM,YAC3B,CAAC,SAAS,MAAM,OAAO,CAAC,EAAE;IAMnC,wBAAwB;kBAErB,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,aAAa,CAAC,cAAc,CAAC,YAC5D,CAAC;IAGV,yBAAyB;aAEtB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,YACnB,CAAC;IAGV,4BAA4B;iBAEzB,CAAC,SAAS,MAAM,CAAC,WAAU,OAAO,GAAG,QAAQ,GAAG,MAAM,YAChD,CAAC;CAUX,CAAC;AAMF,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC;IACxD,oBAAoB;IACpB,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IACxC,qBAAqB;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sBAAsB;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,uBAAuB;IACvB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IACxC,8BAA8B;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,gBAAgB,CAkDvF;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;eACf,CAAC,SAAS,MAAM,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC;gBAOpC,CAAC,SAAS,MAAM,CAAC,OAAO,MAAM,KAAG,cAAc,CAAC,CAAC,CAAC;gBAOlD,CAAC,SAAS,MAAM,CAAC,OAAO,MAAM,KAAG,cAAc,CAAC,CAAC,CAAC;UAOxD,CAAC,SAAS,MAAM,CAAC,OAAO,MAAM,KAAG,cAAc,CAAC,CAAC,CAAC;UAOlD,CAAC,SAAS,MAAM,CAAC,OAAO,MAAM,KAAG,cAAc,CAAC,CAAC,CAAC;YAOhD,CAAC,SAAS,MAAM,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC;cAOnC,CAAC,SAAS,MAAM,CAAC,SAAS,MAAM,YAAY,MAAM,KAAG,cAAc,CAAC,CAAC,CAAC;aAOvE,CAAC,SAAS,MAAM,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC;aAUrC,CAAC,QACF,MAAM,YACF,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,WACrB,MAAM,WACN,MAAM,EAAE,KAChB,cAAc,CAAC,CAAC,CAAC;CAMrB,CAAC;AAMF,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B;;OAEG;gBACe,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,SACtC,CAAC,EAAE,aACC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,WACtB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,EAAE,CAAC;IAUf;;OAEG;gBACe,CAAC,SACV,CAAC,EAAE,aACC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAC9B,OAAO,CAAC;QAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC;IAe5C;;OAEG;cACa,CAAC,EAAE,CAAC,SACX,CAAC,EAAE,eACG,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,YAC9C;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC;IAqDtD;;OAEG;gBACS,CAAC,SAAS,CAAC,EAAE,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE;IAYlD;;OAEG;UACG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YACvB,CAAC,EAAE,YACH,CAAC,EAAE,YACH,MAAM,CAAC,YACR;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACtD,CAAC,EAAE;CAqBP,CAAC"}

package/dist/core/datasource-hooks.d.ts

@@ -0,0 +1,93 @@
+/**
+ * React hooks for NiceDataSource binding.
+ *
+ * useNiceDataSource  — list/grid binding (sort, page, filter, search, CRUD)
+ * useNiceRecord      — single-record binding (edit form, detail view)
+ * useNiceField       — single-field two-way binding (input, label, etc.)
+ * useNiceLookupSource — options binding for Select/Autocomplete/TagBox
+ */
+import type { NiceFilterGroup, NiceDataSource, NiceLoadOptions, NiceSortExpression, NiceSortDirection } from './datasource';
+import type { NiceOption } from './types';
+export interface UseNiceDataSourceOptions {
+    /** Auto-load on mount & when query changes. Default: true. */
+    autoLoad?: boolean;
+    defaultPageSize?: number;
+    defaultSort?: NiceSortExpression[];
+    defaultFilter?: NiceFilterGroup;
+    defaultSearch?: string;
+    /** Additional load options merged into every request. */
+    loadOptions?: Partial<NiceLoadOptions>;
+}
+export interface NiceDataSourceState<T> {
+    data: T[];
+    totalCount: number;
+    loading: boolean;
+    error: string | null;
+    page: number;
+    pageSize: number;
+    sort: NiceSortExpression[];
+    filter: NiceFilterGroup | undefined;
+    search: string;
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+    setSort: (sort: NiceSortExpression[]) => void;
+    setSortField: (field: string, direction: NiceSortDirection) => void;
+    setFilter: (filter: NiceFilterGroup | undefined) => void;
+    setSearch: (search: string) => void;
+    reload: () => void;
+    insert: (item: Partial<T>) => Promise<void>;
+    update: (key: unknown, changes: Partial<T>) => Promise<void>;
+    remove: (key: unknown) => Promise<void>;
+}
+export declare function useNiceDataSource<T = any>(source: NiceDataSource<T> | null | undefined, options?: UseNiceDataSourceOptions): NiceDataSourceState<T>;
+export interface NiceRecordState<T> {
+    /** Original loaded data. */
+    data: T | undefined;
+    /** Data with local changes applied. */
+    editData: Record<string, unknown>;
+    loading: boolean;
+    error: string | null;
+    /** Pending local changes not yet saved. */
+    changes: Partial<T>;
+    isDirty: boolean;
+    /** Set a single field value locally (does NOT save). */
+    set: (field: string, value: unknown) => void;
+    /** Set multiple fields locally. */
+    setMany: (changes: Partial<T>) => void;
+    /** Persist local changes to the data source. */
+    save: () => Promise<void>;
+    /** Reload from server, discarding local changes. */
+    reload: () => void;
+    /** Discard local changes without reloading. */
+    reset: () => void;
+}
+export declare function useNiceRecord<T = any>(source: NiceDataSource<T> | null | undefined, key: unknown): NiceRecordState<T>;
+export interface NiceFieldState {
+    value: unknown;
+    setValue: (v: unknown) => void;
+    loading: boolean;
+    error: string | null;
+    isDirty: boolean;
+    /** Save just this field. */
+    save: () => Promise<void>;
+}
+export declare function useNiceField<T = any>(source: NiceDataSource<T> | null | undefined, key: unknown, field: string): NiceFieldState;
+export interface UseNiceLookupSourceOptions {
+    iconField?: string;
+    descriptionField?: string;
+    groupField?: string;
+    /** Field(s) searched when user types. If omitted, server-side search is used. */
+    searchFields?: string[];
+    autoLoad?: boolean;
+    /** Max items to load. Default: 200. */
+    take?: number;
+}
+export interface NiceLookupSourceState {
+    options: NiceOption[];
+    loading: boolean;
+    error: string | null;
+    search: (query: string) => void;
+    reload: () => void;
+}
+export declare function useNiceLookupSource<T = any>(source: NiceDataSource<T> | null | undefined, valueField: string, labelField: string, opts?: UseNiceLookupSourceOptions): NiceLookupSourceState;
+//# sourceMappingURL=datasource-hooks.d.ts.map

package/dist/core/datasource-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource-hooks.d.ts","sourceRoot":"","sources":["../../src/core/datasource-hooks.ts"],"names":[],"mappings":"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"}