@iyulab/flex-table 0.19.0 → 0.20.0

package/README.md

@@ -105,9 +105,11 @@ interface ColumnDefinition {
   sortable?: boolean;      // Enable sorting (default: true)
   editable?: boolean;      // Per-column edit control (follows global editable)
   pinned?: 'left' | 'right'; // Freeze column during horizontal scroll
+  format?: string | ((value, row, col) => string); // Display format, see "format vs renderer" below
   renderer?: 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
+  conditionalRules?: ConditionalRule[]; // Per-cell style rules, see below
 }
 ```
 
@@ -115,6 +117,42 @@ The `editor` callback must return a Lit `TemplateResult` containing an input ele
 
 The `validator` callback returns `null` if valid, or an error message string. On failure, the cell shows a red border for 3 seconds and a `validation-error` event is dispatched.
 
+### `format` vs `renderer`
+
+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) => 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.
+- **`renderer`**: 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
+const columns: ColumnDefinition<Order>[] = [
+  { key: 'total', header: 'Total', format: '#,##0.00' },                 // "1,234.50"
+  { key: 'placedAt', header: 'Placed', format: 'yyyy-MM-dd' },           // date pattern
+  { key: 'status', header: 'Status', renderer: (v) => html`<span class="badge badge-${v}">${v}</span>` },
+];
+```
+
+If both are set on the same column, `renderer` takes precedence — `format` has no effect once a custom `renderer` fully controls the cell's output.
+
+### Conditional Formatting
+
+`conditionalRules` applies a style to a cell when its `when` predicate matches — a declarative alternative to writing a `renderer` just to color-code status/threshold values:
+
+```typescript
+const columns: ColumnDefinition<Order>[] = [
+  {
+    key: 'status',
+    header: 'Status',
+    conditionalRules: [
+      { when: (v) => v === 'overdue', style: { color: '#dc2626', fontWeight: 'bold' } },
+      { when: (v) => v === 'paid', style: { color: '#16a34a' } },
+    ],
+  },
+];
+```
+
+Rules are evaluated in order and combined; later matching rules override earlier ones for overlapping style properties.
+
 ## Methods
 
 ### Row Operations
