@declarion/react 0.53.0 → 0.54.1

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

@@ -1,29 +1,96 @@
+import type { QueryCacheNotifyEvent, QueryKey } from "@tanstack/react-query";
+/** A query as the query cache holds it, whatever its data type. */
+export type CachedQuery = QueryCacheNotifyEvent["query"];
+/** An entity the relay is not delivering; `mark` lets a resync drop only the mark it saw. */
+export interface DegradedMark {
+    mark: number;
+    since: number;
+}
+export interface RealtimeThresholds {
+    pauseGraceMs: number;
+    silenceMs: number;
+}
+/**
+ * Which query keys a resync covers. `all` and `entities` also take in matching
+ * keys first observed while the resync is pending; `keys` is fixed.
+ */
+export type ResyncScope = {
+    kind: "all";
+} | {
+    kind: "entities";
+    entities: ReadonlySet<string>;
+} | {
+    kind: "keys";
+};
+export interface Resync {
+    id: number;
+    /** The fetch generation when it opened; only a fetch stamped above it satisfies a key. */
+    generation: number;
+    openedAt: number;
+    /** A refused read: shown at once, never issued, closed only by a fetch someone else starts. */
+    standing: boolean;
+    issued: boolean;
+    /** Whether issuing waits a random delay, so a fleet-wide cause does not burst. */
+    jitter: boolean;
+    scope: ResyncScope;
+    /** Query hash → key. */
+    keys: ReadonlyMap<string, QueryKey>;
+    /** Query hash → the query last seen observed under it, so a removed one still blocks while observed. */
+    observed: ReadonlyMap<string, CachedQuery>;
+    /** Marks dropped on completion, each only while it still carries this number. */
+    carriedMarks: ReadonlyMap<string, number>;
+    /** Entities with an observed key not yet satisfied. */
+    blocking: ReadonlySet<string>;
+}
 interface RealtimeState {
-    /** Entity codes the relay auto-degraded this session. */
-    degradedEntities: ReadonlySet<string>;
-    /** Mark one entity as auto-degraded. Idempotent. */
+    degradedEntities: ReadonlyMap<string, DegradedMark>;
+    /** Mark one entity degraded. A repeated mark renumbers it and keeps its start. */
     markDegraded: (entityCode: string) => void;
-    /** Realtime is delivering everything again; forget every degraded entity. */
-    clearDegraded: () => void;
+    /** Drop each mark named, only while the entity still carries that number. */
+    unmarkDegraded: (marks: ReadonlyMap<string, number>) => void;
+    /** Self-closing: no connection has stated its snapshot, or it went silent. */
+    connectionInterruptedSince: number | null;
+    holdConnectionInterruption: () => void;
+    clearConnectionInterruption: () => void;
+    /** Self-closing: the server's last word says the relay may not be streaming. */
+    relayInterruptedSince: number | null;
+    holdRelayInterruption: () => void;
+    clearRelayInterruption: () => void;
+    /** Self-closing: a connection presented a position and its replay has not applied. */
+    replayStartedAt: number | null;
+    startReplay: () => void;
+    endReplay: () => void;
     /**
-     * True while a presented resume position's replay has not landed. The rows
-     * keep rendering; what is not true is that they are up to date.
+     * Null while the declared thresholds load. `unreadable` is itself a held
+     * connection interruption, shown at once: claiming "Live" without the means
+     * to know is the defect this model removes.
      */
-    replayPending: boolean;
-    setReplayPending: (pending: boolean) => void;
-    /**
-     * True while a row re-read was turned away for budget. The rows keep
-     * rendering, but only a refresh the person asks for will renew them.
-     */
-    readRefused: boolean;
-    setReadRefused: (refused: boolean) => void;
+    thresholds: RealtimeThresholds | "unreadable" | null;
+    setThresholds: (thresholds: RealtimeThresholds | "unreadable" | null) => void;
+    resyncs: readonly Resync[];
+    addResync: (resync: Omit<Resync, "id">) => number;
+    updateResync: (id: number, patch: Partial<Omit<Resync, "id">>) => void;
+    removeResync: (id: number) => void;
 }
 export declare const useRealtimeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<RealtimeState>>;
