compote-ui 0.85.0 → 0.86.0

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

@@ -1,8 +1,11 @@
 import type { DataTableExportData } from '../export/export-data';
 import type { DataTableExporter } from '../export/types';
 import { type XlsxCell, type XlsxDateFormats } from './xlsx-cell';
+import { type XlsxRowsColumn } from './xlsx-rows';
 export { DEFAULT_XLSX_DATE_FORMATS, toXlsxCell, xlsxNumberFormat } from './xlsx-cell';
 export type { XlsxCell, XlsxDateFormats, XlsxDatePart } from './xlsx-cell';
+export { rowsToExportData } from './xlsx-rows';
+export type { XlsxRowsColumn } from './xlsx-rows';
 export type XlsxExporterOptions = Partial<XlsxDateFormats> & {
     id?: string;
     label?: string;
@@ -21,6 +24,20 @@ export declare function exportDataToSheet(data: DataTableExportData, formats?: X
  * first call, so importing this module costs nothing until an export runs — and stays SSR-safe.
  */
 export declare function exportDataToXlsxBlob(data: DataTableExportData, options?: XlsxExporterOptions): Promise<Blob>;
+export type XlsxRowsOptions = XlsxExporterOptions & {
+    /**
+     * Locale the values are formatted in: the text that sets column widths, the text of cells
+     * written as text (a number format Excel can't express), and the decimals of a number format.
+     * Default `en-US`.
+     */
+    locale?: string;
+};
+/**
+ * Plain row objects as an .xlsx file, for an export that isn't a DataTable: typed cells, a bold
+ * frozen header row and content-fitted column widths, exactly like a table export. Download
+ * the result with `downloadBlob(blob, 'name.xlsx')`.
+ */
+export declare function exportRowsToXlsxBlob(rows: ReadonlyArray<Record<string, unknown>>, columns: ReadonlyArray<XlsxRowsColumn>, options?: XlsxRowsOptions): Promise<Blob>;
 /**
  * An Excel exporter: numbers, dates and booleans as typed cells, formatted like the table.
  * Needs `write-excel-file` installed.

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

@@ -1,7 +1,9 @@
 import { PhMicrosoftExcelLogo } from '../../../icons';
 import { downloadBlob } from '../../../utils/download';
 import { DEFAULT_XLSX_DATE_FORMATS, toXlsxCell } from './xlsx-cell';
+import { rowsToExportData } from './xlsx-rows';
 export { DEFAULT_XLSX_DATE_FORMATS, toXlsxCell, xlsxNumberFormat } from './xlsx-cell';
+export { rowsToExportData } from './xlsx-rows';
 // Column widths in characters of Excel's default font.
 const MIN_COLUMN_WIDTH = 8;
 const MAX_COLUMN_WIDTH = 60;
@@ -58,6 +60,14 @@ export async function exportDataToXlsxBlob(data, options = {}) {
         columns: xlsxColumnWidths(data).map((width) => ({ width }))
     }).toBlob();
 }
+/**
+ * Plain row objects as an .xlsx file, for an export that isn't a DataTable: typed cells, a bold
+ * frozen header row and content-fitted column widths, exactly like a table export. Download
+ * the result with `downloadBlob(blob, 'name.xlsx')`.
+ */
+export async function exportRowsToXlsxBlob(rows, columns, options = {}) {
+    return exportDataToXlsxBlob(rowsToExportData(rows, columns, options.locale), options);
+}
 function pickFormats({ date, time, dateTime }) {
     return {
         ...(date !== undefined ? { date } : {}),

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

@@ -0,0 +1,31 @@
+import type { DataTableExportData } from '../export/export-data';
+import type { DataTableColumnType } from '../types';
+/**
+ * A column of plain row objects for `exportRowsToXlsxBlob`: which key to read, and how the
+ * values are typed (the same `type` and `formatOptions` a DataTable column has).
+ */
+export type XlsxRowsColumn = {
+    /** The key to read from each row object. */
+    key: string;
+    /** The header cell; defaults to `key`. */
+    header?: string;
+    /**
+     * How the value is written. `number`, `currency` and `percent` become Excel numbers, `date`,
+     * `time` and `date-time` Excel dates, `boolean` TRUE/FALSE. Without a type (or `text`) the
+     * value is written as text, so a numeric column needs a type to stay computable.
+     */
+    type?: DataTableColumnType;
+    /**
+     * Intl options for the Excel format of a typed column: `{ minimumFractionDigits: 2,
+     * maximumFractionDigits: 2 }` for fixed decimals, `{ useGrouping: false,
+     * maximumFractionDigits: 0 }` for whole numbers without a thousands separator (`useGrouping:
+     * false` alone keeps the decimals a value has). A `number` column with none shows as many
+     * decimals as each value has (up to 3).
+     */
+    formatOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions;
+};
+/**
+ * Plain row objects as the export data the xlsx exporter takes, so they get the same typed
+ * cells, bold frozen header and content-fitted widths as a DataTable export.
+ */
+export declare function rowsToExportData(rows: ReadonlyArray<Record<string, unknown>>, columns: ReadonlyArray<XlsxRowsColumn>, locale?: string): DataTableExportData;

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

@@ -0,0 +1,60 @@
+import { TYPE_NUMBER_FORMAT_DEFAULTS } from '../data-table-utils';
+import { formatDateCell } from '../date-cell';
+const NUMBER_TYPES = new Set(['number', 'currency', 'percent']);
+const isEmpty = (value) => value === null || value === undefined || value === '';
+/**
+ * The text a DataTable cell of this type would show (same rules as the table's own cell text):
+ * what text and fallback cells write, and what column widths are measured on. `''` when the
+ * table would show `-`.
+ */
+function cellText(column, value, locale) {
+    if (isEmpty(value))
+        return '';
+    const { type } = column;
+    try {
+        if (type && NUMBER_TYPES.has(type)) {
+            // Like the table: numeric strings count as numbers, anything else shows nothing.
+            const number = Number(value);
+            if (Number.isNaN(number))
+                return '';
+            return new Intl.NumberFormat(locale, {
+                ...TYPE_NUMBER_FORMAT_DEFAULTS[type],
+                ...column.formatOptions
+            }).format(number);
+        }
+        if (type === 'date' || type === 'time' || type === 'date-time') {
+            // Reads a Date, an ISO/DB string, an epoch number... the way the table does.
+            return (formatDateCell(value, type, locale, column.formatOptions) ??
+                '');
+        }
+        if (type === 'boolean')
+            return value ? 'Yes' : 'No';
+    }
+    catch {
+        // Invalid Intl options: fall back to the plain string.
+    }
+    return String(value);
+}
+/**
+ * Plain row objects as the export data the xlsx exporter takes, so they get the same typed
+ * cells, bold frozen header and content-fitted widths as a DataTable export.
+ */
+export function rowsToExportData(rows, columns, locale = 'en-US') {
+    return {
+        columns: columns.map((column) => ({
+            id: column.key,
+            header: column.header ?? column.key,
+            type: column.type,
+            formatOptions: column.formatOptions,
+            hasCustomCell: false,
+            hasExportValue: false,
+            locale,
+            // Only a table has a width in px; an xlsx export measures the content instead.
+            size: 0
+        })),
+        rows: rows.map((row) => columns.map((column) => {
+            const value = row[column.key];
+            return { value, text: cellText(column, value, locale) };
+        }))
+    };
+}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * as HoverCard from './components/hover-card';
 export * as ScrollArea from './components/scroll-area';
 export { loadImage, fileToDataUrl, cropImage, processImage } from './utils/image-processing';
 export type { ProcessImageOptions, CropRegion } from './utils/image-processing';
+export { downloadBlob } from './utils/download';
 export * as Carousel from './components/carousel';
 export { default as Checkbox } from './components/checkbox/checkbox.svelte';
 export { default as CheckboxGroup } from './components/checkbox/checkbox-group.svelte';

package/dist/index.js

@@ -9,6 +9,7 @@ export * as Collapsible from './components/collapsible';
 export * as HoverCard from './components/hover-card';
 export * as ScrollArea from './components/scroll-area';
 export { loadImage, fileToDataUrl, cropImage, processImage } from './utils/image-processing';
+export { downloadBlob } from './utils/download';
 export * as Carousel from './components/carousel';
 export { default as Checkbox } from './components/checkbox/checkbox.svelte';
 export { default as CheckboxGroup } from './components/checkbox/checkbox-group.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.85.0",
+	"version": "0.86.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",

package/skills/data-table/SKILL.md

@@ -34,6 +34,7 @@ sources:
   - 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/xlsx/xlsx-rows.ts
   - src/lib/components/data-table-v9/virtual/data-table-virtualized.svelte
   - src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte
 ---

package/skills/data-table/references/export.md

@@ -107,6 +107,55 @@ const excel = createXlsxExporter({
 `exportDataToXlsxBlob(data, options)` returns the file as a `Blob` (e.g. to upload instead of
 download), and `toXlsxCell` maps one cell.
 
+### Plain rows (an export that isn't a table)
+
+`exportRowsToXlsxBlob(rows, columns, options)` writes row objects with the same typed cells, bold
+frozen header and content-fitted widths. `columns` are `{ key, header?, type?, formatOptions? }`;
+`options` are the exporter options plus `locale` (default `en-US`), the locale values are
+formatted in: it sets the text column widths are measured on, the text of cells written as text
+(a number format Excel can't express, such as `notation: 'compact'`), and the decimals of a
+number format.
+`downloadBlob` (exported from `compote-ui`) hands the file to the browser. Browser-only: call it
+from an event handler.
+
+```ts
+import { downloadBlob } from 'compote-ui';
+import { exportRowsToXlsxBlob } from 'compote-ui/data-table/xlsx';
+
+const blob = await exportRowsToXlsxBlob(
+	rows, // Record<string, unknown>[]
+	[
+		{ key: 'sku', header: 'SKU' },
+		{
+			key: 'qty',
+			header: 'Qty',
+			type: 'number',
+			formatOptions: { useGrouping: false, maximumFractionDigits: 0 }
+		},
+		{
+			key: 'price',
+			header: 'Price',
+			type: 'number',
+			formatOptions: { minimumFractionDigits: 2, maximumFractionDigits: 2 }
+		}
+	],
+	{ sheet: 'Cart' }
+);
+downloadBlob(blob, 'cart.xlsx');
+```
+
+- A column without a `type` (or `text`) is written as text, so a numeric column needs
+  `type: 'number'` to stay computable in Excel; a text SKU such as `00123` keeps its zeros.
+- A `number` column with no `formatOptions` shows as many decimals as each value has (up to 3):
+  give prices `minimumFractionDigits`/`maximumFractionDigits` for a fixed `#,##0.00`, and
+  `{ useGrouping: false, maximumFractionDigits: 0 }` for a plain `0` (quantities, ids);
+  `useGrouping: false` alone only drops the thousands separator, so `1.5` would be `0.0`.
+- Values are read like the table reads them: a numeric string in a `number` column is a number,
+  a `date` column takes a `Date`, an ISO string or an epoch number, and `NaN` or text that isn't
+  a number or date is an empty cell.
+- `null`, `undefined` and `''` are empty cells. `rowsToExportData(rows, columns, locale)` is the
+  conversion alone, if you want to pass the result to `exportDataToXlsxBlob` yourself.
+
 ## Custom exporter
 
 An exporter is `{ id, label, icon?, export(context) }`. `context` holds `table`, `scope`