From cba4550be4d21aa3156717628bb252c940ec0bc1 Mon Sep 17 00:00:00 2001
From: Truman Gao <106889354+tdgao@users.noreply.github.com>
Date: Fri, 8 May 2026 15:29:06 -0600
Subject: [PATCH] feat: table component updates (#6042)

* feat: implement table header slot, empty state, and virtualization

* refactor: pnpm prepr
---
 packages/ui/src/components/base/Table.vue     | 140 +++++++++++---
 packages/ui/src/stories/base/Table.stories.ts | 182 +++++++++++++++++-
 2 files changed, 291 insertions(+), 31 deletions(-)

diff --git a/packages/ui/src/components/base/Table.vue b/packages/ui/src/components/base/Table.vue
index d952a5337..048fa92f0 100644
--- a/packages/ui/src/components/base/Table.vue
+++ b/packages/ui/src/components/base/Table.vue
@@ -1,5 +1,11 @@
 <template>
 	<div class="overflow-hidden rounded-2xl border border-solid border-surface-5">
+		<div
+			v-if="hasHeaderSlot"
+			class="border-solid border-0 border-b border-surface-5 bg-surface-3 p-4"
+		>
+			<slot name="header" />
+		</div>
 		<table class="w-full table-fixed border-separate border-spacing-0 border-surface-5">
 			<thead class="">
 				<tr class="bg-surface-3">
@@ -44,37 +50,62 @@
 					</th>
 				</tr>
 			</thead>
-			<tbody>
-				<tr
-					v-for="(row, rowIndex) in data"
-					:key="rowIndex"
-					:class="rowIndex % 2 === 0 ? 'bg-surface-2' : 'bg-surface-1.5'"
-				>
-					<td v-if="showSelection" class="w-10 border-solid border-0 border-t border-surface-5">
-						<Checkbox
-							:model-value="isSelected(row)"
-							class="shrink-0 p-4"
-							@update:model-value="toggleSelection(row)"
-						/>
-					</td>
-					<td
-						v-for="column in columns"
-						:key="column.key"
-						class="text-secondary h-14 overflow-hidden first:pl-4 last:pr-4 border-solid border-0 border-t border-surface-5"
-						:class="`text-${column.align ?? 'left'}`"
-						:style="column.width ? { width: column.width } : undefined"
-					>
-						<slot
-							:name="`cell-${column.key}`"
-							:row="row"
-							:value="row[column.key]"
-							:column="column"
-							:index="rowIndex"
-						>
-							{{ row[column.key] ?? '' }}
+			<tbody :ref="setListContainer">
+				<tr v-if="data.length === 0" class="bg-surface-2">
+					<td :colspan="columnSpan" class="border-solid border-0 border-t border-surface-5 p-0">
+						<slot name="empty-state">
+							<div class="text-secondary flex h-64 items-center justify-center">
+								No data available.
+							</div>
 						</slot>
 					</td>
 				</tr>
+				<template v-else>
+					<tr v-if="virtualized && topSpacerHeight > 0" aria-hidden="true">
+						<td
+							:colspan="columnSpan"
+							class="border-0 p-0"
+							:style="{ height: `${topSpacerHeight}px` }"
+						></td>
+					</tr>
+					<tr
+						v-for="(row, rowIndex) in renderedRows"
+						:key="getRowRenderKey(row, getAbsoluteRowIndex(rowIndex))"
+						:class="getAbsoluteRowIndex(rowIndex) % 2 === 0 ? 'bg-surface-2' : 'bg-surface-1.5'"
+					>
+						<td v-if="showSelection" class="w-10 border-solid border-0 border-t border-surface-5">
+							<Checkbox
+								:model-value="isSelected(row)"
+								class="shrink-0 p-4"
+								@update:model-value="toggleSelection(row)"
+							/>
+						</td>
+						<td
+							v-for="column in columns"
+							:key="column.key"
+							class="text-secondary h-14 overflow-hidden first:pl-4 last:pr-4 border-solid border-0 border-t border-surface-5"
+							:class="`text-${column.align ?? 'left'}`"
+							:style="column.width ? { width: column.width } : undefined"
+						>
+							<slot
+								:name="`cell-${column.key}`"
+								:row="row"
+								:value="row[column.key]"
+								:column="column"
+								:index="getAbsoluteRowIndex(rowIndex)"
+							>
+								{{ row[column.key] ?? '' }}
+							</slot>
+						</td>
+					</tr>
+					<tr v-if="virtualized && bottomSpacerHeight > 0" aria-hidden="true">
+						<td
+							:colspan="columnSpan"
+							class="border-0 p-0"
+							:style="{ height: `${bottomSpacerHeight}px` }"
+						></td>
+					</tr>
+				</template>
 			</tbody>
 		</table>
 	</div>
@@ -86,8 +117,9 @@
 	generic="K extends string = string, T extends Record<string, unknown> = Record<K, unknown>"
 >
 import { ChevronDownIcon, ChevronUpIcon } from '@modrinth/assets'
-import { computed } from 'vue'
+import { computed, toRef, useSlots } from 'vue'
 
+import { useVirtualScroll } from '../../composables/virtual-scroll'
 import Checkbox from './Checkbox.vue'
 
 export type TableColumnAlign = 'left' | 'center' | 'right'
@@ -115,16 +147,49 @@ const props = withDefaults(
 		data: T[] /* Row data for table */
 		showSelection?: boolean
 		rowKey?: keyof T /* The key used to uniquely identify each row */
+		virtualized?: boolean
+		virtualRowHeight?: number
+		virtualBufferSize?: number /* The number of extra rows rendered above and below the visible viewport */
 	}>(),
 	{
 		showSelection: false,
 		rowKey: 'id' as keyof T,
+		virtualized: false,
+		virtualRowHeight: 56,
+		virtualBufferSize: 5,
 	},
 )
 
 const selectedIds = defineModel<unknown[]>('selectedIds', { default: () => [] })
 const sortColumn = defineModel<string | undefined>('sortColumn')
 const sortDirection = defineModel<SortDirection>('sortDirection', { default: 'asc' })
+const slots = useSlots()
+const hasHeaderSlot = computed(() => Boolean(slots.header))
+const columnSpan = computed(() => Math.max(props.columns.length + (props.showSelection ? 1 : 0), 1))
+
+const {
+	listContainer,
+	totalHeight,
+	visibleRange,
+	visibleTop: topSpacerHeight,
+	visibleItems,
+} = useVirtualScroll(toRef(props, 'data'), {
+	itemHeight: props.virtualRowHeight,
+	bufferSize: props.virtualBufferSize,
+	enabled: toRef(props, 'virtualized'),
+})
+
+const renderedRows = computed(() => (props.virtualized ? visibleItems.value : props.data))
+const bottomSpacerHeight = computed(() => {
+	if (!props.virtualized) {
+		return 0
+	}
+
+	return Math.max(
+		0,
+		totalHeight.value - topSpacerHeight.value - renderedRows.value.length * props.virtualRowHeight,
+	)
+})
 
 const emit = defineEmits<{
 	sort: [column: string, direction: SortDirection]
@@ -141,6 +206,23 @@ function getRowId(row: T): unknown {
 	return row[props.rowKey as keyof T]
 }
 
+function setListContainer(element: unknown) {
+	listContainer.value = props.virtualized ? (element as HTMLElement | null) : null
+}
+
+function getAbsoluteRowIndex(rowIndex: number): number {
+	return props.virtualized ? visibleRange.value.start + rowIndex : rowIndex
+}
+
+function getRowRenderKey(row: T, rowIndex: number): PropertyKey {
+	const rowId = getRowId(row)
+	if (typeof rowId === 'string' || typeof rowId === 'number' || typeof rowId === 'symbol') {
+		return rowId
+	}
+
+	return rowIndex
+}
+
 function isSelected(row: T): boolean {
 	return selectedIds.value.includes(getRowId(row))
 }
diff --git a/packages/ui/src/stories/base/Table.stories.ts b/packages/ui/src/stories/base/Table.stories.ts
index 43edafd06..93e0768ca 100644
--- a/packages/ui/src/stories/base/Table.stories.ts
+++ b/packages/ui/src/stories/base/Table.stories.ts
@@ -1,6 +1,6 @@
 import { EditIcon, MoreVerticalIcon, TrashIcon } from '@modrinth/assets'
 import type { Meta, StoryObj } from '@storybook/vue3-vite'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 
 import Badge from '../../components/base/Badge.vue'
 import ButtonStyled from '../../components/base/ButtonStyled.vue'
@@ -219,6 +219,38 @@ export const WithCustomHeaderSlots: StoryObj = {
 	}),
 }
 
+export const WithHeaderSlot: StoryObj = {
+	args: {},
+	render: () => ({
+		components: { Table, ButtonStyled },
+		setup() {
+			const columns = [
+				{ key: 'name', label: 'Name' },
+				{ key: 'email', label: 'Email' },
+				{ key: 'status', label: 'Status' },
+				{ key: 'role', label: 'Role' },
+			]
+			const data = sampleUsers
+
+			return { columns, data }
+		},
+		template: /* html */ `
+			<Table :columns="columns" :data="data">
+				<template #header>
+					<div class="flex flex-col gap-3 xl:flex-row xl:items-center xl:justify-between">
+						<div class="text-lg font-semibold text-contrast">Team Members</div>
+						<div class="flex items-center gap-2">
+							<ButtonStyled color="brand">
+								<button type="button">Invite member</button>
+							</ButtonStyled>
+						</div>
+					</div>
+				</template>
+			</Table>
+		`,
+	}),
+}
+
 export const WithActionsColumn: StoryObj = {
 	args: {},
 	render: () => ({
@@ -368,6 +400,124 @@ export const FullFeatured: StoryObj = {
 	}),
 }
 
+export const VirtualizedLargeData: StoryObj = {
+	args: {},
+	render: () => ({
+		components: { Table, Badge },
+		setup() {
+			const columns = [
+				{ key: 'name', label: 'Name', enableSorting: true },
+				{ key: 'email', label: 'Email', enableSorting: true },
+				{ key: 'status', label: 'Status', align: 'center' as const, width: '140px' },
+				{ key: 'role', label: 'Role', enableSorting: true, align: 'right' as const },
+			]
+			const statuses: User['status'][] = ['active', 'inactive', 'pending']
+			const roles = ['Admin', 'Editor', 'Maintainer', 'Reviewer', 'User']
+			const largeData = Array.from({ length: 10000 }, (_, index): User => {
+				const id = String(index + 1)
+				const paddedId = id.padStart(5, '0')
+
+				return {
+					id,
+					name: `User ${paddedId}`,
+					email: `user-${paddedId}@example.com`,
+					status: statuses[index % statuses.length],
+					role: roles[index % roles.length],
+				}
+			})
+			const selectedIds = ref<string[]>([])
+			const sortColumn = ref<string | undefined>('name')
+			const sortDirection = ref<'asc' | 'desc'>('asc')
+			const data = computed(() => {
+				const sorted = [...largeData]
+				const activeSortColumn = sortColumn.value
+
+				if (!activeSortColumn) {
+					return sorted
+				}
+
+				const directionFactor = sortDirection.value === 'asc' ? 1 : -1
+				sorted.sort((left, right) => {
+					return (
+						String(left[activeSortColumn as keyof User]).localeCompare(
+							String(right[activeSortColumn as keyof User]),
+							undefined,
+							{ numeric: true, sensitivity: 'base' },
+						) * directionFactor
+					)
+				})
+
+				return sorted
+			})
+
+			const statusColor = (status: string) => {
+				switch (status) {
+					case 'active':
+						return 'green'
+					case 'inactive':
+						return 'red'
+					case 'pending':
+						return 'orange'
+					default:
+						return 'gray'
+				}
+			}
+
+			function handleSort(column: string, direction: 'asc' | 'desc') {
+				console.log(`Sorting ${largeData.length} rows by ${column} ${direction}`)
+			}
+
+			return {
+				columns,
+				data,
+				selectedIds,
+				sortColumn,
+				sortDirection,
+				statusColor,
+				handleSort,
+			}
+		},
+		template: /* html */ `
+			<div class="space-y-4 max-h-[60vh] overflow-y-scroll">
+				<Table
+					:columns="columns"
+					:data="data"
+					show-selection
+					row-key="id"
+					virtualized
+					:virtual-row-height="56"
+					v-model:selected-ids="selectedIds"
+					v-model:sort-column="sortColumn"
+					v-model:sort-direction="sortDirection"
+					@sort="handleSort"
+				>
+					<template #header>
+						<div class="flex items-center justify-between gap-4">
+							<div class="text-lg font-semibold text-contrast">Virtualized members</div>
+							<div class="text-sm text-secondary">{{ data.length.toLocaleString() }} rows</div>
+						</div>
+					</template>
+					<template #cell-name="{ value, index }">
+						<div class="flex items-center gap-2">
+							<span class="text-secondary tabular-nums">#{{ index + 1 }}</span>
+							<span class="font-semibold">{{ value }}</span>
+						</div>
+					</template>
+					<template #cell-status="{ value }">
+						<div class="flex justify-center">
+							<Badge :color="statusColor(value)">{{ value }}</Badge>
+						</div>
+					</template>
+				</Table>
+				<div class="flex gap-4 text-secondary text-sm">
+					<span>Selected: {{ selectedIds.length }} items</span>
+					<span>Sort: {{ sortColumn }} ({{ sortDirection }})</span>
+				</div>
+			</div>
+		`,
+	}),
+}
+
 export const WithOverflowMenu: StoryObj = {
 	args: {},
 	render: () => ({
@@ -378,7 +528,7 @@ export const WithOverflowMenu: StoryObj = {
 				{ key: 'email', label: 'Email' },
 				{ key: 'status', label: 'Status', align: 'center' as const, width: '20%' },
 				{ key: 'role', label: 'Role' },
-				{ key: 'actions', label: '', width: '48px' },
+				{ key: 'actions', label: '', width: '68px' },
 			]
 			const data = sampleUsers
 
@@ -453,3 +603,31 @@ export const WithOverflowMenu: StoryObj = {
 		`,
 	}),
 }
+
+export const EmptyState: StoryObj = {
+	args: {},
+	render: () => ({
+		components: { Table },
+		setup() {
+			const columns = [
+				{ key: 'name', label: 'Name' },
+				{ key: 'email', label: 'Email' },
+				{ key: 'status', label: 'Status' },
+				{ key: 'role', label: 'Role' },
+			]
+			const data: User[] = []
+
+			return { columns, data }
+		},
+		template: /* html */ `
+			<Table :columns="columns" :data="data">
+				<template #empty-state>
+					<div class="flex h-64 flex-col items-center justify-center gap-2 text-center">
+						<div class="font-semibold text-contrast">No members found</div>
+						<div class="text-sm text-secondary">Invite a team member to get started.</div>
+					</div>
+				</template>
+			</Table>
+		`,
+	}),
+}