@protobase/schema 0.13.3 → 0.14.0

package/dist/refs.d.ts

@@ -1,11 +1,17 @@
 import { AnyField, Field } from "./field.js";
 //#region src/refs.d.ts
+/** The fields of `.fields({ ... })` by name; `null` ignores a column on purpose. */
 export type FieldsInput = Record<string, AnyField | null>;
 export type ActiveFields<F> = { [K in keyof F as F[K] extends null ? never : K]: F[K]; };
+/** A field picked in a builder's callback, such as `r.status`: its name, typed with its value. */
 export type Ref<N extends string = string, V = unknown> = {
+  /** The field's name. */
   readonly name: N;
+  /** The field's value type, for the compiler only; never set. */
   readonly $value?: V;
 };
+/** A reference per field of `F`, by name. */
 export type Refs<F> = { readonly [K in keyof F & string]: F[K] extends Field<infer V> ? Ref<K, V> : never; };
+/** The `r` of a builder's callback: a reference per field of `F`, the ignored (`null`) ones left out. */
 export type FieldRefs<F> = Refs<ActiveFields<F>>;
 //#endregion

package/dist/relation-field.d.ts

@@ -1,6 +1,11 @@
 import { Field } from "./field.js";
 //#region src/relation-field.d.ts
+/** `f.relation(resource)`: a field holding the key of a record of another resource. */
 export declare class RelationField<V> extends Field<V> {
+  /**
+   * The columns that hold the other record's key, in the order of that key, for a resource with a key of several
+   * columns. See [Keys and relations](website/src/content/docs/reference/data-config.mdx#keys-and-relations).
+   */
   columns(columns: string[]): Field<V>;
 }
 //#endregion

package/dist/relation-field.js

@@ -1,6 +1,11 @@
 import { Field } from "./field.js";
 //#region src/relation-field.ts
