@shival99/z-ui 1.0.1 → 1.0.2

package/types/shival99-z-ui-services.d.ts

@@ -0,0 +1,364 @@
+import { Observable } from 'rxjs';
+import * as i0 from '@angular/core';
+import { TranslationObject, TranslateService } from '@ngx-translate/core';
+
+/**
+ * Z-Cache Types
+ */
+/** Cache entry with TTL */
+interface ZCacheEntry<T = unknown> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+}
+/** Cache service configuration */
+interface ZCacheConfig {
+    /** Prefix for cache keys */
+    prefix?: string;
+    /** Whether to encrypt data */
+    encrypt?: boolean;
+}
+
+/**
+ * Z-Cache Service
+ * A localStorage-based cache service with optional encryption
+ */
+
+declare class ZCacheService {
+    private static _prefix;
+    private static _encrypt;
+    /**
+     * Configure the cache service
+     */
+    static configure(config: ZCacheConfig): void;
+    private static _encode;
+    private static _decode;
+    private static _getFullKey;
+    private static _safeOperation;
+    /**
+     * Get a value from cache
+     * @param key - Cache key
+     * @param defaultValue - Default value if not found
+     * @param encrypt - Whether to use encryption (default: service config)
+     */
+    static get<T>(key: string, defaultValue?: T, encrypt?: boolean): T | undefined;
+    /**
+     * Set a value in cache
+     * @param key - Cache key
+     * @param data - Data to store
+     * @param encrypt - Whether to use encryption
+     */
+    static set<T>(key: string, data: T, encrypt?: boolean): boolean;
+    /**
+     * Delete a key from cache
+     * @param key - Cache key
+     * @param encrypt - Whether key is encrypted
+     */
+    static delete(key: string, encrypt?: boolean): boolean;
+    /**
+     * Delete multiple keys from cache
+     * @param keys - Array of cache keys
+     * @param encrypt - Whether keys are encrypted
+     */
+    static deleteMultiple(keys: string[], encrypt?: boolean): boolean;
+    /**
+     * Clear all cache with the configured prefix
+     */
+    static clear(): boolean;
+    /**
+     * Check if a key exists in cache
+     * @param key - Cache key
+     * @param encrypt - Whether key is encrypted
+     */
+    static has(key: string, encrypt?: boolean): boolean;
+    /**
+     * Get all keys with the configured prefix
+     */
+    static keys(): string[];
+}
+
+/**
+ * Z-IndexDB Types
+ */
+/** Configuration for a single IndexedDB store */
+interface ZIndexDbStoreConfig {
+    /** Name of the store */
+    name: string;
+    /** Whether to encrypt data (default: true) */
+    encrypt?: boolean;
+    /** Keys to avoid during clear operation */
+    protectedKeys?: string[];
+}
+/** Configuration for Z-IndexDB Service */
+interface ZIndexDbConfig {
+    /** Database name */
+    dbName?: string;
+    /** Database version */
+    version?: number;
+    /** Transaction mode */
+    mode?: IDBTransactionMode;
+    /** Store configurations - supports multiple stores */
+    stores?: ZIndexDbStoreConfig[];
+    /** Default store name (for backward compatibility) */
+    defaultStore?: string;
+    /** Keys to avoid during clear operation (global) */
+    protectedKeys?: string[];
+}
+
+/**
+ * Z-IndexDB Service
+ * A robust IndexedDB service with multi-store support, encryption, and retry logic
+ */
+
+declare class ZIndexDbService {
+    private _db;
+    private _dbName;
+    private _version;
+    private _mode;
+    private _dbReady;
+    private _stores;
+    private _defaultStoreName;
+    private _globalProtectedKeys;
+    constructor(config?: ZIndexDbConfig);
+    private _getStoreConfig;
+    private _encrypt;
+    private _decrypt;
+    private _closeConnection;
+    private _reconnect;
+    private _withRetry;
+    private _initDb;
+    /**
+     * Get a value from the store
+     * @param key - The key to retrieve
+     * @param defaultValue - Default value if key not found
+     * @param storeName - Optional store name (uses default if not specified)
+     */
+    get<T>(key: string, defaultValue?: T, storeName?: string): Promise<T | undefined>;
+    /**
+     * Set a value in the store
+     * @param key - The key to set
+     * @param value - The value to store
+     * @param storeName - Optional store name
+     */
+    set<T>(key: string, value: T, storeName?: string): Promise<void>;
+    /**
+     * Delete a key from the store
+     * @param key - Key or array of keys to delete
+     * @param storeName - Optional store name
+     */
+    delete(key: string | string[], storeName?: string): Promise<void>;
+    /**
+     * Clear all data from a store (respecting protected keys)
+     * @param storeName - Optional store name
+     */
+    clear(storeName?: string): Promise<void>;
+    /**
+     * Get all items from a store
+     * @param storeName - Optional store name
+     */
+    getAll<T = unknown>(storeName?: string): Promise<Record<string, T>>;
+    /**
+     * Set multiple items at once
+     * @param items - Object with key-value pairs
+     * @param storeName - Optional store name
+     */
+    setMultiple<T>(items: Record<string, T>, storeName?: string): Promise<void>;
+    /**
+     * Get the list of available store names
+     */
+    getStoreNames(): string[];
+    /**
+     * Check if a store exists
+     * @param storeName - Store name to check
+     */
+    hasStore(storeName: string): boolean;
+    /**
+     * Add a new store (requires database version upgrade)
+     * Note: This will cause database reconnection
+     * @param config - Store configuration
+     */
+    addStore(config: ZIndexDbStoreConfig): Promise<void>;
+}
+
+type SubjectType = 'subject' | 'behavior';
+declare class ZSubjectService {
+    private readonly _subjects;
+    private readonly _behaviorSubjects;
+    /**
+     * Emit a value to a subject
+     * @param key - Subject identifier
+     * @param type - 'subject' for Subject, 'behavior' for BehaviorSubject
+     * @param value - Value to emit
+     */
+    emit<T>(key: string, type: SubjectType, value: T): void;
+    /**
+     * Get an observable for a subject
+     * @param key - Subject identifier
+     * @param type - 'subject' for Subject, 'behavior' for BehaviorSubject
+     * @param initialValue - Initial value for BehaviorSubject (required for new behavior subjects)
+     */
+    on$<T>(key: string, type: SubjectType, initialValue?: T): Observable<T>;
+    /**
+     * Get the current value of a BehaviorSubject
+     * @param key - Subject identifier
+     */
+    getValue<T>(key: string): T | undefined;
+    /**
+     * Complete and remove a subject
+     * @param key - Subject identifier
+     * @param type - 'subject' for Subject, 'behavior' for BehaviorSubject
+     */
+    complete(key: string, type: SubjectType): void;
+    /**
+     * Complete all subjects
+     */
+    completeAll(): void;
+    /**
+     * Check if a subject exists
+     * @param key - Subject identifier
+     * @param type - 'subject' for Subject, 'behavior' for BehaviorSubject
+     */
+    has(key: string, type: SubjectType): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ZSubjectService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ZSubjectService>;
+}
+
+/**
+ * Z-Theme Types
+ */
+type ZThemeName = 'green' | 'orange' | 'violet' | 'neutral' | 'stone' | 'zinc' | 'gray' | 'slate' | 'hospital';
+declare const Z_DEFAULT_THEME: ZThemeName;
+declare const Z_THEME_CSS_MAP: Record<ZThemeName, string>;
+
+declare class ZThemeService {
+    private readonly _document;
+    private readonly _isDark;
+    private readonly _currentTheme;
+    private readonly _loadedThemes;
+    readonly isDark: i0.Signal<boolean>;
+    readonly currentTheme: i0.Signal<ZThemeName>;
+    setTheme(theme: ZThemeName): void;
+    toggleDarkMode(isDark: boolean): void;
+    preloadTheme(theme: ZThemeName): void;
+    private _loadThemeCSS;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ZThemeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ZThemeService>;
+}
+
+declare class ZTranslateService {
+    private readonly _translate;
+    /** Current language signal */
+    readonly currentLang: i0.WritableSignal<string>;
+    /** Available languages */
+    readonly availableLangs: i0.WritableSignal<string[]>;
+    constructor();
+    private _initialize;
+    /**
+     * Change the current language
+     * @param lang - Language code
+     */
+    use(lang: string): void;
+    /**
+     * Get the current language code
+     */
+    getLang(): string;
+    /**
+     * Get translation synchronously (returns key if not found)
+     * @param key - Translation key
+     * @param params - Interpolation parameters
+     */
+    instant(key: string, params?: Record<string, unknown>): string;
+    /**
+     * Get translation asynchronously
+     * @param key - Translation key
+     * @param params - Interpolation parameters
+     */
+    get(key: string, params?: Record<string, unknown>): Promise<string>;
+    /**
+     * Get translation as observable
+     * @param key - Translation key
+     * @param params - Interpolation parameters
+     */
+    get$(key: string, params?: Record<string, unknown>): Observable<string>;
+    /**
+     * Stream translations (re-emits on language change)
+     * @param key - Translation key
+     * @param params - Interpolation parameters
+     */
+    stream$(key: string, params?: Record<string, unknown>): Observable<string>;
+    /**
+     * Get multiple translations at once
+     * @param keys - Array of translation keys
+     * @param params - Interpolation parameters (applied to all)
+     */
+    getMany(keys: string[], params?: Record<string, unknown>): Promise<Record<string, string>>;
+    /**
+     * Check if a translation key exists
+     * @param key - Translation key
+     */
+    has(key: string): boolean;
+    /**
+     * Add translations dynamically
+     * @param lang - Language code
+     * @param translations - Translation object
+     * @param shouldMerge - Whether to merge with existing translations
+     */
+    setTranslation(lang: string, translations: TranslationObject, shouldMerge?: boolean): void;
+    /**
+     * Get the underlying TranslateService for advanced usage
+     */
+    getNgxTranslate(): TranslateService;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ZTranslateService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ZTranslateService>;
+}
+
+/**
+ * Z-Http Types
+ */
+/** HTTP cache entry */
+interface ZHttpCacheEntry<T = unknown> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+}
+/** HTTP error response */
+interface ZHttpError {
+    message: string;
+    status: number;
+    error?: unknown;
+    endpoint?: string;
+    method?: string;
+    body?: unknown;
+}
+/** HTTP request options */
+interface ZHttpOptions<TParams extends object = object> {
+    params?: TParams;
+    headers?: Record<string, string | string[]>;
+    enableCache?: boolean;
+    timeCache?: number;
+    contentType?: 'json' | 'urlencoded' | 'form-data';
+    skipToken?: boolean;
+}
+
+/**
+ * Z-Translate Types
+ */
+/** Translate service configuration */
+interface ZTranslateConfig {
+    /** Default language */
+    defaultLang?: string;
+    /** Available languages */
+    availableLangs?: string[];
+    /** Path to translation files */
+    translationPath?: string;
+    /** Translation file extension */
+    fileExtension?: string;
+}
+/** Translate I18n configuration */
+interface ZTranslateI18nConfig {
+    defaultLang?: string;
+    availableLangs?: string[];
+}
+
+export { ZCacheService, ZIndexDbService, ZSubjectService, ZThemeService, ZTranslateService, Z_DEFAULT_THEME, Z_THEME_CSS_MAP };
+export type { ZCacheConfig, ZCacheEntry, ZHttpCacheEntry, ZHttpError, ZHttpOptions, ZIndexDbConfig, ZIndexDbStoreConfig, ZThemeName, ZTranslateConfig, ZTranslateI18nConfig };

