@beppla/tapas-ui 1.4.35 → 1.5.0

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

@@ -1,421 +0,0 @@
-# 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` - 组合图组件

package/package/module/Quantity/README.md

@@ -1,251 +0,0 @@
-# TapasQuantity
-
-一个简洁高效的数量选择器组件，支持增减操作、范围限制和自定义步长。
-
-## 功能特性
-
-- ✅ 数量增减：支持增加和减少操作
-- ✅ 范围限制：支持最大值和最小值设置
-- ✅ 自定义步长：支持自定义每次增减的数量
-- ✅ 状态管理：支持禁用状态和边界状态
-- ✅ 边界提示：可选的数值范围提示
-- ✅ 自定义样式：支持按钮大小和样式自定义
-- ✅ 响应式设计：适配不同屏幕尺寸
-- ✅ 无障碍支持：完整的可访问性支持
-
-## 安装使用
-
-```tsx
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-// 基础用法
-<TapasQuantity
-  value={5}
-  onChange={(value) => console.log('数量:', value)}
-/>
-```
-
-## Props
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `value` | `number` | - | 当前数量值（必填） |
-| `onChange` | `(value: number) => void` | - | 数量变化回调 |
-| `min` | `number` | `0` | 最小值 |
-| `max` | `number` | `99999` | 最大值 |
-| `step` | `number` | `1` | 每次增减的步长 |
-| `disabled` | `boolean` | `false` | 是否禁用 |
-| `showValue` | `boolean` | `true` | 是否显示当前值 |
-| `showBoundaryHint` | `boolean` | `false` | 是否显示边界提示 |
-| `buttonSize` | `number` | `32` | 增减按钮的大小 |
-| `style` | `ViewStyle` | - | 容器样式 |
-| `buttonStyle` | `ViewStyle` | - | 按钮样式 |
-| `valueStyle` | `ViewStyle` | - | 值显示区域样式 |
-
-## 使用示例
-
-### 基础数量选择
-
-```tsx
-import React, { useState } from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const QuantityDemo = () => {
-  const [quantity, setQuantity] = useState(1);
-
-  const handleQuantityChange = (value: number) => {
-    setQuantity(value);
-    console.log('数量变化:', value);
-  };
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={handleQuantityChange}
-      min={1}
-      max={99}
-    />
-  );
-};
-```
-
-### 带范围提示的数量选择
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const RangeQuantityDemo = () => {
-  const [quantity, setQuantity] = useState(5);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      min={1}
-      max={10}
-      showBoundaryHint={true}
-    />
-  );
-};
-```
-
-### 自定义步长
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const StepQuantityDemo = () => {
-  const [quantity, setQuantity] = useState(10);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      min={0}
-      max={100}
-      step={5}
-      showBoundaryHint={true}
-    />
-  );
-};
-```
-
-### 禁用状态
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const DisabledQuantityDemo = () => {
-  return (
-    <TapasQuantity
-      value={5}
-      onChange={() => {}}
-      disabled={true}
-    />
-  );
-};
-```
-
-### 自定义按钮大小
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const CustomSizeQuantityDemo = () => {
-  const [quantity, setQuantity] = useState(5);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      buttonSize={40}
-      min={0}
-      max={10}
-    />
-  );
-};
-```
-
-### 隐藏数值显示
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const HiddenValueDemo = () => {
-  const [quantity, setQuantity] = useState(5);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      showValue={false}
-      min={0}
-      max={10}
-    />
-  );
-};
-```
-
-### 负数值范围
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const NegativeRangeDemo = () => {
-  const [quantity, setQuantity] = useState(0);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      min={-10}
-      max={10}
-      showBoundaryHint={true}
-    />
-  );
-};
-```
-
-### 小数步长
-
-```tsx
-import React from 'react';
-import { TapasQuantity } from '@beppla/tapas-ui';
-
-const DecimalStepDemo = () => {
-  const [quantity, setQuantity] = useState(0.5);
-
-  return (
-    <TapasQuantity
-      value={quantity}
-      onChange={setQuantity}
-      min={0}
-      max={1}
-      step={0.1}
-      showBoundaryHint={true}
-    />
-  );
-};
-```
-
-## 最佳实践
-
-1. **合理的范围设置**：根据业务需求设置合适的最大值和最小值
-2. **适当的步长**：根据实际使用场景选择合适的步长值
-3. **边界提示**：当范围较大或需要用户了解限制时，启用边界提示
-4. **禁用状态**：在数据加载或操作不可用时，使用禁用状态
-5. **回调处理**：在 onChange 回调中处理数量变化，避免直接修改状态
-
-## 使用场景
-
-- 商品数量选择
-- 表单数量输入
-- 购物车数量调整
-- 库存数量管理
-- 评分系统
-- 配置参数调整
-- 游戏数值设置
-- 数据筛选范围
-
-## 注意事项
-
-1. `value` 属性是必填的，必须提供初始值
-2. 当 `value` 超出 `min` 和 `max` 范围时，组件会自动调整到有效范围内
-3. `step` 值应该合理设置，避免过大的步长导致用户体验不佳
-4. 组件会自动处理边界情况，当达到最小值时减少按钮会被禁用，达到最大值时增加按钮会被禁用
-5. 支持 React Native 和 React Native Web 环境
-
-## 技术实现
-
-- 使用 `useState` 管理内部状态
-- 支持受控和非受控模式
-- 自动边界检查和约束
-- 响应式按钮状态管理
-- 完整的类型安全支持
-- 主题集成和样式自定义