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

# 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

// 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)

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

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:

{
  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:

pnpm build
pnpm typecheck

Development

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