@declarion/react 0.38.5 → 0.40.0

package/dist-lib/stores/list-layout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-device list-table WIDTH store (plan 2026-07-18 "Adjustable table
+ * columns", rev 2). Holds ONE thing: column pixel widths, device-local in
+ * localStorage, per (tenant, user, SCREEN) by column id. Screen-keyed, so
+ * widening a column once holds across EVERY view of that screen on this device.
+ * Absent entry = the YAML default (`field.display.width ?? 150`), resolved by
+ * TanStack when `header.getSize()` reads `columnSizing[id] ?? columnDef.size`.
+ *
+ * Why widths are the ONLY thing here: order/visibility/sort/filters already
+ * live in the URL and are persisted per device per tab by the `tabs` store -
+ * that is the single source of truth for the logical layout (a second store
+ * mirroring them caused a cold-open seed to clobber `?sort`; removed in rev 2).
+ * Width is the one column setting that must NOT ride a shareable URL: it is
+ * physical fit (a width tuned for a 27"/4K monitor would corrupt the same view
+ * for a teammate on a laptop), so it is device-local and never in a saved view.
+ *
+ * This does NOT violate the "browser stores nothing" appearance-preferences
+ * rule (Decision 33, `preferences.ts`): that governs deployment BRANDING
+ * (theme/accent/density). Widths are device state of the same class as the
+ * `tabs` store, which already uses localStorage. Keying + persistence mirror
+ * `stores/tabs.ts`: a module-level (tenant,user) scope set via `setScope`, the
+ * whole snapshot under one key `declarion::${tenantId}::${userId}::listlayout`,
+ * hydrated on tenant switch. `childKey` callers pass a composite screenKey
+ * `${screenCode}::child::${childKey}`; the store is agnostic to it.
+ */
+/** Minimum resizable column width in px. Exported so the resize handler and
+ *  the store's defensive clamp share ONE floor (no magic number). */
+export declare const MIN_COL_WIDTH = 60;
+/** Maximum resizable column width in px (a sane cap so a column can never
+ *  become absurdly wide). Shared by the TanStack per-column `maxSize` and the
+ *  store's defensive clamp. */
+export declare const MAX_COL_WIDTH = 1200;
+/** Snapshot schema version. A snapshot with a different `v` is discarded on
+ *  read (future migrations plug in here). */
+export declare const LIST_LAYOUT_VERSION = 2;
+/** A screen's width overrides: colId -> pixel width. */
+export type WidthMap = Record<string, number>;
+interface LayoutSnapshot {
+    v: number;
+    /** screenKey -> (colId -> width). */
+    widths: Record<string, WidthMap>;
+    /** True once this user has resized any column on this device - gates the
+     *  one-time "widths are personal per device" education toast. */
+    resizeEduShown?: boolean;
+}
+interface LayoutState extends LayoutSnapshot {
+    setScope: (tenantId: string | null, userId: string | null) => void;
+    hydrate: () => void;
+    /** Set one column's width (clamped). */
+    setWidth: (screenKey: string, colId: string, width: number) => void;
+    /** Merge a batch of column widths (clamped). */
+    setWidths: (screenKey: string, widths: WidthMap) => void;
+    /** Drop all width overrides for a screen (back to YAML defaults). Stored as
+     *  an empty map, not a deleted key, so the reset propagates across tabs. */
+    resetWidths: (screenKey: string) => void;
+    /** Drop width entries for colIds no longer in the screen schema. */
+    prune: (screenKey: string, validColIds: string[]) => void;
+    /** Record that the one-time resize-education toast has been shown. */
+    markResizeEduShown: () => void;
+}
+/** Narrow an untrusted persisted snapshot (localStorage is hostile) to
+ *  LayoutSnapshot, discarding anything malformed or of a foreign version. */
+export declare function parseLayoutSnapshot(raw: string): LayoutSnapshot | null;
+/**
+ * Merge an incoming cross-tab snapshot into the local one, last-writer-wins per
+ * screenKey (a screenKey present in `incoming` replaces the local value
+ * wholesale, so a prune / reset-to-`{}` / edit all propagate; screenKeys only
+ * the local tab touched survive).
+ */
+export declare function mergeSnapshot(local: LayoutSnapshot, incoming: LayoutSnapshot): LayoutSnapshot;
+export declare const useListLayoutStore: import("zustand").UseBoundStore<import("zustand").StoreApi<LayoutState>>;
+/** Subscribe to the window `storage` event for the layout key and merge an
+ *  incoming snapshot (last-writer-wins per screenKey). Idempotent. */
+export declare function startListLayoutCrossTabSync(): void;
+export interface ScopedListLayout {
+    widths: WidthMap;
+    /** Whether the one-time resize-education toast has already been shown. */
+    resizeEduShown: boolean;
+    setWidth: (colId: string, width: number) => void;
+    setWidths: (widths: WidthMap) => void;
+    resetWidths: () => void;
+    prune: (validColIds: string[]) => void;
+    markResizeEduShown: () => void;
+}
+export declare function useListLayout(screenKey: string | null | undefined): ScopedListLayout;
+export {};

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { Ln as e, _t as t, at as n, ft as r, mt as i, pt as a, r as o, t as s } from "./useCurrentScreen-DD3KdlMj.js";
+import { Dt as e, Mt as t, Ot as n, Qn as r, bt as i, kt as a, r as o, t as s } from "./useCurrentScreen-mw8TfE8q.js";
 import { useState as c } from "react";
 import { MemoryRouter as l } from "react-router-dom";
 import { QueryClient as u, QueryClientProvider as d } from "@tanstack/react-query";
@@ -85,11 +85,11 @@ function C(e) {
 	}
 	return e;
 }