-export declare function isEntityLive(realtimeFlag: boolean | undefined, degradedEntities: ReadonlySet<string>, entityCode: string): boolean;
+export declare function isEntityLive(realtimeFlag: boolean | undefined, degradedEntities: {
+    has(entityCode: string): boolean;
+}, entityCode: string): boolean;
+type CurrentnessInputs = Pick<RealtimeState, "degradedEntities" | "connectionInterruptedSince" | "relayInterruptedSince" | "replayStartedAt" | "thresholds" | "resyncs">;
+/**
+ * Whether an entity is current at `now`, and the next instant that answer can
+ * flip without any state changing - when a self-closing cause reaches the pause
+ * grace. Measured from each cause's stored start, so every surface flips at the
+ * same instant.
+ */
+export declare function screenCurrentness(state: CurrentnessInputs, realtimeFlag: boolean | undefined, entityCode: string, now: number): {
+    live: boolean;
+    recheckAt: number | null;
+};
 /**
- * Whether a screen showing this entity is CURRENT - a different question from
- * isEntityLive, which answers whether the relay delivers at all. The rows keep
- * rendering throughout; this is what says they may be behind. docs/realtime.md.
+ * The one predicate every indicator reads: is the screen showing this entity
+ * CURRENT. The rows keep rendering throughout; this says whether they may be
+ * behind. docs/realtime.md "Currentness".
  */
 export declare function useScreenIsLive(realtimeFlag: boolean | undefined, entityCode: string): boolean;
 export {};

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { Er as e, Jt as t, Vt as n, nn as r, on as i, r as a, rn as o, t as s, tn as c } from "./useCurrentScreen-BdnZq8vZ.js";
+import { $t as e, Bt as t, cn as n, dn as r, jr as i, on as a, r as o, sn as s, t as c } from "./useCurrentScreen-aHx9HH1m.js";
 import { useState as l } from "react";
 import { MemoryRouter as u, useLocation as d } from "react-router";
 import { QueryClient as f, QueryClientProvider as p } from "@tanstack/react-query";
@@ -74,7 +74,7 @@ function T() {
 		created_at: "2026-01-01T00:00:00Z",
 		updated_at: "2026-01-01T00:00:00Z"
 	};
-	i.getState().setUser(t, e);
+	r.getState().setUser(t, e);
 }
 function E(e) {
 	if (e === void 0) return { rows: [] };
@@ -89,15 +89,15 @@ function E(e) {
 	}
 	return e;
 }
