@declarion/react 0.15.0 → 0.22.0

package/dist-lib/lib/actions.d.ts

@@ -1,4 +1,17 @@
-import type { Action, ActionCondition, LocalizedString, Schema } from "../types/schema";
+import type { Action, ActionCondition, Entity, LocalizedString, Schema } from "../types/schema";
+/**
+ * rowDetailId builds the detail-route id for a row - the value an href's
+ * `${id}` placeholder and a detail screen's `:id` segment receive - addressing
+ * it by the entity's REAL primary key (any single field or a composite key), so
+ * an entity whose PK is not named `id` (e.g. `schedule.code`) resolves correctly
+ * instead of emitting an empty `${id}`. Falls back to a raw `id` lookup only
+ * when no entity is in scope (defensive; an href dispatch always has one) or the
+ * row has no resolvable PK yet (an optimistic placeholder).
+ *
+ * Single source of truth for row -> detail-id, shared by ResponsiveActionBar
+ * (action_layout dispatch) and ActionButton (flat href dispatch).
+ */
+export declare function rowDetailId(row: Record<string, unknown> | undefined, entity: Entity | undefined): string;
 /**
  * Evaluates action conditions against row data.
  * Returns true if the action is available (all conditions pass).
@@ -141,29 +154,34 @@ export declare function filterLayoutForSlot(layout: ResolvedActionLayoutNode[],
     excludeIf?: (action: Action) => boolean;
 }): ResolvedActionLayoutNode[];
 /**
- * True when an action should be treated as requiring a row selection.
+ * True when an action needs at least one selected row to be meaningful, so a
+ * surface (the list toolbar) greys it while nothing is selected and enables it
+ * once a selection exists.
  *
- * THIS IS A PROXY, not the canonical rule. The canonical "requires
- * selection" answer is derived per dispatch mode (see docs/dsl.md §16.6.2:
- * `handler.invoke`, association semantics, `href ${id}`). The SDK cannot
- * evaluate that rule - the resolved-action wire format carries no `invoke`
- * value, and two of the five modes (`ui_steps`, `widget`) have no
- * derivation at all. So the SDK stands in slot membership: an action is
- * selection-mode iff its `visibility` includes `list_floatbar`.
+ * The server derives this from the handler's id-arity contract (a handler that
+ * cannot run without object IDs - not allow_no_objects, not invoke=unbound),
+ * association mode, or an href `${id}` row-link, and emits it as
+ * `requires_selection`. When the field is PRESENT it is authoritative.
  *
- * This matches the platform's authoring guidance - the loader's
- * `bulk_selection_required`-removal error tells authors to "use
- * visibility: [list_floatbar] for selection-mode actions" - so the proxy
- * agrees with the canonical rule for every guideline-following schema
- * (a mis-declared schema can diverge). Full rationale, the divergence
- * case, and the planned hybrid replacement: docs/architecture.md
- * "List Toolbar Selection Model".
+ * When ABSENT (an older server, or the `widget`/`ui_steps` modes the server
+ * does not derive) we fall back to the historical proxy: slot membership in
+ * `list_floatbar`. Absent MUST NOT be read as false, or every handler action
+ * would silently read as page-level against an older server.
  *
- * Drives list-toolbar state: a selection-mode action renders disabled
- * while no rows are selected, and moves to the floatbar (not the static
- * toolbar) once a selection exists.
+ * See docs/architecture.md "List Toolbar Selection Model" and plan
+ * 2026-06-22-toolbar-action-slots-and-id-arity.md.
  */
 export declare function actionRequiresSelection(action: Action): boolean;
