/**
 * BottomUtils 子项动画 Hook
 *
 * 功能说明：
 * 1. 为子项列表提供从下向上进入、从上向下离开的动画效果
 * 2. 子项依次出现的波浪式动画（stagger 效果）
 * 3. 离开时反向依次消失
 *
 * 动画效果：
 * - 进入动画：每个子项从下方 50px 处滑入，同时淡入（y: 50 → 0, opacity: 0 → 1）
 * - 离开动画：每个子项向下方 50px 处滑出，同时淡出（y: 0 → 50, opacity: 1 → 0）
 *
 * Stagger 效果：
 * - 进入时（visible）：子项从第一个到最后一个依次出现，每个间隔 0.05 秒
 * - 离开时（hidden）：子项从最后一个到第一个依次消失，每个间隔 0.03 秒（更快）
 *
 * 使用方法：
 * 1. 在父组件中使用 AnimatePresence 包裹子项容器
 * 2. 在子项容器上设置 initial="hidden"、animate="visible"、exit="hidden"
 * 3. 在子项容器上使用 containerVariants
 * 4. 在每个子项上使用 itemVariants
 *
 * @returns {object} 返回包含以下属性的对象：
 *   - containerVariants: 容器的动画变体（用于 motion.div）
 *   - itemVariants: 子项的动画变体（用于每个子项）
 */
export function useBranchOfficeUtilsAnimation() {
  // ==================== 容器动画变体 ====================
  // 作用：控制整个子项容器的动画和子项的 stagger 效果
  const containerVariants = {
    // 隐藏状态
    // - 用途 1：作为初始状态（initial="hidden"）
    // - 用途 2：作为离开状态（exit="hidden"）
    // - 当同时定义 hidden.transition 和 visible.transition 时
    //   Framer Motion 会根据当前是进入还是离开自动选择对应的 transition
    hidden: {
      opacity: 0, // 容器整体透明
      y: 200, // 容器从下方 200px 处开始/离开到下方 200px
      // 离开时的 transition 配置（当 exit="hidden" 时使用）
      // 进入时会使用 visible.transition，所以这里只配置离开相关的参数
      transition: {
        duration: 0.2, // 容器离开动画时长：0.2 秒（比进入快）
        ease: "easeIn", // 容器离开缓动函数
        // 子项依次离开的反向波浪效果
        staggerChildren: 0.03, // 离开时间隔更短（0.03 秒），显得更轻快
        staggerDirection: -1, // -1 = 反向（从最后一个到第一个）
      },
    },

    // 可见状态（进入动画）
    // - 当组件挂载后立即使用（animate="visible"）
    visible: {
      opacity: 1, // 容器整体不透明
      y: 0, // 容器移动到正常位置
      transition: {
        duration: 0.3, // 容器动画时长：0.3 秒
        ease: "easeOut", // 容器缓动函数
        // 子项依次出现的波浪效果（进入时使用）
        staggerChildren: 0.05, // 每个子项间隔 0.05 秒依次出现
        staggerDirection: 1, // 1 = 正向（从第一个到最后一个）
      },
    },
  };

  // ==================== 子项动画变体 ====================
  // 作用：控制单个子项的进入和离开动画
  const itemVariants = {
    // 隐藏状态
    // - 作为初始状态（initial="hidden"）
    // - 作为离开的目标状态（exit="hidden" 时子项会动画到此状态）
    hidden: {
      y: 50, // Y 轴位置：从下方 50px 处开始/离开到下方 50px
      opacity: 0, // 透明度：完全透明
    },

    // 可见状态
    // - 作为进入的目标状态（animate="visible" 时子项会动画到此状态）
    visible: {
      y: 0, // Y 轴位置：移动到正常位置
      opacity: 1, // 透明度：变为完全不透明
      transition: {
        duration: 0.3, // 动画时长：0.3 秒
        ease: "easeOut", // 缓动函数：快速开始，缓慢结束
      },
    },
  };

  // ==================== 返回值 ====================
  // 返回容器和子项的动画变体
  return {
    containerVariants, // 容器的动画变体，用于 motion.div 的 variants 属性
    itemVariants, // 子项的动画变体，用于每个子项 motion.div 的 variants 属性
  };
}
