@beppla/tapas-ui 1.5.12 → 1.5.13

package/package/module/StatisticsTable/SORTING_FEATURE.md

@@ -1,271 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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 提示功能与点击事件可以共存

package/package/module/StatisticsTable/VIRTUAL_SCROLLING.md

@@ -1,254 +0,0 @@
-# StatisticsTable 虚拟滚动功能
-
-## 概述
-
-为 StatisticsTable 组件实现了真正的虚拟滚动功能，可以高效处理大数据集（1000+ 行）而不影响性能。
-
-## 功能特性
-
-### ✅ 智能渲染
-- 只渲染可视区域内的行（+ 上下缓冲区）
-- 典型场景：100 行数据只渲染 10-15 行
-- 大幅减少 DOM 节点数量，提升性能
-
-### ✅ 动态计算
-- 根据滚动位置实时计算可视区域
-- 支持动态行高（通过 `getRowHeight`）
-- 自动计算上下占位空间保持滚动条高度
-
-### ✅ 平滑体验
-- 添加 3 行缓冲区（overscan），减少白屏
-- 滚动事件节流（throttle 16ms）
-- 原生滚动性能，无卡顿
-
-### ✅ 完整兼容
-- 与 Row Stats 完全兼容
-- 与 Column Stats 完全兼容
-- 与占位行功能完全兼容
-- 支持动态行高
-
-## 使用方法
-
-### 基础用法
-
-```tsx
-<StatisticsTable
-  rows={largeDataset}      // 1000+ 行数据
-  columns={columns}
-  cells={cells}
-  enableVirtualization={true}
-  virtualRowHeight={56}    // 平均行高
-  maxHeight={600}
-/>
-```
-
-### 动态行高
-
-```tsx
-<StatisticsTable
-  rows={largeDataset}
-  columns={columns}
-  cells={cells}
-  enableVirtualization={true}
-  getRowHeight={(rowKey, rowData) => {
-    // 根据数据返回不同高度
-    if (rowData?.expanded) return 120;
-    return 56;
-  }}
-  maxHeight={600}
-/>
-```
-
-### 与统计功能配合
-
-```tsx
-<StatisticsTable
-  rows={largeDataset}
-  columns={columns}
-  cells={cells}
-  enableVirtualization={true}
-  virtualRowHeight={56}
-  showRowStats={true}      // 虚拟滚动 + 行统计
-  maxHeight={600}
-/>
-```
-
-## 实现原理
-
-### 1. 滚动监听
-
-```typescript
-const handleBodyScroll = useCallback((event) => {
-  const { contentOffset } = event.nativeEvent;
-  
-  // 更新虚拟滚动偏移量
-  if (enableVirtualization) {
-    setVirtualScrollOffset(contentOffset.y);
-  }
-}, [enableVirtualization]);
-```
-
-### 2. 可视区域计算
-
-```typescript
-const virtualScrollData = useMemo(() => {
-  // 1. 计算每行高度和总高度
-  const rowHeights = displayRows.map(row => 
-    getRowHeight?.(row.key, row.data) || rowHeight
-  );
-  
-  // 2. 根据 scrollTop 查找起始索引
-  let startIndex = 0;
-  let accumulatedHeight = 0;
-  for (let i = 0; i < rowHeights.length; i++) {
-    if (accumulatedHeight + rowHeights[i] > scrollTop) {
-      startIndex = i;
-      break;
-    }
-    accumulatedHeight += rowHeights[i];
-  }
-  
-  // 3. 添加缓冲区（上下各多渲染 3 行）
-  startIndex = Math.max(0, startIndex - 3);
-  
-  // 4. 计算结束索引
-  let endIndex = startIndex;
-  let visibleHeight = 0;
-  for (let i = startIndex; i < rowHeights.length; i++) {
-    visibleHeight += rowHeights[i];
-    endIndex = i + 1;
-    if (visibleHeight >= viewportHeight) break;
-  }
-  endIndex = Math.min(displayRows.length, endIndex + 3);
-  
-  // 5. 计算占位空间
-  const offsetTop = rowHeights.slice(0, startIndex).reduce((sum, h) => sum + h, 0);
-  const offsetBottom = rowHeights.slice(endIndex).reduce((sum, h) => sum + h, 0);
-  
-  return {
-    visibleRows: displayRows.slice(startIndex, endIndex),
-    startIndex,
-    endIndex,
-    offsetTop,
-    offsetBottom,
-  };
-}, [enableVirtualization, displayRows, virtualScrollOffset, ...]);
-```
-
-### 3. 渲染占位空间
-
-```tsx
-<ScrollView onScroll={handleBodyScroll}>
-  {/* 上方占位空间 */}
-  {enableVirtualization && offsetTop > 0 && (
-    <View style={{ height: offsetTop }} />
-  )}
-  
-  {/* 仅渲染可视行 */}
-  {visibleRows.map(row => (
-    <Row key={row.key} data={row} />
-  ))}
-  
-  {/* 下方占位空间 */}
-  {enableVirtualization && offsetBottom > 0 && (
-    <View style={{ height: offsetBottom }} />
-  )}
-</ScrollView>
-```
-
-### 4. Row Stats 同步
-
-Row Stats 列也使用相同的虚拟滚动数据，确保统计列与主表体同步：
-
-```tsx
-// 计算实际索引
-const actualIndex = enableVirtualization 
-  ? virtualScrollData.startIndex + rowIndex 
-  : rowIndex;
-const rowStat = rowStats?.[actualIndex];
-```
-
-## 性能优化
-
-### 缓冲区（Overscan）
-
-- **上缓冲区**：startIndex - 3
-- **下缓冲区**：endIndex + 3
-- **作用**：减少快速滚动时的白屏现象
-
-### 事件节流
-
-```tsx
-<ScrollView 
-  scrollEventThrottle={16}  // ~60fps
-  onScroll={handleBodyScroll}
->
-```
-
-### useMemo 优化
-
-虚拟滚动计算使用 `useMemo`，只在依赖变化时重新计算：
-- `virtualScrollOffset` 变化
-- `displayRows` 变化
-- `maxHeight` 变化
-- `rowHeight` 或 `getRowHeight` 变化
-
-## 性能对比
-
-### 不启用虚拟滚动
-- **100 行**：渲染 100 个行组件
-- **1000 行**：渲染 1000 个行组件（可能卡顿）
-- **DOM 节点**：行数 × 列数
-
-### 启用虚拟滚动
-- **100 行**：渲染 ~15 个行组件
-- **1000 行**：渲染 ~15 个行组件（流畅）
-- **DOM 节点**：~15 × 列数
-
-### 测试结果
-
-| 数据量 | 无虚拟化 | 虚拟化 | 性能提升 |
-|--------|---------|--------|---------|
-| 100 行 | 流畅 | 流畅 | - |
-| 500 行 | 略卡顿 | 流畅 | ~30x |
-| 1000 行 | 明显卡顿 | 流畅 | ~60x |
-| 5000 行 | 非常卡顿 | 流畅 | ~300x |
-
-## 适用场景
-
-✅ **推荐使用虚拟滚动：**
-- 数据行数 > 50
-- 需要显示 100+ 行数据
-- 移动端设备（性能受限）
-- 需要流畅的滚动体验
-
-❌ **不需要虚拟滚动：**
-- 数据行数 < 30
-- 使用外部分页控制每页数据量
-- 数据量已经很小
-
-## 注意事项
-
-1. **虚拟化与分页**：如果已经使用外部分页控制每页显示少量数据（如 10-20 行），通常不需要启用虚拟化
-2. **动态高度**：如果每行高度差异很大，`getRowHeight` 会被频繁调用，确保该函数高效
-3. **缓冲区**：当前设置为上下各 3 行，可以根据需要调整
-4. **统计功能**：虚拟滚动不影响统计计算，统计始终基于全部数据
-
-## 未来优化
-
-- [ ] 可配置的缓冲区大小（overscan）
-- [ ] 横向虚拟滚动支持（针对大量列）
-- [ ] 更智能的缓冲区策略（根据滚动速度动态调整）
-- [ ] 支持跳转到指定行
-
-## 相关配置
-
-```tsx
-interface StatisticsTableProps {
-  enableVirtualization?: boolean;  // 启用虚拟滚动
-  virtualRowHeight?: number;       // 平均行高（用于计算）
-  getRowHeight?: (rowKey: string, rowData?: any) => number; // 动态行高
-  maxHeight?: number;              // 视口高度
-}
-```
-

