@lytjs/web 6.4.0

package/README.md

@@ -0,0 +1,179 @@
+# @lytjs/web
+
+> Web 平台工具包，提供 CSS 变量管理、ResizeObserver、Web Components 等 Web 特定功能
+
+## 安装
+
+```bash
+npm install @lytjs/web
+```
+
+## 核心功能
+
+### CSS 变量管理
+
+```typescript
+import { setCssVar, getCssVar, removeCssVar, setCssVars, watchCssVar } from '@lytjs/web';
+
+// 设置 CSS 变量
+setCssVar('--primary-color', '#1890ff');
+setCssVar('--font-size', '14px', document.documentElement);
+
+// 获取 CSS 变量
+const color = getCssVar('--primary-color');
+
+// 移除 CSS 变量
+removeCssVar('--primary-color');
+
+// 批量设置
+setCssVars({
+  '--primary-color': '#1890ff',
+  '--secondary-color': '#52c41a',
+  '--font-size': '14px',
+});
+
+// 监听 CSS 变量变化
+const unwatch = watchCssVar('--primary-color', (newVal, oldVal) => {
+  console.log('CSS 变量变化:', oldVal, '->', newVal);
+});
+```
+
+### ResizeObserver
+
+```typescript
+import { useResizeObserver, createResizeObserver, type ResizeObserverEntry } from '@lytjs/web';
+
+// 使用 ResizeObserver
+const cleanup = useResizeObserver(
+  document.getElementById('container'),
+  (entries: ResizeObserverEntry[]) => {
+    for (const entry of entries) {
+      console.log('尺寸变化:', entry.contentRect);
+    }
+  },
+);
+
+// 停止监听
+cleanup();
+
+// 创建可复用的 ResizeObserver
+const observer = createResizeObserver((entries) => {
+  // 处理尺寸变化
+});
+
+observer.observe(element1);
+observer.observe(element2);
+observer.disconnect();
+```
+
+### Web Components
+
+```typescript
+import {
+  defineLytElement,
+  useShadowRoot,
+  useHost,
+  useWebComponentSlots,
+  injectChildStyles,
+} from '@lytjs/web';
+
+// 定义 Web Component
+const MyElement = defineLytElement({
+  name: 'my-element',
+  props: {
+    title: String,
+    count: Number,
+  },
+  setup(props) {
+    const shadowRoot = useShadowRoot();
+    const host = useHost();
+    const slots = useWebComponentSlots();
+
+    return () => h('div', [h('h1', props.title), h('p', `Count: ${props.count}`), h('slot')]);
+  },
+});
+
+// 注册自定义元素
+customElements.define('my-element', MyElement);
+```
+
+### 媒体查询
+
+```typescript
+import { useMediaQuery, usePreferredColorScheme, usePreferredReducedMotion } from '@lytjs/web';
+
+// 响应式断点
+const isMobile = useMediaQuery('(max-width: 768px)');
+const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+const isDesktop = useMediaQuery('(min-width: 1025px)');
+
+// 系统主题偏好
+const colorScheme = usePreferredColorScheme(); // 'light' | 'dark'
+const reducedMotion = usePreferredReducedMotion(); // boolean
+```
+
+### 网络状态
+
+```typescript
+import { useOnline, useNetworkStatus } from '@lytjs/web';
+
+// 在线状态
+const isOnline = useOnline();
+
+// 详细网络状态
+const network = useNetworkStatus();
+// {
+//   online: boolean,
+//   type: 'wifi' | '4g' | '3g' | '2g' | 'slow-2g',
+//   downlink: number,
+//   rtt: number,
+// }
+```
+
+### 页面可见性
+
+```typescript
+import { usePageVisibility } from '@lytjs/web';
+
+const isVisible = usePageVisibility();
+
+// 页面可见性变化时
+if (isVisible) {
+  // 恢复动画、轮询等
+} else {
+  // 暂停动画、轮询等
+}
+```
+
+### 鼠标/触摸位置
+
+```typescript
+import { useMousePosition, useMouseInElement, useWindowScroll } from '@lytjs/web';
+
+// 鼠标位置
+const { x, y } = useMousePosition();
+
+// 元素内相对位置
+const { x: elX, y: elY, isOutside } = useMouseInElement(elementRef);
+
+// 窗口滚动
+const { x: scrollX, y: scrollY } = useWindowScroll();
+```
+
+## 类型定义
+
+```typescript
+import type {
+  ResizeObserverEntry,
+  ResizeObserverCallback,
+  LytElementOptions,
+  LytElementConstructor,
+  NetworkStatus,
+} from '@lytjs/web';
+```
+
+## 相关包
+
+- [@lytjs/core](../core) - 框架核心
+- [@lytjs/adapter-web](../adapter-web) - Web 平台适配器
+- [@lytjs/common-dom](../common/packages/dom) - DOM 工具

