@declarion/react 0.32.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 { 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 { 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";
@@ -87,7 +87,7 @@ function S(e) {
 }
 function C(e) {
 	let r = e.entityData ?? {};
-	t((e, t) => {
+	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: [],
@@ -109,7 +109,7 @@ function C(e) {
 		};
 	});
 	let a = e.entityItems ?? {}, s = e.entityItemResponses ?? {};
-	o((e, t) => {
+	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;
@@ -118,14 +118,14 @@ function C(e) {
 		return { data: o };
 	});
 	let c = e.actionResults ?? {};
-	n(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() {
-	t(null), o(null), n(null), r.setState({
+	n(null), t(null), o(null), r.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,

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,51 +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;
-    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;
 }
-export interface BrandingThemeTypography {
-    font_display?: string;
-    body?: number;
-    page_title?: number;
-    table_cell?: number;
-    control?: number;
-    caption?: number;
+/**
+ * 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?: BrandingThemeTypography;
+    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;
@@ -230,6 +300,7 @@ export interface BrandingChrome {
         };
     };
     embed?: {
+        viewport?: BrandingViewport;
         surfaces?: {
             list?: BrandingSurfaceFlags;
             detail?: BrandingSurfaceFlags;
@@ -242,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
@@ -29,7 +43,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;
@@ -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;
@@ -413,6 +428,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;

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

@@ -1,5 +1,5 @@
-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 { 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";
@@ -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 o(`/api/data/${this.entity}?${t.toString()}`)).data);
 	}
 	async list(e = {}) {
-		let n, i = !1;
+		let t, n = !1;
 		try {
-			n = await t(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;
-			} 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: i
+			reset: n
 		};
 	}
 	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 s(`${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 s(`${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 };
@@ -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) {
@@ -232,40 +232,40 @@ function O(e, t, n) {
 }
 //#endregion
 //#region src/hooks/useTabSearchMirror.ts
-function k(t) {
-	let n = e(), [r] = d();
+function k(e) {
+	let t = n(), [r] = d();
 	l(() => {
-		if (!t || n.enabled) return;
-		let e = c.getState(), i = e.findTabByPathname(t);
-		i && e.updateTabSearch(i.id, r.toString());
+		if (!e || t.enabled) return;
+		let n = c.getState(), i = n.findTabByPathname(e);
+		i && n.updateTabSearch(i.id, r.toString());
 	}, [
 		r,
-		t,
-		n.enabled
+		e,
+		t.enabled
 	]);
 }
 //#endregion
 //#region src/hooks/useRegisterScreenTab.ts
-function A(t, n, r, i) {
-	let a = e();
+function A(e, t, r, i) {
+	let a = n();
 	l(() => {
-		!t || a.enabled || c.getState().openTab({
-			pathname: t,
+		!e || a.enabled || c.getState().openTab({
+			pathname: e,
 			search: i,
-			title: n,
+			title: t,
 			icon: r,
 			closable: !0
 		});
 	}, [
+		e,
 		t,
-		n,
 		r,
 		a.enabled
 	]);
 }
 function j(e, t, n) {
-	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);
+	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
@@ -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 {
@@ -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 o = (await s(`${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 o.find((e) => e.group_code === n) ?? o[0];
+	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 s(`${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 s(`${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);
 		}
 	});
 }