@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/Overlay/README.md

@@ -0,0 +1,84 @@
+# Overlay
+
+覆盖层组件，基于 `@rneui/themed` 的 Overlay 封装，用于显示底部弹出的模态内容面板。预设从底部弹出、占屏幕 80% 高度的样式，适合底部 Sheet 和弹出菜单场景。
+
+## 功能特性
+
+- ✅ 继承 @rneui/themed OverlayProps 的全部能力
+- ✅ 预设底部弹出样式（absolute + bottom: 0）
+- ✅ 半透明遮罩背景（backdropStyle）
+- ✅ 支持点击遮罩关闭（onBackdropPress）
+- ✅ 自定义 overlayStyle 和 backdropStyle 覆盖默认样式
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { Overlay } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | - | 是否显示覆盖层（必填） |
+| onBackdropPress | `() => void` | - | 点击遮罩回调 |
+| overlayStyle | `StyleProp<ViewStyle>` | 底部弹出，宽100%，高80% | 覆盖层样式 |
+| backdropStyle | `StyleProp<ViewStyle>` | 半透明灰色 | 遮罩样式 |
+| children | `React.ReactNode` | - | 覆盖层内容 |
+
+> 继承 `@rneui/themed` OverlayProps 的所有属性
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+
+<Button onPress={() => setIsVisible(true)}>Open Overlay</Button>
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+>
+  <View>
+    <Text>Overlay Content</Text>
+  </View>
+</Overlay>
+```
+
+### 自定义高度
+
+```tsx
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+  overlayStyle={{ height: '50%' }}
+>
+  <Text>Half screen overlay</Text>
+</Overlay>
+```
+
+### 居中弹出
+
+```tsx
+<Overlay
+  isVisible={isVisible}
+  onBackdropPress={() => setIsVisible(false)}
+  overlayStyle={{
+    width: '80%',
+    height: 'auto',
+    position: 'relative',
+    borderRadius: 12,
+  }}
+>
+  <Text>Centered modal content</Text>
+</Overlay>
+```
+
+## 注意事项
+
+- 默认样式为底部弹出面板（`position: absolute, bottom: 0, width: 100%, height: 80%`）
+- 传入 `overlayStyle` 会与默认样式合并（数组形式），后者优先级更高
+- 组件需在 `ThemeProvider` 内使用
+- 遮罩背景色使用主题的 `grey4` 颜色

package/package/module/Pagination/BACKGROUND_COLOR.md

@@ -0,0 +1,173 @@
+# Pagination 背景色自定义
+
+## 概述
+
+TapasPagination 组件现在支持自定义背景色，允许您根据应用的设计需求灵活调整分页器的外观。
+
+## 新增属性
+
+### `backgroundColor`
+
+自定义分页器的背景色。
+
+```typescript
+backgroundColor?: string;
+```
+
+**类型**: `string` (可选)  
+**默认值**: 使用主题的 `theme.colors.background`  
+**支持格式**: 
+- 十六进制颜色：`#FFFFFF`、`#FFF`
+- RGB/RGBA：`rgb(255, 255, 255)`、`rgba(255, 255, 255, 0.5)`
+- 颜色名称：`white`、`blue` 等
+
+## 使用示例
+
+### 基础用法
+
+```typescript
+import Pagination from '@beppla/tapas-ui';
+
+<Pagination
+  totalCount="Total: 20"
+  pageParams={{
+    page: 1,
+    pageSize: 10,
+    totalItems: 60,
+    totalPage: 6,
+  }}
+  backgroundColor="#E3F2FD"  // 浅蓝色背景
+  onPageChange={(page) => console.log('Page:', page)}
+/>
+```
+
+### 不同场景的颜色示例
+
+```typescript
+// 浅色背景（适合深色文字）
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="#F5F5F5"  // 浅灰色
+/>
+
+// 品牌色背景
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="#E8F5E9"  // 浅绿色
+/>
+
+// 透明背景
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="transparent"
+/>
+
+// 使用主题默认背景（不设置 backgroundColor）
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  // backgroundColor 未设置时自动使用主题背景色
+/>
+```
+
+### 与其他样式组合
+
+```typescript
+<Pagination
+  totalCount="Total: 50"
+  pageParams={pageParams}
+  backgroundColor="#FFF9C4"  // 自定义背景色
+  paginationContainerStyle={{
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: '#E0E0E0',
+    paddingHorizontal: 32,
+  }}
+/>
+```
+
+## 推荐颜色方案
+
+### 浅色主题推荐
+
+```typescript
+const lightThemeColors = {
+  default: '#FFFFFF',      // 纯白
+  subtle: '#F5F5F5',       // 浅灰
+  info: '#E3F2FD',         // 浅蓝
+  success: '#E8F5E9',      // 浅绿
+  warning: '#FFF9C4',      // 浅黄
+  error: '#FFEBEE',        // 浅红
+};
+```
+
+### 深色主题推荐
+
+```typescript
+const darkThemeColors = {
+  default: '#1E1E1E',      // 深灰
+  subtle: '#2C2C2C',       // 较浅深灰
+  info: '#1A237E',         // 深蓝
+  success: '#1B5E20',      // 深绿
+  warning: '#F57F17',      // 深黄
+};
+```
+
+## 注意事项
+
+1. **文字对比度**: 确保背景色与文字颜色有足够的对比度，以保证可读性
+2. **品牌一致性**: 建议使用与应用整体设计语言一致的颜色
+3. **可访问性**: 遵循 WCAG 2.1 标准，确保颜色对比度至少为 4.5:1
+4. **主题集成**: 如果不设置 `backgroundColor`，组件会自动使用主题的背景色
+
+## 完整 Props
+
+```typescript
+interface Props {
+  totalCount: string;
+  pageSizeOptions?: ItemProps[];
+  visibleTotalCount?: boolean;
+  visiblePageSizeOptions?: boolean;
+  pageParams?: TPageParams;
+  onPageChange?: (page: TPageParams) => void;
+  onPageSizeChange?: (item: ItemProps) => void;
+  paginationContainerStyle?: StyleProp<ViewStyle>;
+  pageSizePosition?: TDropdownPosition;
+  backgroundColor?: string;  // ✨ 新增
+}
+```
+
+## Storybook 示例
+
+在 Storybook 中查看以下示例：
+
+- **Basic**: 默认样式
+- **CustomBackgroundColor**: 单一自定义背景色示例
+- **DifferentBackgroundColors**: 多种背景色对比展示
+
+## 常见问题
+
+### Q: 为什么我设置的背景色不生效？
+
+A: 请检查：
+1. `backgroundColor` 属性是否正确传递
+2. `paginationContainerStyle` 中是否有覆盖性的背景色设置
+3. 颜色值格式是否正确
+
+### Q: 可以使用渐变背景吗？
+
+A: 原生 `backgroundColor` 不支持渐变。如需渐变背景，请使用 `paginationContainerStyle` 配合其他库实现。
+
+### Q: 如何实现半透明背景？
+
+A: 使用 RGBA 格式：
+```typescript
+backgroundColor="rgba(255, 255, 255, 0.8)"  // 80% 不透明度
+```
+
+## 版本历史
+
+- **v1.4.17**: 新增 `backgroundColor` 属性支持

