@protobase/schema 0.21.1 → 0.21.3

package/dist/access/restrict.d.ts

@@ -4,7 +4,7 @@ import { ResolvedAccess } from "./resolve.js";
 /**
  * The resource as one user may see it: only readable fields remain, and a field is `readOnly`
  * unless it is writable on create or update. `search` (and `searchMatch`) shrinks to readable fields, and `tenant`,
- * `softDelete` and `owner` are dropped when their field is hidden. The event catalogue, whose conditions may use any
+ * `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is. The event catalogue, whose conditions may use any
  * field, is dropped. Key columns always stay,
  * because records are addressed by them.
  *

package/dist/access/restrict.js

@@ -2,7 +2,7 @@
 /**
 * The resource as one user may see it: only readable fields remain, and a field is `readOnly`
 * unless it is writable on create or update. `search` (and `searchMatch`) shrinks to readable fields, and `tenant`,
-* `softDelete` and `owner` are dropped when their field is hidden. The event catalogue, whose conditions may use any
+* `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is. The event catalogue, whose conditions may use any
 * field, is dropped. Key columns always stay,
 * because records are addressed by them.
 *
@@ -17,10 +17,11 @@ const restrictModel = (model, access) => {
 	const keep = (name) => name !== void 0 && visible.has(name) ? name : void 0;
 	const search = model.search?.filter((name) => visible.has(name));
 	const searchMatch = model.searchMatch && Object.entries(model.searchMatch).filter(([name]) => visible.has(name));
-	const { search: _search, searchMatch: _searchMatch, tenant: _tenant, softDelete: _softDelete, owner: _owner, events: _events, ...rest } = model;
+	const { search: _search, searchMatch: _searchMatch, tenant: _tenant, softDelete: _softDelete, owner: _owner, position: _position, events: _events, ...rest } = model;
 	const tenant = keep(model.tenant);
 	const softDelete = keep(model.softDelete);
 	const owner = keep(model.owner);
+	const position = model.position && keep(model.position.field) && (model.position.within === void 0 || keep(model.position.within)) ? model.position : void 0;
 	return {
 		...rest,
 		fields: Object.fromEntries(Object.entries(model.fields).filter(([name]) => visible.has(name)).map(([name, field]) => [name, {
@@ -31,7 +32,8 @@ const restrictModel = (model, access) => {
 		...searchMatch?.length && { searchMatch: Object.fromEntries(searchMatch) },
 		...tenant && { tenant },
 		...softDelete && { softDelete },
-		...owner && { owner }
+		...owner && { owner },
+		...position && { position: { ...position } }
 	};
 };
 //#endregion

package/dist/model.d.ts

@@ -94,6 +94,13 @@ export type ResourceModel = {
   searchMatch?: Record<string, SearchMatch>;
   /** The field holding the owning user's id; `.own` capability scopes filter on it. */
   owner?: string;
