@beppla/tapas-ui 1.5.2 → 1.5.6

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 组件实现

package/module/PieChart/README.md

@@ -0,0 +1,212 @@
+# PieChart / NestedPieChart
+
+饼图组件，包含基础饼图（PieChart）和嵌套饼图（NestedPieChart）两个组件。支持饼图、环形图（Donut）、多层级嵌套等展示方式。采用**双平台渲染**策略：Web 端使用 recharts，Native 端使用 react-native-svg-charts。
+
+## 功能特性
+
+### PieChart
+- ✅ **双平台渲染**：Web 使用 recharts，Native 使用 react-native-svg-charts
+- ✅ 支持饼图和环形图（通过 innerRadius 控制）
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 图例可显示数值，支持 left / right 对齐
+- ✅ 自定义图例间距：行间距（legendItemGap）、Label-Value 间距（legendLabelValueGap）
+- ✅ Label 最小宽度控制（legendLabelMinWidth），确保数值列对齐
+- ✅ 饼图与图例间距可调（legendChartGap，左右位置时生效）
+- ✅ 自定义外圆/内圆半径，支持数字（像素）和字符串（百分比）
+- ✅ 支持扇区标签显示和中心文字
+- ✅ 长图例列表自动滚动（Native 端 ScrollView）
+
+### NestedPieChart
+- ✅ 支持多层级嵌套饼图（仅 Web 平台）
+- ✅ 树形数据结构和扁平数据结构，支持自动推断
+- ✅ 分组图例（grouped legend），可折叠展开
+- ✅ 自动配色策略（渐变色阶，baseColors 映射）
+- ✅ 扇区点击/悬停、图例点击事件
+- ✅ 图例过滤（enableLegendFilter）
+- ✅ 自定义 Tooltip
+- ✅ 格式化函数（数值 / 百分比）
+
+## 安装使用
+
+```tsx
+import { PieChart } from '@beppla/tapas-ui/components/PieChart';
+import { NestedPieChart } from '@beppla/tapas-ui/components/PieChart';
+```
+
+## PieChart Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `PieChartData[]` | (必填) | 饼图数据 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `300` | 图表高度 |
+| colors | `string[]` | 默认 6 色 | 颜色方案 |
+| outerRadius | `number \| string` | 自动计算 | 外圆半径，支持像素和百分比（如 `'80%'`） |
+| innerRadius | `number \| string` | `0` | 内圆半径，设置后变为环形图 |
+| padAngle | `number` | `0.02` | 扇区间隔角度 |
+| showLabels | `boolean` | `false` | 是否在扇区上显示标签 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'right'` | 图例位置 |
+| showLegendValues | `boolean` | `true` | 图例是否显示数值 |
+| legendValueAlign | `'left' \| 'right'` | `'right'` | 图例数值对齐方式 |
+| legendItemGap | `number` | `8` | 图例行间距（px） |
+| legendLabelValueGap | `number` | `12` | Label 与 Value 间距（px） |
+| legendLabelMinWidth | `number` | - | Label 最小宽度，确保对齐 |
+| legendChartGap | `number` | `30` | 饼图与图例间距（左右位置时生效） |
+| centerText | `string` | - | 中心文字（环形图） |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### PieChartData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `number` | 数值（必填） |
+| label | `string` | 标签 |
+| color | `string` | 自定义颜色（优先级高于 colors 数组） |
+| key | `string \| number` | 唯一标识 |
+
+## NestedPieChart Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `NestedPieChartNode[] \| NestedPieChartFlatData[]` | (必填) | 嵌套数据 |
+| dataType | `'tree' \| 'flat'` | 自动推断 | 数据类型 |
+| levels | `number` | 自动计算 | 显示层数 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | - | 图表高度 |
+| outerRadius | `number \| string` | - | 外圆半径 |
+| innerRadius | `number \| string` | - | 最内层半径 |
+| radiusGap | `number` | `10` | 层间间隔 |
+| colorStrategy | `ColorStrategy` | - | 配色策略（baseColors、autoGenerate、colorSteps） |
+| colors | `string[]` | - | 默认配色数组 |
+| showLegend | `boolean` | - | 是否显示图例 |
+| legendMode | `'flat' \| 'grouped'` | - | 图例模式 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | - | 图例位置 |
+| legendContent | `'all' \| 'parent-only' \| 'children-only'` | - | 图例显示内容 |
+| legendCollapsible | `boolean` | - | 图例是否可折叠 |
+| legendDefaultExpanded | `boolean` | - | 图例默认展开 |
+| legendSortStrategy | `'none' \| 'value-desc' \| 'value-asc' \| 'label-asc' \| 'label-desc'` | - | 图例排序策略 |
+| legendGroupSortStrategy | `LegendSortStrategy` | - | 分组排序策略 |
+| legendShowValues | `boolean` | - | 是否显示数值 |
+| legendShowPercent | `boolean` | - | 是否显示百分比 |
+| legendItemGap | `number` | - | 图例项间距 |
+| legendGroupGap | `number` | - | 分组间距 |
+| legendLabelMinWidth | `number` | - | Label 最小宽度 |
+| legendChartGap | `number` | - | 饼图与图例间距 |
+| showLabels | `boolean` | - | 是否显示扇区标签 |
+| labelLevel | `'all' \| number` | - | 显示标签的层级 |
+| formatValue | `(value: number) => string` | - | 数值格式化 |
+| formatPercent | `(percent: number) => string` | - | 百分比格式化 |
+| onSliceClick | `(event: SliceClickEvent) => void` | - | 扇区点击 |
+| onSliceHover | `(event: SliceClickEvent \| null) => void` | - | 扇区悬停 |
+| onLegendClick | `(event: LegendClickEvent) => void` | - | 图例点击 |
+| enableLegendFilter | `boolean` | - | 点击图例过滤扇区 |
+| showTooltip | `boolean` | - | 是否显示 Tooltip |
+| customTooltip | `(event: SliceClickEvent) => ReactNode` | - | 自定义 Tooltip |
+| padAngle | `number` | - | 扇区间隔角度 |
+| centerText | `string` | - | 中心文字 |
+| centerTextStyle | `React.CSSProperties` | - | 中心文字样式 |
+| emptyText | `string` | - | 空数据文本 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础饼图
+
+```tsx
+<PieChart
+  data={[
+    { value: 40, label: 'Category A', color: '#FF6B00' },
+    { value: 30, label: 'Category B', color: '#0066CC' },
+    { value: 20, label: 'Category C', color: '#00B894' },
+    { value: 10, label: 'Category D', color: '#6C5CE7' },
+  ]}
+  height={300}
+/>
+```
+
+### 环形图（Donut Chart）
+
+```tsx
+<PieChart
+  data={sampleData}
+  innerRadius="50%"
+  centerText="Total"
+/>
+```
+
+### 自定义饼图大小
+
+```tsx
+<PieChart data={sampleData} outerRadius={100} height={300} />
+<PieChart data={sampleData} outerRadius="80%" height={350} />
+```
+
+### 图例配置
+
+```tsx
+<PieChart
+  data={sampleData}
+  legendPosition="right"
+  showLegendValues
+  legendValueAlign="right"
+  legendItemGap={12}
+  legendLabelValueGap={20}
+  legendLabelMinWidth={200}
+  legendChartGap={48}
+/>
+```
+
+### NestedPieChart 嵌套饼图
+
+```tsx
+<NestedPieChart
+  data={[
+    {
+      key: 'food',
+      label: 'Food',
+      children: [
+        { key: 'rice', label: 'Rice', value: 30 },
+        { key: 'noodle', label: 'Noodle', value: 20 },
+      ],
+    },
+    {
+      key: 'drink',
+      label: 'Drink',
+      children: [
+        { key: 'coffee', label: 'Coffee', value: 25 },
+        { key: 'tea', label: 'Tea', value: 15 },
+      ],
+    },
+  ]}
+  showLegend
+  legendMode="grouped"
+  legendCollapsible
+/>
+```
+
+### 自定义配色
+
+```tsx
+<NestedPieChart
+  data={nestedData}
+  colorStrategy={{
+    baseColors: { cash: '#00B894', card: '#FF6B00' },
+    autoGenerate: true,
+  }}
+  height={450}
+/>
+```
+
+## 注意事项
+
+- **PieChart 双平台渲染**：Web 端使用 recharts（功能完整），Native 端使用 react-native-svg-charts（功能受限）
+- **NestedPieChart 仅支持 Web 平台**，Native 端会显示降级提示
+- `innerRadius` 设置为大于 0 的值即变为环形图
+- `outerRadius` 支持数字（像素）和字符串（百分比如 `'80%'`）
+- `legendChartGap` 仅在图例位于 left / right 时生效
+- `legendLabelMinWidth` 可确保不同长度标签的数值列对齐
+- Native 端图例使用 ScrollView 实现长列表滚动
+- 需安装对应平台依赖：Web 需要 `recharts`，Native 需要 `react-native-svg-charts` + `react-native-svg`

package/module/Popover/README.md

@@ -0,0 +1,82 @@
+# Popover
+
+气泡弹出层组件，用于显示与触发元素相对定位的内容面板。支持四个方向（top/bottom/left/right）和三种箭头位置（start/center/end），适合工具提示、操作菜单等场景。
+
+## 功能特性
+
+- ✅ 四个弹出方向：top、bottom、left、right
+- ✅ 三种箭头位置：start、center、end
+- ✅ 自定义宽高尺寸
+- ✅ 带阴影的浮层效果（elevation: 8）
+- ✅ 箭头自动跟随方向和位置调整
+- ✅ 通过 isVisible 控制显隐
+- ✅ 支持自定义容器和内容区样式
+- ✅ 主题色适配（withTheme HOC）
+
+## 安装使用
+
+```tsx
+import { Popover } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | - | 是否显示（必填） |
+| children | `React.ReactNode` | - | 弹出层内容 |
+| position | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 弹出方向 |
+| arrowPosition | `'start' \| 'center' \| 'end'` | `'center'` | 箭头在边上的位置 |
+| width | `number` | `392` | 弹出层宽度 |
+| height | `number` | `696` | 弹出层高度 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 外层容器样式 |
+| contentStyle | `StyleProp<ViewStyle>` | - | 内容区域样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+
+<Button onPress={() => setIsVisible(true)}>Show Popover</Button>
+<Popover isVisible={isVisible} position="bottom">
+  <Text>Popover content here</Text>
+</Popover>
+```
+
+### 左侧弹出 + 箭头末端
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="left"
+  arrowPosition="end"
+  width={392}
+  height={396}
+>
+  <Text>Left popover with end arrow</Text>
+</Popover>
+```
+
+### 自定义尺寸
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="top"
+  arrowPosition="start"
+  width={280}
+  height={200}
+>
+  <Text>Compact popover</Text>
+</Popover>
+```
+
+## 注意事项
+
+- 组件使用 `position: absolute` 定位，需要父容器提供合适的定位上下文
+- `isVisible` 为 `false` 时组件返回 `null`，不占据布局空间
+- 箭头使用 TapasIcon 的 `left_arrow` 图标，通过旋转适配不同方向
+- `arrowPosition` 的 `center` 值根据 `width` 或 `height` 自动计算居中位置
+- 需在 `ThemeProvider` 内使用

package/module/Progress/README.md

@@ -0,0 +1,106 @@
+# Progress
+
+进度条组件，用于显示文件上传或图片处理等任务的进度状态。支持 image 和 file 两种布局类型，可展示进行中（progress）、完成（done）和失败（failed）三种状态。
+
+## 功能特性
+
+- ✅ 两种展示类型：image（图片进度条）和 file（文件进度条）
+- ✅ 三种状态：progress（进行中）、done（完成）、failed（失败）
+- ✅ 状态自动匹配图标和颜色（success / error）
+- ✅ 自定义起始和结束内容区域（支持 ReactNode）
+- ✅ 进度百分比展示
+- ✅ file 类型支持文件名展示
+- ✅ 主题色适配
+- ✅ React.memo 优化渲染性能
+
+## 安装使用
+
+```tsx
+import { Progress } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | `'image' \| 'file'` | - | 展示类型（必填） |
+| data | `ProgressData` | - | 进度数据（必填） |
+| testID | `string` | - | 测试标识 |
+
+### ProgressData
+
+```tsx
+interface ProgressData {
+  start: React.ReactNode | string;   // 左侧内容（如缩略图、图标）
+  end?: React.ReactNode | string;    // 右侧内容（状态文本）
+  status: 'progress' | 'done' | 'failed';  // 当前状态
+  progress?: number;                  // 进度值（0-100）
+  file?: string;                      // 文件名（file 类型使用）
+}
+```
+
+## 使用示例
+
+### 图片上传进度
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'progress',
+    progress: 65,
+  }}
+/>
+```
+
+### 上传完成
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'done',
+    end: 'Uploaded',
+  }}
+/>
+```
+
+### 文件上传
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'document.pdf',
+    status: 'progress',
+    progress: 42,
+  }}
+/>
+```
+
+### 上传失败
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'report.xlsx',
+    status: 'failed',
+    end: 'Upload failed',
+  }}
+/>
+```
+
+## 注意事项
+
+- `data` 为 null 或 undefined 时组件返回 null
+- `image` 类型为左右布局，进度条位于中间
+- `file` 类型为上下布局，文件名在上方，进度条在下方
+- `end` 属性不存在时，默认显示 `progress%` 文本
+- 进度条宽度通过 CSS `width: ${progress}%` 实现
+- 使用 `withTheme` + `React.memo` 双重优化
+- 需在 `ThemeProvider` 内使用

