@protobase/schema 0.0.0-stage → 0.1.0

package/dist/search-match.d.ts

@@ -0,0 +1,29 @@
+import { ResourceModel, SearchMatch } from "./model.js";
+//#region src/search-match.d.ts
+/**
+ * One part of a search text. Every word must match a search field; `whole` is the entire text, tried only against
+ * `digitsEnd` fields when it holds several words, so a phone number typed with spaces ("+31 6 4706") still finds it.
+ */
+export type SearchTerm = {
+  text: string;
+  digits: string;
+  whole: boolean;
+};
+/** The text's words, and the whole text first when it is a phone number of several words. */
+export declare const searchTerms: (text: string) => SearchTerm[];
+/**
+ * Whether one field value matches a term. A plain search field contains the word, ignoring case; a `digitsEnd` field's
+ * digits (spaces, `+` and dashes ignored) end with the term's digits. Null never matches.
+ */
+export declare const termMatches: (value: unknown, term: SearchTerm, match: SearchMatch | undefined) => boolean;
+/**
+ * The server's `search("text")` in memory: every word matches a search field, or the whole text, as a phone number,
+ * ends a `digitsEnd` field. Text without words matches nothing. The SQL in `compileSearch` follows the same rules.
+ */
+export declare const matchesSearch: (model: ResourceModel, row: Record<string, unknown>, text: string) => boolean;
+/**
+ * The search field that explains why the record matched when the `shown` fields do not: the first search field matching
+ * the first term that matches no shown field. Undefined when the shown fields explain every term the record matched.
+ */
+export declare const matchedSearchField: (model: ResourceModel, row: Record<string, unknown>, text: string, shown: string[]) => string | undefined;
+//#endregion

package/dist/search-match.js

@@ -0,0 +1,50 @@
+//#region src/search-match.ts
+const phoneLike = /^[\d\s+\-().\/]+$/;
+const digitsOf = (text) => phoneLike.test(text) ? text.replace(/\D/g, "") : "";
+/** The text's words, and the whole text first when it is a phone number of several words. */
+const searchTerms = (text) => {
+	const words = text.split(/\s+/).filter(Boolean).map((word) => ({
+		text: word,
+		digits: digitsOf(word),
+		whole: false
+	}));
+	const digits = words.length > 1 ? digitsOf(text.trim()) : "";
+	return digits ? [{
+		text: text.trim(),
+		digits,
+		whole: true
+	}, ...words] : words;
+};
+/**
+* Whether one field value matches a term. A plain search field contains the word, ignoring case; a `digitsEnd` field's
+* digits (spaces, `+` and dashes ignored) end with the term's digits. Null never matches.
+*/
+const termMatches = (value, term, match) => {
+	if (value === null || value === void 0) return false;
+	if (match === "digitsEnd") return term.digits !== "" && String(value).replace(/\D/g, "").endsWith(term.digits);
+	return !term.whole && String(value).toLowerCase().includes(term.text.toLowerCase());
+};
+const matchingFields = (model, row, term) => (model.search ?? []).filter((name) => termMatches(row[name], term, model.searchMatch?.[name]));
+/**
+* The server's `search("text")` in memory: every word matches a search field, or the whole text, as a phone number,
+* ends a `digitsEnd` field. Text without words matches nothing. The SQL in `compileSearch` follows the same rules.
+*/
+const matchesSearch = (model, row, text) => {
+	const terms = searchTerms(text);
+	const words = terms.filter((term) => !term.whole);
+	const whole = terms.find((term) => term.whole);
+	if (whole && matchingFields(model, row, whole).length > 0) return true;
+	return words.length > 0 && words.every((term) => matchingFields(model, row, term).length > 0);
+};
+/**
+* The search field that explains why the record matched when the `shown` fields do not: the first search field matching
+* the first term that matches no shown field. Undefined when the shown fields explain every term the record matched.
+*/
+const matchedSearchField = (model, row, text, shown) => {
+	for (const term of searchTerms(text)) {
+		const fields = matchingFields(model, row, term);
+		if (fields.length > 0 && !fields.some((name) => shown.includes(name))) return fields[0];
+	}
+};
+//#endregion
+export { matchedSearchField, matchesSearch, searchTerms, termMatches };

