@beppla/tapas-ui 1.5.13 → 1.5.15

package/package/module/StatisticsTable/SORTING_FEATURE.md

@@ -0,0 +1,271 @@
+# StatisticsTable 排序功能
+
+## 概述
+
+StatisticsTable 组件支持两种方式实现列排序：
+1. **内置排序 UI**：使用 `sortable`, `sortDirection`, `onSort` 属性
+2. **完全自定义**：使用 `renderHeader` 属性完全控制表头渲染
+
+## 方式一：内置排序 UI
+
+### 功能特性
+
+- ✅ 内置排序指示器（▲▼箭头）
+- ✅ 自动高亮当前排序方向
+- ✅ 点击表头切换排序
+- ✅ 主题颜色自适应
+
+### 使用示例
+
+```tsx
+import React, { useState } from 'react';
+import { StatisticsTable } from '@beppla/tapas-ui';
+
+function SortableTable() {
+  const [sortConfig, setSortConfig] = useState({
+    column: null,
+    direction: null,
+  });
+
+  const handleSort = (columnKey: string) => {
+    setSortConfig(prev => ({
+      column: columnKey,
+      direction: prev.column === columnKey && prev.direction === 'asc' 
+        ? 'desc' 
+        : 'asc'
+    }));
+  };
+
+  const columns = [
+    { 
+      key: 'store1', 
+      title: 'Store A (€)', 
+      width: 180,
+      sortable: true,  // 启用排序
+      sortDirection: sortConfig.column === 'store1' ? sortConfig.direction : null,
+      onSort: handleSort,
+    },
+    { 
+      key: 'store2', 
+      title: 'Store B (€)', 
+      width: 180,
+      sortable: true,
+      sortDirection: sortConfig.column === 'store2' ? sortConfig.direction : null,
+      onSort: handleSort,
+    },
+  ];
+
+  // 对数据进行排序
+  let sortedRows = [...rows];
+  if (sortConfig.column && sortConfig.direction) {
+    sortedRows = sortedRows.sort((a, b) => {
+      const cellA = cells.find(c => c.rowKey === a.key && c.columnKey === sortConfig.column);
+      const cellB = cells.find(c => c.rowKey === b.key && c.columnKey === sortConfig.column);
+      const valueA = cellA?.amount || 0;
+      const valueB = cellB?.amount || 0;
+      return sortConfig.direction === 'asc' ? valueA - valueB : valueB - valueA;
+    });
+  }
+
+  return (
+    <StatisticsTable 
+      rows={sortedRows} 
+      columns={columns} 
+      cells={cells} 
+    />
+  );
+}
+```
+
+### 内置 UI 说明
+
+**排序指示器：**
+- 两个箭头：▲ 升序，▼ 降序
+- 未激活：浅灰色 `rgba(0, 0, 0, 0.26)`
+- 激活时：深色 `rgba(0, 0, 0, 0.87)`
+
+**点击行为：**
+- 第一次点击：升序（▲ 高亮）
+- 第二次点击：降序（▼ 高亮）
+- 第三次点击：取消排序（视具体实现）
+
+## 方式二：完全自定义 Header
+
+### 使用 renderHeader
+
+```tsx
+const columns = [
+  {
+    key: 'store1',
+    title: 'Store A (€)',
+    width: 200,
+    renderHeader: (column) => (
+      <TouchableOpacity 
+        onPress={() => handleCustomSort(column.key)}
+        style={{ 
+          flexDirection: 'row', 
+          alignItems: 'center', 
+          gap: 8,
+          padding: 4,
+        }}
+      >
+        <Text style={{ 
+          fontSize: 14, 
+          fontWeight: '600',
+          color: '#333',
+        }}>
+          {column.title}
+        </Text>
+        
+        {/* 自定义排序图标 */}
+        <View style={{ flexDirection: 'column', gap: 2 }}>
+          <TapasIcon 
+            name="caret-up" 
+            size={10} 
+            color={currentSort.column === column.key && currentSort.dir === 'asc' 
+              ? '#895F38'  // 品牌色
+              : '#CCC'     // 灰色
+            } 
+          />
+          <TapasIcon 
+            name="caret-down" 
+            size={10} 
+            color={currentSort.column === column.key && currentSort.dir === 'desc' 
+              ? '#895F38' 
+              : '#CCC'
+            } 
+          />
+        </View>
+      </TouchableOpacity>
+    ),
+  },
+];
+```
+
+### 自定义样式示例
+
+```tsx
+renderHeader: (column) => (
+  <View style={{ 
+    flexDirection: 'row', 
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    width: '100%',
+  }}>
+    <Text style={{ fontSize: 14, fontWeight: '700' }}>
+      {column.title}
+    </Text>
+    
+    {/* 自定义徽章 */}
+    {column.key === 'total' && (
+      <View style={{ 
+        backgroundColor: '#F55523', 
+        borderRadius: 12, 
+        paddingHorizontal: 6,
+        paddingVertical: 2,
+      }}>
+        <Text style={{ fontSize: 10, color: '#FFF' }}>Total</Text>
+      </View>
+    )}
+    
+    {/* 排序按钮 */}
+    <SortButton active={isSorted} direction={direction} />
+  </View>
+)
+```
+
+## 新增属性
+
+### StatisticsTableColumn
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `sortable` | `boolean` | 是否可排序（启用内置排序 UI） |
+| `sortDirection` | `'asc' \| 'desc' \| null` | 当前排序方向 |
+| `onSort` | `(columnKey: string) => void` | 排序回调函数 |
+| `renderHeader` | `(column) => ReactNode` | 完全自定义表头渲染 |
+
+## 实现细节
+
+### 内置排序渲染逻辑
+
+```typescript
+// 默认渲染（带排序支持）
+const isSortable = column.sortable && column.onSort;
+
+const HeaderContent = (
+  <View style={styles.headerContent}>
+    <Text style={styles.headerText}>
+      {column.title}
+    </Text>
+    {isSortable && (
+      <View style={styles.sortIndicator}>
+        <Text style={[
+          styles.sortArrow, 
+          column.sortDirection === 'asc' && styles.sortArrowActive
+        ]}>▲</Text>
+        <Text style={[
+          styles.sortArrow, 
+          column.sortDirection === 'desc' && styles.sortArrowActive
+        ]}>▼</Text>
+      </View>
+    )}
+  </View>
+);
+
+return (
+  <TouchableOpacity
+    onPress={isSortable ? () => column.onSort!(column.key) : undefined}
+    activeOpacity={isSortable ? 0.7 : 1}
+    disabled={!isSortable}
+  >
+    {HeaderContent}
+  </TouchableOpacity>
+);
+```
+
+### 优先级
+
+1. 如果提供了 `renderHeader`：使用完全自定义渲染
+2. 如果设置了 `sortable` 和 `onSort`：使用内置排序 UI
+3. 否则：显示普通文本标题
+
+## 使用建议
+
+### 何时使用内置排序 UI？
+
+✅ **推荐使用：**
+- 简单的表格排序需求
+- 想要快速实现排序功能
+- 满意内置的箭头样式
+- 不需要特殊的排序图标
+
+### 何时使用自定义 renderHeader？
+
+✅ **推荐使用：**
+- 需要特定的排序图标或样式
+- 表头需要额外的元素（徽章、图标、提示等）
+- 需要完全控制表头布局
+- 需要与设计系统保持一致
+
+## 注意事项
+
+1. **数据排序逻辑**：组件本身不处理数据排序，需要用户自己实现排序逻辑
+2. **状态管理**：排序状态需要用户管理（使用 useState）
+3. **性能**：对于大数据集，建议配合虚拟滚动使用
+4. **占位列**：占位列会自动跳过排序功能
+
+## Storybook 示例
+
+- `SortableColumns` - 内置排序 UI 演示
+- `CustomHeaderRendering` - 完全自定义表头演示
+
+## 相关更新
+
+- ✅ StatisticsTableColumn 接口添加排序相关属性
+- ✅ 表头支持点击事件
+- ✅ 内置排序指示器样式
+- ✅ 完整的自定义渲染支持
+- ✅ 2 个 Storybook 示例
+- ✅ 2 个测试用例
+

