@protobase/ui 0.0.0-stage → 0.1.0

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

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

package/dist/app/pages/composed-page.js

@@ -0,0 +1,19 @@
+import { Notice, useAdminMeta } from "../meta-gate.js";
+import { RenderNode } from "./render-node.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/app/pages/composed-page.tsx
+/** `/<page>`: the page's tree as `/meta` gave it to this user. */
+const ComposedPage = ({ name }) => {
+	const page = useAdminMeta().pages[name];
+	if (!page) return /* @__PURE__ */ jsxs(Notice, {
+		title: "Not found",
+		children: [
+			"There is no page called ",
+			name,
+			"."
+		]
+	});
+	return /* @__PURE__ */ jsx(RenderNode, { node: page.tree });
+};
+//#endregion
+export { ComposedPage };

package/dist/app/pages/confirm-action.js

@@ -0,0 +1,20 @@
+import { Button } from "../../primitives/button.js";
+import { Dialog } from "../../primitives/dialog.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/app/pages/confirm-action.tsx
+/** The question an action with `confirm` asks before it runs. */
+const ConfirmAction = ({ action, label, danger, onCancel, onConfirm }) => /* @__PURE__ */ jsx(Dialog, {
+	title: `${label}?`,
+	description: action.confirm,
+	onClose: onCancel,
+	actions: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Button, {
+		onClick: onCancel,
+		children: "Cancel"
+	}), /* @__PURE__ */ jsx(Button, {
+		variant: danger ? "danger" : "primary",
+		onClick: onConfirm,
+		children: label
+	})] })
+});
+//#endregion
+export { ConfirmAction };

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