package/package/module/Pagination/DROPDOWN_IMPROVEMENTS.md

@@ -0,0 +1,321 @@
+# Pagination 下拉框优化
+
+## 版本 1.4.19 更新内容
+
+### 主要改进
+
+1. **自动位置检测** - 下拉框会自动检测可用空间，智能决定向上或向下显示
+2. **背景色同步** - 下拉框背景色自动继承 Pagination 的背景色
+3. **自适应宽度** - 下拉框宽度根据选项内容自动计算，避免文字换行挤压
+4. **布局优化** - 修复下拉框展开时挤压文字的问题
+
+## 向下兼容性 ✅
+
+### 完全向下兼容
+
+所有修改都是**向下兼容**的，不会破坏现有代码：
+
+| 修改项 | 类型 | 影响 | 兼容性 |
+|--------|------|------|--------|
+| `pageSizePosition` 默认值 | 从 `undefined` 改为 `'auto'` | 行为改进 | ✅ 完全兼容 |
+| `dropdownBackgroundColor` | 新增可选参数 | 无影响 | ✅ 完全兼容 |
+| `TDropdownPosition` 新增 `'auto'` | 类型扩展 | 无影响 | ✅ 完全兼容 |
+| z-index 提升 | 从 1000 → 9999 | 更好的层级 | ✅ 完全兼容 |
+
+### 迁移说明
+
+**不需要任何代码修改**！现有代码可以直接升级。
+
+```typescript
+// 现有代码无需修改
+<Pagination
+  totalCount="Total: 20"
+  pageParams={pageParams}
+  onPageChange={handlePageChange}
+/>
+
+// 可选：使用新功能
+<Pagination
+  totalCount="Total: 20"
+  pageParams={pageParams}
+  backgroundColor="#F5F5F5"  // 下拉框会自动继承
+  pageSizePosition="auto"    // 自动检测位置（默认值）
+  onPageChange={handlePageChange}
+/>
+```
+
+## 父级样式要求
+
+### ⚠️ 重要：容器要求
+
+TapasPagination 使用**绝对定位**的下拉框，需要满足以下条件：
+
+#### 1. 父容器需要有定位上下文
+
+```typescript
+// ✅ 正确：父容器有 position
+<View style={{ position: 'relative' }}>
+  <Pagination {...props} />
+</View>
+
+// ✅ 正确：使用 flex 容器
+<View style={{ display: 'flex', flexDirection: 'column' }}>
+  <Pagination {...props} />
+</View>
+
+// ❌ 错误：可能导致下拉框定位异常
+<View>
+  <Pagination {...props} />
+</View>
+```
+
+#### 2. 父容器需要有足够的 z-index 空间
+
+```typescript
+// ✅ 正确：确保父容器 z-index 不会限制下拉框
+<View style={{ position: 'relative', zIndex: 10 }}>
+  <Pagination {...props} />  {/* 下拉框 z-index: 9999 */}
+</View>
+
+// ❌ 错误：父容器 z-index 过高可能被其他元素遮挡
+<View style={{ position: 'relative', zIndex: 99999 }}>
+  <Pagination {...props} />
+</View>
+```
+
+#### 3. 避免 overflow: hidden 裁剪
+
+```typescript
+// ✅ 正确：允许下拉框溢出
+<View style={{ position: 'relative', overflow: 'visible' }}>
+  <Pagination {...props} />
+</View>
+
+// ❌ 错误：下拉框会被裁剪
+<View style={{ overflow: 'hidden' }}>
+  <Pagination {...props} />
+</View>
+```
+
+### 推荐的父容器配置
+
+```typescript
+// 完美的父容器配置
+<View style={{
+  position: 'relative',
+  overflow: 'visible',  // 允许下拉框溢出
+  zIndex: 1,            // 合理的层级
+  minHeight: 48,        // Pagination 的最小高度
+}}>
+  <Pagination
+    totalCount="Total: 20"
+    pageParams={pageParams}
+    backgroundColor="#FFFFFF"
+    pageSizePosition="auto"  // 自动检测空间
+  />
+</View>
+```
+
+## 新功能详解
+
+### 1. 自动位置检测 (`auto`)
+
+下拉框会智能检测可用空间：
+
+```typescript
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  pageSizePosition="auto"  // 默认值，自动检测
+/>
+```
+
+**工作原理**：
+- 检测按钮下方可用空间
+- 检测按钮上方可用空间
+- 如果下方空间不足且上方空间更大，向上展开
+- 否则向下展开
+
+### 2. 背景色自动继承
+
+```typescript
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="#E3F2FD"  // 下拉框自动使用相同背景色
+/>
+```
+
+### 3. 手动控制位置（依然支持）
+
+```typescript
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  pageSizePosition="upCenter"  // 强制向上居中
+/>
+```
+
+支持的位置：
+- `'auto'` - 自动检测（推荐，默认）
+- `'upCenter'` - 向上居中
+- `'upLeft'` - 向上左对齐
+- `'upRight'` - 向上右对齐
+- `'center'` - 向下居中
+- `'left'` - 向下左对齐
+- `'right'` - 向下右对齐
+
+## 常见问题
+
+### Q: 下拉框被裁剪了怎么办？
+
+A: 检查父容器是否有 `overflow: 'hidden'`，改为 `overflow: 'visible'`
+
+```typescript
+// 修复前
+<View style={{ overflow: 'hidden' }}>
+  <Pagination {...props} />
+</View>
+
+// 修复后
+<View style={{ overflow: 'visible' }}>
+  <Pagination {...props} />
+</View>
+```
+
+### Q: 下拉框定位异常怎么办？
+
+A: 确保父容器有 `position: 'relative'`
+
+```typescript
+<View style={{ position: 'relative' }}>
+  <Pagination {...props} />
+</View>
+```
+
+### Q: 下拉框被其他元素遮挡怎么办？
+
+A: 检查其他元素的 z-index，确保不超过 9999
+
+```typescript
+// 其他浮动元素
+<View style={{ position: 'absolute', zIndex: 999 }}>  
+  {/* z-index < 9999，不会遮挡下拉框 */}
+</View>
+```
+
+### Q: 如何禁用自动检测？
+
+A: 手动指定位置
+
+```typescript
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  pageSizePosition="upCenter"  // 强制向上
+/>
+```
+
+## 性能考虑
+
+自动位置检测仅在 Web 平台生效：
+- **Web**: 使用 `measure` API 检测空间
+- **移动端**: 使用 BottomSheet，无需检测
+
+## 最佳实践
+
+### 1. 表格底部的分页器
+
+```typescript
+<View style={{ position: 'relative', overflow: 'visible' }}>
+  <DataTable data={data} />
+  <Pagination
+    totalCount={`Total: ${total}`}
+    pageParams={pageParams}
+    pageSizePosition="auto"  // 自动检测
+  />
+</View>
+```
+
+### 2. 固定在页面底部
+
+```typescript
+<View style={{
+  position: 'fixed',
+  bottom: 0,
+  left: 0,
+  right: 0,
+  backgroundColor: '#FFF',
+  zIndex: 100,
+}}>
+  <Pagination
+    totalCount={`Total: ${total}`}
+    pageParams={pageParams}
+    pageSizePosition="upCenter"  // 固定在底部时强制向上
+  />
+</View>
+```
+
+### 3. 自定义样式容器
+
+```typescript
+<View style={{
+  position: 'relative',
+  overflow: 'visible',
+  padding: 16,
+  borderRadius: 8,
+  boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
+}}>
+  <Pagination
+    totalCount={`Total: ${total}`}
+    pageParams={pageParams}
+    backgroundColor="transparent"  // 透明背景
+  />
+</View>
+```
+
+## 技术细节
+
+### z-index 层级
+
+```
+App Container         z-index: 0
+  └─ Content         z-index: 1
+      └─ Pagination  z-index: 1
+          └─ Dropdown (展开) z-index: 9999
+```
+
+### 自动检测算法
+
+```typescript
+if (spaceBelow < dropdownHeight && spaceAbove > spaceBelow) {
+  // 下方空间不足 且 上方空间更大 → 向上
+  position = 'up';
+} else {
+  // 其他情况 → 向下
+  position = 'down';
+}
+```
+
+## API 参考
+
+### 新增属性
+
+```typescript
+interface Props {
+  // ... 其他属性
+  pageSizePosition?: 'auto' | 'upCenter' | 'upLeft' | 'upRight' | 'center' | 'left' | 'right';  // 默认 'auto'
+  backgroundColor?: string;           // 自定义背景色，下拉框自动继承
+  pageSizeDropdownWidth?: number;    // 自定义下拉框宽度（可选，默认自动计算）
+}
+```
+
+## 版本历史
+
+- **v1.4.19**: 
+  - ✨ 新增自动位置检测（'auto' 模式）
+  - 🎨 背景色自动继承
+  - 📐 自适应宽度：根据选项内容自动计算下拉框宽度
+  - 🐛 修复展开时挤压文字问题
+  - ⬆️ 提升 z-index 避免遮挡
+  - 📊 新增 pageSizeDropdownWidth 支持手动设置宽度