package/package/module/StatisticsTable/STATS_CELL_CLICK.md

@@ -0,0 +1,120 @@
+# StatisticsTable Stats Cell Click 功能
+
+## 概述
+
+StatisticsTable 组件现在支持 Row Stats 和 Column Stats 单元格的点击事件。
+
+## 新增属性
+
+### `onRowStatsCellClick`
+
+Row Stats 单元格点击事件回调。
+
+```typescript
+onRowStatsCellClick?: (
+  rowKey: string,
+  statsType: 'sum' | 'mean',
+  stats: {
+    sumQuantity: number;
+    sumAmount: number;
+    meanQuantity: number;
+    meanAmount: number;
+  }
+) => void;
+```
+
+**参数说明：**
+- `rowKey`: 被点击行的 key
+- `statsType`: 统计类型，'sum' 表示合计列，'mean' 表示平均列
+- `stats`: 该行的统计数据对象
+
+### `onColumnStatsCellClick`
+
+Column Stats 单元格点击事件回调。
+
+```typescript
+onColumnStatsCellClick?: (
+  columnKey: string,
+  statsType: 'sum' | 'mean',
+  stats: {
+    sumQuantity: number;
+    sumAmount: number;
+    meanQuantity: number;
+    meanAmount: number;
+  },
+  column: StatisticsTableColumn
+) => void;
+```
+
+**参数说明：**
+- `columnKey`: 被点击列的 key
+- `statsType`: 统计类型，'sum' 表示合计行，'mean' 表示平均行
+- `stats`: 该列的统计数据对象
+- `column`: 列配置对象
+
+## 使用示例
+
+### Row Stats 点击示例
+
+```typescript
+import { StatisticsTable } from '@beppla/tapas-ui';
+
+const MyComponent = () => {
+  const handleRowStatsCellClick = (rowKey, statsType, stats) => {
+    console.log(`点击了 ${rowKey} 的 ${statsType} 统计`, stats);
+    // 执行自定义逻辑，如打开详情弹窗、导航等
+  };
+
+  return (
+    <StatisticsTable
+      rows={rows}
+      columns={columns}
+      cells={cells}
+      showRowStats={true}
+      onRowStatsCellClick={handleRowStatsCellClick}
+    />
+  );
+};
+```
+
+### Column Stats 点击示例
+
+```typescript
+import { StatisticsTable } from '@beppla/tapas-ui';
+
+const MyComponent = () => {
+  const handleColumnStatsCellClick = (columnKey, statsType, stats, column) => {
+    console.log(`点击了 ${column.title} 的 ${statsType} 统计`, stats);
+    // 执行自定义逻辑
+  };
+
+  return (
+    <StatisticsTable
+      rows={rows}
+      columns={columns}
+      cells={cells}
+      showColumnStats={true}
+      onColumnStatsCellClick={handleColumnStatsCellClick}
+    />
+  );
+};
+```
+
+## 功能特性
+
+1. **视觉反馈**：点击时有 opacity 过渡效果（activeOpacity: 0.7）
+2. **Hover 支持**：保留了原有的 hover 悬停提示功能
+3. **可选性**：不传递回调时单元格不可点击
+4. **完整数据**：回调提供完整的统计数据和上下文信息
+
+## Storybook 示例
+
+在 Storybook 中查看交互式示例：
+- `RowStatsCellClick` - Row Stats 单元格点击示例
+- `ColumnStatsCellClick` - Column Stats 单元格点击示例
+
+## 注意事项
+
+- Row Stats 和 Column Stats 是互斥的，同时只能显示一个
+- 点击事件仅在提供相应回调函数时才会生效
+- 单元格的 hover 提示功能与点击事件可以共存