@luanlu/mk-motion 1.2.0 → 1.2.1

package/src/core/animator.ts

@@ -0,0 +1,124 @@
+import type { AnimationName, AnimationOptions } from './utils.ts'
+import { toCssTime, setCSSVariables, removeCSSVariables } from './utils.ts'
+
+const DEFAULT_OPTIONS: Required<AnimationOptions> = {
+  duration: 500,
+  easing: 'ease',
+  delay: 0,
+  iterations: 1,
+  direction: 'normal',
+  fill: 'both',
+}
+
+export class Animator {
+  private element: HTMLElement
+  private currentAnimation: Animation | null = null
+
+  constructor(element: HTMLElement | string) {
+    this.element =
+      typeof element === 'string'
+        ? document.querySelector(element)!
+        : element
+
+    if (!this.element) {
+      throw new Error(`Animator: element not found`)
+    }
+  }
+
+  /**
+   * 播放 CSS 类动画
+   */
+  animate(
+    name: AnimationName,
+    options: AnimationOptions = {}
+  ): Promise<Animator> {
+    return new Promise((resolve) => {
+      const opts = { ...DEFAULT_OPTIONS, ...options }
+
+      setCSSVariables(this.element, {
+        duration: toCssTime(opts.duration),
+        easing: opts.easing,
+      })
+
+      const className = `mk-animated mk-${name}`
+      this.element.classList.add(...className.split(' '))
+
+      const cleanup = () => {
+        this.element.classList.remove(...className.split(' '))
+        removeCSSVariables(this.element, ['duration', 'easing'])
+        resolve(this)
+      }
+
+      const onEnd = (e: AnimationEvent) => {
+        if (e.animationName.startsWith('mk-')) {
+          this.element.removeEventListener('animationend', onEnd)
+          cleanup()
+        }
+      }
+
+      if (opts.iterations === Infinity || opts.iterations <= 0) {
+        this.element.classList.add('mk-infinite')
+        resolve(this)
+        return
+      }
+
+      this.element.addEventListener('animationend', onEnd)
+    })
+  }
+
+  /**
+   * 使用 Web Animations API 播放动画
+   */
+  waa(
+    keyframes: Keyframe[] | PropertyIndexedKeyframes,
+    options: AnimationOptions & { duration?: number } = {}
+  ): Promise<Animator> {
+    return new Promise((resolve) => {
+      const opts = { ...DEFAULT_OPTIONS, ...options }
+
+      this.currentAnimation = this.element.animate(keyframes, {
+        duration: opts.duration,
+        easing: opts.easing,
+        delay: opts.delay,
+        iterations: opts.iterations === Infinity ? Infinity : opts.iterations,
+        direction: opts.direction,
+        fill: opts.fill,
+      })
+
+      this.currentAnimation.onfinish = () => resolve(this)
+
+      if (opts.iterations === Infinity || opts.iterations <= 0) {
+        resolve(this)
+      }
+    })
+  }
+
+  /**
+   * 停止当前动画
+   */
+  stop(): this {
+    if (this.currentAnimation) {
+      this.currentAnimation.cancel()
+      this.currentAnimation = null
+    }
+    return this
+  }
+
+  /**
+   * 移除所有动效类
+   */
+  reset(): this {
+    const classes = Array.from(this.element.classList)
+    const toRemove = classes.filter((c) => c.startsWith('mk-'))
+    this.element.classList.remove(...toRemove)
+    return this
+  }
+
+  /**
+   * 设置元素样式变量
+   */
+  vars(variables: Record<string, string | number>): this {
+    setCSSVariables(this.element, variables)
+    return this
+  }
+}

package/src/core/timeline.ts

