vanilla-jui 1.3.9 → 1.3.11

package/src/components/theme.js

@@ -0,0 +1,353 @@
+import { jsx } from 'vanilla-signal';
+import { t } from 'vanilla-signal-i18n';
+
+import locales from '../locales/index.js';
+import { all, requireRenderDOM } from '../utilities/dom.js';
+import { createEventManager } from '../utilities/events.js';
+import { getCookie, setCookie } from '../utilities/storage.js';
+
+/**
+ * @typedef {object} ThemeOptions
+ * @property {string} [mode="dark"] 主题明暗模式，支持 light、dark、auto 或自定义值。
+ * @property {string} [theme="indigo"] 色彩主题名。
+ * @property {string} [radius="sm"] 圆角等级。
+ * @property {string} [shadow="sm"] 阴影等级。
+ * @property {string} [font="sm"] 字号等级。
+ * @property {string} [key="jui-theme"] Cookie 存储 key。
+ */
+
+/**
+ * @typedef {object} ThemePanelGroup
+ * @property {string} title 分组标题。
+ * @property {string} type 对应 ThemeOptions 中的配置项。
+ * @property {Array<[string,string]>} buttons 按钮配置，格式为 `[值, 展示文案]`。
+ */
+
+/**
+ * 主题管理组件。
+ *
+ * 负责主题配置的实例化、主题面板交互和 Cookie 读写。实例初始化不修改 html
+ * 类名，仅在面板点击交互时同步当前点击项对应的 html class。
+ *
+ * 如需首屏按 Cookie 渲染 html class，可在 <head> 中放置：
+ *
+ * ```html
+ * <script>
+ * (function(d,k){var m=d.cookie.match(new RegExp('(?:^|; )'+k+'=([^;]*)'));if(!m)return;try{var o=JSON.parse(m[1]),r=o.mode==='auto'?(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light'):o.mode,h=d.documentElement;h.classList.add(r||'dark','j-theme-'+(o.theme||'indigo'),'j-radius-'+(o.radius||'sm'),'j-shadow-'+(o.shadow||'sm'),'j-font-'+(o.font||'sm'));}catch(e){}})(document,'jui-theme');
+ * </script>
+ * ```
+ */
+export class Theme {
+  /**
+   * 创建主题实例。
+   * @param {ThemeOptions} [options={}] 主题配置。
+   */
+  constructor(options = {}) {
+    requireRenderDOM('Theme');
+
+    this.props = {
+      mode: 'dark',
+      theme: 'indigo',
+      radius: 'sm',
+      shadow: 'sm',
+      font: 'sm',
+      key: 'jui-theme',
+      ...options,
+    };
+
+    this.languages = locales;
+
+    this._init();
+  }
+
+  /**
+   * 初始化主题状态、读取缓存并绑定事件。
+   * @private
+   * @returns {void}
+   */
+  _init() {
+    this.cleanup = { events: createEventManager() };
+    this.runtime = { destroyed: false };
+    this._loadConfig();
+    this._bindEvent();
+    this._syncActiveButtons();
+  }
+
+  /**
+   * 获取主题面板文案。
+   * @private
+   * @param {string} key 文案 key。
+   * @returns {string}
+   */
+  _t(key) {
+    return t(key, this.languages);
+  }
+
+  /**
+   * 从 Cookie 读取主题配置。
+   * @private
+   * @returns {void}
+   */
+  _loadConfig() {
+    try {
+      const result = getCookie(this.props.key);
+      if (result && result.trim()) {
+        this.props = Object.assign({}, this.props, JSON.parse(result));
+      }
+    } catch {}
+  }
+
+  /**
+   * 将当前主题配置写入 Cookie。
+   * @private
+   * @returns {void}
+   */
+  _saveConfig() {
+    const { mode, theme, radius, shadow, font } = this.props;
+    const render = mode === 'auto' ? this._scheme() : mode;
+    setCookie(
+      this.props.key,
+      JSON.stringify({ mode, theme, radius, shadow, font, render })
+    );
+  }
+
+  _scheme() {
+    return window?.matchMedia('(prefers-color-scheme: dark)')?.matches
+      ? 'dark'
+      : 'light';
+  }
+
+  /**
+   * 同步主题面板按钮激活态。
+   * @private
+   * @returns {void}
+   */
+  _syncActiveButtons() {
+    const items = all('.palette-item');
+    for (const item of items) {
+      const type = item.dataset.palette;
+      const val = this.props[type];
+      const buttons = all('button[data-palette]', item);
+      for (const btn of buttons) {
+        const v = btn.dataset.palette;
+        const isActive = v === (val === undefined ? null : val);
+        btn.classList.toggle('is-active', isActive);
+      }
+    }
+  }
+
+  /**
+   * 绑定主题面板点击事件。
+   * @private
+   * @returns {void}
+   */
+  _bindEvent() {
+    this.cleanup.events.on('palette', document.body, 'click', (e) => {
+      const btn = e.target.closest(
+        '.palette-item .items > button[data-palette]'
+      );
+      if (!btn) return;
+
+      const groupEl = btn.closest('.palette-item');
+      if (!groupEl) return;
+
+      const type = groupEl.dataset.palette;
+      const value = btn.dataset.palette;
+
+      if (btn.classList.contains('is-active')) return;
+
+      const previous = this.props[type];
+      this.props[type] = value;
+
+      const h = document.documentElement;
+      if (type === 'mode') {
+        const actual = value === 'auto' ? this._scheme() : value;
+        h.classList.remove('light', 'dark', previous);
+        if (actual) h.classList.add(actual);
+      } else {
+        const prefixes = {
+          theme: 'j-theme-',
+          radius: 'j-radius-',
+          shadow: 'j-shadow-',
+          font: 'j-font-',
+        };
+        const prefix = prefixes[type];
+        if (prefix) {
+          const toRemove = Array.from(h.classList).filter((c) =>
+            c.startsWith(prefix)
+          );
+          if (toRemove.length) h.classList.remove(...toRemove);
+          h.classList.add(`${prefix}${value}`);
+        }
+      }
+
+      this._saveConfig();
+      this._syncActiveButtons();
+    });
+  }
+
+  /**
+   * 解绑主题面板点击事件。
+   * @private
+   * @returns {void}
+   */
+  _unbindEvent() {
+    this.cleanup.events.clear();
+  }
+
+  /**
+   * 创建主题交互面板。
+   * @param {string} [containerClass="j-theme-palette"] 主题交互面板容器类名。
+   * @param {ThemePanelGroup[]|null} [panelConfig=null] 自定义面板分组配置。
+   * @returns {HTMLElement} 主题交互面板节点。
+   */
+  createPanel(containerClass = 'j-theme-palette', panelConfig = null) {
+    const groups = panelConfig || [
+      {
+        title: this._t('Theme'),
+        type: 'theme',
+        buttons: [
+          ['gray', this._t('Gray')],
+          ['olive', this._t('Olive')],
+          ['tomato', this._t('Tomato')],
+          ['ruby', this._t('Ruby')],
+          ['pink', this._t('Pink')],
+          ['violet', this._t('Violet')],
+          ['indigo', this._t('Indigo')],
+          ['blue', this._t('Blue')],
+          ['teal', this._t('Teal')],
+          ['grass', this._t('Grass')],
+          ['mint', this._t('Mint')],
+          ['lime', this._t('Lime')],
+          ['yellow', this._t('Yellow')],
+          ['orange', this._t('Orange')],
+          ['gold', this._t('Gold')],
+        ],
+      },
+      {
+        title: this._t('Radius'),
+        type: 'radius',
+        buttons: [
+          ['none', this._t('n')],
+          ['sm', this._t('sm')],
+          ['md', this._t('md')],
+          ['lg', this._t('lg')],
+          ['xl', this._t('XL')],
+          ['round', this._t('Round')],
+        ],
+      },
+      {
+        title: this._t('Shadow'),
+        type: 'shadow',
+        buttons: [
+          ['none', this._t('n')],
+          ['sm', this._t('sm')],
+          ['md', this._t('md')],
+          ['lg', this._t('lg')],
+        ],
+      },
+      {
+        title: this._t('Font'),
+        type: 'font',
+        buttons: [
+          ['sm', this._t('sm')],
+          ['md', this._t('md')],
+        ],
+      },
+      {
+        title: this._t('Mode'),
+        type: 'mode',
+        buttons: [
+          ['light', this._t('Light')],
+          ['dark', this._t('Dark')],
+          ['auto', this._t('Auto')],
+        ],
+      },
+    ];
+
+    const panel = jsx('div', {
+      className: containerClass,
+      children: [
+        jsx('div', {
+          style: {
+            display: 'flex',
+            justifyContent: 'center',
+          },
+          children: jsx('button', {
+            className: 'j-button is-text',
+            'data-action': 'close',
+            children: this._t('b'),
+          }),
+        }),
+        jsx('h3', { children: this._t('t') }),
+        jsx('p', {
+          style: {
+            marginTop: 0,
+            fontSize: 'var(--text-sm, 0.875rem)',
+          },
+          children: this._t('d'),
+        }),
+        jsx('div', {
+          className: 'palette-container',
+          children: groups.map((group) =>
+            jsx('div', {
+              className: 'palette-item',
+              'data-palette': group.type,
+              children: [
+                jsx('div', { className: 'item-title', children: group.title }),
+                jsx('div', {
+                  className: 'items',
+                  children: group.buttons.map(([val, label]) => {
+                    const isActive =
+                      String(this.props[group.type]) === String(val);
+                    return jsx('button', {
+                      className: `j-button is-default${isActive ? ' is-active' : ''}`,
+                      'data-palette': val,
+                      children: [
+                        group.type === 'theme'
+                          ? jsx('span', {
+                              className: 'el-prefix item-hex',
+                              style: {
+                                backgroundColor: `var(--ui-${val})`,
+                              },
+                            })
+                          : null,
+                        jsx('span', {
+                          className: 'button-text',
+                          children: label,
+                        }),
+                      ],
+                    });
+                  }),
+                }),
+              ],
+            })
+          ),
+        }),
+      ],
+    });
+    return panel;
+  }
+
+  /**
+   * 更新主题配置并写入 Cookie。
+   * @param {Partial<ThemeOptions>} newConfig 需要覆盖的主题配置。
+   * @returns {void}
+   */
+  setConfig(newConfig) {
+    this.props = Object.assign({}, this.props, newConfig);
+    this._saveConfig();
+    this._syncActiveButtons();
+  }
+
+  /**
+   * 销毁当前主题实例并解绑事件。
+   * @returns {void}
+   */
+  destroy() {
+    if (this.runtime.destroyed) return;
+    this.runtime.destroyed = true;
+    this._unbindEvent();
+    this.cleanup = null;
+  }
+}