@@ -0,0 +1,58 @@
+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 { 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";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+//#region src/app/pages/field-value.tsx
+const RelationValue = ({ field, value, known }) => {
+	const { resources, views } = useAdminMeta();
+	const client = useClient();
+	const queryClient = useQueryClient();
+	const target = field.relation ? resources[field.relation.resource] : void 0;
+	const id = String(value);
+	const label = useQuery({
+		queryKey: keys.relatedLabel(target?.name ?? "", id),
+		enabled: Boolean(target) && known === void 0,
+		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)}`,
+		className: "font-medium text-primary-text hover:underline",
+		children: known ?? label.data ?? id
+	});
+};
+/** A stored value as the record page shows it: the view's hints, badges for statuses, names for relations (`relationLabel` when already known). */
+const FieldValue = ({ model, field, value, format, relationLabel }) => {
+	const { views } = useAdminMeta();
+	const hints = {
+		...views[model.name]?.fields[field.name],
+		...format && { format }
+	};
+	if (value === null || value === void 0 || value === "") return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground",
+		children: "—"
+	});
+	if (field.type === "relation") return /* @__PURE__ */ jsx(RelationValue, {
+		field,
+		value,
+		known: relationLabel
+	});
+	const text = displayValue(field, value, hints);
+	if (field.type === "enum" || hints.format === "badge") return /* @__PURE__ */ jsx(Badge, {
+		tone: toneFor(String(value)),
+		children: text
+	});
+	return /* @__PURE__ */ jsx("span", {
+		className: cn(hints.format === "code" && "font-mono text-xs", (field.type === "decimal" || field.type === "integer") && "tabular-nums"),
+		children: text
+	});
+};
+//#endregion
+export { FieldValue };

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

@@ -0,0 +1,25 @@
+import { ComponentType, ReactNode } from "react";
+import { Client } from "@protobase/client";
+//#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. */
+export type ActionContext = {
+  resource: string;
+  record?: Record<string, unknown>;
+  /** The record's key as the URL carries it. */
+  recordKey?: string;
+  etag?: string;
+  client: Client;
+  navigate: (to: string) => 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')`), and handlers for named actions that have no built-in behaviour.
+ */
+export type ProjectUi = {
+  components?: Record<string, ComponentType<any>>;
+  actions?: Record<string, ActionHandler>;
+};
+/** Typed identity, for `export default defineUi({ components, actions })` in `protobase.ui.tsx`. */
+export declare const defineUi: (ui: ProjectUi) => ProjectUi;
+//#endregion

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

@@ -0,0 +1,13 @@
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/app/pages/project-ui.tsx
+/** Typed identity, for `export default defineUi({ components, actions })` in `protobase.ui.tsx`. */
+const defineUi = (ui) => ui;
+const ProjectUiContext = createContext({});
+const ProjectUiProvider = ({ ui, children }) => /* @__PURE__ */ jsx(ProjectUiContext.Provider, {
+	value: ui ?? {},
+	children
+});
+const useProjectUi = () => useContext(ProjectUiContext);
+//#endregion
+export { ProjectUiProvider, defineUi, useProjectUi };

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

@@ -0,0 +1,40 @@
+import { useRouter } from "../router.js";
+import { ActionRail } from "../../record-view/action-rail.js";
+import { ConfirmAction } from "./confirm-action.js";
+import { useActionRunner } from "./use-run-action.js";
+import { actionIcon } from "../action-icon.js";
+import { useState } from "react";
+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 scope = {
+		model,
+		record: stored.record,
+		key: recordKey,
+		etag: stored.etag,
+		permissions: stored.permissions
+	};
+	const runner = useActionRunner(model.name, scope, (action) => action.run?.kind === "delete" && navigate(`/${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) => ({
+		name: action.label,
+		icon: actionIcon(action.icon),
+		blocked: runner.blocked(action),
+		running: runner.running === action.name,
+		onRun: () => action.confirm ? setAsking(action) : void runner.run(action)
+	})) }), asking && /* @__PURE__ */ jsx(ConfirmAction, {
+		action: asking,
+		label: asking.label,
+		danger: asking.run?.kind === "delete",
+		onCancel: () => setAsking(void 0),
+		onConfirm: () => {
+			setAsking(void 0);
+			runner.run(asking);
+		}
+	})] });
+};
+//#endregion
+export { RecordActions };

package/dist/app/pages/record-scope.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from "react";
+import { RecordPermissions } from "@protobase/client";
+import { ResourceModel } from "@protobase/schema";
+//#region src/app/pages/record-scope.d.ts
+/** The record a RecordCard, or one card of a CardRow, shows; Fields, Actions and forms inside it work on it. */
+export type LayoutRecord = {
+  model: ResourceModel;
+  record: Record<string, unknown>;
+  /** The key as the URL carries it. */
+  key: string;
+  etag?: string;
+  permissions?: RecordPermissions;
+};
+/** The record around a custom component in a composed page, or `undefined` outside a RecordCard or CardRow. */
+export declare const useLayoutRecord: () => LayoutRecord | undefined;
+//#endregion

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

@@ -0,0 +1,12 @@
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/app/pages/record-scope.tsx
+const RecordScopeContext = createContext(void 0);
+const RecordScope = ({ value, children }) => /* @__PURE__ */ jsx(RecordScopeContext.Provider, {
+	value,
+	children
+});
+/** The record around a custom component in a composed page, or `undefined` outside a RecordCard or CardRow. */
+const useLayoutRecord = () => useContext(RecordScopeContext);
+//#endregion
+export { RecordScope, useLayoutRecord };

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

@@ -0,0 +1,110 @@
+import { Button } from "../../primitives/button.js";
+import { humanize } from "../../live/naming.js";
+import { Link } from "../router.js";
+import { useAdminMeta } from "../meta-gate.js";
+import { scopeOf } from "./use-layout-data.js";
+import { FieldValue } from "./field-value.js";
+import { usePathValue } from "./use-path-value.js";
+import { useRelationLabels } from "./use-relation-labels.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { resolveFieldPath } from "@protobase/layout";
+//#region src/app/pages/record-table.tsx
+const isPath = (column) => column.includes(".");
+/** The header of a column: the label of the field it ends at, from that field's view. */
+const useHeader = (model) => {
+	const { resources, views } = useAdminMeta();
+	return (column) => {
+		const resolved = resolveFieldPath(resources, model.name, column);
+		const last = resolved.ok ? resolved.steps.at(-1) : void 0;
+		const name = last?.field.name ?? column;
+		return views[last?.model.name ?? model.name]?.fields[name]?.label ?? humanize(name);
+	};
+};
+/** A value through relations (`unitId.propertyId`), fetched like the record page fetches it and cached. */
+const PathCell = ({ model, row, column }) => {
+	const value = usePathValue(scopeOf(model, row), column);
+	if (value.state === "loading") return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground",
+		children: "…"
+	});
+	if (value.state === "missing") return /* @__PURE__ */ jsx("span", {
+		className: "text-muted-foreground",
+		children: "—"
+	});
+	return /* @__PURE__ */ jsx(FieldValue, {
+		model: value.model,
+		field: value.field,
+		value: value.value
+	});
+};
+/**
+* Records as table rows; the first column opens the record, unless it is a relation, which links to the record it
+* names instead (a join record's first column is usually what it joins). Columns may follow relations (`unitId.propertyId`).
+*/
+const RecordTable = ({ model, columns, rows, label, pager }) => {
+	const { resources } = useAdminMeta();
+	const header = useHeader(model);
+	const first = columns[0] === void 0 ? void 0 : resolveFieldPath(resources, model.name, columns[0]);
+	const opensRecord = !first?.ok || first.steps.at(-1).field.type !== "relation";
+	const labels = useRelationLabels(model, columns.filter((column) => !isPath(column)), rows);
+	const cell = (row, column) => isPath(column) ? /* @__PURE__ */ jsx(PathCell, {
+		model,
+		row,
+		column
+	}) : /* @__PURE__ */ jsx(FieldValue, {
+		model,
+		field: model.fields[column],
+		value: row[column],
+		relationLabel: labels.get(column)?.get(String(row[column]))
+	});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
+		className: "-mx-4 overflow-x-auto",
+		children: /* @__PURE__ */ jsxs("table", {
+			className: "w-full min-w-max text-left text-[13px]",
+			children: [/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", {
+				className: "border-b text-xs text-muted-foreground",
+				children: columns.map((column) => /* @__PURE__ */ jsx("th", {
+					scope: "col",
+					className: "px-4 py-2 font-medium",
+					children: header(column)
+				}, column))
+			}) }), /* @__PURE__ */ jsx("tbody", { children: rows.map((row) => {
+				const scope = scopeOf(model, row);
+				return /* @__PURE__ */ jsx("tr", {
+					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)}`,
+							className: "font-medium text-primary-text hover:underline",
+							children: cell(row, column)
+						}) : cell(row, column)
+					}, column))
+				}, scope.key);
+			}) })]
+		})
+	}), pager && (pager.hasPrevious || pager.hasNext) && /* @__PURE__ */ jsxs("nav", {
+		"aria-label": `${label} pages`,
+		className: "mt-3 flex items-center justify-end gap-2 text-xs text-muted-foreground",
+		children: [
+			/* @__PURE__ */ jsxs("span", { children: ["Page ", pager.page] }),
+			/* @__PURE__ */ jsx(Button, {
+				size: "sm",
+				"aria-label": "Previous page",
+				disabled: !pager.hasPrevious || pager.busy,
+				onClick: pager.previous,
+				children: /* @__PURE__ */ jsx(ChevronLeft, { className: "size-3.5" })
+			}),
+			/* @__PURE__ */ jsx(Button, {
+				size: "sm",
+				"aria-label": "Next page",
+				disabled: !pager.hasNext || pager.busy,
+				onClick: pager.next,
+				children: /* @__PURE__ */ jsx(ChevronRight, { className: "size-3.5" })
+			})
+		]
+	})] });
+};
+//#endregion
+export { RecordTable };

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

