@protobase/ui 0.9.0 → 0.11.0

package/dist/app/app.js

@@ -13,9 +13,11 @@ import { humanize } from "../live/naming.js";
 import { ToastProvider } from "../toasts/toast-provider.js";
 import { useProjectUi } from "./pages/project-ui.js";
 import { AssistantButton, AssistantPanel } from "./assistant-shell.js";
+import { bottomBarFromMeta } from "./bottom-bar-from-meta.js";
 import { breadcrumbFor } from "./breadcrumb-for.js";
-import { Router, matchRoute, useRouter } from "./router.js";
 import { MetaGate, Notice, useAdminMeta } from "./meta-gate.js";
+import { Router, useRouter } from "./router.js";
+import { useAppAddress } from "./use-app-address.js";
 import { CreatePage } from "./create/create-page.js";
 import { ListPage } from "./list-page.js";
 import { MembersPage } from "../organizations/members-page.js";
@@ -23,6 +25,8 @@ import { InvitationsPage } from "../organizations/invitations-page.js";
 import { reopenIn, useOrganizations } from "../organizations/use-organizations.js";
 import { OrganizationPage } from "../organizations/organization-page.js";
 import { OrganizationsPage } from "../organizations/organizations-page.js";
+import { actingUser } from "../roles/acting-user.js";
+import { useActiveRole } from "../roles/use-active-role.js";
 import { userMenuFromMeta } from "./user-menu-from-meta.js";
 import { navFromMeta } from "./nav-from-meta.js";
 import { ComposedPage } from "./pages/composed-page.js";
@@ -32,34 +36,51 @@ import { useGlobalSearch } from "./search/use-global-search.js";
 import { RuntimeUpdateButton } from "./runtime/runtime-update.js";
 import { StaffBanner } from "./staff-banner.js";
 import { useNavRecent } from "./use-nav-recent.js";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/app/app.tsx
+const placeOf = (address) => address?.kind === "page" ? address.page : address?.resource;
+const recordOf = (address) => address?.kind === "record" ? address : void 0;
 const Routes = ({ workspace, sidebarMode, assistant, runtime }) => {
 	const meta = useAdminMeta();
 	const { state, session, signOut, stopStaffSession, organizations: organizationSettings } = useAuth();
 	if (state.kind !== "signed-in") throw new Error("The shell is only rendered for a signed-in user");
 	const { user, staff } = state;
-	const { path, params, basePath, navigate } = useRouter();
-	const route = matchRoute(path);
+	const { path, params, basePath } = useRouter();
+	const { address, go, open } = useAppAddress();
+	const place = placeOf(address);
+	const shown = recordOf(address);
 	const search = useGlobalSearch();
-	const recent = useNavRecent(meta, basePath, route);
+	const recent = useNavRecent(meta, basePath, {
+		resource: place,
+		key: shown?.key
+	});
 	const groups = navFromMeta(meta, basePath, recent);
-	const first = Object.keys(meta.pages)[0] ?? Object.keys(meta.resources)[0];
-	const page = route.resource && !route.key ? meta.pages[route.resource] : void 0;
-	const open = (href) => navigate(href.startsWith(basePath) ? href.slice(basePath.length) : href);
+	const firstPage = Object.keys(meta.pages)[0];
+	const firstResource = Object.keys(meta.resources)[0];
+	const page = address?.kind === "page" ? meta.pages[address.page] : void 0;
 	useEffect(() => {
-		if (!route.resource && first) navigate(`/${first}`, { replace: true });
+		if (path !== "/") return;
+		if (firstPage) go({
+			kind: "page",
+			page: firstPage
+		}, { replace: true });
+		else if (firstResource) go({
+			kind: "list",
+			resource: firstResource
+		}, { replace: true });
 	}, [
-		route.resource,
-		first,
-		navigate
+		path,
+		firstPage,
+		firstResource,
+		go
 	]);
-	const view = route.resource ? meta.views[route.resource] : void 0;
-	const group = groups.find((entry) => entry.items.some((item) => item.id === route.resource));
-	const model = route.resource ? meta.resources[route.resource] : void 0;
-	const record = useRecord(route.resource ?? "", route.key ?? "", Boolean(model && route.key && route.key !== "new"));
-	const title = model && record.data ? recordTitle(model, view, record.data.record, route.key ?? "") : route.key;
+	const resource = address?.kind === "page" ? void 0 : address?.resource;
+	const view = resource ? meta.views[resource] : void 0;
+	const group = groups.find((entry) => entry.items.some((item) => item.id === place));
+	const model = resource ? meta.resources[resource] : void 0;
+	const record = useRecord(shown?.resource ?? "", shown?.key ?? "", Boolean(model && shown));
+	const title = model && shown && record.data ? recordTitle(model, view, record.data.record, shown.key) : shown?.key;
 	const { shell } = useProjectUi();
 	const Actions = shell?.actions;
 	const RightPanel = shell?.rightPanel;
@@ -80,7 +101,9 @@ const Routes = ({ workspace, sidebarMode, assistant, runtime }) => {
 		url: runtimeUrl,
 		client: runtime
 	});
