@harbortouch/skytab-analytics-report-utils 0.17.0 → 0.19.1

package/README.md

@@ -111,6 +111,85 @@ fs.writeFileSync('report.pdf', buffer);
 
 ---
 
+### Exporting report data to Excel
+
+Import from the `/excel` sub-path. This keeps `exceljs` out of frontend bundles — it is only included when this import is actually used.
+
+```typescript
+import { ExcelExporter } from '@harbortouch/skytab-analytics-report-utils/excel';
+
+const exporter = new ExcelExporter();
+
+const buffer = await exporter.generate({
+	sheets: [
+		{
+			sheetName: 'Sales Summary',
+			filters: [
+				{ label: 'Date Range', value: 'Jan 1 – Jan 31' },
+				{ label: 'Location', value: 'Downtown' },
+			],
+			table: {
+				columns: [
+					{ header: 'Item', key: 'name' },
+					{ header: 'Net Sales', key: 'netSales' },
+					{ header: 'Qty', key: 'qty' },
+				],
+				rows: reportRows,
+			},
+		},
+	],
+});
+
+// buffer is a Node.js Buffer containing the .xlsx binary
+fs.writeFileSync('report.xlsx', buffer);
+```
+
+`ExcelExporter.generate()` returns a `Promise<Buffer>`. Each entry in `sheets` produces one worksheet tab in the workbook.
+
+**`ExcelSheet`**
+
+| Field       | Type            | Description                                             |
+| ----------- | --------------- | ------------------------------------------------------- |
+| `sheetName` | `string`        | Optional worksheet name (defaults to `'Report'`)        |
+| `filters`   | `ExcelFilter[]` | Optional applied-filters block rendered above the table |
+| `table`     | `ExcelTable`    | Optional table to render on the sheet                   |
+
+**`ExcelTable`**
+
+| Field     | Type                        | Description                                |
+| --------- | --------------------------- | ------------------------------------------ |
+| `columns` | `ExcelTableColumn[]`        | Column definitions (order preserved)       |
+| `rows`    | `Record<string, unknown>[]` | Row data — keyed by `ExcelTableColumn.key` |
+
+**`ExcelTableColumn`**
+
+| Field    | Type     | Description                                             |
+| -------- | -------- | ------------------------------------------------------- |
+| `header` | `string` | Column header label                                     |
+| `key`    | `string` | Field name used to look up the value in each row object |
+| `width`  | `number` | Optional hint — auto-sized from content if omitted      |
+
+**`ExcelFilter`**
+
+| Field   | Type     | Description  |
+| ------- | -------- | ------------ |
+| `label` | `string` | Filter label |
+| `value` | `string` | Filter value |
+
+**Behaviour notes**
+
+- Each `ExcelSheet` entry produces one worksheet tab in the workbook.
+- Applied filters are rendered as `Label: value` rows above the table, separated from it by a blank row.
+- The header row is bold with a grey fill (`#D3D3D3`) and has Excel auto-filter enabled.
+- Alternating data rows use a light grey background (`#F5F5F5`).
+- Numeric cell values are right-aligned; all other values are left-aligned.
+- Column widths are auto-calculated from header and cell content; the optional `width` field overrides the auto-calculation for a specific column.
+- `null` and `undefined` cell values are rendered as empty cells.
+
+> **Note:** `exceljs` is a dependency of this library — consuming projects do not need to install it separately.
+
+---
+
 ### 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.
@@ -161,11 +240,15 @@ 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
-├── pdf/
-│   ├── index.ts            — PdfExporter — published as the ./pdf sub-path export
-│   └── pdf.utils.ts        — stripEmojis() helper
+├── exporters/
+│   ├── types.ts            — Shared ExportTableColumn / ExportTable / ExportFilter interfaces
+│   ├── csv/
+│   │   └── index.ts        — CsvExporter — published as the ./csv sub-path export
+│   ├── excel/
+│   │   └── index.ts        — ExcelExporter — published as the ./excel sub-path export
+│   └── pdf/
+│       ├── index.ts        — PdfExporter — published as the ./pdf sub-path export
+│       └── pdf.utils.ts    — stripEmojis() helper
 ├── reports/
 │   ├── salesSummary.ts
 │   ├── ticketSummary.ts

