@iyulab/flex-table 0.48.6 → 0.49.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.49.1] - 2026-10-06
+
+### Fixed
+
+- **The column filter is a dialog with a keyboard contract.** It is announced as a dialog named for its
+  column ("Filter Customer"); Tab and Shift+Tab stay inside it (it floats over the table, so focus that
+  left it would leave it open behind the next control); Escape closes it and returns focus to that
+  column's menu button — before, focus dropped to the page. A click outside still closes it without
+  moving focus.
+
+## [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
 
@@ -509,6 +519,7 @@ conformance claim for the success criteria it does not list.
 |---|---|---|
 | SC 2.5.8 Target Size (Minimum) | Sortable headers, column menu buttons, the open column menu, the open filter dropdown (text and number), the find/replace bar, the cell context menu and row selection checkboxes are at least 24×24 CSS px or meet the spacing exception (24px between centers, counting the neighbouring resize handles), and are actually hit at that position. Two small targets use the equivalent-control exception: the 6px column resize handle (every resize is also in the column menu) and the hidden-column marker (its column menu offers **Show: …**) | `tests/browser/target-size.browser.test.ts` (real Chromium) |
 | SC 2.1.1 Keyboard (pointer-cursor check) | Nothing the grid renders shows a pointer cursor without being an interactive element. Sorting by header click also has a keyboard path — the column menu's **Sort ascending** / **Sort descending** (the check alone cannot see that, because the header cell wraps the menu button) | `tests/browser/target-size.browser.test.ts` · `src/flex-table.test.ts` |
+| SC 2.4.3 Focus Order · SC 2.1.2 No Keyboard Trap | The column filter is a dialog named for its column: opening it from the column menu moves focus into it, Tab and Shift+Tab cycle inside it, and Escape closes it and returns focus to that column's menu button (Escape is the way out) | `tests/browser/column-menu.browser.test.ts` |
 | SC 2.5.7 Dragging Movements | Resizing never requires a drag — the column menu's **Auto-fit width**, **Wider** and **Narrower** are single clicks | `tests/browser/column-menu.browser.test.ts` |
 | SC 1.3.1 Info and Relationships (virtualized grid) | Only the visible rows and columns are in the DOM, so every row carries `aria-rowindex` and every cell `aria-colindex` (1-based, in display order), and the grid's `aria-rowcount` / `aria-colcount` give the full size — the header row is row 1, data rows start at 2, and the footer row (if any) is last. A screen reader announces "row 621 of 10001" after scrolling instead of counting the rows that happen to be rendered. The footer row's cells are grid cells | `tests/browser/aria-grid-index.browser.test.ts` |
 

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;
+        }>;
+    }>;
+}