compote-ui 0.83.0 → 0.85.0

package/dist/components/data-table-v9/xlsx/index.js

@@ -0,0 +1,84 @@
+import { PhMicrosoftExcelLogo } from '../../../icons';
+import { downloadBlob } from '../../../utils/download';
+import { DEFAULT_XLSX_DATE_FORMATS, toXlsxCell } from './xlsx-cell';
+export { DEFAULT_XLSX_DATE_FORMATS, toXlsxCell, xlsxNumberFormat } from './xlsx-cell';
+// Column widths in characters of Excel's default font.
+const MIN_COLUMN_WIDTH = 8;
+const MAX_COLUMN_WIDTH = 60;
+// One character of slack: char counts already overshoot narrow lowercase text, and this keeps
+// wide letters (W, M, capitals) from being cut off.
+const COLUMN_WIDTH_PADDING = 1;
+/** Characters in the longest line of `text` (code points, so č or 🙂 count once). */
+function longestLine(text) {
+    let longest = 0;
+    for (const line of text.split(/\r\n|\r|\n/))
+        longest = Math.max(longest, Array.from(line).length);
+    return longest;
+}
+/**
+ * A width per column that fits its header and the longest cell text (the text the table
+ * shows, which is close to what Excel shows), plus padding, between 8 and 60 characters.
+ */
+export function xlsxColumnWidths(data) {
+    return data.columns.map((column, index) => {
+        let longest = longestLine(column.header);
+        for (const cells of data.rows) {
+            const text = cells[index]?.text;
+            if (text)
+                longest = Math.max(longest, longestLine(text));
+        }
+        return Math.min(MAX_COLUMN_WIDTH, Math.max(MIN_COLUMN_WIDTH, longest + COLUMN_WIDTH_PADDING));
+    });
+}
+/** The export data as sheet rows: a bold header row, then typed cells. */
+export function exportDataToSheet(data, formats = DEFAULT_XLSX_DATE_FORMATS) {
+    const header = data.columns.map((column) => ({
+        type: String,
+        value: column.header,
+        fontWeight: 'bold'
+    }));
+    const rows = data.rows.map((cells) => data.columns.map((column, index) => {
+        const cell = cells[index];
+        return cell ? toXlsxCell(column, cell, formats) : null;
+    }));
+    return [header, ...rows];
+}
+/**
+ * The export data as an .xlsx file. Loads `write-excel-file` (an optional peer dependency) on
+ * first call, so importing this module costs nothing until an export runs — and stays SSR-safe.
+ */
+export async function exportDataToXlsxBlob(data, options = {}) {
+    const { default: writeXlsxFile } = await import('write-excel-file/browser');
+    const formats = { ...DEFAULT_XLSX_DATE_FORMATS, ...pickFormats(options) };
+    const sheetData = exportDataToSheet(data, formats);
+    // XlsxCell is a subset of the package's cell shape; cast via its own (type-only) type.
+    return writeXlsxFile(sheetData, {
+        sheet: options.sheet,
+        stickyRowsCount: 1,
+        columns: xlsxColumnWidths(data).map((width) => ({ width }))
+    }).toBlob();
+}
+function pickFormats({ date, time, dateTime }) {
+    return {
+        ...(date !== undefined ? { date } : {}),
+        ...(time !== undefined ? { time } : {}),
+        ...(dateTime !== undefined ? { dateTime } : {})
+    };
+}
+/**
+ * An Excel exporter: numbers, dates and booleans as typed cells, formatted like the table.
+ * Needs `write-excel-file` installed.
+ */
+export function createXlsxExporter(options = {}) {
+    const { id = 'xlsx', label = 'Excel' } = options;
+    return {
+        id,
+        label,
+        icon: PhMicrosoftExcelLogo,
+        export: async ({ filename, getData }) => {
+            const blob = await exportDataToXlsxBlob(getData(), options);
+            downloadBlob(blob, `${filename}.xlsx`);
+        }
+    };
+}
+export const xlsxExporter = createXlsxExporter();

