npm package: @harbortouch/skytab-analytics-report-utils
Description: Centralized report column presentation configuration for SkyTab Analytics
Latest version: 0.4.4

# skytab-analytics-report-utils

A **framework-agnostic TypeScript library** that centralises all report column presentation configuration for SkyTab Analytics. It is the **shared source of truth** consumed by frontend, backend, and export services — ensuring column definitions, types, widths, footers, and i18n keys stay consistent across all applications.

## What it provides

- Which columns exist in each report
- How each column is typed (`money`, `percent`, `string`, etc.)
- Column widths and alignment rules
- Footer aggregation logic (sum / percent-change / average)
- Column group structure (for multi-level headers)
- i18n translation key references for column labels and tooltips

**No React. No i18n runtime. No API dependencies.** Consumers apply the configuration using their own framework.

---

## Installation

```bash
# Local development (consuming project's package.json)
{
  "dependencies": {
    "@harbortouch/skytab-analytics-report-utils": "file:../skytab-analytics-report-utils"
  }
}
```

Requires **Node ≥ 22.6.0** and **pnpm ≥ 9.0.0**.

---

## Usage

```typescript
// Import everything from the main entry point
import {
  salesSummaryConfig,
  COLUMN_REGISTRY,
  getColumnAlignment,
  calculateReportTotals,
} from '@harbortouch/skytab-analytics-report-utils';

// Sub-path imports for smaller bundles
import { COLUMN_REGISTRY } from '@harbortouch/skytab-analytics-report-utils/columns';
import { salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils/reports';
```

### Integrating with the frontend (React + TanStack Table)

```typescript
import { salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils';
import { type FieldConfig } from '@hooks/useReportBuilder';

const FIELD_CONFIG = salesSummaryConfig.fields as Record<keyof SalesSummaryRecord, FieldConfig<SalesSummaryRecord>>;
```

### Computing totals rows

```typescript
import { calculateReportTotals, salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils';

const totals = calculateReportTotals(
  data,                        // row data array
  salesSummaryConfig.fields,   // field config from this library
  { labelField: 'groupByName', label: 'Total' },
);
```

---

## Repository structure

```
src/
├── types.ts                — Core interfaces (FieldType, ColumnPresentationConfig, ReportConfig, …)
├── columns/
│   └── index.ts            — ReportColumnKey union type + COLUMN_REGISTRY (i18n keys)
├── reports/
│   ├── salesSummary.ts
│   ├── ticketSummary.ts
│   ├── ticketLive.ts
│   ├── productMix.ts
│   ├── modifierMix.ts
│   ├── itemTax.ts
│   └── index.ts            — Re-exports all report configs
├── totals.ts               — calculateReportTotals() utility
├── utils/
│   └── alignment.ts        — getColumnAlignment(), isNumericType()
└── index.ts                — Main entry point
```

---

## Available reports

| Export | Report |
|---|---|
| `salesSummaryConfig` | Sales Summary |
| `ticketSummaryConfig` | Ticket Summary |
| `ticketLiveConfig` | Ticket Live |
| `productMixConfig` | Product Mix |
| `modifierMixConfig` | Modifier Mix |
| `itemTaxConfig` | Item Tax |

---

## Core concepts

### `FieldType`

Governs both formatting and alignment for a column:

| Type | Alignment | Description |
|---|---|---|
| `string` | left | Plain text |
| `date` | left | Calendar date |
| `time` | left | Time of day |
| `boolean` | right | True/false flag |
| `money` | right | Currency value |
| `number` | right | Integer or generic numeric |
| `fixedNumber` | right | Decimal with fixed precision |
| `percent` | right | Ratio displayed as percentage (×100) |

### `FooterCalculation`

Declarative aggregation for totals rows:

| Type | Formula |
|---|---|
| `sum` | `Σ row[field]` |
| `percentChange` | `(Σ numerator − Σ denominator) / Σ denominator` |
| `average` | `Σ numerator / Σ denominator` |

### Column Registry

Every column key maps to three i18n keys via `COLUMN_REGISTRY`:

```typescript
{
  titleKey: 'common.report-col.net-sales',
  shortTitleKey: 'common.report-col.net-sales.short',
  infoTextKey: 'common.report-col.net-sales.info',
}
```

Consumers resolve these keys through their own i18n framework.

---

## Adding a new report

1. Create `src/reports/<reportName>.ts` with a `FIELDS` record and a `ReportConfig` export.
2. Re-export from `src/reports/index.ts`.
3. Re-export from `src/index.ts`.
4. Add any new column keys to `src/columns/index.ts` (`ReportColumnKey` union + `COLUMN_REGISTRY` entry).
5. Build and verify:

```bash
pnpm build
pnpm typecheck
```

---

## Development

```bash
pnpm build       # Build ESM + CJS outputs to dist/
pnpm dev         # Watch mode
pnpm typecheck   # TypeScript type check (no emit)
pnpm lint:js     # ESLint
pnpm lint:js:fix # ESLint with auto-fix
```