@lytjs/web 6.4.0

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+/**
+ * @lytjs/web - CSS 变量支持模块
+ *
+ * 提供增强的 CSS 自定义属性（CSS Variables）支持，
+ * 包括设置、获取、监听 CSS 变量变化等功能
+ *
+ * @module @lytjs/web/css-vars
+ * @version 6.0.0
+ */
+/**
+ * CSS 变量值类型
+ */
+type CSSVarValue = string | number | null | undefined;
+/**
+ * CSS 变量变更回调
+ */
+type CSSVarChangeCallback = (newValue: string | null, oldValue: string | null, variable: string) => void;
+/**
+ * CSS 变量配置选项
+ */
+interface CSSVarOptions {
+    /** 是否继承父元素的值 */
+    inherit?: boolean;
+    /** 单位（用于数值类型） */
+    unit?: string;
+}
+/**
+ * 规范化 CSS 变量名
+ * 确保变量名以 -- 开头
+ *
+ * @param name - 变量名（可带或不带 -- 前缀）
+ * @returns 规范化后的变量名
+ * @example
+ * ```ts
+ * normalizeVarName('primary-color') // '--primary-color'
+ * normalizeVarName('--primary-color') // '--primary-color'
+ * ```
+ */
+declare function normalizeVarName(name: string): string;
+/**
+ * 移除 CSS 变量名的 -- 前缀
+ *
+ * @param name - 变量名
+ * @returns 无前缀的变量名
+ * @example
+ * ```ts
+ * stripVarPrefix('--primary-color') // 'primary-color'
+ * stripVarPrefix('primary-color') // 'primary-color'
+ * ```
+ */
+declare function stripVarPrefix(name: string): string;
+/**
+ * setCSSVar 参数对象 - 指定元素上的 CSS 变量
+ */
+interface SetCSSVarWithElementOptions {
+    /** 目标元素 */
+    element: HTMLElement;
+    /** 变量名 */
+    name: string;
+    /** 变量值（null/undefined 表示移除） */
+    value?: CSSVarValue;
+    /** 配置选项 */
+    options?: CSSVarOptions;
+}
+/**
+ * setCSSVar 参数对象 - 全局 CSS 变量
+ */
+interface SetCSSVarGlobalOptions {
+    /** 变量名 */
+    name: string;
+    /** 变量值（null/undefined 表示移除） */
+    value?: CSSVarValue;
+    /** 配置选项 */
+    options?: CSSVarOptions;
+}
+/**
+ * 设置 CSS 变量
+ *
+ * @param params - 参数对象
+ * @example
+ * ```ts
+ * // 设置全局变量
+ * setCSSVar({ name: '--primary-color', value: '#007bff' })
+ *
+ * // 设置元素变量
+ * setCSSVar({ element: myElement, name: 'font-size', value: 16, options: { unit: 'px' } })
+ *
+ * // 移除变量
+ * setCSSVar({ element: myElement, name: '--old-var', value: null })
+ * ```
+ */
+declare function setCSSVar(params: SetCSSVarWithElementOptions): void;
+declare function setCSSVar(params: SetCSSVarGlobalOptions): void;
+/** @deprecated 使用对象参数形式 setCSSVar({ element, name, value }) 替代 */
+declare function setCSSVar(element: HTMLElement, name: string, value?: CSSVarValue, options?: CSSVarOptions): void;
+/**
+ * 获取 CSS 变量值
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @param name - 变量名
+ * @param fallback - 默认值（变量不存在时返回）
+ * @returns 变量值或默认值
+ * @example
+ * ```ts
+ * // 获取全局变量
+ * const color = getCSSVar('--primary-color')
+ *
+ * // 获取元素变量
+ * const size = getCSSVar(myElement, 'font-size', '16px')
+ * ```
+ */
+declare function getCSSVar(name: string, fallback?: string): string | null;
+declare function getCSSVar(element: HTMLElement, name: string, fallback?: string): string | null;
+/**
+ * 批量设置 CSS 变量
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @param vars - 变量键值对对象
+ * @example
+ * ```ts
+ * setCSSVars({
+ *   '--primary-color': '#007bff',
+ *   '--font-size': '16px',
+ *   '--spacing': 8,
+ * })
+ * ```
+ */
+declare function setCSSVars(vars: Record<string, CSSVarValue>): void;
+declare function setCSSVars(element: HTMLElement, vars: Record<string, CSSVarValue>): void;
+/**
+ * 批量获取 CSS 变量
+ *
+ * @param names - 变量名数组
+ * @returns 变量值对象
+ * @example
+ * ```ts
+ * const values = getCSSVars(['--primary-color', '--font-size'])
+ * // { '--primary-color': '#007bff', '--font-size': '16px' }
+ * ```
+ */
+declare function getCSSVars(names: string[]): Record<string, string | null>;
+declare function getCSSVars(element: HTMLElement, names: string[]): Record<string, string | null>;
+/**
+ * 移除 CSS 变量
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @param name - 变量名
+ * @example
+ * ```ts
+ * removeCSSVar('--old-variable')
+ * removeCSSVar(myElement, '--old-variable')
+ * ```
+ */
+declare function removeCSSVar(name: string): void;
+declare function removeCSSVar(element: HTMLElement, name: string): void;
+/**
+ * 批量移除 CSS 变量
+ *
+ * @param names - 变量名数组
+ * @example
+ * ```ts
+ * removeCSSVars(['--var1', '--var2'])
+ * ```
+ */
+declare function removeCSSVars(names: string[]): void;
+declare function removeCSSVars(element: HTMLElement, names: string[]): void;
+/**
+ * 检查元素是否有指定的 CSS 变量
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @param name - 变量名
+ * @returns 如果变量存在则返回 true
+ * @example
+ * ```ts
+ * if (hasCSSVar('--primary-color')) {
+ *   // 变量存在
+ * }
+ * ```
+ */
+declare function hasCSSVar(name: string): boolean;
+declare function hasCSSVar(element: HTMLElement, name: string): boolean;
+/**
+ * 获取元素上定义的所有 CSS 变量
+ *
+ * 注意：此方法通过遍历 computedStyle 的所有属性来查找 CSS 变量，
+ * 在属性数量较多的元素上可能存在性能开销。
+ * computedStyle.length 通常在数百到数千之间，遍历是 O(n) 操作。
+ * 建议仅在调试或初始化时调用，避免在热路径中频繁使用。
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @returns CSS 变量键值对
+ * @example
+ * ```ts
+ * const vars = getAllCSSVars()
+ * // { '--primary-color': '#007bff', '--font-size': '16px', ... }
+ * ```
+ */
+declare function getAllCSSVars(element?: HTMLElement): Record<string, string>;
+/**
+ * 切换 CSS 变量的值（在两个值之间切换）
+ *
+ * @param element - 目标元素（默认为 document.documentElement）
+ * @param name - 变量名
+ * @param value1 - 第一个值
+ * @param value2 - 第二个值
+ * @returns 切换后的值
+ * @example
+ * ```ts
+ * // 在 'dark' 和 'light' 之间切换主题
+ * toggleCSSVar('--theme', 'dark', 'light')
+ * ```
+ */
+declare function toggleCSSVar(name: string, value1: string, value2: string): string;
+declare function toggleCSSVar(element: HTMLElement, name: string, value1: string, value2: string): string;
+/**
+ * CSS 变量观察器
+ * 用于监听 CSS 变量的变化
+ */
+declare class CSSVarObserver {
+    private observer;
+    private callbacks;
+    private element;
+    constructor(element?: HTMLElement);
+    /**
+     * 开始观察 CSS 变量变化
+     *
+     * @param names - 要观察的变量名数组（可选，不指定则观察所有）
+     */
+    observe(names?: string[]): void;
+    /**
+     * 停止观察
+     */
+    disconnect(): void;
+    /**
+     * 订阅变量变化
+     *
+     * @param name - 变量名
+     * @param callback - 变化回调
+     * @returns 取消订阅函数
+     */
+    subscribe(name: string, callback: CSSVarChangeCallback): () => void;
+    /**
+     * 检查变量变化
+     * FIX: P2-v11-37 添加最大条目限制，防止 lastValues Map 无限增长
+     */
+    private lastValues;
+    /** lastValues 最大条目数 */
+    private static readonly MAX_LAST_VALUES_SIZE;
+    private checkChanges;
+}
+/**
+ * 主题配置
+ */
+interface ThemeConfig {
+    [key: string]: CSSVarValue;
+}
+/**
+ * 主题管理器
+ * 用于管理多主题切换
+ */
+declare class ThemeManager {
+    private themes;
+    private currentTheme;
+    private element;
+    constructor(element?: HTMLElement);
+    /**
+     * 注册主题
+     *
+     * @param name - 主题名称
+     * @param config - 主题配置（CSS 变量键值对）
+     */
+    register(name: string, config: ThemeConfig): void;
+    /**
+     * 应用主题
+     *
+     * @param name - 主题名称
+     */
+    apply(name: string): boolean;
+    /**
+     * 获取当前主题名称
+     */
+    getCurrentTheme(): string | null;
+    /**
+     * 获取已注册的主题列表
+     */
+    getRegisteredThemes(): string[];
+    /**
+     * 检查主题是否存在
+     */
+    hasTheme(name: string): boolean;
+    /**
+     * 获取主题配置
+     */
+    getThemeConfig(name: string): ThemeConfig | undefined;
+}
+
+/**
+ * @lytjs/web - ResizeObserver 管理模块
+ *
+ * 提供 ResizeObserver 的安全封装，确保在组件卸载时自动清理观察者，
+ * 防止内存泄漏。
+ * FIX: P2-5 ResizeObserver 未清理问题
+ *
+ * @module @lytjs/web/resize-observer
+ * @version 6.0.0
+ */
+/**
+ * ResizeObserver 回调函数类型
+ */
+type ResizeObserverCallback = (entries: ResizeObserverEntry[]) => void;
+/**
+ * ResizeObserver 观察选项
+ */
+interface ResizeObserverOptions {
+    /** 指定要观察的盒模型 */
+    box?: 'content-box' | 'border-box' | 'device-pixel-content-box';
+}
+/**
+ * 受管理的 ResizeObserver 包装类
+ *
+ * 自动处理 ResizeObserver 的创建、观察和清理，
+ * 确保在组件卸载时不会泄漏观察者。
+ *
+ * FIX: P2-5 ResizeObserver 未清理问题
+ *
+ * @example
+ * ```ts
+ * // 创建管理器
+ * const manager = new ResizeObserverManager((entries) => {
+ *   for (const entry of entries) {
+ *     console.log('Element resized:', entry.target);
+ *   }
+ * });
+ *
+ * // 观察元素
+ * manager.observe(myElement);
+ *
+ * // 组件卸载时清理
+ * onUnmounted(() => {
+ *   manager.disconnect();
+ * });
+ * ```
+ */
+declare class ResizeObserverManager {
+    private observer;
+    private callback;
+    private observedElements;
+    private isConnected;
+    constructor(callback: ResizeObserverCallback);
+    /**
+     * 开始观察元素
+     *
+     * @param target - 要观察的目标元素
+     * @param options - 观察选项
+     * @returns 是否成功开始观察
+     */
+    observe(target: Element, options?: ResizeObserverOptions): boolean;
+    /**
+     * 停止观察指定元素
+     *
+     * @param target - 要停止观察的目标元素
+     * @returns 是否成功停止观察
+     */
+    unobserve(target: Element): boolean;
+    /**
+     * 停止观察所有元素并断开连接
+     *
+     * FIX: P2-5 这是关键方法，确保在组件卸载时调用此方法
+     */
+    disconnect(): void;
+    /**
+     * 检查是否正在观察指定元素
+     *
+     * @param target - 要检查的目标元素
+     * @returns 是否正在观察
+     */
+    isObserving(target: Element): boolean;
+    /**
+     * 获取当前观察的元素数量
+     */
+    get observedCount(): number;
+    /**
+     * 检查观察者是否已连接（正在观察至少一个元素）
+     */
+    get connected(): boolean;
+    /**
+     * 检查 ResizeObserver 是否可用
+     */
+    get isAvailable(): boolean;
+}
+/**
+ * 创建并使用 ResizeObserver，返回清理函数
+ *
+ * 这是使用 ResizeObserver 的推荐方式，确保在组件卸载时调用返回的清理函数。
+ *
+ * FIX: P2-5 ResizeObserver 未清理问题
+ *
+ * @example
+ * ```ts
+ * // 在组件中使用
+ * const cleanup = useResizeObserver(myElement, (entries) => {
+ *   for (const entry of entries) {
+ *     console.log('Resized:', entry.contentRect);
+ *   }
+ * });
+ *
+ * // 组件卸载时清理
+ * onUnmounted(() => {
+ *   cleanup();
+ * });
+ * ```
+ *
+ * @param target - 要观察的目标元素
+ * @param callback - 尺寸变化回调
+ * @param options - 观察选项
+ * @returns 清理函数，调用后停止观察并释放资源
+ */
+declare function useResizeObserver(target: Element, callback: ResizeObserverCallback, options?: ResizeObserverOptions): () => void;
+/**
+ * 检查浏览器是否支持 ResizeObserver
+ *
+ * @returns 如果支持则返回 true
+ */
+declare function supportsResizeObserver(): boolean;
+/**
+ * ResizeObserver 统计信息
+ */
+interface ResizeObserverStats {
+    /** 活跃的管理器数量 */
+    activeManagers: number;
+    /** 总共观察的元素数量 */
+    totalObservedElements: number;
+}
+
+export { type CSSVarChangeCallback, CSSVarObserver, type CSSVarOptions, type CSSVarValue, type ResizeObserverCallback, ResizeObserverManager, type ResizeObserverOptions, type ResizeObserverStats, type ThemeConfig, ThemeManager, getAllCSSVars, getCSSVar, getCSSVars, hasCSSVar, normalizeVarName, removeCSSVar, removeCSSVars, setCSSVar, setCSSVars, stripVarPrefix, supportsResizeObserver, toggleCSSVar, useResizeObserver };