@beppla/tapas-ui 1.4.31 → 1.4.33

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/PieChart/BACKWARD_COMPATIBILITY.md

@@ -0,0 +1,157 @@
+# 向下兼容性说明
+
+## ✅ 完全向下兼容
+
+NestedPieChart 的添加**不会影响**现有的 PieChart 组件及其使用：
+
+### 1. 独立导出
+
+```typescript
+// 现有组件 - 完全不受影响
+export { PieChart } from './PieChart';
+export type { PieChartProps, PieChartData } from './PieChart';
+
+// 新增组件 - 独立导出
+export { default as NestedPieChart } from './NestedPieChart';
+export type {
+  NestedPieChartProps,
+  NestedPieChartNode,
+  // ... 其他类型
+} from './NestedPieChart.types';
+```
+
+### 2. 现有代码无需更改
+
+**旧代码继续正常工作：**
+```tsx
+// 这些代码完全不受影响
+import { PieChart } from '@beppla/tapas-ui';
+
+<PieChart 
+  data={[
+    { value: 100, label: 'A' },
+    { value: 200, label: 'B' }
+  ]}
+/>
+```
+
+**新功能可选使用：**
+```tsx
+// 只有需要多层级时才使用新组件
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+<NestedPieChart 
+  data={nestedData}
+/>
+```
+
+### 3. 文件结构
+
+```
+components/PieChart/
+├── PieChart.tsx                 # 原有 - 未修改
+├── __tests__/PieChart.test.tsx  # 原有 - 未修改
+├── NestedPieChart.tsx           # 新增
+├── NestedPieChart.types.ts      # 新增
+├── NestedPieChart.utils.ts      # 新增
+├── GroupedLegend.tsx            # 新增
+├── __tests__/NestedPieChart.test.tsx # 新增
+└── index.tsx                    # 更新 - 仅添加导出
+```
+
+### 4. 依赖关系
+
+- NestedPieChart **不依赖** PieChart
+- PieChart **不依赖** NestedPieChart
+- 两者**完全独立**，互不影响
+
+### 5. 包大小影响
+
+- **Tree-shaking 支持**：如果不使用 NestedPieChart，它不会被打包
+- **按需导入**：
+  ```tsx
+  // 只导入 PieChart - NestedPieChart 不会被打包
+  import { PieChart } from '@beppla/tapas-ui';
+  
+  // 只导入 NestedPieChart - PieChart 不会被打包
+  import { NestedPieChart } from '@beppla/tapas-ui';
+  ```
+
+### 6. API 兼容性
+
+| 特性 | PieChart | NestedPieChart | 说明 |
+|------|----------|----------------|------|
+| 单层数据 | ✅ | ✅ | NestedPieChart 支持降级 |
+| 多层数据 | ❌ | ✅ | 新功能 |
+| Web 支持 | ✅ | ✅ | 完全支持 |
+| RN 支持 | ✅ | ⚠️ | 降级提示 |
+| Props 冲突 | N/A | ❌ | 无冲突 |
+
+### 7. 版本策略
+
+这是一个**小版本（minor）**更新：
+- ✅ 添加新功能
+- ✅ 完全向下兼容
+- ❌ 无破坏性变更
+- ❌ 无 API 修改
+
+符合语义化版本规范（Semver）。
+
+### 8. 迁移路径（可选）
+
+如果要从 PieChart 迁移到 NestedPieChart：
+
+**不需要迁移：**
+- 单层数据继续使用 PieChart 即可
+
+**需要迁移：**
+- 只有需要多层级功能时才考虑
+- 数据结构需要调整为树形或扁平+groupKey
+
+**迁移示例：**
+```tsx
+// 旧代码 (PieChart - 单层)
+<PieChart data={[
+  { value: 100, label: 'A' },
+  { value: 200, label: 'B' }
+]} />
+
+// 新代码 (NestedPieChart - 多层)
+<NestedPieChart data={[
+  { 
+    key: 'group-a', 
+    label: 'Group A',
+    children: [
+      { key: 'a1', label: 'A1', value: 50 },
+      { key: 'a2', label: 'A2', value: 50 }
+    ]
+  }
+]} />
+```
+
+### 9. TypeScript 类型安全
+
+- 所有新类型都独立导出
+- 不会与现有类型冲突
+- 完整的类型推导支持
+
+### 10. 测试覆盖
+
+- PieChart 的测试不受影响
+- NestedPieChart 有独立的测试套件
+- 无测试冲突
+
+## 🎯 总结
+
+**NestedPieChart 是一个完全独立的新组件：**
+
+✅ 不修改现有组件  
+✅ 不修改现有 API  
+✅ 不影响现有使用  
+✅ 不增加包大小（未使用时）  
+✅ 可选使用，渐进增强  
+
+**建议：**
+- 现有项目无需任何修改
+- 新需求可使用 NestedPieChart
+- 两者可共存使用

