@beppla/tapas-ui 1.4.15 → 1.4.17

package/package/module/StatisticsTable/README.md

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