@beppla/tapas-ui 1.2.34 → 1.2.36

package/components/StatisticsTable/README.md

@@ -0,0 +1,178 @@
+# 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
+- ✅ Pagination support
+- ✅ Loading state
+- ✅ Empty state
+- ✅ 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 Pagination
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  pagination={{
+    current: 1,
+    pageSize: 10,
+    total: 100,
+    onChange: (page, pageSize) => {
+      console.log('Page:', page, 'PageSize:', pageSize);
+    },
+  }}
+/>
+```
+
+## 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) |
+| `pagination` | `PaginationConfig \| false` | `false` | Pagination configuration |
+| `loading` | `boolean` | `false` | Show loading state |
+| `emptyText` | `string` | `'No data'` | Text for empty state |
+| `maxHeight` | `number` | `500` | Maximum table body height |
+| `rowLabelWidth` | `number` | `150` | Width of first column (row labels) |
+| `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;
+}
+
+interface PaginationConfig {
+  current: number;
+  pageSize: number;
+  total: number;
+  onChange?: (page: number, pageSize: number) => void;
+}
+```
+
+## 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
+