picocrank 1.33.0 → 1.34.0

package/vue/components/Table.vue

@@ -41,11 +41,38 @@
 
 						<span v-if="filterable && isHeaderFiltered(header)" class="filter-indicator" title="Filtered" aria-hidden="true">⧩</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">
-							<span v-if="sortBy === header.key">
-								<span v-if="sortDir === 'asc'">▲</span>
-								<span v-else-if="sortDir === 'desc'">▼</span>
-							</span>
+							<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>
 					</th>
 					<th
@@ -74,77 +101,112 @@
 				</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)"
+							:tabindex="isActiveCell(item.row, header, item.displayIndex) ? 0 : -1"
+							@click="onCellClick(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 +236,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 +260,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 +285,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,15 +316,26 @@ 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
 
@@ -343,6 +428,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 +455,7 @@ const props = defineProps({
 		type: [String, Function],
 		default: 'id',
 	},
+	/** @deprecated Use `viewSettings` with `viewControlMode="callbackControlled"`. */
 	layoutPresets: {
 		type: Object,
 		default: null,
@@ -406,6 +507,14 @@ const props = defineProps({
 		type: [Array, Function],
 		default: null,
 	},
+	groupable: {
+		type: Boolean,
+		default: true,
+	},
+	groupBy: {
+		type: String,
+		default: undefined,
+	},
 })
 
 const emit = defineEmits([
@@ -432,6 +541,8 @@ const emit = defineEmits([
 	'column-priorities-change',
 	'update:layoutLabel',
 	'layout-label-change',
+	'update:groupBy',
+	'group-by-change',
 ])
 
 const attrs = useAttrs()
@@ -561,15 +672,24 @@ const internalColumnPriorities = ref({})
 const savedPresets = ref([])
 const defaultPresetId = ref(null)
 const activeLayoutPresetId = ref(null)
+const internalGroupBy = ref(null)
+const collapsedGroupIds = ref([])
 
 const isRemote = computed(() => typeof props.fetchRows === 'function')
 
-const layoutPresetsAvailable = computed(() => {
-	if (isRemote.value) {
-		return props.layoutPresets != null
-	}
-	return Boolean(props.tableId)
-})
+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 +749,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
@@ -750,16 +917,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 start = (page.value - 1) * pageSize.value
-	return sortedItems.value.slice(start, start + pageSize.value)
+const collapsedGroupIdSet = computed(() => new Set(collapsedGroupIds.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 +1009,7 @@ const queryParams = computed(() => {
 		pageSize: pageSize.value,
 		sortBy: sortBy.value,
 		sortDir: sortDir.value,
+		groupBy: activeGroupBy.value,
 		filterQuery: activeFilterQuery.value,
 	}
 
@@ -852,6 +1049,7 @@ function headerClasses(header) {
 		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),
 	}
@@ -1402,7 +1600,7 @@ function closeRowContextMenu() {
 	rowContextMenuAnchor.value = null
 }
 
-function onRowContextMenu(row, displayIndex, event) {
+function onRowContextMenu(row, sourceIndex, event) {
 	if (!hasRowContextMenu.value) {
 		return
 	}
@@ -1413,8 +1611,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 +1747,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 +1772,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 +1863,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 +1878,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 +1925,7 @@ function getCurrentLayoutState() {
 		filters: cloneFilters(activeFilters.value),
 		sortBy: sortBy.value,
 		sortDir: sortDir.value,
+		groupBy: activeGroupBy.value,
 		pageSize: pageSize.value,
 	}
 }
@@ -1745,6 +1965,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 +1986,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 +2026,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 +2099,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 +2136,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 +2186,7 @@ function getDeveloperDefaultLayoutState() {
 		filters: {},
 		sortBy: null,
 		sortDir: 'asc',
+		groupBy: null,
 		pageSize: DEFAULT_PAGE_SIZE,
 	}
 }
@@ -1980,6 +2246,7 @@ function loadDeveloperDefaults() {
 	setFilters({})
 	sortBy.value = null
 	sortDir.value = 'asc'
+	setGroupBy(null)
 	setColumnOrder(getDeveloperDefaultColumnOrder())
 	setColumnPriorities({})
 
@@ -2074,6 +2341,17 @@ watch(
 	},
 )
 
+watch(
+	activeGroupBy,
+	() => {
+		page.value = 1
+		if (isRemote.value) {
+			scheduleFetchRows()
+		}
+		emitQueryChange()
+	},
+)
+
 watch(
 	() => [sortBy.value, sortDir.value],
 	() => {
@@ -2184,6 +2462,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 +2500,7 @@ watch(
 )
 
 watch(
-	() => [props.tableId, props.layoutPresets],
+	() => [props.viewControlMode, props.tableId, viewSettingsHandlers.value],
 	() => {
 		void refreshSavedPresets()
 		updateActiveLayoutLabel()
@@ -2221,6 +2517,7 @@ watch(
 		activeFilters,
 		sortBy,
 		sortDir,
+		activeGroupBy,
 		pageSize,
 		() => props.headers,
 		savedPresets,
@@ -2247,17 +2544,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)
@@ -2330,9 +2628,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,