feat(export): support name and comment XLSX headers

apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments } from "../xlsxHeader";
+
+describe("xlsxHeader", () => {
+  it("builds comment-only and combined header overrides", () => {
+    const columns = ["id", "name", "created_at"];
+    const comments = [" Identifier ", "", undefined];
+
+    expect(buildXlsxHeaderOverrides(columns, comments, "comment")).toEqual(["Identifier", null, null]);
+    expect(buildXlsxHeaderOverrides(columns, comments, "name-comment")).toEqual(["id (Identifier)", null, null]);
+  });
+
+  it("keeps name mode and comment-less exports on the original headers", () => {
+    expect(buildXlsxHeaderOverrides(["id"], ["Identifier"], "name")).toBeUndefined();
+    expect(buildXlsxHeaderOverrides(["id"], ["  "], "name-comment")).toBeUndefined();
+    expect(hasXlsxHeaderComments([undefined, "  ", "Name"])).toBe(true);
+    expect(hasXlsxHeaderComments([undefined, "  "])).toBe(false);
+  });
+});

apps/desktop/src/lib/export/xlsxHeader.ts

@@ -0,0 +1,17 @@
+export type XlsxHeaderMode = "name" | "comment" | "name-comment";
+
+export function hasXlsxHeaderComments(comments: readonly (string | null | undefined)[] | undefined): boolean {
+  return comments?.some((comment) => !!comment?.trim()) ?? false;
+}
+
+export function buildXlsxHeaderOverrides(columns: readonly string[], comments: readonly (string | null | undefined)[] | undefined, mode: XlsxHeaderMode): (string | null)[] | undefined {
+  if (mode === "name") return undefined;
+
+  const overrides = columns.map((column, index) => {
+    const comment = comments?.[index]?.trim();
+    if (!comment) return null;
+    return mode === "comment" ? comment : `${column} (${comment})`;
+  });
+
+  return overrides.some((header) => header !== null) ? overrides : undefined;
+}