@beppla/tapas-ui 1.4.32 → 1.4.34

package/components/PieChart/NestedPieChart.types.ts

@@ -0,0 +1,171 @@
+/**
+ * NestedPieChart 类型定义
+ * 支持多层级饼图数据结构
+ */
+
+// 树形数据结构（推荐）
+export interface NestedPieChartNode {
+  key: string | number; // 唯一标识
+  label: string; // 显示文本
+  value?: number; // 叶子节点必须有 value，分支节点可选（自动汇总）
+  color?: string; // 自定义颜色（优先级高于自动配色）
+  children?: NestedPieChartNode[]; // 子节点
+  metadata?: Record<string, any>; // 额外元数据（用于 tooltip 等）
+}
+
+// 扁平数据结构（备选）
+export interface NestedPieChartFlatData {
+  key: string | number;
+  label: string;
+  value: number;
+  groupKey: string | number; // 所属分组的 key
+  groupLabel: string; // 所属分组的名称
+  color?: string;
+  metadata?: Record<string, any>;
+}
+
+// 图例模式
+export type LegendMode = 'flat' | 'grouped';
+
+// 图例显示内容
+export type LegendContent = 'all' | 'parent-only' | 'children-only';
+
+// 图例排序策略
+export type LegendSortStrategy = 
+  | 'none' // 保持原始顺序
+  | 'value-desc' // 按值降序
+  | 'value-asc' // 按值升序
+  | 'label-asc' // 按标签升序
+  | 'label-desc'; // 按标签降序
+
+// 配色策略
+export interface ColorStrategy {
+  baseColors?: Record<string, string>; // 大类基色 mapping，key 为分组 key
+  autoGenerate?: boolean; // 是否自动生成子类渐变色
+  colorSteps?: number; // 渐变色阶数
+  minColorDiff?: number; // 相邻颜色最小色差（0-1）
+}
+
+// 格式化函数
+export type ValueFormatter = (value: number) => string;
+export type PercentFormatter = (percent: number) => string;
+
+// 交互事件
+export interface SliceClickEvent {
+  key: string | number;
+  label: string;
+  value: number;
+  level: number; // 层级：0 为根，1 为第一层子节点
+  path: Array<string | number>; // 从根到当前节点的 key 路径
+  parentKey?: string | number;
+  metadata?: Record<string, any>;
+}
+
+export interface LegendClickEvent extends SliceClickEvent {
+  groupKey?: string | number;
+  isGroupHeader?: boolean; // 是否点击的是分组标题
+}
+
+// 主组件 Props
+export interface NestedPieChartProps {
+  // 数据
+  data: NestedPieChartNode[] | NestedPieChartFlatData[];
+  dataType?: 'tree' | 'flat'; // 数据类型，默认根据数据结构自动推断
+  
+  // 层级配置
+  levels?: number; // 显示层数，默认自动计算（最多支持的层数）
+  
+  // 尺寸
+  width?: number;
+  height?: number;
+  
+  // 半径配置（支持数字或百分比）
+  outerRadius?: number | string;
+  innerRadius?: number | string; // 最内层半径（形成 donut）
+  radiusGap?: number; // 层与层之间的间隔，默认 10
+  
+  // 配色
+  colorStrategy?: ColorStrategy;
+  colors?: string[]; // 默认配色数组（当 baseColors 未提供时使用）
+  
+  // 图例
+  showLegend?: boolean;
+  legendMode?: LegendMode;
+  legendPosition?: 'top' | 'bottom' | 'left' | 'right';
+  legendContent?: LegendContent;
+  legendCollapsible?: boolean; // 是否可折叠
+  legendDefaultExpanded?: boolean; // 默认展开状态
+  legendSortStrategy?: LegendSortStrategy;
+  legendGroupSortStrategy?: LegendSortStrategy; // 分组排序策略
+  legendShowValues?: boolean;
+  legendShowPercent?: boolean;
+  legendItemGap?: number;
+  legendGroupGap?: number; // 分组之间的间距
+  legendLabelMinWidth?: number;
+  legendChartGap?: number;
+  
+  // 标签
+  showLabels?: boolean; // 是否在扇区上显示标签
+  labelLevel?: 'all' | number; // 显示哪一层的标签，'all' 或层级数字
+  
+  // 格式化
+  formatValue?: ValueFormatter;
+  formatPercent?: PercentFormatter;
+  
+  // 交互
+  onSliceClick?: (event: SliceClickEvent) => void;
+  onSliceHover?: (event: SliceClickEvent | null) => void;
+  onLegendClick?: (event: LegendClickEvent) => void;
+  enableLegendFilter?: boolean; // 点击 legend 可隐藏/显示对应扇区
+  
+  // Tooltip
+  showTooltip?: boolean;
+  customTooltip?: (event: SliceClickEvent) => React.ReactNode;
+  
+  // 间隔
+  padAngle?: number; // 扇区间隔角度
+  
+  // 中心文本
+  centerText?: string;
+  centerTextStyle?: React.CSSProperties;
+  
+  // 空数据
+  emptyText?: string;
+  
+  // 样式
+  style?: any;
+  testID?: string;
+}
+
+// 内部处理后的数据结构
+export interface ProcessedSliceData {
+  key: string | number;
+  label: string;
+  value: number;
+  percent: number; // 占总体的百分比
+  color: string;
+  level: number;
+  parentKey?: string | number;
+  path: Array<string | number>;
+  children?: ProcessedSliceData[];
+  metadata?: Record<string, any>;
+}
+
+// 图例分组数据结构
+export interface LegendGroupData {
+  groupKey: string | number;
+  groupLabel: string;
+  groupValue: number;
+  groupPercent: number;
+  groupColor: string;
+  items: Array<{
+    key: string | number;
+    label: string;
+    value: number;
+    percent: number;
+    color: string;
+    metadata?: Record<string, any>;
+  }>;
+  isExpanded: boolean;
+  metadata?: Record<string, any>;
+}

