vanilla-jui 1.3.11 → 1.4.1

package/src/utilities/dom.js

@@ -1,313 +0,0 @@
-import { jsx } from 'vanilla-signal';
-
-/**
- * 判断当前环境是否可访问 DOM。
- * @returns {boolean}
- */
-export function canUseDOM() {
-  return typeof document !== 'undefined';
-}
-
-/**
- * 判断当前环境是否可执行 DOM 渲染。
- * @returns {boolean}
- */
-export function canRenderDOM() {
-  if (!canUseDOM() || typeof document.createElement !== 'function') {
-    return false;
-  }
-
-  const element = document.createElement('div');
-  return typeof element.insertBefore === 'function';
-}
-
-/**
- * 强制要求当前环境可执行 DOM 渲染。
- * @param {string} [namespace='Component'] 错误命名空间。
- * @returns {true}
- * @throws {Error} 当前环境不可渲染 DOM 时抛出。
- */
-export function requireRenderDOM(namespace = 'Component') {
-  if (!canRenderDOM()) {
-    throw new Error(`${namespace}: DOM render environment is required.`);
-  }
-  return true;
-}
-
-/**
- * 判断是否为 DOM Node。
- * @param {*} value 需要判断的值。
- * @returns {boolean}
- */
-export function isNode(value) {
-  return canUseDOM() && typeof Node !== 'undefined' && value instanceof Node;
-}
-
-/**
- * 判断是否为 DOM Element。
- * @param {*} value 需要判断的值。
- * @returns {boolean}
- */
-export function isElement(value) {
-  return (
-    canUseDOM() && typeof Element !== 'undefined' && value instanceof Element
-  );
-}
-
-/**
- * 判断值是否为可接受的容器输入。
- * @param {*} value 需要判断的值。
- * @returns {boolean}
- */
-function isContainerLike(value) {
-  return (
-    typeof value === 'string' ||
-    isElement(value) ||
-    isNode(value) ||
-    Array.isArray(value)
-  );
-}
-
-function firstElement(nodes) {
-  return nodes.find(isElement) || null;
-}
-
-function flattenNodeArray(value, out = []) {
-  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 节点数组。
- *
- * 字符串会按 HTML 片段解析；函数会以 context 调用后继续归一化。
- * @param {*} content 组件内容。
- * @param {*} [context] 传给函数内容的上下文。
- * @returns {Node[]}
- */
-export function normalizeContentNodes(content, context) {
-  const value = typeof content === 'function' ? content(context) : 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))];
-}
-
-/**
- * 将 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 元素引用、选择器、节点或空值。
- * @param {string} [namespace='Component'] 错误命名空间。
- * @returns {Node[]|null}
- */
-export function resolveNodeList(ref, _namespace = 'Component') {
-  if (ref === false || ref == null) return null;
-
-  if (typeof ref === 'string') {
-    if (!canUseDOM()) return null;
-    const nodes = Array.from(document.querySelectorAll(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 元素引用、选择器、节点或空值。
- * @param {string} [namespace='Component'] 错误命名空间。
- * @returns {Node|null}
- */
-export function resolveNode(ref, namespace = 'Component') {
-  if (isElement(ref) || isNode(ref)) return ref;
-
-  if (typeof ref === 'string') {
-    if (!canUseDOM()) return null;
-    return document.querySelector(ref);
-  }
-
-  if (Array.isArray(ref)) {
-    const nodes = resolveNodeList(ref, namespace) || [];
-    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 元素引用、选择器、节点或空值。
- * @param {string} [namespace='Component'] 错误命名空间。
- * @returns {Element|null}
- */
-export function resolveElement(ref, namespace = 'Component') {
-  if (!isContainerLike(ref) || ref === false || ref == null) return null;
-
-  if (typeof ref === 'string') {
-    if (!canUseDOM()) return null;
-    const element = document.querySelector(ref);
-    return isElement(element) ? element : null;
-  }
-
-  if (Array.isArray(ref)) {
-    const nodes = resolveNodeList(ref, namespace);
-    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(
-  container,
-  namespace = 'Component',
-  expect = 'element'
-) {
-  if (!['node', 'element', 'array'].includes(expect)) {
-    throw new Error(
-      `${namespace}: expect must be one of 'node', 'element', 'array'.`
-    );
-  }
-
-  if (!isContainerLike(container)) return null;
-
-  if (expect === 'array') {
-    return resolveNodeList(container, namespace);
-  }
-
-  if (expect === 'node') {
-    return resolveNode(container, namespace);
-  }
-
-  return resolveElement(container, namespace);
-}
-
-/**
- * 强制解析容器并要求返回值存在。
- *
- * @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(
-  container,
-  namespace = 'Component',
-  expect = 'element'
-) {
-  const resolved = resolveContainer(container, namespace, expect);
-  if (resolved == null) {
-    throw new Error(`${namespace}: container not found.`);
-  }
-  return resolved;
-}
-
-/**
- * 判断是否为组件可渲染内容。
- * @param {*} value 需要判断的值。
- * @returns {boolean}
- */
-export function isRenderableContent(value) {
-  return (
-    value == null ||
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean' ||
-    typeof value === 'function' ||
-    Array.isArray(value) ||
-    isNode(value)
-  );
-}
-
-/**
- * 创建通用加载状态节点。
- * @param {string} [className='j-loading is-active'] 容器类名。
- * @returns {HTMLElement}
- */
-export function createLoading(className = 'j-loading is-active') {
-  return jsx('div', {
-    className,
-    'aria-live': 'polite',
-    children: jsx('div', { className: 'loading-spinner' }),
-  });
-}
-
-/**
- * 根据 CSS 选择器获取第一个匹配的元素。
- * @param {string} selector CSS 选择器。
- * @param {Document|Element} [context=document] 查询范围。
- * @returns {Element|null}
- */
-export function q(selector, context = document) {
-  return context.querySelector(selector);
-}
-
-/**
- * 根据 CSS 选择器获取所有匹配的元素。
- * @param {string} selector CSS 选择器。
- * @param {Document|Element} [context=document] 查询范围。
- * @returns {Element[]}
- */
-export function all(selector, context = document) {
-  return Array.from(context.querySelectorAll(selector));
-}

package/src/utilities/events.js

@@ -1,69 +0,0 @@
-const NOOP = () => {};
-
-/**
- * 绑定 DOM 事件并返回一次性解绑函数。
- *
- * 语法糖，不做target等参数的校验。
- *
- * @param {EventTarget} target 事件目标。
- * @param {string} type 事件类型。
- * @param {EventListenerOrEventListenerObject} handler 事件处理器。
- * @param {AddEventListenerOptions|boolean} [options] 事件选项。
- * @returns {Function} 解绑函数，可重复调用。
- */
-export function listen(target, type, handler, options) {
-  let active = true;
-  target.addEventListener(type, handler, options);
-  return () => {
-    if (!active) return;
-    active = false;
-    target.removeEventListener(type, handler, options);
-  };
-}
-
-/**
- * 创建实例级事件管理器。
- *
- * - `on()` 绑定事件并自动记录解绑函数。
- * - 同一个 key 重复绑定时会先解绑旧事件，避免组件重渲染时重复监听。
- * - `off(key)` 和 `clear()` 用于跨作用域精确释放。
- * @returns {{on: Function, off: Function, clear: Function, size: Function}}
- */
-export function createEventManager() {
-  const records = new Map();
-
-  const off = (key) => {
-    const dispose = records.get(key);
-    if (!dispose) return false;
-    dispose();
-    records.delete(key);
-    return true;
-  };
-
-  return {
-    on(key, target, type, handler, options) {
-      if (typeof key !== 'string' || key.trim() === '') {
-        throw new TypeError('EventManager.on: key expects a non-empty string.');
-      }
-
-      off(key);
-
-      if (target == null) return NOOP;
-
-      const dispose = listen(target, type, handler, options);
-      records.set(key, dispose);
-      return dispose;
-    },
-
-    off,
-
-    clear() {
-      for (const dispose of records.values()) dispose();
-      records.clear();
-    },
-
-    size() {
-      return records.size;
-    },
-  };
-}

package/src/utilities/http.js

@@ -1,30 +0,0 @@
-/**
- * 发送 JSON POST 请求并解析 JSON 响应。
- * @param {string} url 请求地址。
- * @param {*} body 请求体，会被 JSON.stringify。
- * @param {RequestInit} [options] 透传给 fetch 的请求配置。
- * @returns {Promise<any>} JSON 响应体。
- */
-export async function postJson(url, body, options = {}) {
-  const headers = new Headers(options.headers);
-
-  if (!headers.has('Content-Type')) {
-    headers.set('Content-Type', 'application/json');
-  }
-
-  const res = await fetch(url, {
-    ...options,
-    method: options.method || 'POST',
-    headers,
-    body: JSON.stringify(body),
-  });
-
-  return res.json();
-}
-
-/**
- * 当前站点 WordPress REST API 根地址。
- * @type {string}
- */
-export const restUrl =
-  typeof window !== 'undefined' ? `${window.location.origin}/wp-json` : '';

package/src/utilities/legacy-dom.js

@@ -1,179 +0,0 @@
-import { q } from './dom.js';
-import { listen } from './events.js';
-
-/**
- * 创建 DOM 元素。
- *
- * 这是历史工具函数，新组件优先使用 signal.js/vanilla-signal 的 jsx 渲染。
- * @param {string} tagName 标签名。
- * @param {object} [options={}] 元素配置。
- * @param {string} [options.is] 自定义内建元素扩展名。
- * @param {string} [options.className] className。
- * @param {string} [options.id] id。
- * @param {Record<string, any>} [options.attrs] attribute 集合。
- * @param {Record<string, any>} [options.style] 行内样式集合。
- * @param {Record<string, Function>} [options.events] 事件处理集合。
- * @param {string} [options.text] textContent。
- * @param {string} [options.html] innerHTML，调用方需自行处理 XSS 风险。
- * @param {Node|Node[]|string} [options.children] 子节点或 HTML 字符串。
- * @param {boolean|Function} [options.dependency] 依赖条件，false 时返回空字符串。
- * @returns {HTMLElement|string}
- * @legacy 废弃，请使用 h() 或 jsx() 替代。
- */
-export function el(tagName, options = {}) {
-  if (typeof document === 'undefined') {
-    throw new Error('el() can only be used in browser environment.');
-  }
-
-  if (
-    options.dependency === false ||
-    (typeof options.dependency === 'function' && !options.dependency())
-  ) {
-    return '';
-  }
-
-  const { is, className, id, attrs, style, events, text, html, children } =
-    options;
-  const element = is
-    ? document.createElement(tagName, { is })
-    : document.createElement(tagName);
-
-  if (className) element.className = className;
-  if (id) element.id = id;
-
-  if (attrs && typeof attrs === 'object') {
-    for (const [key, value] of Object.entries(attrs)) {
-      if (value != null) element.setAttribute(key, String(value));
-    }
-  }
-
-  if (style && typeof style === 'object') {
-    for (const [key, value] of Object.entries(style)) {
-      if (value != null) element.style[key] = value;
-    }
-  }
-
-  if (events && typeof events === 'object') {
-    for (const [type, handler] of Object.entries(events)) {
-      if (typeof handler === 'function') {
-        listen(element, type, handler);
-      }
-    }
-  }
-
-  if (children !== undefined) {
-    if (Array.isArray(children)) {
-      element.append(...children);
-    } else if (typeof children === 'string') {
-      element.innerHTML = children;
-    } else if (children instanceof Node) {
-      element.appendChild(children);
-    }
-  } else if (html !== undefined) {
-    element.innerHTML = html;
-  } else if (text !== undefined) {
-    element.textContent = text;
-  }
-
-  return element;
-}
-
-/**
- * 当目标元素进入可视区域时执行渲染回调，仅执行一次后自动清理。
- * 支持传入选择器字符串或 Element 对象，即使元素尚未挂载到 DOM 也能工作。
- *
- * @param {string|Element} target CSS 选择器或 DOM 元素。
- * @param {Function} renderCallback 渲染回调函数，仅执行一次。
- * @param {Object} [options] 配置项。
- * @param {number|number[]} [options.threshold=0.1] 触发阈值。
- * @param {string} [options.rootMargin="0px"] 根边距。
- * @param {Element|null} [options.root=null] 根容器。
- * @param {boolean} [options.waitForDOM=true] 是否等待元素出现在 DOM 中。
- * @returns {Function} 停止观察的清理函数。
- */
-export function lazyRender(target, renderCallback, options = {}) {
-  const {
-    threshold = 0.1,
-    rootMargin = '0px',
-    root = null,
-    waitForDOM = true,
-  } = options;
-  const observerOptions = { threshold, rootMargin, root };
-
-  let cleanup = () => {};
-  let element = null;
-
-  if (typeof target === 'string') {
-    element = q(target);
-  } else if (typeof Element !== 'undefined' && target instanceof Element) {
-    element = target;
-  } else {
-    console.warn('lazyRender: target 必须是 CSS 选择器字符串或 DOM 元素');
-    return cleanup;
-  }
-
-  if (element && document.body.contains(element)) {
-    cleanup = observeAndRender(element, renderCallback, observerOptions);
-    return cleanup;
-  }
-
-  if (!waitForDOM) {
-    renderCallback();
-    return cleanup;
-  }
-
-  const observer = new MutationObserver(() => {
-    let found = false;
-
-    if (typeof target === 'string') {
-      const current = q(target);
-      if (current && document.body.contains(current)) {
-        found = true;
-        element = current;
-      }
-    } else if (document.body.contains(target)) {
-      found = true;
-      element = target;
-    }
-
-    if (found) {
-      observer.disconnect();
-      cleanup = observeAndRender(element, renderCallback, observerOptions);
-    }
-  });
-
-  observer.observe(document.documentElement, {
-    childList: true,
-    subtree: true,
-  });
-
-  return () => {
-    observer.disconnect();
-    cleanup();
-  };
-}
-
-function observeAndRender(element, renderCallback, observerOptions) {
-  if (!window.IntersectionObserver) {
-    renderCallback();
-    return () => {};
-  }
-
-  const io = new IntersectionObserver((entries) => {
-    for (const entry of entries) {
-      if (entry.isIntersecting) {
-        io.unobserve(element);
-        io.disconnect();
-        renderCallback();
-        break;
-      }
-    }
-  }, observerOptions);
-
-  io.observe(element);
-
-  return () => {
-    io.unobserve(element);
-    io.disconnect();
-  };
-}

package/src/utilities/storage.js

@@ -1,46 +0,0 @@
-/**
- * 读取 Cookie。
- * @param {string} name Cookie 名称。
- * @returns {string|null}
- */
-export function getCookie(name) {
-  if (typeof document === 'undefined') return null;
-
-  const value = `; ${document.cookie}`;
-  const parts = value.split(`; ${name}=`);
-  if (parts.length === 2) return parts.pop().split(';').shift();
-  return null;
-}
-
-/**
- * 写入 Cookie。
- * @param {string} name Cookie 名称。
- * @param {string} value Cookie 值。
- * @param {number} [seconds=86400] 有效期，单位秒。
- * @returns {boolean} 写入后是否能读取到相同值。
- */
-export function setCookie(name, value, seconds = 60 * 60 * 24) {
-  if (typeof document === 'undefined') return false;
-
-  const expires = new Date(Date.now() + seconds * 1000).toUTCString();
-  document.cookie = [
-    `${name}=${value}`,
-    `expires=${expires}`,
-    'path=/',
-    'sameSite=strict',
-  ].join('; ');
-
-  return getCookie(name) === value;
-}
-
-/**
- * 删除 Cookie。
- * @param {string} name Cookie 名称。
- * @returns {boolean} 删除后是否不可读取。
- */
-export function removeCookie(name) {
-  if (typeof document === 'undefined') return true;
-
-  document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
-  return !getCookie(name);
-}