@beppla/tapas-ui 1.4.6 → 1.4.8

package/module/StatisticsTable/README.md

@@ -8,10 +8,12 @@ A versatile table component for displaying matrix data with optional row and col
 - ✅ Row statistics (Sum/Mean columns)
 - ✅ Column statistics (Sum/Mean rows)
 - ✅ Horizontal and vertical scrolling
-- ✅ Pagination support
+- ✅ Virtual scrolling for large datasets (high performance)
+- ✅ External pagination support
 - ✅ Loading state
 - ✅ Empty state
 - ✅ Placeholder rows and columns (fill container when data is insufficient)
+- ✅ Internationalization (i18n) support
 - ✅ Customizable styling
 - ✅ TypeScript support
 - ✅ Cross-platform (Web & Mobile)
@@ -87,22 +89,43 @@ const cells = [
 />
 ```
 
-## With Pagination
+## With External Pagination
+
+The StatisticsTable component doesn't include built-in pagination. Use the separate Pagination component for better layout control:
 
 ```tsx
-<StatisticsTable
-  rows={rows}
-  columns={columns}
-  cells={cells}
-  pagination={{
-    current: 1,
-    pageSize: 10,
-    total: 100,
-    onChange: (page, pageSize) => {
-      console.log('Page:', page, 'PageSize:', pageSize);
-    },
-  }}
-/>
+import { StatisticsTable, Pagination } from '@beppla/tapas-ui';
+
+function MyTable() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const pageSize = 10;
+  
+  // Calculate paginated rows
+  const paginatedRows = rows.slice(
+    (currentPage - 1) * pageSize,
+    currentPage * pageSize
+  );
+  
+  return (
+    <>
+      <StatisticsTable
+        rows={paginatedRows}
+        columns={columns}
+        cells={cells}
+      />
+      <Pagination
+        totalCount={`${rows.length} items`}
+        pageParams={{
+          page: currentPage,
+          pageSize: pageSize,
+          totalItems: rows.length,
+          totalPage: Math.ceil(rows.length / pageSize),
+        }}
+        onPageChange={(params) => setCurrentPage(params.page)}
+      />
+    </>
+  );
+}
 ```
 
 ## With Placeholder Rows and Columns
@@ -134,11 +157,34 @@ You can control the size of placeholder rows and columns:
   minRows={10}
   minColumns={5}
   placeholderRowHeight={80}    // Each placeholder row will be 80px tall
-  placeholderColumnWidth={200} // Each placeholder column will be 200px wide
+  placeholderColumnWidth={200} // All placeholder columns will be 200px wide
   maxHeight={600}
 />
 ```
 
+**Individual placeholder column widths** for better screen adaptation:
+
+```tsx
+<StatisticsTable
+  rows={rows}              // 2 data columns
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minColumns={5}           // Need 3 placeholder columns
+  placeholderColumnWidth={[180, 220, 150]} // Individual widths for each placeholder
+  // Placeholder column 1: 180px
+  // Placeholder column 2: 220px
+  // Placeholder column 3: 150px
+/>
+```
+
+If array length is less than placeholder columns needed, the last value will be reused:
+
+```tsx
+placeholderColumnWidth={[200, 150]}  // minColumns=5, need 3 placeholders
+// Result: [200, 150, 150] - last value (150) reused
+```
+
 **How it works:**
 - If `rows.length < minRows`: Adds `(minRows - rows.length)` empty placeholder rows
 - If columns count `< minColumns`: Adds `(minColumns - columns.count)` empty placeholder columns
@@ -176,6 +222,102 @@ Scroll shadow features:
 - Shadows automatically show/hide based on scroll position
 - Works seamlessly with row statistics and column statistics
 