+/**
+ * True when the action declares the `list_floatbar` (selection bar) slot.
+ *
+ * This is the OLD body of actionRequiresSelection, kept ONLY to decide
+ * toolbar/floatbar de-duplication: an action that opts into the floatbar is
+ * rendered there on selection, so the static toolbar drops it to avoid a
+ * double-render. It is NOT the selection predicate - greying is driven by
+ * actionRequiresSelection (the accurate server signal).
+ */
+export declare function actionInFloatbarSlot(action: Action): boolean;
 /**
  * Walks a ResolvedActionLayoutNode[] and sets `enabled: false` plus the
  * given `reason` on every leaf whose action satisfies `predicate`. Groups

package/dist-lib/testing.d.ts

@@ -0,0 +1,66 @@
+import { type ReactElement } from "react";
+import { type RenderResult } from "@testing-library/react";
+import { QueryClient } from "@tanstack/react-query";
+import { type ActionExecuteRequest, type ActionExecuteResponse } from "./api/data";
+import type { Schema } from "./types/schema";
+import type { 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
+ *  envelope - it does NOT sniff for an envelope shape, so a domain result like
+ *  { status: "closed" } keeps its result intact. Simulate a failure by throwing
+ *  from a function result. The union avoids `unknown` so the function form keeps
+ *  its typed `body` parameter at consumer call sites. */
+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. */
+export interface EntityDataFixture {
+    rows: Record<string, unknown>[];
+    meta?: Partial<ListMeta>;
+    refs?: Refs;
+}
+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 -> { [id]: row }; resolves useEntityItem. */
+    entityItems?: Record<string, Record<string, Record<string, unknown>>>;
+    /** 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 "/". */
+    route?: string;
+}
+export interface RenderWithDeclarionResult extends RenderResult {
+    /** The live QueryClient, for advanced cache assertions or manual refetch. */
+    queryClient: QueryClient;
+}
+/** Build a valid Schema from a partial - fills the required empty maps so a
+ *  consumer only declares the entities/screens its test needs. */
+export declare function schemaFixture(partial?: Partial<Schema>): Schema;
+/** Build the ListResponse envelope the real list hooks consume, from rows +
+ *  optional meta overrides. Defaults meta to an exact count of the row set. */
+export declare function entityDataFixture(rows: Record<string, unknown>[], meta?: Partial<ListMeta>, refs?: Refs): ListResponse;
+/** Typed pass-through for an action-result map (ergonomic + future-proof seam). */
+export declare function actionResults(map: Record<string, ActionResult>): Record<string, ActionResult>;
+/**
+ * Build a FULL action-dispatch envelope for a stub - so a render test can drive
+ * ActionRunner's NON-success toasts (status "partial" / "skipped" / "accepted"
+ * with success / errors / skipped arrays), which a plain result payload cannot
+ * express. A plain actionResults value stays the result payload (wrapped as
+ * success); only an actionEnvelope() value is forwarded verbatim, so a domain
+ * result with a `status` field is never mistaken for an envelope.
+ */
+export declare function actionEnvelope(env: Partial<ActionExecuteResponse> & {
+    status: string;
+}): ActionResult;
+/** Clear every harness seam + the seeded auth state. Auto-registered as an
+ *  afterEach when the test runner exposes one (vitest/jest globals); exported
+ *  so a runner without globals can call it explicitly. */
+export declare function cleanupDeclarion(): void;
+/**
+ * Render a consumer screen under the SDK's real providers with fixtures seeded
+ * through the read/action seams. Returns the testing-library result plus the
+ * live queryClient.
+ */
+export declare function renderWithDeclarion(ui: ReactElement, opts?: RenderWithDeclarionOptions): RenderWithDeclarionResult;

package/dist-lib/testing.js

@@ -0,0 +1,147 @@
+import { Pt as e, ct as t, lt as n, t as r, tt as i, ut as a } from "./ActionRunner-C2A73D9b.js";
+import { MemoryRouter as o } from "react-router-dom";
+import { QueryClient as s, QueryClientProvider as c } from "@tanstack/react-query";
+import { Toaster as l } from "sonner";
+import { jsx as u, jsxs as d } from "react/jsx-runtime";
+import { render as f } from "@testing-library/react";
+//#region src/testing.tsx
+function p(e = {}) {
+	return {
+		languages: [],
+		structures: {},
+		entities: {},
+		screens: {},
+		navigation: [],
+		actions: {},
+		enums: {},
+		parameters: {},
+		...e
+	};
+}
+function m(e, t = {}, n) {
+	return {
+		data: e,
+		meta: {
+			total: t.total ?? e.length,
+			page: t.page ?? 1,
+			per_page: t.per_page ?? 50,
+			total_pages: t.total_pages ?? 1,
+			has_more: t.has_more ?? !1,
+			count_mode: t.count_mode ?? "exact"
+		},
+		...n === void 0 ? {} : { $refs: n }
+	};
+}
+function h(e) {
+	return e;
+}
+var g = Symbol("declarion.testing.actionEnvelope");
+function _(e) {
+	return {
+		...e,
+		[g]: !0
+	};
+}
+function v(e) {
+	if (e && typeof e == "object" && e[g]) {
+		let t = { ...e };
+		return delete t[g], t;
+	}
+	return {
+		status: "success",
+		result: e
+	};
+}
+function y() {
+	let t = {
+		id: "test-tenant",
+		code: "test",
+		name: "Test",
+		role: "admin"
+	}, n = {
+		id: "test-user",
+		email: "test@example.com",
+		display_name: "Test User",
+		is_active: !0,
+		roles: ["admin"],
+		permissions: ["*"],
+		tenant: t,
+		created_at: "2026-01-01T00:00:00Z",
+		updated_at: "2026-01-01T00:00:00Z"
+	};
+	e.getState().setUser(n, t);
+}
+function b(e) {
+	if (e === void 0) return { rows: [] };
+	if (Array.isArray(e)) return { rows: e };
+	if (Array.isArray(e.data)) {
+		let t = e;
+		return {
+			rows: t.data,
+			meta: t.meta,
+			refs: t.$refs
+		};
+	}
+	return e;
+}
+function x(e) {
+	let r = e.entityData ?? {};
+	a((e, t) => {
+		let n = r[e], i = b(n), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
+		return t.count === "only" ? {
+			data: [],
+			meta: {
+				page: 1,
+				per_page: a,
+				total: o,
+				total_pages: i.meta?.total_pages ?? Math.max(1, Math.ceil(o / a)),
+				count_mode: i.meta?.count_mode ?? "exact"
+			}
+		} : {
+			data: i.rows,
+			meta: {
+				page: i.meta?.page ?? 1,
+				per_page: a,
+				has_more: i.meta?.has_more ?? !1
+			},
+			...i.refs === void 0 ? {} : { $refs: i.refs }
+		};
+	});
+	let o = e.entityItems ?? {};
+	n((e, t) => {
+		let n = typeof t == "string" ? t : i(t);
+		return { data: o[e]?.[n] };
+	});
+	let s = e.actionResults ?? {};
+	t(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 v(typeof n == "function" ? await n(t) : n);
+	});
+}
+function S() {
+	a(null), n(null), t(null), e.setState({
+		user: null,
+		isAuthenticated: !1,
+		activeTenant: null,
+		tenants: []
+	});
+}
+function C(e, t = {}) {
+	let n = new s({ defaultOptions: { queries: {
+		retry: !1,
+		gcTime: Infinity
+	} } });
+	y(), n.setQueryData(["schema", !0], t.schema ?? p()), x(t);
+	let i = f(/* @__PURE__ */ d(c, {
+		client: n,
+		children: [/* @__PURE__ */ u(o, {
+			initialEntries: [t.route ?? "/"],
+			children: /* @__PURE__ */ u(r, { children: e })
+		}), /* @__PURE__ */ u(l, {})]
+	}));
+	return Object.assign(i, { queryClient: n });
+}
+typeof afterEach == "function" && afterEach(() => S());
+//#endregion
+export { _ as actionEnvelope, h as actionResults, S as cleanupDeclarion, m as entityDataFixture, C as renderWithDeclarion, p as schemaFixture };

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

