vanilla-jui 1.4.5 → 1.4.6

package/src/utilities/browser.ts

@@ -4,8 +4,11 @@ declare global {
       mobile: boolean;
       brands: Array<{ brand: string; version: string }>;
       platform: string;
-      getHighEntropyValues: (hints: string[]) => Promise<any>;
+      getHighEntropyValues: (
+        hints: string[]
+      ) => Promise<Record<string, unknown>>;
     };
+    msMaxTouchPoints?: number;
   }
   interface Window {
     opera?: string;
@@ -13,64 +16,35 @@ declare global {
 }
 
 /**
- * 判断当前环境是否为移动设备。
- * @returns {boolean}
+ * 采用 MDN 推荐的组合策略：特性检测优先，UA 嗅探兜底
  */
 export function isMobile(): boolean {
-  if (typeof window === 'undefined' || typeof navigator === 'undefined') {
-    return false;
-  }
+  if (typeof navigator === 'undefined') return false;
 
-  // 1. 优先使用现代 Client Hints API
-  if (
-    navigator.userAgentData &&
-    typeof navigator.userAgentData.mobile === 'boolean'
-  ) {
+  if (typeof navigator.userAgentData?.mobile === 'boolean') {
     return navigator.userAgentData.mobile;
   }
 
-  // 提取 UA 字符串并做安全处理
-  const ua = navigator.userAgent || navigator.vendor || window.opera || '';
-
-  // 2. 核心 UA 正则匹配
-  const mobileUaRegex =
-    /Android|iPhone|iPad|iPod|Mobile|Windows Phone|webOS|BlackBerry|IEMobile|Opera Mini/i;
-  const isMobileUa = mobileUaRegex.test(ua);
-
-  // 3. 排除平板设备 (Tablet)
-  const isTabletUa = /iPad|Android(?!.*Mobile)|Tablet/i.test(ua);
-
-  // 4. 综合判定逻辑（针对 iOS 和 Android 分别处理）
-  if (isMobileUa && !isTabletUa) {
-    // 对于 iOS 设备，UA 匹配通常足够
-    if (
-      /iPhone|iPod|Windows Phone|webOS|BlackBerry|IEMobile|Opera Mini/i.test(ua)
-    ) {
-      return true;
-    }
-    // Android 设备需结合屏幕尺寸或触摸能力，避免大屏安卓平板被误判
-    if (/Android/i.test(ua)) {
-      const hasTouchSupport =
-        'maxTouchPoints' in navigator
-          ? navigator.maxTouchPoints > 0
-          : 'ontouchstart' in window;
-      const screenWidth = Math.min(window.screen.width, window.screen.height);
-      return screenWidth <= 768 || hasTouchSupport;
-    }
+  const ua = navigator.userAgent || '';
+  if (
+    /\b(BlackBerry|webOS|iPhone|IEMobile|Android|Windows Phone|iPad|iPod)\b/i.test(
+      ua
+    )
+  ) {
+    return true;
   }
 
-  // 5. 针对 iOS 13+ iPad 伪装成 Mac 的特殊兜底
-  const isLikelyIPad = /Macintosh|MacIntel/i.test(ua);
-  if (isLikelyIPad) {
-    const hasTouchSupport =
-      'maxTouchPoints' in navigator
-        ? navigator.maxTouchPoints > 0
-        : 'ontouchstart' in window;
-    const screenWidth = Math.min(window.screen.width, window.screen.height);
-    return hasTouchSupport && screenWidth <= 768;
+  if (
+    typeof window === 'undefined' ||
+    typeof window.matchMedia !== 'function'
+  ) {
+    return false;
   }
 
-  return false;
+  return (
+    window.matchMedia('(pointer: coarse)').matches &&
+    window.matchMedia('(max-width: 820px)').matches
+  );
 }
 
 /**

package/src/utilities/class-name.ts

@@ -0,0 +1,5 @@
+export type ClassNameToken = string | false | null | undefined;
+
+export function joinClasses(...tokens: ClassNameToken[]): string {
+  return tokens.filter(Boolean).join(' ');
+}

package/src/utilities/dom.ts

@@ -1,6 +1,8 @@
-import { jsx } from 'vanilla-signal';
-
-import { icon } from '../components/icons';
+import {
+  isDomElementValue,
+  isDomNodeValue,
+  isRenderableValue,
+} from './types.ts';
 
 export type ContainerExpect = 'node' | 'element' | 'array';
 export type ResolveContainerResult<
@@ -49,7 +51,7 @@ function isContainerExpect(value: unknown): value is ContainerExpect {
  * @returns {boolean}
  */
 export function isNode(value: unknown): value is Node {
-  return value instanceof Node;
+  return isDomNodeValue(value);
 }
 
 /**
@@ -58,7 +60,7 @@ export function isNode(value: unknown): value is Node {
  * @returns {boolean}
  */
 export function isElement(value: unknown): value is Element {
-  return value instanceof Element;
+  return isDomElementValue(value);
 }
 
 /**
@@ -294,35 +296,15 @@ export function requireContainer<TExpect extends ContainerExpect = 'element'>(
 export function isRenderableContent(
   value: unknown
 ): value is RenderableContent {
-  return (
-    value == null ||
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean' ||
-    typeof value === 'function' ||
-    Array.isArray(value) ||
-    isNode(value)
-  );
+  return isRenderableValue(value);
 }
 
-/**
- * 创建通用加载状态节点。
- * @returns {HTMLElement}
- */
-export function createLoading(): HTMLDivElement {
-  return jsx('div', {
-    'aria-live': 'polite',
-    style: {
-      display: 'flex',
-      justifyContent: 'center',
-      alignItems: 'center',
-      position: 'absolute',
-      width: '100%',
-      height: '100%',
-      backdropFilter: 'blur(4px)',
-    },
-    children: icon('loader', { width: 24, className: 'animate-spin' }),
-  });
+export function normalizeRenderableContentNodes<TContext>(
+  content: unknown,
+  context: TContext
+): Node[] | null {
+  if (!isRenderableContent(content)) return null;
+  return normalizeContentNodes(content, context);
 }
 
 /**

package/src/utilities/function.ts

@@ -0,0 +1,4 @@
+export { default as debounce } from 'lodash-es/debounce.js';
+export { default as throttle } from 'lodash-es/throttle.js';
+export type { DebouncedFunc, DebounceSettings } from 'lodash-es/debounce.js';
+export type { ThrottleSettings } from 'lodash-es/throttle.js';

package/src/utilities/http.ts

@@ -1,3 +1,10 @@
+/**
+ * 当前站点 WordPress REST API 根地址。
+ * @type {string}
+ */
+export const restUrl: string =
+  typeof window !== 'undefined' ? `${window.location.origin}/wp-json` : '';
+
 /**
  * 发送 JSON POST 请求并解析 JSON 响应。
  * @template T - 期望返回的 JSON 数据类型
@@ -26,10 +33,3 @@ export async function postJson<T = unknown>(
 
   return res.json() as Promise<T>;
 }
-
-/**
- * 当前站点 WordPress REST API 根地址。
- * @type {string}
- */
-export const restUrl: string =
-  typeof window !== 'undefined' ? `${window.location.origin}/wp-json` : '';

package/src/utilities/id.ts

@@ -0,0 +1,57 @@
+/**
+ * 生成标准 UUID v4 字符串。
+ *
+ * 优先使用浏览器原生的 crypto.randomUUID()，
+ * 不支持时使用 polyfill 实现。
+ *
+ * @returns UUID v4 字符串（如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）
+ */
+export function uuid(): string {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto.getRandomValues !== 'function') {
+    throw new Error('Your browser is too old to support secure login.');
+  }
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+}
+
+/**
+ * 生成适合 DOM id 的随机字符串。
+ *
+ * 使用安全的随机数生成器，生成的字符串适合作为 HTML 元素的 id 属性。
+ *
+ * @param [length=8] - 字符串长度，范围 1 到 87381
+ * @returns 随机字符串
+ * @throws {Error} 长度不在有效范围内时抛出错误
+ */
+export function randomId(length: number = 8): string {
+  if (!Number.isInteger(length) || length < 1 || length > 87381) {
+    throw new Error('Length must be an integer between 1 and 87381');
+  }
+
+  const byteLength = Math.ceil((length * 3) / 4);
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  const base64 = btoa(binary);
+
+  return base64.substring(0, length).replace(/\+/g, '-').replace(/\//g, '_');
+}

package/src/utilities/object.ts

@@ -0,0 +1,5 @@
+import _isPlainObject from 'lodash-es/isPlainObject.js';
+
+export function isPlainObject(obj: unknown): boolean {
+  return _isPlainObject(obj);
+}

package/src/utilities/timer.ts

@@ -0,0 +1,38 @@
+/**
+ * 定时器管理器
+ */
+export const timer = {
+  // 存储定时器 { key: timerId }
+  timers: {} as Record<string, ReturnType<typeof setTimeout>>,
+
+  /**
+   * 注册并开始一个定时器
+   * @param {string} key - 定时器的唯一标识
+   * @param {number} duration - 延迟执行的时间（毫秒）
+   * @param {function} callback - 延迟执行的回调函数
+   */
+  start(key: string, duration: number, callback: () => void) {
+    // 1. 如果该 key 已经存在，先清除旧的定时器，防止重复触发
+    if (this.timers[key]) {
+      clearTimeout(this.timers[key]);
+    }
+    // 2. 设置新的定时器，并保存其 ID
+    this.timers[key] = setTimeout(() => {
+      callback();
+      // 3. 执行完毕后，自动从管理器中注销该定时器
+      delete this.timers[key];
+    }, duration);
+  },
+
+  /**
+   * 明确注销一个定时器
+   * @param {string} key - 需要取消的定时器唯一标识
+   */
+  cancel(key: string) {
+    if (this.timers[key]) {
+      clearTimeout(this.timers[key]);
+      // 从管理器中移除该记录
+      delete this.timers[key];
+    }
+  },
+};