package/package/module/Pagination/README.md

@@ -0,0 +1,106 @@
+# Pagination
+
+分页组件，用于大数据列表的分页导航。支持页码选择、每页条数切换、分组翻页和总数展示，适配桌面和移动端。
+
+## 功能特性
+
+- ✅ 页码分组展示（每组 5 页），前后翻组
+- ✅ 当前页高亮（圆形选中样式）
+- ✅ 每页条数下拉选择（Dropdown 集成）
+- ✅ 总数显示（可选隐藏）
+- ✅ 移动端自适应：默认隐藏总数和每页条数选择
+- ✅ 自定义每页条数选项（pageSizeOptions）
+- ✅ 自定义容器样式和背景色
+- ✅ 下拉框位置和宽度可配置
+- ✅ 无障碍支持（accessibilityRole / accessibilityLabel）
+
+## 安装使用
+
+```tsx
+import { Pagination } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| totalCount | `string` | - | 总数显示文本（必填） |
+| pageParams | `TPageParams` | `{ page: 1, pageSize: 10, totalItems: 0, totalPage: 1 }` | 分页参数 |
+| pageSizeOptions | `ItemProps[]` | `[1, 5, 10, 20, 50, 100]/Page` | 每页条数选项 |
+| visibleTotalCount | `boolean` | 桌面端 `true`，移动端 `false` | 是否显示总数 |
+| visiblePageSizeOptions | `boolean` | 桌面端 `true`，移动端 `false` | 是否显示每页条数选择 |
+| onPageChange | `(page: TPageParams) => void` | - | 页码变化回调 |
+| onPageSizeChange | `(item: ItemProps) => void` | - | 每页条数变化回调 |
+| paginationContainerStyle | `StyleProp<ViewStyle>` | - | 容器样式 |
+| pageSizePosition | `TDropdownPosition` | `'auto'` | 下拉框弹出位置 |
+| backgroundColor | `string` | - | 背景色 |
+| pageSizeDropdownWidth | `number` | 自动计算 | 下拉框宽度 |
+
+### TPageParams
+
+```tsx
+type TPageParams = {
+  page: number;       // 当前页码
+  pageSize: number;   // 每页条数
+  totalItems: number; // 总条数
+  totalPage: number;  // 总页数
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Pagination
+  totalCount="100 items"
+  pageParams={{
+    page: 1,
+    pageSize: 10,
+    totalItems: 100,
+    totalPage: 10,
+  }}
+  onPageChange={(params) => {
+    fetchData(params.page, params.pageSize);
+  }}
+/>
+```
+
+### 自定义每页条数
+
+```tsx
+<Pagination
+  totalCount="500 records"
+  pageParams={pageParams}
+  pageSizeOptions={[
+    { name: '25/Page', value: 25 },
+    { name: '50/Page', value: 50 },
+    { name: '100/Page', value: 100 },
+  ]}
+  onPageChange={handlePageChange}
+  onPageSizeChange={(item) => {
+    setPageSize(item.value);
+  }}
+/>
+```
+
+### 隐藏总数和条数选择
+
+```tsx
+<Pagination
+  totalCount=""
+  pageParams={pageParams}
+  visibleTotalCount={false}
+  visiblePageSizeOptions={false}
+  onPageChange={handlePageChange}
+/>
+```
+
+## 注意事项
+
+- 页码分组为每组 5 页，通过左右箭头翻组
+- `pageParams` 变化会自动同步内部状态
+- 移动端自动隐藏总数和每页条数选择器
+- 下拉框宽度默认根据最长选项文本自动计算（最小 140px，最大 200px）
+- 组件使用 `React.memo` 优化渲染
+- 下拉框基于 Dropdown 组件实现