@harbortouch/skytab-analytics-report-utils 0.15.0 → 0.16.0

package/README.md

@@ -33,19 +33,34 @@ 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,
+	salesSummaryConfig,
+	COLUMN_REGISTRY,
+	getColumnAlignment,
+	calculateReportTotals,
 } from '@harbortouch/skytab-analytics-report-utils';
+```
+
+### Exporting report data to CSV
+
+Import from the `/csv` sub-path. This keeps `csv-stringify` out of frontend bundles — it is only included when this import is actually used.
+
+```typescript
+import { CsvExporter } from '@harbortouch/skytab-analytics-report-utils/csv';
+
+const exporter = new CsvExporter();
+const csv = exporter.generate(reportRows);
+// returns a UTF-8 BOM-prefixed CSV string (compatible with Excel)
 
-// 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';
+// With overrides (any csv-stringify option)
+const tsv = new CsvExporter({ delimiter: '\t', bom: false });
+const output = tsv.generate(reportRows);
 ```
 
+`CsvExporter` accepts an array of plain objects. Object keys become the header row; all keys are included in their original order. Returns a BOM-only string for empty input (or an empty string when `bom: false` is set).
+
+> **Note:** `csv-stringify` is a dependency of this library — consuming projects do not need to install it separately.
+
 ### Integrating with the frontend (React + TanStack Table)
 
 ```typescript
@@ -61,9 +76,9 @@ const FIELD_CONFIG = salesSummaryConfig.fields as Record<keyof SalesSummaryRecor
 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' },
+	data, // row data array
+	salesSummaryConfig.fields, // field config from this library
+	{ labelField: 'groupByName', label: 'Total' },
 );
 ```
 
@@ -76,6 +91,8 @@ src/
 ├── types.ts                — Core interfaces (FieldType, ColumnPresentationConfig, ReportConfig, …)
 ├── columns/
 │   └── index.ts            — ReportColumnKey union type + COLUMN_REGISTRY (i18n keys)
+├── csv/
+│   └── index.ts            — CsvExporter — published as the ./csv sub-path export
 ├── reports/
 │   ├── salesSummary.ts
 │   ├── ticketSummary.ts
@@ -94,14 +111,14 @@ src/
 
 ## Available reports
 
-| Export | Report |
-|---|---|
-| `salesSummaryConfig` | Sales Summary |
+| Export                | Report         |
+| --------------------- | -------------- |
+| `salesSummaryConfig`  | Sales Summary  |
 | `ticketSummaryConfig` | Ticket Summary |
-| `ticketLiveConfig` | Ticket Live |
-| `productMixConfig` | Product Mix |
-| `modifierMixConfig` | Modifier Mix |
-| `itemTaxConfig` | Item Tax |
+| `ticketLiveConfig`    | Ticket Live    |
+| `productMixConfig`    | Product Mix    |
+| `modifierMixConfig`   | Modifier Mix   |
+| `itemTaxConfig`       | Item Tax       |
 
 ---
 
@@ -111,26 +128,26 @@ src/
 
 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) |
+| 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]` |
+| Type            | Formula                                         |
+| --------------- | ----------------------------------------------- |
+| `sum`           | `Σ row[field]`                                  |
 | `percentChange` | `(Σ numerator − Σ denominator) / Σ denominator` |
-| `average` | `Σ numerator / Σ denominator` |
+| `average`       | `Σ numerator / Σ denominator`                   |
 
 ### Column Registry
 

package/dist/csv/index.cjs

@@ -0,0 +1,42 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/csv/index.ts
+var csv_exports = {};
+__export(csv_exports, {
+  CsvExporter: () => CsvExporter
+});
+module.exports = __toCommonJS(csv_exports);
+var import_sync = require("csv-stringify/sync");
+var CsvExporter = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  generate(rows) {
+    const opts = { header: true, delimiter: ",", bom: true, ...this.options };
+    if (!rows.length) {
+      return opts.bom ? "\uFEFF" : "";
+    }
+    return (0, import_sync.stringify)(rows, opts);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CsvExporter
+});

package/dist/csv/index.d.cts

@@ -0,0 +1,9 @@
+import { OptionsNormalized, Input } from 'csv-stringify/sync';
+
+declare class CsvExporter {
+    private readonly options;
+    constructor(options?: Partial<OptionsNormalized>);
+    generate(rows: Input): string;
+}
+
+export { CsvExporter };

package/dist/csv/index.d.ts

@@ -0,0 +1,9 @@
+import { OptionsNormalized, Input } from 'csv-stringify/sync';
+
+declare class CsvExporter {
+    private readonly options;
+    constructor(options?: Partial<OptionsNormalized>);
+    generate(rows: Input): string;
+}
+
+export { CsvExporter };

package/dist/csv/index.js

@@ -0,0 +1,17 @@
+// src/csv/index.ts
+import { stringify } from "csv-stringify/sync";
+var CsvExporter = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  generate(rows) {
+    const opts = { header: true, delimiter: ",", bom: true, ...this.options };
+    if (!rows.length) {
+      return opts.bom ? "\uFEFF" : "";
+    }
+    return stringify(rows, opts);
+  }
+};
+export {
+  CsvExporter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harbortouch/skytab-analytics-report-utils",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "Centralized report column presentation configuration for SkyTab Analytics",
 	"engines": {
 		"node": ">=22.6.0",
@@ -14,6 +14,11 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"require": "./dist/index.cjs"
+		},
+		"./csv": {
+			"types": "./dist/csv/index.d.ts",
+			"import": "./dist/csv/index.js",
+			"require": "./dist/csv/index.cjs"
 		}
 	},
 	"files": [
@@ -45,5 +50,8 @@
 		"typescript-eslint": "^8.53.1",
 		"vitest": "^4.1.5"
 	},
-	"packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a"
+	"packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a",
+	"dependencies": {
+		"csv-stringify": "^6.8.1"
+	}
 }