@chaos_team/chaos-ui 1.0.5

package/dist/lib.d.ts

@@ -0,0 +1,804 @@
+import { ClassValue } from 'clsx';
+export { b as MessageGlobalConfig, M as MessageOptions, c as MessagePlacement, a as MessageType, m as message } from './message-KJli9tvf.js';
+import { AxiosRequestConfig } from 'axios';
+export { f as formatCurrency, a as formatDate, b as formatDateTime, c as formatNumber, d as formatPercent, e as formatRelativeTime } from './format-BUpOzeCo.js';
+import * as React$1 from 'react';
+import { Resource } from 'i18next';
+export { default as i18n } from 'i18next';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * @lib storage
+ * @category lib/storage
+ * @since 0.2.0
+ * @description localStorage/sessionStorage 包装(过期/序列化/加密) / Storage wrapper with expiry, serialization, and optional encryption
+ * @example
+ * storage.set('key', { foo: 'bar' }, { expires: 3600 });
+ * const data = storage.get<{ foo: string }>('key');
+ */
+interface StorageOptions {
+    /** Expiry in seconds / 过期时间(秒) */
+    expires?: number;
+    /** Whether to use sessionStorage instead of localStorage / 是否使用 sessionStorage */
+    session?: boolean;
+}
+declare const storage: {
+    /**
+     * Set a value in storage / 设置存储值
+     * @param key Storage key
+     * @param value Value to store
+     * @param options Storage options (expiry, session)
+     */
+    set<T>(key: string, value: T, options?: StorageOptions): void;
+    /**
+     * Get a value from storage / 获取存储值
+     * @param key Storage key
+     * @param options Storage options (session)
+     * @returns The stored value or null if not found or expired
+     */
+    get<T>(key: string, options?: StorageOptions): T | null;
+    /**
+     * Remove a value from storage / 移除存储值
+     */
+    remove(key: string, options?: StorageOptions): void;
+    /**
+     * Clear all storage / 清空存储
+     */
+    clear(options?: StorageOptions): void;
+    /**
+     * Check if a key exists and is not expired / 检查键是否存在
+     */
+    has(key: string, options?: StorageOptions): boolean;
+    /**
+     * Get all keys / 获取所有键
+     */
+    keys(options?: StorageOptions): string[];
+    /**
+     * Get storage size (approximate in bytes) / 获取存储大小(近似字节)
+     */
+    size(options?: StorageOptions): number;
+};
+/** SessionStorage convenience wrapper / sessionStorage 便捷包装 */
+declare const sessionStorage: {
+    set: <T>(key: string, value: T, options?: Omit<StorageOptions, "session">) => void;
+    get: <T>(key: string) => T | null;
+    remove: (key: string) => void;
+    clear: () => void;
+    has: (key: string) => boolean;
+    keys: () => string[];
+};
+
+/**
+ * @lib eventBus
+ * @category lib/event
+ * @since 0.2.0
+ * @description 全局事件总线 / Global event bus for cross-component communication
+ * @example
+ * eventBus.on('user:login', (user) => console.log(user));
+ * eventBus.emit('user:login', { name: 'John' });
+ * eventBus.off('user:login');
+ */
+type EventHandler<T = unknown> = (payload: T) => void;
+declare class EventBus {
+    private handlers;
+    /**
+     * Subscribe to an event / 订阅事件
+     * @param event Event name
+     * @param handler Event handler
+     * @returns Unsubscribe function
+     */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Subscribe to an event once (auto-unsubscribe after first call) / 订阅一次
+     */
+    once<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Unsubscribe from an event / 取消订阅
+     * @param event Event name
+     * @param handler Specific handler (if omitted, removes all handlers for the event)
+     */
+    off<T = unknown>(event: string, handler?: EventHandler<T>): void;
+    /**
+     * Emit an event / 触发事件
+     */
+    emit<T = unknown>(event: string, payload?: T): void;
+    /**
+     * Remove all handlers for an event (or all events) / 清除所有处理器
+     */
+    clear(event?: string): void;
+    /**
+     * Get all registered event names / 获取所有事件名
+     */
+    events(): string[];
+    /**
+     * Get handler count for an event / 获取事件处理器数量
+     */
+    listenerCount(event: string): number;
+}
+/** Global event bus instance / 全局事件总线实例 */
+declare const eventBus: EventBus;
+
+/**
+ * @lib download
+ * @category lib/file
+ * @since 0.2.0
+ * @description 文件下载工具 / File download utilities (Blob/URL/Stream)
+ * @example
+ * download.text('hello.txt', 'Hello World');
+ * download.blob('data.bin', blob);
+ * download.url('https://example.com/file.pdf');
+ */
+declare const download: {
+    /**
+     * Download text content as a file / 下载文本文件
+     */
+    text(filename: string, content: string, mime?: string): void;
+    /**
+     * Download JSON as a file / 下载 JSON 文件
+     */
+    json(filename: string, data: unknown, pretty?: boolean): void;
+    /**
+     * Download a Blob / 下载 Blob
+     */
+    blob(filename: string, blob: Blob): void;
+    /**
+     * Download from a URL / 从 URL 下载
+     */
+    url(filename: string, url: string): void;
+    /**
+     * Download CSV from array of objects / 从对象数组下载 CSV
+     */
+    csv(filename: string, rows: Record<string, unknown>[], headers?: string[]): void;
+    /**
+     * Download from fetch response / 从 fetch 响应下载
+     */
+    response(filename: string, response: Response): Promise<void>;
+    /**
+     * Download via fetch with progress / 通过 fetch 下载(带进度)
+     */
+    fetch(url: string, filename: string, options?: RequestInit): Promise<void>;
+};
+
+/**
+ * @lib cookie
+ * @category lib/storage
+ * @since 0.2.0
+ * @description Cookie 读写工具 / Cookie read/write utilities
+ * @example
+ * cookie.set('token', 'abc123', { expires: 7, secure: true });
+ * const token = cookie.get('token');
+ * cookie.remove('token');
+ */
+interface CookieOptions {
+    /** Expiry in days / 过期天数 */
+    expires?: number;
+    /** Expiry date / 过期日期 */
+    expiresDate?: Date;
+    /** Path (default: '/') / 路径 */
+    path?: string;
+    /** Domain / 域名 */
+    domain?: string;
+    /** Secure flag / 安全标志 */
+    secure?: boolean;
+    /** SameSite policy / SameSite 策略 */
+    sameSite?: "strict" | "lax" | "none";
+    /** HttpOnly flag (only works when set by server) / HttpOnly 标志 */
+    httpOnly?: boolean;
+}
+declare const cookie: {
+    /**
+     * Set a cookie / 设置 Cookie
+     */
+    set(name: string, value: string, options?: CookieOptions): void;
+    /**
+     * Get a cookie value / 获取 Cookie
+     */
+    get(name: string): string | null;
+    /**
+     * Remove a cookie / 删除 Cookie
+     */
+    remove(name: string, options?: Pick<CookieOptions, "path" | "domain">): void;
+    /**
+     * Get all cookies as an object / 获取所有 Cookie
+     */
+    getAll(): Record<string, string>;
+    /**
+     * Check if a cookie exists / 检查 Cookie 是否存在
+     */
+    has(name: string): boolean;
+};
+
+/**
+ * @lib url
+ * @category lib/url
+ * @since 0.2.0
+ * @description URL 参数解析/序列化工具 / URL parameter parse/serialize utilities
+ * @example
+ * const params = url.parse('https://example.com?a=1&b=2');
+ * url.stringify({ a: 1, b: [2, 3] });
+ * url.getQuery('key');
+ * url.setQuery('key', 'value');
+ */
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue | QueryValue[]>;
+declare const url: {
+    /**
+     * Parse a query string into an object / 解析查询字符串
+     * @param search Query string (e.g., '?a=1&b=2' or 'a=1&b=2')
+     * @returns Parsed parameters object
+     */
+    parse(search?: string): Record<string, string>;
+    /**
+     * Serialize an object into a query string / 序列化为查询字符串
+     * @param params Parameters object
+     * @returns Query string (without leading '?')
+     */
+    stringify(params: QueryParams): string;
+    /**
+     * Get a specific query parameter / 获取特定查询参数
+     */
+    getQuery(key: string, search?: string): string | null;
+    /**
+     * Set query parameters (updates URL in browser) / 设置查询参数
+     */
+    setQuery(params: QueryParams, options?: {
+        push?: boolean;
+    }): void;
+    /**
+     * Remove query parameters / 移除查询参数
+     */
+    removeQuery(keys: string | string[]): void;
+    /**
+     * Parse a full URL into parts / 解析完整 URL
+     */
+    parseUrl(fullUrl: string): {
+        protocol: string;
+        hostname: string;
+        port: string;
+        pathname: string;
+        search: string;
+        hash: string;
+        params: Record<string, string>;
+    };
+    /**
+     * Build a URL with query parameters / 构建带参数的 URL
+     */
+    buildUrl(base: string, params?: QueryParams): string;
+    /**
+     * Check if URL is external / 检查是否外部链接
+     */
+    isExternal(link: string): boolean;
+};
+
+type ModalKind = "confirm" | "info" | "warning" | "success" | "error";
+
+/**
+ * @lib modal
+ * @category lib/feedback
+ * @since 0.3.0
+ * @description 命令式模态框 API (antd Modal.confirm/Radix Dialog equivalent) / Imperative modal API
+ * @keywords modal, dialog, confirm, imperative, popup
+ * @example
+ * ```ts
+ * import { Modal } from '@chaos_team/chaos-ui';
+ *
+ * Modal.confirm({
+ *   title: '确认删除?',
+ *   content: '此操作不可撤销',
+ *   okText: '删除',
+ *   cancelText: '取消',
+ *   onOk: async () => { await deleteItem(); },
+ * });
+ *
+ * Modal.info({ title: '提示', content: '请检查输入' });
+ * Modal.warning({ title: '警告', content: '余额不足' });
+ * Modal.success({ title: '成功', content: '保存完成' });
+ * Modal.error({ title: '错误', content: '网络异常' });
+ * ```
+ */
+
+interface ModalConfirmOptions {
+    title?: React.ReactNode;
+    content?: React.ReactNode;
+    okText?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    okVariant?: "default" | "destructive";
+    width?: string | number;
+    closable?: boolean;
+    maskClosable?: boolean;
+    icon?: React.ReactNode;
+    /** Callback when OK is clicked (supports async). If provided, the modal will show a loading state until it resolves. */
+    onOk?: () => void | Promise<void>;
+    /** Callback when Cancel is clicked. */
+    onCancel?: () => void;
+}
+type ModalAlertOptions = Omit<ModalConfirmOptions, "okVariant" | "cancelText" | "onCancel">;
+type ModalAPI = {
+    confirm: (options: ModalConfirmOptions) => void;
+    info: (options: ModalAlertOptions) => void;
+    warning: (options: ModalAlertOptions) => void;
+    success: (options: ModalAlertOptions) => void;
+    error: (options: ModalAlertOptions) => void;
+    closeAll: () => void;
+};
+declare const Modal: ModalAPI;
+
+interface ApiError {
+    status: number;
+    code?: string;
+    message: string;
+    details?: unknown;
+}
+interface ApiClientConfig {
+    baseURL?: string;
+    timeout?: number;
+    getToken?: () => string | null | Promise<string | null>;
+    refreshToken?: () => Promise<string | null>;
+    onTokenExpired?: () => void;
+    onError?: (error: ApiError) => void;
+    showErrorToast?: boolean;
+}
+declare class ApiClient {
+    private instance;
+    constructor(config?: ApiClientConfig);
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, body?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, body?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    patch<T>(url: string, body?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    setHeader(key: string, value: string): void;
+    removeHeader(key: string): void;
+}
+declare function getApiClient(config?: ApiClientConfig): ApiClient;
+declare function safeRequest<T>(fn: () => Promise<T>, fallback?: T): Promise<T | undefined>;
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+declare const logger: {
+    readonly level: LogLevel;
+    setLevel(level: LogLevel): void;
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+
+type Role = "admin" | "manager" | "editor" | "viewer" | "guest";
+type Permission = "read" | "create" | "update" | "delete" | "publish" | "export" | "import" | "manage_users" | "manage_roles" | "manage_settings";
+declare function hasPermission(role: Role, permission: Permission): boolean;
+declare function hasAnyPermission(role: Role, permissions: Permission[]): boolean;
+declare function hasAllPermissions(role: Role, permissions: Permission[]): boolean;
+
+interface ChaosI18nProviderProps {
+    locale?: string;
+    children: React.ReactNode;
+    resources?: Resource;
+}
+declare function ChaosI18nProvider({ locale, children, resources, }: ChaosI18nProviderProps): React$1.JSX.Element;
+
+/**
+ * Common validation utilities for forms and data processing.
+ * @since 0.2.0
+ */
+declare const patterns: {
+    /** Chinese mobile phone (11 digits, starts with 1) */
+    phone: RegExp;
+    /** Email address */
+    email: RegExp;
+    /** Chinese ID card (18 digits with check digit) */
+    idCard: RegExp;
+    /** Bank card number (16-19 digits) */
+    bankCard: RegExp;
+    /** Unified Social Credit Code (18 chars, alphanumeric) */
+    uscc: RegExp;
+    /** URL */
+    url: RegExp;
+    /** IPv4 */
+    ipv4: RegExp;
+};
+declare const validators: {
+    /** Test against a regex pattern */
+    pattern: (value: string, pattern: RegExp) => boolean;
+    /** Required field — not null, not undefined, not empty string, not whitespace-only */
+    required: (value: unknown) => boolean;
+    /** Minimum string length */
+    minLength: (value: string, min: number) => boolean;
+    /** Maximum string length */
+    maxLength: (value: string, max: number) => boolean;
+    /** Number range (inclusive) */
+    range: (value: number, min: number, max: number) => boolean;
+    /** Matches a specific value (e.g. password confirm) */
+    matches: <T>(value: T, target: T) => boolean;
+    /** Phone number */
+    phone: (value: string) => boolean;
+    /** Email */
+    email: (value: string) => boolean;
+    /** Chinese ID card */
+    idCard: (value: string) => boolean;
+    /** Bank card */
+    bankCard: (value: string) => boolean;
+    /** Unified Social Credit Code */
+    uscc: (value: string) => boolean;
+    /** URL */
+    url: (value: string) => boolean;
+    /** IPv4 */
+    ipv4: (value: string) => boolean;
+    /** Positive integer */
+    positiveInteger: (value: number) => boolean;
+    /** Non-negative integer */
+    nonNegativeInteger: (value: number) => boolean;
+    /** Decimal with precision */
+    decimal: (precision: number) => (value: number) => boolean;
+};
+
+/**
+ * Random number and ID generation utilities.
+ * @since 0.2.0
+ */
+/**
+ * Random integer in [min, max] (inclusive).
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * Random float in [min, max).
+ */
+declare function randomFloat(min: number, max: number): number;
+/**
+ * Generate a UUID v4 string.
+ */
+declare function uuid(): string;
+/**
+ * Generate a non-repeating sequence of integers in [0, n-1] (Fisher-Yates).
+ */
+declare function uniqueSequence(n: number): number[];
+/**
+ * Pick a random element from an array.
+ */
+declare function randomPick<T>(arr: T[]): T | undefined;
+/**
+ * Pick n random elements from an array (without replacement).
+ */
+declare function randomSample<T>(arr: T[], n: number): T[];
+/**
+ * Random string of given length (alphanumeric).
+ */
+declare function randomString(length: number): string;
+/**
+ * Random hex color.
+ */
+declare function randomColor(): string;
+
+/**
+ * Tree data structure utilities.
+ * @since 0.2.0
+ */
+interface TreeNode {
+    id: string | number;
+    parentId?: string | number | null;
+    children?: TreeNode[];
+    [key: string]: unknown;
+}
+/**
+ * Convert a flat array (with id/parentId) to a nested tree.
+ * Root nodes are those with parentId === null/undefined or parentId not found.
+ */
+declare function arrayToTree<T extends TreeNode>(items: T[], options?: {
+    idKey?: string;
+    parentKey?: string;
+    childrenKey?: string;
+    rootParentId?: string | number | null;
+}): T[];
+/**
+ * Flatten a nested tree back to an array.
+ */
+declare function treeToArray<T extends TreeNode>(tree: T[], options?: {
+    childrenKey?: string;
+}): T[];
+/**
+ * Find a node in a tree by predicate.
+ */
+declare function findInTree<T extends TreeNode>(tree: T[], predicate: (node: T) => boolean, childrenKey?: string): T | undefined;
+/**
+ * Get the full path (ancestors) of a node by id.
+ */
+declare function getPathById<T extends TreeNode>(tree: T[], targetId: string | number, idKey?: string, childrenKey?: string): T[];
+/**
+ * Get all leaf nodes from a tree.
+ */
+declare function getLeafNodes<T extends TreeNode>(tree: T[], childrenKey?: string): T[];
+
+/**
+ * Color utility functions.
+ * @since 0.2.0
+ */
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface HSL {
+    h: number;
+    s: number;
+    l: number;
+}
+/**
+ * Parse a hex color string to RGB.
+ */
+declare function hexToRgb(hex: string): RGB | null;
+/**
+ * Convert RGB to hex string.
+ */
+declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Convert RGB to HSL.
+ */
+declare function rgbToHsl({ r, g, b }: RGB): HSL;
+/**
+ * Convert HSL to RGB.
+ */
+declare function hslToRgb({ h, s, l }: HSL): RGB;
+/**
+ * Calculate relative luminance (WCAG).
+ */
+declare function luminance(hex: string): number;
+/**
+ * Calculate contrast ratio between two hex colors (WCAG).
+ */
+declare function contrastRatio(hex1: string, hex2: string): number;
+/**
+ * Check if contrast meets WCAG AA (4.5:1 for normal text).
+ */
+declare function meetsWCAGAA(hex1: string, hex2: string): boolean;
+/**
+ * Lighten a hex color by percentage (0-100).
+ */
+declare function lighten(hex: string, amount: number): string;
+/**
+ * Darken a hex color by percentage (0-100).
+ */
+declare function darken(hex: string, amount: number): string;
+/**
+ * Generate a palette of shades from a base color.
+ */
+declare function generatePalette(hex: string, steps?: number): string[];
+
+/**
+ * Array utility functions.
+ * @since 0.2.0
+ */
+/**
+ * Group an array by a key or callback.
+ */
+declare function groupBy<T>(arr: T[], key: keyof T | ((item: T) => string | number)): Record<string, T[]>;
+/**
+ * Sort an array by a key (stable).
+ */
+declare function sortBy<T>(arr: T[], key: keyof T | ((item: T) => string | number | Date), direction?: "asc" | "desc"): T[];
+/**
+ * Remove duplicate items from an array (shallow comparison).
+ */
+declare function unique<T>(arr: T[]): T[];
+/**
+ * Remove duplicates by a key or callback.
+ */
+declare function uniqueBy<T>(arr: T[], key: keyof T | ((item: T) => unknown)): T[];
+/**
+ * Split an array into chunks of a given size.
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * Paginate an array (1-indexed page).
+ */
+declare function paginate<T>(arr: T[], page: number, pageSize: number): {
+    items: T[];
+    total: number;
+    totalPages: number;
+    page: number;
+};
+/**
+ * Count occurrences of each value.
+ */
+declare function countBy<T>(arr: T[], key?: keyof T | ((item: T) => string)): Record<string, number>;
+/**
+ * Shuffle an array (Fisher-Yates, returns new array).
+ */
+declare function shuffle<T>(arr: T[]): T[];
+
+/**
+ * Content Security Policy (CSP) headers for Next.js apps using Chaos UI.
+ *
+ * Usage in next.config.ts:
+ * ```ts
+ * import { cspHeaders } from "@chaos_team/chaos-ui/next";
+ *
+ * export default {
+ *   async headers() {
+ *     return [
+ *       {
+ *         source: "/(.*)",
+ *         headers: cspHeaders(),
+ *       },
+ *     ];
+ *   },
+ * };
+ * ```
+ */
+declare function cspHeaders(): Array<{
+    key: string;
+    value: string;
+}>;
+
+/**
+ * @module crypto
+ * @category Utility
+ * @since 1.0.0-beta.0
+ * @description Cryptographic helpers — non-secret hashing (djb2/fnv1a), Base64/Hex encoding, random id/token generation, and a thin wrapper over the Web Crypto API for HMAC. None of these are for secrets-at-rest; use the Web Crypto `SubtleCrypto` API (exposed via `subtle`) for signed/hashed security-sensitive operations.
+ * @example
+ * hashString("abc");        // djb2 numeric hash
+ * randomId();               // "k3j8a..."
+ * toBase64("hello");        // "aGVsbG8="
+ */
+/**
+ * djb2 string hash — fast, non-cryptographic. Stable across runs.
+ * @returns 32-bit unsigned integer.
+ */
+declare function hashString(input: string): number;
+/** FNV-1a 32-bit hash — alternative non-cryptographic hash. */
+declare function hashFnv1a(input: string): number;
+/** Generate a random id of the given length using a URL-safe alphabet. */
+declare function randomId(length?: number): string;
+/** Generate a random hex token of the given byte length (default 16 bytes → 32 hex chars). */
+declare function randomToken(byteLength?: number): string;
+/** Cryptographically-strong random byte array via Web Crypto (falls back to Math.random). */
+declare function randomBytes(length: number): Uint8Array;
+/** Encode a UTF-8 string to Base64 (browser-safe). */
+declare function toBase64(input: string): string;
+/** Decode a Base64 string to UTF-8. */
+declare function fromBase64(input: string): string;
+/** Encode a byte array / string to lowercase hex. */
+declare function toHex(input: Uint8Array | string): string;
+/** Decode a hex string to a byte array. */
+declare function fromHex(input: string): Uint8Array;
+/** Access to the Web Crypto `SubtleCrypto` API, or `undefined` when unavailable. */
+declare const subtle: SubtleCrypto | undefined;
+/**
+ * Backward-compat default export name. Returns the module's helper bag so that
+ * `import { crypto } from "@/lib/crypto"` keeps working; it is NOT the global
+ * `crypto` (Web Crypto). Prefer the named helpers above.
+ */
+declare function crypto(): {
+    hashString: typeof hashString;
+    hashFnv1a: typeof hashFnv1a;
+    randomId: typeof randomId;
+    randomToken: typeof randomToken;
+    randomBytes: typeof randomBytes;
+    toBase64: typeof toBase64;
+    fromBase64: typeof fromBase64;
+    toHex: typeof toHex;
+    fromHex: typeof fromHex;
+    subtle: SubtleCrypto | undefined;
+};
+
+/**
+ * @module date
+ * @category Utility
+ * @since 1.0.0-beta.0
+ * @description Date helpers that complement @/lib/format — parsing, comparison, arithmetic, and query predicates. For user-facing formatting use `formatDate`/`formatDateTime` from `@/lib/format`.
+ * @example
+ * parseDate("2026-06-30");      // Date
+ * addDays(new Date(), 7);       // Date +7d
+ * isSameDay(a, b);              // boolean
+ * startOfDay(new Date());       // Date at 00:00:00
+ */
+/** Parse a value into a Date, returning `undefined` for invalid input (does not throw). */
+declare function parseDate(value: Date | number | string | undefined | null): Date | undefined;
+/** Returns true if the value is a valid Date. */
+declare function isValidDate(value: unknown): value is Date;
+/** Add a number of units to a date. Returns a new Date. */
+declare function add(date: Date, amount: number, unit?: "year" | "month" | "week" | "day" | "hour" | "minute" | "second"): Date;
+/** Shorthand for add(date, amount, "day"). */
+declare function addDays(date: Date, amount: number): Date;
+/** Difference between two dates in the given unit (truncated, integer). */
+declare function diff(a: Date, b: Date, unit?: "day" | "hour" | "minute" | "second"): number;
+/** Reset a date to 00:00:00.000 local time. */
+declare function startOfDay(date: Date): Date;
+/** Set a date to 23:59:59.999 local time. */
+declare function endOfDay(date: Date): Date;
+/** True if the two dates fall on the same calendar day. */
+declare function isSameDay(a: Date, b: Date): boolean;
+/** True if `date` is today. */
+declare function isToday(date: Date): boolean;
+/** True if `date` is within the current calendar week (Sun–Sat). */
+declare function isThisWeek(date: Date): boolean;
+/** Format a date as an ISO `YYYY-MM-DD` string (local time). */
+declare function toISODate(date: Date): string;
+/** Backward-compat default export name — returns the helper bag. */
+declare function date(): {
+    parseDate: typeof parseDate;
+    isValidDate: typeof isValidDate;
+    add: typeof add;
+    addDays: typeof addDays;
+    diff: typeof diff;
+    startOfDay: typeof startOfDay;
+    endOfDay: typeof endOfDay;
+    isSameDay: typeof isSameDay;
+    isToday: typeof isToday;
+    isThisWeek: typeof isThisWeek;
+    toISODate: typeof toISODate;
+};
+
+/**
+ * @module excel
+ * @category Utility
+ * @since 1.0.0-beta.0
+ * @description Spreadsheet helpers — CSV serialize/parse (RFC 4180 compliant) and a minimal XLSX (SpreadsheetML 2003 XML) generator for simple row data. No external dependency; for full XLSX read/write, integrate a peer dep like `exceljs`/`xlsx`.
+ * @example
+ * toCSV([{a:1,b:"hi"}]);          // "a,b\r\n1,hi\r\n"
+ * parseCSV("a,b\r\n1,hi\r\n");    // [{a:"1",b:"hi"}]
+ */
+interface CsvOptions {
+    delimiter?: string;
+    quote?: string;
+    newline?: string;
+    headers?: string[];
+}
+/** Serialize an array of row objects into a CSV string (BOM-free). */
+declare function toCSV(rows: Record<string, unknown>[], options?: CsvOptions): string;
+/** Parse a CSV string into an array of row objects (first row = headers). */
+declare function parseCSV(text: string, options?: CsvOptions): Record<string, string>[];
+/** A minimal XLSX (SpreadsheetML 2003 XML) string for a single sheet of row data. */
+declare function toSpreadsheetXml(rows: unknown[][], options?: {
+    sheetName?: string;
+}): string;
+/** Backward-compat default export name — returns the helper bag. */
+declare function excel(): {
+    toCSV: typeof toCSV;
+    parseCSV: typeof parseCSV;
+    toSpreadsheetXml: typeof toSpreadsheetXml;
+};
+
+/**
+ * @module pdf
+ * @category Utility
+ * @since 1.0.0-beta.0
+ * @description Minimal PDF helpers — builds a tiny valid single-page PDF document from plain text lines and renders an HTML print view. Not a full PDF engine; for rich layout integrate a peer dep like `pdfmake`/`@react-pdf/renderer`. The generated PDF uses the standard 14 font Helvetica.
+ * @example
+ * buildPdf("Report", ["Line one", "Line two"]);  // ArrayBuffer
+ * openPdf(buildPdf(...));                          // opens in a new tab
+ */
+/** Build a minimal one-page PDF document from a title and body lines. Returns a Uint8Array. */
+declare function buildPdf(title: string, lines?: string[]): Uint8Array;
+/** Build a PDF and open it in a new browser tab. No-op on the server. */
+declare function openPdf(bytes: Uint8Array): void;
+/** Build a PDF and trigger a download with the given filename. */
+declare function downloadPdf(bytes: Uint8Array, filename: string): void;
+/** Backward-compat default export name — returns the helper bag. */
+declare function pdf(): {
+    buildPdf: typeof buildPdf;
+    openPdf: typeof openPdf;
+    downloadPdf: typeof downloadPdf;
+};
+
+/**
+ * @module worker
+ * @category Utility
+ * @since 1.0.0-beta.0
+ * @description Web Worker helpers — create a worker from an inline function (no separate file needed), run a function off the main thread with a timeout, and a tiny pool for parallel map. Falls back to running synchronously on the main thread when Workers are unavailable (jsdom/SSR).
+ * @example
+ * const heavy = (n: number) => n * n;
+ * const result = await runInWorker(heavy, 5);  // 25
+ */
+/** Create a Web Worker from an inline function. Returns the Worker, or null if unsupported. */
+declare function createWorkerFromFn<T extends (...args: never[]) => unknown>(fn: T): Worker | null;
+/** Run a pure function off the main thread. Falls back to in-thread execution when Workers are unavailable. */
+declare function runInWorker<T extends (...args: never[]) => unknown>(fn: T, args: Parameters<T>, timeout?: number): Promise<ReturnType<T>>;
+/** Run a map over an array with up to `concurrency` workers in parallel. */
+declare function parallelMap<I, O>(items: I[], fn: (item: I, index: number) => O | Promise<O>, concurrency?: number): Promise<O[]>;
+/** Backward-compat default export name — returns the helper bag. */
+declare function worker(): {
+    createWorkerFromFn: typeof createWorkerFromFn;
+    runInWorker: typeof runInWorker;
+    parallelMap: typeof parallelMap;
+};
+
+export { type ApiClientConfig, type ApiError, ChaosI18nProvider, type CsvOptions, EventBus, type LogLevel, Modal, type ModalAlertOptions, type ModalConfirmOptions, type ModalKind, type Permission, type Role, type TreeNode, add, addDays, arrayToTree, buildPdf, chunk, cn, contrastRatio, cookie, countBy, createWorkerFromFn, crypto, cspHeaders, darken, date, diff, download, downloadPdf, endOfDay, eventBus, excel, findInTree, fromBase64, fromHex, generatePalette, getApiClient, getLeafNodes, getPathById, groupBy, hasAllPermissions, hasAnyPermission, hasPermission, hashFnv1a, hashString, hexToRgb, hslToRgb, isSameDay, isThisWeek, isToday, isValidDate, lighten, logger, luminance, meetsWCAGAA, openPdf, paginate, parallelMap, parseCSV, parseDate, patterns, pdf, randomBytes, randomColor, randomFloat, randomId, randomInt, randomPick, randomSample, randomString, randomToken, rgbToHex, rgbToHsl, runInWorker, safeRequest, sessionStorage, shuffle, sortBy, startOfDay, storage, subtle, toBase64, toCSV, toHex, toISODate, toSpreadsheetXml, treeToArray, unique, uniqueBy, uniqueSequence, url, uuid, validators, worker };