@iyulab/flex-table 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [0.64.0] - 2026-10-08
+
+### Added
+
+- **`useODataSource` and `useArraySource` return `source`** — the source the hook binds, the same object every render.
+  A React screen hands it to a list skeleton that binds its views itself (`<ListPage source={orders.source}>`,
+  `bindSource(orders.source, el)`) and keeps its options as props, instead of building the source with `useMemo`,
+  reading it with `useSyncExternalStore` and calling `update` from an effect. `useArraySource`'s `source` reads the
+  hook's state and notifies its subscribers after each commit.
+
+## [0.63.0] - 2026-10-08
+
+### Added
+
+- **Dot-path column keys** — `{ key: 'Customer.Name' }` reads `row.Customer.Name`, so a referenced record's name is a
+  column. Display, `format`, sorting, filtering, copying, editing, import and export read and write the cell through the
+  same path (`getCellValue` / `setCellValue`, now exported); a property named by the whole key (`'@odata.etag'`) still
+  wins. The server sort of such a column is the OData path (`$orderby=Customer/Name`), and `parseOrderBy` reads it back
+  as the column key.
+- **`createODataSource` / `useODataSource` `expand` and `select`** — `$expand` (a string or an array) and `$select`,
+  sent by the page reads and by `fetchAll` alike; changing either re-reads. `buildODataQuery` takes them too.
+
+- **`importFromFile` reports what did not come in.** It returns an `ImportReport` — and `data-import` now carries the
+  same object — `{ count, unmatchedHeaders, missingColumns, coercionFailures }`: file headers no column matched (their
+  values were dropped without a trace before), columns the file lacks, and cells that are not their column's type
+  (`{ row, key, raw }` — the cell keeps its text). `null` for a file type it does not read.
+- **`ColumnDefinition.importAliases`** — other headers a file may give the column (a template a person made says
+  «관리 번호» where the label is «관리번호»). Headers now also match ignoring surrounding spaces.
+- `flexTableLocale` keys `booleanTrueWords` / `booleanFalseWords` — the words a boolean column reads as true and false
+  (`yes,y` / `no,n`; Korean `예,네` / `아니오,아니요`), besides `true`/`false`/`1`/`0` and the locale's labels.
+
+### Changed
+
+- **A boolean column keeps text it cannot read** — on import and on paste — instead of turning it into `false`.
+  «예», «Y» or «yes» became «no»; now the words above are read and anything else stays as written (and is reported on
+  import), as `number` and `date` columns already did.
+
+### Fixed
+
+- **A comma-separated `.csv` imports.** It was read as tab-separated, so each line became one cell under an unmatched
+  header and the whole file came in as empty rows. A CSV may now be separated by commas or semicolons (Excel on
+  comma-decimal locales), detected from the header line.
+- A CSV that starts with a byte-order mark — as `exportToFile` writes it — reads back: the mark was part of the first
+  header, so that column did not match.
+- Two file headers that match the same column no longer both write into it; the second is reported as unmatched.
+
+- **A hidden `flex-table` is hidden.** Its host's `display: block` outranked the browser's `[hidden]` rule, so
+  `hidden` did nothing — a list that switches between a table and a card view (which hides the view it is not
+  showing) drew both.
+
 ## [0.62.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -134,7 +134,7 @@ guarantee about a *constrained* host. `height-model.browser.test.ts` pins both s
 
 ```typescript
 interface ColumnDefinition {
-  key: string;             // Unique key matching data property names
+  key: string;             // The row property, or a dot path into a nested record ('Customer.Name' — see below)
   label: string;           // Column header text
   type?: ColumnType;       // 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' (any other string falls back to 'text')
   width?: number;          // Column width in pixels (default: auto)
@@ -166,6 +166,23 @@ A `number` column's built-in editor reads numbers the way people type them in th
 
 A `date` column's built-in editor is `u-date-picker` from `@iyulab/components`: a text box that shows and takes `YYYY-MM-DD` in every browser language (the native date input would show the browser's UI language, e.g. `10/02/2026`), with a calendar beside it — click the box or press ArrowDown, and a picked day is the new value. It also reads `2026/10/2`, `20261002` and `10-02` (this year), stores the ISO date string, and rejects text that is not a date (`error` is the localized "Enter a date as YYYY-MM-DD"). Pasted dates are read the same way. A `datetime` column's editor works the same with a time: it shows `YYYY-MM-DD HH:mm` in local time, reads `2026-10-02 14:05` (a date alone is midnight), and stores the local `YYYY-MM-DDTHH:mm` string; in its calendar a day and a time are applied together with Apply. While the calendar is open, Escape closes the calendar; the next Escape cancels the edit.
 
+### Nested values — dot-path keys
+
+A `key` may be a path into a nested record: `{ key: 'Customer.Name', label: 'Customer' }` reads `row.Customer.Name` —
+what a server list gets from OData `$expand` (the source's `expand` option). Display, `format`, sorting, filtering,
+copying, editing, import and export all read and write the cell through the same path, and the server sort of that
+column is `$orderby=Customer/Name`. A row that has a property named by the whole key (`'@odata.etag'`) gives that
+property; the path is read only when the name is not there. `getCellValue(row, key)` / `setCellValue(row, key, value)`
+(root entry) are the functions the table uses.
+
+```typescript
+const source = createODataSource('/api/orders', { expand: 'Customer($select=Name)' });
+const columns: ColumnDefinition[] = [
+  { key: 'Number', label: 'Order' },
+  { key: 'Customer.Name', label: 'Customer' }, // sortable on the server, exported as shown
+];
+```
+
 ### `format` vs `render`
 
 Both control how a cell's raw value is displayed, but they differ in what they replace:
@@ -323,6 +340,32 @@ try {
 Without a table, `exportDataBlob(rows, columns, format)` and `downloadBlob(blob, filename)` (root entry) do the same
 — `exportData` stays synchronous and writes XLSX uncompressed.
 
+### Import
+
+`importFromFile(file)` reads an `.xlsx`, `.csv` or `.tsv` file into `data` (undoable) — also what dropping a file on a
+table with `import-enabled` does. The first row is the header: each header goes to the column whose `label` — or one
+of its `importAliases` — it matches, exactly first, then ignoring case and surrounding spaces. Each cell is read as its
+column's type, the same way pasting reads it. A CSV may be separated by commas or semicolons; the byte-order mark an
+export starts with is not part of the first header, so an exported file reads back as it was.
+
+Nothing is dropped silently. The returned report — the same object `data-import` carries — says what did not come in:
+
+```ts
+const report = await table.importFromFile(file); // null for a file type it does not read
+// { count: 120,
+//   unmatchedHeaders: ['비고2'],                          // their values were not imported
+//   missingColumns: ['since'],                            // empty in every imported row
+//   coercionFailures: [{ row: 4, key: 'qty', raw: 'many' }] } // the cell keeps its text
+```
+
+A boolean column reads `true`/`false`/`1`/`0`, the locale's true/false labels and its words (`flexTableLocale` keys
+`booleanTrueWords`/`booleanFalseWords` — `yes,y`/`no,n` in English, `예,네`/`아니오,아니요` in Korean); any other text
+stays text and is reported, rather than becoming `false`.
+
+```ts
+{ key: 'code', label: '관리번호', importAliases: ['관리 번호', 'Asset no.'] } // a template a person made
+```
+
 ## Events
 
 All events use `CustomEvent` with `bubbles: true, composed: true`. They are typed: `FlexTableEventMap` maps
@@ -349,7 +392,7 @@ type-checks without a cast. The React wrapper's `on*` props carry the same types
 | `row-activate` | `{ row, id, via, index, col, key }` | "Open this row" (e.g. navigate to a detail view): a plain click on a body cell (`via: 'click'`), or Enter on a non-editable cell (`via: 'keyboard'`). Not a Shift / Ctrl / Cmd click (those extend the selection), the click that ends a drag, or a click on a control the cell renders (a link, a button). The grid's own contract — its Enter handler keeps the keystroke from reliably reaching a listener the host attaches to the same element |
 | `batch-update` | `{ changes: [{ row, key, oldValue, newValue }] }` | Batch update applied |
 | `row-reorder` | `{ from, to }` | Row dragged to a new place (data indices) |
-| `data-import` | `{ count }` | Rows imported from a file |
+| `data-import` | `ImportReport` — `{ count, unmatchedHeaders, missingColumns, coercionFailures }` | Rows imported from a file (see Import) |
 | `fill-handle-apply` | `{ sourceRange, targetRange, cells }` | Fill handle wrote `cells` (`{ dataRow, key, oldValue, newValue }`) |
 | `find-replace` | `{ type, cells }` | Replace (`type: 'replace'`) or replace-all from the find panel; `cells` are `{ row, col, oldValue, newValue }` with `col` the column key |
 | `comment-change` | `{ dataIndex, id, colKey, text }` | Cell comment set, changed or removed (`text: null`). Comments stay on their rows (`id`) when rows move |
@@ -796,6 +839,8 @@ const source = useODataSource('/api/orders', {
 | `initialSearch` | `''` | Initial search term |
 | `initialSort` | — | Initial sort as `SortCriteria[]`. Takes precedence over `defaultOrderBy` — it is the shape `onSortChange` hands you, so a stored sort round-trips without re-serializing it |
 | `fixedFilter` | — | Filter always applied in addition to search. Changing it resets the page to 0 — see below |
+| `expand` | — | `$expand` — referenced records to fetch with each row: `'Customer($select=Name),Owner'` or `['Customer', 'Owner']`. A column reads one with a dot-path key (`key: 'Customer.Name'`), and its server sort is `$orderby=Customer/Name`. The page reads and `fetchAll` send the same value |
+| `select` | — | `$select` — the properties to fetch; all when omitted |
 | `baseUrl` | `window.location.origin` | Override the request origin (proxy/BFF setups) |
 | `fetcher` | global `fetch` | Custom transport — pass a wrapper that injects auth headers |
 | `onUnauthorized` | — | Called on `401` responses, before the generic error is set. A `403` (signed in, not permitted) does not call it — it surfaces as `error` |
@@ -866,6 +911,7 @@ The hook returns:
 | `search` / `setSearch` | Current search term and its setter (resets to page 0) |
 | `refresh` | Re-run the current request |
 | `fetchAll` | The whole result of the current conditions — the source's `fetchAll` (below), for exporting what the list shows |
+| `source` | The source the hook binds (the same object every render) — hand it to a list skeleton that binds views itself: `<ListPage source={orders.source}>` (`@iyulab/enterprise/react`) or `bindSource(orders.source, element)`. `useArraySource` returns one too, over its own state |
 
 #### Search semantics
 

package/dist/array/index.js

@@ -1,5 +1,5 @@
-import { n as e, t, u as n } from "../fetch-all-J37bOtgc.js";
-import { n as r, t as i } from "../view-BtoXdUGF.js";
+import { n as e, t, u as n } from "../fetch-all-DkdNzWrF.js";
+import { n as r, t as i } from "../view-DuDIMoXV.js";
 //#region src/array/source.ts
 function a(e, t = {}) {
 	let a = e, o = t, s = n({

package/dist/array/types.d.ts

@@ -1,6 +1,7 @@
 import type { SortCriteria } from '../core/sorting.js';
 import type { SourceError } from '../core/source-error.js';
 import type { FetchAllOptions } from '../core/fetch-all.js';
+import type { ArraySource } from './source.js';
 export interface UseArraySourceOptions<T> {
     /** 페이지당 행 수. `useODataSource`와 동일 기본값. */
     pageSize?: number;
@@ -30,7 +31,11 @@ export interface UseArraySourceOptions<T> {
      */
     searchFields?: (row: T) => Array<string | number | boolean | null | undefined>;
 }
+/** `useArraySource` 의 `source` — 목록 골격(`ListPage` · `bindSource`)에 넘기는 소스. 이 훅의 상태를 읽고 조작은 훅으로 간다. */
+export type HookArraySource<T> = Omit<ArraySource<T>, 'update'>;
 export interface UseArraySourceResult<T> {
+    /** 이 훅의 상태를 소스 모양으로 — `<ListPage source={orders.source}>` · `bindSource(orders.source, el)`. 늘 같은 객체다. */
+    source: HookArraySource<T>;
     /** 현재 페이지의 행(검색+정렬 적용 후 slice). */
     data: T[];
     /** 검색+정렬 적용 후, 페이지 나누기 전의 총 건수(`useODataSource`의 `@odata.count`와 동일 의미). */

package/dist/clipboard/clipboard.d.ts

@@ -6,6 +6,17 @@ import type { ColumnDefinition, DataRow } from '../models/types.js';
  */
 export declare function copyToClipboard(data: DataRow[], columns: ColumnDefinition[], range: CellRange): string;
 export declare function parseValueForColumn(raw: string, col: ColumnDefinition): unknown;
+/**
+ * {@link parseValueForColumn} with the outcome: `failed` is true when the column has a type (`number`, `boolean`,
+ * `date`, `datetime`) and the text is not one — the value is then the text itself, unchanged. An importer reports
+ * those cells instead of losing them.
+ */
+export declare function parseCellForColumn(raw: string, col: ColumnDefinition): {
+    value: unknown;
+    failed: boolean;
+};
+/** A boolean as a spreadsheet writes it, or `null` when the text is not one. */
+export declare function parseBoolean(raw: string): boolean | null;
 /**
  * A number as a person edits it: the active locale's decimal separator, no grouping, every digit
  * kept (`1234.5` → `1234,5` on a German page). The inverse is {@link parseValueForColumn}.

package/dist/core/cell-value.d.ts

@@ -0,0 +1,13 @@
+import type { DataRow } from '../models/types.js';
+/**
+ * A column's value in a row. `key` is a property name, or a dot path into nested objects — `'Customer.Name'` reads
+ * `row.Customer.Name` (an OData `$expand`, a joined record). A row that has a property by the whole name (`'a.b'`,
+ * `'@odata.etag'`) gives that property: the path is only read when the name is not there. Every place the table reads
+ * a cell — display, format, sort, filter, copy, export — goes through this, so they agree.
+ */
+export declare function getCellValue(row: DataRow | null | undefined, key: string): unknown;
+/**
+ * Writes a column's value — the inverse of {@link getCellValue}: the property by the whole name when the row has it
+ * (or the key has no dot), otherwise the path, creating the objects along it that are missing.
+ */
+export declare function setCellValue(row: DataRow, key: string, value: unknown): void;

package/dist/events.d.ts

@@ -1,3 +1,4 @@
+import type { ImportReport } from './export/import.js';
 import type { CellPosition, CellRange } from './core/selection.js';
 import type { SortCriteria } from './core/sorting.js';
 import type { ColumnDefinition, DataRow } from './models/types.js';
@@ -143,10 +144,8 @@ export interface FlexTableEventMap {
         colKey: string;
         text: string | null;
     }>;
-    /** Rows were imported from a file; `count` is how many. */
-    'data-import': CustomEvent<{
-        count: number;
-    }>;
+    /** Rows were imported from a file — the same report `importFromFile` returns: `count`, and what did not come in. */
+    'data-import': CustomEvent<ImportReport>;
     'sort-change': CustomEvent<{
         criteria: SortCriteria[];
     }>;

package/dist/export/delimited-reader.d.ts

@@ -0,0 +1,11 @@
+import type { ImportedSheet } from './xlsx-reader.js';
+/**
+ * The separator a CSV file uses — `,` or, as Excel writes it on locales whose decimal mark is a comma, `;` (a tab
+ * also counts). Counted on the first line outside quotes; the most frequent wins, and `,` when none appears.
+ */
+export declare function detectDelimiter(text: string): string;
+/**
+ * A CSV or TSV file as a header row and data rows. The byte-order mark a spreadsheet-bound export starts with
+ * (`exportToFile` writes one) is not part of the first header.
+ */
+export declare function readDelimited(text: string, kind: 'csv' | 'tsv'): ImportedSheet;

package/dist/export/import.d.ts

@@ -0,0 +1,30 @@
+import type { ColumnDefinition, DataRow } from '../models/types.js';
+import type { ImportedSheet } from './xlsx-reader.js';
+/**
+ * What an import took in and what it could not — `importFromFile` returns it and `data-import` carries it, so a
+ * preview can show «what will not come in» before anything is saved.
+ */
+export interface ImportReport {
+    /** Rows imported. */
+    count: number;
+    /** File headers no column matched (by `label` or `importAliases`) — their values were not imported. */
+    unmatchedHeaders: string[];
+    /** Keys of the columns no file header matched — those cells are empty in every imported row. */
+    missingColumns: string[];
+    /**
+     * Cells whose text is not a value of the column's type (`number`, `boolean`, `date`, `datetime`). The cell keeps the
+     * text as it was. `row` is the 0-based index among the imported rows.
+     */
+    coercionFailures: {
+        row: number;
+        key: string;
+        raw: string;
+    }[];
+}
+/** File header → column key: the label or an alias, exactly first, then ignoring case and surrounding spaces. */
+export declare function matchHeaders(headers: string[], columns: ColumnDefinition[]): Map<number, string>;
+/** A parsed sheet as table rows, with the report of what did not come in. */
+export declare function buildImport(sheet: ImportedSheet, columns: ColumnDefinition[]): {
+    rows: DataRow[];
+    report: ImportReport;
+};

package/dist/{fetch-all-J37bOtgc.js → fetch-all-DkdNzWrF.js}

@@ -1,4 +1,4 @@
-import { n as e } from "./locale-D9g0ksXq.js";
+import { n as e } from "./locale-Covm8PfH.js";
 import t from "odata-query";
 //#region src/odata/query.ts
 function n(e) {
@@ -17,26 +17,29 @@ function i(e) {
 	return e.split(",").map((e) => {
 		let t = e.trim().split(/\s+/);
 		return {
-			key: t[0],
+			key: t[0].replace(/\//g, "."),
 			direction: t[1]?.toLowerCase() === "desc" ? "desc" : "asc"
 		};
 	});
 }
 function a(e) {
-	let { page: r = 0, pageSize: i, sortCriteria: a = [], defaultOrderBy: o, search: s, fixedFilter: c } = e, l = a.length > 0 ? a.map((e) => `${e.key} ${e.direction}`).join(", ") : o, u = i === void 0 ? { count: !0 } : {
+	return e.replace(/\./g, "/");
+}
+function o(e) {
+	let { page: r = 0, pageSize: i, sortCriteria: o = [], defaultOrderBy: s, search: c, fixedFilter: l, expand: u, select: d } = e, f = o.length > 0 ? o.map((e) => `${a(e.key)} ${e.direction}`).join(", ") : s, p = i === void 0 ? { count: !0 } : {
 		top: i,
 		skip: r * i,
 		count: !0
 	};
-	if (l && (u.orderBy = l), c && (u.filter = c), s) {
-		let e = n(s);
-		e && (u.search = e);
+	if (f && (p.orderBy = f), l && (p.filter = l), u && u.length > 0 && (p.expand = u), d && d.length > 0 && (p.select = d), c) {
+		let e = n(c);
+		e && (p.search = e);
 	}
-	return t(u);
+	return t(p);
 }
 //#endregion
 //#region src/core/source-error.ts
-async function o(t) {
+async function s(t) {
 	let n = await t.text().catch(() => ""), r = {
 		message: e("requestFailed", { status: t.status }),
 		status: t.status
@@ -49,10 +52,10 @@ async function o(t) {
 	if (r.body = i, !i || typeof i != "object") return r;
 	let a = i, o = a.error && typeof a.error == "object" ? a.error : a;
 	typeof o.message == "string" && o.message ? r.message = o.message : typeof a.message == "string" && a.message && (r.message = a.message), typeof o.code == "string" && o.code && (r.code = o.code);
-	let c = s(o.details);
-	return c && (r.details = c), r;
+	let s = c(o.details);
+	return s && (r.details = s), r;
 }
-function s(e) {
+function c(e) {
 	if (!Array.isArray(e)) return;
 	let t = e.filter((e) => {
 		if (!e || typeof e != "object") return !1;
@@ -61,26 +64,26 @@ function s(e) {
 	});
 	return t.length > 0 ? t : void 0;
 }
-var c = class extends Error {
+var l = class extends Error {
 	constructor(e) {
 		super(e.message), this.name = "SourceRequestError", this.failure = e;
 	}
-}, l = class extends c {
+}, u = class extends l {
 	constructor(t, n) {
 		super({ message: e("tooManyRows", { maxRows: t }) }), this.name = "RowLimitError", this.total = n, this.maxRows = t;
 	}
 };
-function u(t) {
-	return new c({
+function d(t) {
+	return new l({
 		message: e("networkFailed"),
 		cause: t
 	});
 }
-function d(e) {
-	return e instanceof c ? e.failure : e instanceof Error ? { message: e.message } : { message: String(e) };
+function f(e) {
+	return e instanceof l ? e.failure : e instanceof Error ? { message: e.message } : { message: String(e) };
 }
 //#endregion
 //#region src/core/fetch-all.ts
-var f = 1e5;
+var p = 1e5;
 //#endregion
-export { o as a, n as c, u as i, i as l, l as n, d as o, c as r, a as s, f as t, r as u };
+export { s as a, n as c, d as i, i as l, u as n, f as o, l as r, o as s, p as t, r as u };