@readdy/anim 0.0.21

package/dist/types/stories/magnetic-hover.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimMagneticHover } from '../animations/button/magnetic-hover/react';
+import '../animations/button/magnetic-hover/style.css';
+declare const meta: Meta<typeof AnimMagneticHover>;
+export default meta;
+type Story = StoryObj<typeof AnimMagneticHover>;
+export declare const Default: Story;

package/dist/types/stories/pop-in-stack.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimPopInStack } from '../animations/card/pop-in-stack/react';
+import '../animations/card/pop-in-stack/style.css';
+declare const meta: Meta<typeof AnimPopInStack>;
+export default meta;
+type Story = StoryObj<typeof AnimPopInStack>;
+export declare const Default: Story;

package/dist/types/stories/pulse.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimPulse } from '../animations/button/pulse/react';
+import '../animations/button/pulse/style.css';
+declare const meta: Meta<typeof AnimPulse>;
+export default meta;
+type Story = StoryObj<typeof AnimPulse>;
+export declare const Default: Story;
+export declare const WithContent: Story;

package/dist/types/stories/rainbow-button.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimRainbowButton } from '../animations/button/rainbow-button/react';
+import '../animations/button/rainbow-button/style.css';
+declare const meta: Meta<typeof AnimRainbowButton>;
+export default meta;
+type Story = StoryObj<typeof AnimRainbowButton>;
+export declare const Default: Story;
+export declare const WithContent: Story;

package/dist/types/stories/reveal-from-top.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimRevealFromTop } from '../animations/card/reveal-from-top/react';
+import '../animations/card/reveal-from-top/style.css';
+declare const meta: Meta<typeof AnimRevealFromTop>;
+export default meta;
+type Story = StoryObj<typeof AnimRevealFromTop>;
+export declare const Default: Story;
+export declare const WithContent: Story;

package/dist/types/stories/rgb-split-glitch.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimRgbSplitGlitch } from '../animations/card/rgb-split-glitch/react';
+import '../animations/card/rgb-split-glitch/style.css';
+declare const meta: Meta<typeof AnimRgbSplitGlitch>;
+export default meta;
+type Story = StoryObj<typeof AnimRgbSplitGlitch>;
+export declare const Default: Story;
+export declare const WithContent: Story;

package/dist/types/stories/roll-in.stories.d.ts

@@ -0,0 +1,9 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimRollIn } from '../animations/header/roll-in/react';
+import '../animations/header/roll-in/style.css';
+declare const meta: Meta<typeof AnimRollIn>;
+export default meta;
+type Story = StoryObj<typeof AnimRollIn>;
+export declare const Default: Story;
+export declare const WithContent: Story;
+export declare const ChineseRichText: Story;

package/dist/types/stories/shimmer-border.stories.d.ts

@@ -0,0 +1,9 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimShimmerBorder } from '../animations/button/shimmer-border/react';
+import '../animations/button/shimmer-border/style.css';
+declare const meta: Meta<typeof AnimShimmerBorder>;
+export default meta;
+type Story = StoryObj<typeof AnimShimmerBorder>;
+export declare const Default: Story;
+export declare const WithContent: Story;
+export declare const Hover: Story;

package/dist/types/stories/shimmer-text.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimShimmerText } from '../animations/header/shimmer-text/react';
+import '../animations/header/shimmer-text/style.css';
+declare const meta: Meta<typeof AnimShimmerText>;
+export default meta;
+type Story = StoryObj<typeof AnimShimmerText>;
+export declare const Default: Story;
+export declare const ChineseRichText: Story;

package/dist/types/stories/shuffle.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimShuffle } from '../animations/header/shuffle/react';
+import '../animations/header/shuffle/style.css';
+declare const meta: Meta<typeof AnimShuffle>;
+export default meta;
+type Story = StoryObj<typeof AnimShuffle>;
+export declare const Default: Story;
+export declare const RichTextHeading: Story;

package/dist/types/stories/sketch-button.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimSketchButton } from '../animations/button/sketch-button/react';
+import '../animations/button/sketch-button/style.css';
+declare const meta: Meta<typeof AnimSketchButton>;
+export default meta;
+type Story = StoryObj<typeof AnimSketchButton>;
+export declare const Default: Story;

package/dist/types/stories/split-text.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimSplitText } from '../animations/header/split-text/react';
+import '../animations/header/split-text/style.css';
+declare const meta: Meta<typeof AnimSplitText>;
+export default meta;
+type Story = StoryObj<typeof AnimSplitText>;
+export declare const Default: Story;
+export declare const ChineseRichText: Story;

