picocrank 1.33.0 → 1.35.0

package/vue/components/Table.vue

@@ -4,11 +4,31 @@
 		:class="needsTableWrapper ? tableWrapperClasses : undefined"
 		:style="needsTableWrapper ? undefined : { display: 'contents' }"
 	>
-		<table class="row-hover" :class="{ loading: isLoading }">
+		<table
+			ref="tableElementRef"
+			class="row-hover"
+			:class="{
+				loading: isLoading,
+				'has-column-widths': hasResizedColumns,
+				'is-column-resizing': activeResizeKey != null,
+			}"
+			:aria-busy="isLoading ? 'true' : undefined"
+			:aria-colcount="ariaColCount"
+		>
+			<colgroup>
+				<col v-if="selectable" class="table-select-col-width" />
+				<col
+					v-for="(header, index) in visibleHeaders"
+					:key="header.key || index"
+					:style="columnWidthStyle(header)"
+				/>
+				<col v-if="showColumnOptionsButton" class="table-column-options-col-width" />
+			</colgroup>
 			<thead>
 				<tr>
 					<th
 						v-if="selectable"
+						scope="col"
 						class="table-select-col"
 						@click.stop
 					>
@@ -25,8 +45,13 @@
 					<th
 						v-for="(header, index) in visibleHeaders"
 						:key="header.key || index"
-						:class="[headerClasses(header), header.class]"
-						:style="{ width: header.width || 'auto' }"
+						scope="col"
+						:data-column-key="header.key"
+						:class="[headerClasses(header), header.class, { 'is-resizing': activeResizeKey === header.key }]"
+						:style="[columnWidthStyle(header), columnOverflowStyle()]"
+						:aria-sort="headerAriaSort(header)"
+						:aria-haspopup="isHeaderFilterable(header) ? 'dialog' : undefined"
+						:aria-expanded="headerFilterExpanded(header)"
 						@click="onHeaderClick(header, $event)"
 						@contextmenu.prevent="openFilter(header, $event)"
 						@pointerdown="onHeaderPointerDown(header, $event)"
@@ -41,15 +66,58 @@
 
 						<span v-if="filterable && isHeaderFiltered(header)" class="filter-indicator" title="Filtered" aria-hidden="true">⧩</span>
 
-						<span v-if="header.sortable" class="sort-indicator">
-							<span v-if="sortBy === header.key">
-								<span v-if="sortDir === 'asc'">▲</span>
-								<span v-else-if="sortDir === 'desc'">▼</span>
-							</span>
+						<span
+							v-if="isHeaderGrouped(header)"
+							class="group-indicator"
+							title="Grouped"
+							aria-hidden="true"
+						>
+							<HugeiconsIcon
+								:icon="Group01Icon"
+								width="0.95em"
+								height="0.95em"
+								:strokeWidth="2"
+								aria-hidden="true"
+							/>
+						</span>
+
+						<span v-if="header.sortable" class="sort-indicator" aria-hidden="true">
+							<HugeiconsIcon
+								v-if="sortBy === header.key && sortDir === 'asc'"
+								:icon="SortByUp02Icon"
+								width="0.95em"
+								height="0.95em"
+								:strokeWidth="2"
+								aria-hidden="true"
+							/>
+							<HugeiconsIcon
+								v-else-if="sortBy === header.key && sortDir === 'desc'"
+								:icon="SortByDown02Icon"
+								width="0.95em"
+								height="0.95em"
+								:strokeWidth="2"
+								aria-hidden="true"
+							/>
 						</span>
+
+						<span
+							v-if="isHeaderResizable(header)"
+							class="column-resize-handle"
+							role="separator"
+							aria-orientation="vertical"
+							:aria-label="`Resize ${header.label || header.key} column`"
+							:aria-valuemin="MIN_COLUMN_WIDTH"
+							:aria-valuenow="columnResizeValueNow(header)"
+							:class="{ 'is-active': activeResizeKey === header.key }"
+							@pointerdown.stop="onResizePointerDown(header, $event)"
+							@dblclick.stop="onResizeDoubleClick(header, $event)"
+							@click.stop
+							@contextmenu.stop.prevent
+						/>
 					</th>
 					<th
 						v-if="showColumnOptionsButton"
+						scope="col"
 						class="actions table-column-options-header"
 					>
 						<span class="actions-menu-trigger">
@@ -74,77 +142,113 @@
 				</tr>
 			</thead>
 			<tbody v-if="hasRows">
-				<tr
-					v-for="(row, rowIndex) in displayRows"
-					:key="resolveRowKey(row, rowIndex)"
-					: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
+				<template v-for="(item, itemIndex) in displayBodyItems" :key="bodyItemKey(item, itemIndex)">
+					<tr
+						v-if="item.kind === 'group'"
+						class="table-group-row"
+						:class="{ 'table-group-row-collapsed': item.collapsed }"
 					>
-						<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)"
+						<td
+							v-if="selectable"
+							class="table-select-col table-group-cell"
+							data-row-click-ignore
+						/>
+						<td
+							:colspan="bodyGroupColspan"
+							class="table-group-cell"
+						>
+							<button
+								type="button"
+								class="table-group-toggle neutral"
+								:aria-expanded="item.collapsed ? 'false' : 'true'"
+								:aria-label="item.collapsed ? 'Expand group' : 'Collapse group'"
+								data-row-click-ignore
+								@click.stop="toggleGroupCollapsed(item.groupId)"
 							>