package/dist/user-menu.d.ts

@@ -0,0 +1,25 @@
+import { UserMenuItemModel, UserMenuModel } from "./model.js";
+//#region src/user-menu.d.ts
+declare const items: {
+  /** Opens the resource's list. A resource in the user menu is left out of the sidebar. */
+  resource: (resource: string, options?: {
+    label?: string;
+    icon?: string;
+  }) => UserMenuItemModel;
+  /** Opens a composed page (`page()` from @protobase/layout). A page in the user menu is left out of the sidebar. */
+  page: (page: string, options?: {
+    label?: string;
+    icon?: string;
+  }) => UserMenuItemModel;
+  /** An address outside the admin, opened in a new tab: `https:`, `http:` or `mailto:`. */
+  link: (label: string, href: string, options?: {
+    icon?: string;
+  }) => UserMenuItemModel;
+};
+/** What the server needs from a `userMenu(...)` export of the config module. */
+export type UserMenuSource = {
+  toUserMenuModel(): UserMenuModel;
+};
+/** The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out". */
+export declare const userMenu: (build: (m: typeof items) => UserMenuItemModel[]) => UserMenuSource;
+//#endregion

package/dist/user-menu.js

@@ -0,0 +1,32 @@
+//#region src/user-menu.ts
+const items = {
+	/** Opens the resource's list. A resource in the user menu is left out of the sidebar. */
+	resource: (resource, options = {}) => ({
+		kind: "resource",
+		resource,
+		...options
+	}),
+	/** Opens a composed page (`page()` from @protobase/layout). A page in the user menu is left out of the sidebar. */
+	page: (page, options = {}) => ({
+		kind: "page",
+		page,
+		...options
+	}),
+	/** An address outside the admin, opened in a new tab: `https:`, `http:` or `mailto:`. */
+	link: (label, href, options = {}) => {
+		if (!/^(https?:\/\/|mailto:)/i.test(href)) throw new Error(`User menu link "${label}": href must start with https://, http:// or mailto:`);
+		return {
+			kind: "link",
+			label,
+			href,
+			...options
+		};
+	}
+};
+/** The pages under the signed-in user, at the bottom of the sidebar, above the built-in "Sign out". */
+const userMenu = (build) => {
+	const model = { items: build(items) };
+	return { toUserMenuModel: () => structuredClone(model) };
+};
+//#endregion
+export { userMenu };

package/dist/view-actions.d.ts

@@ -0,0 +1,24 @@
+import { ActionModel } from "./model.js";
+//#region src/view-actions.d.ts
+type ActionOptions = {
+  label: string;
+  icon?: string;
+  confirm?: string;
+};
+export declare const actions: {
+  /** An action the app implements: it runs the handler registered under `name`. */
+  action: (name: string, o: ActionOptions & {
+    bulk?: boolean;
+  }) => ActionModel;
+  /** Sets fields of the record, as one update with its ETag, for example `{ status: 'paid' }`. */
+  update: (name: string, o: ActionOptions & {
+    set: Record<string, unknown>;
+  }) => ActionModel;
+  /** Deletes the record (soft delete when the resource has one). */
+  remove: (name: string, o: ActionOptions) => ActionModel;
+  /** Opens `href`: a path in the app or a URL; `{field}` is replaced by the record's value, such as `/orders/{orderId}`. */
+  link: (name: string, o: Omit<ActionOptions, "confirm"> & {
+    href: string;
+  }) => ActionModel;
+};
+//#endregion

package/dist/view-actions.js

