@beppla/tapas-ui 1.5.9 → 1.5.11

package/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/package/module/Popover/Popover.js

@@ -0,0 +1,160 @@
+"use strict";
+
+import React from 'react';
+import { View } from 'react-native';
+import { makeStyles, withTheme } from '@rneui/themed';
+import Icon from '../Icons/TapasIcon';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const useStyles = makeStyles(theme => ({
+  container: {
+    position: 'absolute',
+    backgroundColor: theme.colors.white,
+    borderRadius: theme.radius.rounded,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: 12
+    },
+    shadowOpacity: 0.58,
+    shadowRadius: 24,
+    elevation: 8,
+    zIndex: 9999
+  },
+  arrow: {
+    position: 'absolute',
+    color: theme.colors.white,
+    width: 12,
+    height: 27
+  },
+  arrowTop: {
+    top: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: -2
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowBottom: {
+    bottom: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: 2
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowLeft: {
+    left: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: -2,
+      height: 0
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowRight: {
+    right: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 2,
+      height: 0
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  content: {
+    flex: 1,
+    borderRadius: theme.radius.rounded,
+    overflow: 'hidden'
+  }
+}));
+const Popover = ({
+  isVisible,
+  children,
+  position = 'bottom',
+  arrowPosition = 'center',
+  width = 392,
+  height = 696,
+  containerStyle,
+  contentStyle,
+  testID,
+  ...props
+}) => {
+  const styles = useStyles(props);
+  if (!isVisible) return null;
+  const getArrowStyle = () => {
+    let arrowPositionStyle = {};
+    switch (position) {
+      case 'top':
+        arrowPositionStyle = styles.arrowTop;
+        break;
+      case 'bottom':
+        arrowPositionStyle = styles.arrowBottom;
+        break;
+      case 'left':
+        arrowPositionStyle = styles.arrowLeft;
+        break;
+      case 'right':
+        arrowPositionStyle = styles.arrowRight;
+        break;
+    }
+
+    // 根据箭头位置调整left/top值
+    const positionStyle = {};
+    if (position === 'top' || position === 'bottom') {
+      switch (arrowPosition) {
+        case 'start':
+          positionStyle.left = 20;
+          break;
+        case 'center':
+          positionStyle.left = width / 2 - 6;
+          break;
+        case 'end':
+          positionStyle.right = 20;
+          break;
+      }
+    } else {
+      switch (arrowPosition) {
+        case 'start':
+          positionStyle.top = 20;
+          break;
+        case 'center':
+          positionStyle.top = height / 2 - 6;
+          break;
+        case 'end':
+          positionStyle.bottom = 20;
+          break;
+      }
+    }
+    return {
+      ...styles.arrow,
+      ...arrowPositionStyle,
+      ...positionStyle
+    };
+  };
+  return /*#__PURE__*/_jsxs(View, {
+    style: [styles.container, {
+      width,
+      height
+    }, containerStyle],
+    testID: testID ?? "popover",
+    children: [/*#__PURE__*/_jsx(Icon, {
+      name: "left_arrow",
+      size: 17,
+      style: getArrowStyle()
+    }), /*#__PURE__*/_jsx(View, {
+      style: [styles.content, contentStyle],
+      children: children
+    })]
+  });
+};
+export default withTheme(Popover);
+//# sourceMappingURL=Popover.js.map

package/package/module/Popover/Popover.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","View","makeStyles","withTheme","Icon","jsx","_jsx","jsxs","_jsxs","useStyles","theme","container","position","backgroundColor","colors","white","borderRadius","radius","rounded","shadowColor","grey4","shadowOffset","width","height","shadowOpacity","shadowRadius","elevation","zIndex","arrow","color","arrowTop","top","arrowBottom","bottom","arrowLeft","left","arrowRight","right","content","flex","overflow","Popover","isVisible","children","arrowPosition","containerStyle","contentStyle","testID","props","styles","getArrowStyle","arrowPositionStyle","positionStyle","style","name","size"],"sourceRoot":"../../../components","sources":["Popover/Popover.tsx"],"mappings":"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","ignoreList":[]}

package/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/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` 内使用