@declarion/react 0.48.2 → 0.49.0

package/dist-lib/testing.d.ts

@@ -15,6 +15,8 @@ import type { DataResponse, ListMeta, ListResponse, Refs } from "./types/api";
 export type ActionResult = ((body: ActionExecuteRequest) => unknown) | Record<string, unknown> | unknown[] | string | number | boolean | null;
 /** Rows plus optional meta + response-level `$refs` (ref/expanded-column data)
  *  for one entity's list/count fixture. */
+/** One entity's list fixture, or the failure its query returns. */
+export type EntityDataEntry = Record<string, unknown>[] | EntityDataFixture | ListResponse | Error;
 export interface EntityDataFixture {
     rows: Record<string, unknown>[];
     meta?: Partial<ListMeta>;
@@ -23,8 +25,10 @@ export interface EntityDataFixture {
 export interface RenderWithDeclarionOptions {
     /** Seeded into the schema query cache so useSchema resolves warm. Build with schemaFixture. */
     schema?: Schema;
-    /** entity -> rows, { rows, meta }, or an entityDataFixture() ListResponse; resolves useEntityData / useEntityCount. */
-    entityData?: Record<string, Record<string, unknown>[] | EntityDataFixture | ListResponse>;
+    /** entity -> rows, { rows, meta }, or an entityDataFixture() ListResponse.
+     *  An Error entry makes the query FAIL; a FUNCTION entry is called with the
+     *  request, so a filtered query can answer differently from an unfiltered one. */
+    entityData?: Record<string, EntityDataEntry | ((params: Record<string, unknown>) => EntityDataEntry)>;
     /** 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`. */
@@ -43,10 +47,21 @@ export interface RenderWithDeclarionOptions {
     screenCode?: string;
     /** Optional responsive viewport seam for component tests that assert phone/tablet behavior. */
     viewport?: ResponsiveViewport;
+    /** Called with every list request before it resolves. A screen decides what
+     *  to ASK for - which columns, which sort, whether to expand refs - and that
+     *  is invisible in the rendered output. */
+    onListRequest?: (entity: string, params: Record<string, unknown>) => void;
+    /** Mounts the screen inside an embed context, as the white-label iframe does:
+     *  the embed query string the host passes. Absent means the in-app render. */
+    embedQuery?: string;
 }
 export interface RenderWithDeclarionResult extends RenderResult {
     /** The live QueryClient, for advanced cache assertions or manual refetch. */
     queryClient: QueryClient;
+    /** Where the screen has navigated to, as `pathname + search + hash`. The
+     *  alternative is stubbing the navigate hook, which asserts that the screen
+     *  CALLED something rather than that the user arrived. */
+    location: () => string;
 }
 /** Build a valid Schema from a partial - fills the required empty maps so a
  *  consumer only declares the entities/screens its test needs. */

package/dist-lib/testing.js

@@ -1,12 +1,12 @@
-import { Dt as e, Et as t, Ot as n, er as r, jt as i, r as a, t as o, yt as s } from "./useCurrentScreen-BshVTPVq.js";
-import { useState as c } from "react";
-import { MemoryRouter as l } from "react-router";
-import { QueryClient as u, QueryClientProvider as d } from "@tanstack/react-query";
-import { Toaster as f } from "sonner";
-import { jsx as p, jsxs as m } from "react/jsx-runtime";
-import { render as h } from "@testing-library/react";
+import { Dt as e, Et as t, Ot as n, ft as r, jt as i, nr as a, r as o, t as s, yt as c } from "./useCurrentScreen-C5Oio-1G.js";
+import { useState as l } from "react";
+import { MemoryRouter as u, useLocation as d } from "react-router";
+import { QueryClient as f, QueryClientProvider as p } from "@tanstack/react-query";
+import { Toaster as m } from "sonner";
+import { jsx as h, jsxs as g } from "react/jsx-runtime";
+import { render as _ } from "@testing-library/react";
 //#region src/testing.tsx
-function g(e = {}) {
+function v(e = {}) {
 	return {
 		languages: [],
 		structures: {},
@@ -19,7 +19,7 @@ function g(e = {}) {
 		...e
 	};
 }
-function _(e, t = {}, n) {
+function y(e, t = {}, n) {
 	return {
 		data: e,
 		meta: {
@@ -33,27 +33,31 @@ function _(e, t = {}, n) {
 		...n === void 0 ? {} : { $refs: n }
 	};
 }
-function v(e) {
+function b(e) {
 	return e;
 }
-var y = Symbol("declarion.testing.actionEnvelope");
-function b(e) {
+var x = Symbol("declarion.testing.actionEnvelope");
+function S(e) {
 	return {
 		...e,
-		[y]: !0
+		[x]: !0
 	};
 }
-function x(e) {
-	if (e && typeof e == "object" && e[y]) {
+function C(e) {
+	if (e && typeof e == "object" && e[x]) {
 		let t = { ...e };
-		return delete t[y], t;
+		return delete t[x], t;
 	}
 	return {
 		status: "success",
 		result: e
 	};
 }
-function S() {
+function w({ into: e }) {
+	let t = d();
+	return e.current = `${t.pathname}${t.search}${t.hash}`, null;
+}
+function T() {
 	let e = {
 		id: "test-tenant",
 		code: "test",
@@ -72,7 +76,7 @@ function S() {
 	};
 	i.getState().setUser(t, e);
 }
-function C(e) {
+function E(e) {
 	if (e === void 0) return { rows: [] };
 	if (Array.isArray(e)) return { rows: e };
 	if (Array.isArray(e.data)) {
@@ -85,46 +89,50 @@ function C(e) {
 	}
 	return e;
 }
-function w(r) {
+function D(r) {
 	let i = r.entityData ?? {};
 	n((e, t) => {
-		let n = i[e], r = C(n), a = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
+		let n = t;
+		r.onListRequest?.(e, n);
+		let a = i[e], o = typeof a == "function" ? a(n) : a;
+		if (o instanceof Error) throw o;
+		let s = E(o), c = s.meta?.per_page ?? 50, l = s.meta?.total ?? s.rows.length;
 		return t.count === "only" ? {
 			data: [],
 			meta: {
 				page: 1,
-				per_page: a,
-				total: o,
-				total_pages: r.meta?.total_pages ?? Math.max(1, Math.ceil(o / a)),
-				count_mode: r.meta?.count_mode ?? "exact"
+				per_page: c,
+				total: l,
+				total_pages: s.meta?.total_pages ?? Math.max(1, Math.ceil(l / c)),
+				count_mode: s.meta?.count_mode ?? "exact"
 			}
 		} : {
-			data: r.rows,
+			data: s.rows,
 			meta: {
-				page: r.meta?.page ?? 1,
-				per_page: a,
-				has_more: r.meta?.has_more ?? !1
+				page: s.meta?.page ?? 1,
+				per_page: c,
+				has_more: s.meta?.has_more ?? !1
 			},
-			...r.refs === void 0 ? {} : { $refs: r.refs }
+			...s.refs === void 0 ? {} : { $refs: s.refs }
 		};
 	});
 	let a = r.entityItems ?? {}, o = r.entityItemResponses ?? {};
 	e((e, t) => {
-		let n = typeof t == "string" ? t : s(t), r = o[e]?.[n];
+		let n = typeof t == "string" ? t : c(t), r = o[e]?.[n];
 		if (r instanceof Error) throw r;
 		if (r !== void 0) return r;
 		let i = a[e]?.[n];
 		if (i instanceof Error) throw i;
 		return { data: i };
 	});
-	let c = r.actionResults ?? {};
+	let s = r.actionResults ?? {};
 	t(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 x(typeof n == "function" ? await n(t) : n);
+		if (!(e in s)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
+		let n = s[e];
+		return C(typeof n == "function" ? await n(t) : n);
 	});
 }
-function T() {
+function O() {
 	n(null), e(null), t(null), i.setState({
 		user: null,
 		isAuthenticated: !1,
@@ -132,48 +140,54 @@ function T() {
 		tenants: []
 	});
 }
-function E(e, t = {}) {
-	let n = new u({ defaultOptions: { queries: {
+function k(e, t = {}) {
+	let n = new f({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
 	} } });
-	S(), n.setQueryData(["schema", !0], t.schema ?? g()), w(t);
-	let i = t.screenCode ? /* @__PURE__ */ p(o, {
+	T(), n.setQueryData(["schema", !0], t.schema ?? v()), D(t);
+	let i = t.screenCode ? /* @__PURE__ */ h(s, {
 		code: t.screenCode,
 		children: e
-	}) : e, s = /* @__PURE__ */ m(d, {
+	}) : e, c = { current: t.route ?? "/" }, l = /* @__PURE__ */ g(p, {
 		client: n,
-		children: [/* @__PURE__ */ p(l, {
+		children: [/* @__PURE__ */ g(u, {
 			initialEntries: [t.route ?? "/"],
-			children: /* @__PURE__ */ p(a, { children: i })
-		}), /* @__PURE__ */ p(f, {})]
-	}), c = h(t.viewport ? /* @__PURE__ */ p(r, {
+			children: [/* @__PURE__ */ h(w, { into: c }), /* @__PURE__ */ h(o, { children: i })]
+		}), /* @__PURE__ */ h(m, {})]
+	}), d = t.embedQuery ? /* @__PURE__ */ h(r, {
+		query: t.embedQuery,
+		children: l
+	}) : l, y = _(t.viewport ? /* @__PURE__ */ h(a, {
 		viewportOverride: t.viewport,
-		children: s
-	}) : s);
-	return Object.assign(c, { queryClient: n });
+		children: d
+	}) : d);
+	return Object.assign(y, {
+		queryClient: n,
+		location: () => c.current
+	});
 }
-function D({ children: e, authenticated: t = !0, ...n }) {
-	let [r] = c(() => {
-		let e = new u({ defaultOptions: { queries: {
+function A({ children: e, authenticated: t = !0, ...n }) {
+	let [r] = l(() => {
+		let e = new f({ defaultOptions: { queries: {
 			retry: !1,
 			gcTime: Infinity
 		} } });
-		return t ? (S(), e.setQueryData(["schema", !0], n.schema ?? g())) : i.setState({
+		return t ? (T(), e.setQueryData(["schema", !0], n.schema ?? v())) : i.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
 			tenants: []
-		}), w(n), e;
+		}), D(n), e;
 	});
-	return /* @__PURE__ */ m(d, {
+	return /* @__PURE__ */ g(p, {
 		client: r,
-		children: [/* @__PURE__ */ p(l, {
+		children: [/* @__PURE__ */ h(u, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ p(a, { children: e })
-		}), /* @__PURE__ */ p(f, {})]
+			children: /* @__PURE__ */ h(o, { children: e })
+		}), /* @__PURE__ */ h(m, {})]
 	});
 }
-typeof afterEach == "function" && afterEach(() => T());
+typeof afterEach == "function" && afterEach(() => O());
 //#endregion
-export { D as PreviewHarness, b as actionEnvelope, v as actionResults, T as cleanupDeclarion, _ as entityDataFixture, E as renderWithDeclarion, g as schemaFixture };
+export { A as PreviewHarness, S as actionEnvelope, b as actionResults, O as cleanupDeclarion, y as entityDataFixture, k as renderWithDeclarion, v as schemaFixture };

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

@@ -33,24 +33,50 @@ export interface DataResponse<T = Record<string, unknown>> {
     data: T;
     $refs?: Refs;
 }
+/**
+ * A failure, in RFC 9457 Problem Details form - the one shape every Declarion
+ * carrier sends. `type` is the identifier to branch on; its last path segment is
+ * identical in every deployment. `title` is the sentence to SHOW: the server
+ * already rendered it in this caller's language, and the browser holds no
+ * catalogue to render one itself. A type's declared members are TOP-LEVEL, which
+ * is why this is an index signature and not a fixed shape.
+ */
 export interface ApiErrorBody {
-    error: {
-        message: string;
-        code: string;
-        field?: string;
-    };
-    /** Bulk operation item index (present on validation errors for array requests). */
-    index?: number;
+    type: string;
+    status?: number;
+    title: string;
+    /** This occurrence. A DIAGNOSTIC, not the headline - and absent for a failure nothing recognised. */
+    detail?: string;
+    instance?: string;
+    retryable: boolean;
+    [member: string]: unknown;
 }
 export declare class ApiError extends Error {
     status: number;
+    /** The identifier to compare - the type's last path segment, e.g. `entity.not_found`. */
     code: string;
+    /** The full `type`, e.g. `/errors/entity.not_found`. */
+    type: string;
+    /** Whether the same call can succeed later. From the DECLARATION, never computed from a status. */
+    retryable: boolean;
+    /** The diagnostic for this occurrence. Never the headline a user reads. */
+    detail?: string;
     /** Bulk operation item index (present on validation errors for array requests). */
     index?: number;
-    /** Raw JSON body for endpoints that return a non-standard error envelope (e.g. invoke:each batch). */
+    /** The untouched body, so a caller can re-detect a shape this class does not model. */
     raw?: unknown;
-    constructor(status: number, message: string, code: string, index?: number, raw?: unknown);
+    constructor(status: number, body: Partial<ApiErrorBody>, raw?: unknown);
+    /**
+     * A declared member of this error's type. ONE accessor, so the six known
+     * consumers (`constraint`, `row_version`, `did_you_mean`, `valid_parameters`,
+     * `threshold`, `width`) do not each invent an access pattern.
+     */
+    ext<T = unknown>(member: string): T | undefined;
 }
+/** The comparable identifier inside a `type`: its last path segment. */
+export declare function errorCodeOf(type: string | undefined): string;
+/** Whether a parsed JSON body is the platform's error object. */
+export declare function isApiErrorBody(body: unknown): body is ApiErrorBody;
 /**
  * Stable error codes for cursor-based list pagination. The server returns
  * these on ValidationError{Field:"after"} when an `after` token cannot be
@@ -68,15 +94,15 @@ export declare class ApiError extends Error {
  * direct apiFetch callers can recognise these codes to drive their own
  * retry logic.
  */
-export declare const CURSOR_SEMANTICS_MISMATCH = "cursor_semantics_mismatch";
-export declare const CURSOR_LOCALE_CHANGED = "cursor_locale_changed";
+export declare const CURSOR_SEMANTICS_MISMATCH = "cursor.semantics_mismatch";
+export declare const CURSOR_LOCALE_CHANGED = "cursor.locale_changed";
 /**
  * A cross-store (Postgres-hot / ClickHouse-cold) archive cursor that the server
  * could not decode for this read - a malformed token, a tenant/entity mismatch,
  * or a retired bespoke-archive cursor minted before the native-cursor release.
  * Same recovery contract as the other two: drop `after`, refetch window 1.
  */
-export declare const ARCHIVE_CURSOR_INVALID = "archive_cursor_invalid";
+export declare const ARCHIVE_CURSOR_INVALID = "cursor.archive_invalid";
 /** True if the error is a recoverable cursor-stale signal that warrants
  *  refetching page 1 instead of surfacing to the user. */
 export declare function isCursorStaleError(err: unknown): boolean;
@@ -533,3 +559,19 @@ export interface EnrichedRow extends RowData {
     $units?: Units;
     $evidence?: EvidenceVerdict;
 }
+/** readProblem is the ONE way this client reads a failing response.
+ *
+ *  It always consumes the body, even where only the status is acted on: an
+ *  unread body leaves its stream - and the connection under it - open in the
+ *  browser until garbage collection, and a page holding one never reaches
+ *  network idle. A `/reset` page sat with one open refresh response for exactly
+ *  that reason.
+ *
+ *  `raw` is the untouched body, which the batch re-detection still needs; `body`
+ *  is it only when it IS the error object. Two top-level shapes arrive here: a
+ *  flat error object HAS a `type`, and a processed batch result
+ *  (`{status, success, errors}`) is deliberately not an error. */
+export declare function readProblem(res: Response): Promise<{
+    raw: unknown;
+    body: Partial<ApiErrorBody>;
+}>;

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

@@ -102,6 +102,15 @@ export interface EntityField {
      */
     name?: string;
     type: string;
+    /**
+     * Computed and stamped by the server: whether a CROSS-store read can order by
+     * this field. Meaningful only where the entity's list_pagination is "cursor".
+     * Asked rather than re-derived here - a second copy of the backend's type
+     * allowlist drifts the day either side moves, and the symptom is an operator
+     * clicking a column header and getting a raw backend error in place of the
+     * table.
+     */
+    cross_store_sortable?: boolean;
     required?: boolean;
     primary?: boolean;
     auto?: boolean;
@@ -1018,7 +1027,6 @@ export interface HandlerDef {
         icon?: string;
     };
     params?: OrderedMap<HandlerParam>;
-    success_event?: string;
 }
 export interface Schema {
     languages: LanguageDef[];
@@ -1031,6 +1039,16 @@ export interface Schema {
     enums: Record<string, EnumDef>;
     parameters: Record<string, ParameterDef>;
     messages?: Record<string, LocalizedString>;
+    /**
+     * Declared error types, code -> title per language. For rendering a STORED
+     * code - on an agent turn, a job row, an audit row - in the reader's
+     * language. An error answering a request carries its own title in the
+     * response and needs none of this.
+     *
+     * Errors are NEVER declared under `messages`: a failure has a type, and a
+     * type has a title.
+     */
+    errors?: Record<string, LocalizedString>;
     areas?: AreaDef[];
     accents?: Record<string, AccentDef>;
     /**
@@ -1062,11 +1080,9 @@ export interface ClassificationTierDef {
     audit_on_read?: boolean;
     icon?: string;
     /**
-     * When true, the tier triggers stricter SoD controls: superadmin
-     * reveals emit a distinct audit code, tenant param
-     * `auth.superadmin_classification_bypass=false` disables the
-     * implicit bypass, role self-assignment is refused, transitive role
-     * inheritance is hard-errored at load. Plan §11 Decisions Log #20-22.
+     * When true, the tier triggers stricter SoD controls: a platform owner's
+     * reveal emits a distinct audit code, role self-assignment is refused, and
+     * transitive role inheritance is hard-errored at load.
      */
     sod_protected?: boolean;
 }