@declarion/react 0.34.0 → 0.35.1

package/dist-lib/stores/page-state.d.ts

@@ -6,7 +6,7 @@ import type { QueryClient, QueryKey } from "@tanstack/react-query";
 export declare const DEFAULT_PAGE_STATE_TTL_MS: number;
 /** Hard upper bound on retained-page entries. Bounds total memory and is the
  *  ONLY bound in embed mode, which has no tab-close signal at all. Generous
- *  relative to `ui_tabs_max_open` (a user rarely revisits more than this many
+ *  relative to `preferences.tabs_max_open` (a user rarely revisits more than this many
  *  distinct URLs within one TTL window); the least-recently-active entry is
  *  evicted first when the cap is exceeded. */
 export declare const PAGE_STATE_MAX_ENTRIES = 64;

package/dist-lib/stores/preferences.d.ts

@@ -0,0 +1,37 @@
+import type { BrandingPreferences } from "../types/api";
+export type ColorScheme = "light" | "dark";
+export type AccentId = "violet" | "blue" | "teal" | "amber" | "rose";
+export type Density = "compact" | "comfortable" | "cozy";
+export type SidebarMode = "wide" | "collapsed";
+export type TabsPosition = "top" | "bottom";
+export type AiSurface = "command" | "panel" | "both" | "off";
+export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export interface Preferences {
+    colorScheme: ColorScheme;
+    accent: AccentId;
+    density: Density;
+    sidebar: SidebarMode;
+    tabsPosition: TabsPosition;
+    tabsMaxOpen: number;
+    /** When false, tabs are not persisted across reloads. */
+    tabsPersist: boolean;
+    radius: number;
+    zebra: boolean;
+    aiSurface: AiSurface;
+    /** Where toasts appear. Read by <Toaster> in app.tsx. */
+    toastPosition: ToastPosition;
+}
+export declare function applyPreferences(p: Preferences): void;
+interface PreferencesState extends Preferences {
+    set: <K extends keyof Preferences>(key: K, value: Preferences[K]) => void;
+    setMany: (patch: Partial<Preferences>) => void;
+    /** Apply the deployment's defaults from `branding.preferences`. ONLY fills
+     *  keys the user has not already changed this session, so a branding
+     *  refetch never clobbers a toggle the user just clicked. */
+    hydrateFromBranding: (preferences: BrandingPreferences | undefined) => void;
+    /** Forget every session choice and return to the deployment's defaults —
+     *  the same state a fresh page load resolves, reproduced on demand. */
+    resetToDefaults: (preferences: BrandingPreferences | undefined) => void;
+}
+export declare const usePreferencesStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PreferencesState>>;
+export {};

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-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 { Fn as e, dt as t, ft as n, ht as r, rt as i, t as a, ut as o } from "./ActionRunner-Bkkb_YMa.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"
-	}, n = {
+	}, t = {
 		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"
 	};
