hero-animate 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SinJayXie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# hero-animate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+iOS 风格「图标 ⇄ 窗口」形变转场：窗口从触发元素（按钮 / 图标）的矩形展开，关闭时沿同一条路径收回原处。框架无关核心 + Vue 3 / React 开箱即用组件。
+
+[![npm](https://img.shields.io/npm/v/hero-animate.svg)](https://www.npmjs.com/package/hero-animate)
+[![license](https://img.shields.io/npm/l/hero-animate.svg)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-GitHub%20Pages-5b5bd6)](https://sinjayxie.github.io/hero-animate/)
+
+- **形变转场**：遮罩 + 面板 + 图标克隆三层交叉，视觉上「图标长成窗口 / 窗口塌回图标」
+- **零配置**：自动记录 pointerdown 触发源；无触发源时回落到本体中心缩放
+- **Vue / React 组件**：`open` 状态驱动，内置挂载 / 卸载与离场动画管理
+- **弹簧可调**：`mass / stiffness / damping / velocity` 任意字段覆盖，其余用默认值
+- **无障碍**：`prefers-reduced-motion` 下自动跳过动画
+- **ESM + 类型**：核心入口零框架依赖，`vue` / `react` 为可选 peer
+
+## 安装
+
+```bash
+pnpm add hero-animate animejs
+# Vue 项目额外安装 vue（已有可跳过）
+# React 项目额外安装 react（已有可跳过）
+```
+
+`animejs@^4` 为必装 peer 依赖；`vue` / `react` 仅在引入对应子入口时需要。
+
+## 快速开始
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { HeroTransition } from "hero-animate/vue";
+
+const open = ref(false);
+</script>
+
+<template>
+  <button class="icon-button" @click="open = true">📁</button>
+
+  <HeroTransition :open="open" class="modal-mask" @exited="open = false">
+    <div class="modal-panel">
+      <h3>从图标长出来的窗口</h3>
+      <button @click="open = false">关闭</button>
+    </div>
+  </HeroTransition>
+</template>
+```
+
+### React
+
+```tsx
+import { useState } from "react";
+import { HeroTransition } from "hero-animate/react";
+
+export function Demo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button className="icon-button" onClick={() => setOpen(true)}>📁</button>
+
+      <HeroTransition open={open} className="modal-mask" onExited={() => {}}>
+        <div className="modal-panel">
+          <h3>从图标长出来的窗口</h3>
+          <button onClick={() => setOpen(false)}>关闭</button>
+        </div>
+      </HeroTransition>
+    </>
+  );
+}
+```
+
+### 锚定浮层（下拉 / 菜单）
+
+`masked={false}` 时根元素本身就是面板；配合 `ghostOnly`，浮层只动克隆体，真实浮层在飞行期间让位，适合 JS 定位的小浮层。
+
+```tsx
+<HeroTransition
+  open={open}
+  masked={false}
+  ghostOnly
+  anchor={() => buttonRef.current}
+  className="popover-panel"
+  style={{ position: "fixed", left: x, top: y }}
+>
+  …
+</HeroTransition>
+```
+
+### 核心 API（任意框架 / 原生）
+
+```ts
+import { createHeroTransition } from "hero-animate";
+
+const hero = createHeroTransition(
+  (root) => root.querySelector(".modal-panel"),
+  { masked: true }
+);
+
+// CSS hooks 语义：动画结束调用 done
+hero.onEnter(maskEl, () => {});
+hero.onLeave(maskEl, () => {});
+hero.cancel(); // 中断并清理
+```
+
+`createDialogHero(selector = ".modal-panel", options?)` 是外层 `<Transition :css="false">` 场景的语法糖。
+
+## CSS 约定
+
+转场不注入任何样式，但会读取元素的自然样式来对齐：
+
+```css
+.modal-mask {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(4px); /* 会被读取为遮罩动画的终点模糊值 */
+}
+
+.modal-panel {
+  width: 420px;
+  border-radius: 20px;
+  background: #fff;
+}
+```
+
+- 面板选择器默认 `.modal-panel`，可用 `panelSelector` 覆盖
+- 组件在原地渲染：若祖先节点带 `transform` / `filter` / `backdrop-filter`，`position: fixed` 会以该祖先为包含块。建议将弹窗挂到 `body`（Vue `Teleport` / React Portal）
+
+## API
+
+### HeroOptions
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `masked` | `boolean` | `true` | 根元素是遮罩（内部找面板）；`false` 时根元素本身就是面板 |
+| `panelSelector` | `string` | `".modal-panel"` | 面板选择器，用于在根元素内定位面板 |
+| `anchor` | `() => HTMLElement \| null` | — | 无指针来源时的锚点（快捷键打开等场景） |
+| `ghostOnly` | `boolean` | `false` | 只动画克隆体，不写真实浮层 transform |
+| `spring` | `HeroSpringParams` | 见下 | 打开曲线弹簧参数 |
+| `springAccel` | `HeroSpringParams` | 见下 | 关闭曲线弹簧参数 |
+
+### HeroHandlers
+
+| 成员 | 类型 | 说明 |
+| --- | --- | --- |
+| `onEnter` | `(el: Element, done: () => void) => void` | 打开转场，结束调用 `done` |
+| `onLeave` | `(el: Element, done: () => void) => void` | 关闭转场，结束调用 `done` |
+| `cancel` | `() => void` | 中断时间线、移除克隆层、还原被隐藏的触发元素 |
+
+### 组件 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | 必填，驱动打开 / 关闭 |
+| `masked` | `boolean` | `true` | 同 `HeroOptions.masked` |
+| `panelSelector` | `string` | `".modal-panel"` | 同 `HeroOptions.panelSelector` |
+| `anchor` | `() => HTMLElement \| null` | — | 同 `HeroOptions.anchor` |
+| `ghostOnly` | `boolean` | `false` | 同 `HeroOptions.ghostOnly` |
+| `spring` / `springAccel` | `HeroSpringParams` | 见下 | 弹簧参数 |
+
+- Vue：`entered` / `exited` 事件，其余 attrs 透传根元素
+- React：`onEntered` / `onExited` 回调，额外支持 `className` / `style` / `children`
+
+## 弹簧参数
+
+默认值与 `SPRING_PARAMS` 一致：
+
+```ts
+import { SPRING_PARAMS } from "hero-animate";
+
+// { mass: 1, stiffness: 250, damping: 35, velocity: 20 }
+```
+
+只传想覆盖的字段，其余自动回落：
+
+```ts
+createHeroTransition(getPanel, {
+  spring: { stiffness: 300, damping: 32 },      // 打开
+  springAccel: { stiffness: 280, damping: 30 }, // 关闭
+});
+```
+
+| 字段 | 含义 | 默认值 |
+| --- | --- | --- |
+| `mass` | 质量，越大越迟滞 | `1` |
+| `stiffness` | 刚度，越大越快 | `250` |
+| `damping` | 阻尼，越小回弹越明显 | `35` |
+| `velocity` | 初速度 | `20` |
+
+## 触发源追踪
+
+库在创建转场时自动在 window 捕获阶段安装一次监听，记录最近一次 pointerdown 命中的 `button / [role="button"] / a / label` 及其矩形（800ms 内有效）。如需提前安装：
+
+```ts
+import { installModalSourceTracking } from "hero-animate";
+installModalSourceTracking();
+```
+
+## 开发与发布
+
+```bash
+pnpm install
+pnpm dev          # 本地文档 + 演示（http://localhost:5173）
+pnpm typecheck    # 类型检查
+pnpm build        # 构建 dist/（ESM + d.ts）
+pnpm docs:build   # 构建文档站到 docs-dist/
+npm publish       # 发布（prepublishOnly 会自动构建）
+```
+
+文档站通过 [deploy-docs.yml](./.github/workflows/deploy-docs.yml) 在 push 到 `main` 时自动发布到 GitHub Pages。首次部署前需在仓库 **Settings → Pages → Build and deployment** 将 Source 设为 **GitHub Actions**（`GITHUB_TOKEN` 无权自动创建 Pages 站点）。
+
+## License
+
+[MIT](./LICENSE) © SinJayXie

package/dist/heroTransition-CND4UQtc.js

@@ -0,0 +1,330 @@
+import { createTimeline as e, spring as t } from "animejs";
+// lib/motion.ts
+var n = {
+	micro: 100,
+	press: 130,
+	hover: 150,
+	short: 180,
+	base: 420,
+	panel: 420,
+	page: 350,
+	pop: 420
+}, r = {
+	mass: 1,
+	stiffness: 250,
+	damping: 35,
+	velocity: 20
+};
+function i(e) {
+	return t({
+		...r,
+		...e
+	});
+}
+var a = {
+	hover: 1.04,
+	press: .96,
+	dismiss: .9
+}, o = null;
+function s() {
+	return typeof window > "u" || !window.matchMedia ? null : (o ||= window.matchMedia("(prefers-reduced-motion: reduce)"), o);
+}
+function c() {
+	return s()?.matches ?? !1;
+}
+// lib/modalSource.ts
+var l = "button, [role='button'], a, label", u = null, d = !1;
+function f(e) {
+	let t = e.target;
+	if (!t || !t.closest) return;
+	let n = t.closest(l);
+	if (!n) return;
+	let r = n.getBoundingClientRect();
+	r.width < 2 || r.height < 2 || (u = {
+		source: {
+			el: n,
+			rect: {
+				left: r.left,
+				top: r.top,
+				width: r.width,
+				height: r.height
+			}
+		},
+		at: performance.now()
+	});
+}
+function p() {
+	d || typeof window > "u" || (d = !0, window.addEventListener("pointerdown", f, { capture: !0 }));
+}
+function m(e = 800) {
+	return !u || performance.now() - u.at > e ? null : u.source;
+}
+function h(e) {
+	return e.left + e.width > 0 && e.top + e.height > 0 && e.left < window.innerWidth && e.top < window.innerHeight;
+}
+// lib/heroTransition.ts
+var g = "rgba(0, 0, 0, 0)", _ = "rgba(0, 0, 0, 0.4)", v = "blur(0px)";
+function y(e) {
+	let t = getComputedStyle(e), n = t.backdropFilter || t.webkitBackdropFilter;
+	return n && n !== "none" ? n : v;
+}
+function b(t, r = {}) {
+	p();
+	let o = r.masked ?? !0, s = r.anchor, l = r.ghostOnly ?? !1, u = r.panelSelector ?? ".modal-panel", d = i(r.spring), f = i(r.springAccel), b = 0, x = null, S = null, C = null, w = null, T = null, E = null, D = null, O = null, k = null;
+	function A(e) {
+		E = e, D = e.style.opacity === "" ? null : e.style.opacity, e.style.opacity = "0";
+	}
+	function j() {
+		E && (D === null ? E.style.removeProperty("opacity") : E.style.opacity = D, E = null, D = null);
+	}
+	function M(e) {
+		return parseFloat(getComputedStyle(e).borderTopLeftRadius) || 0;
+	}
+	function N(e) {
+		return t(e) || (e instanceof HTMLElement ? (e.matches(u) ? e : e.querySelector(u)) ?? (o ? null : e) : null);
+	}
+	function P() {
+		S?.remove(), S = null, C?.remove(), C = null;
+	}
+	function F() {
+		if (w?.isConnected) {
+			let e = w.getBoundingClientRect();
+			if (e.width > 0 && e.height > 0) return {
+				left: e.left,
+				top: e.top,
+				width: e.width,
+				height: e.height
+			};
+		}
+		return T && T.width > 0 && h(T) ? T : null;
+	}
+	function I() {
+		let e = s?.();
+		if (!e?.isConnected) return null;
+		let t = e.getBoundingClientRect();
+		return t.width <= 0 || t.height <= 0 ? null : {
+			el: e,
+			rect: {
+				left: t.left,
+				top: t.top,
+				width: t.width,
+				height: t.height
+			}
+		};
+	}
+	function L(e, t, n, r) {
+		let i = t.cloneNode(!0);
+		i.style.removeProperty("transform"), i.style.removeProperty("transform-origin"), i.style.removeProperty("opacity"), i.style.removeProperty("right"), i.style.removeProperty("bottom"), i.style.position = "fixed", i.style.left = `${n.left}px`, i.style.top = `${n.top}px`, i.style.width = `${n.width}px`, i.style.height = `${n.height}px`, i.style.margin = "0", i.style.pointerEvents = "none", i.style.transformOrigin = "0 0";
+		let a = e instanceof HTMLElement && Number(getComputedStyle(e).zIndex) || 0;
+		return i.style.zIndex = String(a + r), document.body.appendChild(i), i;
+	}
+	function R(e, t) {
+		let n = e.querySelectorAll("input, textarea, select"), r = t.querySelectorAll("input, textarea, select");
+		n.length === r.length && n.forEach((e, t) => {
+			let n = r[t];
+			e instanceof HTMLInputElement && n instanceof HTMLInputElement && (n.checked = e.checked, n.indeterminate = e.indeterminate), n.value !== e.value && (n.value = e.value);
+		});
+	}
+	function z(e) {
+		e.style.removeProperty("transform"), e.style.removeProperty("transform-origin"), e.style.removeProperty("border-radius"), e.style.removeProperty("opacity");
+	}
+	function B(t, r) {
+		let i = t, s = N(t);
+		O = i, k = s, x?.cancel(), P(), j();
+		let u = o ? y(i) : v;
+		if (o && (i.style.removeProperty("background-color"), i.style.removeProperty("backdrop-filter"), i.style.removeProperty("opacity")), c() || !s) {
+			s?.style.removeProperty("opacity"), r();
+			return;
+		}
+		z(s);
+		let f = m() ?? I();
+		if (!f) {
+			s.style.opacity = "0", o && (i.style.backgroundColor = g, i.style.backdropFilter = v), x = e({ onComplete: () => {
+				z(s), o && (i.style.removeProperty("background-color"), i.style.removeProperty("backdrop-filter")), r();
+			} }), o && x.add(i, {
+				backgroundColor: [g, _],
+				backdropFilter: [v, u],
+				duration: n.base,
+				ease: d
+			}, 0), x.add(s, {
+				opacity: [0, 1],
+				scaleX: [a.dismiss, 1],
+				scaleY: [a.dismiss, 1],
+				duration: n.base,
+				ease: d
+			}, 0);
+			return;
+		}
+		w = f.el, T = f.rect;
+		let p = f.rect, h = s.getBoundingClientRect(), E = p.width / h.width, D = p.height / h.height, F = h.left - p.left, R = h.top - p.top, B = M(f.el), V = M(s);
+		if (l) {
+			s.style.opacity = "0";
+			let a = ++b;
+			requestAnimationFrame(() => {
+				if (a !== b || !s.isConnected) return;
+				let c = s.getBoundingClientRect();
+				if (c.width <= 0 || c.height <= 0) {
+					z(s), r();
+					return;
+				}
+				let l = p.width / c.width, f = p.height / c.height, m = c.left - p.left, h = c.top - p.top;
+				S = L(t, s, {
+					left: c.left,
+					top: c.top,
+					width: c.width,
+					height: c.height
+				}, 1), S.style.transform = `translate(${-m}px, ${-h}px) scale(${l}, ${f})`, S.style.borderRadius = `${B}px`, o && (i.style.backgroundColor = g, i.style.backdropFilter = v), x = e({ onComplete: () => {
+					P(), z(s), o && (i.style.removeProperty("background-color"), i.style.removeProperty("backdrop-filter")), r();
+				} }), o && x.add(i, {
+					backgroundColor: [g, _],
+					backdropFilter: [v, u],
+					duration: n.base,
+					ease: d
+				}, 0), x.add(S, {
+					translateX: [-m, 0],
+					translateY: [-h, 0],
+					scaleX: [l, 1],
+					scaleY: [f, 1],
+					borderRadius: [B, M(s)],
+					duration: n.pop,
+					ease: d
+				}, 0);
+			});
+		} else s.style.transformOrigin = "0 0", s.style.transform = `translate(${-F}px, ${-R}px) scale(${E}, ${D})`, s.style.borderRadius = `${B}px`, C = L(t, f.el, p, 2), A(f.el), o && (i.style.backgroundColor = g, i.style.backdropFilter = v), x = e({ onComplete: () => {
+			P(), z(s), o && (i.style.removeProperty("background-color"), i.style.removeProperty("backdrop-filter")), r();
+		} }), o && x.add(i, {
+			backgroundColor: [g, _],
+			backdropFilter: [v, u],
+			duration: n.base,
+			ease: d
+		}, 0), x.add(s, {
+			translateX: [-F, 0],
+			translateY: [-R, 0],
+			scaleX: [E, 1],
+			scaleY: [D, 1],
+			borderRadius: [B, V],
+			duration: n.pop,
+			ease: d
+		}, 0).add(C, {
+			translateX: [0, F],
+			translateY: [0, R],
+			scaleX: [1, 1 / E],
+			scaleY: [1, 1 / D],
+			duration: n.pop,
+			ease: d
+		}, 0).add(C, {
+			opacity: [
+				1,
+				0,
+				0
+			],
+			duration: n.pop,
+			ease: d
+		}, 0);
+	}
+	function V(t, r) {
+		let i = t, s = N(t);
+		O = i, k = s;
+		let u = () => {
+			j(), o && i && i.style.removeProperty("pointer-events"), r();
+		};
+		x?.cancel(), b++, P(), s && z(s), o && (i.style.removeProperty("background-color"), i.style.removeProperty("backdrop-filter"), i.style.removeProperty("opacity"), i.style.pointerEvents = "none");
+		let d = o ? y(i) : v;
+		if (c() || !s) {
+			u();
+			return;
+		}
+		let p = s.getBoundingClientRect(), m = F();
+		if (!m) {
+			x = e({ onComplete: () => {
+				z(s), u();
+			} }), x.add(s, {
+				scaleX: [1, a.dismiss],
+				scaleY: [1, a.dismiss],
+				opacity: [1, 0],
+				duration: n.base,
+				ease: f
+			}, 0), o && x.add(i, {
+				backgroundColor: [_, g],
+				backdropFilter: [d, v],
+				duration: n.base,
+				ease: f
+			}, 0);
+			return;
+		}
+		let h = m.width / p.width, T = m.height / p.height, E = m.left - p.left, D = m.top - p.top, A = M(s), I = w?.isConnected ? M(w) : A;
+		S = L(t, s, {
+			left: p.left,
+			top: p.top,
+			width: p.width,
+			height: p.height
+		}, 2), R(s, S), S.style.borderRadius = `${A}px`, l ? (s.style.opacity = "0", x = e({ onComplete: () => {
+			P(), z(s), u();
+		} }), o && x.add(i, {
+			opacity: 0,
+			duration: n.panel,
+			ease: f
+		}, 0), x.add(S, {
+			translateX: [0, E],
+			translateY: [0, D],
+			scaleX: [1, h],
+			scaleY: [1, T],
+			borderRadius: [A, I],
+			duration: n.panel,
+			ease: f
+		}, 0).add(S, {
+			opacity: [1, 0],
+			duration: n.panel,
+			ease: f
+		}, 0)) : (C = L(t, w ?? s, m, 1), C.style.transform = `translate(${-E}px, ${-D}px) scale(${1 / h}, ${1 / T})`, C.style.opacity = "0", s.style.opacity = "0", x = e({ onComplete: () => {
+			P(), z(s), u();
+		} }), o && x.add(i, {
+			backgroundColor: [_, g],
+			backdropFilter: [d, v],
+			duration: n.panel,
+			ease: f
+		}, 0), x.add(S, {
+			translateX: [0, E],
+			translateY: [0, D],
+			scaleX: [1, h],
+			scaleY: [1, T],
+			borderRadius: [A, I],
+			duration: n.panel,
+			ease: f
+		}, 0).add(S, {
+			opacity: [1, 0],
+			duration: n.panel,
+			ease: f
+		}, 0).add(C, {
+			translateX: [-E, 0],
+			translateY: [-D, 0],
+			scaleX: [1 / h, 1],
+			scaleY: [1 / T, 1],
+			duration: n.panel,
+			ease: f
+		}, 0).add(C, {
+			opacity: [
+				0,
+				.8,
+				1
+			],
+			duration: n.panel,
+			ease: f
+		}, 0));
+	}
+	function H() {
+		x?.cancel(), x = null, b++, P(), j(), k && (z(k), k.style.removeProperty("opacity")), O && (O.style.removeProperty("background-color"), O.style.removeProperty("backdrop-filter"), O.style.removeProperty("opacity"), O.style.removeProperty("pointer-events"));
+	}
+	return {
+		onEnter: B,
+		onLeave: V,
+		cancel: H
+	};
+}
+function x(e = ".modal-panel", t = {}) {
+	return b((t) => t instanceof HTMLElement ? t.matches(e) ? t : t.querySelector(e) : null, {
+		panelSelector: e,
+		...t
+	});
+}
+export { r as i, b as n, p as r, x as t };

package/dist/heroTransition.d.ts

@@ -0,0 +1,44 @@
+import { type HeroSpringParams } from "./motion";
+export interface HeroHandlers {
+    onEnter: (el: Element, done: () => void) => void;
+    onLeave: (el: Element, done: () => void) => void;
+    /** 取消当前转场：清理时间线、克隆层与内联样式，并立即还原真实元素 */
+    cancel: () => void;
+}
+export interface HeroOptions {
+    /**
+     * 是否存在独立遮罩（根 el = 遮罩，内部 getPanel() = 面板）。
+     * false：根 el 就是面板（无背景遮罩的锚定浮层）。
+     */
+    masked?: boolean;
+    /**
+     * 无指针来源时的锚点（快捷键打开场景）：用它作为展开起点与收回终点。
+     * 有指针来源（点击打开）时优先用点击的那个元素。
+     */
+    anchor?: () => HTMLElement | null;
+    /**
+     * 只操作 ghost 模式（适合 AppSelect 下拉 / CSV 菜单这类 JS 定位的小浮层）：
+     *   · 打开与关闭都只动克隆体，真实浮层飞行期间 opacity 0 让位、结束同帧交回；
+     *   · 不生成「图标层」，也不隐藏触发元素本体（控件本体保持可见更自然）；
+     *   · 不写真实浮层的内联 transform，避免干扰它自己的定位计算。
+     */
+    ghostOnly?: boolean;
+    /**
+     * 面板选择器，默认 `.modal-panel`，用于 resolvePanel 兜底
+     * （getPanel 取不到真实元素时，按此选择器在根元素内查找面板）。
+     */
+    panelSelector?: string;
+    /**
+     * 打开曲线（anime.js spring）参数：mass / stiffness / damping / velocity。
+     * 只需传入想覆盖的字段，其余回落到默认值。
+     */
+    spring?: HeroSpringParams;
+    /** 关闭曲线（anime.js spring）参数；未提供的字段回落到默认值。 */
+    springAccel?: HeroSpringParams;
+}
+export declare function createHeroTransition(getPanel: (root: Element) => HTMLElement | null, options?: HeroOptions): HeroHandlers;
+/**
+ * 便捷工厂：外层 <Transition :css="false"> 包住整个弹窗组件时使用。
+ * 面板通过根元素内的选择器定位（弹窗面板通常带 .modal-panel）。
+ */
+export declare function createDialogHero(selector?: string, options?: HeroOptions): HeroHandlers;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createHeroTransition, createDialogHero } from "./heroTransition";
+export type { HeroHandlers, HeroOptions } from "./heroTransition";
+export { installModalSourceTracking } from "./modalSource";
+export type { SourceRect, ModalSource } from "./modalSource";
+export { SPRING_PARAMS } from "./motion";
+export type { HeroSpringParams } from "./motion";

package/dist/index.js

@@ -0,0 +1 @@
+export { i as SPRING_PARAMS, t as createDialogHero, n as createHeroTransition, r as installModalSourceTracking } from "./heroTransition-CND4UQtc.js";

package/dist/modalSource.d.ts

@@ -0,0 +1,19 @@
+export interface SourceRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface ModalSource {
+    el: HTMLElement;
+    rect: SourceRect;
+}
+/** 在应用启动时调用一次 */
+export declare function installModalSourceTracking(): void;
+/**
+ * 取最近的触发源（含元素引用）；超过 maxAge（ms）视为无效。
+ * 不清除记录：弹窗关闭时仍需以同一元素作为收回目标。
+ */
+export declare function consumeSource(maxAge?: number): ModalSource | null;
+/** 矩形当前是否仍在窗口可视区域内（防止收回时飞向屏外） */
+export declare function isRectOnScreen(r: SourceRect): boolean;

package/dist/motion.d.ts

@@ -0,0 +1,47 @@
+export declare const DURATION: {
+    /** 极短：描边、图标状态切换 */
+    readonly micro: 100;
+    /** 按压/小型状态 */
+    readonly press: 130;
+    /** 悬停过渡 */
+    readonly hover: 150;
+    /** 短促入场（遮罩、下拉） */
+    readonly short: 180;
+    /** 标准入场 */
+    readonly base: 420;
+    /** 面板 / 选中指示 */
+    readonly panel: 420;
+    /** 整页转场 */
+    readonly page: 350;
+    /** 点击放大弹出的感知时长（与 SPRING.pop 对齐） */
+    readonly pop: 420;
+};
+/**
+ * 默认弹簧参数：苹果进场/离场曲线共用同一组物理参数。
+ * 业务方可通过 HeroOptions.spring / springAccel 覆盖其中任意字段，
+ * 未提供的字段回落到这里。
+ */
+export declare const SPRING_PARAMS: {
+    readonly mass: 1;
+    readonly stiffness: 250;
+    readonly damping: 35;
+    readonly velocity: 20;
+};
+export interface HeroSpringParams {
+    mass?: number;
+    stiffness?: number;
+    damping?: number;
+    velocity?: number;
+}
+/** 按默认值补齐后创建 anime.js spring 缓动 */
+export declare function springEase(overrides?: HeroSpringParams): import("animejs").Spring;
+export declare const SCALE: {
+    /** 悬停 */
+    readonly hover: 1.04;
+    /** 按下（需要收缩感时） */
+    readonly press: 0.96;
+    /** 无锚点弹层的退场收缩（缩到中心消失） */
+    readonly dismiss: 0.9;
+};
+/** 系统是否要求减少动态效果 */
+export declare function prefersReducedMotion(): boolean;

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { HeroSpringParams } from "./motion";
+export interface HeroTransitionProps {
+    open: boolean;
+    masked?: boolean;
+    ghostOnly?: boolean;
+    panelSelector?: string;
+    anchor?: () => HTMLElement | null;
+    /** 打开曲线弹簧参数（未提供的字段用默认值） */
+    spring?: HeroSpringParams;
+    /** 关闭曲线弹簧参数（未提供的字段用默认值） */
+    springAccel?: HeroSpringParams;
+    onEntered?: () => void;
+    onExited?: () => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/**
+ * hero 转场的 React 适配：负责挂载/卸载时序，动画本身交给核心库。
+ * 离场动画期间保持挂载，done 之后才卸载。
+ */
+export declare function HeroTransition({ open, masked, ghostOnly, panelSelector, anchor, spring, springAccel, onEntered, onExited, className, style, children, }: HeroTransitionProps): JSX.Element | null;

package/dist/react.js

@@ -0,0 +1,64 @@
+import { n as e } from "./heroTransition-CND4UQtc.js";
+import { useEffect as t, useMemo as n, useRef as r, useState as i } from "react";
+import { jsx as a } from "react/jsx-runtime";
+// lib/react.tsx
+function o({ open: o, masked: s = !0, ghostOnly: c = !1, panelSelector: l = ".modal-panel", anchor: u, spring: d, springAccel: f, onEntered: p, onExited: m, className: h, style: g, children: _ }) {
+	let [v, y] = i(o), b = r(null), x = r("closed"), S = r(0), C = r(u), w = r(p), T = r(m);
+	t(() => {
+		C.current = u, w.current = p, T.current = m;
+	});
+	let E = JSON.stringify(d ?? null), D = JSON.stringify(f ?? null), O = n(() => e((e) => e instanceof HTMLElement ? e.querySelector(l) : null, {
+		masked: s,
+		ghostOnly: c,
+		panelSelector: l,
+		anchor: () => C.current?.() ?? null,
+		spring: d,
+		springAccel: f
+	}), [
+		s,
+		c,
+		l,
+		E,
+		D
+	]);
+	return t(() => {
+		if (o) {
+			if (!v) {
+				y(!0);
+				return;
+			}
+			let e = b.current;
+			if (!e) return;
+			let t = x.current;
+			if (t === "entering" || t === "open") return;
+			let n = ++S.current;
+			x.current = "entering", O.onEnter(e, () => {
+				n === S.current && (x.current = "open", w.current?.());
+			});
+			return;
+		}
+		if (!v) return;
+		let e = b.current;
+		if (!e) {
+			y(!1);
+			return;
+		}
+		if (x.current === "leaving") return;
+		let t = ++S.current;
+		x.current = "leaving", O.onLeave(e, () => {
+			t === S.current && (x.current = "closed", y(!1), T.current?.());
+		});
+	}, [
+		o,
+		v,
+		O
+	]), t(() => () => {
+		S.current++, x.current = "closed", O.cancel();
+	}, [O]), v ? /* @__PURE__ */ a("div", {
+		ref: b,
+		className: h,
+		style: g,
+		children: _
+	}) : null;
+}
+export { o as HeroTransition };

package/dist/vue.d.ts

@@ -0,0 +1,84 @@
+import { type PropType } from "vue";
+import { type HeroSpringParams } from "./index";
+export interface HeroTransitionProps {
+    open: boolean;
+    masked?: boolean;
+    ghostOnly?: boolean;
+    panelSelector?: string;
+    anchor?: () => HTMLElement | null;
+    /** 打开曲线弹簧参数（未提供的字段用默认值） */
+    spring?: HeroSpringParams;
+    /** 关闭曲线弹簧参数（未提供的字段用默认值） */
+    springAccel?: HeroSpringParams;
+}
+export declare const HeroTransition: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    open: {
+        type: BooleanConstructor;
+        required: true;
+    };
+    masked: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    ghostOnly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    panelSelector: {
+        type: StringConstructor;
+        default: string;
+    };
+    anchor: {
+        type: PropType<() => HTMLElement | null>;
+        default: undefined;
+    };
+    spring: {
+        type: PropType<HeroSpringParams>;
+        default: undefined;
+    };
+    springAccel: {
+        type: PropType<HeroSpringParams>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("entered" | "exited")[], "entered" | "exited", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    open: {
+        type: BooleanConstructor;
+        required: true;
+    };
+    masked: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    ghostOnly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    panelSelector: {
+        type: StringConstructor;
+        default: string;
+    };
+    anchor: {
+        type: PropType<() => HTMLElement | null>;
+        default: undefined;
+    };
+    spring: {
+        type: PropType<HeroSpringParams>;
+        default: undefined;
+    };
+    springAccel: {
+        type: PropType<HeroSpringParams>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onEntered?: ((...args: any[]) => any) | undefined;
+    onExited?: ((...args: any[]) => any) | undefined;
+}>, {
+    panelSelector: string;
+    masked: boolean;
+    ghostOnly: boolean;
+    anchor: () => HTMLElement | null;
+    spring: HeroSpringParams;
+    springAccel: HeroSpringParams;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.js

@@ -0,0 +1,74 @@
+import { n as e } from "./heroTransition-CND4UQtc.js";
+import "./index.js";
+import { defineComponent as t, h as n, nextTick as r, onBeforeUnmount as i, onMounted as a, ref as o, watch as s } from "vue";
+// lib/vue.ts
+var c = t({
+	name: "HeroTransition",
+	inheritAttrs: !1,
+	props: {
+		open: {
+			type: Boolean,
+			required: !0
+		},
+		masked: {
+			type: Boolean,
+			default: !0
+		},
+		ghostOnly: {
+			type: Boolean,
+			default: !1
+		},
+		panelSelector: {
+			type: String,
+			default: ".modal-panel"
+		},
+		anchor: {
+			type: Function,
+			default: void 0
+		},
+		spring: {
+			type: Object,
+			default: void 0
+		},
+		springAccel: {
+			type: Object,
+			default: void 0
+		}
+	},
+	emits: ["entered", "exited"],
+	setup(t, { slots: c, attrs: l, emit: u }) {
+		let d = o(t.open), f = o(null), p = 0, m = e((e) => e instanceof HTMLElement ? e.querySelector(t.panelSelector) : null, {
+			masked: t.masked,
+			ghostOnly: t.ghostOnly,
+			panelSelector: t.panelSelector,
+			anchor: () => t.anchor?.() ?? null,
+			spring: t.spring,
+			springAccel: t.springAccel
+		});
+		async function h() {
+			let e = ++p;
+			if (d.value || (d.value = !0, await r()), e !== p) return;
+			let t = f.value;
+			t && m.onEnter(t, () => {
+				e === p && u("entered");
+			});
+		}
+		function g() {
+			let e = ++p, t = f.value;
+			t ? m.onLeave(t, () => {
+				e === p && (d.value = !1, u("exited"));
+			}) : (d.value = !1, u("exited"));
+		}
+		return s(() => t.open, (e) => {
+			e ? h() : g();
+		}), a(() => {
+			t.open && h();
+		}), i(() => {
+			p++, m.cancel();
+		}), () => d.value ? n("div", {
+			...l,
+			ref: f
+		}, c.default?.()) : null;
+	}
+});
+export { c as HeroTransition };

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "hero-animate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "iOS 风格「图标 ⇄ 窗口」形变转场，框架无关核心 + Vue/React 组件",
+  "author": "SinJayXie",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SinJayXie/hero-animate.git"
+  },
+  "homepage": "https://sinjayxie.github.io/hero-animate/",
+  "bugs": {
+    "url": "https://github.com/SinJayXie/hero-animate/issues"
+  },
+  "keywords": [
+    "hero",
+    "hero-transition",
+    "shared-element",
+    "transition",
+    "animation",
+    "spring",
+    "animejs",
+    "vue",
+    "react",
+    "modal",
+    "dialog",
+    "popover"
+  ],
+  "sideEffects": [
+    "./src/**",
+    "*.css"
+  ],
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@12.15.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "docs:build": "vite build --config vite.docs.config.ts",
+    "docs:preview": "vite preview --config vite.docs.config.ts --port 4173",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "animejs": "^4.5.0",
+    "react": ">=18",
+    "vue": ">=3.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/prismjs": "^1.26.6",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "animejs": "^4.5.0",
+    "prismjs": "^1.30.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.2.2",
+    "vue": "^3.5.44"
+  }
+}