+/** `f.relation(resource)`: a field holding the key of a record of another resource. */
 var RelationField = class extends Field {
+	/**
+	* The columns that hold the other record's key, in the order of that key, for a resource with a key of several
+	* columns. See [Keys and relations](website/src/content/docs/reference/data-config.mdx#keys-and-relations).
+	*/
 	columns(columns) {
 		return this.with({ relation: {
 			resource: this.meta.relation.resource,

package/dist/resource-types.d.ts

@@ -3,19 +3,37 @@ import { Field } from "./field.js";
 import { ActiveFields, Ref } from "./refs.js";
 //#region src/resource-types.d.ts
 type Prettify<T> = { [K in keyof T]: T[K]; } & {};
+/** The record of a resource with fields `F`: each field's value type by name, the ignored (`null`) ones left out. */
 export type RecordOf<F> = Prettify<{ [K in keyof ActiveFields<F>]: ActiveFields<F>[K] extends Field<infer V> ? V : never; }>;
+/** What `.primaryKey()` picks: one field, or a list for a key of several columns. */
 export type KeyRefs = Ref | readonly Ref[];
+/** A record's key from the fields `.primaryKey()` picked: one value, or a tuple of the parts. */
 export type KeyOf<K> = K extends readonly Ref[] ? { -readonly [I in keyof K]: K[I] extends Ref<string, infer V> ? V : never; } : K extends Ref<string, infer V> ? V : never;
+/** A problem `.validate()` finds with a record, answered with `400` and the field named. */
 export type Issue<F> = {
+  /** The field it is about. */
   field: keyof RecordOf<F> & string;
+  /** What is wrong, for the user. */
   message: string;
 };
 /** Resource-level rules: operation, row filter and record-level check in one function. */
 export type Access<F> = { [A in AccessAction]?: AccessFn<RecordOf<F>>; };
+/**
+ * The record type of a resource, from the builder `resource(...)` returns: `InferRecord<typeof orders>`.
+ *
+ * @typeParam R - The resource builder, whose `$fields` carries its fields.
+ */
 export type InferRecord<R extends {
+  /** The builder's fields, as a type only. */
   readonly $fields: unknown;
 }> = RecordOf<R['$fields']>;
+/**
+ * The key type of a resource, from the builder `resource(...)` returns: `RecordKey<typeof stock>`.
+ *
+ * @typeParam R - The resource builder, whose `$key` carries the fields of its key.
+ */
 export type RecordKey<R extends {
+  /** The fields of the builder's key, as a type only. */
   readonly $key: unknown;
 }> = KeyOf<R['$key']>;
 //#endregion

package/dist/resource.d.ts

@@ -7,25 +7,59 @@ import { Access, Issue, KeyRefs, RecordOf } from "./resource-types.js";
 import "./index.js";
 import { z } from "zod";
 //#region src/resource.d.ts
-type SearchRef = Ref & {
+/** A field picked for search, with how it matches. */
+export type SearchRef = Ref & {
+  /** How it matches when not by containing the words; see {@link SearchMatch}. */
   readonly match?: SearchMatch;
 };
 /** A field picked for search; `digitsEnd()` matches only the end of its digits, ignoring spaces, `+` and dashes. */
-type SearchRefs<F> = { readonly [K in keyof FieldRefs<F>]: FieldRefs<F>[K] & {
+export type SearchRefs<F> = { readonly [K in keyof FieldRefs<F>]: FieldRefs<F>[K] & {
+  /** Matches only the end of the field's digits, ignoring spaces, `+` and dashes, for phone numbers. */
   digitsEnd(): SearchRef;
 }; };
-type Validator<F> = (record: RecordOf<F>) => Issue<F>[] | undefined;
+/** A rule over a whole record for `.validate()`: the issues it finds, or `undefined` when there are none. */
+export type Validator<F> = (record: RecordOf<F>) => Issue<F>[] | undefined;
+/**
+ * A resource as `resource(name)` builds it. Every method returns a new builder, so a resource is one chain. See
+ * [resource()](website/src/content/docs/reference/data-config.mdx#resource).
+ */
 export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
+  /** @internal */
   readonly state: ResourceState;
+  /** @internal */
   readonly validators: readonly Validator<F>[];
+  /** @internal */
   readonly accessRules: Access<F>;
+  /** The fields, for the compiler only, which {@link InferRecord} reads; never set. */
   readonly $fields: F;
+  /** The fields of the key, for the compiler only, which {@link RecordKey} reads; never set. */
   readonly $key: K;
-  constructor(state: ResourceState, validators?: readonly Validator<F>[], accessRules?: Access<F>);
+  /** @internal */
+  constructor(
+  /** @internal */
+  state: ResourceState,
+  /** @internal */
+  validators?: readonly Validator<F>[],
+  /** @internal */
+  accessRules?: Access<F>);
+  /** The table, with or without its schema: `'shop.repairs'` or `'repairs'`. Required. */
   table(table: string): ResourceBuilder<F, K>;
+  /**
+   * The columns, by field name, each built with `f`. `name: null` ignores a column on purpose. The column is the
+   * snake_case of the name unless `.column()` says otherwise. Required, and called before the methods that pick fields.
+   */
   fields<const N extends FieldsInput>(fields: N): ResourceBuilder<N, never>;
+  /** The key: one field, or a list for a key of several columns (`(r) => [r.order_id, r.line_no]`). Required. */
   primaryKey<const P extends KeyRefs>(pick: (r: FieldRefs<F>) => P): ResourceBuilder<F, P>;
+  /**
+   * A nullable timestamp or date that marks a record deleted: deleting sets it, lists leave such rows out and
+   * `:undelete` clears it.
+   */
   softDelete(pick: (r: FieldRefs<F>) => Ref): ResourceBuilder<F, K>;
+  /**
+   * The field that separates tenants: every query is limited to the caller's tenant, creates set it, and a request body
+   * may not.
+   */
   tenant(pick: (r: FieldRefs<F>) => Ref): ResourceBuilder<F, K>;
   /**
    * Fields matched by `search("...")` and bare words in filters. Authoritative over the UI's list search defaults.
@@ -35,22 +69,76 @@ export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
   /** The field holding the owning user's id, which `.own` capability scopes filter on. */
   owner(pick: (r: FieldRefs<F>) => Ref): ResourceBuilder<F, K>;
   /**
-   * The events changes to its records raise, captured in the database for every write, from the API or elsewhere:
-   * `(e, r) => [...e.crud(), e.becomes('large', 'total > 1000')]`.
+   * The events changes to its records raise, captured in the database for every write, from the API or elsewhere. See
+   * [Declaring events](website/src/content/docs/reference/events.mdx#declaring-events).
+   *
+   * @example
+   * ```ts
+   * .events((e, r) => [
+   *   ...e.crud(),
+   *   e.becomes('large', 'total > 1000'),
+   *   e.updated('statusChanged', { changed: [r.status] }),
+   *   e.updated('reopened', { from: 'status = "cancelled"', when: 'status != "cancelled"' }),
+   * ])
+   * ```
    */
   events(define: (e: EventHelpers<RecordOf<F>>, r: FieldRefs<F>) => EventSpec[]): ResourceBuilder<F, K>;
   /** The code predicates (`match`) of its events, by event name. */
   eventMatches(): Record<string, EventMatch<any>>;
+  /**
+   * A rule over the whole record, run after the field checks on every create and update. Its issues answer `400` with
+   * the field named. Each call adds a rule.
+   *
+   * @example
+   * ```ts
+   * .validate((repair) => (repair.status === 'collected' && !repair.paid ? [{ field: 'paid', message: 'A bike leaves the shop paid' }] : undefined))
+   * ```
+   */
   validate(validator: Validator<F>): ResourceBuilder<F, K>;
+  /**
+   * Rules per operation (`list`, `read`, `create`, `update`, `delete`). A rule returns `true`, `false`, or a filter that
+   * limits the rows. An operation without a rule needs its capability when the app has roles. See
+   * [Access](website/src/content/docs/reference/access.mdx).
+   *
+   * @example
+   * ```ts
+   * .access({
+   *   read: roles.can('work_orders.read'),
+   *   update: roles.can('work_orders.update').and((_ctx, record) => (record as { status: string }).status !== 'done'),
+   *   delete: roles.is('admin'),
+   * })
+   * ```
+   */
   access(rules: Access<F>): ResourceBuilder<F, K>;
   /** Role-based rules per field, for fields that declared `.access(...)`. */
   fieldAccess(): Record<string, FieldAccess>;
+  /** The resource as the server and the app read it. Throws when the table, fields or key are missing, or a field option conflicts with another. */
   toModel(): ResourceModel;
+  /** The Zod schema of a whole record, from its fields' schemas. */
   recordSchema(): z.ZodType<RecordOf<F>>;
+  /** The columns of the fields given as `null`, which the resource ignores on purpose. */
   ignoredColumns(): string[];
   private refs;
   private knownFields;
   private next;
 }
+/**
+ * A resource: one table of an existing database, its columns as fields, its key and the rules around it. `name` is its
+ * address (`/api/v1/<name>`) and how other config refers to it. See
+ * [Data config](website/src/content/docs/reference/data-config.mdx).
+ *
+ * @example
+ * ```ts
+ * export const customers = resource('customers')
+ *   .table('shop.customers')
+ *   .fields({
+ *     id: f.integer().readOnly().filterable().sortable().dbDefault(),
+ *     name: f.text().min(2).filterable().sortable(),
+ *     email: f.text().optional().filterable(),
+ *   })
+ *   .primaryKey((r) => r.id)
+ *   .search((r) => [r.name, r.email])
+ * ```
+ */
 export declare const resource: (name: string) => ResourceBuilder<{}, never>;
 //#endregion

package/dist/resource.js

@@ -4,24 +4,35 @@ import { buildResourceModel, ignoredColumns } from "./resource-model.js";
 import { createRefs } from "./refs.js";
 import { z } from "zod";
 //#region src/resource.ts
+/**
+* A resource as `resource(name)` builds it. Every method returns a new builder, so a resource is one chain. See
+* [resource()](website/src/content/docs/reference/data-config.mdx#resource).
+*/
 var ResourceBuilder = class ResourceBuilder {
 	state;
 	validators;
 	accessRules;
+	/** @internal */
 	constructor(state, validators = [], accessRules = {}) {
 		this.state = state;
 		this.validators = validators;
 		this.accessRules = accessRules;
 	}
+	/** The table, with or without its schema: `'shop.repairs'` or `'repairs'`. Required. */
 	table(table) {
 		return this.next({ table });
 	}
+	/**
+	* The columns, by field name, each built with `f`. `name: null` ignores a column on purpose. The column is the
+	* snake_case of the name unless `.column()` says otherwise. Required, and called before the methods that pick fields.
+	*/
 	fields(fields) {
 		return new ResourceBuilder({
 			...this.state,
 			fields
 		});
 	}
+	/** The key: one field, or a list for a key of several columns (`(r) => [r.order_id, r.line_no]`). Required. */
 	primaryKey(pick) {
 		const picked = pick(this.refs());
 		const refs = Array.isArray(picked) ? picked : [picked];
@@ -30,9 +41,17 @@ var ResourceBuilder = class ResourceBuilder {
 			primaryKey: refs.map((ref) => ref.name)
 		}, this.validators, this.accessRules);
 	}
+	/**
+	* A nullable timestamp or date that marks a record deleted: deleting sets it, lists leave such rows out and
+	* `:undelete` clears it.
+	*/
 	softDelete(pick) {
 		return this.next({ softDelete: pick(this.refs()).name });
 	}
+	/**
+	* The field that separates tenants: every query is limited to the caller's tenant, creates set it, and a request body
+	* may not.
+	*/
 	tenant(pick) {
 		return this.next({ tenant: pick(this.refs()).name });
 	}
@@ -59,8 +78,18 @@ var ResourceBuilder = class ResourceBuilder {
 		return this.next({ owner: pick(this.refs()).name });
 	}
 	/**
-	* The events changes to its records raise, captured in the database for every write, from the API or elsewhere:
-	* `(e, r) => [...e.crud(), e.becomes('large', 'total > 1000')]`.
+	* The events changes to its records raise, captured in the database for every write, from the API or elsewhere. See
+	* [Declaring events](website/src/content/docs/reference/events.mdx#declaring-events).
+	*
+	* @example
+	* ```ts
+	* .events((e, r) => [
+	*   ...e.crud(),
+	*   e.becomes('large', 'total > 1000'),
+	*   e.updated('statusChanged', { changed: [r.status] }),
+	*   e.updated('reopened', { from: 'status = "cancelled"', when: 'status != "cancelled"' }),
+	* ])
+	* ```
 	*/
 	events(define) {
 		return this.next({ events: define(eventHelpers(), this.refs()) });
@@ -69,9 +98,32 @@ var ResourceBuilder = class ResourceBuilder {
 	eventMatches() {
 		return eventMatches(this.toModel(), this.state.events ?? []);
 	}
+	/**
+	* A rule over the whole record, run after the field checks on every create and update. Its issues answer `400` with
+	* the field named. Each call adds a rule.
+	*
+	* @example
+	* ```ts
+	* .validate((repair) => (repair.status === 'collected' && !repair.paid ? [{ field: 'paid', message: 'A bike leaves the shop paid' }] : undefined))
+	* ```
+	*/
 	validate(validator) {
 		return new ResourceBuilder(this.state, [...this.validators, validator], this.accessRules);
 	}
+	/**
+	* Rules per operation (`list`, `read`, `create`, `update`, `delete`). A rule returns `true`, `false`, or a filter that
+	* limits the rows. An operation without a rule needs its capability when the app has roles. See
+	* [Access](website/src/content/docs/reference/access.mdx).
+	*
+	* @example
+	* ```ts
+	* .access({
+	*   read: roles.can('work_orders.read'),
+	*   update: roles.can('work_orders.update').and((_ctx, record) => (record as { status: string }).status !== 'done'),
+	*   delete: roles.is('admin'),
+	* })
+	* ```
+	*/
 	access(rules) {
 		return new ResourceBuilder(this.state, this.validators, {
 			...this.accessRules,
@@ -82,13 +134,16 @@ var ResourceBuilder = class ResourceBuilder {
 	fieldAccess() {
 		return Object.fromEntries(Object.entries(this.state.fields ?? {}).flatMap(([key, field]) => field?.meta.access ? [[key, field.meta.access]] : []));
 	}
+	/** The resource as the server and the app read it. Throws when the table, fields or key are missing, or a field option conflicts with another. */
 	toModel() {
 		return buildResourceModel(this.state);
 	}
+	/** The Zod schema of a whole record, from its fields' schemas. */
 	recordSchema() {
 		const shape = Object.fromEntries(Object.entries(this.state.fields ?? {}).flatMap(([key, field]) => field ? [[key, field.schema]] : []));
 		return z.object(shape);
 	}
+	/** The columns of the fields given as `null`, which the resource ignores on purpose. */
 	ignoredColumns() {
 		return ignoredColumns(this.state.fields);
 	}
@@ -105,6 +160,24 @@ var ResourceBuilder = class ResourceBuilder {
 		}, this.validators, this.accessRules);
 	}
 };
+/**
+* A resource: one table of an existing database, its columns as fields, its key and the rules around it. `name` is its
+* address (`/api/v1/<name>`) and how other config refers to it. See
+* [Data config](website/src/content/docs/reference/data-config.mdx).
+*
+* @example
+* ```ts
+* export const customers = resource('customers')
+*   .table('shop.customers')
+*   .fields({
+*     id: f.integer().readOnly().filterable().sortable().dbDefault(),
+*     name: f.text().min(2).filterable().sortable(),
+*     email: f.text().optional().filterable(),
+*   })
+*   .primaryKey((r) => r.id)
+*   .search((r) => [r.name, r.email])
+* ```
+*/
 const resource = (name) => new ResourceBuilder({ name });
 //#endregion
 export { ResourceBuilder, resource };

package/dist/user-menu.d.ts

@@ -18,8 +18,12 @@ declare const items: {
 };
 /** What the server needs from a `userMenu(...)` export of the config module. */
 export type UserMenuSource = {
+  /** The menu's model, a copy each time. */
   toUserMenuModel(): UserMenuModel;
 };
-/** The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out". */
+/**
+ * The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out": `m.resource`,
+ * `m.page` and `m.link`. Export it from the config module. See [User menu](website/src/content/docs/reference/user-menu.md).
+ */
 export declare const userMenu: (build: (m: typeof items) => UserMenuItemModel[]) => UserMenuSource;
 //#endregion

package/dist/user-menu.js

@@ -24,7 +24,10 @@ const items = {
 		};
 	}
 };
-/** The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out". */
+/**
+* The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out": `m.resource`,
+* `m.page` and `m.link`. Export it from the config module. See [User menu](website/src/content/docs/reference/user-menu.md).
+*/
 const userMenu = (build) => {
 	const model = { items: build(items) };
 	return { toUserMenuModel: () => structuredClone(model) };

package/dist/view-actions.d.ts

@@ -1,5 +1,6 @@
 import { ActionModel, AppAddress } from "./model.js";
 //#region src/view-actions.d.ts
+/** @inline */
 type ActionOptions = {
   label: string;
   icon?: string;

package/dist/view-displays.d.ts

@@ -3,11 +3,14 @@ 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) & {
+  /** The name it is registered under. */
   readonly blockName: string;
+  /** Whether it is the project's or a plugin's, rather than a built-in block. */
   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]; };
+/** @inline */
 type Naming = {
   name?: string;
   label?: string;

package/dist/view-field.d.ts

@@ -1,15 +1,28 @@
 import { BadgeShape, FieldFormat, FieldViewModel, JsonValue } 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> {
+  /** The field's name. */
   readonly name: N;
+  /** The hints given so far. */
   readonly props: FieldViewModel;
-  constructor(name: N, props?: FieldViewModel);
+  /** @internal */
+  constructor(
+  /** The field's name. */
+  name: N,
+  /** The hints given so far. */
+  props?: FieldViewModel);
+  /** What the field is called, instead of its name in words. */
   label(label: string): FieldView<N, V>;
+  /** A line under the field on the record page and in forms. */
   help(help: string): FieldView<N, V>;
+  /** How the value shows: `badge` for statuses, `code` in monospace, `percent` with a % sign. */
   format(format: FieldFormat): FieldView<N, V>;
+  /** Text before a number wherever it is shown, such as a currency: `.prefix('€')`. */
   prefix(prefix: string): FieldView<N, V>;
   /** Text after a number wherever it is shown, such as a unit: `.suffix(' m²')`. */
   suffix(suffix: string): FieldView<N, V>;
+  /** How many decimals a number shows wherever it is shown. */
   decimals(decimals: number): FieldView<N, V>;
   /** Labels for an enum's values, such as `{ co_signer: 'Co-signer' }`; values left out read as themselves in words. */
   valueLabels(labels: { readonly [P in Extract<V, string>]?: string; }): FieldView<N, V>;

package/dist/view-field.js

@@ -1,21 +1,27 @@
 //#region src/view-field.ts
 const hexColor = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** How a view shows one field, as `.fields((r) => ...)` hands it out: each hint returns a new field view. */
 var FieldView = class FieldView {
 	name;
 	props;
+	/** @internal */
 	constructor(name, props = {}) {
 		this.name = name;
 		this.props = props;
 	}
+	/** What the field is called, instead of its name in words. */
 	label(label) {
 		return this.with({ label });
 	}
+	/** A line under the field on the record page and in forms. */
 	help(help) {
 		return this.with({ help });
 	}
+	/** How the value shows: `badge` for statuses, `code` in monospace, `percent` with a % sign. */
 	format(format) {
 		return this.with({ format });
 	}
+	/** Text before a number wherever it is shown, such as a currency: `.prefix('€')`. */
 	prefix(prefix) {
 		return this.with({ prefix });
 	}
@@ -23,6 +29,7 @@ var FieldView = class FieldView {
 	suffix(suffix) {
 		return this.with({ suffix });
 	}
+	/** How many decimals a number shows wherever it is shown. */
 	decimals(decimals) {
 		return this.with({ decimals });
 	}

package/dist/view-widgets.d.ts

@@ -2,15 +2,22 @@ import { DatePreset, FilterWidgetModel } from "./model.js";
 import { Ref } from "./refs.js";
 //#region src/view-widgets.d.ts
 export declare const widgets: {
+  /** A slider between the field's lowest and highest value; `histogram` draws the values' histogram behind it. */
   range: (ref: Ref, o?: {
     histogram?: boolean;
   }) => FilterWidgetModel;
+  /**
+   * A menu of the field's values with counts; `search` adds a search box for long lists. On a relation it searches the
+   * referenced records as you type, on a number field it is a range slider.
+   */
   facets: (ref: Ref, o?: {
     search?: boolean;
   }) => FilterWidgetModel;
+  /** A date range with buttons for the `presets`, such as `today` and `30d`. */
   dateRange: (ref: Ref, o?: {
     presets?: DatePreset[];
   }) => FilterWidgetModel;
+  /** A switch for a boolean field. */
   toggle: (ref: Ref) => FilterWidgetModel;
   /**
    * A menu of boolean fields under one `label`, such as "for sale" and "for rent": a record shows when any chosen field

package/dist/view-widgets.js

@@ -1,20 +1,27 @@
 //#region src/view-widgets.ts
 const widgets = {
+	/** A slider between the field's lowest and highest value; `histogram` draws the values' histogram behind it. */
 	range: (ref, o = {}) => ({
 		kind: "range",
 		field: ref.name,
 		histogram: o.histogram ?? false
 	}),
+	/**
+	* A menu of the field's values with counts; `search` adds a search box for long lists. On a relation it searches the
+	* referenced records as you type, on a number field it is a range slider.
+	*/
 	facets: (ref, o = {}) => ({
 		kind: "facets",
 		field: ref.name,
 		search: o.search ?? false
 	}),
+	/** A date range with buttons for the `presets`, such as `today` and `30d`. */
 	dateRange: (ref, o = {}) => ({
 		kind: "dateRange",
 		field: ref.name,
 		presets: o.presets ?? []
 	}),
+	/** A switch for a boolean field. */
 	toggle: (ref) => ({
 		kind: "toggle",
 		field: ref.name

package/dist/view.d.ts

@@ -8,7 +8,11 @@ import { widgets } from "./view-widgets.js";
 type FieldsOf<R extends {
   readonly $fields: unknown;
 }> = R['$fields'];
-/** `nav(...)` with `recent.status` limited to the resource's fields. */
+/**
+ * `nav(...)` with `recent.status` limited to the resource's fields.
+ *
+ * @inline
+ */
 type NavInput<R extends {
   readonly $fields: unknown;
 }> = Omit<NavModel, 'recent'> & {
@@ -16,18 +20,31 @@ type NavInput<R extends {
     status: keyof FieldsOf<R> & string;
   };
 };
-type FieldViews<R extends {
+/** The `r` of `.fields((r) => ...)`: a field view per field of the resource, to give hints such as `.label()`. */
+export type FieldViews<R extends {
+  /** The resource's fields, as `resource(...)` declares them. */
   readonly $fields: unknown;
 }> = { readonly [K in keyof FieldRefs<FieldsOf<R>> & string]: FieldView<K, NonNullable<FieldRefs<FieldsOf<R>>[K]['$value']>>; };
+/**
+ * A view of a resource, as `view(...)` starts it: how the admin shows it. Each method returns a new view, so one view
+ * can build on another. See [UI config](website/src/content/docs/reference/ui-config.mdx).
+ */
 export declare class ViewBuilder<R extends {
+  /** The resource's fields, as `resource(...)` declares them. */
   readonly $fields: unknown;
 }> {
+  /** @internal */
   readonly state: ViewModel;
-  constructor(state: ViewModel);
+  /** @internal */
+  constructor(
+  /** @internal */
+  state: ViewModel);
+  /** What a record and the records are called, such as "New repair" and "Repairs"; the resource name in words by default. */
   names(names: {
     singular: string;
     plural: string;
   }): ViewBuilder<R>;
+  /** An icon name carried in `/meta`, for apps that draw their own shell; the admin picks sidebar icons by resource name. */
   icon(icon: string): ViewBuilder<R>;
   /** Shows this view only to users with one of these roles; a view without roles is the default. */
   forRoles(roles: string[]): ViewBuilder<R>;
@@ -41,9 +58,11 @@ export declare class ViewBuilder<R extends {
     title?: Ref | Ref[];
     subtitle?: Ref;
   }): ViewBuilder<R>;
-  /** Where the resource sits in the sidebar; `recent` lists a few of its records under the entry (see https://docs.protobase.net/reference/sidebar/). */
+  /** Where the resource sits in the sidebar; `recent` lists a few of its records under the entry (see [Sidebar](website/src/content/docs/reference/sidebar.md#recent-records)). */
   nav(nav: NavInput<R>): ViewBuilder<R>;
+  /** A line under the list's title. */
   help(help: string): ViewBuilder<R>;
+  /** 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
@@ -56,21 +75,50 @@ export declare class ViewBuilder<R extends {
     displays?: ListDisplayModel[];
     default?: string;
   }): ViewBuilder<R>;
+  /**
+   * The filter widgets above the list, in order, each on a `.filterable()` field: `w.facets`, `w.dateRange`, `w.range`,
+   * `w.toggle` and `w.flags`. Together they write the list's `?filter=`.
+   */
   filters(build: (r: FieldRefs<FieldsOf<R>>, w: typeof widgets) => FilterWidgetModel[]): ViewBuilder<R>;
+  /**
+   * The record page, as items of `l` in order: sections, sidebar cards, related records, maps and custom components.
+   * 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>;
+  /** Where the record page shows that it saved: a toast (the default) or the Save button. */
   saveFeedback(saveFeedback: SaveFeedback): ViewBuilder<R>;
+  /**
+   * The named actions of the record page's action rail, which composed pages can put on buttons too: `a.update`,
+   * `a.remove` and `a.link` need no code, `a.action` runs a handler the app registers.
+   */
   actions(build: (a: typeof actions) => ActionModel[]): ViewBuilder<R>;
   /** 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;
 }
+/**
+ * Starts the view of a resource: how the admin shows it. Pass the resource's type, so every field reference (`r.status`)
+ * is checked against it. See [UI config](website/src/content/docs/reference/ui-config.mdx).
+ *
+ * @example
+ * ```ts
+ * import { view } from '@protobase/schema'
+ * import type { repairs } from './data'
+ *
+ * export const repairsView = view<typeof repairs>('repairs')
+ *   .names({ singular: 'Repair', plural: 'Repairs' })
+ *   .list((r) => ({ columns: [r.number, r.status, r.booked_on], sort: [[r.booked_on, 'desc']] }))
+ * ```
+ */
 export declare const view: <R extends {
+  /** The resource's fields, as `resource(...)` declares them. */
   readonly $fields: unknown;
 }>(resource: string) => ViewBuilder<R>;
 //#endregion