package/types/shival99-z-ui-utils.d.ts

@@ -0,0 +1,145 @@
+import { WritableSignal } from '@angular/core';
+import { ClassValue } from 'clsx';
+import { Observable } from 'rxjs';
+import { FormGroup, FormArray } from '@angular/forms';
+
+/**
+ * Z-Common Types
+ * Common utility types
+ */
+type ZBrowserName = 'Chrome' | 'Edge' | 'Firefox' | 'Safari' | 'Opera' | 'IE' | 'Unknown' | string;
+type ZDeviceType = 'mobile' | 'tablet' | 'desktop';
+interface ZBrowserInfo {
+    name: ZBrowserName;
+    version: string;
+    agent: string;
+    device: ZDeviceType;
+    time: string;
+}
+interface ZNavigatorUABrandVersion {
+    brand: string;
+    version: string;
+}
+interface ZNavigatorUAData {
+    brands: ZNavigatorUABrandVersion[];
+    mobile: boolean;
+    platform: string;
+}
+declare global {
+    interface Navigator {
+        userAgentData?: ZNavigatorUAData;
+    }
+}
+
+/**
+ * Z-Common Utils
+ * Common utility functions for z-ui library
+ * All functions are prefixed with 'z' for consistency
+ */
+
+/** Merge Tailwind CSS classes with clsx */
+declare const zMergeClasses: (...inputs: ClassValue[]) => string;
+/** Transform boolean-like values to boolean */
+declare const zTransform: (value: boolean | string) => boolean;
+/** Generate a unique ID with optional prefix */
+declare const zGenerateId: (prefix?: string) => string;
+declare const zNoop: () => undefined;
+/** Simple UUID generator */
+declare const zUuid: () => string;
+/** Capitalize each word in a string */
+declare const zCapitalCase: (text: string) => string;
+/** Check if text is truncated (requires element to be rendered) */
+declare const zIsTextTruncated: (el: HTMLElement) => Promise<boolean>;
+/** Decode unicode escape sequences */
+declare const zDecodeUnicode: (str: string) => string;
+/** Generate a random color in hex, rgb, and hsl formats */
+declare const zRandomColor: () => {
+    hex: string;
+    rgb: string;
+    hsl: string;
+};
+/** Convert color string to ARGB format */
+declare const zConvertColorToArgb: (color: string) => string;
+/** Clean null/undefined values from object recursively */
+declare const zCleanObject: <T = unknown>(obj: T) => T;
+/** Flatten tree structure to flat array */
+declare const zTreeFlatten: <T extends Record<string, unknown>>(list: T[], keyMap: keyof T, parentKeyMap: keyof T, sortFn?: (a: T, b: T) => number) => (T & {
+    level: number;
+    parentsKey: string[];
+})[];
+/** Build tree structure from flat array */
+declare const zTreeBuild: <T extends Record<string, unknown>>(list: T[], keyMap: keyof T, parentKeyMap: keyof T, sortFn?: (a: T, b: T) => number) => (T & {
+    level: number;
+    parentsKey: string[];
+    children: unknown[];
+})[];
+/** Vietnamese character map for normalization */
+declare const VIETNAMESE_MAP: Record<string, string>;
+/** Remove Vietnamese diacritics from string */
+declare const zRemoveVietnamese: (str: string) => string;
+/** Full-text search using MiniSearch */
+declare const zMiniSearch: <T>(data: T[], query: string, fields: (keyof T | string)[]) => T[];
+/** Full-text search as Observable with loading state */
+declare const zMiniSearch$: <T>(data: T[], query: string, fields: (keyof T | string)[], loading?: WritableSignal<boolean>, fakeDelay?: number) => Observable<T[]>;
+/** Detect browser information */
+declare const zDetectBrowser: () => ZBrowserInfo;
+
+/**
+ * Z-Echarts Types
+ */
+interface ZEchartsThemeOptions {
+    /** Theme name (default: 'zTheme') */
+    themeName?: string;
+    /** Font family (default: Lexend, Arial, Helvetica, sans-serif) */
+    fontFamily?: string;
+}
+
+/**
+ * Z-Echarts Utils
+ * ECharts utility functions
+ */
+
+/**
+ * Register custom Z-UI theme for ECharts
+ * @param options - Theme configuration options
+ */
+declare function zRegisterEchartsTheme(options?: ZEchartsThemeOptions): void;
+/** @deprecated Use zRegisterEchartsTheme instead */
+declare const registerEchartsMsgTheme: () => void;
+
+/**
+ * Z-Form Utils
+ * Form utility functions
+ */
+
+/**
+ * Submit form and mark invalid controls as dirty
+ * @param form - FormGroup or FormArray to submit
+ * @returns true if form is valid, false otherwise
+ */
+declare const zSubmitForm: (form: FormGroup | FormArray) => boolean;
+/** Legacy alias */
+declare const submitForm: (form: FormGroup | FormArray) => boolean;
+/**
+ * Debug invalid form controls by logging to console
+ * @param form - FormGroup to debug
+ * @param parentKey - Parent key for nested controls
+ */
+declare const zDebugFormInvalid: (form: FormGroup, parentKey?: string) => void;
+/** Legacy alias */
+declare const debugFormInvalid: (form: FormGroup, parentKey?: string) => void;
+
+/**
+ * Z-Form Types
+ * Form utility types
+ */
+/** Form submit result */
+type ZFormSubmitResult = boolean;
+/** Form debug options */
+interface ZFormDebugOptions {
+    showValid?: boolean;
+    logLevel?: 'error' | 'warn' | 'log';
+}
+
+export { VIETNAMESE_MAP, debugFormInvalid, registerEchartsMsgTheme, submitForm, zCapitalCase, zCleanObject, zConvertColorToArgb, zDebugFormInvalid, zDecodeUnicode, zDetectBrowser, zGenerateId, zIsTextTruncated, zMergeClasses, zMiniSearch, zMiniSearch$, zNoop, zRandomColor, zRegisterEchartsTheme, zRemoveVietnamese, zSubmitForm, zTransform, zTreeBuild, zTreeFlatten, zUuid };
+export type { ZBrowserInfo, ZBrowserName, ZDeviceType, ZEchartsThemeOptions, ZFormDebugOptions, ZFormSubmitResult, ZNavigatorUABrandVersion, ZNavigatorUAData };