package/dist/components/data-table-v9/xlsx/xlsx-cell.d.ts

@@ -0,0 +1,51 @@
+import { type ZonedOrCalendarDate } from '../../../utils/date';
+import type { DataTableExportCell, DataTableExportColumn } from '../export/export-data';
+/** Excel number formats for date columns. */
+export type XlsxDateFormats = {
+    date: string;
+    time: string;
+    dateTime: string;
+};
+export declare const DEFAULT_XLSX_DATE_FORMATS: XlsxDateFormats;
+/**
+ * One sheet cell, in the shape `write-excel-file` takes. Declared here so the published types
+ * don't depend on the optional peer.
+ */
+export type XlsxCell = null | {
+    type: StringConstructor;
+    value: string;
+    fontWeight?: 'bold';
+} | {
+    type: NumberConstructor;
+    value: number;
+    format: string;
+} | {
+    type: DateConstructor;
+    value: Date;
+    format: string;
+} | {
+    type: BooleanConstructor;
+    value: boolean;
+};
+/**
+ * The Excel format string matching how the table shows `value`, or undefined when the
+ * column's Intl options have no faithful Excel equivalent (the cell is then written as text).
+ * Decimals are chosen per value, exactly as many as Intl shows (read from `formatToParts`, so
+ * Intl's own rounding decides): `#,##0.###` would leave a trailing `.` on whole numbers.
+ */
+export declare function xlsxNumberFormat(column: DataTableExportColumn, value: number): string | undefined;
+/** Which part of a date a column shows, and so which part Excel gets. */
+export type XlsxDatePart = 'date' | 'time' | 'date-time';
+/**
+ * The date as Excel should show it. Excel dates have no zone, and `write-excel-file` reads a
+ * `Date` in UTC, so the wall clock of the zone the table shows is written as UTC. A `date`
+ * column drops the time (midnight); a `time` column keeps only the time of day, on Excel's day
+ * zero (1899-12-30), so times sort and compare by time alone.
+ */
+export declare function toXlsxDate(date: ZonedOrCalendarDate, part?: XlsxDatePart): Date;
+/**
+ * One export cell as a typed sheet cell: numbers, dates and booleans stay computable in Excel;
+ * everything else — and any column with its own `cell` renderer but no `exportValue` — is the
+ * text the table shows. Typed cells can't hold formulas, so no `'` guard is needed.
+ */
+export declare function toXlsxCell(column: DataTableExportColumn, cell: DataTableExportCell, formats?: XlsxDateFormats): XlsxCell;

package/dist/components/data-table-v9/xlsx/xlsx-cell.js

