@beppla/tapas-ui 1.5.14 → 1.5.15

package/package/module/StatisticsTable/README.md

@@ -0,0 +1,470 @@
+# StatisticsTable
+
+A versatile table component for displaying matrix data with optional row and column statistics (Sum/Mean).
+
+## Features
+
+- ✅ Matrix data display (rows × columns)
+- ✅ Row statistics (Sum/Mean columns)
+- ✅ Column statistics (Sum/Mean rows)
+- ✅ Horizontal and vertical scrolling
+- ✅ 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)
+
+## Installation
+
+```bash
+yarn add @beppla/tapas-ui
+# or
+npm install @beppla/tapas-ui
+```
+
+## Basic Usage
+
+```tsx
+import { StatisticsTable } from '@beppla/tapas-ui';
+
+const rows = [
+  { key: '2024-12-01', label: 'Dec 1, 2024' },
+  { key: '2024-12-02', label: 'Dec 2, 2024' },
+];
+
+const columns = [
+  { key: 'store1', title: 'Store A', width: 150 },
+  { key: 'store2', title: 'Store B', width: 150 },
+];
+
+const cells = [
+  { rowKey: '2024-12-01', columnKey: 'store1', quantity: 100, amount: 500.00 },
+  { rowKey: '2024-12-01', columnKey: 'store2', quantity: 150, amount: 750.00 },
+  { rowKey: '2024-12-02', columnKey: 'store1', quantity: 120, amount: 600.00 },
+  { rowKey: '2024-12-02', columnKey: 'store2', quantity: 180, amount: 900.00 },
+];
+
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+/>
+```
+
+## With Row Statistics
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  showRowStats={true}
+/>
+```
+
+## With Column Statistics
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  showColumnStats={true}
+/>
+```
+
+## With Both Statistics
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  showRowStats={true}
+  showColumnStats={true}
+/>
+```
+
+## With External Pagination
+
+The StatisticsTable component doesn't include built-in pagination. Use the separate Pagination component for better layout control:
+
+```tsx
+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
+
+When you have limited data but want to ensure a minimum table size, use placeholder rows and columns:
+
+```tsx
+<StatisticsTable
+  rows={rows}         // e.g. only 3 rows of data
+  columns={columns}   // e.g. only 2 columns of data
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}        // Table will have 10 rows (3 data + 7 empty placeholders)
+  minColumns={5}      // Table will have 5 columns (2 data + 3 empty placeholders)
+  maxHeight={600}     // Set container height
+/>
+```
+
+### Customizing Placeholder Size
+
+You can control the size of placeholder rows and columns:
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  minColumns={5}
+  placeholderRowHeight={80}    // Each placeholder row will be 80px tall
+  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
+- Placeholder cells are visually empty but maintain table structure
+- Each placeholder row uses `placeholderRowHeight` (defaults to `rowHeight`, which is 56px)
+- Each placeholder column uses `placeholderColumnWidth` (defaults to 150px)
+
+**Use cases:**
+- Consistent table size regardless of data volume
+- Visual stability during data loading
+- Aligning multiple tables with different data volumes
+- Filling empty space with placeholder cells
+- Controlling exact table dimensions by setting custom placeholder sizes
+
+## With Scroll Shadows
+
+The table supports automatic scroll shadows on all four sides to indicate scrollable content:
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enableScrollShadow={true}   // Enable scroll shadows (default: true)
+  showScrollIndicator={false}  // Hide scrollbars (default: false)
+  maxHeight={400}
+/>
+```
+
+Scroll shadow features:
+- **Left shadow**: Appears when content is scrolled horizontally to the right
+- **Right shadow**: Appears when there's more content to scroll right (adjusts for row stats)
+- **Top shadow**: Appears when content is scrolled vertically downward
+- **Bottom shadow**: Appears when there's more content to scroll down (adjusts for column stats)
+- 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}
+/>
+```
+
+## 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:
+
+```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 |
+|------|------|---------|-------------|
+| `rows` | `Array<{ key: string; label: string }>` | Required | Row definitions |
+| `columns` | `StatisticsTableColumn[]` | Required | Column definitions |
+| `cells` | `StatisticsTableCell[]` | Required | Cell data |
+| `showRowStats` | `boolean` | `false` | Show row statistics (Sum/Mean columns) |
+| `showColumnStats` | `boolean` | `false` | Show column statistics (Sum/Mean rows) |
+| `loading` | `boolean` | `false` | Show loading 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 \| 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 |
+
+## Type Definitions
+
+```tsx
+interface StatisticsTableColumn {
+  key: string;
+  title: string;
+  width?: number;
+}
+
+interface StatisticsTableCell {
+  rowKey: string;
+  columnKey: string;
+  quantity: number;
+  amount: number;
+}
+```
+
+## Use Cases
+
+- **Metadata Details**: Display sales/wastage data by date and store
+- **Performance Reports**: Show metrics across time periods and locations
+- **Financial Tables**: Display revenue/cost data with totals and averages
+- **Analytics Dashboards**: Present multi-dimensional data with statistics
+
+## Backward Compatibility
+
+This component is fully compatible with:
+- React Native 0.76+
+- React 18.3+
+- TypeScript 5.0+
+- Expo SDK 52+
+
+## Accessibility
+
+- Proper semantic structure
+- Scrollable content indicators
+- Screen reader friendly
+- Keyboard navigation support (Web)
+
+## Performance
+
+- Optimized with `useMemo` for large datasets
+- Efficient re-rendering
+- Virtualization-ready (future enhancement)
+
+## License
+
+MIT
+