@declarion/react 0.23.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.js

@@ -1,4 +1,4 @@
-import { Pt as e, ct as t, lt as n, t as r, tt as i, ut as a } from "./ActionRunner-C2A73D9b.js";
+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";
@@ -86,42 +86,42 @@ function x(e) {
 	return e;
 }
 function S(e) {
-	let r = e.entityData ?? {};
-	a((e, t) => {
-		let n = r[e], i = x(n), a = i.meta?.per_page ?? 50, o = i.meta?.total ?? i.rows.length;
+	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 y(typeof n == "function" ? await n(t) : n);
 	});
 }
 function C() {
-	a(null), n(null), t(null), e.setState({
+	n(null), t(null), a(null), e.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,
@@ -134,33 +134,33 @@ function w(e, t = {}) {
 		gcTime: Infinity
 	} } });
 	b(), n.setQueryData(["schema", !0], t.schema ?? m()), S(t);
-	let i = p(/* @__PURE__ */ f(l, {
+	let r = p(/* @__PURE__ */ f(l, {
 		client: n,
 		children: [/* @__PURE__ */ d(s, {
 			initialEntries: [t.route ?? "/"],
-			children: /* @__PURE__ */ d(r, { children: e })
+			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, ...i }) {
+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], i.schema ?? m())) : e.setState({
+		return n ? (b(), t.setQueryData(["schema", !0], r.schema ?? m())) : e.setState({
 			user: null,
 			isAuthenticated: !1,
 			activeTenant: null,
 			tenants: []
-		}), S(i), t;
+		}), S(r), t;
 	});
 	return /* @__PURE__ */ f(l, {
 		client: a,
 		children: [/* @__PURE__ */ d(s, {
-			initialEntries: [i.route ?? "/"],
-			children: /* @__PURE__ */ d(r, { children: t })
+			initialEntries: [r.route ?? "/"],
+			children: /* @__PURE__ */ d(i, { children: t })
 		}), /* @__PURE__ */ d(u, {})]
 	});
 }

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.23.0",
+  "version": "0.24.0",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",