+  /** The integer field holding the records' order by hand (`.position()`), 1 the first. */
+  position?: {
+    /** The integer field, 1 the first record. */
+    field: string;
+    /** The relation whose records each have an order of their own, as an invoice's items do; one order for all records when omitted. */
+    within?: 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()`). */

package/dist/resource-model.d.ts

@@ -12,6 +12,10 @@ export type ResourceState = {
   search?: string[];
   searchMatch?: Record<string, SearchMatch>;
   owner?: string;
+  position?: {
+    field: string;
+    within?: string;
+  };
   events?: EventSpec[];
   history?: boolean;
 };

package/dist/resource-model.js

@@ -58,7 +58,8 @@ const assembleModel = (state) => {
 		...state.search && { search: [...state.search] },
 		...state.searchMatch && Object.keys(state.searchMatch).length > 0 && { searchMatch: { ...state.searchMatch } },
 		...state.owner && { owner: state.owner },
-		...state.history && { history: true }
+		...state.history && { history: true },
+		...state.position && { position: { ...state.position } }
 	};
 };
 const sensitiveProblems = (model) => Object.values(model.fields).filter((field) => field.sensitive).flatMap((field) => [
@@ -101,12 +102,29 @@ const placeholderProblems = (model, field) => {
 	const placeholder = Object.hasOwn(model.fields, target) ? model.fields[target] : void 0;
 	return placeholder && !placeholder.file && placeholder.type !== "text" ? [`has "${target}" as its placeholder, which must be a text field`] : [];
 };
+const positionProblems = (model) => {
+	if (!model.position) return [];
+	const { field: name, within } = model.position;
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	if (!field) return [`position "${name}" is not a field`];
+	const parent = within !== void 0 && Object.hasOwn(model.fields, within) ? model.fields[within] : void 0;
+	if (within !== void 0 && !parent) return [`position "${name}" is within "${within}", which is not a field`];
+	return [
+		...field.type !== "integer" && field.type !== "bigint" ? [`position "${name}" is ${field.type}, not an integer`] : [],
+		...field.sortable ? [] : [`position "${name}" is not sortable, and the list in its order sorts by it`],
+		...model.primaryKey.includes(name) ? [`position "${name}" is part of the key, which a move would change`] : [],
+		...within === name ? [`position "${name}" cannot be within itself`] : [],
+		...parent && parent.type !== "relation" ? [`position "${name}" is within "${within}", which is ${parent.type}, not a relation`] : [],
+		...parent && !parent.filterable ? [`position "${name}" is within "${within}", which is not filterable, and each parent's records are found by it`] : []
+	];
+};
 const buildResourceModel = (state) => {
 	const model = assembleModel(state);
 	const events = state.events && buildEventModels(model, state.events);
 	const problems = [
 		...sensitiveProblems(model),
 		...fileProblems(model),
+		...positionProblems(model),
 		...events?.problems ?? []
 	];
 	if (problems.length > 0) throw new Error(`Resource "${model.name}": ${problems.join("; ")}`);

package/dist/resource.d.ts

@@ -68,6 +68,20 @@ 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>;
+  /**
+   * The integer field holding the records' order, 1 the first, which a list's **Sort** button changes by dragging the
+   * records; a move renumbers them 1, 2, 3, ... in one batch `reorder`. With `within`, a relation, each parent's records
+   * have an order of their own, as an invoice's items do, sorted in the parent's related section. The field must be
+   * sortable and `within` filterable. See [Sorting by hand](website/src/content/docs/reference/ui-config.mdx#sorting-by-hand).
+   *
+   * @example
+   * ```ts
+   * .position((r) => r.position, { within: (r) => r.invoice_id })
+   * ```
+   */
+  position(pick: (r: FieldRefs<F>) => Ref, o?: {
+    within?: (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. See
    * [Declaring events](website/src/content/docs/reference/events.mdx#declaring-events).

package/dist/resource.js

@@ -78,6 +78,24 @@ var ResourceBuilder = class ResourceBuilder {
 		return this.next({ owner: pick(this.refs()).name });
 	}
 	/**
+	* The integer field holding the records' order, 1 the first, which a list's **Sort** button changes by dragging the
+	* records; a move renumbers them 1, 2, 3, ... in one batch `reorder`. With `within`, a relation, each parent's records
+	* have an order of their own, as an invoice's items do, sorted in the parent's related section. The field must be
+	* sortable and `within` filterable. See [Sorting by hand](website/src/content/docs/reference/ui-config.mdx#sorting-by-hand).
+	*
+	* @example
+	* ```ts
+	* .position((r) => r.position, { within: (r) => r.invoice_id })
+	* ```
+	*/
+	position(pick, o = {}) {
+		const within = o.within?.(this.refs()).name;
+		return this.next({ position: {
+			field: pick(this.refs()).name,
+			...within !== void 0 && { within }
+		} });
+	}
+	/**
 	* 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).
 	*

package/package.json

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