package/package/module/PieChart/BUGFIX_EMPTY_DATA.md

@@ -0,0 +1,86 @@
+# 问题修复：Empty Data 报错
+
+## 🐛 问题描述
+
+在 Storybook 中查看 `Empty Data` story 时出现错误：
+```
+Cannot read properties of undefined (reading 'fonts')
+```
+
+## 🔍 根本原因
+
+NestedPieChart 组件在空数据情况下使用了 `Text` 组件（来自 `@rneui/themed`），该组件依赖主题上下文中的 `theme.fonts` 配置。但在某些 Storybook 场景下可能缺少完整的主题提供者（ThemeProvider）。
+
+## ✅ 解决方案
+
+将空数据提示从 React Native 的 `Text` 组件改为纯 HTML `div`，因为：
+
+1. **NestedPieChart 是 Web 专用组件**（使用 Recharts）
+2. **不需要 RN 的 Text 组件**来显示空状态
+3. **避免主题依赖**，使组件更加独立和健壮
+
+### 修改内容
+
+**修改前：**
+```tsx
+import RNText from '../Text/Text';
+
+// 空数据处理
+if (!processedData || processedData.length === 0 || total === 0) {
+  return (
+    <View style={[styles.container, { height }, style]} testID={testID}>
+      <RNText style={styles.emptyText}>{emptyText}</RNText>
+    </View>
+  );
+}
+```
+
+**修改后：**
+```tsx
+// 移除 RNText 导入
+
+// 空数据处理
+if (!processedData || processedData.length === 0 || total === 0) {
+  return (
+    <View style={[styles.container, { height }, style]} testID={testID}>
+      <div style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '100%',
+        color: '#999',
+        fontSize: 14,
+      }}>
+        {emptyText}
+      </div>
+    </View>
+  );
+}
+```
+
+同样的修改也应用到了 RN 端降级提示。
+
+## 🎯 修复结果
+
+- ✅ Empty Data story 正常渲染
+- ✅ 无主题依赖错误
+- ✅ ESLint 检查通过
+- ✅ 组件更加独立和健壮
+
+## 📝 注意事项
+
+由于 NestedPieChart 是 **Web 专用组件**（Platform.OS === 'web' && RechartsPieChart），使用纯 HTML 元素完全合理且推荐。组件已经在顶部添加了 eslint-disable 注释来处理 Web 专用代码。
+
+## 🧪 验证
+
+在 Storybook 中访问：
+- `Empty Data` story - 现在应该正常显示 "No sales data available"
+- 所有其他 stories - 不受影响，正常工作
+
+## 🔄 后续
+
+如果将来需要在 React Native 端实现完整功能，可以考虑：
+1. 条件渲染：Web 端用 div，RN 端用 Text
+2. 或者确保 ThemeProvider 包裹所有组件使用场景
+
+但目前的解决方案对于 Web 专用组件来说是最佳实践。