@protobase/layout 0.10.0 → 0.11.1

package/dist/block-specs.js

@@ -127,7 +127,10 @@ const blockSpecs = {
 	},
 	Link: {
 		children: true,
-		props: { href: required("text") }
+		props: {
+			href: optional("text"),
+			to: optional("address")
+		}
 	}
 };
 const formats = [
@@ -158,7 +161,8 @@ const checks = {
 	mode: [(value) => value === "create" || value === "edit", "create or edit"],
 	label: [(value) => typeof value === "string" || value === false, "text, or false for none"],
 	amount: [(value) => typeof value === "string" || typeof value === "number" && Number.isFinite(value), "a number or a field name"],
-	scalar: [(value) => typeof value === "string" || typeof value === "number", "text or a number"]
+	scalar: [(value) => typeof value === "string" || typeof value === "number", "text or a number"],
+	address: [(value) => isObject(value) && !isLayoutNode(value) && typeof value.kind === "string", "an address, such as { kind: 'list', resource: 'orders' }"]
 };
 /** Problems with one element's props and children against its block's spec. */
 const propProblems = (spec, props, childCount) => {

package/dist/blocks.d.ts

@@ -1,5 +1,5 @@
 import { Block, LayoutChildren, LayoutNode, LayoutValue } from "./node.js";
-import { FieldFormat } from "@protobase/schema";
+import { AppAddress, FieldFormat } from "@protobase/schema";
 //#region src/blocks.d.ts
 /** One element or several, for slots such as a card's header `actions`. */
 export type Elements = LayoutNode | LayoutNode[];
@@ -100,8 +100,17 @@ export type ShowProps = {
   when: string;
   children?: LayoutChildren;
 };
-export type LinkProps = {
+/**
+ * A link: `to` an address in the app, `{field}` in it filled from the record around it, or an `href` that leaves the
+ * app (`https:`, `mailto:`). One of the two.
+ */
+export type LinkProps = ({
+  to: AppAddress;
+  href?: never;
+} | {
   href: string;
+  to?: never;
+}) & {
   children?: LayoutChildren;
 };
 export declare const Page: Block<PageProps>;

package/dist/check-page.d.ts

@@ -5,6 +5,8 @@ export type PageCheckInput = {
   models: Record<string, ResourceModel>;
   /** The named actions of a resource, from all of its views. */
   actions: (resource: string) => ReadonlySet<string>;
+  /** The composed pages' names, which links may go to; `checkPages` fills them in. */
+  pages?: ReadonlySet<string>;
 };
 /** Throws one error listing every problem of every page, including names that collide with each other or a resource. */
 export declare const checkPages: (pages: PageModel[], input: PageCheckInput) => void;

package/dist/check-page.js

@@ -1,7 +1,8 @@
+import { dataProps } from "./node.js";
 import { countedResource, parseCondition } from "./condition.js";
 import { walkTree } from "./walk.js";
 import { resolveFieldPath } from "./field-path.js";
-import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
+import { addressErrors, checkFilter, checkOrderBy, fieldRefsIn, parseFilter, parseOrderBy } from "@protobase/schema";
 //#region src/check-page.ts
 const filterProblem = (model, source) => {
 	const parsed = parseFilter(source);
@@ -19,7 +20,9 @@ const sortProblem = (model, source) => {
 const text = (value) => typeof value === "string" ? value : void 0;
 /** The resource an element reads or writes: its own `resource` prop, or the record around it. */
 const elementResource = (node, scope) => text(node.props.resource) ?? (scope.record ? scope.resource : void 0);
-const nodeProblems = (node, scope, { models, actions }) => {
+/** The record a link's `{field}` placeholders read: the one around it, when there is one. */
+const linkSource = (models, scope) => scope.record && scope.resource !== void 0 ? models[scope.resource] : void 0;
+const nodeProblems = (node, scope, { models, actions, pages }) => {
 	const problems = [];
 	const resource = elementResource(node, scope);
 	const own = text(node.props.resource);
@@ -63,6 +66,13 @@ const nodeProblems = (node, scope, { models, actions }) => {
 		case "Action":
 			if (resource !== void 0 && !actions(resource).has(String(node.props.name))) problems.push(`no action "${node.props.name}" on ${resource}; declare it with view('${resource}').actions(...)`);
 			break;
+		case "Link":
+			if (node.props.to !== void 0) problems.push(...addressErrors(node.props.to, {
+				models,
+				pages,
+				source: linkSource(models, scope)
+			}).map((error) => `to: ${error}`));
+			break;
 		case "Show": {
 			const parsed = parseCondition(String(node.props.when));
 			if (!parsed.ok) break;
@@ -79,12 +89,22 @@ const nodeProblems = (node, scope, { models, actions }) => {
 	}
 	return problems;
 };
+const customProblems = (node, scope, { models }) => {
+	const own = text(node.props.resource);
+	if (own !== void 0 && !models[own]) return [`unknown resource "${own}"`];
+	const resource = elementResource(node, scope);
+	return fieldRefsIn(dataProps(node)).flatMap((path) => {
+		if (resource === void 0) return [`field reference "${path}" needs a record around it, or a "resource" prop`];
+		const resolved = resolveFieldPath(models, resource, path);
+		return resolved.ok ? [] : [resolved.message];
+	});
+};
 /** Everything a page names that the models do not have: resources, fields, filters, sorts, actions and conditions. */
 const pageProblems = (page, input) => {
 	const problems = [];
 	walkTree(page.tree, (node, { path, scope }) => {
-		if (node.custom) return;
-		for (const problem of nodeProblems(node, scope, input)) problems.push(`${path}: ${problem}`);
+		const found = node.custom ? customProblems(node, scope, input) : nodeProblems(node, scope, input);
+		for (const problem of found) problems.push(`${path}: ${problem}`);
 	});
 	return problems;
 };
@@ -92,13 +112,17 @@ const pageProblems = (page, input) => {
 const checkPages = (pages, input) => {
 	const problems = [];
 	const seen = /* @__PURE__ */ new Set();
+	const named = {
+		...input,
+		pages: input.pages ?? new Set(pages.map((page) => page.name))
+	};
 	for (const page of pages) {
 		if (seen.has(page.name)) problems.push(`Page "${page.name}" is defined twice`);
 		if (input.models[page.name]) problems.push(`Page "${page.name}" has the name of a resource; both would be at /${page.name}`);
 		seen.add(page.name);
-		for (const problem of pageProblems(page, input)) problems.push(`Page "${page.name}": ${problem}`);
+		for (const problem of pageProblems(page, named)) problems.push(`Page "${page.name}": ${problem}`);
 	}
 	if (problems.length > 0) throw new Error(`The pages do not match the resources:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
 };
 //#endregion
-export { checkPages, elementResource, pageProblems };
+export { checkPages, elementResource, linkSource, pageProblems };

package/dist/check-structure.js

@@ -1,6 +1,7 @@
 import { blockSpecs, propProblems } from "./block-specs.js";
 import { parseCondition } from "./condition.js";
 import { walkTree } from "./walk.js";
+import { appHrefError } from "@protobase/schema";
 //#region src/check-structure.ts
 /** Problems that need a record around the element, which only a `RecordCard` or a `CardRow` card provides. */
 const recordProblems = (node, scope) => {
@@ -24,6 +25,11 @@ const statProblems = ({ props }) => {
 	].filter((name) => props[name] !== void 0).length !== 1) return ["takes exactly one of \"value\", \"resource\" (a count) and \"field\""];
 	return props.filter !== void 0 && props.resource === void 0 ? ["\"filter\" needs \"resource\""] : [];
 };
+const linkProblems = ({ props }) => {
+	if (props.to === void 0 === (props.href === void 0)) return ["takes exactly one of \"to\" (an address in the app) and \"href\" (a link that leaves it)"];
+	const error = typeof props.href === "string" ? appHrefError(props.href) : void 0;
+	return error ? [error] : [];
+};
 /**
 * Checks a page's tree without the models: the root is one `Page`, every built-in element has known props of the right
 * kind, elements that show a record's fields sit inside one, and conditions parse. Returns the problems, each with
@@ -41,6 +47,7 @@ const structureProblems = (tree) => {
 		propProblems(spec, node.props, node.children.length).forEach(report);
 		recordProblems(node, scope).forEach(report);
 		if (node.type === "Stat") statProblems(node).forEach(report);
+		if (node.type === "Link") linkProblems(node).forEach(report);
 		if (node.type === "Show" && typeof node.props.when === "string") {
 			const parsed = parseCondition(node.props.when);
 			if (!parsed.ok) report(`"when" is not a valid condition: ${parsed.message}`);

package/dist/component.d.ts

@@ -1,10 +1,17 @@
 import { Block, LayoutChildren } from "./node.js";
 //#region src/component.d.ts
+/** `plugin`: the plugin that provides the component at runtime, instead of the project's protobase.ui.tsx. */
+export type ComponentOptions = {
+  plugin?: string;
+};
 /**
  * Declares a custom component for layouts: `<UsageChart metric="cpu" />` becomes an element of type `UsageChart`,
  * which the app renders with the React component registered under that name. Its props must be static values too.
+ * With `plugin`, a plugin provides it, so `protobase build` does not look for it in protobase.ui.tsx.
  */
-export declare const component: <P extends object = Record<string, never>>(name: string) => Block<P & {
+export declare const component: <P extends object = Record<string, never>>(name: string, options?: ComponentOptions) => Block<P & {
   children?: LayoutChildren;
-}>;
+}> & {
+  readonly plugin?: string;
+};
 //#endregion

package/dist/component.js

@@ -5,11 +5,14 @@ const componentName = /^[A-Z][A-Za-z0-9]*$/;
 /**
 * Declares a custom component for layouts: `<UsageChart metric="cpu" />` becomes an element of type `UsageChart`,
 * which the app renders with the React component registered under that name. Its props must be static values too.
+* With `plugin`, a plugin provides it, so `protobase build` does not look for it in protobase.ui.tsx.
 */
-const component = (name) => {
+const component = (name, options = {}) => {
 	if (!componentName.test(name)) throw new Error(`Component name "${name}" must be PascalCase, such as UsageChart`);
 	if (Object.hasOwn(blockSpecs, name) || name === "Fragment") throw new Error(`"${name}" is a built-in block; give the custom component another name`);
-	return defineBlock(name, true);
+	if (options.plugin !== void 0 && options.plugin.trim() === "") throw new Error(`component('${name}') names an empty plugin; name the plugin that provides it`);
+	const block = defineBlock(name, true);
+	return options.plugin === void 0 ? block : Object.assign(block, { plugin: options.plugin });
 };
 //#endregion
 export { component };

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import { Block, LayoutChild, LayoutChildren, LayoutNode, LayoutValue, isLayoutNode } from "./node.js";
 import { Action, ActionProps, ButtonVariant, Card, CardProps, CardRow, CardRowProps, DataProps, Elements, Field, FieldProps, Grid, GridProps, GridSpan, Link, LinkProps, ModalForm, ModalFormProps, Page, PageProps, Progress, ProgressProps, RecordCard, RecordCardProps, Show, ShowProps, Stat, StatProps, Table, TableProps } from "./blocks.js";
-import { component } from "./component.js";
+import { ComponentOptions, component } from "./component.js";
 import { PageDefinition, PageModel, PageOptions, isPageDefinition, page } from "./page.js";
 import { checkPages } from "./check-page.js";
 import { prunePage } from "./prune-page.js";
 import { countedResource, evaluateCondition, parseCondition } from "./condition.js";
 import { PathStep, resolveFieldPath } from "./field-path.js";
 import { jsx_runtime_d_exports } from "./jsx-runtime.js";
-export { Action, type ActionProps, type Block, type ButtonVariant, Card, type CardProps, CardRow, type CardRowProps, type DataProps, type Elements, Field, type FieldProps, Grid, type GridProps, type GridSpan, type LayoutChild, type LayoutChildren, type LayoutNode, type LayoutValue, Link, type LinkProps, ModalForm, type ModalFormProps, Page, type PageDefinition, type PageModel, type PageOptions, type PageProps, type PathStep, Progress, type ProgressProps, RecordCard, type RecordCardProps, Show, type ShowProps, Stat, type StatProps, Table, type TableProps, checkPages, component, countedResource, evaluateCondition, isLayoutNode, isPageDefinition, jsx_runtime_d_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath };
+import { FieldRefValue, fieldRef } from "@protobase/schema";
+export { Action, type ActionProps, type Block, type ButtonVariant, Card, type CardProps, CardRow, type CardRowProps, type ComponentOptions, type DataProps, type Elements, Field, type FieldProps, type FieldRefValue, Grid, type GridProps, type GridSpan, type LayoutChild, type LayoutChildren, type LayoutNode, type LayoutValue, Link, type LinkProps, ModalForm, type ModalFormProps, Page, type PageDefinition, type PageModel, type PageOptions, type PageProps, type PathStep, Progress, type ProgressProps, RecordCard, type RecordCardProps, Show, type ShowProps, Stat, type StatProps, Table, type TableProps, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_d_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath };

package/dist/index.js

@@ -7,4 +7,5 @@ import { resolveFieldPath } from "./field-path.js";
 import { checkPages } from "./check-page.js";
 import { prunePage } from "./prune-page.js";
 import { jsx_runtime_exports } from "./jsx-runtime.js";
-export { Action, Card, CardRow, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, Show, Stat, Table, checkPages, component, countedResource, evaluateCondition, isLayoutNode, isPageDefinition, jsx_runtime_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath };
+import { fieldRef } from "@protobase/schema";
+export { Action, Card, CardRow, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, Show, Stat, Table, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath };

package/dist/node.js

@@ -1,4 +1,6 @@
 //#region src/node.ts
 const isLayoutNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.type === "string" && Array.isArray(value.children);
+/** An element's props without the elements it holds (`actions={...}`), which are walked as elements of their own. */
+const dataProps = (node) => Object.fromEntries(Object.entries(node.props).filter(([, value]) => !isLayoutNode(value) && !(Array.isArray(value) && value.length > 0 && value.every(isLayoutNode))));
 //#endregion
-export { isLayoutNode };
+export { dataProps, isLayoutNode };

package/dist/prune-page.d.ts

@@ -13,8 +13,9 @@ export type CallerAccess = {
 };
 /**
  * The page as one caller may see it, or `undefined` when its roles leave the caller out. Every element that names a
- * resource, field, filter, sort or action the caller cannot use is left out, with what it contains; table columns
- * and form fields are narrowed to what the caller may read and write. Data still comes from the API, which applies
+ * resource, field, filter, sort or action the caller cannot use is left out, with what it contains, custom components
+ * by their `resource` and field references (`fieldRef`) too; table columns and form fields are narrowed to what the
+ * caller may read and write. Data still comes from the API, which applies
  * the same access rules (row filters included) to every request.
  */
 export declare const prunePage: (page: PageModel, roles: readonly string[], access: CallerAccess) => PageModel | undefined;

package/dist/prune-page.js

@@ -1,8 +1,9 @@
+import { dataProps } from "./node.js";
 import { countedResource, parseCondition } from "./condition.js";
 import { mapTree } from "./walk.js";
 import { resolveFieldPath } from "./field-path.js";
-import { elementResource } from "./check-page.js";
-import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
+import { elementResource, linkSource } from "./check-page.js";
+import { addressErrors, checkFilter, checkOrderBy, parseFilter, parseOrderBy, pruneByShape, shapes } from "@protobase/schema";
 //#region src/prune-page.ts
 const text = (value) => typeof value === "string" ? value : void 0;
 const filterFits = (model, source) => {
@@ -16,8 +17,15 @@ const sortFits = (model, source) => {
 	return parsed.ok && checkOrderBy(model, parsed.items).ok;
 };
 const writable = (model, name) => Object.hasOwn(model.fields, name) && !model.fields[name].readOnly;
+const pruneCustom = (node, scope, { models }) => {
+	const own = text(node.props.resource);
+	if (own !== void 0 && !models[own]) return null;
+	const resource = elementResource(node, scope);
+	const readable = (path) => resource !== void 0 && resolveFieldPath(models, resource, path).ok;
+	return pruneByShape(dataProps(node), shapes.refs, readable) === void 0 ? null : node;
+};
 const prune = (node, scope, access) => {
-	if (node.custom) return node;
+	if (node.custom) return pruneCustom(node, scope, access);
 	const { models } = access;
 	const own = text(node.props.resource);
 	if (own !== void 0 && !models[own]) return null;
@@ -56,6 +64,10 @@ const prune = (node, scope, access) => {
 			} : null;
 		}
 		case "Action": return resource !== void 0 && model && access.actions(resource).has(String(node.props.name)) ? node : null;
+		case "Link": return node.props.to === void 0 || addressErrors(node.props.to, {
+			models,
+			source: linkSource(models, scope)
+		}).length === 0 ? node : null;
 		case "Show": {
 			const parsed = parseCondition(String(node.props.when));
 			if (!parsed.ok) return null;
@@ -70,8 +82,9 @@ const prune = (node, scope, access) => {
 };
 /**
 * The page as one caller may see it, or `undefined` when its roles leave the caller out. Every element that names a
-* resource, field, filter, sort or action the caller cannot use is left out, with what it contains; table columns
-* and form fields are narrowed to what the caller may read and write. Data still comes from the API, which applies
+* resource, field, filter, sort or action the caller cannot use is left out, with what it contains, custom components
+* by their `resource` and field references (`fieldRef`) too; table columns and form fields are narrowed to what the
+* caller may read and write. Data still comes from the API, which applies
 * the same access rules (row filters included) to every request.
 */
 const prunePage = (page, roles, access) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/layout",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Composed pages for Protobase, written as JSX that compiles to plain data, with its JSX runtime.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/schema": "0.10.0",
+    "@protobase/schema": "0.11.1",
     "aip-parsers": "^1.0.0"
   }
 }