@@ -384,6 +384,7 @@ export declare function extractPkValues(entity: Entity, record: Record<string, u
 export declare function pkValuePartsToId(values: string[]): string;
 export declare function pkValuesToId(pkValues: PkValues): string;
 export declare function pkValuesToDetailId(entity: Entity, pkValues: PkValues): string;
+export declare function singlePkValues(entity: Entity, value: string): PkValues | undefined;
 export declare function pkValuesFromId(id: string, expectedCount: number): string[] | null;
 export declare function resolveDetailRoute(list: Pick<Screen, "detail_screen"> | undefined, entity: Pick<Entity, "detail_screen"> | undefined, allScreens: Record<string, {
     route?: string;
@@ -818,6 +819,16 @@ export interface Action {
      */
     resolved_hidden_defaults?: Record<string, unknown>;
     ui_steps?: UIStep[];
+    /**
+     * Server-derived: the action needs at least one selected row to be
+     * meaningful (the list toolbar greys it while nothing is selected). Derived
+     * from the handler's id-arity contract (cannot run without object IDs),
+     * association mode, or an href `${id}` row-link. ABSENT means the server did
+     * not derive it (older server, or widget/ui_steps modes) - consumers MUST
+     * fall back to the list_floatbar slot proxy, NOT treat absent as false. See
+     * actionRequiresSelection in lib/actions.ts.
+     */
+    requires_selection?: boolean;
 }
 export interface LanguageDef {
     code: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.15.0",
+  "version": "0.22.0",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",
@@ -25,6 +25,11 @@
       "import": "./dist-lib/vite/index.js",
       "default": "./dist-lib/vite/index.js"
     },
+    "./testing": {
+      "types": "./dist-lib/testing.d.ts",
+      "import": "./dist-lib/testing.js",
+      "default": "./dist-lib/testing.js"
+    },
     "./styles.css": "./dist-lib/declarion-react.css"
   },
   "files": [
@@ -36,9 +41,15 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@testing-library/react": "^16.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
@@ -57,11 +68,11 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.4.0",
-    "lucide-react": "^1.18.0",
+    "lucide-react": "^1.21.0",
     "mdast-util-to-string": "^4.0.0",
     "monaco-editor": "^0.55.1",
     "react-markdown": "^10.1.0",
-    "react-router-dom": "^7.17.0",
+    "react-router-dom": "^7.18.0",
     "react-textarea-autosize": "^8.5.9",
     "recharts": "^3.8.1",
     "remark-breaks": "^4.0.0",
@@ -96,7 +107,7 @@
     "tailwindcss": "^4.3.1",
     "tsc-alias": "^1.8.17",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.1",
+    "typescript-eslint": "^8.62.0",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"
   },
@@ -108,7 +119,7 @@
     "check:pkg": "publint run",
     "lint": "tsc --noEmit && eslint src --max-warnings=0",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage --coverage.include='src/**'",
+    "test:coverage": "vitest run --coverage",
     "preview": "vite preview"
   }
 }