+## Virtual Scrolling for Large Datasets
+
+For tables with hundreds or thousands of rows, enable virtual scrolling for optimal performance:
+
+```tsx
+<StatisticsTable
+  rows={thousandsOfRows}
+  columns={columns}
+  cells={cells}
+  enableVirtualization={true}
+  virtualRowHeight={56}     // Default row height for calculation
+  maxHeight={600}
+/>
+```
+
+**How it works:**
+- Only renders rows visible in the viewport (plus a small buffer)
+- Automatically calculates which rows to render based on scroll position
+- Maintains proper scroll behavior with placeholder spaces above/below
+- Supports dynamic row heights via `getRowHeight` prop
+- Typical performance: 10,000+ rows scroll smoothly
+
+**Performance tips:**
+- Set `virtualRowHeight` to match your average row height
+- Use `getRowHeight` for dynamic heights, but be aware it's called frequently
+- For uniform row heights, use the default `rowHeight` for best performance
+
+**Example with dynamic heights:**
+
+```tsx
+<StatisticsTable
+  rows={largeDataset}
+  columns={columns}
+  cells={cells}
+  enableVirtualization={true}
+  getRowHeight={(rowKey, rowData) => {
+    // Return height based on row data
+    return rowData?.isExpanded ? 120 : 56;
+  }}
+  maxHeight={600}
+/>
+```
+
+## Internationalization (i18n)
+
+Customize loading and empty state texts for different languages:
+
+```tsx
+// English
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  loading={isLoading}
+  loadingText="Loading..."
+  emptyText="No data available"
+/>
+
+// Chinese
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  loading={isLoading}
+  loadingText="加载中..."
+  emptyText="暂无数据"
+/>
+
+// Spanish
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  loading={isLoading}
+  loadingText="Cargando..."
+  emptyText="No hay datos"
+/>
+
+// With i18n library
+import { useTranslation } from 'react-i18next';
+
+function MyTable() {
+  const { t } = useTranslation();
+  
+  return (
+    <StatisticsTable
+      rows={rows}
+      columns={columns}
+      cells={cells}
+      loadingText={t('table.loading')}
+      emptyText={t('table.empty')}
+    />
+  );
+}
+```
+
 ## Props
 
 | Prop | Type | Default | Description |
@@ -185,16 +327,19 @@ Scroll shadow features:
 | `cells` | `StatisticsTableCell[]` | Required | Cell data |
 | `showRowStats` | `boolean` | `false` | Show row statistics (Sum/Mean columns) |
 | `showColumnStats` | `boolean` | `false` | Show column statistics (Sum/Mean rows) |
-| `pagination` | `PaginationConfig \| false` | `false` | Pagination configuration |
 | `loading` | `boolean` | `false` | Show loading state |
-| `emptyText` | `string` | `'No data'` | Text for empty state |
+| `loadingText` | `string` | `'Loading...'` | Text to display during loading (for i18n) |
+| `emptyText` | `string` | `'No data'` | Text to display when empty (for i18n) |
 | `maxHeight` | `number` | `500` | Maximum table body height |
 | `rowLabelWidth` | `number` | `150` | Width of first column (row labels) |
 | `enablePlaceholder` | `boolean` | `false` | Enable placeholder rows/columns to fill container |
 | `minRows` | `number` | `0` | Minimum number of rows (adds placeholders if needed) |
 | `minColumns` | `number` | `0` | Minimum number of columns (adds placeholders if needed) |
 | `placeholderRowHeight` | `number` | `rowHeight` (56) | Height of each placeholder row |
-| `placeholderColumnWidth` | `number` | `150` | Width of each placeholder column |
+| `placeholderColumnWidth` | `number \| number[]` | `150` | Width of placeholder columns (single number or array for each column) |
+| `enableVirtualization` | `boolean` | `false` | Enable virtual scrolling for large datasets |
+| `virtualRowHeight` | `number` | `56` | Average row height for virtual scroll calculations |
+| `getRowHeight` | `(rowKey, rowData) => number` | - | Dynamic row height function (used in virtual scrolling) |
 | `enableScrollShadow` | `boolean` | `true` | Enable scroll shadows on all four sides |
 | `showScrollIndicator` | `boolean` | `false` | Show scroll indicators/scrollbars |
 | `style` | `ViewStyle` | - | Custom container styles |
@@ -214,13 +359,6 @@ interface StatisticsTableCell {
   quantity: number;
   amount: number;
 }
