vanilla-jui 1.3.10 → 1.4.0

package/src/components/parabola.ts

@@ -0,0 +1,335 @@
+import { jsx } from 'vanilla-signal';
+
+import { type ResolveSchema, resolveProps } from '../utilities/core.ts';
+import { type DOMReference, isNode, resolveElement } from '../utilities/dom.ts';
+
+export type ParabolaDirection =
+  | 'center'
+  | 'top-right'
+  | 'top-left'
+  | 'bottom-right'
+  | 'bottom-left';
+
+export interface ParabolaBallOptions {
+  color: string;
+  size: string;
+}
+
+export interface ParabolaClassNames {
+  ball: string;
+}
+
+export type ParabolaClassNameConfig = Partial<ParabolaClassNames>;
+
+export interface ParabolaOptions extends Record<string, unknown> {
+  ball?: ParabolaBallOptions;
+  className?: ParabolaClassNameConfig;
+  from?: DOMReference;
+  to?: DOMReference;
+  direction?: ParabolaDirection;
+  showDelay?: number;
+  hideDelay?: number;
+  onShow?: ((parabola: Parabola) => void) | null;
+  onHidden?: ((parabola: Parabola) => void) | null;
+}
+
+interface ResolvedParabolaOptions extends Record<string, unknown> {
+  ball: ParabolaBallOptions;
+  className: ParabolaClassNames;
+  from: DOMReference;
+  to: DOMReference;
+  direction: ParabolaDirection;
+  showDelay: number;
+  hideDelay: number;
+  onShow: ((parabola: Parabola) => void) | null;
+  onHidden: ((parabola: Parabola) => void) | null;
+}
+
+interface ParabolaPath {
+  startX: number;
+  startY: number;
+  endX: number;
+  endY: number;
+}
+
+const DEFAULT_BALL: ParabolaBallOptions = {
+  color: 'var(--primary, #3e63dd)',
+  size: '10px',
+};
+
+const DEFAULT_CLASS_NAMES: ParabolaClassNames = {
+  ball: 'parabola-ball',
+};
+
+const ELEMENT_REF_RULE = {
+  validate: (value: unknown) =>
+    value == null ||
+    typeof value === 'string' ||
+    Array.isArray(value) ||
+    isNode(value),
+  message: 'expects Element, Node, selector or JSX node.',
+};
+
+const PARABOLA_OPTIONS_SCHEMA = {
+  ball: {
+    default: DEFAULT_BALL,
+    type: 'object',
+    normalize: (value: unknown) => ({
+      ...DEFAULT_BALL,
+      ...(value && typeof value === 'object' ? value : {}),
+    }),
+    validate: (value: unknown) =>
+      !!value &&
+      typeof value === 'object' &&
+      typeof (value as ParabolaBallOptions).color === 'string' &&
+      typeof (value as ParabolaBallOptions).size === 'string',
+    message:
+      'expects an object with two string properties: "color" and "size".',
+  },
+  className: {
+    default: DEFAULT_CLASS_NAMES,
+    type: 'object',
+    normalize: (value: unknown) => ({
+      ...DEFAULT_CLASS_NAMES,
+      ...(value && typeof value === 'object' ? value : {}),
+    }),
+  },
+  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'] },
+} satisfies ResolveSchema<ParabolaOptions>;
+
+function normalizeOptions(input: ParabolaOptions): ResolvedParabolaOptions {
+  const options = resolveProps(
+    input,
+    PARABOLA_OPTIONS_SCHEMA,
+    'Parabola.options'
+  );
+  return {
+    ball: options.ball as ParabolaBallOptions,
+    className: options.className as ParabolaClassNames,
+    from: options.from as DOMReference,
+    to: options.to as DOMReference,
+    direction: options.direction as ParabolaDirection,
+    showDelay: options.showDelay as number,
+    hideDelay: options.hideDelay as number,
+    onShow: options.onShow as ResolvedParabolaOptions['onShow'],
+    onHidden: options.onHidden as ResolvedParabolaOptions['onHidden'],
+  };
+}
+
+/**
+ * 抛物线动画组件。
+ *
+ * 用于实现“加入购物车”等从一个元素飞向另一个元素的小球动画。
+ */
+export class Parabola {
+  options: ResolvedParabolaOptions;
+  hidden: boolean;
+  _ball: HTMLElement | null;
+  _animationId: number | null;
+  _fromEl: Element | null;
+  _toEl: Element | null;
+  private showTimerId: ReturnType<typeof setTimeout> | null;
+
+  /**
+   * 创建抛物线动画实例。
+   * @param {ParabolaOptions} options 动画配置。
+   */
+  constructor(options: ParabolaOptions = {}) {
+    this.options = normalizeOptions(options);
+    this.hidden = false;
+    this._ball = null;
+    this._animationId = null;
+    this._fromEl = resolveElement(this.options.from);
+    this._toEl = resolveElement(this.options.to);
+    this.showTimerId = null;
+
+    this.createBall();
+  }
+
+  private createBall(): void {
+    if (this.hidden || this._ball) return;
+
+    const { color, size } = this.options.ball;
+
+    this._ball = jsx('div', {
+      className: this.options.className.ball,
+      'data-parabola': 'ball',
+      style: {
+        backgroundColor: color,
+        width: size,
+        height: size,
+        position: 'fixed',
+        borderRadius: '50%',
+        transform: 'translate(-50%, -50%)',
+        pointerEvents: 'none',
+        zIndex: '9999',
+        opacity: '1',
+      },
+    }) as HTMLElement;
+    document.body.appendChild(this._ball);
+  }
+
+  private calculatePath(): ParabolaPath | null {
+    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: number;
+    let startY: number;
+    switch (this.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:
+        startX = fL + fW / 2;
+        startY = fT + fH / 2;
+    }
+
+    const endX = tL + tW / 2;
+    const endY = tT + tH / 2;
+
+    return { startX, startY, endX, endY };
+  }
+
+  private easeOutCubic(t: number): number {
+    return 1 - (1 - t) ** 3;
+  }
+
+  private animate(
+    startX: number,
+    startY: number,
+    endX: number,
+    endY: number,
+    duration = 800
+  ): void {
+    if (this.hidden || !this._ball) return;
+
+    const startTime = performance.now();
+    const deltaX = endX - startX;
+    const deltaY = endY - startY;
+    const peakOffset = -100;
+
+    const step = (currentTime: number): void => {
+      if (this.hidden || !this._ball) 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。
+   */
+  show(): Promise<boolean> {
+    if (this.hidden) return Promise.resolve(false);
+
+    return new Promise((resolve) => {
+      this.showTimerId = setTimeout(() => {
+        this.showTimerId = null;
+        if (this.hidden || !this._ball) {
+          resolve(false);
+          return;
+        }
+
+        const path = this.calculatePath();
+        if (!path) {
+          this.destroy();
+          resolve(false);
+          return;
+        }
+
+        this._ball.style.left = `${path.startX}px`;
+        this._ball.style.top = `${path.startY}px`;
+
+        this.options.onShow?.(this);
+
+        this.animate(path.startX, path.startY, path.endX, path.endY);
+        resolve(true);
+      }, this.options.showDelay);
+    });
+  }
+
+  /**
+   * 销毁动画实例并清理 DOM、定时器和动画帧。
+   * @returns {void}
+   */
+  destroy(): void {
+    if (this.hidden) return;
+
+    this._ball?.remove();
+
+    if (this.showTimerId) {
+      clearTimeout(this.showTimerId);
+      this.showTimerId = null;
+    }
+    if (this._animationId) cancelAnimationFrame(this._animationId);
+
+    this._ball = null;
+    this._fromEl = null;
+    this._toEl = null;
+    this._animationId = null;
+    this.hidden = true;
+
+    this.options.onHidden?.(this);
+  }
+
+  /**
+   * show 的语义化别名。
+   * @returns {Promise<boolean>}
+   */
+  start(): Promise<boolean> {
+    return this.show();
+  }
+}
+
+export function createParabola(options: ParabolaOptions = {}): Parabola {
+  return new Parabola(options);
+}

package/src/components/{sticky.js → sticky.ts}

@@ -1,12 +1,65 @@
 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';
+import Component, {
+  type ComponentDOM,
+  type ComponentRuntime,
+} from '../core/Component.ts';
+import { type ResolveSchema, resolveProps } from '../utilities/core.ts';
+import { type DOMReference, all, requireContainer } from '../utilities/dom.ts';
+
+export type StickyOverflow = 'destroy' | 'ignore';
+
+export interface StickyProps extends Record<string, unknown> {
+  target?: DOMReference;
+  parent?: DOMReference;
+  max?: number;
+  top?: number;
+  gap?: number;
+  overflow?: StickyOverflow;
+  onUpdate?: ((sticky: Sticky) => void) | null;
+}
+
+interface ResolvedStickyProps extends Record<string, unknown> {
+  target: DOMReference;
+  parent: DOMReference;
+  max: number;
+  top: number;
+  gap: number;
+  overflow: StickyOverflow;
+  onUpdate: ((sticky: Sticky) => void) | null;
+}
+
+export interface StickyStateItem {
+  element: HTMLElement;
+  top: number;
+}
+
+interface StickyState extends Record<string, unknown> {
+  count: number;
+  top: number;
+  items: StickyStateItem[];
+}
+
+interface StickyDOM extends ComponentDOM {
+  root: Element | null;
+  parent: Element | null;
+  targets: HTMLElement[];
+}
+
+interface StickyRuntimeItem {
+  element: HTMLElement;
+  top: number;
+  originalPosition: string;
+  originalTop: string;
+  originalZIndex: string;
+}
+
+interface StickyRuntime extends ComponentRuntime {
+  active: boolean;
+  built: boolean;
+  ignored: boolean;
+  items: StickyRuntimeItem[];
+}
 
 const STICKY_PROPS_SCHEMA = {
   target: { default: null },
@@ -14,19 +67,20 @@ const STICKY_PROPS_SCHEMA = {
   max: {
     default: 10,
     type: 'number',
-    validate: (value) => Number.isInteger(value) && value > 0,
+    validate: (value) =>
+      typeof value === 'number' && Number.isInteger(value) && value > 0,
     message: 'expects a positive integer.',
   },
   top: {
     default: 16,
     type: 'number',
-    validate: (value) => value >= 0,
+    validate: (value) => typeof value === 'number' && value >= 0,
     message: 'expects a positive number or 0.',
   },
   gap: {
     default: 16,
     type: 'number',
-    validate: (value) => value >= 0,
+    validate: (value) => typeof value === 'number' && value >= 0,
     message: 'expects a positive number or 0.',
   },
   overflow: {
@@ -35,44 +89,37 @@ const STICKY_PROPS_SCHEMA = {
     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)));
+} satisfies ResolveSchema<StickyProps>;
+
+function normalizeProps(input: StickyProps): ResolvedStickyProps {
+  const props = resolveProps(input, STICKY_PROPS_SCHEMA, 'Sticky.props');
+  return {
+    target: props.target as DOMReference,
+    parent: props.parent as DOMReference,
+    max: props.max as number,
+    top: props.top as number,
+    gap: props.gap as number,
+    overflow: props.overflow as StickyOverflow,
+    onUpdate: props.onUpdate as ResolvedStickyProps['onUpdate'],
+  };
 }
 
-/**
- * 判断元素是否在指定父级中。
- * @param {Element} element 目标元素。
- * @param {Element|null} parent 父级。
- * @returns {boolean}
- */
-function isWithinParent(element, parent) {
-  return !parent || element === parent || parent.contains(element);
+function uniqueElements(elements: readonly Node[]): HTMLElement[] {
+  const htmlElements = elements.filter(
+    (element): element is HTMLElement => element instanceof HTMLElement
+  );
+  return Array.from(new Set(htmlElements));
 }
 
-/**
- * 归一化 parent 输入。
- * @param {Element|Node|string|null|false} parent 父级输入。
- * @returns {Element|null}
- */
-function resolveParent(parent) {
+function resolveParent(parent: DOMReference): Element | null {
   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) {
+function resolveTarget(
+  target: DOMReference,
+  parent: Element | null
+): HTMLElement[] {
   if (target === false || target == null) return [];
 
   if (typeof target === 'string') {
@@ -80,21 +127,20 @@ function resolveTarget(target, parent) {
       return uniqueElements(requireContainer(target, 'Sticky.target', 'array'));
     }
 
-    const elements = uniqueElements(
-      Array.from(parent.querySelectorAll(target))
-    );
+    const elements = uniqueElements(all<HTMLElement>(target, parent));
     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);
-
+  const elements = uniqueElements(
+    requireContainer(target, 'Sticky.target', 'array')
+  );
   if (!parent) return elements;
-  const scopedElements = elements.filter((element) =>
-    isWithinParent(element, parent)
+
+  const scopedElements = elements.filter(
+    (element) => element === parent || parent.contains(element)
   );
   if (scopedElements.length === 0) {
     throw new Error('Sticky.target: target not found in parent.');
@@ -102,29 +148,25 @@ function resolveTarget(target, 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 {
+export class Sticky extends Component<
+  ResolvedStickyProps,
+  StickyState,
+  StickyDOM
+> {
+  declare runtime: StickyRuntime;
+
   /**
    * 创建 Sticky 实例。
    * @param {object} [input={}] Sticky 配置。
    */
-  constructor(input = {}) {
-    const props = resolveProps(input, STICKY_PROPS_SCHEMA, 'Sticky.props');
+  constructor(input: StickyProps = {}) {
+    const props = normalizeProps(input);
     super(props);
 
     this.dom.parent = null;
@@ -146,34 +188,28 @@ export class Sticky extends Component {
    * 构建 Sticky 行为并应用样式。
    * @returns {Sticky} 当前实例。
    */
-  build() {
+  build(): this {
     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.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();
+    this.captureItems();
+    this.apply();
     return this;
   }
 
-  /**
-   * 按当前实例的 targets 创建运行时条目。
-   * @private
-   */
-  _captureItems() {
+  private captureItems(): void {
     this.runtime.items = this.dom.targets.map((element) => ({
       element,
       top: this.props.top,
@@ -183,13 +219,7 @@ export class Sticky extends Component {
     }));
   }
 
-  /**
-   * 按 max/overflow 处理当前实例的目标集合。
-   * @param {Element[]} targets 目标元素集合。
-   * @returns {Element[]}
-   * @private
-   */
-  _resolveOverflow(targets) {
+  private resolveOverflow(targets: HTMLElement[]): HTMLElement[] {
     const { max, overflow } = this.props;
     if (targets.length <= max) return targets;
 
@@ -197,15 +227,9 @@ export class Sticky extends Component {
     return overflow === 'ignore' ? [] : targets.slice(-max);
   }
 
-  /**
-   * 对本实例重新计算 sticky 偏移。
-   * @param {number} [startTop=this.props.top] 起始 top。
-   * @returns {number} 当前实例处理后的下一个 top。
-   * @private
-   */
-  _apply(startTop = this.props.top) {
+  private apply(startTop = this.props.top): number {
     let nextTop = startTop;
-    const stateItems = [];
+    const stateItems: StickyStateItem[] = [];
 
     for (const item of this.runtime.items) {
       item.top = nextTop;
@@ -213,7 +237,7 @@ export class Sticky extends Component {
       item.element.style.top = `${nextTop}px`;
 
       stateItems.push({ element: item.element, top: nextTop });
-      nextTop += getElementHeight(item.element) + this.props.gap;
+      nextTop += item.element.offsetHeight + this.props.gap;
     }
 
     this.setState({
@@ -229,11 +253,7 @@ export class Sticky extends Component {
     return nextTop;
   }
 
-  /**
-   * 恢复本实例管理元素的原始内联样式。
-   * @private
-   */
-  _restore() {
+  private restore(): void {
     for (const item of this.runtime.items) {
       item.element.style.position = item.originalPosition;
       item.element.style.top = item.originalTop;
@@ -245,20 +265,25 @@ export class Sticky extends Component {
    * 重新计算当前实例内所有 sticky 元素的 top。
    * @returns {Sticky} 当前实例。
    */
-  refresh() {
+  refresh(): this {
     if (this.runtime.destroyed || !this.runtime.built || !this.runtime.active) {
       return this;
     }
-    this._apply();
+    this.apply();
     return this;
   }
 
+  destroy(): void {
+    if (this.runtime.destroyed) return;
+    this.restore();
+    super.destroy();
+  }
+
   /**
    * 销毁实例并恢复被管理元素的原始样式。
    * @private
    */
-  onDestroy() {
-    this._restore();
+  protected onDestroy(): void {
     this.runtime.active = false;
     this.runtime.built = false;
     this.runtime.items = [];
@@ -266,6 +291,6 @@ export class Sticky extends Component {
   }
 }
 
-export function createSticky(props = {}) {
+export function createSticky(props: StickyProps = {}): Sticky {
   return new Sticky(props);
 }