picocrank 1.32.0 → 1.33.0

package/docs/table.md

@@ -0,0 +1,99 @@
+# Table
+
+`Table` supports local data and remote `fetchRows` data. Existing usages remain
+uncontrolled; pass any query-state prop to control that field independently.
+
+## Query state
+
+```vue
+<Table
+  v-model:sort-by="sortBy"
+  v-model:sort-dir="sortDir"
+  v-model:page="page"
+  v-model:page-size="pageSize"
+/>
+```
+
+`sortBy`, `sortDir`, `page`, and `pageSize` default to internal state when
+omitted. Controlled values may be changed after mount. User actions emit the
+corresponding `update:*` event. Sorting resets the page by default; set
+`:reset-page-on-sort="false"` to preserve the current page. Page-size, data, and
+filter changes continue to reset to page 1.
+
+A sortable header can provide a value comparator:
+
+```js
+{
+  key: 'version',
+  sortable: true,
+  comparator: (left, right, leftRow, rightRow) =>
+    left.localeCompare(right, undefined, { numeric: true }),
+}
+```
+
+The comparator defines ascending order and receives non-null cell values plus
+their rows. `Table` reverses its result for descending order and keeps null
+values last. `sortRows(rows, sortBy, sortDir, comparator)` accepts the same
+optional comparator.
+
+## Cells and display hooks
+
+Named `#cell-{key}` slots and the generic `#cell` slot receive:
+
+```ts
+{ row, value, header, rowIndex, sourceIndex }
+```
+
+`rowIndex` is the index on the displayed page. For local data, `sourceIndex` is
+the index in `data`; for remote data it is the index in the current response.
+
+The `rowClass` and `rowStyle` callbacks receive
+`{ row, rowIndex, sourceIndex }`. `cellClass`, `cellStyle`, and `cellAttrs`
+receive that context plus `{ value, header }`. Return Vue-compatible class or
+style values. `cellAttrs` is intended for attributes such as `title`, `aria-*`,
+and `data-*`; use the dedicated class/style callbacks for those fields.
+Header `class` continues to apply to both its header and body cells.
+
+## Selection and active cells
+
+`selectionClickMode` controls selectable-row clicks:
+
+- `row` (default): row clicks toggle selection; Ctrl/Cmd also toggles and Shift
+  selects a range on the displayed page.
+- `checkbox`: only checkboxes change selection; row clicks emit `row-click`.
+- `modifier`: Ctrl/Cmd toggles, Shift selects a displayed-page range, and an
+  unmodified click emits `row-click`.
+- `extended`: unmodified clicks replace the selection, Ctrl/Cmd toggles, and
+  Shift adds a range on the displayed page. This matches desktop-style
+  selection while leaving the default behavior unchanged.
+
+The additive `row-click` payload is `{ row, index, event }`, where `event` is
+the native click event.
+
+`activeCell` is an optional controlled `{ rowKey, columnKey }` value:
+
+```vue
+<Table
+  v-model:active-cell="activeCell"
+  @cell-click="onCellClick"
+/>
+```
+
+Clicking a data cell emits `cell-click` with the enriched cell context and adds
+the visibly outlined `table-active-cell` class. The component ref exposes:
+
+- `clearFilters()`
+- `focusActiveCell(options?)` (returns whether a displayed active cell was focused)
+- `clearActiveCell()`
+- `activateCellAt(rowIndex, columnIndex, options?)`
+- `moveActiveCell(rowDelta, columnDelta, options?)`
+- `getActiveCellContext()`
+- the existing `loadDeveloperDefaults()` and `layoutLabel`
+
+Cell indices use `displayRows` and `visibleHeaders` and are clamped to the
+displayed grid. Pass `{ wrapColumns: true }` to `moveActiveCell` to move from
+the last column of one row to the first column of the next (or in reverse),
+which is suitable for Tab/Shift+Tab. Pass `{ focus: true, focusOptions? }` to
+activation or movement methods to focus the destination after Vue renders.
+`getActiveCellContext()` returns the cell slot context plus `rowKey`,
+`columnKey`, and `columnIndex`, or `null` when the active cell is not displayed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picocrank",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "type": "module",
   "description": "A set of zero dependency Vue components built on the Femtocrank global CSS theme.",
   "main": "vite.config.js",