-function w(e) {
-	let t = e.entityData ?? {};
-	i((e, n) => {
-		let r = t[e], i = C(r), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
-		return n.count === "only" ? {
+function w(t) {
+	let r = t.entityData ?? {};
+	a((e, t) => {
+		let n = r[e], i = C(n), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
+		return t.count === "only" ? {
 			data: [],
 			meta: {
 				page: 1,
@@ -108,50 +108,50 @@ function w(e) {
 			...i.refs === void 0 ? {} : { $refs: i.refs }
 		};
 	});
-	let o = e.entityItems ?? {}, s = e.entityItemResponses ?? {};
-	a((e, t) => {
-		let r = typeof t == "string" ? t : n(t), i = s[e]?.[r];
-		if (i instanceof Error) throw i;
-		if (i !== void 0) return i;
-		let a = o[e]?.[r];
+	let o = t.entityItems ?? {}, s = t.entityItemResponses ?? {};
+	n((e, t) => {
+		let n = typeof t == "string" ? t : i(t), r = s[e]?.[n];
+		if (r instanceof Error) throw r;
+		if (r !== void 0) return r;
+		let a = o[e]?.[n];
 		if (a instanceof Error) throw a;
 		return { data: a };
 	});
-	let c = e.actionResults ?? {};
-	r(async (e, t) => {
+	let c = t.actionResults ?? {};
+	e(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 x(typeof n == "function" ? await n(t) : n);
 	});
 }
 function T() {
-	i(null), a(null), r(null), t.setState({
+	a(null), n(null), e(null), t.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
 		tenants: []
 	});
 }
-function E(t, n = {}) {
-	let r = new u({ defaultOptions: { queries: {
+function E(e, t = {}) {
+	let n = new u({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
 	} } });
-	S(), r.setQueryData(["schema", !0], n.schema ?? g()), w(n);
-	let i = n.screenCode ? /* @__PURE__ */ p(s, {
-		code: n.screenCode,
-		children: t
-	}) : t, a = /* @__PURE__ */ m(d, {
-		client: r,
+	S(), n.setQueryData(["schema", !0], t.schema ?? g()), w(t);
+	let i = t.screenCode ? /* @__PURE__ */ p(s, {
+		code: t.screenCode,
+		children: e
+	}) : e, a = /* @__PURE__ */ m(d, {
+		client: n,
 		children: [/* @__PURE__ */ p(l, {
-			initialEntries: [n.route ?? "/"],
+			initialEntries: [t.route ?? "/"],
 			children: /* @__PURE__ */ p(o, { children: i })
 		}), /* @__PURE__ */ p(f, {})]
-	}), c = h(n.viewport ? /* @__PURE__ */ p(e, {
-		viewportOverride: n.viewport,
+	}), c = h(t.viewport ? /* @__PURE__ */ p(r, {
+		viewportOverride: t.viewport,
 		children: a
 	}) : a);
-	return Object.assign(c, { queryClient: r });
+	return Object.assign(c, { queryClient: n });
 }
 function D({ children: e, authenticated: n = !0, ...r }) {
 	let [i] = c(() => {

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

@@ -355,7 +355,12 @@ export interface ParamLookup {
     source?: "object" | "user" | "role" | "tenant" | "env" | "yaml";
     type?: string;
 }
-/** @deprecated Prefer `ParamLookup`. Retained for callers still inspecting `source`. */
+/**
+ * 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
+ * self-sufficient without a second schema fetch.
+ */
 export interface ResolvedParam {
     code: string;
     name: LocalizedString;
@@ -364,6 +369,12 @@ export interface ResolvedParam {
     description?: LocalizedString;
     value: unknown;
     source: "object" | "user" | "role" | "tenant" | "env" | "yaml" | "none";
+    /** Override levels the param accepts (reserved words or entity codes). */
+    scopes?: string[];
+    /** Structure code when `type === "structure"`. */
+    structure?: string;
+    /** Closed value set for a choices-constrained string param. */
+    choices?: string[];
 }
 export interface ParamOverride {
     param_code: string;
@@ -449,6 +460,22 @@ export interface V2PropertyInstance {
     updated_by?: string;
 }
 /** Per-row parameter override. */
+/**
+ * The last verification verdict of an evidence-covered row, shipped under the
+ * row's `$evidence` key (the evidence satellite, mirroring `$statuses`). Read
+ * cheaply from the stored verification result - never a live re-verify. Mirrors
+ * the Go `evidence.RowVerdict`. `verdict` is one of: `verified`, `unverified`,
+ * `tampered`, `erased`, `indeterminate`, `outside_coverage`.
+ */
+export interface EvidenceVerdict {
+    verdict: string;
+    verified_at?: string;
+    reason?: string;
+    seq?: number;
+    generation?: number;
+    checkpoint_number?: number;
+    covered: boolean;
+}
 export interface V2ParamInstance {
     param_code: string;
     value: unknown;
@@ -498,4 +525,5 @@ export interface EnrichedRow extends RowData {
     $params?: V2ParamInstance[];
     $children?: Record<string, Record<string, unknown>[]>;
     $units?: Units;
+    $evidence?: EvidenceVerdict;
 }

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

@@ -360,6 +360,11 @@ export interface Entity {
     tenant_key?: string;
     children?: ChildRelation[];
     status_groups?: Record<string, StatusGroupDef>;
+    /** Computed by the server: this entity's rows are evidence-covered (an
+     *  `evidence:` block, or an audit table the core audit source covers). Drives
+     *  the evidence panel / `?expand=evidence` the same way `status_groups` drives
+     *  the statuses surface. Absent for uncovered entities. */
+    evidence_covered?: boolean;
     properties?: Record<string, PropertyDef>;
     search_fields?: string[];
     actions?: Record<string, Action>;
@@ -377,6 +382,10 @@ export interface Entity {
      *  routes a singleton entity's detail screen at the screen's declared
      *  `route:` without a `:id` segment, and skips list-route registration. */
     singleton?: boolean;
+    /** Carrier scope its `$params` writes land under (e.g. my_tenant -> "tenant",
+     *  profile -> "user"). Absent = writes land under the entity's own code. Used
+     *  by ParamsBlock to compute the attachable parameter set. */
+    params_scope?: string;
     /** Server-enforced WHERE applied unconditionally on every read/write
      *  via server/handlers/data_prefilter.go. Values may be literal scalars
      *  OR `$caller.*` expressions (`$caller.user_id`, `$caller.tenant_id`)
@@ -759,6 +768,9 @@ export interface HandlerParam {
         description?: LocalizedString;
         color?: string;
     }>;
+    /** `type: structure` (or structure-shaped json) param target: the top-level
+     *  structure code whose fields the dialog renders as a nested form. */
+    structure?: string;
     /** `type: ref` param target. Scalar entity-code string (shorthand) OR a
      *  structured RefConfig (non-id lookup / display). Normalize via
      *  normalizeRefConfig before use. */