feat(helper): add transition helpers with components and styles

docs/tools/helper/client.md

@@ -163,3 +163,73 @@
 ```
 
 :::
+
+## Component
+
+### FadeInExpandTransition
+
+Provides fade-in transition effects when block-level elements expand, supporting both `height` or `width` properties.
+
+**Props:**
+
+```ts
+interface FadeInExpandTransitionProps {
+  /**
+   * Whether to group transitions
+   */
+  group?: boolean
+  /**
+   * Transition mode
+   */
+  mode?: 'default' | 'in-out' | 'out-in'
+
+  /**
+   * Whether to switch to the transition of `width`
+   *
+   * @default false
+   */
+  width?: boolean
+
+  appear?: boolean
+  onLeave?: () => void
+  onAfterEnter?: () => void
+  onAfterLeave?: () => void
+}
+```
+
+**Import Styles:**
+
+Transition animations require importing the following CSS files as needed:
+
+- `@vuepress/helper/transition/fade-in-height-expand.css` - `height` transition animation
+
+- `@vuepress/helper/transition/fade-in-width-expand.css` - `width` transition animation
+
+::: tip Only one CSS file needs to be imported
+
+:::
+
+**Usage:**
+
+```vue
+<script setup lang="ts">
+import { FadeInExpandTransition } from '@vuepress/helper/client'
+
+import '@vuepress/helper/transition/fade-in-height-expand.css'
+// import '@vuepress/helper/transition/fade-in-width-expand.css'
+
+const expand = ref(false)
+</script>
+
+<template>
+  <button @click="expand = !expand">
+    {{ expand ? 'Collapse' : 'Expand' }}
+  </button>
+
+  <FadeInExpandTransition>
+    <div v-show="expand">
+      <p>Content</p>
+    </div>
+  </FadeInExpandTransition>
+</template>
+```

docs/tools/helper/style.md

@@ -9,3 +9,64 @@
 ## Normalize
 
 `@vuepress/helper/normalize.css` is a CSS file that normalizes the default styles of the browser. It is recommended to import it in community themes.
+
+## Transitions
+
+`@vuepress/helper/transition/*.css` is a collection of CSS files that provide transitions for elements. It is recommended to import for use as needed in community themes.
+
+- `fade-in.css`
+- `fade-in-up.css`
+- `fade-in-down.css`
+- `fade-in-left.css`
+- `fade-in-right.css`
+- `fade-in-scale-up.css`
+- `slide-in-up.css`
+- `slide-in-down.css`
+- `slide-in-left.css`
+- `slide-in-right.css`
+
+**Usage:**
+
+```vue
+<script setup>
+import '@vuepress/helper/transition/fade-in.css'
+</script>
+
+<template>
+  <Transition name="fade-in">
+    <div>...</div>
+  </Transition>
+</template>
+```
+
+**CSS Variables:**
+
+```css
+:root {
+  /* general transitions variables */
+
+  --transition-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --transition-ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --transition-duration: 0.3s;
+  --transition-enter-duration: var(--transition-duration);
+  --transition-leave-duration: 0.2s;
+  --transition-delay: 0.1s;
+
+  /* specific transitions variables */
+
+  --transition-fade-in-up-offset: 10px;
+  --transition-fade-in-down-offset: -10px;
+  --transition-fade-in-left-offset: 10px;
+  --transition-fade-in-right-offset: -10px;
+
+  --transition-fade-in-scale-up-scale: 0.9;
+  --transition-fade-in-scale-up-duration: 0.2s;
+  --transition-fade-in-scale-up-origin: inherit;
+
+  --transition-slide-in-up-offset: 100%;
+  --transition-slide-in-down-offset: -100%;
+  --transition-slide-in-left-offset: 100%;
+  --transition-slide-in-right-offset: -100%;
+}
+```

docs/zh/tools/helper/client.md

@@ -163,3 +163,71 @@
 ```
 
 :::
+
+## 组件{#component}
+
+### FadeInExpandTransition
+
+为块级元素的展开提供淡入淡出过渡效果，支持 `height` 或 `width` 属性。
+
+**Props:**
+
+```ts
+interface FadeInExpandTransitionProps {
+  /**
+   * 是否分组过渡
+   */
+  group?: boolean
+  /**
+   * 过渡模式
+   */
+  mode?: 'default' | 'in-out' | 'out-in'
+
+  /**
+   * 是否切换为 `width` 的过渡
+   *
+   * @default false
+   */
+  width?: boolean
+
+  appear?: boolean
+  onLeave?: () => void
+  onAfterEnter?: () => void
+  onAfterLeave?: () => void
+}
+```
+
+**导入样式：**
+
+过渡动画需要按需引入以下 CSS 文件：
+
+- `@vuepress/helper/transition/fade-in-height-expand.css` - `height` 过渡动画
+- `@vuepress/helper/transition/fade-in-width-expand.css` - `width` 过渡动画
+
+::: tip 只需要引入其中一个 CSS 文件
+:::
+
+**Usage:**
+
+```vue
+<script setup lang="ts">
+import { FadeInExpandTransition } from '@vuepress/helper/client'
+
+import '@vuepress/helper/transition/fade-in-height-expand.css'
+// import '@vuepress/helper/transition/fade-in-width-expand.css'
+
+const expand = ref(false)
+</script>
+
+<template>
+  <button @click="expand = !expand">
+    {{ expand ? 'Collapse' : 'Expand' }}
+  </button>
+
+  <FadeInExpandTransition>
+    <div v-show="expand">
+      <p>Content</p>
+    </div>
+  </FadeInExpandTransition>
+</template>
+```

