@iyulab/flex-table 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.50.0] - 2026-10-06
+
+### Fixed
+
+- **Tab no longer traps the focus in the table.** Tab past the last cell (Shift+Tab before the first)
+  stayed on that cell, so keyboard focus could never leave the table (WCAG 2.1.2). Tab still walks the
+  cells; at either end it now moves on to the next (previous) control on the page.
+
+### Added
+
+- **The header row is reachable by keyboard.** ArrowUp from the first row moves onto the column's header
+  cell; ArrowLeft / ArrowRight / Home / End move along the header and ArrowDown returns to the body. On a
+  header cell, Enter or Space sorts (Shift adds the column to the sort), Alt+ArrowDown or the context-menu
+  key opens the column menu, and Alt+ArrowLeft / Alt+ArrowRight resize the column. Escape from that menu
+  returns to the same header cell. An empty table keeps the header row reachable.
+- Keyboard focus arriving on a table with nothing active activates the first cell, so the first arrow
+  key already moves and no Tab is spent entering.
+
+### Changed
+
+- **The column menu buttons are no longer Tab stops** (`tabindex="-1"`, like the row checkboxes) — the
+  table is one Tab stop and the header row reaches each column's menu. Pages that relied on tabbing to a
+  menu button reach it from the header row instead.
+
+## [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

package/README.md

@@ -437,8 +437,8 @@ package dependency; CSS custom properties are resolved at render time, not impor
 
 | Key | Action |
 |-----|--------|
-| Arrow keys | Navigate cells |
-| Tab / Shift+Tab | Move to next/previous cell |
+| Arrow keys | Navigate cells (ArrowUp from the first row moves onto the header row) |
+| Tab / Shift+Tab | Move to next/previous cell; past the last (before the first) cell, leave the table |
 | Enter / F2 | Start editing (Enter on a non-editable cell fires `row-activate`) |
 | Typing a printable character | Start editing an editable cell with that character |
 | Escape | Cancel edit / clear selection / close the find panel |
@@ -455,9 +455,15 @@ package dependency; CSS custom properties are resolved at render time, not impor
 | Ctrl+Shift+Z / Ctrl+Y | Redo |
 | Alt+ArrowLeft / Alt+ArrowRight | Resize current column (±20px) |
 | Ctrl+Click header | Select entire column |
+| ArrowLeft / ArrowRight / Home / End (header row) | Move along the header; ArrowDown returns to the first row |
+| Enter / Space (header row) | Sort the column (ascending → descending → none); with Shift, add it to the sort |
+| Alt+ArrowDown or the context-menu key (header row) | Open the column menu |
 | Enter / Space on a column menu button | Open the column menu |
 | ArrowUp / ArrowDown / Home / End (column menu) | Move between menu items |
-| Escape (column menu) | Close the menu and return focus to its button |
+| Escape (column menu) | Close the menu and return focus to where it was opened from |
+
+The table is one Tab stop: keyboard focus arriving on it activates the first cell (the first header cell
+when there are no rows), and the column menu buttons and row checkboxes are reached by keys, not Tab.
 
 ## Localization
 
@@ -519,6 +525,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/{flex-table-BsxF9Q3O.js → flex-table-B64ScsFY.js}