package/dist/types/stories/text-type.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimTextType } from '../animations/header/text-type/react';
+import '../animations/header/text-type/style.css';
+declare const meta: Meta<typeof AnimTextType>;
+export default meta;
+type Story = StoryObj<typeof AnimTextType>;
+export declare const Default: Story;
+export declare const RichTextHeading: Story;

package/dist/types/stories/tilted-card.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimTiltedCard } from '../animations/card/tilted-card/react';
+import '../animations/card/tilted-card/style.css';
+declare const meta: Meta<typeof AnimTiltedCard>;
+export default meta;
+type Story = StoryObj<typeof AnimTiltedCard>;
+export declare const Default: Story;

package/dist/types/stories/word-curtain-reveal.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AnimWordCurtainReveal } from '../animations/header/word-curtain-reveal/react';
+import '../animations/header/word-curtain-reveal/style.css';
+declare const meta: Meta<typeof AnimWordCurtainReveal>;
+export default meta;
+type Story = StoryObj<typeof AnimWordCurtainReveal>;
+export declare const Default: Story;
+export declare const RichTextHeading: Story;

package/package.json

@@ -0,0 +1,166 @@
+{
+  "name": "@readdy/anim",
+  "version": "0.0.21",
+  "type": "module",
+  "description": "Readdy animation library — pure JS + CSS animations for the Readdy AI website editor",
+  "main": "dist/full.js",
+  "module": "dist/full.js",
+  "types": "dist/types/react-barrel.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    "./header/letter-bounce": "./animations/header/letter-bounce/index.js",
+    "./header/letter-bounce/style.css": "./animations/header/letter-bounce/style.css",
+    "./header/letter-bounce/react": "./animations/header/letter-bounce/react.tsx",
+    "./header/shimmer-text": "./animations/header/shimmer-text/index.js",
+    "./header/shimmer-text/style.css": "./animations/header/shimmer-text/style.css",
+    "./header/shimmer-text/react": "./animations/header/shimmer-text/react.tsx",
+    "./header/split-text": "./animations/header/split-text/index.js",
+    "./header/split-text/style.css": "./animations/header/split-text/style.css",
+    "./header/split-text/react": "./animations/header/split-text/react.tsx",
+    "./header/gradient-text": "./animations/header/gradient-text/index.js",
+    "./header/gradient-text/style.css": "./animations/header/gradient-text/style.css",
+    "./header/gradient-text/react": "./animations/header/gradient-text/react.tsx",
+    "./header/text-type": "./animations/header/text-type/index.js",
+    "./header/text-type/style.css": "./animations/header/text-type/style.css",
+    "./header/text-type/react": "./animations/header/text-type/react.tsx",
+    "./header/fly-in-chars": "./animations/header/fly-in-chars/index.js",
+    "./header/fly-in-chars/style.css": "./animations/header/fly-in-chars/style.css",
+    "./header/fly-in-chars/react": "./animations/header/fly-in-chars/react.tsx",
+    "./header/shuffle": "./animations/header/shuffle/index.js",
+    "./header/shuffle/style.css": "./animations/header/shuffle/style.css",
+    "./header/shuffle/react": "./animations/header/shuffle/react.tsx",
+    "./header/word-curtain-reveal": "./animations/header/word-curtain-reveal/index.js",
+    "./header/word-curtain-reveal/style.css": "./animations/header/word-curtain-reveal/style.css",
+    "./header/word-curtain-reveal/react": "./animations/header/word-curtain-reveal/react.tsx",
+    "./header/roll-in": "./animations/header/roll-in/index.js",
+    "./header/roll-in/style.css": "./animations/header/roll-in/style.css",
+    "./header/roll-in/react": "./animations/header/roll-in/react.tsx",
+    "./header/bounce-in-down": "./animations/header/bounce-in-down/index.js",
+    "./header/bounce-in-down/style.css": "./animations/header/bounce-in-down/style.css",
+    "./header/bounce-in-down/react": "./animations/header/bounce-in-down/react.tsx",
+    "./header/anime-splittext": "./animations/header/anime-splittext/index.js",
+    "./header/anime-splittext/style.css": "./animations/header/anime-splittext/style.css",
+    "./header/anime-splittext/react": "./animations/header/anime-splittext/react.tsx",
+    "./button/magnetic-hover": "./animations/button/magnetic-hover/index.js",
+    "./button/magnetic-hover/style.css": "./animations/button/magnetic-hover/style.css",
+    "./button/magnetic-hover/react": "./animations/button/magnetic-hover/react.tsx",
+    "./button/border-beam": "./animations/button/border-beam/index.js",
+    "./button/border-beam/style.css": "./animations/button/border-beam/style.css",
+    "./button/border-beam/react": "./animations/button/border-beam/react.tsx",
+    "./button/shimmer-border": "./animations/button/shimmer-border/index.js",
+    "./button/shimmer-border/style.css": "./animations/button/shimmer-border/style.css",
+    "./button/shimmer-border/react": "./animations/button/shimmer-border/react.tsx",
+    "./button/rainbow-button": "./animations/button/rainbow-button/index.js",
+    "./button/rainbow-button/style.css": "./animations/button/rainbow-button/style.css",
+    "./button/rainbow-button/react": "./animations/button/rainbow-button/react.tsx",
+    "./button/sketch-button": "./animations/button/sketch-button/index.js",
+    "./button/sketch-button/style.css": "./animations/button/sketch-button/style.css",
+    "./button/sketch-button/react": "./animations/button/sketch-button/react.tsx",
+    "./button/confetti-button": "./animations/button/confetti-button/index.js",
+    "./button/confetti-button/style.css": "./animations/button/confetti-button/style.css",
+    "./button/confetti-button/react": "./animations/button/confetti-button/react.tsx",
+    "./button/glow-cta": "./animations/button/glow-cta/index.js",
+    "./button/glow-cta/style.css": "./animations/button/glow-cta/style.css",
+    "./button/glow-cta/react": "./animations/button/glow-cta/react.tsx",
+    "./button/bubble-button": "./animations/button/bubble-button/index.js",
+    "./button/bubble-button/style.css": "./animations/button/bubble-button/style.css",
+    "./button/bubble-button/react": "./animations/button/bubble-button/react.tsx",
+    "./button/bounce-elastic": "./animations/button/bounce-elastic/index.js",
+    "./button/bounce-elastic/style.css": "./animations/button/bounce-elastic/style.css",
+    "./button/bounce-elastic/react": "./animations/button/bounce-elastic/react.tsx",
+    "./button/pulse": "./animations/button/pulse/index.js",
+    "./button/pulse/style.css": "./animations/button/pulse/style.css",
+    "./button/pulse/react": "./animations/button/pulse/react.tsx",
+    "./button/blur-fade-in": "./animations/button/blur-fade-in/index.js",
+    "./button/blur-fade-in/style.css": "./animations/button/blur-fade-in/style.css",
+    "./button/blur-fade-in/react": "./animations/button/blur-fade-in/react.tsx",
+    "./button/3d-flip": "./animations/button/3d-flip/index.js",
+    "./button/3d-flip/style.css": "./animations/button/3d-flip/style.css",
+    "./button/3d-flip/react": "./animations/button/3d-flip/react.tsx",
+    "./card/blur-rise": "./animations/card/blur-rise/index.js",
+    "./card/blur-rise/style.css": "./animations/card/blur-rise/style.css",
+    "./card/blur-rise/react": "./animations/card/blur-rise/react.tsx",
+    "./card/float-idle": "./animations/card/float-idle/index.js",
+    "./card/float-idle/style.css": "./animations/card/float-idle/style.css",
+    "./card/float-idle/react": "./animations/card/float-idle/react.tsx",
+    "./card/tilted-card": "./animations/card/tilted-card/index.js",
+    "./card/tilted-card/style.css": "./animations/card/tilted-card/style.css",
+    "./card/tilted-card/react": "./animations/card/tilted-card/react.tsx",
+    "./card/card-flip": "./animations/card/card-flip/index.js",
+    "./card/card-flip/style.css": "./animations/card/card-flip/style.css",
+    "./card/card-flip/react": "./animations/card/card-flip/react.tsx",
+    "./card/image-zoom-rotate": "./animations/card/image-zoom-rotate/index.js",
+    "./card/image-zoom-rotate/style.css": "./animations/card/image-zoom-rotate/style.css",
+    "./card/image-zoom-rotate/react": "./animations/card/image-zoom-rotate/react.tsx",
+    "./card/rgb-split-glitch": "./animations/card/rgb-split-glitch/index.js",
+    "./card/rgb-split-glitch/style.css": "./animations/card/rgb-split-glitch/style.css",
+    "./card/rgb-split-glitch/react": "./animations/card/rgb-split-glitch/react.tsx",
+    "./card/card-fan-spread": "./animations/card/card-fan-spread/index.js",
+    "./card/card-fan-spread/style.css": "./animations/card/card-fan-spread/style.css",
+    "./card/card-fan-spread/react": "./animations/card/card-fan-spread/react.tsx",
+    "./card/image-magnifier": "./animations/card/image-magnifier/index.js",
+    "./card/image-magnifier/style.css": "./animations/card/image-magnifier/style.css",
+    "./card/image-magnifier/react": "./animations/card/image-magnifier/react.tsx",
+    "./card/pop-in-stack": "./animations/card/pop-in-stack/index.js",
+    "./card/pop-in-stack/style.css": "./animations/card/pop-in-stack/style.css",
+    "./card/pop-in-stack/react": "./animations/card/pop-in-stack/react.tsx",
+    "./card/bounce-in-bottom": "./animations/card/bounce-in-bottom/index.js",
+    "./card/bounce-in-bottom/style.css": "./animations/card/bounce-in-bottom/style.css",
+    "./card/bounce-in-bottom/react": "./animations/card/bounce-in-bottom/react.tsx",
+    "./card/reveal-from-top": "./animations/card/reveal-from-top/index.js",
+    "./card/reveal-from-top/style.css": "./animations/card/reveal-from-top/style.css",
+    "./card/reveal-from-top/react": "./animations/card/reveal-from-top/react.tsx",
+    "./shared/text-split": "./shared/text-split.js",
+    "./react": "./react-barrel.js"
+  },
+  "files": [
+    "animations",
+    "shared",
+    "react-barrel.js",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly && node scripts/generate-dist-meta.js && node scripts/copy-metadata.js",
+    "id-map:sync": "node scripts/generate-animation-id-map.js",
+    "metadata:check": "node scripts/check-metadata.js",
+    "metadata:update": "node scripts/update-metadata.js",
+    "preview:sync": "node scripts/generate-preview-manifest.js && node scripts/generate-animation-id-map.js",
+    "preview": "npm run preview:sync && vite --config preview/vite.config.js",
+    "preview:build": "npm run preview:sync && vite build --config preview/vite.config.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@storybook/addon-controls": "^9.0.8",
+    "@storybook/addon-docs": "^10.4.2",
+    "@storybook/react": "^10.4.2",
+    "@storybook/react-vite": "^10.4.2",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.2.0",
+    "jsdom": "^24.0.0",
+    "postcss": "^8.4.38",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.18.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "storybook": "^10.4.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "license": "MIT"
+}

