@warkypublic/svelix 0.1.46 → 0.2.1

package/dist/components/CardGrid/CardGrid.svelte

@@ -1,644 +1,503 @@
-<script lang="ts">
-	import { untrack } from 'svelte';
-	import type { Snippet } from 'svelte';
-	import { createVirtualizer, type SvelteVirtualizer } from '@tanstack/svelte-virtual';
-	import BetterMenu from '../BetterMenu/BetterMenu.svelte';
-	import type { BetterMenuInstanceItem } from '../BetterMenu/types.js';
-	import { GridlerResolveSpecAdapter } from '../Gridler/adapters/GridlerResolveSpecAdapter.js';
-	import { GridlerRestHeaderSpecAdapter } from '../Gridler/adapters/GridlerRestHeaderSpecAdapter.js';
-	import {
-		gridColumnFiltersToFilterOptions,
-		buildSearchFilters,
-		applyLocalFilter,
-	} from '../Gridler/utils/filters.js';
-	import { applyLocalSort, sortOrderToSortOptions } from '../Gridler/utils/sort.js';
-	import type { GridlerAdapterConfig, GridlerColumn } from '../Gridler/types.js';
-	import type { FilterOption } from '@warkypublic/resolvespec-js';
-	import CardGridFilterPanel from './CardGridFilterPanel.svelte';
-	import DefaultCard from './DefaultCard.svelte';
-	import {
-		toggleItemInSelection,
-		rangeSelect,
-		isItemSelected,
-		computeColumnsInRow,
-	} from './cardGrid.js';
-	import type {
-		CardGridColumn,
-		CardSortOption,
-		CardGridContextMenuItem,
-	} from './cardGrid.js';
-	import type { GridColumnSortOrder, GridColumnFilters } from '../Types/generic_grid.js';
-
-	interface Props {
-		// Column / display
-		columns: CardGridColumn[];
-		displayColumns?: string[];
-		cardMinWidth?: number;
-		cardGap?: number;
-		/**
-		 * Maximum number of columns shown on the front face.
-		 * When `resolvedColumns.length` exceeds this, a flip button appears and the
-		 * remaining columns are shown on the card's back face.
-		 */
-		cardMaxFrontColumns?: number;
-
-		// Custom rendering
-		/** Front-face snippet: (record, index, selected, focused) */
-		card?: Snippet<[Record<string, unknown>, number, boolean, boolean]>;
-		/** Back-face snippet for flip mode: (record, index, selected, focused) */
-		cardBack?: Snippet<[Record<string, unknown>, number, boolean, boolean]>;
-		empty?: Snippet;
-		skeleton?: Snippet;
-
-		// Data source
-		dataSource?: 'resolvespec' | 'headerspec' | 'local';
-		dataSourceOptions?: {
-			url?: string;
-			authToken?: string;
-			schema?: string;
-			entity?: string;
-			uniqueID?: string;
-			hotfields?: string[];
-			extraOptions?: Record<string, unknown>;
-		};
-		data?: Record<string, unknown>[] | (() => Promise<Record<string, unknown>[]>);
-		pageSize?: number;
-		uniqueID?: string;
-
-		// Search
-		searchValue?: string;
-		onSearchValueChange?: (v: string) => void;
-		serverSideSearch?: boolean;
-		searchColumns?: string[];
-		searchPlaceholder?: string;
-
-		// Sort
-		sortOrder?: GridColumnSortOrder;
-		onSortOrderChange?: (order: GridColumnSortOrder) => void;
-		sortOptions?: CardSortOption[];
-
-		// Filters
-		filters?: GridColumnFilters;
-		onFilterChange?: (filters: GridColumnFilters) => void;
-
-		// Selection
-		selectedItems?: Record<string, unknown>[];
-		onSelectedItemsChange?: (items: Record<string, unknown>[]) => void;
-		multiSelect?: boolean;
-
-		// Card events
-		onCardClick?: (record: Record<string, unknown>, index: number) => void;
-		onCardDblClick?: (record: Record<string, unknown>, index: number) => void;
-		onCardContextMenu?: (
-			record: Record<string, unknown>,
-			index: number,
-			x: number,
-			y: number,
-		) => void;
-
-		// Context menu
-		menuItems?: CardGridContextMenuItem[];
-
-		// Status (bindable)
-		total?: number;
-		loading?: boolean;
-		onLoadError?: (error: string) => void;
-
-		// Layout
-		class?: string;
-		toolbarEnd?: Snippet;
+<script lang="ts">import { untrack } from "svelte";
+import { SvelteSet } from "svelte/reactivity";
+import { createVirtualizer } from "@tanstack/svelte-virtual";
+import BetterMenu from "../BetterMenu/BetterMenu.svelte";
+import { GridlerResolveSpecAdapter } from "../Gridler/adapters/GridlerResolveSpecAdapter.js";
+import { GridlerRestHeaderSpecAdapter } from "../Gridler/adapters/GridlerRestHeaderSpecAdapter.js";
+import { gridColumnFiltersToFilterOptions, buildSearchFilters, applyLocalFilter } from "../Gridler/utils/filters.js";
+import { applyLocalSort, sortOrderToSortOptions } from "../Gridler/utils/sort.js";
+import CardGridFilterPanel from "./CardGridFilterPanel.svelte";
+import DefaultCard from "./DefaultCard.svelte";
+import { toggleItemInSelection, rangeSelect, isItemSelected, computeColumnsInRow } from "./cardGrid.js";
+let { columns, displayColumns, cardMinWidth = 280, cardGap = 16, cardMaxFrontColumns, card, cardBack, empty, skeleton, dataSource = "local", dataSourceOptions, data, pageSize = 20, uniqueID: uniqueIDProp, searchValue, onSearchValueChange, serverSideSearch = true, searchColumns, searchPlaceholder = "Search…", sortOrder, onSortOrderChange, sortOptions, filters, onFilterChange, selectedItems: selectedItemsProp, onSelectedItemsChange, multiSelect = true, onCardClick, onCardDblClick, onCardContextMenu, menuItems, total = $bindable(0), loading = $bindable(false), onLoadError, class: cls, toolbarEnd, animate: animateProp, density: densityProp, expand: expandProp } = $props();
+// ── Animation defaults ──────────────────────────────────────────────
+const animateEnabled = $derived(animateProp ?? true);
+// ── Density/expand defaults ─────────────────────────────────────────────
+const densityMode = $derived(densityProp ?? "default");
+const expandMode = $derived(expandProp ?? "none");
+// ── Derived config ─────────────────────────────────────────────────────────
+const resolvedUniqueID = $derived(uniqueIDProp ?? dataSourceOptions?.uniqueID ?? "id");
+const resolvedColumns = $derived(displayColumns?.length ? columns.filter((c) => displayColumns?.includes(c.id)) : columns);
+// Flip mode split
+const frontColumns = $derived(cardMaxFrontColumns != null ? resolvedColumns.slice(0, cardMaxFrontColumns) : resolvedColumns);
+const backColumns = $derived(cardMaxFrontColumns != null ? resolvedColumns.slice(cardMaxFrontColumns) : []);
+const flipModeEnabled = $derived(backColumns.length > 0);
+// How many detail rows the skeleton should mimic
+const skeletonDetailRows = $derived(Math.max(0, frontColumns.length - 2));
+// ── Controlled/uncontrolled search ─────────────────────────────────────────
+let internalSearchValue = $state("");
+const resolvedSearchValue = $derived(searchValue ?? internalSearchValue);
+function emitSearchValue(v) {
+	if (searchValue === undefined) internalSearchValue = v;
+	onSearchValueChange?.(v);
+}
+// ── Controlled/uncontrolled filters ───────────────────────────────────────
+let internalFilters = $state({});
+const resolvedFilters = $derived(filters ?? internalFilters);
+function handleFilterChange(next) {
+	if (filters === undefined) internalFilters = next;
+	onFilterChange?.(next);
+}
+// ── Controlled/uncontrolled sort ──────────────────────────────────────────
+let internalSortOrder = $state({});
+const resolvedSortOrder = $derived(sortOrder ?? internalSortOrder);
+function handleSortOrderChange(order) {
+	if (sortOrder === undefined) internalSortOrder = order;
+	onSortOrderChange?.(order);
+}
+const resolvedSort = $derived(Object.values(resolvedSortOrder).some((d) => d !== "none") ? sortOrderToSortOptions(resolvedSortOrder) : []);
+// ── Density/expand resolution ───────────────────────────────────────────
+const densityMinWidth = $derived(densityMode === "compact" ? 200 : densityMode === "spacious" ? 400 : densityMode === "comfortable" ? 340 : cardMinWidth);
+const densityGap = $derived(densityMode === "compact" ? 8 : densityMode === "spacious" ? 32 : densityMode === "comfortable" ? 24 : cardGap);
+// Expand multiplies the effective min-width/gap per-card
+const expandFactor = $derived(expandMode === "none" ? 1 : expandMode === "medium" ? 1.5 : 2);
+// ── Controlled/uncontrolled selection ─────────────────────────────────────
+let internalSelectedItems = $state([]);
+const resolvedSelectedItems = $derived(selectedItemsProp ?? internalSelectedItems);
+function setSelectedItems(items) {
+	if (selectedItemsProp === undefined) internalSelectedItems = items;
+	onSelectedItemsChange?.(items);
+}
+// ── Local data path ────────────────────────────────────────────────────────
+let localData = $state([]);
+let localLoading = $state(false);
+$effect(() => {
+	if (dataSource !== "local") return;
+	if (typeof data === "function") {
+		localLoading = true;
+		data().then((d) => {
+			localData = d;
+		}).catch((e) => {
+			onLoadError?.(e instanceof Error ? e.message : "Failed to load data");
+		}).finally(() => {
+			localLoading = false;
+		});
+	} else if (Array.isArray(data)) {
+		localData = data;
+	} else {
+		localData = [];
 	}
-
-	let {
-		columns,
-		displayColumns,
-		cardMinWidth = 280,
-		cardGap = 16,
-		cardMaxFrontColumns,
-		card,
-		cardBack,
-		empty,
-		skeleton,
-		dataSource = 'local',
-		dataSourceOptions,
-		data,
-		pageSize = 20,
-		uniqueID: uniqueIDProp,
-		searchValue,
-		onSearchValueChange,
-		serverSideSearch = true,
-		searchColumns,
-		searchPlaceholder = 'Search…',
-		sortOrder,
-		onSortOrderChange,
-		sortOptions,
-		filters,
-		onFilterChange,
-		selectedItems: selectedItemsProp,
-		onSelectedItemsChange,
-		multiSelect = true,
-		onCardClick,
-		onCardDblClick,
-		onCardContextMenu,
-		menuItems,
-		total = $bindable(0),
-		loading = $bindable(false),
-		onLoadError,
-		class: cls,
-		toolbarEnd,
-	}: Props = $props();
-
-	// ── Derived config ─────────────────────────────────────────────────────────
-
-	const resolvedUniqueID = $derived(uniqueIDProp ?? dataSourceOptions?.uniqueID ?? 'id');
-
-	const resolvedColumns = $derived(
-		displayColumns?.length ? columns.filter((c) => displayColumns!.includes(c.id)) : columns,
-	);
-
-	// Flip mode split
-	const frontColumns = $derived(
-		cardMaxFrontColumns != null ? resolvedColumns.slice(0, cardMaxFrontColumns) : resolvedColumns,
-	);
-	const backColumns = $derived(
-		cardMaxFrontColumns != null ? resolvedColumns.slice(cardMaxFrontColumns) : [],
-	);
-	const flipModeEnabled = $derived(backColumns.length > 0);
-
-	// How many detail rows the skeleton should mimic
-	const skeletonDetailRows = $derived(Math.max(0, frontColumns.length - 2));
-
-	// ── Controlled/uncontrolled search ─────────────────────────────────────────
-
-	let internalSearchValue = $state('');
-	const resolvedSearchValue = $derived(searchValue ?? internalSearchValue);
-
-	function emitSearchValue(v: string) {
-		if (searchValue === undefined) internalSearchValue = v;
-		onSearchValueChange?.(v);
+});
+const asCols = (cols) => cols;
+const localSorted = $derived(applyLocalSort(localData, resolvedSort, asCols(columns)));
+const localFiltered = $derived(applyLocalFilter(localSorted, resolvedFilters, asCols(columns)));
+const localSearched = $derived.by(() => {
+	if (!resolvedSearchValue.trim() || serverSideSearch && isServerMode) return localFiltered;
+	const q = resolvedSearchValue.trim().toLowerCase();
+	const searchCols = searchColumns?.length ? searchColumns : columns.filter((c) => !c.disableSearch).map((c) => c.id);
+	return localFiltered.filter((row) => searchCols.some((colId) => {
+		const col = columns.find((c) => c.id === colId);
+		const key = col?.dataKey ?? colId;
+		const val = getNestedVal(key, row);
+		return val != null && String(val).toLowerCase().includes(q);
+	}));
+});
+function getNestedVal(key, row) {
+	const parts = key.split(".");
+	let val = row;
+	for (const part of parts) {
+		if (val == null || typeof val !== "object") return undefined;
+		val = val[part];
 	}
-
-	// ── Controlled/uncontrolled filters ───────────────────────────────────────
-
-	let internalFilters = $state<GridColumnFilters>({});
-	const resolvedFilters = $derived(filters ?? internalFilters);
-
-	function handleFilterChange(next: GridColumnFilters) {
-		if (filters === undefined) internalFilters = next;
-		onFilterChange?.(next);
+	return val;
+}
+// ── Server state ───────────────────────────────────────────────────────────
+let serverData = $state([]);
+let serverTotal = $state(0);
+let serverCursor = $state(undefined);
+let serverFetchVersion = 0;
+let serverLoading = $state(false);
+let serverAllLoaded = $state(false);
+let refreshTrigger = $state(0);
+$effect(() => {
+	total = serverTotal;
+});
+$effect(() => {
+	loading = serverLoading || localLoading;
+});
+const isServerMode = $derived(dataSource !== "local");
+const serverAdapter = $derived.by(() => {
+	if (!isServerMode) return null;
+	const url = dataSourceOptions?.url;
+	const schema = dataSourceOptions?.schema;
+	const entity = dataSourceOptions?.entity;
+	if (!url || !schema || !entity) return null;
+	const config = {
+		url,
+		token: dataSourceOptions?.authToken,
+		schema,
+		entity,
+		uniqueID: resolvedUniqueID,
+		extraOptions: dataSourceOptions?.extraOptions
+	};
+	return dataSource === "headerspec" ? new GridlerRestHeaderSpecAdapter(config) : new GridlerResolveSpecAdapter(config);
+});
+const resolvedFields = $derived.by(() => {
+	const colFields = columns.map((c) => c.dataKey ?? c.id);
+	const hotfields = dataSourceOptions?.hotfields ?? [];
+	const seen = new Set(colFields);
+	return [...colFields, ...hotfields.filter((f) => !seen.has(f))];
+});
+function buildAllFilters(search) {
+	const base = Object.keys(resolvedFilters).length ? gridColumnFiltersToFilterOptions(resolvedFilters) : [];
+	if (!search?.trim()) return base;
+	const searchCols = searchColumns?.length ? searchColumns : columns.filter((c) => !c.disableSearch).map((c) => c.id);
+	return [...base, ...buildSearchFilters(search, asCols([]), searchCols)];
+}
+$effect(() => {
+	const _adapter = serverAdapter;
+	const _sort = resolvedSort;
+	const _search = serverSideSearch ? resolvedSearchValue : null;
+	const _pageSize = pageSize;
+	const _filters = resolvedFilters;
+	const _refresh = refreshTrigger;
+	void _refresh;
+	if (!_adapter) return;
+	let cancelled = false;
+	serverFetchVersion++;
+	serverLoading = true;
+	serverData = [];
+	serverTotal = 0;
+	serverCursor = undefined;
+	serverAllLoaded = false;
+	_adapter.readPage(_pageSize, undefined, _sort, buildAllFilters(_search), untrack(() => resolvedFields)).then((result) => {
+		if (cancelled) return;
+		serverData = result.data;
+		serverTotal = result.total;
+		serverCursor = result.nextCursor;
+		serverAllLoaded = result.data.length < _pageSize || !result.nextCursor;
+	}).catch((e) => {
+		if (!cancelled) onLoadError?.(e instanceof Error ? e.message : "Failed to load data");
+	}).finally(() => {
+		if (!cancelled) serverLoading = false;
+	});
+	return () => {
+		cancelled = true;
+	};
+});
+async function loadNextPage() {
+	const _adapter = serverAdapter;
+	if (!_adapter || serverLoading || serverAllLoaded || !serverCursor) return;
+	const cursorSnapshot = serverCursor;
+	const versionSnapshot = serverFetchVersion;
+	serverLoading = true;
+	try {
+		const result = await _adapter.readPage(pageSize, cursorSnapshot, resolvedSort, buildAllFilters(serverSideSearch ? resolvedSearchValue : null), resolvedFields);
+		if (serverFetchVersion !== versionSnapshot) return;
+		serverData = [...serverData, ...result.data];
+		serverCursor = result.nextCursor;
+		serverAllLoaded = result.data.length < pageSize || !result.nextCursor || result.nextCursor === cursorSnapshot;
+	} catch (e) {
+		onLoadError?.(e instanceof Error ? e.message : "Failed to load page");
+	} finally {
+		serverLoading = false;
 	}
-
-	// ── Controlled/uncontrolled sort ──────────────────────────────────────────
-
-	let internalSortOrder = $state<GridColumnSortOrder>({});
-	const resolvedSortOrder = $derived(sortOrder ?? internalSortOrder);
-
-	function handleSortOrderChange(order: GridColumnSortOrder) {
-		if (sortOrder === undefined) internalSortOrder = order;
-		onSortOrderChange?.(order);
+}
+// ── Display data ───────────────────────────────────────────────────────────
+const displayData = $derived(isServerMode ? serverData : localSearched);
+// ── UI state ───────────────────────────────────────────────────────────────
+let focusedIndex = $state(-1);
+let anchorIndex = $state(-1);
+let columnsInRow = $state(1);
+let containerEl = $state(null);
+let sentinelEl = $state(null);
+let searchInputEl = $state(null);
+let filterBtnEl = $state(null);
+let menu = $state(null);
+// Per-card flip state
+let flippedCards = new SvelteSet();
+function toggleFlip(e, item) {
+	e.stopPropagation();
+	const id = item[resolvedUniqueID];
+	if (flippedCards.has(id)) {
+		flippedCards.delete(id);
+	} else {
+		flippedCards.add(id);
 	}
-
-	const resolvedSort = $derived(
-		Object.values(resolvedSortOrder).some((d) => d !== 'none')
-			? sortOrderToSortOptions(resolvedSortOrder)
-			: [],
-	);
-
-	// ── Controlled/uncontrolled selection ─────────────────────────────────────
-
-	let internalSelectedItems = $state<Record<string, unknown>[]>([]);
-	const resolvedSelectedItems = $derived(selectedItemsProp ?? internalSelectedItems);
-
-	function setSelectedItems(items: Record<string, unknown>[]) {
-		if (selectedItemsProp === undefined) internalSelectedItems = items;
-		onSelectedItemsChange?.(items);
-	}
-
-	// ── Local data path ────────────────────────────────────────────────────────
-
-	let localData = $state<Record<string, unknown>[]>([]);
-	let localLoading = $state(false);
-
-	$effect(() => {
-		if (dataSource !== 'local') return;
-		if (typeof data === 'function') {
-			localLoading = true;
-			(data as () => Promise<Record<string, unknown>[]>)()
-				.then((d) => { localData = d; })
-				.catch((e) => { onLoadError?.(e instanceof Error ? e.message : 'Failed to load data'); })
-				.finally(() => { localLoading = false; });
-		} else if (Array.isArray(data)) {
-			localData = data as Record<string, unknown>[];
-		} else {
-			localData = [];
-		}
+}
+$effect(() => {
+	if (!containerEl) return;
+	const obs = new ResizeObserver((entries) => {
+		columnsInRow = computeColumnsInRow(entries[0]?.contentRect.width ?? 0, densityMinWidth * expandFactor, densityGap * expandFactor);
 	});
-
-	type _GC = GridlerColumn;
-	const asCols = (cols: CardGridColumn[]) => cols as unknown as _GC[];
-
-	const localSorted   = $derived(applyLocalSort(localData, resolvedSort, asCols(columns)));
-	const localFiltered = $derived(applyLocalFilter(localSorted, resolvedFilters, asCols(columns)));
-
-	const localSearched = $derived.by(() => {
-		if (!resolvedSearchValue.trim() || (serverSideSearch && isServerMode)) return localFiltered;
-		const q = resolvedSearchValue.trim().toLowerCase();
-		const searchCols = searchColumns?.length
-			? searchColumns
-			: columns.filter((c) => !c.disableSearch).map((c) => c.id);
-		return localFiltered.filter((row) =>
-			searchCols.some((colId) => {
-				const col = columns.find((c) => c.id === colId);
-				const key = col?.dataKey ?? colId;
-				const val = getNestedVal(key, row);
-				return val != null && String(val).toLowerCase().includes(q);
-			}),
-		);
+	obs.observe(containerEl);
+	return () => obs.disconnect();
+});
+$effect(() => {
+	if (!sentinelEl || !isServerMode) return;
+	const obs = new IntersectionObserver((entries) => {
+		if (entries[0]?.isIntersecting) loadNextPage();
+	}, { rootMargin: "200px" });
+	obs.observe(sentinelEl);
+	return () => obs.disconnect();
+});
+// ── Selection ──────────────────────────────────────────────────────────────
+function handleCardClick(e, item, index) {
+	focusedIndex = index;
+	if (!multiSelect) {
+		setSelectedItems([item]);
+		anchorIndex = index;
+		onCardClick?.(item, index);
+		return;
+	}
+	if (e.shiftKey && anchorIndex >= 0) {
+		setSelectedItems(rangeSelect(displayData, anchorIndex, index));
+	} else if (e.ctrlKey || e.metaKey) {
+		setSelectedItems(toggleItemInSelection(resolvedSelectedItems, item, resolvedUniqueID));
+		anchorIndex = index;
+	} else {
+		setSelectedItems([item]);
+		anchorIndex = index;
+	}
+	onCardClick?.(item, index);
+}
+function handleCardContextMenu(e, item, index) {
+	e.preventDefault();
+	onCardContextMenu?.(item, index, e.clientX, e.clientY);
+	menu?.show("cg-context-menu", {
+		x: e.clientX,
+		y: e.clientY,
+		items: buildContextMenuItems(item)
 	});
-
-	function getNestedVal(key: string, row: Record<string, unknown>): unknown {
-		const parts = key.split('.');
-		let val: unknown = row;
-		for (const part of parts) {
-			if (val == null || typeof val !== 'object') return undefined;
-			val = (val as Record<string, unknown>)[part];
+}
+function handleContainerClick(e) {
+	if (e.target === e.currentTarget) {
+		setSelectedItems([]);
+		focusedIndex = -1;
+	}
+}
+// ── Context menu ───────────────────────────────────────────────────────────
+function buildContextMenuItems(item) {
+	const items = [];
+	if (menuItems?.length) {
+		for (const mi of menuItems) {
+			if (mi.kind === "separator") {
+				items.push({ isDivider: true });
+			} else {
+				items.push({
+					label: mi.label,
+					onClick: mi.disabled ? undefined : () => mi.onselect?.(item)
+				});
+			}
 		}
-		return val;
+		items.push({ isDivider: true });
 	}
-
-	// ── Server state ───────────────────────────────────────────────────────────
-
-	let serverData       = $state<Record<string, unknown>[]>([]);
-	let serverTotal      = $state(0);
-	let serverCursor     = $state<string | undefined>(undefined);
-	let serverFetchVersion = 0;
-	let serverLoading    = $state(false);
-	let serverAllLoaded  = $state(false);
-	let refreshTrigger   = $state(0);
-
-	$effect(() => { total   = serverTotal; });
-	$effect(() => { loading = serverLoading || localLoading; });
-
-	const isServerMode = $derived(dataSource !== 'local');
-
-	const serverAdapter = $derived.by(() => {
-		if (!isServerMode) return null;
-		const url    = dataSourceOptions?.url;
-		const schema = dataSourceOptions?.schema;
-		const entity = dataSourceOptions?.entity;
-		if (!url || !schema || !entity) return null;
-		const config: GridlerAdapterConfig = {
-			url, token: dataSourceOptions?.authToken, schema, entity,
-			uniqueID: resolvedUniqueID,
-			extraOptions: dataSourceOptions?.extraOptions as GridlerAdapterConfig['extraOptions'],
-		};
-		return dataSource === 'headerspec'
-			? new GridlerRestHeaderSpecAdapter(config)
-			: new GridlerResolveSpecAdapter(config);
+	items.push({
+		label: "Refresh",
+		onClick: () => refresh()
 	});
-
-	const resolvedFields = $derived.by(() => {
-		const colFields = columns.map((c) => c.dataKey ?? c.id);
-		const hotfields = dataSourceOptions?.hotfields ?? [];
-		const seen = new Set(colFields);
-		return [...colFields, ...hotfields.filter((f) => !seen.has(f))];
+	if (resolvedSearchValue) items.push({
+		label: "Clear search",
+		onClick: () => emitSearchValue("")
 	});
-
-	function buildAllFilters(search: string | null): FilterOption[] {
-		const base = Object.keys(resolvedFilters).length
-			? gridColumnFiltersToFilterOptions(resolvedFilters) : [];
-		if (!search?.trim()) return base;
-		const searchCols = searchColumns?.length
-			? searchColumns
-			: columns.filter((c) => !c.disableSearch).map((c) => c.id);
-		return [...base, ...buildSearchFilters(search, asCols([]), searchCols)];
-	}
-
-	$effect(() => {
-		const _adapter  = serverAdapter;
-		const _sort     = resolvedSort;
-		const _search   = serverSideSearch ? resolvedSearchValue : null;
-		const _pageSize = pageSize;
-		const _filters  = resolvedFilters;
-		const _refresh  = refreshTrigger;
-		void _refresh;
-
-		if (!_adapter) return;
-
-		let cancelled = false;
-		serverFetchVersion++;
-		serverLoading   = true;
-		serverData      = [];
-		serverTotal     = 0;
-		serverCursor    = undefined;
-		serverAllLoaded = false;
-
-		_adapter
-			.readPage(_pageSize, undefined, _sort, buildAllFilters(_search), untrack(() => resolvedFields))
-			.then((result) => {
-				if (cancelled) return;
-				serverData      = result.data;
-				serverTotal     = result.total;
-				serverCursor    = result.nextCursor;
-				serverAllLoaded = result.data.length < _pageSize || !result.nextCursor;
-			})
-			.catch((e) => { if (!cancelled) onLoadError?.(e instanceof Error ? e.message : 'Failed to load data'); })
-			.finally(() => { if (!cancelled) serverLoading = false; });
-
-		return () => { cancelled = true; };
+	if (Object.keys(resolvedFilters).length > 0) items.push({
+		label: "Clear filters",
+		onClick: () => handleFilterChange({})
 	});
-
-	async function loadNextPage() {
-		const _adapter = serverAdapter;
-		if (!_adapter || serverLoading || serverAllLoaded || !serverCursor) return;
-		const cursorSnapshot  = serverCursor;
-		const versionSnapshot = serverFetchVersion;
-		serverLoading = true;
-		try {
-			const result = await _adapter.readPage(
-				pageSize, cursorSnapshot, resolvedSort,
-				buildAllFilters(serverSideSearch ? resolvedSearchValue : null), resolvedFields,
-			);
-			if (serverFetchVersion !== versionSnapshot) return;
-			serverData      = [...serverData, ...result.data];
-			serverCursor    = result.nextCursor;
-			serverAllLoaded = result.data.length < pageSize || !result.nextCursor || result.nextCursor === cursorSnapshot;
-		} catch (e) {
-			onLoadError?.(e instanceof Error ? e.message : 'Failed to load page');
-		} finally {
-			serverLoading = false;
-		}
-	}
-
-	// ── Display data ───────────────────────────────────────────────────────────
-
-	const displayData = $derived(isServerMode ? serverData : localSearched);
-
-	// ── UI state ───────────────────────────────────────────────────────────────
-
-	let focusedIndex   = $state(-1);
-	let anchorIndex    = $state(-1);
-	let columnsInRow   = $state(1);
-	let containerEl    = $state<HTMLElement | null>(null);
-	let sentinelEl     = $state<HTMLElement | null>(null);
-	let searchInputEl  = $state<HTMLInputElement | null>(null);
-	let filterBtnEl    = $state<HTMLButtonElement | null>(null);
-	let menu           = $state<BetterMenu | null>(null);
-
-	// Per-card flip state
-	let flippedCards = $state(new Set<unknown>());
-
-	function toggleFlip(e: MouseEvent, item: Record<string, unknown>) {
-		e.stopPropagation();
-		const id   = item[resolvedUniqueID];
-		const next = new Set(flippedCards);
-		next.has(id) ? next.delete(id) : next.add(id);
-		flippedCards = next;
-	}
-
-	$effect(() => {
-		if (!containerEl) return;
-		const obs = new ResizeObserver((entries) => {
-			columnsInRow = computeColumnsInRow(entries[0]?.contentRect.width ?? 0, cardMinWidth, cardGap);
-		});
-		obs.observe(containerEl);
-		return () => obs.disconnect();
+	if (Object.values(resolvedSortOrder).some((d) => d !== "none")) items.push({
+		label: "Clear sort",
+		onClick: () => handleSortOrderChange({})
 	});
-
-	$effect(() => {
-		if (!sentinelEl || !isServerMode) return;
-		const obs = new IntersectionObserver(
-			(entries) => { if (entries[0]?.isIntersecting) loadNextPage(); },
-			{ rootMargin: '200px' },
-		);
-		obs.observe(sentinelEl);
-		return () => obs.disconnect();
+	return items;
+}
+// ── Filter panel ───────────────────────────────────────────────────────────
+const activeFilterCount = $derived(Object.keys(resolvedFilters).length);
+function openFilterPanel() {
+	if (!filterBtnEl) return;
+	const rect = filterBtnEl.getBoundingClientRect();
+	menu?.show("cg-filter-panel", {
+		x: rect.left,
+		y: rect.bottom + 4,
+		renderer: filterPanelSnippet
 	});
-
-	// ── Selection ──────────────────────────────────────────────────────────────
-
-	function handleCardClick(e: MouseEvent, item: Record<string, unknown>, index: number) {
-		focusedIndex = index;
-		if (!multiSelect) {
-			setSelectedItems([item]);
-			anchorIndex = index;
-			onCardClick?.(item, index);
-			return;
+}
+// ── Sort pills ─────────────────────────────────────────────────────────────
+function toggleSortOption(columnId) {
+	const current = resolvedSortOrder[columnId] ?? "none";
+	const next = current === "none" ? "asc" : current === "asc" ? "desc" : "none";
+	const newOrder = { ...resolvedSortOrder };
+	if (next === "none") delete newOrder[columnId];
+	else newOrder[columnId] = next;
+	handleSortOrderChange(newOrder);
+}
+// ── Keyboard navigation ────────────────────────────────────────────────────
+function moveFocus(next) {
+	focusedIndex = next;
+	scrollToCard(next);
+	if (!multiSelect) {
+		const item = displayData[next];
+		if (item) setSelectedItems([item]);
+	}
+}
+function handleKeyDown(e) {
+	const count = displayData.length;
+	if (count === 0) return;
+	switch (e.key) {
+		case "ArrowLeft":
+			e.preventDefault();
+			moveFocus(Math.max(0, focusedIndex - 1));
+			break;
+		case "ArrowRight":
+			e.preventDefault();
+			moveFocus(Math.min(count - 1, focusedIndex + 1));
+			break;
+		case "ArrowUp":
+			e.preventDefault();
+			moveFocus(Math.max(0, focusedIndex - columnsInRow));
+			break;
+		case "ArrowDown":
+			e.preventDefault();
+			moveFocus(Math.min(count - 1, focusedIndex + columnsInRow));
+			break;
+		case "Tab":
+			e.preventDefault();
+			moveFocus(e.shiftKey ? Math.max(0, focusedIndex - 1) : Math.min(count - 1, focusedIndex + 1));
+			break;
+		case "Enter": {
+			if (focusedIndex >= 0) {
+				const item = displayData[focusedIndex];
+				if (item) onCardClick?.(item, focusedIndex);
+			}
+			break;
 		}
-		if (e.shiftKey && anchorIndex >= 0) {
-			setSelectedItems(rangeSelect(displayData, anchorIndex, index));
-		} else if (e.ctrlKey || e.metaKey) {
-			setSelectedItems(toggleItemInSelection(resolvedSelectedItems, item, resolvedUniqueID));
-			anchorIndex = index;
-		} else {
-			setSelectedItems([item]);
-			anchorIndex = index;
+		case " ": {
+			e.preventDefault();
+			if (focusedIndex >= 0) {
+				const item = displayData[focusedIndex];
+				if (item) setSelectedItems(multiSelect ? toggleItemInSelection(resolvedSelectedItems, item, resolvedUniqueID) : [item]);
+			}
+			break;
 		}
-		onCardClick?.(item, index);
-	}
-
-	function handleCardContextMenu(e: MouseEvent, item: Record<string, unknown>, index: number) {
-		e.preventDefault();
-		onCardContextMenu?.(item, index, e.clientX, e.clientY);
-		menu?.show('cg-context-menu', {
-			x: e.clientX, y: e.clientY,
-			items: buildContextMenuItems(item),
-		});
-	}
-
-	function handleContainerClick(e: MouseEvent) {
-		if (e.target === e.currentTarget) {
+		case "Escape":
 			setSelectedItems([]);
 			focusedIndex = -1;
-		}
-	}
-
-	// ── Context menu ───────────────────────────────────────────────────────────
-
-	function buildContextMenuItems(item: Record<string, unknown>): BetterMenuInstanceItem[] {
-		const items: BetterMenuInstanceItem[] = [];
-		if (menuItems?.length) {
-			for (const mi of menuItems) {
-				if (mi.kind === 'separator') {
-					items.push({ isDivider: true });
-				} else {
-					items.push({ label: mi.label, onClick: mi.disabled ? undefined : () => mi.onselect?.(item) });
-				}
+			break;
+		case "a":
+		case "A":
+			if ((e.ctrlKey || e.metaKey) && multiSelect) {
+				e.preventDefault();
+				setSelectedItems([...displayData]);
 			}
-			items.push({ isDivider: true });
-		}
-		items.push({ label: 'Refresh', onClick: () => refresh() });
-		if (resolvedSearchValue)
-			items.push({ label: 'Clear search', onClick: () => emitSearchValue('') });
-		if (Object.keys(resolvedFilters).length > 0)
-			items.push({ label: 'Clear filters', onClick: () => handleFilterChange({}) });
-		if (Object.values(resolvedSortOrder).some((d) => d !== 'none'))
-			items.push({ label: 'Clear sort', onClick: () => handleSortOrderChange({}) });
-		return items;
+			break;
+		case "f":
+		case "F":
+			if (e.ctrlKey || e.metaKey) {
+				e.preventDefault();
+				searchInputEl?.focus();
+			}
+			break;
 	}
-
-	// ── Filter panel ───────────────────────────────────────────────────────────
-
-	const activeFilterCount = $derived(Object.keys(resolvedFilters).length);
-
-	function openFilterPanel() {
-		if (!filterBtnEl) return;
-		const rect = filterBtnEl.getBoundingClientRect();
-		menu?.show('cg-filter-panel', {
-			x: rect.left, y: rect.bottom + 4,
-			renderer: filterPanelSnippet as unknown as (props: Record<string, unknown>) => unknown,
+}
+function scrollToCard(index) {
+	if (virtualizerInstance) {
+		const rowIndex = Math.floor(index / Math.max(1, columnsInRow));
+		virtualizerInstance.scrollToIndex(rowIndex, {
+			align: "auto",
+			behavior: "smooth"
+		});
+	} else {
+		containerEl?.querySelector(`[data-card-index="${index}"]`)?.scrollIntoView({
+			block: "nearest",
+			behavior: "smooth"
 		});
 	}
-
-	// ── Sort pills ─────────────────────────────────────────────────────────────
-
-	function toggleSortOption(columnId: string) {
-		const current = resolvedSortOrder[columnId] ?? 'none';
-		const next    = current === 'none' ? 'asc' : current === 'asc' ? 'desc' : ('none' as const);
-		const newOrder = { ...resolvedSortOrder };
-		if (next === 'none') delete newOrder[columnId]; else newOrder[columnId] = next;
-		handleSortOrderChange(newOrder);
-	}
-
-	// ── Keyboard navigation ────────────────────────────────────────────────────
-
-	function moveFocus(next: number) {
-		focusedIndex = next;
-		scrollToCard(next);
-		if (!multiSelect) {
-			const item = displayData[next];
-			if (item) setSelectedItems([item]);
-		}
+}
+export function selectItem(uniqueIDValue) {
+	const idx = displayData.findIndex((item) => item[resolvedUniqueID] === uniqueIDValue);
+	if (idx < 0) return false;
+	focusedIndex = idx;
+	scrollToCard(idx);
+	return true;
+}
+export function refresh() {
+	if (isServerMode) {
+		refreshTrigger++;
+	} else if (typeof data === "function") {
+		localLoading = true;
+		data().then((d) => {
+			localData = d;
+		}).catch((e) => {
+			onLoadError?.(e instanceof Error ? e.message : "Failed to load data");
+		}).finally(() => {
+			localLoading = false;
+		});
 	}
-
-	function handleKeyDown(e: KeyboardEvent) {
-		const count = displayData.length;
-		if (count === 0) return;
-		switch (e.key) {
-			case 'ArrowLeft':  e.preventDefault(); moveFocus(Math.max(0, focusedIndex - 1)); break;
-			case 'ArrowRight': e.preventDefault(); moveFocus(Math.min(count - 1, focusedIndex + 1)); break;
-			case 'ArrowUp':    e.preventDefault(); moveFocus(Math.max(0, focusedIndex - columnsInRow)); break;
-			case 'ArrowDown':  e.preventDefault(); moveFocus(Math.min(count - 1, focusedIndex + columnsInRow)); break;
-			case 'Tab':
-				e.preventDefault();
-				moveFocus(e.shiftKey ? Math.max(0, focusedIndex - 1) : Math.min(count - 1, focusedIndex + 1));
-				break;
-			case 'Enter': {
-				if (focusedIndex >= 0) { const item = displayData[focusedIndex]; if (item) onCardClick?.(item, focusedIndex); }
-				break;
-			}
-			case ' ': {
-				e.preventDefault();
-				if (focusedIndex >= 0) {
-					const item = displayData[focusedIndex];
-					if (item) setSelectedItems(multiSelect
-						? toggleItemInSelection(resolvedSelectedItems, item, resolvedUniqueID)
-						: [item]);
-				}
-				break;
-			}
-			case 'Escape': setSelectedItems([]); focusedIndex = -1; break;
-			case 'a': case 'A':
-				if ((e.ctrlKey || e.metaKey) && multiSelect) { e.preventDefault(); setSelectedItems([...displayData]); }
-				break;
-			case 'f': case 'F':
-				if (e.ctrlKey || e.metaKey) { e.preventDefault(); searchInputEl?.focus(); }
-				break;
-		}
+}
+// Reconcile selection across refresh() — drop items no longer in displayData.
+// `internalSelectedItems` is read via untrack() so this effect doesn't depend on
+// its own write target — .filter() always returns a new array reference, which
+// would otherwise re-trigger this same effect forever (effect_update_depth_exceeded).
+$effect(() => {
+	if (displayData.length === 0) return;
+	const currentIds = new Set(displayData.map((item) => item[resolvedUniqueID]));
+	const current = untrack(() => internalSelectedItems);
+	const next = current.filter((item) => currentIds.has(item[resolvedUniqueID]));
+	if (next.length !== current.length) {
+		internalSelectedItems = next;
 	}
-
-	function scrollToCard(index: number) {
-		if (virtualizerInstance) {
-			const rowIndex = Math.floor(index / Math.max(1, columnsInRow));
-			virtualizerInstance.scrollToIndex(rowIndex, { align: 'auto', behavior: 'smooth' });
-		} else {
-			containerEl?.querySelector(`[data-card-index="${index}"]`)
-				?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-		}
+});
+// ── Loading states ─────────────────────────────────────────────────────────
+const isFirstLoad = $derived(isServerMode && serverLoading && serverData.length === 0 || !isServerMode && localLoading && localData.length === 0);
+const isLoadingMore = $derived(isServerMode && serverLoading && serverData.length > 0);
+const isEmpty = $derived(!isFirstLoad && displayData.length === 0);
+// Cap skeleton count so we don't render 200 ghost cards
+const skeletonCount = $derived(Math.min(pageSize, 8));
+// ── Virtualizer ────────────────────────────────────────────────────────────
+// Group flat displayData into rows of columnsInRow items each
+const virtualRows = $derived.by(() => {
+	const cols = Math.max(1, columnsInRow);
+	const rows = [];
+	for (let i = 0; i < displayData.length; i += cols) {
+		rows.push(displayData.slice(i, i + cols));
 	}
-
-	// ── Public API ─────────────────────────────────────────────────────────────
-
-	export function refresh() {
-		if (isServerMode) {
-			refreshTrigger++;
-		} else if (typeof data === 'function') {
-			localLoading = true;
-			(data as () => Promise<Record<string, unknown>[]>)()
-				.then((d) => { localData = d; })
-				.catch((e) => { onLoadError?.(e instanceof Error ? e.message : 'Failed to load data'); })
-				.finally(() => { localLoading = false; });
-		}
+	return rows;
+});
+// createVirtualizer returns a Svelte 4 store that calls subscribe with the
+// same object reference on every scroll update. Svelte 5 $state uses Object.is
+// equality, so assigning the same reference never triggers reactivity.
+// Fix: extract the values we need inside the subscribe callback directly into
+// $state variables — getVirtualItems() returns a new array each call, and
+// getTotalSize() is a primitive, so both reliably trigger Svelte updates.
+let virtualizerInstance = $state(null);
+let virtualItems = $state([]);
+let totalSize = $state(0);
+$effect(() => {
+	const el = containerEl;
+	if (!el) {
+		virtualizerInstance = null;
+		virtualItems = [];
+		totalSize = 0;
+		return;
 	}
-
-	// ── Loading states ─────────────────────────────────────────────────────────
-
-	const isFirstLoad   = $derived((isServerMode && serverLoading && serverData.length === 0) || (!isServerMode && localLoading && localData.length === 0));
-	const isLoadingMore = $derived(isServerMode && serverLoading && serverData.length > 0);
-	const isEmpty       = $derived(!isFirstLoad && displayData.length === 0);
-	// Cap skeleton count so we don't render 200 ghost cards
-	const skeletonCount = $derived(Math.min(pageSize, 8));
-
-	// ── Virtualizer ────────────────────────────────────────────────────────────
-
-	// Group flat displayData into rows of columnsInRow items each
-	const virtualRows = $derived.by(() => {
-		const cols = Math.max(1, columnsInRow);
-		const rows: Record<string, unknown>[][] = [];
-		for (let i = 0; i < displayData.length; i += cols) {
-			rows.push(displayData.slice(i, i + cols));
-		}
-		return rows;
+	const rowCount = untrack(() => virtualRows.length);
+	const gap = untrack(() => cardGap);
+	const virt = createVirtualizer({
+		count: rowCount,
+		estimateSize: () => 220 + gap,
+		overscan: 2,
+		getScrollElement: () => el
 	});
-
-	// createVirtualizer returns a Svelte 4 store that calls subscribe with the
-	// same object reference on every scroll update. Svelte 5 $state uses Object.is
-	// equality, so assigning the same reference never triggers reactivity.
-	// Fix: extract the values we need inside the subscribe callback directly into
-	// $state variables — getVirtualItems() returns a new array each call, and
-	// getTotalSize() is a primitive, so both reliably trigger Svelte updates.
-	let virtualizerInstance = $state<SvelteVirtualizer<HTMLElement, HTMLElement> | null>(null);
-	let virtualItems        = $state<ReturnType<SvelteVirtualizer<HTMLElement, HTMLElement>['getVirtualItems']>>([]);
-	let totalSize           = $state(0);
-
-	$effect(() => {
-		const el = containerEl;
-		if (!el) {
-			virtualizerInstance = null;
-			virtualItems        = [];
-			totalSize           = 0;
-			return;
-		}
-		const rowCount = untrack(() => virtualRows.length);
-		const gap      = untrack(() => cardGap);
-		const virt = createVirtualizer<HTMLElement, HTMLElement>({
-			count:            rowCount,
-			estimateSize:     () => 220 + gap,
-			overscan:         2,
-			getScrollElement: () => el,
-		});
-		return virt.subscribe((v) => {
-			virtualizerInstance = v;
-			virtualItems        = v.getVirtualItems();
-			totalSize           = v.getTotalSize();
-		});
+	return virt.subscribe((v) => {
+		virtualizerInstance = v;
+		virtualItems = v.getVirtualItems();
+		totalSize = v.getTotalSize();
 	});
-
-	// Update virtualizer when row count or gap changes.
-	// Untracked read of virtualizerInstance so scroll events don't re-trigger this.
-	$effect(() => {
-		const count = virtualRows.length;
-		const gap   = cardGap;
-		untrack(() => {
-			if (!virtualizerInstance || !containerEl) return;
-			virtualizerInstance.setOptions({
-				...virtualizerInstance.options,
-				count,
-				estimateSize:     () => 220 + gap,
-				getScrollElement: () => containerEl,
-			});
+});
+// Update virtualizer when row count or gap changes.
+// Untracked read of virtualizerInstance so scroll events don't re-trigger this.
+$effect(() => {
+	const count = virtualRows.length;
+	const gap = cardGap;
+	untrack(() => {
+		if (!virtualizerInstance || !containerEl) return;
+		virtualizerInstance.setOptions({
+			...virtualizerInstance.options,
+			count,
+			estimateSize: () => 220 + gap,
+			getScrollElement: () => containerEl
 		});
 	});
+});
 </script>
 
 {#snippet filterPanelSnippet()}
@@ -734,16 +593,16 @@
 		</div>
 
 		<!-- ── Card grid ────────────────────────────────────────────────────── -->
-		<!-- svelte-ignore a11y_interactive_supports_focus -->
 		<div
 			bind:this={containerEl}
 			class="cg-grid"
+			class:cg-animate={animateEnabled}
 			role="listbox"
 			aria-multiselectable={multiSelect}
 			tabindex="0"
 			onkeydown={handleKeyDown}
 			onclick={handleContainerClick}
-			style="--cg-min-width:{cardMinWidth}px;--cg-gap:{cardGap}px;--cg-cols:{columnsInRow};"
+			style="--cg-min-width:{densityMinWidth * expandFactor}px;--cg-gap:{densityGap * expandFactor}px;--cg-cols:{columnsInRow};"
 		>
 			{#if isFirstLoad}
 				<!-- ── Skeleton cards ─────────────────────────────────── -->
@@ -1118,6 +977,22 @@
 		outline-offset: 2px;
 	}
 
+	/* ── Card entry animation (enabled via .cg-animate on the container) ── */
+
+	@keyframes cg-card-in {
+		from { opacity: 0; transform: translateY(6px) scale(0.97); }
+		to   { opacity: 1; transform: translateY(0)   scale(1); }
+	}
+
+	.cg-animate .cg-card {
+		animation: cg-card-in 180ms ease both;
+	}
+
+	/* Selected cards override the entry animation's transform */
+	.cg-animate .cg-card-selected {
+		animation: none;
+	}
+
 	/* ── Skeleton cards ───────────────────────────────────────────────────── */
 
 	@keyframes cg-shimmer {