@protobase/schema 0.19.13 → 0.19.14

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, RelatedColumnModel, 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, 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";
@@ -38,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 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 };
+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 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, 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

@@ -1,4 +1,4 @@
-import { CardPhotosModel, HelpWhen, LayoutItemModel, RelatedModel, SectionPresentation } from "./model.js";
+import { CardPhotosModel, HelpWhen, LayoutItemModel, RelatedModel, SectionPresentation, ShowWhen } from "./model.js";
 import { Ref } from "./refs.js";
 import { ComponentRef, ViewProps } from "./view-displays.js";
 //#region src/layout.d.ts
@@ -14,6 +14,10 @@ import { ComponentRef, ViewProps } from "./view-displays.js";
  *   l.related('Parts used', { resource: 'repair_parts', field: 'repair_id' }),
  * ])
  * ```
+ *
+ * Every item shows on both the form and the read view unless its `when` says `editing` (the form and the create form)
+ * or `reading` (the read view and the locked form). See
+ * [Form and read view](website/src/content/docs/reference/ui-config.mdx#form-and-read-view).
  */
 export declare const layout: {
   /**
@@ -27,6 +31,7 @@ export declare const layout: {
     help?: string;
     helpWhen?: HelpWhen;
     presentation?: SectionPresentation;
+    when?: ShowWhen;
   }) => LayoutItemModel;
   /**
    * The record's photos as tiles in the main column, one large and the next four smaller, the last saying how many more
@@ -39,9 +44,12 @@ export declare const layout: {
   gallery: (title: string, o: {
     image?: Ref;
     photos?: CardPhotosModel;
+    when?: ShowWhen;
   }) => LayoutItemModel;
   /** A read-only summary card of fields beside the main column. */
-  sidebar: (fields: Ref[]) => LayoutItemModel;
+  sidebar: (fields: Ref[], o?: {
+    when?: ShowWhen;
+  }) => 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;
   /**
@@ -54,6 +62,7 @@ export declare const layout: {
     longitude: Ref;
     zoom?: number;
     sidebar?: boolean;
+    when?: ShowWhen;
   }) => LayoutItemModel;
   /**
    * A component of the project, registered in `protobase.ui.tsx` under its name, drawn where it is listed: in the main
@@ -64,6 +73,7 @@ export declare const layout: {
     title?: string;
     props?: ViewProps<P>;
     sidebar?: boolean;
+    when?: ShowWhen;
   }) => LayoutItemModel;
 };
 //#endregion

package/dist/layout.js

@@ -13,6 +13,10 @@ import { customComponent } from "./view-displays.js";
 *   l.related('Parts used', { resource: 'repair_parts', field: 'repair_id' }),
 * ])
 * ```