package/react-barrel.js

@@ -0,0 +1,44 @@
+/**
+ * @readdy/anim/react — React 组件桶导出
+ * 用法：import { AnimBlurRise } from '@readdy/anim/react'
+ */
+
+// header
+export { AnimLetterBounce } from './animations/header/letter-bounce/react.tsx'
+export { AnimShimmerText } from './animations/header/shimmer-text/react.tsx'
+export { AnimSplitText } from './animations/header/split-text/react.tsx'
+export { AnimGradientText } from './animations/header/gradient-text/react.tsx'
+export { AnimTextType } from './animations/header/text-type/react.tsx'
+export { AnimFlyInChars } from './animations/header/fly-in-chars/react.tsx'
+export { AnimShuffle } from './animations/header/shuffle/react.tsx'
+export { AnimWordCurtainReveal } from './animations/header/word-curtain-reveal/react.tsx'
+export { AnimRollIn } from './animations/header/roll-in/react.tsx'
+export { AnimBounceInDown } from './animations/header/bounce-in-down/react.tsx'
+export { AnimAnimeSplittext } from './animations/header/anime-splittext/react.tsx'
+
+// button
+export { AnimMagneticHover } from './animations/button/magnetic-hover/react.tsx'
+export { AnimBorderBeam } from './animations/button/border-beam/react.tsx'
+export { AnimShimmerBorder } from './animations/button/shimmer-border/react.tsx'
+export { AnimRainbowButton } from './animations/button/rainbow-button/react.tsx'
+export { AnimSketchButton } from './animations/button/sketch-button/react.tsx'
+export { AnimConfettiButton } from './animations/button/confetti-button/react.tsx'
+export { AnimGlowCta } from './animations/button/glow-cta/react.tsx'
+export { AnimBubbleButton } from './animations/button/bubble-button/react.tsx'
+export { AnimBounceElastic } from './animations/button/bounce-elastic/react.tsx'
+export { AnimPulse } from './animations/button/pulse/react.tsx'
+export { AnimBlurFadeIn } from './animations/button/blur-fade-in/react.tsx'
+export { Anim3DFlip } from './animations/button/3d-flip/react.tsx'
+
+// card
+export { AnimBlurRise } from './animations/card/blur-rise/react.tsx'
+export { AnimFloatIdle } from './animations/card/float-idle/react.tsx'
+export { AnimTiltedCard } from './animations/card/tilted-card/react.tsx'
+export { AnimCardFlip } from './animations/card/card-flip/react.tsx'
+export { AnimImageZoomRotate } from './animations/card/image-zoom-rotate/react.tsx'
+export { AnimRgbSplitGlitch } from './animations/card/rgb-split-glitch/react.tsx'
+export { AnimCardFanSpread } from './animations/card/card-fan-spread/react.tsx'
+export { AnimImageMagnifier } from './animations/card/image-magnifier/react.tsx'
+export { AnimPopInStack } from './animations/card/pop-in-stack/react.tsx'
+export { AnimBounceInBottom } from './animations/card/bounce-in-bottom/react.tsx'
+export { AnimRevealFromTop } from './animations/card/reveal-from-top/react.tsx'

