@declarion/react 0.26.4 → 0.27.0

package/dist-lib/lib/screen-back.d.ts

@@ -0,0 +1,72 @@
+import { type ReturnTarget, type TabItem } from "../stores/tabs";
+/** Drop a leading `?` so a search string matches the canonical `TabItem.search`
+ *  / `ReturnTarget.search` form (stored WITHOUT `?`). Empty in -> empty out. */
+export declare function stripLeadingQuestion(search: string | undefined | null): string;
+/** Re-attach the leading `?` for the router/`navigate` form, or `undefined`
+ *  when there is no query. The inverse of `stripLeadingQuestion`. */
+export declare function toRouterSearch(search: string | undefined): string | undefined;
+/** The current location at navigate time (canonical: `search` may carry `?`,
+ *  `hash` carries `#`). Sourced from `window.location` at the click. */
+export interface CaptureLocation {
+    pathname: string;
+    search?: string;
+    hash?: string;
+}
+/**
+ * Build the return target to stamp on the DESTINATION tab when navigating from
+ * `current` to `destinationPathname`. Returns `undefined` (no capture) when:
+ *   - the current path is not a same-origin in-app route,
+ *   - the current path is an excluded (auth) route,
+ *   - the destination shares the current PATHNAME (self guard, Invariant 7) -
+ *     a same-screen, different-query link must not self-stamp a Back.
+ *
+ * `originTab` supplies metadata (id/title/icon/screen) for switching to or
+ * reopening the origin; only the current location drives pathname/search/hash.
+ */
+export declare function captureReturnTarget(current: CaptureLocation, destinationPathname: string, originTab?: Pick<TabItem, "id" | "title" | "icon" | "screen">): ReturnTarget | undefined;
+/** The Back visibility intent, derived from a tab's `returnTo` alone (no tab
+ *  list needed). `hasOriginBack` drives an origin Back affordance;
+ *  `allowFallbackBack` permits a screen's static/parent fallback (false ONLY
+ *  for a menu-cleared `null`). */
+export interface BackVisibility {
+    hasOriginBack: boolean;
+    allowFallbackBack: boolean;
+}
+/**
+ * Interpret the tri-state `returnTo` for Back VISIBILITY:
+ *   - embed enabled -> never an origin Back; fallback allowed (embed has no tabs),
+ *   - `null` (menu-cleared) -> no origin Back AND no fallback (a menu-opened
+ *     screen has nowhere to return),
+ *   - a valid origin object -> origin Back,
+ *   - `undefined` / invalid object (deep-link) -> no origin Back, fallback allowed.
+ */
+export declare function resolveBackVisibility(returnTo: ReturnTarget | null | undefined, embedEnabled: boolean): BackVisibility;
+/** The resolved Back destination. `live` = the origin tab is still open (switch
+ *  to it); `reopen` = the origin tab was closed (reopen it). Both navigate to
+ *  the CAPTURED snapshot (pathname+search+hash). */
+export interface ResolvedBack {
+    kind: "live" | "reopen";
+    tabId?: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+    title?: string;
+    icon?: string;
+    screen?: string;
+}
+/**
+ * Resolve the Back DESTINATION from a tab's `returnTo` and the live tab list.
+ * Returns `null` when there is no valid origin (the caller then uses its
+ * fallback). The origin tab (live by `tabId`, else by `pathname`) decides only
+ * SWITCH vs REOPEN; the destination URL is always the CAPTURED snapshot. Embed
+ * yields `null` (Back is fallback-only in embed; no tab ops).
+ *
+ * Divergence from the plan's Invariant 5 (reasoned): the plan preferred the
+ * live tab's CURRENT search over the captured one, premised on every origin
+ * screen mirroring its URL into the tab store. That premise is false for custom
+ * screens (Compare, dashboards) with no per-page mirror, so preferring live
+ * search loses URL-encoded state (Business Case 3). The captured `returnTo` is
+ * exact at drill time ("where I came from"), so it is the single source of
+ * truth for the destination URL - no per-screen search mirror needed.
+ */
+export declare function resolveBackTarget(returnTo: ReturnTarget | null | undefined, tabs: TabItem[], embedEnabled: boolean): ResolvedBack | null;