@@ -312,6 +350,27 @@ function App() {
 
 All `<flex-table>` properties are available as React props, and all custom events are mapped to `on*` callbacks (e.g., `cell-edit-commit` → `onCellEditCommit`).
 
+#### Imperative API via `ref`
+
+`FlexTableReact` forwards `ref` to the underlying `FlexTable` custom element instance, so all [Methods](#methods) (`addRow`, `deleteRows`, `selectAll`, `setFilter`, etc.) are reachable without re-rendering the whole table:
+
+```tsx
+import { useRef } from 'react';
+import { FlexTableReact, type FlexTable } from '@iyulab/flex-table/react';
+
+function App() {
+  const tableRef = useRef<FlexTable>(null);
+
+  return (
+    <>
+      <button onClick={() => tableRef.current?.addRow({ name: '', age: 0 })}>Add row</button>
+      <button onClick={() => tableRef.current?.deleteRows()}>Delete selected</button>
+      <FlexTableReact ref={tableRef} columns={columns} data={data} selectable />
+    </>
+  );
+}
+```
+
 #### Typed rows (generics)
 
 `FlexTableReact` and `ColumnDefinition` are generic over your row type — no `as unknown as` casts needed in `data`, `columns`, or callbacks:

package/dist/{flex-table-BQc2PU5u.js → flex-table-C_7PqhEb.js}

@@ -321,6 +321,24 @@ var s = t`
     border-radius: 4px;
   }
 
+  .ft-loading-overlay {
+    position: absolute;
+    inset: 0;
+    z-index: 90;
+    background: rgba(255, 255, 255, 0.5);
+    pointer-events: none;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :host(:not([theme="light"])) .ft-loading-overlay {
+      background: rgba(30, 30, 30, 0.5);
+    }
+  }
+
+  :host([theme="dark"]) .ft-loading-overlay {
+    background: rgba(30, 30, 30, 0.5);
+  }
+
   .ft-row-num-header,
   .ft-row-num {
     position: absolute;
@@ -1480,7 +1498,7 @@ var Y = {
 	lte: "≤"
 }, X = 120, Z = 40, xe = 32, Q = 5, $ = class extends e {
 	constructor(...e) {
-		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this.rowHeight = xe, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._activeCell = null, this._editingCell = null, this._sortCriteria = [], this._selection = new y(), this._editing = new b(), this._rowSelection = new x(), this._undo = new D(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._autocompleteState = null, this._headerMenu = null, this._bodyContextMenu = null, this._commentPopup = null, this._viewDirty = !0, this._isDragging = !1, this._wasDrag = !1, this._resizing = null, this._resizeCleanup = null, this._colDrag = null, this._colDragIndicatorLeft = null, this._fillDrag = null, this._rowDrag = null, this._rowDragIndicatorY = null, this._findState = null, this._columnWidths = /* @__PURE__ */ new Map(), this._hostResizeObserver = null, this._comments = /* @__PURE__ */ new Map(), this._isDragOver = !1, this._onCommentPopupOutsideClick = () => {
+		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this.rowHeight = xe, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.loading = !1, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._activeCell = null, this._editingCell = null, this._sortCriteria = [], this._selection = new y(), this._editing = new b(), this._rowSelection = new x(), this._undo = new D(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._autocompleteState = null, this._headerMenu = null, this._bodyContextMenu = null, this._commentPopup = null, this._viewDirty = !0, this._isDragging = !1, this._wasDrag = !1, this._resizing = null, this._resizeCleanup = null, this._colDrag = null, this._colDragIndicatorLeft = null, this._fillDrag = null, this._rowDrag = null, this._rowDragIndicatorY = null, this._findState = null, this._columnWidths = /* @__PURE__ */ new Map(), this._hostResizeObserver = null, this._comments = /* @__PURE__ */ new Map(), this._isDragOver = !1, this._onCommentPopupOutsideClick = () => {
 			this._commitCommentPopup();
 		}, this._invalidCells = /* @__PURE__ */ new Map(), this._textFilterState = /* @__PURE__ */ new Map(), this._numberFilterState = /* @__PURE__ */ new Map(), this._dateFilterState = /* @__PURE__ */ new Map(), this._emptyFilterState = /* @__PURE__ */ new Map();
 	}
@@ -2055,7 +2073,7 @@ var Y = {
 	updated(e) {
 		this._focusEditor(), this._adjustFilterDropdown();
 		let t = String(this._visibleRowCount), n = String(this.visibleColumns.length);
-		if (this.getAttribute("aria-rowcount") !== t && this.setAttribute("aria-rowcount", t), this.getAttribute("aria-colcount") !== n && this.setAttribute("aria-colcount", n), e.has("_commentPopup") && this._commentPopup) {
+		if (this.getAttribute("aria-rowcount") !== t && this.setAttribute("aria-rowcount", t), this.getAttribute("aria-colcount") !== n && this.setAttribute("aria-colcount", n), this.loading ? this.getAttribute("aria-busy") !== "true" && this.setAttribute("aria-busy", "true") : this.hasAttribute("aria-busy") && this.removeAttribute("aria-busy"), e.has("_commentPopup") && this._commentPopup) {
 			let e = this.shadowRoot?.querySelector(".ft-comment-popup textarea");
 			e && (e.value = this.getComment(this._commentPopup.dataIndex, this._commentPopup.colKey) ?? "", e.focus(), e.select());
 		}
@@ -3676,12 +3694,12 @@ var Y = {
     `;
 	}
 	render() {
-		let e = this.visibleColumns, t = this.importEnabled && this._isDragOver ? n`<div class="ft-import-overlay">Drop file to import (.xlsx / .csv)</div>` : r;
-		if (e.length === 0) return n`${t}<div class="ft-empty">No columns defined</div>`;
-		let i = this.headerHeight, a = this._totalRowWidth, { start: o, end: s } = this.visibleColRange, c = [];
-		for (let t = 0; t < e.length; t++) (e[t].pinned === "left" || e[t].pinned === "right") && (t < o || t >= s) && c.push(t);
-		let l = 0, u = this._scrollLeft, d = this.selectable ? n`<div class="ft-checkbox-header"
-            style="position: absolute; top: 0; left: ${u + l}px; width: 36px; height: ${i}px; z-index: 4;">
+		let e = this.visibleColumns, t = this.importEnabled && this._isDragOver ? n`<div class="ft-import-overlay">Drop file to import (.xlsx / .csv)</div>` : r, i = this.loading ? n`<div class="ft-loading-overlay"></div>` : r;
+		if (e.length === 0) return n`${t}${i}<div class="ft-empty">No columns defined</div>`;
+		let a = this.headerHeight, o = this._totalRowWidth, { start: s, end: c } = this.visibleColRange, l = [];
+		for (let t = 0; t < e.length; t++) (e[t].pinned === "left" || e[t].pinned === "right") && (t < s || t >= c) && l.push(t);
+		let u = 0, d = this._scrollLeft, f = this.selectable ? n`<div class="ft-checkbox-header"
+            style="position: absolute; top: 0; left: ${d + u}px; width: 36px; height: ${a}px; z-index: 4;">
           ${this._rowSelection.mode === "multi" ? n`
             <input type="checkbox"
               .checked=${this._rowSelection.isAllSelected}
@@ -3689,38 +3707,40 @@ var Y = {
               @change=${this._onSelectAllChange}>
           ` : ""}
         </div>` : "";
-		this.selectable && (l += 36);
-		let f = this.showRowNumbers ? n`<div class="ft-row-num-header"
-            style="position: absolute; top: 0; left: ${u + l}px; width: 48px; height: ${i}px; z-index: 4;">#</div>` : "", p = [];
-		for (let t of c) p.push(this._renderHeaderCell(e[t], t));
-		for (let t = o; t < s; t++) p.push(this._renderHeaderCell(e[t], t));
-		let m = this._colDragIndicatorLeft == null ? "" : n`<div class="ft-drop-indicator" style="left:${this._colDragIndicatorLeft}px"></div>`;
+		this.selectable && (u += 36);
+		let p = this.showRowNumbers ? n`<div class="ft-row-num-header"
+            style="position: absolute; top: 0; left: ${d + u}px; width: 48px; height: ${a}px; z-index: 4;">#</div>` : "", m = [];
+		for (let t of l) m.push(this._renderHeaderCell(e[t], t));
+		for (let t = s; t < c; t++) m.push(this._renderHeaderCell(e[t], t));
+		let h = this._colDragIndicatorLeft == null ? "" : n`<div class="ft-drop-indicator" style="left:${this._colDragIndicatorLeft}px"></div>`;
 		if (this.data.length === 0 || this._visibleRowCount === 0) return n`
-        <div class="ft-header" role="row" style="width: ${a}px; height: ${i}px;">
-          ${d}${f}
-          ${p}
+        ${i}
+        <div class="ft-header" role="row" style="width: ${o}px; height: ${a}px;">
+          ${f}${p}
           ${m}
+          ${h}
         </div>
         <div class="ft-empty">${this.data.length === 0 ? "No data" : "No matching data"}</div>
       `;
-		let { start: h, end: g } = this.visibleRange, _ = this._frozenRowCount, v = [];
-		for (let e = h; e < g; e++) v.push(this._renderRow(e, o, s, c, (e - _) * this.rowHeight));
-		let y = this._renderFillHandle(), b = this._rowDragIndicatorY == null ? "" : n`<div class="ft-row-drop-indicator" style="top:${this._rowDragIndicatorY}px;width:${a + this._prefixWidth}px;"></div>`;
+		let { start: g, end: _ } = this.visibleRange, v = this._frozenRowCount, y = [];
+		for (let e = g; e < _; e++) y.push(this._renderRow(e, s, c, l, (e - v) * this.rowHeight));
+		let b = this._renderFillHandle(), x = this._rowDragIndicatorY == null ? "" : n`<div class="ft-row-drop-indicator" style="top:${this._rowDragIndicatorY}px;width:${o + this._prefixWidth}px;"></div>`;
 		return n`
       ${t}
+      ${i}
       ${this._renderFindPanel()}
-      <div class="ft-header" role="row" style="width: ${a}px; height: ${i}px;">
-        ${d}${f}
-        ${p}
+      <div class="ft-header" role="row" style="width: ${o}px; height: ${a}px;">
+        ${f}${p}
         ${m}
+        ${h}
       </div>
-      ${this._renderFrozenRows(o, s, c)}
-      <div class="ft-body" style="height: ${this.totalBodyHeight}px; width: ${a}px;">
-        ${v}
+      ${this._renderFrozenRows(s, c, l)}
+      <div class="ft-body" style="height: ${this.totalBodyHeight}px; width: ${o}px;">
+        ${y}
       </div>
-      ${this.footerData ? this._renderFooter(o, s, c) : ""}
+      ${this.footerData ? this._renderFooter(s, c, l) : ""}
+      ${x}
       ${b}
-      ${y}
       ${this._renderHeaderContextMenu()}
       ${this._renderBodyContextMenu()}
       ${this._renderCommentPopup()}
@@ -3946,6 +3966,9 @@ J([a({ type: Array })], $.prototype, "columns", void 0), J([a({
 	type: Number,
 	attribute: "frozen-rows"
 })], $.prototype, "frozenRows", void 0), J([a({
+	type: Boolean,
+	reflect: !0
+})], $.prototype, "loading", void 0), J([a({
 	type: Boolean,
 	attribute: "import-enabled"
 })], $.prototype, "importEnabled", void 0), J([a({ type: Boolean })], $.prototype, "selectable", void 0), J([a({

package/dist/flex-table.d.ts

@@ -45,6 +45,12 @@ export declare class FlexTable extends LitElement {
     showContextMenu: boolean;
     /** Number of rows to freeze at the top (always visible during vertical scroll). */
     frozenRows: number;
+    /**
+     * True일 때 그리드 위에 로딩 오버레이를 표시하고 host에 `aria-busy="true"`를 반영한다.
+     * `useODataSource()`가 반환하는 `loading`과 자연 연동하도록 설계됨:
+     * `<FlexTableReact loading={source.loading} .../>`.
+     */
+    loading: boolean;
     /** Enable file drag-and-drop import (.xlsx, .csv). */
     importEnabled: boolean;
     /** Enable row-level checkbox selection. */

package/dist/flex-table.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, r, t as i } from "./flex-table-BQc2PU5u.js";
+import { a as e, i as t, n, r, t as i } from "./flex-table-C_7PqhEb.js";
 export { i as FlexTable, t as RowSelectionState, r as UndoStack, n as exportData, e as renderCell };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { t as e } from "./flex-table-BQc2PU5u.js";
+import { t as e } from "./flex-table-C_7PqhEb.js";
 import t from "react";
 import { createComponent as n } from "@lit/react";
 var r = n({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",