@protobase/ui 0.12.22 → 0.13.3

package/dist/app/pages/blocks/table.js

@@ -1,54 +1,34 @@
-import { Skeleton } from "../../../primitives/skeleton.js";
 import { useAdminMeta } from "../../meta-gate.js";
-import { ErrorBanner } from "../../error-banner.js";
-import { useListPage } from "../use-layout-data.js";
 import { propsOf } from "./block-props.js";
-import { CardFrame, Quiet } from "./card-frame.js";
-import { RecordTable } from "../record-table.js";
-import { useState } from "react";
-import { jsx } from "react/jsx-runtime";
+import { CardFrame } from "./card-frame.js";
+import { EmbeddedDisplaySwitch, EmbeddedList } from "../../embedded-list/embedded-list.js";
+import { useEmbeddedDisplay } from "../../embedded-list/use-embedded-display.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/app/pages/blocks/table.tsx
-/** The view's list columns, else the first five fields that are not keys or the tenant. */
-const defaultColumns = (model, view) => view?.list?.columns ?? Object.keys(model.fields).filter((name) => !model.primaryKey.includes(name) && name !== model.tenant).slice(0, 5);
-const LoadedTable = ({ model, view, filter, sort, columns, pageSize = 10, title, description, empty, actions }) => {
-	const shown = (columns ?? defaultColumns(model, view)).filter((name) => Object.hasOwn(model.fields, name));
-	const [tokens, setTokens] = useState([""]);
-	const page = useListPage(model, {
-		filter,
-		sort,
-		pageSize,
-		pageToken: tokens.at(-1)
-	});
-	const rows = page.data?.items ?? [];
-	const next = page.data?.nextPageToken;
+const LoadedTable = ({ model, view, filter = "", sort = "", columns, limit = 10, display: preferred, title, description, empty, actions }) => {
+	const [display, pick] = useEmbeddedDisplay(view, `page:${model.name}:${title ?? ""}:${filter}`, preferred);
 	return /* @__PURE__ */ jsx(CardFrame, {
 		title,
 		description,
-		actions,
+		actions: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(EmbeddedDisplaySwitch, {
+			view,
+			value: display,
+			onChange: pick
+		}), actions] }),
 		className: "h-full",
-		children: page.isPending ? /* @__PURE__ */ jsx("div", {
-			className: "flex flex-col gap-2",
-			children: Array.from({ length: 3 }, (_, index) => /* @__PURE__ */ jsx(Skeleton, { className: "h-4 w-full" }, index))
-		}) : page.error ? /* @__PURE__ */ jsx(ErrorBanner, {
-			title: "Could not load",
-			error: page.error
-		}) : rows.length === 0 && tokens.length === 1 ? /* @__PURE__ */ jsx(Quiet, { children: empty ?? "Nothing here yet." }) : /* @__PURE__ */ jsx(RecordTable, {
+		children: /* @__PURE__ */ jsx(EmbeddedList, {
 			model,
-			columns: shown,
-			rows,
-			label: title ?? model.name,
-			pager: {
-				page: tokens.length,
-				hasPrevious: tokens.length > 1,
-				hasNext: Boolean(next),
-				busy: page.isFetching,
-				previous: () => setTokens((stack) => stack.slice(0, -1)),
-				next: () => next && setTokens((stack) => [...stack, next])
-			}
+			view,
+			filter,
+			sort,
+			columns,
+			limit,
+			display,
+			empty
 		})
 	});
 };
-/** A page of records at a time, in `sort` order; the first column opens the record. */
+/** The first `limit` records in `sort` order, in the list page's table or display, with a link to the whole list. */
 const TableBlock = ({ node, slots }) => {
 	const props = propsOf(node);
 	const { resources, views } = useAdminMeta();
@@ -62,4 +42,4 @@ const TableBlock = ({ node, slots }) => {
 	});
 };
 //#endregion
