vanilla-jui 1.3.10 → 1.4.0

package/src/utilities/dom.ts

@@ -0,0 +1,468 @@
+import { jsx } from 'vanilla-signal';
+
+import { icon } from '../components/icons';
+
+export type ContainerExpect = 'node' | 'element' | 'array';
+export type ResolveContainerResult<
+  TExpect extends ContainerExpect = 'element',
+> = TExpect extends 'array' ? Node[] : TExpect extends 'node' ? Node : Element;
+export type RequireContainerResult<
+  TExpect extends ContainerExpect = 'element',
+> = NonNullable<ResolveContainerResult<TExpect>>;
+export type DOMReference =
+  | Node
+  | string
+  | readonly DOMReference[]
+  | false
+  | null
+  | undefined;
+export type QueryContext = Document | DocumentFragment | Element;
+export type CleanupFunction = () => void;
+export type LazyRenderTarget = string | Element;
+export type LazyRenderCallback = () => void;
+export type RenderableContent<TContext = unknown> =
+  | Node
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly RenderableContent<TContext>[]
+  | ((context: TContext) => RenderableContent<TContext>);
+
+export interface LazyRenderOptions {
+  threshold?: number | number[];
+  rootMargin?: string;
+  root?: Element | Document | null;
+  waitForDOM?: boolean;
+}
+
+const CONTAINER_EXPECTS = ['node', 'element', 'array'] as const;
+
+function isContainerExpect(value: unknown): value is ContainerExpect {
+  return CONTAINER_EXPECTS.includes(value as ContainerExpect);
+}
+
+/**
+ * 判断是否为 DOM Node。
+ * @param {*} value 需要判断的值。
+ * @returns {boolean}
+ */
+export function isNode(value: unknown): value is Node {
+  return value instanceof Node;
+}
+
+/**
+ * 判断是否为 DOM Element。
+ * @param {*} value 需要判断的值。
+ * @returns {boolean}
+ */
+export function isElement(value: unknown): value is Element {
+  return value instanceof Element;
+}
+
+/**
+ * 判断值是否为可接受的容器输入。
+ * @param {*} value 需要判断的值。
+ * @returns {boolean}
+ */
+function isContainerLike(
+  value: unknown
+): value is string | Node | readonly DOMReference[] {
+  return (
+    typeof value === 'string' ||
+    isElement(value) ||
+    isNode(value) ||
+    Array.isArray(value)
+  );
+}
+
+function firstElement(nodes: readonly Node[]): Element | null {
+  return nodes.find(isElement) || null;
+}
+
+function flattenNodeArray(
+  value: readonly DOMReference[],
+  out: Node[] = []
+): Node[] | null {
+  for (const item of value) {
+    if (Array.isArray(item)) {
+      if (!flattenNodeArray(item, out)) return null;
+      continue;
+    }
+
+    if (isNode(item)) {
+      out.push(item);
+      continue;
+    }
+
+    return null;
+  }
+
+  return out;
+}
+
+/**
+ * 将可渲染内容归一化为 DOM 节点数组。
+ *
+ * 支持的输入类型：
+ * - **Node/Element**: 包装为单元素数组
+ * - **string**: 按 HTML 片段解析为节点数组
+ * - **number/boolean**: 转换为文本节点
+ * - **Array**: 递归扁平化处理
+ * - **Function**: 调用后递归处理返回值
+ * - **null/undefined/false/true**: 返回空数组
+ *
+ * @param {RenderableContent<TContext>} content 可渲染内容。
+ * @param {TContext} [context] 传递给函数类型内容的上下文。
+ * @returns {Node[]} 归一化后的节点数组。
+ */
+export function normalizeContentNodes<TContext = unknown>(
+  content: RenderableContent<TContext>,
+  context?: TContext
+): Node[] {
+  if (typeof content === 'function') {
+    return normalizeContentNodes(content(context as TContext), context);
+  }
+
+  const value = content;
+
+  if (value == null || value === false || value === true) return [];
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => normalizeContentNodes(item, context));
+  }
+
+  if (isNode(value)) return [value];
+
+  if (typeof value === 'string') {
+    const template = document.createElement('template');
+    template.innerHTML = value;
+    return Array.from(template.content.childNodes);
+  }
+
+  return [
+    document.createTextNode(
+      String(value as string | number | boolean | bigint | symbol)
+    ),
+  ];
+}
+
+/**
+ * 将 DOM 引用解析为节点列表。
+ *
+ * 支持的输入类型：
+ * - **Node**: 包装为单元素数组，如 `document.body`
+ * - **Element**: 包装为单元素数组，如 `div`
+ * - **string**: CSS 选择器，如 `'div'`, `'.class'`, `'#id'`
+ * - **Array**: 扁平化为节点数组，如 `[el1, [el2, el3]]`
+ * - **false/null/undefined**: 返回 null
+ *
+ * @param {Element|Node|string|Array|false|null|undefined} ref 元素引用、选择器、节点或空值。
+ * @returns {Node[]|null}
+ */
+export function resolveNodeList(ref: DOMReference): Node[] | null {
+  if (ref === false || ref == null) return null;
+
+  if (typeof ref === 'string') {
+    const nodes = all(ref);
+    return nodes.length > 0 ? nodes : null;
+  }
+
+  if (Array.isArray(ref)) {
+    const nodes = flattenNodeArray(ref, []);
+    return nodes && nodes.length > 0 ? nodes : null;
+  }
+
+  if (isNode(ref)) return [ref];
+
+  return null;
+}
+
+/**
+ * 将 DOM 引用解析为节点。
+ *
+ * 支持的输入类型：
+ * - **Node/Element**: 直接返回，如 `document.body`, `div`
+ * - **string**: CSS 选择器，如 `'div'`, `'.class'`, `'#id'`
+ * - **Array**: 返回第一个节点，如 `[el1, el2]`
+ * - **false/null/undefined**: 返回 null
+ *
+ * @param {Element|Node|string|Array|false|null|undefined} ref 元素引用、选择器、节点或空值。
+ * @returns {Node|null}
+ */
+export function resolveNode(ref: DOMReference): Node | null {
+  if (isElement(ref) || isNode(ref)) return ref;
+
+  if (typeof ref === 'string') {
+    return document.querySelector(ref);
+  }
+
+  if (Array.isArray(ref)) {
+    const nodes = resolveNodeList(ref) || [];
+    return nodes[0] || null;
+  }
+
+  return null;
+}
+
+/**
+ * 将 DOM 引用解析为元素。
+ *
+ * 支持的输入类型：
+ * - **Element**: 直接返回，如 `document.querySelector('#app')`
+ * - **string**: CSS 选择器，如 `'div'`, `'.class'`, `'#id'`
+ * - **Array**: 返回第一个 Element，如 `[el1, el2]`
+ * - **false/null/undefined**: 返回 null
+ *
+ * @param {Element|Node|string|Array|false|null|undefined} ref 元素引用、选择器、节点或空值。
+ * @returns {Element|null}
+ */
+export function resolveElement(ref: DOMReference): Element | null {
+  if (!isContainerLike(ref)) return null;
+
+  if (typeof ref === 'string') {
+    const element = document.querySelector(ref);
+    return isElement(element) ? element : null;
+  }
+
+  if (Array.isArray(ref)) {
+    const nodes = resolveNodeList(ref);
+    return Array.isArray(nodes) ? firstElement(nodes) : null;
+  }
+
+  return isElement(ref) ? ref : null;
+}
+
+/**
+ * 统一解析容器引用。
+ *
+ * @param {Element|Node|string|Array|false|null|undefined} container 容器引用、选择器、节点或数组。
+ * @param {string} [namespace='Component'] 错误命名空间。
+ * @param {'node'|'element'|'array'} [expect='element'] 期望返回类型。
+ * @returns {Node|Element|Node[]|null}
+ */
+export function resolveContainer<TExpect extends ContainerExpect = 'element'>(
+  container: DOMReference,
+  namespace: string = 'Component',
+  expect: TExpect = 'element' as TExpect
+): ResolveContainerResult<TExpect> | null {
+  if (!isContainerExpect(expect)) {
+    throw new Error(
+      `${namespace}: expect must be one of 'node', 'element', 'array'.`
+    );
+  }
+
+  if (!isContainerLike(container)) return null;
+
+  if (expect === 'array') {
+    return resolveNodeList(container) as ResolveContainerResult<TExpect> | null;
+  }
+
+  if (expect === 'node') {
+    return resolveNode(container) as ResolveContainerResult<TExpect> | null;
+  }
+
+  return resolveElement(container) as ResolveContainerResult<TExpect> | null;
+}
+
+/**
+ * 强制解析容器并要求返回值存在。
+ *
+ * @param {Element|Node|string|Array|false|null|undefined} container 容器引用、选择器、节点或数组。
+ * @param {string} [namespace='Component'] 错误命名空间。
+ * @param {'node'|'element'|'array'} [expect='element'] 期望返回类型。
+ * @returns {Node|Element|Node[]}
+ */
+export function requireContainer<TExpect extends ContainerExpect = 'element'>(
+  container: DOMReference,
+  namespace: string = 'Component',
+  expect: TExpect = 'element' as TExpect
+): RequireContainerResult<TExpect> {
+  const resolved = resolveContainer(container, namespace, expect);
+  if (resolved == null) {
+    throw new Error(`${namespace}: container not found.`);
+  }
+  return resolved as RequireContainerResult<TExpect>;
+}
+
+/**
+ * 判断是否为组件可渲染内容。
+ * @param {*} value 需要判断的值。
+ * @returns {boolean}
+ */
+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)
+  );
+}
+
+/**
+ * 创建通用加载状态节点。
+ * @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' }),
+  });
+}
+
+/**
+ * 根据 CSS 选择器获取第一个匹配的元素。
+ * @param {string} selector CSS 选择器。
+ * @param {Document|Element} [context=document] 查询范围。
+ * @returns {Element|null}
+ */
+export function q<TElement extends Element = Element>(
+  selector: string,
+  context: QueryContext = document
+): TElement | null {
+  return context.querySelector<TElement>(selector);
+}
+
+/**
+ * 根据 CSS 选择器获取所有匹配的元素。
+ * @param {string} selector CSS 选择器。
+ * @param {Document|Element} [context=document] 查询范围。
+ * @returns {Element[]}
+ */
+export function all<TElement extends Element = Element>(
+  selector: string,
+  context: QueryContext = document
+): TElement[] {
+  return Array.from(context.querySelectorAll<TElement>(selector));
+}
+
+/**
+ * 当目标元素进入可视区域时执行渲染回调，仅执行一次后自动清理。
+ *
+ * 支持选择器字符串或 Element。目标尚未挂载时默认等待 DOM 变化；不支持
+ * IntersectionObserver 时会立即执行回调，保证降级环境也能渲染。
+ * @param {string|Element} target CSS 选择器或 DOM 元素。
+ * @param {Function} renderCallback 渲染回调函数，仅执行一次。
+ * @param {Object} [options] 配置项。
+ * @returns {Function} 停止观察的清理函数。
+ */
+export function lazyRender(
+  target: LazyRenderTarget,
+  renderCallback: LazyRenderCallback,
+  options?: LazyRenderOptions
+): CleanupFunction;
+export function lazyRender(
+  target: unknown,
+  renderCallback: LazyRenderCallback,
+  options: LazyRenderOptions = {}
+): CleanupFunction {
+  if (typeof renderCallback !== 'function') {
+    throw new TypeError('lazyRender: renderCallback expects function.');
+  }
+
+  const {
+    threshold = 0.1,
+    rootMargin = '0px',
+    root = null,
+    waitForDOM = true,
+  } = options;
+  const observerOptions: IntersectionObserverInit = {
+    threshold,
+    rootMargin,
+    root,
+  };
+
+  if (!isLazyRenderTarget(target)) {
+    console.warn('lazyRender: target 必须是 CSS 选择器字符串或 DOM 元素');
+    return noop;
+  }
+
+  let cleanup: CleanupFunction = noop;
+  let element = resolveLazyRenderTarget(target);
+
+  if (element && document.body.contains(element)) {
+    cleanup = observeAndRender(element, renderCallback, observerOptions);
+    return cleanup;
+  }
+
+  if (!waitForDOM || typeof MutationObserver === 'undefined') {
+    renderCallback();
+    return cleanup;
+  }
+
+  const observer = new MutationObserver(() => {
+    const current = resolveLazyRenderTarget(target);
+    if (!current || !document.body.contains(current)) return;
+
+    element = current;
+    observer.disconnect();
+    cleanup = observeAndRender(element, renderCallback, observerOptions);
+  });
+
+  observer.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+  });
+
+  return () => {
+    observer.disconnect();
+    cleanup();
+  };
+}
+
+function noop(): void {}
+
+function isLazyRenderTarget(value: unknown): value is LazyRenderTarget {
+  return typeof value === 'string' || isElement(value);
+}
+
+function resolveLazyRenderTarget(target: LazyRenderTarget): Element | null {
+  return typeof target === 'string' ? q(target) : target;
+}
+
+function observeAndRender(
+  element: Element,
+  renderCallback: LazyRenderCallback,
+  observerOptions: IntersectionObserverInit
+): CleanupFunction {
+  if (
+    typeof window === 'undefined' ||
+    typeof window.IntersectionObserver === 'undefined'
+  ) {
+    renderCallback();
+    return noop;
+  }
+
+  const observer = new window.IntersectionObserver((entries) => {
+    for (const entry of entries) {
+      if (!entry.isIntersecting) continue;
+
+      observer.unobserve(element);
+      observer.disconnect();
+      renderCallback();
+      break;
+    }
+  }, observerOptions);
+
+  observer.observe(element);
+
+  return () => {
+    observer.unobserve(element);
+    observer.disconnect();
+  };
+}

