@iyulab/flex-table 0.61.0 → 0.62.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.62.0] - 2026-10-08
+
+### Added
+
+- **`ColumnDefinition.exportValue(value, row)`** — what export writes for the column (CSV, TSV, JSON, XLSX). Without
+  it export writes the raw value as before; a column that shows a label for a code can now say so once instead of the
+  consumer rewriting the rows before `{ rows }`. A returned `Date` is a date cell in XLSX.
+- **CSV/TSV byte order mark** — `{ bom: true }` on `exportToString`/`exportToBlob`/`exportData`/`exportDataBlob`, and
+  `exportToFile` adds it by default (a downloaded file is opened in a spreadsheet; Excel on a non-UTF-8 system code page
+  garbled Korean without it). `{ bom: false }` turns it off.
+
+### Fixed
+
+- XLSX: an ISO string in a `date`/`datetime` column is a date cell — JSON sources (OData) send dates as strings, so the
+  file had text where the list showed dates. Strings that do not read as a date stay text.
+- XLSX: date serials are the wall-clock time the table shows. They were counted from UTC, so a local-midnight date in
+  a timezone ahead of UTC (Korea, +09) went in as the afternoon of the day before and a date format showed that day.
+
 ## [0.61.0] - 2026-10-07
 
 ### Added

package/README.md

