@declarion/react 0.27.0 → 0.28.0

package/dist-lib/lib/canonical-url.d.ts

@@ -0,0 +1,27 @@
+/** The minimal location shape canonicalUrl needs (a router `Location` satisfies
+ *  it; tests can pass a bare object). */
+export interface CanonicalLocation {
+    pathname: string;
+    search?: string;
+}
+/**
+ * Build the canonical URL key for a location: normalized pathname + the
+ * view-defining query, sorted by key, with the embed transport params removed.
+ *
+ * Sorting makes `?a=1&b=2` and `?b=2&a=1` one key. Removing `EMBED_PARAM_KEYS`
+ * makes the same screen one key whether or not the embed params ride along, so
+ * a retained page is shared between the embedded and non-embedded view of the
+ * same URL. Default query values are NOT collapsed (which params have a default
+ * is screen-specific and collapsing the wrong one would silently merge or fork
+ * pages); two URLs that differ only by an explicit-vs-implicit default are
+ * treated as distinct, which is safe (at worst slightly less sharing).
+ */
+export declare function canonicalUrl(location: CanonicalLocation): string;
+/**
+ * The SCREEN-scoped key: the normalized pathname alone, ignoring the query.
+ * Coarser than `canonicalUrl` - it does NOT fork when filters/sort/columns
+ * change. Used for deep state that must persist ACROSS in-screen query changes
+ * (row selection, pruned to the visible result set) rather than resetting per
+ * filtered view. Two filter views of the same screen share one screen key.
+ */
+export declare function canonicalPath(location: CanonicalLocation): string;

package/dist-lib/lib/scroll-restoration.d.ts

@@ -0,0 +1,90 @@
+/** The default deep-state bag key under which a screen's scroll anchor is
+ *  stored. A screen with one scroll container uses this; a screen with several
+ *  passes distinct keys. */
+export declare const SCROLL_STATE_KEY = "scroll";
+/**
+ * A saved scroll position. `key` is the stable key of the row at the top of the
+ * viewport (empty when the container had no rows / is non-virtualized); `delta`
+ * is the sub-row pixel offset; `offset` is the raw scroll offset kept as a
+ * last-resort fallback when the anchor row is gone.
+ */
+export interface ScrollAnchor {
+    key: string;
+    delta: number;
+    offset: number;
+}
+/** The minimal virtualizer surface the seam needs. A
+ *  `Virtualizer<HTMLElement, Element>` is structurally assignable; a test can
+ *  pass a fake. */
+export interface ScrollableVirtualizer {
+    scrollOffset: number | null;
+    getVirtualItemForOffset: (offset: number) => {
+        index: number;
+        start: number;
+    } | undefined;
+    getOffsetForIndex: (index: number, align?: "start") => readonly [number, unknown] | undefined;
+    getTotalSize: () => number;
+    scrollToOffset: (offset: number, opts?: {
+        align?: "start";
+        behavior?: "auto";
+    }) => void;
+}
+/**
+ * Capture the scroll anchor at `scrollOffset`. `topItem` is the virtual item at
+ * the top of the viewport (`getVirtualItemForOffset(scrollOffset)`); `rowKeys`
+ * maps its index to a stable row key. Returns an anchor with an empty `key`
+ * (raw-offset-only) when there is no top item or no key for it. Pure.
+ */
+export declare function captureScrollAnchor(scrollOffset: number, topItem: {
+    index: number;
+    start: number;
+} | undefined, rowKeys: string[]): ScrollAnchor;
+/**
+ * Resolve the scroll offset to restore to, from a saved `anchor`, the CURRENT
+ * `rowKeys`, an `offsetForIndex` accessor (the virtualizer's measured start of a
+ * row), and the current `totalSize` (for clamping). Pure and testable.
+ *
+ * Fallback chain (Decision #17): anchor row found -> its measured start + delta;
+ * anchor row gone (deleted / filtered out) -> clamped raw offset; unusable
+ * offset -> top (0). Returns null when there is nothing saved.
+ */
+export declare function resolveScrollOffset(anchor: ScrollAnchor | undefined, rowKeys: string[], offsetForIndex: (index: number) => number | undefined, totalSize: number): number | null;
+/** Read the saved raw scroll offset for the current page ONCE, for seeding a
+ *  virtualizer's `initialOffset` (read-once at init). Returns 0 when none /
+ *  retention off. The full anchor re-restore happens after rows measure. */
+export declare function useSavedScrollOffset(stateKey?: string): number;
+/**
+ * Bind scroll save + anchor-row restore for a VIRTUALIZED list to the retained
+ * page keyed by the live canonical URL.
+ *
+ * - Restore: once per pageKey, after `rowKeys` first become non-empty, scrolls
+ *   to `resolveScrollOffset(...)` (anchor row -> clamped raw -> top).
+ * - Save: a throttled scroll listener captures the top-of-viewport anchor and
+ *   writes it imperatively (no re-render); the final position flushes on
+ *   unmount / pageKey change to the DEPARTING view's own URL (tracked via a
+ *   per-render ref).
+ *
+ * `enabled` (default true) lets a caller gate the seam; when false it is inert.
+ */
+export declare function useVirtualScrollRestoration(opts: {
+    virtualizer: ScrollableVirtualizer | null;
+    scrollElementRef: {
+        current: HTMLElement | null;
+    };
+    rowKeys: string[];
+    stateKey?: string;
+    enabled?: boolean;
+}): void;
+/**
+ * Scroll save + restore for a PLAIN (non-virtualized) scroll container - the
+ * detail page. Stores the raw `scrollTop` (no anchor rows to key by) under the
+ * live canonical URL; restores after first layout; saves throttled-on-scroll +
+ * on unmount flush.
+ */
+export declare function usePlainScrollRestoration(opts: {
+    scrollElementRef: {
+        current: HTMLElement | null;
+    };
+    stateKey?: string;
+    enabled?: boolean;
+}): void;