package/dist/index.cjs

@@ -0,0 +1,481 @@
+'use strict';
+
+// src/css-vars.ts
+function normalizeVarName(name) {
+  return name.startsWith("--") ? name : `--${name}`;
+}
+function stripVarPrefix(name) {
+  return name.startsWith("--") ? name.slice(2) : name;
+}
+function setCSSVar(paramsOrElement, name, value, options) {
+  let element;
+  let varName;
+  let varValue;
+  let opts;
+  if (paramsOrElement instanceof HTMLElement) {
+    element = paramsOrElement;
+    varName = normalizeVarName(name);
+    varValue = value;
+    opts = options;
+  } else if ("element" in paramsOrElement) {
+    element = paramsOrElement.element;
+    varName = normalizeVarName(paramsOrElement.name);
+    varValue = paramsOrElement.value;
+    opts = paramsOrElement.options;
+  } else {
+    element = document.documentElement;
+    varName = normalizeVarName(paramsOrElement.name);
+    varValue = paramsOrElement.value;
+    opts = paramsOrElement.options;
+  }
+  if (!element) return;
+  if (varValue === null || varValue === void 0) {
+    element.style.removeProperty(varName);
+    return;
+  }
+  let finalValue;
+  if (typeof varValue === "number") {
+    finalValue = opts?.unit ? `${varValue}${opts.unit}` : String(varValue);
+  } else {
+    finalValue = varValue;
+  }
+  element.style.setProperty(varName, finalValue);
+}
+function getCSSVar(elementOrName, nameOrFallback, fallback) {
+  let element;
+  let varName;
+  let defaultValue;
+  if (typeof elementOrName === "string") {
+    element = document.documentElement;
+    varName = normalizeVarName(elementOrName);
+    defaultValue = nameOrFallback;
+  } else {
+    element = elementOrName;
+    varName = normalizeVarName(nameOrFallback);
+    defaultValue = fallback;
+  }
+  if (!element) return defaultValue ?? null;
+  const inlineValue = element.style.getPropertyValue(varName);
+  if (inlineValue) return inlineValue;
+  const computedStyle = window.getComputedStyle(element);
+  const value = computedStyle.getPropertyValue(varName).trim();
+  return value || defaultValue || null;
+}
+function setCSSVars(elementOrVars, vars) {
+  let element;
+  let variables;
+  if (elementOrVars instanceof HTMLElement) {
+    element = elementOrVars;
+    variables = vars ?? {};
+  } else {
+    element = document.documentElement;
+    variables = elementOrVars;
+  }
+  if (!element) return;
+  Object.entries(variables).forEach(([name, value]) => {
+    setCSSVar(element, name, value);
+  });
+}
+function getCSSVars(elementOrNames, names) {
+  let element;
+  let varNames;
+  if (elementOrNames instanceof HTMLElement) {
+    element = elementOrNames;
+    varNames = names ?? [];
+  } else {
+    element = document.documentElement;
+    varNames = elementOrNames;
+  }
+  const result = {};
+  varNames.forEach((name) => {
+    result[name] = getCSSVar(element, name);
+  });
+  return result;
+}
+function removeCSSVar(elementOrName, name) {
+  let element;
+  let varName;
+  if (typeof elementOrName === "string") {
+    element = document.documentElement;
+    varName = normalizeVarName(elementOrName);
+  } else {
+    element = elementOrName;
+    varName = normalizeVarName(name);
+  }
+  if (!element) return;
+  element.style.removeProperty(varName);
+}
+function removeCSSVars(elementOrNames, names) {
+  let element;
+  let varNames;
+  if (elementOrNames instanceof HTMLElement) {
+    element = elementOrNames;
+    varNames = names ?? [];
+  } else {
+    element = document.documentElement;
+    varNames = elementOrNames;
+  }
+  if (!element) return;
+  varNames.forEach((name) => {
+    element.style.removeProperty(normalizeVarName(name));
+  });
+}
+function hasCSSVar(elementOrName, name) {
+  let element;
+  let varName;
+  if (typeof elementOrName === "string") {
+    element = document.documentElement;
+    varName = normalizeVarName(elementOrName);
+  } else {
+    element = elementOrName;
+    varName = normalizeVarName(name);
+  }
+  if (!element) return false;
+  if (element.style.getPropertyValue(varName)) return true;
+  const computedStyle = window.getComputedStyle(element);
+  return !!computedStyle.getPropertyValue(varName).trim();
+}
+function getAllCSSVars(element) {
+  const el = element ?? document.documentElement;
+  if (!el) return {};
+  const result = {};
+  const computedStyle = window.getComputedStyle(el);
+  for (let i = 0; i < computedStyle.length; i++) {
+    const prop = computedStyle[i];
+    if (prop.startsWith("--")) {
+      const value = computedStyle.getPropertyValue(prop).trim();
+      if (value) {
+        result[prop] = value;
+      }
+    }
+  }
+  return result;
+}
+function toggleCSSVar(elementOrName, nameOrValue1, value1OrValue2, value2) {
+  let element;
+  let varName;
+  let val1;
+  let val2;
+  if (typeof elementOrName === "string") {
+    element = document.documentElement;
+    varName = normalizeVarName(elementOrName);
+    val1 = nameOrValue1;
+    val2 = value1OrValue2;
+  } else {
+    element = elementOrName;
+    varName = normalizeVarName(nameOrValue1);
+    val1 = value1OrValue2;
+    val2 = value2;
+  }
+  const currentValue = getCSSVar(element, varName);
+  const newValue = currentValue === val1 ? val2 : val1;
+  setCSSVar(element, varName, newValue);
+  return newValue;
+}
+var _CSSVarObserver = class _CSSVarObserver {
+  constructor(element) {
+    this.observer = null;
+    this.callbacks = /* @__PURE__ */ new Map();
+    /**
+     * 检查变量变化
+     * FIX: P2-v11-37 添加最大条目限制，防止 lastValues Map 无限增长
+     */
+    this.lastValues = /* @__PURE__ */ new Map();
+    this.element = element ?? document.documentElement;
+  }
+  /**
+   * 开始观察 CSS 变量变化
+   *
+   * @param names - 要观察的变量名数组（可选，不指定则观察所有）
+   */
+  observe(names) {
+    if (this.observer) return;
+    const targetNames = names?.map(normalizeVarName);
+    this.observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.type === "attributes" && mutation.attributeName === "style") {
+          this.checkChanges(targetNames);
+        }
+      });
+    });
+    this.observer.observe(this.element, {
+      attributes: true,
+      attributeFilter: ["style"]
+    });
+  }
+  /**
+   * 停止观察
+   */
+  disconnect() {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+  /**
+   * 订阅变量变化
+   *
+   * @param name - 变量名
+   * @param callback - 变化回调
+   * @returns 取消订阅函数
+   */
+  subscribe(name, callback) {
+    const varName = normalizeVarName(name);
+    if (!this.callbacks.has(varName)) {
+      this.callbacks.set(varName, /* @__PURE__ */ new Set());
+    }
+    this.callbacks.get(varName).add(callback);
+    return () => {
+      this.callbacks.get(varName)?.delete(callback);
+    };
+  }
+  checkChanges(targetNames) {
+    const namesToCheck = targetNames ?? Array.from(this.callbacks.keys());
+    if (this.lastValues.size > _CSSVarObserver.MAX_LAST_VALUES_SIZE) {
+      const activeNames = new Set(this.callbacks.keys());
+      for (const key of this.lastValues.keys()) {
+        if (!activeNames.has(key)) {
+          this.lastValues.delete(key);
+        }
+      }
+    }
+    namesToCheck.forEach((name) => {
+      const currentValue = getCSSVar(this.element, name);
+      const lastValue = this.lastValues.get(name);
+      if (currentValue !== lastValue) {
+        this.lastValues.set(name, currentValue);
+        const callbacks = this.callbacks.get(name);
+        if (callbacks) {
+          callbacks.forEach((cb) => cb(currentValue, lastValue ?? null, name));
+        }
+      }
+    });
+  }
+};
+/** lastValues 最大条目数 */
+_CSSVarObserver.MAX_LAST_VALUES_SIZE = 500;
+var CSSVarObserver = _CSSVarObserver;
+var ThemeManager = class {
+  constructor(element) {
+    this.themes = /* @__PURE__ */ new Map();
+    this.currentTheme = null;
+    this.element = element ?? document.documentElement;
+  }
+  /**
+   * 注册主题
+   *
+   * @param name - 主题名称
+   * @param config - 主题配置（CSS 变量键值对）
+   */
+  register(name, config) {
+    this.themes.set(name, config);
+  }
+  /**
+   * 应用主题
+   *
+   * @param name - 主题名称
+   */
+  apply(name) {
+    const theme = this.themes.get(name);
+    if (!theme) return false;
+    setCSSVars(this.element, theme);
+    this.currentTheme = name;
+    this.element.setAttribute("data-theme", name);
+    return true;
+  }
+  /**
+   * 获取当前主题名称
+   */
+  getCurrentTheme() {
+    return this.currentTheme;
+  }
+  /**
+   * 获取已注册的主题列表
+   */
+  getRegisteredThemes() {
+    return Array.from(this.themes.keys());
+  }
+  /**
+   * 检查主题是否存在
+   */
+  hasTheme(name) {
+    return this.themes.has(name);
+  }
+  /**
+   * 获取主题配置
+   */
+  getThemeConfig(name) {
+    return this.themes.get(name);
+  }
+};
+
+// src/resize-observer.ts
+exports.ResizeObserverManager = class ResizeObserverManager {
+  constructor(callback) {
+    this.observer = null;
+    this.observedElements = /* @__PURE__ */ new Set();
+    this.isConnected = false;
+    this.callback = callback;
+    if (typeof ResizeObserver === "undefined") {
+      if (__DEV__) {
+        console.warn(
+          "[lytjs/resize-observer] ResizeObserver is not supported in this environment."
+        );
+      }
+      return;
+    }
+    this.observer = new ResizeObserver((entries) => {
+      const activeEntries = entries.filter((entry) => this.observedElements.has(entry.target));
+      if (activeEntries.length > 0) {
+        this.callback(activeEntries);
+      }
+    });
+  }
+  /**
+   * 开始观察元素
+   *
+   * @param target - 要观察的目标元素
+   * @param options - 观察选项
+   * @returns 是否成功开始观察
+   */
+  observe(target, options) {
+    if (!this.observer) {
+      if (__DEV__) {
+        console.warn("[lytjs/resize-observer] Cannot observe: ResizeObserver is not available.");
+      }
+      return false;
+    }
+    if (this.observedElements.has(target)) {
+      if (__DEV__) {
+        console.warn("[lytjs/resize-observer] Element is already being observed.");
+      }
+      return false;
+    }
+    try {
+      this.observer.observe(target, options);
+      this.observedElements.add(target);
+      this.isConnected = true;
+      return true;
+    } catch (err) {
+      if (__DEV__) {
+        console.error("[lytjs/resize-observer] Error observing element:", err);
+      }
+      return false;
+    }
+  }
+  /**
+   * 停止观察指定元素
+   *
+   * @param target - 要停止观察的目标元素
+   * @returns 是否成功停止观察
+   */
+  unobserve(target) {
+    if (!this.observer) {
+      return false;
+    }
+    if (!this.observedElements.has(target)) {
+      return false;
+    }
+    try {
+      this.observer.unobserve(target);
+      this.observedElements.delete(target);
+      if (this.observedElements.size === 0) {
+        this.isConnected = false;
+      }
+      return true;
+    } catch (err) {
+      if (__DEV__) {
+        console.error("[lytjs/resize-observer] Error unobserving element:", err);
+      }
+      return false;
+    }
+  }
+  /**
+   * 停止观察所有元素并断开连接
+   *
+   * FIX: P2-5 这是关键方法，确保在组件卸载时调用此方法
+   */
+  disconnect() {
+    if (!this.observer) {
+      return;
+    }
+    try {
+      this.observer.disconnect();
+      this.observedElements.clear();
+      this.isConnected = false;
+    } catch (err) {
+      if (__DEV__) {
+        console.error("[lytjs/resize-observer] Error disconnecting observer:", err);
+      }
+    }
+  }
+  /**
+   * 检查是否正在观察指定元素
+   *
+   * @param target - 要检查的目标元素
+   * @returns 是否正在观察
+   */
+  isObserving(target) {
+    return this.observedElements.has(target);
+  }
+  /**
+   * 获取当前观察的元素数量
+   */
+  get observedCount() {
+    return this.observedElements.size;
+  }
+  /**
+   * 检查观察者是否已连接（正在观察至少一个元素）
+   */
+  get connected() {
+    return this.isConnected;
+  }
+  /**
+   * 检查 ResizeObserver 是否可用
+   */
+  get isAvailable() {
+    return this.observer !== null;
+  }
+};
+function useResizeObserver(target, callback, options) {
+  const manager = new exports.ResizeObserverManager(callback);
+  manager.observe(target, options);
+  return () => {
+    manager.disconnect();
+  };
+}
+function supportsResizeObserver() {
+  return typeof ResizeObserver !== "undefined";
+}
+if (__DEV__) {
+  const managerRegistry = /* @__PURE__ */ new WeakSet();
+  const OriginalManager = exports.ResizeObserverManager;
+  exports.ResizeObserverManager = class extends OriginalManager {
+    constructor(callback) {
+      super(callback);
+      managerRegistry.add(this);
+    }
+  };
+  globalThis.__getResizeObserverStats = () => {
+    return {
+      activeManagers: 0,
+      totalObservedElements: 0
+    };
+  };
+}
+
+exports.CSSVarObserver = CSSVarObserver;
+exports.ThemeManager = ThemeManager;
+exports.getAllCSSVars = getAllCSSVars;
+exports.getCSSVar = getCSSVar;
+exports.getCSSVars = getCSSVars;
+exports.hasCSSVar = hasCSSVar;
+exports.normalizeVarName = normalizeVarName;
+exports.removeCSSVar = removeCSSVar;
+exports.removeCSSVars = removeCSSVars;
+exports.setCSSVar = setCSSVar;
+exports.setCSSVars = setCSSVars;
+exports.stripVarPrefix = stripVarPrefix;
+exports.supportsResizeObserver = supportsResizeObserver;
+exports.toggleCSSVar = toggleCSSVar;
+exports.useResizeObserver = useResizeObserver;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map