-						</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"
+								<HugeiconsIcon
+									class="table-group-chevron"
+									:icon="ArrowDown01Icon"
+									width="1em"
+									height="1em"
+									aria-hidden="true"
+								/>
+							</button>
+							<span class="table-group-label">{{ formatGroupValue(item.value) }}</span>
+							<span class="table-group-count subtle">({{ item.count }})</span>
+						</td>
+					</tr>
+					<tr
+						v-else
 						:class="[
-							cellClasses(header),
-							header.class,
-							resolveCellClass(row, header, rowIndex),
-							{ 'table-active-cell': isActiveCell(row, header, rowIndex) },
-							isLastColumnWithOptions(cellIndex) ? 'table-last-column-with-options' : null,
+							{
+								'row-clickable': rowClickable,
+								'row-selected': selectable && isRowSelected(item.row, item.displayIndex),
+								'row-context-menu-active': isRowContextMenuTarget(item.row, item.displayIndex),
+							},
+							resolveRowClass(item.row, item.displayIndex),
 						]"
-						:style="resolveCellStyle(row, header, rowIndex)"
-						:tabindex="isActiveCell(row, header, rowIndex) ? 0 : -1"
-						@click="onCellClick(row, header, rowIndex, $event)"
+						:style="resolveRowStyle(item.row, item.displayIndex)"
+						@click="onRowClick(item.row, item.displayIndex, $event)"
+						@contextmenu="onRowContextMenu(item.row, item.displayIndex, $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] }}
-						</span>
-					</td>
-				</tr>
+						<td
+							v-if="selectable"
+							class="table-select-col"
+							data-row-click-ignore
+							@click.stop
+						>
+							<label class="table-select-label">
+								<input
+									type="checkbox"
+									:checked="isRowSelected(item.row, item.displayIndex)"
+									:aria-label="`Select row ${resolveRowKey(item.row, item.displayIndex)}`"
+									@click.stop="rememberSelectionCheckboxClick(item.row, item.displayIndex, $event)"
+									@change="onSelectionCheckboxChange(item.row, item.displayIndex)"
+								>
+							</label>
+						</td>
+						<td
+							v-for="(header, cellIndex) in visibleHeaders"
+							:key="header.key || cellIndex"
+							:ref="(element) => registerCellElement(element, item.row, header, item.displayIndex)"
+							v-bind="resolveCellAttrs(item.row, header, item.displayIndex)"
+							:colspan="bodyColumnColspan(cellIndex) || undefined"
+							:class="[
+								cellClasses(header),
+								header.class,
+								resolveCellClass(item.row, header, item.displayIndex),
+								{ 'table-active-cell': isActiveCell(item.row, header, item.displayIndex) },
+								isLastColumnWithOptions(cellIndex) ? 'table-last-column-with-options' : null,
+							]"
+							:style="[resolveCellStyle(item.row, header, item.displayIndex), columnOverflowStyle()]"
+							:tabindex="isActiveCell(item.row, header, item.displayIndex) ? 0 : -1"
+							@click="onCellClick(item.row, header, item.displayIndex, $event)"
+							@keydown="onCellKeydown(item.row, header, item.displayIndex, $event)"
+						>
+							<slot
+								v-if="slots[`cell-${header.key}`]"
+								:name="`cell-${header.key}`"
+								:row="item.row"
+								:value="item.row[header.key]"
+								:header="header"
+								:row-index="item.displayIndex"
+								:source-index="sourceRowIndex(item.row, item.displayIndex)"
+							/>
+							<slot
+								v-else-if="slots.cell"
+								name="cell"
+								:row="item.row"
+								:value="item.row[header.key]"
+								:header="header"
+								:row-index="item.displayIndex"
+								:source-index="sourceRowIndex(item.row, item.displayIndex)"
+							/>
+							<span v-else>
+								{{ item.row[header.key] }}
+							</span>
+						</td>
+					</tr>
+				</template>
 			</tbody>
 		</table>
 
@@ -174,10 +278,13 @@
 		:rows="props.data"
 		:select-options="activeSelectOptions"
 		:can-hide="canHideActiveFilterColumn"
+		:can-group-by="canGroupByActiveFilterColumn"
+		:is-grouped-column="isActiveFilterHeaderGrouped"
 		@apply="onFilterApply"
 		@clear="onFilterClear"
 		@cancel="onFilterCancel"
 		@hide="onFilterHideColumn"
+		@group-by="onFilterGroupBy"
 	/>
 
 	<TableColumnOptionsPopover
@@ -195,10 +302,13 @@
 		:presets="savedPresets"
 		:default-preset-id="defaultPresetId"
 		:save-layout-preset="onSavePreset"
+		:overwrite-layout-preset="onOverwritePreset"
 		:load-layout-preset="onLoadPreset"
 		:delete-layout-preset="onDeletePreset"
 		:set-default-layout-preset="onSetDefaultPreset"
 		:load-developer-defaults="loadDeveloperDefaults"