@@ -0,0 +1,128 @@
+import type { AnimationName, AnimationOptions } from './utils.ts'
+
+interface TimelineItem {
+  name: AnimationName
+  target: HTMLElement | string
+  options?: AnimationOptions
+  at?: number  // 相对时间线起点的毫秒数
+}
+
+export class Timeline {
+  private items: TimelineItem[] = []
+  private running = false
+  private abortController: AbortController | null = null
+
+  add(
+    name: AnimationName,
+    target: HTMLElement | string,
+    options?: AnimationOptions & { at?: number }
+  ): this {
+    this.items.push({
+      name,
+      target,
+      options,
+      at: options?.at ?? this.estimateEndTime(),
+    })
+    return this
+  }
+
+  private estimateEndTime(): number {
+    if (this.items.length === 0) return 0
+    const last = this.items[this.items.length - 1]
+    const duration = last.options?.duration ?? 500
+    return (last.at ?? 0) + duration
+  }
+
+  async play(): Promise<void> {
+    if (this.running) return
+    this.running = true
+    this.abortController = new AbortController()
+    const signal = this.abortController.signal
+
+    const promises = this.items.map((item) => {
+      return new Promise<void>((resolve) => {
+        const el =
+          typeof item.target === 'string'
+            ? document.querySelector(item.target)
+            : item.target
+
+        if (!el || signal.aborted) {
+          resolve()
+          return
+        }
+
+        const delay = item.at ?? 0
+        const duration = item.options?.duration ?? 500
+        const easing = item.options?.easing ?? 'ease'
+
+        const timer = setTimeout(() => {
+          if (signal.aborted) {
+            resolve()
+            return
+          }
+
+          const className = `mk-animated mk-${item.name}`
+          const htmlEl = el as HTMLElement
+          htmlEl.classList.add(...className.split(' '))
+          htmlEl.style.setProperty('--mk-duration', `${duration}ms`)
+          htmlEl.style.setProperty('--mk-easing', easing)
+
+          const onEnd = (e: AnimationEvent) => {
+            if (e.animationName.startsWith('mk-')) {
+              htmlEl.removeEventListener('animationend', onEnd)
+              htmlEl.classList.remove(...className.split(' '))
+              htmlEl.style.removeProperty('--mk-duration')
+              htmlEl.style.removeProperty('--mk-easing')
+              resolve()
+            }
+          }
+
+          htmlEl.addEventListener('animationend', onEnd)
+
+          // 安全兜底：如果动画没触发，超时 resolve
+          setTimeout(() => {
+            htmlEl.removeEventListener('animationend', onEnd)
+            htmlEl.classList.remove(...className.split(' '))
+            htmlEl.style.removeProperty('--mk-duration')
+            htmlEl.style.removeProperty('--mk-easing')
+            resolve()
+          }, duration + 100)
+        }, delay)
+
+        signal.addEventListener('abort', () => {
+          clearTimeout(timer)
+          resolve()
+        })
+      })
+    })
+
+    await Promise.all(promises)
+    this.running = false
+  }
+
+  stop(): void {
+    this.abortController?.abort()
+    this.running = false
+
+    // 清理所有残留的动画类
+    this.items.forEach((item) => {
+      const el =
+        typeof item.target === 'string'
+          ? document.querySelector(item.target)
+          : item.target
+      if (el) {
+        const htmlEl = el as HTMLElement
+        const className = `mk-animated mk-${item.name}`
+        htmlEl.classList.remove(...className.split(' '))
+        htmlEl.style.removeProperty('--mk-duration')
+        htmlEl.style.removeProperty('--mk-easing')
+      }
+    })
+  }
+
+  clear(): this {
+    this.stop()
+    this.items = []
+    return this
+  }
+}

package/src/core/utils.ts