@@ -0,0 +1,84 @@
+import { useProjectUi } from "./project-ui.js";
+import { ActionBlock } from "./blocks/action.js";
+import { CardBlock } from "./blocks/card.js";
+import { CardRowBlock } from "./blocks/card-row.js";
+import { FieldBlock } from "./blocks/field.js";
+import { GridBlock } from "./blocks/grid.js";
+import { LinkBlock } from "./blocks/link.js";
+import { ModalFormBlock } from "./blocks/modal-form.js";
+import { PageBlock } from "./blocks/page-block.js";
+import { ProgressBlock } from "./blocks/progress.js";
+import { RecordCardBlock } from "./blocks/record-card.js";
+import { ShowBlock } from "./blocks/show.js";
+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 { isLayoutNode } from "@protobase/layout";
+//#region src/app/pages/render-node.tsx
+const blocks = {
+	Page: PageBlock,
+	Grid: GridBlock,
+	Card: CardBlock,
+	Stat: StatBlock,
+	RecordCard: RecordCardBlock,
+	Field: FieldBlock,
+	Table: TableBlock,
+	CardRow: CardRowBlock,
+	Progress: ProgressBlock,
+	ModalForm: ModalFormBlock,
+	Action: ActionBlock,
+	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) => {
+	const runs = [];
+	for (const child of children) {
+		const last = runs.at(-1);
+		if (isInline(child) && last && isInline(last[0])) last.push(child);
+		else runs.push([child]);
+	}
+	return runs.map((run, index) => {
+		const [first] = run;
+		if (!isInline(first)) return /* @__PURE__ */ jsx(RenderNode, { node: first }, index);
+		return /* @__PURE__ */ jsx("p", {
+			className: "text-[13px] leading-relaxed",
+			children: run.map((child, position) => typeof child === "string" ? /* @__PURE__ */ jsx(Fragment, { children: child }, position) : /* @__PURE__ */ jsx(RenderNode, { node: child }, position))
+		}, index);
+	});
+};
+const isElements = (value) => isLayoutNode(value) || Array.isArray(value) && value.length > 0 && value.every(isLayoutNode);
+/** Element props (`actions={...}`) rendered like children; the block decides where they go and in which record. */
+const renderSlots = (node) => Object.fromEntries(Object.entries(node.props).flatMap(([name, value]) => isElements(value) ? [[name, /* @__PURE__ */ jsx(Fragment$1, { children: renderChildren(Array.isArray(value) ? value : [value]) })]] : []));
+/** One element of a composed page: a built-in block, or the project's component registered under its name. */
+const RenderNode = ({ node }) => {
+	const { components } = useProjectUi();
+	if (node.custom) {
+		const Custom = components?.[node.type];
+		if (!Custom) return /* @__PURE__ */ jsxs(Problem, { children: [
+			"No component is registered as ",
+			node.type,
+			". Add it to the components in protobase.ui.tsx."
+		] });
+		return /* @__PURE__ */ jsx(Custom, {
+			...node.props,
+			children: node.children.length > 0 ? renderChildren(node.children) : void 0
+		});
+	}
+	const Block = blocks[node.type];
+	if (!Block) return /* @__PURE__ */ jsxs(Problem, { children: [node.type, " is not a block this version of the app knows."] });
+	return /* @__PURE__ */ jsx(Block, {
+		node,
+		slots: renderSlots(node),
+		children: renderChildren(node.children)
+	});
+};
+//#endregion
+export { RenderNode };

