picocrank 1.31.1 → 1.33.0

package/vue/components/Table.vue

@@ -7,6 +7,21 @@
 		<table class="row-hover" :class="{ loading: isLoading }">
 			<thead>
 				<tr>
+					<th
+						v-if="selectable"
+						class="table-select-col"
+						@click.stop
+					>
+						<label class="table-select-label">
+							<input
+								type="checkbox"
+								:checked="allDisplayRowsSelected"
+								:indeterminate="someDisplayRowsSelected"
+								:aria-label="allDisplayRowsSelected ? 'Deselect all rows on this page' : 'Select all rows on this page'"
+								@change="toggleSelectAllDisplayRows"
+							>
+						</label>
+					</th>
 					<th
 						v-for="(header, index) in visibleHeaders"
 						:key="header.key || index"
@@ -62,30 +77,68 @@
 				<tr
 					v-for="(row, rowIndex) in displayRows"
 					:key="resolveRowKey(row, rowIndex)"
-					:class="{ 'row-clickable': rowClickable }"
+					:class="[
+						{
+							'row-clickable': rowClickable,
+							'row-selected': selectable && isRowSelected(row, rowIndex),
+							'row-context-menu-active': isRowContextMenuTarget(row, rowIndex),
+						},
+						resolveRowClass(row, rowIndex),
+					]"
+					:style="resolveRowStyle(row, rowIndex)"
 					@click="onRowClick(row, rowIndex, $event)"
+					@contextmenu="onRowContextMenu(row, rowIndex, $event)"
 				>
+					<td
+						v-if="selectable"
+						class="table-select-col"
+						data-row-click-ignore
+						@click.stop
+					>
+						<label class="table-select-label">
+							<input
+								type="checkbox"
+								:checked="isRowSelected(row, rowIndex)"
+								:aria-label="`Select row ${resolveRowKey(row, rowIndex)}`"
+								@click.stop="rememberSelectionCheckboxClick(row, rowIndex, $event)"
+								@change="onSelectionCheckboxChange(row, rowIndex)"
+							>
+						</label>
+					</td>
 					<td
 						v-for="(header, cellIndex) in visibleHeaders"
 						:key="header.key || cellIndex"
+						:ref="(element) => registerCellElement(element, row, header, rowIndex)"
+						v-bind="resolveCellAttrs(row, header, rowIndex)"
 						:colspan="bodyColumnColspan(cellIndex) || undefined"
 						:class="[
 							cellClasses(header),
 							header.class,
+							resolveCellClass(row, header, rowIndex),
+							{ 'table-active-cell': isActiveCell(row, header, rowIndex) },
 							isLastColumnWithOptions(cellIndex) ? 'table-last-column-with-options' : null,
 						]"
+						:style="resolveCellStyle(row, header, rowIndex)"
+						:tabindex="isActiveCell(row, header, rowIndex) ? 0 : -1"
+						@click="onCellClick(row, header, rowIndex, $event)"
 					>
 						<slot
 							v-if="slots[`cell-${header.key}`]"
 							:name="`cell-${header.key}`"
 							:row="row"
 							:value="row[header.key]"
+							:header="header"
+							:row-index="rowIndex"
+							:source-index="sourceRowIndex(row, rowIndex)"
 						/>
 						<slot
 							v-else-if="slots.cell"
 							name="cell"
 							:row="row"
 							:value="row[header.key]"
+							:header="header"
+							:row-index="rowIndex"
+							:source-index="sourceRowIndex(row, rowIndex)"
 						/>
 						<span v-else>
 							{{ row[header.key] }}
@@ -120,9 +173,11 @@
 		:value="activeFilterValue"
 		:rows="props.data"
 		:select-options="activeSelectOptions"
+		:can-hide="canHideActiveFilterColumn"
 		@apply="onFilterApply"
 		@clear="onFilterClear"
 		@cancel="onFilterCancel"
+		@hide="onFilterHideColumn"
 	/>
 
 	<TableColumnOptionsPopover
@@ -148,15 +203,25 @@
 		@apply="onColumnOptionsApply"
 		@cancel="onColumnOptionsCancel"
 	/>
+
+	<TableRowContextMenu
+		v-model:open="rowContextMenuOpen"
+		:items="rowContextMenuItems"
+		:client-x="rowContextMenuX"
+		:client-y="rowContextMenuY"
+		:target-count="rowContextMenuTargetKeys.length"
+		@select="onRowContextMenuSelect"
+	/>
 </template>
 
 <script setup>
