@protobase/schema 0.19.12 → 0.19.13

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FileOptions, FileProcessor, FileProcessorInput, ImageFormat, ImageVariant, ImageVariantOptions, imageFormats } from "./files/file-options.js";
-import { ActionModel, ActionRun, AppAddress, BadgeShape, BottomBarItemModel, BottomBarModel, CardFavoriteModel, CardPhotosModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, CreateModel, CustomSectionModel, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, ExportModel, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FieldWidgetModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterLayout, FilterOf, FilterValue, FilterWidgetModel, GalleryModel, HelpWhen, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListModel, ListQuery, Literal, MapSectionModel, MapView, NavModel, NavRecentModel, NowValue, OrderByItem, RecordMode, RelatedModel, ResourceModel, SaveFeedback, SaveSearchModel, SearchMatch, SearchResultModel, SearchesOfModel, SectionPresentation, SignInPromptModel, SignInViewModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { ActionModel, ActionRun, AppAddress, BadgeShape, BottomBarItemModel, BottomBarModel, CardFavoriteModel, CardPhotosModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, CreateModel, CustomSectionModel, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, ExportModel, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FieldWidgetModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterLayout, FilterOf, FilterValue, FilterWidgetModel, GalleryModel, HelpWhen, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListModel, ListQuery, Literal, MapSectionModel, MapView, NavModel, NavRecentModel, NowValue, OrderByItem, RecordMode, RelatedColumnModel, RelatedModel, ResourceModel, SaveFeedback, SaveSearchModel, SearchMatch, SearchResultModel, SearchesOfModel, SectionPresentation, SignInPromptModel, SignInViewModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
 import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./access/types.js";
 import { AnyField, Constraint, Field, FieldMeta, FieldTypeDef } from "./field.js";
 import { RelationField } from "./relation-field.js";
@@ -9,6 +9,7 @@ import { FieldRefs, FieldsInput, Ref, Refs } from "./refs.js";
 import { CreatedOptions, DeletedOptions, EventActor, EventContext, EventHelpers, EventMatch, EventSpec, UndeletedOptions, UpdatedOptions } from "./events/event-helpers.js";
 import { Access, InferRecord, Issue, KeyOf, KeyRefs, RecordKey, RecordOf } from "./resource-types.js";
 import { ResourceBuilder, SearchRef, SearchRefs, Validator, resource } from "./resource.js";
+import { ListColumn } from "./view-columns.js";
 import { ComponentRef, ViewProps } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
 import { FieldViews, ViewBuilder, view } from "./view.js";
@@ -37,4 +38,4 @@ import { AccessSource, ResolveOptions, ResolvedAccess, RowFilterOperation, acces
 import { restrictModel } from "./access/restrict.js";
 import "./access/index.js";
 import { AssistantAction, AssistantActionRequest, AssistantCardPart, AssistantDiff, AssistantEvent, AssistantMessage, AssistantMessageRequest, AssistantPart, AssistantState, AssistantStep, AssistantStepState, AssistantTablePart, AssistantTextPart, AssistantTone, AssistantWidgetPart } from "./assistant/protocol.js";
-export { type Access, type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AnyField, 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 BadgeShape, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type CardFavoriteModel, type CardPhotosModel, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type ComponentRef, type Constraint, type CreateModel, type CreatedOptions, type CustomSectionModel, type DatePreset, type DeletedOptions, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type ExportModel, type Field, type FieldAccess, type FieldFormat, type FieldMeta, type FieldModel, type FieldPath, type FieldRefValue, type FieldRefs, type FieldRule, type FieldType, type FieldTypeDef, type FieldView, type FieldViewModel, type FieldViews, type FieldWidgetModel, type FieldsInput, type FileField, type FileFieldModel, type FileOptions, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLayout, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type GalleryModel, type Grant, type HeldCapability, type HelpWhen, type ImageFormat, type ImageVariant, type ImageVariantOptions, type InferRecord, type Issue, type JsonValue, type KeyOf, type KeyRefs, type KeyType, type KeyValue, type LayoutItemModel, type ListDisplayModel, type ListModel, type ListQuery, type Literal, type MapSectionModel, type MapView, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RecordMode, type RecordOf, type Ref, type Refs, type RelatedModel, type RelationField, type ResolveOptions, type ResolvedAccess, type ResourceBuilder, type ResourceModel, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SaveSearchModel, type SearchMatch, type SearchRef, type SearchRefs, type SearchResultModel, type SearchesOfModel, type SectionPresentation, type SignInAddress, type SignInPromptModel, type SignInStep, type SignInViewModel, type SortSpec, type Span, type StatusTone, type UndeletedOptions, type UpdatedOptions, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type Validator, type ViewBuilder, type ViewModel, type ViewProps, accessWarnings, addressWords, anonymousRole, appPath, bottomBar, bottomBarErrors, checkFilter, checkOrderBy, checkRecord, createWhere, defineRoles, enumLabel, evaluateFilter, f, fieldRef, fieldsUsedBy, imageFormats, keyTypes, layout as l, maxBottomBarItems, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readAppPath, readSignInAddress, resolveAccess, resource, restrictModel, rule, signInParams, signInPath, signInRoute, signInSteps, userMenu, view, where };
+export { type Access, type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AnyField, 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 BadgeShape, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type CardFavoriteModel, type CardPhotosModel, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type ComponentRef, type Constraint, type CreateModel, type CreatedOptions, type CustomSectionModel, type DatePreset, type DeletedOptions, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type ExportModel, type Field, type FieldAccess, type FieldFormat, type FieldMeta, type FieldModel, type FieldPath, type FieldRefValue, type FieldRefs, type FieldRule, type FieldType, type FieldTypeDef, type FieldView, type FieldViewModel, type FieldViews, type FieldWidgetModel, type FieldsInput, type FileField, type FileFieldModel, type FileOptions, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLayout, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type GalleryModel, type Grant, type HeldCapability, type HelpWhen, type ImageFormat, type ImageVariant, type ImageVariantOptions, type InferRecord, type Issue, type JsonValue, type KeyOf, type KeyRefs, type KeyType, type KeyValue, type LayoutItemModel, type ListColumn, type ListDisplayModel, type ListModel, type ListQuery, type Literal, type MapSectionModel, type MapView, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RecordMode, type RecordOf, type Ref, type Refs, type RelatedColumnModel, type RelatedModel, type RelationField, type ResolveOptions, type ResolvedAccess, type ResourceBuilder, type ResourceModel, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SaveSearchModel, type SearchMatch, type SearchRef, type SearchRefs, type SearchResultModel, type SearchesOfModel, type SectionPresentation, type SignInAddress, type SignInPromptModel, type SignInStep, type SignInViewModel, type SortSpec, type Span, type StatusTone, type UndeletedOptions, type UpdatedOptions, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type Validator, type ViewBuilder, type ViewModel, type ViewProps, accessWarnings, addressWords, anonymousRole, appPath, bottomBar, bottomBarErrors, checkFilter, checkOrderBy, checkRecord, createWhere, defineRoles, enumLabel, evaluateFilter, f, fieldRef, fieldsUsedBy, imageFormats, keyTypes, layout as l, maxBottomBarItems, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readAppPath, readSignInAddress, resolveAccess, resource, restrictModel, rule, signInParams, signInPath, signInRoute, signInSteps, userMenu, view, where };

package/dist/model.d.ts

@@ -455,6 +455,31 @@ export type ListModel = {
   displays?: ListDisplayModel[];
   /** The display the list opens in when the address names none; the table when omitted. */
   default?: string;
+  /** The columns of related records among `columns`, each named there by its `name`. */
+  relatedColumns?: RelatedColumnModel[];
+};
+/**
+ * A list column of the records of another resource that point at each row, directly or through a join resource, as a
+ * dot per record in its status's colour, each opening the record (`c.related(...)`). See
+ * [Related records in a list](website/src/content/docs/reference/ui-config.mdx#related-records-in-a-list).
+ */
+export type RelatedColumnModel = {
+  /** The column's name in the list's `columns`, which no field of the resource has. */
+  name: string;
+  /** The column's header; the name in words when omitted. */
+  label?: string;
+  /** The resource whose records it shows. */
+  resource: string;
+  /** The filterable field of `resource` matched against the row's key, or with `through` against the join records' keys. */
+  field: string;
+  /** The join records between the row and the shown ones, as a related section's. */
+  through?: RelatedModel['through'];
+  /** An AIP-160 filter on the shown records. */
+  filter?: string;
+  /** An AIP-132 order of the dots. */
+  sort?: string;
+  /** The enum field of `resource` whose value colours each dot, by its view's `valueColors`. */
+  status: string;
 };
 /** A button of a date range filter: today, yesterday, the last 7, 30 or 90 days, or this month, quarter or year. */
 export type DatePreset = 'today' | 'yesterday' | '7d' | '30d' | '90d' | 'month' | 'quarter' | 'year';

package/dist/view-columns.d.ts

@@ -0,0 +1,18 @@
+import { RelatedColumnModel } from "./model.js";
+//#region src/view-columns.d.ts
+/** A column of a view's list that is no field of the resource, as `c` makes one. */
+export type ListColumn = RelatedColumnModel & {
+  /** Marks a related records column. */
+  readonly kind: 'related';
+};
+export declare const columns: {
+  /**
+   * A column named `name` of the records of `resource` that point at each row, through its relation `field` or, with
+   * `through`, through a join resource, as a related section's. Each record is a dot in the colour its `status` value
+   * has in its view's `valueColors`, in `sort` order, and a link to the record, showing its card on hover or focus. The
+   * name must not be a field of the resource. See
+   * [Related records in a list](website/src/content/docs/reference/ui-config.mdx#related-records-in-a-list).
+   */
+  related: (name: string, o: Omit<RelatedColumnModel, "name">) => ListColumn;
+};
+//#endregion

package/dist/view-columns.js

@@ -0,0 +1,17 @@
+//#region src/view-columns.ts
+const isListColumn = (value) => typeof value === "object" && value !== null && value.kind === "related";
+const columns = { 
+/**
+* A column named `name` of the records of `resource` that point at each row, through its relation `field` or, with
+* `through`, through a join resource, as a related section's. Each record is a dot in the colour its `status` value
+* has in its view's `valueColors`, in `sort` order, and a link to the record, showing its card on hover or focus. The
+* name must not be a field of the resource. See
+* [Related records in a list](website/src/content/docs/reference/ui-config.mdx#related-records-in-a-list).
+*/
+related: (name, o) => ({
+	kind: "related",
+	name,
+	...structuredClone(o)
+}) };
+//#endregion
+export { columns, isListColumn };

package/dist/view.d.ts

@@ -1,6 +1,7 @@
 import { ActionModel, ChartGranularity, ChartRange, CreateModel, ExportModel, FilterWidgetModel, HelpWhen, LayoutItemModel, ListDisplayModel, NavModel, NavRecentModel, RecordMode, ResourceModel, SaveFeedback, SaveSearchModel, SignInPromptModel, ViewModel } from "./model.js";
 import { FieldRefs, Ref } from "./refs.js";
 import { actions } from "./view-actions.js";
+import { ListColumn, columns } from "./view-columns.js";
 import { displays } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
 import { widgets } from "./view-widgets.js";
@@ -65,11 +66,12 @@ export declare class ViewBuilder<R extends {
   /** Hints per field, such as `{ total: r.total.prefix('€').decimals(2) }`; calls add up. */
   fields(build: (r: FieldViews<R>) => Record<string, FieldView>): ViewBuilder<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.
+   * The list: its table's `columns`, fields or columns of related records (`c.related`), `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 or column names collide or `default` names none.
    */
-  list(build: (r: FieldRefs<FieldsOf<R>>, d: typeof displays) => {
-    columns: Ref[];
+  list(build: (r: FieldRefs<FieldsOf<R>>, d: typeof displays, c: typeof columns) => {
+    columns: Array<Ref | ListColumn>;
     sort?: Array<[Ref, 'asc' | 'desc']>;
     search?: Ref[];
     displays?: ListDisplayModel[];
@@ -172,7 +174,7 @@ export declare class ViewBuilder<R extends {
     };
     limit?: number;
   }): ViewBuilder<R>;
-  /** With the resource's model, also verifies the title, search result and list display fields, a gallery's image, `listOf`, `searchesOf` and the sidebar's `recent` group. */
+  /** With the resource's model, also verifies the title, search result and list display fields, related column names, a gallery's image, `listOf`, `searchesOf` and the sidebar's `recent` group. */
   toModel(resource?: ResourceModel): ViewModel;
   private refs;
   private next;

package/dist/view.js

@@ -2,6 +2,7 @@ import { createRefs, ref } from "./refs.js";
 import { isMenuHref } from "./menu-href.js";
 import { navRecentErrors } from "./nav-recent.js";
 import { actions } from "./view-actions.js";
+import { columns, isListColumn } from "./view-columns.js";
 import { displayErrors, displayFields, displays } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
 import { widgets } from "./view-widgets.js";
@@ -72,13 +73,19 @@ var ViewBuilder = class ViewBuilder {
 		} });
 	}
 	/**
-	* 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.
+	* The list: its table's `columns`, fields or columns of related records (`c.related`), `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 or column names collide or `default` names none.
 	*/
 	list(build) {
-		const { columns, sort, search, displays: shown = [], default: opens } = build(this.refs(), displays);
+		const { columns: columns$1, sort, search, displays: shown = [], default: opens } = build(this.refs(), displays, columns);
+		const related = columns$1.filter(isListColumn).map(({ kind: _, ...column }) => column);
+		const names = columns$1.map((column) => column.name);
+		const repeated = names.find((name, index) => names.indexOf(name) !== index);
+		if (repeated !== void 0) throw new Error(`View "${this.state.resource}": the list has two columns named "${repeated}"`);
 		const list = {
-			columns: columns.map((ref) => ref.name),
+			columns: names,
+			...related.length > 0 && { relatedColumns: related },
 			...sort && { sort: sort.map(([ref, dir]) => [ref.name, dir]) },
 			...search && { search: search.map((ref) => ref.name) },
 			...shown.length > 0 && { displays: shown },
@@ -218,7 +225,7 @@ var ViewBuilder = class ViewBuilder {
 		};
 		return this.next({ searchesOf: searches });
 	}
-	/** With the resource's model, also verifies the title, search result and list display fields, a gallery's image, `listOf`, `searchesOf` and the sidebar's `recent` group. */
+	/** With the resource's model, also verifies the title, search result and list display fields, related column names, a gallery's image, `listOf`, `searchesOf` and the sidebar's `recent` group. */
 	toModel(resource) {
 		const { title, nav, searchResult, list, listOf } = 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`);
@@ -231,6 +238,8 @@ var ViewBuilder = class ViewBuilder {
 			const flag = display.kind === "cards" ? display.flags?.find((name) => resource.fields[name].type !== "boolean") : void 0;
 			if (flag !== void 0) throw new Error(`View "${this.state.resource}": display "${display.name}" shows "${flag}" as a flag, which is not a boolean field`);
 		}
+		const clash = resource ? list?.relatedColumns?.find((column) => Object.hasOwn(resource.fields, column.name)) : void 0;
+		if (clash) throw new Error(`View "${this.state.resource}": related column "${clash.name}" has the name of a field of the resource`);
 		for (const item of resource ? this.state.layout : []) {
 			if (item.kind !== "gallery" || item.image === void 0) continue;
 			if (!Object.hasOwn(resource.fields, item.image)) throw new Error(`View "${this.state.resource}": gallery "${item.title}" names field "${item.image}", which the resource does not have`);

package/package.json

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