+*
+* Every item shows on both the form and the read view unless its `when` says `editing` (the form and the create form)
+* or `reading` (the read view and the locked form). See
+* [Form and read view](website/src/content/docs/reference/ui-config.mdx#form-and-read-view).
 */
 const layout = {
 	/**
@@ -28,7 +32,8 @@ const layout = {
 		fields: fields.map((ref) => ref.name),
 		...o.help !== void 0 && { help: o.help },
 		...o.helpWhen !== void 0 && { helpWhen: o.helpWhen },
-		...o.presentation !== void 0 && { presentation: o.presentation }
+		...o.presentation !== void 0 && { presentation: o.presentation },
+		...o.when !== void 0 && { when: o.when }
 	}),
 	/**
 	* The record's photos as tiles in the main column, one large and the next four smaller, the last saying how many more
@@ -44,13 +49,15 @@ const layout = {
 			kind: "gallery",
 			title,
 			...o.image && { image: o.image.name },
-			...o.photos && { photos: { ...o.photos } }
+			...o.photos && { photos: { ...o.photos } },
+			...o.when !== void 0 && { when: o.when }
 		};
 	},
 	/** A read-only summary card of fields beside the main column. */
-	sidebar: (fields) => ({
+	sidebar: (fields, o = {}) => ({
 		kind: "sidebar",
-		fields: fields.map((ref) => ref.name)
+		fields: fields.map((ref) => ref.name),
+		...o.when !== void 0 && { when: o.when }
 	}),
 	/** A table of the records of another resource that point at this one, directly or through a join table. */
 	related: (title, o) => ({
@@ -69,7 +76,8 @@ const layout = {
 		latitude: o.latitude.name,
 		longitude: o.longitude.name,
 		...o.zoom !== void 0 && { zoom: o.zoom },
-		...o.sidebar && { sidebar: true }
+		...o.sidebar && { sidebar: true },
+		...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
@@ -81,7 +89,8 @@ const layout = {
 		component: customComponent(component, "l.custom"),
 		...o.title !== void 0 && { title: o.title },
 		...o.props && { props: markFieldRefs(o.props) },
-		...o.sidebar && { sidebar: true }
+		...o.sidebar && { sidebar: true },
+		...o.when !== void 0 && { when: o.when }
 	})
 };
 //#endregion

package/dist/model.d.ts

@@ -219,6 +219,8 @@ export type FieldViewModel = {
   help?: string;
   /** When `help` shows: always, or only while the record is edited; the view's `helpWhen` when omitted. */
   helpWhen?: HelpWhen;
+  /** When the field shows on the record page: always, the default, only on its form or only on its read view. */
+  when?: ShowWhen;
   /** How the value is shown. */
   format?: FieldFormat;
   /** A text that runs over several lines: forms edit it in a box that grows with it, and its line breaks show. */
@@ -254,6 +256,12 @@ export type FieldViewModel = {
  * [The record page](website/src/content/docs/reference/ui-config.mdx#the-record-page).
  */
 export type HelpWhen = 'always' | 'editing';
+/**
+ * When a record page's field or layout item shows: `always`, the default; only while the record is `editing`, on its
+ * form and the create form; or only while `reading` it, on the read view and the locked form. See
+ * [Form and read view](website/src/content/docs/reference/ui-config.mdx#form-and-read-view).
+ */
+export type ShowWhen = 'always' | 'editing' | 'reading';
 /** How a field's badges are drawn: `arrow` points them right, as on a rating scale. */
 export type BadgeShape = 'arrow';
 /** A field type by the name a plugin registers it under, and the plain data it is given. */
@@ -560,6 +568,8 @@ export type RelatedModel = {
   display?: string;
   /** The text when nothing matches. */
   empty?: string;
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
 };
 /**
  * A project component drawn on the record page where it is listed, in the main column or with `sidebar` in the
@@ -576,6 +586,8 @@ export type CustomSectionModel = {
   props?: Record<string, JsonValue>;
   /** Drawn as a sidebar card instead of in the main column. */
   sidebar?: true;
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
 };
 /**
  * A map of the record's position, its `latitude` and `longitude` fields in decimal degrees (WGS84), centred on a marker
@@ -595,6 +607,8 @@ export type MapSectionModel = {
   zoom?: number;
   /** Drawn as a sidebar card instead of in the main column. */
   sidebar?: true;
+  /** 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';
@@ -615,11 +629,15 @@ export type LayoutItemModel = {
    * label/value rows; the form edits them as any section's.
    */
   presentation?: SectionPresentation;
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
 } | {
   /** A read-only summary card beside the main column. */
   kind: 'sidebar';
   /** The fields it shows, in order. */
   fields: string[];
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
 } | RelatedModel | CustomSectionModel | MapSectionModel | GalleryModel;
 /**
  * A record's photos as tiles in the main column under `title`, one large and the next few smaller, opening a lightbox
@@ -636,6 +654,8 @@ export type GalleryModel = {
   image?: string;
   /** The records holding the further photos. */
   photos?: CardPhotosModel;
+  /** Whether it shows on the form, the read view or both. */
+  when?: ShowWhen;
 };
 /** How far back a list's chart reaches. */
 export type ChartRange = '7d' | '30d' | '90d' | '1y' | 'all';

package/dist/view-field.d.ts

@@ -1,4 +1,4 @@
-import { BadgeShape, FieldFormat, FieldViewModel, HelpWhen, JsonValue } from "./model.js";
+import { BadgeShape, FieldFormat, FieldViewModel, HelpWhen, JsonValue, ShowWhen } from "./model.js";
 //#region src/view-field.d.ts
 /** How a view shows one field, as `.fields((r) => ...)` hands it out: each hint returns a new field view. */
 export declare class FieldView<N extends string = string, V = unknown> {
@@ -21,6 +21,11 @@ export declare class FieldView<N extends string = string, V = unknown> {
   help(help: string, o?: {
     when?: HelpWhen;
   }): FieldView<N, V>;
+  /**
+   * When the field shows on the record page: `editing` only on its form and the create form, `reading` only on its read
+   * view and locked form; `always` when omitted. Its lists, cards and filters show it either way.
+   */
+  when(when: ShowWhen): FieldView<N, V>;
   /** How the value shows: `badge` for statuses, `code` in monospace, `percent` with a % sign. */
   format(format: FieldFormat): FieldView<N, V>;
   /**

package/dist/view-field.js

@@ -23,6 +23,13 @@ var FieldView = class FieldView {
 			...o.when !== void 0 && { helpWhen: o.when }
 		});
 	}
+	/**
+	* When the field shows on the record page: `editing` only on its form and the create form, `reading` only on its read
+	* view and locked form; `always` when omitted. Its lists, cards and filters show it either way.
+	*/
+	when(when) {
+		return this.with({ when });
+	}
 	/** How the value shows: `badge` for statuses, `code` in monospace, `percent` with a % sign. */
 	format(format) {
 		return this.with({ format });

package/package.json

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