package/dist/app/pages/use-layout-data.js

@@ -0,0 +1,73 @@
+import { keys } from "../../data/query-keys.js";
+import { useClient } from "../../data/api-provider.js";
+import { recordKey } from "../../live/model-helpers.js";
+import { useCallback } from "react";
+import { keepPreviousData, useQuery, useQueryClient } from "@tanstack/react-query";
+import { encodeKey } from "@protobase/schema";
+//#region src/app/pages/use-layout-data.ts
+/** A list item as a record scope: the key as the URL carries it, and the etag and permissions the item carries. */
+const scopeOf = (model, row) => ({
+	model,
+	record: row,
+	key: encodeKey(recordKey(model, row)),
+	etag: typeof row.etag === "string" ? row.etag : void 0,
+	permissions: row.permissions
+});
+/** How many records of `model` match `filter`, counted by the server inside the caller's access rules. */
+const countQuery = (client, model, filter = "") => ({
+	queryKey: keys.count(model.name, filter),
+	queryFn: async () => {
+		const page = await client.list(model.name, {
+			filter: filter || void 0,
+			pageSize: 1,
+			count: "exact",
+			fields: model.primaryKey
+		});
+		return page.totalSize ?? page.totalSizeEstimate;
+	}
+});
+const useCount = (model, filter = "") => useQuery(countQuery(useClient(), model, filter));
+/** The record a RecordCard shows: the one `recordKey` names, or the first that matches `filter` in `sort` order. */
+const useFirstRecord = (model, { filter = "", sort = "", key }) => {
+	const client = useClient();
+	return useQuery({
+		queryKey: key === void 0 ? keys.firstRecord(model.name, filter, sort) : keys.record(model.name, key),
+		queryFn: async () => {
+			if (key !== void 0) {
+				const stored = await client.get(model.name, key);
+				return {
+					...scopeOf(model, stored.record),
+					etag: stored.etag,
+					permissions: stored.permissions
+				};
+			}
+			const page = await client.list(model.name, {
+				filter: filter || void 0,
+				orderBy: sort || void 0,
+				pageSize: 1
+			});
+			return page.items[0] ? scopeOf(model, page.items[0]) : null;
+		}
+	});
+};
+/** One page of a list, from `pageToken`; the previous page stays on screen while the next loads. */
+const useListPage = (model, { filter = "", sort = "", pageSize, pageToken = "" }) => {
+	const client = useClient();
+	return useQuery({
+		queryKey: keys.list(model.name, filter, sort, pageSize, pageToken),
+		placeholderData: keepPreviousData,
+		queryFn: () => client.list(model.name, {
+			filter: filter || void 0,
+			orderBy: sort || void 0,
+			pageSize,
+			pageToken: pageToken || void 0
+		})
+	});
+};
+/** Refetches everything shown of a resource after a write: lists, counts, records and labels. */
+const useRefreshResource = () => {
+	const queryClient = useQueryClient();
+	return useCallback((resource) => queryClient.invalidateQueries({ predicate: (query) => query.queryKey[1] === resource }), [queryClient]);
+};
+//#endregion
+export { countQuery, scopeOf, useCount, useFirstRecord, useListPage, useRefreshResource };