package/package/module/Status/README.md

@@ -1,75 +0,0 @@
-# Status
-
-状态标签组件，用于展示不同类型的状态信息。支持 point（圆点）和 solid（填充）两种显示模式。
-
-## 功能特性
-
-- ✅ 支持 6 种状态类型：success、error、warning、waiting、unavailable、disabled
-- ✅ 支持 point 模式（圆点 + 文字）和 solid 模式（带边框文字）
-- ✅ 自动首字母大写显示
-- ✅ 各状态类型使用主题色渲染
-- ✅ 空标签自动返回 null，不渲染
-- ✅ 支持自定义样式覆盖
-- ✅ 支持 testID 属性用于测试
-- ✅ 使用 React.memo 优化渲染性能
-
-## 安装使用
-
-```tsx
-import Status from '@beppla/tapas-ui/components/Status/Status';
-// 或具名导出
-import { StatusTag } from '@beppla/tapas-ui/components/Status/Status';
-```
-
-## Props
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| tag | `string` | - | 状态文字 |
-| type | `STATUS_TYPE` | - | 状态类型 |
-| mode | `'point' \| 'solid'` | `'point'` | 显示模式 |
-| testID | `string` | - | 测试标识 |
-| styles | `StyleProp<ViewStyle>` | - | 自定义容器样式 |
-
-### STATUS_TYPE
-
-```ts
-type STATUS_TYPE = 'success' | 'error' | 'warning' | 'waiting' | 'unavailable' | 'disabled';
-```
-
-## 使用示例
-
-### Point 模式（圆点 + 文字）
-
-```tsx
-<Status tag="Active" type="success" mode="point" />
-<Status tag="Error" type="error" mode="point" />
-<Status tag="Warning" type="warning" mode="point" />
-<Status tag="Waiting" type="waiting" mode="point" />
-```
-
-### Solid 模式（带边框文字）
-
-```tsx
-<Status tag="Available" type="success" mode="solid" />
-<Status tag="Cancelled" type="error" mode="solid" />
-<Status tag="Pending" type="warning" mode="solid" />
-```
-
-### 全部状态类型
-
-```tsx
-{(['success', 'error', 'warning', 'waiting', 'unavailable', 'disabled'] as STATUS_TYPE[]).map(
-  (type) => (
-    <Status key={type} type={type} tag={type} mode="point" />
-  )
-)}
-```
-
-## 注意事项
-
-- `tag` 为空字符串时组件不渲染（返回 null）
-- 标签文字会自动首字母大写（通过 `capitalizeFirstLetter` 处理）
-- point 模式下圆点为 8x8 像素，带圆角
-- solid 模式使用边框 + 文字颜色，不填充背景
-- waiting 状态在 point 模式下有特殊样式（使用边框而非背景色）