-export { TableBlock, defaultColumns };
+export { TableBlock };

package/dist/app/pages/field-value.js

@@ -2,14 +2,15 @@ import { cn } from "../../lib/cn.js";
 import { keys } from "../../data/query-keys.js";
 import { useClient } from "../../data/api-provider.js";
 import { fetchLabels } from "../../live/relation-labels.js";
-import { fileShown } from "../../live/file-values.js";
+import { fileShown, shownImage } from "../../live/file-values.js";
 import { displayValue } from "../../live/display-value.js";
 import { useAdminMeta } from "../meta-gate.js";
 import { AppLink } from "../use-app-address.js";
+import { FileImage } from "../../live/file-image.js";
 import { useShownWidget } from "../field-types/shown-widget.js";
 import { WidgetPart } from "../field-types/widget-part.js";
 import { ValueBadge } from "../value-badge.js";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 //#region src/app/pages/field-value.tsx
 const RelationValue = ({ field, value, known }) => {
@@ -50,13 +51,25 @@ const BuiltInValue = ({ model, field, value, format, relationLabel }) => {
 		known: relationLabel
 	});
 	const file = field.type === "file" ? fileShown(value) : void 0;
-	if (file && "url" in file && file.url) return /* @__PURE__ */ jsx("a", {
-		href: file.url,
-		target: "_blank",
-		rel: "noreferrer",
-		className: "font-medium text-primary-text hover:underline",
-		children: file.name
-	});
+	if (file && "url" in file && file.url) {
+		const image = shownImage(value, {
+			width: 40,
+			height: 40
+		});
+		return /* @__PURE__ */ jsxs("span", {
+			className: "inline-flex min-w-0 items-center gap-2",
+			children: [image && /* @__PURE__ */ jsx(FileImage, {
+				image,
+				className: "size-10 shrink-0 rounded border border-border object-cover"
+			}), /* @__PURE__ */ jsx("a", {
+				href: file.url,
+				target: "_blank",
+				rel: "noreferrer",
+				className: "truncate font-medium text-primary-text hover:underline",
+				children: file.name
+			})]
+		});
+	}
 	const text = displayValue(field, value, hints);
 	if (field.type === "enum" || hints.format === "badge") return /* @__PURE__ */ jsx(ValueBadge, {
 		value,

package/dist/app/record-page.js

@@ -292,7 +292,8 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 								children: [layout.flatMap((item, index) => {
 									if (item.kind === "related") return [/* @__PURE__ */ jsx(RelatedSection, {
 										item,
-										recordKey
+										recordKey,
+										owner: model.name
 									}, `related:${item.title}`)];
 									if (item.kind === "custom") return item.sidebar ? [] : [/* @__PURE__ */ jsx(CustomSection, {
 										item,

package/dist/app/related-section.js

@@ -4,17 +4,20 @@ import { useClient } from "../data/api-provider.js";
 import { useAdminMeta } from "./meta-gate.js";
 import { ErrorBanner } from "./error-banner.js";
 import { Section } from "../record-view/section.js";
-import { RecordTable } from "./pages/record-table.js";
-import { defaultColumns } from "./pages/blocks/table.js";
-import { useState } from "react";
+import { listColumnNames } from "../live/columns-from-model.js";
+import { EmbeddedDisplaySwitch, EmbeddedList } from "./embedded-list/embedded-list.js";
+import { useEmbeddedDisplay } from "./embedded-list/use-embedded-display.js";
 import { jsx } from "react/jsx-runtime";
-import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
 import { createWhere, printFilter } from "@protobase/schema";
 //#region src/app/related-section.tsx
 const where = createWhere();
 /** The most join records a section reads to find its records; the list API's largest page. */
 const maxThrough = 500;
-const and = (...parts) => parts.filter((part) => Boolean(part)).map((part) => `(${part})`).join(" AND ");
+const and = (...parts) => {
+	const given = parts.filter((part) => Boolean(part));
+	return given.length === 1 ? given[0] : given.map((part) => `(${part})`).join(" AND ");
+};
 /**
 * The filter on the section's resource: its `field` is this record's key, or, through a join resource, one of the keys
 * the join records that point at this record hold. `null` when no join record does, so nothing can match.
@@ -54,47 +57,6 @@ const useMatch = (item, recordKey) => {
 		error: null
 	};
 };
-const RelatedRows = ({ item, model, filter }) => {
-	const client = useClient();
-	const { views } = useAdminMeta();
-	const [tokens, setTokens] = useState([""]);
-	const pageSize = item.pageSize ?? 10;
-	const sort = item.sort ?? "";
-	const token = tokens.at(-1) ?? "";
-	const page = useQuery({
-		queryKey: keys.list(model.name, filter, sort, pageSize, token),
-		placeholderData: keepPreviousData,
-		queryFn: () => client.search(model.name, {
-			filter,
-			orderBy: sort || void 0,
-			pageSize,
-			pageToken: token || void 0
-		})
-	});
-	if (page.isPending) return /* @__PURE__ */ jsx(Loading, {});
-	if (page.error) return /* @__PURE__ */ jsx(ErrorBanner, {
-		title: "Could not load",
-		error: page.error
-	});
-	const rows = page.data.items;
-	if (rows.length === 0 && tokens.length === 1) return /* @__PURE__ */ jsx(Empty, { text: item.empty });
-	const columns = (item.columns ?? defaultColumns(model, views[model.name]).filter((name) => name !== item.field)).filter((name) => name.includes(".") || Object.hasOwn(model.fields, name));
-	const next = page.data.nextPageToken;
-	return /* @__PURE__ */ jsx(RecordTable, {
-		model,
-		columns,
-		rows,
-		label: item.title,
-		pager: {
-			page: tokens.length,
-			hasPrevious: tokens.length > 1,
-			hasNext: Boolean(next),
-			busy: page.isFetching,
-			previous: () => setTokens((stack) => stack.slice(0, -1)),
-			next: () => next && setTokens((stack) => [...stack, next])
-		}
-	});
-};
 const Loading = () => /* @__PURE__ */ jsx("div", {
 	className: "flex flex-col gap-2",
 	children: Array.from({ length: 3 }, (_, index) => /* @__PURE__ */ jsx(Skeleton, { className: "h-4 w-full" }, index))
@@ -103,22 +65,38 @@ const Empty = ({ text }) => /* @__PURE__ */ jsx("p", {
 	className: "text-[13px] text-muted-foreground",
 	children: text ?? "Nothing here yet."
 });
-/** A record page section listing the records of another resource that point at this record, directly or through a join resource. */
-const RelatedSection = ({ item, recordKey }) => {
-	const { resources } = useAdminMeta();
+/**
+* A record page section listing the first records of another resource that point at this record, directly or through
+* a join resource, in the list page's table or display, with a link to them all in the list.
+*/
+const RelatedSection = ({ item, recordKey, owner }) => {
+	const { resources, views } = useAdminMeta();
 	const model = resources[item.resource];
+	const view = model && views[model.name];
 	const match = useMatch(item, recordKey);
+	const [display, pick] = useEmbeddedDisplay(view, `related:${owner}:${item.title}`, item.display);
 	if (!model) return null;
+	const columns = item.columns ?? listColumnNames(model, view).filter((name) => name !== item.field);
 	return /* @__PURE__ */ jsx(Section, {
 		title: item.title,
 		help: item.help,
+		actions: /* @__PURE__ */ jsx(EmbeddedDisplaySwitch, {
+			view,
+			value: display,
+			onChange: pick
+		}),
 		children: match.isPending ? /* @__PURE__ */ jsx(Loading, {}) : match.error ? /* @__PURE__ */ jsx(ErrorBanner, {
 			title: "Could not load",
 			error: match.error
-		}) : match.filter === null || match.filter === void 0 ? /* @__PURE__ */ jsx(Empty, { text: item.empty }) : /* @__PURE__ */ jsx(RelatedRows, {
-			item,
+		}) : match.filter === null || match.filter === void 0 ? /* @__PURE__ */ jsx(Empty, { text: item.empty }) : /* @__PURE__ */ jsx(EmbeddedList, {
 			model,
-			filter: match.filter
+			view,
+			filter: match.filter,
+			sort: item.sort ?? "",
+			columns,
+			limit: item.limit ?? 10,
+			display,
+			empty: item.empty
 		}, match.filter)
 	});
 };

package/dist/app/router.js

@@ -85,6 +85,7 @@ const Router = ({ basePath = "", initialUrl, children }) => {
 			path: parsed.pathname.slice(basePath.length) || "/",
 			params: parsed.searchParams,
 			basePath,
+			entry: position.current,
 			navigate,
 			registerGuard
 		};

package/dist/app/use-record-editor.js

@@ -106,7 +106,8 @@ const useRecordEditor = ({ model, stored, recordKey, mode, subject, draftKey, li
 		await Promise.all([
 			queryClient.invalidateQueries({ queryKey: keys.record(model.name, recordKey) }),
 			queryClient.invalidateQueries({ queryKey: ["list"] }),
-			queryClient.invalidateQueries({ queryKey: ["page"] })
+			queryClient.invalidateQueries({ queryKey: ["page"] }),
+			queryClient.invalidateQueries({ queryKey: ["map"] })
 		]);
 		lines?.reset();
 	};

package/dist/data/api-provider.d.ts

@@ -28,6 +28,7 @@ export declare const useClient: () => {
     filter?: import("@protobase/client").FilterInput;
     buckets?: number;
   }) => Promise<import("@protobase/client").Histogram>;
+  map: <R extends import("@protobase/client").ResourceRef>(resource: R, params: import("@protobase/client").MapParams) => Promise<import("@protobase/client").MapResult<import("@protobase/client").RecordOf<R>>>;
   seek: <R extends import("@protobase/client").ResourceRef>(resource: R, params: import("@protobase/client").ListParams & {
     position: number;
   }) => Promise<import("@protobase/client").ListPage<import("@protobase/client").RecordOf<R>>>;
@@ -66,6 +67,7 @@ export declare const useResourceClient: (resource: string) => {
     filter?: import("@protobase/client").FilterInput;
     buckets?: number;
   }) => Promise<import("@protobase/client").Histogram>;
+  map: <R extends import("@protobase/client").ResourceRef>(resource: R, params: import("@protobase/client").MapParams) => Promise<import("@protobase/client").MapResult<import("@protobase/client").RecordOf<R>>>;
   seek: <R extends import("@protobase/client").ResourceRef>(resource: R, params: import("@protobase/client").ListParams & {
     position: number;
   }) => Promise<import("@protobase/client").ListPage<import("@protobase/client").RecordOf<R>>>;

package/dist/data/query-keys.js

@@ -66,6 +66,15 @@ const keys = {
 		buckets,
 		filter
 	],
+	/** The records or buckets a map shows; `filter` holds its bounding box. */
+	map: (resource, position, zoom, filter, orderBy) => [
+		"map",
+		resource,
+		position,
+		zoom,
+		filter,
+		orderBy
+	],
 	relatedLabel: (resource, id) => [
 		"related-label",
 		resource,

package/dist/data/use-update-record.js

@@ -18,6 +18,7 @@ const useUpdateRecord = (resource, key) => {
 			queryClient.setQueryData(keys.record(resource, encoded), stored);
 			queryClient.invalidateQueries({ queryKey: ["page", resource] });
 			queryClient.invalidateQueries({ queryKey: ["list", resource] });
+			queryClient.invalidateQueries({ queryKey: ["map", resource] });
 		}
 	});
 };

package/dist/data-grid/cells.js

@@ -4,7 +4,8 @@ import { Badge } from "../primitives/badge.js";
 import { formatMoney } from "../format/money.js";
 import { formatInt, formatPercent, formatSigned } from "../format/number.js";
 import { formatDate, formatDateTime } from "../format/date.js";
-import { fileShown, isPreviewable } from "../live/file-values.js";
+import { fileShown, shownImage } from "../live/file-values.js";
+import { FileImage } from "../live/file-image.js";
 import { userById } from "../mocks/users.js";
 import { valueColor } from "../live/value-color.js";
 import { Check, Paperclip } from "lucide-react";
@@ -75,12 +76,14 @@ const renderCell = (spec, value) => {
 				className: "truncate text-danger-text",
 				children: file.name
 			});
-			const url = "url" in file ? file.url : void 0;
+			const image = shownImage(value, {
+				width: 20,
+				height: 20
+			});
 			return /* @__PURE__ */ jsxs("span", {
 				className: "inline-flex min-w-0 items-center gap-2",
-				children: [url && isPreviewable(file.type) ? /* @__PURE__ */ jsx("img", {
-					src: url,
-					alt: "",
+				children: [image ? /* @__PURE__ */ jsx(FileImage, {
+					image,
 					className: "size-5 shrink-0 rounded-sm object-cover"
 				}) : /* @__PURE__ */ jsx(Paperclip, { className: "size-3.5 shrink-0 text-muted-foreground" }), /* @__PURE__ */ jsx("span", {
 					className: "truncate",

package/dist/data-grid/data-grid.js

@@ -8,16 +8,14 @@ import { useHorizontalScroll } from "./use-horizontal-scroll.js";
 import { usePinnedColumns } from "./use-pinned-columns.js";
 import { GridHeader } from "./grid-header.js";
 import { DataRow, SkeletonRow } from "./grid-row.js";
-import { windowFor } from "./geometry.js";
-import { useGridScroll } from "./use-grid-scroll.js";
 import { usePagedRows } from "./use-paged-rows.js";
-import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useVirtualRows } from "./use-virtual-rows.js";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { useVirtualizer } from "@tanstack/react-virtual";
 import { useTable } from "@tanstack/react-table";
 //#region src/data-grid/data-grid.tsx
 const headerHeight = 32;
-const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0, latencyMs = 150, sort: controlledSort, onSortChange, onOpenRow, rowActions, bulkActions, pinKey, defaultPinned, rowNumbers = true, compact = false, selectable = true, className }) => {
+const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0, onScrollIndex, latencyMs = 150, sort: controlledSort, onSortChange, onOpenRow, rowActions, bulkActions, pinKey, defaultPinned, rowNumbers = true, compact = false, selectable = true, fit = false, className }) => {
 	const rowHeight = compact ? 28 : 36;
 	const [pinned, setPinned] = usePinnedColumns(pinKey, defaultPinned);
 	const columns = useMemo(() => {
@@ -52,45 +50,27 @@ const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0,
 		reverse,
 		total
 	]);
-	const { ref, onScroll, viewport, top, geometry } = useGridScroll(total, rowHeight, initialScrollIndex);
+	const { ref, onScroll, viewport, top, geometry, rows: virtualRows, first: firstIndex, last: lastIndex } = useVirtualRows({
+		total,
+		rowHeight,
+		initialIndex: initialScrollIndex,
+		inset: headerHeight
+	});
 	const narrow = !useIsDesktop();
 	const gutter = narrow || !rowNumbers ? 40 : gutterWidthFor(total);
 	const bodyHeight = Math.max(0, viewport - headerHeight);
-	const bodyRef = useRef(null);
-	const offsetListener = useRef(null);
-	const { base, count } = windowFor(total, top, rowHeight);
-	const localOffset = top - base * rowHeight;
-	const virtualizer = useVirtualizer({
-		count,
-		getScrollElement: () => bodyRef.current,
-		estimateSize: () => rowHeight,
-		overscan: 6,
-		initialRect: {
-			width: 0,
-			height: bodyHeight
-		},
-		observeElementOffset: (_, callback) => {
-			offsetListener.current = callback;
-			callback(localOffset, false);
-			return () => {
-				offsetListener.current = null;
-			};
-		}
-	});
-	useLayoutEffect(() => offsetListener.current?.(localOffset, false), [localOffset, base]);
-	const items = virtualizer.getVirtualItems();
-	const firstIndex = base + (items[0]?.index ?? 0);
-	const lastIndex = base + (items[items.length - 1]?.index ?? 0);
+	const topIndex = Math.floor(top / rowHeight);
+	useEffect(() => onScrollIndex?.(topIndex), [topIndex, onScrollIndex]);
 	const getRow = usePagedRows({
 		total,
 		rowAt: sourceRowAt ? rowAt : void 0,
 		loadRows: source.loadRows,
 		latencyMs
 	}, firstIndex, lastIndex);
-	const loaded = items.map((item) => ({
-		item,
-		index: base + item.index,
-		row: getRow(base + item.index)
+	const loaded = virtualRows.map(({ index, offset }) => ({
+		index,
+		offset,
+		row: getRow(index)
 	}));
 	const data = useMemo(() => loaded.flatMap(({ row }) => row ? [row] : []), [
 		getRow,
@@ -143,6 +123,7 @@ const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0,
 	const last = Math.min(total, first + visibleRows - 1);
 	return /* @__PURE__ */ jsxs("div", {
 		className: cn("flex min-h-0 flex-col overflow-hidden rounded-lg border bg-background", className),
+		style: fit ? { height: headerHeight + total * rowHeight + 2 } : void 0,
 		children: [/* @__PURE__ */ jsx("div", {
 			ref,
 			onScroll,
@@ -175,14 +156,13 @@ const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0,
 								selectedCount,
 								onClearSelection: () => setRowSelection({})
 							}), /* @__PURE__ */ jsx("div", {
-								ref: bodyRef,
 								className: "relative min-h-0 flex-1 overflow-clip",
-								children: loaded.map(({ item, index, row }) => {
+								children: loaded.map(({ index, offset, row }) => {
 									const frame = {
 										specs: columns,
 										gutter,
 										index,
-										offset: item.start - localOffset,
+										offset,
 										height: rowHeight,
 										selectable,
 										trailing,
@@ -217,7 +197,7 @@ const DataGrid = ({ columns: given, source, naturalSort, initialScrollIndex = 0,
 					})] })
 				})
 			})
-		}), /* @__PURE__ */ jsx(GridFooter, {
+		}), !fit && /* @__PURE__ */ jsx(GridFooter, {
 			total,
 			first,
 			last,

package/dist/data-grid/geometry.js

@@ -1,8 +1,6 @@
 //#region src/data-grid/geometry.ts
 /** Browsers cap element height (about 17M px in the strictest); stay well below it. */
 const maxContentHeight = 1e7;
-const chunk = 2e3;
-const windowSize = 5e3;
 const gridGeometry = (total, rowHeight, viewportHeight) => {
 	const trueHeight = total * rowHeight;
 	const contentHeight = Math.min(trueHeight, maxContentHeight);
@@ -19,14 +17,14 @@ const gridGeometry = (total, rowHeight, viewportHeight) => {
 const topFromScroll = (geometry, scrollTop) => geometry.maxScroll === 0 ? 0 : scrollTop / geometry.maxScroll * geometry.maxTop;
 const scrollFromTop = (geometry, top) => geometry.maxTop === 0 ? 0 : top / geometry.maxTop * geometry.maxScroll;
 const clampTop = (geometry, top) => Math.min(Math.max(0, top), geometry.maxTop);
-/** The slice of rows handed to the virtualizer; it moves in whole chunks so row measurements stay small. */
-const windowFor = (total, top, rowHeight) => {
-	const topRow = Math.floor(top / rowHeight);
-	const base = Math.min(Math.max(0, Math.floor(topRow / chunk) * chunk - chunk), Math.max(0, total - windowSize));
+/** The rows drawn for a scroll offset: those in a viewport of `height`, and `overscan` more on each side. */
+const rowsInView = (total, top, rowHeight, height, overscan) => {
+	const first = Math.max(0, Math.floor(top / rowHeight) - overscan);
+	const last = Math.min(total - 1, Math.floor((top + height) / rowHeight) + overscan);
 	return {
-		base,
-		count: Math.min(windowSize, total - base)
+		first,
+		last: Math.max(first - 1, last)
 	};
 };
 //#endregion
-export { clampTop, gridGeometry, maxContentHeight, scrollFromTop, topFromScroll, windowFor };
+export { clampTop, gridGeometry, maxContentHeight, rowsInView, scrollFromTop, topFromScroll };

package/dist/data-grid/use-grid-scroll.js

@@ -64,6 +64,12 @@ const useGridScroll = (total, rowHeight, initialIndex) => {
 		element.addEventListener("wheel", onWheel, { passive: false });
 		return () => element.removeEventListener("wheel", onWheel);
 	}, [syncNative]);
+	/** Moves to a virtual offset, for a layout change that keeps a row in view. */
+	const scrollTo = useCallback((nextTop) => {
+		const next = clampTop(latest.current.geometry, nextTop);
+		setTop(next);
+		syncNative(next);
+	}, [syncNative]);
 	return {
 		ref,
 		onScroll: useCallback(() => {
@@ -73,7 +79,8 @@ const useGridScroll = (total, rowHeight, initialIndex) => {
 		}, []),
 		viewport,
 		top,
-		geometry
+		geometry,
+		scrollTo
 	};
 };
 //#endregion

package/dist/data-grid/use-virtual-rows.js

@@ -0,0 +1,31 @@
+import { rowsInView } from "./geometry.js";
+import { useGridScroll } from "./use-grid-scroll.js";
+//#region src/data-grid/use-virtual-rows.ts
+const overscan = 6;
+/**
+* Rows of a fixed height over a proxy scroller, so any number of rows scrolls at native speed: `ref` and `onScroll` go
+* on the scrolling element, and each drawn row sits at `offset` from the top of the viewport's rows, below `inset`.
+* `first` and `last` are the indexes of the drawn rows, overscan included.
+*/
+const useVirtualRows = ({ total, rowHeight, initialIndex, inset = 0, settle }) => {
+	const scroll = useGridScroll(total, rowHeight, initialIndex);
+	const { ref, onScroll, viewport, geometry, scrollTo } = scroll;
+	const top = settle ? settle(scroll.top) : scroll.top;
+	const { first, last } = rowsInView(total, top, rowHeight, Math.max(0, viewport - inset), overscan);
+	return {
+		ref,
+		onScroll,
+		viewport,
+		top,
+		geometry,
+		scrollTo,
+		rows: Array.from({ length: last - first + 1 }, (_, offset) => ({
+			index: first + offset,
+			offset: (first + offset) * rowHeight - top
+		})),
+		first,
+		last
+	};
+};
+//#endregion
+export { useVirtualRows };

package/dist/live/columns-from-model.js

@@ -61,9 +61,11 @@ const kindOf = (field, view, index) => {
 	}
 };
 const currencyCents = (value) => Math.round(Number.parseFloat(String(value)) * 100);
-/** Grid columns for a view's list: kinds follow the field types and the view's format hints. */
-const columnsFromModel = (resource, view, highlight = []) => {
-	return (view?.list?.columns ?? Object.keys(resource.fields).slice(0, 6)).flatMap((name, index) => {
+/** The fields a view's list shows as columns: its list columns, else the resource's first six fields. */
+const listColumnNames = (resource, view) => view?.list?.columns ?? Object.keys(resource.fields).slice(0, 6);
+/** Grid columns for `names`, by default the view's list: kinds follow the field types and the view's format hints. */
+const columnsFromModel = (resource, view, highlight = [], names = listColumnNames(resource, view)) => {
+	return names.flatMap((name, index) => {
 		const field = resource.fields[name];
 		if (!field) return [];
 		const viewField = view?.fields[name];
@@ -97,4 +99,4 @@ const columnsFromModel = (resource, view, highlight = []) => {
 	});
 };
 //#endregion
-export { columnsFromModel, headerWidth, toneFor };
+export { columnsFromModel, headerWidth, listColumnNames, toneFor };

package/dist/live/file-image.js

@@ -0,0 +1,35 @@
+import { useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { thumbHashToDataURL } from "thumbhash";
+//#region src/live/file-image.tsx
+const placeholderImage = (hash) => {
+	let binary;
+	try {
+		binary = atob(hash);
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "InvalidCharacterError") return void 0;
+		throw error;
+	}
+	return thumbHashToDataURL(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+};
+/** An image of a file, its placeholder drawn blurred behind it until it has loaded. */
+const FileImage = ({ image, className, loading }) => {
+	const [loaded, setLoaded] = useState();
+	const placeholder = useMemo(() => image.placeholder === void 0 ? void 0 : placeholderImage(image.placeholder), [image.placeholder]);
+	const waiting = placeholder !== void 0 && loaded !== image.url;
+	return /* @__PURE__ */ jsx("img", {
+		src: image.url,
+		alt: "",
+		loading,
+		decoding: "async",
+		onLoad: () => setLoaded(image.url),
+		className,
+		style: waiting ? {
+			backgroundImage: `url("${placeholder}")`,
+			backgroundSize: "cover",
+			backgroundPosition: "center"
+		} : void 0
+	});
+};
+//#endregion
+export { FileImage };

package/dist/live/file-values.js

@@ -34,6 +34,22 @@ const formatSize = (bytes) => {
 };
 /** Raster images the browser shows; SVG is never shown, since it can carry scripts. */
 const isPreviewable = (type) => type.startsWith("image/") && type !== "image/svg+xml";
+const density = 2;
+const unbounded = 1e5;
+const covers = (variant, box) => (variant.width !== void 0 || variant.height !== void 0) && (variant.width ?? unbounded) >= box.width * density && (variant.height ?? unbounded) >= box.height * density;
+const area = (variant) => (variant.width ?? unbounded) * (variant.height ?? unbounded);
+/**
+* The picture of a file for `box`: the link of its smallest variant large enough for it, else the file's own, with its
+* placeholder; `undefined` for a file that is no raster image with a link.
+*/
+const shownImage = (value, box) => {
+	const file = fileShown(value);
+	if (!file || "missing" in file || !file.url || !isPreviewable(file.type)) return void 0;
+	return {
+		url: ("variants" in file && file.variants ? Object.values(file.variants) : []).filter((variant) => covers(variant, box)).sort((a, b) => area(a) - area(b))[0]?.url ?? file.url,
+		..."placeholder" in file && file.placeholder !== void 0 && { placeholder: file.placeholder }
+	};
+};
 /** The file input's `accept`: the field's allowed types, or nothing when it takes any. */
 const acceptOf = (field) => {
 	const accept = field.file?.accept ?? [];
@@ -52,4 +68,4 @@ const fileDiffers = (draft, stored) => {
 	return uri(draft) !== uri(stored);
 };
 //#endregion
-export { acceptOf, fileDiffers, filePatchValue, fileShown, formatSize, isFileDraft, isPreviewable, isStoredFile };
+export { acceptOf, fileDiffers, filePatchValue, fileShown, formatSize, isFileDraft, isPreviewable, isStoredFile, shownImage };