vanilla-jui 1.3.8 → 1.3.10

package/src/components/parabola.js

@@ -0,0 +1,295 @@
+import { jsx } from 'vanilla-signal';
+
+import { resolveProps, timer } from '../utilities/core.js';
+import { isNode, requireRenderDOM, resolveElement } from '../utilities/dom.js';
+
+const ELEMENT_REF_RULE = {
+  validate: (value) =>
+    value == null ||
+    typeof value === 'string' ||
+    Array.isArray(value) ||
+    isNode(value),
+  message: 'expects Element, Node, selector or JSX node.',
+};
+
+const PARABOLA_OPTIONS_SCHEMA = {
+  ball: {
+    default: {
+      color: 'var(--primary, #3e63dd)',
+      size: '10px',
+    },
+    type: 'object',
+    validate: (value) =>
+      value &&
+      Object.keys(value).length === 2 &&
+      typeof value.color === 'string' &&
+      typeof value.size === 'string',
+    message:
+      'expects an object with two string properties: "color" and "size".',
+  },
+  from: { default: null, ...ELEMENT_REF_RULE },
+  to: { default: null, ...ELEMENT_REF_RULE },
+  direction: {
+    default: 'center',
+    type: 'string',
+    enum: ['center', 'top-right', 'top-left', 'bottom-right', 'bottom-left'],
+  },
+  showDelay: { default: 0, type: 'number' },
+  hideDelay: { default: 0, type: 'number' },
+  onShow: { default: null, types: ['function', 'null'] },
+  onHidden: { default: null, types: ['function', 'null'] },
+};
+
+/**
+ * @typedef {object} ParabolaBallOptions
+ * @property {string} color 小球颜色。
+ * @property {string} size 小球尺寸，例如 `10px`。
+ */
+
+/**
+ * @typedef {object} ParabolaOptions
+ * @property {ParabolaBallOptions} [ball] 小球样式配置。
+ * @property {Element|Node|string|Array} from 起点元素、选择器或 JSX/h 返回节点。
+ * @property {Element|Node|string|Array} to 终点元素、选择器或 JSX/h 返回节点。
+ * @property {"center"|"top-right"|"top-left"|"bottom-right"|"bottom-left"} [direction="center"] 起点取样位置。
+ * @property {number} [showDelay=0] 开始动画前的延迟，单位毫秒。
+ * @property {number} [hideDelay=0] 预留隐藏延迟配置。
+ * @property {Function|null} [onShow] 动画开始前回调。
+ * @property {Function|null} [onHidden] 动画结束或销毁后回调。
+ */
+
+/**
+ * 抛物线动画组件。
+ *
+ * 用于实现“加入购物车”等从一个元素飞向另一个元素的小球动画。
+ */
+export class Parabola {
+  /**
+   * 创建抛物线动画实例。
+   * @param {ParabolaOptions} options 动画配置。
+   */
+  constructor(options) {
+    requireRenderDOM('Parabola');
+
+    this.options = resolveProps(
+      options,
+      PARABOLA_OPTIONS_SCHEMA,
+      'Parabola.options'
+    );
+    this._init(this.options);
+  }
+
+  /**
+   * 初始化动画状态并创建小球。
+   * @private
+   * @param {ParabolaOptions} options 已归一化配置。
+   * @returns {void}
+   */
+  _init(options) {
+    this.hidden = false;
+
+    this._ball = null;
+    this._animationId = null;
+
+    const fromEl = resolveElement(options.from, 'Parabola.from');
+    const toEl = resolveElement(options.to, 'Parabola.to');
+
+    this._fromEl = fromEl;
+    this._toEl = toEl;
+
+    this._createBall(options);
+  }
+
+  /**
+   * 创建动画小球节点。
+   * @private
+   * @param {ParabolaOptions} options 已归一化配置。
+   * @returns {void}
+   */
+  _createBall(options) {
+    if (this.hidden || this._ball) return;
+
+    const { color, size } = options.ball;
+
+    this._ball = jsx('div', {
+      className: 'parabola-ball',
+      style: {
+        backgroundColor: color,
+        width: size,
+        height: size,
+        position: 'fixed',
+        borderRadius: '50%',
+        transform: 'translate(-50%, -50%)',
+        pointerEvents: 'none',
+        zIndex: '9999',
+        opacity: '1',
+      },
+    });
+    document.body.appendChild(this._ball);
+  }
+
+  /**
+   * 计算动画起点和终点坐标。
+   * @private
+   * @param {ParabolaOptions} options 已归一化配置。
+   * @returns {{startX:number,startY:number,endX:number,endY:number}|null}
+   */
+  _calculatePath(options) {
+    const fromRect = this._fromEl?.getBoundingClientRect();
+    const toRect = this._toEl?.getBoundingClientRect();
+
+    if (!fromRect || !toRect) return null;
+
+    const { left: fL, top: fT, width: fW, height: fH } = fromRect;
+    const { left: tL, top: tT, width: tW, height: tH } = toRect;
+
+    let startX, startY;
+    switch (options.direction) {
+      case 'top-left':
+        startX = fL + fW * 0.2;
+        startY = fT + fH * 0.2;
+        break;
+      case 'top-right':
+        startX = fL + fW * 0.8;
+        startY = fT + fH * 0.2;
+        break;
+      case 'bottom-left':
+        startX = fL + fW * 0.2;
+        startY = fT + fH * 0.8;
+        break;
+      case 'bottom-right':
+        startX = fL + fW * 0.8;
+        startY = fT + fH * 0.8;
+        break;
+      default: // 'center'
+        startX = fL + fW / 2;
+        startY = fT + fH / 2;
+    }
+
+    const endX = tL + tW / 2;
+    const endY = tT + tH / 2;
+
+    return { startX, startY, endX, endY };
+  }
+
+  /**
+   * 三次缓出曲线。
+   * @private
+   * @param {number} t 动画进度，范围 0 到 1。
+   * @returns {number}
+   */
+  _easeOutCubic(t) {
+    return 1 - (1 - t) ** 3;
+  }
+
+  /**
+   * 执行抛物线动画。
+   * @private
+   * @param {number} startX 起点 x 坐标。
+   * @param {number} startY 起点 y 坐标。
+   * @param {number} endX 终点 x 坐标。
+   * @param {number} endY 终点 y 坐标。
+   * @param {number} [duration=800] 动画时长，单位毫秒。
+   * @returns {void}
+   */
+  _animate(startX, startY, endX, endY, duration = 800) {
+    if (this.hidden) return;
+
+    const startTime = performance.now();
+    const deltaX = endX - startX;
+    const deltaY = endY - startY;
+    const peakOffset = -100;
+
+    const step = (currentTime) => {
+      if (this.hidden) return;
+
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const eased = this._easeOutCubic(progress);
+
+      const currentX = startX + deltaX * eased;
+      const currentY =
+        startY + peakOffset * Math.sin(Math.PI * eased) + deltaY * eased;
+
+      const opacity = 1 - progress;
+
+      this._ball.style.left = `${currentX}px`;
+      this._ball.style.top = `${currentY}px`;
+      this._ball.style.opacity = `${opacity}`;
+      this._ball.style.transform = `translate(-50%, -50%) scale(${1 - eased * 0.3})`;
+
+      if (progress < 1) {
+        this._animationId = requestAnimationFrame(step);
+      } else {
+        this.destroy(); // 动画结束，直接销毁
+      }
+    };
+
+    this._animationId = requestAnimationFrame(step);
+  }
+
+  /**
+   * 开始播放动画。
+   * @returns {Promise<boolean>} 成功开始动画时返回 true；元素缺失或已销毁时返回 false。
+   */
+  async show() {
+    if (this.hidden) return false;
+
+    return new Promise((resolve) => {
+      timer.start('show', this.options.showDelay, () => {
+        if (this.hidden) {
+          resolve(false);
+          return;
+        }
+
+        const path = this._calculatePath(this.options);
+        if (!path) {
+          this.destroy();
+          resolve(false);
+          return;
+        }
+
+        this._ball.style.left = `${path.startX}px`;
+        this._ball.style.top = `${path.startY}px`;
+
+        if (this.options.onShow) this.options.onShow();
+
+        this._animate(path.startX, path.startY, path.endX, path.endY);
+        resolve(true);
+      });
+    });
+  }
+
+  /**
+   * 销毁动画实例并清理 DOM、定时器和动画帧。
+   * @returns {void}
+   */
+  destroy() {
+    if (this.hidden) return;
+
+    this._ball?.remove();
+
+    timer.cancel('show');
+    if (this._animationId) cancelAnimationFrame(this._animationId);
+
+    this._ball = null;
+    this._fromEl = null;
+    this._toEl = null;
+
+    this.hidden = true;
+
+    if (this.options.onHidden) this.options.onHidden();
+  }
+
+  /**
+   * show 的语义化别名。
+   * @returns {Promise<boolean>}
+   */
+  start() {
+    return this.show();
+  }
+}
+
+export function createParabola(options = {}) {
+  return new Parabola(options);
+}

