@declarion/react 0.22.0 → 0.24.0

package/dist-lib/lib/filters.d.ts

@@ -11,6 +11,25 @@ export interface FilterNode {
 }
 /** All supported filter operator codes. */
 export type FilterOp = "eq" | "not_eq" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in" | "between" | "contains" | "starts_with" | "is_empty" | "is_not_empty" | "today" | "this_week" | "this_month" | "last_7_days" | "last_30_days" | "last_hour" | "last_24_hours";
+/**
+ * Resolution status of one filter value, produced by the filter-value label
+ * resolver (`useFilterValueLabels`). `special` / `resolved` carry a `label`
+ * and are terminal-synchronous (no flicker); `loading` is a ref fetch in
+ * flight (render a skeleton, never the raw uuid); `unresolved` is a ref that
+ * could not be labeled (deleted / no access); `plain` is a literal/number/date
+ * (rendered raw, as before).
+ */
+export type FilterValueStatus = "special" | "resolved" | "loading" | "unresolved" | "plain";
+/** Resolver result for one `(field, value)`: a label when known, the raw
+ *  coerced value always (the terminal fallback). */
+export interface FilterValueLabel {
+    status: FilterValueStatus;
+    label?: string;
+    raw: string;
+}
+/** Maps one stored filter `(field, value)` to its human label. The single
+ *  source of chip + drawer value labels; see `useFilterValueLabels`. */
+export type FilterValueResolver = (field: string, value: unknown) => FilterValueLabel;
 /** Operators that don't take a value. */
 export declare const NO_VALUE_OPS: Set<FilterOp>;
 /** Human-friendly display names for operators. */
@@ -30,8 +49,17 @@ export declare function hasOrGroups(nodes: FilterNode[]): boolean;
 export declare function flatFieldConditions(nodes: FilterNode[]): FilterNode[];
 /** Count active field conditions in the filter tree. */
 export declare function countActiveFilters(nodes: FilterNode[]): number;
-/** Format a filter node for chip display. */
-export declare function formatFilterChip(node: FilterNode): string;
+/**
+ * Format a filter node for chip display as a string (op label + value).
+ *
+ * When a `resolveValue` resolver is passed, each value is humanized to its
+ * label for the synchronous statuses (`special` / `resolved`) and falls back
+ * to the raw value otherwise. Without a resolver, values render raw exactly as
+ * before. This string form is used in OR-group joins and as a fallback; the
+ * single-chip renderer (`FilterChips`) uses a richer per-value renderer that
+ * also shows a skeleton while a ref label loads.
+ */
+export declare function formatFilterChip(node: FilterNode, resolveValue?: FilterValueResolver): string;
 /** Create a simple equality filter node. */
 export declare function eqFilter(field: string, value: string): FilterNode;
 /** Remove a filter node by field name, recursing into OR/AND groups. */

package/dist-lib/testing.d.ts

@@ -1,4 +1,4 @@
-import { type ReactElement } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import { type RenderResult } from "@testing-library/react";
 import { QueryClient } from "@tanstack/react-query";
 import { type ActionExecuteRequest, type ActionExecuteResponse } from "./api/data";
@@ -64,3 +64,21 @@ export declare function cleanupDeclarion(): void;
  * live queryClient.
  */
 export declare function renderWithDeclarion(ui: ReactElement, opts?: RenderWithDeclarionOptions): RenderWithDeclarionResult;
+export interface PreviewHarnessProps extends RenderWithDeclarionOptions {
+    children: ReactNode;
+    /** Default true: seeds an admin user so useSchema's auth gate opens and the
+     *  screen renders authenticated. Set false to render a pre-login screen
+     *  (SignIn / SignUp / Forgot / Reset / TwoFA / AuthShell) in its logged-out
+     *  state, where useSchema stays disabled (no fetch) as in production. */
+    authenticated?: boolean;
+}
+/**
+ * Component form of {@link renderWithDeclarion} for live previews / stories /
+ * Storybook: wraps `children` in the SDK's real providers (QueryClient +
+ * MemoryRouter + ActionRunnerProvider + the Sonner outlet) and seeds the same
+ * read/action seams from props, so an SDK screen renders against fixtures with
+ * no network. Unlike renderWithDeclarion (which calls testing-library's render),
+ * this returns an element you compose directly. Providers + seeds are created
+ * once per mount (useState initializer) so a static snapshot is deterministic.
+ */
+export declare function PreviewHarness({ children, authenticated, ...opts }: PreviewHarnessProps): ReactElement;

package/dist-lib/testing.js