@@ -159,6 +159,11 @@ var x = r`
 
   .ft-header-cell.ft-sortable { cursor: pointer; }
   .ft-header-cell.ft-sortable:hover { background: var(--ft-header-hover-bg); }
+  /* The header cell the keyboard is on (ArrowUp from the first row) — same ring as the active body cell. */
+  .ft-header-cell.ft-header-active {
+    outline: 2px solid var(--ft-active-color);
+    outline-offset: -2px;
+  }
 
   .ft-header-cell.ft-header-align-center { justify-content: center; }
   .ft-header-cell.ft-header-align-end { justify-content: flex-end; }
@@ -1887,7 +1892,9 @@ var K = {
 	lte: "≤"
 }, q = 120, J = 40, Y = 20, X = 32, Z = 5, Ze = 200, Q = class extends n {
 	constructor(...e) {
-		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this._rowHeightFromCss = X, this._targetFloor = 0, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.emptyMessage = "No data", this.noMatchingMessage = "No matching data", this.loading = !1, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this.stylesheets = [], this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._baseStyleSheets = [], this._activeCell = null, this._editingCell = null, this._sortCriteria = [], this._selection = new oe(), this._editing = new se(), this._rowSelection = new A(), this._undo = new j(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._lastCheckboxRowIndex = null, this._checkboxShiftPending = !1, 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._wasHeaderDrag = !1, this._wasRowDrag = !1, 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._warnedUnconstrained = !1, this._onCommentPopupOutsideClick = () => {
+		super(...e), this.columns = [], this._data = [], this._inUndoRedo = !1, this.clearUndoOnDataChange = !1, this.clearSelectionOnDataChange = !1, this._rowHeightFromCss = X, this._targetFloor = 0, this.showRowNumbers = !1, this.theme = void 0, this.maxRows = 0, this.editable = !0, this.showFilters = !1, this.showContextMenu = !1, this.frozenRows = 0, this.emptyMessage = "No data", this.noMatchingMessage = "No matching data", this.loading = !1, this.importEnabled = !1, this.selectable = !1, this.dataMode = "client", this.footerData = null, this.stylesheets = [], this._scrollTop = 0, this._scrollLeft = 0, this._viewportHeight = 0, this._viewportWidth = 0, this._colLeftOffsets = [], this._totalRowWidth = 0, this._baseStyleSheets = [], this._activeCell = null, this._headerCol = null, this._editingCell = null, this._sortCriteria = [], this._selection = new oe(), this._editing = new se(), this._rowSelection = new A(), this._undo = new j(), this._filters = [], this._filteredIndices = [], this._sortedIndices = [], this._openFilterKey = null, this._rowSelectionVersion = 0, this._lastCheckboxRowIndex = null, this._checkboxShiftPending = !1, 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._wasHeaderDrag = !1, this._wasRowDrag = !1, 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._warnedUnconstrained = !1, this._onHostFocus = (e) => {
+			e.composedPath()[0] !== this || this._activeCell || this._headerCol !== null || this.visibleColumns.length !== 0 && this.matches(":focus-visible") && (this._visibleRowCount > 0 ? (this._selection.setActive(0, 0), this._syncActiveCell()) : this._headerCol = 0);
+		}, 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();
 	}
@@ -2418,10 +2425,10 @@ var K = {
 		};
 	}
 	connectedCallback() {
-		super.connectedCallback(), this._onScroll = this._onScroll.bind(this), this._onKeyDown = this._onKeyDown.bind(this), this._onDocumentClick = this._onDocumentClick.bind(this), this._onContextMenu = this._onContextMenu.bind(this), this._onDragover = this._onDragover.bind(this), this._onDragleave = this._onDragleave.bind(this), this._onDrop = this._onDrop.bind(this), this.addEventListener("scroll", this._onScroll, { passive: !0 }), this.addEventListener("keydown", this._onKeyDown), this.addEventListener("contextmenu", this._onContextMenu), this.addEventListener("dragover", this._onDragover), this.addEventListener("dragleave", this._onDragleave), this.addEventListener("drop", this._onDrop), this.hasAttribute("tabindex") || this.setAttribute("tabindex", "0"), this.setAttribute("role", "grid"), typeof ResizeObserver < "u" && (this._hostResizeObserver = new ResizeObserver(() => this._measureViewport()), this._hostResizeObserver.observe(this));
+		super.connectedCallback(), this._onScroll = this._onScroll.bind(this), this._onKeyDown = this._onKeyDown.bind(this), this._onDocumentClick = this._onDocumentClick.bind(this), this._onContextMenu = this._onContextMenu.bind(this), this._onDragover = this._onDragover.bind(this), this._onDragleave = this._onDragleave.bind(this), this._onDrop = this._onDrop.bind(this), this.addEventListener("scroll", this._onScroll, { passive: !0 }), this.addEventListener("keydown", this._onKeyDown), this.addEventListener("focus", this._onHostFocus), this.addEventListener("contextmenu", this._onContextMenu), this.addEventListener("dragover", this._onDragover), this.addEventListener("dragleave", this._onDragleave), this.addEventListener("drop", this._onDrop), this.hasAttribute("tabindex") || this.setAttribute("tabindex", "0"), this.setAttribute("role", "grid"), typeof ResizeObserver < "u" && (this._hostResizeObserver = new ResizeObserver(() => this._measureViewport()), this._hostResizeObserver.observe(this));
 	}
 	disconnectedCallback() {
-		super.disconnectedCallback(), this.removeEventListener("scroll", this._onScroll), this.removeEventListener("keydown", this._onKeyDown), this.removeEventListener("contextmenu", this._onContextMenu), this.removeEventListener("dragover", this._onDragover), this.removeEventListener("dragleave", this._onDragleave), this.removeEventListener("drop", this._onDrop), document.removeEventListener("click", this._onDocumentClick), document.removeEventListener("mousedown", this._onCommentPopupOutsideClick), this._isDragging = !1, this._wasDrag = !1, this._resizeCleanup &&= (this._resizeCleanup(), null), this._hostResizeObserver &&= (this._hostResizeObserver.disconnect(), null);
+		super.disconnectedCallback(), this.removeEventListener("scroll", this._onScroll), this.removeEventListener("keydown", this._onKeyDown), this.removeEventListener("focus", this._onHostFocus), this.removeEventListener("contextmenu", this._onContextMenu), this.removeEventListener("dragover", this._onDragover), this.removeEventListener("dragleave", this._onDragleave), this.removeEventListener("drop", this._onDrop), document.removeEventListener("click", this._onDocumentClick), document.removeEventListener("mousedown", this._onCommentPopupOutsideClick), this._isDragging = !1, this._wasDrag = !1, this._resizeCleanup &&= (this._resizeCleanup(), null), this._hostResizeObserver &&= (this._hostResizeObserver.disconnect(), null);
 	}
 	firstUpdated() {
 		this._readDensityTokens(), this._measureViewport(), this.shadowRoot && Array.isArray(this.shadowRoot.adoptedStyleSheets) && (this._baseStyleSheets = [...this.shadowRoot.adoptedStyleSheets]), this._syncStylesheets();
@@ -2528,28 +2535,34 @@ var K = {
 		this._openFilterKey &&= null, this._headerMenu &&= null, this._bodyContextMenu &&= null;
 	}
 	_onContextMenu(e) {
-		let t = e.composedPath().find((e) => e instanceof HTMLElement && e.classList.contains("ft-cell"));
-		if (!t) return;
+		let t = e.composedPath(), n = t.find((e) => e instanceof HTMLElement && e.classList.contains("ft-cell"));
+		if (!n) {
+			if (t[0] === this && this._headerCol !== null) {
+				let t = this.visibleColumns[this._headerCol];
+				t && (e.preventDefault(), this._openColumnMenu(t));
+			}
+			return;
+		}
 		e.preventDefault();
-		let n = t.parentElement;
-		if (!n || !n.classList.contains("ft-row")) return;
-		let r = parseInt(t.dataset.colIndex ?? "-1", 10), i = n.style.top, a = Math.round(parseInt(i, 10) / this.rowHeight);
-		if (r < 0 || a < 0) return;
-		let o = this._toDataIndex(a), s = this.visibleColumns[r];
-		if (!s) return;
-		let c = this._emit("context-menu", {
+		let r = n.parentElement;
+		if (!r || !r.classList.contains("ft-row")) return;
+		let i = parseInt(n.dataset.colIndex ?? "-1", 10), a = r.style.top, o = Math.round(parseInt(a, 10) / this.rowHeight);
+		if (i < 0 || o < 0) return;
+		let s = this._toDataIndex(o), c = this.visibleColumns[i];
+		if (!c) return;
+		let l = 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]
+			row: s,
+			col: i,
+			key: c.key,
+			value: this.data[s]?.[c.key],
+			rowData: this.data[s]
 		}, { cancelable: !0 });
-		this._cancelCommentPopup(), this.showContextMenu && !c.defaultPrevented && (this._bodyContextMenu = {
-			rowIndex: a,
-			colIndex: r,
-			dataIndex: o,
+		this._cancelCommentPopup(), this.showContextMenu && !l.defaultPrevented && (this._bodyContextMenu = {
+			rowIndex: o,
+			colIndex: i,
+			dataIndex: s,
 			x: e.clientX,
 			y: e.clientY
 		}, requestAnimationFrame(() => {
@@ -2775,7 +2788,7 @@ var K = {
 		this._autocompleteState = null, this._applyEdit(e), this._selection.moveDown(), this._syncActiveCell();
 	}
 	_syncActiveCell() {
-		this._activeCell = this._selection.activeCell ? { ...this._selection.activeCell } : null, this._scrollToActiveCell(), this._dispatchSelectionEvent();
+		this._activeCell = this._selection.activeCell ? { ...this._selection.activeCell } : null, this._activeCell && (this._headerCol = null), this._scrollToActiveCell(), this._dispatchSelectionEvent();
 	}
 	_onKeyDown(e) {
 		if (this._editing.current || this._openFilterKey && e.composedPath().some((e) => e instanceof Element && e.classList.contains("ft-filter-dropdown"))) return;
@@ -2789,7 +2802,22 @@ var K = {
 				"y"
 			].includes(t) && this._handleCtrlKey(e)) return;
 		}
-		if (t.length !== 0 && this._visibleRowCount !== 0 && (e.composedPath()[0] === this || e.ctrlKey || e.metaKey)) {
+		if (t.length !== 0 && (e.composedPath()[0] === this || e.ctrlKey || e.metaKey)) {
+			if (this._headerCol !== null) {
+				this._onHeaderKeyDown(e, t);
+				return;
+			}
+			if (this._visibleRowCount === 0) {
+				[
+					"ArrowDown",
+					"ArrowUp",
+					"ArrowLeft",
+					"ArrowRight",
+					"Home",
+					"End"
+				].includes(e.key) && (e.preventDefault(), this._headerCol = 0);
+				return;
+			}
 			if ((e.key === "Enter" || e.key === "F2") && this._activeCell && !_(e)) {
 				e.preventDefault();
 				let n = t[this._activeCell.col];
@@ -2802,7 +2830,6 @@ var K = {
 					"ArrowUp",
 					"ArrowLeft",
 					"ArrowRight",
-					"Tab",
 					"Home",
 					"End"
 				].includes(e.key)) {
@@ -2825,10 +2852,47 @@ var K = {
 					e && this._isCellEditable(e) && this._startEdit();
 					return;
 				}
+				if (e.key === "ArrowUp" && !e.shiftKey && !e.altKey && this._activeCell?.row === 0) {
+					e.preventDefault(), this._enterHeader(this._activeCell.col);
+					return;
+				}
 				this._handleNavigation(e) && (e.preventDefault(), this._syncActiveCell());
 			}
 		}
 	}
+	_onHeaderKeyDown(e, t) {
+		if (e.ctrlKey || e.metaKey) return;
+		let n = Math.min(this._headerCol ?? 0, t.length - 1), r = t[n], i;
+		switch (e.key) {
+			case "ArrowLeft":
+			case "ArrowRight":
+				if (e.altKey) {
+					e.preventDefault(), this._resizeColumnBy(r.key, e.key === "ArrowRight" ? Y : -20);
+					return;
+				}
+				i = e.key === "ArrowLeft" ? Math.max(0, n - 1) : Math.min(t.length - 1, n + 1);
+				break;
+			case "Home":
+				i = 0;
+				break;
+			case "End":
+				i = t.length - 1;
+				break;
+			case "ArrowDown":
+				e.preventDefault(), e.altKey ? this._openColumnMenu(r) : this._visibleRowCount > 0 && (this._selection.setActive(0, n), this._syncActiveCell());
+				return;
+			case "Enter":
+			case " ":
+				if (_(e)) return;
+				e.preventDefault(), r.sortable !== !1 && this._toggleSort(r, e.shiftKey);
+				return;
+			default: return;
+		}
+		e.preventDefault(), this._headerCol = i, this._scrollColumnIntoView(i);
+	}
+	_enterHeader(e) {
+		this._selection.clear(), this._syncActiveCell(), this._headerCol = e, this._scrollColumnIntoView(e);
+	}
 	_handleCtrlKey(e) {
 		if (!(e.ctrlKey || e.metaKey) || e.altKey) return !1;
 		switch (e.key.toLowerCase()) {
@@ -2874,7 +2938,10 @@ var K = {
 			case "ArrowDown": return e.shiftKey ? this._selection.shiftMoveDown() : this._selection.moveDown(), !0;
 			case "ArrowLeft": return e.shiftKey ? this._selection.shiftMoveLeft() : this._selection.moveLeft(), !0;
 			case "ArrowRight": return e.shiftKey ? this._selection.shiftMoveRight() : this._selection.moveRight(), !0;
-			case "Tab": return e.shiftKey ? this._selection.movePrev() : this._selection.moveNext(), !0;
+			case "Tab": {
+				let t = this._selection.activeCell, n = e.shiftKey ? this._selection.movePrev() : this._selection.moveNext();
+				return !(t && n && t.row === n.row && t.col === n.col);
+			}
 			case "Home": return e.ctrlKey ? this._selection.moveToStart() : this._selection.moveToRowStart(), !0;
 			case "End": return e.ctrlKey ? this._selection.moveToEnd() : this._selection.moveToRowEnd(), !0;
 			case "Escape": return this._findState ? (this._closeFindPanel(), !0) : (this._selection.clear(), !0);
@@ -3102,24 +3169,29 @@ var K = {
 	_scrollToActiveCell() {
 		if (!this._activeCell) return;
 		let e = this._activeCell.row * this.rowHeight + this.headerHeight, t = e + this.rowHeight;
-		this._activeCell.row < this._frozenRowCount || (e < this.scrollTop + this.headerHeight + this.frozenRowsHeight ? this.scrollTop = e - this.headerHeight - this.frozenRowsHeight : t > this.scrollTop + this.clientHeight && (this.scrollTop = t - this.clientHeight));
-		let n = this.visibleColumns, r = this._activeCell.col, i = this._colLeftOffsets[r] ?? 0, a = i + this._getColWidth(n[r]);
-		i < this.scrollLeft ? this.scrollLeft = i : a > this.scrollLeft + this.clientWidth && (this.scrollLeft = a - this.clientWidth);
+		this._activeCell.row < this._frozenRowCount || (e < this.scrollTop + this.headerHeight + this.frozenRowsHeight ? this.scrollTop = e - this.headerHeight - this.frozenRowsHeight : t > this.scrollTop + this.clientHeight && (this.scrollTop = t - this.clientHeight)), this._scrollColumnIntoView(this._activeCell.col);
+	}
+	_scrollColumnIntoView(e) {
+		let t = this.visibleColumns, n = this._colLeftOffsets[e] ?? 0, r = n + this._getColWidth(t[e]);
+		n < this.scrollLeft ? this.scrollLeft = n : r > this.scrollLeft + this.clientWidth && (this.scrollLeft = r - this.clientWidth);
 	}
 	_dispatchSelectionEvent() {
 		this._emit("cell-select", this._activeCell ? { ...this._activeCell } : null);
 	}
-	_onHeaderClick(t, n) {
+	_onHeaderClick(e, t) {
 		if (this._wasHeaderDrag) {
 			this._wasHeaderDrag = !1;
 			return;
 		}
-		let r = this.visibleColumns.indexOf(n);
-		if (t.ctrlKey || t.metaKey) {
-			this._selectColumn(r);
+		let n = this.visibleColumns.indexOf(t);
+		if (e.ctrlKey || e.metaKey) {
+			this._selectColumn(n);
 			return;
 		}
-		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] }));
+		t.sortable !== !1 && this._toggleSort(t, e.shiftKey);
+	}
+	_toggleSort(t, n) {
+		this._sortCriteria = e(this._sortCriteria, t.key, n), this.dataMode !== "server" && this._recomputeView(), this.requestUpdate(), this._emit("sort-change", { criteria: [...this._sortCriteria] });
 	}
 	_selectColumn(e) {
 		let t = this._visibleRowCount;
@@ -3158,7 +3230,8 @@ var K = {
 			n ? "ft-sortable" : "",
 			u ? "ft-pinned" : "",
 			d === "center" ? "ft-header-align-center" : "",
-			d === "end" ? "ft-header-align-end" : ""
+			d === "end" ? "ft-header-align-end" : "",
+			this._headerCol === t ? "ft-header-active" : ""
 		].filter(Boolean).join(" "), p = n ? r ? r.direction === "asc" ? "ascending" : "descending" : "none" : void 0, m = this._getColWidth(e), h = this.headerHeight, g = this._colLeftOffsets[t] ?? 0, _;
 		_ = c ? `position: absolute; top: 0; left: ${this._scrollLeft + this._getPinnedLeft(t)}px; width: ${m}px; height: ${h}px; z-index: 4;` : l ? `position: absolute; top: 0; left: ${this._getPinnedRightLeft(t)}px; width: ${m}px; height: ${h}px; z-index: 4;` : `left: ${g}px; width: ${m}px; height: ${h}px;`;
 		let v = this._colDrag?.active && this._colDrag.colIndex === t, y = [...f.split(" "), v ? "ft-col-dragging" : ""].filter(Boolean).join(" "), b = this.columns, x = b.findIndex((t) => t.key === e.key), S = [];
@@ -3175,7 +3248,7 @@ var K = {
         @mousedown=${(n) => this._onHeaderMouseDown(n, e, t)}
         @click=${n ? (t) => this._onHeaderClick(t, e) : void 0}>
         ${C ? i`
