@beppla/tapas-ui 1.4.8 → 1.4.10

package/commonjs/StatisticsTable/README.md

@@ -265,6 +265,81 @@ For tables with hundreds or thousands of rows, enable virtual scrolling for opti
 />
 ```
 
+## Sortable Columns
+
+Add sorting functionality to column headers with built-in or custom rendering:
+
+### Built-in Sorting UI
+
+```tsx
+import { StatisticsTable } from '@beppla/tapas-ui';
+
+function SortableTable() {
+  const [sortConfig, setSortConfig] = useState<{
+    column: string | null;
+    direction: 'asc' | 'desc' | null;
+  }>({ 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,
+    },
+  ];
+
+  return <StatisticsTable rows={rows} columns={columns} cells={cells} />;
+}
+```
+
+### Custom Header Rendering
+
+For complete control over header appearance:
+
+```tsx
+const columns = [
+  {
+    key: 'store1',
+    title: 'Store A',
+    width: 180,
+    renderHeader: (column) => (
+      <TouchableOpacity 
+        onPress={() => handleSort(column.key)}
+        style={{ flexDirection: 'row', alignItems: 'center', gap: 4 }}
+      >
+        <Text style={{ fontSize: 14, fontWeight: '600' }}>
+          {column.title}
+        </Text>
+        <View>
+          <Icon name="arrow-up" size={10} color={sortDirection === 'asc' ? '#000' : '#ccc'} />
+          <Icon name="arrow-down" size={10} color={sortDirection === 'desc' ? '#000' : '#ccc'} />
+        </View>
+      </TouchableOpacity>
+    ),
+  },
+];
+```
+
 ## Internationalization (i18n)
 
 Customize loading and empty state texts for different languages:

package/commonjs/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/commonjs/StatisticsTable/StatisticsTable.js

@@ -227,11 +227,11 @@ function StatisticsTable({
     },
     // Hover 行
     rowHovered: {
-      backgroundColor: colors.colorSurface1 // 白色
+      backgroundColor: colors.colorSurface8 // rgba(0, 0, 0, 0.04) - 更柔和
     },
-    // Hover 单元格 - rgba(0, 0, 0, 0.08)
+    // Hover 单元格
     cellHovered: {
-      backgroundColor: 'rgba(0, 0, 0, 0.08)'
+      backgroundColor: colors.colorSurface8 // rgba(0, 0, 0, 0.04) - 更柔和
     },
     // Column Stats 行（Sum/Mean）- 纯白色背景
     columnStatsRow: {
@@ -673,6 +673,20 @@ function StatisticsTable({
           onScroll: handleScroll,
           scrollEventThrottle: 16,
           style: hideScrollbarStyle,
+          onContentSizeChange: () => {
+            // 当内容大小变化时，检查是否需要显示滚动阴影
+            if (scrollViewRef.current && enableScrollShadow) {
+              // React Native 会在 contentSize 变化后自动触发 onScroll
+              // 但为了确保状态正确，我们手动触发一次
+              setTimeout(() => {
+                scrollViewRef.current?.scrollTo?.({
+                  x: 0,
+                  y: 0,
+                  animated: false
+                });
+              }, 0);
+            }
+          },
           children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
             children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
               style: [styles.header, themedStyles.header],
@@ -685,14 +699,44 @@ function StatisticsTable({
                 })
               }), displayColumns.map(column => {
                 const colWidth = getColWidth(column);
-                return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+                const isPlaceholder = column.key.startsWith('_placeholder_col_');
+
+                // 如果提供了自定义 header 渲染函数
+                if (column.renderHeader && !isPlaceholder) {
+                  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+                    style: [styles.headerCell, themedStyles.headerCell, {
+                      width: colWidth
+                    }],
+                    children: column.renderHeader(column)
+                  }, column.key);
+                }
+
+                // 默认渲染（带排序支持）
+                const isSortable = column.sortable && column.onSort;
+                const HeaderContent = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+                  style: styles.headerContent,
+                  children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                    style: [styles.headerText, themedStyles.headerText],
+                    children: column.title
+                  }), isSortable && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+                    style: styles.sortIndicator,
+                    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                      style: [styles.sortArrow, column.sortDirection === 'asc' && styles.sortArrowActive],
+                      children: "\u25B2"
+                    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+                      style: [styles.sortArrow, column.sortDirection === 'desc' && styles.sortArrowActive],
+                      children: "\u25BC"
+                    })]
+                  })]
+                });
+                return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
                   style: [styles.headerCell, themedStyles.headerCell, {
                     width: colWidth
                   }],
-                  children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-                    style: [styles.headerText, themedStyles.headerText],
-                    children: column.title
-                  })
+                  onPress: isSortable ? () => column.onSort(column.key) : undefined,
+                  activeOpacity: isSortable ? 0.7 : 1,
+                  disabled: !isSortable,
+                  children: HeaderContent
                 }, column.key);
               })]
             }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.ScrollView, {
@@ -1019,6 +1063,24 @@ const styles = _reactNative.StyleSheet.create({
     fontWeight: '500',
     textAlign: 'center'
   },
+  headerContent: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 6
+  },
+  sortIndicator: {
+    flexDirection: 'column',
+    gap: 2
+  },
+  sortArrow: {
+    fontSize: 8,
+    color: 'rgba(0, 0, 0, 0.26)',
+    lineHeight: 8
+  },
+  sortArrowActive: {
+    color: 'rgba(0, 0, 0, 0.87)'
+  },
   row: {
     flexDirection: 'row',
     borderBottomWidth: 1