package/dist-lib/stores/page-state.d.ts

@@ -0,0 +1,61 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+/** Default retention window before the `ui_page_state_ttl_ms` parameter
+ *  resolves (and the fallback when it is absent). 30 minutes - long enough to
+ *  switch among tabs all day instantly, bounded enough to keep memory sane.
+ *  Mirrors the YAML default in core_parameters.yaml; both must agree. */
+export declare const DEFAULT_PAGE_STATE_TTL_MS: number;
+/** Hard upper bound on retained-page entries. Bounds total memory and is the
+ *  ONLY bound in embed mode, which has no tab-close signal at all. Generous
+ *  relative to `ui_tabs_max_open` (a user rarely revisits more than this many
+ *  distinct URLs within one TTL window); the least-recently-active entry is
+ *  evicted first when the cap is exceeded. */
+export declare const PAGE_STATE_MAX_ENTRIES = 64;
+/** One retained page's deep state. `bag` holds small JSON-serializable deep
+ *  values; `queryKeys` references the screen's PRIMARY React Query reads so an
+ *  eviction can release the cached data alongside the deep state. */
+export interface PageStateEntry {
+    bag: Record<string, unknown>;
+    lastActiveAt: number;
+    queryKeys: QueryKey[];
+}
+interface PageStateStore {
+    /** pageKey (canonical URL) -> retained-page deep state. */
+    entries: Record<string, PageStateEntry>;
+    /** Active retention window. `<= 0` disables retention. Set by the runtime
+     *  from the resolved `ui_page_state_ttl_ms`; defaults to the 30-min fallback
+     *  so retention works before the parameter loads. */
+    ttlMs: number;
+    /** Set the retention window. `<= 0` disables retention and immediately clears
+     *  every entry (with linked `removeQueries`), so a runtime toggle to "off"
+     *  frees memory at once. */
+    setTtl: (ttlMs: number) => void;
+    /** Write a deep value under `pageKey`, refreshing `lastActiveAt` and
+     *  enforcing the LRU cap. No-op when retention is disabled. */
+    set: (pageKey: string, key: string, value: unknown) => void;
+    /** Read a deep value, or `undefined` when absent / reaped / retention off. */
+    read: (pageKey: string, key: string) => unknown;
+    /** Refresh `lastActiveAt` for a still-mounted view so it is not reaped while
+     *  active. No-op when the entry is absent or retention is disabled. */
+    touch: (pageKey: string) => void;
+    /** Track one of the screen's PRIMARY React Query keys so eviction releases
+     *  the cached data. Deduplicated. No-op when retention is disabled. */
+    registerQueryKey: (pageKey: string, queryKey: QueryKey) => void;
+    /** Explicitly evict one retained page NOW: drop its deep state AND
+     *  `removeQueries` its tracked keys. Idempotent; works even when retention is
+     *  disabled (used by per-screen kill policies, e.g. a deleted detail record). */
+    kill: (pageKey: string) => void;
+    /** Reap every entry stale past the active TTL (`now - lastActiveAt > ttlMs`),
+     *  releasing data + deep state together. When retention is disabled, evicts
+     *  all. `now` is injected for testability. */
+    sweep: (now: number) => void;
+    /** Drop EVERY retained page NOW (releasing all tracked queries) without
+     *  changing the TTL - the auth-scope reset. Called on logout so a different
+     *  user signing in within the same JS session cannot restore the prior user's
+     *  deep state (selection, scroll, custom-screen values). */
+    clear: () => void;
+}
+/** Register the app's QueryClient so retained-page eviction can release the
+ *  tracked entity-read queries. Called once at app mount. */
+export declare function setPageStateQueryClient(client: QueryClient | null): void;
+export declare const usePageStateStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PageStateStore>>;
+export {};

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-D9fJRkNV.js";
+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";
@@ -87,7 +87,7 @@ function x(e) {
 }
 function S(i) {
 	let a = i.entityData ?? {};
-	n((e, t) => {
+	r((e, t) => {
 		let n = a[e], r = x(n), i = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
 		return t.count === "only" ? {
 			data: [],
@@ -109,19 +109,19 @@ function S(i) {
 		};
 	});
 	let o = i.entityItems ?? {};
-	r((e, n) => {
-		let r = typeof n == "string" ? n : t(n);
-		return { data: o[e]?.[r] };
+	t((t, n) => {
+		let r = typeof n == "string" ? n : e(n);
+		return { data: o[t]?.[r] };
 	});
 	let s = i.actionResults ?? {};
-	e(async (e, t) => {
+	n(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);
 	});
 }
 function C() {
-	n(null), r(null), e(null), i.setState({
+	r(null), t(null), n(null), i.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,

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

@@ -1,4 +1,4 @@
-import { Lt as e, Nt as t, Pt as n } from "./ActionRunner-D9fJRkNV.js";
+import { Ft as e, It as t, zt as n } from "./ActionRunner-DtUDeH4F.js";
 import { useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
 //#region src/components/file-widgets/helpers.ts
 var s = ["thumb_200", "thumb_300"];
@@ -113,17 +113,17 @@ function T(e, 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));
+async function D(n, r) {
+	let i = await e(), a = await fetch(n, 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);
+	t();
+	let o = await e();
+	return fetch(n, T(o, r));
+}
+async function O(e, t, r) {
+	if (!n()) throw Error("resolveEmbedFileSrc called outside embed token mode");
+	let i = await D(C(e, t), r);
+	if (i.status === 202 && typeof t == "object") throw new w(e, t.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");
@@ -132,7 +132,7 @@ async function O(t, n, r) {
 		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);
+	let o = await D(t === "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 {
@@ -148,23 +148,23 @@ function k(e) {
 function A(e) {
 	return e.startsWith("derivation:") ? { derivation: e.slice(11) } : e === "download" ? "download" : "preview";
 }
-function j(t, n, r) {
-	let a = k(n), [s, c] = o(() => e() ? void 0 : r);
+function j(e, t, r) {
+	let a = k(t), [s, c] = o(() => n() ? void 0 : r);
 	return i(() => {
-		e() || c(r);
+		n() || c(r);
 	}, [r]), i(() => {
-		if (!e()) return;
-		if (!t) {
+		if (!n()) return;
+		if (!e) {
 			c(void 0);
 			return;
 		}
-		let n = null, r = !1, i = new AbortController();
-		return c(void 0), O(t, A(a), i.signal).then((e) => {
+		let t = null, r = !1, i = new AbortController();
+		return c(void 0), O(e, A(a), i.signal).then((e) => {
 			if (r) {
 				e.kind === "blob" && URL.revokeObjectURL(e.url);
 				return;
 			}
-			e.kind === "blob" && (n = e.url), c(e.url);
+			e.kind === "blob" && (t = e.url), c(e.url);
 		}).catch((e) => {
 			if (!r) {
 				if (e instanceof w) {
@@ -174,22 +174,22 @@ function j(t, n, r) {
 				e instanceof DOMException && e.name === "AbortError" || (console.error("[declarion-embed] file src resolution failed:", e), c(void 0));
 			}
 		}), () => {
-			r = !0, i.abort(), n && URL.revokeObjectURL(n);
+			r = !0, i.abort(), t && URL.revokeObjectURL(t);
 		};
-	}, [t, a]), s;
+	}, [e, a]), s;
 }
 function M() {
-	let t = a([]);
+	let e = a([]);
 	return i(() => () => {
-		for (let e of t.current) URL.revokeObjectURL(e);
-		t.current = [];
-	}, []), { open: r((n, r, i) => {
-		if (!e()) {
+		for (let t of e.current) URL.revokeObjectURL(t);
+		e.current = [];
+	}, []), { open: r((t, r, i) => {
+		if (!n()) {
 			i && window.open(i, "_blank", "noopener");
 			return;
 		}
-		n && O(n, r).then((e) => {
-			e.kind === "blob" && t.current.push(e.url), window.open(e.url, "_blank", "noopener");
+		t && O(t, r).then((t) => {
+			t.kind === "blob" && e.current.push(t.url), window.open(t.url, "_blank", "noopener");
 		}).catch((e) => {
 			e instanceof w || console.error("[declarion-embed] file open failed:", e);
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",