# Reveal Bottom Sheet

`ShowtimeRevealBottomSheet` 是一个基于 `ShowtimeBottomSheet` 的高层包装组件，专门用来处理“头部 reveal 层”这类交互。

它保留底层 sheet 的拖拽、吸附和内容区边界联动能力，同时把以下展示逻辑收进组件内部：

- reveal 层显隐区间判断
- reveal 进度计算
- 一次拖拽可以从 reveal 区间外开始；面板跨过区间下边界后，真实 `panelY` 会连续驱动 reveal progress，抵达上边界时完整展开
- reveal progress 大于 0 时会自动隐藏默认拖拽把手；progress 回到 0 时恢复调用方传入的 `handleVisible` 设置
- 拖拽时关闭过渡、松手后回到离散 snap
- placeholder 占位高度和 reveal 进度同步
- reveal 区间内的相邻 snap 切换共用同一条进度状态线，避免头部和面板出现割裂感

## 三个 Slot

| Slot | 说明 |
| --- | --- |
| `reveal` | 动态头部层，可放图片、渐变、插画、视频容器或任意元素 |
| `header` | 前景头部内容，例如标题、说明、操作区 |
| `default` | 内容区主体 |

## 基础用法

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ShowtimeRevealBottomSheet,
  type ShowtimeSheetSnap
} from 'showtime-components'

const snap = ref<ShowtimeSheetSnap>('quick-full')
</script>

<template>
  <ShowtimeRevealBottomSheet
    v-model:snap="snap"
    :snap-points="[
      { key: 'peek', position: 90 },
      { key: 'half', position: 55 },
      { key: 'quick-full', position: 30 },
      { key: 'full', position: 0 }
    ]"
    :reveal-height="220"
    :reveal-snap-keys="['quick-full', 'full']"
  >
    <template #reveal>
      <div class="hero-cover" />
    </template>

    <template #header>
      <div class="hero-header">
        <strong>互动留言</strong>
      </div>
    </template>

    <div>这里是内容区域</div>
  </ShowtimeRevealBottomSheet>
</template>
```

## 常用 Props

| 名称 | 说明 | 默认值 |
| --- | --- | --- |
| `snap` | 当前吸附点 | 继承底层 sheet 默认行为 |
| `snapPoints` | 透传到底层 bottom sheet 的吸附点配置 | 无 |
| `revealHeight` | reveal 区高度，单位 px | `200` |
| `revealSnapKeys` | reveal 生效的 snap key 列表 | `['half', 'full']` |
| `revealClass` | reveal 层附加类名 | `''` |
| `headerClass` | 前景头部附加类名 | `''` |
| `bodyClass` | 内容区附加类名 | `''` |

其余拖拽、圆角、把手、内容区边界联动等能力，继续沿用底层 `ShowtimeBottomSheet` 的核心 props。

## 默认交互基线

`ShowtimeRevealBottomSheet` 对底层交互默认做了一组更适合 reveal 场景的取值：

- `headerDragOnly=false`
- `contentEdgeSnap=true`

这意味着内容区边界继续拖动时，sheet 可以自然接管后续位移。组件会在 reveal 开始展示后自动隐藏默认把手，并在完全收起后恢复 `handleVisible`；业务通常只需要按最终 snap 调整 `panelRadius` 或内容滚动策略，不需要再维护一套 reveal 进度或按 snap 手动切换手势开关。

## 过渡说明

- 拖拽中会关闭 reveal 层、placeholder 和面板圆角的独立过渡，保证手势跟手
- 即使拖拽从 `revealSnapKeys` 区间外开始，进入区间后 reveal 层和 placeholder 也会立即接管真实 `panelY` 并连续变化
- 当 `revealSnapKeys` 覆盖多个相邻 snap（例如 `quick-full` 和 `full`）时，reveal 区间内的切换会继续跟随底层 sheet 的实际进度，而不是让头部自己额外跑一段 CSS 补间
- 默认把手与 reveal progress 共用显隐时机：progress 大于 0 时隐藏，回到 0 时恢复调用方的 `handleVisible`
- 离开 reveal 区间后，reveal 层和 placeholder 会恢复常规过渡，用于进入或退出 reveal 态
- reveal 层和 placeholder 的过渡通过 `--showtime-reveal-layer-transition` 与 `--showtime-reveal-placeholder-transition` 变量解析，便于按业务调整；系统开启 `prefers-reduced-motion: reduce` 时会自动设为 `none`

例如，可以只在某个实例上缩短离开 reveal 区间的过渡：

```css
.compact-reveal :deep(.showtime-reveal-bottom-sheet__reveal) {
  --showtime-reveal-layer-transition: transform 220ms var(--showtime-ease-emphasized), opacity 140ms var(--showtime-ease-standard);
}

.compact-reveal :deep(.showtime-reveal-bottom-sheet__placeholder) {
  --showtime-reveal-placeholder-transition: height 220ms var(--showtime-ease-emphasized);
}
```

## 使用建议

- 如果你只需要通用底部弹层，继续使用 `ShowtimeBottomSheet`
- 如果你有“头部封面 / 头图 / 渐变层 / 插画层会随拖拽动态 reveal”的需求，用 `ShowtimeRevealBottomSheet`
- `reveal` slot 不要只按图片思维理解，它本质上是一个动态头部层容器

## 样式定制

Reveal 层会继承 Bottom Sheet 的共享颜色和动效 token，详情见 [样式定制](./style-customization.md)。`panelBackground` 与 `panelRadius` 仍可按实例设置。