package/dist/{csv → exporters/csv}/index.cjs

@@ -17,7 +17,7 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/csv/index.ts
+// src/exporters/csv/index.ts
 var csv_exports = {};
 __export(csv_exports, {
   CsvExporter: () => CsvExporter

package/dist/{csv → exporters/csv}/index.js

@@ -1,4 +1,4 @@
-// src/csv/index.ts
+// src/exporters/csv/index.ts
 import { stringify } from "csv-stringify/sync";
 var CsvExporter = class {
   constructor(options = {}) {

package/dist/exporters/excel/index.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/exporters/excel/index.ts
+var excel_exports = {};
+__export(excel_exports, {
+  ExcelExporter: () => ExcelExporter
+});
+module.exports = __toCommonJS(excel_exports);
+var import_exceljs = __toESM(require("exceljs"), 1);
+var GRAY_FILL = {
+  type: "pattern",
+  pattern: "solid",
+  fgColor: { argb: "FFD9D9D9" }
+};
+var toCell = (value) => {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return null;
+};
+var ExcelExporter = class {
+  async generate(content) {
+    const workbook = new import_exceljs.default.Workbook();
+    const usedNames = /* @__PURE__ */ new Set();
+    for (const section of content.sections) {
+      let sheetName = section.sheetName.slice(0, 31);
+      if (usedNames.has(sheetName.toLowerCase())) {
+        let suffix = 2;
+        let candidate = `${sheetName.slice(0, 28)}_${suffix}`;
+        while (usedNames.has(candidate.toLowerCase())) {
+          suffix++;
+          candidate = `${sheetName.slice(0, 28)}_${suffix}`;
+        }
+        sheetName = candidate;
+      }
+      usedNames.add(sheetName.toLowerCase());
+      const sheet = workbook.addWorksheet(sheetName);
+      if (section.filters && section.filters.length > 0) {
+        const titleRow = sheet.addRow(["Applied Filters"]);
+        titleRow.getCell(1).font = { bold: true };
+        titleRow.getCell(1).fill = GRAY_FILL;
+        for (const filter of section.filters) {
+          const row = sheet.addRow([filter.label, filter.value]);
+          row.getCell(1).font = { bold: true };
+        }
+        sheet.addRow([]);
+      }
+      if (section.table) {
+        const headerRow = sheet.addRow(section.table.columns.map((col) => col.header));
+        headerRow.font = { bold: true };
+        headerRow.eachCell((cell) => {
+          cell.fill = GRAY_FILL;
+        });
+        section.table.columns.forEach((col, i) => {
+          if (col.width) {
+            sheet.getColumn(i + 1).width = col.width / 7;
+          }
+        });
+        for (const row of section.table.rows) {
+          sheet.addRow(section.table.columns.map((col) => toCell(row[col.key])));
+        }
+      }
+    }
+    const buf = await workbook.xlsx.writeBuffer();
+    return Buffer.from(buf);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExcelExporter
+});

package/dist/exporters/excel/index.d.cts

@@ -0,0 +1,15 @@
+import { E as ExportTable, a as ExportFilter } from '../../types-BzLsgnfc.cjs';
+export { b as XlsxTableColumn } from '../../types-BzLsgnfc.cjs';
+
+interface XlsxDocumentSection {
+    sheetName: string;
+    table?: ExportTable;
+    filters?: ExportFilter[];
+}
+declare class ExcelExporter {
+    generate(content: {
+        sections: XlsxDocumentSection[];
+    }): Promise<Buffer>;
+}
+
+export { ExcelExporter, type XlsxDocumentSection, ExportFilter as XlsxFilter, ExportTable as XlsxTable };

package/dist/exporters/excel/index.d.ts

@@ -0,0 +1,15 @@
+import { E as ExportTable, a as ExportFilter } from '../../types-BzLsgnfc.js';
+export { b as XlsxTableColumn } from '../../types-BzLsgnfc.js';
+
+interface XlsxDocumentSection {
+    sheetName: string;
+    table?: ExportTable;
+    filters?: ExportFilter[];
+}
+declare class ExcelExporter {
+    generate(content: {
+        sections: XlsxDocumentSection[];
+    }): Promise<Buffer>;
+}
+
+export { ExcelExporter, type XlsxDocumentSection, ExportFilter as XlsxFilter, ExportTable as XlsxTable };

package/dist/exporters/excel/index.js

@@ -0,0 +1,66 @@
+// src/exporters/excel/index.ts
+import ExcelJS from "exceljs";
+var GRAY_FILL = {
+  type: "pattern",
+  pattern: "solid",
+  fgColor: { argb: "FFD9D9D9" }
+};
+var toCell = (value) => {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return null;
+};
+var ExcelExporter = class {
+  async generate(content) {
+    const workbook = new ExcelJS.Workbook();
+    const usedNames = /* @__PURE__ */ new Set();
+    for (const section of content.sections) {
+      let sheetName = section.sheetName.slice(0, 31);
+      if (usedNames.has(sheetName.toLowerCase())) {
+        let suffix = 2;
+        let candidate = `${sheetName.slice(0, 28)}_${suffix}`;
+        while (usedNames.has(candidate.toLowerCase())) {
+          suffix++;
+          candidate = `${sheetName.slice(0, 28)}_${suffix}`;
+        }
+        sheetName = candidate;
+      }
+      usedNames.add(sheetName.toLowerCase());
+      const sheet = workbook.addWorksheet(sheetName);
+      if (section.filters && section.filters.length > 0) {
+        const titleRow = sheet.addRow(["Applied Filters"]);
+        titleRow.getCell(1).font = { bold: true };
+        titleRow.getCell(1).fill = GRAY_FILL;
+        for (const filter of section.filters) {
+          const row = sheet.addRow([filter.label, filter.value]);
+          row.getCell(1).font = { bold: true };
+        }
+        sheet.addRow([]);
+      }
+      if (section.table) {
+        const headerRow = sheet.addRow(section.table.columns.map((col) => col.header));
+        headerRow.font = { bold: true };
+        headerRow.eachCell((cell) => {
+          cell.fill = GRAY_FILL;
+        });
+        section.table.columns.forEach((col, i) => {
+          if (col.width) {
+            sheet.getColumn(i + 1).width = col.width / 7;
+          }
+        });
+        for (const row of section.table.rows) {
+          sheet.addRow(section.table.columns.map((col) => toCell(row[col.key])));
+        }
+      }
+    }
+    const buf = await workbook.xlsx.writeBuffer();
+    return Buffer.from(buf);
+  }
+};
+export {
+  ExcelExporter
+};

package/dist/{pdf → exporters/pdf}/index.cjs

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/pdf/index.ts
+// src/exporters/pdf/index.ts
 var pdf_exports = {};
 __export(pdf_exports, {
   PdfExporter: () => PdfExporter
@@ -35,7 +35,7 @@ __export(pdf_exports, {
 module.exports = __toCommonJS(pdf_exports);
 var import_pdfkit = __toESM(require("pdfkit"), 1);
 
-// src/pdf/pdf.utils.ts
+// src/exporters/pdf/pdf.utils.ts
 var stripEmojis = (text) => {
   if (!text) {
     return text;
@@ -46,7 +46,7 @@ var stripEmojis = (text) => {
   ).replace(/\s+/g, " ").trim();
 };
 
-// src/pdf/index.ts
+// src/exporters/pdf/index.ts
 var FONT_BOLD = "Helvetica-Bold";
 var FONT_REGULAR = "Helvetica";
 var COLOR_BLACK = "#000000";
@@ -61,7 +61,7 @@ var PdfExporter = class {
       doc.on("end", () => resolve(Buffer.concat(buffers)));
       doc.on("error", reject);
       try {
-        content.pages.forEach((section, index) => {
+        content.sections.forEach((section, index) => {
           const sanitizedSections = this.sanitizeSections(section);
           if (index > 0) {
             doc.addPage();

package/dist/exporters/pdf/index.d.cts

@@ -0,0 +1,18 @@
+import { E as ExportTable, a as ExportFilter, b as ExportTableColumn } from '../../types-BzLsgnfc.cjs';
+
+interface PdfSection {
+    table?: ExportTable;
+    filters?: ExportFilter[];
+}
+declare class PdfExporter {
+    generate(content: {
+        sections: PdfSection[];
+    }): Promise<Buffer>;
+    private sanitizeSections;
+    drawFilters(doc: PDFKit.PDFDocument, filters: ExportFilter[]): number;
+    drawTable(doc: PDFKit.PDFDocument, table: ExportTable, startY?: number): void;
+    drawHeader(doc: PDFKit.PDFDocument, columns: ExportTableColumn[], startY: number, tableWidth: number, headerHeight: number, cellPadding: number, headerFontSize: number, minColumnWidth: number): number;
+    drawRow(doc: PDFKit.PDFDocument, row: Record<string, unknown>, rowIndex: number, columns: ExportTableColumn[], currentY: number, tableWidth: number, rowHeight: number, cellPadding: number, dataFontSize: number, minColumnWidth: number): number;
+}
+
+export { PdfExporter, ExportFilter as PdfFilter, type PdfSection, ExportTable as PdfTable, ExportTableColumn as PdfTableColumn };

package/dist/exporters/pdf/index.d.ts

@@ -0,0 +1,18 @@
+import { E as ExportTable, a as ExportFilter, b as ExportTableColumn } from '../../types-BzLsgnfc.js';
+
+interface PdfSection {
+    table?: ExportTable;
+    filters?: ExportFilter[];
+}
+declare class PdfExporter {
+    generate(content: {
+        sections: PdfSection[];
+    }): Promise<Buffer>;
+    private sanitizeSections;
+    drawFilters(doc: PDFKit.PDFDocument, filters: ExportFilter[]): number;
+    drawTable(doc: PDFKit.PDFDocument, table: ExportTable, startY?: number): void;
+    drawHeader(doc: PDFKit.PDFDocument, columns: ExportTableColumn[], startY: number, tableWidth: number, headerHeight: number, cellPadding: number, headerFontSize: number, minColumnWidth: number): number;
+    drawRow(doc: PDFKit.PDFDocument, row: Record<string, unknown>, rowIndex: number, columns: ExportTableColumn[], currentY: number, tableWidth: number, rowHeight: number, cellPadding: number, dataFontSize: number, minColumnWidth: number): number;
+}
+
+export { PdfExporter, ExportFilter as PdfFilter, type PdfSection, ExportTable as PdfTable, ExportTableColumn as PdfTableColumn };

package/dist/{pdf → exporters/pdf}/index.js

@@ -1,7 +1,7 @@
-// src/pdf/index.ts
+// src/exporters/pdf/index.ts
 import PDFDocument from "pdfkit";
 
-// src/pdf/pdf.utils.ts
+// src/exporters/pdf/pdf.utils.ts
 var stripEmojis = (text) => {
   if (!text) {
     return text;
@@ -12,7 +12,7 @@ var stripEmojis = (text) => {
   ).replace(/\s+/g, " ").trim();
 };
 
-// src/pdf/index.ts
+// src/exporters/pdf/index.ts
 var FONT_BOLD = "Helvetica-Bold";
 var FONT_REGULAR = "Helvetica";
 var COLOR_BLACK = "#000000";
@@ -27,7 +27,7 @@ var PdfExporter = class {
       doc.on("end", () => resolve(Buffer.concat(buffers)));
       doc.on("error", reject);
       try {
-        content.pages.forEach((section, index) => {
+        content.sections.forEach((section, index) => {
           const sanitizedSections = this.sanitizeSections(section);
           if (index > 0) {
             doc.addPage();