@@ -0,0 +1,35 @@
+//#region src/view-actions.ts
+const named = (name, o) => ({
+	name,
+	label: o.label,
+	bulk: o.bulk ?? false,
+	...o.icon !== void 0 && { icon: o.icon },
+	...o.confirm !== void 0 && { confirm: o.confirm }
+});
+const actions = {
+	/** An action the app implements: it runs the handler registered under `name`. */
+	action: (name, o) => named(name, o),
+	/** Sets fields of the record, as one update with its ETag, for example `{ status: 'paid' }`. */
+	update: (name, o) => ({
+		...named(name, o),
+		run: {
+			kind: "update",
+			values: o.set
+		}
+	}),
+	/** Deletes the record (soft delete when the resource has one). */
+	remove: (name, o) => ({
+		...named(name, o),
+		run: { kind: "delete" }
+	}),
+	/** Opens `href`: a path in the app or a URL; `{field}` is replaced by the record's value, such as `/orders/{orderId}`. */
+	link: (name, o) => ({
+		...named(name, o),
+		run: {
+			kind: "link",
+			href: o.href
+		}
+	})
+};
+//#endregion
+export { actions };

package/dist/view-field.d.ts

@@ -0,0 +1,16 @@
+import { FieldFormat, FieldViewModel } from "./model.js";
+//#region src/view-field.d.ts
+export declare class FieldView<N extends string = string, V = unknown> {
+  readonly name: N;
+  readonly props: FieldViewModel;
+  constructor(name: N, props?: FieldViewModel);
+  label(label: string): FieldView<N, V>;
+  help(help: string): FieldView<N, V>;
+  format(format: FieldFormat): FieldView<N, V>;
+  prefix(prefix: string): FieldView<N, V>;
+  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>;
+  private with;
+}
+//#endregion

package/dist/view-field.js

@@ -0,0 +1,39 @@
+//#region src/view-field.ts
+var FieldView = class FieldView {
+	name;
+	props;
+	constructor(name, props = {}) {
+		this.name = name;
+		this.props = props;
+	}
+	label(label) {
+		return this.with({ label });
+	}
+	help(help) {
+		return this.with({ help });
+	}
+	format(format) {
+		return this.with({ format });
+	}
+	prefix(prefix) {
+		return this.with({ prefix });
+	}
+	decimals(decimals) {
+		return this.with({ decimals });
+	}
+	/** Labels for an enum's values, such as `{ co_signer: 'Co-signer' }`; values left out read as themselves in words. */
+	valueLabels(labels) {
+		return this.with({ valueLabels: {
+			...this.props.valueLabels,
+			...labels
+		} });
+	}
+	with(patch) {
+		return new FieldView(this.name, {
+			...this.props,
+			...patch
+		});
+	}
+};
+//#endregion
+export { FieldView };

package/dist/view-widgets.d.ts

@@ -0,0 +1,16 @@
+import { DatePreset, FilterWidgetModel } from "./model.js";
+import { Ref } from "./refs.js";
+//#region src/view-widgets.d.ts
+export declare const widgets: {
+  range: (ref: Ref, o?: {
+    histogram?: boolean;
+  }) => FilterWidgetModel;
+  facets: (ref: Ref, o?: {
+    search?: boolean;
+  }) => FilterWidgetModel;
+  dateRange: (ref: Ref, o?: {
+    presets?: DatePreset[];
+  }) => FilterWidgetModel;
+  toggle: (ref: Ref) => FilterWidgetModel;
+};
+//#endregion

package/dist/view-widgets.js

@@ -0,0 +1,24 @@
+//#region src/view-widgets.ts
+const widgets = {
+	range: (ref, o = {}) => ({
+		kind: "range",
+		field: ref.name,
+		histogram: o.histogram ?? false
+	}),
+	facets: (ref, o = {}) => ({
+		kind: "facets",
+		field: ref.name,
+		search: o.search ?? false
+	}),
+	dateRange: (ref, o = {}) => ({
+		kind: "dateRange",
+		field: ref.name,
+		presets: o.presets ?? []
+	}),
+	toggle: (ref) => ({
+		kind: "toggle",
+		field: ref.name
+	})
+};
+//#endregion
+export { widgets };

