@iyulab/flex-table 0.39.0 → 0.40.1

package/dist/flex-table.d.ts

@@ -88,7 +88,7 @@ export declare class FlexTable extends LitElement {
     /**
      * Constructable stylesheets adopted into this element's shadow root, in addition to the
      * grid's own styles. Cell renderers run inside the shadow root, so external document
-     * stylesheets (class-based utilities, design-system CSS) don't reach elements a `renderer`
+     * stylesheets (class-based utilities, design-system CSS) don't reach elements a `render` function
      * returns — this is the escape hatch for that. Not an attribute (a `CSSStyleSheet` can't be
      * serialized to one) — set it as a property.
      */

package/dist/flex-table.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./flex-table-JGaGcJTl.js";
-export { a as FlexTable, t as RowSelectionState, i as UndoStack, n as exportData, e as flexTableLocale, r as renderCell };
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-Dl5CYn-V.js";
+export { o as FlexTable, e as RowSelectionState, t as UndoStack, n as effectiveAlign, i as exportData, r as flexTableLocale, a as renderCell };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { FlexTable } from './flex-table.js';
-export type { ColumnDefinition, ColumnType, DataRow, CellRenderer, CellEditor, CellValidator, SelectionMode, DataMode, CellStyle, ConditionalRule } from './models/types.js';
+export type { ColumnDefinition, ColumnType, ColumnAlign, DataRow, CellRenderer, CellEditor, CellValidator, SelectionMode, DataMode, CellStyle, ConditionalRule } from './models/types.js';
+export { effectiveAlign } from './models/types.js';
 export type { CellPosition, CellRange } from './core/selection.js';
 export type { SortCriteria, SortDirection } from './core/sorting.js';
 export type { ColumnFilter, FilterPredicate, FilterErrorCallback } from './core/filtering.js';

package/dist/models/types.d.ts

@@ -4,6 +4,13 @@ import type { TemplateResult } from 'lit';
  * Any string is accepted as a type — unknown types fall back to 'text' behavior.
  */
 export type ColumnType = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | (string & {});
+/** Logical horizontal alignment — `start`/`end` follow the writing direction. */
+export type ColumnAlign = 'start' | 'center' | 'end';
+/** The alignment a column's cells render with: `align`, or the default derived from `type`. */
+export declare function effectiveAlign(col: {
+    align?: ColumnAlign;
+    type?: ColumnType;
+}): ColumnAlign;
 /** Option item for select columns */
 export interface SelectOption {
     label: string;
@@ -47,8 +54,8 @@ export type DataMode = 'client' | 'server';
 export interface ColumnDefinition<T = DataRow> {
     /** Unique key matching data property names */
     key: string;
-    /** Display header text */
-    header: string;
+    /** Column header text */
+    label: string;
     /** Data type for rendering/editing (default: 'text'). Unknown types fall back to 'text'. */
     type?: ColumnType;
     /** Column width in pixels (default: auto) */
@@ -60,14 +67,19 @@ export interface ColumnDefinition<T = DataRow> {
     /** Whether the column is sortable (default: true) */
     sortable?: boolean;
     /**
-     * Horizontal alignment of the header label (default: 'start').
-     * Independent of cell content alignment — a consumer centering cell content
-     * via a custom `renderer` (e.g. an icon-only action column) sets this to
-     * 'center' so the header visually matches.
+     * Horizontal alignment of cell content. Logical values, so right-to-left locales mirror.
+     * Default: derived from `type` — 'end' for 'number', 'center' for 'boolean', 'start' otherwise.
+     */
+    align?: ColumnAlign;
+    /**
+     * Horizontal alignment of the header label.
+     * Default: the column's effective cell alignment (`align`, or the `type` default above), so a
+     * right-aligned number column gets a right-aligned header. Set it only when the header should
+     * differ from its values.
      */
-    headerAlign?: 'start' | 'center' | 'end';
+    headerAlign?: ColumnAlign;
     /** Custom cell renderer — overrides built-in type rendering */
-    renderer?: CellRenderer<T>;
+    render?: CellRenderer<T>;
     /** Whether the column is editable (default: true — follows global editable setting) */
     editable?: boolean;
     /** Custom cell editor — overrides built-in type editing */

package/dist/odata/index.d.ts

@@ -1,2 +1,2 @@
-export { useODataSource, buildSearchExpression, parseOrderBy } from './use-odata-source.js';
-export type { UseODataSourceOptions, UseODataSourceResult } from './types.js';
+export { buildSearchExpression, parseOrderBy, buildODataQuery } from './query.js';
+export type { ODataQueryState } from './query.js';

package/dist/odata/index.js

@@ -1,2 +1,2 @@
-import { i as e, n as t, t as n } from "../use-odata-source-BiZrIEVV.js";
-export { n as buildSearchExpression, t as parseOrderBy, e as useODataSource };
+import { n as e, r as t, t as n } from "../query-Dw4iO0ir.js";
+export { n as buildODataQuery, e as buildSearchExpression, t as parseOrderBy };

package/dist/odata/query.d.ts

@@ -0,0 +1,72 @@
+import type { SortCriteria } from '../core/sorting.js';
+/**
+ * 검색어를 OData `$search` 표현식으로 인코딩한다 (`red shirt` → `"red" AND "shirt"`).
+ *
+ * 토큰을 인용하는 이유: OData 4.0의 `searchWord`는 문자(Unicode L/Nl)만 허용해
+ * `2026`·`ZT-E2E-A` 같은 검색어가 거부된다. 4.01이 숫자·하이픈을 허용하도록 완화했으나
+ * Microsoft.OData 렉서는 아직 4.0 규칙이다(odata.net#2445). `searchPhrase`는 두 버전
+ * 모두에서 적법하므로 서버 버전과 무관하게 안전하다.
+ *
+ * 통째로가 아니라 토큰별로 감싸는 이유: 인용 없는 다중 단어는 암묵 AND로 파싱되므로
+ * (`searchAndExpr = RWS [ 'AND' RWS ] searchExpr`), 전체를 한 phrase로 감싸면 연속
+ * 문자열 매칭으로 의미가 바뀐다. 토큰별 인용은 기존 의미론을 그대로 보존한다.
+ *
+ * `"`는 phrase 안에 넣을 수 없고 이스케이프 규칙도 없어(`qchar-no-AMP-DQUOTE`) 제거한다.
+ *
+ * @returns `$search` 표현식, 또는 유효 토큰이 없으면 `undefined`
+ */
+export declare function buildSearchExpression(term: string): string | undefined;
+/** `resolveInitialState`가 읽는 옵션 — 두 소스 훅의 옵션 타입이 공통으로 갖는 부분. */
+export interface InitialSourceStateOptions {
+    defaultOrderBy?: string;
+    initialPage?: number;
+    initialSearch?: string;
+    initialSort?: SortCriteria[];
+}
+/**
+ * 옵션에서 `page`/`search`/`sortCriteria`의 **초기값**을 뽑는다.
+ *
+ * ★**두 훅이 이 함수 하나를 공유하는 것이 요점이다.** README가 *"same shape … so the same
+ * binding code works with either source"*를 계약으로 선언하는데, 초기값 해석을 양쪽에
+ * 복제하면 그 계약이 **문장으로만** 유지된다 — 이 리포가 반복 기록한 실패 형태다.
+ * 구현이 하나면 드리프트가 없다.
+ *
+ * ⚠**`initialSort`가 `defaultOrderBy`를 이긴다.** 둘은 같은 것을 서로 다른 표기로
+ * 말하고(`SortCriteria[]` ↔ `$orderby` 문자열), 더 구체적인 쪽을 우선한다.
+ * `initialSort`는 `onSortChange`가 주는 모양 그대로라 저장해 둔 정렬을 파싱 없이 되돌린다.
+ *
+ * ⚠**React가 useState 초기값을 첫 렌더에서만 읽는다는 사실이 계약의 일부다** — 이후의
+ * 옵션 변경은 무시되고, 이동은 `setPage`/`setSearch`로 한다. `defaultOrderBy`가 이미
+ * 그렇게 동작해 왔으므로 새 규칙이 아니다.
+ */
+export declare function resolveInitialState(options: InitialSourceStateOptions): {
+    page: number;
+    search: string;
+    sortCriteria: SortCriteria[];
+};
+/**
+ * `$orderby` 문자열을 정렬 기준 배열로 파싱한다 (`'a asc, b desc'`).
+ * 방향이 생략되거나 `desc`가 아니면 `asc`로 본다(OData 기본값).
+ */
+export declare function parseOrderBy(orderBy: string): SortCriteria[];
+/** `buildODataQuery` 가 읽는 표 상태 — `useODataSource` 가 요청마다 넘기는 것과 같은 모양. */
+export interface ODataQueryState {
+    /** 0부터 세는 페이지 번호. */
+    page: number;
+    pageSize: number;
+    sortCriteria?: SortCriteria[];
+    /** 정렬 기준이 비었을 때 쓰는 `$orderby` 문자열. */
+    defaultOrderBy?: string;
+    /** 사용자가 친 검색어(리터럴) — `buildSearchExpression` 으로 인코딩된다. */
+    search?: string;
+    /** odata-query 의 필터 객체(`{ IsActive: true }` 등). */
+    fixedFilter?: Record<string, unknown>;
+}
+/**
+ * 표 상태를 OData 쿼리 문자열(`?$top=…&$skip=…&$count=true…`)로 만든다.
+ *
+ * `useODataSource` 가 요청마다 하는 일 그대로다 — 훅 밖으로 꺼낸 이유는 `buildSearchExpression` 과
+ * 같다: React 없이 서버 페이징을 하는 소비자(Lit 앱의 표, 표가 아닌 목록)가 같은 쿼리를
+ * 재구현하지 않게. 정렬 기준이 있으면 그것이, 없으면 `defaultOrderBy` 가 `$orderby` 가 된다.
+ */
+export declare function buildODataQuery(state: ODataQueryState): string;

package/dist/odata/use-odata-source.d.ts

@@ -1,57 +1,6 @@
-import type { SortCriteria } from '../core/sorting.js';
 import type { UseODataSourceOptions, UseODataSourceResult } from './types.js';
-/**
- * 검색어를 OData `$search` 표현식으로 인코딩한다 (`red shirt` → `"red" AND "shirt"`).
- *
- * 토큰을 인용하는 이유: OData 4.0의 `searchWord`는 문자(Unicode L/Nl)만 허용해
- * `2026`·`ZT-E2E-A` 같은 검색어가 거부된다. 4.01이 숫자·하이픈을 허용하도록 완화했으나
- * Microsoft.OData 렉서는 아직 4.0 규칙이다(odata.net#2445). `searchPhrase`는 두 버전
- * 모두에서 적법하므로 서버 버전과 무관하게 안전하다.
- *
- * 통째로가 아니라 토큰별로 감싸는 이유: 인용 없는 다중 단어는 암묵 AND로 파싱되므로
- * (`searchAndExpr = RWS [ 'AND' RWS ] searchExpr`), 전체를 한 phrase로 감싸면 연속
- * 문자열 매칭으로 의미가 바뀐다. 토큰별 인용은 기존 의미론을 그대로 보존한다.
- *
- * `"`는 phrase 안에 넣을 수 없고 이스케이프 규칙도 없어(`qchar-no-AMP-DQUOTE`) 제거한다.
- *
- * @returns `$search` 표현식, 또는 유효 토큰이 없으면 `undefined`
- */
-export declare function buildSearchExpression(term: string): string | undefined;
-/** `resolveInitialState`가 읽는 옵션 — 두 소스 훅의 옵션 타입이 공통으로 갖는 부분. */
-export interface InitialSourceStateOptions {
-    defaultOrderBy?: string;
-    initialPage?: number;
-    initialSearch?: string;
-    initialSort?: SortCriteria[];
-}
-/**
- * 옵션에서 `page`/`search`/`sortCriteria`의 **초기값**을 뽑는다.
- *
- * ★**두 훅이 이 함수 하나를 공유하는 것이 요점이다.** README가 *"same shape … so the same
- * binding code works with either source"*를 계약으로 선언하는데, 초기값 해석을 양쪽에
- * 복제하면 그 계약이 **문장으로만** 유지된다 — 이 리포가 반복 기록한 실패 형태다.
- * 구현이 하나면 드리프트가 없다.
- *
- * ⚠**`initialSort`가 `defaultOrderBy`를 이긴다.** 둘은 같은 것을 서로 다른 표기로
- * 말하고(`SortCriteria[]` ↔ `$orderby` 문자열), 더 구체적인 쪽을 우선한다.
- * `initialSort`는 `onSortChange`가 주는 모양 그대로라 저장해 둔 정렬을 파싱 없이 되돌린다.
- *
- * ⚠**React가 useState 초기값을 첫 렌더에서만 읽는다는 사실이 계약의 일부다** — 이후의
- * 옵션 변경은 무시되고, 이동은 `setPage`/`setSearch`로 한다. `defaultOrderBy`가 이미
- * 그렇게 동작해 왔으므로 새 규칙이 아니다.
- */
-export declare function resolveInitialState(options: InitialSourceStateOptions): {
-    page: number;
-    search: string;
-    sortCriteria: SortCriteria[];
-};
 /**
  * OData v4 서버 사이드 데이터소스 React 훅.
  * flex-table의 dataMode="server"와 함께 사용한다.
  */
 export declare function useODataSource<T = Record<string, unknown>>(url: string, options?: UseODataSourceOptions): UseODataSourceResult<T>;
-/**
- * `$orderby` 문자열을 정렬 기준 배열로 파싱한다 (`'a asc, b desc'`).
- * 방향이 생략되거나 `desc`가 아니면 `asc`로 본다(OData 기본값).
- */
-export declare function parseOrderBy(orderBy: string): SortCriteria[];

package/dist/query-Dw4iO0ir.js

@@ -0,0 +1,37 @@
+import e from "odata-query";
+//#region src/odata/query.ts
+function t(e) {
+	let t = e.split(/\s+/).map((e) => e.replace(/"/g, "")).filter((e) => e.length > 0);
+	if (t.length !== 0) return t.map((e) => `"${e}"`).join(" AND ");
+}
+function n(e) {
+	let { defaultOrderBy: t, initialPage: n = 0, initialSearch: i = "", initialSort: a } = e;
+	return {
+		page: n,
+		search: i,
+		sortCriteria: a ?? (t ? r(t) : [])
+	};
+}
+function r(e) {
+	return e.split(",").map((e) => {
+		let t = e.trim().split(/\s+/);
+		return {
+			key: t[0],
+			direction: t[1]?.toLowerCase() === "desc" ? "desc" : "asc"
+		};
+	});
+}
+function i(n) {
+	let { page: r, pageSize: i, sortCriteria: a = [], defaultOrderBy: o, search: s, fixedFilter: c } = n, l = a.length > 0 ? a.map((e) => `${e.key} ${e.direction}`).join(", ") : o, u = {
+		top: i,
+		skip: r * i,
+		count: !0
+	};
+	if (l && (u.orderBy = l), c && (u.filter = c), s) {
+		let e = t(s);
+		e && (u.search = e);
+	}
+	return e(u);
+}
+//#endregion
+export { n as i, t as n, r, i as t };

package/dist/react-events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/react.d.ts

@@ -27,6 +27,13 @@ declare const FlexTableReactBase: import("@lit/react").ReactWebComponent<FlexTab
     onBatchUpdate: EventName<CustomEvent>;
     onContextMenu: EventName<CustomEvent>;
     onFilterError: EventName<CustomEvent>;
+    onRowReorder: EventName<CustomEvent>;
+    onColumnVisibilityChange: EventName<CustomEvent>;
+    onCommentChange: EventName<CustomEvent>;
+    onDataImport: EventName<CustomEvent>;
+    onFillHandleApply: EventName<CustomEvent>;
+    onFindReplace: EventName<CustomEvent>;
+    onHeaderContextMenu: EventName<CustomEvent>;
 }>;
 type BaseProps = React.ComponentProps<typeof FlexTableReactBase>;
 /**
@@ -43,18 +50,22 @@ export type FlexTableReactProps<T = DataRow> = Omit<BaseProps, 'data' | 'columns
  * The underlying custom element (`FlexTable`) is a single registered class and cannot
  * itself be generic across instances — the DOM has no notion of `FlexTable<Order>` vs
  * `FlexTable<Consumer>`. `FlexTableReact<T>` performs one internal cast at this boundary
- * so consumers get end-to-end type safety (`data`, `columns`, `renderer`/`editor`/`validator`
+ * so consumers get end-to-end type safety (`data`, `columns`, `render`/`editor`/`validator`
  * callbacks) without casting at every call site.
  *
  * @example
  * ```tsx
  * const columns: ColumnDefinition<Order>[] = [
- *   { key: 'id', header: 'ID' },
- *   { key: 'total', header: 'Total', renderer: (v, row) => `${row.total} ${row.currency}` },
+ *   { key: 'id', label: 'ID' },
+ *   { key: 'total', label: 'Total', render: (v, row) => `${row.total} ${row.currency}` },
  * ];
  * <FlexTableReact<Order> data={orders} columns={columns} />
  * ```
  */
 export declare const FlexTableReact: <T = DataRow>(props: FlexTableReactProps<T> & React.RefAttributes<FlexTable>) => React.ReactElement | null;
 export type { FlexTable };
-export type { ColumnDefinition, DataRow, ColumnType, CellRenderer, CellEditor, CellValidator, ConditionalRule, SelectionMode, DataMode } from './models/types.js';
+export type { ColumnDefinition, DataRow, ColumnType, ColumnAlign, CellRenderer, CellEditor, CellValidator, ConditionalRule, SelectionMode, DataMode } from './models/types.js';
+export { useODataSource } from './odata/use-odata-source.js';
+export type { UseODataSourceOptions, UseODataSourceResult } from './odata/types.js';
+export { useArraySource } from './array/use-array-source.js';
+export type { UseArraySourceOptions, UseArraySourceResult } from './array/types.js';

package/dist/react.js

@@ -1,10 +1,146 @@
-import { t as e } from "./flex-table-JGaGcJTl.js";
-import t from "react";
-import { createComponent as n } from "@lit/react";
-var r = n({
+import { t as e } from "./flex-table-Dl5CYn-V.js";
+import { i as t, t as n } from "./query-Dw4iO0ir.js";
+import { t as r } from "./view-DiLr-TdY.js";
+import i, { useCallback as a, useEffect as o, useMemo as s, useRef as c, useState as l } from "react";
+import { createComponent as u } from "@lit/react";
+//#region src/odata/use-odata-source.ts
+function d(e, r = {}) {
+	let { pageSize: i = 20, defaultOrderBy: s, initialPage: u = 0, initialSearch: d = "", initialSort: f, fixedFilter: p, baseUrl: m, fetcher: h = fetch, onUnauthorized: g, enabled: _ = !0 } = r, v = p ? JSON.stringify(p) : "", [y, b] = l([]), [x, S] = l(0), [C, w] = l(!1), [T, E] = l(null), D = t({
+		defaultOrderBy: s,
+		initialPage: u,
+		initialSearch: d,
+		initialSort: f
+	}), [O, k] = l(D.page), [A, j] = l(D.sortCriteria), [M, N] = l(D.search), [P, F] = l(0), [I, L] = l(v);
+	v !== I && (L(v), k(0));
+	let R = c(null), z = a(() => {
+		F((e) => e + 1);
+	}, []), B = a((e) => {
+		N(e), k(0);
+	}, []), V = a((e) => {
+		let t = e.detail?.criteria;
+		t && (j(t), k(0));
+	}, []);
+	return o(() => {
+		if (R.current?.abort(), !_) return;
+		let t = new AbortController();
+		R.current = t, w(!0), E(null);
+		let r = n({
+			page: O,
+			pageSize: i,
+			sortCriteria: A,
+			defaultOrderBy: s,
+			search: M,
+			fixedFilter: p
+		}), a = `${m ?? window.location.origin}${e}${r}`, o = async (e) => {
+			let n = await h(e, { signal: t.signal });
+			if (!n.ok) {
+				(n.status === 401 || n.status === 403) && g && g(n);
+				let e = await n.text().catch(() => ""), t = `Request failed (${n.status})`;
+				try {
+					let n = JSON.parse(e);
+					t = n?.error?.message ?? n?.message ?? t;
+				} catch {}
+				throw Error(t);
+			}
+			return n.json();
+		};
+		return (async () => {
+			let e = await o(a), t = [...e.value ?? e], n = new URL(a).origin, r = /* @__PURE__ */ new Set([a]), s = a, c = e["@odata.nextLink"];
+			for (; typeof c == "string" && c && t.length < i;) {
+				let e = new URL(c, s);
+				if (e.origin !== n) throw Error(`OData nextLink points outside the source origin (${e.origin})`);
+				if (s = e.toString(), r.has(s)) throw Error(`OData nextLink repeats an already-read page (${s})`);
+				r.add(s);
+				let i = await o(s);
+				t.push(...i.value ?? []), c = i["@odata.nextLink"];
+			}
+			return {
+				count: e["@odata.count"],
+				rows: t
+			};
+		})().then(({ count: e, rows: n }) => {
+			if (t.signal.aborted) return;
+			let r = e ?? 0;
+			b(n), S(r), E(null);
+			let a = r === 0 ? 0 : Math.ceil(r / i) - 1;
+			O > a && k(a);
+		}).catch((e) => {
+			t.signal.aborted || e.name !== "AbortError" && (E(e.message), b([]), S(0));
+		}).finally(() => {
+			t.signal.aborted || w(!1);
+		}), () => t.abort();
+	}, [
+		_,
+		e,
+		O,
+		i,
+		A,
+		M,
+		v,
+		s,
+		P,
+		m
+	]), {
+		data: y,
+		totalCount: x,
+		loading: C || !_,
+		error: T,
+		page: O,
+		setPage: k,
+		sortCriteria: A,
+		onSortChange: V,
+		search: M,
+		setSearch: B,
+		refresh: z
+	};
+}
+//#endregion
+//#region src/array/use-array-source.ts
+function f(e, n = {}) {
+	let { pageSize: i = 20, defaultOrderBy: o, initialPage: c = 0, initialSearch: u = "", initialSort: d, columns: f, searchFields: p } = n, m = t({
+		defaultOrderBy: o,
+		initialPage: c,
+		initialSearch: u,
+		initialSort: d
+	}), [h, g] = l(m.page), [_, v] = l(m.sortCriteria), [y, b] = l(m.search), x = a((e) => {
+		b(e), g(0);
+	}, []), S = a((e) => {
+		let t = e.detail?.criteria;
+		t && (v(t), g(0));
+	}, []), C = a(() => {}, []), { data: w, totalCount: T } = s(() => r(e, {
+		search: y,
+		sortCriteria: _,
+		page: h,
+		pageSize: i,
+		columns: f,
+		searchFields: p
+	}), [
+		e,
+		y,
+		_,
+		h,
+		i,
+		f,
+		p
+	]), E = T === 0 ? 0 : Math.ceil(T / i) - 1;
+	return h > E && g(E), {
+		data: w,
+		totalCount: T,
+		loading: !1,
+		error: null,
+		page: h,
+		setPage: g,
+		sortCriteria: _,
+		onSortChange: S,
+		search: y,
+		setSearch: x,
+		refresh: C
+	};
+}
+var p = u({
 	tagName: "flex-table",
 	elementClass: e,
-	react: t,
+	react: i,
 	events: {
 		onCellSelect: "cell-select",
 		onCellEditCommit: "cell-edit-commit",
@@ -29,8 +165,15 @@ var r = n({
 		onValidationError: "validation-error",
 		onBatchUpdate: "batch-update",
 		onContextMenu: "context-menu",
-		onFilterError: "filter-error"
+		onFilterError: "filter-error",
+		onRowReorder: "row-reorder",
+		onColumnVisibilityChange: "column-visibility-change",
+		onCommentChange: "comment-change",
+		onDataImport: "data-import",
+		onFillHandleApply: "fill-handle-apply",
+		onFindReplace: "find-replace",
+		onHeaderContextMenu: "header-context-menu"
 	}
 });
 //#endregion
-export { r as FlexTableReact };
+export { p as FlexTableReact, f as useArraySource, d as useODataSource };

package/dist/view-DiLr-TdY.js

@@ -0,0 +1,13 @@
+import { t as e } from "./sorting-CjfjRxwL.js";
+//#region src/array/view.ts
+function t(t, { search: n, sortCriteria: r, page: i, pageSize: a, columns: o, searchFields: s }) {
+	let c = n.trim().toLowerCase(), l = c ? t.filter((e) => (s ? s(e) : Object.values(e)).some((e) => e != null && String(e).toLowerCase().includes(c))) : t, u = l;
+	r.length > 0 && (u = e(l, r, o ?? []).map((e) => l[e]));
+	let d = u.length, f = d === 0 ? 0 : Math.ceil(d / a) - 1, p = Math.min(Math.max(i, 0), f) * a;
+	return {
+		data: u.slice(p, p + a),
+		totalCount: d
+	};
+}
+//#endregion
+export { t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
     "CHANGELOG.md",
@@ -71,7 +72,7 @@
     "odata-query": "^8.1.0"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.27.0",
+    "@iyulab/components": ">=1.51.0",
     "@lit/react": "^1.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },

package/skills/iyulab-flex-table/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: iyulab-flex-table
+description: Spreadsheet-grade data grid web component (`<flex-table>`, built with Lit) with virtual scrolling, inline cell editing, validation, range selection, clipboard, undo/redo, sorting, filtering, pinned columns, and CSV/TSV/JSON/XLSX export, plus a React wrapper and OData / in-memory data-source hooks. Use when working with @iyulab/flex-table — defining columns, editing cells, handling grid events, wiring server-side paging with useODataSource or useArraySource, or styling the grid.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.40.1"
+---
+
+# @iyulab/flex-table
+
+A schema-agnostic data grid custom element (`<flex-table>`) for large datasets and cell-level editing.
+Rows are plain objects (`DataRow = Record<string, unknown>`); columns describe how to show and edit them.
+
+## Install
+
+```bash
+npm install @iyulab/flex-table @iyulab/components
+# React wrapper and hooks (optional peers)
+npm install @lit/react react
+```
+
+`@iyulab/components` is a peer dependency (locale, formatting, design tokens).
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@iyulab/flex-table` | Registers `<flex-table>`; exports `FlexTable`, types, `exportData`, `renderCell`, `flexTableLocale`, `RowSelectionState`, `UndoStack`, `effectiveAlign` |
+| `@iyulab/flex-table/react` | `FlexTableReact`, `useODataSource`, `useArraySource` |
+| `@iyulab/flex-table/odata` | Pure helpers, no React: `buildODataQuery`, `buildSearchExpression`, `parseOrderBy` |
+| `@iyulab/flex-table/array` | Pure helper, no React: `computeArrayView` |
+
+## Quick start
+
+```html
+<flex-table id="table" style="height: 400px" show-row-numbers></flex-table>
+
+<script type="module">
+  import '@iyulab/flex-table';
+
+  const table = document.getElementById('table');
+  table.columns = [
+    { key: 'name', label: 'Name', type: 'text', width: 200 },
+    { key: 'age', label: 'Age', type: 'number', width: 100 },
+    { key: 'active', label: 'Active', type: 'boolean', width: 80 },
+  ];
+  table.data = [
+    { name: 'Alice', age: 30, active: true },
+    { name: 'Bob', age: 25, active: false },
+  ];
+  table.addEventListener('cell-edit-commit', (e) => console.log(e.detail));
+</script>
+```
+
+## Key concepts
+
+**Give it a height.** The host is its own scroll container and virtualizes against its own height.
+Without a height (or a constrained flex parent with `min-height: 0`), every row is rendered.
+
+**Columns.** Each `ColumnDefinition` needs `key` and `label`. `type` picks the built-in
+renderer/editor (`text`, `number`, `boolean`, `date`, `datetime`, `select`; unknown strings behave
+as `text`). See `references/api.md` for every field.
+
+- `format` changes only the displayed text (`'#,##0.00'`, `'0.00%'`, `'yyyy-MM-dd'`, or a function); sorting, filtering, editing and export keep the raw value.
+- `render` replaces the cell content (`(value, row, col) => TemplateResult | string`) and wins over `format`.
+- `editor` returns a Lit template containing an element with class `ft-editor`; its `.value` is committed.
+- `validator` returns `null` when valid, or an error message (the edit is rejected and `validation-error` fires).
+- `conditionalRules` applies `{ when, style }` rules in order; later matches override earlier ones.
+- `pinned: 'left' | 'right'` freezes a column during horizontal scroll.
+
+**Data is mutated in place.** Assigning a new array re-renders; changing a row object does not.
+Use `updateRows([{ row, key, value }])` for programmatic edits (undoable, fires `batch-update`) or
+`refreshData()` after an external in-place mutation.
+
+**Editing and read-only.** `editable` defaults to `true`. For a read-only grid set
+`table.editable = false` (a property, since a boolean attribute cannot express `false`) — Enter on a non-editable cell then fires
+`row-activate`, the grid's "open this row" contract.
+
+**Row selection is index-based.** Enable with `selectable` (`selection-mode="single|multi"`).
+There is no row key, so set `clear-selection-on-data-change` when selection drives bulk actions and
+`data` can be replaced. `selectWhere(predicate)` selects rows by content.
+
+**Client vs server mode.** `data-mode="client"` (default) sorts and filters locally.
+`data-mode="server"` only emits `sort-change` / `filter-change`; you supply already-processed rows.
+
+**Filtering.** Programmatic `setFilter(key, (value, row) => boolean)`; `show-filters` adds a
+**Filter…** entry to each column's header menu (text, number range, boolean, date/datetime range).
+Both share one filter state.
+
+**Undo/redo** covers edits, row and column operations, paste and comments (`max-undo-size`, default 100).
+
+## React
+
+```tsx
+import { useRef } from 'react';
+import { FlexTableReact, type FlexTable, type ColumnDefinition } from '@iyulab/flex-table/react';
+
+interface Order { id: string; total: number; currency: string }
+
+const columns: ColumnDefinition<Order>[] = [
+  { key: 'id', label: 'ID' },
+  { key: 'total', label: 'Total', render: (_v, row) => `${row.total} ${row.currency}` },
+];
+
+function Orders({ orders }: { orders: Order[] }) {
+  const ref = useRef<FlexTable>(null);
+  return (
+    <FlexTableReact<Order>
+      ref={ref}
+      data={orders}
+      columns={columns}
+      selectable
+      onCellEditCommit={(e) => console.log(e.detail)}
+    />
+  );
+}
+```
+
+Server paging from OData or an in-memory array uses the same binding — see `references/react.md`.
+
+## Common pitfalls
+
+- No height → no virtualization.
+- `--ft-row-height` is read once at first render; change row height later via `rowHeight` / `row-height`.
+- Styles for elements returned by `render` must be passed through the `stylesheets` property
+  (constructable `CSSStyleSheet[]`); document CSS does not cross the shadow boundary.
+- `useODataSource` `fetcher` / `onUnauthorized` must be stable references (`useCallback`).
+- Always render `error` from `useODataSource`; a failed request otherwise leaves the grid empty.
+
+## References
+
+- [references/api.md](references/api.md) — properties, column definition, methods, events
+- [references/react.md](references/react.md) — `FlexTableReact`, `useODataSource`, `useArraySource`, pure OData/array helpers
+- [references/styling.md](references/styling.md) — CSS custom properties, density, keyboard shortcuts, localization