package/src/components/sticky.js

@@ -0,0 +1,271 @@
+import { createDeepStore } from 'vanilla-signal';
+
+import Component from '../core/Component.js';
+import { resolveProps } from '../utilities/core.js';
+import {
+  isElement,
+  requireContainer,
+  requireRenderDOM,
+} from '../utilities/dom.js';
+
+const STICKY_PROPS_SCHEMA = {
+  target: { default: null },
+  parent: { default: null },
+  max: {
+    default: 10,
+    type: 'number',
+    validate: (value) => Number.isInteger(value) && value > 0,
+    message: 'expects a positive integer.',
+  },
+  top: {
+    default: 16,
+    type: 'number',
+    validate: (value) => value >= 0,
+    message: 'expects a positive number or 0.',
+  },
+  gap: {
+    default: 16,
+    type: 'number',
+    validate: (value) => value >= 0,
+    message: 'expects a positive number or 0.',
+  },
+  overflow: {
+    default: 'destroy',
+    type: 'string',
+    enum: ['destroy', 'ignore'],
+  },
+  onUpdate: { default: null, types: ['function', 'null'] },
+};
+
+/**
+ * 对元素数组去重，并保持原始顺序。
+ * @param {Element[]} elements 元素数组。
+ * @returns {Element[]}
+ */
+function uniqueElements(elements) {
+  return Array.from(new Set(elements.filter(isElement)));
+}
+
+/**
+ * 判断元素是否在指定父级中。
+ * @param {Element} element 目标元素。
+ * @param {Element|null} parent 父级。
+ * @returns {boolean}
+ */
+function isWithinParent(element, parent) {
+  return !parent || element === parent || parent.contains(element);
+}
+
+/**
+ * 归一化 parent 输入。
+ * @param {Element|Node|string|null|false} parent 父级输入。
+ * @returns {Element|null}
+ */
+function resolveParent(parent) {
+  if (parent === false || parent == null) return null;
+  return requireContainer(parent, 'Sticky.parent', 'element');
+}
+
+/**
+ * 在 parent 作用域内解析 sticky 目标。
+ * @param {Element|Node|string|Array|null|false} target 目标输入。
+ * @param {Element|null} parent 父级。
+ * @returns {Element[]}
+ */
+function resolveTarget(target, parent) {
+  if (target === false || target == null) return [];
+
+  if (typeof target === 'string') {
+    if (!parent) {
+      return uniqueElements(requireContainer(target, 'Sticky.target', 'array'));
+    }
+
+    const elements = uniqueElements(
+      Array.from(parent.querySelectorAll(target))
+    );
+    if (elements.length === 0) {
+      throw new Error('Sticky.target: target not found.');
+    }
+    return elements;
+  }
+
+  const nodes = requireContainer(target, 'Sticky.target', 'array');
+  const elements = uniqueElements(nodes);
+
+  if (!parent) return elements;
+  const scopedElements = elements.filter((element) =>
+    isWithinParent(element, parent)
+  );
+  if (scopedElements.length === 0) {
+    throw new Error('Sticky.target: target not found in parent.');
+  }
+  return scopedElements;
+}
+
+/**
+ * 读取元素 offsetHeight。
+ * @param {Element} element 目标元素。
+ * @returns {number}
+ */
+function getElementHeight(element) {
+  const height = element.offsetHeight;
+  return Number.isFinite(height) ? height : 0;
+}
+
+/**
+ * Sticky 吸附组件。
+ *
+ * 用于给一个或多个元素应用 `position: sticky`，并按顺序计算 `top`
+ * 偏移，适合页面侧边栏中多个 widget 的堆叠吸附场景。
+ */
+export class Sticky extends Component {
+  /**
+   * 创建 Sticky 实例。
+   * @param {object} [input={}] Sticky 配置。
+   */
+  constructor(input = {}) {
+    const props = resolveProps(input, STICKY_PROPS_SCHEMA, 'Sticky.props');
+    super(props);
+
+    this.dom.parent = null;
+    this.dom.targets = [];
+
+    this.runtime.active = false;
+    this.runtime.built = false;
+    this.runtime.ignored = false;
+    this.runtime.items = [];
+
+    this.state = createDeepStore({
+      count: 0,
+      top: props.top,
+      items: [],
+    });
+  }
+
+  /**
+   * 构建 Sticky 行为并应用样式。
+   * @returns {Sticky} 当前实例。
+   */
+  build() {
+    if (this.runtime.destroyed)
+      throw new Error('Sticky.build: instance destroyed');
+    if (this.runtime.built) return this;
+
+    requireRenderDOM('Sticky');
+
+    this.init(this.props);
+
+    this.dom.parent = resolveParent(this.props.parent);
+    this.dom.targets = resolveTarget(this.props.target, this.dom.parent);
+    this.dom.targets = this._resolveOverflow(this.dom.targets);
+
+    this.runtime.built = true;
+
+    if (this.dom.targets.length === 0) return this;
+
+    this.runtime.active = true;
+    this._captureItems();
+    this._apply();
+    return this;
+  }
+
+  /**
+   * 按当前实例的 targets 创建运行时条目。
+   * @private
+   */
+  _captureItems() {
+    this.runtime.items = this.dom.targets.map((element) => ({
+      element,
+      top: this.props.top,
+      originalPosition: element.style.position,
+      originalTop: element.style.top,
+      originalZIndex: element.style.zIndex,
+    }));
+  }
+
+  /**
+   * 按 max/overflow 处理当前实例的目标集合。
+   * @param {Element[]} targets 目标元素集合。
+   * @returns {Element[]}
+   * @private
+   */
+  _resolveOverflow(targets) {
+    const { max, overflow } = this.props;
+    if (targets.length <= max) return targets;
+
+    this.runtime.ignored = overflow === 'ignore';
+    return overflow === 'ignore' ? [] : targets.slice(-max);
+  }
+
+  /**
+   * 对本实例重新计算 sticky 偏移。
+   * @param {number} [startTop=this.props.top] 起始 top。
+   * @returns {number} 当前实例处理后的下一个 top。
+   * @private
+   */
+  _apply(startTop = this.props.top) {
+    let nextTop = startTop;
+    const stateItems = [];
+
+    for (const item of this.runtime.items) {
+      item.top = nextTop;
+      item.element.style.position = 'sticky';
+      item.element.style.top = `${nextTop}px`;
+
+      stateItems.push({ element: item.element, top: nextTop });
+      nextTop += getElementHeight(item.element) + this.props.gap;
+    }
+
+    this.setState({
+      count: this.runtime.items.length,
+      top: this.runtime.items[0]?.top ?? this.props.top,
+      items: stateItems,
+    });
+
+    if (typeof this.props.onUpdate === 'function') {
+      this.props.onUpdate(this);
+    }
+
+    return nextTop;
+  }
+
+  /**
+   * 恢复本实例管理元素的原始内联样式。
+   * @private
+   */
+  _restore() {
+    for (const item of this.runtime.items) {
+      item.element.style.position = item.originalPosition;
+      item.element.style.top = item.originalTop;
+      item.element.style.zIndex = item.originalZIndex;
+    }
+  }
+
+  /**
+   * 重新计算当前实例内所有 sticky 元素的 top。
+   * @returns {Sticky} 当前实例。
+   */
+  refresh() {
+    if (this.runtime.destroyed || !this.runtime.built || !this.runtime.active) {
+      return this;
+    }
+    this._apply();
+    return this;
+  }
+
+  /**
+   * 销毁实例并恢复被管理元素的原始样式。
+   * @private
+   */
+  onDestroy() {
+    this._restore();
+    this.runtime.active = false;
+    this.runtime.built = false;
+    this.runtime.items = [];
+    this.dom.targets = [];
+  }
+}
+
+export function createSticky(props = {}) {
+  return new Sticky(props);
+}