@declarion/react 0.31.1 → 0.32.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 { Nn as e, dt as t, lt as n, mt as r, nt as i, t as a, ut as o } from "./ActionRunner-CaSrGpBi.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";
@@ -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);
+	r.getState().setUser(t, 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;
+function C(e) {
+	let r = e.entityData ?? {};
+	t((e, t) => {
+		let n = r[e], i = S(n), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
 		return t.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 a = e.entityItems ?? {}, s = e.entityItemResponses ?? {};
+	o((e, t) => {
+		let n = typeof t == "string" ? t : i(t), r = s[e]?.[n];
+		if (r instanceof Error) throw r;
+		if (r !== void 0) return r;
+		let o = a[e]?.[n];
+		if (o instanceof Error) throw o;
+		return { data: o };
 	});
-	let s = t.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];
+	let c = e.actionResults ?? {};
+	n(async (e, t) => {
+		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({
+	t(null), o(null), n(null), r.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,21 +142,21 @@ function T(e, n = {}) {
 		client: r,
 		children: [/* @__PURE__ */ f(c, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ f(o, { children: e })
+			children: /* @__PURE__ */ f(a, { children: t })
 		}), /* @__PURE__ */ f(d, {})]
-	}), a = m(n.viewport ? /* @__PURE__ */ f(t, {
+	}), o = m(n.viewport ? /* @__PURE__ */ f(e, {
 		viewportOverride: n.viewport,
 		children: i
 	}) : i);
-	return Object.assign(a, { queryClient: r });
+	return Object.assign(o, { queryClient: r });
 }
 function E({ children: e, authenticated: t = !0, ...n }) {
-	let [r] = s(() => {
+	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 t ? (x(), e.setQueryData(["schema", !0], n.schema ?? h())) : r.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
@@ -160,10 +164,10 @@ function E({ children: e, authenticated: t = !0, ...n }) {
 		}), C(n), e;
 	});
 	return /* @__PURE__ */ p(u, {
-		client: r,
+		client: i,
 		children: [/* @__PURE__ */ f(c, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ f(o, { children: e })
+			children: /* @__PURE__ */ f(a, { 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,73 @@ export interface PublicBranding {
     workspace_domain?: string;
     legal_links?: PublicLegalLinks;
 }
+export interface BrandingThemeColors {
+    accent?: string;
+    accent_hover?: string;
+    accent_soft?: string;
+    primary?: string;
+    sidebar?: string;
+    rail?: string;
+    surface?: string;
+    surface_2?: string;
+    background?: string;
+    text?: string;
+    text_muted?: string;
+    border?: string;
+}
+export interface BrandingThemeTypography {
+    font_display?: string;
+    body?: number;
+    page_title?: number;
+    table_cell?: number;
+    control?: number;
+    caption?: number;
+}
+export interface BrandingTheme {
+    css_url?: string;
+    font_sans?: string;
+    font_mono?: string;
+    radius?: string;
+    density?: string;
+    colors?: BrandingThemeColors;
+    typography?: BrandingThemeTypography;
+}
+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 +261,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

@@ -261,6 +261,7 @@ export interface ParameterDef {
     name: LocalizedString;
     description?: LocalizedString;
     type: string;
+    structure?: string;
     default?: unknown;
     is_public?: boolean;
     category?: string;
@@ -925,20 +926,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 +937,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-D74hyWIa.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 { J as e, Ot as t, R as n, Yt as r, gn as i, kt as a, on as o, rt as s } from "./ActionRunner-CaSrGpBi.js";
+import { vt as c } from "./registry-KQyyL5Gt.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";
@@ -109,7 +109,7 @@ var b = class {
 		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 s(`${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 s(`${this.entity}.__restore`, {
 			object_ids: e,
 			entity: this.entity
 		})).object_count ?? e.length };
@@ -232,39 +232,39 @@ function O(e, t, n) {
 }
 //#endregion
 //#region src/hooks/useTabSearchMirror.ts
-function k(e) {
-	let t = o(), [n] = d();
+function k(t) {
+	let n = e(), [r] = d();
 	l(() => {
-		if (!e || t.enabled) return;
-		let r = c.getState(), i = r.findTabByPathname(e);
-		i && r.updateTabSearch(i.id, n.toString());
+		if (!t || n.enabled) return;
+		let e = c.getState(), i = e.findTabByPathname(t);
+		i && e.updateTabSearch(i.id, r.toString());
 	}, [
-		n,
-		e,
-		t.enabled
+		r,
+		t,
+		n.enabled
 	]);
 }
 //#endregion
 //#region src/hooks/useRegisterScreenTab.ts
-function A(e, t, n, r) {
-	let i = o();
+function A(t, n, r, i) {
+	let a = e();
 	l(() => {
-		!e || i.enabled || c.getState().openTab({
-			pathname: e,
-			search: r,
-			title: t,
-			icon: n,
+		!t || a.enabled || c.getState().openTab({
+			pathname: t,
+			search: i,
+			title: n,
+			icon: r,
 			closable: !0
 		});
 	}, [
-		e,
 		t,
 		n,
-		i.enabled
+		r,
+		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;
+	let r = e?.route, i = t ? o(e?.display?.name) || o(t.display.name_plural) : "", a = e?.display?.icon || t?.display.icon;
 	A(t ? r : void 0, i, a, n);
 }
 //#endregion
@@ -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 o = (await s(`${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 o.find((e) => e.group_code === n) ?? o[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 s(`${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 s(`${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);
 		}
 	});
 }

package/dist-lib/{value-BooGwUik.js → value-BfXXl5EE.js}

@@ -1,4 +1,4 @@
-import { Ft as e, It as t, zt as n } from "./ActionRunner-BzaZQtiI.js";
+import { Ft as e, It as t, zt as n } from "./ActionRunner-CaSrGpBi.js";
 import { useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
 //#region src/components/file-widgets/helpers.ts
 var s = ["thumb_200", "thumb_300"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",

package/dist-lib/hooks/useEntityItem.d.ts

@@ -1,10 +0,0 @@
-import { type QueryKey } from "@tanstack/react-query";
-import type { PkValues } from "../types/schema";
-/**
- * The React Query key for a single-record read. Single source of truth for both
- * `useEntityItem` and a detail screen registering its PRIMARY read with its
- * retained page (`useRegisterRetainedQuery`). For a string PK uses it directly;
- * for a composite PK sorts the parts so key order does not fork the cache.
- */
-export declare function entityItemQueryKey(entity: string | undefined, pkValues: PkValues | string | undefined): QueryKey;
-export declare function useEntityItem(entity: string | undefined, pkValues: PkValues | string | undefined): import("@tanstack/react-query").UseQueryResult<NoInfer<import("..").DataResponse<Record<string, unknown>>>, Error>;