package/shared/constants.js

@@ -0,0 +1,64 @@
+/**
+ * @readdy/anim/shared/constants.js
+ *
+ * 共享常量 —— 动效 ID 前缀、class 前缀、ID 构建器
+ * 解决 issues #2：动效 ID 前缀不一致
+ */
+
+/** 动效 ID 前缀，统一格式 */
+export const ANIM_ID_PREFIX = 'readdy-anim-'
+
+/** CSS class 前缀 */
+export const ANIM_CLASS_PREFIX = 'readdy-anim-'
+
+/**
+ * 构建动效 CSS class
+ * @param {string} name - class 后缀，如 'text-type'
+ * @returns {string} 完整 class，如 'readdy-anim-text-type'
+ */
+export function buildAnimClass(name) {
+  return ANIM_CLASS_PREFIX + name
+}
+
+/**
+ * 构建动效相关 DOM id
+ * 目前与 class 前缀保持一致，便于 SVG filter / portal 节点等共享同一命名空间。
+ *
+ * @param {string} name - id 后缀，如 'bubble-goo'
+ * @returns {string} 完整 id，如 'readdy-anim-bubble-goo'
+ */
+export function buildAnimDomId(name) {
+  return ANIM_CLASS_PREFIX + name
+}
+
+/**
+ * 构建动效规范 ID
+ * 统一接受动效 slug，例如：
+ * - buildAnimId('letter-bounce') => 'readdy-anim-letter-bounce'
+ * - buildAnimId('bubble-button') => 'readdy-anim-bubble-button'
+ *
+ * @param {string} name - 动效 slug
+ * @returns {string} 规范 ID
+ */
+export function buildAnimId(name) {
+  const slug = String(name).trim()
+
+  if (!slug) {
+    throw new Error('buildAnimId(name) requires a non-empty animation slug')
+  }
+
+  if (slug.includes('/')) {
+    throw new Error(`buildAnimId(name) only accepts animation slugs, received path-like value: ${slug}`)
+  }
+
+  const normalizedSlug = slug
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase()
+
+  if (!normalizedSlug) {
+    throw new Error(`buildAnimId(name) could not derive a valid animation slug from: ${slug}`)
+  }
+
+  return ANIM_ID_PREFIX + normalizedSlug
+}

