@protobase/schema 0.20.0 → 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, GroupChartModel, HelpWhen, 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 { 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";
@@ -39,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 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 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 };
+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/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

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/package.json

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