@protobase/ui 0.10.0 → 0.11.1

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

@@ -1,5 +1,5 @@
-import { Link } from "../../router.js";
 import { useAdminMeta } from "../../meta-gate.js";
+import { AppLink } from "../../use-app-address.js";
 import { Skeleton } from "../../../primitives/skeleton.js";
 import { useLayoutRecord } from "../record-scope.js";
 import { useCount } from "../use-layout-data.js";
@@ -17,9 +17,12 @@ const Count = ({ model, filter }) => {
 		className: "text-[13px] text-danger-text",
 		children: "Could not count"
 	});
-	const href = `/${model.name}${filter ? `?filter=${encodeURIComponent(filter)}` : ""}`;
-	return /* @__PURE__ */ jsx(Link, {
-		to: href,
+	return /* @__PURE__ */ jsx(AppLink, {
+		to: {
+			kind: "list",
+			resource: model.name,
+			filter
+		},
 		className: `${big} hover:text-primary-text`,
 		children: count.data.toLocaleString("en-IE")
 	});

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

@@ -1,5 +1,5 @@
-import { ErrorBanner } from "../../error-banner.js";
 import { useAdminMeta } from "../../meta-gate.js";
+import { ErrorBanner } from "../../error-banner.js";
 import { Skeleton } from "../../../primitives/skeleton.js";
 import { useListPage } from "../use-layout-data.js";
 import { propsOf } from "./block-props.js";

package/dist/app/pages/custom-boundary.js

@@ -0,0 +1,17 @@
+import { Problem } from "./problem.js";
+import { Component } from "react";
+import { jsxs } from "react/jsx-runtime";
+//#region src/app/pages/custom-boundary.tsx
+/** Draws a warning in place of a project's or plugin's component that throws, so one component cannot blank the app. */
+var CustomBoundary = class extends Component {
+	state = { failed: false };
+	static getDerivedStateFromError() {
+		return { failed: true };
+	}
+	render() {
+		if (!this.state.failed) return this.props.children;
+		return this.props.fallback === void 0 ? /* @__PURE__ */ jsxs(Problem, { children: [this.props.name, " could not be drawn."] }) : this.props.fallback;
+	}
+};
+//#endregion
+export { CustomBoundary };

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,12 @@
+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}]`)), {
+/** Two UI configs define one component or action handler differently. */
+var UiConflictError = class extends Error {
+	name = "UiConflictError";
+};
+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
 }];
@@ -8,7 +14,7 @@ const union = (kind, named, pick) => {
 	const merged = {};
 	const owners = /* @__PURE__ */ new Map();
 	for (const { ui, label } of named) for (const [name, value] of Object.entries(pick(ui) ?? {})) {
-		if (Object.hasOwn(merged, name) && merged[name] !== value) throw new Error(`${kind} "${name}" is defined twice, by ${owners.get(name)} and by ${label}; rename one of them`);
+		if (Object.hasOwn(merged, name) && merged[name] !== value) throw new UiConflictError(`${kind} "${name}" is defined twice, by ${owners.get(name)} and by ${label}; rename one of them`);
 		merged[name] = value;
 		owners.set(name, owners.get(name) ?? label);
 	}
@@ -42,4 +48,4 @@ const mergeUi = (...uis) => {
 	};
 };
 //#endregion
-export { mergeUi };
+export { UiConflictError, mergeUi };

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,17 @@ 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;
+/**
+ * Typed identity, for `export default definePlugin({ name, components, actions, shell })` in a plugin's
+ * `protobase.ui.tsx`: a plugin is a UI config the app loads at runtime instead of building it in, its components
+ * exported by name as in a project's.
+ */
+export declare const definePlugin: (plugin: ProjectUi) => ProjectUi;
 //#endregion

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

@@ -2,8 +2,14 @@ import { createContext, useContext } from "react";
 //#region src/app/pages/project-ui.tsx
 /** Typed identity, for `export default defineUi({ extends, components, actions })` in `protobase.ui.tsx`. */
 const defineUi = (ui) => ui;
-/** The project's UI, merged with the UI configs it extends; `ProjectUiProvider` provides it. */
+/**
+* Typed identity, for `export default definePlugin({ name, components, actions, shell })` in a plugin's
+* `protobase.ui.tsx`: a plugin is a UI config the app loads at runtime instead of building it in, its components
+* exported by name as in a project's.
+*/
+const definePlugin = (plugin) => plugin;
+/** The project's UI, merged with the UI configs it extends and the plugins loaded; `PluginGate` or `ProjectUiProvider` provides it. */
 const ProjectUiContext = createContext({});
 const useProjectUi = () => useContext(ProjectUiContext);
 //#endregion
-export { ProjectUiContext, defineUi, useProjectUi };
+export { ProjectUiContext, definePlugin, defineUi, useProjectUi };

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,6 @@
 import { useProjectUi } from "./project-ui.js";
+import { Problem } from "./problem.js";
+import { CustomBoundary } from "./custom-boundary.js";
 import { ActionBlock } from "./blocks/action.js";
 import { CardBlock } from "./blocks/card.js";
 import { CardRowBlock } from "./blocks/card-row.js";
@@ -14,6 +16,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 +34,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) => {
@@ -65,11 +63,14 @@ const RenderNode = ({ node }) => {
 		if (!Custom) return /* @__PURE__ */ jsxs(Problem, { children: [
 			"No component is registered as ",
 			node.type,
-			". Add it to the components in protobase.ui.tsx."
+			". Export it from protobase.ui.tsx, or load the plugin that provides it."
 		] });
-		return /* @__PURE__ */ jsx(Custom, {
-			...node.props,
-			children: node.children.length > 0 ? renderChildren(node.children) : void 0
+		return /* @__PURE__ */ jsx(CustomBoundary, {
+			name: node.type,
+			children: /* @__PURE__ */ jsx(Custom, {
+				...unmarkFieldRefs(node.props),
+				children: node.children.length > 0 ? renderChildren(node.children) : void 0
+			})
 		});
 	}
 	const Block = blocks[node.type];

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 };