@iyulab/flex-table 0.49.1 → 0.50.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.50.1] - 2026-10-06
+
+### Fixed
+
+- **Screen readers hear the active cell.** The table kept the focus on itself and marked the active cell
+  with a class only, so assistive technology announced the grid and nothing as the arrow keys moved
+  (the host cannot point `aria-activedescendant` into its own shadow tree). The focus now sits on the
+  active cell — or the active header cell — while the table has it (roving focus): each move is announced
+  with the cell's row, column and content. `document.activeElement` is still the table.
+- When scrolling moves the focused cell out of the rendered window, the focus waits on the table instead
+  of staying on a recycled cell that now shows another row; the next key brings it back onto the active
+  cell.
+
+## [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

package/README.md

@@ -67,7 +67,7 @@ npm install @iyulab/flex-table
 - **Data Mode** — Client-side or server-side sorting/filtering (`dataMode`)
 - **Context Menu** — `context-menu` event for custom right-click menus
 - **React Wrapper** — `@iyulab/flex-table/react` subpath for idiomatic React usage
-- **ARIA** — `role="grid"`, `aria-sort`, `aria-selected`, `aria-readonly`, `aria-invalid`, `aria-rowcount`, `aria-colcount`, `aria-rowindex`, `aria-colindex`
+- **ARIA** — `role="grid"` with roving focus (the focus sits on the active cell or header cell, so screen readers announce each move), `aria-sort`, `aria-selected`, `aria-readonly`, `aria-invalid`, `aria-rowcount`, `aria-colcount`, `aria-rowindex`, `aria-colindex`
 
 ## Sizing
 
@@ -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,17 @@ 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.
+While the table has the focus, the focus sits on the active cell (or header cell) itself — `document.activeElement`
+is the table, and its `shadowRoot.activeElement` is that cell.
 
 ## Localization
 

package/dist/{flex-table-CpAhHipx.js → flex-table-Hx-xTm0e.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,23 @@ 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._focusedCellEl = 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._onFocusIn = (e) => {
+			let t = e.composedPath()[0];
+			t !== this && this._isGridSurface(t) && (this._focusedCellEl = t, this.tabIndex === 0 && (this._hostTabIndexLowered = !0, this.tabIndex = -1));
+		}, this._onFocusOut = (e) => {
+			let t = e.relatedTarget;
+			if (t && (t === this || this.contains(t) || this.shadowRoot?.contains(t))) return;
+			let n = e.composedPath()[0];
+			requestAnimationFrame(() => {
+				if (n instanceof HTMLElement && n === this._focusedCellEl && !n.isConnected) {
+					this._syncGridFocus();
+					return;
+				}
+				document.activeElement !== this && (this._focusedCellEl = null, this._hostTabIndexLowered && (this._hostTabIndexLowered = !1, this.tabIndex = 0));
+			});
+		}, this._hostTabIndexLowered = !1, this._onCommentPopupOutsideClick = () => {
 			this._commitCommentPopup();
 		}, this._invalidCells = /* @__PURE__ */ new Map(), this._textFilterState = /* @__PURE__ */ new Map(), this._numberFilterState = /* @__PURE__ */ new Map(), this._dateFilterState = /* @__PURE__ */ new Map(), this._emptyFilterState = /* @__PURE__ */ new Map();
 	}
