@protobase/schema 0.10.0 → 0.11.1

package/dist/address-errors.d.ts

@@ -0,0 +1,16 @@
+import { AppAddress, ResourceModel } from "./model.js";
+//#region src/address-errors.d.ts
+export type AddressCheck = {
+  /** The resources; against a caller's restricted models, the check says whether that caller can follow the link. */
+  models: Record<string, ResourceModel>;
+  /** The composed pages; without them a page's name is not checked. */
+  pages?: ReadonlySet<string>;
+  /** The resource of the record the link sits on, whose fields its `{field}` placeholders name. */
+  source?: ResourceModel;
+};
+/**
+ * What is wrong with a link's address against these models: an unknown resource or page, a `{field}` the record it sits
+ * on does not have, or a filter or order naming fields the resource does not have. Empty when it can be followed.
+ */
+export declare const addressErrors: (to: AppAddress, { models, pages, source }: AddressCheck) => string[];
+//#endregion

package/dist/address-errors.js

@@ -0,0 +1,59 @@
+import { parseFilter } from "./filter/parse.js";
+import { checkFilter } from "./filter/check.js";
+import { checkOrderBy, parseOrderBy } from "./filter/order-by.js";
+import { addressPlaceholders } from "./address-template.js";
+//#region src/address-errors.ts
+const nameErrors = [
+	"unknown-field",
+	"not-filterable",
+	"not-sortable",
+	"unsupported-traversal",
+	"invalid-traversal"
+];
+const withSamples = (filter) => filter.replace(/(["']?)\{[A-Za-z_][A-Za-z0-9_]*\}\1/g, (_, quote) => quote ? `${quote}x${quote}` : "0");
+const filterErrors = (model, filter) => {
+	const parsed = parseFilter(withSamples(filter));
+	if (!parsed.ok) return parsed.errors.map((error) => `filter: ${error.message}`);
+	if (!parsed.ast) return [];
+	const checked = checkFilter(model, parsed.ast);
+	return checked.ok ? [] : checked.errors.filter((error) => nameErrors.includes(error.code)).map((error) => `filter: ${error.message}`);
+};
+const orderErrors = (model, orderBy) => {
+	if (addressPlaceholders({
+		kind: "list",
+		resource: model.name,
+		orderBy
+	}).length > 0) return [];
+	const parsed = parseOrderBy(orderBy);
+	if (!parsed.ok) return parsed.errors.map((error) => `orderBy: ${error.message}`);
+	const checked = checkOrderBy(model, parsed.items);
+	return checked.ok ? [] : checked.errors.map((error) => `orderBy: ${error.message}`);
+};
+/**
+* What is wrong with a link's address against these models: an unknown resource or page, a `{field}` the record it sits
+* on does not have, or a filter or order naming fields the resource does not have. Empty when it can be followed.
+*/
+const addressErrors = (to, { models, pages, source }) => {
+	const placeholders = addressPlaceholders(to).flatMap((name) => {
+		if (!source) return [`"{${name}}" takes a value from the record, but the link sits on none`];
+		return Object.hasOwn(source.fields, name) ? [] : [`"{${name}}" is not a field of ${source.name}`];
+	});
+	switch (to.kind) {
+		case "page": return pages && !pages.has(to.page) ? [`unknown page "${to.page}"`] : [];
+		case "list":
+		case "record":
+		case "create": {
+			const target = Object.hasOwn(models, to.resource) ? models[to.resource] : void 0;
+			if (!target) return [`unknown resource "${to.resource}"`];
+			if (to.kind !== "list") return placeholders;
+			return [
+				...placeholders,
+				...to.filter ? filterErrors(target, to.filter) : [],
+				...to.orderBy ? orderErrors(target, to.orderBy) : []
+			];
+		}
+		default: return [`an address's kind is list, record, create or page, not "${String(to.kind)}"`];
+	}
+};
+//#endregion
+export { addressErrors };

package/dist/address-template.d.ts

@@ -0,0 +1,16 @@
+import { AppAddress } from "./model.js";
+//#region src/address-template.d.ts
+/** The fields whose values a link's address takes from the record, from its `{field}` placeholders. */
+export declare const addressPlaceholders: (to: AppAddress) => string[];
+/** The fields an href takes from the record, from its `{field}` placeholders. */
+export declare const hrefPlaceholders: (href: string) => string[];
+/** `to` with every `{field}` in its key, filter and order replaced by the record's value; a missing value becomes empty. */
+export declare const fillAddress: (to: AppAddress, record?: Record<string, unknown>) => AppAddress;
+/**
+ * Whether an href leaves the app: it starts with a scheme (`https:`, `mailto:`) or `//`. A path inside the app is an
+ * address, given as `to`, so that it is written one way everywhere.
+ */
+export declare const leavesApp: (href: string) => boolean;
+/** Why an href cannot be a link's `href`: it points inside the app, which takes an address in `to`. */
+export declare const appHrefError: (href: string) => string | undefined;
+//#endregion

package/dist/address-template.js

@@ -0,0 +1,38 @@
+//#region src/address-template.ts
+const placeholder = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const names = (text) => [...text.matchAll(placeholder)].map((match) => match[1]);
+const templated = (to) => {
+	if (to.kind === "record") return (Array.isArray(to.key) ? to.key : [to.key]).filter((part) => typeof part === "string");
+	if (to.kind === "list") return [to.filter, to.orderBy].filter((part) => part !== void 0);
+	return [];
+};
+/** The fields whose values a link's address takes from the record, from its `{field}` placeholders. */
+const addressPlaceholders = (to) => [...new Set(templated(to).flatMap(names))];
+/** The fields an href takes from the record, from its `{field}` placeholders. */
+const hrefPlaceholders = (href) => [...new Set(names(href))];
+const fill = (text, record) => text.replace(placeholder, (_, name) => record[name] === null || record[name] === void 0 ? "" : String(record[name]));
+/** `to` with every `{field}` in its key, filter and order replaced by the record's value; a missing value becomes empty. */
+const fillAddress = (to, record = {}) => {
+	if (to.kind === "record") {
+		const part = (value) => typeof value === "string" ? fill(value, record) : value;
+		return {
+			...to,
+			key: Array.isArray(to.key) ? to.key.map(part) : part(to.key)
+		};
+	}
+	if (to.kind !== "list") return to;
+	return {
+		...to,
+		...to.filter !== void 0 && { filter: fill(to.filter, record) },
+		...to.orderBy !== void 0 && { orderBy: fill(to.orderBy, record) }
+	};
+};
+/**
+* Whether an href leaves the app: it starts with a scheme (`https:`, `mailto:`) or `//`. A path inside the app is an
+* address, given as `to`, so that it is written one way everywhere.
+*/
+const leavesApp = (href) => /^([a-z][a-z0-9+.-]*:|\/\/)/i.test(href);
+/** Why an href cannot be a link's `href`: it points inside the app, which takes an address in `to`. */
+const appHrefError = (href) => leavesApp(href) ? void 0 : `href "${href}" points inside the app; give the link \`to\` instead, an address such as { kind: 'record', resource: 'orders', key: '{order_id}' }`;
+//#endregion
+export { addressPlaceholders, appHrefError, fillAddress, hrefPlaceholders, leavesApp };

package/dist/app-address.d.ts

@@ -0,0 +1,26 @@
+import { AppAddress } from "./model.js";
+//#region src/app-address.d.ts
+/**
+ * The words of the app's addresses. Only `appPath` and `readAppPath` write and read them, so the shape of an address
+ * changes in this module alone.
+ */
+export declare const addressWords: {
+  /** A list's filter (AIP-160), as the list API takes it. */
+  readonly filter: "filter";
+  /** A list's order (AIP-132). */
+  readonly orderBy: "order_by";
+  /** The list display shown, when it is not the view's default. */
+  readonly display: "display";
+  /** Where a list's filters sit: `bar` (the default) or `panel`. */
+  readonly filterLayout: "layout";
+  /** The second path segment that opens a resource's create form instead of a record. */
+  readonly create: "new";
+};
+/** The path of `address` below `basePath` (such as `/admin`), every name and key encoded the one way the app reads them. */
+export declare const appPath: (address: AppAddress, basePath?: string) => string;
+/**
+ * The address `pathAndQuery` (below the base path) shows, or `undefined` for anything else: the root, the app's own
+ * pages under `/-/`, or a path that is not one. A first segment in `pages` is a composed page, otherwise a resource.
+ */
+export declare const readAppPath: (pathAndQuery: string, pages: ReadonlySet<string>) => AppAddress | undefined;
+//#endregion

package/dist/app-address.js

@@ -0,0 +1,90 @@
+import { encodeKey } from "./keys.js";
+//#region src/app-address.ts
+/**
+* The words of the app's addresses. Only `appPath` and `readAppPath` write and read them, so the shape of an address
+* changes in this module alone.
+*/
+const addressWords = {
+	/** A list's filter (AIP-160), as the list API takes it. */
+	filter: "filter",
+	/** A list's order (AIP-132). */
+	orderBy: "order_by",
+	/** The list display shown, when it is not the view's default. */
+	display: "display",
+	/** Where a list's filters sit: `bar` (the default) or `panel`. */
+	filterLayout: "layout",
+	/** The second path segment that opens a resource's create form instead of a record. */
+	create: "new"
+};
+const listWords = [
+	"display",
+	"filter",
+	"orderBy",
+	"filterLayout"
+];
+const listQuery = (address) => {
+	const query = new URLSearchParams();
+	for (const name of listWords) {
+		const value = address[name];
+		if (value !== void 0 && value !== "") query.set(addressWords[name], value);
+	}
+	const text = query.toString();
+	return text ? `?${text}` : "";
+};
+/** The path of `address` below `basePath` (such as `/admin`), every name and key encoded the one way the app reads them. */
+const appPath = (address, basePath = "") => {
+	switch (address.kind) {
+		case "page": return `${basePath}/${encodeURIComponent(address.page)}`;
+		case "create": return `${basePath}/${encodeURIComponent(address.resource)}/${addressWords.create}`;
+		case "record": return `${basePath}/${encodeURIComponent(address.resource)}/${encodeURIComponent(encodeKey(address.key))}`;
+		case "list": return `${basePath}/${encodeURIComponent(address.resource)}${listQuery(address)}`;
+	}
+};
+const decodeSegments = (pathname) => {
+	try {
+		return pathname.split("/").filter(Boolean).map(decodeURIComponent);
+	} catch (error) {
+		if (error instanceof URIError) return void 0;
+		throw error;
+	}
+};
+const filterLayout = (value) => value === "bar" || value === "panel" ? value : void 0;
+/**
+* The address `pathAndQuery` (below the base path) shows, or `undefined` for anything else: the root, the app's own
+* pages under `/-/`, or a path that is not one. A first segment in `pages` is a composed page, otherwise a resource.
+*/
+const readAppPath = (pathAndQuery, pages) => {
+	const url = new URL(pathAndQuery, "http://app");
+	const segments = decodeSegments(url.pathname);
+	if (!segments || segments.length === 0 || segments.length > 2) return void 0;
+	const [first, second] = segments;
+	if (first === "-") return void 0;
+	if (pages.has(first)) return second === void 0 ? {
+		kind: "page",
+		page: first
+	} : void 0;
+	if (second === addressWords.create) return {
+		kind: "create",
+		resource: first
+	};
+	if (second !== void 0) return {
+		kind: "record",
+		resource: first,
+		key: second
+	};
+	const params = url.searchParams;
+	const display = params.get(addressWords.display) || void 0;
+	const filter = params.get(addressWords.filter) || void 0;
+	const orderBy = params.get(addressWords.orderBy) || void 0;
+	const layout = filterLayout(params.get(addressWords.filterLayout));
+	return {
+		kind: "list",
+		resource: first,
+		...display && { display },
+		...filter && { filter },
+		...orderBy && { orderBy },
+		...layout && { filterLayout: layout }
+	};
+};
+//#endregion
+export { addressWords, appPath, readAppPath };

package/dist/field-ref.d.ts

@@ -0,0 +1,19 @@
+import { JsonValue } from "./model.js";
+//#region src/field-ref.d.ts
+/**
+ * A field named inside free-form data, such as a custom component's props: `{ $field: 'status' }`, or a path through
+ * relations (`plan.name`) on a page. Marked, so that the walker leaving out hidden fields finds it wherever it is.
+ */
+export type FieldRefValue = {
+  readonly $field: string;
+};
+/** A field reference for a layout's custom component props, such as `<UsageChart field={fieldRef('total')} />`. */
+export declare const fieldRef: (path: string) => FieldRefValue;
+export declare const isFieldRef: (value: unknown) => value is FieldRefValue;
+/** Props as a view stores them: every `r.field` in them, at any depth, becomes a field reference. */
+export declare const markFieldRefs: (value: unknown) => JsonValue;
+/** Props as a custom component gets them: every field reference as its field's name. */
+export declare const unmarkFieldRefs: <T>(value: T) => T;
+/** Every field the value names through field references, at any depth. */
+export declare const fieldRefsIn: (value: unknown) => string[];
+//#endregion

package/dist/field-ref.js

@@ -0,0 +1,29 @@
+import { isRef } from "./refs.js";
+//#region src/field-ref.ts
+/** A field reference for a layout's custom component props, such as `<UsageChart field={fieldRef('total')} />`. */
+const fieldRef = (path) => ({ $field: path });
+const isFieldRef = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 1 && typeof value.$field === "string";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Props as a view stores them: every `r.field` in them, at any depth, becomes a field reference. */
+const markFieldRefs = (value) => {
+	if (isRef(value)) return fieldRef(value.name);
+	if (Array.isArray(value)) return value.map(markFieldRefs);
+	if (isObject(value)) return Object.fromEntries(Object.entries(value).map(([name, entry]) => [name, markFieldRefs(entry)]));
+	return value;
+};
+/** Props as a custom component gets them: every field reference as its field's name. */
+const unmarkFieldRefs = (value) => {
+	if (isFieldRef(value)) return value.$field;
+	if (Array.isArray(value)) return value.map(unmarkFieldRefs);
+	if (isObject(value)) return Object.fromEntries(Object.entries(value).map(([name, entry]) => [name, unmarkFieldRefs(entry)]));
+	return value;
+};
+/** Every field the value names through field references, at any depth. */
+const fieldRefsIn = (value) => {
+	if (isFieldRef(value)) return [value.$field];
+	if (Array.isArray(value)) return value.flatMap(fieldRefsIn);
+	if (isObject(value)) return Object.values(value).flatMap(fieldRefsIn);
+	return [];
+};
+//#endregion
+export { fieldRef, fieldRefsIn, isFieldRef, markFieldRefs, unmarkFieldRefs };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionModel, ActionRun, BottomBarItemModel, BottomBarModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterOf, FilterValue, FilterWidgetModel, KeyValue, LayoutItemModel, ListModel, ListQuery, Literal, NavModel, NavRecentModel, NowValue, OrderByItem, RelatedModel, ResourceModel, SaveFeedback, SearchMatch, SearchResultModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { ActionModel, ActionRun, AppAddress, BottomBarItemModel, BottomBarModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, CustomSectionModel, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterLayout, FilterOf, FilterValue, FilterWidgetModel, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListModel, ListQuery, Literal, NavModel, NavRecentModel, NowValue, OrderByItem, RelatedModel, ResourceModel, SaveFeedback, SearchMatch, SearchResultModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
 import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./access/types.js";
 import { FileProcessor, FileProcessorInput, checkedAccept, checkedProvider, parseSize } from "./files/file-options.js";
 import { Field } from "./field.js";
@@ -8,8 +8,11 @@ import { EventActor, EventContext, EventHelpers, EventMatch, EventSpec } from ".
 import { InferRecord, RecordKey } from "./resource-types.js";
 import { resource } from "./resource.js";
 import { checkEventFilter } from "./events/event-models.js";
+import { ComponentRef, ViewProps, displayFields, tableDisplay } from "./view-displays.js";
 import { view } from "./view.js";
 import { webhookResources } from "./webhooks/webhook-resources.js";
+import { FieldRefValue, fieldRef, fieldRefsIn, isFieldRef, markFieldRefs, unmarkFieldRefs } from "./field-ref.js";
+import { PropShapes, RefShape, pruneByShape, shapes } from "./ref-shape.js";
 import { enumLabel } from "./enum-label.js";
 import { SearchTerm, matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
 import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
@@ -18,6 +21,10 @@ import { BottomBarSource, bottomBar, bottomBarFor, maxBottomBarItems } from "./b
 import { BottomBarNames, bottomBarErrors } from "./bottom-bar-errors.js";
 import { layout } from "./layout.js";
 import { KeyType, decodeKey, encodeKey, keyTypes } from "./keys.js";
+import { addressWords, appPath, readAppPath } from "./app-address.js";
+import { PluginHost, PluginRequirement, inRange, pluginProblem } from "./plugin-version.js";
+import { addressPlaceholders, appHrefError, fillAddress, hrefPlaceholders, leavesApp } from "./address-template.js";
+import { AddressCheck, addressErrors } from "./address-errors.js";
 import { FilterLimits, FilterParse, parseFilter } from "./filter/parse.js";
 import { CheckResult, checkFilter } from "./filter/check.js";
 import { EvaluateOptions, evaluateFilter } from "./filter/evaluate.js";
@@ -35,4 +42,4 @@ import "./access/index.js";
 import { AssistantAction, AssistantActionRequest, AssistantCardPart, AssistantDiff, AssistantEvent, AssistantMessage, AssistantMessageRequest, AssistantPart, AssistantState, AssistantStep, AssistantStepState, AssistantTablePart, AssistantTextPart, AssistantTone, AssistantWidgetPart } from "./assistant/protocol.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FileField, type FileFieldModel, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, applyAssistantEvent, bottomBar, bottomBarErrors, bottomBarFor, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, maxBottomBarItems, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, webhookResources, where };
+export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AddressCheck, type AppAddress, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type ComponentRef, type CustomSectionModel, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRefValue, type FieldRule, type FieldType, type FieldViewModel, type FileField, type FileFieldModel, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLayout, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type JsonValue, type KeyType, type KeyValue, type LayoutItemModel, type ListDisplayModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type PluginHost, type PluginRequirement, type PropShapes, type RecordKey, type RefShape, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, type ViewProps, accessWarnings, addressErrors, addressPlaceholders, addressWords, appHrefError, appPath, applyAssistantEvent, bottomBar, bottomBarErrors, bottomBarFor, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, displayFields, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldRef, fieldRefsIn, fieldsUsedBy, fillAddress, hrefPlaceholders, inRange, isFieldRef, keyTypes, layout as l, leavesApp, markFieldRefs, matchedSearchField, matchesSearch, maxBottomBarItems, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, pluginProblem, printFilter, printOrderBy, pruneByShape, readAppPath, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, shapes, statusTones, tableDisplay, termMatches, unmarkFieldRefs, userMenu, view, webhookResources, where };

package/dist/index.js

@@ -9,20 +9,27 @@ import { createWhere, where } from "./filter/where.js";
 import { accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./access/resolve.js";
 import { checkEventFilter } from "./events/event-models.js";
 import { resource } from "./resource.js";
+import { fieldRef, fieldRefsIn, isFieldRef, markFieldRefs, unmarkFieldRefs } from "./field-ref.js";
+import { displayFields, tableDisplay } from "./view-displays.js";
 import { layout } from "./layout.js";
 import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
+import { addressPlaceholders, appHrefError, fillAddress, hrefPlaceholders, leavesApp } from "./address-template.js";
 import { view } from "./view.js";
 import { webhookResources } from "./webhooks/webhook-resources.js";
+import { pruneByShape, shapes } from "./ref-shape.js";
 import { enumLabel } from "./enum-label.js";
 import { matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
 import { userMenu } from "./user-menu.js";
 import { bottomBar, bottomBarFor, maxBottomBarItems } from "./bottom-bar.js";
 import { bottomBarErrors } from "./bottom-bar-errors.js";
 import { decodeKey, encodeKey, keyTypes } from "./keys.js";
+import { addressWords, appPath, readAppPath } from "./app-address.js";
+import { inRange, pluginProblem } from "./plugin-version.js";
+import { addressErrors } from "./address-errors.js";
 import { rule } from "./access/rule.js";
 import { defineRoles } from "./access/roles.js";
 import { pickView } from "./access/pick-view.js";
 import { restrictModel } from "./access/restrict.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { accessWarnings, applyAssistantEvent, bottomBar, bottomBarErrors, bottomBarFor, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, maxBottomBarItems, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, webhookResources, where };
+export { accessWarnings, addressErrors, addressPlaceholders, addressWords, appHrefError, appPath, applyAssistantEvent, bottomBar, bottomBarErrors, bottomBarFor, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, displayFields, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldRef, fieldRefsIn, fieldsUsedBy, fillAddress, hrefPlaceholders, inRange, isFieldRef, keyTypes, layout as l, leavesApp, markFieldRefs, matchedSearchField, matchesSearch, maxBottomBarItems, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, pluginProblem, printFilter, printOrderBy, pruneByShape, readAppPath, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, shapes, statusTones, tableDisplay, termMatches, unmarkFieldRefs, userMenu, view, webhookResources, where };

package/dist/layout.d.ts

@@ -1,5 +1,6 @@
 import { LayoutItemModel, RelatedModel } from "./model.js";
 import { Ref } from "./refs.js";
+import { ComponentRef, ViewProps } from "./view-displays.js";
 //#region src/layout.d.ts
 export declare const layout: {
   section: (title: string, fields: Ref[], o?: {
@@ -8,5 +9,15 @@ export declare const layout: {
   sidebar: (fields: Ref[]) => LayoutItemModel;
   /** A table of the records of another resource that point at this one, directly or through a join table. */
   related: (title: string, o: Omit<RelatedModel, "kind" | "title">) => LayoutItemModel;
+  /**
+   * A component of the project, registered in `protobase.ui.tsx` under its name, drawn where it is listed: in the main
+   * column, or in the sidebar with `sidebar: true`. The record page stays around it, with its title, breadcrumbs,
+   * actions and save; the component reads the record with `useLayoutRecord()`.
+   */
+  custom: <P extends object>(component: ComponentRef<P>, o?: {
+    title?: string;
+    props?: ViewProps<P>;
+    sidebar?: boolean;
+  }) => LayoutItemModel;
 };
 //#endregion

package/dist/layout.js

@@ -1,3 +1,5 @@
+import { markFieldRefs } from "./field-ref.js";
+import { customComponent } from "./view-displays.js";
 //#region src/layout.ts
 const layout = {
 	section: (title, fields, o = {}) => ({
@@ -15,6 +17,18 @@ const layout = {
 		kind: "related",
 		title,
 		...structuredClone(o)
+	}),
+	/**
+	* A component of the project, registered in `protobase.ui.tsx` under its name, drawn where it is listed: in the main
+	* column, or in the sidebar with `sidebar: true`. The record page stays around it, with its title, breadcrumbs,
+	* actions and save; the component reads the record with `useLayoutRecord()`.
+	*/
+	custom: (component, o = {}) => ({
+		kind: "custom",
+		component: customComponent(component, "l.custom"),
+		...o.title !== void 0 && { title: o.title },
+		...o.props && { props: markFieldRefs(o.props) },
+		...o.sidebar && { sidebar: true }
 	})
 };
 //#endregion

package/dist/model.d.ts

@@ -71,6 +71,10 @@ export type EventModel = {
   match?: true;
 };
 export type SortSpec = Array<[field: string, direction: 'asc' | 'desc']>;
+/** A value that survives `JSON.stringify` unchanged, as a custom component's props in a view must be. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
 export type KeyValue = string | number;
 export type ListQuery = {
   filter?: CheckedFilter;
@@ -80,6 +84,29 @@ export type ListQuery = {
   direction?: 'after' | 'before';
   limit: number;
 };
+export type FilterLayout = 'bar' | 'panel';
+/**
+ * A place in the app: a resource's list, one of its records, its create form, or a composed page. A record's `key` is
+ * its one value or its parts, as the record API takes them; `readAppPath` gives it back as the API's text form.
+ */
+export type AppAddress = {
+  kind: 'list';
+  resource: string;
+  filter?: string;
+  orderBy?: string;
+  display?: string;
+  filterLayout?: FilterLayout;
+} | {
+  kind: 'record';
+  resource: string;
+  key: KeyValue | readonly KeyValue[];
+} | {
+  kind: 'create';
+  resource: string;
+} | {
+  kind: 'page';
+  page: string;
+};
 export type FieldFormat = 'relative' | 'absolute' | 'compact' | 'percent' | 'badge' | 'code';
 export type FieldViewModel = {
   label?: string;
@@ -90,11 +117,37 @@ export type FieldViewModel = {
   /** What an enum value reads as wherever it is shown; a value without one reads as itself in words (`enumLabel`). */
   valueLabels?: Record<string, string>;
 };
+/**
+ * A way to show a list besides its table: a card per record, or a project component (`custom`) drawing the rows the
+ * list page loads. `name` is what the address names (`?display=cards`); `label` and `icon` are its switch's.
+ */
+export type ListDisplayModel = {
+  kind: 'cards';
+  name: string;
+  label?: string;
+  icon?: string;
+  title?: string;
+  subtitle?: string;
+  badge?: string;
+  meta?: string[];
+} | {
+  kind: 'custom';
+  name: string;
+  label: string;
+  icon?: string;
+  component: string;
+  fields: string[];
+  props?: Record<string, JsonValue>;
+};
 export type ListModel = {
   columns: string[];
   sort?: SortSpec;
   /** Defaults for the UI's search box. `ResourceModel.search` is authoritative for what `search(...)` matches on the server. */
   search?: string[];
+  /** Other ways to show the list besides its table, in the order the switch shows them after it. */
+  displays?: ListDisplayModel[];
+  /** The display the list opens in when the address names none; the table when omitted. */
+  default?: string;
 };
 export type DatePreset = 'today' | 'yesterday' | '7d' | '30d' | '90d' | 'month' | 'quarter' | 'year';
 export type FilterWidgetModel = {
@@ -136,6 +189,17 @@ export type RelatedModel = {
   pageSize?: number;
   empty?: string;
 };
+/**
+ * A project component drawn on the record page where it is listed, in the main column or with `sidebar` in the
+ * sidebar, under `title` when it has one. It gets `props` and reads the record with `useLayoutRecord()`.
+ */
+export type CustomSectionModel = {
+  kind: 'custom';
+  component: string;
+  title?: string;
+  props?: Record<string, JsonValue>;
+  sidebar?: true;
+};
 export type LayoutItemModel = {
   kind: 'section';
   title: string;
@@ -144,7 +208,7 @@ export type LayoutItemModel = {
 } | {
   kind: 'sidebar';
   fields: string[];
-} | RelatedModel;
+} | RelatedModel | CustomSectionModel;
 export type ChartRange = '7d' | '30d' | '90d' | '1y' | 'all';
 export type ChartGranularity = 'hour' | 'day' | 'week' | 'month';
 export type ChartModel = {
@@ -154,14 +218,18 @@ export type ChartModel = {
 };
 export type SaveFeedback = 'toast' | 'button';
 /**
- * What a named action does in the app: set fields of the record (`update`), delete it (`delete`) or open a link
- * (`link`, with `{field}` replaced by the record's values). Without it the app runs a handler it registered by name.
+ * What a named action does in the app: set fields of the record (`update`), delete it (`delete`), go to an address in
+ * the app (`link` with `to`) or open a link that leaves it (`link` with `href`), `{field}` replaced by the record's
+ * values. Without it the app runs a handler it registered by name.
  */
 export type ActionRun = {
   kind: 'update';
   values: Record<string, unknown>;
 } | {
   kind: 'delete';
+} | {
+  kind: 'link';
+  to: AppAddress;
 } | {
   kind: 'link';
   href: string;

package/dist/plugin-version.d.ts

@@ -0,0 +1,22 @@
+//#region src/plugin-version.d.ts
+/**
+ * Whether `version` is in `range`: comparators such as `>=0.12.0 <1.0.0`, separated by spaces, all of which must hold.
+ * Undefined when the range is not one of those, or the version is no x.y.z version.
+ */
+export declare const inRange: (version: string, range: string) => boolean | undefined;
+/** What a plugin's plugin.json says it is built for: a plugin API, and the Protobase versions it runs on. */
+export type PluginRequirement = {
+  api: number;
+  protobase: string;
+};
+/** An app that loads plugins: the plugin API its @protobase/ui provides, and its Protobase version. */
+export type PluginHost = {
+  api: number;
+  version: string;
+};
+/**
+ * Why an app does not load a plugin built for `requirement`, or undefined when it does: the plugin API must be the
+ * app's, and the app's Protobase version in the plugin's range.
+ */
+export declare const pluginProblem: (requirement: PluginRequirement, host: PluginHost) => string | undefined;
+//#endregion

package/dist/plugin-version.js

@@ -0,0 +1,48 @@
+//#region src/plugin-version.ts
+const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const parseVersion = (text) => {
+	const match = versionPattern.exec(text);
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : void 0;
+};
+const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+const comparatorPattern = /^(>=|<=|>|<|=)?(.+)$/;
+const holds = {
+	">=": (order) => order >= 0,
+	"<=": (order) => order <= 0,
+	">": (order) => order > 0,
+	"<": (order) => order < 0,
+	"=": (order) => order === 0
+};
+/**
+* Whether `version` is in `range`: comparators such as `>=0.12.0 <1.0.0`, separated by spaces, all of which must hold.
+* Undefined when the range is not one of those, or the version is no x.y.z version.
+*/
+const inRange = (version, range) => {
+	const own = parseVersion(version);
+	const comparators = range.trim().split(/\s+/);
+	if (!own || range.trim() === "") return void 0;
+	let result = true;
+	for (const comparator of comparators) {
+		const [, operator = "=", text = ""] = comparatorPattern.exec(comparator) ?? [];
+		const bound = parseVersion(text);
+		if (!bound) return void 0;
+		result &&= holds[operator](compare(own, bound));
+	}
+	return result;
+};
+/**
+* Why an app does not load a plugin built for `requirement`, or undefined when it does: the plugin API must be the
+* app's, and the app's Protobase version in the plugin's range.
+*/
+const pluginProblem = (requirement, host) => {
+	if (requirement.api !== host.api) return `it is built for plugin API ${requirement.api}, and this app has plugin API ${host.api}`;
+	const fits = inRange(host.version, requirement.protobase);
+	if (fits === void 0) return `its Protobase range "${requirement.protobase}" is not one this app reads, such as >=0.12.0`;
+	if (!fits) return `it needs Protobase ${requirement.protobase}, and this app runs ${host.version}`;
+};
+//#endregion
+export { inRange, pluginProblem };

package/dist/ref-shape.d.ts

@@ -0,0 +1,80 @@
+//#region src/ref-shape.d.ts
+/**
+ * Where a part of a model names fields, and what a field the caller cannot read does to it. A shape declares every part
+ * of the model it walks: a part it does not declare is left out, so a new part cannot reach a caller unchecked.
+ */
+export type RefShape =
+/** Plain data that names no field: kept as it is. */
+{
+  kind: 'data';
+} |
+/** A field's name: left out when hidden. */
+{
+  kind: 'field';
+} |
+/** Free-form data, such as a custom component's props, with field references (`{ $field }`) anywhere: left out when one is hidden. */
+{
+  kind: 'refs';
+} |
+/** An object keyed by field names, such as field hints: hidden keys are left out, or with `all` the whole object. */
+{
+  kind: 'keys';
+  all: boolean;
+} |
+/** A list: entries left out are dropped, and with `nonEmpty` a list left empty is left out too. */
+{
+  kind: 'list';
+  of: RefShape;
+  nonEmpty: boolean;
+} |
+/** A fixed list, such as `[field, direction]`: left out when any entry is. */
+{
+  kind: 'tuple';
+  items: RefShape[];
+} |
+/** An object: a part left out is dropped, a `requires` part left out leaves out the object; `after` tidies the result. */
+{
+  kind: 'object';
+  props: Record<string, RefShape>;
+  requires: string[];
+  after?: (value: never) => unknown;
+} |
+/** One shape per value of `kind`, as layout items and displays are told apart; an unknown kind is left out. */
+{
+  kind: 'oneOf';
+  cases: Record<string, RefShape>;
+} |
+/** A part pruned by code, such as one naming another resource's fields: `prune` returns it narrowed, or `undefined`. */
+{
+  kind: 'map';
+  prune: (value: never) => unknown;
+};
+/** One shape per property of `T`, so the compiler names a property the shape forgets. */
+export type PropShapes<T> = { [K in keyof T]-?: RefShape; };
+/** The shapes, typed against the model they describe. */
+export declare const shapes: {
+  data: RefShape;
+  field: RefShape;
+  refs: RefShape;
+  keys: (o?: {
+    all?: boolean;
+  }) => RefShape;
+  list: (of: RefShape, o?: {
+    nonEmpty?: boolean;
+  }) => RefShape;
+  tuple: (...items: RefShape[]) => RefShape;
+  object: <T extends object>(props: PropShapes<T>, o?: {
+    requires?: Array<keyof T & string>;
+    after?: (value: T) => T;
+  }) => RefShape;
+  oneOf: <T extends {
+    kind: string;
+  }>(cases: { [K in T["kind"]]: RefShape; }) => RefShape;
+  map: <T>(prune: (value: T) => T | undefined) => RefShape;
+};
+/**
+ * `value` with every part naming a field `visible` refuses left out, as `shape` says, or `undefined` when the whole
+ * value goes. One walker for every model the app sends: views, custom component props and composed pages' custom nodes.
+ */
+export declare const pruneByShape: <T>(value: T, shape: RefShape, visible: (name: string) => boolean) => T | undefined;
+//#endregion

package/dist/ref-shape.js

@@ -0,0 +1,88 @@
+import { fieldRefsIn } from "./field-ref.js";
+//#region src/ref-shape.ts
+/** The shapes, typed against the model they describe. */
+const shapes = {
+	data: { kind: "data" },
+	field: { kind: "field" },
+	refs: { kind: "refs" },
+	keys: (o = {}) => ({
+		kind: "keys",
+		all: o.all ?? false
+	}),
+	list: (of, o = {}) => ({
+		kind: "list",
+		of,
+		nonEmpty: o.nonEmpty ?? false
+	}),
+	tuple: (...items) => ({
+		kind: "tuple",
+		items
+	}),
+	object: (props, o = {}) => ({
+		kind: "object",
+		props,
+		requires: o.requires ?? [],
+		...o.after && { after: o.after }
+	}),
+	oneOf: (cases) => ({
+		kind: "oneOf",
+		cases
+	}),
+	map: (prune) => ({
+		kind: "map",
+		prune
+	})
+};
+const gone = Symbol("gone");
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const walk = (value, shape, visible) => {
+	switch (shape.kind) {
+		case "data": return value;
+		case "field": return typeof value === "string" && visible(value) ? value : gone;
+		case "refs": return fieldRefsIn(value).every(visible) ? value : gone;
+		case "keys": {
+			if (!isObject(value)) return gone;
+			const entries = Object.entries(value);
+			const kept = entries.filter(([name]) => visible(name));
+			return shape.all && kept.length < entries.length ? gone : Object.fromEntries(kept);
+		}
+		case "list": {
+			if (!Array.isArray(value)) return gone;
+			const kept = value.map((entry) => walk(entry, shape.of, visible)).filter((entry) => entry !== gone);
+			return shape.nonEmpty && kept.length === 0 ? gone : kept;
+		}
+		case "tuple": {
+			if (!Array.isArray(value) || value.length !== shape.items.length) return gone;
+			const items = value.map((entry, index) => walk(entry, shape.items[index], visible));
+			return items.includes(gone) ? gone : items;
+		}
+		case "object": {
+			if (!isObject(value)) return gone;
+			const kept = {};
+			for (const [name, entry] of Object.entries(value)) {
+				const part = Object.hasOwn(shape.props, name) ? shape.props[name] : void 0;
+				if (!part || entry === void 0) continue;
+				const pruned = walk(entry, part, visible);
+				if (pruned === gone && shape.requires.includes(name)) return gone;
+				if (pruned !== gone) kept[name] = pruned;
+			}
+			return shape.after ? shape.after(kept) : kept;
+		}
+		case "oneOf": {
+			const kind = isObject(value) && typeof value.kind === "string" ? value.kind : void 0;
+			const shaped = kind !== void 0 && Object.hasOwn(shape.cases, kind) ? shape.cases[kind] : void 0;
+			return shaped ? walk(value, shaped, visible) : gone;
+		}
+		case "map": return shape.prune(value) ?? gone;
+	}
+};
+/**
+* `value` with every part naming a field `visible` refuses left out, as `shape` says, or `undefined` when the whole
+* value goes. One walker for every model the app sends: views, custom component props and composed pages' custom nodes.
+*/
+const pruneByShape = (value, shape, visible) => {
+	const pruned = walk(value, shape, visible);
+	return pruned === gone ? void 0 : pruned;
+};
+//#endregion
+export { pruneByShape, shapes };

package/dist/refs.js

@@ -1,8 +1,12 @@
 //#region src/refs.ts
+const refMark = Symbol("protobase.ref");
+/** A field reference as a view builder hands it out (`r.status`), recognisable wherever it is passed, props included. */
+const ref = (name) => Object.defineProperty({ name }, refMark, { value: true });
+const isRef = (value) => typeof value === "object" && value !== null && value[refMark] === true;
 const createRefs = (make, known) => new Proxy({}, { get: (_, name) => {
 	if (typeof name === "symbol") return void 0;
 	if (known && !known.includes(name)) throw new Error(`Unknown field "${name}"`);
 	return make(name);
 } });
 //#endregion
-export { createRefs };
+export { createRefs, isRef, ref };

package/dist/view-actions.d.ts

@@ -1,4 +1,4 @@
-import { ActionModel } from "./model.js";
+import { ActionModel, AppAddress } from "./model.js";
 //#region src/view-actions.d.ts
 type ActionOptions = {
   label: string;
@@ -16,9 +16,15 @@ export declare const actions: {
   }) => ActionModel;
   /** Deletes the record (soft delete when the resource has one). */
   remove: (name: string, o: ActionOptions) => ActionModel;
-  /** Opens `href`: a path in the app or a URL; `{field}` is replaced by the record's value, such as `/orders/{orderId}`. */
-  link: (name: string, o: Omit<ActionOptions, "confirm"> & {
+  /**
+   * Goes `to` an address in the app, such as `{ kind: 'record', resource: 'orders', key: '{order_id}' }`, or opens an
+   * `href` that leaves it (`https:`, `mailto:`); `{field}` is replaced by the record's value. A path in the app is
+   * refused as an `href`, so every address in the app is written one way.
+   */
+  link: (name: string, o: Omit<ActionOptions, "confirm"> & ({
+    to: AppAddress;
+  } | {
     href: string;
-  }) => ActionModel;
+  })) => ActionModel;
 };
 //#endregion

package/dist/view-actions.js

@@ -1,3 +1,4 @@
+import { appHrefError } from "./address-template.js";
 //#region src/view-actions.ts
 const named = (name, o) => ({
 	name,
@@ -22,14 +23,29 @@ const actions = {
 		...named(name, o),
 		run: { kind: "delete" }
 	}),
-	/** Opens `href`: a path in the app or a URL; `{field}` is replaced by the record's value, such as `/orders/{orderId}`. */
-	link: (name, o) => ({
-		...named(name, o),
-		run: {
-			kind: "link",
-			href: o.href
-		}
-	})
+	/**
+	* Goes `to` an address in the app, such as `{ kind: 'record', resource: 'orders', key: '{order_id}' }`, or opens an
+	* `href` that leaves it (`https:`, `mailto:`); `{field}` is replaced by the record's value. A path in the app is
+	* refused as an `href`, so every address in the app is written one way.
+	*/
+	link: (name, o) => {
+		if ("to" in o) return {
+			...named(name, o),
+			run: {
+				kind: "link",
+				to: structuredClone(o.to)
+			}
+		};
+		const error = appHrefError(o.href);
+		if (error) throw new Error(`Action "${name}": ${error}`);
+		return {
+			...named(name, o),
+			run: {
+				kind: "link",
+				href: o.href
+			}
+		};
+	}
 };
 //#endregion
 export { actions };

package/dist/view-displays.d.ts

@@ -0,0 +1,42 @@
+import { ListDisplayModel } from "./model.js";
+import { Ref } from "./refs.js";
+//#region src/view-displays.d.ts
+/** A custom component as `component(name)` from `@protobase/layout` declares it. */
+export type ComponentRef<P> = ((props: P) => unknown) & {
+  readonly blockName: string;
+  readonly custom: boolean;
+};
+/** A custom component's props as a view gives them: plain data, or `r.field` where it takes a field's name. */
+export type ViewProps<P> = { [K in keyof Omit<P, 'children'>]: P[K] extends string ? P[K] | Ref : P[K]; };
+type Naming = {
+  name?: string;
+  label?: string;
+  icon?: string;
+};
+/** The name of the list's own display, which every list has. */
+export declare const tableDisplay = "table";
+export declare const displays: {
+  /**
+   * A card per record: `title` (default: the view's title) over `subtitle`, `badge` drawn as a badge with its value
+   * labels, and a few small `meta` fields such as dates. Named `cards` unless `name` says otherwise.
+   */
+  cards: (fields: {
+    title?: Ref;
+    subtitle?: Ref;
+    badge?: Ref;
+    meta?: Ref[];
+  }, o?: Naming) => ListDisplayModel;
+  /**
+   * The list drawn by a component of the project, registered in `protobase.ui.tsx` under its name. It gets `props` and
+   * reads the rows with `useListDisplay()`; `fields` are the fields it shows, fetched with relation names.
+   */
+  custom: <P extends object>(component: ComponentRef<P>, o: Naming & {
+    name: string;
+    label: string;
+    fields: Ref[];
+    props?: ViewProps<P>;
+  }) => ListDisplayModel;
+};
+/** Every field a display names: what it shows, and the field references in a custom display's props. */
+export declare const displayFields: (display: ListDisplayModel) => string[];
+//#endregion

package/dist/view-displays.js

@@ -0,0 +1,61 @@
+import { fieldRefsIn, markFieldRefs } from "./field-ref.js";
+//#region src/view-displays.ts
+const naming = ({ label, icon }) => ({
+	...label !== void 0 && { label },
+	...icon !== void 0 && { icon }
+});
+/** The name of the list's own display, which every list has. */
+const tableDisplay = "table";
+/** The component of a custom display or section, which must be a project's, not a built-in block. */
+const customComponent = (component, where) => {
+	if (!component.custom) throw new Error(`${where} takes a component declared with component(...), not the built-in block ${component.blockName}`);
+	return component.blockName;
+};
+const displays = {
+	/**
+	* A card per record: `title` (default: the view's title) over `subtitle`, `badge` drawn as a badge with its value
+	* labels, and a few small `meta` fields such as dates. Named `cards` unless `name` says otherwise.
+	*/
+	cards: (fields, o = {}) => ({
+		kind: "cards",
+		name: o.name ?? "cards",
+		...naming(o),
+		...fields.title && { title: fields.title.name },
+		...fields.subtitle && { subtitle: fields.subtitle.name },
+		...fields.badge && { badge: fields.badge.name },
+		...fields.meta && { meta: fields.meta.map((ref) => ref.name) }
+	}),
+	/**
+	* The list drawn by a component of the project, registered in `protobase.ui.tsx` under its name. It gets `props` and
+	* reads the rows with `useListDisplay()`; `fields` are the fields it shows, fetched with relation names.
+	*/
+	custom: (component, o) => ({
+		kind: "custom",
+		name: o.name,
+		label: o.label,
+		...naming({ icon: o.icon }),
+		component: customComponent(component, "d.custom"),
+		fields: o.fields.map((ref) => ref.name),
+		...o.props && { props: markFieldRefs(o.props) }
+	})
+};
+const displayName = /^[a-z][a-zA-Z0-9-]*$/;
+/** What is wrong with a list's displays and default, by their names alone. */
+const displayErrors = (list) => {
+	const names = (list.displays ?? []).map((display) => display.name);
+	return [
+		...names.filter((name) => !displayName.test(name)).map((name) => `display name "${name}" must start with a lowercase letter and hold only letters, digits and dashes`),
+		...names.filter((name) => name === tableDisplay).map(() => `"${tableDisplay}" is the list's own display; give the display another name`),
+		...names.filter((name, index) => names.indexOf(name) !== index).map((name) => `display "${name}" is defined twice`),
+		...list.default === void 0 || list.default === "table" || names.includes(list.default) ? [] : [`default "${list.default}" is not one of the displays (${[tableDisplay, ...names].join(", ")})`]
+	];
+};
+/** Every field a display names: what it shows, and the field references in a custom display's props. */
+const displayFields = (display) => display.kind === "cards" ? [
+	display.title,
+	display.subtitle,
+	display.badge,
+	...display.meta ?? []
+].filter((name) => name !== void 0) : [...display.fields, ...fieldRefsIn(display.props)];
+//#endregion
+export { customComponent, displayErrors, displayFields, displays, tableDisplay };

package/dist/view.d.ts

@@ -1,6 +1,7 @@
-import { ActionModel, ChartGranularity, ChartRange, FilterWidgetModel, LayoutItemModel, NavModel, NavRecentModel, ResourceModel, SaveFeedback, ViewModel } from "./model.js";
+import { ActionModel, ChartGranularity, ChartRange, FilterWidgetModel, LayoutItemModel, ListDisplayModel, NavModel, NavRecentModel, ResourceModel, SaveFeedback, ViewModel } from "./model.js";
 import { FieldRefs, Ref } from "./refs.js";
 import { actions } from "./view-actions.js";
+import { displays } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
 import { widgets } from "./view-widgets.js";
 //#region src/view.d.ts
@@ -44,10 +45,16 @@ export declare class ViewBuilder<R extends {
   nav(nav: NavInput<R>): ViewBuilder<R>;
   help(help: string): ViewBuilder<R>;
   fields(build: (r: FieldViews<R>) => Record<string, FieldView>): ViewBuilder<R>;
-  list(build: (r: FieldRefs<FieldsOf<R>>) => {
+  /**
+   * The list: its table's `columns`, `sort` and `search`, and other `displays` to switch to (`d.cards`, `d.custom`), one
+   * of which may be the `default` the list opens in. Throws when display names collide or `default` names none.
+   */
+  list(build: (r: FieldRefs<FieldsOf<R>>, d: typeof displays) => {
     columns: Ref[];
     sort?: Array<[Ref, 'asc' | 'desc']>;
     search?: Ref[];
+    displays?: ListDisplayModel[];
+    default?: string;
   }): ViewBuilder<R>;
   filters(build: (r: FieldRefs<FieldsOf<R>>, w: typeof widgets) => FilterWidgetModel[]): ViewBuilder<R>;
   layout(build: (r: FieldRefs<FieldsOf<R>>) => LayoutItemModel[]): ViewBuilder<R>;
@@ -58,7 +65,7 @@ export declare class ViewBuilder<R extends {
   }): ViewBuilder<R>;
   saveFeedback(saveFeedback: SaveFeedback): ViewBuilder<R>;
   actions(build: (a: typeof actions) => ActionModel[]): ViewBuilder<R>;
-  /** With the resource's model, also verifies the title and search result fields and the sidebar's `recent` group. */
+  /** With the resource's model, also verifies the title, search result and list display fields and the sidebar's `recent` group. */
   toModel(resource?: ResourceModel): ViewModel;
   private refs;
   private next;

package/dist/view.js

@@ -1,4 +1,5 @@
-import { createRefs } from "./refs.js";
+import { createRefs, ref } from "./refs.js";
+import { displayErrors, displayFields, displays } from "./view-displays.js";
 import { navRecentErrors } from "./nav-recent.js";
 import { actions } from "./view-actions.js";
 import { FieldView } from "./view-field.js";
@@ -50,13 +51,22 @@ var ViewBuilder = class ViewBuilder {
 			...fields
 		} });
 	}
+	/**
+	* The list: its table's `columns`, `sort` and `search`, and other `displays` to switch to (`d.cards`, `d.custom`), one
+	* of which may be the `default` the list opens in. Throws when display names collide or `default` names none.
+	*/
 	list(build) {
-		const { columns, sort, search } = build(this.refs());
-		return this.next({ list: {
+		const { columns, sort, search, displays: shown = [], default: opens } = build(this.refs(), displays);
+		const list = {
 			columns: columns.map((ref) => ref.name),
 			...sort && { sort: sort.map(([ref, dir]) => [ref.name, dir]) },
-			...search && { search: search.map((ref) => ref.name) }
-		} });
+			...search && { search: search.map((ref) => ref.name) },
+			...shown.length > 0 && { displays: shown },
+			...opens !== void 0 && { default: opens }
+		};
+		const errors = displayErrors(list);
+		if (errors.length > 0) throw new Error(`View "${this.state.resource}": ${errors.join("; ")}`);
+		return this.next({ list });
 	}
 	filters(build) {
 		return this.next({ filters: build(this.refs(), widgets) });
@@ -78,18 +88,22 @@ var ViewBuilder = class ViewBuilder {
 	actions(build) {
 		return this.next({ actions: build(actions) });
 	}
-	/** With the resource's model, also verifies the title and search result fields and the sidebar's `recent` group. */
+	/** With the resource's model, also verifies the title, search result and list display fields and the sidebar's `recent` group. */
 	toModel(resource) {
-		const { title, nav, searchResult } = this.state;
+		const { title, nav, searchResult, list } = this.state;
 		if (resource && title !== void 0 && !Object.hasOwn(resource.fields, title)) throw new Error(`View "${this.state.resource}": title field "${title}" does not exist on the resource`);
 		const missing = resource ? [...searchResult?.title ?? [], ...searchResult?.subtitle ? [searchResult.subtitle] : []].filter((name) => !Object.hasOwn(resource.fields, name)) : [];
 		if (missing.length > 0) throw new Error(`View "${this.state.resource}": search result field "${missing[0]}" does not exist on the resource`);
+		for (const display of resource ? list?.displays ?? [] : []) {
+			const unknown = displayFields(display).find((name) => !Object.hasOwn(resource.fields, name));
+			if (unknown !== void 0) throw new Error(`View "${this.state.resource}": display "${display.name}" names field "${unknown}", which the resource does not have`);
+		}
 		const recentErrors = resource && nav?.recent ? navRecentErrors(nav.recent, resource) : [];
 		if (recentErrors.length > 0) throw new Error(`View "${this.state.resource}": nav.recent ${recentErrors.join("; ")}`);
 		return structuredClone(this.state);
 	}
 	refs() {
-		return createRefs((name) => ({ name }));
+		return createRefs(ref);
 	}
 	next(patch) {
 		return new ViewBuilder({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/schema",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Resource, field, view and access definitions for Protobase configs.",
   "license": "Apache-2.0",
   "repository": {