@beppla/tapas-ui 1.5.12 → 1.5.13

package/package/module/Pagination/DROPDOWN_IMPROVEMENTS.md

@@ -1,321 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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 组件实现

package/package/module/PieChart/BACKWARD_COMPATIBILITY.md

@@ -1,157 +0,0 @@
-# 向下兼容性说明
-
-## ✅ 完全向下兼容
-
-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

@@ -1,86 +0,0 @@
-# 问题修复：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 专用组件来说是最佳实践。