@jielga/tmdatagrid-xlsx 2.0.0-beta.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jielga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @jielga/tmdatagrid-xlsx
+
+Excel (xlsx) export format for [@jielga/tmdatagrid](https://www.npmjs.com/package/@jielga/tmdatagrid), on [exceljs](https://www.npmjs.com/package/exceljs).
+
+- Documentation: <https://jielga.github.io/TMDataGrid/docs/xlsx>
+- Source, issues and the contributor guide: <https://github.com/Jielga/TMDataGrid>
+
+```sh
+bun add @jielga/tmdatagrid-xlsx
+```
+
+```sh
+npm install @jielga/tmdatagrid-xlsx
+```
+
+`xlsxFormat()` is a `TMDataGridExportFormat`, so it goes wherever the grid takes one:
+
+```tsx
+import { useTMDataGrid } from "@jielga/tmdatagrid";
+import { xlsxFormat } from "@jielga/tmdatagrid-xlsx";
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: xlsxFormat() },
+});
+```
+
+Numbers, dates and booleans arrive as typed cells, so nothing depends on the reader's locale.
+
+See [docs/xlsx.md](docs/xlsx.md) for the options and the cell typing.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { TMDataGridExportFormat } from "@jielga/tmdatagrid";
+//#region .types-tmp/xlsxFormat.d.ts
+type TMDataGridXlsxFormatOptions = {
+  /** Worksheet name. Defaults to `"Sheet1"`. */
+  sheetName?: string;
+  /** Column widths from the longest text in each column, capped at 60 characters. Defaults to `true`. */
+  autoWidth?: boolean;
+};
+/**
+ * A real Excel workbook rather than a CSV that Excel can open.
+ *
+ * That is the whole reason the format exists: a typed cell needs no separator,
+ * no decimal mark and no BOM to survive the trip, so nothing depends on the
+ * reader's locale. Numbers arrive as numbers, dates as dates with a number
+ * format, booleans as booleans, and a text cell can hold a semicolon or a
+ * newline without ending the row.
+ *
+ * `exceljs` is why this is a separate package: it is a large dependency, and a
+ * grid that exports CSV should not carry a spreadsheet writer.
+ */
+declare function xlsxFormat({ sheetName, autoWidth }?: TMDataGridXlsxFormatOptions): TMDataGridExportFormat;
+//#endregion
+export { type TMDataGridXlsxFormatOptions, xlsxFormat };

package/dist/index.js

@@ -0,0 +1,59 @@
+import e from "exceljs";
+//#region src/xlsxFormat.ts
+var t = 60, n = 10, r = 2, i = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+function a(e) {
+	return e.getHours() === 0 && e.getMinutes() === 0 && e.getSeconds() === 0 && e.getMilliseconds() === 0;
+}
+function o(e) {
+	return a(e) ? "yyyy-mm-dd" : "yyyy-mm-dd hh:mm";
+}
+function s(e) {
+	let t = e.toLocaleString("sv-SE");
+	return a(e) ? t.slice(0, 10) : t.slice(0, 16);
+}
+function c(e) {
+	if (e == null) return "";
+	if (typeof e == "number") return Number.isFinite(e) ? String(e) : "";
+	if (typeof e == "string") return e;
+	if (typeof e == "boolean") return e ? "true" : "false";
+	if (e instanceof Date) return Number.isNaN(e.getTime()) ? "" : s(e);
+	if (Array.isArray(e)) return e.map((e) => c(e)).join(", ");
+	if (typeof e == "object") try {
+		return JSON.stringify(e);
+	} catch {
+		return "";
+	}
+	return String(e);
+}
+function l(e) {
+	return e == null ? null : typeof e == "number" ? Number.isFinite(e) ? e : null : e instanceof Date ? Number.isNaN(e.getTime()) ? null : e : typeof e == "boolean" ? e : c(e);
+}
+function u({ sheetName: a = "Sheet1", autoWidth: s = !0 } = {}) {
+	return {
+		id: "xlsx",
+		extension: "xlsx",
+		mimeType: i,
+		write: async (u, { includeHeaders: d }) => {
+			let f = new e.Workbook(), p = f.addWorksheet(a), m = u.headers.map((e) => d ? e.length : 0);
+			if (d) {
+				let e = p.addRow(u.headers);
+				e.font = { bold: !0 };
+			}
+			for (let e of u.rows) {
+				let t = p.addRow(e.map((e) => l(e)));
+				e.forEach((e, n) => {
+					e instanceof Date && !Number.isNaN(e.getTime()) && (t.getCell(n + 1).numFmt = o(e));
+					let r = c(e).length;
+					r > (m[n] ?? 0) && (m[n] = r);
+				});
+			}
+			return s && m.forEach((e, i) => {
+				p.getColumn(i + 1).width = Math.min(t, Math.max(n, e + r));
+			}), new Blob([await f.xlsx.writeBuffer()], { type: i });
+		}
+	};
+}
+//#endregion
+export { u as xlsxFormat };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/xlsxFormat.ts"],"sourcesContent":["import ExcelJS from \"exceljs\";\r\nimport type {\r\n  TMDataGridExportData,\r\n  TMDataGridExportFormat,\r\n  TMDataGridExportWriteOptions,\r\n} from \"@jielga/tmdatagrid\";\r\n\r\n/**\r\n * How wide a column may get from `autoWidth`. A long free-text cell would\r\n * otherwise push a column past the width of the window, and a column nobody\r\n * can see past is worse than one that clips.\r\n */\r\nconst MAX_COLUMN_WIDTH = 60;\r\n\r\n/** Narrow columns still need room for their header and the filter arrow. */\r\nconst MIN_COLUMN_WIDTH = 10;\r\n\r\n/** Excel measures a column in characters, and a cell needs a little padding. */\r\nconst WIDTH_PADDING = 2;\r\n\r\nconst MIME_TYPE =\r\n  \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\";\r\n\r\n/** A date at midnight is a date; anything else is a moment in time. */\r\nfunction isMidnight(value: Date): boolean {\r\n  return (\r\n    value.getHours() === 0 &&\r\n    value.getMinutes() === 0 &&\r\n    value.getSeconds() === 0 &&\r\n    value.getMilliseconds() === 0\r\n  );\r\n}\r\n\r\nfunction dateNumberFormat(value: Date): string {\r\n  return isMidnight(value) ? \"yyyy-mm-dd\" : \"yyyy-mm-dd hh:mm\";\r\n}\r\n\r\n/** The date as its number format renders it, for a width and for a joined array. */\r\nfunction dateText(value: Date): string {\r\n  const text = value.toLocaleString(\"sv-SE\");\r\n  return isMidnight(value) ? text.slice(0, 10) : text.slice(0, 16);\r\n}\r\n\r\n/**\r\n * A value as text, for the cells a spreadsheet has no type for and for the\r\n * width measurement.\r\n *\r\n * Deliberately not `formatExportValue` from the grid: that one writes a\r\n * decimal comma and an `sv-SE` date, both of which would be wrong here. A\r\n * typed cell carries the value itself and Excel renders it in the reader's own\r\n * locale, so only the untypable values reach this.\r\n */\r\nfunction cellText(value: unknown): string {\r\n  if (value === null || value === undefined) return \"\";\r\n  if (typeof value === \"number\") return Number.isFinite(value) ? String(value) : \"\";\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (value instanceof Date) {\r\n    return Number.isNaN(value.getTime()) ? \"\" : dateText(value);\r\n  }\r\n  // A multiSelect cell holds an array of values; a spreadsheet cell holds one\r\n  // string, so the elements are joined the way they read on screen.\r\n  if (Array.isArray(value)) {\r\n    return value.map((entry) => cellText(entry)).join(\", \");\r\n  }\r\n  // An object in a cell is a shape the addon cannot know. JSON at least keeps\r\n  // what was there, where `String(value)` would write \"[object Object]\".\r\n  if (typeof value === \"object\") {\r\n    try {\r\n      return JSON.stringify(value);\r\n    } catch {\r\n      return \"\";\r\n    }\r\n  }\r\n  return String(value);\r\n}\r\n\r\n/**\r\n * What goes into the worksheet cell: a number, a date, a boolean or a string.\r\n *\r\n * `null` for everything empty, which is what exceljs writes as a blank cell -\r\n * an empty string would be a cell holding text of length zero, and a formula\r\n * counting it would count it.\r\n */\r\nfunction cellValue(value: unknown): number | Date | boolean | string | null {\r\n  if (value === null || value === undefined) return null;\r\n  if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\r\n  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;\r\n  if (typeof value === \"boolean\") return value;\r\n  return cellText(value);\r\n}\r\n\r\nexport type TMDataGridXlsxFormatOptions = {\r\n  /** Worksheet name. Defaults to `\"Sheet1\"`. */\r\n  sheetName?: string;\r\n  /** Column widths from the longest text in each column, capped at 60 characters. Defaults to `true`. */\r\n  autoWidth?: boolean;\r\n};\r\n\r\n/**\r\n * A real Excel workbook rather than a CSV that Excel can open.\r\n *\r\n * That is the whole reason the format exists: a typed cell needs no separator,\r\n * no decimal mark and no BOM to survive the trip, so nothing depends on the\r\n * reader's locale. Numbers arrive as numbers, dates as dates with a number\r\n * format, booleans as booleans, and a text cell can hold a semicolon or a\r\n * newline without ending the row.\r\n *\r\n * `exceljs` is why this is a separate package: it is a large dependency, and a\r\n * grid that exports CSV should not carry a spreadsheet writer.\r\n */\r\nexport function xlsxFormat({\r\n  sheetName = \"Sheet1\",\r\n  autoWidth = true,\r\n}: TMDataGridXlsxFormatOptions = {}): TMDataGridExportFormat {\r\n  return {\r\n    id: \"xlsx\",\r\n    extension: \"xlsx\",\r\n    mimeType: MIME_TYPE,\r\n    write: async (\r\n      data: TMDataGridExportData,\r\n      { includeHeaders }: TMDataGridExportWriteOptions,\r\n    ): Promise<Blob> => {\r\n      const workbook = new ExcelJS.Workbook();\r\n      const sheet = workbook.addWorksheet(sheetName);\r\n\r\n      // The longest text seen per column, header included, for `autoWidth`.\r\n      const widths = data.headers.map((header) =>\r\n        includeHeaders ? header.length : 0,\r\n      );\r\n\r\n      if (includeHeaders) {\r\n        const headerRow = sheet.addRow(data.headers);\r\n        headerRow.font = { bold: true };\r\n      }\r\n\r\n      for (const row of data.rows) {\r\n        const added = sheet.addRow(row.map((value) => cellValue(value)));\r\n        row.forEach((value, index) => {\r\n          if (value instanceof Date && !Number.isNaN(value.getTime())) {\r\n            added.getCell(index + 1).numFmt = dateNumberFormat(value);\r\n          }\r\n          const length = cellText(value).length;\r\n          if (length > (widths[index] ?? 0)) widths[index] = length;\r\n        });\r\n      }\r\n\r\n      if (autoWidth) {\r\n        widths.forEach((width, index) => {\r\n          sheet.getColumn(index + 1).width = Math.min(\r\n            MAX_COLUMN_WIDTH,\r\n            Math.max(MIN_COLUMN_WIDTH, width + WIDTH_PADDING),\r\n          );\r\n        });\r\n      }\r\n\r\n      return new Blob([await workbook.xlsx.writeBuffer()], { type: MIME_TYPE });\r\n    },\r\n  };\r\n}\r\n"],"mappings":";;AAYA,IAAM,IAAmB,IAGnB,IAAmB,IAGnB,IAAgB,GAEhB,IACJ;AAGF,SAAS,EAAW,GAAsB;CACxC,OACE,EAAM,SAAS,MAAM,KACrB,EAAM,WAAW,MAAM,KACvB,EAAM,WAAW,MAAM,KACvB,EAAM,gBAAgB,MAAM;AAEhC;AAEA,SAAS,EAAiB,GAAqB;CAC7C,OAAO,EAAW,CAAK,IAAI,eAAe;AAC5C;AAGA,SAAS,EAAS,GAAqB;CACrC,IAAM,IAAO,EAAM,eAAe,OAAO;CACzC,OAAO,EAAW,CAAK,IAAI,EAAK,MAAM,GAAG,EAAE,IAAI,EAAK,MAAM,GAAG,EAAE;AACjE;AAWA,SAAS,EAAS,GAAwB;CACxC,IAAI,KAAU,MAA6B,OAAO;CAClD,IAAI,OAAO,KAAU,UAAU,OAAO,OAAO,SAAS,CAAK,IAAI,OAAO,CAAK,IAAI;CAC/E,IAAI,OAAO,KAAU,UAAU,OAAO;CACtC,IAAI,OAAO,KAAU,WAAW,OAAO,IAAQ,SAAS;CACxD,IAAI,aAAiB,MACnB,OAAO,OAAO,MAAM,EAAM,QAAQ,CAAC,IAAI,KAAK,EAAS,CAAK;CAI5D,IAAI,MAAM,QAAQ,CAAK,GACrB,OAAO,EAAM,KAAK,MAAU,EAAS,CAAK,CAAC,CAAC,CAAC,KAAK,IAAI;CAIxD,IAAI,OAAO,KAAU,UACnB,IAAI;EACF,OAAO,KAAK,UAAU,CAAK;CAC7B,QAAQ;EACN,OAAO;CACT;CAEF,OAAO,OAAO,CAAK;AACrB;AASA,SAAS,EAAU,GAAyD;CAK1E,OAJI,KAAU,OAAoC,OAC9C,OAAO,KAAU,WAAiB,OAAO,SAAS,CAAK,IAAI,IAAQ,OACnE,aAAiB,OAAa,OAAO,MAAM,EAAM,QAAQ,CAAC,IAAI,OAAO,IACrE,OAAO,KAAU,YAAkB,IAChC,EAAS,CAAK;AACvB;AAqBA,SAAgB,EAAW,EACzB,eAAY,UACZ,eAAY,OACmB,CAAC,GAA2B;CAC3D,OAAO;EACL,IAAI;EACJ,WAAW;EACX,UAAU;EACV,OAAO,OACL,GACA,EAAE,wBACgB;GAClB,IAAM,IAAW,IAAI,EAAQ,SAAS,GAChC,IAAQ,EAAS,aAAa,CAAS,GAGvC,IAAS,EAAK,QAAQ,KAAK,MAC/B,IAAiB,EAAO,SAAS,CACnC;GAEA,IAAI,GAAgB;IAClB,IAAM,IAAY,EAAM,OAAO,EAAK,OAAO;IAC3C,EAAU,OAAO,EAAE,MAAM,GAAK;GAChC;GAEA,KAAK,IAAM,KAAO,EAAK,MAAM;IAC3B,IAAM,IAAQ,EAAM,OAAO,EAAI,KAAK,MAAU,EAAU,CAAK,CAAC,CAAC;IAC/D,EAAI,SAAS,GAAO,MAAU;KAC5B,AAAI,aAAiB,QAAQ,CAAC,OAAO,MAAM,EAAM,QAAQ,CAAC,MACxD,EAAM,QAAQ,IAAQ,CAAC,CAAC,CAAC,SAAS,EAAiB,CAAK;KAE1D,IAAM,IAAS,EAAS,CAAK,CAAC,CAAC;KAC/B,AAAI,KAAU,EAAO,MAAU,OAAI,EAAO,KAAS;IACrD,CAAC;GACH;GAWA,OATI,KACF,EAAO,SAAS,GAAO,MAAU;IAC/B,EAAM,UAAU,IAAQ,CAAC,CAAC,CAAC,QAAQ,KAAK,IACtC,GACA,KAAK,IAAI,GAAkB,IAAQ,CAAa,CAClD;GACF,CAAC,GAGI,IAAI,KAAK,CAAC,MAAM,EAAS,KAAK,YAAY,CAAC,GAAG,EAAE,MAAM,EAAU,CAAC;EAC1E;CACF;AACF"}