package/src/utilities/events.ts

@@ -0,0 +1,106 @@
+/**
+ * 绑定 DOM 事件并返回一次性解绑函数。
+ *
+ * @template T - 事件目标类型（如 HTMLElement, Window 等）
+ * @template K - 事件类型字符串（如 'click', 'scroll'）
+ * @param {T} target - 事件目标。
+ * @param {K} type - 事件类型。
+ * @param {(this: T, ev: HTMLElementEventMap[K extends keyof HTMLElementEventMap ? K : never]) => any} handler - 事件处理器。
+ * @param {boolean | AddEventListenerOptions} [options] - 事件选项。
+ * @returns {() => void} 解绑函数，可重复调用。
+ */
+export function listen<T extends EventTarget, K extends string>(
+  target: T,
+  type: K,
+  handler: (this: T, ev: Event) => any,
+  options?: boolean | AddEventListenerOptions
+): () => void {
+  let active = true;
+  target.addEventListener(type, handler as EventListener, options);
+
+  return () => {
+    if (!active) return;
+    active = false;
+    target.removeEventListener(type, handler as EventListener, options);
+  };
+}
+
+/**
+ * 事件管理器实例的接口定义
+ */
+export interface IEventManager {
+  /**
+   * 绑定事件并自动记录解绑函数。
+   * 同一个 key 重复绑定时会先解绑旧事件，避免组件重渲染时重复监听。
+   */
+  on<T extends EventTarget, K extends string>(
+    key: string,
+    target: T,
+    type: K,
+    handler: (this: T, ev: Event) => any,
+    options?: boolean | AddEventListenerOptions
+  ): () => void;
+
+  /** 根据 key 解绑特定事件 */
+  off(key: string): boolean;
+
+  /** 清除所有已绑定的事件 */
+  clear(): void;
+
+  /** 获取当前绑定的事件数量 */
+  size(): number;
+}
+
+/**
+ * 创建实例级事件管理器。
+ *
+ * - `on()` 绑定事件并自动记录解绑函数。
+ * - 同一个 key 重复绑定时会先解绑旧事件，避免组件重渲染时重复监听。
+ * - `off(key)` 和 `clear()` 用于跨作用域精确释放。
+ */
+export function createEventManager(): IEventManager {
+  const records = new Map<string, () => void>();
+
+  const off = (key: string): boolean => {
+    const dispose = records.get(key);
+    if (!dispose) return false;
+    dispose();
+    records.delete(key);
+    return true;
+  };
+
+  return {
+    on<T extends EventTarget, K extends string>(
+      key: string,
+      target: T,
+      type: K,
+      handler: (this: T, ev: Event) => any,
+      options?: boolean | AddEventListenerOptions
+    ): () => void {
+      if (typeof key !== 'string' || key.trim() === '') {
+        throw new TypeError('EventManager.on: key expects a non-empty string.');
+      }
+
+      // 先解绑旧事件
+      off(key);
+
+      // 防御性编程：如果 target 为空，返回空函数
+      if (target == null) return () => {};
+
+      const dispose = listen(target, type, handler, options);
+      records.set(key, dispose);
+      return dispose;
+    },
+
+    off,
+
+    clear(): void {
+      for (const dispose of records.values()) dispose();
+      records.clear();
+    },
+
+    size(): number {
+      return records.size;
+    },
+  };
+}

