@beppla/tapas-ui 1.5.9 → 1.5.11

package/package/module/PieChart/NestedPieChart.README.md

@@ -0,0 +1,421 @@
+# NestedPieChart (多层级饼图)
+
+多层级饼图组件，支持双层嵌套、分组图例、交互高亮等功能。专为 Store insights / Summary 等场景设计。
+
+## 特性
+
+### 核心功能
+
+- ✅ **多层级支持**：支持 2 层嵌套（外层大类 + 内层子类），可扩展到 N 层
+- ✅ **树形数据结构**：支持 `tree` 和 `flat` 两种数据输入格式
+- ✅ **智能配色**：
+  - 大类固定基色（可自定义 mapping）
+  - 子类自动生成同色系渐变色
+  - 保证相邻颜色可辨识（可配置最小色差）
+- ✅ **分组图例**：
+  - 按大类分组显示
+  - 支持折叠/展开（可配置默认状态）
+  - 显示分组小计和子项明细
+  - 可配置排序策略（按值、按标签、保持原序）
+- ✅ **交互高亮**：
+  - Hover 扇区高亮对应图例项
+  - Hover 图例项高亮对应扇区
+  - 点击事件支持（扇区和图例）
+- ✅ **数据筛选**：点击图例可隐藏/显示对应扇区（可选）
+- ✅ **自定义 Tooltip**：支持自定义渲染和格式化
+- ✅ **数据处理**：自动去重、合并、过滤 0 值
+- ✅ **响应式布局**：自适应容器尺寸
+- ✅ **跨端支持**：Web 端完整功能，RN 端提供降级方案
+
+## 基础用法
+
+### 树形数据（推荐）
+
+```tsx
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+const data = [
+  {
+    key: 'cash',
+    label: 'Cash',
+    children: [
+      { key: 'cash-19', label: '19% VAT', value: 1250.50 },
+      { key: 'cash-7', label: '7% VAT', value: 680.30 },
+    ],
+  },
+  {
+    key: 'credit-card',
+    label: 'Credit Card',
+    children: [
+      { key: 'cc-19', label: '19% VAT', value: 3420.80 },
+      { key: 'cc-7', label: '7% VAT', value: 1560.40 },
+    ],
+  },
+];
+
+const paymentMethodColors = {
+  'cash': '#00B894',
+  'credit-card': '#FF6B00',
+};
+
+<NestedPieChart
+  data={data}
+  height={450}
+  colorStrategy={{
+    baseColors: paymentMethodColors,
+    autoGenerate: true,
+  }}
+  formatValue={(value) => `€${value.toFixed(2)}`}
+/>
+```
+
+### 扁平数据
+
+```tsx
+const flatData = [
+  { key: 'cash-19', label: '19% VAT', value: 1250.50, groupKey: 'cash', groupLabel: 'Cash' },
+  { key: 'cash-7', label: '7% VAT', value: 680.30, groupKey: 'cash', groupLabel: 'Cash' },
+  { key: 'cc-19', label: '19% VAT', value: 3420.80, groupKey: 'credit-card', groupLabel: 'Credit Card' },
+];
+
+<NestedPieChart
+  data={flatData}
+  dataType="flat"
+  height={450}
+/>
+```
+
+## Props
+
+### 数据相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `NestedPieChartNode[]` \| `NestedPieChartFlatData[]` | **required** | 图表数据 |
+| `dataType` | `'tree'` \| `'flat'` | auto | 数据类型，默认自动推断 |
+| `levels` | `number` | auto | 显示层数，默认自动计算 |
+
+### 尺寸相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `number` | auto | 容器宽度 |
+| `height` | `number` | `400` | 容器高度 |
+| `outerRadius` | `number` \| `string` | auto | 外圆半径（可以是数字或百分比） |
+| `innerRadius` | `number` \| `string` | `60` | 内圆半径（形成 donut 图） |
+| `radiusGap` | `number` | `15` | 层与层之间的间隔 |
+
+### 配色相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `colorStrategy` | `ColorStrategy` | `{ autoGenerate: true }` | 配色策略 |
+| `colors` | `string[]` | `DEFAULT_COLORS` | 默认配色数组 |
+
+#### ColorStrategy
+
+```tsx
+interface ColorStrategy {
+  baseColors?: Record<string, string>; // 大类基色 mapping
+  autoGenerate?: boolean;              // 是否自动生成子类渐变色
+  colorSteps?: number;                 // 渐变色阶数
+  minColorDiff?: number;               // 相邻颜色最小色差 (0-1)
+}
+```
+
+### 图例相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showLegend` | `boolean` | `true` | 是否显示图例 |
+| `legendMode` | `'flat'` \| `'grouped'` | `'grouped'` | 图例模式 |
+| `legendPosition` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` | `'right'` | 图例位置 |
+| `legendContent` | `'all'` \| `'parent-only'` \| `'children-only'` | `'all'` | 图例显示内容 |
+| `legendCollapsible` | `boolean` | `true` | 是否可折叠 |
+| `legendDefaultExpanded` | `boolean` | `true` | 默认展开状态 |
+| `legendSortStrategy` | `LegendSortStrategy` | `'none'` | 子项排序策略 |
+| `legendGroupSortStrategy` | `LegendSortStrategy` | `'none'` | 分组排序策略 |
+| `legendShowValues` | `boolean` | `true` | 是否显示数值 |
+| `legendShowPercent` | `boolean` | `true` | 是否显示百分比 |
+| `legendItemGap` | `number` | `6` | 图例项间距 |
+| `legendGroupGap` | `number` | `16` | 分组间距 |
+| `legendLabelMinWidth` | `number` | auto | 标签最小宽度 |
+| `legendChartGap` | `number` | `30` | 图例与图表间距 |
+
+#### LegendSortStrategy
+
+- `'none'`: 保持原始顺序
+- `'value-desc'`: 按值降序
+- `'value-asc'`: 按值升序
+- `'label-asc'`: 按标签升序
+- `'label-desc'`: 按标签降序
+
+### 格式化相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formatValue` | `(value: number) => string` | Euro format | 数值格式化函数 |
+| `formatPercent` | `(percent: number) => string` | `${percent.toFixed(1)}%` | 百分比格式化函数 |
+
+### 交互相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSliceClick` | `(event: SliceClickEvent) => void` | - | 扇区点击事件 |
+| `onSliceHover` | `(event: SliceClickEvent \| null) => void` | - | 扇区 hover 事件 |
+| `onLegendClick` | `(event: LegendClickEvent) => void` | - | 图例点击事件 |
+| `enableLegendFilter` | `boolean` | `false` | 是否启用图例筛选功能 |
+
+### Tooltip 相关
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showTooltip` | `boolean` | `true` | 是否显示 Tooltip |
+| `customTooltip` | `(event: SliceClickEvent) => ReactNode` | - | 自定义 Tooltip 渲染 |
+
+### 其他
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `padAngle` | `number` | `0.01` | 扇区间隔角度 |
+| `centerText` | `string` | - | 中心文本 |
+| `centerTextStyle` | `CSSProperties` | - | 中心文本样式 |
+| `emptyText` | `string` | `'No data available'` | 空数据提示文本 |
+| `style` | `any` | - | 容器样式 |
+| `testID` | `string` | - | 测试 ID |
+
+## 数据结构
+
+### NestedPieChartNode (树形)
+
+```tsx
+interface NestedPieChartNode {
+  key: string | number;           // 唯一标识
+  label: string;                  // 显示文本
+  value?: number;                 // 叶子节点必须有值
+  color?: string;                 // 自定义颜色（可选）
+  children?: NestedPieChartNode[]; // 子节点
+  metadata?: Record<string, any>; // 额外元数据
+}
+```
+
+### NestedPieChartFlatData (扁平)
+
+```tsx
+interface NestedPieChartFlatData {
+  key: string | number;
+  label: string;
+  value: number;
+  groupKey: string | number;      // 所属分组
+  groupLabel: string;             // 分组名称
+  color?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+## 事件对象
+
+### SliceClickEvent
+
+```tsx
+interface SliceClickEvent {
+  key: string | number;
+  label: string;
+  value: number;
+  level: number;                  // 0=根，1=第一层子节点
+  path: Array<string | number>;   // 从根到当前节点的路径
+  parentKey?: string | number;
+  metadata?: Record<string, any>;
+}
+```
+
+### LegendClickEvent
+
+```tsx
+interface LegendClickEvent extends SliceClickEvent {
+  groupKey?: string | number;
+  isGroupHeader?: boolean;        // 是否点击的是分组标题
+}
+```
+
+## 高级用法
+
+### 自定义配色策略
+
+```tsx
+<NestedPieChart
+  data={data}
+  colorStrategy={{
+    baseColors: {
+      'cash': '#00B894',
+      'credit-card': '#FF6B00',
+      'apple-pay': '#0066CC',
+    },
+    autoGenerate: true,
+    colorSteps: 5,
+    minColorDiff: 0.12,
+  }}
+/>
+```
+
+### 交互和筛选
+
+```tsx
+function InteractiveChart() {
+  const [selectedItem, setSelectedItem] = useState<string>('');
+  
+  return (
+    <>
+      <NestedPieChart
+        data={data}
+        enableLegendFilter={true}
+        onSliceClick={(event) => {
+          setSelectedItem(event.label);
+        }}
+        onLegendClick={(event) => {
+          console.log('Legend clicked:', event);
+        }}
+      />
+      {selectedItem && <Text>Selected: {selectedItem}</Text>}
+    </>
+  );
+}
+```
+
+### 自定义 Tooltip
+
+```tsx
+<NestedPieChart
+  data={data}
+  customTooltip={(event) => (
+    <div style={{
+      backgroundColor: '#2C3E50',
+      color: 'white',
+      padding: '12px',
+      borderRadius: '8px',
+    }}>
+      <div style={{ fontWeight: 600 }}>{event.label}</div>
+      <div>Amount: €{event.value.toFixed(2)}</div>
+      <div>Level: {event.level === 0 ? 'Payment Method' : 'Tax Rate'}</div>
+    </div>
+  )}
+/>
+```
+
+### 排序策略
+
+```tsx
+<NestedPieChart
+  data={data}
+  legendGroupSortStrategy="value-desc"  // 分组按值降序
+  legendSortStrategy="value-desc"       // 子项按值降序
+/>
+```
+
+### 中心文本和样式
+
+```tsx
+<NestedPieChart
+  data={data}
+  centerText="€14,768"
+  centerTextStyle={{
+    fontSize: '28px',
+    fontWeight: 700,
+    color: '#2C3E50',
+  }}
+/>
+```
+
+## 使用场景
+
+### Store Insights / Summary
+
+```tsx
+// 支付方式 -> 税率分析
+const salesData = [
+  {
+    key: 'cash',
+    label: 'Cash',
+    children: [
+      { key: 'cash-19', label: '19% VAT', value: 1250.50 },
+      { key: 'cash-7', label: '7% VAT', value: 680.30 },
+    ],
+  },
+  // ...
+];
+
+<NestedPieChart
+  data={salesData}
+  height={450}
+  formatValue={(value) => new Intl.NumberFormat('de-DE', {
+    style: 'currency',
+    currency: 'EUR',
+  }).format(value)}
+/>
+```
+
+### 分类销售分析
+
+```tsx
+// 产品类别 -> 子类别销售
+const productData = [
+  {
+    key: 'food',
+    label: 'Food & Beverage',
+    children: [
+      { key: 'food-hot', label: 'Hot Meals', value: 5200 },
+      { key: 'food-cold', label: 'Cold Drinks', value: 3100 },
+      { key: 'food-dessert', label: 'Desserts', value: 1800 },
+    ],
+  },
+  // ...
+];
+```
+
+## 注意事项
+
+1. **数据要求**：
+   - 每个节点必须有唯一的 `key`
+   - 叶子节点必须有 `value`
+   - 0 值会被自动过滤
+
+2. **性能优化**：
+   - 自动去重和合并相同 key 的数据
+   - 建议数据量不超过 100 个节点（包括所有层级）
+
+3. **跨端支持**：
+   - Web 端：完整功能
+   - React Native：目前提供降级提示，后续版本支持
+
+4. **颜色生成**：
+   - 建议为主要分类提供 `baseColors` mapping
+   - 子类渐变色会自动生成，保证同色系且可辨识
+
+## 类型定义
+
+完整的 TypeScript 类型定义请参考：
+- `NestedPieChart.types.ts`
+
+## 工具函数
+
+组件提供了一系列工具函数，可单独导入使用：
+
+```tsx
+import {
+  isTreeData,
+  flatToTree,
+  cleanData,
+  generateColorShades,
+  generateColorMap,
+  processData,
+  buildLegendGroupData,
+  formatEuro,
+} from '@beppla/tapas-ui';
+```
+
+## 相关组件
+
+- `PieChart` - 基础饼图组件
+- `BarChart` - 柱状图组件
+- `LineChart` - 折线图组件
+- `ComboChart` - 组合图组件