+		:group-by="activeGroupBy"
+		:groupable="props.groupable"
 		:anchor-el="columnOptionsButtonRef"
 		@apply="onColumnOptionsApply"
 		@cancel="onColumnOptionsCancel"
@@ -217,7 +327,13 @@
 <script setup>
 import { ref, computed, watch, nextTick, onMounted, onBeforeUnmount, useSlots, useAttrs } from 'vue'
 import { HugeiconsIcon } from '@hugeicons/vue'
-import { LayoutGridIcon } from '@hugeicons/core-free-icons'
+import {
+	ArrowDown01Icon,
+	Group01Icon,
+	LayoutGridIcon,
+	SortByDown02Icon,
+	SortByUp02Icon,
+} from '@hugeicons/core-free-icons'
 import Pagination from './Pagination.vue'
 import TableColumnFilterPopover from './TableColumnFilterPopover.vue'
 import TableColumnOptionsPopover from './TableColumnOptionsPopover.vue'
@@ -242,17 +358,29 @@ import {
 	getPresetById,
 	listPresets,
 	savePreset,
+	overwritePreset,
 	deletePreset,
 	setDefaultPreset,
 	sanitizePresetState,
 	layoutStatesEqual,
 } from '../composables/tableColumnPresets.js'
+import {
+	getViewSettingsHandlers,
+	isViewSettingsControlEnabled,
+	VIEW_CONTROL_CALLBACK,
+} from '../composables/tableViewSettings.js'
 import {
 	defaultColumnPriorityForIndex,
 	isValidColPriority,
 } from '../composables/tableColumnPriorities.js'
+import {
+	buildDisplayBodyItems,
+	formatGroupValue,
+	isHeaderGroupable,
+} from '../composables/tableGroupBy.js'
 
 const DEFAULT_PAGE_SIZE = 10