@@ -0,0 +1,47 @@
+export type AnimationName =
+  | 'fadeIn' | 'fadeOut'
+  | 'slideInUp' | 'slideInDown' | 'slideInLeft' | 'slideInRight'
+  | 'slideOutUp' | 'slideOutDown'
+  | 'zoomIn' | 'zoomOut'
+  | 'bounceIn' | 'bounceOut'
+  | 'flipInX' | 'flipInY'
+  | 'shake' | 'pulse' | 'rotateIn'
+
+export interface AnimationOptions {
+  duration?: number
+  easing?: string
+  delay?: number
+  iterations?: number
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
+  fill?: 'none' | 'forwards' | 'backwards' | 'both'
+}
+
+export function parseTime(value: number | string): number {
+  if (typeof value === 'number') return value
+  const trimmed = value.trim().toLowerCase()
+  if (trimmed.endsWith('ms')) return parseFloat(trimmed)
+  if (trimmed.endsWith('s')) return parseFloat(trimmed) * 1000
+  return parseFloat(trimmed)
+}
+
+export function toCssTime(ms: number): string {
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(2).replace(/\.?0+$/, '')}s`
+}
+
+export function setCSSVariables(
+  el: HTMLElement,
+  vars: Record<string, string | number>
+): void {
+  Object.entries(vars).forEach(([key, value]) => {
+    el.style.setProperty(`--mk-${key}`, String(value))
+  })
+}
+
+export function removeCSSVariables(
+  el: HTMLElement,
+  keys: string[]
+): void {
+  keys.forEach((key) => {
+    el.style.removeProperty(`--mk-${key}`)
+  })
+}

package/src/effects/glitch.ts

@@ -0,0 +1,99 @@
+export interface GlitchOptions {
+  duration?: number        // 单次故障时长
+  intensity?: number       // 1~10 故障强度
+  color1?: string          // 故障色 1
+  color2?: string          // 故障色 2
+}
+
+const DEFAULT_GLITCH: Required<GlitchOptions> = {
+  duration: 300,
+  intensity: 5,
+  color1: '#ff0040',
+  color2: '#00ffff',
+}
+
+/**
+ * 给元素添加赛博朋克故障风效果
+ */
+export function glitch(
+  element: HTMLElement | string,
+  options: GlitchOptions = {}
+): Promise<void> {
+  const el =
+    typeof element === 'string'
+      ? document.querySelector<HTMLElement>(element)!
+      : element
+
+  if (!el) throw new Error('glitch: element not found')
+
+  const opts = { ...DEFAULT_GLITCH, ...options }
+  const intensity = Math.min(Math.max(opts.intensity, 1), 10)
+
+  const original = el.style.cssText
+  const steps = Math.floor(intensity * 2)
+
+  return new Promise((resolve) => {
+    let current = 0
+    const interval = opts.duration / steps
+
+    const run = () => {
+      if (current >= steps) {
+        el.style.cssText = original
+        el.style.textShadow = ''
+        resolve()
+        return
+      }
+
+      const x = (Math.random() - 0.5) * intensity * 4
+      const clip = `inset(${Math.random() * 80}% 0 ${Math.random() * 80}% 0)`
+      const shadow1 = `${opts.color1} ${x}px 0`
+      const shadow2 = `${opts.color2} ${-x}px 0`
+
+      el.style.transform = `translateX(${x}px)`
+      el.style.clipPath = clip
+      el.style.textShadow = `${shadow1}, ${shadow2}`
+
+      current++
+      setTimeout(run, interval)
+    }
+
+    run()
+  })
+}
+
+/**
+ * 持续故障效果（可停止）
+ */
+export function glitchLoop(
+  element: HTMLElement | string,
+  options: GlitchOptions = {}
+): () => void {
+  const el =
+    typeof element === 'string'
+      ? document.querySelector<HTMLElement>(element)!
+      : element
+
+  if (!el) throw new Error('glitchLoop: element not found')
+
+  const opts = { ...DEFAULT_GLITCH, ...options }
+  const original = el.style.cssText
+  let running = true
+
+  const loop = async () => {
+    if (!running) return
+    await glitch(el, { ...opts, duration: 100 + Math.random() * 200 })
+    if (running) {
+      setTimeout(loop, 200 + Math.random() * 800)
+    }
+  }
+
+  loop()
+
+  return () => {
+    running = false
+    el.style.cssText = original
+    el.style.textShadow = ''
+    el.style.clipPath = ''
+    el.style.transform = ''
+  }
+}

package/src/effects/particle.ts

@@ -0,0 +1,134 @@
+export interface ParticleOptions {
+  count?: number          // 粒子数量
+  color?: string | string[]  // 颜色
+  speed?: number          // 扩散速度
+  size?: number           // 粒子大小
+  gravity?: number        // 重力
+  fadeOut?: boolean       // 是否淡出
+  duration?: number       // 动画总时长
+}
+
+const DEFAULT_PARTICLE: Required<Omit<ParticleOptions, 'color'>> = {
+  count: 30,
+  speed: 6,
+  size: 6,
+  gravity: 0.3,
+  fadeOut: true,
+  duration: 1000,
+}
+
+interface Particle {
+  el: HTMLElement
+  vx: number
+  vy: number
+  x: number
+  y: number
+  life: number
+  maxLife: number
+}
+
+/**
+ * 在元素位置触发粒子爆炸效果
+ */
+export function particleBurst(
+  element: HTMLElement | string,
+  options: ParticleOptions = {}
+): Promise<void> {
+  const el =
+    typeof element === 'string'
+      ? document.querySelector<HTMLElement>(element)!
+      : element
+
+  if (!el) throw new Error('particleBurst: element not found')
+
+  const opts = { ...DEFAULT_PARTICLE, ...options }
+  const colors = Array.isArray(opts.color)
+    ? opts.color
+    : [opts.color ?? '#38bdf8']
+
+  const rect = el.getBoundingClientRect()
+  const centerX = rect.left + rect.width / 2
+  const centerY = rect.top + rect.height / 2
+
+  const particles: Particle[] = []
+
+  for (let i = 0; i < opts.count; i++) {
+    const angle = (Math.PI * 2 * i) / opts.count + Math.random() * 0.5
+    const velocity = opts.speed * (0.5 + Math.random() * 0.8)
+
+    const pEl = document.createElement('div')
+    pEl.style.cssText = `
+      position: fixed;
+      left: ${centerX}px;
+      top: ${centerY}px;
+      width: ${opts.size}px;
+      height: ${opts.size}px;
+      border-radius: 50%;
+      background: ${colors[i % colors.length]};
+      pointer-events: none;
+      z-index: 9999;
+    `
+    document.body.appendChild(pEl)
+
+    particles.push({
+      el: pEl,
+      vx: Math.cos(angle) * velocity,
+      vy: Math.sin(angle) * velocity,
+      x: centerX,
+      y: centerY,
+      life: 0,
+      maxLife: opts.duration!,
+    })
+  }
+
+  return new Promise((resolve) => {
+    const startTime = performance.now()
+
+    const tick = (now: number) => {
+      const elapsed = now - startTime
+      let alive = 0
+
+      particles.forEach((p) => {
+        p.life = elapsed
+        p.vy += opts.gravity!
+        p.x += p.vx
+        p.y += p.vy
+
+        const progress = p.life / p.maxLife
+        const opacity = opts.fadeOut ? 1 - progress : 1
+
+        if (progress < 1) {
+          alive++
+          p.el.style.transform = `translate(${p.x - centerX}px, ${p.y - centerY}px)`
+          p.el.style.opacity = String(Math.max(0, opacity))
+        }
+      })
+
+      if (alive > 0) {
+        requestAnimationFrame(tick)
+      } else {
+        particles.forEach((p) => p.el.remove())
+        resolve()
+      }
+    }
+
+    requestAnimationFrame(tick)
+  })
+}
+
+/**
+ * 在点击位置触发粒子（不绑定元素）
+ */
+export function particleAt(
+  x: number,
+  y: number,
+  options: ParticleOptions = {}
+): Promise<void> {
+  const dummy = document.createElement('div')
+  dummy.style.position = 'fixed'
+  dummy.style.left = x + 'px'
+  dummy.style.top = y + 'px'
+  document.body.appendChild(dummy)
+
+  return particleBurst(dummy, options).finally(() => dummy.remove())
+}

package/src/effects/text-split.ts

@@ -0,0 +1,95 @@
+export interface TextSplitOptions {
+  type?: 'char' | 'word'       // 按字符拆分还是按词
+  stagger?: number             // 每个元素间隔毫秒
+  duration?: number            // 单个动画时长
+  animation?: 'fadeUp' | 'fadeDown' | 'zoomIn' | 'rotateIn' | 'slideLeft'
+}
+
+const DEFAULT_SPLIT: Required<Omit<TextSplitOptions, 'type'>> & { type: 'char' } = {
+  type: 'char',
+  stagger: 40,
+  duration: 500,
+  animation: 'fadeUp',
+}
+
+const ANIMATION_PRESETS: Record<string, { from: string; to: string }> = {
+  fadeUp:    { from: 'opacity:0;transform:translateY(20px)',   to: 'opacity:1;transform:translateY(0)' },
+  fadeDown:  { from: 'opacity:0;transform:translateY(-20px)',  to: 'opacity:1;transform:translateY(0)' },
+  zoomIn:    { from: 'opacity:0;transform:scale(0.5)',         to: 'opacity:1;transform:scale(1)' },
+  rotateIn:  { from: 'opacity:0;transform:rotate(-180deg)',    to: 'opacity:1;transform:rotate(0)' },
+  slideLeft: { from: 'opacity:0;transform:translateX(-30px)',  to: 'opacity:1;transform:translateX(0)' },
+}
+
+export class TextSplit {
+  private element: HTMLElement
+  private originalHTML: string
+
+  constructor(element: HTMLElement | string) {
+    this.element =
+      typeof element === 'string'
+        ? document.querySelector(element)!
+        : element
+
+    if (!this.element) {
+      throw new Error('TextSplit: element not found')
+    }
+
+    this.originalHTML = this.element.innerHTML
+  }
+
+  async animate(options: TextSplitOptions = {}): Promise<void> {
+    const opts = { ...DEFAULT_SPLIT, ...options }
+    const preset = ANIMATION_PRESETS[opts.animation!]
+    const text = this.element.textContent ?? ''
+
+    // 清空并拆分
+    this.element.innerHTML = ''
+    this.element.style.display = 'inline-block'
+
+    const parts = opts.type === 'char' ? text.split('') : text.split(/(\s+)/)
+    const spans: HTMLSpanElement[] = []
+
+    parts.forEach((part) => {
+      const span = document.createElement('span')
+      span.textContent = part
+      span.style.display = 'inline-block'
+      span.style.cssText += preset.from
+      span.style.transition = `all ${opts.duration}ms cubic-bezier(0.34, 1.56, 0.64, 1)`
+      this.element.appendChild(span)
+      spans.push(span)
+    })
+
+    // 强制重排
+    this.element.offsetHeight
+
+    return new Promise((resolve) => {
+      let completed = 0
+      const total = spans.length
+
+      spans.forEach((span, i) => {
+        setTimeout(() => {
+          span.style.cssText += preset.to
+
+          setTimeout(() => {
+            completed++
+            if (completed >= total) resolve()
+          }, opts.duration)
+        }, i * opts.stagger)
+      })
+    })
+  }
+
+  reset(): void {
+    this.element.innerHTML = this.originalHTML
+    this.element.style.display = ''
+  }
+}
+
+export function splitText(
+  element: HTMLElement | string,
+  options?: TextSplitOptions
+): Promise<void> {
+  const ts = new TextSplit(element)
+  ts.reset()
+  return ts.animate(options)
+}