package/docs/xlsx.md

@@ -0,0 +1,72 @@
+# Excel export (xlsx)
+
+`@jielga/tmdatagrid-xlsx` adds a real Excel workbook to the grid's [export formats](/docs/export).
+It is a separate package because it is built on `exceljs`, and the grid never depends on a spreadsheet writer: a grid that exports CSV should not pay for one.
+
+```sh
+npm install @jielga/tmdatagrid-xlsx
+```
+
+The package declares `@jielga/tmdatagrid` as a peer dependency, so the two versions stay in step.
+
+## xlsxFormat
+
+`xlsxFormat()` returns a `TMDataGridExportFormat`, which is what `exportOptions.format` takes.
+Set it once and every export of that grid writes a workbook.
+
+```tsx
+import { useTMDataGrid } from "@jielga/tmdatagrid";
+import { xlsxFormat } from "@jielga/tmdatagrid-xlsx";
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: xlsxFormat(), fileName: "employees" },
+});
+```
+
+Every `TMDataGrid.Menu.Export` item takes its own `format`, so one menu can offer both.
+The item without a `format` writes the grid's own, the CSV default here.
+
+```tsx
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.Export format={xlsxFormat()} label="Export all rows as xlsx" />
+</TMDataGrid.Menu>
+```
+
+A typed cell needs no separator, no decimal mark and no byte order mark to survive the trip, so an xlsx file reads the same whatever locale the reader's Excel runs.
+That is what it buys over [`csvExcelFormat`](/docs/export).
+
+Values are written like this:
+
+| Value | Cell |
+| --- | --- |
+| `number`, finite | A number cell |
+| `number`, `NaN` or infinite | Empty |
+| `Date` at 00:00:00 | A date cell, number format `yyyy-mm-dd` |
+| `Date` with a time | A date cell, number format `yyyy-mm-dd hh:mm` |
+| `Date`, invalid | Empty |
+| `boolean` | A boolean cell |
+| `string` | Text |
+| `null`, `undefined` | Empty |
+| Array | Its elements as text, joined with `, ` |
+| Any other object | `JSON.stringify` of it, empty when that throws |
+
+`includeHeaders` writes the column labels as a bold first row.
+It defaults to `true`, and `exportOptions.includeHeaders` is where you turn it off.
+
+The format's `write` is async and answers a `Blob`.
+Safari refuses a download that starts after the click gesture has ended, so a grid of hundreds of thousands of rows may need its own button rather than the menu item.
+
+```demo
+file: data/ExportXlsx.tsx
+hint: The grid menu has an xlsx item beside the CSV one.
+```
+
+## Options
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `sheetName` | `string` | `"Sheet1"` | The worksheet's name. |
+| `autoWidth` | `boolean` | `true` | Sets each column's width from its longest text, header included, between 10 and 60 characters. Off leaves the widths unset, and Excel uses its own default. |

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jielga/tmdatagrid-xlsx",
+  "version": "2.0.0-beta.14",
+  "description": "Excel (xlsx) export format for @jielga/tmdatagrid, on exceljs.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jielga/TMDataGrid.git",
+    "directory": "packages/tmdatagrid-xlsx"
+  },
+  "homepage": "https://jielga.github.io/TMDataGrid/",
+  "bugs": {
+    "url": "https://github.com/Jielga/TMDataGrid/issues"
+  },
+  "keywords": [
+    "react",
+    "datagrid",
+    "excel",
+    "xlsx",
+    "export",
+    "tanstack-intent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "intent": {
+    "docs": "docs/"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*",
+    "docs",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./docs/*": "./docs/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && rolldown -c rolldown.dts.config.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "oxlint && bun run build"
+  },
+  "peerDependencies": {
+    "@jielga/tmdatagrid": "^2.0.0-beta.14"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  },
+  "devDependencies": {
+    "@jielga/tmdatagrid": "2.0.0-beta.14",
+    "@tanstack/intent": "0.3.6",
+    "rolldown": "~1.1.5",
+    "rolldown-plugin-dts": "^0.27.14",
+    "typescript": "~7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}

package/skills/xlsx/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: xlsx
+description: >
+  Excel (.xlsx) export for TMDataGrid through the @jielga/tmdatagrid-xlsx
+  addon. Covers why exceljs lives in a separate package, xlsxFormat() as a
+  TMDataGridExportFormat, setting it as exportOptions.format or per menu item
+  on TMDataGrid.Menu.Export and TMDataGrid.Menu.ExportSelected, how each value
+  becomes a typed cell (numbers, dates with their number format, booleans,
+  arrays, objects, empties), the bold header row under includeHeaders, and the
+  sheetName and autoWidth options. Load when a grid should download a real
+  workbook rather than a CSV, when an exported number or date arrives as text,
+  or when naming or sizing the worksheet.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid-xlsx'
+  library_version: '2.0.0-beta.14'
+sources:
+  - 'Jielga/TMDataGrid:packages/tmdatagrid-xlsx/docs/xlsx.md'
+---
+
+# TMDataGrid - Excel export (xlsx)
+
+A real workbook rather than a CSV Excel can open. A typed cell carries no
+separator, no decimal mark and no byte order mark, so the file reads the same
+whatever locale the reader's Excel runs.
+
+`exceljs` is the reason this is its own package: the grid never depends on a
+spreadsheet writer.
+
+```sh
+npm install @jielga/tmdatagrid-xlsx
+```
+
+## Setting the format
+
+`xlsxFormat()` returns a `TMDataGridExportFormat`, so it goes anywhere the grid
+takes one.
+
+```tsx
+import { useTMDataGrid } from "@jielga/tmdatagrid";
+import { xlsxFormat } from "@jielga/tmdatagrid-xlsx";
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: xlsxFormat(), fileName: "employees" },
+});
+```
+
+Each `TMDataGrid.Menu.Export` and `TMDataGrid.Menu.ExportSelected` item takes
+its own `format`, which overrides `exportOptions` for that item alone - that is
+how one menu offers both CSV and xlsx.
+
+```tsx
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.Export format={xlsxFormat()} />
+  <TMDataGrid.Menu.ExportSelected format={xlsxFormat()} />
+</TMDataGrid.Menu>
+```
+
+## How values are written
+
+| Value | Cell |
+| --- | --- |
+| `number`, finite | A number cell |
+| `number`, `NaN` or infinite | Empty |
+| `Date` at 00:00:00 | A date cell, `yyyy-mm-dd` |
+| `Date` with a time | A date cell, `yyyy-mm-dd hh:mm` |
+| `Date`, invalid | Empty |
+| `boolean` | A boolean cell |
+| `string` | Text |
+| `null`, `undefined` | Empty |
+| Array | Its elements as text, joined with `, ` |
+| Any other object | `JSON.stringify` of it, empty when that throws |
+
+`includeHeaders` (default `true`) writes the column labels as a bold first row.
+
+## Common mistakes
+
+### HIGH Expecting the grid to export xlsx on its own
+
+The grid ships CSV, TSV and JSON only. Without `format: xlsxFormat()` the menu
+item downloads the CSV default, whatever the file is called.
+
+Source: `packages/tmdatagrid-xlsx/docs/xlsx.md`.
+
+### MEDIUM Formatting a value before it reaches the export
+
+A number turned into a string is written as text, and Excel will not sum it.
+Leave the value alone, or use `meta.exportValue` to hand over a real number or
+`Date`.
+
+Source: `packages/tmdatagrid-xlsx/docs/xlsx.md` (How values are written).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `xlsxFormat` | Export | `(options?) => TMDataGridExportFormat` | – | The format. `id`, `extension` and the download's MIME type are all xlsx. |
+| `sheetName` | Option | `string` | `"Sheet1"` | The worksheet's name. |
+| `autoWidth` | Option | `boolean` | `true` | Column widths from the longest text, header included, between 10 and 60 characters. |
+| `TMDataGridXlsxFormatOptions` | Export | type | – | The options object. |
+| `@jielga/tmdatagrid` | Peer dependency | `^2.0.0-beta.14` | – | The two versions release together. |
+
+See also: the `cell-selection` skill for the grid's own export options, the
+clipboard and `exportGrid`.

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The package's only entry point. One export: the format, plus its options
+ * type.
+ */
+export { xlsxFormat } from "./xlsxFormat";
+export type { TMDataGridXlsxFormatOptions } from "./xlsxFormat";

package/src/xlsxFormat.ts

@@ -0,0 +1,160 @@
+import ExcelJS from "exceljs";
+import type {
+  TMDataGridExportData,
+  TMDataGridExportFormat,
+  TMDataGridExportWriteOptions,
+} from "@jielga/tmdatagrid";
+
+/**
+ * How wide a column may get from `autoWidth`. A long free-text cell would
+ * otherwise push a column past the width of the window, and a column nobody
+ * can see past is worse than one that clips.
+ */
+const MAX_COLUMN_WIDTH = 60;
+
+/** Narrow columns still need room for their header and the filter arrow. */
+const MIN_COLUMN_WIDTH = 10;
+
+/** Excel measures a column in characters, and a cell needs a little padding. */
+const WIDTH_PADDING = 2;
+
+const MIME_TYPE =
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+
+/** A date at midnight is a date; anything else is a moment in time. */
+function isMidnight(value: Date): boolean {
+  return (
+    value.getHours() === 0 &&
+    value.getMinutes() === 0 &&
+    value.getSeconds() === 0 &&
+    value.getMilliseconds() === 0
+  );
+}
+
+function dateNumberFormat(value: Date): string {
+  return isMidnight(value) ? "yyyy-mm-dd" : "yyyy-mm-dd hh:mm";
+}
+
+/** The date as its number format renders it, for a width and for a joined array. */
+function dateText(value: Date): string {
+  const text = value.toLocaleString("sv-SE");
+  return isMidnight(value) ? text.slice(0, 10) : text.slice(0, 16);
+}
+
+/**
+ * A value as text, for the cells a spreadsheet has no type for and for the
+ * width measurement.
+ *
+ * Deliberately not `formatExportValue` from the grid: that one writes a
+ * decimal comma and an `sv-SE` date, both of which would be wrong here. A
+ * typed cell carries the value itself and Excel renders it in the reader's own
+ * locale, so only the untypable values reach this.
+ */
+function cellText(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "";
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "" : dateText(value);
+  }
+  // A multiSelect cell holds an array of values; a spreadsheet cell holds one
+  // string, so the elements are joined the way they read on screen.
+  if (Array.isArray(value)) {
+    return value.map((entry) => cellText(entry)).join(", ");
+  }
+  // An object in a cell is a shape the addon cannot know. JSON at least keeps
+  // what was there, where `String(value)` would write "[object Object]".
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return "";
+    }
+  }
+  return String(value);
+}
+
+/**
+ * What goes into the worksheet cell: a number, a date, a boolean or a string.
+ *
+ * `null` for everything empty, which is what exceljs writes as a blank cell -
+ * an empty string would be a cell holding text of length zero, and a formula
+ * counting it would count it.
+ */
+function cellValue(value: unknown): number | Date | boolean | string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === "boolean") return value;
+  return cellText(value);
+}
+
+export type TMDataGridXlsxFormatOptions = {
+  /** Worksheet name. Defaults to `"Sheet1"`. */
+  sheetName?: string;
+  /** Column widths from the longest text in each column, capped at 60 characters. Defaults to `true`. */
+  autoWidth?: boolean;
+};
+
+/**
+ * A real Excel workbook rather than a CSV that Excel can open.
+ *
+ * That is the whole reason the format exists: a typed cell needs no separator,
+ * no decimal mark and no BOM to survive the trip, so nothing depends on the
+ * reader's locale. Numbers arrive as numbers, dates as dates with a number
+ * format, booleans as booleans, and a text cell can hold a semicolon or a
+ * newline without ending the row.
+ *
+ * `exceljs` is why this is a separate package: it is a large dependency, and a
+ * grid that exports CSV should not carry a spreadsheet writer.
+ */
+export function xlsxFormat({
+  sheetName = "Sheet1",
+  autoWidth = true,
+}: TMDataGridXlsxFormatOptions = {}): TMDataGridExportFormat {
+  return {
+    id: "xlsx",
+    extension: "xlsx",
+    mimeType: MIME_TYPE,
+    write: async (
+      data: TMDataGridExportData,
+      { includeHeaders }: TMDataGridExportWriteOptions,
+    ): Promise<Blob> => {
+      const workbook = new ExcelJS.Workbook();
+      const sheet = workbook.addWorksheet(sheetName);
+
+      // The longest text seen per column, header included, for `autoWidth`.
+      const widths = data.headers.map((header) =>
+        includeHeaders ? header.length : 0,
+      );
+
+      if (includeHeaders) {
+        const headerRow = sheet.addRow(data.headers);
+        headerRow.font = { bold: true };
+      }
+
+      for (const row of data.rows) {
+        const added = sheet.addRow(row.map((value) => cellValue(value)));
+        row.forEach((value, index) => {
+          if (value instanceof Date && !Number.isNaN(value.getTime())) {
+            added.getCell(index + 1).numFmt = dateNumberFormat(value);
+          }
+          const length = cellText(value).length;
+          if (length > (widths[index] ?? 0)) widths[index] = length;
+        });
+      }
+
+      if (autoWidth) {
+        widths.forEach((width, index) => {
+          sheet.getColumn(index + 1).width = Math.min(
+            MAX_COLUMN_WIDTH,
+            Math.max(MIN_COLUMN_WIDTH, width + WIDTH_PADDING),
+          );
+        });
+      }
+
+      return new Blob([await workbook.xlsx.writeBuffer()], { type: MIME_TYPE });
+    },
+  };
+}