@beppla/tapas-ui 1.4.34 → 1.5.0

package/package/module/Pagination/BACKGROUND_COLOR.md

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

@@ -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/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
-- 两者可共存使用