package/vue/components/Table.spec.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { mount } from '@vue/test-utils'
-import { nextTick } from 'vue'
+import { h, nextTick } from 'vue'
 import Table from './Table.vue'
 
 const globalStubs = {
@@ -37,6 +37,7 @@ function mountTable(overrides = {}) {
 		global: {
 			stubs: globalStubs,
 		},
+		slots: overrides.slots,
 	})
 }
 
@@ -144,6 +145,467 @@ describe('Table multi-select', () => {
 
 		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual([])
 	})
+
+	it('supports checkbox-only selection while preserving row clicks', async () => {
+		const onRowClick = vi.fn()
+		const wrapper = mountTable({
+			props: {
+				selectionClickMode: 'checkbox',
+				onRowClick,
+			},
+		})
+
+		await wrapper.findAll('tbody tr')[0].trigger('click', { ctrlKey: true })
+
+		expect(wrapper.emitted('update:selectedKeys')).toBeUndefined()
+		expect(wrapper.emitted('row-click')?.[0]?.[0].row.name).toBe('Ada')
+		expect(wrapper.emitted('row-click')?.[0]?.[0].index).toBe(0)
+		expect(wrapper.emitted('row-click')?.[0]?.[0].event).toBeInstanceOf(MouseEvent)
+		expect(wrapper.emitted('row-click')?.[0]?.[0].event.ctrlKey).toBe(true)
+		expect(onRowClick).toHaveBeenCalledTimes(1)
+
+		await wrapper.findAll('td.table-select-col input[type="checkbox"]')[0].setValue(true)
+
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Ada'])
+	})
+
+	it('supports modifier toggles and shift ranges on displayed rows', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectionClickMode: 'modifier',
+				onRowClick: () => {},
+			},
+		})
+		const tableRows = wrapper.findAll('tbody tr')
+
+		await tableRows[1].trigger('click')
+		expect(wrapper.emitted('row-click')).toHaveLength(1)
+		expect(wrapper.emitted('update:selectedKeys')).toBeUndefined()
+
+		await tableRows[0].trigger('click', { ctrlKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Ada'])
+
+		await tableRows[2].trigger('click', { shiftKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual([
+			'Ada',
+			'Grace',
+			'Katherine',
+		])
+
+		await tableRows[1].trigger('click', { metaKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual([
+			'Ada',
+			'Katherine',
+		])
+		expect(wrapper.emitted('row-click')).toHaveLength(1)
+	})
+
+	it('supports extended replace, modifier-toggle, and range semantics', async () => {
+		const extendedRows = [
+			...rows,
+			{ name: 'Margaret', city: 'Arlington' },
+		]
+		const wrapper = mountTable({
+			props: {
+				data: extendedRows,
+				showPagination: true,
+				pageSize: 3,
+				selectionClickMode: 'extended',
+			},
+		})
+		const tableRows = wrapper.findAll('tbody tr')
+
+		await tableRows[0].trigger('click')
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Ada'])
+
+		await tableRows[1].trigger('click')
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Grace'])
+
+		await tableRows[0].trigger('click', { ctrlKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Grace', 'Ada'])
+
+		await tableRows[1].trigger('click', { metaKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual(['Ada'])
+
+		await tableRows[2].trigger('click', { shiftKey: true })
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).toEqual([
+			'Ada',
+			'Grace',
+			'Katherine',
+		])
+		expect(wrapper.emitted('update:selectedKeys')?.at(-1)?.[0]).not.toContain('Margaret')
+	})
+})
+
+describe('Table controlled query state', () => {
+	it('keeps sort internal by default and emits sort updates', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+			},
+		})
+		const names = () => wrapper.findAll('tbody tr').map((row) => row.find('td').text())
+
+		await wrapper.find('thead th').trigger('click')
+		expect(names()).toEqual(['Ada', 'Grace', 'Katherine'])
+		expect(wrapper.emitted('update:sortBy')?.at(-1)?.[0]).toBe('name')
+
+		await wrapper.find('thead th').trigger('click')
+		expect(names()).toEqual(['Katherine', 'Grace', 'Ada'])
+		expect(wrapper.emitted('update:sortDir')?.at(-1)?.[0]).toBe('desc')
+	})
+
+	it('accepts controlled sort changes after mount', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+			},
+		})
+		const names = () => wrapper.findAll('tbody tr').map((row) => row.find('td').text())
+
+		await wrapper.setProps({ sortBy: 'name', sortDir: 'desc' })
+		expect(names()).toEqual(['Katherine', 'Grace', 'Ada'])
+
+		await wrapper.find('thead th').trigger('click')
+		expect(wrapper.emitted('update:sortDir')?.at(-1)?.[0]).toBe('asc')
+		expect(names()).toEqual(['Katherine', 'Grace', 'Ada'])
+
+		await wrapper.setProps({ sortDir: 'asc' })
+		expect(names()).toEqual(['Ada', 'Grace', 'Katherine'])
+	})
+
+	it('supports controlled page and pageSize updates', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+				showPagination: true,
+				page: 2,
+				pageSize: 1,
+			},
+		})
+		const visibleNames = () => wrapper.findAll('tbody tr').map((row) => row.find('td').text())
+		const pagination = wrapper.findComponent({ name: 'Pagination' })
+
+		expect(visibleNames()).toEqual(['Grace'])
+
+		pagination.vm.$emit('update:page', 3)
+		await nextTick()
+		expect(wrapper.emitted('update:page')?.at(-1)?.[0]).toBe(3)
+		expect(visibleNames()).toEqual(['Grace'])
+
+		await wrapper.setProps({ page: 3 })
+		expect(visibleNames()).toEqual(['Katherine'])
+
+		await wrapper.setProps({ page: 1 })
+		pagination.vm.$emit('update:pageSize', 2)
+		await nextTick()
+		expect(wrapper.emitted('update:pageSize')?.at(-1)?.[0]).toBe(2)
+		expect(visibleNames()).toEqual(['Ada'])
+
+		await wrapper.setProps({ pageSize: 2 })
+		expect(visibleNames()).toEqual(['Ada', 'Grace'])
+	})
+
+	it('preserves the page on sort when resetPageOnSort is false', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+				showPagination: true,
+				pageSize: 1,
+				resetPageOnSort: false,
+			},
+		})
+		const pagination = wrapper.findComponent({ name: 'Pagination' })
+
+		pagination.vm.$emit('update:page', 2)
+		await nextTick()
+		expect(wrapper.find('tbody td').text()).toBe('Grace')
+		const pageUpdateCount = wrapper.emitted('update:page')?.length
+
+		await wrapper.find('thead th').trigger('click')
+
+		expect(wrapper.find('tbody td').text()).toBe('Grace')
+		expect(wrapper.emitted('update:page')).toHaveLength(pageUpdateCount)
+	})
+
+	it('keeps the default sort reset and still resets for size, data, and filters', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+				showPagination: true,
+				pageSize: 1,
+				resetPageOnSort: false,
+			},
+		})
+		const pagination = wrapper.findComponent({ name: 'Pagination' })
+		const goToSecondPage = async () => {
+			pagination.vm.$emit('update:page', 2)
+			await nextTick()
+			expect(wrapper.find('tbody td').text()).toBe('Grace')
+		}
+
+		await goToSecondPage()
+		pagination.vm.$emit('update:pageSize', 2)
+		await wrapper.setProps({ pageSize: 2 })
+		expect(wrapper.emitted('update:page')?.at(-1)?.[0]).toBe(1)
+
+		pagination.vm.$emit('update:pageSize', 1)
+		await wrapper.setProps({ pageSize: 1 })
+		await goToSecondPage()
+		await wrapper.setProps({ data: [...rows] })
+		expect(wrapper.emitted('update:page')?.at(-1)?.[0]).toBe(1)
+
+		await goToSecondPage()
+		await wrapper.setProps({
+			filterable: true,
+			filters: {
+				city: [{ type: 'text', operator: 'contains', value: 'London' }],
+			},
+		})
+		expect(wrapper.emitted('update:page')?.at(-1)?.[0]).toBe(1)
+
+		const defaultWrapper = mountTable({
+			props: {
+				selectable: false,
+				showPagination: true,
+				pageSize: 1,
+			},
+		})
+		const defaultPagination = defaultWrapper.findComponent({ name: 'Pagination' })
+		defaultPagination.vm.$emit('update:page', 2)
+		await nextTick()
+
+		await defaultWrapper.find('thead th').trigger('click')
+
+		expect(defaultWrapper.emitted('update:page')?.at(-1)?.[0]).toBe(1)
+		expect(defaultWrapper.find('tbody td').text()).toBe('Ada')
+	})
+})
+
+describe('Table sorting and cell extension hooks', () => {
+	it('uses a header comparator for natural sorting', async () => {
+		const comparator = vi.fn((left, right) =>
+			left.localeCompare(right, undefined, { numeric: true }))
+		const versionRows = [
+			{ version: 'item10' },
+			{ version: 'item2' },
+			{ version: 'item1' },
+		]
+		const wrapper = mountTable({
+			props: {
+				headers: [
+					{ key: 'version', label: 'Version', sortable: true, comparator },
+				],
+				data: versionRows,
+				rowKey: 'version',
+				selectable: false,
+			},
+		})
+
+		await wrapper.find('thead th').trigger('click')
+
+		expect(wrapper.findAll('tbody td').map((cell) => cell.text())).toEqual([
+			'item1',
+			'item2',
+			'item10',
+		])
+		expect(comparator).toHaveBeenCalled()
+		expect(comparator.mock.calls[0][2]).toEqual(versionRows[1])
+	})
+
+	it('enriches cell slots and applies row and cell hooks', () => {
+		const rowClass = vi.fn(({ row }) => row.name === 'Katherine' && 'custom-row')
+		const rowStyle = vi.fn(({ rowIndex }) => ({ opacity: rowIndex === 0 ? '0.5' : '1' }))
+		const cellClass = vi.fn(({ header }) => header.key === 'city' && 'custom-cell')
+		const cellStyle = vi.fn(({ sourceIndex }) => ({ fontWeight: sourceIndex === 2 ? '700' : '400' }))
+		const cellAttrs = vi.fn(({ header, sourceIndex }) => (
+			header.key === 'city'
+				? { title: 'City value', 'data-source-index': sourceIndex }
+				: null
+		))
+		const wrapper = mountTable({
+			props: {
+				headers: [
+					{ key: 'name', label: 'Name', class: 'legacy-header-class' },
+					{ key: 'city', label: 'City' },
+				],
+				selectable: false,
+				sortBy: 'name',
+				sortDir: 'desc',
+				rowClass,
+				rowStyle,
+				cellClass,
+				cellStyle,
+				cellAttrs,
+			},
+			slots: {
+				'cell-name': ({ row, value, header, rowIndex, sourceIndex }) =>
+					h(
+						'span',
+						{ class: 'slot-payload' },
+						`${row.name}:${value}:${header.key}:${rowIndex}:${sourceIndex}`,
+					),
+			},
+		})
+
+		const firstRow = wrapper.findAll('tbody tr')[0]
+		const cells = firstRow.findAll('td')
+
+		expect(firstRow.classes()).toContain('custom-row')
+		expect(firstRow.attributes('style')).toContain('opacity: 0.5')
+		expect(cells[0].classes()).toContain('legacy-header-class')
+		expect(cells[0].find('.slot-payload').text()).toBe('Katherine:Katherine:name:0:2')
+		expect(cells[1].classes()).toContain('custom-cell')
+		expect(cells[1].attributes('style')).toContain('font-weight: 700')
+		expect(cells[1].attributes('title')).toBe('City value')
+		expect(cells[1].attributes('data-source-index')).toBe('2')
+		expect(rowClass).toHaveBeenCalledWith({
+			row: rows[2],
+			rowIndex: 0,
+			sourceIndex: 2,
+		})
+		expect(cellClass.mock.calls[1][0].header.key).toBe('city')
+	})
+})
+
+describe('Table active cell and exposed APIs', () => {
+	it('tracks clicked cells, emits cell details, focuses, and clears', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+			},
+		})
+		const firstCell = wrapper.find('tbody td')
+
+		await firstCell.trigger('click')
+
+		expect(firstCell.classes()).toContain('table-active-cell')
+		expect(wrapper.emitted('update:activeCell')?.at(-1)?.[0]).toEqual({
+			rowKey: 'Ada',
+			columnKey: 'name',
+		})
+		expect(wrapper.emitted('cell-click')?.at(-1)?.[0]).toMatchObject({
+			row: rows[0],
+			value: 'Ada',
+			header: headers[0],
+			rowIndex: 0,
+			sourceIndex: 0,
+			rowKey: 'Ada',
+			columnKey: 'name',
+		})
+
+		expect(wrapper.vm.focusActiveCell()).toBe(true)
+		expect(document.activeElement).toBe(firstCell.element)
+
+		wrapper.vm.clearActiveCell()
+		await nextTick()
+		expect(wrapper.emitted('update:activeCell')?.at(-1)?.[0]).toBeNull()
+		expect(wrapper.find('.table-active-cell').exists()).toBe(false)
+	})
+
+	it('activates and moves cells with clamping and column wrapping', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+			},
+		})
+
+		let context = wrapper.vm.activateCellAt(-10, 10)
+		await nextTick()
+		expect(context).toMatchObject({
+			rowKey: 'Ada',
+			columnKey: 'city',
+			rowIndex: 0,
+			columnIndex: 1,
+		})
+
+		context = wrapper.vm.moveActiveCell(0, 1, { wrapColumns: true })
+		await nextTick()
+		expect(context).toMatchObject({
+			rowKey: 'Grace',
+			columnKey: 'name',
+			rowIndex: 1,
+			columnIndex: 0,
+		})
+
+		context = wrapper.vm.moveActiveCell(0, -1, { wrapColumns: true })
+		await nextTick()
+		expect(context).toMatchObject({
+			rowKey: 'Ada',
+			columnKey: 'city',
+			rowIndex: 0,
+			columnIndex: 1,
+		})
+
+		context = wrapper.vm.moveActiveCell(-10, -10)
+		await nextTick()
+		expect(context).toMatchObject({
+			rowKey: 'Ada',
+			columnKey: 'name',
+			rowIndex: 0,
+			columnIndex: 0,
+		})
+
+		wrapper.vm.activateCellAt(99, 99)
+		context = wrapper.vm.moveActiveCell(10, 1, { wrapColumns: true })
+		await nextTick()
+		expect(context).toMatchObject({
+			rowKey: 'Katherine',
+			columnKey: 'city',
+			rowIndex: 2,
+			columnIndex: 1,
+		})
+
+		context = wrapper.vm.activateCellAt(1, 1, { focus: true })
+		await nextTick()
+		expect(wrapper.vm.getActiveCellContext()).toMatchObject(context)
+		expect(document.activeElement).toBe(wrapper.find('.table-active-cell').element)
+	})
+
+	it('supports a controlled active cell set after mount', async () => {
+		const wrapper = mountTable({
+			props: {
+				selectable: false,
+				activeCell: null,
+			},
+		})
+
+		await wrapper.setProps({
+			activeCell: { rowKey: 'Grace', columnKey: 'city' },
+		})
+
+		const active = wrapper.find('.table-active-cell')
+		expect(active.text()).toBe('New York')
+		expect(wrapper.vm.focusActiveCell()).toBe(true)
+		expect(document.activeElement).toBe(active.element)
+
+		wrapper.vm.activateCellAt(0, 0)
+		await nextTick()
+		expect(wrapper.emitted('update:activeCell')?.at(-1)?.[0]).toEqual({
+			rowKey: 'Ada',
+			columnKey: 'name',
+		})
+		expect(wrapper.find('.table-active-cell').text()).toBe('New York')
+
+		wrapper.vm.clearActiveCell()
+		expect(wrapper.emitted('update:activeCell')?.at(-1)?.[0]).toBeNull()
+		expect(wrapper.find('.table-active-cell').text()).toBe('New York')
+	})
+
+	it('exposes clearFilters', () => {
+		const wrapper = mountTable({
+			props: {
+				filterable: true,
+				filters: {
+					name: [{ type: 'text', operator: 'contains', value: 'Ada' }],
+				},
+			},
+		})
+
+		wrapper.vm.clearFilters()
+
+		expect(wrapper.emitted('update:filters')?.at(-1)?.[0]).toEqual({})
+	})
 })
 
 describe('Table row context menu', () => {

package/vue/components/Table.vue

@@ -77,11 +77,15 @@
 				<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),
-					}"
+					: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)"
 				>