-
-interface PaginationConfig {
-  current: number;
-  pageSize: number;
-  total: number;
-  onChange?: (page: number, pageSize: number) => void;
-}
 ```
 
 ## Use Cases

package/module/StatisticsTable/StatisticsTable.js

@@ -3,7 +3,6 @@
 import React, { useMemo, useCallback, useState, useRef, useEffect } from 'react';
 import { View, ScrollView, StyleSheet, Platform, TouchableOpacity, Text, Animated } from 'react-native';
 import { useTheme } from '@rneui/themed';
-import Pagination from '../Pagination/Pagination';
 import Hoverable from '../Hoverable/Hoverable';
 
 // Tooltip 内容类型
@@ -86,8 +85,8 @@ export function StatisticsTable({
   cells,
   showRowStats = false,
   showColumnStats = false,
-  pagination,
   loading = false,
+  loadingText = 'Loading...',
   emptyText = 'No data',
   maxHeight = 500,
   rowLabelWidth = 150,
@@ -146,6 +145,9 @@ export function StatisticsTable({
     isAtBottom: false
   });
 
+  // 虚拟滚动状态
+  const [virtualScrollOffset, setVirtualScrollOffset] = useState(0);
+
   // Hover 状态
   const [hoveredCell, setHoveredCell] = useState(null);
   const scrollViewRef = useRef(null);
@@ -188,12 +190,13 @@ export function StatisticsTable({
       backgroundColor: colors.colorSurface // 米色背景
     },
     header: {
-      backgroundColor: headerStyle?.backgroundColor || colors.colorSurface,
-      // 米色
+      backgroundColor: headerStyle?.backgroundColor || colors.colorSurface7,
+      // rgba(0, 0, 0, 0.08)
       borderBottomColor: colors.colorTableBorder
     },
     headerCell: {
-      borderRightColor: colors.colorTableBorder
+      borderRightColor: colors.colorTableBorder,
+      backgroundColor: headerStyle?.backgroundColor || colors.colorSurface7
     },
     headerText: {
       color: headerStyle?.textColor || colors.colorTextPrimary,
@@ -202,7 +205,7 @@ export function StatisticsTable({
     },
     // Row Stats 表头样式
     statsHeaderCell: {
-      backgroundColor: rowStatsHeaderStyle?.backgroundColor || 'rgba(0, 0, 0, 0.08)',
+      backgroundColor: rowStatsHeaderStyle?.backgroundColor || colors.colorSurface7,
       borderRightColor: colors.colorTableBorder,
       borderBottomColor: colors.colorTableBorder
     },
@@ -255,10 +258,6 @@ export function StatisticsTable({
       fontSize: columnStatsLabelStyle?.fontSize || 14,
       fontWeight: columnStatsLabelStyle?.fontWeight || '600'
     },
-    paginationContainer: {
-      borderTopColor: colors.colorTableBorder,
-      backgroundColor: colors.colorSurface
-    },
     // Column Stats 分隔线
     columnStatsDivider: {
       borderTopWidth: 2,
@@ -344,11 +343,15 @@ export function StatisticsTable({
       // 添加占位列来填充
       const placeholderColumns = Array.from({
         length: missingColumns
-      }, (_, i) => ({
-        key: `_placeholder_col_${i}`,
-        title: '',
-        width: placeholderColumnWidth // 使用自定义占位列宽度
-      }));
+      }, (_, i) => {
+        // 支持数组形式的宽度设置
+        const width = Array.isArray(placeholderColumnWidth) ? placeholderColumnWidth[i] || placeholderColumnWidth[placeholderColumnWidth.length - 1] || 150 : placeholderColumnWidth;
+        return {
+          key: `_placeholder_col_${i}`,
+          title: '',
+          width: width
+        };
+      });
       finalColumns = [...columns, ...placeholderColumns];
     }
 
@@ -407,8 +410,13 @@ export function StatisticsTable({
       y: contentOffset.y,
       animated: false
     });
+
+    // 更新虚拟滚动偏移量
+    if (enableVirtualization) {
+      setVirtualScrollOffset(contentOffset.y);
+    }
     handleScroll(event);
-  }, [handleScroll]);
+  }, [handleScroll, enableVirtualization]);
 
   // 处理单元格 hover
   const handleCellHover = useCallback((rowKey, columnKey, isHovered) => {
@@ -517,7 +525,10 @@ export function StatisticsTable({
       children: /*#__PURE__*/_jsx(View, {
         style: styles.loadingRow,
         children: /*#__PURE__*/_jsx(Text, {
-          children: "Loading..."
+          style: {
+            color: colors.colorTextPlaceholder
+          },
+          children: loadingText
         })
       })
     });
@@ -536,7 +547,75 @@ export function StatisticsTable({
       })
     });
   }
-  const visibleRows = enableVirtualization ? displayRows.slice(0, Math.ceil(maxHeight / virtualRowHeight)) : displayRows;
+
+  // 虚拟滚动计算
+  const virtualScrollData = useMemo(() => {
+    if (!enableVirtualization) {
+      return {
+        visibleRows: displayRows,
+        startIndex: 0,
+        endIndex: displayRows.length,
+        offsetTop: 0,
+        offsetBottom: 0,
+        totalHeight: 0
+      };
+    }
+
+    // 计算每行的累积高度
+    const rowHeights = [];
+    let totalHeight = 0;
+    displayRows.forEach(row => {
+      const height = row.height || (getRowHeight ? getRowHeight(row.key, row.data) : rowHeight || virtualRowHeight);
+      rowHeights.push(height);
+      totalHeight += height;
+    });
+
+    // 计算可视区域
+    const viewportHeight = maxHeight - (actualShowColumnStats ? 120 : 0);
+    const scrollTop = virtualScrollOffset;
+
+    // 查找起始索引
+    let startIndex = 0;
+    let accumulatedHeight = 0;
+    for (let i = 0; i < rowHeights.length; i++) {
+      const currentHeight = rowHeights[i] || virtualRowHeight;
+      if (accumulatedHeight + currentHeight > scrollTop) {
+        startIndex = i;
+        break;
+      }
+      accumulatedHeight += currentHeight;
+    }
+
+    // 添加缓冲区（上下各多渲染几行）
+    const overscan = 3;
+    startIndex = Math.max(0, startIndex - overscan);
+
+    // 查找结束索引
+    let endIndex = startIndex;
+    let visibleHeight = 0;
+    for (let i = startIndex; i < rowHeights.length; i++) {
+      const currentHeight = rowHeights[i] || virtualRowHeight;
+      visibleHeight += currentHeight;
+      endIndex = i + 1;
+      if (visibleHeight >= viewportHeight) {
+        break;
+      }
+    }
+    endIndex = Math.min(displayRows.length, endIndex + overscan);
+
+    // 计算上下占位空间
+    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,
+      totalHeight
+    };
+  }, [enableVirtualization, displayRows, virtualScrollOffset, maxHeight, actualShowColumnStats, rowHeight, getRowHeight]);
+  const visibleRows = virtualScrollData.visibleRows;
 
   // Web 阴影样式
   const webShadowStyle = Platform.OS === 'web' ? {
@@ -610,7 +689,7 @@ export function StatisticsTable({
                   })
                 }, column.key);
               })]
-            }), /*#__PURE__*/_jsx(ScrollView, {
+            }), /*#__PURE__*/_jsxs(ScrollView, {
               ref: bodyScrollViewRef,
               style: {
                 maxHeight: maxHeight - columnStatsHeight
@@ -618,15 +697,24 @@ export function StatisticsTable({
               showsVerticalScrollIndicator: showScrollIndicator,
               onScroll: handleBodyScroll,
               scrollEventThrottle: 16,
-              children: visibleRows.map(row => {
+              children: [enableVirtualization && virtualScrollData.offsetTop > 0 && /*#__PURE__*/_jsx(View, {
+                style: {
+                  height: virtualScrollData.offsetTop
+                }
+              }), visibleRows.map((row, rowIndex) => {
                 const currentRowHeight = getRowHeightValue(row);
                 const isClickable = !!onRowPress;
                 const isRowHovered = hoveredCell?.rowKey === row.key;
                 const isPlaceholder = row.key.startsWith('_placeholder_row_');
+                const isLastRow = rowIndex === visibleRows.length - 1;
                 return /*#__PURE__*/_jsxs(TouchableOpacity, {
                   style: [styles.row, themedStyles.row, {
                     minHeight: currentRowHeight
-                  }, isRowHovered && !isPlaceholder && themedStyles.rowHovered],
+                  }, isRowHovered && !isPlaceholder && themedStyles.rowHovered,
+                  // 最后一行且没有 Column Stats 时移除底部边框，避免与表格底边重合
+                  isLastRow && !actualShowColumnStats && {
+                    borderBottomWidth: 0
+                  }],
                   onPress: isClickable && !isPlaceholder ? () => onRowPress(row.key, row.data) : undefined,
                   activeOpacity: isClickable && !isPlaceholder ? 0.7 : 1,
                   disabled: !isClickable || isPlaceholder,
@@ -670,7 +758,11 @@ export function StatisticsTable({
                     }, column.key);
                   })]
                 }, row.key);
-              })
+              }), enableVirtualization && virtualScrollData.offsetBottom > 0 && /*#__PURE__*/_jsx(View, {
+                style: {
+                  height: virtualScrollData.offsetBottom
+                }
+              })]
             }), actualShowColumnStats && columnStats && /*#__PURE__*/_jsxs(Animated.View, {
               style: [styles.columnStatsContainer, themedStyles.columnStatsDivider, enableStatsAnimation && {
                 opacity: columnStatsAnimation,
@@ -820,15 +912,21 @@ export function StatisticsTable({
               children: rowStatsHeaders.mean
             })
           })]
-        }), /*#__PURE__*/_jsx(ScrollView, {
+        }), /*#__PURE__*/_jsxs(ScrollView, {
           ref: rowStatsScrollRef,
           style: {
             maxHeight: maxHeight - columnStatsHeight
           },
           showsVerticalScrollIndicator: false,
           scrollEnabled: false,
-          children: visibleRows.map((row, rowIndex) => {
-            const rowStat = rowStats?.[rowIndex];
+          children: [enableVirtualization && virtualScrollData.offsetTop > 0 && /*#__PURE__*/_jsx(View, {
+            style: {
+              height: virtualScrollData.offsetTop
+            }
+          }), visibleRows.map((row, rowIndex) => {
+            // 计算在原始数组中的索引
+            const actualIndex = enableVirtualization ? virtualScrollData.startIndex + rowIndex : rowIndex;
+            const rowStat = rowStats?.[actualIndex];
             const currentRowHeight = getRowHeightValue(row);
             const isRowHovered = hoveredCell?.rowKey === row.key;
             const isSumHovered = hoveredCell?.rowKey === row.key && hoveredCell?.columnKey === '__row_sum__';
@@ -879,23 +977,13 @@ export function StatisticsTable({
                 })
               })]
             }, row.key);
-          })
+          }), enableVirtualization && virtualScrollData.offsetBottom > 0 && /*#__PURE__*/_jsx(View, {
+            style: {
+              height: virtualScrollData.offsetBottom
+            }
+          })]
         })]
       })]
-    }), pagination !== false && pagination && /*#__PURE__*/_jsx(View, {
-      style: [styles.paginationContainer, themedStyles.paginationContainer],
-      children: /*#__PURE__*/_jsx(Pagination, {
-        totalCount: `${pagination.total} items`,
-        pageParams: {
-          page: pagination.current,
-          pageSize: pagination.pageSize,
-          totalItems: pagination.total,
-          totalPage: Math.ceil(pagination.total / pagination.pageSize)
-        },
-        onPageChange: params => {
-          pagination.onChange?.(params.page, params.pageSize);
-        }
-      })
     })]
   });
 }
@@ -984,9 +1072,6 @@ const styles = StyleSheet.create({
   emptyText: {
     fontSize: 14
   },
-  paginationContainer: {
-    borderTopWidth: 1
-  },
   // Row Stats 容器
   rowStatsContainer: {
     position: 'relative'
@@ -1004,11 +1089,13 @@ const styles = StyleSheet.create({
   },
   shadowLeft: {
     left: 0,
-    top: 0,
+    top: 40,
+    // 从表头底部开始
     bottom: 0
   },
   shadowRight: {
-    top: 0,
+    top: 40,
+    // 从表头底部开始
     bottom: 0
   },
   // 水平阴影条
@@ -1021,7 +1108,7 @@ const styles = StyleSheet.create({
     backgroundColor: 'transparent'
   },
   shadowTop: {
-    top: 56 // header height
+    top: 40 // header height (paddingVertical: 12*2 + content ~16)
   },
   shadowBottom: {
     // bottom 由动态样式设置