package/shared/meta.js

@@ -0,0 +1,21 @@
+/**
+ * @readdy/anim/shared/meta.js
+ *
+ * 元数据工具 —— 从 options 定义派生默认值
+ * 解决 issues #3：animation.defaultOptions 字段不存在
+ */
+
+/**
+ * 从 options 定义中提取默认值
+ *
+ * @param {Record<string, { default: any, type: string, description?: string }>} optionsDef
+ *   动效的 options 定义，如 { stagger: { default: 60, type: 'number' }, ... }
+ * @returns {Record<string, any>} 默认值对象，如 { stagger: 60, ... }
+ */
+export function getDefaultOptions(optionsDef) {
+  const result = {}
+  for (const [key, def] of Object.entries(optionsDef)) {
+    result[key] = def.default
+  }
+  return result
+}

package/shared/pointer-follow.js

@@ -0,0 +1,91 @@
+export function getPointerMetrics(target, event) {
+  const rect =
+    target && typeof target.getBoundingClientRect === 'function'
+      ? target.getBoundingClientRect()
+      : target
+  const centerX = rect.left + rect.width / 2
+  const centerY = rect.top + rect.height / 2
+  const deltaX = event.clientX - centerX
+  const deltaY = event.clientY - centerY
+
+  return {
+    rect,
+    deltaX,
+    deltaY,
+    relativeX: rect.width ? deltaX / rect.width : 0,
+    relativeY: rect.height ? deltaY / rect.height : 0,
+  }
+}
+
+export function attachPointerFollow(el, handlers) {
+  const { onMove, onLeave, onEnter } = handlers
+  const requestFrame =
+    window.requestAnimationFrame?.bind(window) ?? ((callback) => window.setTimeout(callback, 16))
+  const cancelFrame =
+    window.cancelAnimationFrame?.bind(window) ?? ((frameId) => window.clearTimeout(frameId))
+
+  let frameId = null
+  let lastEvent = null
+  let activeRect = null
+
+  const context = {
+    get rect() {
+      return activeRect
+    },
+    refreshRect() {
+      activeRect = el.getBoundingClientRect()
+      return activeRect
+    },
+    getMetrics(event) {
+      return getPointerMetrics(activeRect ?? context.refreshRect(), event)
+    },
+  }
+
+  const flushMove = () => {
+    frameId = null
+    if (!lastEvent) {
+      return
+    }
+    if (!activeRect) {
+      context.refreshRect()
+    }
+    onMove(lastEvent, context)
+  }
+
+  const handleEnter = (event) => {
+    context.refreshRect()
+    onEnter?.(event, context)
+  }
+
+  const handleMove = (event) => {
+    lastEvent = event
+    if (frameId !== null) {
+      return
+    }
+    frameId = requestFrame(flushMove)
+  }
+
+  const handleLeave = (event) => {
+    if (frameId !== null) {
+      cancelFrame(frameId)
+      frameId = null
+    }
+    lastEvent = null
+    activeRect = null
+    onLeave?.(event, context)
+  }
+
+  el.addEventListener('pointerenter', handleEnter)
+  el.addEventListener('pointermove', handleMove)
+  el.addEventListener('pointerleave', handleLeave)
+
+  return () => {
+    if (frameId !== null) {
+      cancelFrame(frameId)
+      frameId = null
+    }
+    el.removeEventListener('pointerenter', handleEnter)
+    el.removeEventListener('pointermove', handleMove)
+    el.removeEventListener('pointerleave', handleLeave)
+  }
+}