-	const admin = isAdmin(user);
+	const role = useActiveRole(useCallback(() => reopenIn(basePath), [basePath]));
+	const acting = actingUser(user, role.current);
+	const admin = isAdmin(acting);
 	const organizations = useOrganizations(Boolean(organizationSettings));
 	const current = organizations.current;
 	const outsideOrganizations = Boolean(organizationSettings) && current !== void 0 && !current.organization;
@@ -88,10 +111,10 @@ const Routes = ({ workspace, sidebarMode, assistant, runtime }) => {
 	const accountPage = path === "/-/account" ? "Sign-in & security" : path === "/-/sign-in-policy" ? "Sign-in policy" : organizationPage;
 	const breadcrumb = accountPage ? [accountPage] : breadcrumbFor({
 		basePath,
-		route,
+		address,
 		group: group?.label,
 		page,
-		resourceLabel: view?.names?.plural ?? (route.resource && humanize(route.resource)),
+		resourceLabel: view?.names?.plural ?? (resource && humanize(resource)),
 		recordTitle: title
 	});
 	const content = path === "/-/account" ? /* @__PURE__ */ jsx(AccountSecurityPage, { email: user.email }) : path === "/-/sign-in-policy" ? admin ? /* @__PURE__ */ jsx(SignInPolicyPage, {}) : /* @__PURE__ */ jsx(Notice, {
@@ -107,23 +130,34 @@ const Routes = ({ workspace, sidebarMode, assistant, runtime }) => {
 	}) : path === "/-/organization/members" ? /* @__PURE__ */ jsx(MembersPage, { current }) : /* @__PURE__ */ jsx(InvitationsPage, { current }) : organizationPage && path === "/-/organizations" || outsideOrganizations ? /* @__PURE__ */ jsx(OrganizationsPage, {
 		state: organizations,
 		basePath
-	}) : !route.resource ? /* @__PURE__ */ jsx(Notice, {
+	}) : !address ? path === "/" ? /* @__PURE__ */ jsx(Notice, {
 		title: "Choose a resource",
 		children: "Pick one from the sidebar."
-	}) : page ? /* @__PURE__ */ jsx(ComposedPage, { name: page.name }, page.name) : route.key === "new" ? /* @__PURE__ */ jsx(CreatePage, { resource: route.resource }, `${route.resource}/new`) : route.key ? /* @__PURE__ */ jsx(RecordPage, {
-		resource: route.resource,
-		recordKey: route.key
-	}, `${route.resource}/${route.key}`) : /* @__PURE__ */ jsx(ListPage, { resource: route.resource }, route.resource);
+	}) : /* @__PURE__ */ jsx(Notice, {
+		title: "Not found",
+		children: "There is nothing at this address."
+	}) : address.kind === "page" ? page ? /* @__PURE__ */ jsx(ComposedPage, { name: page.name }, page.name) : /* @__PURE__ */ jsxs(Notice, {
+		title: "Not found",
+		children: [
+			"There is no page called ",
+			address.page,
+			"."
+		]
+	}) : address.kind === "create" ? /* @__PURE__ */ jsx(CreatePage, { resource: address.resource }, `${address.resource}/new`) : address.kind === "record" ? /* @__PURE__ */ jsx(RecordPage, {
+		resource: address.resource,
+		recordKey: address.key
+	}, `${address.resource}/${address.key}`) : /* @__PURE__ */ jsx(ListPage, { address }, address.resource);
 	const appShell = /* @__PURE__ */ jsx(AppShell, {
 		sidebarMode: sidebarMode ?? "text-small",
-		activeItem: route.resource ?? "",
+		activeItem: place ?? "",
 		breadcrumb,
-		user: userToShell(user),
+		user: userToShell(acting),
 		onSignOut: () => void signOut(),
 		workspace: current?.organization?.name ?? workspace,
 		navGroups: groups,
+		bottomBar: bottomBarFromMeta(meta, basePath, place),
 		userMenu: [
-			...userMenuFromMeta(meta, basePath, route.resource),
+			...userMenuFromMeta(meta, basePath, place),
 			...organizationSettings ? organizationMenuItems(basePath, path, current) : [],
 			...accountMenuItems(basePath, path, admin)
 		],
@@ -135,6 +169,11 @@ const Routes = ({ workspace, sidebarMode, assistant, runtime }) => {
 			others: organizations.organizations.filter((organization) => organization.id !== current?.organization?.id),
 			onSwitch: (id) => void session.organizations.switchTo(id).then(() => reopenIn(basePath))
 		},
+		roles: role.current?.active ? {
+			active: role.current.active,
+			roles: role.current.roles,
+			onSwitch: role.switchTo
+		} : void 0,
 		onNavigate: open,
 		search: search.available ? {
 			placeholder: search.placeholder,

package/dist/app/batch-failure.js

@@ -4,7 +4,7 @@ const label = (op) => {
 	const resource = typeof op.resource === "string" ? op.resource : op.resource.toModel().name;
 	return op.op === "reorder" ? `reorder ${resource} by ${op.field}` : `${op.op} ${resource}`;
 };
-/** "Operation 2 (reorder invoiceLines by position) failed: ..." so the person knows which part was refused. */
+/** "Operation 2 (reorder invoice_lines by position) failed: ..." so the person knows which part was refused. */
 const describeBatchFailure = (error, ops) => {
 	const index = error.operation;
 	const op = index === void 0 ? void 0 : ops[index];

package/dist/app/bottom-bar-from-meta.js

@@ -0,0 +1,37 @@
+import { iconFor } from "./icons.js";
+import { menuIcon } from "./menu-icons.js";
+import { ExternalLink, LayoutDashboard } from "lucide-react";
+import { appPath } from "@protobase/schema";
+//#region src/app/bottom-bar-from-meta.ts
+/** The bottom bar's tabs from `/meta`: resources and pages open in the app (active while open), links open a new tab. */
+const bottomBarFromMeta = (meta, basePath, activeResource) => (meta.bottomBar?.items ?? []).map((item, index) => {
+	if (item.kind === "link") return {
+		id: `link-${index}`,
+		label: item.label,
+		icon: menuIcon(item.icon, ExternalLink),
+		href: item.href,
+		external: true
+	};
+	if (item.kind === "page") return {
+		id: item.page,
+		label: item.label,
+		icon: menuIcon(item.icon ?? meta.pages[item.page]?.icon, LayoutDashboard),
+		href: appPath({
+			kind: "page",
+			page: item.page
+		}, basePath),
+		active: item.page === activeResource
+	};
+	return {
+		id: item.resource,
+		label: item.label,
+		icon: menuIcon(item.icon, iconFor(item.resource)),
+		href: appPath({
+			kind: "list",
+			resource: item.resource
+		}, basePath),
+		active: item.resource === activeResource
+	};
+});
+//#endregion
+export { bottomBarFromMeta };

package/dist/app/breadcrumb-for.js

@@ -1,21 +1,30 @@
+import { appPath } from "@protobase/schema";
 //#region src/app/breadcrumb-for.ts
 /** Group, then the page or resource list, then the record (or "New"): each with a page of its own links to it. */
-const breadcrumbFor = ({ basePath, route, group, page, resourceLabel, recordTitle }) => {
+const breadcrumbFor = ({ basePath, address, group, page, resourceLabel, recordTitle }) => {
 	const groupCrumb = group ? [group] : [];
 	if (page) return [...groupCrumb, {
 		label: page.title,
-		href: `${basePath}/${page.name}`
+		href: appPath({
+			kind: "page",
+			page: page.name
+		}, basePath)
 	}];
-	if (!route.resource) return ["Admin"];
-	const list = `${basePath}/${route.resource}`;
+	if (!address || address.kind === "page") return ["Admin"];
 	const resource = resourceLabel ? [{
 		label: resourceLabel,
-		href: list
+		href: appPath({
+			kind: "list",
+			resource: address.resource
+		}, basePath)
 	}] : [];
-	if (!route.key) return [...groupCrumb, ...resource];
-	const record = {
-		label: route.key === "new" ? "New" : recordTitle ?? route.key,
-		href: `${list}/${encodeURIComponent(route.key)}`
+	if (address.kind === "list") return [...groupCrumb, ...resource];
+	const record = address.kind === "create" ? {
+		label: "New",
+		href: appPath(address, basePath)
+	} : {
+		label: recordTitle ?? address.key,
+		href: appPath(address, basePath)
 	};
 	return [
 		...groupCrumb,

package/dist/app/create/create-page.js

@@ -1,9 +1,9 @@
 import { useClient } from "../../data/api-provider.js";
 import { recordKey } from "../../live/model-helpers.js";
 import { humanize } from "../../live/naming.js";
-import { useRouter } from "../router.js";
-import { FieldEditor } from "../field-editor.js";
 import { Notice, useAdminMeta, usePermissions } from "../meta-gate.js";
+import { useAppAddress } from "../use-app-address.js";
+import { FieldEditor } from "../field-editor.js";
 import { can } from "../permissions.js";
 import { useLiveSave } from "../use-live-save.js";
 import { CreateRecordForm } from "./create-record-form.js";
@@ -12,7 +12,6 @@ import { useState } from "react";
 import { isApiError } from "@protobase/client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useQueryClient } from "@tanstack/react-query";
-import { encodeKey } from "@protobase/schema";
 //#region src/app/create/create-page.tsx
 const without = (source, name) => Object.fromEntries(Object.entries(source).filter(([key]) => key !== name));
 /** `/:resource/new`: a form from the view's layout; on success it opens the new record. */
@@ -44,7 +43,7 @@ const LoadedCreate = ({ resource }) => {
 	const view = meta.views[resource];
 	const client = useClient();
 	const queryClient = useQueryClient();
-	const { navigate } = useRouter();
+	const { go } = useAppAddress();
 	const noun = view?.names?.singular ?? humanize(resource);
 	const feedback = useLiveSave(view?.saveFeedback ?? "toast", `New ${noun.toLowerCase()}`);
 	const sections = createSections(model, view);
@@ -72,7 +71,11 @@ const LoadedCreate = ({ resource }) => {
 			"facets",
 			"series"
 		]) queryClient.invalidateQueries({ queryKey: [prefix, resource] });
-		navigate(`/${resource}/${encodeKey(recordKey(model, created.record))}`, { replace: true });
+		go({
+			kind: "record",
+			resource,
+			key: recordKey(model, created.record)
+		}, { replace: true });
 	});
 	const formSections = sections.map((section) => ({
 		title: section.title,
@@ -112,7 +115,10 @@ const LoadedCreate = ({ resource }) => {
 		saving: feedback.phase === "saving",
 		message: feedback.message,
 		onSubmit: () => void submit(),
-		onCancel: () => navigate(`/${resource}`)
+		onCancel: () => go({
+			kind: "list",
+			resource
+		})
 	});
 };
 //#endregion

package/dist/app/current-address.d.ts

@@ -0,0 +1,26 @@
+import { AppAddress, FilterLayout, ResourceModel, ViewModel } from "@protobase/schema";
+//#region src/app/current-address.d.ts
+/** A list as the app shows it: every value there, the view's default where the address names none. */
+export type ListAddress = {
+  kind: 'list';
+  resource: string;
+  display: string;
+  filter: string;
+  orderBy: string;
+  filterLayout: FilterLayout;
+};
+/** The address the app shows, as logical values. A record's key is in the text form the record API takes. */
+export type CurrentAddress = ListAddress | {
+  kind: 'record';
+  resource: string;
+  key: string;
+} | {
+  kind: 'create';
+  resource: string;
+} | {
+  kind: 'page';
+  page: string;
+};
+/** What can change about the list the app shows; `undefined` returns a value to its default. */
+export type ListChange = Partial<Omit<ListAddress, 'kind' | 'resource'>>;
+//#endregion

package/dist/app/current-address.js

@@ -0,0 +1,41 @@
+import { defaultOrderBy } from "./list-order.js";
+import { encodeKey, tableDisplay } from "@protobase/schema";
+//#region src/app/current-address.ts
+/** What a list shows when its address names nothing: the view's default display, the list's sort, the filters in a bar. */
+const listDefaults = (model, view) => ({
+	display: view?.list?.default ?? tableDisplay,
+	orderBy: model ? defaultOrderBy(model, view) : "",
+	filterLayout: "bar"
+});
+/** The address as read from the location, with a list's defaults filled in and a record's key as text. */
+const currentAddress = (read, defaults) => {
+	if (read?.kind === "record") return {
+		kind: "record",
+		resource: read.resource,
+		key: encodeKey(read.key)
+	};
+	if (read?.kind !== "list") return read;
+	return {
+		...defaults(read.resource),
+		filter: "",
+		...read
+	};
+};
+/** The list address after `change`, leaving out every value that is empty or its default, so `/<resource>` stays clean. */
+const changedList = (read, change, defaults) => {
+	const next = {
+		...read,
+		...change
+	};
+	const differs = (name) => next[name] !== void 0 && next[name] !== defaults[name];
+	return {
+		kind: "list",
+		resource: read.resource,
+		...next.filter && { filter: next.filter },
+		...differs("display") && { display: next.display },
+		...differs("orderBy") && { orderBy: next.orderBy },
+		...differs("filterLayout") && { filterLayout: next.filterLayout }
+	};
+};
+//#endregion
+export { changedList, currentAddress, listDefaults };

package/dist/app/custom-section.js

@@ -0,0 +1,37 @@
+import { useProjectUi } from "./pages/project-ui.js";
+import { Section } from "../record-view/section.js";
+import { SidebarCard } from "../record-view/record-sidebar.js";
+import { Problem } from "./pages/problem.js";
+import { RecordScope } from "./pages/record-scope.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { unmarkFieldRefs } from "@protobase/schema";
+//#region src/app/custom-section.tsx
+/**
+* A component of the record layout (`l.custom`), drawn with the record around it, so `useLayoutRecord()` gives it, in a
+* section or a sidebar card under its title when it has one. The record page around it stays the framework's.
+*/
+const CustomSection = ({ item, scope }) => {
+	const { components } = useProjectUi();
+	const Component = components?.[item.component];
+	const body = Component ? /* @__PURE__ */ jsx(RecordScope, {
+		value: scope,
+		children: /* @__PURE__ */ jsx(Component, { ...unmarkFieldRefs(item.props ?? {}) })
+	}) : /* @__PURE__ */ jsxs(Problem, { children: [
+		"No component is registered as ",
+		item.component,
+		". Export it from protobase.ui.tsx."
+	] });
+	if (item.sidebar) return item.title ? /* @__PURE__ */ jsx(SidebarCard, {
+		title: item.title,
+		children: body
+	}) : body;
+	return item.title ? /* @__PURE__ */ jsx(Section, {
+		title: item.title,
+		children: body
+	}) : /* @__PURE__ */ jsx("section", {
+		className: "py-8",
+		children: body
+	});
+};
+//#endregion
+export { CustomSection };

package/dist/app/delete/record-diff.js

@@ -1,7 +1,7 @@
 import { humanize } from "../../live/naming.js";
 import { displayValue } from "../../live/display-value.js";
 //#region src/app/delete/record-diff.ts
-const volatile = /* @__PURE__ */ new Set(["updatedAt"]);
+const volatile = /* @__PURE__ */ new Set(["updated_at", "updatedAt"]);
 /** The fields whose stored value differs between two reads of a record, for the "changed since you opened it" dialog. */
 const diffRecords = (model, view, before, after) => Object.values(model.fields).flatMap((field) => {
 	if (volatile.has(field.name) || JSON.stringify(before[field.name] ?? null) === JSON.stringify(after[field.name] ?? null)) return [];

package/dist/app/displays/cards-display.js

@@ -0,0 +1,76 @@
+import { Badge } from "../../primitives/badge.js";
+import { humanize } from "../../live/naming.js";
+import { AppLink } from "../use-app-address.js";
+import { displayValue } from "../../live/display-value.js";
+import { Skeleton } from "../../primitives/skeleton.js";
+import { toneFor } from "../../live/columns-from-model.js";
+import { DisplayFooter, DisplayState } from "./display-frame.js";
+import { cardFields } from "./list-displays.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/app/displays/cards-display.tsx
+const grid = "grid grid-cols-[repeat(auto-fill,minmax(15rem,1fr))] gap-3";
+/** A card per record, opening its page: the title over the subtitle, the badge beside it and small meta fields below. */
+const CardsDisplay = ({ model, view, display, list }) => {
+	const { title, subtitle, badge, meta } = cardFields(model, view, display);
+	const label = (name) => view?.fields[name]?.label ?? humanize(name);
+	const text = (row, name) => {
+		const field = model.fields[name];
+		if (!field) return "";
+		return row.labels[name] ?? displayValue(field, row.record[name], view?.fields[name]);
+	};
+	const plural = (view?.names?.plural ?? humanize(model.name)).toLowerCase();
+	return /* @__PURE__ */ jsxs(DisplayState, {
+		list,
+		empty: `No ${plural} match.`,
+		loading: /* @__PURE__ */ jsx("div", {
+			className: grid,
+			children: Array.from({ length: 6 }, (_, index) => /* @__PURE__ */ jsx(Skeleton, { className: "h-24" }, index))
+		}),
+		children: [/* @__PURE__ */ jsx("ul", {
+			className: grid,
+			"aria-label": view?.names?.plural ?? humanize(model.name),
+			children: list.rows.map((row) => {
+				const status = badge === void 0 ? void 0 : row.record[badge];
+				return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(AppLink, {
+					to: {
+						kind: "record",
+						resource: model.name,
+						key: row.key
+					},
+					className: "flex h-full flex-col gap-1.5 rounded-lg border border-border bg-background p-3 text-[13px] hover:border-border-strong hover:bg-surface focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/30",
+					children: [
+						/* @__PURE__ */ jsxs("span", {
+							className: "flex items-start justify-between gap-2",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "min-w-0 truncate font-medium",
+								children: text(row, title)
+							}), badge !== void 0 && status !== null && status !== void 0 && /* @__PURE__ */ jsx(Badge, {
+								tone: toneFor(String(status)),
+								children: text(row, badge)
+							})]
+						}),
+						subtitle !== void 0 && /* @__PURE__ */ jsx("span", {
+							className: "truncate text-muted-foreground",
+							children: text(row, subtitle)
+						}),
+						meta.length > 0 && /* @__PURE__ */ jsx("dl", {
+							className: "mt-auto flex flex-wrap gap-x-3 gap-y-0.5 pt-1 text-xs text-muted-foreground",
+							children: meta.map((name) => /* @__PURE__ */ jsxs("div", {
+								className: "flex gap-1",
+								children: [/* @__PURE__ */ jsx("dt", {
+									className: "sr-only",
+									children: label(name)
+								}), /* @__PURE__ */ jsx("dd", {
+									className: "tabular-nums",
+									children: text(row, name)
+								})]
+							}, name))
+						})
+					]
+				}) }, row.key);
+			})
+		}), /* @__PURE__ */ jsx(DisplayFooter, { list })]
+	});
+};
+//#endregion
+export { CardsDisplay };

package/dist/app/displays/custom-display.js

@@ -0,0 +1,28 @@
+import { useProjectUi } from "../pages/project-ui.js";
+import { Problem } from "../pages/problem.js";
+import { ListDisplayProvider } from "./display-context.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { unmarkFieldRefs } from "@protobase/schema";
+//#region src/app/displays/custom-display.tsx
+/**
+* A display the project draws: the component registered under its name gets the display's props, field references
+* as the names they reference, and reads the list page's rows with `useListDisplay()`.
+*/
+const CustomDisplay = ({ display, list }) => {
+	const { components } = useProjectUi();
+	const Component = components?.[display.component];
+	if (!Component) return /* @__PURE__ */ jsxs(Problem, { children: [
+		"No component is registered as ",
+		display.component,
+		". Export it from protobase.ui.tsx."
+	] });
+	return /* @__PURE__ */ jsx(ListDisplayProvider, {
+		value: list,
+		children: /* @__PURE__ */ jsx("div", {
+			className: "min-h-0 flex-1 overflow-y-auto",
+			children: /* @__PURE__ */ jsx(Component, { ...unmarkFieldRefs(display.props ?? {}) })
+		})
+	});
+};
+//#endregion
+export { CustomDisplay };

package/dist/app/displays/display-context.d.ts

@@ -0,0 +1,21 @@
+import { ListDisplayRow } from "./list-displays.js";
+import { ReactNode } from "react";
+//#region src/app/displays/display-context.d.ts
+/** The rows a list display draws: the list page loads them through the list API, with its filter, search and order. */
+export type ListDisplay = {
+  resource: string;
+  rows: ListDisplayRow[];
+  /** How many records match, as the server counts them. */
+  total: number;
+  loading: boolean;
+  error: Error | null;
+  /** Whether more rows can be loaded with `loadMore`. */
+  more: boolean;
+  loadMore: () => void;
+};
+/**
+ * The list a custom display (`d.custom`) draws. The list page owns the rows, the address and the data: a display never
+ * fetches its list, changes the address or keeps its own history.
+ */
+export declare const useListDisplay: () => ListDisplay;
+//#endregion

package/dist/app/displays/display-context.js

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/app/displays/display-context.tsx
+const ListDisplayContext = createContext(void 0);
+const ListDisplayProvider = ({ value, children }) => /* @__PURE__ */ jsx(ListDisplayContext.Provider, {
+	value,
+	children
+});
+/**
+* The list a custom display (`d.custom`) draws. The list page owns the rows, the address and the data: a display never
+* fetches its list, changes the address or keeps its own history.
+*/
+const useListDisplay = () => {
+	const display = useContext(ListDisplayContext);
+	if (!display) throw new Error("useListDisplay is used inside a list display, which the list page draws");
+	return display;
+};
+/** The list display around a component, or `undefined` outside one. */
+const useOptionalListDisplay = () => useContext(ListDisplayContext);
+//#endregion
+export { ListDisplayProvider, useListDisplay, useOptionalListDisplay };

package/dist/app/displays/display-controls.js

@@ -0,0 +1,55 @@
+import { humanize } from "../../live/naming.js";
+import { parseSort } from "../list-order.js";
+import { displayChoices, sortFields } from "./list-displays.js";
+import { Segmented } from "../../primitives/segmented.js";
+import { Calendar, Columns3, LayoutGrid, List, SquareKanban, Table2 } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/app/displays/display-controls.tsx
+/** The icons a display's `icon` may name; another name shows the label alone. */
+const icons = {
+	table: Table2,
+	cards: LayoutGrid,
+	kanban: SquareKanban,
+	board: Columns3,
+	list: List,
+	calendar: Calendar
+};
+/** The list page's switch between the table and the view's displays; nothing for a list with only its table. */
+const DisplaySwitch = ({ view, value, onChange }) => {
+	const choices = displayChoices(view);
+	if (choices.length < 2) return null;
+	return /* @__PURE__ */ jsx(Segmented, {
+		label: "Display",
+		value,
+		onChange,
+		options: choices.map((choice) => ({
+			value: choice.name,
+			label: choice.label,
+			icon: choice.icon === void 0 ? void 0 : icons[choice.icon]
+		}))
+	});
+};
+const directions = [["asc", "ascending"], ["desc", "descending"]];
+/** The order of a display without column headers, over the sortable fields it shows and the order the list has now. */
+const SortMenu = ({ model, view, display, orderBy, onChange }) => {
+	const current = parseSort(orderBy);
+	const fields = sortFields(model, view, display);
+	const names = fields.includes(current.columnId) ? fields : [current.columnId, ...fields];
+	const label = (name) => view?.fields[name]?.label ?? humanize(name);
+	return /* @__PURE__ */ jsx("select", {
+		"aria-label": "Sort",
+		value: `${current.columnId} ${current.direction}`,
+		onChange: (event) => onChange(event.target.value),
+		className: "h-7 rounded-md border border-border-strong bg-background px-2 text-xs shadow-sm focus:border-primary focus:outline-none focus:ring-2 focus:ring-primary/20",
+		children: names.flatMap((name) => directions.map(([direction, word]) => /* @__PURE__ */ jsxs("option", {
+			value: `${name} ${direction}`,
+			children: [
+				label(name),
+				", ",
+				word
+			]
+		}, `${name} ${direction}`)))
+	});
+};
+//#endregion
+export { DisplaySwitch, SortMenu };