@@ -2418,10 +2439,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.renderRoot.addEventListener("focusin", this._onFocusIn), this.renderRoot.addEventListener("focusout", this._onFocusOut), 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.renderRoot.removeEventListener("focusin", this._onFocusIn), this.renderRoot.removeEventListener("focusout", this._onFocusOut), 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();
@@ -2472,7 +2493,7 @@ var K = {
 		(!(e.size <= 2 && !e.has("data") && !e.has("columns") && !e.has("_openFilterKey") && !e.has("_editingCell") && !e.has("_activeCell") && (e.has("_scrollTop") || e.has("_scrollLeft"))) || this._viewDirty) && (this._recomputeView(), this._viewDirty = !1), this._updateColOffsets(), this._selection.setDimensions(this._visibleRowCount, this.visibleColumns.length), this._rowSelection.setRowCount(this._visibleRowCount);
 	}
 	updated(e) {
-		this._focusEditor(), this._adjustFilterDropdown(), e.has("_headerMenu") && this._keepMenuInView(".ft-header-menu"), e.has("_bodyContextMenu") && this._bodyContextMenu && (this._keepMenuInView(".ft-body-context-menu"), this.shadowRoot?.querySelector(".ft-body-context-menu [role=\"menuitem\"]")?.focus()), e.has("stylesheets") && this._syncStylesheets();
+		this._focusEditor(), this._syncGridFocus(), this._adjustFilterDropdown(), e.has("_headerMenu") && this._keepMenuInView(".ft-header-menu"), e.has("_bodyContextMenu") && this._bodyContextMenu && (this._keepMenuInView(".ft-body-context-menu"), this.shadowRoot?.querySelector(".ft-body-context-menu [role=\"menuitem\"]")?.focus()), e.has("stylesheets") && this._syncStylesheets();
 		let t = String(1 + this._visibleRowCount + +!!this.footerData), n = String(this.visibleColumns.length);
 		if (this.getAttribute("aria-rowcount") !== t && this.setAttribute("aria-rowcount", t), this.getAttribute("aria-colcount") !== n && this.setAttribute("aria-colcount", n), this.loading ? this.getAttribute("aria-busy") !== "true" && this.setAttribute("aria-busy", "true") : this.hasAttribute("aria-busy") && this.removeAttribute("aria-busy"), e.has("_commentPopup") && this._commentPopup) {
 			let e = this.shadowRoot?.querySelector(".ft-comment-popup textarea");
@@ -2528,28 +2549,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 +2802,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 +2816,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 && (this._isGridSurface(e.composedPath()[0]) || 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 +2844,6 @@ var K = {
 					"ArrowUp",
 					"ArrowLeft",
 					"ArrowRight",
-					"Tab",
 					"Home",
 					"End"
 				].includes(e.key)) {
@@ -2825,10 +2866,69 @@ 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);
+	}
+	_isGridSurface(e) {
+		return e === this || e instanceof HTMLElement && (e.classList.contains("ft-cell") || e.classList.contains("ft-header-cell")) && !e.classList.contains("ft-editing");
+	}
+	_keyboardCellEl() {
+		let e = this.shadowRoot;
+		if (!e) return null;
+		if (this._headerCol !== null) return e.querySelector(`.ft-header-cell[data-col-index="${this._headerCol}"]`);
+		let t = this._activeCell;
+		return t ? e.querySelector(`.ft-row[aria-rowindex="${t.row + 2}"] .ft-cell[data-col-index="${t.col}"]`) : null;
+	}
+	_syncGridFocus() {
+		let e = this.shadowRoot;
+		if (!e) return;
+		let t = e.activeElement;
+		if (document.activeElement !== this) {
+			this._focusedCellEl && !this._focusedCellEl.isConnected && (document.activeElement === document.body || document.activeElement === null) && (this._focusedCellEl = null, (this._keyboardCellEl() ?? this).focus({ preventScroll: !0 }));
+			return;
+		}
+		if (t && !this._isGridSurface(t)) return;
+		let n = this._keyboardCellEl() ?? this;
+		n !== (t ?? this) && n.focus({ preventScroll: !0 });
+	}
 	_handleCtrlKey(e) {
 		if (!(e.ctrlKey || e.metaKey) || e.altKey) return !1;
 		switch (e.key.toLowerCase()) {
@@ -2874,7 +2974,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 +3205,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 +3266,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 = [];
@@ -3167,6 +3276,7 @@ var K = {
 		return i`
       <div class=${y}
         role="columnheader"
+        tabindex="-1"
         aria-colindex=${t + 1}
         data-col-index=${t}
         style=${_}
@@ -3175,7 +3285,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 +3296,7 @@ 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 })}
@@ -3232,12 +3343,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());
@@ -3251,7 +3365,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));
@@ -3427,9 +3541,15 @@ var K = {
 	}
 	_closeFilterDropdown(e = !0) {
 		let t = this._openFilterKey;
-		this._openFilterKey = null, e && t !== null && this.updateComplete.then(() => {
-			[...this.shadowRoot?.querySelectorAll(".ft-column-menu-btn") ?? []].find((e) => e.dataset.key === t)?.focus();
-		});
+		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;
@@ -4350,6 +4470,7 @@ var K = {
 		return i`
       <div class=${E ? C + " ft-has-comment" : C}
         role="gridcell"
+        tabindex="-1"
         aria-colindex=${r + 1}
         data-col-index=${r}
         aria-selected=${v ? "true" : "false"}
@@ -4486,7 +4607,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,13 @@ 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;
+    /** The cell (body or header) that last held the keyboard focus — to take it back if a re-render drops it. */
+    private _focusedCellEl;
     private _editingCell;
     private _sortCriteria;
     private _selection;
@@ -394,6 +401,40 @@ 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;
+    /**
+     * The grid's own keyboard surface: the host, the active body cell, the active header cell. Keys on
+     * anything else inside it (an editor, a menu, a button a cell renders) belong to that control.
+     */
+    private _isGridSurface;
+    /**
+     * The element the keyboard is on — the active header cell, else the active body cell — when it is
+     * rendered (the body scrolls it out of the virtual window), else `null`.
+     */
+    private _keyboardCellEl;
+    /**
+     * Roving focus: while the grid holds the focus, the focus sits on the cell the keyboard is on, so
+     * assistive technology announces each move (the host cannot point `aria-activedescendant` into its
+     * own shadow tree). It moves only between the host and the grid's cells — never out of an editor,
+     * a menu or a control that holds it.
+     */
+    private _syncGridFocus;
+    private _onFocusIn;
+    private _onFocusOut;
+    private _hostTabIndexLowered;
     private _handleCtrlKey;
     private _handleAltKey;
     /** Widen (positive) or narrow (negative) a visible column by `delta` px, never below its minimum. */
@@ -423,8 +464,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 +501,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;

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-CpAhHipx.js";
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-Hx-xTm0e.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-CpAhHipx.js";
+import { t as e } from "./flex-table-Hx-xTm0e.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.1",
+  "version": "0.50.1",
   "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,10 @@ 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 with roving focus — the focus sits on the active cell or header cell (screen
+readers announce each move); 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