@declarion/react 0.27.0 → 0.28.1

package/dist-lib/{DraggableChildrenTable-C1s26ScM.js → DraggableChildrenTable-D4WoV6ck.js}

@@ -1,5 +1,5 @@
 import { s as e } from "./DynamicIcon-DCRdxxZ7.js";
-import { Fn as t, In as n, m as r, mn as i, p as a, tn as o } from "./ActionRunner-D9fJRkNV.js";
+import { Ln as t, Rn as n, gn as r, m as i, p as a, rn as o } from "./ActionRunner-DtUDeH4F.js";
 import { n as s, r as c, t as l } from "./dataTableStyles-vwD1mVOP.js";
 import { useCallback as u, useMemo as d, useRef as f } from "react";
 import { jsx as p, jsxs as m } from "react/jsx-runtime";
@@ -207,7 +207,7 @@ function T({ row: n, columns: o, editableColumns: s, displayOnlyColumns: c, chil
 						...A,
 						textDecoration: y ? "line-through" : "none"
 					},
-					children: t ? r({
+					children: t ? i({
 						field: t,
 						fieldName: e,
 						value: n[e],
@@ -215,7 +215,7 @@ function T({ row: n, columns: o, editableColumns: s, displayOnlyColumns: c, chil
 						record: n,
 						refs: f,
 						locale: v
-					}) : i(n[e])
+					}) : r(n[e])
 				}, e) : /* @__PURE__ */ p("td", {
 					style: {
 						...j,
@@ -224,7 +224,7 @@ function T({ row: n, columns: o, editableColumns: s, displayOnlyColumns: c, chil
 						borderRadius: a ? 4 : 0
 					},
 					title: a ? `${e} is required` : void 0,
-					children: t ? r({
+					children: t ? i({
 						field: t,
 						fieldName: e,
 						value: n[e],
@@ -233,7 +233,7 @@ function T({ row: n, columns: o, editableColumns: s, displayOnlyColumns: c, chil
 						record: n,
 						refs: f,
 						locale: v
-					}) : i(n[e])
+					}) : r(n[e])
 				}, e);
 			}),
 			/* @__PURE__ */ p("td", {

package/dist-lib/{Grid-C4fCdbYW.js → Grid-CsK_TuK_.js}

@@ -1,5 +1,5 @@
-import { C as e, S as t, _ as n, b as r, x as i, y as a } from "./ActionRunner-D9fJRkNV.js";
-import { c as o, i as s, l as c, t as l } from "./value-BQWyqKHC.js";
+import { C as e, S as t, _ as n, b as r, x as i, y as a } from "./ActionRunner-DtUDeH4F.js";
+import { c as o, i as s, l as c, t as l } from "./value-CNUbJNK-.js";
 import { useCallback as u, useEffect as d, useMemo as f, useRef as p, useState as m } from "react";
 import { Fragment as h, jsx as g, jsxs as _ } from "react/jsx-runtime";
 import { DndContext as v, PointerSensor as y, closestCenter as b, useSensor as x, useSensors as ee } from "@dnd-kit/core";

package/dist-lib/{MarkdownRenderer-VQnKhMQx.js → MarkdownRenderer-CwlNQju5.js}

@@ -1,4 +1,4 @@
-import { T as e } from "./ActionRunner-D9fJRkNV.js";
+import { T as e } from "./ActionRunner-DtUDeH4F.js";
 import { jsx as t, jsxs as n } from "react/jsx-runtime";
 import r, { defaultUrlTransform as i } from "react-markdown";
 import a from "remark-breaks";

package/dist-lib/embed/EmbedHistoryTracker.d.ts

@@ -0,0 +1 @@
+export declare function EmbedHistoryTracker(): null;

package/dist-lib/embed/embed-history.d.ts

@@ -0,0 +1,19 @@
+/** The React Router navigation action, as returned by `useNavigationType()`. */
+export type EmbedNavAction = "PUSH" | "POP" | "REPLACE";
+interface EmbedHistoryState {
+    /** In-frame history depth: 0 at the entry screen, +1 per in-frame drill. */
+    readonly depth: number;
+    /** When true, the NEXT applied navigation is treated as a fresh root (depth
+     *  resets to 0) regardless of its action. Set by a host-driven `navigate`. */
+    readonly nextIsRoot: boolean;
+    /** Apply one navigation's action to the depth. PUSH +1, POP -1 (floored at
+     *  0), REPLACE unchanged; a pending root marker forces 0 and clears itself.
+     *  Called once per navigation by the tracker. */
+    applyNavigation: (action: EmbedNavAction) => void;
+    /** Mark the next applied navigation as a fresh root (host-driven `navigate`). */
+    markRoot: () => void;
+    /** Reset to the entry screen (embed re-bootstrap). */
+    reset: () => void;
+}
+export declare const useEmbedHistoryStore: import("zustand").UseBoundStore<import("zustand").StoreApi<EmbedHistoryState>>;
+export {};

package/dist-lib/embed/index.d.ts

@@ -10,7 +10,9 @@ export { EmbedDirtyReporter } from "./EmbedDirtyReporter";
 export { EMBED_MESSAGE_SOURCE, EMBED_PROTOCOL_VERSION, EMBED_MESSAGE_TYPES, postToParent, type EmbedMessageType, type EmbedMessage, type EmbedMessagePayloadMap, type EmbedReadyPayload, type EmbedSetTokenPayload, type EmbedTokenExpiredPayload, type EmbedReloadRequiredPayload, type EmbedResizedPayload, type EmbedNavigationPayload, type EmbedDirtyChangedPayload, type EmbedNavigationFailedPayload, type EmbedNavigatePayload, type EmbedSetThemePayload, } from "./protocol";
 export { resolveEmbedNavigation, resolveEmbedNavigationPayload, } from "./screen-location";
 export type { EmbedNavigationResolution } from "./screen-location";
-export { useEmbedNavigate, useEmbedScreenNavigate, useEmbedNavigationFailed, } from "./useEmbedNavigate";
+export { useEmbedNavigate, useEmbedScreenNavigate, useEmbedScreenBack, useEmbedNavigationFailed, } from "./useEmbedNavigate";
+export { useEmbedHistoryStore, type EmbedNavAction } from "./embed-history";
+export { EmbedHistoryTracker } from "./EmbedHistoryTracker";
 export { useGlobalLinkInterceptor, interceptedNavigationTarget, interceptedProgrammaticTarget, NATIVE_LINK_ATTR, } from "./useGlobalLinkInterceptor";
 export { EmbedLocationReporter } from "./EmbedLocationReporter";
 export { useEmbedDirtyStore, useReportEmbedDirty } from "./embed-dirty";

package/dist-lib/embed/useEmbedNavigate.d.ts

@@ -26,6 +26,18 @@ export declare function useEmbedScreenNavigate(): (to: string, opts?: NavigateOp
  * them.
  */
 export declare function useEmbedNavigate(): (to: string, opts?: NavigateOptions) => void;
+/**
+ * Embed-mode Back: pop the iframe's own browser history (`navigate(-1)`) to the
+ * exact prior URL, so the URL-keyed retained page + cache restore the prior
+ * screen's full state - "the same as a normal app", just without tab chrome.
+ *
+ * Routed through the SAME deferred unsaved-changes guard the rest of embed
+ * navigation uses: a raw `navigate(-1)` would bypass the dirty guard and
+ * silently discard an in-progress edit (Codex finding). The CALLER
+ * (`useScreenBack`) decides WHEN to use this (only when in-frame history depth
+ * > 0); this hook only performs the guarded pop.
+ */
+export declare function useEmbedScreenBack(): () => void;
 /**
  * Emit a `navigation-failed` event to the host. Used where an in-frame
  * navigation cannot be handled OUTSIDE the chokepoint - chiefly the embedded

package/dist-lib/hooks/useActionData.d.ts

@@ -0,0 +1,61 @@
+import { type QueryKey } from "@tanstack/react-query";
+/** The canonical list-page envelope a paginated action returns in its `result` -
+ *  the same shape `data.list` (ListResponse) produces. */
+export interface ActionListPage<T> {
+    data: T[];
+    meta?: {
+        cursor?: string;
+        has_more?: boolean;
+    };
+}
+/** Query-key root for a one-shot action read. Mirrors the entity root
+ *  `entity-data`. */
+export declare const ACTION_DATA_KEY = "action-data";
+/** Query-key root for a cursor (infinite) action read. Mirrors the entity cursor
+ *  root `entity-data-cursor`; distinct from the one-shot read so it is
+ *  reaped/registered independently. */
+export declare const ACTION_DATA_CURSOR_KEY = "action-data-cursor";
+/**
+ * The React Query key for a one-shot action read. Single source of truth for
+ * both `useActionData` and a screen registering it as its PRIMARY read with its
+ * retained page (`useRegisterRetainedQuery`). `params` is embedded directly;
+ * React Query hashes it stably (sorted keys).
+ */
+export declare function actionDataQueryKey(actionCode: string | undefined, params: Record<string, unknown>): QueryKey;
+/**
+ * Read an arbitrary action ONCE and cache its `result` - the action mirror of
+ * `useEntityData`. `T` is whatever the action returns (a summary object, or a
+ * plain array that is not cursor-paginated). Returns the raw React Query result;
+ * the caller registers the key via `actionDataQueryKey` +
+ * `useRegisterRetainedQuery` for retention.
+ */
+export declare function useActionData<T>(actionCode: string | undefined, params: Record<string, unknown>, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<NoInfer<T>, Error>;
+/**
+ * The React Query key for a cursor (infinite) action read. Single source of
+ * truth for both `useCursorActionData` and its retained-page registration. The
+ * key excludes the cursor (the cursor is the page param, not part of identity).
+ */
+export declare function cursorActionDataQueryKey(actionCode: string | undefined, params: Record<string, unknown>): QueryKey;
+/** The accumulated, table-ready result of a cursor action read - mirrors the
+ *  shape `useCursorEntityData` feeds a list. */
+export interface CursorActionDataResult<T> {
+    rows: T[];
+    hasMore: boolean;
+    fetchNextPage: () => void;
+    isFetchingNextPage: boolean;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: () => void;
+    queryKey: QueryKey;
+}
+/**
+ * Drive a cursor-paginated table from an action that returns an `ActionListPage`
+ * in its `result`. The mirror of `useCursorEntityData`, differing only in the
+ * source (an action via `executeAction`, not `EntityClient.list`): it
+ * accumulates windows with `useInfiniteQuery`, advancing `meta.cursor` while
+ * `meta.has_more`, and exposes the flattened rows. Register the returned
+ * `queryKey` with `useRegisterRetainedQuery` so the pages survive a tab switch /
+ * Back within the retention window and die with the retained page.
+ */
+export declare function useCursorActionData<T>(actionCode: string | undefined, params: Record<string, unknown>, enabled?: boolean): CursorActionDataResult<T>;

package/dist-lib/hooks/useCursorEntityData.d.ts

@@ -1,3 +1,4 @@
+import { type QueryKey } from "@tanstack/react-query";
 import type { FilterNodeParam, Refs, V2Meta } from "../types/api";
 /**
  * Query-key root for the cursor (infinite) entity list. Distinct from the
@@ -7,6 +8,18 @@ import type { FilterNodeParam, Refs, V2Meta } from "../types/api";
  * list. See useSSE.ts.
  */
 export declare const CURSOR_ENTITY_DATA_KEY = "entity-data-cursor";
+/**
+ * The stable JSON segment of the cursor list's query key (the view-defining
+ * params, order-independent). Extracted so both the hook and the key builder
+ * compute it identically.
+ */
+export declare function cursorEntityStableKey(params: CursorEntityDataParams): string;
+/**
+ * The React Query key for the cursor (infinite) entity list. Single source of
+ * truth for both `useCursorEntityData` and a screen registering its PRIMARY
+ * cursor read with its retained page (`useRegisterRetainedQuery`).
+ */
+export declare function cursorEntityDataQueryKey(entity: string | undefined, params: CursorEntityDataParams): QueryKey;
 export interface CursorEntityDataParams {
     sort?: string;
     filters?: FilterNodeParam[];

package/dist-lib/hooks/useEntityData.d.ts

@@ -1,4 +1,12 @@
+import { type QueryKey } from "@tanstack/react-query";
 import type { ListParams, ListResponse } from "../types/api";
+/**
+ * The React Query key for an entity list-window read. The single source of
+ * truth for both `useEntityData` and a screen registering its PRIMARY read with
+ * its retained page (`useRegisterRetainedQuery`), so the registered key matches
+ * the live query exactly. See hooks/usePageStateRuntime.ts.
+ */
+export declare function entityDataQueryKey(entity: string | undefined, params: ListParams): QueryKey;
 /**
  * useEntityData fetches one page-window of entity rows.
  *

package/dist-lib/hooks/useEntityItem.d.ts

@@ -1,2 +1,10 @@
+import { type QueryKey } from "@tanstack/react-query";
 import type { PkValues } from "../types/schema";
+/**
+ * The React Query key for a single-record read. Single source of truth for both
+ * `useEntityItem` and a detail screen registering its PRIMARY read with its
+ * retained page (`useRegisterRetainedQuery`). For a string PK uses it directly;
+ * for a composite PK sorts the parts so key order does not fork the cache.
+ */
+export declare function entityItemQueryKey(entity: string | undefined, pkValues: PkValues | string | undefined): QueryKey;
 export declare function useEntityItem(entity: string | undefined, pkValues: PkValues | string | undefined): import("@tanstack/react-query").UseQueryResult<NoInfer<import("..").DataResponse<Record<string, unknown>>>, Error>;

package/dist-lib/hooks/usePageState.d.ts

@@ -0,0 +1,32 @@
+/** A `useState`-style setter accepting a value or an updater. */
+export type PageStateSetter<T> = (next: T | ((prev: T) => T)) => void;
+/**
+ * How coarsely a value is keyed.
+ *   - `"url"` (default): keyed by the full canonical URL, so it FORKS when
+ *     filters/sort/sub-view change (per-view memory - e.g. scroll position,
+ *     expanded rows). A filter change is a new view with its own value.
+ *   - `"path"`: keyed by the screen pathname only, so it PERSISTS across
+ *     in-screen query changes (e.g. row selection, which survives a filter or
+ *     column change and is pruned to the visible rows, not reset).
+ */
+export type PageStateScope = "url" | "path";
+export interface PageStateOptions {
+    scope?: PageStateScope;
+}
+/**
+ * Bind a deep value to the current screen's retained page.
+ *
+ * Returns `[value, setValue]`:
+ *   - `value` is the stored value for the live canonical URL, or `defaultValue`
+ *     when absent / reaped / retention disabled. Re-renders only when THIS
+ *     pageKey's value for THIS key changes.
+ *   - `setValue` writes through to the store under the LIVE canonical URL
+ *     (tracked via a per-render ref, so the stable setter always targets the
+ *     currently-mounted view - never a key captured at mount, never the
+ *     destination's after a navigation). Accepts a value or an updater.
+ *
+ * Writes are immediate (write-through), so there is no deferred unmount flush to
+ * lose: a value set while mounted at a URL is already stored under that URL when
+ * the screen unmounts. The retained page is created lazily on first write.
+ */
+export declare function usePageState<T>(key: string, defaultValue: T, opts?: PageStateOptions): [T, PageStateSetter<T>];

package/dist-lib/hooks/usePageStateRuntime.d.ts

@@ -0,0 +1,27 @@
+import { type QueryClient, type QueryKey } from "@tanstack/react-query";
+/**
+ * Apply `gcTime` to every retained-read query-key prefix. Exported so app.tsx
+ * can seed the DEFAULT floor on the QueryClient at module load - BEFORE the
+ * first screen renders and creates its reads - so even that first screen's data
+ * is not GC'd at React Query's 5-min default within the retention window. The
+ * runtime then overrides with the resolved per-tenant value for later reads.
+ */
+export declare function applyRetainedReadGcTime(client: QueryClient, gcTime: number): void;
+/**
+ * Mount once (Layout) to drive the retained-page lifecycle from the resolved
+ * `ui_page_state_ttl_ms`. Idempotent and inert beyond its three effects.
+ */
+export declare function usePageStateRuntime(): void;
+/**
+ * Register a screen's PRIMARY heavy read (its list or detail query key) with the
+ * current retained page, so a kill/sweep `removeQueries` releases the cached
+ * data alongside the deep state. Call from the standard pages (and custom
+ * screens) with the key from the matching key-builder (`entityDataQueryKey` /
+ * `cursorEntityDataQueryKey` / `entityItemQueryKey`).
+ *
+ * Pass ONLY primary heavy reads - never a shared ref/lookup query, or a
+ * sibling screen that shares its key would lose it on this page's eviction.
+ * `enabled` (default true) lets the cursor/offset pages register exactly the
+ * read they actually use.
+ */
+export declare function useRegisterRetainedQuery(queryKey: QueryKey | undefined, enabled?: boolean): void;

package/dist-lib/hooks/usePageStateTtl.d.ts

@@ -0,0 +1,11 @@
+/** The platform parameter governing retained-page retention. Declared in
+ *  modules/_platform/schema/core_parameters.yaml (int, category `ui`,
+ *  `[tenant]`, env `DECLARION_UI_PAGE_STATE_TTL_MS`). */
+export declare const PAGE_STATE_TTL_PARAM = "ui_page_state_ttl_ms";
+/**
+ * Resolve the retention window in milliseconds. Returns the per-tenant value
+ * once the parameter loads, the YAML-mirrored default before then, and clamps a
+ * malformed value to the default (never NaN/negative). `0` is honored as
+ * "retention disabled".
+ */
+export declare function usePageStateTtl(): number;

package/dist-lib/hooks/useRegisterScreenTab.d.ts

@@ -1,2 +1,11 @@
 import { type Entity, type Screen } from "../types/schema";
+/**
+ * The embed-guarded tab registration shared by the schema-driven Smart pages
+ * (`useRegisterScreenTab`) and the public custom-screen hook (`useScreenTab`),
+ * so the "open a tab for this screen" logic - and its embed guard - lives in one
+ * place. Registers `route` as a tab once; `search` is captured at first
+ * registration (the mirror syncs later changes), so it is excluded from the
+ * effect deps. No-op when `route` is absent or embed mode is on (Invariant 8).
+ */
+export declare function useScreenTabRegistration(route: string | undefined, title: string, icon: string | undefined, search: string): void;
 export declare function useRegisterScreenTab(screen: Screen | undefined, entity: Entity | undefined, search: string): void;

package/dist-lib/hooks/useScreenTab.d.ts

@@ -0,0 +1,10 @@
+export interface UseScreenTabOptions {
+    /** The tab's route. Defaults to the live `location.pathname` - the right value
+     *  for a param-less custom screen, which is the common case. */
+    route?: string;
+    /** Tab title. Defaults to the route when omitted. */
+    title?: string;
+    /** Tab icon name (resolved by the icon registry). */
+    icon?: string;
+}
+export declare function useScreenTab(opts?: UseScreenTabOptions): void;

package/dist-lib/index.d.ts

@@ -16,11 +16,13 @@ export { useSchema } from "./hooks/useSchema";
 export { useEntity } from "./hooks/useEntity";
 export { useScreen } from "./hooks/useScreen";
 export { useAuth } from "./hooks/useAuth";
-export { useEntityData, useEntityCount } from "./hooks/useEntityData";
-export { useCursorEntityData } from "./hooks/useCursorEntityData";
+export { useEntityData, useEntityCount, entityDataQueryKey } from "./hooks/useEntityData";
+export { useCursorEntityData, cursorEntityDataQueryKey, cursorEntityStableKey, } from "./hooks/useCursorEntityData";
 export type { CursorEntityDataParams, CursorEntityDataResult, } from "./hooks/useCursorEntityData";
 export { useAllEntityData } from "./hooks/useAllEntityData";
-export { useEntityItem } from "./hooks/useEntityItem";
+export { useEntityItem, entityItemQueryKey } from "./hooks/useEntityItem";
+export { useActionData, useCursorActionData, actionDataQueryKey, cursorActionDataQueryKey, ACTION_DATA_KEY, ACTION_DATA_CURSOR_KEY, } from "./hooks/useActionData";
+export type { ActionListPage, CursorActionDataResult } from "./hooks/useActionData";
 export { useCreateEntity, useUpdateEntity, useDeleteEntity } from "./hooks/useMutations";
 export { useDebounce } from "./hooks/useDebounce";
 export { usePublicParams, useResolvedParam, useParam } from "./hooks/useParams";
@@ -38,6 +40,17 @@ export { useTabStore, type TabItem, type ReturnTarget } from "./stores/tabs";
 export { useTabNavigate } from "./hooks/useTabNavigate";
 export { useScreenBack } from "./hooks/useScreenBack";
 export type { UseScreenBackOptions, ScreenBack } from "./hooks/useScreenBack";
+export { usePageState } from "./hooks/usePageState";
+export type { PageStateSetter } from "./hooks/usePageState";
+export { canonicalUrl } from "./lib/canonical-url";
+export type { CanonicalLocation } from "./lib/canonical-url";
+export { useRegisterRetainedQuery } from "./hooks/usePageStateRuntime";
+export { usePageStateTtl, PAGE_STATE_TTL_PARAM } from "./hooks/usePageStateTtl";
+export { useScreenTab } from "./hooks/useScreenTab";
+export type { UseScreenTabOptions } from "./hooks/useScreenTab";
+export { useTabSearchMirror } from "./hooks/useTabSearchMirror";
+export { useVirtualScrollRestoration, usePlainScrollRestoration, useSavedScrollOffset, SCROLL_STATE_KEY, } from "./lib/scroll-restoration";
+export type { ScrollAnchor, ScrollableVirtualizer } from "./lib/scroll-restoration";
 export { SmartListPage } from "./components/pages/SmartListPage";
 export { SmartDetailPage } from "./components/pages/SmartDetailPage";
 export { SmartRecordListPage } from "./components/pages/SmartRecordListPage";