@nice2dev/ui-core 1.0.10

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

@@ -0,0 +1,201 @@
+/**
+ * NiceOfflineStorage — IndexedDB-based offline storage
+ * Sprint 5: Offline Support & Cross-tab Sync
+ */
+import type { NiceDataSource, NiceLoadOptions, NiceSortExpression, NiceFilterGroup } from './datasource';
+export interface NiceIndexedDBConfig {
+    /** Database name */
+    dbName: string;
+    /** Store/table name */
+    storeName: string;
+    /** Key field (default 'id') */
+    keyField?: string;
+    /** Database version (default 1) */
+    version?: number;
+    /** Additional indexes to create */
+    indexes?: Array<{
+        name: string;
+        keyPath: string | string[];
+        unique?: boolean;
+    }>;
+}
+/**
+ * Creates a data source backed by IndexedDB for offline storage.
+ */
+export declare function createIndexedDBDataSource<T extends Record<string, any>>(config: NiceIndexedDBConfig): NiceDataSource<T> & {
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    getAll(): Promise<T[]>;
+    bulkInsert(items: T[]): Promise<void>;
+    bulkDelete(keys: unknown[]): Promise<void>;
+    exportData(): Promise<T[]>;
+    importData(items: T[]): Promise<void>;
+};
+export interface NiceOfflineFirstConfig<T> {
+    /** Remote data source */
+    remoteSource: NiceDataSource<T>;
+    /** IndexedDB configuration */
+    offlineConfig: NiceIndexedDBConfig;
+    /** Sync strategy */
+    syncStrategy?: 'remote-first' | 'local-first' | 'merge';
+    /** Conflict resolution */
+    onConflict?: (local: T, remote: T) => T;
+    /** Called when sync completes */
+    onSync?: (result: {
+        added: number;
+        updated: number;
+        removed: number;
+    }) => void;
+    /** Auto-sync interval in ms (0 to disable) */
+    autoSyncInterval?: number;
+}
+export interface NicePendingChange<T> {
+    id: string;
+    action: 'insert' | 'update' | 'remove';
+    key?: unknown;
+    data?: Partial<T>;
+    timestamp: number;
+    retries: number;
+}
+/**
+ * Creates an offline-first data source that syncs with a remote source.
+ * Works offline and syncs changes when back online.
+ */
+export declare function createOfflineFirstDataSource<T extends Record<string, any>>(config: NiceOfflineFirstConfig<T>): NiceDataSource<T> & {
+    sync(): Promise<void>;
+    isOnline(): boolean;
+    getPendingChanges(): Promise<NicePendingChange<T>[]>;
+    clearPendingChanges(): Promise<void>;
+};
+export interface NiceCrossTabSyncConfig<T> {
+    /** Channel name for BroadcastChannel */
+    channelName: string;
+    /** Data source to sync */
+    source: NiceDataSource<T>;
+}
+export type CrossTabMessage<T> = {
+    type: 'insert';
+    data: T;
+} | {
+    type: 'update';
+    key: unknown;
+    changes: Partial<T>;
+} | {
+    type: 'remove';
+    key: unknown;
+} | {
+    type: 'refresh';
+} | {
+    type: 'request-sync';
+} | {
+    type: 'sync-data';
+    data: T[];
+};
+/**
+ * Wraps a data source with cross-tab synchronization using BroadcastChannel.
+ */
+export declare function withCrossTabSync<T extends Record<string, any>>(config: NiceCrossTabSyncConfig<T>): NiceDataSource<T> & {
+    broadcast(msg: CrossTabMessage<T>): void;
+    requestSync(): void;
+};
+export interface NiceURLStateConfig {
+    /** Prefix for URL params (default '') */
+    prefix?: string;
+    /** Which state to persist */
+    persist?: {
+        filter?: boolean;
+        sort?: boolean;
+        page?: boolean;
+        search?: boolean;
+    };
+    /** Use hash instead of query string */
+    useHash?: boolean;
+}
+export interface NiceURLState {
+    filter?: NiceFilterGroup;
+    sort?: NiceSortExpression[];
+    skip?: number;
+    take?: number;
+    search?: string;
+}
+/**
+ * Manages data source state in URL for bookmarkable/shareable views.
+ */
+export declare function createURLStateManager(config?: NiceURLStateConfig): {
+    /**
+     * Read current state from URL.
+     */
+    read(): NiceURLState;
+    /**
+     * Write state to URL.
+     */
+    write(state: NiceURLState): void;
+    /**
+     * Clear all state from URL.
+     */
+    clear(): void;
+    /**
+     * Create load options from URL state.
+     */
+    toLoadOptions(): NiceLoadOptions;
+};
+export interface NiceStateSnapshot {
+    version: string;
+    timestamp: number;
+    data: unknown[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Utilities for exporting and importing data source state.
+ */
+export declare const NiceStateIO: {
+    /**
+     * Export data to JSON string.
+     */
+    exportToJSON<T>(source: NiceDataSource<T>, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Import data from JSON string.
+     */
+    importFromJSON<T>(source: NiceDataSource<T> & {
+        bulkInsert?(items: T[]): Promise<void>;
+    }, json: string, options?: {
+        replace?: boolean;
+        validate?: (item: T) => boolean;
+    }): Promise<{
+        imported: number;
+        skipped: number;
+    }>;
+    /**
+     * Download data as JSON file.
+     */
+    downloadAsJSON<T>(source: NiceDataSource<T>, filename?: string): Promise<void>;
+    /**
+     * Import from file input.
+     */
+    importFromFile<T>(source: NiceDataSource<T>, file: File, options?: {
+        replace?: boolean;
+        validate?: (item: T) => boolean;
+    }): Promise<{
+        imported: number;
+        skipped: number;
+    }>;
+};
+export interface NiceUserPreferences {
+    [key: string]: unknown;
+}
+/**
+ * Manages user preferences with localStorage backend.
+ */
+export declare function createUserPreferencesStore(storageKey?: string): {
+    get<T>(key: string, defaultValue?: T): T | undefined;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    getAll(): NiceUserPreferences;
+    setAll(prefs: NiceUserPreferences): void;
+    clear(): void;
+    /**
+     * Merge with existing preferences.
+     */
+    merge(prefs: Partial<NiceUserPreferences>): void;
+};
+//# sourceMappingURL=datasource-offline.d.ts.map

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

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

package/dist/core/datasource.d.ts

@@ -0,0 +1,181 @@
+/**
+ * NiceDataSource — Universal data-binding abstraction.
+ *
+ * Protocol-agnostic interface for fetching, querying and mutating data.
+ * Works with REST, OData v4, GraphQL, static arrays, or any custom backend.
+ *
+ * Usage:
+ *   const src = createRestDataSource({ url: '/api/employees', keyField: 'id' });
+ *   <NiceDataGrid dataSource={src} columns={[...]} />
+ */
+export type NiceFilterOperator = '=' | '<>' | '<' | '<=' | '>' | '>=' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'between' | 'isblank' | 'isnotblank' | (string & {});
+export type NiceFilterCondition = {
+    type: 'condition';
+    field: string;
+    operator: NiceFilterOperator;
+    value: unknown;
+};
+export type NiceFilterGroup = {
+    type: 'group';
+    logic: 'and' | 'or';
+    items: (NiceFilterCondition | NiceFilterGroup)[];
+};
+/** Sort direction for data source queries. */
+export type NiceSortDirection = 'asc' | 'desc';
+/** A single sort expression: field name + direction. */
+export interface NiceSortExpression {
+    field: string;
+    direction: NiceSortDirection;
+}
+/** Parameters sent to `load()`. All optional — adapters use what they support. */
+export interface NiceLoadOptions {
+    filter?: NiceFilterGroup;
+    sort?: NiceSortExpression[];
+    skip?: number;
+    take?: number;
+    search?: string;
+    searchFields?: string[];
+    select?: string[];
+    expand?: string[];
+    group?: {
+        field: string;
+        direction?: NiceSortDirection;
+    }[];
+    /** Arbitrary parameters forwarded to the adapter (e.g. custom query strings). */
+    customParams?: Record<string, unknown>;
+}
+/** Result returned by {@link NiceDataSource.load}. */
+export interface NiceLoadResult<T> {
+    data: T[];
+    totalCount: number;
+    summary?: Record<string, unknown>;
+}
+/** Events emitted by all NiceDataSource implementations. */
+export type NiceDataSourceEventMap = {
+    changed: [];
+    loading: [boolean];
+    error: [Error | null];
+    loaded: [NiceLoadResult<unknown>];
+};
+type Listener<Args extends unknown[]> = (...args: Args) => void;
+/**
+ * Universal data source interface for Nice2Dev UI data components.
+ * All data-bound components (NiceDataGrid, NiceList, NiceForm, etc.) accept a `NiceDataSource`.
+ * Create one via `createArrayDataSource`, `createRestDataSource`, `createODataDataSource`,
+ * `createGraphQLDataSource`, or `createCustomDataSource`.
+ */
+export interface NiceDataSource<T = any> {
+    /** Field name used as unique row key. */
+    readonly keyField: string;
+    /** True when insert/update/remove are available. */
+    readonly writable: boolean;
+    load(options?: NiceLoadOptions): Promise<NiceLoadResult<T>>;
+    byKey(key: unknown): Promise<T | undefined>;
+    insert?(item: Partial<T>): Promise<T>;
+    update?(key: unknown, changes: Partial<T>): Promise<T>;
+    remove?(key: unknown): Promise<void>;
+    on<K extends keyof NiceDataSourceEventMap>(event: K, handler: Listener<NiceDataSourceEventMap[K]>): () => void;
+}
+/** Configuration for {@link createArrayDataSource}. */
+export interface NiceArrayDataSourceConfig<T = any> {
+    keyField?: string;
+    data: T[];
+}
+/**
+ * Creates an in-memory data source backed by a plain array.
+ * Supports sort, filter, paginate, search, and full CRUD — all client-side.
+ */
+export declare function createArrayDataSource<T extends Record<string, any> = any>(config: NiceArrayDataSourceConfig<T>): NiceDataSource<T>;
+/** Configuration for {@link createRestDataSource}. */
+export interface NiceRestConfig<T = any> {
+    /** Base URL, e.g. `/api/employees` */
+    url: string;
+    keyField?: string;
+    /** GET URL for loading. Default: `url`. */
+    loadUrl?: string;
+    /** POST URL. Default: `url`. */
+    insertUrl?: string;
+    /** PUT/PATCH URL builder. Default: `url/:key`. */
+    updateUrl?: string | ((key: unknown) => string);
+    /** DELETE URL builder. Default: `url/:key`. */
+    deleteUrl?: string | ((key: unknown) => string);
+    /** GET URL for single record. Default: `url/:key`. */
+    byKeyUrl?: string | ((key: unknown) => string);
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    fetchOptions?: RequestInit;
+    /** 'PUT' (default) or 'PATCH'. */
+    updateMethod?: 'PUT' | 'PATCH';
+    /** Map NiceLoadOptions → query-string params. If omitted, default mapping is used. */
+    mapLoadParams?: (options: NiceLoadOptions) => Record<string, string>;
+    /** Extract NiceLoadResult from fetch response JSON. */
+    extractLoadResult?: (json: unknown) => NiceLoadResult<T>;
+    /** Extract single item from response JSON. */
+    extractItem?: (json: unknown) => T;
+    prepareInsertBody?: (item: Partial<T>) => unknown;
+    prepareUpdateBody?: (key: unknown, changes: Partial<T>) => unknown;
+    onError?: (error: Error, operation: string) => void;
+}
+/**
+ * Creates a data source that communicates with a REST API.
+ * Supports customizable URL patterns, headers, request/response mapping,
+ * and optional auth header factories.
+ */
+export declare function createRestDataSource<T extends Record<string, any> = any>(config: NiceRestConfig<T>): NiceDataSource<T>;
+/** Configuration for {@link createODataDataSource}. */
+export interface NiceODataConfig<T = any> {
+    /** OData entity set URL, e.g. `/odata/Employees`. */
+    url: string;
+    keyField?: string;
+    version?: 3 | 4;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    fetchOptions?: RequestInit;
+    onError?: (error: Error, operation: string) => void;
+}
+export declare function createODataDataSource<T extends Record<string, any> = any>(config: NiceODataConfig<T>): NiceDataSource<T>;
+/** Configuration for {@link createGraphQLDataSource}. */
+export interface NiceGraphQLConfig<T = any> {
+    /** GraphQL endpoint URL. */
+    url: string;
+    keyField?: string;
+    /** Named queries / mutations. */
+    queries: {
+        /** Query returning list + totalCount. */
+        load: string;
+        /** Query returning single item by key. */
+        byKey?: string;
+        /** Mutation for insert. */
+        insert?: string;
+        /** Mutation for update. */
+        update?: string;
+        /** Mutation for delete. */
+        remove?: string;
+    };
+    /** Map NiceLoadOptions → GraphQL variables. Default: pass skip/take/sort/filter/search directly. */
+    mapVariables?: (options: NiceLoadOptions) => Record<string, unknown>;
+    /** Extract NiceLoadResult from query response data. */
+    extractLoadResult?: (data: unknown) => NiceLoadResult<T>;
+    /** Extract single item from query/mutation response data. */
+    extractItem?: (data: unknown) => T;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    onError?: (error: Error, operation: string) => void;
+}
+export declare function createGraphQLDataSource<T extends Record<string, any> = any>(config: NiceGraphQLConfig<T>): NiceDataSource<T>;
+/**
+ * Handler functions for a fully custom data source.
+ * Provide your own `load`, `byKey`, `insert`, `update`, `remove` implementations.
+ */
+export interface NiceCustomDataSourceHandlers<T = any> {
+    keyField?: string;
+    load: (options: NiceLoadOptions) => Promise<NiceLoadResult<T>>;
+    byKey?: (key: unknown) => Promise<T | undefined>;
+    insert?: (item: Partial<T>) => Promise<T>;
+    update?: (key: unknown, changes: Partial<T>) => Promise<T>;
+    remove?: (key: unknown) => Promise<void>;
+}
+/**
+ * Creates a data source from user-supplied handler functions.
+ * Use this when none of the built-in adapters (Array, REST, OData, GraphQL) fits your backend.
+ */
+export declare function createCustomDataSource<T extends Record<string, any> = any>(handlers: NiceCustomDataSourceHandlers<T>): NiceDataSource<T>;
+export {};
+//# sourceMappingURL=datasource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../src/core/datasource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,MAAM,MAAM,kBAAkB,GAC1B,GAAG,GACH,IAAI,GACJ,GAAG,GACH,IAAI,GACJ,GAAG,GACH,IAAI,GACJ,UAAU,GACV,aAAa,GACb,YAAY,GACZ,UAAU,GACV,SAAS,GACT,SAAS,GACT,YAAY,GACZ,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,CAAC,mBAAmB,GAAG,eAAe,CAAC,EAAE,CAAC;CAClD,CAAC;AAMF,8CAA8C;AAC9C,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/C,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,IAAI,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,iBAAiB,CAAA;KAAE,EAAE,CAAC;IAC3D,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAMD,4DAA4D;AAC5D,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;IACnB,KAAK,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IACtB,MAAM,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CACnC,CAAC;AAEF,KAAK,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;AAqChE;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAG3B,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAG5C,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGrC,EAAE,CAAC,CAAC,SAAS,MAAM,sBAAsB,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,GAC3C,MAAM,IAAI,CAAC;CACf;AAmHD,uDAAuD;AACvD,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,GAAG;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,EAAE,CAAC;CACX;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACvE,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,CAyDnB;AAMD,sDAAsD;AACtD,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;IAChD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;IAChD,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;IAG/C,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,kCAAkC;IAClC,YAAY,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IAG/B,sFAAsF;IACtF,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGrE,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC;IACzD,8CAA8C;IAC9C,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;IAGnC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAClD,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAEnE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAiED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACtE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAwFnB;AAMD,uDAAuD;AACvD,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAgDD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACvE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,cAAc,CAAC,CAAC,CAAC,CA2DnB;AAMD,yDAAyD;AACzD,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,GAAG;IACxC,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,iCAAiC;IACjC,OAAO,EAAE;QACP,yCAAyC;QACzC,IAAI,EAAE,MAAM,CAAC;QACb,0CAA0C;QAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,2BAA2B;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,2BAA2B;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,2BAA2B;QAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,oGAAoG;IACpG,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrE,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC;IACzD,6DAA6D;IAC7D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;IAEnC,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACzE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CA0InB;AAMD;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,CAAC,GAAG,GAAG;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACjD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EACxE,QAAQ,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACxC,cAAc,CAAC,CAAC,CAAC,CA4DnB"}

package/dist/core/displayMode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared helpers for the `displayMode` prop on form-field controls.
+ *
+ * When `displayMode` is `true`, a control should render as a label-style,
+ * clickable text representation of its value (no input chrome). Clicking it
+ * (or focusing via Tab + Enter) should switch the control into the regular
+ * editable rendering for in-place editing — this replaces the standalone
+ * NiceInPlaceEditor and gives every base control the "click-to-edit" pattern.
+ */
+import React from 'react';
+export interface UseDisplayModeOptions {
+    enabled?: boolean;
+    readOnly?: boolean;
+    disabled?: boolean;
+}
+export interface UseDisplayModeResult {
+    /** True when the control should render as a clickable label (not the editor). */
+    isDisplay: boolean;
+    /** Switches into edit mode (focus the editor on next render). */
+    enterEdit: () => void;
+    /** Switches back into display mode. */
+    exitEdit: () => void;
+    /** Ref-callback that, when set on the editable input/textarea/etc., focuses it on enter. */
+    autoFocusRef: (node: HTMLElement | null) => void;
+}
+/**
+ * Tracks edit/display state for a control that supports `displayMode`.
+ * The editor is rendered when display mode is off OR the user has clicked
+ * to edit. On blur the control returns to display mode.
+ */
+export declare function useDisplayModeEdit({ enabled, readOnly, disabled, }: UseDisplayModeOptions): UseDisplayModeResult;
+export interface DisplayModeViewProps {
+    value: React.ReactNode;
+    placeholder?: React.ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    onActivate: () => void;
+    className?: string;
+    ariaLabel?: string;
+}
+/**
+ * Renders a clickable label-style view of the value. Pressing Enter or Space
+ * (when focused) activates edit mode just like clicking it.
+ */
+export declare const DisplayModeView: React.FC<DisplayModeViewProps>;
+//# sourceMappingURL=displayMode.d.ts.map

package/dist/core/displayMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayMode.d.ts","sourceRoot":"","sources":["../../src/core/displayMode.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAmD,MAAM,OAAO,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,4FAA4F;IAC5F,YAAY,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACP,QAAQ,EACR,QAAQ,GACT,EAAE,qBAAqB,GAAG,oBAAoB,CA8C9C;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CAsC1D,CAAC"}

package/dist/core/displayStyle.d.ts

@@ -0,0 +1,79 @@
+import type { ThemeVariantConfig } from './themeVariants';
+/**
+ * Cross-component visual presentation style.
+ * Each style maps 1:1 to a ThemeVariantConfig preset controlling
+ * buttons, inputs, cards, badges, tabs, toggles, tooltips, tables, etc.
+ */
+export type NiceDisplayStyle = 'default' | 'minimal' | 'rounded' | 'sharp' | 'glass' | 'neumorphic' | 'playful' | 'enterprise' | 'modern3d' | 'brutalist' | 'luxe' | 'pill' | 'flat' | 'editorial' | 'dashboard' | 'softCloud' | 'cosmic' | 'corporate' | 'bank' | 'government' | 'military' | 'legal' | 'medical' | 'swiss' | 'scandinavian' | 'bauhaus' | 'notebook' | 'origami' | 'watercolor' | 'monochrome' | 'paper' | 'zen' | 'terminal' | 'hacker' | 'retro8bit' | 'synthwave' | 'cyberpunk' | 'steampunk' | 'vapor' | 'neon' | 'windows95' | 'material' | 'fluent' | 'cupertino' | 'ant' | 'bootstrap' | 'chakra' | 'notion' | 'linear' | 'vercel' | 'candy' | 'bubblegum' | 'cartoon' | 'kawaii' | 'circus' | 'gaming' | 'kiddo' | 'disco' | 'clown';
+/** All available display style names. */
+export declare const NICE_DISPLAY_STYLES: NiceDisplayStyle[];
+/** Resolves a display style name to a full ThemeVariantConfig. */
+export declare function resolveDisplayStyleConfig(style: NiceDisplayStyle): ThemeVariantConfig;
+/** Component categories for style resolution. */
+export type NiceComponentType = 'button' | 'input' | 'card' | 'badge' | 'tab' | 'toggle' | 'tooltip' | 'modal' | 'table' | 'menu';
+export interface NiceDisplayStyleContextValue {
+    /** Currently active global display style. */
+    displayStyle: NiceDisplayStyle;
+    /** Resolved variant config for the current display style. */
+    variantConfig: ThemeVariantConfig;
+    /** Change the global display style. */
+    setDisplayStyle: (style: NiceDisplayStyle) => void;
+}
+export declare const NiceDisplayStyleContext: import("react").Context<NiceDisplayStyleContextValue>;
+/**
+ * Returns the current global display style from context.
+ */
+export declare function useNiceDisplayStyle(): NiceDisplayStyleContextValue;
+/**
+ * Resolves the effective display style for a component, with priority:
+ *   prop (per-component) → context (global) → 'default'
+ */
+export declare function useResolvedDisplayStyle(propStyle?: NiceDisplayStyle): {
+    style: NiceDisplayStyle;
+    config: ThemeVariantConfig;
+};
+/**
+ * Returns inline CSS properties for a specific component type
+ * based on the resolved display style.
+ *
+ * @param componentType - Which component category to style
+ * @param propStyle - Optional per-component display style override
+ * @param primaryColor - Primary color for style generators (e.g. badge, button)
+ */
+export declare function useComponentDisplayStyle(componentType: NiceComponentType, propStyle?: NiceDisplayStyle, primaryColor?: string): React.CSSProperties;
+/**
+ * Returns the CSS class suffix for a given component type and display style.
+ * Components use this to apply style-specific classes: e.g. `nice-btn--style-gradient`
+ */
+export declare function useComponentDisplayClass(componentType: NiceComponentType, propStyle?: NiceDisplayStyle): string;
+/**
+ * Returns density CSS properties for the current display style.
+ */
+export declare function useDisplayDensity(propStyle?: NiceDisplayStyle): React.CSSProperties;
+/**
+ * Returns animation CSS properties for the current display style.
+ */
+export declare function useDisplayAnimation(propStyle?: NiceDisplayStyle): React.CSSProperties;
+/**
+ * Generates inline style properties for a specific component type
+ * from a ThemeVariantConfig.
+ */
+export declare function getComponentStyleFromConfig(componentType: NiceComponentType, config: ThemeVariantConfig, primaryColor?: string): React.CSSProperties;
+/**
+ * Returns a CSS class string expressing the display-style data attributes.
+ * Apply this to a container to let CSS selectors respond to the style.
+ */
+export declare function getDisplayStyleDataAttrs(style: NiceDisplayStyle): Record<string, string>;
+/**
+ * Describes a display style for UI pickers / documentation.
+ */
+export interface NiceDisplayStyleInfo {
+    name: NiceDisplayStyle;
+    label: string;
+    description: string;
+    density: string;
+    animation: string;
+}
+/** Metadata for all built-in display styles. */
+export declare const NICE_DISPLAY_STYLE_INFO: NiceDisplayStyleInfo[];
+//# sourceMappingURL=displayStyle.d.ts.map

package/dist/core/displayStyle.d.ts.map

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

package/dist/core/helpContext.d.ts

@@ -0,0 +1,97 @@
+/**
+ * NiceHelpContext — Global context for inline help system
+ *
+ * Provides:
+ * - Global enable/disable for inline help
+ * - Per-component help visibility control
+ * - Help content loading from .doc.json files
+ * - Localization support
+ *
+ * @since 2.6.0
+ */
+import React, { type ReactNode } from 'react';
+export interface HelpProp {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: string | number | boolean;
+    description: string;
+}
+export interface HelpExample {
+    title: string;
+    code: string;
+    language?: string;
+}
+export interface HelpContent {
+    name: string;
+    description: string;
+    category: string;
+    version?: string;
+    since?: string;
+    status?: 'stable' | 'beta' | 'deprecated';
+    author?: string;
+    props?: HelpProp[];
+    examples?: HelpExample[];
+    tips?: string[];
+    seeAlso?: string[];
+}
+export interface HelpConfig {
+    /** Global enable/disable for all inline help */
+    enabled: boolean;
+    /** Default visibility for help panels (collapsed/expanded) */
+    defaultExpanded: boolean;
+    /** Show help icon in component headers */
+    showHelpIcon: boolean;
+    /** Help panel position */
+    position: 'top' | 'bottom' | 'tooltip' | 'sidebar';
+    /** Locale for help content */
+    locale: string;
+    /** Custom help content loader */
+    contentLoader?: (componentName: string, locale: string) => Promise<HelpContent | null>;
+}
+export interface HelpContextValue {
+    /** Current help configuration */
+    config: HelpConfig;
+    /** Update help configuration */
+    setConfig: (config: Partial<HelpConfig>) => void;
+    /** Toggle global help visibility */
+    toggleGlobalHelp: () => void;
+    /** Per-component disabled set */
+    disabledComponents: Set<string>;
+    /** Disable help for specific component */
+    disableComponentHelp: (componentName: string) => void;
+    /** Enable help for specific component */
+    enableComponentHelp: (componentName: string) => void;
+    /** Check if help is enabled for component */
+    isHelpEnabled: (componentName: string) => boolean;
+    /** Get help content for component */
+    getHelpContent: (componentName: string) => Promise<HelpContent | null>;
+    /** Loaded help content cache */
+    helpCache: Map<string, HelpContent>;
+}
+export interface NiceHelpProviderProps {
+    children: ReactNode;
+    /** Initial configuration */
+    config?: Partial<HelpConfig>;
+    /** Preloaded help content */
+    helpContent?: Record<string, HelpContent>;
+}
+export declare const NiceHelpProvider: React.FC<NiceHelpProviderProps>;
+/**
+ * Hook to access global help configuration and utilities
+ */
+export declare function useNiceHelp(): HelpContextValue;
+/**
+ * Hook to get help content for a specific component
+ */
+export declare function useComponentHelp(componentName: string): {
+    content: HelpContent | null;
+    loading: boolean;
+    enabled: boolean;
+    loadContent: () => Promise<void>;
+    position: "tooltip" | "top" | "bottom" | "sidebar";
+    defaultExpanded: boolean;
+    showHelpIcon: boolean;
+};
+export default NiceHelpProvider;
+//# sourceMappingURL=helpContext.d.ts.map

package/dist/core/helpContext.d.ts.map

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