-          <button class="ft-hidden-col-indicator"
+          <button class="ft-hidden-col-indicator" tabindex="-1"
             title=${k("showHiddenColumns")}
             @click=${(t) => {
 			t.stopPropagation(), this._showHiddenBefore(e);
@@ -3186,6 +3259,8 @@ var K = {
         ${o >= 0 ? i`<span class="ft-sort-order">${o + 1}</span>` : ""}
         <button class="ft-column-menu-btn ${s ? "ft-filter-active" : ""}"
           type="button"
+          tabindex="-1"
+          data-key=${e.key}
           title=${k("columnMenu")}
           aria-label=${k("columnMenuFor", { header: e.label })}
           aria-haspopup="menu"
@@ -3231,12 +3306,15 @@ var K = {
 			this._headerMenu = null;
 			return;
 		}
-		let n = e.currentTarget.getBoundingClientRect();
+		this._openColumnMenu(t, e.currentTarget);
+	}
+	_openColumnMenu(e, t = this._columnMenuButton(e.key)) {
+		let n = t?.getBoundingClientRect();
 		this._openFilterKey = null, this._headerMenu = {
-			key: t.key,
-			x: n.left,
-			y: n.bottom,
-			hiddenNeighbors: this._hiddenNeighbors(t)
+			key: e.key,
+			x: n?.left ?? 0,
+			y: n?.bottom ?? 0,
+			hiddenNeighbors: this._hiddenNeighbors(e)
 		}, requestAnimationFrame(() => {
 			document.addEventListener("click", this._onDocumentClick, { once: !0 });
 		}), this.updateComplete.then(() => this._menuItems()[0]?.focus());
@@ -3250,7 +3328,7 @@ var K = {
 	}
 	_closeHeaderMenu(e) {
 		let t = this._headerMenu?.key;
-		this._headerMenu = null, e && t && this._columnMenuButton(t)?.focus();
+		this._headerMenu = null, e && t && (this._headerCol === null ? this._columnMenuButton(t)?.focus() : this.focus());
 	}
 	_onHeaderMenuKeydown(e) {
 		this._onMenuKeydown(e, ".ft-header-menu", (e) => this._closeHeaderMenu(e));
@@ -3424,11 +3502,34 @@ var K = {
 		let s = Math.max(4, Math.min(n.left, i - r.width - 4));
 		e.style.left = `${s}px`, e.style.top = `${o}px`;
 	}
+	_closeFilterDropdown(e = !0) {
+		let t = this._openFilterKey;
+		if (this._openFilterKey = null, e && t !== null) {
+			if (this._headerCol !== null) {
+				this.focus();
+				return;
+			}
+			this.updateComplete.then(() => {
+				[...this.shadowRoot?.querySelectorAll(".ft-column-menu-btn") ?? []].find((e) => e.dataset.key === t)?.focus();
+			});
+		}
+	}
+	_onFilterDialogKeydown(e) {
+		if (e.key !== "Tab") return;
+		let t = [...e.currentTarget.querySelectorAll("input, select, textarea, button, u-date-picker")].filter((e) => !e.disabled && e.getClientRects().length > 0);
+		if (t.length === 0) return;
+		let n = e.composedPath(), r = t.findIndex((e) => n.includes(e)), i = t.length - 1;
+		e.shiftKey && r <= 0 ? (e.preventDefault(), t[i].focus()) : !e.shiftKey && (r === i || r === -1) && (e.preventDefault(), t[0].focus());
+	}
 	_renderFilterDropdown(e) {
 		let t = e.type ?? "text";
 		return i`
-      <div class="ft-filter-dropdown" role="group" aria-label=${k("filterFor", { header: e.label })}
-        @click=${(e) => e.stopPropagation()}>
+      <div class="ft-filter-dropdown" role="dialog" aria-label=${k("filterFor", { header: e.label })}
+        @click=${(e) => e.stopPropagation()}
+        @keydown=${{
+			handleEvent: (e) => this._onFilterDialogKeydown(e),
+			capture: !0
+		}}>
         ${t === "boolean" ? this._renderBooleanFilter(e) : t === "number" ? this._renderNumberFilter(e) : t === "date" || t === "datetime" ? this._renderDateFilter(e) : this._renderTextFilter(e)}
         <div class="ft-filter-actions">
           <button class="ft-filter-clear" @click=${() => this._clearColumnFilter(e.key)}>${k("clear")}</button>
@@ -3472,7 +3573,7 @@ var K = {
 			(r === "" || r === "empty" || r === "non-empty") && (r ? this._emptyFilterState.set(e, r) : this._emptyFilterState.delete(e), t?.(), this._applyFilterForKey(e));
 		}}
           @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
           <option value="">${k("blankAll")}</option>
           <option value="empty">${k("emptyOnly")}</option>
@@ -3550,7 +3651,7 @@ var K = {
 			}), this._applyTextFilter(e.key);
 		}}
           @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
           <option value="contains">${k("contains")}</option>
           <option value="starts">${k("startsWith")}</option>
@@ -3571,7 +3672,7 @@ var K = {
 			}), this._emptyFilterState.delete(e.key), this._applyTextFilter(e.key);
 		}}
         @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
       ${this._renderEmptyFilterRow(e.key, () => {
 			this._textFilterState.delete(e.key);
@@ -3605,7 +3706,7 @@ var K = {
 			}, this._numberFilterState.set(e, i), this._emptyFilterState.delete(e), this._applyFilterForKey(e);
 		}}
           @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
           ${Object.keys(K).map((e) => i`<option value=${e}>${K[e]}</option>`)}
         </select>
@@ -3622,7 +3723,7 @@ var K = {
 			}, this._numberFilterState.set(e, i), this._emptyFilterState.delete(e), this._applyFilterForKey(e);
 		}}
           @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
       </div>
     `;
@@ -3639,7 +3740,7 @@ var K = {
 			r.join = n, this._numberFilterState.set(e.key, r), this._emptyFilterState.delete(e.key), this._applyFilterForKey(e.key);
 		}}
           @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
           <option value="and">AND</option>
           <option value="or">OR</option>
@@ -3671,7 +3772,7 @@ var K = {
 	}
 	_renderDateFilter(e) {
 		let t = e.type === "datetime", n = this._dateFilterState.get(e.key) ?? {}, r = (e) => e?.slice(0, 10), o = (e) => {
-			e.key === "Escape" && $(e.currentTarget) || (e.stopPropagation(), e.key === "Escape" && (this._openFilterKey = null));
+			e.key === "Escape" && $(e.currentTarget) || (e.stopPropagation(), e.key === "Escape" && this._closeFilterDropdown());
 		};
 		return i`
       <div class="ft-filter-range ft-filter-range-dates">
@@ -3703,7 +3804,7 @@ var K = {
 			n === "all" ? this.removeFilter(e.key) : this.setFilter(e.key, (e) => !!e == (n === "true"));
 		}}
         @keydown=${(e) => {
-			e.key === "Escape" && (this._openFilterKey = null), e.stopPropagation();
+			e.key === "Escape" && this._closeFilterDropdown(), e.stopPropagation();
 		}}>
         <option value="all">${k("all")}</option>
         <option value="true">\u2714 ${k("booleanTrue")}</option>
@@ -4468,7 +4569,7 @@ G([s({ type: Array })], Q.prototype, "columns", void 0), G([s({
 })], Q.prototype, "footerData", void 0), G([s({ attribute: !1 })], Q.prototype, "stylesheets", void 0), G([s({
 	type: Number,
 	attribute: "max-undo-size"
-})], Q.prototype, "maxUndoSize", null), G([c()], Q.prototype, "_scrollTop", void 0), G([c()], Q.prototype, "_scrollLeft", void 0), G([c()], Q.prototype, "_viewportHeight", void 0), G([c()], Q.prototype, "_viewportWidth", void 0), G([c()], Q.prototype, "_activeCell", void 0), G([c()], Q.prototype, "_editingCell", void 0), G([c()], Q.prototype, "_sortCriteria", void 0), G([c()], Q.prototype, "_openFilterKey", void 0), G([c()], Q.prototype, "_rowSelectionVersion", void 0), G([c()], Q.prototype, "_autocompleteState", void 0), G([c()], Q.prototype, "_headerMenu", void 0), G([c()], Q.prototype, "_bodyContextMenu", void 0), G([c()], Q.prototype, "_commentPopup", void 0), G([c()], Q.prototype, "_isDragOver", void 0), Q = G([o("flex-table")], Q);
+})], Q.prototype, "maxUndoSize", null), G([c()], Q.prototype, "_scrollTop", void 0), G([c()], Q.prototype, "_scrollLeft", void 0), G([c()], Q.prototype, "_viewportHeight", void 0), G([c()], Q.prototype, "_viewportWidth", void 0), G([c()], Q.prototype, "_activeCell", void 0), G([c()], Q.prototype, "_headerCol", void 0), G([c()], Q.prototype, "_editingCell", void 0), G([c()], Q.prototype, "_sortCriteria", void 0), G([c()], Q.prototype, "_openFilterKey", void 0), G([c()], Q.prototype, "_rowSelectionVersion", void 0), G([c()], Q.prototype, "_autocompleteState", void 0), G([c()], Q.prototype, "_headerMenu", void 0), G([c()], Q.prototype, "_bodyContextMenu", void 0), G([c()], Q.prototype, "_commentPopup", void 0), G([c()], Q.prototype, "_isDragOver", void 0), Q = G([o("flex-table")], Q);
 function Qe(e, t) {
 	if (t) {
 		let t = fe(e);

package/dist/flex-table.d.ts

@@ -108,6 +108,11 @@ export declare class FlexTable extends LitElement {
     /** The grid's own compiled styles, captured once so `stylesheets` merges without dropping them. */
     private _baseStyleSheets;
     private _activeCell;
+    /**
+     * The header cell the keyboard is on — the header row sits above the first body row (ArrowUp from
+     * it). Exclusive with an active body cell: entering one leaves the other.
+     */
+    private _headerCol;
     private _editingCell;
     private _sortCriteria;
     private _selection;
@@ -394,6 +399,20 @@ export declare class FlexTable extends LitElement {
     private _selectAutocompleteCandidate;
     private _syncActiveCell;
     private _onKeyDown;
+    /**
+     * The keyboard on the header row: arrows / Home / End move along it, ArrowDown returns to the body,
+     * Enter or Space sorts (Shift adds to the sort), Alt+ArrowDown opens the column menu, Alt+Arrow
+     * resizes. Tab leaves the grid.
+     */
+    private _onHeaderKeyDown;
+    /** Move the keyboard from the body onto the header cell of visible column `colIndex`. */
+    private _enterHeader;
+    /**
+     * Keyboard focus arriving on a grid with nothing active places it on the first cell (the first header
+     * cell when the body is empty), so the first arrow already moves and Tab is not spent entering. A
+     * pointer focus places the cell it pressed instead.
+     */
+    private _onHostFocus;
     private _handleCtrlKey;
     private _handleAltKey;
     /** Widen (positive) or narrow (negative) a visible column by `delta` px, never below its minimum. */
@@ -423,8 +442,12 @@ export declare class FlexTable extends LitElement {
     private _clearRanges;
     private _clearRange;
     private _scrollToActiveCell;
+    /** Scroll horizontally so the visible column at `colIndex` is in view — cached column offsets. */
+    private _scrollColumnIntoView;
     private _dispatchSelectionEvent;
     private _onHeaderClick;
+    /** Cycle `col`'s sort (asc → desc → none); `multi` adds it to the existing criteria (Shift). */
+    private _toggleSort;
     private _selectColumn;
     /** Public API: select an entire column by index. */
     selectColumn(colIndex: number): void;
@@ -456,6 +479,8 @@ export declare class FlexTable extends LitElement {
      * and resizing without dragging the 6px handle (WCAG 2.2 SC 2.5.7 / 2.5.8).
      */
     private _onColumnMenuBtnClick;
+    /** Open `col`'s column menu under `anchor` (its menu button by default) and focus the first item. */
+    private _openColumnMenu;
     private _menuItems;
     private _columnMenuButton;
     private _closeHeaderMenu;
@@ -484,6 +509,18 @@ export declare class FlexTable extends LitElement {
     /** Keep a fixed-position menu inside the viewport — a menu opened near the right or bottom edge would spill off-screen. */
     private _keepMenuInView;
     private _adjustFilterDropdown;
+    /**
+     * Close the filter dialog. From the keyboard (Escape) focus goes back to the column's menu button — the
+     * dialog leaves the DOM, and focus inside it would otherwise drop to the page (APG dialog). A click
+     * outside closes it without moving focus: the click already put focus where the user meant.
+     */
+    private _closeFilterDropdown;
+    /**
+     * Tab stays inside the filter dialog (it floats over the table, fixed to the header — a focus that left
+     * it would leave it open and unreachable behind the next control). Capture phase: the controls stop
+     * their own keydowns from reaching the grid.
+     */
+    private _onFilterDialogKeydown;
     private _renderFilterDropdown;
     private _buildTextPredicate;
     private _applyTextFilter;

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

@@ -1,4 +1,4 @@
-import { t as e } from "./flex-table-BsxF9Q3O.js";
+import { t as e } from "./flex-table-B64ScsFY.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.49.0",
+  "version": "0.50.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",

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

@@ -68,7 +68,10 @@ flex-table {
 
 | Key | Action |
 |---|---|
-| Arrows / Tab / Shift+Tab | Move between cells |
+| Arrows / Tab / Shift+Tab | Move between cells; Tab past the last (Shift+Tab before the first) leaves the table |
+| ArrowUp on the first row | Move onto the header row (arrows / Home / End along it, ArrowDown back) |
+| Enter / Space on a header cell | Sort (Shift adds to the sort) |
+| Alt+ArrowDown or context-menu key on a header cell | Open the column menu |
 | Home / End, Ctrl+Home / Ctrl+End | Row start/end, table start/end |
 | Shift+Arrow, Shift+Click | Extend range selection |
 | Shift+Space | Select / deselect the active cell's row (`selectable`; row checkboxes are not Tab stops) |
@@ -84,6 +87,9 @@ flex-table {
 | Alt+ArrowLeft / Alt+ArrowRight | Resize current column |
 | Enter / Space on a column menu button | Open the column menu (arrows, Home/End navigate; Escape closes) |
 
+The table is one Tab stop — keyboard focus arriving on it activates the first cell; the column menu
+buttons are not Tab stops (the header row reaches them).
+
 Ctrl also matches Cmd on macOS. Editing shortcuts are ignored when `editable` is `false`.
 
 ## Localization