@eztrak/shared 0.17.1 → 0.19.0

package/dist/components/index.mjs

@@ -28,8 +28,8 @@ import {
   TooltipText,
   dropdownStyles,
   resolveActions
-} from "../chunk-4ASJWHN3.mjs";
-import "../chunk-QOYMQFOB.mjs";
+} from "../chunk-2KXV5C3X.mjs";
+import "../chunk-A5Y5QGVL.mjs";
 export {
   ActionMenuItem,
   Breadcrumbs,

package/dist/excel/index.d.mts

@@ -0,0 +1,146 @@
+type ExcelAlign = "left" | "center" | "right";
+/** Per-column Excel colors. Hex is RRGGBB; a leading # is accepted. */
+type ExcelColumnStyle = {
+    headerFill?: string;
+    headerColor?: string;
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    align?: ExcelAlign;
+    /** Excel number format, for example '"$"#,##0.00'. */
+    numFmt?: string;
+};
+type ExcelTheme = {
+    headerFill?: string;
+    headerColor?: string;
+    fill?: string;
+    color?: string;
+    borderColor?: string;
+    fontName?: string;
+    fontSize?: number;
+};
+type ExcelFormatParams = {
+    value: unknown;
+    data: Record<string, unknown>;
+};
+type ExcelExportColumn = {
+    field?: string;
+    headerName?: string;
+    children?: ExcelExportColumn[];
+    hide?: boolean;
+    checkboxSelection?: boolean;
+    headerCheckboxSelection?: boolean;
+    valueFormatter?: (params: ExcelFormatParams) => unknown;
+    format?: (params: ExcelFormatParams) => unknown;
+    excel?: ExcelColumnStyle;
+};
+type ExportExcelErrorCode = "empty" | "invalid" | "no-columns" | "filename" | "write";
+type ExportExcelFailure = {
+    ok: false;
+    code: ExportExcelErrorCode;
+    error: string;
+};
+type ExportExcelReportResult = {
+    ok: true;
+    fileName: string;
+} | ExportExcelFailure;
+type ExportExcelReportOptions = {
+    data?: unknown[] | null;
+    fileName?: string;
+    columns?: ExcelExportColumn[];
+    sheetName?: string;
+    theme?: ExcelTheme;
+    /** Drop columns with hide: true. Default false, matching vault grids. */
+    skipHidden?: boolean;
+    /**
+     * Format leaf fields whose name contains "date" when they have no formatter.
+     * Vault turns this on and passes its own date formatter.
+     */
+    formatDateFields?: boolean;
+    formatDate?: (value: unknown) => unknown;
+    /**
+     * Date suffix for the file name. Omit to use the local YYYY-MM-DD.
+     * Pass null when the caller could not produce a stamp.
+     */
+    dateStamp?: string | null;
+};
+type ResolvedTheme = {
+    headerFill: string;
+    headerColor: string;
+    fill: string;
+    color: string;
+    borderColor: string;
+    fontName: string;
+    fontSize: number;
+};
+type ExcelCellStyle = {
+    font: {
+        name: string;
+        sz: number;
+        bold?: boolean;
+        color: {
+            rgb: string;
+        };
+    };
+    fill: {
+        patternType: "solid";
+        fgColor: {
+            rgb: string;
+        };
+    };
+    alignment: {
+        vertical: "center";
+        horizontal: ExcelAlign;
+        wrapText: false;
+    };
+    border: {
+        top: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        bottom: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        left: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        right: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+    };
+    numFmt?: string;
+};
+type WorkBook = {
+    SheetNames: string[];
+    Sheets: Record<string, WorkSheet>;
+};
+type WorkSheet = Record<string, unknown>;
+declare const DEFAULT_EXCEL_THEME: ResolvedTheme;
+declare const excelHeaderStyle: (theme?: ExcelTheme, column?: ExcelColumnStyle) => ExcelCellStyle;
+declare const excelDataStyle: (theme?: ExcelTheme, column?: ExcelColumnStyle) => ExcelCellStyle;
+type BuiltExcelWorkbook = {
+    ok: true;
+    workbook: WorkBook;
+    fileName: string;
+    sheetName: string;
+} | ExportExcelFailure;
+/**
+ * Build a styled workbook. Does not write a file.
+ * Header merges follow the column tree, so two groups with the same title stay separate.
+ */
+declare const buildExcelWorkbook: (options?: ExportExcelReportOptions) => BuiltExcelWorkbook;
+/** Write a styled .xlsx. Returns a result; it does not toast. */
+declare const exportExcelReport: (options?: ExportExcelReportOptions) => ExportExcelReportResult;
+
+export { type BuiltExcelWorkbook, DEFAULT_EXCEL_THEME, type ExcelAlign, type ExcelCellStyle, type ExcelColumnStyle, type ExcelExportColumn, type ExcelFormatParams, type ExcelTheme, type ExportExcelErrorCode, type ExportExcelFailure, type ExportExcelReportOptions, type ExportExcelReportResult, buildExcelWorkbook, excelDataStyle, excelHeaderStyle, exportExcelReport };

package/dist/excel/index.d.ts

@@ -0,0 +1,146 @@
+type ExcelAlign = "left" | "center" | "right";
+/** Per-column Excel colors. Hex is RRGGBB; a leading # is accepted. */
+type ExcelColumnStyle = {
+    headerFill?: string;
+    headerColor?: string;
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    align?: ExcelAlign;
+    /** Excel number format, for example '"$"#,##0.00'. */
+    numFmt?: string;
+};
+type ExcelTheme = {
+    headerFill?: string;
+    headerColor?: string;
+    fill?: string;
+    color?: string;
+    borderColor?: string;
+    fontName?: string;
+    fontSize?: number;
+};
+type ExcelFormatParams = {
+    value: unknown;
+    data: Record<string, unknown>;
+};
+type ExcelExportColumn = {
+    field?: string;
+    headerName?: string;
+    children?: ExcelExportColumn[];
+    hide?: boolean;
+    checkboxSelection?: boolean;
+    headerCheckboxSelection?: boolean;
+    valueFormatter?: (params: ExcelFormatParams) => unknown;
+    format?: (params: ExcelFormatParams) => unknown;
+    excel?: ExcelColumnStyle;
+};
+type ExportExcelErrorCode = "empty" | "invalid" | "no-columns" | "filename" | "write";
+type ExportExcelFailure = {
+    ok: false;
+    code: ExportExcelErrorCode;
+    error: string;
+};
+type ExportExcelReportResult = {
+    ok: true;
+    fileName: string;
+} | ExportExcelFailure;
+type ExportExcelReportOptions = {
+    data?: unknown[] | null;
+    fileName?: string;
+    columns?: ExcelExportColumn[];
+    sheetName?: string;
+    theme?: ExcelTheme;
+    /** Drop columns with hide: true. Default false, matching vault grids. */
+    skipHidden?: boolean;
+    /**
+     * Format leaf fields whose name contains "date" when they have no formatter.
+     * Vault turns this on and passes its own date formatter.
+     */
+    formatDateFields?: boolean;
+    formatDate?: (value: unknown) => unknown;
+    /**
+     * Date suffix for the file name. Omit to use the local YYYY-MM-DD.
+     * Pass null when the caller could not produce a stamp.
+     */
+    dateStamp?: string | null;
+};
+type ResolvedTheme = {
+    headerFill: string;
+    headerColor: string;
+    fill: string;
+    color: string;
+    borderColor: string;
+    fontName: string;
+    fontSize: number;
+};
+type ExcelCellStyle = {
+    font: {
+        name: string;
+        sz: number;
+        bold?: boolean;
+        color: {
+            rgb: string;
+        };
+    };
+    fill: {
+        patternType: "solid";
+        fgColor: {
+            rgb: string;
+        };
+    };
+    alignment: {
+        vertical: "center";
+        horizontal: ExcelAlign;
+        wrapText: false;
+    };
+    border: {
+        top: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        bottom: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        left: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+        right: {
+            style: "thin";
+            color: {
+                rgb: string;
+            };
+        };
+    };
+    numFmt?: string;
+};
+type WorkBook = {
+    SheetNames: string[];
+    Sheets: Record<string, WorkSheet>;
+};
+type WorkSheet = Record<string, unknown>;
+declare const DEFAULT_EXCEL_THEME: ResolvedTheme;
+declare const excelHeaderStyle: (theme?: ExcelTheme, column?: ExcelColumnStyle) => ExcelCellStyle;
+declare const excelDataStyle: (theme?: ExcelTheme, column?: ExcelColumnStyle) => ExcelCellStyle;
+type BuiltExcelWorkbook = {
+    ok: true;
+    workbook: WorkBook;
+    fileName: string;
+    sheetName: string;
+} | ExportExcelFailure;
+/**
+ * Build a styled workbook. Does not write a file.
+ * Header merges follow the column tree, so two groups with the same title stay separate.
+ */
+declare const buildExcelWorkbook: (options?: ExportExcelReportOptions) => BuiltExcelWorkbook;
+/** Write a styled .xlsx. Returns a result; it does not toast. */
+declare const exportExcelReport: (options?: ExportExcelReportOptions) => ExportExcelReportResult;
+
+export { type BuiltExcelWorkbook, DEFAULT_EXCEL_THEME, type ExcelAlign, type ExcelCellStyle, type ExcelColumnStyle, type ExcelExportColumn, type ExcelFormatParams, type ExcelTheme, type ExportExcelErrorCode, type ExportExcelFailure, type ExportExcelReportOptions, type ExportExcelReportResult, buildExcelWorkbook, excelDataStyle, excelHeaderStyle, exportExcelReport };

package/dist/excel/index.js

@@ -0,0 +1,355 @@
+"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/excel/index.ts
+var excel_exports = {};
+__export(excel_exports, {
+  DEFAULT_EXCEL_THEME: () => DEFAULT_EXCEL_THEME,
+  buildExcelWorkbook: () => buildExcelWorkbook,
+  excelDataStyle: () => excelDataStyle,
+  excelHeaderStyle: () => excelHeaderStyle,
+  exportExcelReport: () => exportExcelReport
+});
+module.exports = __toCommonJS(excel_exports);
+var XLSX = __toESM(require("xlsx-js-style"));
+var ERRORS = {
+  empty: "No valid data to download. Please ensure data is available.",
+  invalid: "Invalid data structure. Please ensure data is correctly formatted.",
+  "no-columns": "No data to export. Please check the data source.",
+  filename: "Failed to generate file name. Please try again."
+};
+var DEFAULT_EXCEL_THEME = {
+  headerFill: "2F75B6",
+  headerColor: "FFFFFF",
+  fill: "FFFFFF",
+  color: "1F2933",
+  borderColor: "8FA4BF",
+  fontName: "Calibri",
+  fontSize: 11
+};
+var fail = (code) => ({
+  ok: false,
+  code,
+  error: ERRORS[code]
+});
+var rgb = (input, fallback) => {
+  if (!input) return fallback;
+  const hex = input.trim().replace(/^#/, "").toUpperCase();
+  return /^[0-9A-F]{6}$/.test(hex) ? hex : fallback;
+};
+var resolveTheme = (theme) => ({
+  headerFill: rgb(theme?.headerFill, DEFAULT_EXCEL_THEME.headerFill),
+  headerColor: rgb(theme?.headerColor, DEFAULT_EXCEL_THEME.headerColor),
+  fill: rgb(theme?.fill, DEFAULT_EXCEL_THEME.fill),
+  color: rgb(theme?.color, DEFAULT_EXCEL_THEME.color),
+  borderColor: rgb(theme?.borderColor, DEFAULT_EXCEL_THEME.borderColor),
+  fontName: theme?.fontName?.trim() || DEFAULT_EXCEL_THEME.fontName,
+  fontSize: typeof theme?.fontSize === "number" && theme.fontSize > 0 ? theme.fontSize : DEFAULT_EXCEL_THEME.fontSize
+});
+var gridBorder = (color) => {
+  const edge = () => ({ style: "thin", color: { rgb: color } });
+  return { top: edge(), bottom: edge(), left: edge(), right: edge() };
+};
+var excelHeaderStyle = (theme, column) => {
+  const resolved = resolveTheme(theme);
+  return {
+    font: {
+      name: resolved.fontName,
+      sz: resolved.fontSize,
+      bold: true,
+      color: { rgb: rgb(column?.headerColor, resolved.headerColor) }
+    },
+    fill: {
+      patternType: "solid",
+      fgColor: { rgb: rgb(column?.headerFill, resolved.headerFill) }
+    },
+    alignment: {
+      vertical: "center",
+      horizontal: column?.align ?? "left",
+      wrapText: false
+    },
+    border: gridBorder(resolved.borderColor)
+  };
+};
+var excelDataStyle = (theme, column) => {
+  const resolved = resolveTheme(theme);
+  const font = {
+    name: resolved.fontName,
+    sz: resolved.fontSize,
+    color: { rgb: rgb(column?.color, resolved.color) }
+  };
+  if (column?.bold) font.bold = true;
+  const style = {
+    font,
+    fill: {
+      patternType: "solid",
+      fgColor: { rgb: rgb(column?.fill, resolved.fill) }
+    },
+    alignment: {
+      vertical: "center",
+      horizontal: column?.align ?? "left",
+      wrapText: false
+    },
+    border: gridBorder(resolved.borderColor)
+  };
+  if (column?.numFmt) style.numFmt = column.numFmt;
+  return style;
+};
+var getNestedValue = (obj, path) => {
+  if (!obj || typeof obj !== "object") return "";
+  try {
+    const value = path.split(".").reduce((acc, key) => {
+      if (acc == null || typeof acc !== "object") return void 0;
+      return acc[key];
+    }, obj);
+    return value ?? "";
+  } catch {
+    return "";
+  }
+};
+var isGroup = (col) => Array.isArray(col.children) && col.children.length > 0;
+var isSkippedLeaf = (col) => {
+  if (col.checkboxSelection || col.headerCheckboxSelection) return true;
+  const field = typeof col.field === "string" ? col.field.trim() : "";
+  return !field || field === "checkbox" || field === "checkboxSelection";
+};
+var collectLeaves = (cols, groups, skipHidden) => {
+  const leaves = [];
+  cols.forEach((col) => {
+    if (!col || typeof col !== "object") return;
+    if (skipHidden && col.hide) return;
+    if (isGroup(col)) {
+      const group = {
+        name: col.headerName || "",
+        excel: col.excel
+      };
+      leaves.push(...collectLeaves(col.children ?? [], [...groups, group], skipHidden));
+      return;
+    }
+    if (isSkippedLeaf(col)) return;
+    const field = col.field.trim();
+    leaves.push({
+      field,
+      headerName: (col.headerName || field).trim() || field,
+      column: col,
+      groups
+    });
+  });
+  return leaves;
+};
+var labelFromKey = (key) => key.replace(/([A-Z])/g, " $1").replace(/^\w/, (char) => char.toUpperCase()).trim();
+var columnsFromRows = (rows) => {
+  const first = rows[0];
+  if (!first || typeof first !== "object" || Array.isArray(first)) {
+    return fail("invalid");
+  }
+  return Object.keys(first).filter((key) => key !== "checkbox" && key !== "checkboxSelection" && key.trim()).map((key) => ({ field: key, headerName: labelFromKey(key) }));
+};
+var formatLeafValue = (row, leaf, options) => {
+  let value = getNestedValue(row, leaf.field);
+  const formatter = leaf.column.format || leaf.column.valueFormatter;
+  if (typeof formatter === "function") {
+    try {
+      return formatter({ value, data: row }) ?? "";
+    } catch {
+      return value ?? "";
+    }
+  }
+  const fieldLooksLikeDate = leaf.field.toLowerCase().includes("date");
+  if (options.formatDateFields && fieldLooksLikeDate && typeof options.formatDate === "function") {
+    try {
+      return options.formatDate(value) ?? "";
+    } catch {
+      return value ?? "";
+    }
+  }
+  if (value instanceof Date) return value;
+  if (value != null && typeof value === "object") return "";
+  const numFmt = leaf.column.excel?.numFmt;
+  if (numFmt) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) {
+      return Number(value);
+    }
+  }
+  return value ?? "";
+};
+var localDateStamp = () => {
+  const date = /* @__PURE__ */ new Date();
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+};
+var resolveDateStamp = (dateStamp) => {
+  if (dateStamp === null) return null;
+  if (typeof dateStamp === "string" && dateStamp.trim()) return dateStamp.trim();
+  return localDateStamp();
+};
+var safeSheetName = (name) => {
+  const cleaned = (name || "Report").replace(/[:\\/?*[\]]/g, " ").trim() || "Report";
+  return cleaned.slice(0, 31);
+};
+var buildHeaderGrid = (leaves) => {
+  const totalHeaderRows = Math.max(...leaves.map((leaf) => leaf.groups.length + 1), 1);
+  const headerRows = Array.from(
+    { length: totalHeaderRows },
+    () => Array.from({ length: leaves.length }, () => "")
+  );
+  const merges = [];
+  for (let depth = 0; depth < totalHeaderRows - 1; depth += 1) {
+    let colIndex = 0;
+    while (colIndex < leaves.length) {
+      const group = leaves[colIndex].groups[depth];
+      if (!group) {
+        colIndex += 1;
+        continue;
+      }
+      let span = 1;
+      while (colIndex + span < leaves.length && leaves[colIndex + span].groups[depth] === group) {
+        span += 1;
+      }
+      headerRows[depth][colIndex] = group.name;
+      if (span > 1) {
+        merges.push({
+          s: { r: depth, c: colIndex },
+          e: { r: depth, c: colIndex + span - 1 }
+        });
+      }
+      colIndex += span;
+    }
+  }
+  leaves.forEach((leaf, colIndex) => {
+    const row = leaf.groups.length;
+    headerRows[row][colIndex] = leaf.headerName;
+    if (row < totalHeaderRows - 1) {
+      merges.push({
+        s: { r: row, c: colIndex },
+        e: { r: totalHeaderRows - 1, c: colIndex }
+      });
+    }
+  });
+  return { headerRows, merges, totalHeaderRows };
+};
+var headerStyleFor = (leaf, row, theme) => {
+  const source = row < leaf.groups.length ? leaf.groups[row].excel : leaf.column.excel;
+  return excelHeaderStyle(theme, source);
+};
+var columnWidth = (leaf, values) => {
+  const headerLength = Math.max(
+    leaf.headerName.length,
+    ...leaf.groups.map((group) => group.name.length),
+    0
+  );
+  const dataLength = values.reduce((max, value) => {
+    return Math.max(max, String(value ?? "").length);
+  }, 0);
+  return { wch: Math.min(Math.max(headerLength, dataLength, 12), 50) };
+};
+var buildExcelWorkbook = (options = {}) => {
+  const data = options.data;
+  if (!Array.isArray(data) || data.length === 0) return fail("empty");
+  const provided = Array.isArray(options.columns) ? options.columns : [];
+  const columns = provided.length ? provided : columnsFromRows(data);
+  if (!Array.isArray(columns)) return columns;
+  const leaves = collectLeaves(columns, [], options.skipHidden === true);
+  if (!leaves.length) return fail("no-columns");
+  const dateStamp = resolveDateStamp(options.dateStamp);
+  if (!dateStamp) return fail("filename");
+  const { headerRows, merges, totalHeaderRows } = buildHeaderGrid(leaves);
+  const records = data.map(
+    (row) => row && typeof row === "object" && !Array.isArray(row) ? row : {}
+  );
+  const dataRows = records.map(
+    (row) => leaves.map((leaf) => formatLeafValue(row, leaf, options))
+  );
+  const sheet = XLSX.utils.aoa_to_sheet([...headerRows, ...dataRows]);
+  const lastCell = XLSX.utils.encode_cell({
+    r: headerRows.length + dataRows.length - 1,
+    c: leaves.length - 1
+  });
+  sheet["!ref"] = `A1:${lastCell}`;
+  sheet["!merges"] = merges;
+  sheet["!cols"] = leaves.map(
+    (leaf, index) => columnWidth(
+      leaf,
+      dataRows.map((row) => row[index])
+    )
+  );
+  sheet["!rows"] = Array.from({ length: totalHeaderRows }, () => ({ hpt: 22 }));
+  const range = XLSX.utils.decode_range(sheet["!ref"]);
+  for (let row = range.s.r; row <= range.e.r; row += 1) {
+    for (let col = range.s.c; col <= range.e.c; col += 1) {
+      const address = XLSX.utils.encode_cell({ r: row, c: col });
+      const cell = sheet[address] ?? {
+        t: "s",
+        v: ""
+      };
+      const leaf = leaves[col];
+      if (row < totalHeaderRows) {
+        cell.s = headerStyleFor(leaf, row, options.theme);
+      } else {
+        const style = excelDataStyle(options.theme, leaf.column.excel);
+        if (leaf.column.excel?.numFmt) cell.z = leaf.column.excel.numFmt;
+        cell.s = style;
+      }
+      sheet[address] = cell;
+    }
+  }
+  const sheetName = safeSheetName(options.sheetName);
+  const workbook = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(workbook, sheet, sheetName);
+  const baseName = options.fileName == null ? "" : String(options.fileName);
+  return {
+    ok: true,
+    workbook,
+    sheetName,
+    fileName: `${baseName ? `${baseName}_` : ""}${dateStamp}.xlsx`
+  };
+};
+var exportExcelReport = (options = {}) => {
+  const built = buildExcelWorkbook(options);
+  if (!built.ok) return built;
+  try {
+    XLSX.writeFile(built.workbook, built.fileName, { cellStyles: true });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return { ok: false, code: "write", error: message };
+  }
+  return { ok: true, fileName: built.fileName };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_EXCEL_THEME,
+  buildExcelWorkbook,
+  excelDataStyle,
+  excelHeaderStyle,
+  exportExcelReport
+});
+//# sourceMappingURL=index.js.map