-function D(e) {
-	let n = e.entityData ?? {};
-	o((t, r) => {
-		let i = r;
-		e.onListRequest?.(t, i);
-		let a = n[t], o = typeof a == "function" ? a(i) : a;
+function D(t) {
+	let r = t.entityData ?? {};
+	n((e, n) => {
+		let i = n;
+		t.onListRequest?.(e, i);
+		let a = r[e], o = typeof a == "function" ? a(i) : a;
 		if (o instanceof Error) throw o;
 		let s = E(o), c = s.meta?.per_page ?? 50, l = s.meta?.total ?? s.rows.length;
-		return r.count === "only" ? {
+		return n.count === "only" ? {
 			data: [],
 			meta: {
 				page: 1,
@@ -116,64 +116,64 @@ function D(e) {
 			...s.refs === void 0 ? {} : { $refs: s.refs }
 		};
 	});
-	let i = e.entityItems ?? {}, a = e.entityItemResponses ?? {};
-	r((e, n) => {
-		let r = typeof n == "string" ? n : t(n), o = a[e]?.[r];
-		if (o instanceof Error) throw o;
-		if (o !== void 0) return o;
-		let s = i[e]?.[r];
+	let i = t.entityItems ?? {}, o = t.entityItemResponses ?? {};
+	s((t, n) => {
+		let r = typeof n == "string" ? n : e(n), a = o[t]?.[r];
+		if (a instanceof Error) throw a;
+		if (a !== void 0) return a;
+		let s = i[t]?.[r];
 		if (s instanceof Error) throw s;
 		return { data: s };
 	});
-	let s = e.actionResults ?? {};
-	c(async (e, t) => {
-		if (!(e in s)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
-		let n = s[e];
+	let c = t.actionResults ?? {};
+	a(async (e, t) => {
+		if (!(e in c)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
+		let n = c[e];
 		return C(typeof n == "function" ? await n(t) : n);
 	});
 }
 function O() {
-	o(null), r(null), c(null), i.setState({
+	n(null), s(null), a(null), r.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
 		tenants: []
 	});
 }
-function k(t, r = {}) {
-	let i = new f({ defaultOptions: { queries: {
+function k(e, n = {}) {
+	let r = new f({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
 	} } });
-	T(), i.setQueryData(["schema", !0], r.schema ?? v()), D(r);
-	let o = r.screenCode ? /* @__PURE__ */ h(s, {
-		code: r.screenCode,
-		children: t
-	}) : t, c = { current: r.route ?? "/" }, l = /* @__PURE__ */ g(p, {
-		client: i,
+	T(), r.setQueryData(["schema", !0], n.schema ?? v()), D(n);
+	let a = n.screenCode ? /* @__PURE__ */ h(c, {
+		code: n.screenCode,
+		children: e
+	}) : e, s = { current: n.route ?? "/" }, l = /* @__PURE__ */ g(p, {
+		client: r,
 		children: [/* @__PURE__ */ g(u, {
-			initialEntries: [r.route ?? "/"],
-			children: [/* @__PURE__ */ h(w, { into: c }), /* @__PURE__ */ h(a, { children: o })]
+			initialEntries: [n.route ?? "/"],
+			children: [/* @__PURE__ */ h(w, { into: s }), /* @__PURE__ */ h(o, { children: a })]
 		}), /* @__PURE__ */ h(m, {})]
-	}), d = r.embedQuery ? /* @__PURE__ */ h(n, {
-		query: r.embedQuery,
+	}), d = n.embedQuery ? /* @__PURE__ */ h(t, {
+		query: n.embedQuery,
 		children: l
-	}) : l, y = _(r.viewport ? /* @__PURE__ */ h(e, {
-		viewportOverride: r.viewport,
+	}) : l, y = _(n.viewport ? /* @__PURE__ */ h(i, {
+		viewportOverride: n.viewport,
 		children: d
 	}) : d);
 	return Object.assign(y, {
-		queryClient: i,
-		location: () => c.current
+		queryClient: r,
+		location: () => s.current
 	});
 }
 function A({ children: e, authenticated: t = !0, ...n }) {
-	let [r] = l(() => {
+	let [i] = l(() => {
 		let e = new f({ defaultOptions: { queries: {
 			retry: !1,
 			gcTime: Infinity
 		} } });
-		return t ? (T(), e.setQueryData(["schema", !0], n.schema ?? v())) : i.setState({
+		return t ? (T(), e.setQueryData(["schema", !0], n.schema ?? v())) : r.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
@@ -181,10 +181,10 @@ function A({ children: e, authenticated: t = !0, ...n }) {
 		}), D(n), e;
 	});
 	return /* @__PURE__ */ g(p, {
-		client: r,
+		client: i,
 		children: [/* @__PURE__ */ h(u, {
 			initialEntries: [n.route ?? "/"],
-			children: /* @__PURE__ */ h(a, { children: e })
+			children: /* @__PURE__ */ h(o, { children: e })
 		}), /* @__PURE__ */ h(m, {})]
 	});
 }

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

@@ -1,4 +1,4 @@
-import type { AccentDef, LocalizedString } from "./schema";
+import type { AccentDef, EntityField, LocalizedString } from "./schema";
 import type { HydratedFile } from "./files";
 import type { FilterNode } from "../lib/filters";
 export interface ListMeta {
@@ -398,7 +398,7 @@ export interface ParamLookup {
 /**
  * One entry of the bulk `GET /api/params` response (and per-code resolution).
  * Carries the declaration facets the admin UIs need to compute attachment,
- * render structure editors, and render choice selects, so the bulk endpoint is
+ * render structure editors, and render member selects, so the bulk endpoint is
  * self-sufficient without a second schema fetch.
  */
 export interface ResolvedParam {
@@ -413,8 +413,12 @@ export interface ResolvedParam {
     scopes?: string[];
     /** Structure code when `type === "structure"`. */
     structure?: string;
-    /** Closed value set for a choices-constrained string param. */
-    choices?: string[];
+    /** Members of a closed type - `enum`, or an enum-backed `string_array`.
+     *  Carried whole rather than as bare codes so the editor can show a name. */
+    values?: EntityField["values"];
+    /** Shared enum this parameter names, when it names one rather than listing
+     *  its members inline. Present for display; `values` is what to render. */
+    enum?: string;
 }
 export interface ParamOverride {
     param_code: string;

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

@@ -301,6 +301,12 @@ export interface ParameterDef {
     category?: string;
     /** Override scopes accepted on writes. Subset of: env, tenant, role, user, object. Empty = all. */
     scopes?: string[];
+    /** Members of a closed type - `enum`, or an enum-backed `string_array`. Resolved
+     *  at load whether declared inline or by naming a shared enum, so this is the set
+     *  the platform enforces. Same shape a field's members have. */
+    values?: EntityField["values"];
+    /** The shared enum this parameter names, when it names one. `values` is what to render. */
+    enum?: string;
 }
 export interface AssociationDisplay {
     name?: LocalizedString;