package/src/components/toast.js

@@ -0,0 +1,329 @@
+import { jsx } from 'vanilla-signal';
+
+import { randomId, timer, validateParam } from '../utilities/core.js';
+import { q, requireRenderDOM } from '../utilities/dom.js';
+import { listen } from '../utilities/events.js';
+import { icon } from './icons.js';
+
+const TOAST_TYPE_RULE = {
+  type: 'string',
+  enum: ['info', 'success', 'warning', 'error', 'primary'],
+};
+
+const TOAST_DURATION_RULE = {
+  type: 'number',
+  validate: (value) => value >= 0,
+  message: 'expects a positive number or 0.',
+};
+
+const LITE_DURATION_RULE = {
+  type: 'number',
+  validate: (value) => value > 0,
+  message: 'expects a number greater than 0.',
+};
+
+/**
+ * Toast 消息提示工具。
+ *
+ * 以静态方法方式使用，支持多类型堆叠消息和单实例轻提示。
+ */
+export class Toast {
+  /**
+   * 当前 Toast 使用的 timer key 集合，用于统一清理。
+   * @type {Set<string>}
+   */
+  static timers = new Set();
+
+  static disposers = new Map();
+  /**
+   * 展示一条 Toast 消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒；传 0 时不自动关闭。
+   * @param {"info"|"success"|"warning"|"error"|"primary"} [type="info"] 消息类型。
+   * @returns {HTMLElement} Toast 节点。
+   */
+  static show(message = '', duration = 3000, type = 'info') {
+    requireRenderDOM('Toast');
+
+    validateParam('message', message, 'string', 'Toast.show');
+    validateParam('duration', duration, TOAST_DURATION_RULE, 'Toast.show');
+    validateParam('type', type, TOAST_TYPE_RULE, 'Toast.show');
+
+    const toastContainer = Toast._getOrCreateContainer();
+
+    const id = randomId();
+    const toast = jsx('div', {
+      className: `j-toast is-${type}`,
+      'data-toast': id,
+      children: [
+        jsx('span', {
+          className: 'toast-icon',
+          children: icon(type === 'primary' ? 'info' : type),
+        }),
+        jsx('span', { className: 'toast-message', children: message }),
+      ],
+    });
+
+    toastContainer.appendChild(toast);
+
+    Toast._setTimer(
+      id,
+      'show',
+      () => {
+        toast.classList.add('is-shown');
+      },
+      10
+    );
+
+    if (duration > 0) {
+      Toast._setTimer(
+        id,
+        'hide',
+        () => {
+          Toast.hide(toast);
+        },
+        duration
+      );
+    }
+
+    const disposeClick = listen(toast, 'click', () => {
+      Toast.hide(toast);
+    });
+    Toast.disposers.set(toast, disposeClick);
+
+    return toast;
+  }
+
+  /**
+   * 展示成功消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒。
+   * @returns {HTMLElement}
+   */
+  static success(message = '', duration = 3000) {
+    return Toast.show(message, duration, 'success');
+  }
+
+  /**
+   * 展示信息消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒。
+   * @returns {HTMLElement}
+   */
+  static info(message = '', duration = 3000) {
+    return Toast.show(message, duration, 'info');
+  }
+
+  /**
+   * 展示主色消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒。
+   * @returns {HTMLElement}
+   */
+  static primary(message = '', duration = 3000) {
+    return Toast.show(message, duration, 'primary');
+  }
+
+  /**
+   * 展示警告消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒。
+   * @returns {HTMLElement}
+   */
+  static warning(message = '', duration = 3000) {
+    return Toast.show(message, duration, 'warning');
+  }
+
+  /**
+   * 展示错误消息。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=3000] 展示时长，单位毫秒。
+   * @returns {HTMLElement}
+   */
+  static error(message = '', duration = 3000) {
+    return Toast.show(message, duration, 'error');
+  }
+
+  /**
+   * 隐藏指定 Toast。
+   * @param {HTMLElement} toast 需要隐藏的 Toast 节点。
+   * @returns {void}
+   */
+  static hide(toast) {
+    if (toast) {
+      Toast.disposers.get(toast)?.();
+      Toast.disposers.delete(toast);
+
+      toast.classList.remove('is-shown');
+      toast.classList.add('is-hidden');
+
+      const id = toast.dataset.toast;
+      Toast._setTimer(
+        id,
+        'remove',
+        () => {
+          if (toast.parentNode) {
+            toast.parentNode.removeChild(toast);
+          }
+
+          const container = q('.j-toast-container');
+          if (container && container.children.length === 0) {
+            container.parentNode.removeChild(container);
+          }
+        },
+        300
+      );
+    }
+  }
+
+  /**
+   * 展示轻量单例提示。
+   *
+   * 页面上同一时间只保留一个 lite toast。
+   * @param {string} [message=""] 消息内容。
+   * @param {number} [duration=2000] 展示时长，单位毫秒。
+   * @returns {HTMLElement} 轻提示节点。
+   */
+  static lite(message = '', duration = 2000) {
+    requireRenderDOM('Toast');
+
+    validateParam('message', message, 'string', 'Toast.lite');
+    validateParam('duration', duration, LITE_DURATION_RULE, 'Toast.lite');
+
+    const existing = q('.j-toast-lite');
+    if (existing) existing.remove();
+
+    const id = randomId();
+    const lite = jsx('div', {
+      className: 'j-toast-lite',
+      'data-toast': id,
+      children: message,
+    });
+    document.body.appendChild(lite);
+
+    Toast._setTimer(id, 'show', () => lite.classList.add('is-shown'), 10);
+
+    Toast._setTimer(
+      id,
+      'hide',
+      () => {
+        lite.classList.remove('is-shown');
+        lite.classList.add('is-hidden');
+        Toast._setTimer(id, 'remove', () => lite.remove(), 300);
+      },
+      duration
+    );
+
+    return lite;
+  }
+
+  // action 模式不支持自动关闭，必须通过按钮点击触发关闭。
+  static action(message = '', props = {}) {
+    requireRenderDOM('Toast');
+
+    // DOM 结构如下：
+    //  <div class="j-toast-container">
+    //     <div class="j-toast is-action is-shown">
+    //       <div class="toast-message">这是一条成功提示消息。</div>
+    //       <div class="toast-action">
+    //           <button class="j-button is-sm is-ghost">cancel</button>
+    //           <button class="j-button is-sm is-outline">action</button>
+    //       </div>
+    //     </div>
+    //   </div>
+
+    // const existing = q('.j-toast.is-action');
+    // if (existing) existing.remove();
+
+    const toastContainer = Toast._getOrCreateContainer();
+
+    const id = randomId();
+    const action = jsx('div', {
+      className: 'j-toast is-action',
+      'data-toast': id,
+      children: [
+        jsx('div', { className: 'toast-message', children: message }),
+        jsx('div', {
+          className: 'toast-actions',
+          children: [
+            jsx('button', {
+              className: 'j-button is-sm is-ghost',
+              children: props.text.cancel || 'cancel',
+              'data-action': 'cancel',
+              onClick: () => {
+                action.classList.remove('is-shown');
+                action.classList.add('is-hidden');
+                Toast.hide(action);
+              },
+            }),
+            jsx('button', {
+              className: 'j-button is-sm is-outline',
+              children: props.text.action || 'action',
+              'data-action': 'toast-action',
+              onClick: async () => {
+                await props.onAction?.();
+                Toast.hide(action);
+              },
+            }),
+          ],
+        }),
+      ],
+    });
+    toastContainer.appendChild(action);
+
+    // 在挂载后异步添加显示态，确保 CSS transition 能从初始态过渡。
+    Toast._setTimer(
+      id,
+      'show',
+      () => {
+        action.classList.add('is-shown');
+        const actionButton = q('[data-action="toast-action"]', action);
+        actionButton?.focus();
+      },
+      10
+    );
+
+    return action;
+  }
+
+  static _getOrCreateContainer() {
+    let toastContainer = q('.j-toast-container');
+    if (!toastContainer) {
+      toastContainer = jsx('div', { className: 'j-toast-container' });
+      document.body.appendChild(toastContainer);
+    }
+    return toastContainer;
+  }
+
+  /**
+   * 创建可统一清理的定时器。
+   * @private
+   * @param {Function} callback 定时回调。
+   * @param {number} delay 延迟毫秒。
+   * @returns {string} timer key。
+   */
+  static _setTimer(id, action, callback, delay) {
+    const key = `${id}-${action}`;
+    Toast.timers.add(key);
+    timer.start(key, delay, () => {
+      Toast.timers.delete(key);
+      callback();
+    });
+    return key;
+  }
+
+  /**
+   * 清理所有 Toast 节点和定时器。
+   * @returns {void}
+   */
+  static clearAll() {
+    for (const key of Toast.timers) {
+      timer.cancel(key);
+    }
+    Toast.timers.clear();
+    for (const dispose of Toast.disposers.values()) dispose();
+    Toast.disposers.clear();
+    q('.j-toast-container')?.remove();
+    q('.j-toast-lite')?.remove();
+  }
+}