package/module/RadioButton/README.md

@@ -0,0 +1,85 @@
+# RadioButton
+
+单选按钮组件，用于在一组选项中选择一个值。采用圆形指示器和文字标签的经典单选样式。
+
+## 功能特性
+
+- ✅ 支持多个选项的单选功能
+- ✅ 受控模式，通过 selected 属性指定默认选中项
+- ✅ 自动跟踪外部 selected 属性变化
+- ✅ 圆形选中指示器，使用主题色渲染
+- ✅ 垂直排列布局，每个选项固定高度 40px
+- ✅ 使用 React.memo 优化渲染性能
+- ✅ 支持 testID 属性用于测试
+
+## 安装使用
+
+```tsx
+import RadioButton from '@beppla/tapas-ui/components/RadioButton/RadioButton';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| options | `Option[]` | - | 选项列表 |
+| onPress | `(option: Option) => void` | - | 选中回调，返回被选中的选项 |
+| selected | `string` | `""` | 默认选中项的 key 值 |
+| testID | `string` | - | 测试标识 |
+
+### Option 数据类型
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| key | `string` | 选项唯一标识 |
+| text | `string` | 选项显示文字 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<RadioButton
+  options={[
+    { key: 'a', text: '选项 A' },
+    { key: 'b', text: '选项 B' },
+    { key: 'c', text: '选项 C' },
+  ]}
+  onPress={(option) => console.log('选中:', option.key)}
+/>
+```
+
+### 指定默认选中
+
+```tsx
+<RadioButton
+  options={[
+    { key: 'male', text: '男' },
+    { key: 'female', text: '女' },
+  ]}
+  selected="male"
+  onPress={(option) => setGender(option.key)}
+/>
+```
+
+### 受控模式
+
+```tsx
+const [selected, setSelected] = useState('option1');
+
+<RadioButton
+  options={[
+    { key: 'option1', text: '立即配送' },
+    { key: 'option2', text: '预约配送' },
+  ]}
+  selected={selected}
+  onPress={(option) => setSelected(option.key)}
+/>
+```
+
+## 注意事项
+
+- 组件通过 `withTheme` HOC 注入主题，圆形指示器颜色使用 `theme.colors.primary`
+- 选项文字颜色也使用主题主色，与指示器保持一致
+- 组件不支持禁用单个选项，如需此功能需自行扩展
+- `selected` 属性变化时会自动同步内部状态

