@protobase/schema 0.19.16 → 0.21.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FileOptions, FileProcessor, FileProcessorInput, ImageFormat, ImageVariant, ImageVariantOptions, imageFormats } from "./files/file-options.js";
-import { ActionInputKind, ActionInputModel, 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, ShowWhen, SignInPromptModel, SignInViewModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { ActionInputKind, ActionInputModel, 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, GroupChartModel, HelpWhen, HistorySectionModel, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListModel, ListQuery, Literal, MapSectionModel, MapView, NavModel, NavRecentModel, NowValue, OrderByItem, PeriodChartModel, RecordMode, RelatedColumnModel, RelatedModel, ResourceModel, SaveFeedback, SaveSearchModel, SearchMatch, SearchResultModel, SearchesOfModel, SectionPresentation, ShowWhen, 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 { ChartInput, GroupChartInput, PeriodChartInput } from "./view-chart.js";
 import { ListColumn } from "./view-columns.js";
 import { ComponentRef, ViewProps } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
@@ -38,4 +39,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 ActionInputKind, type ActionInputModel, 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 ShowWhen, 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, fitsKeyType, 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 ActionInputKind, type ActionInputModel, 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 ChartInput, 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 GroupChartInput, type GroupChartModel, type HeldCapability, type HelpWhen, type HistorySectionModel, 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 PeriodChartInput, type PeriodChartModel, 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 ShowWhen, 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, fitsKeyType, 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/internal.d.ts

@@ -1,5 +1,6 @@
 import { checkedAccept, checkedProvider, parseSize } from "./files/file-options.js";
 import { actionInputErrors, shownInputs } from "./action-inputs.js";
+import { chartFields, isGroupChart } from "./view-chart.js";
 import { boardErrors, cardPhotoLimit, displayFields, tableDisplay } from "./view-displays.js";
 import { fieldRefsIn, isFieldRef, markFieldRefs, unmarkFieldRefs } from "./field-ref.js";
 import { bottomBarFor } from "./bottom-bar.js";
@@ -15,4 +16,4 @@ import { addressPlaceholders, appHrefError, fillAddress, hrefField, hrefPlacehol
 import { AddressCheck, addressErrors } from "./address-errors.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { type AddressCheck, type PluginHost, type PluginRequirement, type PropShapes, type RefShape, type SearchTerm, actionInputErrors, addressErrors, addressPlaceholders, appHrefError, applyAssistantEvent, boardErrors, bottomBarFor, cardPhotoLimit, checkEventFilter, checkedAccept, checkedProvider, decodeKey, defaultRecentLimit, displayFields, emptyAssistantState, encodeKey, fieldRefsIn, fillAddress, hrefField, hrefPlaceholders, inRange, isFieldRef, leavesApp, linkActionError, markFieldRefs, matchedSearchField, matchesSearch, navRecentErrors, parseSize, pluginProblem, pruneByShape, readEventStream, redactSecrets, searchTerms, shapes, shownInputs, statusTones, tableDisplay, termMatches, unmarkFieldRefs, webhookResources };
+export { type AddressCheck, type PluginHost, type PluginRequirement, type PropShapes, type RefShape, type SearchTerm, actionInputErrors, addressErrors, addressPlaceholders, appHrefError, applyAssistantEvent, boardErrors, bottomBarFor, cardPhotoLimit, chartFields, checkEventFilter, checkedAccept, checkedProvider, decodeKey, defaultRecentLimit, displayFields, emptyAssistantState, encodeKey, fieldRefsIn, fillAddress, hrefField, hrefPlaceholders, inRange, isFieldRef, isGroupChart, leavesApp, linkActionError, markFieldRefs, matchedSearchField, matchesSearch, navRecentErrors, parseSize, pluginProblem, pruneByShape, readEventStream, redactSecrets, searchTerms, shapes, shownInputs, statusTones, tableDisplay, termMatches, unmarkFieldRefs, webhookResources };

package/dist/internal.js

@@ -4,6 +4,7 @@ import { checkEventFilter } from "./events/event-models.js";
 import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
 import { actionInputErrors, shownInputs } from "./action-inputs.js";
 import { addressPlaceholders, appHrefError, fillAddress, hrefField, hrefPlaceholders, leavesApp, linkActionError } from "./address-template.js";
+import { chartFields, isGroupChart } from "./view-chart.js";
 import { fieldRefsIn, isFieldRef, markFieldRefs, unmarkFieldRefs } from "./field-ref.js";
 import { boardErrors, cardPhotoLimit, displayFields, tableDisplay } from "./view-displays.js";
 import { bottomBarFor } from "./bottom-bar.js";
@@ -15,4 +16,4 @@ import { redactSecrets } from "./redact-secrets.js";
 import { addressErrors } from "./address-errors.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { actionInputErrors, addressErrors, addressPlaceholders, appHrefError, applyAssistantEvent, boardErrors, bottomBarFor, cardPhotoLimit, checkEventFilter, checkedAccept, checkedProvider, decodeKey, defaultRecentLimit, displayFields, emptyAssistantState, encodeKey, fieldRefsIn, fillAddress, hrefField, hrefPlaceholders, inRange, isFieldRef, leavesApp, linkActionError, markFieldRefs, matchedSearchField, matchesSearch, navRecentErrors, parseSize, pluginProblem, pruneByShape, readEventStream, redactSecrets, searchTerms, shapes, shownInputs, statusTones, tableDisplay, termMatches, unmarkFieldRefs, webhookResources };
+export { actionInputErrors, addressErrors, addressPlaceholders, appHrefError, applyAssistantEvent, boardErrors, bottomBarFor, cardPhotoLimit, chartFields, checkEventFilter, checkedAccept, checkedProvider, decodeKey, defaultRecentLimit, displayFields, emptyAssistantState, encodeKey, fieldRefsIn, fillAddress, hrefField, hrefPlaceholders, inRange, isFieldRef, isGroupChart, leavesApp, linkActionError, markFieldRefs, matchedSearchField, matchesSearch, navRecentErrors, parseSize, pluginProblem, pruneByShape, readEventStream, redactSecrets, searchTerms, shapes, shownInputs, statusTones, tableDisplay, termMatches, unmarkFieldRefs, webhookResources };

package/dist/layout.d.ts

@@ -64,6 +64,15 @@ export declare const layout: {
     sidebar?: boolean;
     when?: ShowWhen;
   }) => LayoutItemModel;
+  /**
+   * The record's changes, newest first: who made each, when, and the fields before and after, only those the user may
+   * read. `limit` changes show before Show more (default 10). Needs `.history()` on the resource; a view without a
+   * layout shows it last by itself. See [Record history](website/src/content/docs/reference/history.mdx).
+   */
+  history: (title?: string, o?: {
+    limit?: number;
+    when?: ShowWhen;
+  }) => 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,

package/dist/layout.js

@@ -80,6 +80,20 @@ const layout = {
 		...o.when !== void 0 && { when: o.when }
 	}),
 	/**
+	* The record's changes, newest first: who made each, when, and the fields before and after, only those the user may
+	* read. `limit` changes show before Show more (default 10). Needs `.history()` on the resource; a view without a
+	* layout shows it last by itself. See [Record history](website/src/content/docs/reference/history.mdx).
+	*/
+	history: (title = "History", o = {}) => {
+		if (o.limit !== void 0 && (!Number.isInteger(o.limit) || o.limit < 1)) throw new Error(`l.history "${title}": limit must be a positive whole number`);
+		return {
+			kind: "history",
+			title,
+			...o.limit !== void 0 && { limit: o.limit },
+			...o.when !== void 0 && { when: o.when }
+		};
+	},
+	/**
 	* 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()`.

package/dist/model.d.ts

@@ -96,6 +96,8 @@ export type ResourceModel = {
   owner?: string;
   /** The events its changes raise (`.events()`), the catalogue subscriptions pick from. */
   events?: EventModel[];
+  /** Whether every change of its records is kept, with who made it (`.history()`). */
+  history?: true;
 };
 /** What happened to a record: `delete` and `undelete` include setting and clearing a soft delete field. */
 export type EventOperation = 'create' | 'update' | 'delete' | 'undelete';