@@ -1,11 +1,12 @@
-import { Pt as e, ct as t, lt as n, t as r, tt as i, ut as a } from "./ActionRunner-C2A73D9b.js";
-import { MemoryRouter as o } from "react-router-dom";
-import { QueryClient as s, QueryClientProvider as c } from "@tanstack/react-query";
-import { Toaster as l } from "sonner";
-import { jsx as u, jsxs as d } from "react/jsx-runtime";
-import { render as f } from "@testing-library/react";
+import { It as e, dt as t, ft as n, rt as r, t as i, ut as a } from "./ActionRunner-eixtbT5K.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";
+import { Toaster as u } from "sonner";
+import { jsx as d, jsxs as f } from "react/jsx-runtime";
+import { render as p } from "@testing-library/react";
 //#region src/testing.tsx
-function p(e = {}) {
+function m(e = {}) {
 	return {
 		languages: [],
 		structures: {},
@@ -18,7 +19,7 @@ function p(e = {}) {
 		...e
 	};
 }
-function m(e, t = {}, n) {
+function h(e, t = {}, n) {
 	return {
 		data: e,
 		meta: {
@@ -32,27 +33,27 @@ function m(e, t = {}, n) {
 		...n === void 0 ? {} : { $refs: n }
 	};
 }
-function h(e) {
+function g(e) {
 	return e;
 }
-var g = Symbol("declarion.testing.actionEnvelope");
-function _(e) {
+var _ = Symbol("declarion.testing.actionEnvelope");
+function v(e) {
 	return {
 		...e,
-		[g]: !0
+		[_]: !0
 	};
 }
-function v(e) {
-	if (e && typeof e == "object" && e[g]) {
+function y(e) {
+	if (e && typeof e == "object" && e[_]) {
 		let t = { ...e };
-		return delete t[g], t;
+		return delete t[_], t;
 	}
 	return {
 		status: "success",
 		result: e
 	};
 }
-function y() {
+function b() {
 	let t = {
 		id: "test-tenant",
 		code: "test",
@@ -71,7 +72,7 @@ function y() {
 	};
 	e.getState().setUser(n, t);
 }
-function b(e) {
+function x(e) {
 	if (e === void 0) return { rows: [] };
 	if (Array.isArray(e)) return { rows: e };
 	if (Array.isArray(e.data)) {
@@ -84,64 +85,85 @@ function b(e) {
 	}
 	return e;
 }
-function x(e) {
-	let r = e.entityData ?? {};
-	a((e, t) => {
-		let n = r[e], i = b(n), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
+function S(e) {
+	let i = e.entityData ?? {};
+	n((e, t) => {
+		let n = i[e], r = x(n), a = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
 		return t.count === "only" ? {
 			data: [],
 			meta: {
 				page: 1,
 				per_page: a,
 				total: o,
-				total_pages: i.meta?.total_pages ?? Math.max(1, Math.ceil(o / a)),
-				count_mode: i.meta?.count_mode ?? "exact"
+				total_pages: r.meta?.total_pages ?? Math.max(1, Math.ceil(o / a)),
+				count_mode: r.meta?.count_mode ?? "exact"
 			}
 		} : {
-			data: i.rows,
+			data: r.rows,
 			meta: {
-				page: i.meta?.page ?? 1,
+				page: r.meta?.page ?? 1,
 				per_page: a,
-				has_more: i.meta?.has_more ?? !1
+				has_more: r.meta?.has_more ?? !1
 			},
-			...i.refs === void 0 ? {} : { $refs: i.refs }
+			...r.refs === void 0 ? {} : { $refs: r.refs }
 		};
 	});
 	let o = e.entityItems ?? {};
-	n((e, t) => {
-		let n = typeof t == "string" ? t : i(t);
+	t((e, t) => {
+		let n = typeof t == "string" ? t : r(t);
 		return { data: o[e]?.[n] };
 	});
 	let s = e.actionResults ?? {};
-	t(async (e, t) => {
+	a(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 v(typeof n == "function" ? await n(t) : n);
+		return y(typeof n == "function" ? await n(t) : n);
 	});
 }
-function S() {
-	a(null), n(null), t(null), e.setState({
+function C() {
+	n(null), t(null), a(null), e.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
 		tenants: []
 	});
 }
-function C(e, t = {}) {
-	let n = new s({ defaultOptions: { queries: {
+function w(e, t = {}) {
+	let n = new c({ defaultOptions: { queries: {
 		retry: !1,
 		gcTime: Infinity
 	} } });
-	y(), n.setQueryData(["schema", !0], t.schema ?? p()), x(t);
-	let i = f(/* @__PURE__ */ d(c, {
+	b(), n.setQueryData(["schema", !0], t.schema ?? m()), S(t);
+	let r = p(/* @__PURE__ */ f(l, {
 		client: n,
-		children: [/* @__PURE__ */ u(o, {
+		children: [/* @__PURE__ */ d(s, {
 			initialEntries: [t.route ?? "/"],
-			children: /* @__PURE__ */ u(r, { children: e })
-		}), /* @__PURE__ */ u(l, {})]
+			children: /* @__PURE__ */ d(i, { children: e })
+		}), /* @__PURE__ */ d(u, {})]
 	}));
-	return Object.assign(i, { queryClient: n });
+	return Object.assign(r, { queryClient: n });
+}
+function T({ children: t, authenticated: n = !0, ...r }) {
+	let [a] = o(() => {
+		let t = new c({ defaultOptions: { queries: {
+			retry: !1,
+			gcTime: Infinity
+		} } });
+		return n ? (b(), t.setQueryData(["schema", !0], r.schema ?? m())) : e.setState({
+			user: null,
+			isAuthenticated: !1,
+			activeTenant: null,
+			tenants: []
+		}), S(r), t;
+	});
+	return /* @__PURE__ */ f(l, {
+		client: a,
+		children: [/* @__PURE__ */ d(s, {
+			initialEntries: [r.route ?? "/"],
+			children: /* @__PURE__ */ d(i, { children: t })
+		}), /* @__PURE__ */ d(u, {})]
+	});
 }
-typeof afterEach == "function" && afterEach(() => S());
+typeof afterEach == "function" && afterEach(() => C());
 //#endregion
-export { _ as actionEnvelope, h as actionResults, S as cleanupDeclarion, m as entityDataFixture, C as renderWithDeclarion, p as schemaFixture };
+export { T as PreviewHarness, v as actionEnvelope, g as actionResults, C as cleanupDeclarion, h as entityDataFixture, w as renderWithDeclarion, m as schemaFixture };

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

@@ -44,6 +44,29 @@ export interface RefConfig {
     display?: RefDisplay;
     fields?: string[];
 }
+/** One declared filter-only option ({code, label}). `code` is stored into the
+ *  filter when chosen (a literal or a `$user.*` token resolved server-side);
+ *  `label` is the localized display string. Mirrors engine.FilterSpecialValue. */
+export interface FilterSpecialValue {
+    code: string;
+    label: LocalizedString;
+}
+/** Per-screen override of a field's filter_special_values, keyed in
+ *  Screen.filter_special_values by the filter field code. */
+export interface ScreenFilterSpecialValues {
+    mode?: "append" | "replace" | "clear";
+    values?: FilterSpecialValue[];
+}
+/** Normalizes a handler-param ref (scalar entity-code string OR structured
+ *  object) into a RefConfig. One helper shared by filters, SmartDetailPage
+ *  fields, and ActionDialog params so the scalar shorthand and structured form
+ *  reach the relation combobox identically. */
+export declare function normalizeRefConfig(ref: string | RefConfig | undefined): RefConfig | undefined;
+/** Computes the effective filter_special_values for a field on a screen by
+ *  merging the field-level list with an optional screen override per its mode
+ *  (append [default] / replace / clear). Pure; mirrors the engine's
+ *  EffectiveFilterSpecialValues so the SDK and loader agree. */
+export declare function effectiveFilterSpecialValues(fieldValues: FilterSpecialValue[] | undefined, override: ScreenFilterSpecialValues | undefined): FilterSpecialValue[];
 export interface UnitConfig {
     storage: string;
     display?: string;
@@ -98,6 +121,10 @@ export interface EntityField {
     enum?: string;
     files?: FileFieldDef;
     ref?: RefConfig;
+    /** Filter-only declared options (e.g. "Myself" -> $user.id) surfaced in this
+     *  field's filter control. Inert everywhere else. A screen MAY override these
+     *  per-screen via Screen.filter_special_values. */
+    filter_special_values?: FilterSpecialValue[];
     structure?: string;
     array?: boolean;
     copyable?: boolean;
@@ -529,6 +556,10 @@ export interface Screen {
     list_resizable?: boolean;
     detail_screen?: string;
     fixed_filters?: Record<string, unknown>;
+    /** Per-screen override of field-level filter_special_values, keyed by filter
+     *  field code. Append/replace/clear the entity field's declared values for
+     *  just this screen. Mirrors engine.Screen.FilterSpecialValues. */
+    filter_special_values?: Record<string, ScreenFilterSpecialValues>;
     views?: ViewDefinition[];
     /** Action slot promotion for list screens (rule-of-2). UI honors first 2.
      *  Note: primary_record_actions (detail header) was removed in Task 5 of plan
@@ -639,7 +670,10 @@ export interface HandlerParam {
         description?: LocalizedString;
         color?: string;
     }>;
-    ref?: string;
+    /** `type: ref` param target. Scalar entity-code string (shorthand) OR a
+     *  structured RefConfig (non-id lookup / display). Normalize via
+     *  normalizeRefConfig before use. */
+    ref?: string | RefConfig;
     display?: HandlerParamDisplay;
     /**
      * Narrows the param's option set. Values may be literals or templates

package/package.json

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