@declarion/react 0.31.2 → 0.34.0

package/dist-lib/testing.d.ts

@@ -4,7 +4,7 @@ import { QueryClient } from "@tanstack/react-query";
 import { type ResponsiveViewport } from "./hooks/useResponsiveMode";
 import { type ActionExecuteRequest, type ActionExecuteResponse } from "./api/data";
 import type { Schema } from "./types/schema";
-import type { ListMeta, ListResponse, Refs } from "./types/api";
+import type { DataResponse, ListMeta, ListResponse, Refs } from "./types/api";
 /** A single action's stubbed outcome: the action's RESULT payload (what
  *  executeDeclarionAction unwraps from response.result), or a function of the
  *  dispatched body returning it. The harness always wraps it in a success
@@ -25,8 +25,10 @@ export interface RenderWithDeclarionOptions {
     schema?: Schema;
     /** entity -> rows, { rows, meta }, or an entityDataFixture() ListResponse; resolves useEntityData / useEntityCount. */
     entityData?: Record<string, Record<string, unknown>[] | EntityDataFixture | ListResponse>;
-    /** entity -> { [id]: row }; resolves useEntityItem. */
-    entityItems?: Record<string, Record<string, Record<string, unknown>>>;
+    /** entity -> { [id]: row | Error }; resolves useObject. Error entries let tests model 404/403 without network. */
+    entityItems?: Record<string, Record<string, Record<string, unknown> | Error>>;
+    /** entity -> { [id]: DataResponse | Error }; resolves useObject when a test needs envelope metadata like `$refs`. */
+    entityItemResponses?: Record<string, Record<string, DataResponse | Error>>;
     /** action code -> result | (body) => result; resolves executeAction (and create/update/delete/restore). */
     actionResults?: Record<string, ActionResult>;
     /** Initial path for the memory router (e.g. "/replay/abc/compare"). Default "/". */

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { H as e, Nn as t, X as n, Y as r, Z as i, mt as a, t as o } from "./ActionRunner-BzaZQtiI.js";
+import { In as e, _t as t, at as n, ft as r, mt as i, pt as a, t as o } from "./ActionRunner-UGGvGypS.js";
 import { useState as s } from "react";
 import { MemoryRouter as c } from "react-router-dom";
 import { QueryClient as l, QueryClientProvider as u } from "@tanstack/react-query";
@@ -59,7 +59,7 @@ function x() {
 		code: "test",
 		name: "Test",
 		role: "admin"
-	}, t = {
+	}, n = {
 		id: "test-user",
 		email: "test@example.com",
 		display_name: "Test User",
@@ -70,7 +70,7 @@ function x() {
 		created_at: "2026-01-01T00:00:00Z",
 		updated_at: "2026-01-01T00:00:00Z"
 	};
-	a.getState().setUser(t, e);
+	t.getState().setUser(n, e);
 }
 function S(e) {
 	if (e === void 0) return { rows: [] };
@@ -85,50 +85,54 @@ function S(e) {
 	}
 	return e;
 }