@@ -148,6 +148,7 @@ interface ColumnDefinition {
   options?: string[] | SelectOption[]; // Allowed values for type: 'select' (SelectOption = { label, value })
   autocomplete?: boolean | 'strict'; // Suggest existing column values while editing; 'strict' rejects values not in the list
   format?: string | ((value, row, col) => string); // Display format, see "format vs render" below
+  exportValue?: (value, row) => string | number | boolean | Date | null; // What export writes for this column (default: the raw value)
   render?: CellRenderer;   // Custom cell render: (value, row, col) => TemplateResult | string
   editor?: CellEditor;     // Custom cell editor: (value, row, col) => TemplateResult
   validator?: CellValidator; // Validate before commit: (value, row, col) => string | null
@@ -169,7 +170,7 @@ A `date` column's built-in editor is `u-date-picker` from `@iyulab/components`:
 
 Both control how a cell's raw value is displayed, but they differ in what they replace:
 
-- **`format`**: a plain string pattern (Excel-style, e.g. `'#,##0.00'`, `'0.00%'`, `'$#,##0'`, `'yyyy-MM-dd'`) or a `(value, row, col) => string` function. Only the *displayed text* changes — editing, sorting, filtering, and export all keep operating on the raw underlying value. Use this for number/date/currency display formatting.
+- **`format`**: a plain string pattern (Excel-style, e.g. `'#,##0.00'`, `'0.00%'`, `'$#,##0'`, `'yyyy-MM-dd'`) or a `(value, row, col) => string` function. Only the *displayed text* changes — editing, sorting, filtering, and export all keep operating on the raw underlying value (give the column an `exportValue` when the file should carry what the list shows, see Export). Use this for number/date/currency display formatting.
 - **`render`**: a `(value, row, col) => TemplateResult | string` function that replaces the cell's rendered content entirely — badges, links, icons, multi-field composites. Sorting/filtering still use the raw value, but the visual output is fully custom.
 
 ```typescript
@@ -290,7 +291,17 @@ Default is `false`, matching `clear-undo-on-data-change`.
 |--------|---------|-------------|
 | `exportToString(format, options?)` | `string \| Uint8Array` | Export to `'csv'` / `'tsv'` / `'json'` (a string) or `'xlsx'` (bytes, uncompressed). Pass `{ selectionOnly: true }` for selection range, or `{ rows }` to export rows the table does not hold (see below) |
 | `exportToBlob(format, options?)` | `Promise<Blob>` | The same export as a `Blob` of the format's MIME type — `'xlsx'` is DEFLATE-compressed |
-| `exportToFile(format, filename?, options?)` | `Promise<void>` | Export and trigger browser file download (`'xlsx'` compressed) |
+| `exportToFile(format, filename?, options?)` | `Promise<void>` | Export and trigger browser file download (`'xlsx'` compressed). CSV/TSV start with a UTF-8 BOM by default — pass `{ bom: false }` for a file another program loads |
+
+What goes into the file:
+
+- **Values**: the raw value of each visible column, or the column's `exportValue(value, row)` when it has one — e.g. a
+  status code shown as a label: `{ key: 'status', render: …, exportValue: (v) => statusLabel(v) }`.
+- **Dates**: in XLSX a `date`/`datetime` column is a date cell — a `Date`, or an ISO string as JSON sources (OData) send
+  it (`YYYY-MM-DD` is that day; a full ISO string is read with its offset), the same rule the cells display with. The
+  cell holds the wall-clock time the table shows. A string that does not read as a date stays text.
+- **BOM**: `{ bom: true }` starts CSV/TSV with a UTF-8 byte order mark so Excel on a non-UTF-8 system code page reads
+  non-ASCII text correctly — the default for `exportToFile`, off for `exportToString`/`exportToBlob`.
 
 The table exports the rows it holds — the filtered rows in sort order, or the selection. **A server-paged table
 (`data-mode="server"`) holds one page**, so its export is one page. To export what the list shows — the whole result

package/dist/export/export.d.ts

@@ -1,15 +1,24 @@
 import type { ColumnDefinition, DataRow } from '../models/types.js';
 export type ExportFormat = 'csv' | 'tsv' | 'json' | 'xlsx';
+/** Options for `exportData` / `exportDataBlob`. */
+export interface ExportOptions {
+    /**
+     * CSV/TSV only — start the text with a UTF-8 byte order mark. Spreadsheet apps (Excel on a non-UTF-8 system
+     * code page, e.g. Korean Windows) read a CSV without one in the system code page and garble non-ASCII text.
+     * Leave it off for files another program loads. Default: `false`.
+     */
+    bom?: boolean;
+}
 /**
  * Export data to the specified format.
  * Returns string for text formats (csv/tsv/json) or Uint8Array for xlsx.
  */
-export declare function exportData(data: DataRow[], columns: ColumnDefinition[], format: ExportFormat): string | Uint8Array<ArrayBuffer>;
+export declare function exportData(data: DataRow[], columns: ColumnDefinition[], format: ExportFormat, options?: ExportOptions): string | Uint8Array<ArrayBuffer>;
 /**
  * Export data as a `Blob` of the format's MIME type. XLSX is DEFLATE-compressed (unlike `exportData`,
  * which stays synchronous and therefore stores the workbook uncompressed).
  */
-export declare function exportDataBlob(data: DataRow[], columns: ColumnDefinition[], format: ExportFormat): Promise<Blob>;
+export declare function exportDataBlob(data: DataRow[], columns: ColumnDefinition[], format: ExportFormat, options?: ExportOptions): Promise<Blob>;
 /**
  * Trigger a file download in the browser.
  */

package/dist/export/values.d.ts

@@ -0,0 +1,17 @@
+import type { ColumnDefinition, DataRow } from '../models/types.js';
+/**
+ * 내보낼 셀 값 — 열이 `exportValue` 를 주면 그 결과, 아니면 원시값. 표시 규칙(`format`·`render`)은 쓰지 않는다:
+ * 원시값이 맞는 내보내기(다시 적재)가 있고, 라벨이 맞는 열은 그것을 열 스스로 말한다.
+ */
+export declare function exportCellValue(row: DataRow, col: ColumnDefinition): unknown;
+/**
+ * 날짜로 내보낼 값이면 `Date` — 표시 경로(`@iyulab/components` `formatDate`)와 같은 규칙이다: `Date` 는 그대로, 날짜 열의
+ * 문자열은 `YYYY-MM-DD` 면 그 날(로컬 달력), 아니면 ISO 로 읽는다. 읽지 못하면 `null`(글자로 남긴다 — 버리지 않는다).
+ * JSON 으로 오는 소스(OData 포함)는 날짜가 문자열이라, 종전에는 날짜 열이어도 XLSX 에 글자 셀로 들어갔다.
+ */
+export declare function exportDate(value: unknown, col: ColumnDefinition): Date | null;
+/**
+ * Excel 직렬값 — **벽시계 시각**으로 센다(표가 보여 주는 로컬 날짜·시각과 같은 칸). 직렬값에는 시간대가 없어, UTC 시각으로
+ * 세면 로컬 자정의 날짜가 UTC 와 다른 시간대(한국 +09)에서 전날 오후로 들어가 날짜 서식에 전날이 보였다.
+ */
+export declare function excelSerial(d: Date): number;