@declarion/react 0.29.0 → 0.31.1

package/dist-lib/testing.d.ts

@@ -1,6 +1,7 @@
 import { type ReactElement, type ReactNode } from "react";
 import { type RenderResult } from "@testing-library/react";
 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";
@@ -30,6 +31,8 @@ export interface RenderWithDeclarionOptions {
     actionResults?: Record<string, ActionResult>;
     /** Initial path for the memory router (e.g. "/replay/abc/compare"). Default "/". */
     route?: string;
+    /** Optional responsive viewport seam for component tests that assert phone/tablet behavior. */
+    viewport?: ResponsiveViewport;
 }
 export interface RenderWithDeclarionResult extends RenderResult {
     /** The live QueryClient, for advanced cache assertions or manual refetch. */

package/dist-lib/testing.js

@@ -1,12 +1,12 @@
-import { H as e, X as t, Y as n, Z as r, mt as i, t as a } from "./ActionRunner-DtUDeH4F.js";
-import { useState as o } from "react";
-import { MemoryRouter as s } from "react-router-dom";
-import { QueryClient as c, QueryClientProvider as l } from "@tanstack/react-query";
-import { Toaster as u } from "sonner";
-import { jsx as d, jsxs as f } from "react/jsx-runtime";
-import { render as p } from "@testing-library/react";
+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 { useState as s } from "react";
+import { MemoryRouter as c } from "react-router-dom";
+import { QueryClient as l, QueryClientProvider as u } from "@tanstack/react-query";
+import { Toaster as d } from "sonner";
+import { jsx as f, jsxs as p } from "react/jsx-runtime";
+import { render as m } from "@testing-library/react";
 //#region src/testing.tsx
-function m(e = {}) {
+function h(e = {}) {
 	return {
 		languages: [],
 		structures: {},
@@ -19,7 +19,7 @@ function m(e = {}) {
 		...e
 	};
 }
-function h(e, t = {}, n) {
+function g(e, t = {}, n) {
 	return {
 		data: e,
 		meta: {
@@ -33,27 +33,27 @@ function h(e, t = {}, n) {
 		...n === void 0 ? {} : { $refs: n }
 	};
 }
-function g(e) {
+function _(e) {
 	return e;
 }
-var _ = Symbol("declarion.testing.actionEnvelope");
-function v(e) {
+var v = Symbol("declarion.testing.actionEnvelope");
+function y(e) {
 	return {
 		...e,
-		[_]: !0
+		[v]: !0
 	};
 }
-function y(e) {
-	if (e && typeof e == "object" && e[_]) {
+function b(e) {
+	if (e && typeof e == "object" && e[v]) {
 		let t = { ...e };
-		return delete t[_], t;
+		return delete t[v], t;
 	}
 	return {
 		status: "success",
 		result: e
 	};
 }
-function b() {
+function x() {
 	let e = {
 		id: "test-tenant",
 		code: "test",
@@ -70,9 +70,9 @@ function b() {
 		created_at: "2026-01-01T00:00:00Z",
 		updated_at: "2026-01-01T00:00:00Z"
 	};
-	i.getState().setUser(t, e);
+	a.getState().setUser(t, e);
 }
-function x(e) {
+function S(e) {
 	if (e === void 0) return { rows: [] };
 	if (Array.isArray(e)) return { rows: e };
 	if (Array.isArray(e.data)) {
@@ -85,10 +85,10 @@ function x(e) {
 	}
 	return e;
 }
-function S(i) {
-	let a = i.entityData ?? {};
-	r((e, t) => {
-		let n = a[e], r = x(n), i = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
+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" ? {
 			data: [],
 			meta: {
@@ -108,62 +108,65 @@ function S(i) {
 			...r.refs === void 0 ? {} : { $refs: r.refs }
 		};
 	});
-	let o = i.entityItems ?? {};
-	t((t, n) => {
+	let o = t.entityItems ?? {};
+	n((t, n) => {
 		let r = typeof n == "string" ? n : e(n);
 		return { data: o[t]?.[r] };
 	});
-	let s = i.actionResults ?? {};
-	n(async (e, t) => {
+	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];
-		return y(typeof n == "function" ? await n(t) : n);
+		return b(typeof n == "function" ? await n(t) : n);
 	});
 }
-function C() {
-	r(null), t(null), n(null), i.setState({
+function w() {
+	i(null), n(null), r(null), a.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
 		tenants: []
 	});
 }
-function w(e, t = {}) {
-	let n = new c({ defaultOptions: { queries: {
+function T(e, n = {}) {
+	let r = new l({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
 	} } });
-	b(), n.setQueryData(["schema", !0], t.schema ?? m()), S(t);
-	let r = p(/* @__PURE__ */ f(l, {
-		client: n,
-		children: [/* @__PURE__ */ d(s, {
-			initialEntries: [t.route ?? "/"],
-			children: /* @__PURE__ */ d(a, { children: e })
-		}), /* @__PURE__ */ d(u, {})]
-	}));
-	return Object.assign(r, { queryClient: n });
+	x(), r.setQueryData(["schema", !0], n.schema ?? h()), C(n);
+	let i = /* @__PURE__ */ p(u, {
+		client: r,
+		children: [/* @__PURE__ */ f(c, {
+			initialEntries: [n.route ?? "/"],
+			children: /* @__PURE__ */ f(o, { children: e })
+		}), /* @__PURE__ */ f(d, {})]
+	}), a = m(n.viewport ? /* @__PURE__ */ f(t, {
+		viewportOverride: n.viewport,
+		children: i
+	}) : i);
+	return Object.assign(a, { queryClient: r });
 }
-function T({ children: e, authenticated: t = !0, ...n }) {
-	let [r] = o(() => {
-		let e = new c({ defaultOptions: { queries: {
+function E({ children: e, authenticated: t = !0, ...n }) {
+	let [r] = s(() => {
+		let e = new l({ defaultOptions: { queries: {
 			retry: !1,
 			gcTime: Infinity
 		} } });
-		return t ? (b(), e.setQueryData(["schema", !0], n.schema ?? m())) : i.setState({
+		return t ? (x(), e.setQueryData(["schema", !0], n.schema ?? h())) : a.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
 			tenants: []
-		}), S(n), e;
+		}), C(n), e;
 	});
-	return /* @__PURE__ */ f(l, {
+	return /* @__PURE__ */ p(u, {
 		client: r,
-		children: [/* @__PURE__ */ d(s, {
+		children: [/* @__PURE__ */ f(c, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ d(a, { children: e })
-		}), /* @__PURE__ */ d(u, {})]
+			children: /* @__PURE__ */ f(o, { children: e })
+		}), /* @__PURE__ */ f(d, {})]
 	});
 }
-typeof afterEach == "function" && afterEach(() => C());
+typeof afterEach == "function" && afterEach(() => w());
 //#endregion
-export { T as PreviewHarness, v as actionEnvelope, g as actionResults, C as cleanupDeclarion, h as entityDataFixture, w as renderWithDeclarion, m as schemaFixture };
+export { E as PreviewHarness, y as actionEnvelope, _ as actionResults, w as cleanupDeclarion, g as entityDataFixture, T as renderWithDeclarion, h as schemaFixture };

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

@@ -186,6 +186,7 @@ export interface ChildQuickAdd {
 }
 export interface ChildDisplay {
     name: LocalizedString;
+    description?: LocalizedString;
     icon?: string;
     mode?: ChildDisplayMode;
     columns?: string[];
@@ -268,6 +269,7 @@ export interface ParameterDef {
 }
 export interface AssociationDisplay {
     name?: LocalizedString;
+    description?: LocalizedString;
     icon?: string;
 }
 export interface AssociationDef {
@@ -294,6 +296,15 @@ export interface OpSet {
     write?: boolean;
     delete?: boolean;
 }
+export interface CardSpec {
+    title_field?: string;
+    subtitle_field?: string;
+    badge_fields?: string[];
+    fields?: string[];
+    meta_fields?: string[];
+    hide_empty_fields?: boolean;
+    max_body_fields?: number;
+}
 export interface Entity {
     table: string;
     primary_key?: string[];
@@ -310,6 +321,7 @@ export interface Entity {
         display_template?: string;
         empty_state?: EmptyStateDef;
     };
+    card?: CardSpec;
     fields: OrderedMap<EntityField>;
     soft_delete?: string;
     tenant_key?: string;
@@ -518,6 +530,32 @@ export interface ScreenVisibility {
     required_permission: string;
     source: string;
 }
+export type ViewportKey = "phone" | "tablet" | "desktop";
+export type ListPresentation = "table" | "cards";
+export type RecordListPresentation = "split" | "drilldown" | "stacked";
+export type DetailTabsPresentation = "sections" | "scroll";
+export type DetailSidebarPresentation = "inline" | "hidden";
+export type RelatedRecordsPresentation = "cards" | "table";
+export interface ResponsiveDetailLayout {
+    header_card?: boolean;
+    tabs?: DetailTabsPresentation;
+    sidebar?: DetailSidebarPresentation;
+    related_records?: RelatedRecordsPresentation;
+}
+export interface ResponsiveListBranch {
+    presentation?: ListPresentation;
+}
+export interface ResponsiveDetailBranch {
+    header_card?: boolean;
+    tabs?: DetailTabsPresentation;
+}
+export interface ScreenResponsiveViewport {
+    presentation?: ListPresentation | RecordListPresentation;
+    layout?: ResponsiveDetailLayout;
+    list?: ResponsiveListBranch;
+    detail?: ResponsiveDetailBranch;
+}
+export type ScreenResponsive = Partial<Record<ViewportKey, ScreenResponsiveViewport>>;
 export interface Screen {
     type: "list" | "detail" | "custom" | "record_list";
     entity?: string;
@@ -536,10 +574,15 @@ export interface Screen {
     visibility?: ScreenVisibility;
     display?: {
         name: LocalizedString;
+        /** Localized explanation of the screen, surfaced via the list-header info
+         *  affordance (falls back to the entity description). Optional. */
+        description?: LocalizedString;
         icon: string;
     };
     columns?: string[];
     default_columns?: string[];
+    card?: CardSpec;
+    responsive?: ScreenResponsive;
     filters?: string[];
     default_filters?: string[];
     search_fields?: string[];
@@ -617,6 +660,7 @@ export interface ActivityRailConfig {
 export interface ViewDefinition {
     code: string;
     name: LocalizedString;
+    description?: LocalizedString;
     icon?: string;
     filters?: Array<{
         field: string;
@@ -806,11 +850,12 @@ export interface Action {
          */
         shortcut?: string;
         /**
-         * Localized help text for tooltip/popover.
-         * Reason: separate from display.name so the title stays terse while a
-         * longer explanation surfaces on hover.
+         * Localized explanation of what the action does. Surfaces as the control
+         * tooltip (precedence: disabled-reason > description > name) and the
+         * ActionDialog subtitle. Optional; absent renders exactly as before.
+         * (Supersedes the removed `help` field - plan 2026-07-02 Decision 16.)
          */
-        help?: LocalizedString;
+        description?: LocalizedString;
     };
     visibility?: string[];
     confirmation?: LocalizedString;
@@ -874,6 +919,7 @@ export interface HandlerDef {
     entity?: string;
     display?: {
         name?: LocalizedString;
+        description?: LocalizedString;
         icon?: string;
     };
     params?: OrderedMap<HandlerParam>;