@@ -96,31 +100,45 @@
 								type="checkbox"
 								:checked="isRowSelected(row, rowIndex)"
 								:aria-label="`Select row ${resolveRowKey(row, rowIndex)}`"
-								@change="toggleRowSelection(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] }}
@@ -197,7 +215,7 @@
 </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'
@@ -236,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,
@@ -250,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,
@@ -331,6 +367,35 @@ const props = defineProps({
 		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
@@ -349,8 +414,14 @@ 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',
@@ -366,9 +437,111 @@ const emit = defineEmits([
 const attrs = useAttrs()
 const slots = useSlots()
 
-const rowClickable = computed(() => Boolean(attrs.onRowClick) || props.selectable)
+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)
@@ -561,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(() => {
@@ -683,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)
@@ -702,6 +938,192 @@ 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
 ))
@@ -724,6 +1146,7 @@ function setSelectedKeys(nextKeys) {
 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
@@ -731,10 +1154,60 @@ function toggleRowSelection(row, index) {
 	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))
@@ -756,15 +1229,18 @@ function toggleSelectAllDisplayRows() {
 	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
 	}
 })
 
@@ -822,11 +1298,49 @@ function onRowClick(row, displayIndex, event) {
 	if (event.target.closest('a, button, input, select, textarea, [data-row-click-ignore]')) {
 		return
 	}
+
 	if (props.selectable) {
-		toggleRowSelection(row, displayIndex)
-		return
+		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) })
+
+	emit('row-click', {
+		row,
+		index: filteredRowIndex(displayIndex),
+		event,
+	})
 }
 
 const rowContextMenuOpen = ref(false)
