@declarion/react 0.12.4 → 0.19.0

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

@@ -141,29 +141,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-F1HBBKyQ.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/api.d.ts

@@ -68,6 +68,13 @@ export declare class ApiError extends Error {
  */
 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";
 /** 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;
@@ -271,6 +278,13 @@ export interface V2Meta {
     limit: number;
     has_more: boolean;
     cursor?: string;
+    /** How `total` was produced: "exact" or "estimated". Absent when no count
+     *  was requested. A cross-store cursor total is always "estimated". */
+    count_mode?: string;
+    /** True when a count WAS requested but abandoned because the cold-tier count
+     *  would exceed the interactive scan bound (BC4b). The data window still
+     *  loaded; render NO total ("~N") - distinct from a real `total: 0`. */
+    count_unknown?: boolean;
 }
 /**
  * Refs map: keyed by entity code (or $-prefixed virtual entity code),
@@ -316,6 +330,16 @@ export interface V2ListParams {
     limit?: number;
     after?: string;
     include_deleted?: boolean;
+    /** Request the (estimated) total alongside the window (`?count=with`). The
+     *  cursor UI sends this on the FIRST window only; later windows omit it. */
+    count?: boolean;
+    /** Screen code, so the server applies that screen's `fixed_filters` (a
+     *  cursor list of a `fixed_filters` view, e.g. the audit auth-log, needs
+     *  the same server-side prefilter the offset list gets). */
+    screen?: string;
+    /** Return display-bounded (truncated) values for list cells, matching the
+     *  offset list's `preview: true`. */
+    preview?: boolean;
 }
 /** Per-field resolved display unit codes. */
 export type Units = Record<string, string>;

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

@@ -363,6 +363,16 @@ export interface Entity {
      * docs/plans/2026-05-18-declarative-row-count.md.
      */
     count?: "exact" | "estimated";
+    /**
+     * Computed (server-side, never author-set) pagination mode the generated
+     * admin list MUST use: "offset" (numbered pages) or "cursor" (keyset /
+     * infinite scroll). "cursor" iff the entity declares `persistence.archive`
+     * AND the deployment has ClickHouse wired at boot - a cross-store hot+cold
+     * read cannot offset-paginate. Absent means "offset" (every plain Postgres /
+     * ClickHouse-only / ClickHouse-disabled-archive entity). The SDK branches the
+     * list UI on this. See docs/plans/2026-06-20-cross-store-list-cursor-pagination.md.
+     */
+    list_pagination?: "offset" | "cursor";
 }
 export interface ExportConfig {
     enabled?: boolean;
@@ -808,6 +818,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.12.4",
+  "version": "0.19.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": [
@@ -37,7 +42,13 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "@testing-library/react": "^16.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -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"
   }
 }