package/src/utilities/http.ts

@@ -0,0 +1,35 @@
+/**
+ * 发送 JSON POST 请求并解析 JSON 响应。
+ * @template T - 期望返回的 JSON 数据类型
+ * @param {string} url - 请求地址
+ * @param {unknown} body - 请求体，会被 JSON.stringify
+ * @param {RequestInit} [options] - 透传给 fetch 的请求配置（排除 method 和 body）
+ * @returns {Promise<T>} 解析后的 JSON 响应体
+ */
+export async function postJson<T = unknown>(
+  url: string,
+  body: unknown,
+  options: Omit<RequestInit, 'method' | 'body'> = {}
+): Promise<T> {
+  const headers = new Headers(options.headers);
+
+  if (!headers.has('Content-Type')) {
+    headers.set('Content-Type', 'application/json');
+  }
+
+  const res = await fetch(url, {
+    ...options,
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  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/storage.ts

@@ -0,0 +1,46 @@
+export function getCookie(name: string): string | null {
+  if (typeof document === 'undefined') return null;
+
+  const escapedName = escapeRegExp(name);
+  const match = document.cookie.match(
+    new RegExp('(?:^|;\\s*)' + escapedName + '=([^;]*)')
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function setCookie(
+  name: string,
+  value: string,
+  seconds: number = 60 * 60 * 24 // 默认有效期为 24 小时
+): boolean {
+  if (typeof document === 'undefined') return false;
+
+  const encodedName = encodeURIComponent(name);
+  const encodedValue = encodeURIComponent(value);
+
+  let cookieStr = `${encodedName}=${encodedValue}; path=/; SameSite=Lax`;
+
+  if (seconds > 0) {
+    const expires = new Date(Date.now() + seconds * 1000).toUTCString();
+    cookieStr += `; expires=${expires}`;
+  }
+
+  if (location.protocol === 'https:') {
+    cookieStr += '; Secure';
+  }
+
+  document.cookie = cookieStr;
+
+  return getCookie(name) === value;
+}
+
+export function removeCookie(name: string): boolean {
+  if (typeof document === 'undefined') return true;
+
+  document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
+  return !getCookie(name);
+}