docs/zh/tools/helper/style.md

@@ -9,3 +9,64 @@
 ## 规范化
 
 `@vuepress/helper/normalize.css` 是一个 CSS 文件，用于规范化浏览器的默认样式。推荐在社区主题中引入它。
+
+## 过渡{#transitions}
+
+`@vuepress/helper/transition/*.css` 是一组提供元素过渡效果的CSS文件集合，推荐在社区主题中按需导入使用。
+
+- `fade-in.css`
+- `fade-in-up.css`
+- `fade-in-down.css`
+- `fade-in-left.css`
+- `fade-in-right.css`
+- `fade-in-scale-up.css`
+- `slide-in-up.css`
+- `slide-in-down.css`
+- `slide-in-left.css`
+- `slide-in-right.css`
+
+**使用：**
+
+```vue
+<script setup>
+import '@vuepress/helper/transition/fade-in.css'
+</script>
+
+<template>
+  <Transition name="fade-in">
+    <div>...</div>
+  </Transition>
+</template>
+```
+
+**CSS 变量：**
+
+```css
+:root {
+  /* general transitions variables */
+
+  --transition-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --transition-ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --transition-duration: 0.3s;
+  --transition-enter-duration: var(--transition-duration);
+  --transition-leave-duration: 0.2s;
+  --transition-delay: 0.1s;
+
+  /* specific transitions variables */
+
+  --transition-fade-in-up-offset: 10px;
+  --transition-fade-in-down-offset: -10px;
+  --transition-fade-in-left-offset: 10px;
+  --transition-fade-in-right-offset: -10px;
+
+  --transition-fade-in-scale-up-scale: 0.9;
+  --transition-fade-in-scale-up-duration: 0.2s;
+  --transition-fade-in-scale-up-origin: inherit;
+
+  --transition-slide-in-up-offset: 100%;
+  --transition-slide-in-down-offset: -100%;
+  --transition-slide-in-left-offset: 100%;
+  --transition-slide-in-right-offset: -100%;
+}
+```

tools/helper/package.json

@@ -33,6 +33,7 @@
     "./colors.css": "./lib/client/styles/colors.css",
     "./normalize.css": "./lib/client/styles/normalize.css",
     "./sr-only.css": "./lib/client/styles/sr-only.css",
+    "./transition/*.css": "./lib/client/styles/transition/*.css",
     "./scss/*.scss": {
       "sass": "./scss/*.scss"
     },

tools/helper/src/client/components/Transitions/FadeInExpandTransition.ts

@@ -0,0 +1,89 @@
+import type { Component, PropType } from 'vue'
+import { Transition, TransitionGroup, defineComponent, h } from 'vue'
+
+export const FadeInExpandTransition = defineComponent({
+  name: 'FadeInExpandTransition',
+  props: {
+    /* Whether to group transitions */
+    group: Boolean,
+    appear: Boolean,
+    /* Whether to switch to the transition of `width` */
+    width: Boolean,
+    mode: String as PropType<'default' | 'in-out' | 'out-in'>,
+    onLeave: Function,
+    onAfterLeave: Function,
+    onAfterEnter: Function,
+  },
+  setup(props, { slots }) {
+    const handleBeforeLeave = (el: HTMLElement): void => {
+      if (props.width) {
+        el.style.maxWidth = `${el.offsetWidth}px`
+      } else {
+        el.style.maxHeight = `${el.offsetHeight}px`
+      }
+      void el.offsetWidth
+    }
+
+    const handleLeave = (el: HTMLElement): void => {
+      if (props.width) {
+        el.style.maxWidth = '0'
+      } else {
+        el.style.maxHeight = '0'
+      }
+      void el.offsetWidth
+      props.onLeave?.()
+    }
+
+    const handleAfterLeave = (el: HTMLElement): void => {
+      if (props.width) {
+        el.style.maxWidth = ''
+      } else {
+        el.style.maxHeight = ''
+      }
+      props.onAfterLeave?.()
+    }
+
+    const handleEnter = (el: HTMLElement): void => {
+      el.style.transition = 'none'
+      if (props.width) {
+        const memorizedWidth = el.offsetWidth
+        el.style.maxWidth = '0'
+        void el.offsetWidth
+        el.style.transition = ''
+        el.style.maxWidth = `${memorizedWidth}px`
+      } else {
+        const memorizedHeight = el.offsetHeight
+        el.style.maxHeight = '0'
+        void el.offsetWidth
+        el.style.transition = ''
+        el.style.maxHeight = `${memorizedHeight}px`
+      }
+      void el.offsetWidth
+    }
+
+    const handleAfterEnter = (el: HTMLElement): void => {
+      if (props.width) {
+        el.style.maxWidth = ''
+      } else {
+        el.style.maxHeight = ''
+      }
+      props.onAfterEnter?.()
+    }
+
+    return () =>
+      h(
+        (props.group ? TransitionGroup : Transition) as Component,
+        {
+          name: props.width ? 'fade-in-width-expand' : 'fade-in-height-expand',
+          appear: props.appear,
+          mode: props.mode,
+          onEnter: handleEnter,
+          onAfterEnter: handleAfterEnter,
+          onBeforeLeave: handleBeforeLeave,
+          onLeave: handleLeave,
+          onAfterLeave: handleAfterLeave,
+        },
+        slots,
+      )
+  },
+})

tools/helper/src/client/components/Transitions/index.ts

@@ -0,0 +1 @@
+export * from './FadeInExpandTransition.js'

tools/helper/src/client/components/index.ts

@@ -1 +1,2 @@
 export * from './LoadingIcon.js'
+export * from './Transitions/index.js'