@protobase/ui 0.10.0 → 0.11.0

package/dist/app/pages/project-ui.d.ts

@@ -1,7 +1,8 @@
 import { ComponentType } from "react";
 import { Client } from "@protobase/client";
+import { AppAddress } from "@protobase/schema";
 //#region src/app/pages/project-ui.d.ts
-/** What a named action's handler gets: the record it runs on (inside a RecordCard or CardRow), the API and the router. */
+/** What a named action's handler gets: the record it runs on (inside a RecordCard or CardRow), the API, and a way to move. */
 export type ActionContext = {
   resource: string;
   record?: Record<string, unknown>;
@@ -9,17 +10,19 @@ export type ActionContext = {
   recordKey?: string;
   etag?: string;
   client: Client;
-  navigate: (to: string) => void;
+  /** Moves the app to an address, such as `{ kind: 'record', resource: 'orders', key: 42 }`. */
+  navigate: (to: AppAddress) => void;
 };
 export type ActionHandler = (context: ActionContext) => void | Promise<void>;
 /**
  * The project's own React code for composed pages: custom components by the name their layout declares
  * (`component('UsageChart')`) or a widget part names, handlers for named actions that have no built-in behaviour, and
- * the shell's slots. `extends` lists UI configs merged in before it (see `mergeUi`); `name` names it in their errors.
+ * the shell's slots. `extends` lists UI configs merged in before it (see `mergeUi`), or whole `protobase.ui.tsx` modules
+ * (`import * as tasksUi from '...'`), their exported components included; `name` names it in their errors.
  */
 export type ProjectUi = {
   name?: string;
-  extends?: ProjectUi[];
+  extends?: Array<ProjectUi | UiModule>;
   components?: Record<string, ComponentType<any>>;
   actions?: Record<string, ActionHandler>;
   /** Rendered in the shell on every page: `actions` at the end of the top bar, `rightPanel` beside the page. */
@@ -28,6 +31,11 @@ export type ProjectUi = {
     rightPanel?: ComponentType;
   };
 };
+/** A `protobase.ui.tsx` module as `import * as` gives it: components exported by name, the rest as the default export. */
+export type UiModule = {
+  readonly default?: ProjectUi;
+  readonly [name: string]: unknown;
+};
 /** Typed identity, for `export default defineUi({ extends, components, actions })` in `protobase.ui.tsx`. */
 export declare const defineUi: (ui: ProjectUi) => ProjectUi;
 //#endregion

package/dist/app/pages/record-actions.js

@@ -1,4 +1,4 @@
-import { useRouter } from "../router.js";
+import { useAppAddress } from "../use-app-address.js";
 import { ActionRail } from "../../record-view/action-rail.js";
 import { ConfirmAction } from "./confirm-action.js";
 import { useActionRunner } from "./use-run-action.js";
@@ -8,7 +8,7 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/app/pages/record-actions.tsx
 /** The record page's named actions, run like the Action block runs them; deleting the record returns to the list. */
 const RecordActions = ({ model, stored, recordKey }) => {
-	const { navigate } = useRouter();
+	const { go } = useAppAddress();
 	const scope = {
 		model,
 		record: stored.record,
@@ -16,7 +16,10 @@ const RecordActions = ({ model, stored, recordKey }) => {
 		etag: stored.etag,
 		permissions: stored.permissions
 	};
-	const runner = useActionRunner(model.name, scope, (action) => action.run?.kind === "delete" && navigate(`/${model.name}`, { replace: true }));
+	const runner = useActionRunner(model.name, scope, (action) => action.run?.kind === "delete" && go({
+		kind: "list",
+		resource: model.name
+	}, { replace: true }));
 	const [asking, setAsking] = useState();
 	if (runner.actions.length === 0) return null;
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ActionRail, { actions: runner.actions.map((action) => ({

package/dist/app/pages/record-table.js

@@ -1,7 +1,7 @@
 import { Button } from "../../primitives/button.js";
 import { humanize } from "../../live/naming.js";
-import { Link } from "../router.js";
 import { useAdminMeta } from "../meta-gate.js";
+import { AppLink } from "../use-app-address.js";
 import { scopeOf } from "./use-layout-data.js";
 import { FieldValue } from "./field-value.js";
 import { usePathValue } from "./use-path-value.js";
@@ -75,8 +75,12 @@ const RecordTable = ({ model, columns, rows, label, pager }) => {
 					className: "border-b last:border-0 hover:bg-surface",
 					children: columns.map((column, index) => /* @__PURE__ */ jsx("td", {
 						className: "px-4 py-2",
-						children: index === 0 && opensRecord ? /* @__PURE__ */ jsx(Link, {
-							to: `/${model.name}/${encodeURIComponent(scope.key)}`,
+						children: index === 0 && opensRecord ? /* @__PURE__ */ jsx(AppLink, {
+							to: {
+								kind: "record",
+								resource: model.name,
+								key: scope.key
+							},
 							className: "font-medium text-primary-text hover:underline",
 							children: cell(row, column)
 						}) : cell(row, column)

package/dist/app/pages/render-node.js

@@ -1,4 +1,5 @@
 import { useProjectUi } from "./project-ui.js";
+import { Problem } from "./problem.js";
 import { ActionBlock } from "./blocks/action.js";
 import { CardBlock } from "./blocks/card.js";
 import { CardRowBlock } from "./blocks/card-row.js";
@@ -14,6 +15,7 @@ import { StatBlock } from "./blocks/stat.js";
 import { TableBlock } from "./blocks/table.js";
 import { Fragment } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { unmarkFieldRefs } from "@protobase/schema";
 import { isLayoutNode } from "@protobase/layout";
 //#region src/app/pages/render-node.tsx
 const blocks = {
@@ -31,11 +33,6 @@ const blocks = {
 	Show: ShowBlock,
 	Link: LinkBlock
 };
-const Problem = ({ children }) => /* @__PURE__ */ jsx("div", {
-	role: "alert",
-	className: "rounded-lg border border-dashed border-warning bg-warning-soft p-3 text-[13px] text-warning-text",
-	children
-});
 const isInline = (child) => typeof child === "string" || !child.custom && child.type === "Link";
 /** Text and links run together as one paragraph, like a sentence with a link in it; other elements stand alone. */
 const renderChildren = (children) => {
@@ -68,7 +65,7 @@ const RenderNode = ({ node }) => {
 			". Add it to the components in protobase.ui.tsx."
 		] });
 		return /* @__PURE__ */ jsx(Custom, {
-			...node.props,
+			...unmarkFieldRefs(node.props),
 			children: node.children.length > 0 ? renderChildren(node.children) : void 0
 		});
 	}

package/dist/app/pages/ui-from-module.d.ts

@@ -0,0 +1,9 @@
+import { ProjectUi } from "./project-ui.js";
+//#region src/app/pages/ui-from-module.d.ts
+/**
+ * The UI config of a `protobase.ui.tsx` module: its default export (`defineUi`, for action handlers, shell slots and
+ * the configs it extends), and every component it exports under a PascalCase name as the component of that name. A
+ * name both exported and in `components` must be the same component.
+ */
+export declare const uiFromModule: (module: Record<string, unknown>) => ProjectUi;
+//#endregion

package/dist/app/pages/ui-from-module.js

@@ -0,0 +1,23 @@
+//#region src/app/pages/ui-from-module.ts
+const componentName = /^[A-Z][A-Za-z0-9]*$/;
+const isComponent = (value) => typeof value === "function" || typeof value === "object" && value !== null && "$$typeof" in value;
+/**
+* The UI config of a `protobase.ui.tsx` module: its default export (`defineUi`, for action handlers, shell slots and
+* the configs it extends), and every component it exports under a PascalCase name as the component of that name. A
+* name both exported and in `components` must be the same component.
+*/
+const uiFromModule = (module) => {
+	const ui = module.default ?? {};
+	const named = Object.entries(module).filter((entry) => entry[0] !== "default" && componentName.test(entry[0]) && isComponent(entry[1]));
+	if (named.length === 0) return ui;
+	for (const [name, component] of named) if (ui.components && Object.hasOwn(ui.components, name) && ui.components[name] !== component) throw new Error(`The component "${name}" is exported by name and given in components as another one; keep the export`);
+	return {
+		...ui,
+		components: {
+			...ui.components,
+			...Object.fromEntries(named)
+		}
+	};
+};
+//#endregion
+export { uiFromModule };

package/dist/app/pages/use-run-action.js

@@ -1,12 +1,13 @@
 import { useClient } from "../../data/api-provider.js";
 import { useToast } from "../../toasts/toast-provider.js";
 import { useProjectUi } from "./project-ui.js";
-import { useRouter } from "../router.js";
 import { useAdminMeta, usePermissions } from "../meta-gate.js";
+import { useAppAddress } from "../use-app-address.js";
 import { can } from "../permissions.js";
-import { fillHref, isAppPath } from "./action-href.js";
+import { fillHref } from "./action-href.js";
 import { useRefreshResource } from "./use-layout-data.js";
 import { useState } from "react";
+import { fillAddress } from "@protobase/schema";
 //#region src/app/pages/use-run-action.ts
 const message = (error) => error instanceof Error ? error.message : "Something went wrong";
 /**
@@ -21,7 +22,7 @@ const useActionRunner = (resource, scope, afterRun) => {
 	const client = useClient();
 	const toast = useToast();
 	const refresh = useRefreshResource();
-	const { navigate } = useRouter();
+	const { go } = useAppAddress();
 	const [running, setRunning] = useState();
 	const actions = views[resource]?.actions ?? [];
 	const blocked = (action) => {
@@ -34,9 +35,8 @@ const useActionRunner = (resource, scope, afterRun) => {
 	const perform = async (action) => {
 		const { run } = action;
 		if (run?.kind === "link") {
-			const href = fillHref(run.href, scope?.record);
-			if (isAppPath(href)) navigate(href);
-			else window.location.assign(href);
+			if ("to" in run) go(fillAddress(run.to, scope?.record));
+			else window.location.assign(fillHref(run.href, scope?.record));
 			return;
 		}
 		if (run?.kind === "update") await client.update(resource, scope.key, run.values, scope.etag ?? "*");
@@ -47,7 +47,7 @@ const useActionRunner = (resource, scope, afterRun) => {
 			recordKey: scope?.key,
 			etag: scope?.etag,
 			client,
-			navigate
+			navigate: go
 		});
 		await refresh(resource);
 		toast.show({

package/dist/app/record-page.js

@@ -7,11 +7,12 @@ import { useClient } from "../data/api-provider.js";
 import { useRecord } from "../data/use-record.js";
 import { recordTitle } from "../live/model-helpers.js";
 import { humanize } from "../live/naming.js";
+import { Notice, useAdminMeta, usePermissions } from "./meta-gate.js";
 import { useNavigationGuard, useRouter } from "./router.js";
+import { useAppAddress } from "./use-app-address.js";
 import { displayValue } from "../live/display-value.js";
 import { ErrorBanner } from "./error-banner.js";
 import { FieldEditor } from "./field-editor.js";
-import { Notice, useAdminMeta, usePermissions } from "./meta-gate.js";
 import { can, fieldAccess } from "./permissions.js";
 import { Field } from "../record-view/field.js";
 import { Section } from "../record-view/section.js";
@@ -21,6 +22,7 @@ import { toneFor } from "../live/columns-from-model.js";
 import { useDeleteFlow } from "./delete/use-delete-flow.js";
 import { useRestore } from "./delete/use-restore.js";
 import { auditField } from "../live/audit-fields.js";
+import { CustomSection } from "./custom-section.js";
 import { RecordActions } from "./pages/record-actions.js";
 import { RecordLines, findLinesResource } from "./record-lines.js";
 import { draftStorageKey } from "./draft-storage.js";
@@ -29,7 +31,7 @@ import { useLinesDraft } from "./use-lines-draft.js";
 import { useRecordEditor } from "./use-record-editor.js";
 import { useRelatedRecords } from "./use-related-records.js";
 import { RelatedSection } from "./related-section.js";
-import { useMemo } from "react";
+import { Fragment, useMemo } from "react";
 import { Check } from "lucide-react";
 import { isApiError } from "@protobase/client";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
@@ -85,7 +87,8 @@ const RecordPage = ({ resource, recordKey }) => {
 };
 const LoadedRecord = ({ model, recordKey, stored }) => {
 	const meta = useAdminMeta();
-	const { basePath, navigate } = useRouter();
+	const { basePath } = useRouter();
+	const { go, open } = useAppAddress();
 	const view = meta.views[model.name];
 	const singular = view?.names?.singular ?? humanize(model.name);
 	const title = recordTitle(model, view, stored.record, recordKey);
@@ -112,7 +115,10 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 		model,
 		view,
 		restore,
-		onDeleted: () => navigate(`/${model.name}`, { replace: true }),
+		onDeleted: () => go({
+			kind: "list",
+			resource: model.name
+		}, { replace: true }),
 		onReview: () => void queryClient.invalidateQueries({ queryKey: keys.record(model.name, recordKey) })
 	});
 	const related = useRelatedRecords(model, view, meta.resources, meta.views, stored.record, basePath);
@@ -149,7 +155,7 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 				value: editor.value(name),
 				stored: stored.record[name],
 				relationLabel: related.labels[name],
-				relationHref: related.hrefs[name],
+				relationTo: related.addresses[name],
 				locked: !canUpdate || access === "read",
 				invalid: Boolean(editor.errors[name]),
 				reveal: field.sensitive ? () => client.reveal(model.name, recordKey, name) : void 0,
@@ -158,6 +164,29 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 			})
 		}, field.sensitive ? `${name}:${stored.etag}` : name);
 	};
+	const firstSidebar = layout.findIndex((item) => item.kind === "sidebar");
+	const summary = /* @__PURE__ */ jsx(MetadataCard, {
+		title: "Summary",
+		rows: sidebarFields.flatMap((name) => {
+			const field = model.fields[name];
+			if (!field || !visible(name)) return [];
+			const text = displayValue(field, stored.record[name], hint(name));
+			return [{
+				label: hint(name)?.label ?? humanize(name),
+				value: field.type === "enum" ? /* @__PURE__ */ jsx(Badge, {
+					tone: toneFor(String(stored.record[name])),
+					children: text
+				}) : /* @__PURE__ */ jsx("strong", { children: text })
+			}];
+		})
+	});
+	const scope = {
+		model,
+		record: stored.record,
+		key: recordKey,
+		etag: stored.etag,
+		permissions: stored.permissions
+	};
 	const saveControls = /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		editor.dirty && /* @__PURE__ */ jsx("span", {
 			className: "text-xs text-muted-foreground",
@@ -243,11 +272,15 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 						className: "grid grid-cols-1 gap-8 md:grid-cols-[minmax(0,1fr)_300px] md:gap-12",
 						children: [/* @__PURE__ */ jsxs("main", {
 							className: "divide-y divide-border",
-							children: [layout.flatMap((item) => {
+							children: [layout.flatMap((item, index) => {
 								if (item.kind === "related") return [/* @__PURE__ */ jsx(RelatedSection, {
 									item,
 									recordKey
 								}, `related:${item.title}`)];
+								if (item.kind === "custom") return item.sidebar ? [] : [/* @__PURE__ */ jsx(CustomSection, {
+									item,
+									scope
+								}, `custom:${index}`)];
 								if (item.kind !== "section") return [];
 								const fields = item.fields.filter((name) => model.fields[name] && visible(name));
 								if (fields.length === 0) return [];
@@ -273,21 +306,11 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 									stored,
 									recordKey
 								}),
-								/* @__PURE__ */ jsx(MetadataCard, {
-									title: "Summary",
-									rows: sidebarFields.flatMap((name) => {
-										const field = model.fields[name];
-										if (!field || !visible(name)) return [];
-										const text = displayValue(field, stored.record[name], hint(name));
-										return [{
-											label: hint(name)?.label ?? humanize(name),
-											value: field.type === "enum" ? /* @__PURE__ */ jsx(Badge, {
-												tone: toneFor(String(stored.record[name])),
-												children: text
-											}) : /* @__PURE__ */ jsx("strong", { children: text })
-										}];
-									})
-								}),
+								firstSidebar === -1 && summary,
+								layout.map((item, index) => item.kind === "custom" && item.sidebar ? /* @__PURE__ */ jsx(CustomSection, {
+									item,
+									scope
+								}, `custom:${index}`) : index === firstSidebar ? /* @__PURE__ */ jsx(Fragment, { children: summary }, "summary") : null),
 								/* @__PURE__ */ jsx(MetadataCard, {
 									title: "Details",
 									rows: [auditField(model, "created"), updatedAt].flatMap((name) => {
@@ -302,7 +325,7 @@ const LoadedRecord = ({ model, recordKey, stored }) => {
 									title: "Related records",
 									children: /* @__PURE__ */ jsx(RelatedRecords, {
 										records: related.records,
-										onNavigate: (href) => navigate(href)
+										onNavigate: open
 									})
 								})
 							]

package/dist/app/related-section.js

@@ -1,7 +1,7 @@
 import { keys } from "../data/query-keys.js";
 import { useClient } from "../data/api-provider.js";
-import { ErrorBanner } from "./error-banner.js";
 import { useAdminMeta } from "./meta-gate.js";
+import { ErrorBanner } from "./error-banner.js";
 import { Section } from "../record-view/section.js";
 import { Skeleton } from "../primitives/skeleton.js";
 import { RecordTable } from "./pages/record-table.js";

package/dist/app/router.js

@@ -59,7 +59,7 @@ const Router = ({ basePath = "", initialUrl, children }) => {
 		setUrl(full);
 	}, [memory]);
 	const navigate = useCallback((to, { replace = false } = {}) => {
-		const full = to.startsWith(basePath) && basePath ? to : `${basePath}${to}`;
+		const full = `${basePath}${to}`;
 		if (pathOf(full) !== pathOf(urlRef.current) && guards.current.size > 0) return setPending({
 			kind: "link",
 			full,
@@ -81,20 +81,12 @@ const Router = ({ basePath = "", initialUrl, children }) => {
 	};
 	const value = useMemo(() => {
 		const parsed = new URL(url, "http://local");
-		const path = parsed.pathname.slice(basePath.length) || "/";
 		return {
-			path,
+			path: parsed.pathname.slice(basePath.length) || "/",
 			params: parsed.searchParams,
 			basePath,
 			navigate,
-			registerGuard,
-			setParams: (patch) => {
-				const next = new URLSearchParams(parsed.searchParams);
-				for (const [name, entry] of Object.entries(patch)) if (entry === void 0 || entry === "") next.delete(name);
-				else next.set(name, entry);
-				const query = next.toString();
-				navigate(`${path}${query ? `?${query}` : ""}`, { replace: true });
-			}
+			registerGuard
 		};
 	}, [
 		url,
@@ -132,14 +124,6 @@ const Link = ({ to, onClick, ...rest }) => {
 		...rest
 	});
 };
-/** `/orders` is a list, `/orders/<key>` a record; composite keys stay in their comma-joined form. */
-const matchRoute = (path) => {
-	const [resource, key] = path.split("/").filter(Boolean);
-	return {
-		resource: resource && decodeURIComponent(resource),
-		key: key && decodeURIComponent(key)
-	};
-};
 /** While `active`, leaving the page asks first (in-app links and closing the tab). */
 const useNavigationGuard = (active) => {
 	const { registerGuard } = useRouter();
@@ -152,4 +136,4 @@ const useNavigationGuard = (active) => {
 	}, [active]);
 };
 //#endregion
-export { Link, Router, matchRoute, useNavigationGuard, useRouter };
+export { Link, Router, useNavigationGuard, useRouter };

package/dist/app/search/search-model.js

@@ -1,6 +1,6 @@
 import { recordKey, recordTitleField } from "../../live/model-helpers.js";
 import { humanize } from "../../live/naming.js";
-import { createWhere, encodeKey, enumLabel, matchedSearchField, printFilter } from "@protobase/schema";
+import { appPath, createWhere, encodeKey, enumLabel, matchedSearchField, printFilter } from "@protobase/schema";
 //#region src/app/search/search-model.ts
 const where = createWhere();
 const searchTargets = (meta) => Object.values(meta.resources).flatMap((model) => {
@@ -63,7 +63,11 @@ const toHit = (target, row, text, basePath = "") => {
 		id: key,
 		title: title.map((name) => shown(target, row, name)).filter(Boolean).join(" ") || key,
 		...subtitle && { subtitle },
-		href: `${basePath}/${target.model.name}/${encodeURIComponent(key)}`
+		href: appPath({
+			kind: "record",
+			resource: target.model.name,
+			key
+		}, basePath)
 	};
 };
 //#endregion

package/dist/app/search/use-global-search.js

@@ -1,6 +1,6 @@
 import { useClient } from "../../data/api-provider.js";
-import { useRouter } from "../router.js";
 import { useAdminMeta } from "../meta-gate.js";
+import { useRouter } from "../router.js";
 import { useDebounced } from "../../lib/use-debounced.js";
 import { searchFields, searchFilter, searchPlaceholder, searchTargets, toHit } from "./search-model.js";
 import { useMemo, useState } from "react";

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

@@ -0,0 +1,24 @@
+import { CurrentAddress, ListAddress, ListChange } from "./current-address.js";
+import { AnchorHTMLAttributes } from "react";
+import { AppAddress } from "@protobase/schema";
+//#region src/app/use-app-address.d.ts
+/**
+ * The app's address as logical values, and the ways to change it: `set` changes the list in place, `go` moves to
+ * another address, `href` is an address for an `<a href>` and `open` follows such an href. Every component reads and
+ * writes the address through this hook, never the query string or a path of its own.
+ */
+export declare const useAppAddress: () => {
+  address: CurrentAddress | undefined;
+  set: (change: ListChange) => void;
+  go: (to: AppAddress, options?: {
+    replace?: boolean;
+  }) => void;
+  href: (to: AppAddress) => string;
+  open: (target: string) => void;
+};
+/** A link to an address in the app: an ordinary anchor that the router follows without reloading the page. */
+export declare const AppLink: ({ to, ...rest }: AnchorHTMLAttributes<HTMLAnchorElement> & {
+  to: AppAddress;
+}) => import("react").JSX.Element;
+//#endregion
+export type { CurrentAddress, ListAddress, ListChange };

package/dist/app/use-app-address.js

@@ -0,0 +1,47 @@
+import { changedList, currentAddress, listDefaults } from "./current-address.js";
+import { useAdminMeta } from "./meta-gate.js";
+import { Link, useRouter } from "./router.js";
+import { useCallback, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+import { appPath, readAppPath } from "@protobase/schema";
+//#region src/app/use-app-address.tsx
+/**
+* The app's address as logical values, and the ways to change it: `set` changes the list in place, `go` moves to
+* another address, `href` is an address for an `<a href>` and `open` follows such an href. Every component reads and
+* writes the address through this hook, never the query string or a path of its own.
+*/
+const useAppAddress = () => {
+	const { path, params, basePath, navigate } = useRouter();
+	const { pages, resources, views } = useAdminMeta();
+	const pageNames = useMemo(() => new Set(Object.keys(pages)), [pages]);
+	const query = params.toString();
+	const read = useMemo(() => readAppPath(query ? `${path}?${query}` : path, pageNames), [
+		path,
+		query,
+		pageNames
+	]);
+	const defaults = useCallback((resource) => listDefaults(resources[resource], views[resource]), [resources, views]);
+	const address = useMemo(() => currentAddress(read, defaults), [read, defaults]);
+	const go = useCallback((to, options) => navigate(appPath(to), options), [navigate]);
+	return {
+		address,
+		set: useCallback((change) => {
+			if (read?.kind !== "list") throw new Error("set changes the list the app shows; use go to move to another address");
+			go(changedList(read, change, defaults(read.resource)), { replace: true });
+		}, [
+			read,
+			defaults,
+			go
+		]),
+		go,
+		href: useCallback((to) => appPath(to, basePath), [basePath]),
+		open: useCallback((target) => navigate(target.startsWith(`${basePath}/`) ? target.slice(basePath.length) : target), [basePath, navigate])
+	};
+};
+/** A link to an address in the app: an ordinary anchor that the router follows without reloading the page. */
+const AppLink = ({ to, ...rest }) => /* @__PURE__ */ jsx(Link, {
+	to: appPath(to),
+	...rest
+});
+//#endregion
+export { AppLink, useAppAddress };

package/dist/app/use-related-records.js

@@ -3,6 +3,7 @@ import { useClient } from "../data/api-provider.js";
 import { humanize } from "../live/naming.js";
 import { fetchLabels } from "../live/relation-labels.js";
 import { useQueries, useQueryClient } from "@tanstack/react-query";
+import { appPath } from "@protobase/schema";
 //#region src/app/use-related-records.ts
 /** One entry per relation the record holds, named by the record it points at. The tenant is left out. */
 const useRelatedRecords = (model, view, resources, views, record, basePath) => {
@@ -17,13 +18,18 @@ const useRelatedRecords = (model, view, resources, views, record, basePath) => {
 			queryFn: async () => (await fetchLabels(queryClient, client, target, [id], views[target.name])).get(id) ?? id
 		};
 	}) });
+	const addresses = relations.map((field) => ({
+		kind: "record",
+		resource: field.relation.resource,
+		key: String(record[field.name])
+	}));
 	return {
-		hrefs: Object.fromEntries(relations.map((field) => [field.name, `/${field.relation.resource}/${encodeURIComponent(String(record[field.name]))}`])),
+		addresses: Object.fromEntries(relations.map((field, index) => [field.name, addresses[index]])),
 		labels: Object.fromEntries(relations.map((field, index) => [field.name, labels[index]?.data])),
 		records: relations.map((field, index) => ({
 			kind: view?.fields[field.name]?.label ?? humanize(field.name),
 			label: labels[index]?.data ?? String(record[field.name]),
-			href: `${basePath}/${field.relation.resource}/${encodeURIComponent(String(record[field.name]))}`
+			href: appPath(addresses[index], basePath)
 		}))
 	};
 };

package/dist/app/user-menu-from-meta.js

@@ -2,6 +2,7 @@ import { humanize } from "../live/naming.js";
 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/user-menu-from-meta.ts
 /** The resources and pages the user menu holds; the sidebar leaves them out. */
 const userMenuResources = (meta) => new Set((meta.userMenu?.items ?? []).flatMap((item) => item.kind === "resource" ? [item.resource] : item.kind === "page" ? [item.page] : []));
@@ -20,7 +21,10 @@ const userMenuFromMeta = (meta, basePath, activeResource) => (meta.userMenu?.ite
 			id: item.page,
 			label: item.label ?? page?.title ?? humanize(item.page),
 			icon: menuIcon(item.icon ?? page?.icon, LayoutDashboard),
-			href: `${basePath}/${item.page}`,
+			href: appPath({
+				kind: "page",
+				page: item.page
+			}, basePath),
 			active: item.page === activeResource
 		};
 	}
@@ -28,7 +32,10 @@ const userMenuFromMeta = (meta, basePath, activeResource) => (meta.userMenu?.ite
 		id: item.resource,
 		label: item.label ?? meta.views[item.resource]?.names?.plural ?? humanize(item.resource),
 		icon: menuIcon(item.icon, iconFor(item.resource)),
-		href: `${basePath}/${item.resource}`,
+		href: appPath({
+			kind: "list",
+			resource: item.resource
+		}, basePath),
 		active: item.resource === activeResource
 	};
 });

package/dist/index.d.ts

@@ -9,7 +9,13 @@ import { useRecord } from "./data/use-record.js";
 import { useFacets, useHistogram, useSeries } from "./data/use-aggregates.js";
 import { isConflict, useUpdateRecord } from "./data/use-update-record.js";
 import { mergeUi } from "./app/pages/merge-ui.js";
+import { uiFromModule } from "./app/pages/ui-from-module.js";
 import { LayoutRecord, useLayoutRecord } from "./app/pages/record-scope.js";
+import { CurrentAddress, ListAddress, ListChange } from "./app/current-address.js";
+import { AppLink, useAppAddress } from "./app/use-app-address.js";
+import { ListDisplayRow } from "./app/displays/list-displays.js";
+import { ListDisplay, useListDisplay } from "./app/displays/display-context.js";
+import { RecordLink } from "./app/displays/record-link.js";
 import { useApiToken } from "./auth/use-api-token.js";
 import { AssistantDock, AssistantDockProps } from "./assistant-dock/assistant-dock.js";
 import { PartView } from "./assistant-dock/part-view.js";
@@ -30,4 +36,4 @@ import { Step, StepList, StepState } from "./step-list/step-list.js";
 import { DiffView, DiffViewProps } from "./diff-view/diff-view.js";
 import { DiffLine, diffStats, parseDiff } from "./diff-view/diff.js";
 import { CompactTable, CompactTableProps } from "./compact-table/compact-table.js";
-export { ActionCard, type ActionCardProps, type ActionContext, type ActionHandler, ApiProvider, type ApiProviderProps, App, type AppProps, AssistantDock, type AssistantDockProps, type BackendData, type BackendRefresh, type CardAction, type CardTone, ChatMessage, ChatThread, type ChatThreadProps, CompactTable, type CompactTableProps, Composer, type ComposerProps, type DiffLine, DiffView, type DiffViewProps, FieldList, type LayoutRecord, type MetaData, PartView, type ProjectUi, SidePanel, type SidePanelProps, type Step, StepList, type StepState, defineUi, diffStats, isConflict, mergeUi, parseDiff, useApiToken, useAssistant, useAssistantClient, useBackendData, useClient, useFacets, useHistogram, useLayoutRecord, useList, useMeta, useRecord, useSeries, useUpdateRecord };
+export { ActionCard, type ActionCardProps, type ActionContext, type ActionHandler, ApiProvider, type ApiProviderProps, App, AppLink, type AppProps, AssistantDock, type AssistantDockProps, type BackendData, type BackendRefresh, type CardAction, type CardTone, ChatMessage, ChatThread, type ChatThreadProps, CompactTable, type CompactTableProps, Composer, type ComposerProps, type CurrentAddress, type DiffLine, DiffView, type DiffViewProps, FieldList, type LayoutRecord, type ListAddress, type ListChange, type ListDisplay, type ListDisplayRow, type MetaData, PartView, type ProjectUi, RecordLink, SidePanel, type SidePanelProps, type Step, StepList, type StepState, defineUi, diffStats, isConflict, mergeUi, parseDiff, uiFromModule, useApiToken, useAppAddress, useAssistant, useAssistantClient, useBackendData, useClient, useFacets, useHistogram, useLayoutRecord, useList, useListDisplay, useMeta, useRecord, useSeries, useUpdateRecord };

package/dist/index.js

@@ -18,10 +18,14 @@ import { AssistantDock } from "./assistant-dock/assistant-dock.js";
 import { useAssistant } from "./assistant-dock/use-assistant.js";
 import { useAssistantClient } from "./assistant-dock/use-assistant-client.js";
 import { useMeta } from "./data/use-meta.js";
+import { AppLink, useAppAddress } from "./app/use-app-address.js";
 import { useFacets, useHistogram, useSeries } from "./data/use-aggregates.js";
+import { useListDisplay } from "./app/displays/display-context.js";
 import { useLayoutRecord } from "./app/pages/record-scope.js";
+import { uiFromModule } from "./app/pages/ui-from-module.js";
 import { mergeUi } from "./app/pages/merge-ui.js";
 import { useList } from "./data/use-list.js";
 import { isConflict, useUpdateRecord } from "./data/use-update-record.js";
 import { App } from "./app/app.js";
-export { ActionCard, ApiProvider, App, AssistantDock, ChatMessage, ChatThread, CompactTable, Composer, DiffView, FieldList, PartView, SidePanel, StepList, defineUi, diffStats, isConflict, mergeUi, parseDiff, useApiToken, useAssistant, useAssistantClient, useBackendData, useClient, useFacets, useHistogram, useLayoutRecord, useList, useMeta, useRecord, useSeries, useUpdateRecord };
+import { RecordLink } from "./app/displays/record-link.js";
+export { ActionCard, ApiProvider, App, AppLink, AssistantDock, ChatMessage, ChatThread, CompactTable, Composer, DiffView, FieldList, PartView, RecordLink, SidePanel, StepList, defineUi, diffStats, isConflict, mergeUi, parseDiff, uiFromModule, useApiToken, useAppAddress, useAssistant, useAssistantClient, useBackendData, useClient, useFacets, useHistogram, useLayoutRecord, useList, useListDisplay, useMeta, useRecord, useSeries, useUpdateRecord };

package/dist/live/use-live-rows.js

@@ -4,7 +4,10 @@ import { createGridLoader } from "./grid-loader.js";
 import { useMemo } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 //#region src/live/use-live-rows.ts
-/** A grid row source backed by the API; `total` is the server's estimate from the first page. */
+/**
+* A grid row source backed by the API; `total` is the server's estimate from the first page. `page` loads one page of
+* the same rows by number, and `key` names them in the query cache, for list displays that page through them.
+*/
 const useLiveRows = ({ resources, views, model, columns, filter, orderBy }) => {
 	const client = useClient();
 	const queryClient = useQueryClient();
@@ -38,7 +41,9 @@ const useLiveRows = ({ resources, views, model, columns, filter, orderBy }) => {
 			loadRows: loader.loadRows
 		} : void 0, [first.data, loader]),
 		error: first.error,
-		isLoading: first.isLoading
+		isLoading: first.isLoading,
+		page: loader.page,
+		key: [...keys.first(model.name, filter, orderBy), columnKey]
 	};
 };
 //#endregion