package/module/ScanButton/README.md

@@ -0,0 +1,72 @@
+# ScanButton
+
+浮动扫描按钮组件，用于快速启动二维码扫描等功能。支持五个定位位置，可自定义文本、图标和颜色，以悬浮按钮形式固定在页面指定位置。
+
+## 功能特性
+
+- ✅ 五种定位位置：bottom-right / bottom-left / top-right / top-left / center
+- ✅ 自定义按钮文本
+- ✅ 自定义图标（TapasIcon 图标名）
+- ✅ 自定义图标大小
+- ✅ 自定义背景色、文字色、图标色
+- ✅ 悬浮定位（position: absolute）
+- ✅ 圆角胶囊按钮样式 + 阴影效果
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { ScanButton } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| onPress | `() => void` | - | 按钮点击回调 |
+| text | `string` | `'Scan QR Code'` | 按钮文本 |
+| icon | `string` | `'qr_code_scan'` | 图标名称 |
+| size | `number` | `20` | 图标大小 |
+| position | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'center'` | `'bottom-right'` | 按钮定位位置 |
+| backgroundColor | `string` | 主题 primary | 背景色 |
+| textColor | `string` | 主题 white | 文字颜色 |
+| iconColor | `string` | 主题 white | 图标颜色 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<ScanButton onPress={() => navigation.navigate('Scanner')} />
+```
+
+### 左下角定位
+
+```tsx
+<ScanButton
+  position="bottom-left"
+  onPress={() => handleScan()}
+/>
+```
+
+### 自定义样式
+
+```tsx
+<ScanButton
+  text="Scan Barcode"
+  icon="barcode_scanner"
+  position="top-right"
+  backgroundColor="#895F38"
+  textColor="#FFF"
+  onPress={() => handleBarcodeScan()}
+/>
+```
+
+## 注意事项
+
+- 组件使用 `position: absolute` 定位，需要父容器具备定位上下文
+- 按钮固定高度 40px，圆角 20px（胶囊形状）
+- 文本超长会自动截断（numberOfLines=1, ellipsizeMode=tail）
+- `center` 位置通过负 margin 实现居中，可能需要根据内容宽度调整
+- 需在 `ThemeProvider` 内使用