@@ -1550,7 +2064,7 @@ function scheduleFetchRows() {
 }
 
 watch(
-	() => [pageSize.value, sortBy.value, sortDir.value],
+	pageSize,
 	() => {
 		page.value = 1
 		if (isRemote.value) {
@@ -1560,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()
@@ -1567,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,
 	() => {
@@ -1674,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) {
@@ -1721,6 +2286,12 @@ onBeforeUnmount(() => {
 defineExpose({
 	layoutLabel: activeLayoutLabel,
 	loadDeveloperDefaults,
+	clearFilters: clearAllFilters,
+	focusActiveCell,
+	clearActiveCell,
+	activateCellAt,
+	moveActiveCell,
+	getActiveCellContext,
 })
 </script>
 
@@ -1792,6 +2363,16 @@ 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);

package/vue/composables/tableFilters.js

@@ -387,7 +387,7 @@ export function cloneColumnFilterEntries(value, header = null, rows = []) {
 	return normalizeColumnFilterEntries(value, header, rows).map((entry) => ({ ...entry }))
 }
 
-export function sortRows(rows, sortBy, sortDir) {
+export function sortRows(rows, sortBy, sortDir, comparator = null) {
 	if (!sortBy) {
 		return [...rows]
 	}
@@ -399,6 +399,11 @@ export function sortRows(rows, sortBy, sortDir) {
 		if (av === bv) return 0
 		if (av === null || av === undefined) return 1
 		if (bv === null || bv === undefined) return -1
+		if (typeof comparator === 'function') {
+			const result = Number(comparator(av, bv, a, b))
+			if (!Number.isFinite(result) || result === 0) return 0
+			return sortDir === 'asc' ? result : -result
+		}
 		if (typeof av === 'string' && typeof bv === 'string') {
 			return sortDir === 'asc' ? av.localeCompare(bv) : bv.localeCompare(av)
 		}