@@ -636,6 +638,20 @@ export type MapSectionModel = {
   /** Whether it shows on the form, the read view or both. */
   when?: ShowWhen;
 };
+/**
+ * The record's changes, newest first, with who made each and the fields before and after: only fields the caller may
+ * read. Needs `.history()` on the resource. See [Record history](website/src/content/docs/reference/history.mdx).
+ */
+export type HistorySectionModel = {
+  /** A history section. */
+  kind: 'history';
+  /** The section's title. */
+  title: string;
+  /** How many changes it shows before Show more; 10 when omitted. */
+  limit?: number;
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
+};
 /** How a section shows its fields on the read view: `facts` as a row of key facts; label/value rows when omitted. */
 export type SectionPresentation = 'facts';
 /** An item of the record page (`.layout((r) => ...)` with `l`); see [The record page](website/src/content/docs/reference/ui-config.mdx#the-record-page). */
@@ -664,7 +680,7 @@ export type LayoutItemModel = {
   fields: string[];
   /** Whether it shows on the form, the read view or both. */
   when?: ShowWhen;
-} | RelatedModel | CustomSectionModel | MapSectionModel | GalleryModel;
+} | RelatedModel | CustomSectionModel | MapSectionModel | GalleryModel | HistorySectionModel;
 /**
  * A record's photos as tiles in the main column under `title`, one large and the next few smaller, opening a lightbox
  * that steps through them all: first the record's own file field `image`, then the `image` of the records of
@@ -687,8 +703,8 @@ export type GalleryModel = {
 export type ChartRange = '7d' | '30d' | '90d' | '1y' | 'all';
 /** How long each bar of a list's chart is. */
 export type ChartGranularity = 'hour' | 'day' | 'week' | 'month';