package/dist/app/pages/use-path-value.js

@@ -0,0 +1,65 @@
+import { keys } from "../../data/query-keys.js";
+import { useClient } from "../../data/api-provider.js";
+import { useAdminMeta } from "../meta-gate.js";
+import { useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import { resolveFieldPath } from "@protobase/layout";
+//#region src/app/pages/use-path-value.ts
+/** The steps of `path` from the record around it, or none when it names nothing the caller can read. */
+const stepsOf = (resources, scope, path) => {
+	if (!scope) return [];
+	const resolved = resolveFieldPath(resources, scope.model.name, path);
+	return resolved.ok ? resolved.steps : [];
+};
+/** The query that follows the relations of `steps` from `scope`, fetching each record it passes like a record page. */
+const pathQuery = (client, queryClient, scope, path, steps) => ({
+	queryKey: keys.pathValue(scope?.model.name ?? "", scope?.key ?? "", path),
+	enabled: steps.length > 1,
+	queryFn: async () => {
+		let record = scope.record;
+		for (const step of steps.slice(0, -1)) {
+			const id = record[step.field.name];
+			if (id === null || id === void 0) return null;
+			const target = step.field.relation.resource;
+			record = (await queryClient.fetchQuery({
+				queryKey: keys.record(target, String(id)),
+				queryFn: () => client.get(target, String(id))
+			})).record;
+		}
+		return record[steps.at(-1).field.name] ?? null;
+	}
+});
+const valueOf = (scope, steps, query) => {
+	const last = steps.at(-1);
+	if (!scope || !last) return { state: "missing" };
+	if (steps.length === 1) return {
+		state: "ready",
+		value: scope.record[last.field.name],
+		field: last.field,
+		model: last.model
+	};
+	if (query.isPending) return { state: "loading" };
+	return {
+		state: "ready",
+		value: query.data ?? null,
+		field: last.field,
+		model: last.model
+	};
+};
+/** The value at `path` from the record around it: `status` directly, `plan.name` through the plan it points at. */
+const usePathValue = (scope, path) => {
+	const { resources } = useAdminMeta();
+	const steps = stepsOf(resources, scope, path);
+	const query = useQuery(pathQuery(useClient(), useQueryClient(), scope, path, steps));
+	return valueOf(scope, steps, query);
+};
+/** Several paths at once, for conditions. */
+const usePathValues = (scope, paths) => {
+	const { resources } = useAdminMeta();
+	const client = useClient();
+	const queryClient = useQueryClient();
+	const steps = paths.map((path) => stepsOf(resources, scope, path));
+	const queries = useQueries({ queries: paths.map((path, index) => pathQuery(client, queryClient, scope, path, steps[index])) });
+	return paths.map((_, index) => valueOf(scope, steps[index], queries[index]));
+};
+//#endregion
+export { usePathValue, usePathValues };

package/dist/app/pages/use-relation-labels.js

@@ -0,0 +1,30 @@
+import { keys } from "../../data/query-keys.js";
+import { useClient } from "../../data/api-provider.js";
+import { useAdminMeta } from "../meta-gate.js";
+import { fetchLabels } from "../../live/relation-labels.js";
+import { useQueries, useQueryClient } from "@tanstack/react-query";
+//#region src/app/pages/use-relation-labels.ts
+/** Names for the relation columns of the rows on screen, one list call per column, by column then key. */
+const useRelationLabels = (model, columns, rows) => {
+	const { resources, views } = useAdminMeta();
+	const client = useClient();
+	const queryClient = useQueryClient();
+	const relations = columns.flatMap((name) => {
+		const field = model.fields[name];
+		const target = field?.type === "relation" && field.relation ? resources[field.relation.resource] : void 0;
+		if (!target || target.primaryKey.length !== 1) return [];
+		const ids = [...new Set(rows.flatMap((row) => row[name] === null || row[name] === void 0 ? [] : [String(row[name])]))].sort();
+		return ids.length > 0 ? [{
+			name,
+			target,
+			ids
+		}] : [];
+	});
+	const results = useQueries({ queries: relations.map(({ target, ids }) => ({
+		queryKey: keys.labelMap(target.name, ids.join(",")),
+		queryFn: () => fetchLabels(queryClient, client, target, ids, views[target.name])
+	})) });
+	return new Map(relations.flatMap(({ name }, index) => results[index]?.data ? [[name, results[index].data]] : []));
+};
+//#endregion
+export { useRelationLabels };