@iyulab/flex-table 0.48.6 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.49.0] - 2026-10-06
+
+### Added
+
+- **Typed events.** `FlexTableEventMap` (exported, with `CellChange`) maps each of the 31 event names to
+  its `CustomEvent<detail>`, and `FlexTable` overloads `addEventListener`/`removeEventListener` with it:
+  `table.addEventListener('sort-change', (e) => e.detail.criteria)` type-checks without a cast. Before,
+  a TypeScript listener got a plain `Event`. The names stay off the global event map on purpose — several
+  are generic (`sort-change`, `selection-change`) and would collide with other libraries.
+- The element dispatches every event through one helper keyed on the map, so a detail that drifts from
+  the documented shape no longer compiles.
+
+### Changed
+
+- **React `on*` props carry the detail types** (they were `CustomEvent<any>`). A handler that declared a
+  detail shape the event never had now fails to type-check — that is the point; handlers typed as plain
+  `CustomEvent` keep working.
+
+### Documentation
+
+- The README's event tables list the seven events they were missing (`row-reorder`, `data-import`,
+  `fill-handle-apply`, `find-replace`, `comment-change`, `column-visibility-change`,
+  `header-context-menu`).
+
+### Fixed
+
+- The package no longer ships empty `.d.ts` files for its own tests.
+
 ## [0.48.6] - 2026-10-06
 
 ### Fixed

package/README.md

@@ -282,7 +282,10 @@ Default is `false`, matching `clear-undo-on-data-change`.
 
 ## Events
 
-All events use `CustomEvent` with `bubbles: true, composed: true`.
+All events use `CustomEvent` with `bubbles: true, composed: true`. They are typed: `FlexTableEventMap` maps
+each name to its `CustomEvent<detail>`, and `addEventListener` on a `FlexTable` (for example from
+`document.querySelector('flex-table')`) uses it — `table.addEventListener('sort-change', (e) => e.detail.criteria)`
+type-checks without a cast. The React wrapper's `on*` props carry the same types.
 
 ### Cell Events
 
@@ -302,6 +305,11 @@ All events use `CustomEvent` with `bubbles: true, composed: true`.
 | `row-delete` | `{ indices, rows }` | Rows deleted |
 | `row-activate` | `{ row, index, col, key }` | Enter pressed on a non-editable cell — the grid's own contract for "activate this row" (e.g. navigate to a detail view), guaranteed even though the internal Enter handler prevents 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 |
+| `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, colKey, text }` | Cell comment set, changed or removed (`text: null`) |
 
 ### Column Events
 
@@ -312,6 +320,8 @@ All events use `CustomEvent` with `bubbles: true, composed: true`.
 | `column-reorder` | `{ key, oldIndex, newIndex }` | Column moved |
 | `column-resize` | `{ key, width, colIndex }` | Column resized (drag, auto-fit, or keyboard) |
 | `column-select` | `{ colIndex, key, rowCount }` | Entire column selected |
+| `column-visibility-change` | `{ key, hidden }` | Column hidden or shown |
+| `header-context-menu` | `{ key, label, x, y }` | Right-click on a column header |
 
 ### Sort & Filter Events
 

package/dist/events.d.ts