-/** A chart of records over time above a list, following its filters (`.chart(...)`). */
-export type ChartModel = {
+/** A chart of records over time above a list, following its filters (`.chart(...)` with `field`). */
+export type PeriodChartModel = {
   /** The date or timestamp field the records are counted by. */
   field: string;
   /** How far back it reaches. */
@@ -696,6 +712,21 @@ export type ChartModel = {
   /** How long each bar is. */
   granularity: ChartGranularity;
 };
+/** A chart of records per value of a field above a list, following its filters (`.chart(...)` with `groupBy`). */
+export type GroupChartModel = {
+  /** The field whose values make the groups, such as a status or a relation; not a date. */
+  groupBy: string;
+  /** Bars, the largest first, or a donut. */
+  type: 'bar' | 'donut';
+  /** A numeric field each group adds up, instead of counting its records. */
+  sum?: string;
+  /** A numeric field each group averages, instead of counting its records. */
+  average?: string;
+  /** How many values it shows, the largest. */
+  limit: number;
+};
+/** The chart above a list: records over time, or records per value of a field. */
+export type ChartModel = PeriodChartModel | GroupChartModel;
 /**
  * How the record page opens to a user who may change the record: `edit`, the default, as its form, ready to change;
  * `read` as a read view of label/value tables, with an Edit button to the form; `locked` as the same form, locked until

package/dist/resource-model.d.ts

@@ -13,5 +13,6 @@ export type ResourceState = {
   searchMatch?: Record<string, SearchMatch>;
   owner?: string;
   events?: EventSpec[];
+  history?: boolean;
 };
 //#endregion

package/dist/resource-model.js

@@ -57,7 +57,8 @@ const assembleModel = (state) => {
 		...state.tenant && { tenant: state.tenant },
 		...state.search && { search: [...state.search] },
 		...state.searchMatch && Object.keys(state.searchMatch).length > 0 && { searchMatch: { ...state.searchMatch } },
-		...state.owner && { owner: state.owner }
+		...state.owner && { owner: state.owner },
+		...state.history && { history: true }
 	};
 };
 const sensitiveProblems = (model) => Object.values(model.fields).filter((field) => field.sensitive).flatMap((field) => [

package/dist/resource.d.ts

@@ -83,6 +83,12 @@ export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
    * ```
    */
   events(define: (e: EventHelpers<RecordOf<F>>, r: FieldRefs<F>) => EventSpec[]): ResourceBuilder<F, K>;
+  /**
+   * Keeps every change of its records, from the API or elsewhere: the fields before and after, and who made it. The
+   * record page shows it as History, and admins list every change as Activity. See
+   * [Record history](website/src/content/docs/reference/history.mdx).
+   */
+  history(): ResourceBuilder<F, K>;
   /** The code predicates (`match`) of its events, by event name. */
   eventMatches(): Record<string, EventMatch<any>>;
   /**

package/dist/resource.js

@@ -94,6 +94,14 @@ var ResourceBuilder = class ResourceBuilder {
 	events(define) {
 		return this.next({ events: define(eventHelpers(), this.refs()) });
 	}
+	/**
+	* Keeps every change of its records, from the API or elsewhere: the fields before and after, and who made it. The
+	* record page shows it as History, and admins list every change as Activity. See
+	* [Record history](website/src/content/docs/reference/history.mdx).
+	*/
+	history() {
+		return this.next({ history: true });
+	}
 	/** The code predicates (`match`) of its events, by event name. */
 	eventMatches() {
 		return eventMatches(this.toModel(), this.state.events ?? []);

package/dist/view-chart.d.ts

@@ -0,0 +1,32 @@
+import { ChartGranularity, ChartModel, ChartRange, GroupChartModel } from "./model.js";
+import { Ref } from "./refs.js";
+//#region src/view-chart.d.ts
+/** Records per `granularity` over a date or timestamp `field`. */
+export type PeriodChartInput = {
+  /** The date or timestamp field the records are counted by. */
+  field: Ref;
+  /** How far back it reaches. */
+  range: ChartRange;
+  /** How long each bar is. */
+  granularity: ChartGranularity;
+};
+/** Records per value of `groupBy`, counted, or with `sum` or `average` that of a numeric field. */
+export type GroupChartInput = {
+  /** The field whose values make the groups, such as a status or a relation; not a date. */
+  groupBy: Ref;
+  /** Bars, the default, or a donut. */
+  type?: GroupChartModel['type'];
+  /** How many values it shows, the largest; default 10. */
+  limit?: number;
+  /** A numeric field each group adds up, instead of counting its records. */
+  sum?: Ref;
+  /** A numeric field each group averages, instead of counting its records. */
+  average?: Ref;
+};
+/** What `.chart(...)` takes: a chart over time or per value. */
+export type ChartInput = PeriodChartInput | GroupChartInput;
+/** Whether a list's chart counts records per value of a field rather than over time. */
+export declare const isGroupChart: (chart: ChartModel) => chart is GroupChartModel;
+/** The fields a list's chart reads: its date field, or the field it groups by and the one it adds up. */
+export declare const chartFields: (chart: ChartModel) => string[];
+//#endregion

package/dist/view-chart.js

@@ -0,0 +1,29 @@
+//#region src/view-chart.ts
+const defaultLimit = 10;
+const chartModel = (input) => {
+	if (!("groupBy" in input)) return {
+		field: input.field.name,
+		range: input.range,
+		granularity: input.granularity
+	};
+	if (input.sum && input.average) throw new Error("A chart takes sum or average, not both");
+	const limit = input.limit ?? defaultLimit;
+	if (!Number.isInteger(limit) || limit < 1) throw new Error(`A chart's limit must be a positive whole number, not ${limit}`);
+	return {
+		groupBy: input.groupBy.name,
+		type: input.type ?? "bar",
+		...input.sum && { sum: input.sum.name },
+		...input.average && { average: input.average.name },
+		limit
+	};
+};
+/** Whether a list's chart counts records per value of a field rather than over time. */
+const isGroupChart = (chart) => "groupBy" in chart;
+/** The fields a list's chart reads: its date field, or the field it groups by and the one it adds up. */
+const chartFields = (chart) => isGroupChart(chart) ? [
+	chart.groupBy,
+	...chart.sum ? [chart.sum] : [],
+	...chart.average ? [chart.average] : []
+] : [chart.field];
+//#endregion
+export { chartFields, chartModel, isGroupChart };

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 { ActionModel, 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 { ChartInput } from "./view-chart.js";
 import { ListColumn, columns } from "./view-columns.js";
 import { displays } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
@@ -90,12 +91,12 @@ export declare class ViewBuilder<R extends {
    * Without it the page shows one section with every field.
    */
   layout(build: (r: FieldRefs<FieldsOf<R>>) => LayoutItemModel[]): ViewBuilder<R>;
-  /** A chart of records per `granularity` over a date or timestamp `field` above the list, following its filters. */
-  chart(build: (r: FieldRefs<FieldsOf<R>>) => {
-    field: Ref;
-    range: ChartRange;
-    granularity: ChartGranularity;
-  }): ViewBuilder<R>;
+  /**
+   * A chart above the list, following its filters: records per `granularity` over a date or timestamp `field`, or
+   * records per value of `groupBy`, such as a status or a relation, as bars or a donut of the `limit` largest (default
+   * 10), counted or with `sum` or `average` that of a numeric field.
+   */
+  chart(build: (r: FieldRefs<FieldsOf<R>>) => ChartInput): ViewBuilder<R>;
   /**
    * How the record page opens to a user who may change the record: `edit`, the default, as its form; `read` as a read
    * view, its sections as tables of labels and values, with an Edit button to the form; `locked` as the form, locked

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 { chartModel } from "./view-chart.js";
 import { columns, isListColumn } from "./view-columns.js";
 import { boardErrors, displayErrors, displayFields, displays } from "./view-displays.js";
 import { FieldView } from "./view-field.js";
@@ -114,14 +115,13 @@ var ViewBuilder = class ViewBuilder {
 	layout(build) {
 		return this.next({ layout: build(this.refs()) });
 	}
-	/** A chart of records per `granularity` over a date or timestamp `field` above the list, following its filters. */
+	/**
+	* A chart above the list, following its filters: records per `granularity` over a date or timestamp `field`, or
+	* records per value of `groupBy`, such as a status or a relation, as bars or a donut of the `limit` largest (default
+	* 10), counted or with `sum` or `average` that of a numeric field.
+	*/
 	chart(build) {
-		const { field, range, granularity } = build(this.refs());
-		return this.next({ chart: {
-			field: field.name,
-			range,
-			granularity
-		} });
+		return this.next({ chart: chartModel(build(this.refs())) });
 	}
 	/**
 	* How the record page opens to a user who may change the record: `edit`, the default, as its form; `read` as a read

package/package.json

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