@@ -0,0 +1,123 @@
+import { GregorianCalendar, toCalendar } from '@internationalized/date';
+import { readDateInZone } from '../../../utils/date';
+import { dateCellTimeZone } from '../date-cell';
+import { TYPE_NUMBER_FORMAT_DEFAULTS } from '../data-table-utils';
+export const DEFAULT_XLSX_DATE_FORMATS = {
+    date: 'dd.mm.yyyy',
+    time: 'hh:mm',
+    dateTime: 'dd.mm.yyyy hh:mm'
+};
+const NUMBER_TYPES = new Set(['number', 'currency', 'percent']);
+const DATE_TYPES = new Set(['date', 'time', 'date-time']);
+const isEmpty = (value) => value === null || value === undefined || value === '';
+function textCell(cell) {
+    return cell.text === '' ? null : { type: String, value: cell.text };
+}
+/**
+ * The Excel format string matching how the table shows `value`, or undefined when the
+ * column's Intl options have no faithful Excel equivalent (the cell is then written as text).
+ * Decimals are chosen per value, exactly as many as Intl shows (read from `formatToParts`, so
+ * Intl's own rounding decides): `#,##0.###` would leave a trailing `.` on whole numbers.
+ */
+export function xlsxNumberFormat(column, value) {
+    const defaults = column.type ? TYPE_NUMBER_FORMAT_DEFAULTS[column.type] : undefined;
+    let formatter;
+    try {
+        formatter = new Intl.NumberFormat(column.locale, {
+            ...defaults,
+            ...column.formatOptions
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const resolved = formatter.resolvedOptions();
+    const unsupported = resolved.notation !== 'standard' ||
+        resolved.minimumSignificantDigits !== undefined ||
+        resolved.maximumSignificantDigits !== undefined ||
+        resolved.signDisplay !== 'auto' ||
+        resolved.minimumIntegerDigits !== 1 ||
+        (resolved.roundingIncrement ?? 1) !== 1 ||
+        // Excel display rounds half away from zero, which is Intl's `halfExpand` only.
+        (resolved.roundingMode ?? 'halfExpand') !== 'halfExpand' ||
+        resolved.style === 'unit' ||
+        (resolved.style === 'currency' &&
+            (resolved.currencyDisplay === 'name' || resolved.currencySign === 'accounting'));
+    if (unsupported)
+        return undefined;
+    const fraction = formatter.formatToParts(value).find((part) => part.type === 'fraction');
+    const decimals = fraction?.value.length ?? 0;
+    const grouping = resolved.useGrouping === false ? '0' : '#,##0';
+    const format = decimals > 0 ? `${grouping}.${'0'.repeat(decimals)}` : grouping;
+    if (resolved.style === 'percent')
+        return `${format}%`;
+    if (resolved.style === 'currency')
+        return `${format} "${resolved.currency}"`;
+    return format;
+}
+/**
+ * The date as Excel should show it. Excel dates have no zone, and `write-excel-file` reads a
+ * `Date` in UTC, so the wall clock of the zone the table shows is written as UTC. A `date`
+ * column drops the time (midnight); a `time` column keeps only the time of day, on Excel's day
+ * zero (1899-12-30), so times sort and compare by time alone.
+ */
+export function toXlsxDate(date, part = 'date-time') {
+    const gregorian = toCalendar(date, new GregorianCalendar());
+    const year = gregorian.era === 'BC' ? 1 - gregorian.year : gregorian.year;
+    const result = new Date(0);
+    // Not Date.UTC: it reads years 0–99 as 1900–1999.
+    if (part === 'time')
+        result.setUTCFullYear(1899, 11, 30);
+    else
+        result.setUTCFullYear(year, gregorian.month - 1, gregorian.day);
+    if (part !== 'date' && 'hour' in gregorian) {
+        result.setUTCHours(gregorian.hour, gregorian.minute, gregorian.second, gregorian.millisecond);
+    }
+    return result;
+}
+function dateFormatFor(type, formats) {
+    if (type === 'time')
+        return formats.time;
+    if (type === 'date-time')
+        return formats.dateTime;
+    return formats.date;
+}
+/**
+ * One export cell as a typed sheet cell: numbers, dates and booleans stay computable in Excel;
+ * everything else — and any column with its own `cell` renderer but no `exportValue` — is the
+ * text the table shows. Typed cells can't hold formulas, so no `'` guard is needed.
+ */
+export function toXlsxCell(column, cell, formats = DEFAULT_XLSX_DATE_FORMATS) {
+    const { type } = column;
+    if (column.hasCustomCell && !column.hasExportValue)
+        return textCell(cell);
+    if (type === undefined)
+        return textCell(cell);
+    if (NUMBER_TYPES.has(type)) {
+        if (isEmpty(cell.value))
+            return null;
+        const value = Number(cell.value);
+        if (!Number.isFinite(value))
+            return textCell(cell);
+        const format = xlsxNumberFormat(column, value);
+        return format === undefined ? textCell(cell) : { type: Number, value, format };
+    }
+    if (DATE_TYPES.has(type)) {
+        if (isEmpty(cell.value))
+            return null;
+        const formatOptions = column.formatOptions;
+        const date = readDateInZone(cell.value, dateCellTimeZone(formatOptions));
+        if (!date)
+            return textCell(cell);
+        return {
+            type: Date,
+            value: toXlsxDate(date, type),
+            format: dateFormatFor(type, formats)
+        };
+    }
+    if (type === 'boolean') {
+        // Like the table, only a real true/false is a checkbox; anything else shows `-`.
+        return typeof cell.value === 'boolean' ? { type: Boolean, value: cell.value } : null;
+    }
+    return textCell(cell);
+}

package/dist/icons/PhDownloadSimple.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	let { class: className = '', ...restProps } = $props();
+</script>
+
+<svg
+	xmlns="http://www.w3.org/2000/svg"
+	width="1em"
+	height="1em"
+	viewBox="0 0 256 256"
+	class={className}
+	{...restProps}
+>
+	<path
+		fill="currentColor"
+		d="M224 144v64a8 8 0 0 1-8 8H40a8 8 0 0 1-8-8v-64a8 8 0 0 1 16 0v56h160v-56a8 8 0 0 1 16 0m-101.66 5.66a8 8 0 0 0 11.32 0l40-40a8 8 0 0 0-11.32-11.32L136 124.69V32a8 8 0 0 0-16 0v92.69L93.66 98.34a8 8 0 0 0-11.32 11.32Z"
+	/>
+</svg>
+<!-- Icon from Phosphor by Phosphor Icons - https://github.com/phosphor-icons/core/blob/main/LICENSE -->

package/dist/icons/PhDownloadSimple.svelte.d.ts

@@ -0,0 +1,5 @@
+declare const PhDownloadSimple: import("svelte").Component<{
+    class?: string;
+} & Record<string, any>, {}, "">;
+type PhDownloadSimple = ReturnType<typeof PhDownloadSimple>;
+export default PhDownloadSimple;

package/dist/icons/index.d.ts

@@ -10,6 +10,7 @@ export { default as PhCaretRight } from './PhCaretRight.svelte';
 export { default as PhCaretUp } from './PhCaretUp.svelte';
 export { default as PhCheck } from './PhCheck.svelte';
 export { default as PhColumns } from './PhColumns.svelte';
+export { default as PhDownloadSimple } from './PhDownloadSimple.svelte';
 export { default as PhEye } from './PhEye.svelte';
 export { default as PhEyeSlash } from './PhEyeSlash.svelte';
 export { default as PhFile } from './PhFile.svelte';

package/dist/icons/index.js

@@ -10,6 +10,7 @@ export { default as PhCaretRight } from './PhCaretRight.svelte';
 export { default as PhCaretUp } from './PhCaretUp.svelte';
 export { default as PhCheck } from './PhCheck.svelte';
 export { default as PhColumns } from './PhColumns.svelte';
+export { default as PhDownloadSimple } from './PhDownloadSimple.svelte';
 export { default as PhEye } from './PhEye.svelte';
 export { default as PhEyeSlash } from './PhEyeSlash.svelte';
 export { default as PhFile } from './PhFile.svelte';

package/dist/utils/csv.d.ts

@@ -0,0 +1,13 @@
+export type CsvOptions = {
+    /** Field separator. Defaults to `;`, which Excel expects under most European locales. */
+    separator?: string;
+    /**
+     * Prepend a UTF-8 BOM so Excel reads the file as UTF-8 (otherwise č/ć/š/đ/ž break).
+     * Defaults to `true`.
+     */
+    bom?: boolean;
+};
+/** Quotes a field when it holds a quote, the separator or a line break (RFC 4180). */
+export declare function escapeCsvField(value: string, separator: string): string;
+/** Serializes rows of text as CSV, records separated by CRLF. */
+export declare function toCsv(rows: string[][], { separator, bom }?: CsvOptions): string;

package/dist/utils/csv.js

@@ -0,0 +1,18 @@
+const BOM = '';
+/** Quotes a field when it holds a quote, the separator or a line break (RFC 4180). */
+export function escapeCsvField(value, separator) {
+    if (value.includes('"') || value.includes(separator) || /[\r\n]/.test(value)) {
+        return `"${value.replaceAll('"', '""')}"`;
+    }
+    return value;
+}
+/** Serializes rows of text as CSV, records separated by CRLF. */
+export function toCsv(rows, { separator = ';', bom = true } = {}) {
+    if (separator.length === 0 || /["\r\n]/.test(separator)) {
+        throw new Error(`Invalid CSV separator: ${JSON.stringify(separator)}`);
+    }
+    const body = rows
+        .map((row) => row.map((field) => escapeCsvField(field, separator)).join(separator))
+        .join('\r\n');
+    return bom ? BOM + body : body;
+}

package/dist/utils/download.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hands `blob` to the browser as a download named `filename`. Browser-only: call it from an
+ * event handler, never during SSR.
+ */
+export declare function downloadBlob(blob: Blob, filename: string): void;

package/dist/utils/download.js

@@ -0,0 +1,17 @@
+/**
+ * Hands `blob` to the browser as a download named `filename`. Browser-only: call it from an
+ * event handler, never during SSR.
+ */
+export function downloadBlob(blob, filename) {
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    link.style.display = 'none';
+    document.body.append(link);
+    link.click();
+    link.remove();
+    // Revoking right away can cancel the download in some browsers (Safari); the URL only
+    // pins the blob in memory until then.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}

package/dist/utils/select-filter.js

@@ -62,7 +62,12 @@ export function selectFilterOptions(facets, emptyLabel = '(empty)') {
         label: value,
         count
     }));
-    options.sort((a, b) => a.label.localeCompare(b.label));
+    // A column whose values are all numbers sorts by magnitude (so 2 < 10, -5 < 1.5); anything
+    // else sorts by label with digit runs compared numerically ("Item 2" < "Item 10").
+    const allNumbers = [...facets.keys()].every((key) => isEmpty(key) || Number.isFinite(key));
+    options.sort(allNumbers
+        ? (a, b) => Number(a.value) - Number(b.value)
+        : (a, b) => a.label.localeCompare(b.label, undefined, { numeric: true }));
     if (emptyCount > 0) {
         options.push({ value: EMPTY_SELECT_VALUE, label: emptyLabel, count: emptyCount });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.83.0",
+	"version": "0.85.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -53,15 +53,23 @@
 			"types": "./dist/components/data-table-v9/virtual/index.d.ts",
 			"svelte": "./dist/components/data-table-v9/virtual/index.js"
 		},
+		"./data-table/xlsx": {
+			"types": "./dist/components/data-table-v9/xlsx/index.d.ts",
+			"svelte": "./dist/components/data-table-v9/xlsx/index.js"
+		},
 		"./theme.css": "./dist/theme.css"
 	},
 	"peerDependencies": {
 		"@tanstack/svelte-table": ">=9.1.0 <10",
-		"svelte": "^5.0.0"
+		"svelte": "^5.0.0",
+		"write-excel-file": "^4.1.0"
 	},
 	"peerDependenciesMeta": {
 		"@tanstack/svelte-table": {
 			"optional": true
+		},
+		"write-excel-file": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
@@ -80,6 +88,7 @@
 		"eslint": "^10.12.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-svelte": "^3.23.1",
+		"fflate": "^0.8.2",
 		"globals": "^17.13.0",
 		"prettier": "^3.9.10",
 		"prettier-plugin-svelte": "^4.1.1",
@@ -94,7 +103,8 @@
 		"unplugin-icons": "^24.0.0",
 		"vite": "^8.3.4",
 		"vitest": "^5.0.4",
-		"wrangler": "^4.151.0"
+		"wrangler": "^4.151.0",
+		"write-excel-file": "^4.1.1"
 	},
 	"keywords": [
 		"svelte",

package/skills/data-table/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: data-table
 description: >
-  Load when using compote-ui/data-table or compote-ui/data-table/virtual.
-  Covers TanStack Table v9 wrapper usage, createTable,
+  Load when using compote-ui/data-table, compote-ui/data-table/virtual or
+  compote-ui/data-table/xlsx. Covers TanStack Table v9 wrapper usage, createTable,
   createDataTableColumnHelper, table columns, row selection, filters,
-  formatting, toolbars, virtualized imports, and optional peer dependencies.
+  formatting, toolbars, CSV/Excel export, virtualized imports, and optional
+  peer dependencies.
 metadata:
   type: composition
   library: compote-ui
-  library_version: '0.81.0'
+  library_version: '0.84.0'
 requires:
   - component-usage
   - theming
@@ -27,6 +28,12 @@ sources:
   - src/lib/components/data-table-v9/column-filter-editing.svelte.ts
   - src/lib/utils/select-filter.ts
   - src/lib/utils/date-filter.ts
+  - src/lib/utils/csv.ts
+  - src/lib/components/data-table-v9/export/export-data.ts
+  - src/lib/components/data-table-v9/export/csv-exporter.ts
+  - src/lib/components/data-table-v9/toolbar/data-table-export.svelte
+  - src/lib/components/data-table-v9/xlsx/index.ts
+  - src/lib/components/data-table-v9/xlsx/xlsx-cell.ts
   - src/lib/components/data-table-v9/virtual/data-table-virtualized.svelte
   - src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte
 ---
@@ -266,6 +273,25 @@ spins its icon and sets `aria-busy` until the promise settles. Clicks while busy
 Props: `onRefresh: () => void | Promise<unknown>`, `loading?: boolean`, `triggerLabel?: string`
 (icon-only with `aria-label="Refresh"` and a tooltip when omitted). Errors thrown by `onRefresh` are not caught.
 
+### Export to a file
+
+`DataTable.Export` downloads the visible columns and the filtered, sorted rows. It writes CSV by
+default; pass `exporters` for more formats or your own (an exporter on the server, or a library
+the app already has). With selected rows it offers all rows or only the selected ones. Excel
+comes from `compote-ui/data-table/xlsx` and needs the optional peer `write-excel-file`.
+
+```svelte
+<script lang="ts">
+	import * as DataTable from 'compote-ui/data-table';
+	import { xlsxExporter } from 'compote-ui/data-table/xlsx';
+</script>
+
+<DataTable.Export {table} filename="invoices" exporters={[DataTable.csvExporter, xlsxExporter]} />
+```
+
+Exclude a column with `enableExport: false` (action columns are excluded by default). Use
+`exportValue` when a cell holds a value a file can't show. See [Export](references/export.md).
+
 ## Common Mistakes
 
 ### CRITICAL Missing id for accessorFn column
@@ -355,8 +381,20 @@ The virtual subpath imports `@tanstack/svelte-virtual`.
 
 Source: `package.json`, `src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte`
 
+### HIGH Using the Excel exporter without its optional peer
+
+`compote-ui/data-table/xlsx` imports `write-excel-file` (dynamically, on export). Without it the
+app's build fails to resolve the import. Install it first:
+
+```bash
+bun add write-excel-file
+```
+
+Source: `package.json`, `src/lib/components/data-table-v9/xlsx/index.ts`
+
 ## References
 
 - [Column options](references/column-options.md)
 - [Table state and reactivity](references/table-state-and-reactivity.md)
 - [Virtual table](references/virtual-table.md)
+- [Export](references/export.md)

package/skills/data-table/references/column-options.md

@@ -40,6 +40,10 @@ Common options:
 - `grow?: boolean`
 - `sum?: boolean`
 - `footer?: (values: unknown[]) => string | number | undefined`
+- `exportValue?: (value, row) => unknown` — the value `DataTable.Export` writes instead of the
+  accessor value (e.g. a number out of an object a `cellComponent` renders). Without `cell`, its
+  text is formatted by `type`; it is never passed to `cell`. See [Export](export.md).
+- `enableExport?: boolean` — defaults to `true`, `false` for `type: 'action'`.
 
 Type defaults: