Skip to content

Modern Docker Management, Designed for Everyone

31.6 KB
Raw Blame
<script lang="ts" generics="TData extends Record<string, any> & { id: string }">
	import { createTable, createTableState, renderComponent, renderSnippet } from '@tanstack/svelte-table';
	import type { ColumnFiltersState, RowSelectionState, SortingState, ColumnVisibilityState } from '@tanstack/table-core';
	import { PersistedState } from 'runed';
	import { onDestroy, onMount, untrack } from 'svelte';
	import type { Snippet } from 'svelte';
	import type { Component } from 'svelte';

	import { ArcaneButton } from '#lib/components/arcane-button/index.js';
	import * as Alert from '#lib/components/ui/alert/index.js';
	import { TABLE_PAGE_SIZE_ALL } from '#lib/constants/table-pagination.js';
	import { IsMobile } from '#lib/hooks/is-mobile.svelte.js';
	import { AlertTriangleIcon } from '#lib/icons/index.js';
	import { m } from '#lib/paraglide/messages.js';
	import type { Paginated, SearchPaginationSortRequest } from '#lib/types/shared.js';
	import { handleApiResultWithCallbacks } from '#lib/utils/api.js';
	import { rowKey, type EnvironmentFailure } from '#lib/utils/environments.js';
	import { tryCatch } from '#lib/utils/try-catch.js';

	import ArcaneTableCell from './arcane-table-cell.svelte';
	import TableCheckbox from './arcane-table-checkbox.svelte';
	import ArcaneTableDesktopView from './arcane-table-desktop-view.svelte';
	import ArcaneTableHeader from './arcane-table-header.svelte';
	import ArcaneTableMobileView from './arcane-table-mobile-view.svelte';
	import ArcaneTablePagination from './arcane-table-pagination.svelte';
	import DataTableToolbar from './arcane-table-toolbar.svelte';
	import type { ColumnSpec } from './arcane-table.types.svelte';
	import {
		type CompactTablePrefs,
		type FieldSpec,
		type GroupedData,
		type GroupSelectionState,
		type SelectionModifiers,
		type SortState,
		encodeHidden,
		applyHiddenPatch,
		encodeFilters,
		encodeSort,
		encodeMobileVisibility,
		buildMobileVisibility,
		type BulkAction
	} from './arcane-table.types.svelte';
	import {
		extractPersistedPreferences,
		fromFilterMap,
		getTableRowsForItems,
		restoreTableRequestOptions,
		toFilterMap
	} from './arcane-table.utils';
	import TableEmpty from './table-empty.svelte';
	import { arcaneTableFeatures, type ArcaneColumnDef, type ArcaneRow, type ArcaneTable } from './table-features';

	let {
		items,
		requestOptions = $bindable(),
		withoutSearch = $bindable(),
		withoutFilters = false,
		withoutPagination = false,
		restoreAllPageSize = true,
		selectionDisabled = false,
		loading = false,
		unstyled = false,
		onRefresh,
		onPageSizeChangeRequest,
		columns,
		rowActions,
		mobileCard,
		mobileFields = [],
		mobileFieldVisibility = $bindable<Record<string, boolean>>({}),
		selectedIds = $bindable<string[]>([]),
		bulkActions = [],
		persistKey,
		customViewOptions,
		customToolbarActions,
		customTableView,
		customSettings = $bindable<Record<string, unknown>>({}),
		columnVisibility = $bindable<ColumnVisibilityState>({}),
		preferencesReady = $bindable(false),
		hiddenSortFallback,
		groupedRows = null,
		// Grouping props
		groupBy,
		groupIcon,
		groupCollapsedState = $bindable<Record<string, boolean>>({}),
		onGroupToggle,
		imageNameFilterOptions,
		// Expandable row props
		expandedRowContent,
		emptyState
	}: {
		/** Merged lists carry the environments that could not be loaded. */
		items: Paginated<TData> & { failedEnvironments?: EnvironmentFailure[] };
		requestOptions: SearchPaginationSortRequest;
		withoutSearch?: boolean;
		withoutFilters?: boolean;
		withoutPagination?: boolean;
		/** Restore the default limit instead of a saved All selection when false. */
		restoreAllPageSize?: boolean;
		selectionDisabled?: boolean;
		/** When true and there's no data yet, the desktop view shows skeleton rows (first-load). */
		loading?: boolean;
		unstyled?: boolean;
		onRefresh: (requestOptions: SearchPaginationSortRequest) => Promise<Paginated<TData>>;
		/** Allows a caller to confirm a page-size change before applying it. */
		onPageSizeChangeRequest?: (limit: number, apply: () => void) => void;
		columns: ColumnSpec<TData>[];
		rowActions?: Snippet<[{ row: ArcaneRow<TData>; item: TData }]>;
		mobileCard: Snippet<[{ row: ArcaneRow<TData>; item: TData; mobileFieldVisibility: Record<string, boolean> }]>;
		mobileFields?: FieldSpec[];
		mobileFieldVisibility?: Record<string, boolean>;
		selectedIds?: string[];
		bulkActions?: BulkAction[];
		persistKey?: string;
		customViewOptions?: Snippet;
		customToolbarActions?: Snippet;
		customTableView?: Snippet<
			[
				{
					table: ArcaneTable<TData>;
					renderPagination: Snippet;
					mobileFieldsForOptions: { id: string; label: string; visible: boolean }[];
					onToggleMobileField: (fieldId: string) => void;
				}
			]
		>;
		customSettings?: Record<string, unknown>;
		columnVisibility?: ColumnVisibilityState;
		preferencesReady?: boolean;
		hiddenSortFallback?: SortState;
		groupedRows?: GroupedData<TData>[] | null;
		// Grouping props
		groupBy?: (item: TData) => string;
		groupIcon?: (groupName: string) => Component;
		groupCollapsedState?: Record<string, boolean>;
		onGroupToggle?: (groupName: string) => void;
		imageNameFilterOptions?: string[];
		// Expandable row props
		expandedRowContent?: Snippet<[{ row: ArcaneRow<TData>; item: TData }]>;
		/** First-use empty state, shown when the collection is empty and no search or filter is active. */
		emptyState?: Snippet;
	} = $props();

	// Default page size constant
	const DEFAULT_LIMIT = 20;

	const [rowSelection, setRowSelection] = createTableState<RowSelectionState>({});
	const columnFilters = $derived(fromFilterMap(requestOptions?.filters));
	const serverSort = $derived(requestOptions?.sort);
	let clientSortOverride = $state.raw<{
		serverSort: SearchPaginationSortRequest['sort'];
		column?: string;
		direction?: string;
		sorting: SortingState;
	} | null>(null);
	const sorting = $derived.by((): SortingState => {
		if (
			clientSortOverride &&
			clientSortOverride.serverSort === serverSort &&
			clientSortOverride.column === serverSort?.column &&
			clientSortOverride.direction === serverSort?.direction
		) {
			return clientSortOverride.sorting;
		}
		if (!serverSort) return [];
		return [{ id: serverSort.column, desc: serverSort.direction === 'desc' }];
	});
	const [globalFilter, setGlobalFilter] = createTableState<string>(requestOptions?.search ?? '');

	const enablePersist = $derived(!!persistKey);
	const getEffectiveLimit = () => requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? DEFAULT_LIMIT;
	let prefs = $state<PersistedState<CompactTablePrefs> | null>(null);

	// Expandable row state
	let expandedRows = $state<Set<string>>(new Set());

	// Wrap-text preference, shared by every table (view-options toggle).
	const wrapTextPref = new PersistedState<boolean>('arcane-table-wrap-text', false);
	const wrapText = $derived(wrapTextPref.current);
	function toggleWrapText() {
		wrapTextPref.current = !wrapTextPref.current;
	}

	// Each view owns its virtualizer and restores its own scroll position.
	let desktopScrollEl = $state<HTMLElement>();
	let mobileScrollEl = $state<HTMLElement>();
	const isMobile = new IsMobile();
	const scrollPositions = { desktop: { top: 0, left: 0 }, mobile: { top: 0, left: 0 } };
	const selectedIdSet = $derived(new Set(selectedIds ?? []));

	function restoreScroll(node: HTMLElement, view: keyof typeof scrollPositions) {
		const position = scrollPositions[view];
		const frame = requestAnimationFrame(() => {
			node.scrollTop = position.top;
			node.scrollLeft = position.left;
			node.addEventListener('scroll', savePosition, { passive: true });
		});
		function savePosition() {
			position.top = node.scrollTop;
			position.left = node.scrollLeft;
		}
		return () => {
			cancelAnimationFrame(frame);
			node.removeEventListener('scroll', savePosition);
		};
	}

	// Caps the shell to the viewport space below its unscrolled position so its bottom stays on screen.
	function fitToViewport(node: HTMLElement) {
		let frame = 0;
		const update = () => {
			cancelAnimationFrame(frame);
			frame = requestAnimationFrame(() => {
				let top = node.getBoundingClientRect().top;
				let bottomGap = parseFloat(getComputedStyle(node).marginBottom);
				for (let el = node.parentElement; el; el = el.parentElement) {
					const style = getComputedStyle(el);
					top += el.scrollTop;
					bottomGap += parseFloat(style.paddingBottom) + parseFloat(style.borderBottomWidth) + parseFloat(style.marginBottom);
				}
				const available = window.innerHeight - top - bottomGap;
				node.style.maxHeight = `${Math.max(available, window.innerHeight / 2)}px`;
			});
		};
		const observer = new ResizeObserver(update);
		for (let el = node.parentElement; el; el = el.parentElement) observer.observe(el);
		window.addEventListener('resize', update);
		update();
		return () => {
			cancelAnimationFrame(frame);
			observer.disconnect();
			window.removeEventListener('resize', update);
		};
	}

	function toggleRowExpanded(rowId: string) {
		const next = new Set(expandedRows);
		if (next.has(rowId)) {
			next.delete(rowId);
		} else {
			next.add(rowId);
		}
		expandedRows = next;
	}

	// Client-sorted columns (spec.clientSort): the server can't order these values,
	// so header clicks reorder the current page locally via the column accessor.
	const clientSortAccessors = $derived.by(() => {
		const accessors = new Map<string, (row: TData) => unknown>();
		columns.forEach((spec, i) => {
			if (!spec.clientSort) return;
			const id = spec.id ?? (spec.accessorKey as string) ?? `col_${i}`;
			const accessorKey = spec.accessorKey;
			const accessorFn = spec.accessorFn;
			accessors.set(id, accessorFn ?? ((row: TData) => (accessorKey ? row[accessorKey] : undefined)));
		});
		return accessors;
	});

	const sortedData = $derived.by(() => {
		const data = items.data ?? [];
		const first = sorting[0];
		const accessor = first ? clientSortAccessors.get(String(first.id)) : undefined;
		if (!first || !accessor) return data;
		const direction = first.desc ? -1 : 1;
		return [...data].sort((a, b) => {
			const va = accessor(a);
			const vb = accessor(b);
			if (typeof va === 'number' && typeof vb === 'number') return (va - vb) * direction;
			return String(va ?? '').localeCompare(String(vb ?? '')) * direction;
		});
	});

	const currentPage = $derived(items.pagination?.currentPage ?? requestOptions?.pagination?.page ?? 1);
	const totalPages = $derived(items.pagination?.totalPages ?? 1);
	const totalItems = $derived(items.pagination?.totalItems ?? 0);
	const pageSize = $derived(requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? DEFAULT_LIMIT);
	const canPrev = $derived(currentPage > 1);
	const canNext = $derived(currentPage < totalPages);

	onMount(() => {
		// Initialize prefs first
		if (persistKey && !prefs) {
			prefs = new PersistedState<CompactTablePrefs>(
				persistKey,
				{ v: [], f: [], g: '', l: getEffectiveLimit() },
				{ syncTabs: false }
			);
		}

		// Then restore preferences
		if (!enablePersist) {
			preferencesReady = true;
			return;
		}
		const snapshot = extractPersistedPreferences(prefs?.current, getEffectiveLimit());
		if (!restoreAllPageSize && snapshot.limit === TABLE_PAGE_SIZE_ALL) {
			snapshot.limit = DEFAULT_LIMIT;
		}

		const patchedVisibility = { ...columnVisibility };
		applyHiddenPatch(patchedVisibility, snapshot.hiddenColumns);
		columnVisibility = patchedVisibility;

		const effectiveSearch = (requestOptions?.search ?? '').trim() || snapshot.search;
		if (effectiveSearch !== globalFilter()) setGlobalFilter(effectiveSearch);

		const persistedSort = snapshot.sort;
		if (
			persistedSort &&
			(patchedVisibility[persistedSort.column] ?? defaultColumnVisibility[persistedSort.column]) === false &&
			hiddenSortFallback
		) {
			snapshot.sort = hiddenSortFallback;
			if (snapshot.sort !== persistedSort && prefs) prefs.current = { ...prefs.current, s: encodeSort(snapshot.sort) };
		}
		const restoredOptions = restoreTableRequestOptions(requestOptions, snapshot, getEffectiveLimit());
		if (restoredOptions !== requestOptions) {
			requestOptions = restoredOptions;
			onRefresh(requestOptions);
		}

		if (mobileFields.length && !Object.keys(mobileFieldVisibility).length) {
			mobileFieldVisibility = buildMobileVisibility(mobileFields, snapshot.mobileVisibility);
		}

		if (snapshot.customSettings && Object.keys(snapshot.customSettings).length > 0) {
			customSettings = { ...snapshot.customSettings };
		}

		preferencesReady = true;
		persistCustomSettings(customSettings);
	});

	function updatePagination(patch: Partial<{ page: number; limit: number }>) {
		const prev = requestOptions?.pagination ?? {
			page: items?.pagination?.currentPage ?? 1,
			limit: items?.pagination?.itemsPerPage ?? 10
		};
		scrollPositions.desktop.top = 0;
		scrollPositions.mobile.top = 0;
		if (desktopScrollEl) desktopScrollEl.scrollTop = 0;
		if (mobileScrollEl) mobileScrollEl.scrollTop = 0;
		const next = { ...prev, ...patch };
		requestOptions = { ...requestOptions, pagination: next };
		onRefresh(requestOptions);
	}

	function setPage(page: number) {
		if (page < 1) page = 1;
		if (totalPages > 0 && page > totalPages) page = totalPages;
		updatePagination({ page });
	}

	function setPageSize(limit: number) {
		if (limit === pageSize) return;
		const apply = () => {
			if (enablePersist && prefs) prefs.current = { ...prefs.current, l: limit };
			updatePagination({ limit, page: 1 });
		};
		if (onPageSizeChangeRequest) {
			onPageSizeChangeRequest(limit, apply);
		} else {
			apply();
		}
	}

	function onToggleAll(checked: boolean, table: ArcaneTable<TData>) {
		const pageIds = table.getRowModel().rows.map((r) => r.id);
		if (checked) {
			const set = new Set([...(selectedIds ?? []), ...pageIds]);
			selectedIds = Array.from(set);
		} else {
			const pageSet = new Set(pageIds);
			selectedIds = (selectedIds ?? []).filter((id) => !pageSet.has(id));
		}
	}

	// Shift-select anchor; valid only against the row order and selection array it was recorded with.
	let rangeAnchor: { id: string; orderKey: string; selection: string[] | undefined } | null = null;

	function onToggleRow(checked: boolean, id: string, modifiers?: SelectionModifiers) {
		const ids = orderedRowIds;
		const orderKey = ids.join('\0');
		const anchor =
			modifiers?.shiftKey && rangeAnchor?.orderKey === orderKey && rangeAnchor.selection === selectedIds ? rangeAnchor : null;
		const anchorIndex = anchor ? ids.indexOf(anchor.id) : -1;
		const targetIndex = anchor ? ids.indexOf(id) : -1;
		const useRange = anchorIndex >= 0 && targetIndex >= 0;
		const rangeIds = useRange ? ids.slice(Math.min(anchorIndex, targetIndex), Math.max(anchorIndex, targetIndex) + 1) : [id];
		if (checked) {
			selectedIds = Array.from(new Set([...(selectedIds ?? []), ...rangeIds]));
		} else {
			const remove = new Set(rangeIds);
			selectedIds = (selectedIds ?? []).filter((x) => !remove.has(x));
		}
		rangeAnchor = { id: useRange && anchor ? anchor.id : id, orderKey, selection: selectedIds };
	}

	function buildColumns(specs: ColumnSpec<TData>[], isSelectionDisabled: boolean): ArcaneColumnDef<TData>[] {
		const cols: ArcaneColumnDef<TData>[] = [];

		if (!isSelectionDisabled) {
			cols.push({
				id: 'select',
				header: ({ table }) => {
					const pageIds = table.getRowModel().rows.map((r) => r.id);
					const selectedSet = new Set(selectedIds ?? []);
					const total = pageIds.length;
					const selectedOnPage = pageIds.filter((id) => selectedSet.has(id)).length;
					const checked = total > 0 && selectedOnPage === total;
					const indeterminate = selectedOnPage > 0 && selectedOnPage < total;

					return renderComponent(TableCheckbox, {
						checked,
						indeterminate,
						onCheckedChange: (value) => onToggleAll(!!value, table),
						'aria-label': m.common_select_all()
					});
				},
				cell: ({ row }) => {
					const id = row.id;
					return renderComponent(TableCheckbox, {
						checked: (selectedIds ?? []).includes(id),
						onCheckedChange: (value, modifiers) => onToggleRow(!!value, id, modifiers),
						'aria-label': m.common_select_row()
					});
				},
				enableSorting: false,
				enableHiding: false
			});
		}

		specs.forEach((spec, i) => {
			const accessorKey = spec.accessorKey;
			const accessorFn = spec.accessorFn;
			const id = spec.id ?? (accessorKey as string) ?? `col_${i}`;

			cols.push({
				id,
				...(accessorKey ? { accessorKey } : {}),
				...(accessorFn ? { accessorFn } : {}),
				meta: {
					title: spec.title,
					filterOptions: spec.filterOptions,
					width: spec.width,
					align: spec.align,
					truncate: spec.truncate
				},
				header: ({ column }) => {
					if (spec.header) return renderSnippet(spec.header, { column, title: spec.title, class: spec.class });
					return renderComponent(ArcaneTableHeader, {
						column: spec.sortable || spec.clientSort ? column : undefined,
						title: spec.title,
						class: spec.class
					});
				},
				cell: ({ row, getValue }) => {
					const item = row.original as TData;
					const value = accessorKey ? row.getValue(accessorKey) : getValue?.();
					if (spec.cell) return renderSnippet(spec.cell, { row, item, value });
					if (spec.cellComponent) return renderComponent(spec.cellComponent, { value });
					return renderComponent(ArcaneTableCell, { value });
				},
				enableSorting: !!spec.sortable || !!spec.clientSort,
				enableHiding: true
			});
		});

		if (rowActions) {
			cols.push({
				id: 'actions',
				// The closure reads the live rowActions prop. When the caller flips it
				// to undefined (e.g. a project stops and its per-row actions go away),
				// the old column can still render once before the column set rebuilds —
				// rendering an undefined snippet would crash the page (invalid_snippet).
				cell: ({ row }) => (rowActions ? renderSnippet(rowActions, { row, item: row.original as TData }) : undefined)
			});
		}

		return cols;
	}

	// Compute initial hidden columns from column specs (without mutating state in derived)
	function getInitialHiddenColumns(specs: ColumnSpec<TData>[]): Record<string, boolean> {
		const hidden: Record<string, boolean> = {};
		specs.forEach((spec, i) => {
			if (spec.hidden) {
				const accessorKey = spec.accessorKey;
				const id = spec.id ?? (accessorKey as string) ?? `col_${i}`;
				hidden[id] = false;
			}
		});
		return hidden;
	}

	const defaultColumnVisibility = $derived(getInitialHiddenColumns(columns));
	const effectiveColumnVisibility = $derived({ ...defaultColumnVisibility, ...columnVisibility });

	// Memoize column definitions until their structure or facet options change.
	// Facet catalogs can arrive after the table's first render, so their metadata
	// must participate in the key even though row data does not.
	function getColumnsKey(specs: ColumnSpec<TData>[], hasRowActions: boolean, isSelectionDisabled: boolean): string {
		const columnsMetadata = specs.map((spec, index) => ({
			id: spec.id ?? spec.accessorKey ?? `col_${index}`,
			filterOptions: spec.filterOptions?.map((option) => ({
				value: option.value,
				label: option.label,
				dotClass: option.dotClass
			}))
		}));
		return `${JSON.stringify(columnsMetadata)}:${hasRowActions}:${isSelectionDisabled}`;
	}

	const columnsKey = $derived(getColumnsKey(columns, !!rowActions, selectionDisabled));
	const columnsDef = $derived.by(() => {
		columnsKey; // structural dependency: identity-churned `columns` arrays with an unchanged key don't rebuild defs
		return untrack(() => buildColumns(columns, selectionDisabled));
	});

	const table = createTable({
		features: arcaneTableFeatures,
		// Manual / server-side mode: no client row models are registered, so sorting and
		// filtering never run on the client — these flags make that explicit. Pagination is
		// fully external (no rowPaginationFeature registered), so there is no manualPagination.
		manualSorting: true,
		manualFiltering: true,
		// Stable row identity across server refreshes. Without this v9 keys rows by positional
		// index, so every onRefresh fetch re-keys all rows and forces a full re-render; keying
		// by the backing id lets unchanged rows (and their DOM/selection) be reused.
		getRowId: (row) => rowKey(row),
		get data() {
			return sortedData;
		},
		state: {
			get sorting() {
				return sorting;
			},
			get columnVisibility() {
				return effectiveColumnVisibility;
			},
			get rowSelection() {
				return rowSelection();
			},
			get columnFilters() {
				return columnFilters;
			},
			get globalFilter() {
				return globalFilter();
			}
		},
		get columns() {
			return columnsDef;
		},
		get enableRowSelection() {
			return !selectionDisabled;
		},
		onRowSelectionChange: setRowSelection,
		onSortingChange: (updater) => {
			const wasClientSort = sorting[0] && clientSortAccessors.has(String(sorting[0].id));
			let next: SortingState;
			if (typeof updater === 'function') next = updater(sorting);
			else next = updater;
			const first = next[0];
			// Keep client-only sorting, including its cleared state, until the server sort changes.
			if ((first && clientSortAccessors.has(String(first.id))) || (!first && wasClientSort)) {
				clientSortOverride = {
					serverSort,
					column: serverSort?.column,
					direction: serverSort?.direction,
					sorting: next
				};
				return;
			}
			clientSortOverride = null;
			const sortState = first
				? { column: String(first.id), direction: (first.desc ? 'desc' : 'asc') as 'asc' | 'desc' }
				: undefined;
			if (enablePersist && prefs) {
				prefs.current = {
					...prefs.current,
					s: encodeSort(sortState)
				};
			}
			requestOptions = {
				...requestOptions,
				sort: sortState,
				pagination: {
					page: 1,
					limit: requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? 10
				}
			};
			onRefresh(requestOptions);
		},
		onColumnFiltersChange: (updater) => {
			let next: ColumnFiltersState;
			if (typeof updater === 'function') next = updater(columnFilters);
			else next = updater;
			if (enablePersist && prefs) {
				prefs.current = { ...prefs.current, f: encodeFilters(next) };
			}
			requestOptions = {
				...requestOptions,
				filters: toFilterMap(next),
				pagination: {
					page: 1,
					limit: requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? 10
				}
			};
			onRefresh(requestOptions);
		},
		onColumnVisibilityChange: (updater) => {
			let nextVisibility: ColumnVisibilityState;
			if (typeof updater === 'function') nextVisibility = updater(effectiveColumnVisibility);
			else nextVisibility = updater;
			columnVisibility = nextVisibility;
			// Persist visibility
			if (enablePersist && prefs) {
				prefs.current = { ...prefs.current, v: encodeHidden(columnVisibility) };
			}

			const activeSort = requestOptions?.sort;
			if (activeSort && nextVisibility[activeSort.column] === false && hiddenSortFallback) {
				clientSortOverride = null;
				requestOptions = {
					...requestOptions,
					sort: hiddenSortFallback,
					pagination: {
						page: 1,
						limit: requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? 10
					}
				};
				if (enablePersist && prefs) {
					prefs.current = { ...prefs.current, s: encodeSort(hiddenSortFallback) };
				}
				onRefresh(requestOptions);
			}
		},
		onGlobalFilterChange: (updater) => {
			setGlobalFilter(updater);
			if (typeof globalFilter() !== 'string') setGlobalFilter('');
			const limit = requestOptions?.pagination?.limit ?? items?.pagination?.itemsPerPage ?? 10;
			requestOptions = {
				...requestOptions,
				search: globalFilter(),
				pagination: { page: 1, limit }
			};
			// Persist global filter
			if (enablePersist && prefs) {
				prefs.current = { ...prefs.current, g: globalFilter() };
			}
			onRefresh(requestOptions);
		}
	});

	// Rendered column count (add 1 for the expand chevron column when expandable). Based on
	// visible leaf columns, not columnsDef — hidden columns (e.g. id) would otherwise inflate
	// colspans and create phantom columns that misalign grouped/empty/expanded rows.
	const effectiveColumnsCount = $derived(table.getVisibleLeafColumns().length + (expandedRowContent ? 1 : 0));

	function onToggleMobileField(fieldId: string) {
		mobileFieldVisibility = {
			...mobileFieldVisibility,
			[fieldId]: !mobileFieldVisibility[fieldId]
		};
		// Persist mobile field visibility
		if (enablePersist && prefs) {
			prefs.current = { ...prefs.current, m: encodeMobileVisibility(mobileFieldVisibility) };
		}
	}

	const mobileFieldsForOptions = $derived(
		mobileFields.map((field) => ({
			id: field.id,
			label: field.label,
			visible: mobileFieldVisibility[field.id] ?? true
		}))
	);

	const rowIndex = $derived.by(() => new Map(table.getRowModel().rows.map((row, index) => [row.id, { row, index }])));

	// Compute grouped rows when groupBy is provided
	const effectiveGroupedRows = $derived.by((): GroupedData<TData>[] | null => {
		if (groupedRows) return groupedRows;
		if (!groupBy) return null;

		const groups = new Map<string, TData[]>();
		for (const item of items.data ?? []) {
			const groupName = groupBy(item);
			if (!groups.has(groupName)) {
				groups.set(groupName, []);
			}
			groups.get(groupName)!.push(item);
		}

		return Array.from(groups.entries()).map(([groupName, groupItems]) => ({
			groupName,
			items: groupItems
		}));
	});

	// Row ids in display order (flat model, or expanded groups in group order), matching the desktop view.
	const orderedRowIds = $derived.by((): string[] => {
		const groups = effectiveGroupedRows;
		if (!groups || groups.length === 0) return table.getRowModel().rows.map((row) => row.id);
		return groups.flatMap((group) =>
			(groupCollapsedState[group.groupName] ?? true) ? [] : getTableRowsForItems(rowIndex, group.items).map((row) => row.id)
		);
	});

	// Get selection state for a group
	function getGroupSelectionState(groupItems: TData[]): GroupSelectionState {
		const groupIds = groupItems.map((item) => rowKey(item));
		const selectedCount = groupIds.filter((id) => selectedIdSet.has(id)).length;

		if (selectedCount === 0) return 'none';
		if (selectedCount === groupIds.length) return 'all';
		return 'some';
	}

	// Toggle selection for all items in a group
	function onToggleGroupSelection(groupItems: TData[]) {
		const groupIds = groupItems.map((item) => rowKey(item));
		const state = getGroupSelectionState(groupItems);

		if (state === 'all') {
			// Deselect all in group
			const groupSet = new Set(groupIds);
			selectedIds = (selectedIds ?? []).filter((id) => !groupSet.has(id));
		} else {
			// Select all in group
			const set = new Set([...(selectedIds ?? []), ...groupIds]);
			selectedIds = Array.from(set);
		}
	}

	// Handle group collapse toggle
	function handleGroupToggle(groupName: string) {
		if (onGroupToggle) {
			onGroupToggle(groupName);
		} else {
			// Default behavior: toggle collapsed state (unrecorded groups render collapsed)
			groupCollapsedState = {
				...groupCollapsedState,
				[groupName]: !(groupCollapsedState[groupName] ?? true)
			};
		}
	}

	let lastPersistedSettings: string | null = null;
	let persistTimeout: ReturnType<typeof setTimeout> | undefined;

	export function persistSort(sort: SortState | undefined) {
		if (!enablePersist || !prefs) return;
		prefs.current = { ...prefs.current, s: encodeSort(sort) };
	}

	export function persistCustomSettings(settings: Record<string, unknown>) {
		if (!preferencesReady || !prefs) return;
		const settingsJson = JSON.stringify(settings);
		clearTimeout(persistTimeout);
		if (settingsJson === lastPersistedSettings) return;
		const owner = prefs;
		persistTimeout = setTimeout(() => {
			owner.current = { ...owner.current, c: settings };
			lastPersistedSettings = settingsJson;
		}, 100);
	}

	onDestroy(() => clearTimeout(persistTimeout));

	// With `withoutFilters` the column filters aren't user-controlled — the page bakes
	// in its own scoping filter (e.g. /updates pins `updates`), which must not count as filtering.
	const isFiltered = $derived(
		!!table.atoms.globalFilter.get() || (!withoutFilters && table.atoms.columnFilters.get().length > 0)
	);

	function resetFilters() {
		if (!withoutFilters) table.setColumnFilters([]);
		table.setGlobalFilter('');
	}

	// Styled/unstyled differ only in wrapper chrome; the inner table/mobile/pagination tree is shared.
	const shellClass = $derived(
		unstyled ? 'flex h-full min-h-0 flex-col' : 'bg-background/60 flex h-full min-h-0 flex-col overflow-hidden rounded-xl border'
	);
	const toolbarWrapClass = $derived(unstyled ? 'w-full shrink-0 border-b' : 'border-border/50 w-full shrink-0 border-b');
</script>

{#snippet PaginationSnippet()}
	<ArcaneTablePagination {items} {currentPage} {totalPages} {totalItems} {pageSize} {canPrev} {canNext} {setPage} {setPageSize} />
{/snippet}

{#snippet EmptySnippet()}
	{#if !isFiltered && emptyState}
		{@render emptyState()}
	{:else}
		<TableEmpty onClear={isFiltered ? resetFilters : undefined} />
	{/if}
{/snippet}

{#snippet MobileViewSnippet()}
	<ArcaneTableMobileView
		scrollElement={mobileScrollEl}
		initialScrollTop={scrollPositions.mobile.top}
		{rowIndex}
		{table}
		{mobileCard}
		{mobileFieldVisibility}
		groupedRows={effectiveGroupedRows}
		{groupIcon}
		{expandedRowContent}
		{expandedRows}
		onToggleRowExpanded={toggleRowExpanded}
		{loading}
		empty={EmptySnippet}
	/>
{/snippet}

{#if customTableView}
	{@render customTableView({ table, renderPagination: PaginationSnippet, mobileFieldsForOptions, onToggleMobileField })}
{:else}
	<div {@attach fitToViewport} class={shellClass}>
		{#if !withoutSearch}
			<div class={toolbarWrapClass}>
				<DataTableToolbar
					{table}
					{selectedIds}
					{selectionDisabled}
					{bulkActions}
					{withoutFilters}
					mobileFields={mobileFieldsForOptions}
					{onToggleMobileField}
					{customViewOptions}
					{customToolbarActions}
					{imageNameFilterOptions}
					{wrapText}
					onToggleWrapText={toggleWrapText}
					{isFiltered}
					onResetFilters={resetFilters}
				/>
			</div>
		{/if}

		{#if items.failedEnvironments?.length}
			<div class="shrink-0 px-3 pt-3">
				<Alert.Root variant="warning-subtle" size="sm" icon={AlertTriangleIcon}>
					<div class="flex flex-wrap items-center justify-between gap-2">
						<Alert.Description>
							{m.all_environments_unavailable({
								environments: items.failedEnvironments
									.map(({ environment, message }) => `${environment.name} (${message})`)
									.join(', ')
							})}
						</Alert.Description>
						<ArcaneButton
							action="refresh"
							size="sm"
							customLabel={m.common_retry()}
							onClickPromise={async () =>
								handleApiResultWithCallbacks({ result: await tryCatch(onRefresh(requestOptions)), message: m.common_failed() })}
						/>
					</div>
				</Alert.Root>
			</div>
		{/if}

		{#if !isMobile.current}
			<div
				{@attach (node) => restoreScroll(node, 'desktop')}
				bind:this={desktopScrollEl}
				data-table-scroll="desktop"
				class="isolate h-full min-h-0 flex-1 overflow-auto bg-background"
			>
				<ArcaneTableDesktopView
					{rowIndex}
					{table}
					{selectedIdSet}
					initialScrollTop={scrollPositions.desktop.top}
					columnsCount={effectiveColumnsCount}
					groupedRows={effectiveGroupedRows}
					{groupIcon}
					{groupCollapsedState}
					{selectionDisabled}
					onGroupToggle={handleGroupToggle}
					{getGroupSelectionState}
					{onToggleGroupSelection}
					onToggleRowSelection={(id, selected, modifiers) => onToggleRow(selected, id, modifiers)}
					{unstyled}
					{expandedRowContent}
					{expandedRows}
					onToggleRowExpanded={toggleRowExpanded}
					scrollElement={desktopScrollEl}
					{loading}
					{wrapText}
					empty={EmptySnippet}
				/>
			</div>
		{:else}
			<div
				{@attach (node) => restoreScroll(node, 'mobile')}
				bind:this={mobileScrollEl}
				data-table-scroll="mobile"
				class="isolate block min-h-0 flex-1 overflow-auto bg-background/80"
			>
				{#if unstyled}
					<div class="divide-y divide-border/40">
						{@render MobileViewSnippet()}
					</div>
				{:else}
					{@render MobileViewSnippet()}
				{/if}
			</div>
		{/if}

		{#if !withoutPagination}
			<nav aria-label={m.table_pagination_bottom()} class="shrink-0 border-t border-border/50 px-4 py-3">
				{@render PaginationSnippet()}
			</nav>
		{/if}
	</div>
{/if}