-function C(t) {
-	let a = t.entityData ?? {};
-	i((e, t) => {
-		let n = a[e], r = S(n), i = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
-		return t.count === "only" ? {
+function C(e) {
+	let t = e.entityData ?? {};
+	i((e, n) => {
+		let r = t[e], i = S(r), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
+		return n.count === "only" ? {
 			data: [],
 			meta: {
 				page: 1,
-				per_page: i,
+				per_page: a,
 				total: o,
-				total_pages: r.meta?.total_pages ?? Math.max(1, Math.ceil(o / i)),
-				count_mode: r.meta?.count_mode ?? "exact"
+				total_pages: i.meta?.total_pages ?? Math.max(1, Math.ceil(o / a)),
+				count_mode: i.meta?.count_mode ?? "exact"
 			}
 		} : {
-			data: r.rows,
+			data: i.rows,
 			meta: {
-				page: r.meta?.page ?? 1,
-				per_page: i,
-				has_more: r.meta?.has_more ?? !1
+				page: i.meta?.page ?? 1,
+				per_page: a,
+				has_more: i.meta?.has_more ?? !1
 			},
-			...r.refs === void 0 ? {} : { $refs: r.refs }
+			...i.refs === void 0 ? {} : { $refs: i.refs }
 		};
 	});
-	let o = t.entityItems ?? {};
-	n((t, n) => {
-		let r = typeof n == "string" ? n : e(n);
-		return { data: o[t]?.[r] };
+	let o = e.entityItems ?? {}, s = e.entityItemResponses ?? {};
+	a((e, t) => {
+		let r = typeof t == "string" ? t : n(t), i = s[e]?.[r];
+		if (i instanceof Error) throw i;
+		if (i !== void 0) return i;
+		let a = o[e]?.[r];
+		if (a instanceof Error) throw a;
+		return { data: a };
 	});
-	let s = t.actionResults ?? {};
+	let c = e.actionResults ?? {};
 	r(async (e, t) => {
-		if (!(e in s)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
-		let n = s[e];
+		if (!(e in c)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
+		let n = c[e];
 		return b(typeof n == "function" ? await n(t) : n);
 	});
 }
 function w() {
-	i(null), n(null), r(null), a.setState({
+	i(null), a(null), r(null), t.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
 		tenants: []
 	});
 }
-function T(e, n = {}) {
+function T(t, n = {}) {
 	let r = new l({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
@@ -138,31 +142,31 @@ function T(e, n = {}) {
 		client: r,
 		children: [/* @__PURE__ */ f(c, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ f(o, { children: e })
+			children: /* @__PURE__ */ f(o, { children: t })
 		}), /* @__PURE__ */ f(d, {})]
-	}), a = m(n.viewport ? /* @__PURE__ */ f(t, {
+	}), a = m(n.viewport ? /* @__PURE__ */ f(e, {
 		viewportOverride: n.viewport,
 		children: i
 	}) : i);
 	return Object.assign(a, { queryClient: r });
 }
-function E({ children: e, authenticated: t = !0, ...n }) {
-	let [r] = s(() => {
+function E({ children: e, authenticated: n = !0, ...r }) {
+	let [i] = s(() => {
 		let e = new l({ defaultOptions: { queries: {
 			retry: !1,
 			gcTime: Infinity
 		} } });
-		return t ? (x(), e.setQueryData(["schema", !0], n.schema ?? h())) : a.setState({
+		return n ? (x(), e.setQueryData(["schema", !0], r.schema ?? h())) : t.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
 			tenants: []
-		}), C(n), e;
+		}), C(r), e;
 	});
 	return /* @__PURE__ */ p(u, {
-		client: r,
+		client: i,
 		children: [/* @__PURE__ */ f(c, {
-			initialEntries: [n.route ?? "/"],
+			initialEntries: [r.route ?? "/"],
 			children: /* @__PURE__ */ f(o, { children: e })
 		}), /* @__PURE__ */ f(d, {})]
 	});

package/dist-lib/types/api.d.ts

@@ -30,6 +30,7 @@ export interface ListResponse<T = Record<string, unknown>> {
 }
 export interface DataResponse<T = Record<string, unknown>> {
     data: T;
+    $refs?: Refs;
 }
 export interface ApiErrorBody {
     error: {
@@ -148,6 +149,7 @@ export interface PublicParam {
     code: string;
     name: LocalizedString;
     type: string;
+    structure?: string;
     category: string;
     description?: LocalizedString;
     value: unknown;
@@ -159,8 +161,7 @@ export interface PublicLegalLinks {
     terms_url?: string;
     docs_url?: string;
 }
-/** Subset of branding exposed pre-login by /api/params/public. */
-export interface PublicBranding {
+export interface BrandingIdentity {
     app_name?: string;
     app_logo?: string;
     app_initial?: string;
@@ -176,6 +177,65 @@ export interface PublicBranding {
     workspace_domain?: string;
     legal_links?: PublicLegalLinks;
 }
+export interface BrandingThemeColors {
+    accent?: string;
+    accent_hover?: string;
+    accent_soft?: string;
+    primary?: string;
+    primary_hover?: string;
+    sidebar?: string;
+    rail?: string;
+    surface?: string;
+    surface_2?: string;
+    background?: string;
+    text?: string;
+    text_muted?: string;
+    border?: string;
+}
+export interface BrandingTheme {
+    css_url?: string;
+    font_sans?: string;
+    font_mono?: string;
+    radius?: string;
+    density?: string;
+    colors?: BrandingThemeColors;
+}
+export interface BrandingSurfaceFlags {
+    show_title?: boolean;
+    show_breadcrumbs?: boolean;
+    show_actions?: boolean;
+    show_count?: boolean;
+    show_sidebar?: boolean;
+    show_topbar?: boolean;
+    show_rail?: boolean;
+    show_tabs?: boolean;
+    show_tenant_switcher?: boolean;
+}
+export interface BrandingChrome {
+    full?: {
+        shell?: BrandingSurfaceFlags;
+        surfaces?: {
+            list?: BrandingSurfaceFlags;
+            detail?: BrandingSurfaceFlags;
+            record_list?: BrandingSurfaceFlags;
+            custom?: BrandingSurfaceFlags;
+        };
+    };
+    embed?: {
+        surfaces?: {
+            list?: BrandingSurfaceFlags;
+            detail?: BrandingSurfaceFlags;
+            record_list?: BrandingSurfaceFlags;
+            custom?: BrandingSurfaceFlags;
+        };
+    };
+}
+/** Structured value of the public `branding` parameter. */
+export interface PublicBranding {
+    identity?: BrandingIdentity;
+    theme?: BrandingTheme;
+    chrome?: BrandingChrome;
+}
 /**
  * Deploy-time identity exposed pre-login by /api/params/public so the
  * auth shell can render real region/build values (no mockup placeholders).
@@ -193,7 +253,6 @@ export interface PublicParamsResponse {
     parameters: PublicParam[];
     accents?: Record<string, AccentDef>;
     messages?: Record<string, LocalizedString>;
-    branding?: PublicBranding;
     meta?: PublicMeta;
 }
 /**

package/dist-lib/types/schema.d.ts

@@ -29,7 +29,7 @@ export declare function getDisplayValue(row: Record<string, unknown> | null | un
         display_field?: string;
     };
 } | null | undefined): string | undefined;
-export declare function resolveRefRecordLabel(record: Record<string, unknown>, displayField: string | undefined, fallback: string): string;
+export declare function resolveRefRecordLabel(record: Record<string, unknown>, displayKey: string | undefined, fallback: string): string;
 export declare function screenTitleForPath(pathname: string, screens: Record<string, Screen> | undefined, entities?: Record<string, Entity>): {
     title: string;
     icon?: string;
@@ -261,6 +261,7 @@ export interface ParameterDef {
     name: LocalizedString;
     description?: LocalizedString;
     type: string;
+    structure?: string;
     default?: unknown;
     is_public?: boolean;
     category?: string;
@@ -412,6 +413,22 @@ export interface Entity {
      * list UI on this. See docs/plans/2026-06-20-cross-store-list-cursor-pagination.md.
      */
     list_pagination?: "offset" | "cursor";
+    /**
+     * Static, per-caller document-generation capability computed from the
+     * SYSTEM document template registry at schema projection (registry-only,
+     * no DB read, no ETag impact - system templates are boot-static and are
+     * covered by the schema fingerprint). Absent (or both flags falsy) means
+     * no system template applies for this caller/tenant/entity - the
+     * frontend's Generate affordance renders nothing UNLESS a tenant-uploaded
+     * template is found via the lazy `document.templates.available` runtime
+     * probe (tenant templates are runtime data and are never baked into the
+     * schema). `generate_one` gates the detail-scope toolbar; `generate_many`
+     * gates the list-scope toolbar. See docs/document-generation.md.
+     */
+    documents?: {
+        generate_one?: boolean;
+        generate_many?: boolean;
+    };
 }
 export interface ExportConfig {
     enabled?: boolean;
@@ -925,20 +942,6 @@ export interface HandlerDef {
     params?: OrderedMap<HandlerParam>;
     success_event?: string;
 }
-export interface Branding {
-    app_name?: string;
-    app_logo?: string;
-    app_initial?: string;
-    accent_color?: string;
-    ai_name?: string;
-    wordmark?: string;
-    version_label?: string;
-    status_url?: string;
-    auth_tagline?: LocalizedString;
-    auth_subtagline?: LocalizedString;
-    auth_badges?: LocalizedString[];
-    css_url?: string;
-}
 export interface Schema {
     languages: LanguageDef[];
     structures: Record<string, StructureDef>;
@@ -950,7 +953,6 @@ export interface Schema {
     enums: Record<string, EnumDef>;
     parameters: Record<string, ParameterDef>;
     messages?: Record<string, LocalizedString>;
-    branding?: Branding;
     areas?: AreaDef[];
     accents?: Record<string, AccentDef>;
     /**

package/dist-lib/{useProperties-Co3RdtuT.js → useProperties-CgRhBh0k.js}

@@ -1,5 +1,5 @@
-import { $ as e, Ot as t, U as n, Yt as r, gn as i, kt as a, lt as o, on as s } from "./ActionRunner-BzaZQtiI.js";
-import { ht as c } from "./registry-2KliNTHB.js";
+import { Mt as e, Qt as t, V as n, Z as r, jt as i, ln as a, ot as o, yn as s } from "./ActionRunner-UGGvGypS.js";
+import { vt as c } from "./registry-DnPK3Msj.js";
 import { useEffect as l, useMemo as u } from "react";
 import { useSearchParams as d } from "react-router-dom";
 import { useInfiniteQuery as f, useMutation as p, useQueryClient as m } from "@tanstack/react-query";
@@ -47,33 +47,33 @@ var b = class {
 		this.entity = e, this.refs = t ?? new v();
 	}
 	async get(e) {
-		let n = new URLSearchParams(typeof e == "string" ? { id: e } : e);
-		return _((await t(`/api/data/${this.entity}?${n.toString()}`)).data);
+		let t = new URLSearchParams(typeof e == "string" ? { id: e } : e);
+		return _((await i(`/api/data/${this.entity}?${t.toString()}`)).data);
 	}
 	async list(e = {}) {
-		let n, i = !1;
+		let n, r = !1;
 		try {
-			n = await t(y(this.entity, e));
+			n = await i(y(this.entity, e));
 		} catch (a) {
-			if (e.after && r(a)) {
-				let { after: r, ...a } = e;
-				n = await t(y(this.entity, a)), i = !0;
+			if (e.after && t(a)) {
+				let { after: t, ...a } = e;
+				n = await i(y(this.entity, a)), r = !0;
 			} else throw a;
 		}
 		return this.refs.merge(n.$refs), {
 			data: n.data.map((e) => _(e)),
 			meta: n.meta,
 			$refs: this.refs.all(),
-			reset: i
+			reset: r
 		};
 	}
 	async create(e) {
 		return (await this.createMany([e]))[0];
 	}
-	async createMany(e) {
-		if (e.length === 0) return [];
-		let t = await a("system.batch", {
-			actions: e.map((e) => ({
+	async createMany(t) {
+		if (t.length === 0) return [];
+		let n = await e("system.batch", {
+			actions: t.map((e) => ({
 				action: `${this.entity}.__create`,
 				params: {
 					entity: this.entity,
@@ -82,7 +82,7 @@ var b = class {
 			})),
 			atomic: !0
 		});
-		return x(t, `${this.entity}.__create`), t.results.map((e) => _(S(e)));
+		return x(n, `${this.entity}.__create`), n.results.map((e) => _(S(e)));
 	}
 	async update(e, t) {
 		return (await this.updateMany([{
@@ -90,10 +90,10 @@ var b = class {
 			...t
 		}]))[0];
 	}
-	async updateMany(e) {
-		if (e.length === 0) return [];
-		let t = await a("system.batch", {
-			actions: e.map(({ id: e, ...t }) => ({
+	async updateMany(t) {
+		if (t.length === 0) return [];
+		let n = await e("system.batch", {
+			actions: t.map(({ id: e, ...t }) => ({
 				action: `${this.entity}.__update`,
 				params: {
 					object_ids: [e],
@@ -103,13 +103,13 @@ var b = class {
 			})),
 			atomic: !0
 		});
-		return x(t, `${this.entity}.__update`), t.results.map((e) => _(S(e)));
+		return x(n, `${this.entity}.__update`), n.results.map((e) => _(S(e)));
 	}
 	async delete(e) {
 		await this.deleteMany([e]);
 	}
 	async deleteMany(e) {
-		return e.length === 0 ? { count: 0 } : { count: (await n(`${this.entity}.__delete`, {
+		return e.length === 0 ? { count: 0 } : { count: (await o(`${this.entity}.__delete`, {
 			object_ids: e,
 			entity: this.entity
 		})).object_count ?? e.length };
@@ -118,7 +118,7 @@ var b = class {
 		await this.restoreMany([e]);
 	}
 	async restoreMany(e) {
-		return e.length === 0 ? { count: 0 } : { count: (await n(`${this.entity}.__restore`, {
+		return e.length === 0 ? { count: 0 } : { count: (await o(`${this.entity}.__restore`, {
 			object_ids: e,
 			entity: this.entity
 		})).object_count ?? e.length };
@@ -126,20 +126,20 @@ var b = class {
 	async upsert(e, t) {
 		return (await this.upsertMany([e], t))[0];
 	}
-	async upsertMany(e, t) {
-		if (e.length === 0) return [];
-		let n = await a("system.batch", {
-			actions: e.map((e) => ({
+	async upsertMany(t, n) {
+		if (t.length === 0) return [];
+		let r = await e("system.batch", {
+			actions: t.map((e) => ({
 				action: `${this.entity}.__upsert`,
 				params: {
 					entity: this.entity,
 					fields: e,
-					unique_by: t
+					unique_by: n
 				}
 			})),
 			atomic: !0
 		});
-		return x(n, `${this.entity}.__upsert`), n.results.map((e) => _(C(e)));
+		return x(r, `${this.entity}.__upsert`), r.results.map((e) => _(C(e)));
 	}
 };
 function x(e, t) {
@@ -233,7 +233,7 @@ function O(e, t, n) {
 //#endregion
 //#region src/hooks/useTabSearchMirror.ts
 function k(e) {
-	let t = o(), [n] = d();
+	let t = r(), [n] = d();
 	l(() => {
 		if (!e || t.enabled) return;
 		let r = c.getState(), i = r.findTabByPathname(e);
@@ -246,12 +246,12 @@ function k(e) {
 }
 //#endregion
 //#region src/hooks/useRegisterScreenTab.ts
-function A(e, t, n, r) {
-	let i = o();
+function A(e, t, n, i) {
+	let a = r();
 	l(() => {
-		!e || i.enabled || c.getState().openTab({
+		!e || a.enabled || c.getState().openTab({
 			pathname: e,
-			search: r,
+			search: i,
 			title: t,
 			icon: n,
 			closable: !0
@@ -260,12 +260,12 @@ function A(e, t, n, r) {
 		e,
 		t,
 		n,
-		i.enabled
+		a.enabled
 	]);
 }
 function j(e, t, n) {
-	let r = e?.route, i = t ? s(e?.display?.name) || s(t.display.name_plural) : "", a = e?.display?.icon || t?.display.icon;
-	A(t ? r : void 0, i, a, n);
+	let r = e?.route, i = t ? a(e?.display?.name) || a(t.display.name_plural) : "", o = e?.display?.icon || t?.display.icon;
+	A(t ? r : void 0, i, o, n);
 }
 //#endregion
 //#region src/lib/filters.ts
@@ -332,14 +332,14 @@ function z(e, t) {
 	if (!e.field || !e.op) return "";
 	let n = N[e.op] || e.op;
 	if (M.has(e.op)) return `${n}`;
-	let r = e.field, a = (e) => {
+	let r = e.field, i = (e) => {
 		if (t) {
 			let n = t(r, e);
 			return n.label != null && (n.status === "special" || n.status === "resolved") ? n.label : n.raw;
 		}
-		return i(e);
+		return s(e);
 	};
-	return `${n} ${Array.isArray(e.value) ? e.value.map(a).join(", ") : a(e.value)}`;
+	return `${n} ${Array.isArray(e.value) ? e.value.map(i).join(", ") : i(e.value)}`;
 }
 function B(e, t) {
 	return {
@@ -373,79 +373,79 @@ function V(e, t) {
 }
 //#endregion
 //#region src/api/status.ts
-async function H(e, t, r, i, a) {
-	let o = {
-		status_group_code: r,
-		status_code: i
+async function H(e, t, n, r, i) {
+	let a = {
+		status_group_code: n,
+		status_code: r
 	};
-	a != null && (o.note = a);
-	let s = (await n(`${e}.__update`, {
+	i != null && (a.note = i);
+	let s = (await o(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
-		fields: { $statuses: [o] }
+		fields: { $statuses: [a] }
 	})).result?.rows?.[0]?.$statuses ?? [];
-	return s.find((e) => e.group_code === r) ?? s[0];
+	return s.find((e) => e.group_code === n) ?? s[0];
 }
 //#endregion
 //#region src/hooks/useObjectStatus.ts
-function U(t, n) {
+function U(e, t) {
 	let r = m();
 	return p({
-		mutationFn: ({ groupCode: e, statusCode: r, note: i }) => H(t, n, e, r, i),
+		mutationFn: ({ groupCode: n, statusCode: r, note: i }) => H(e, t, n, r, i),
 		onSuccess: () => {
-			r.invalidateQueries({ queryKey: ["entity-item", t] });
+			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
-		onError: (t) => {
-			e.error(t.message);
+		onError: (e) => {
+			n.error(e.message);
 		}
 	});
 }
 //#endregion
 //#region src/api/properties.ts
-async function W(e, t, r, i) {
-	let a = (await n(`${e}.__update`, {
+async function W(e, t, n, r) {
+	let i = (await o(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
 		fields: { $properties: [{
-			property_code: r,
-			value: i
+			property_code: n,
+			value: r
 		}] }
 	})).result?.rows?.[0]?.$properties ?? [];
-	return a.find((e) => e.property_code === r) ?? a[0];
+	return i.find((e) => e.property_code === n) ?? i[0];
 }
-async function G(e, t, r) {
-	await n(`${e}.__update`, {
+async function G(e, t, n) {
+	await o(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
 		fields: { $properties: [{
-			property_code: r,
+			property_code: n,
 			value: null
 		}] }
 	});
 }
 //#endregion
 //#region src/hooks/useProperties.ts
-function K(t, n) {
+function K(e, t) {
 	let r = m();
 	return p({
-		mutationFn: ({ propertyCode: e, value: r }) => W(t, n, e, r),
+		mutationFn: ({ propertyCode: n, value: r }) => W(e, t, n, r),
 		onSuccess: () => {
-			r.invalidateQueries({ queryKey: ["entity-item", t] });
+			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
-		onError: (t) => {
-			e.error(t.message);
+		onError: (e) => {
+			n.error(e.message);
 		}
 	});
 }
-function q(t, n) {
+function q(e, t) {
 	let r = m();
 	return p({
-		mutationFn: (e) => G(t, n, e),
+		mutationFn: (n) => G(e, t, n),
 		onSuccess: () => {
-			r.invalidateQueries({ queryKey: ["entity-item", t] });
+			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
-		onError: (t) => {
-			e.error(t.message);
+		onError: (e) => {
+			n.error(e.message);
 		}
 	});
 }