-import { ref, computed, watch, onMounted, onBeforeUnmount, useSlots, useAttrs } from 'vue'
+import { ref, computed, watch, nextTick, onMounted, onBeforeUnmount, useSlots, useAttrs } from 'vue'
 import { HugeiconsIcon } from '@hugeicons/vue'
 import { LayoutGridIcon } from '@hugeicons/core-free-icons'
 import Pagination from './Pagination.vue'
 import TableColumnFilterPopover from './TableColumnFilterPopover.vue'
 import TableColumnOptionsPopover from './TableColumnOptionsPopover.vue'
+import TableRowContextMenu from './TableRowContextMenu.vue'
 import { useLongPress } from '../composables/useLongPress.js'
 import {
 	buildSelectOptions,
@@ -189,11 +254,6 @@ import {
 
 const DEFAULT_PAGE_SIZE = 10
 
-const sortBy = ref(null)
-const sortDir = ref('asc')
-const page = ref(1)
-const pageSize = ref(DEFAULT_PAGE_SIZE)
-
 const props = defineProps({
 	headers: {
 		type: Array,
@@ -203,6 +263,29 @@ const props = defineProps({
 		type: Array,
 		default: () => [],
 	},
+	sortBy: {
+		type: [String, Number],
+		default: undefined,
+	},
+	sortDir: {
+		type: String,
+		default: undefined,
+		validator: (value) => value === undefined || value === 'asc' || value === 'desc',
+	},
+	page: {
+		type: Number,
+		default: undefined,
+		validator: (value) => value === undefined || (Number.isFinite(value) && value >= 1),
+	},
+	pageSize: {
+		type: Number,
+		default: undefined,
+		validator: (value) => value === undefined || (Number.isFinite(value) && value >= 1),
+	},
+	resetPageOnSort: {
+		type: Boolean,
+		default: true,
+	},
 	showPagination: {
 		type: Boolean,
 		default: true,
@@ -276,6 +359,53 @@ const props = defineProps({
 		type: Object,
 		default: null,
 	},
+	selectable: {
+		type: Boolean,
+		default: false,
+	},
+	selectedKeys: {
+		type: Array,
+		default: undefined,
+	},
+	selectionClickMode: {
+		type: String,
+		default: 'row',
+		validator: (value) => ['row', 'checkbox', 'modifier', 'extended'].includes(value),
+	},
+	activeCell: {
+		type: Object,
+		default: undefined,
+	},
+	rowClass: {
+		type: Function,
+		default: null,
+	},
+	rowStyle: {
+		type: Function,
+		default: null,
+	},
+	cellClass: {
+		type: Function,
+		default: null,
+	},
+	cellStyle: {
+		type: Function,
+		default: null,
+	},
+	cellAttrs: {
+		type: Function,
+		default: null,
+	},
+	/**
+	 * Row right-click menu. Array of items, or a function that returns items
+	 * for the click context. Each item may include `action(ctx)` where
+	 * `ctx.keys` / `ctx.rows` are the target selection (clicked row, or all
+	 * selected rows when the click is inside the current multi-selection).
+	 */
+	rowContextMenu: {
+		type: [Array, Function],
+		default: null,
+	},
 })
 
 const emit = defineEmits([
@@ -284,6 +414,16 @@ const emit = defineEmits([
 	'query-change',
 	'fetch-error',
 	'row-click',
+	'cell-click',
+	'update:sortBy',
+	'update:sortDir',
+	'update:page',
+	'update:pageSize',
+	'update:selectedKeys',
+	'selection-change',
+	'update:activeCell',
+	'row-context-menu',
+	'row-context-menu-action',
 	'update:columnVisibility',
 	'column-visibility-change',
 	'update:columnOrder',
@@ -297,8 +437,111 @@ const emit = defineEmits([
 const attrs = useAttrs()
 const slots = useSlots()
 
-const rowClickable = computed(() => Boolean(attrs.onRowClick))
+function normalizePage(value) {
+	const numeric = Number(value)
+	return Number.isFinite(numeric) && numeric >= 1 ? Math.floor(numeric) : 1
+}
+
+function normalizePageSize(value) {
+	const numeric = Number(value)
+	return Number.isFinite(numeric) && numeric >= 1 ? Math.floor(numeric) : DEFAULT_PAGE_SIZE
+}
+
+function normalizeSortDir(value) {
+	return value === 'desc' ? 'desc' : 'asc'
+}
+
+function normalizeActiveCell(value) {
+	if (
+		!value
+		|| typeof value !== 'object'
+		|| value.rowKey === null
+		|| value.rowKey === undefined
+		|| value.columnKey === null
+		|| value.columnKey === undefined
+	) {
+		return null
+	}
+	return {
+		rowKey: value.rowKey,
+		columnKey: value.columnKey,
+	}
+}
+
+const internalSortBy = ref(props.sortBy !== undefined ? props.sortBy : null)
+const internalSortDir = ref(normalizeSortDir(props.sortDir))
+const internalPage = ref(normalizePage(props.page))
+const internalPageSize = ref(normalizePageSize(props.pageSize))
+const internalActiveCell = ref(normalizeActiveCell(props.activeCell))
+
+const sortBy = computed({
+	get: () => props.sortBy !== undefined ? props.sortBy : internalSortBy.value,
+	set: (value) => {
+		const nextValue = value ?? null
+		if (nextValue === sortBy.value) {
+			return
+		}
+		if (props.sortBy === undefined) {
+			internalSortBy.value = nextValue
+		}
+		emit('update:sortBy', nextValue)
+	},
+})
+
+const sortDir = computed({
+	get: () => props.sortDir !== undefined ? normalizeSortDir(props.sortDir) : internalSortDir.value,
+	set: (value) => {
+		const nextValue = normalizeSortDir(value)
+		if (nextValue === sortDir.value) {
+			return
+		}
+		if (props.sortDir === undefined) {
+			internalSortDir.value = nextValue
+		}
+		emit('update:sortDir', nextValue)
+	},
+})
+
+const page = computed({
+	get: () => props.page !== undefined ? normalizePage(props.page) : internalPage.value,
+	set: (value) => {
+		const nextValue = normalizePage(value)
+		if (nextValue === page.value) {
+			return
+		}
+		if (props.page === undefined) {
+			internalPage.value = nextValue
+		}
+		emit('update:page', nextValue)
+	},
+})
+
+const pageSize = computed({
+	get: () => props.pageSize !== undefined ? normalizePageSize(props.pageSize) : internalPageSize.value,
+	set: (value) => {
+		const nextValue = normalizePageSize(value)
+		if (nextValue === pageSize.value) {
+			return
+		}
+		if (props.pageSize === undefined) {
+			internalPageSize.value = nextValue
+		}
+		emit('update:pageSize', nextValue)
+	},
+})
+
+const activeCell = computed(() => (
+	props.activeCell !== undefined ? normalizeActiveCell(props.activeCell) : internalActiveCell.value
+))
+
+const rowClickable = computed(() =>
+	Boolean(attrs.onRowClick)
+	|| (props.selectable && props.selectionClickMode !== 'checkbox'),
+)
 const internalFilters = ref({})
+const internalSelectedKeys = ref([])
+const selectionAnchorKey = ref(null)
+const pendingSelectionCheckboxClick = ref(null)
 const remoteRows = ref([])
 const remoteTotal = ref(0)
 const internalLoading = ref(false)
@@ -491,11 +734,20 @@ const filteredItems = computed(() => {
 	return applyFilterQuery(props.data, props.headers, activeFilterQuery.value)
 })
 
+const activeSortHeader = computed(() =>
+	props.headers.find((header) => header?.key === sortBy.value),
+)
+
 const sortedItems = computed(() => {
 	if (isRemote.value) {
 		return filteredItems.value
 	}
-	return sortRows(filteredItems.value, sortBy.value, sortDir.value)
+	return sortRows(
+		filteredItems.value,
+		sortBy.value,
+		sortDir.value,
+		activeSortHeader.value?.comparator,
+	)
 })
 
 const displayRows = computed(() => {
@@ -613,6 +865,60 @@ function cellClasses(header) {
 	}
 }
 
+function sourceRowIndex(row, displayIndex) {
+	const sourceRows = isRemote.value ? remoteRows.value : props.data
+	const index = sourceRows.indexOf(row)
+	return index >= 0 ? index : filteredRowIndex(displayIndex)
+}
+
+function rowContext(row, rowIndex) {
+	return {
+		row,
+		rowIndex,
+		sourceIndex: sourceRowIndex(row, rowIndex),
+	}
+}
+
+function cellContext(row, header, rowIndex) {
+	return {
+		...rowContext(row, rowIndex),
+		value: row?.[header.key],
+		header,
+	}
+}
+
+function resolveRowClass(row, rowIndex) {
+	return props.rowClass?.(rowContext(row, rowIndex))
+}
+
+function resolveRowStyle(row, rowIndex) {
+	return props.rowStyle?.(rowContext(row, rowIndex))
+}
+
+function resolveCellClass(row, header, rowIndex) {
+	return props.cellClass?.(cellContext(row, header, rowIndex))
+}
+
+function resolveCellStyle(row, header, rowIndex) {
+	return props.cellStyle?.(cellContext(row, header, rowIndex))
+}
+
+function resolveCellAttrs(row, header, rowIndex) {
+	const value = props.cellAttrs?.(cellContext(row, header, rowIndex))
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return {}
+	}
+
+	const {
+		class: _class,
+		style: _style,
+		key: _key,
+		ref: _ref,
+		...safeAttrs
+	} = value
+	return safeAttrs
+}
+
 function resolveRowKey(row, index) {
 	if (typeof props.rowKey === 'function') {
 		const key = props.rowKey(row, index)
@@ -632,6 +938,312 @@ function resolveRowKey(row, index) {
 	return index
 }
 
+function activeCellsEqual(left, right) {
+	return left?.rowKey === right?.rowKey && left?.columnKey === right?.columnKey
+}
+
+function setActiveCell(nextCell) {
+	const normalized = normalizeActiveCell(nextCell)
+	if (activeCellsEqual(normalized, activeCell.value)) {
+		return
+	}
+	if (props.activeCell === undefined) {
+		internalActiveCell.value = normalized
+	}
+	emit('update:activeCell', normalized)
+}
+
+function clearActiveCell() {
+	setActiveCell(null)
+}
+
+function isActiveCell(row, header, rowIndex) {
+	const current = activeCell.value
+	return Boolean(
+		current
+		&& current.rowKey === resolveRowKey(row, rowIndex)
+		&& current.columnKey === header.key,
+	)
+}
+
+const activeCellElements = new Map()
+
+function registerCellElement(element, row, header, rowIndex) {
+	const rowKey = resolveRowKey(row, rowIndex)
+	let rowCells = activeCellElements.get(rowKey)
+
+	if (!element) {
+		rowCells?.delete(header.key)
+		if (rowCells?.size === 0) {
+			activeCellElements.delete(rowKey)
+		}
+		return
+	}
+
+	if (!rowCells) {
+		rowCells = new Map()
+		activeCellElements.set(rowKey, rowCells)
+	}
+	rowCells.set(header.key, element)
+}
+
+function focusCell(cell, options) {
+	if (!cell) {
+		return false
+	}
+	const element = activeCellElements.get(cell.rowKey)?.get(cell.columnKey)
+	if (!element) {
+		return false
+	}
+	element.focus(options)
+	return true
+}
+
+function focusActiveCell(options) {
+	return focusCell(activeCell.value, options)
+}
+
+function cellContextAt(rowIndex, columnIndex) {
+	const row = displayRows.value[rowIndex]
+	const header = visibleHeaders.value[columnIndex]
+	if (!row || !header) {
+		return null
+	}
+
+	return {
+		...cellContext(row, header, rowIndex),
+		rowKey: resolveRowKey(row, rowIndex),
+		columnKey: header.key,
+		columnIndex,
+	}
+}
+
+function getActiveCellContext() {
+	const current = activeCell.value
+	if (!current) {
+		return null
+	}
+
+	const rowIndex = displayRows.value.findIndex(
+		(row, index) => resolveRowKey(row, index) === current.rowKey,
+	)
+	const columnIndex = visibleHeaders.value.findIndex(
+		(header) => header.key === current.columnKey,
+	)
+	if (rowIndex < 0 || columnIndex < 0) {
+		return null
+	}
+
+	return cellContextAt(rowIndex, columnIndex)
+}
+
+function clampGridIndex(value, maximum) {
+	const numeric = Number(value)
+	const normalized = Number.isFinite(numeric) ? Math.trunc(numeric) : 0
+	return Math.min(Math.max(normalized, 0), maximum)
+}
+
+function scheduleCellFocus(cell, options) {
+	if (!options?.focus) {
+		return
+	}
+	void nextTick(() => focusCell(cell, options.focusOptions))
+}
+
+function activateCellAt(rowIndex, columnIndex, options = {}) {
+	if (displayRows.value.length === 0 || visibleHeaders.value.length === 0) {
+		return null
+	}
+
+	const nextRowIndex = clampGridIndex(rowIndex, displayRows.value.length - 1)
+	const nextColumnIndex = clampGridIndex(columnIndex, visibleHeaders.value.length - 1)
+	const context = cellContextAt(nextRowIndex, nextColumnIndex)
+	const nextActiveCell = {
+		rowKey: context.rowKey,
+		columnKey: context.columnKey,
+	}
+
+	setActiveCell(nextActiveCell)
+	scheduleCellFocus(nextActiveCell, options)
+	return context
+}
+
+function moveActiveCell(rowDelta, columnDelta, options = {}) {
+	if (displayRows.value.length === 0 || visibleHeaders.value.length === 0) {
+		return null
+	}
+
+	const current = getActiveCellContext()
+	if (!current) {
+		return activateCellAt(0, 0, options)
+	}
+
+	const normalizedRowDelta = Number.isFinite(Number(rowDelta)) ? Math.trunc(Number(rowDelta)) : 0
+	const normalizedColumnDelta = Number.isFinite(Number(columnDelta))
+		? Math.trunc(Number(columnDelta))
+		: 0
+	const rowIndex = clampGridIndex(
+		current.rowIndex + normalizedRowDelta,
+		displayRows.value.length - 1,
+	)
+	let columnIndex
+
+	if (options.wrapColumns) {
+		const linearIndex = (rowIndex * visibleHeaders.value.length)
+			+ current.columnIndex
+			+ normalizedColumnDelta
+		const clampedLinearIndex = clampGridIndex(
+			linearIndex,
+			(displayRows.value.length * visibleHeaders.value.length) - 1,
+		)
+		return activateCellAt(
+			Math.floor(clampedLinearIndex / visibleHeaders.value.length),
+			clampedLinearIndex % visibleHeaders.value.length,
+			options,
+		)
+	}
+
+	columnIndex = clampGridIndex(
+		current.columnIndex + normalizedColumnDelta,
+		visibleHeaders.value.length - 1,
+	)
+	return activateCellAt(rowIndex, columnIndex, options)
+}
+
+function onCellClick(row, header, rowIndex, event) {
+	const context = cellContext(row, header, rowIndex)
+	const nextActiveCell = {
+		rowKey: resolveRowKey(row, rowIndex),
+		columnKey: header.key,
+	}
+	setActiveCell(nextActiveCell)
+	emit('cell-click', {
+		...context,
+		...nextActiveCell,
+		event,
+	})
+}
+
+const activeSelectedKeys = computed(() => (
+	props.selectedKeys !== undefined ? props.selectedKeys : internalSelectedKeys.value
+))
+
+const selectedKeySet = computed(() => new Set(activeSelectedKeys.value))
+
+function isRowSelected(row, index) {
+	return selectedKeySet.value.has(resolveRowKey(row, index))
+}
+
+function setSelectedKeys(nextKeys) {
+	const unique = [...new Set(nextKeys)]
+	if (props.selectedKeys === undefined) {
+		internalSelectedKeys.value = unique
+	}
+	emit('update:selectedKeys', unique)
+	emit('selection-change', unique)
+}
+
+function toggleRowSelection(row, index) {
+	const key = resolveRowKey(row, index)
+	const current = activeSelectedKeys.value
+	selectionAnchorKey.value = key
+	if (selectedKeySet.value.has(key)) {
+		setSelectedKeys(current.filter((item) => item !== key))
+		return
+	}
+	setSelectedKeys([...current, key])
+}
+
+function replaceRowSelection(row, index) {
+	const key = resolveRowKey(row, index)
+	selectionAnchorKey.value = key
+	setSelectedKeys([key])
+}
+
+const displayRowKeys = computed(() =>
+	displayRows.value.map((row, index) => resolveRowKey(row, index)),
+)
+
+function selectRowRange(row, index, { updateAnchor = true } = {}) {
+	const key = resolveRowKey(row, index)
+	const anchorIndex = displayRowKeys.value.findIndex((item) => item === selectionAnchorKey.value)
+	const targetIndex = displayRowKeys.value.findIndex((item) => item === key)
+
+	if (anchorIndex < 0 || targetIndex < 0) {
+		setSelectedKeys([...activeSelectedKeys.value, key])
+		selectionAnchorKey.value = key
+		return
+	}
+
+	const from = Math.min(anchorIndex, targetIndex)
+	const to = Math.max(anchorIndex, targetIndex)
+	setSelectedKeys([
+		...activeSelectedKeys.value,
+		...displayRowKeys.value.slice(from, to + 1),
+	])
+	if (updateAnchor) {
+		selectionAnchorKey.value = key
+	}
+}
+
+function rememberSelectionCheckboxClick(row, index, event) {
+	pendingSelectionCheckboxClick.value = {
+		key: resolveRowKey(row, index),
+		shiftKey: event.shiftKey,
+	}
+}
+
+function onSelectionCheckboxChange(row, index) {
+	const key = resolveRowKey(row, index)
+	const shiftKey = (
+		pendingSelectionCheckboxClick.value?.key === key
+		&& pendingSelectionCheckboxClick.value.shiftKey
+	)
+	pendingSelectionCheckboxClick.value = null
+
+	if (shiftKey) {
+		selectRowRange(row, index)
+		return
+	}
+	toggleRowSelection(row, index)
+}
+
+const allDisplayRowsSelected = computed(() => {
+	const keys = displayRowKeys.value
+	return keys.length > 0 && keys.every((key) => selectedKeySet.value.has(key))
+})
+
+const someDisplayRowsSelected = computed(() => {
+	if (allDisplayRowsSelected.value) {
+		return false
+	}
+	return displayRowKeys.value.some((key) => selectedKeySet.value.has(key))
+})
+
+function toggleSelectAllDisplayRows() {
+	const pageKeys = displayRowKeys.value
+	if (pageKeys.length === 0) {
+		return
+	}
+
+	if (allDisplayRowsSelected.value) {
+		const pageKeySet = new Set(pageKeys)
+		setSelectedKeys(activeSelectedKeys.value.filter((key) => !pageKeySet.has(key)))
+		selectionAnchorKey.value = null
+		return
+	}
+
+	setSelectedKeys([...activeSelectedKeys.value, ...pageKeys])
+	selectionAnchorKey.value = pageKeys.at(-1) ?? null
+}
+
+watch(() => props.selectable, (enabled) => {
+	if (!enabled) {
+		setSelectedKeys([])
+		selectionAnchorKey.value = null
+	}
+})
+
 function setFilters(nextFilters) {
 	const cloned = cloneFilters(nextFilters)
 	if (props.filters === undefined) {
@@ -686,7 +1298,188 @@ function onRowClick(row, displayIndex, event) {
 	if (event.target.closest('a, button, input, select, textarea, [data-row-click-ignore]')) {
 		return
 	}
-	emit('row-click', { row, index: filteredRowIndex(displayIndex) })
+
+	if (props.selectable) {
+		if (props.selectionClickMode === 'extended') {
+			if (event.ctrlKey || event.metaKey) {
+				toggleRowSelection(row, displayIndex)
+				return
+			}
+
+			const hasRangeAnchor = displayRowKeys.value.includes(selectionAnchorKey.value)
+			if (event.shiftKey && hasRangeAnchor) {
+				selectRowRange(row, displayIndex, { updateAnchor: false })
+				return
+			}
+
+			replaceRowSelection(row, displayIndex)
+			return
+		}
+
+		if (
+			props.selectionClickMode !== 'checkbox'
+			&& event.shiftKey
+		) {
+			selectRowRange(row, displayIndex)
+			return
+		}
+
+		if (
+			props.selectionClickMode === 'row'
+			|| (
+				props.selectionClickMode === 'modifier'
+				&& (event.ctrlKey || event.metaKey)
+			)
+		) {
+			toggleRowSelection(row, displayIndex)
+			return
+		}
+	}
+
+	emit('row-click', {
+		row,
+		index: filteredRowIndex(displayIndex),
+		event,
+	})
+}
+
+const rowContextMenuOpen = ref(false)
+const rowContextMenuX = ref(0)
+const rowContextMenuY = ref(0)
+const rowContextMenuItems = ref([])
+const rowContextMenuTargetKeys = ref([])
+const rowContextMenuAnchor = ref(null)
+
+const rowContextMenuTargetKeySet = computed(() => new Set(rowContextMenuTargetKeys.value))
+
+function isRowContextMenuTarget(row, index) {
+	return rowContextMenuOpen.value && rowContextMenuTargetKeySet.value.has(resolveRowKey(row, index))
+}
+
+const hasRowContextMenu = computed(() => {
+	if (typeof props.rowContextMenu === 'function') {
+		return true
+	}
+	return Array.isArray(props.rowContextMenu) && props.rowContextMenu.length > 0
+})
+
+function buildRowLookup() {
+	const map = new Map()
+	const addRows = (rows) => {
+		rows.forEach((row, index) => {
+			const key = resolveRowKey(row, index)
+			if (!map.has(key)) {
+				map.set(key, row)
+			}
+		})
+	}
+
+	if (isRemote.value) {
+		addRows(remoteRows.value)
+	} else {
+		addRows(props.data)
+	}
+	addRows(displayRows.value)
+	return map
+}
+
+function resolveTargetRows(keys) {
+	const lookup = buildRowLookup()
+	return keys.map((key) => lookup.get(key)).filter((row) => row != null)
+}
+
+function normalizeContextMenuItems(rawItems) {
+	if (!Array.isArray(rawItems)) {
+		return []
+	}
+	return rawItems.filter((item) => item && (item.divider || item.label || item.id))
+}
+
+function closeRowContextMenu() {
+	rowContextMenuOpen.value = false
+	rowContextMenuItems.value = []
+	rowContextMenuTargetKeys.value = []
+	rowContextMenuAnchor.value = null
+}
+
+function onRowContextMenu(row, displayIndex, event) {
+	if (!hasRowContextMenu.value) {
+		return
+	}
+	if (event.target.closest('a, button, input, select, textarea, [data-row-click-ignore]')) {
+		return
+	}
+
+	event.preventDefault()
+	event.stopPropagation()
+
+	const key = resolveRowKey(row, displayIndex)
+	const index = filteredRowIndex(displayIndex)
+	let targetKeys
+
+	if (props.selectable && selectedKeySet.value.has(key) && activeSelectedKeys.value.length > 0) {
+		targetKeys = [...activeSelectedKeys.value]
+	} else {
+		targetKeys = [key]
+		if (props.selectable) {
+			setSelectedKeys([key])
+		}
+	}
+
+	const rows = resolveTargetRows(targetKeys)
+	const ctx = {
+		row,
+		key,
+		index,
+		rows,
+		keys: targetKeys,
+		selectedKeys: [...activeSelectedKeys.value],
+	}
+
+	const rawItems = typeof props.rowContextMenu === 'function'
+		? props.rowContextMenu(ctx)
+		: props.rowContextMenu
+	const items = normalizeContextMenuItems(rawItems)
+	if (items.length === 0) {
+		closeRowContextMenu()
+		return
+	}
+
+	rowContextMenuAnchor.value = ctx
+	rowContextMenuTargetKeys.value = targetKeys
+	rowContextMenuItems.value = items
+	rowContextMenuX.value = event.clientX
+	rowContextMenuY.value = event.clientY
+	rowContextMenuOpen.value = true
+
+	emit('row-context-menu', {
+		...ctx,
+		event,
+	})
+}
+
+function onRowContextMenuSelect(item) {
+	const anchor = rowContextMenuAnchor.value
+	const keys = [...rowContextMenuTargetKeys.value]
+	const lookup = buildRowLookup()
+	const rows = keys.map((key) => lookup.get(key)).filter((row) => row != null)
+	const selectedKeys = [...activeSelectedKeys.value]
+	const payload = {
+		item,
+		row: anchor?.row,
+		key: anchor?.key,
+		index: anchor?.index,
+		rows,
+		keys,
+		selectedKeys,
+	}
+
+	if (typeof item.action === 'function') {
+		item.action(payload)
+	}
+
+	emit('row-context-menu-action', payload)
+	closeRowContextMenu()
 }
 
 function openFilter(header, event) {
@@ -756,6 +1549,39 @@ function onFilterCancel() {
 	activeFilterValue.value = []
 }
 
+const canHideActiveFilterColumn = computed(() => {
+	if (!showColumnOptionsButton.value || !activeFilterHeader.value) {
+		return false
+	}
+	const header = activeFilterHeader.value
+	if (!header.key || header.hideable === false || header.hidden) {
+		return false
+	}
+	if (!isHeaderHidden(header) && visibleColumnKeys.value.length <= 1) {
+		return false
+	}
+	return configurableHeaders.value.some((item) => item.key === header.key)
+})
+
+function onFilterHideColumn() {
+	const header = activeFilterHeader.value
+	if (!header?.key || !canHideActiveFilterColumn.value) {
+		onFilterCancel()
+		return
+	}
+
+	const nextVisibleKeys = visibleColumnKeys.value.filter((key) => key !== header.key)
+	if (nextVisibleKeys.length === 0) {
+		onFilterCancel()
+		return
+	}
+
+	setColumnVisibility(nextVisibleKeys)
+	updateActiveLayoutLabel()
+	filterPopoverOpen.value = false
+	onFilterCancel()
+}
+
 function buildColumnVisibility(visibleKeys) {
 	const visibleKeySet = new Set(visibleKeys)
 	return Object.fromEntries(
@@ -1238,7 +2064,7 @@ function scheduleFetchRows() {
 }
 
 watch(
-	() => [pageSize.value, sortBy.value, sortDir.value],
+	pageSize,
 	() => {
 		page.value = 1
 		if (isRemote.value) {
@@ -1248,6 +2074,19 @@ watch(
 	},
 )
 
+watch(
+	() => [sortBy.value, sortDir.value],
+	() => {
+		if (props.resetPageOnSort) {
+			page.value = 1
+		}
+		if (isRemote.value) {
+			scheduleFetchRows()
+		}
+		emitQueryChange()
+	},
+)
+
 watch(page, () => {
 	if (isRemote.value) {
 		scheduleFetchRows()
@@ -1255,6 +2094,40 @@ watch(page, () => {
 	emitQueryChange()
 })
 
+watch(() => props.sortBy, (value) => {
+	if (value !== undefined) {
+		internalSortBy.value = value ?? null
+	}
+})
+
+watch(() => props.sortDir, (value) => {
+	if (value !== undefined) {
+		internalSortDir.value = normalizeSortDir(value)
+	}
+})
+
+watch(() => props.page, (value) => {
+	if (value !== undefined) {
+		internalPage.value = normalizePage(value)
+	}
+})
+
+watch(() => props.pageSize, (value) => {
+	if (value !== undefined) {
+		internalPageSize.value = normalizePageSize(value)
+	}
+})
+
+watch(
+	() => props.activeCell,
+	(value) => {
+		if (value !== undefined) {
+			internalActiveCell.value = normalizeActiveCell(value)
+		}
+	},
+	{ deep: true },
+)
+
 watch(
 	activeFilters,
 	() => {
@@ -1362,11 +2235,15 @@ watch(activeLayoutLabel, (label) => {
 	emitLayoutLabelChange(label)
 }, { immediate: true })
 
-watch(sortedItems, () => {
-	if (!isRemote.value) {
-		page.value = 1
-	}
-})
+watch(
+	() => props.data,
+	() => {
+		if (!isRemote.value) {
+			page.value = 1
+		}
+	},
+	{ deep: true },
+)
 
 onMounted(async () => {
 	if (props.loadSavedLayout) {
@@ -1409,6 +2286,12 @@ onBeforeUnmount(() => {
 defineExpose({
 	layoutLabel: activeLayoutLabel,
 	loadDeveloperDefaults,
+	clearFilters: clearAllFilters,
+	focusActiveCell,
+	clearActiveCell,
+	activateCellAt,
+	moveActiveCell,
+	getActiveCellContext,
 })
 </script>
 
@@ -1457,10 +2340,85 @@ th:first-child {
 	padding-left: 1rem;
 }
 
+th.table-select-col,
+td.table-select-col {
+	width: 2.5rem;
+	min-width: 2.5rem;
+	max-width: 2.5rem;
+	text-align: center;
+	vertical-align: middle;
+	padding-left: 1rem;
+	padding-right: 0.25rem;
+}
+
+.table-select-label {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	margin: 0;
+	cursor: pointer;
+}
+
 tbody tr.row-clickable {
 	cursor: pointer;
 }
 
+tbody td.table-active-cell {
+	outline: 2px solid currentColor;
+	outline-offset: -2px;
+}
+
+tbody td.table-active-cell:focus,
+tbody td.table-active-cell:focus-visible {
+	outline-width: 3px;
+}
+
+tbody tr.row-selected > td {
+	background-color: var(--control-checked-bg);
+	color: var(--control-checked-fg);
+}
+
+table.row-hover tbody tr.row-selected:hover > td,
+table.row-hover tbody tr.row-selected:focus-within > td,
+table.row-hover tbody tr.row-selected.row-context-menu-active > td {
+	background-color: var(--control-checked-hover-bg);
+	color: var(--control-checked-fg);
+}
+
+/* Keep hover styling while the row context menu is open (pointer has left the row). */
+table.row-hover tbody tr.row-context-menu-active > td {
+	background-color: var(--table-row-hover-bg);
+	color: var(--table-row-hover-fg);
+}
+
+/* Beat Femtocrank sticky cell backgrounds so selection remains visible while scrolling. */
+.table-scroll.sticky-cols-1 table tbody tr.row-selected > td,
+.table-scroll.sticky-cols-2 table tbody tr.row-selected > td,
+.table-scroll.sticky-cols-3 table tbody tr.row-selected > td {
+	background-color: var(--control-checked-bg);
+	color: var(--control-checked-fg);
+}
+
+.table-scroll.sticky-cols-1 table.row-hover tbody tr.row-selected:hover > td,
+.table-scroll.sticky-cols-1 table.row-hover tbody tr.row-selected:focus-within > td,
+.table-scroll.sticky-cols-1 table.row-hover tbody tr.row-selected.row-context-menu-active > td,
+.table-scroll.sticky-cols-2 table.row-hover tbody tr.row-selected:hover > td,
+.table-scroll.sticky-cols-2 table.row-hover tbody tr.row-selected:focus-within > td,
+.table-scroll.sticky-cols-2 table.row-hover tbody tr.row-selected.row-context-menu-active > td,
+.table-scroll.sticky-cols-3 table.row-hover tbody tr.row-selected:hover > td,
+.table-scroll.sticky-cols-3 table.row-hover tbody tr.row-selected:focus-within > td,
+.table-scroll.sticky-cols-3 table.row-hover tbody tr.row-selected.row-context-menu-active > td {
+	background-color: var(--control-checked-hover-bg);
+	color: var(--control-checked-fg);
+}
+
+.table-scroll.sticky-cols-1 table.row-hover tbody tr.row-context-menu-active > td,
+.table-scroll.sticky-cols-2 table.row-hover tbody tr.row-context-menu-active > td,
+.table-scroll.sticky-cols-3 table.row-hover tbody tr.row-context-menu-active > td {
+	background-color: var(--table-row-hover-bg);
+	color: var(--table-row-hover-fg);
+}
+
 .table-empty-state {
 	display: flex;
 	align-items: center;