package/components/PieChart/NestedPieChart.utils.ts

@@ -0,0 +1,425 @@
+/**
+ * NestedPieChart 工具函数
+ * 数据处理、配色生成、格式化等
+ */
+
+import {
+  NestedPieChartNode,
+  NestedPieChartFlatData,
+  ProcessedSliceData,
+  LegendGroupData,
+  ColorStrategy,
+  LegendSortStrategy,
+} from './NestedPieChart.types';
+
+/**
+ * 判断是否为树形数据
+ */
+export function isTreeData(
+  data: NestedPieChartNode[] | NestedPieChartFlatData[]
+): data is NestedPieChartNode[] {
+  if (!data || data.length === 0) return false;
+  const firstItem = data[0];
+  if (!firstItem) return false;
+  return 'children' in firstItem || !('groupKey' in firstItem);
+}
+
+/**
+ * 将扁平数据转换为树形数据
+ */
+export function flatToTree(
+  flatData: NestedPieChartFlatData[]
+): NestedPieChartNode[] {
+  const groupMap = new Map<string | number, NestedPieChartNode>();
+  
+  flatData.forEach(item => {
+    if (!groupMap.has(item.groupKey)) {
+      groupMap.set(item.groupKey, {
+        key: item.groupKey,
+        label: item.groupLabel,
+        children: [],
+        metadata: {},
+      });
+    }
+    
+    const group = groupMap.get(item.groupKey)!;
+    group.children!.push({
+      key: item.key,
+      label: item.label,
+      value: item.value,
+      color: item.color,
+      metadata: item.metadata,
+    });
+  });
+  
+  return Array.from(groupMap.values());
+}
+
+/**
+ * 过滤0值并去重合并
+ */
+export function cleanData(
+  data: NestedPieChartNode[]
+): NestedPieChartNode[] {
+  const keyMap = new Map<string | number, NestedPieChartNode>();
+  
+  data.forEach(node => {
+    // 递归处理子节点
+    const cleanedChildren = node.children
+      ? cleanData(node.children)
+      : undefined;
+    
+    // 计算节点值（如果有子节点则汇总）
+    const nodeValue = cleanedChildren && cleanedChildren.length > 0
+      ? cleanedChildren.reduce((sum, child) => sum + (child.value || 0), 0)
+      : node.value || 0;
+    
+    // 过滤0值
+    if (nodeValue === 0) return;
+    
+    // 去重合并
+    if (keyMap.has(node.key)) {
+      const existing = keyMap.get(node.key)!;
+      existing.value = (existing.value || 0) + nodeValue;
+      if (cleanedChildren) {
+        existing.children = [
+          ...(existing.children || []),
+          ...cleanedChildren,
+        ];
+      }
+    } else {
+      keyMap.set(node.key, {
+        ...node,
+        value: nodeValue,
+        children: cleanedChildren,
+      });
+    }
+  });
+  
+  return Array.from(keyMap.values());
+}
+
+/**
+ * 颜色工具：RGB <-> HSL 转换
+ */
+function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+  r /= 255;
+  g /= 255;
+  b /= 255;
+  
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h = 0, s = 0;
+  const l = (max + min) / 2;
+  
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    
+    switch (max) {
+      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+      case g: h = ((b - r) / d + 2) / 6; break;
+      case b: h = ((r - g) / d + 4) / 6; break;
+    }
+  }
+  
+  return [h * 360, s * 100, l * 100];
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  h /= 360;
+  s /= 100;
+  l /= 100;
+  
+  let r, g, b;
+  
+  if (s === 0) {
+    r = g = b = l;
+  } else {
+    const hue2rgb = (p: number, q: number, t: number) => {
+      if (t < 0) t += 1;
+      if (t > 1) t -= 1;
+      if (t < 1/6) return p + (q - p) * 6 * t;
+      if (t < 1/2) return q;
+      if (t < 2/3) return p + (q - p) * (2/3 - t) * 6;
+      return p;
+    };
+    
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    
+    r = hue2rgb(p, q, h + 1/3);
+    g = hue2rgb(p, q, h);
+    b = hue2rgb(p, q, h - 1/3);
+  }
+  
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result && result[1] && result[2] && result[3]
+    ? [
+        parseInt(result[1], 16),
+        parseInt(result[2], 16),
+        parseInt(result[3], 16),
+      ]
+    : [0, 0, 0];
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + [r, g, b]
+    .map(x => {
+      const hex = x.toString(16);
+      return hex.length === 1 ? '0' + hex : hex;
+    })
+    .join('');
+}
+
+/**
+ * 生成渐变色系列（同色系，明度/饱和度渐变）
+ */
+export function generateColorShades(
+  baseColor: string,
+  count: number,
+  _minColorDiff: number = 0.1
+): string[] {
+  if (count <= 1) return [baseColor];
+  
+  const [r, g, b] = hexToRgb(baseColor);
+  const [h, s, l] = rgbToHsl(r, g, b);
+  
+  const colors: string[] = [];
+  
+  // 策略：固定色相，调整饱和度和明度
+  // 为避免颜色过淡或过深，限制明度范围
+  const minL = Math.max(30, l - 25);
+  const maxL = Math.min(85, l + 25);
+  const lStep = (maxL - minL) / (count - 1);
+  
+  // 同时调整饱和度，避免灰蒙蒙
+  const minS = Math.max(40, s - 20);
+  const maxS = Math.min(100, s + 20);
+  const sStep = (maxS - minS) / (count - 1);
+  
+  for (let i = 0; i < count; i++) {
+    const newL = minL + lStep * i;
+    const newS = minS + sStep * (count - 1 - i); // 反向：越深饱和度越高
+    const [newR, newG, newB] = hslToRgb(h, newS, newL);
+    colors.push(rgbToHex(newR, newG, newB));
+  }
+  
+  return colors;
+}
+
+/**
+ * 生成配色方案
+ */
+export function generateColorMap(
+  data: NestedPieChartNode[],
+  strategy: ColorStrategy,
+  defaultColors: string[]
+): Map<string | number, string> {
+  const colorMap = new Map<string | number, string>();
+  const baseColors = strategy.baseColors || {};
+  
+  data.forEach((node, index) => {
+    // 大类颜色
+    const baseColor = baseColors[node.key] || node.color || defaultColors[index % defaultColors.length];
+    if (baseColor) {
+      colorMap.set(node.key, baseColor);
+    }
+    
+    // 子类渐变色
+    if (node.children && node.children.length > 0 && strategy.autoGenerate !== false && baseColor) {
+      const childrenColors = generateColorShades(
+        baseColor,
+        node.children.length,
+        strategy.minColorDiff
+      );
+      
+      node.children.forEach((child, childIndex) => {
+        if (!child.color) {
+          const childColor = childrenColors[childIndex];
+          if (childColor) {
+            colorMap.set(child.key, childColor);
+          }
+        } else {
+          colorMap.set(child.key, child.color);
+        }
+      });
+    }
+  });
+  
+  return colorMap;
+}
+
+/**
+ * 处理数据：计算值、百分比、路径等
+ */
+export function processData(
+  data: NestedPieChartNode[],
+  colorMap: Map<string | number, string>,
+  parentKey?: string | number,
+  parentPath: Array<string | number> = [],
+  level: number = 0
+): { processed: ProcessedSliceData[]; total: number } {
+  let total = 0;
+  const processed: ProcessedSliceData[] = [];
+  
+  data.forEach(node => {
+    const path = [...parentPath, node.key];
+    const nodeValue = node.value || 0;
+    
+    // 递归处理子节点
+    let childrenProcessed: ProcessedSliceData[] = [];
+    let childrenTotal = 0;
+    
+    if (node.children && node.children.length > 0) {
+      const result = processData(node.children, colorMap, node.key, path, level + 1);
+      childrenProcessed = result.processed;
+      childrenTotal = result.total;
+    }
+    
+    // 如果有子节点，使用子节点汇总值；否则使用自身值
+    const finalValue = childrenTotal > 0 ? childrenTotal : nodeValue;
+    
+    if (finalValue > 0) {
+      processed.push({
+        key: node.key,
+        label: node.label,
+        value: finalValue,
+        percent: 0, // 稍后计算
+        color: colorMap.get(node.key) || '#999',
+        level,
+        parentKey,
+        path,
+        children: childrenProcessed.length > 0 ? childrenProcessed : undefined,
+        metadata: node.metadata,
+      });
+      
+      total += finalValue;
+    }
+  });
+  
+  // 计算百分比
+  processed.forEach(item => {
+    item.percent = total > 0 ? (item.value / total) * 100 : 0;
+    if (item.children) {
+      const childTotal = item.children.reduce((sum, child) => sum + child.value, 0);
+      item.children.forEach(child => {
+        child.percent = childTotal > 0 ? (child.value / childTotal) * 100 : 0;
+      });
+    }
+  });
+  
+  return { processed, total };
+}
+
+/**
+ * 排序函数 - 图例项
+ */
+export function sortLegendItems<T extends { label: string; value: number }>(
+  data: T[],
+  strategy: LegendSortStrategy
+): T[] {
+  const sorted = [...data];
+  
+  switch (strategy) {
+    case 'value-desc':
+      return sorted.sort((a, b) => b.value - a.value);
+    case 'value-asc':
+      return sorted.sort((a, b) => a.value - b.value);
+    case 'label-asc':
+      return sorted.sort((a, b) => a.label.localeCompare(b.label));
+    case 'label-desc':
+      return sorted.sort((a, b) => b.label.localeCompare(a.label));
+    default:
+      return sorted;
+  }
+}
+
+/**
+ * 排序函数 - 图例分组
+ */
+export function sortLegendGroups(
+  data: LegendGroupData[],
+  strategy: LegendSortStrategy
+): LegendGroupData[] {
+  const sorted = [...data];
+  
+  switch (strategy) {
+    case 'value-desc':
+      return sorted.sort((a, b) => b.groupValue - a.groupValue);
+    case 'value-asc':
+      return sorted.sort((a, b) => a.groupValue - b.groupValue);
+    case 'label-asc':
+      return sorted.sort((a, b) => a.groupLabel.localeCompare(b.groupLabel));
+    case 'label-desc':
+      return sorted.sort((a, b) => b.groupLabel.localeCompare(a.groupLabel));
+    default:
+      return sorted;
+  }
+}
+
+/**
+ * 构建分组图例数据
+ */
+export function buildLegendGroupData(
+  processed: ProcessedSliceData[],
+  groupSortStrategy: LegendSortStrategy = 'none',
+  itemSortStrategy: LegendSortStrategy = 'none',
+  defaultExpanded: boolean = true
+): LegendGroupData[] {
+  const groups = processed.map(parent => {
+    const items = parent.children
+      ? parent.children.map(child => ({
+          key: child.key,
+          label: child.label,
+          value: child.value,
+          percent: child.percent,
+          color: child.color,
+          metadata: child.metadata,
+        }))
+      : [];
+    
+    const sortedItems = sortLegendItems(items, itemSortStrategy);
+    
+    return {
+      groupKey: parent.key,
+      groupLabel: parent.label,
+      groupValue: parent.value,
+      groupPercent: parent.percent,
+      groupColor: parent.color,
+      items: sortedItems,
+      isExpanded: defaultExpanded,
+      metadata: parent.metadata,
+    };
+  });
+  
+  return sortLegendGroups(groups, groupSortStrategy);
+}
+
+/**
+ * 默认格式化函数
+ */
+export const defaultFormatValue = (value: number): string => {
+  return new Intl.NumberFormat('en-US', {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(value);
+};
+
+export const defaultFormatPercent = (percent: number): string => {
+  return `${percent.toFixed(1)}%`;
+};
+
+/**
+ * 默认货币格式化（欧元）
+ */
+export const formatEuro = (value: number): string => {
+  return new Intl.NumberFormat('de-DE', {
+    style: 'currency',
+    currency: 'EUR',
+  }).format(value);
+};