@protobase/ui 0.9.0 → 0.11.0

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

@@ -2,10 +2,10 @@ import { cn } from "../../lib/cn.js";
 import { Badge } from "../../primitives/badge.js";
 import { keys } from "../../data/query-keys.js";
 import { useClient } from "../../data/api-provider.js";
-import { Link } from "../router.js";
+import { useAdminMeta } from "../meta-gate.js";
+import { AppLink } from "../use-app-address.js";
 import { fileShown } from "../../live/file-values.js";
 import { displayValue } from "../../live/display-value.js";
-import { useAdminMeta } from "../meta-gate.js";
 import { toneFor } from "../../live/columns-from-model.js";
 import { fetchLabels } from "../../live/relation-labels.js";
 import { jsx } from "react/jsx-runtime";
@@ -23,8 +23,12 @@ const RelationValue = ({ field, value, known }) => {
 		queryFn: async () => (await fetchLabels(queryClient, client, target, [id], views[target.name])).get(id) ?? id
 	});
 	if (!target) return /* @__PURE__ */ jsx("span", { children: id });
-	return /* @__PURE__ */ jsx(Link, {
-		to: `/${target.name}/${encodeURIComponent(id)}`,
+	return /* @__PURE__ */ jsx(AppLink, {
+		to: {
+			kind: "record",
+			resource: target.name,
+			key: id
+		},
 		className: "font-medium text-primary-text hover:underline",
 		children: known ?? label.data ?? id
 	});

package/dist/app/pages/merge-ui.js

@@ -1,6 +1,8 @@
+import { uiFromModule } from "./ui-from-module.js";
 import { jsx } from "react/jsx-runtime";
 //#region src/app/pages/merge-ui.tsx
-const flatten = (ui, label) => [...(ui.extends ?? []).flatMap((parent, index) => flatten(parent, parent.name ?? `${label} extends[${index}]`)), {
+const configOf = (parent) => Object.keys(parent).some((key) => key === "default" || /^[A-Z]/.test(key)) ? uiFromModule(parent) : parent;
+const flatten = (ui, label) => [...(ui.extends ?? []).map(configOf).flatMap((parent, index) => flatten(parent, parent.name ?? `${label} extends[${index}]`)), {
 	ui,
 	label
 }];

package/dist/app/pages/problem.js

@@ -0,0 +1,10 @@
+import { jsx } from "react/jsx-runtime";
+//#region src/app/pages/problem.tsx
+/** A warning in place of something the app cannot draw, such as a component no one registered. */
+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
+});
+//#endregion
+export { Problem };

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";
@@ -20,6 +21,8 @@ import { RecordHeader } from "../record-view/record-header.js";
 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";
@@ -28,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";
@@ -84,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);
@@ -111,14 +115,18 @@ 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);
 	const layout = layoutFor(model, view);
 	const sidebarFields = layout.flatMap((item) => item.kind === "sidebar" ? item.fields : []);
 	const status = model.fields.status?.type === "enum" ? String(stored.record.status) : void 0;
-	const updated = stored.record.updatedAt ? Math.max(0, Math.round((Date.now() - Date.parse(String(stored.record.updatedAt))) / 1e3)) : void 0;
+	const updatedAt = auditField(model, "updated");
+	const updated = updatedAt && stored.record[updatedAt] ? Math.max(0, Math.round((Date.now() - Date.parse(String(stored.record[updatedAt]))) / 1e3)) : void 0;
 	const hint = (name) => view?.fields[name];
 	const visible = (name) => fieldAccess(stored.permissions, name) !== "hidden";
 	const fieldView = (name) => {
@@ -147,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,
@@ -156,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",
@@ -241,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 [];
@@ -271,26 +306,16 @@ 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: ["createdAt", "updatedAt"].flatMap((name) => {
-										const field = model.fields[name];
-										return field && visible(name) ? [{
+									rows: [auditField(model, "created"), updatedAt].flatMap((name) => {
+										const field = name ? model.fields[name] : void 0;
+										return name && field && visible(name) ? [{
 											label: hint(name)?.label ?? humanize(name),
 											value: displayValue(field, stored.record[name], hint(name))
 										}] : [];
@@ -300,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)
 		}))
 	};
 };