@@ -0,0 +1,199 @@
+import type { CellPosition, CellRange } from './core/selection.js';
+import type { SortCriteria } from './core/sorting.js';
+import type { ColumnDefinition, DataRow } from './models/types.js';
+/** One cell a bulk operation wrote: data row index, column key, value before and after. */
+export interface CellChange {
+    row: number;
+    key: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+/**
+ * Every event `<flex-table>` dispatches, by name. All bubble and are composed.
+ *
+ * This map is the single source: the element dispatches through a typed helper keyed on it, so a
+ * detail that drifts from what is written here fails to compile. Listeners get the same types —
+ * `table.addEventListener('sort-change', (e) => e.detail.criteria)` — and so does the React
+ * wrapper's `onSortChange`. The names are element-scoped (not on the global event map) because
+ * several are generic (`sort-change`, `selection-change`) and other libraries use them too.
+ */
+export interface FlexTableEventMap {
+    /** Row selection changed (`selectable`). Indices are data indices. */
+    'selection-change': CustomEvent<{
+        selectedIndices: number[];
+        selectedRows: DataRow[];
+    }>;
+    /** After any undoable change, undo or redo. */
+    'undo-state-change': CustomEvent<{
+        canUndo: boolean;
+        canRedo: boolean;
+    }>;
+    /** The set of column filters changed. `filteredCount` is the rows left visible. */
+    'filter-change': CustomEvent<{
+        keys: string[];
+        filteredCount: number;
+    }>;
+    /** A column filter predicate threw for a row; the row is kept. */
+    'filter-error': CustomEvent<{
+        error: unknown;
+        row: DataRow;
+        filterKey: string;
+    }>;
+    'column-add': CustomEvent<{
+        column: ColumnDefinition;
+        index: number;
+    }>;
+    'column-delete': CustomEvent<{
+        column: ColumnDefinition;
+        key: string;
+        index: number;
+    }>;
+    'column-reorder': CustomEvent<{
+        key: string;
+        oldIndex: number;
+        newIndex: number;
+    }>;
+    'column-visibility-change': CustomEvent<{
+        key: string;
+        hidden: boolean;
+    }>;
+    /** A column was resized — during the drag and once more when it ends. `colIndex` is the visible index. */
+    'column-resize': CustomEvent<{
+        key: string;
+        width: number;
+        colIndex: number;
+    }>;
+    /** A whole column was selected. `colIndex` is the visible index. */
+    'column-select': CustomEvent<{
+        colIndex: number;
+        key: string | undefined;
+        rowCount: number;
+    }>;
+    'row-add': CustomEvent<{
+        row: DataRow;
+        index: number;
+    }>;
+    'row-delete': CustomEvent<{
+        indices: number[];
+        rows: DataRow[];
+    }>;
+    /** A row was dragged to a new place. Both are data indices. */
+    'row-reorder': CustomEvent<{
+        from: number;
+        to: number;
+    }>;
+    /** Enter on a non-editable cell — "activate this row". `index` is the data index, `col` the visible column index. */
+    'row-activate': CustomEvent<{
+        row: DataRow;
+        index: number;
+        col: number;
+        key: string | undefined;
+    }>;
+    /** `batchUpdate()` applied its changes. */
+    'batch-update': CustomEvent<{
+        changes: CellChange[];
+    }>;
+    /** The active cell moved; `null` when there is none. */
+    'cell-select': CustomEvent<CellPosition | null>;
+    /** `row` is the data index, `col` the visible column index. */
+    'cell-edit-start': CustomEvent<{
+        row: number;
+        col: number;
+        key: string;
+        value: unknown;
+    }>;
+    'cell-edit-commit': CustomEvent<{
+        row: number;
+        col: number;
+        key: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }>;
+    /** `row` and `col` are visible positions. */
+    'cell-edit-cancel': CustomEvent<{
+        row: number;
+        col: number;
+    }>;
+    /** An edit was rejected (type, `required` or `validator`); the value was not written. */
+    'validation-error': CustomEvent<{
+        row: number;
+        col: number;
+        key: string;
+        value: unknown;
+        error: string;
+    }>;
+    'comment-change': CustomEvent<{
+        dataIndex: number;
+        colKey: string;
+        text: string | null;
+    }>;
+    /** Rows were imported from a file; `count` is how many. */
+    'data-import': CustomEvent<{
+        count: number;
+    }>;
+    'sort-change': CustomEvent<{
+        criteria: SortCriteria[];
+    }>;
+    /**
+     * Right-click on a body cell. Cancelable: `preventDefault()` keeps the built-in menu closed so you
+     * can show your own. `row` is the data index, `col` the visible column index.
+     */
+    'context-menu': CustomEvent<{
+        x: number;
+        y: number;
+        row: number;
+        col: number;
+        key: string;
+        value: unknown;
+        rowData: DataRow | undefined;
+    }>;
+    'header-context-menu': CustomEvent<{
+        key: string;
+        label: string;
+        x: number;
+        y: number;
+    }>;
+    /** Text reached the clipboard (`range` is in visible positions). */
+    'clipboard-copy': CustomEvent<{
+        range: CellRange;
+        text: string;
+    }>;
+    /** Like `clipboard-copy`, and the range was cleared afterwards. */
+    'clipboard-cut': CustomEvent<{
+        range: CellRange;
+        text: string;
+    }>;
+    /** A paste was applied. `addedRows` counts rows appended to fit it. */
+    'clipboard-paste': CustomEvent<{
+        changes: Array<CellChange & {
+            col: number;
+        }>;
+        addedRows: number;
+    }>;
+    /** The clipboard refused a copy or paste (permission, focus, no secure context). */
+    'clipboard-error': CustomEvent<{
+        action: 'copy' | 'paste';
+        error: unknown;
+    }>;
+    /** The fill handle wrote `cells` (data row index and key). */
+    'fill-handle-apply': CustomEvent<{
+        sourceRange: CellRange;
+        targetRange: CellRange;
+        cells: Array<{
+            dataRow: number;
+            key: string;
+            oldValue: unknown;
+            newValue: unknown;
+        }>;
+    }>;
+    /** Replace or replace-all from the find panel. `row` is the data index, `col` the column key. */
+    'find-replace': CustomEvent<{
+        type: 'replace' | 'replace-all';
+        cells: Array<{
+            row: number;
+            col: string;
+            oldValue: unknown;
+            newValue: unknown;
+        }>;
+    }>;
+}

package/dist/{flex-table-CoqeYojZ.js → flex-table-BsxF9Q3O.js}

@@ -1973,14 +1973,10 @@ var K = {
 	}
 	_dispatchRowSelectionEvent() {
 		let { selectedIndices: e, selectedRows: t } = this.getSelectedRows();
-		this.dispatchEvent(new CustomEvent("selection-change", {
-			detail: {
-				selectedIndices: e,
-				selectedRows: t
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._emit("selection-change", {
+			selectedIndices: e,
+			selectedRows: t
+		});
 	}
 	setFilter(e, t) {
 		this._filters = this._filters.filter((t) => t.key !== e), this._filters.push({
@@ -2010,25 +2006,26 @@ var K = {
 	clearUndoHistory() {
 		this._undo.clear(), this._dispatchUndoStateEvent();
 	}
-	_dispatchUndoStateEvent() {
-		this.dispatchEvent(new CustomEvent("undo-state-change", {
-			detail: {
-				canUndo: this.canUndo,
-				canRedo: this.canRedo
-			},
+	_emit(e, t, n) {
+		let r = new CustomEvent(e, {
+			detail: t,
 			bubbles: !0,
-			composed: !0
-		}));
+			composed: !0,
+			...n
+		});
+		return this.dispatchEvent(r), r;
+	}
+	_dispatchUndoStateEvent() {
+		this._emit("undo-state-change", {
+			canUndo: this.canUndo,
+			canRedo: this.canRedo
+		});
 	}
 	_dispatchFilterEvent() {
-		this.dispatchEvent(new CustomEvent("filter-change", {
-			detail: {
-				keys: this.filterKeys,
-				filteredCount: this.filteredRowCount
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._emit("filter-change", {
+			keys: this.filterKeys,
+			filteredCount: this.filteredRowCount
+		});
 	}
 	addColumn(e, t) {
 		let n = t ?? this.columns.length;
@@ -2048,14 +2045,10 @@ var K = {
 					...this.columns.slice(n)
 				], this.requestUpdate();
 			}
-		}), this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-add", {
-			detail: {
-				column: e,
-				index: n
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent(), e;
+		}), this.requestUpdate(), this._emit("column-add", {
+			column: e,
+			index: n
+		}), this._dispatchUndoStateEvent(), e;
 	}
 	deleteColumn(e) {
 		let t = this.columns.findIndex((t) => t.key === e);
@@ -2073,15 +2066,11 @@ var K = {
 			redo: () => {
 				this._filters = this._filters.filter((t) => t.key !== e), this._sortCriteria = this._sortCriteria.filter((t) => t.key !== e), this._columnWidths.delete(e), this.columns = this.columns.filter((t) => t.key !== e), this.requestUpdate();
 			}
-		}), this._activeCell && this._activeCell.col >= this.visibleColumns.length && (this._selection.clear(), this._activeCell = null), this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-delete", {
-			detail: {
-				column: n,
-				key: e,
-				index: t
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent();
+		}), this._activeCell && this._activeCell.col >= this.visibleColumns.length && (this._selection.clear(), this._activeCell = null), this.requestUpdate(), this._emit("column-delete", {
+			column: n,
+			key: e,
+			index: t
+		}), this._dispatchUndoStateEvent();
 	}
 	moveColumn(e, t) {
 		let n = this.columns.findIndex((t) => t.key === e);
@@ -2099,15 +2088,11 @@ var K = {
 				let e = [...this.columns];
 				e.splice(n, 1), e.splice(r, 0, i), this.columns = e, this.requestUpdate();
 			}
-		}), this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-reorder", {
-			detail: {
-				key: e,
-				oldIndex: n,
-				newIndex: r
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent();
+		}), this.requestUpdate(), this._emit("column-reorder", {
+			key: e,
+			oldIndex: n,
+			newIndex: r
+		}), this._dispatchUndoStateEvent();
 	}
 	hideColumn(e) {
 		let t = this.columns.findIndex((t) => t.key === e);
@@ -2142,14 +2127,10 @@ var K = {
 		n !== -1 && (this.columns = this.columns.map((e, r) => r === n ? {
 			...e,
 			hidden: t
-		} : e), this.dispatchEvent(new CustomEvent("column-visibility-change", {
-			detail: {
-				key: e,
-				hidden: t
-			},
-			bubbles: !0,
-			composed: !0
-		})));
+		} : e), this._emit("column-visibility-change", {
+			key: e,
+			hidden: t
+		}));
 	}
 	getHiddenColumns() {
 		return this.columns.filter((e) => e.hidden);
@@ -2165,14 +2146,10 @@ var K = {
 			redo: () => {
 				this.data.splice(r, 0, n), this.requestUpdate();
 			}
-		}), this.requestUpdate(), this.dispatchEvent(new CustomEvent("row-add", {
-			detail: {
-				row: n,
-				index: r
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent(), n;
+		}), this.requestUpdate(), this._emit("row-add", {
+			row: n,
+			index: r
+		}), this._dispatchUndoStateEvent(), n;
 	}
 	deleteRows(e) {
 		let t = e ?? this._getSelectedDataRows();
@@ -2198,14 +2175,10 @@ var K = {
 				let e = this._toDataIndex(this._activeCell.row);
 				t.includes(e) && (this._selection.clear(), this._activeCell = null);
 			}
-			this.requestUpdate(), this.dispatchEvent(new CustomEvent("row-delete", {
-				detail: {
-					indices: r.map((e) => e.index),
-					rows: r.map((e) => e.row)
-				},
-				bubbles: !0,
-				composed: !0
-			})), this._dispatchUndoStateEvent();
+			this.requestUpdate(), this._emit("row-delete", {
+				indices: r.map((e) => e.index),
+				rows: r.map((e) => e.row)
+			}), this._dispatchUndoStateEvent();
 		}
 	}
 	updateRows(e) {
@@ -2231,11 +2204,7 @@ var K = {
 				for (let e of t) this.data[e.row][e.key] = e.newValue;
 				this.requestUpdate();
 			}
-		}), this.requestUpdate(), this.dispatchEvent(new CustomEvent("batch-update", {
-			detail: { changes: t },
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent());
+		}), this.requestUpdate(), this._emit("batch-update", { changes: t }), this._dispatchUndoStateEvent());
 	}
 	_createEmptyRow() {
 		let e = {};
@@ -2298,15 +2267,11 @@ var K = {
 			let n = this._comments.get(e);
 			n && (n.delete(t), n.size === 0 && this._comments.delete(e));
 		}
-		this.dispatchEvent(new CustomEvent("comment-change", {
-			detail: {
-				dataIndex: e,
-				colKey: t,
-				text: n ?? null
-			},
-			bubbles: !0,
-			composed: !0
-		})), this.requestUpdate();
+		this._emit("comment-change", {
+			dataIndex: e,
+			colKey: t,
+			text: n ?? null
+		}), this.requestUpdate();
 	}
 	getComment(e, t) {
 		return this._comments.get(e)?.get(t) ?? null;
@@ -2360,11 +2325,7 @@ var K = {
 			redo: () => {
 				this.data = n, this.requestUpdate();
 			}
-		}), this.dispatchEvent(new CustomEvent("data-import", {
-			detail: { count: n.length },
-			bubbles: !0,
-			composed: !0
-		}));
+		}), this._emit("data-import", { count: n.length });
 	}
 	_applyImportedRows(e) {
 		if (e.length === 0) return;
@@ -2385,11 +2346,7 @@ var K = {
 			redo: () => {
 				this.data = r, this.requestUpdate();
 			}
-		}), this.dispatchEvent(new CustomEvent("data-import", {
-			detail: { count: r.length },
-			bubbles: !0,
-			composed: !0
-		}));
+		}), this._emit("data-import", { count: r.length });
 	}
 	_buildHeaderColumnMap(e) {
 		let t = /* @__PURE__ */ new Map();
@@ -2528,15 +2485,11 @@ var K = {
 			return;
 		}
 		if (this._filteredIndices = ce(this.data, this._filters, (e, t, n) => {
-			this.dispatchEvent(new CustomEvent("filter-error", {
-				detail: {
-					error: e,
-					row: t,
-					filterKey: n.key
-				},
-				bubbles: !0,
-				composed: !0
-			}));
+			this._emit("filter-error", {
+				error: e,
+				row: t,
+				filterKey: n.key
+			});
 		}), this._filters.length === 0 && this._sortCriteria.length === 0) this._sortedIndices = Array.from({ length: this.data.length }, (e, t) => t);
 		else if (this._sortCriteria.length === 0) this._sortedIndices = [...this._filteredIndices];
 		else {
@@ -2584,21 +2537,16 @@ var K = {
 		if (r < 0 || a < 0) return;
 		let o = this._toDataIndex(a), s = this.visibleColumns[r];
 		if (!s) return;
-		let c = new CustomEvent("context-menu", {
-			detail: {
-				x: e.clientX,
-				y: e.clientY,
-				row: o,
-				col: r,
-				key: s.key,
-				value: this.data[o]?.[s.key],
-				rowData: this.data[o]
-			},
-			bubbles: !0,
-			composed: !0,
-			cancelable: !0
-		});
-		this.dispatchEvent(c), this._cancelCommentPopup(), this.showContextMenu && !c.defaultPrevented && (this._bodyContextMenu = {
+		let c = this._emit("context-menu", {
+			x: e.clientX,
+			y: e.clientY,
+			row: o,
+			col: r,
+			key: s.key,
+			value: this.data[o]?.[s.key],
+			rowData: this.data[o]
+		}, { cancelable: !0 });
+		this._cancelCommentPopup(), this.showContextMenu && !c.defaultPrevented && (this._bodyContextMenu = {
 			rowIndex: a,
 			colIndex: r,
 			dataIndex: o,
@@ -2651,16 +2599,12 @@ var K = {
 	_fireRowActivate(e) {
 		if (!this._activeCell) return;
 		let t = this._toDataIndex(this._activeCell.row), n = this.data[t];
-		n && this.dispatchEvent(new CustomEvent("row-activate", {
-			detail: {
-				row: n,
-				index: t,
-				col: this._activeCell.col,
-				key: e?.key
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		n && this._emit("row-activate", {
+			row: n,
+			index: t,
+			col: this._activeCell.col,
+			key: e?.key
+		});
 	}
 	_startEdit() {
 		if (!this._activeCell) return;
@@ -2672,16 +2616,12 @@ var K = {
 			return;
 		}
 		let t = this._toDataIndex(this._activeCell.row), n = this.data[t];
-		this._editing.start(this._activeCell, n[e.key]), this._editingCell = { ...this._activeCell }, this.dispatchEvent(new CustomEvent("cell-edit-start", {
-			detail: {
-				row: t,
-				col: this._activeCell.col,
-				key: e.key,
-				value: n[e.key]
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._editing.start(this._activeCell, n[e.key]), this._editingCell = { ...this._activeCell }, this._emit("cell-edit-start", {
+			row: t,
+			col: this._activeCell.col,
+			key: e.key,
+			value: n[e.key]
+		});
 	}
 	_commitEdit() {
 		if (!this._editing.current) return;
@@ -2722,48 +2662,36 @@ var K = {
 		let { row: n, col: r } = t.position, i = this._toDataIndex(n), a = this.visibleColumns[r], o = t.originalValue;
 		if (a.autocomplete === "strict" && e != null && e !== "" && !this._getAutocompleteCandidates(a, "").includes(String(e))) {
 			let t = k("notInList");
-			this._markCellInvalid(n, r, t), this.dispatchEvent(new CustomEvent("validation-error", {
-				detail: {
-					row: i,
-					col: r,
-					key: a.key,
-					value: e,
-					error: t
-				},
-				bubbles: !0,
-				composed: !0
-			}));
+			this._markCellInvalid(n, r, t), this._emit("validation-error", {
+				row: i,
+				col: r,
+				key: a.key,
+				value: e,
+				error: t
+			});
 			return;
 		}
 		if (a.type === "number" && typeof e == "string" || a.type === "date" && typeof e == "string" && f(e) === null || a.type === "datetime" && typeof e == "string" && p(e) === null) {
 			let t = k(a.type === "number" ? "notANumber" : a.type === "date" ? "notADate" : "notADateTime");
-			this._markCellInvalid(n, r, t), this.dispatchEvent(new CustomEvent("validation-error", {
-				detail: {
-					row: i,
-					col: r,
-					key: a.key,
-					value: e,
-					error: t
-				},
-				bubbles: !0,
-				composed: !0
-			}));
+			this._markCellInvalid(n, r, t), this._emit("validation-error", {
+				row: i,
+				col: r,
+				key: a.key,
+				value: e,
+				error: t
+			});
 			return;
 		}
 		if (a.validator) {
 			let t = a.validator(e, this.data[i], a);
 			if (t) {
-				this._markCellInvalid(n, r, t), this.dispatchEvent(new CustomEvent("validation-error", {
-					detail: {
-						row: i,
-						col: r,
-						key: a.key,
-						value: e,
-						error: t
-					},
-					bubbles: !0,
-					composed: !0
-				}));
+				this._markCellInvalid(n, r, t), this._emit("validation-error", {
+					row: i,
+					col: r,
+					key: a.key,
+					value: e,
+					error: t
+				});
 				return;
 			}
 		}
@@ -2775,29 +2703,21 @@ var K = {
 			redo: () => {
 				this.data[i][a.key] = e, this.requestUpdate();
 			}
-		}), this.requestUpdate(), this.dispatchEvent(new CustomEvent("cell-edit-commit", {
-			detail: {
-				row: i,
-				col: r,
-				key: a.key,
-				oldValue: o,
-				newValue: e
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._dispatchUndoStateEvent();
+		}), this.requestUpdate(), this._emit("cell-edit-commit", {
+			row: i,
+			col: r,
+			key: a.key,
+			oldValue: o,
+			newValue: e
+		}), this._dispatchUndoStateEvent();
 	}
 	_cancelEdit() {
 		this._autocompleteState = null;
 		let e = this._editing.cancel();
-		this._editingCell = null, e && this.dispatchEvent(new CustomEvent("cell-edit-cancel", {
-			detail: {
-				row: e.position.row,
-				col: e.position.col
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._editingCell = null, e && this._emit("cell-edit-cancel", {
+			row: e.position.row,
+			col: e.position.col
+		});
 	}
 	_onEditorKeyDown(e) {
 		if (_(e)) return;
@@ -2942,15 +2862,11 @@ var K = {
 		let n = this.visibleColumns.findIndex((t) => t.key === e), r = this.visibleColumns[n];
 		if (!r) return;
 		let i = this._columnWidths.get(r.key) ?? r.width ?? q, a = r.minWidth ?? J, o = Math.max(a, i + t);
-		this._columnWidths.set(r.key, o), this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-resize", {
-			detail: {
-				key: r.key,
-				width: o,
-				colIndex: n
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._columnWidths.set(r.key, o), this.requestUpdate(), this._emit("column-resize", {
+			key: r.key,
+			width: o,
+			colIndex: n
+		});
 	}
 	_handleNavigation(e) {
 		switch (e.key) {
@@ -2987,24 +2903,16 @@ var K = {
 		}
 	}
 	_clipboardError(e, t) {
-		this.dispatchEvent(new CustomEvent("clipboard-error", {
-			detail: {
-				action: e,
-				error: t
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._emit("clipboard-error", {
+			action: e,
+			error: t
+		});
 	}
 	_afterCopy(e, t, n) {
-		n && this._clearRange(e), this.dispatchEvent(new CustomEvent(n ? "clipboard-cut" : "clipboard-copy", {
-			detail: {
-				range: e,
-				text: t
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		n && this._clearRange(e), this._emit(n ? "clipboard-cut" : "clipboard-copy", {
+			range: e,
+			text: t
+		});
 	}
 	_pasteText(e) {
 		if (!this._activeCell) return;
@@ -3026,14 +2934,10 @@ var K = {
 				}
 			}), this._dispatchUndoStateEvent();
 		}
-		this.requestUpdate(), this.dispatchEvent(new CustomEvent("clipboard-paste", {
-			detail: {
-				changes: r,
-				addedRows: n.length
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this.requestUpdate(), this._emit("clipboard-paste", {
+			changes: r,
+			addedRows: n.length
+		});
 	}
 	_selectPastedRange(e, t) {
 		let n = Math.max(...t.map((e) => e.length)), r = Math.min(e.row + t.length, this._visibleRowCount) - 1, i = Math.min(e.col + n, this.visibleColumns.length) - 1;
@@ -3203,11 +3107,7 @@ var K = {
 		i < this.scrollLeft ? this.scrollLeft = i : a > this.scrollLeft + this.clientWidth && (this.scrollLeft = a - this.clientWidth);
 	}
 	_dispatchSelectionEvent() {
-		this.dispatchEvent(new CustomEvent("cell-select", {
-			detail: this._activeCell ? { ...this._activeCell } : null,
-			bubbles: !0,
-			composed: !0
-		}));
+		this._emit("cell-select", this._activeCell ? { ...this._activeCell } : null);
 	}
 	_onHeaderClick(t, n) {
 		if (this._wasHeaderDrag) {
@@ -3219,26 +3119,18 @@ var K = {
 			this._selectColumn(r);
 			return;
 		}
-		n.sortable !== !1 && (this._sortCriteria = e(this._sortCriteria, n.key, t.shiftKey), this.dataMode !== "server" && this._recomputeView(), this.requestUpdate(), this.dispatchEvent(new CustomEvent("sort-change", {
-			detail: { criteria: [...this._sortCriteria] },
-			bubbles: !0,
-			composed: !0
-		})));
+		n.sortable !== !1 && (this._sortCriteria = e(this._sortCriteria, n.key, t.shiftKey), this.dataMode !== "server" && this._recomputeView(), this.requestUpdate(), this._emit("sort-change", { criteria: [...this._sortCriteria] }));
 	}
 	_selectColumn(e) {
 		let t = this._visibleRowCount;
 		t === 0 || e < 0 || (this._selection.setActive(0, e), this._selection.setActiveWithRange(t - 1, e), this._activeCell = {
 			row: 0,
 			col: e
-		}, this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-select", {
-			detail: {
-				colIndex: e,
-				key: this.visibleColumns[e]?.key,
-				rowCount: t
-			},
-			bubbles: !0,
-			composed: !0
-		})));
+		}, this.requestUpdate(), this._emit("column-select", {
+			colIndex: e,
+			key: this.visibleColumns[e]?.key,
+			rowCount: t
+		}));
 	}
 	selectColumn(e) {
 		this._selectColumn(e);
@@ -3325,16 +3217,12 @@ var K = {
 			x: e.clientX,
 			y: e.clientY,
 			hiddenNeighbors: this._hiddenNeighbors(t)
-		}, this.dispatchEvent(new CustomEvent("header-context-menu", {
-			detail: {
-				key: t.key,
-				label: t.label,
-				x: e.clientX,
-				y: e.clientY
-			},
-			bubbles: !0,
-			composed: !0
-		})), requestAnimationFrame(() => {
+		}, this._emit("header-context-menu", {
+			key: t.key,
+			label: t.label,
+			x: e.clientX,
+			y: e.clientY
+		}), requestAnimationFrame(() => {
 			document.addEventListener("click", this._onDocumentClick, { once: !0 });
 		});
 	}
@@ -3519,11 +3407,7 @@ var K = {
 		n && n.sortable !== !1 && (this._sortCriteria = [{
 			key: e,
 			direction: t
-		}], this.dataMode !== "server" && this._recomputeView(), this.requestUpdate(), this.dispatchEvent(new CustomEvent("sort-change", {
-			detail: { criteria: [...this._sortCriteria] },
-			bubbles: !0,
-			composed: !0
-		})));
+		}], this.dataMode !== "server" && this._recomputeView(), this.requestUpdate(), this._emit("sort-change", { criteria: [...this._sortCriteria] }));
 	}
 	_keepMenuInView(e) {
 		let t = this.shadowRoot?.querySelector(e);
@@ -3837,15 +3721,11 @@ var K = {
 		let r = this.shadowRoot?.querySelectorAll(`.ft-cell[data-col-index="${t}"]`), i = 0, a = this.shadowRoot?.querySelector(`.ft-header-cell[data-col-index="${t}"]`);
 		if (a && (i = Math.max(i, a.scrollWidth)), r) for (let e of r) i = Math.max(i, e.scrollWidth);
 		let o = n.minWidth ?? J, s = Math.max(o, i + 8);
-		this._columnWidths.set(n.key, s), this.requestUpdate(), this.dispatchEvent(new CustomEvent("column-resize", {
-			detail: {
-				key: n.key,
-				width: s,
-				colIndex: t
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		this._columnWidths.set(n.key, s), this.requestUpdate(), this._emit("column-resize", {
+			key: n.key,
+			width: s,
+			colIndex: t
+		});
 	}
 	_onResizeStart(e, t) {
 		e.preventDefault(), e.stopPropagation();
@@ -3864,15 +3744,11 @@ var K = {
 		}, o = () => {
 			if (a(), this._resizing) {
 				let e = this._columnWidths.get(n.key) ?? q;
-				this.dispatchEvent(new CustomEvent("column-resize", {
-					detail: {
-						key: n.key,
-						width: e,
-						colIndex: t
-					},
-					bubbles: !0,
-					composed: !0
-				})), this._resizing = null;
+				this._emit("column-resize", {
+					key: n.key,
+					width: e,
+					colIndex: t
+				}), this._resizing = null;
 			}
 		};
 		document.addEventListener("mousemove", i), document.addEventListener("mouseup", o), this._resizeCleanup = a;
@@ -4001,15 +3877,11 @@ var K = {
 				for (let e of r) this.data[e.dataRow][e.key] = e.newValue;
 				this.requestUpdate();
 			}
-		}), this._dispatchUndoStateEvent(), this.dispatchEvent(new CustomEvent("fill-handle-apply", {
-			detail: {
-				sourceRange: e,
-				targetRange: t,
-				cells: r
-			},
-			bubbles: !0,
-			composed: !0
-		}))), this.requestUpdate();
+		}), this._dispatchUndoStateEvent(), this._emit("fill-handle-apply", {
+			sourceRange: e,
+			targetRange: t,
+			cells: r
+		})), this.requestUpdate();
 	}
 	_detectNumericSeries(e) {
 		if (e.length < 2) return null;
@@ -4101,14 +3973,10 @@ var K = {
 			redo: () => {
 				this.data = [...a], this.requestUpdate();
 			}
-		}), this._dispatchUndoStateEvent(), this.dispatchEvent(new CustomEvent("row-reorder", {
-			detail: {
-				from: n,
-				to: r
-			},
-			bubbles: !0,
-			composed: !0
-		}));
+		}), this._dispatchUndoStateEvent(), this._emit("row-reorder", {
+			from: n,
+			to: r
+		});
 	}
 	_toggleFindPanel(e) {
 		if (this._findState?.mode === e) {
@@ -4191,19 +4059,15 @@ var K = {
 				for (let e of r) this.data[e.dataRow][e.key] = e.newValue;
 				this.requestUpdate();
 			}
-		}), this._dispatchUndoStateEvent(), this.dispatchEvent(new CustomEvent("find-replace", {
-			detail: {
-				type: "replace-all",
-				cells: r.map((e) => ({
-					row: e.dataRow,
-					col: e.key,
-					oldValue: e.oldValue,
-					newValue: e.newValue
-				}))
-			},
-			bubbles: !0,
-			composed: !0
-		}))), this._findState.results = [], this._findState.currentIndex = 0, this.requestUpdate();
+		}), this._dispatchUndoStateEvent(), this._emit("find-replace", {
+			type: "replace-all",
+			cells: r.map((e) => ({
+				row: e.dataRow,
+				col: e.key,
+				oldValue: e.oldValue,
+				newValue: e.newValue
+			}))
+		})), this._findState.results = [], this._findState.currentIndex = 0, this.requestUpdate();
 	}
 	_replaceOne() {
 		if (!this._findState || this._findState.results.length === 0) return;
@@ -4216,19 +4080,15 @@ var K = {
 			redo: () => {
 				this.data[a][o] = n, this.requestUpdate();
 			}
-		}), this._dispatchUndoStateEvent(), this.dispatchEvent(new CustomEvent("find-replace", {
-			detail: {
-				type: "replace",
-				cells: [{
-					row: a,
-					col: o,
-					oldValue: s,
-					newValue: n
-				}]
-			},
-			bubbles: !0,
-			composed: !0
-		})), this._findSearch(), this._findGoTo(Math.min(e, this._findState.results.length - 1));
+		}), this._dispatchUndoStateEvent(), this._emit("find-replace", {
+			type: "replace",
+			cells: [{
+				row: a,
+				col: o,
+				oldValue: s,
+				newValue: n
+			}]
+		}), this._findSearch(), this._findGoTo(Math.min(e, this._findState.results.length - 1));
 	}
 	_renderFindPanel() {
 		if (!this._findState) return "";

package/dist/flex-table.d.ts

@@ -5,6 +5,7 @@ import type { CellPosition, CellRange } from './core/selection.js';
 import type { SortCriteria } from './core/sorting.js';
 import type { FilterPredicate } from './core/filtering.js';
 import type { ColumnDefinition, DataRow, SelectionMode, DataMode } from './models/types.js';
+import type { FlexTableEventMap } from './events.js';
 import type { TemplateResult } from 'lit';
 export declare class FlexTable extends LitElement {
     static styles: import("lit").CSSResult;
@@ -210,6 +211,11 @@ export declare class FlexTable extends LitElement {
     redo(): void;
     /** Clear all undo/redo history. */
     clearUndoHistory(): void;
+    /**
+     * Dispatches one of {@link FlexTableEventMap}'s events — bubbling and composed. Every event goes
+     * through here, so a detail that drifts from the map fails to compile.
+     */
+    private _emit;
     private _dispatchUndoStateEvent;
     private _dispatchFilterEvent;
     /**
@@ -561,6 +567,19 @@ export declare class FlexTable extends LitElement {
     private _renderCell;
     private _renderEditor;
 }
+/**
+ * Typed listeners for {@link FlexTableEventMap} — the DOM's own pattern (`HTMLMediaElement` with
+ * `HTMLMediaElementEventMap`). Element-scoped on purpose: several names are generic and would
+ * collide on the global event map.
+ */
+export interface FlexTable {
+    addEventListener<K extends keyof FlexTableEventMap>(type: K, listener: (this: FlexTable, ev: FlexTableEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: FlexTable, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof FlexTableEventMap>(type: K, listener: (this: FlexTable, ev: FlexTableEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: FlexTable, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'flex-table': FlexTable;

package/dist/flex-table.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-CoqeYojZ.js";
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-BsxF9Q3O.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

@@ -2,6 +2,7 @@ export { FlexTable } from './flex-table.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 { FlexTableEventMap, CellChange } from './events.js';
 export type { SortCriteria, SortDirection } from './core/sorting.js';
 export type { ColumnFilter, FilterPredicate, FilterErrorCallback } from './core/filtering.js';
 export { RowSelectionState } from './core/row-selection.js';

package/dist/react.d.ts

@@ -2,38 +2,39 @@ import React from 'react';
 import { type EventName } from '@lit/react';
 import { FlexTable } from './flex-table.js';
 import type { ColumnDefinition, DataRow } from './models/types.js';
+import type { FlexTableEventMap } from './events.js';
 declare const FlexTableReactBase: import("@lit/react").ReactWebComponent<FlexTable, {
-    onCellSelect: EventName<CustomEvent>;
-    onCellEditCommit: EventName<CustomEvent>;
-    onCellEditCancel: EventName<CustomEvent>;
-    onCellEditStart: EventName<CustomEvent>;
-    onSortChange: EventName<CustomEvent>;
-    onFilterChange: EventName<CustomEvent>;
-    onRowAdd: EventName<CustomEvent>;
-    onRowDelete: EventName<CustomEvent>;
-    onRowActivate: EventName<CustomEvent>;
-    onColumnResize: EventName<CustomEvent>;
-    onColumnSelect: EventName<CustomEvent>;
-    onColumnAdd: EventName<CustomEvent>;
-    onColumnDelete: EventName<CustomEvent>;
-    onColumnReorder: EventName<CustomEvent>;
-    onSelectionChange: EventName<CustomEvent>;
-    onClipboardCopy: EventName<CustomEvent>;
-    onClipboardCut: EventName<CustomEvent>;
-    onClipboardPaste: EventName<CustomEvent>;
-    onClipboardError: EventName<CustomEvent>;
-    onUndoStateChange: EventName<CustomEvent>;
-    onValidationError: EventName<CustomEvent>;
-    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>;
+    onCellSelect: EventName<FlexTableEventMap["cell-select"]>;
+    onCellEditCommit: EventName<FlexTableEventMap["cell-edit-commit"]>;
+    onCellEditCancel: EventName<FlexTableEventMap["cell-edit-cancel"]>;
+    onCellEditStart: EventName<FlexTableEventMap["cell-edit-start"]>;
+    onSortChange: EventName<FlexTableEventMap["sort-change"]>;
+    onFilterChange: EventName<FlexTableEventMap["filter-change"]>;
+    onRowAdd: EventName<FlexTableEventMap["row-add"]>;
+    onRowDelete: EventName<FlexTableEventMap["row-delete"]>;
+    onRowActivate: EventName<FlexTableEventMap["row-activate"]>;
+    onColumnResize: EventName<FlexTableEventMap["column-resize"]>;
+    onColumnSelect: EventName<FlexTableEventMap["column-select"]>;
+    onColumnAdd: EventName<FlexTableEventMap["column-add"]>;
+    onColumnDelete: EventName<FlexTableEventMap["column-delete"]>;
+    onColumnReorder: EventName<FlexTableEventMap["column-reorder"]>;
+    onSelectionChange: EventName<FlexTableEventMap["selection-change"]>;
+    onClipboardCopy: EventName<FlexTableEventMap["clipboard-copy"]>;
+    onClipboardCut: EventName<FlexTableEventMap["clipboard-cut"]>;
+    onClipboardPaste: EventName<FlexTableEventMap["clipboard-paste"]>;
+    onClipboardError: EventName<FlexTableEventMap["clipboard-error"]>;
+    onUndoStateChange: EventName<FlexTableEventMap["undo-state-change"]>;
+    onValidationError: EventName<FlexTableEventMap["validation-error"]>;
+    onBatchUpdate: EventName<FlexTableEventMap["batch-update"]>;
+    onContextMenu: EventName<FlexTableEventMap["context-menu"]>;
+    onFilterError: EventName<FlexTableEventMap["filter-error"]>;
+    onRowReorder: EventName<FlexTableEventMap["row-reorder"]>;
+    onColumnVisibilityChange: EventName<FlexTableEventMap["column-visibility-change"]>;
+    onCommentChange: EventName<FlexTableEventMap["comment-change"]>;
+    onDataImport: EventName<FlexTableEventMap["data-import"]>;
+    onFillHandleApply: EventName<FlexTableEventMap["fill-handle-apply"]>;
+    onFindReplace: EventName<FlexTableEventMap["find-replace"]>;
+    onHeaderContextMenu: EventName<FlexTableEventMap["header-context-menu"]>;
 }>;
 type BaseProps = React.ComponentProps<typeof FlexTableReactBase>;
 /**

package/dist/react.js

@@ -1,4 +1,4 @@
-import { t as e } from "./flex-table-CoqeYojZ.js";
+import { t as e } from "./flex-table-BsxF9Q3O.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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.48.6",
+  "version": "0.49.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.test.d.ts",
     "skills",
     "package.json",
     "README.md",

package/skills/iyulab-flex-table/references/api.md

@@ -134,6 +134,8 @@ Enter/Escape and blur-to-commit behavior.
 ## Events
 
 All are `CustomEvent`s with `bubbles: true, composed: true`. `row`/`index` are data indices.
+Typed by `FlexTableEventMap` (exported): `table.addEventListener('sort-change', (e) => e.detail.criteria)` needs no
+cast, and the React `on*` props carry the same types.
 
 | Event | `detail` |
 |---|---|

package/dist/array/use-array-source.hooks.test.d.ts

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

package/dist/array/use-array-source.test.d.ts

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

package/dist/clipboard/clipboard.test.d.ts

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

package/dist/core/filtering.test.d.ts

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

package/dist/core/selection.test.d.ts

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

package/dist/core/sorting.test.d.ts

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

package/dist/core/undo.test.d.ts

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

package/dist/export/export.test.d.ts

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

package/dist/export/xlsx-deflate.test.d.ts

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

package/dist/export/xlsx-reader.test.d.ts

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

package/dist/flex-table.test.d.ts

@@ -1 +0,0 @@
-import './flex-table.js';

package/dist/odata/index.test.d.ts

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

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

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

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

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

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

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

package/dist/renderers/format.test.d.ts

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

package/dist/styles/density-tokens.test.d.ts

@@ -1 +0,0 @@
-import '../flex-table';

package/dist/styles/token-derivation.test.d.ts

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