# rn-timesheet-pivot
URL: /docs/native/docyrus/timesheet-pivot

A horizontal pivot table for time tracking with heatmap coloring, column totals, and striped rows.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-timesheet-pivot
```

## Usage

```tsx
import { TimesheetPivot } from '@/components/docyrus-native/timesheet-pivot';

const columns = [
  { key: 'mon', label: 'Mon' },
  { key: 'tue', label: 'Tue' },
  { key: 'wed', label: 'Wed' },
  { key: 'thu', label: 'Thu' },
  { key: 'fri', label: 'Fri' },
];

const rows = [
  {
    id: 'project-1',
    title: 'Project Atlas',
    subtitle: 'Mobile sprint',
    values: { mon: 2.5, tue: 1.5, wed: 4, thu: 3.5, fri: 2 },
  },
  {
    id: 'project-2',
    title: 'Project Northwind',
    values: { mon: 1, tue: 2, wed: 0, thu: 2.5, fri: 3 },
  },
];

```

## Features

- **Heatmap coloring** — cells are tinted based on value intensity relative to the max value
- **Column totals footer** — a summary row showing totals per column and a grand total
- **Striped rows** — alternating row backgrounds for readability
- **FlatList rendering** — virtualized row rendering with `getItemLayout` for O(1) scroll performance
- **Three value formats** — `raw`, `hours` (`2.5h`), `minutes` (`2h 30m`)
- **Custom formatter** — override cell display with `valueFormatter`
- **Row press** — optional `onRowPress` callback for navigation
- **Dark mode** — fully theme-aware with light/dark opacity adjustments

## API Reference

### TimesheetPivotProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `TimesheetPivotColumn[]` | — | Column definitions (key + label) |
| `rows` | `TimesheetPivotRow[]` | — | Row data with values per column |
| `messages` | `Partial<TimesheetPivotMessages>` | — | App-supplied copy; each key wins over the translation provider |
| `isLoading` | `boolean` | `false` | Shows loading state |
| `emptyMessage` | `string` | — | Optional empty state override |
| `showTotals` | `boolean` | `true` | Shows total column per row + footer totals row |
| `emptyValue` | `string` | `'—'` | Placeholder for empty/zero cells |
| `valueKind` | `'raw' \| 'hours' \| 'minutes'` | `'raw'` | Default numeric formatter |
| `onRowPress` | `(row: TimesheetPivotRow) => void` | — | Row press callback |
| `valueFormatter` | `(value, columnKey, row) => string` | — | Custom cell value formatter |
| `className` | `string` | — | Additional wrapper className |

### TimesheetPivotColumn

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Unique column identifier (used as key in `values`) |
| `label` | `string` | Display label in header |

### TimesheetPivotRow

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique row identifier |
| `title` | `string` | Primary row label |
| `subtitle` | `string?` | Secondary label (shown below title) |
| `values` | `Record<string, CellValue>` | Cell values keyed by column key |
| `total` | `CellValue?` | Explicit total (auto-computed if omitted) |

### TimesheetPivotMessages

Every field is optional in the `messages` prop and falls back to `<UiTranslationProvider>`.

| Field | Type | Fallback key | English fallback | Description |
|-------|------|--------------|------------------|-------------|
| `loading` | `string` | `ui.timesheetPivot.loading` | `Loading timesheet...` | Loading state label |
| `empty` | `string` | `ui.timesheetPivot.empty` | `No time recorded` | Empty state label |
| `total` | `string` | `ui.timesheetPivot.total` | `Total` | Total column/row header label |
| `row` | `string` | `ui.timesheetPivot.row` | `Item` | First column header label |

### TimesheetPivotCellValue

```ts
type TimesheetPivotCellValue = number | string | null | undefined;
```

## Value Formatting

The component supports three built-in formatters via `valueKind`:

| Kind | Input | Output |
|------|-------|--------|
| `raw` | `2.5` | `2.5` |
| `hours` | `2.5` | `2.5h` |
| `minutes` | `150` | `2h 30m` |

For custom formatting, use `valueFormatter`:

```tsx
<TimesheetPivot
  valueFormatter={(value, columnKey, row) => {
    if (columnKey === '__total__') return `${value}h total`;
    return typeof value === 'number' ? `${value}h` : '—';
  }}
/>
```

## Components

| Component | Description |
|-----------|-------------|
| `TimesheetPivot` | Horizontal pivot table — the mobile timesheet view (conceptually the native counterpart of web `PivotCalendar`) |

## Type Exports

| Type | Description |
|------|-------------|
| `TimesheetPivotProps` | Props for TimesheetPivot |
| `TimesheetPivotColumn` | `{ key, label }` column definition |
| `TimesheetPivotRow` | Row with per-column values |
| `TimesheetPivotCellValue` | `number \| string \| null \| undefined` |
| `TimesheetPivotValueKind` | `'raw' \| 'hours' \| 'minutes'` |
| `TimesheetPivotMessages` | Copy keys |