package/dist/view.d.ts

@@ -0,0 +1,69 @@
+import { ActionModel, ChartGranularity, ChartRange, FilterWidgetModel, LayoutItemModel, NavModel, NavRecentModel, ResourceModel, SaveFeedback, ViewModel } from "./model.js";
+import { FieldRefs, Ref } from "./refs.js";
+import { actions } from "./view-actions.js";
+import { FieldView } from "./view-field.js";
+import { widgets } from "./view-widgets.js";
+//#region src/view.d.ts
+type FieldsOf<R extends {
+  readonly $fields: unknown;
+}> = R['$fields'];
+/** `nav(...)` with `recent.status` limited to the resource's fields. */
+type NavInput<R extends {
+  readonly $fields: unknown;
+}> = Omit<NavModel, 'recent'> & {
+  recent?: Omit<NavRecentModel, 'status'> & {
+    status: keyof FieldsOf<R> & string;
+  };
+};
+type FieldViews<R extends {
+  readonly $fields: unknown;
+}> = { readonly [K in keyof FieldRefs<FieldsOf<R>> & string]: FieldView<K, NonNullable<FieldRefs<FieldsOf<R>>[K]['$value']>>; };
+export declare class ViewBuilder<R extends {
+  readonly $fields: unknown;
+}> {
+  readonly state: ViewModel;
+  constructor(state: ViewModel);
+  names(names: {
+    singular: string;
+    plural: string;
+  }): ViewBuilder<R>;
+  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>;
+  /** The field shown as this record's title. Throws when the field does not exist. */
+  title(pick: (r: FieldRefs<FieldsOf<R>>) => Ref): ViewBuilder<R>;
+  /**
+   * How a record shows in the global search: a bold `title` of one or more fields joined by spaces (default: `title`)
+   * and a `subtitle` field under it, replaced by the search field the text matched when that is neither.
+   */
+  searchResult(pick: (r: FieldRefs<FieldsOf<R>>) => {
+    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/). */
+  nav(nav: NavInput<R>): ViewBuilder<R>;
+  help(help: string): ViewBuilder<R>;
+  fields(build: (r: FieldViews<R>) => Record<string, FieldView>): ViewBuilder<R>;
+  list(build: (r: FieldRefs<FieldsOf<R>>) => {
+    columns: Ref[];
+    sort?: Array<[Ref, 'asc' | 'desc']>;
+    search?: Ref[];
+  }): ViewBuilder<R>;
+  filters(build: (r: FieldRefs<FieldsOf<R>>, w: typeof widgets) => FilterWidgetModel[]): ViewBuilder<R>;
+  layout(build: (r: FieldRefs<FieldsOf<R>>) => LayoutItemModel[]): ViewBuilder<R>;
+  chart(build: (r: FieldRefs<FieldsOf<R>>) => {
+    field: Ref;
+    range: ChartRange;
+    granularity: ChartGranularity;
+  }): ViewBuilder<R>;
+  saveFeedback(saveFeedback: SaveFeedback): ViewBuilder<R>;
+  actions(build: (a: typeof actions) => ActionModel[]): ViewBuilder<R>;
+  /** With the resource's model, also verifies the title and search result fields and the sidebar's `recent` group. */
+  toModel(resource?: ResourceModel): ViewModel;
+  private refs;
+  private next;
+}
+export declare const view: <R extends {
+  readonly $fields: unknown;
+}>(resource: string) => ViewBuilder<R>;
+//#endregion

package/dist/view.js

@@ -0,0 +1,109 @@
+import { createRefs } from "./refs.js";
+import { navRecentErrors } from "./nav-recent.js";
+import { actions } from "./view-actions.js";
+import { FieldView } from "./view-field.js";
+import { widgets } from "./view-widgets.js";
+//#region src/view.ts
+var ViewBuilder = class ViewBuilder {
+	state;
+	constructor(state) {
+		this.state = state;
+	}
+	names(names) {
+		return this.next({ names });
+	}
+	icon(icon) {
+		return this.next({ icon });
+	}
+	/** Shows this view only to users with one of these roles; a view without roles is the default. */
+	forRoles(roles) {
+		return this.next({ roles });
+	}
+	/** The field shown as this record's title. Throws when the field does not exist. */
+	title(pick) {
+		return this.next({ title: pick(this.refs()).name });
+	}
+	/**
+	* How a record shows in the global search: a bold `title` of one or more fields joined by spaces (default: `title`)
+	* and a `subtitle` field under it, replaced by the search field the text matched when that is neither.
+	*/
+	searchResult(pick) {
+		const { title, subtitle } = pick(this.refs());
+		const titles = title === void 0 ? [] : Array.isArray(title) ? title : [title];
+		return this.next({ searchResult: {
+			...titles.length > 0 && { title: titles.map((ref) => ref.name) },
+			...subtitle && { subtitle: subtitle.name }
+		} });
+	}
+	/** Where the resource sits in the sidebar; `recent` lists a few of its records under the entry (see https://docs.protobase.net/reference/sidebar/). */
+	nav(nav) {
+		return this.next({ nav });
+	}
+	help(help) {
+		return this.next({ help });
+	}
+	fields(build) {
+		const built = build(createRefs((name) => new FieldView(name)));
+		const fields = Object.fromEntries(Object.values(built).map((v) => [v.name, v.props]));
+		return this.next({ fields: {
+			...this.state.fields,
+			...fields
+		} });
+	}
+	list(build) {
+		const { columns, sort, search } = build(this.refs());
+		return this.next({ list: {
+			columns: columns.map((ref) => ref.name),
+			...sort && { sort: sort.map(([ref, dir]) => [ref.name, dir]) },
+			...search && { search: search.map((ref) => ref.name) }
+		} });
+	}
+	filters(build) {
+		return this.next({ filters: build(this.refs(), widgets) });
+	}
+	layout(build) {
+		return this.next({ layout: build(this.refs()) });
+	}
+	chart(build) {
+		const { field, range, granularity } = build(this.refs());
+		return this.next({ chart: {
+			field: field.name,
+			range,
+			granularity
+		} });
+	}
+	saveFeedback(saveFeedback) {
+		return this.next({ saveFeedback });
+	}
+	actions(build) {
+		return this.next({ actions: build(actions) });
+	}
+	/** With the resource's model, also verifies the title and search result fields and the sidebar's `recent` group. */
+	toModel(resource) {
+		const { title, nav, searchResult } = this.state;
+		if (resource && title !== void 0 && !Object.hasOwn(resource.fields, title)) throw new Error(`View "${this.state.resource}": title field "${title}" does not exist on the resource`);
+		const missing = resource ? [...searchResult?.title ?? [], ...searchResult?.subtitle ? [searchResult.subtitle] : []].filter((name) => !Object.hasOwn(resource.fields, name)) : [];
+		if (missing.length > 0) throw new Error(`View "${this.state.resource}": search result field "${missing[0]}" does not exist on the resource`);
+		const recentErrors = resource && nav?.recent ? navRecentErrors(nav.recent, resource) : [];
+		if (recentErrors.length > 0) throw new Error(`View "${this.state.resource}": nav.recent ${recentErrors.join("; ")}`);
+		return structuredClone(this.state);
+	}
+	refs() {
+		return createRefs((name) => ({ name }));
+	}
+	next(patch) {
+		return new ViewBuilder({
+			...this.state,
+			...patch
+		});
+	}
+};
+const view = (resource) => new ViewBuilder({
+	resource,
+	fields: {},
+	filters: [],
+	layout: [],
+	actions: []
+});
+//#endregion
+export { ViewBuilder, view };

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@protobase/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Resource, field, view and access definitions for Protobase configs.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PrototeamHQ/protobase.git",
+    "directory": "packages/schema"
+  },
+  "homepage": "https://docs.protobase.net",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "aip-parsers": "^1.0.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.