+const MIN_COLUMN_WIDTH = 48
 
 const props = defineProps({
 	headers: {
@@ -343,6 +471,21 @@ const props = defineProps({
 		type: String,
 		default: '',
 	},
+	/**
+	 * How saved table views (column order, visibility, filters in presets, etc.) are stored.
+	 * - `localStorageControlled`: requires `tableId`; uses browser localStorage (default).
+	 * - `callbackControlled`: requires `viewSettings` callbacks (server or app-owned persistence).
+	 */
+	viewControlMode: {
+		type: String,
+		default: 'localStorageControlled',
+		validator: (value) => ['localStorageControlled', 'callbackControlled'].includes(value),
+	},
+	/** Callback handlers when `viewControlMode` is `callbackControlled`. */
+	viewSettings: {
+		type: Object,
+		default: null,
+	},
 	loadSavedLayout: {
 		type: Boolean,
 		default: true,
@@ -355,6 +498,7 @@ const props = defineProps({
 		type: [String, Function],
 		default: 'id',
 	},
+	/** @deprecated Use `viewSettings` with `viewControlMode="callbackControlled"`. */
 	layoutPresets: {
 		type: Object,
 		default: null,
@@ -406,6 +550,14 @@ const props = defineProps({
 		type: [Array, Function],
 		default: null,
 	},
+	groupable: {
+		type: Boolean,
+		default: true,
+	},
+	groupBy: {
+		type: String,
+		default: undefined,
+	},
 })
 
 const emit = defineEmits([
@@ -432,6 +584,8 @@ const emit = defineEmits([
 	'column-priorities-change',
 	'update:layoutLabel',
 	'layout-label-change',
+	'update:groupBy',
+	'group-by-change',
 ])
 
 const attrs = useAttrs()
@@ -561,15 +715,192 @@ const internalColumnPriorities = ref({})
 const savedPresets = ref([])
 const defaultPresetId = ref(null)
 const activeLayoutPresetId = ref(null)
+const internalGroupBy = ref(null)
+const collapsedGroupIds = ref([])
+/** @type {import('vue').Ref<Record<string, number | null>>} */
+const columnWidths = ref({})
+const activeResizeKey = ref(null)
+const tableElementRef = ref(null)
+let resizeSession = null
 
 const isRemote = computed(() => typeof props.fetchRows === 'function')
 
-const layoutPresetsAvailable = computed(() => {
-	if (isRemote.value) {
-		return props.layoutPresets != null
+const hasResizedColumns = computed(() =>
+	Object.values(columnWidths.value).some((width) => width != null),
+)
+
+function isHeaderResizable(header) {
+	return Boolean(header?.key) && header.resizable !== false
+}
+
+function formatColumnWidth(width) {
+	if (width == null || width === '') {
+		return undefined
 	}
-	return Boolean(props.tableId)
-})
+	return typeof width === 'number' ? `${width}px` : width
+}
+
+function columnWidthStyle(header) {
+	if (!header?.key) {
+		return header?.width ? { width: formatColumnWidth(header.width) } : undefined
+	}
+
+	if (Object.prototype.hasOwnProperty.call(columnWidths.value, header.key)) {
+		const resized = columnWidths.value[header.key]
+		if (resized == null) {
+			return undefined
+		}
+		return { width: `${resized}px` }
+	}
+
+	if (header.width) {
+		return { width: formatColumnWidth(header.width) }
+	}
+
+	return undefined
+}
+
+function columnOverflowStyle() {
+	if (!hasResizedColumns.value) {
+		return undefined
+	}
+	return {
+		overflow: 'hidden',
+		textOverflow: 'ellipsis',
+		whiteSpace: 'nowrap',
+	}
+}
+
+function columnResizeValueNow(header) {
+	const width = columnWidths.value[header.key]
+	return typeof width === 'number' ? width : undefined
+}
+
+function setColumnWidths(nextWidths) {
+	columnWidths.value = nextWidths
+}
+
+function setColumnWidth(columnKey, width) {
+	columnWidths.value = {
+		...columnWidths.value,
+		[columnKey]: width,
+	}
+}
+
+function freezeSiblingColumnWidths(tableEl, activeKey, activeWidth) {
+	const next = { ...columnWidths.value }
+	tableEl?.querySelectorAll('thead th[data-column-key]').forEach((th) => {
+		const key = th.dataset.columnKey
+		if (!key || key === activeKey) {
+			return
+		}
+		if (typeof next[key] === 'number') {
+			return
+		}
+		next[key] = Math.max(MIN_COLUMN_WIDTH, Math.round(th.getBoundingClientRect().width))
+	})
+	next[activeKey] = activeWidth
+	setColumnWidths(next)
+}
+
+function endColumnResize() {
+	if (!resizeSession) {
+		return
+	}
+
+	const { moveListener, upListener, previousUserSelect, previousCursor } = resizeSession
+	window.removeEventListener('pointermove', moveListener)
+	window.removeEventListener('pointerup', upListener)
+	window.removeEventListener('pointercancel', upListener)
+	document.body.style.userSelect = previousUserSelect
+	document.body.style.cursor = previousCursor
+	activeResizeKey.value = null
+	resizeSession = null
+}
+
+function onResizePointerDown(header, event) {
+	if (!isHeaderResizable(header) || event.button !== 0) {
+		return
+	}
+
+	const handle = event.currentTarget
+	const headerCell = handle?.closest('th')
+	if (!headerCell) {
+		return
+	}
+
+	event.preventDefault()
+	endColumnResize()
+
+	const startX = event.clientX
+	const startWidth = Math.max(MIN_COLUMN_WIDTH, Math.round(headerCell.getBoundingClientRect().width))
+	activeResizeKey.value = header.key
+	freezeSiblingColumnWidths(
+		tableElementRef.value ?? headerCell.closest('table'),
+		header.key,
+		startWidth,
+	)
+
+	const previousUserSelect = document.body.style.userSelect
+	const previousCursor = document.body.style.cursor
+	document.body.style.userSelect = 'none'
+	document.body.style.cursor = 'col-resize'
+
+	const moveListener = (moveEvent) => {
+		const nextWidth = Math.max(
+			MIN_COLUMN_WIDTH,
+			Math.round(startWidth + (moveEvent.clientX - startX)),
+		)
+		setColumnWidth(header.key, nextWidth)
+	}
+
+	const upListener = () => {
+		endColumnResize()
+	}
+
+	resizeSession = {
+		moveListener,
+		upListener,
+		previousUserSelect,
+		previousCursor,
+	}
+
+	window.addEventListener('pointermove', moveListener)
+	window.addEventListener('pointerup', upListener)
+	window.addEventListener('pointercancel', upListener)
+
+	if (typeof handle.setPointerCapture === 'function') {
+		try {
+			handle.setPointerCapture(event.pointerId)
+		} catch {
+			// Ignore capture failures (e.g. unsupported pointer type in tests).
+		}
+	}
+}
+
+function onResizeDoubleClick(header, event) {
+	if (!isHeaderResizable(header)) {
+		return
+	}
+
+	event.preventDefault()
+	endColumnResize()
+	setColumnWidth(header.key, null)
+}
+
+const viewSettingsHandlers = computed(() =>
+	getViewSettingsHandlers(props.viewSettings, props.layoutPresets))
+
+const isCallbackViewControl = computed(
+	() => props.viewControlMode === VIEW_CONTROL_CALLBACK,
+)
+
+const layoutPresetsAvailable = computed(() =>
+	isViewSettingsControlEnabled(
+		props.viewControlMode,
+		props.tableId,
+		viewSettingsHandlers.value,
+	))
 
 const activeFilters = computed(() => {
 	if (!props.filterable) {
@@ -629,6 +960,53 @@ function bodyColumnColspan(index) {
 	return isLastColumnWithOptions(index) ? 2 : null
 }
 
+const bodyGroupColspan = computed(() => {
+	let colspan = visibleHeaders.value.length
+	if (showColumnOptionsButton.value) {
+		colspan += 1
+	}
+	return colspan
+})
+
+function bodyItemKey(item, index) {
+	if (item.kind === 'group') {
+		return `group-${item.groupId}`
+	}
+	return resolveRowKey(item.row, item.sourceIndex ?? index)
+}
+
+function isHeaderGrouped(header) {
+	return Boolean(activeGroupBy.value && header?.key === activeGroupBy.value)
+}
+
+function toggleGroupCollapsed(groupId) {
+	const next = new Set(collapsedGroupIdSet.value)
+	if (next.has(groupId)) {
+		next.delete(groupId)
+	} else {
+		next.add(groupId)
+	}
+	collapsedGroupIds.value = [...next]
+}
+
+function setGroupBy(nextGroupBy) {
+	const header = props.headers.find((item) => item.key === nextGroupBy)
+	const normalized = isHeaderGroupable(header, props.groupable) ? nextGroupBy : null
+
+	if (props.groupBy === undefined) {
+		internalGroupBy.value = normalized
+	}
+
+	collapsedGroupIds.value = []
+	page.value = 1
+	emit('update:groupBy', normalized)
+	emit('group-by-change', normalized)
+	if (isRemote.value) {
+		scheduleFetchRows()
+	}
+	emitQueryChange()
+}
+
 function isHeaderHidden(header) {
 	if (header.hidden) {
 		return true
@@ -641,6 +1019,17 @@ function isHeaderHidden(header) {
 
 const visibleHeaders = computed(() => orderedHeaders.value.filter((header) => !isHeaderHidden(header)))
 
+const ariaColCount = computed(() => {
+	let count = visibleHeaders.value.length
+	if (props.selectable) {
+		count += 1
+	}
+	if (showColumnOptionsButton.value) {
+		count += 1
+	}
+	return count > 0 ? count : undefined
+})
+
 const visibleColumnKeys = computed(() =>
 	orderedHeaders.value
 		.filter((header) => !isHeaderHidden(header))
@@ -750,16 +1139,45 @@ const sortedItems = computed(() => {
 	)
 })
 
-const displayRows = computed(() => {
-	if (isRemote.value || !props.showPagination) {
-		return sortedItems.value
+const activeGroupBy = computed(() => {
+	if (!props.groupable) {
+		return null
 	}
+	if (props.groupBy !== undefined) {
+		return props.groupBy || null
+	}
+	return internalGroupBy.value
+})
+
+const collapsedGroupIdSet = computed(() => new Set(collapsedGroupIds.value))
 
-	const start = (page.value - 1) * pageSize.value
-	return sortedItems.value.slice(start, start + pageSize.value)
+const displayBodyItems = computed(() => {
+	const paginate = !isRemote.value && props.showPagination
+	const items = buildDisplayBodyItems(sortedItems.value, {
+		groupBy: activeGroupBy.value,
+		page: page.value,
+		pageSize: pageSize.value,
+		paginate,
+		collapsedGroupIds: collapsedGroupIdSet.value,
+	})
+	let displayIndex = 0
+	return items.map((item) => {
+		if (item.kind !== 'row') {
+			return item
+		}
+		const indexed = { ...item, displayIndex }
+		displayIndex += 1
+		return indexed
+	})
 })
 
-const hasRows = computed(() => displayRows.value.length > 0)
+const displayRows = computed(() =>
+	displayBodyItems.value
+		.filter((item) => item.kind === 'row')
+		.map((item) => item.row),
+)
+
+const hasRows = computed(() => displayBodyItems.value.length > 0)
 
 const hasActiveFilters = computed(() =>
 	isFilterQueryActive(activeFilterQuery.value, props.headers, props.data),
@@ -813,6 +1231,7 @@ const queryParams = computed(() => {
 		pageSize: pageSize.value,
 		sortBy: sortBy.value,
 		sortDir: sortDir.value,
+		groupBy: activeGroupBy.value,
 		filterQuery: activeFilterQuery.value,
 	}
 
@@ -846,12 +1265,32 @@ function isHeaderFiltered(header) {
 	return isColumnFiltered(activeFilters.value?.[header.key], header, props.data)
 }
 
+function headerAriaSort(header) {
+	if (!header?.sortable) {
+		return undefined
+	}
+	if (sortBy.value !== header.key) {
+		return 'none'
+	}
+	return sortDir.value === 'desc' ? 'descending' : 'ascending'
+}
+
+function headerFilterExpanded(header) {
+	if (!isHeaderFilterable(header)) {
+		return undefined
+	}
+	return filterPopoverOpen.value && activeFilterHeader.value?.key === header.key
+		? 'true'
+		: 'false'
+}
+
 function headerClasses(header) {
 	const priority = resolvedColumnPriority(header)
 	return {
 		sortable: header.sortable,
 		filterable: isHeaderFilterable(header),
 		filtered: isHeaderFiltered(header),
+		grouped: isHeaderGrouped(header),
 		'menu-open': filterPopoverOpen.value && activeFilterHeader.value?.key === header.key,
 		[colPriorityClass(priority)]: isValidColPriority(priority),
 	}
@@ -1110,6 +1549,14 @@ function moveActiveCell(rowDelta, columnDelta, options = {}) {
 	return activateCellAt(rowIndex, columnIndex, options)
 }
 
+function isInteractiveCellTarget(target) {
+	return Boolean(
+		target?.closest?.(
+			'a, button, input, select, textarea, [contenteditable="true"], [data-row-click-ignore]',
+		),
+	)
+}
+
 function onCellClick(row, header, rowIndex, event) {
 	const context = cellContext(row, header, rowIndex)
 	const nextActiveCell = {
@@ -1117,6 +1564,9 @@ function onCellClick(row, header, rowIndex, event) {
 		columnKey: header.key,
 	}
 	setActiveCell(nextActiveCell)
+	if (!isInteractiveCellTarget(event.target)) {
+		scheduleCellFocus(nextActiveCell, { focus: true })
+	}
 	emit('cell-click', {
 		...context,
 		...nextActiveCell,
@@ -1124,6 +1574,39 @@ function onCellClick(row, header, rowIndex, event) {
 	})
 }
 
+function onCellKeydown(row, header, rowIndex, event) {
+	if (!activeCell.value || !isActiveCell(row, header, rowIndex)) {
+		return
+	}
+
+	if (isInteractiveCellTarget(event.target) && event.target !== event.currentTarget) {
+		return
+	}
+
+	let rowDelta = 0
+	let columnDelta = 0
+
+	switch (event.key) {
+	case 'ArrowUp':
+		rowDelta = -1
+		break
+	case 'ArrowDown':
+		rowDelta = 1
+		break
+	case 'ArrowLeft':
+		columnDelta = -1
+		break
+	case 'ArrowRight':
+		columnDelta = 1
+		break
+	default:
+		return
+	}
+
+	event.preventDefault()
+	moveActiveCell(rowDelta, columnDelta, { focus: true })
+}
+
 const activeSelectedKeys = computed(() => (
 	props.selectedKeys !== undefined ? props.selectedKeys : internalSelectedKeys.value
 ))
@@ -1402,7 +1885,7 @@ function closeRowContextMenu() {
 	rowContextMenuAnchor.value = null
 }
 
-function onRowContextMenu(row, displayIndex, event) {
+function onRowContextMenu(row, sourceIndex, event) {
 	if (!hasRowContextMenu.value) {
 		return
 	}
@@ -1413,8 +1896,8 @@ function onRowContextMenu(row, displayIndex, event) {
 	event.preventDefault()
 	event.stopPropagation()
 
-	const key = resolveRowKey(row, displayIndex)
-	const index = filteredRowIndex(displayIndex)
+	const key = resolveRowKey(row, sourceIndex)
+	const index = filteredRowIndex(sourceIndex)
 	let targetKeys
 
 	if (props.selectable && selectedKeySet.value.has(key) && activeSelectedKeys.value.length > 0) {
@@ -1549,6 +2032,17 @@ function onFilterCancel() {
 	activeFilterValue.value = []
 }
 
+const canGroupByActiveFilterColumn = computed(() => {
+	if (!props.groupable || !activeFilterHeader.value) {
+		return false
+	}
+	return isHeaderGroupable(activeFilterHeader.value, props.groupable)
+})
+
+const isActiveFilterHeaderGrouped = computed(() =>
+	Boolean(activeFilterHeader.value?.key && activeFilterHeader.value.key === activeGroupBy.value),
+)
+
 const canHideActiveFilterColumn = computed(() => {
 	if (!showColumnOptionsButton.value || !activeFilterHeader.value) {
 		return false
@@ -1563,6 +2057,12 @@ const canHideActiveFilterColumn = computed(() => {
 	return configurableHeaders.value.some((item) => item.key === header.key)
 })
 
+function onFilterGroupBy(columnKey) {
+	setGroupBy(columnKey || null)
+	filterPopoverOpen.value = false
+	onFilterCancel()
+}
+
 function onFilterHideColumn() {
 	const header = activeFilterHeader.value
 	if (!header?.key || !canHideActiveFilterColumn.value) {
@@ -1648,10 +2148,13 @@ function openColumnOptions() {
 	void refreshSavedPresets()
 }
 
-function onColumnOptionsApply({ order, visibleKeys, priorities }) {
+function onColumnOptionsApply({ order, visibleKeys, priorities, groupBy }) {
 	setColumnOrder(order)
 	setColumnVisibility(visibleKeys)
 	setColumnPriorities(priorities)
+	if (groupBy !== undefined && groupBy !== activeGroupBy.value) {
+		setGroupBy(groupBy)
+	}
 	updateActiveLayoutLabel()
 }
 
@@ -1660,15 +2163,16 @@ function onColumnOptionsCancel() {
 }
 
 async function refreshSavedPresets() {
-	if (isRemote.value) {
-		if (!props.layoutPresets || typeof props.layoutPresets.list !== 'function') {
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.list !== 'function') {
 			savedPresets.value = []
 			defaultPresetId.value = null
 			return
 		}
 
 		try {
-			const result = await props.layoutPresets.list()
+			const result = await handlers.list()
 			savedPresets.value = Array.isArray(result?.presets) ? result.presets : []
 			defaultPresetId.value = result?.defaultPresetId ?? null
 		} catch {
@@ -1706,6 +2210,7 @@ function getCurrentLayoutState() {
 		filters: cloneFilters(activeFilters.value),
 		sortBy: sortBy.value,
 		sortDir: sortDir.value,
+		groupBy: activeGroupBy.value,
 		pageSize: pageSize.value,
 	}
 }
@@ -1745,6 +2250,12 @@ function applyPresetState(state) {
 		sortDir.value = 'asc'
 	}
 
+	if (sanitized.groupBy) {
+		setGroupBy(sanitized.groupBy)
+	} else {
+		setGroupBy(null)
+	}
+
 	if (sanitized.pageSize) {
 		pageSize.value = sanitized.pageSize
 	}
@@ -1760,13 +2271,14 @@ function applyPresetState(state) {
 async function onSavePreset({ name, setAsDefault }) {
 	const state = getCurrentLayoutState()
 
-	if (isRemote.value) {
-		if (!props.layoutPresets || typeof props.layoutPresets.save !== 'function') {
-			return { ok: false, error: 'Remote layout save is unavailable.' }
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.save !== 'function') {
+			return { ok: false, error: 'View save callback is unavailable.' }
 		}
 
 		try {
-			const result = await props.layoutPresets.save({ name, state, setAsDefault })
+			const result = await handlers.save({ name, state, setAsDefault })
 			if (result?.ok) {
 				await refreshSavedPresets()
 				if (result.preset?.id) {
@@ -1799,14 +2311,50 @@ async function onSavePreset({ name, setAsDefault }) {
 	return result
 }
 
+async function onOverwritePreset({ presetId }) {
+	const state = getCurrentLayoutState()
+
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.overwrite !== 'function') {
+			return { ok: false, error: 'View overwrite callback is unavailable.' }
+		}
+
+		try {
+			const result = await handlers.overwrite({ presetId, state })
+			if (result?.ok) {
+				await refreshSavedPresets()
+				activeLayoutPresetId.value = presetId
+				updateActiveLayoutLabel()
+			}
+			return result ?? { ok: false, error: 'Unable to overwrite layout.' }
+		} catch {
+			return { ok: false, error: 'Unable to overwrite layout.' }
+		}
+	}
+
+	if (!props.tableId) {
+		return { ok: false, error: 'Table identity is required.' }
+	}
+
+	const result = overwritePreset(props.tableId, presetId, { state })
+	if (result.ok) {
+		refreshSavedPresets()
+		activeLayoutPresetId.value = presetId
+		updateActiveLayoutLabel()
+	}
+	return result
+}
+
 async function onLoadPreset(presetId) {
-	if (isRemote.value) {
-		if (!props.layoutPresets || typeof props.layoutPresets.load !== 'function') {
-			return { ok: false, error: 'Remote layout load is unavailable.' }
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.load !== 'function') {
+			return { ok: false, error: 'View load callback is unavailable.' }
 		}
 
 		try {
-			const result = await props.layoutPresets.load(presetId)
+			const result = await handlers.load(presetId)
 			if (!result?.ok || !result.preset?.state) {
 				return result ?? { ok: false, error: 'Preset not found.' }
 			}
@@ -1836,13 +2384,14 @@ async function onLoadPreset(presetId) {
 }
 
 async function onDeletePreset(presetId) {
-	if (isRemote.value) {
-		if (!props.layoutPresets || typeof props.layoutPresets.delete !== 'function') {
-			return { ok: false, error: 'Remote layout delete is unavailable.' }
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.delete !== 'function') {
+			return { ok: false, error: 'View delete callback is unavailable.' }
 		}
 
 		try {
-			const result = await props.layoutPresets.delete(presetId)
+			const result = await handlers.delete(presetId)
 			if (result?.ok) {
 				await refreshSavedPresets()
 				if (activeLayoutPresetId.value === presetId) {
@@ -1872,13 +2421,14 @@ async function onDeletePreset(presetId) {
 }
 
 async function onSetDefaultPreset(presetId) {
-	if (isRemote.value) {
-		if (!props.layoutPresets || typeof props.layoutPresets.setDefault !== 'function') {
+	if (isCallbackViewControl.value) {
+		const handlers = viewSettingsHandlers.value
+		if (!handlers || typeof handlers.setDefault !== 'function') {
 			return { ok: false, error: 'Unable to update default layout.' }
 		}
 
 		try {
-			const result = await props.layoutPresets.setDefault(presetId)
+			const result = await handlers.setDefault(presetId)
 			if (result?.ok) {
 				await refreshSavedPresets()
 			}
@@ -1921,6 +2471,7 @@ function getDeveloperDefaultLayoutState() {
 		filters: {},
 		sortBy: null,
 		sortDir: 'asc',
+		groupBy: null,
 		pageSize: DEFAULT_PAGE_SIZE,
 	}
 }
@@ -1980,6 +2531,7 @@ function loadDeveloperDefaults() {
 	setFilters({})
 	sortBy.value = null
 	sortDir.value = 'asc'
+	setGroupBy(null)
 	setColumnOrder(getDeveloperDefaultColumnOrder())
 	setColumnPriorities({})
 
@@ -2074,6 +2626,17 @@ watch(
 	},
 )
 
+watch(
+	activeGroupBy,
+	() => {
+		page.value = 1
+		if (isRemote.value) {
+			scheduleFetchRows()
+		}
+		emitQueryChange()
+	},
+)
+
 watch(
 	() => [sortBy.value, sortDir.value],
 	() => {
@@ -2184,6 +2747,24 @@ watch(
 	{ deep: true },
 )
 
+watch(
+	() => props.groupBy,
+	(nextGroupBy) => {
+		if (nextGroupBy !== undefined) {
+			collapsedGroupIds.value = []
+		}
+	},
+)
+
+watch(
+	() => props.groupable,
+	(enabled) => {
+		if (!enabled) {
+			setGroupBy(null)
+		}
+	},
+)
+
 watch(
 	() => props.columnPriorities,
 	(nextPriorities) => {
@@ -2204,7 +2785,7 @@ watch(
 )
 
 watch(
-	() => [props.tableId, props.layoutPresets],
+	() => [props.viewControlMode, props.tableId, viewSettingsHandlers.value],
 	() => {
 		void refreshSavedPresets()
 		updateActiveLayoutLabel()
@@ -2221,6 +2802,7 @@ watch(
 		activeFilters,
 		sortBy,
 		sortDir,
+		activeGroupBy,
 		pageSize,
 		() => props.headers,
 		savedPresets,
@@ -2247,17 +2829,18 @@ watch(
 
 onMounted(async () => {
 	if (props.loadSavedLayout) {
-		if (isRemote.value && props.layoutPresets && typeof props.layoutPresets.getDefault === 'function') {
+		const handlers = viewSettingsHandlers.value
+		if (isCallbackViewControl.value && handlers && typeof handlers.getDefault === 'function') {
 			try {
-				const result = await props.layoutPresets.getDefault()
+				const result = await handlers.getDefault()
 				if (result?.preset?.state) {
 					applyPresetState(result.preset.state)
 					activeLayoutPresetId.value = result.preset.id
 				}
 			} catch {
-				// Ignore default layout load failures in remote mode.
+				// Ignore default layout load failures in callback mode.
 			}
-		} else if (!isRemote.value && props.tableId) {
+		} else if (!isCallbackViewControl.value && props.tableId) {
 			const preset = getDefaultPreset(props.tableId)
 			if (preset?.state) {
 				applyPresetState(preset.state)
@@ -2275,6 +2858,7 @@ onMounted(async () => {
 })
 
 onBeforeUnmount(() => {
+	endColumnResize()
 	if (fetchAbortController.value) {
 		fetchAbortController.value.abort()
 	}
@@ -2296,11 +2880,85 @@ defineExpose({
 </script>
 
 <style scoped>
+table.has-column-widths {
+	table-layout: fixed;
+	width: 100%;
+}
+
+/* Force fixed-layout cells to respect column widths so overflow clipping/ellipsis work. */
+table.has-column-widths th,
+table.has-column-widths td {
+	max-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+table.has-column-widths th.table-select-col,
+table.has-column-widths td.table-select-col,
+table.has-column-widths th.table-column-options-header {
+	max-width: none;
+}
+
+table.is-column-resizing {
+	cursor: col-resize;
+}
+
+table.is-column-resizing thead th.sortable:hover {
+	cursor: col-resize;
+}
+
+col.table-select-col-width,
+col.table-column-options-col-width {
+	width: 2.5rem;
+}
+
+table thead th {
+	position: relative;
+}
+
 table thead th.sortable:hover {
 	cursor: pointer;
 	color: var(--table-header-active-fg);
 }
 
+.column-resize-handle {
+	position: absolute;
+	top: 0;
+	right: -0.2rem;
+	z-index: 2;
+	width: 0.55rem;
+	height: 100%;
+	padding: 0;
+	border: 0;
+	background: transparent;
+	cursor: col-resize;
+	touch-action: none;
+	user-select: none;
+	opacity: 0;
+}
+
+.column-resize-handle::after {
+	content: '';
+	position: absolute;
+	top: 20%;
+	bottom: 20%;
+	left: 50%;
+	width: 2px;
+	transform: translateX(-50%);
+	border-radius: 1px;
+	background-color: var(--border-color, currentColor);
+	opacity: 0.85;
+}
+
+table thead th:hover .column-resize-handle,
+table thead th.is-resizing .column-resize-handle,
+.column-resize-handle:hover,
+.column-resize-handle:focus-visible,
+.column-resize-handle.is-active {
+	opacity: 1;
+}
+
 table thead th.filterable {
 	cursor: context-menu;
 }
@@ -2330,9 +2988,57 @@ table.loading tbody {
 }
 
 .sort-indicator {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
 	width: 1.5em;
-	display: inline-block;
-	text-align: center;
+	vertical-align: middle;
+}
+
+.group-indicator {
+	display: inline-flex;
+	vertical-align: middle;
+	margin-right: 0.25rem;
+	opacity: 0.85;
+}
+
+table thead th.grouped {
+	color: var(--table-header-active-fg);
+}
+
+tbody tr.table-group-row > td.table-group-cell {
+	background-color: var(--table-header-active-bg);
+	color: var(--table-header-fg);
+	font-weight: 600;
+	padding-top: 0.65rem;
+	padding-bottom: 0.65rem;
+}
+
+.table-group-toggle {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	min-width: 1.5rem;
+	margin-right: 0.35rem;
+	padding: 0.1rem 0.35rem;
+	vertical-align: middle;
+}
+
+.table-group-chevron {
+	flex-shrink: 0;
+	transition: transform 0.15s ease;
+}
+
+.table-group-row:not(.table-group-row-collapsed) .table-group-chevron {
+	transform: rotate(180deg);
+}
+
+.table-group-label {
+	margin-right: 0.35rem;
+}
+
+.table-group-count {
+	font-weight: normal;
 }
 
 td:first-child,