package/dist-lib/stores/tabs.d.ts

@@ -1,5 +1,26 @@
 export type TabMode = "view" | "edit" | "create";
 export type TabCloseScope = "current" | "others" | "right" | "all";
+/**
+ * Origin-aware Back return target. The CANONICAL stored shape: `pathname` is an
+ * in-app path (no origin, starts `/` not `//`), `search` is the query string
+ * WITHOUT a leading `?` (matches `TabItem.search`), `hash` carries its leading
+ * `#`. Converted to the `?`-prefixed router form only at the navigate boundary.
+ *
+ * `hash` lives here but NOT on `TabItem` (which has no `hash` field): a closed
+ * origin tab with a hash is reopened via pathname+search, and the hash is
+ * applied only in the `navigate()` call. `tabId`/`title`/`icon`/`screen` are
+ * hints for switching to (or reopening) the origin tab. Never stores secrets,
+ * external URLs, or row data. See docs/plans/2026-06-29-origin-aware-back-navigation.md.
+ */
+export interface ReturnTarget {
+    pathname: string;
+    search?: string;
+    hash?: string;
+    tabId?: string;
+    title?: string;
+    icon?: string;
+    screen?: string;
+}
 export interface TabItem {
     id: string;
     pathname: string;
@@ -14,6 +35,7 @@ export interface TabItem {
     record?: Record<string, unknown>;
     mode?: TabMode;
     dirty?: boolean;
+    returnTo?: ReturnTarget | null;
 }
 interface TabState {
     tabs: TabItem[];
@@ -26,12 +48,24 @@ interface TabState {
     findTabByPathname: (pathname: string) => TabItem | undefined;
     updateTabTitle: (id: string, title: string) => void;
     updateTabSearch: (id: string, search: string) => void;
+    setReturnTarget: (id: string, rt: ReturnTarget | null) => void;
+    commitTabNavigation: (id: string, patch: {
+        search: string;
+        returnTo?: ReturnTarget | null;
+    }) => void;
     setDirty: (id: string, dirty: boolean) => void;
     setMode: (id: string, mode: TabMode) => void;
     updateTab: (id: string, patch: Partial<TabItem>) => void;
     setScope: (tenantId: string | null, userId: string | null) => void;
     hydrate: () => void;
 }
+/** True for an auth/chrome route that must never create a tab or be captured
+ *  as a Back origin. Shared by `openTab` and the origin-capture path. */
+export declare function isExcludedRoute(pathname: string): boolean;
+/** A same-origin in-app path: starts `/` but not `//` (the latter is a
+ *  protocol-relative external URL). The single guard reused on capture, on
+ *  snapshot load (localStorage is hostile), and in the tenant-landing peek. */
+export declare function isSameOriginPath(pathname: unknown): pathname is string;
 export declare function tabIdsForCloseScope(tabs: TabItem[], activeTabId: string | null, scope: TabCloseScope, targetId?: string): string[];
 export declare function peekTenantLandingPath(tenantId: string, userId: string): string | null;
 export declare const useTabStore: import("zustand").UseBoundStore<import("zustand").StoreApi<TabState>>;

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { J as e, V as t, X as n, Y as r, ft as i, t as a } from "./ActionRunner-B2e3Igpd.js";
+import { J as e, V as t, X as n, Y as r, ft as i, t as a } from "./ActionRunner-D9fJRkNV.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";

package/dist-lib/{value-D7fe0TEL.js → value-BQWyqKHC.js}

@@ -1,68 +1,11 @@
-import { Lt as e, Nt as t, Pt as n } from "./ActionRunner-B2e3Igpd.js";
+import { Lt as e, Nt as t, Pt as n } from "./ActionRunner-D9fJRkNV.js";
 import { useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
-//#region src/embed/file-src.ts
-var s = "/api/files";
-function c(e) {
-	if (typeof e != "object" || !e) return !1;
-	let t = e;
-	return typeof t.url == "string" && typeof t.proxy == "boolean";
-}
-function l(e, t) {
-	let n = encodeURIComponent(e);
-	return typeof t == "object" ? `${s}/${n}/derived/${encodeURIComponent(t.derivation)}/url` : `${s}/${n}/url`;
-}
-var u = class extends Error {
-	fileId;
-	key;
-	constructor(e, t) {
-		super(`derivation "${t}" of file ${e} is still generating`), this.fileId = e, this.key = t, this.name = "DerivationPendingError";
-	}
-};
-function d(e, t) {
-	return {
-		method: "GET",
-		credentials: "omit",
-		headers: { Authorization: `Bearer ${e}` },
-		signal: t
-	};
-}
-function f(e) {
-	return `${e}${e.includes("?") ? "&" : "?"}disposition=attachment`;
-}
-async function p(e, r) {
-	let i = await t(), a = await fetch(e, d(i, r));
-	if (a.status !== 401) return a;
-	n();
-	let o = await t();
-	return fetch(e, d(o, r));
-}
-async function m(t, n, r) {
-	if (!e()) throw Error("resolveEmbedFileSrc called outside embed token mode");
-	let i = await p(l(t, n), r);
-	if (i.status === 202 && typeof n == "object") throw new u(t, n.derivation);
-	if (!i.ok) throw Error(`embed file url request failed: ${i.status} ${i.statusText}`);
-	let a = await i.json();
-	if (!c(a)) throw Error("embed file url response is malformed");
-	if (!a.proxy) return {
-		url: a.url,
-		kind: "direct"
-	};
-	if (!a.url.startsWith("/api/files/")) throw Error(`embed file proxy: refusing non-files-route URL ${JSON.stringify(a.url)}`);
-	let o = await p(n === "download" ? f(a.url) : a.url, r);
-	if (!o.ok) throw Error(`embed file proxy fetch failed: ${o.status} ${o.statusText}`);
-	let s = await o.blob();
-	return {
-		url: URL.createObjectURL(s),
-		kind: "blob"
-	};
-}
-//#endregion
 //#region src/components/file-widgets/helpers.ts
-var h = ["thumb_200", "thumb_300"];
-function g() {
+var s = ["thumb_200", "thumb_300"];
+function c() {
 	return typeof navigator > "u" ? ["en"] : (navigator.languages?.length ? navigator.languages : [navigator.language]).filter((e) => typeof e == "string" && e.length > 0);
 }
-function _(e, t) {
+function l(e, t) {
 	for (let n of t) {
 		if (e[n]) return e[n];
 		let t = n.split("-")[0];
@@ -70,17 +13,17 @@ function _(e, t) {
 	}
 	for (let t of Object.values(e)) if (typeof t == "string" && t.length > 0) return t;
 }
-function v(e, t, n) {
+function u(e, t, n) {
 	if (t) return t;
 	let r = e?.metadata?.alt_text;
 	if (typeof r == "string" && r.length > 0) return r;
 	if (r && typeof r == "object" && !Array.isArray(r)) {
-		let e = _(Object.fromEntries(Object.entries(r).filter((e) => e[0].length > 0 && typeof e[1] == "string")), g());
+		let e = l(Object.fromEntries(Object.entries(r).filter((e) => e[0].length > 0 && typeof e[1] == "string")), c());
 		if (e) return e;
 	}
 	return n;
 }
-var y = new Set([
+var d = /* @__PURE__ */ new Set([
 	"image/png",
 	"image/jpeg",
 	"image/webp",
@@ -88,30 +31,30 @@ var y = new Set([
 	"image/avif",
 	"application/pdf"
 ]);
-function b(e) {
+function f(e) {
 	let t = e.content_type?.toLowerCase().split(";")[0]?.trim() ?? "";
-	return y.has(t);
+	return d.has(t);
 }
-function x(e) {
+function p(e) {
 	return e.url ?? e.presigned_url;
 }
-function S(e) {
-	return e.url ? T(e.url, "attachment") : e.presigned_url;
+function m(e) {
+	return e.url ? _(e.url, "attachment") : e.presigned_url;
 }
-function C(e, t) {
+function h(e, t) {
 	if (!e) return;
 	let n = e.derivations ?? {};
 	if (t && n[t]) return n[t];
-	for (let e of h) if (n[e]) return n[e];
+	for (let e of s) if (n[e]) return n[e];
 	return e.url ?? e.presigned_url;
 }
-function w(e, t) {
+function g(e, t) {
 	let n = e?.derivations ?? {};
 	if (t && n[t]) return { derivation: t };
-	for (let e of h) if (n[e]) return { derivation: e };
+	for (let e of s) if (n[e]) return { derivation: e };
 	return "preview";
 }
-function T(e, t) {
+function _(e, t) {
 	try {
 		let n = new URL(e, typeof window < "u" ? window.location.origin : "http://localhost");
 		return n.searchParams.set("disposition", t), /^https?:\/\//i.test(e) ? n.toString() : `${n.pathname}${n.search}${n.hash}`;
@@ -119,7 +62,7 @@ function T(e, t) {
 		return `${e}${e.includes("?") ? "&" : "?"}disposition=${t}`;
 	}
 }
-function E(e) {
+function v(e) {
 	let t = e?.metadata?.focal_point;
 	if (!t || typeof t != "object" || Array.isArray(t)) return null;
 	let n = t, r = typeof n.x == "number" ? n.x : NaN, i = typeof n.y == "number" ? n.y : NaN;
@@ -128,10 +71,10 @@ function E(e) {
 		y: i
 	};
 }
-function D(e) {
+function y(e) {
 	if (e) return `${e.x * 100}% ${e.y * 100}%`;
 }
-function O(e, t) {
+function b(e, t) {
 	return {
 		...e,
 		metadata: {
@@ -141,6 +84,63 @@ function O(e, t) {
 	};
 }
 //#endregion
+//#region src/embed/file-src.ts
+var x = "/api/files";
+function S(e) {
+	if (typeof e != "object" || !e) return !1;
+	let t = e;
+	return typeof t.url == "string" && typeof t.proxy == "boolean";
+}
+function C(e, t) {
+	let n = encodeURIComponent(e);
+	return typeof t == "object" ? `${x}/${n}/derived/${encodeURIComponent(t.derivation)}/url` : `${x}/${n}/url`;
+}
+var w = class extends Error {
+	fileId;
+	key;
+	constructor(e, t) {
+		super(`derivation "${t}" of file ${e} is still generating`), this.fileId = e, this.key = t, this.name = "DerivationPendingError";
+	}
+};
+function T(e, t) {
+	return {
+		method: "GET",
+		credentials: "omit",
+		headers: { Authorization: `Bearer ${e}` },
+		signal: t
+	};
+}
+function E(e) {
+	return `${e}${e.includes("?") ? "&" : "?"}disposition=attachment`;
+}
+async function D(e, r) {
+	let i = await t(), a = await fetch(e, T(i, r));
+	if (a.status !== 401) return a;
+	n();
+	let o = await t();
+	return fetch(e, T(o, r));
+}
+async function O(t, n, r) {
+	if (!e()) throw Error("resolveEmbedFileSrc called outside embed token mode");
+	let i = await D(C(t, n), r);
+	if (i.status === 202 && typeof n == "object") throw new w(t, n.derivation);
+	if (!i.ok) throw Error(`embed file url request failed: ${i.status} ${i.statusText}`);
+	let a = await i.json();
+	if (!S(a)) throw Error("embed file url response is malformed");
+	if (!a.proxy) return {
+		url: a.url,
+		kind: "direct"
+	};
+	if (!a.url.startsWith("/api/files/")) throw Error(`embed file proxy: refusing non-files-route URL ${JSON.stringify(a.url)}`);
+	let o = await D(n === "download" ? E(a.url) : a.url, r);
+	if (!o.ok) throw Error(`embed file proxy fetch failed: ${o.status} ${o.statusText}`);
+	let s = await o.blob();
+	return {
+		url: URL.createObjectURL(s),
+		kind: "blob"
+	};
+}
+//#endregion
 //#region src/components/file-widgets/useEmbedFileSrc.ts
 function k(e) {
 	return typeof e == "object" ? `derivation:${e.derivation}` : e;
@@ -159,7 +159,7 @@ function j(t, n, r) {
 			return;
 		}
 		let n = null, r = !1, i = new AbortController();
-		return c(void 0), m(t, A(a), i.signal).then((e) => {
+		return c(void 0), O(t, A(a), i.signal).then((e) => {
 			if (r) {
 				e.kind === "blob" && URL.revokeObjectURL(e.url);
 				return;
@@ -167,7 +167,7 @@ function j(t, n, r) {
 			e.kind === "blob" && (n = e.url), c(e.url);
 		}).catch((e) => {
 			if (!r) {
-				if (e instanceof u) {
+				if (e instanceof w) {
 					c(void 0);
 					return;
 				}
@@ -188,10 +188,10 @@ function M() {
 			i && window.open(i, "_blank", "noopener");
 			return;
 		}
-		n && m(n, r).then((e) => {
+		n && O(n, r).then((e) => {
 			e.kind === "blob" && t.current.push(e.url), window.open(e.url, "_blank", "noopener");
 		}).catch((e) => {
-			e instanceof u || console.error("[declarion-embed] file open failed:", e);
+			e instanceof w || console.error("[declarion-embed] file open failed:", e);
 		});
 	}, []) };
 }
@@ -207,4 +207,4 @@ function F(e) {
 	return e ? Array.isArray(e) ? e.filter(N) : N(e) ? [e] : [] : [];
 }
 //#endregion
-export { b as a, C as c, E as d, v as f, j as i, w as l, P as n, S as o, O as p, M as r, D as s, F as t, x as u };
+export { f as a, h as c, v as d, u as f, j as i, g as l, P as n, m as o, b as p, M as r, y as s, F as t, p as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",
@@ -65,19 +65,19 @@
     "@radix-ui/react-select": "^2.3.1",
     "@radix-ui/react-separator": "^1.1.10",
     "@radix-ui/react-slot": "^1.3.0",
-    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-query": "^5.101.2",
     "@tanstack/react-table": "^8.21.3",
-    "@tanstack/react-virtual": "^3.14.3",
+    "@tanstack/react-virtual": "^3.14.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.4.0",
-    "lucide-react": "^1.21.0",
+    "lucide-react": "^1.22.0",
     "mdast-util-to-string": "^4.0.0",
     "monaco-editor": "^0.55.1",
     "react-markdown": "^10.1.0",
-    "react-router-dom": "^7.18.0",
+    "react-router-dom": "^7.18.1",
     "react-textarea-autosize": "^8.5.9",
-    "recharts": "^3.8.1",
+    "recharts": "^3.9.0",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
@@ -88,30 +88,30 @@
     "zustand": "^5.0.14"
   },
   "devDependencies": {
-    "@axe-core/react": "^4.11.3",
+    "@axe-core/react": "^4.12.1",
     "@tailwindcss/typography": "^0.5.20",
-    "@tailwindcss/vite": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.2",
+    "@vitejs/plugin-react": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.9",
     "axe-core": "^4.12.1",
-    "eslint": "^10.5.0",
+    "eslint": "^10.6.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^29.1.1",
     "msw": "^2.14.6",
     "publint": "^0.3.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "tailwindcss": "^4.3.1",
+    "tailwindcss": "^4.3.2",
     "tsc-alias": "^1.8.17",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.0",
-    "vite": "^8.0.16",
+    "typescript-eslint": "^8.62.1",
+    "vite": "^8.1.0",
     "vitest": "^4.1.9"
   },
   "scripts": {