@protobase/schema 0.55.2 → 0.55.4

package/dist/model.d.ts

@@ -149,6 +149,11 @@ export type ResourceModel = {
   comments?: true;
   /** Whether open pages refresh as soon as its records change (`.live()`). */
   live?: true;
+  /**
+   * The fields of a unique key whose conflict on create answers the record already holding those values, to a caller
+   * who may read it (`.openExisting()`).
+   */
+  openExisting?: string[];
 };
 /** What happened to a record: `delete` and `undelete` include setting and clearing a soft delete field. */
 export type EventOperation = 'create' | 'update' | 'delete' | 'undelete';
@@ -1118,6 +1123,11 @@ export type NavRecentModel = {
   orderBy?: string;
   /** How many records to show, 1 to 20; 3 when omitted. */
   limit?: number;
+  /**
+   * Marks each record for the person reading, such as bold with a count of unread messages: the name of a hook in the
+   * project UI's `marks`, which the sidebar calls in the browser. Presentation only: it is no field, filter or sort key.
+   */
+  marks?: string;
 };
 /** Where a resource sits in the sidebar (`.nav(...)`); see [Sidebar](website/src/content/docs/reference/sidebar.md). */
 export type NavModel = {
@@ -1135,6 +1145,14 @@ export type NavModel = {
    * filter and the recent records' filter as `tenantField = "<tenant>"`, which the person can clear or change.
    */
   tenant?: 'current';
+  /**
+   * A link under the entry to the resource's create form (its create page when the view has one), for whoever may
+   * create; `true` reads "New <singular>", `{ label }` its own text.
+   */
+  create?: true | {
+    /** The link's text, in place of "New <singular>". */
+    label: string;
+  };
 };
 /** An entry in the menu under the signed-in user, at the bottom of the sidebar. */
 export type UserMenuItemModel = {

package/dist/nav-recent.js

@@ -32,7 +32,8 @@ const navRecentErrors = (recent, model) => [
 	...Object.entries(recent.tones ?? {}).filter(([, tone]) => !statusTones.includes(tone)).map(([value, tone]) => `tone "${tone}" for "${value}" is not one of ${statusTones.join(", ")}`),
 	...recent.limit === void 0 || Number.isInteger(recent.limit) && recent.limit >= 1 && recent.limit <= maxLimit ? [] : [`limit must be a whole number from 1 to ${maxLimit}`],
 	...recent.filter === void 0 ? [] : filterErrors(model, recent.filter).map((error) => `filter: ${error.message}`),
-	...recent.orderBy === void 0 ? [] : orderByErrors(model, recent.orderBy).map((error) => `orderBy: ${error.message}`)
+	...recent.orderBy === void 0 ? [] : orderByErrors(model, recent.orderBy).map((error) => `orderBy: ${error.message}`),
+	...recent.marks === void 0 || typeof recent.marks === "string" && recent.marks !== "" ? [] : ["marks needs the name of a hook in the project UI's marks"]
 ];
 //#endregion
 export { defaultRecentLimit, navRecentErrors, statusTones };

package/dist/open-existing-problems.js

@@ -0,0 +1,16 @@
+//#region src/open-existing-problems.ts
+const openExistingProblems = (model) => {
+	const names = model.openExisting;
+	if (!names) return [];
+	if (names.length === 0) return ["openExisting names no field"];
+	return names.flatMap((name, index) => {
+		const field = model.fields[name];
+		return [
+			...field.encrypted ? ["is encrypted"] : [],
+			...field.file ? ["is a file field"] : [],
+			...names.indexOf(name) !== index ? ["is given twice"] : []
+		].map((problem) => `openExisting field "${name}" ${problem}`);
+	});
+};
+//#endregion
+export { openExistingProblems };

package/dist/resource-model.d.ts

@@ -24,6 +24,7 @@ export type ResourceState = {
   history?: boolean;
   comments?: boolean;
   live?: boolean;
+  openExisting?: string[];
 };
 export declare const parseTable: (table: string) => {
   name: string;

package/dist/resource-model.js

@@ -1,6 +1,7 @@
 import { promptFields } from "./ai-prompt.js";
 import { buildEventModels } from "./events/event-models.js";
 import { computedProblems } from "./computed/computed-problems.js";
+import { openExistingProblems } from "./open-existing-problems.js";
 import { snakeCase } from "./naming.js";
 //#region src/resource-model.ts
 const parseTable = (table) => {
@@ -75,7 +76,8 @@ const assembleModel = (state) => {
 		...state.comments && { comments: true },
 		...state.live && { live: true },
 		...state.position && { position: { ...state.position } },
-		...state.parents && { parents: state.parents.map((parent) => ({ ...parent })) }
+		...state.parents && { parents: state.parents.map((parent) => ({ ...parent })) },
+		...state.openExisting && { openExisting: [...state.openExisting] }
 	};
 };
 const sensitiveProblems = (model) => Object.values(model.fields).filter((field) => field.sensitive).flatMap((field) => [
@@ -168,6 +170,7 @@ const buildResourceModel = (state) => {
 		...positionProblems(model),
 		...parentProblems(model),
 		...aiProblems(model),
+		...openExistingProblems(model),
 		...computedProblems(model),
 		...events?.problems ?? []
 	];

package/dist/resource.d.ts

@@ -82,6 +82,18 @@ export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
   search(pick: (r: SearchRefs<F>) => SearchRef[]): ResourceBuilder<F, K>;
   /** The field holding the owning user's id, which `.own` capability scopes filter on. */
   owner(pick: (r: FieldRefs<F>) => Ref): ResourceBuilder<F, K>;
+  /**
+   * A unique key of the table, as its fields, whose conflict on create opens the record already holding those values:
+   * the API's 409 names that record's key (`existing.key`) to a caller who may read it, and the create form opens it.
+   * The fields must be exactly the columns of a unique index or constraint, such as one over a generated column. See
+   * [Opening an existing record](website/src/content/docs/reference/data-config.mdx#opening-an-existing-record).
+   *
+   * @example
+   * ```ts
+   * .openExisting((r) => [r.organization_id, r.member_key])
+   * ```
+   */
+  openExisting(pick: (r: FieldRefs<F>) => Ref[]): ResourceBuilder<F, K>;
   /**
    * The field holding the id of the user who created the record, such as a chat message's sender: every create sets it
    * to the signed-in user's id, and no request may write it, so it is never the client's word. A create by no user

package/dist/resource.js

@@ -84,6 +84,20 @@ var ResourceBuilder = class ResourceBuilder {
 		return this.next({ owner: pick(this.refs()).name });
 	}
 	/**
+	* A unique key of the table, as its fields, whose conflict on create opens the record already holding those values:
+	* the API's 409 names that record's key (`existing.key`) to a caller who may read it, and the create form opens it.
+	* The fields must be exactly the columns of a unique index or constraint, such as one over a generated column. See
+	* [Opening an existing record](website/src/content/docs/reference/data-config.mdx#opening-an-existing-record).
+	*
+	* @example
+	* ```ts
+	* .openExisting((r) => [r.organization_id, r.member_key])
+	* ```
+	*/
+	openExisting(pick) {
+		return this.next({ openExisting: pick(this.refs()).map((ref) => ref.name) });
+	}
+	/**
 	* The field holding the id of the user who created the record, such as a chat message's sender: every create sets it
 	* to the signed-in user's id, and no request may write it, so it is never the client's word. A create by no user
 	* leaves it empty.

package/dist/view.d.ts

@@ -74,7 +74,8 @@ export declare class ViewBuilder<R extends {
   /**
    * 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)), and `tenant: 'current'` opens it on the
-   * caller's own tenant (see [The current organization](website/src/content/docs/reference/sidebar.md#the-current-organization)).
+   * caller's own tenant (see [The current organization](website/src/content/docs/reference/sidebar.md#the-current-organization)),
+   * and `create` links to the create form under it (see [Create link](website/src/content/docs/reference/sidebar.md#create-link)).
    */
   nav(nav: NavInput<R>): ViewBuilder<R>;
   /** A line under the list's title. */

package/dist/view.js

@@ -86,7 +86,8 @@ var ViewBuilder = class ViewBuilder {
 	/**
 	* 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)), and `tenant: 'current'` opens it on the
-	* caller's own tenant (see [The current organization](website/src/content/docs/reference/sidebar.md#the-current-organization)).
+	* caller's own tenant (see [The current organization](website/src/content/docs/reference/sidebar.md#the-current-organization)),
+	* and `create` links to the create form under it (see [Create link](website/src/content/docs/reference/sidebar.md#create-link)).
 	*/
 	nav(nav) {
 		return this.next({ nav });
@@ -354,6 +355,7 @@ var ViewBuilder = class ViewBuilder {
 		if (nav?.tenant === "current" && !list) throw new Error(`View "${this.state.resource}": nav.tenant narrows the opening filter of the list, so the view needs .list(...)`);
 		const tenantField = resource?.tenant === void 0 ? void 0 : resource.fields[resource.tenant];
 		if (resource && nav?.tenant === "current" && !tenantField?.filterable) throw new Error(`View "${this.state.resource}": nav.tenant opens the list on the current tenant, so the resource needs .tenant() on a .filterable() field`);
+		if (typeof nav?.create === "object" && nav.create.label.trim() === "") throw new Error(`View "${this.state.resource}": nav.create needs a label, or true for "New <singular>"`);
 		const recentErrors = resource && nav?.recent ? navRecentErrors(nav.recent, resource) : [];
 		if (recentErrors.length > 0) throw new Error(`View "${this.state.resource}": nav.recent ${recentErrors.join("; ")}`);
 		if (this.state.lists?.length && (listOf !== void 0 || this.state.searchesOf)) throw new Error(`View "${this.state.resource}": named lists cannot go with listOf or searchesOf, which replace the list page`);

package/package.json

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