package/shared/reduced-motion.js

@@ -0,0 +1,15 @@
+/**
+ * @readdy/anim/shared/reduced-motion.js
+ *
+ * 无障碍工具 —— 检测 prefers-reduced-motion
+ * 所有 React 组件和 init 函数统一使用此函数
+ */
+
+/**
+ * 检测用户是否偏好减少动画
+ * @returns {boolean} true 表示用户偏好减少动画
+ */
+export function prefersReducedMotion() {
+  return typeof window !== 'undefined' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}

package/shared/resolve-card-media.js

@@ -0,0 +1,41 @@
+function hasUsableBackgroundImage(node) {
+  const style = window.getComputedStyle(node)
+  return Boolean(style.backgroundImage && style.backgroundImage !== 'none')
+}
+
+export function resolveCardMediaElement(el, mediaClass) {
+  const byClass = el.querySelector(`.${mediaClass}`)
+  if (byClass instanceof HTMLElement) {
+    return byClass
+  }
+
+  const image = el.querySelector('img')
+  if (image instanceof HTMLImageElement) {
+    let candidate = image.parentElement
+    while (candidate && candidate !== el) {
+      const style = window.getComputedStyle(candidate)
+      if (
+        style.overflow === 'hidden' ||
+        style.position !== 'static' ||
+        candidate.childElementCount === 1 ||
+        hasUsableBackgroundImage(candidate)
+      ) {
+        return candidate
+      }
+      candidate = candidate.parentElement
+    }
+  }
+
+  const backgroundCandidate = Array.from(el.querySelectorAll('*')).find((node) => {
+    if (!(node instanceof HTMLElement)) {
+      return false
+    }
+    return hasUsableBackgroundImage(node)
+  })
+
+  if (backgroundCandidate instanceof HTMLElement) {
+    return backgroundCandidate
+  }
+
+  return el.firstElementChild instanceof HTMLElement ? el.firstElementChild : el
+}