-	t.getState().setUser(n, e);
+	r.getState().setUser(t, e);
 }
 function S(e) {
 	if (e === void 0) return { rows: [] };
@@ -86,10 +86,10 @@ function S(e) {
 	return e;
 }
 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" ? {
+	let r = e.entityData ?? {};
+	n((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,
@@ -108,24 +108,24 @@ function C(e) {
 			...i.refs === void 0 ? {} : { $refs: i.refs }
 		};
 	});
-	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 a = e.entityItems ?? {}, s = e.entityItemResponses ?? {};
+	t((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 c = e.actionResults ?? {};
-	r(async (e, t) => {
+	o(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), a(null), r(null), t.setState({
+	n(null), t(null), o(null), r.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
@@ -142,32 +142,32 @@ function T(t, n = {}) {
 		client: r,
 		children: [/* @__PURE__ */ f(c, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ f(o, { children: t })
+			children: /* @__PURE__ */ f(a, { children: t })
 		}), /* @__PURE__ */ f(d, {})]
-	}), a = m(n.viewport ? /* @__PURE__ */ f(e, {
+	}), 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: n = !0, ...r }) {
+function E({ children: e, authenticated: t = !0, ...n }) {
 	let [i] = s(() => {
 		let e = new l({ defaultOptions: { queries: {
 			retry: !1,
 			gcTime: Infinity
 		} } });
-		return n ? (x(), e.setQueryData(["schema", !0], r.schema ?? h())) : t.setState({
+		return t ? (x(), e.setQueryData(["schema", !0], n.schema ?? h())) : r.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
 			tenants: []
-		}), C(r), e;
+		}), C(n), e;
 	});
 	return /* @__PURE__ */ p(u, {
 		client: i,
 		children: [/* @__PURE__ */ f(c, {
-			initialEntries: [r.route ?? "/"],
-			children: /* @__PURE__ */ f(o, { children: e })
+			initialEntries: [n.route ?? "/"],
+			children: /* @__PURE__ */ f(a, { children: e })
 		}), /* @__PURE__ */ f(d, {})]
 	});
 }

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

@@ -165,7 +165,6 @@ export interface BrandingIdentity {
     app_name?: string;
     app_logo?: string;
     app_initial?: string;
-    accent_color?: string;
     ai_name?: string;
     wordmark?: string;
     version_label?: string;
@@ -177,43 +176,122 @@ export interface BrandingIdentity {
     workspace_domain?: string;
     legal_links?: PublicLegalLinks;
 }
+/**
+ * Fourteen brand colors, each named EXACTLY after the CSS custom property it
+ * writes, with underscores hyphenated: `surface_2` writes `--surface-2`. A
+ * developer who set a field in YAML reaches the same token from their own
+ * stylesheet without a lookup table. `branding.colorFields.test.ts` enforces
+ * the mapping against the YAML structure, across languages.
+ *
+ * The shades that hang off these (`--accent-soft`, `--accent-ring`,
+ * `--row-selected-bg`) are DERIVED from them and are not settable here: a
+ * designer picks an accent, and the tints follow. A brand that wants a bespoke
+ * tint sets the custom property in `theme.css_url`, with a plain rule and no
+ * `!important`.
+ */
 export interface BrandingThemeColors {
-    accent?: string;
-    accent_hover?: string;
-    accent_soft?: string;
-    primary?: string;
-    primary_hover?: string;
-    sidebar?: string;
-    rail?: string;
+    background?: string;
     surface?: string;
     surface_2?: string;
-    background?: string;
+    surface_3?: string;
     text?: string;
-    text_muted?: string;
+    text_2?: string;
+    text_3?: string;
     border?: string;
+    divider?: string;
+    accent?: string;
+    accent_hover?: string;
+    accent_foreground?: string;
+    sidebar?: string;
+    rail?: string;
+}
+/**
+ * Page-title typography. Scheme-independent: a title is the same size in light
+ * and dark. Each field is named after the CSS custom property it writes:
+ * `page_title_size` writes `--page-title-size`.
+ *
+ * Three surfaces render an `<h1>` page title at three sizes the designer chose
+ * (list 20px, record 19px, page 18px). Declaring `page_title_size` overrides all
+ * three at once; omitting it leaves each on its own designed default.
+ */
+export interface BrandingTypography {
+    /** e.g. "15px". Overrides every page title's size. */
+    page_title_size?: string;
+    /** e.g. "22.5px" or "1.5". Overrides every page title's line height. */
+    page_title_line_height?: string;
+}
+/**
+ * Brand colors keyed by color scheme. A scheme may be omitted entirely, or any
+ * field within it omitted; the platform's own token for that scheme applies. A
+ * value is NEVER copied from the other scheme - that is the bug this shape
+ * exists to make impossible.
+ */
+export interface BrandingThemeColorSchemes {
+    light?: BrandingThemeColors;
+    dark?: BrandingThemeColors;
 }
 export interface BrandingTheme {
     css_url?: string;
     font_sans?: string;
     font_mono?: string;
-    radius?: string;
-    density?: string;
-    colors?: BrandingThemeColors;
+    typography?: BrandingTypography;
+    colors?: BrandingThemeColorSchemes;
+}
+/**
+ * The deployment's DEFAULTS for the controls the Preferences screen renders,
+ * and the single durable source of preference state (Decision 33: the browser
+ * stores nothing). A user's toggle holds for the SPA session and resets to
+ * these on reload.
+ *
+ * Wire shape is snake_case because it is YAML. `stores/preferences.ts` owns the
+ * single translation into the camelCase store; add a field here and there, or
+ * it will load, validate, and do nothing.
+ */
+export interface BrandingPreferences {
+    color_scheme?: "light" | "dark";
+    accent?: "violet" | "blue" | "teal" | "amber" | "rose";
+    density?: "compact" | "comfortable" | "cozy";
+    sidebar?: "wide" | "collapsed";
+    tabs_position?: "top" | "bottom";
+    tabs_max_open?: number;
+    tabs_persist?: boolean;
+    radius?: number;
+    zebra_rows?: boolean;
+    ai_surface?: "command" | "panel" | "both" | "off";
+    toast_position?: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
 }
+/**
+ * Per-surface chrome flags - mirrors the YAML `branding_surface_flags`
+ * structure exactly. Kept distinct from {@link BrandingShellFlags}: the two
+ * are different YAML structures, and conflating them let a caller ask a
+ * surface for a shell flag that could never be set there.
+ */
 export interface BrandingSurfaceFlags {
     show_title?: boolean;
-    show_breadcrumbs?: boolean;
     show_actions?: boolean;
     show_count?: boolean;
-    show_sidebar?: boolean;
+}
+/** Shell chrome flags - mirrors the YAML `branding_chrome_shell` structure. */
+export interface BrandingShellFlags {
     show_topbar?: boolean;
     show_rail?: boolean;
+    show_sidebar?: boolean;
     show_tabs?: boolean;
+    show_breadcrumbs?: boolean;
     show_tenant_switcher?: boolean;
+    show_command_palette?: boolean;
+    show_theme_toggle?: boolean;
 }
+/**
+ * The device class the SDK renders for. `auto` derives it from the measured
+ * width, which is what the platform has always done and what a deployment that
+ * declares nothing keeps.
+ */
+export type BrandingViewport = "auto" | "phone" | "tablet" | "desktop";
 export interface BrandingChrome {
     full?: {
-        shell?: BrandingSurfaceFlags;
+        viewport?: BrandingViewport;
+        shell?: BrandingShellFlags;
         surfaces?: {
             list?: BrandingSurfaceFlags;
             detail?: BrandingSurfaceFlags;
@@ -222,6 +300,7 @@ export interface BrandingChrome {
         };
     };
     embed?: {
+        viewport?: BrandingViewport;
         surfaces?: {
             list?: BrandingSurfaceFlags;
             detail?: BrandingSurfaceFlags;
@@ -234,6 +313,7 @@ export interface BrandingChrome {
 export interface PublicBranding {
     identity?: BrandingIdentity;
     theme?: BrandingTheme;
+    preferences?: BrandingPreferences;
     chrome?: BrandingChrome;
 }
 /**

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

@@ -4,6 +4,20 @@ import type { IconDef } from "../stores/icon-registry";
 export { OrderedMap };
 export type { IconDef };
 export type LocalizedString = Record<string, string>;
+/**
+ * Where a `url` cell fetches an unknown host's site icon from.
+ *
+ * This is an outbound-request policy, not a visual style:
+ *   google — one request per rendered hostname to www.google.com.
+ *   direct — /favicon.ico from the site's own origin.
+ *   none   — no request at all; render the globe placeholder.
+ *
+ * Declared per column by `field.display.favicon_source`, and nowhere else -
+ * there is no parameter (plan 2026-07-09 Decision 23). Absent = `google`,
+ * today's rendered default. Mirrors `validFaviconSources` in
+ * golang/internal/engine/types_field_display.go.
+ */
+export type FaviconSource = "google" | "direct" | "none";
 /**
  * Per-entity empty-state copy declared in the manifest under
  * `display.empty_state`. Title and Body are localized; LearnMoreURL is a
@@ -111,6 +125,7 @@ export interface EntityField {
         currency?: string;
         currency_field?: string;
         currency_display?: "symbol" | "narrow_symbol" | "code" | "name";
+        favicon_source?: FaviconSource;
     };
     values?: Array<{
         code: string;

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

@@ -1,5 +1,5 @@
-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 { At as e, V as t, Z as n, Zt as r, cn as i, it as a, kt as o, vn as s } from "./ActionRunner-Bkkb_YMa.js";
+import { vt as c } from "./registry-GTwsJEYp.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";
@@ -48,23 +48,23 @@ var b = class {
 	}
 	async get(e) {
 		let t = new URLSearchParams(typeof e == "string" ? { id: e } : e);
-		return _((await i(`/api/data/${this.entity}?${t.toString()}`)).data);
+		return _((await o(`/api/data/${this.entity}?${t.toString()}`)).data);
 	}
 	async list(e = {}) {
-		let n, r = !1;
+		let t, n = !1;
 		try {
-			n = await i(y(this.entity, e));
-		} catch (a) {
-			if (e.after && t(a)) {
-				let { after: t, ...a } = e;
-				n = await i(y(this.entity, a)), r = !0;
-			} else throw a;
+			t = await o(y(this.entity, e));
+		} catch (i) {
+			if (e.after && r(i)) {
+				let { after: r, ...i } = e;
+				t = await o(y(this.entity, i)), n = !0;
+			} else throw i;
 		}
-		return this.refs.merge(n.$refs), {
-			data: n.data.map((e) => _(e)),
-			meta: n.meta,
+		return this.refs.merge(t.$refs), {
+			data: t.data.map((e) => _(e)),
+			meta: t.meta,
 			$refs: this.refs.all(),
-			reset: r
+			reset: n
 		};
 	}
 	async create(e) {
@@ -109,7 +109,7 @@ var b = class {
 		await this.deleteMany([e]);
 	}
 	async deleteMany(e) {
-		return e.length === 0 ? { count: 0 } : { count: (await o(`${this.entity}.__delete`, {
+		return e.length === 0 ? { count: 0 } : { count: (await a(`${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 o(`${this.entity}.__restore`, {
+		return e.length === 0 ? { count: 0 } : { count: (await a(`${this.entity}.__restore`, {
 			object_ids: e,
 			entity: this.entity
 		})).object_count ?? e.length };
@@ -233,39 +233,39 @@ function O(e, t, n) {
 //#endregion
 //#region src/hooks/useTabSearchMirror.ts
 function k(e) {
-	let t = r(), [n] = d();
+	let t = n(), [r] = d();
 	l(() => {
 		if (!e || t.enabled) return;
-		let r = c.getState(), i = r.findTabByPathname(e);
-		i && r.updateTabSearch(i.id, n.toString());
+		let n = c.getState(), i = n.findTabByPathname(e);
+		i && n.updateTabSearch(i.id, r.toString());
 	}, [
-		n,
+		r,
 		e,
 		t.enabled
 	]);
 }
 //#endregion
 //#region src/hooks/useRegisterScreenTab.ts
-function A(e, t, n, i) {
-	let a = r();
+function A(e, t, r, i) {
+	let a = n();
 	l(() => {
 		!e || a.enabled || c.getState().openTab({
 			pathname: e,
 			search: i,
 			title: t,
-			icon: n,
+			icon: r,
 			closable: !0
 		});
 	}, [
 		e,
 		t,
-		n,
+		r,
 		a.enabled
 	]);
 }
 function j(e, t, 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);
+	let r = e?.route, a = t ? i(e?.display?.name) || i(t.display.name_plural) : "", o = e?.display?.icon || t?.display.icon;
+	A(t ? r : void 0, a, o, n);
 }
 //#endregion
 //#region src/lib/filters.ts
@@ -374,36 +374,36 @@ function V(e, t) {
 //#endregion
 //#region src/api/status.ts
 async function H(e, t, n, r, i) {
-	let a = {
+	let o = {
 		status_group_code: n,
 		status_code: r
 	};
-	i != null && (a.note = i);
-	let s = (await o(`${e}.__update`, {
+	i != null && (o.note = i);
+	let s = (await a(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
-		fields: { $statuses: [a] }
+		fields: { $statuses: [o] }
 	})).result?.rows?.[0]?.$statuses ?? [];
 	return s.find((e) => e.group_code === n) ?? s[0];
 }
 //#endregion
 //#region src/hooks/useObjectStatus.ts
-function U(e, t) {
+function U(e, n) {
 	let r = m();
 	return p({
-		mutationFn: ({ groupCode: n, statusCode: r, note: i }) => H(e, t, n, r, i),
+		mutationFn: ({ groupCode: t, statusCode: r, note: i }) => H(e, n, t, r, i),
 		onSuccess: () => {
 			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
 		onError: (e) => {
-			n.error(e.message);
+			t.error(e.message);
 		}
 	});
 }
 //#endregion
 //#region src/api/properties.ts
 async function W(e, t, n, r) {
-	let i = (await o(`${e}.__update`, {
+	let i = (await a(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
 		fields: { $properties: [{
@@ -414,7 +414,7 @@ async function W(e, t, n, r) {
 	return i.find((e) => e.property_code === n) ?? i[0];
 }
 async function G(e, t, n) {
-	await o(`${e}.__update`, {
+	await a(`${e}.__update`, {
 		object_ids: [t],
 		entity: e,
 		fields: { $properties: [{
@@ -425,27 +425,27 @@ async function G(e, t, n) {
 }
 //#endregion
 //#region src/hooks/useProperties.ts
-function K(e, t) {
+function K(e, n) {
 	let r = m();
 	return p({
-		mutationFn: ({ propertyCode: n, value: r }) => W(e, t, n, r),
+		mutationFn: ({ propertyCode: t, value: r }) => W(e, n, t, r),
 		onSuccess: () => {
 			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
 		onError: (e) => {
-			n.error(e.message);
+			t.error(e.message);
 		}
 	});
 }
-function q(e, t) {
+function q(e, n) {
 	let r = m();
 	return p({
-		mutationFn: (n) => G(e, t, n),
+		mutationFn: (t) => G(e, n, t),
 		onSuccess: () => {
 			r.invalidateQueries({ queryKey: ["entity-item", e] });
 		},
 		onError: (e) => {
-			n.error(e.message);
+			t.error(e.message);
 		}
 	});
 }