@qoretechnologies/reqraft 0.10.53 → 0.10.54-pr.115.ge2d364c

package/dist/components/form/engine/rowMenuContext.d.ts

@@ -0,0 +1,78 @@
+/// <reference types="react" />
+import { IReqoreDropdownItem } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
+/**
+ * SEAM (reqraft): an editor publishes its own actions into the row's ⋮ menu.
+ *
+ * A row already renders one overflow menu — Edit fullscreen, Remove field, and
+ * any `optionActions` the host injected — and the comment on it has always said
+ * why: *"this row already has a menu, so they reuse it rather than adding a
+ * second one beside it."* An EDITOR could not reach that menu, so an editor
+ * with affordances of its own had no choice but to draw a second ⋮ inside the
+ * value cell. The IDE's template field does exactly that, and the two menus
+ * ended up side by side on one control, at slightly different widths.
+ *
+ * `optionActions` does not solve it: that seam is host configuration, resolved
+ * from the option's name and schema before the editor exists, so it cannot know
+ * what the editor can offer *now* — whether its templates have loaded, whether
+ * the value is already an expression, which custom items the field was given.
+ *
+ * ## Why registration is keyed, and by whom
+ *
+ * Menu items carry `onClick` handlers, so they are a new array on every render
+ * and cannot be compared by value. An editor therefore publishes a `key`
+ * alongside them: a primitive describing WHICH items it is currently offering
+ * (`'expression,template'`). The row re-renders only when a publisher's key
+ * changes, so a re-rendering editor cannot drive the row into a state loop.
+ *
+ * Each registration also belongs to ONE publisher. A single shared slot let
+ * two publishers in the same row — an expression builder's operands — overwrite
+ * each other's key on every render, which re-rendered the row and both of them,
+ * which published again: a synchronous render loop that froze the page. And a
+ * slot that outlived its editor kept that editor's handlers after it unmounted,
+ * so a row closed and reopened offered items that did nothing. Registrations
+ * are therefore per publisher, withdrawn on unmount, and a click always reaches
+ * the handler from the publisher's latest render.
+ *
+ * Publish with `useRowMenuPublisher`; provide with `useRowMenuRegistry`.
+ */
+export interface IRowMenuRegistration {
+    /**
+     * Publish a publisher's menu items into the containing row's ⋮.
+     *
+     * @param publisherId identifies the publishing editor (one per mounted editor)
+     * @param key a primitive describing which items are being offered; the row
+     * re-renders only when it changes
+     * @param items the items to merge, or an empty array to contribute none
+     */
+    registerRowMenuItems: (publisherId: string, key: string, items: IReqoreDropdownItem[]) => void;
+    /** Withdraw a publisher's items — when it unmounts or leaves the row. */
+    unregisterRowMenuItems: (publisherId: string) => void;
+}
+/**
+ * Absent outside a compact row — the classic (non-compact) render path has no
+ * row menu to merge into, and an editor there keeps drawing its own control.
+ */
+export declare const RowMenuContext: import("react").Context<IRowMenuRegistration>;
+/**
+ * The row-menu channel for the row this editor is inside, or `undefined` when
+ * there is no row menu to publish into.
+ *
+ * An editor that finds it should render no menu of its own; one that does not
+ * must keep rendering its own, or its actions become unreachable.
+ */
+export declare const useRowMenu: () => IRowMenuRegistration | undefined;
+/**
+ * Publish `items` into `rowMenu` for as long as the calling editor is mounted.
+ * `rowMenu` is passed rather than read here so an editor can claim the channel
+ * and hide it from what it renders (see `TemplateField`).
+ */
+export declare const useRowMenuPublisher: (rowMenu: IRowMenuRegistration | undefined, key: string, items: IReqoreDropdownItem[]) => void;
+/**
+ * The row side of the channel: the registration to provide, and the items the
+ * row's ⋮ should list.
+ */
+export declare const useRowMenuRegistry: () => {
+    rowMenu: IRowMenuRegistration;
+    items: IReqoreDropdownItem[];
+};
+//# sourceMappingURL=rowMenuContext.d.ts.map

package/dist/components/form/engine/rowMenuContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowMenuContext.d.ts","sourceRoot":"","sources":["../../../../src/components/form/engine/rowMenuContext.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wDAAwD,CAAC;AAY7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,IAAI,CAAC;IAC/F,yEAAyE;IACzE,sBAAsB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,+CAA6D,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAO,oBAAoB,GAAG,SAAuC,CAAC;AAE7F;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YACrB,oBAAoB,GAAG,SAAS,OACpC,MAAM,SACJ,mBAAmB,EAAE,KAC3B,IAQF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAwD9B,CAAC"}

package/dist/components/form/engine/rowMenuContext.js

@@ -0,0 +1,103 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRowMenuRegistry = exports.useRowMenuPublisher = exports.useRowMenu = exports.RowMenuContext = void 0;
+var react_1 = require("react");
+/**
+ * Absent outside a compact row — the classic (non-compact) render path has no
+ * row menu to merge into, and an editor there keeps drawing its own control.
+ */
+exports.RowMenuContext = (0, react_1.createContext)(undefined);
+/**
+ * The row-menu channel for the row this editor is inside, or `undefined` when
+ * there is no row menu to publish into.
+ *
+ * An editor that finds it should render no menu of its own; one that does not
+ * must keep rendering its own, or its actions become unreachable.
+ */
+var useRowMenu = function () { return (0, react_1.useContext)(exports.RowMenuContext); };
+exports.useRowMenu = useRowMenu;
+/**
+ * Publish `items` into `rowMenu` for as long as the calling editor is mounted.
+ * `rowMenu` is passed rather than read here so an editor can claim the channel
+ * and hide it from what it renders (see `TemplateField`).
+ */
+var useRowMenuPublisher = function (rowMenu, key, items) {
+    var publisherId = (0, react_1.useId)();
+    (0, react_1.useEffect)(function () {
+        rowMenu === null || rowMenu === void 0 ? void 0 : rowMenu.registerRowMenuItems(publisherId, key, items);
+    }, [rowMenu, publisherId, key, items]);
+    (0, react_1.useEffect)(function () { return function () { return rowMenu === null || rowMenu === void 0 ? void 0 : rowMenu.unregisterRowMenuItems(publisherId); }; }, [rowMenu, publisherId]);
+};
+exports.useRowMenuPublisher = useRowMenuPublisher;
+/**
+ * The row side of the channel: the registration to provide, and the items the
+ * row's ⋮ should list.
+ */
+var useRowMenuRegistry = function () {
+    // Which publishers are offering which item SET — the only state, so only a
+    // change of set re-renders the row.
+    var _a = (0, react_1.useState)({}), keys = _a[0], setKeys = _a[1];
+    // Each publisher's items from its latest render, read at click time.
+    var latest = (0, react_1.useRef)({});
+    var registerRowMenuItems = (0, react_1.useCallback)(function (publisherId, key, items) {
+        latest.current[publisherId] = items;
+        setKeys(function (previous) {
+            var _a;
+            return previous[publisherId] === key ? previous : __assign(__assign({}, previous), (_a = {}, _a[publisherId] = key, _a));
+        });
+    }, []);
+    var unregisterRowMenuItems = (0, react_1.useCallback)(function (publisherId) {
+        delete latest.current[publisherId];
+        setKeys(function (previous) {
+            if (!(publisherId in previous)) {
+                return previous;
+            }
+            var next = __assign({}, previous);
+            delete next[publisherId];
+            return next;
+        });
+    }, []);
+    var rowMenu = (0, react_1.useMemo)(function () { return ({ registerRowMenuItems: registerRowMenuItems, unregisterRowMenuItems: unregisterRowMenuItems }); }, [registerRowMenuItems, unregisterRowMenuItems]);
+    var items = (0, react_1.useMemo)(function () {
+        return Object.keys(keys).flatMap(function (publisherId) {
+            var _a;
+            return ((_a = latest.current[publisherId]) !== null && _a !== void 0 ? _a : []).map(function (item, index) {
+                return item.onClick
+                    ? __assign(__assign({}, item), { 
+                        // Same key, same item set, so the index still names this item;
+                        // the handler is whatever the publisher rendered last.
+                        onClick: (function () {
+                            var _a, _b, _c;
+                            var args = [];
+                            for (var _i = 0; _i < arguments.length; _i++) {
+                                args[_i] = arguments[_i];
+                            }
+                            return (_c = (_b = (_a = latest.current[publisherId]) === null || _a === void 0 ? void 0 : _a[index]) === null || _b === void 0 ? void 0 : _b.onClick) === null || _c === void 0 ? void 0 : _c.call.apply(_c, __spreadArray([_b], args, false));
+                        }) }) : item;
+            });
+        });
+    }, [keys]);
+    return { rowMenu: rowMenu, items: items };
+};
+exports.useRowMenuRegistry = useRowMenuRegistry;
+//# sourceMappingURL=rowMenuContext.js.map

package/dist/components/form/engine/rowMenuContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowMenuContext.js","sourceRoot":"","sources":["../../../../src/components/form/engine/rowMenuContext.ts"],"names":[],"mappings":"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"}

package/dist/components/form/engine/typeChoices.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which options offer the per-type choices ("Integer", "Text", "Hash", …) in
+ * the row's menu.
+ *
+ * A field that pins no concrete type has to give the author some way to say
+ * what kind of value they mean, and the row menu is where that lives — the
+ * alternative, a standalone *"Please select data type"* control, replaces a
+ * typable field with a pick-only one.
+ *
+ * The rule was `ui_type === 'any'`, which is one of the three ways a schema
+ * says "untyped", so the choices went missing on the other two:
+ *
+ *  - **`type: 'auto'` with no `ui_type` at all.** This is how the server
+ *    declares an assertion's Expected Value, so that field never offered them.
+ *    They appeared only inside an expression, where the OPERAND's schema does
+ *    say `ui_type: 'any'` — so the same option offered them in the Visual view
+ *    and not in the Text view, which reads as the menu losing items.
+ *  - **A host's own untyped editor.** The IDE renders Expected Value through
+ *    `test-reference`, a `ui_type` reqraft knows nothing about; the field is no
+ *    less untyped for having a custom editor.
+ *
+ * `ui_type` is asked FIRST and on its own: a schema that names a concrete
+ * editor (`ui_type: 'string'`) has pinned the field even if its storage `type`
+ * is still `auto`.
+ */
+import { IQorusFormField } from '@qoretechnologies/ts-toolkit';
+/** The spellings that mean "no concrete type" wherever they appear. */
+export declare const BuiltInAnyLikeTypes: string[];
+/**
+ * Does this option leave its type up to the author?
+ *
+ * @param option the option's schema entry
+ * @param extraUiTypes host `ui_type` names that are untyped editors of their
+ * own — see `FormEngine`'s `anyLikeUiTypes`
+ */
+export declare const offersTypeChoices: (option: Partial<IQorusFormField> | undefined, extraUiTypes?: string[]) => boolean;
+//# sourceMappingURL=typeChoices.d.ts.map

package/dist/components/form/engine/typeChoices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeChoices.d.ts","sourceRoot":"","sources":["../../../../src/components/form/engine/typeChoices.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,UAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,WACpB,QAAQ,eAAe,CAAC,GAAG,SAAS,iBAC7B,MAAM,EAAE,KACtB,OAaF,CAAC"}

package/dist/components/form/engine/typeChoices.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.offersTypeChoices = exports.BuiltInAnyLikeTypes = void 0;
+/** The spellings that mean "no concrete type" wherever they appear. */
+exports.BuiltInAnyLikeTypes = ['any', 'auto'];
+/**
+ * Does this option leave its type up to the author?
+ *
+ * @param option the option's schema entry
+ * @param extraUiTypes host `ui_type` names that are untyped editors of their
+ * own — see `FormEngine`'s `anyLikeUiTypes`
+ */
+var offersTypeChoices = function (option, extraUiTypes) {
+    if (!option) {
+        return false;
+    }
+    var uiType = option.ui_type;
+    if (uiType) {
+        return exports.BuiltInAnyLikeTypes.includes(uiType) || !!(extraUiTypes === null || extraUiTypes === void 0 ? void 0 : extraUiTypes.includes(uiType));
+    }
+    // No `ui_type`: the storage type is the only thing that can pin the field.
+    return exports.BuiltInAnyLikeTypes.includes(option.type);
+};
+exports.offersTypeChoices = offersTypeChoices;
+//# sourceMappingURL=typeChoices.js.map

package/dist/components/form/engine/typeChoices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeChoices.js","sourceRoot":"","sources":["../../../../src/components/form/engine/typeChoices.ts"],"names":[],"mappings":";;;AA4BA,uEAAuE;AAC1D,QAAA,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAEnD;;;;;;GAMG;AACI,IAAM,iBAAiB,GAAG,UAC/B,MAA4C,EAC5C,YAAuB;IAEvB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAM,MAAM,GAAI,MAA+B,CAAC,OAAO,CAAC;IAExD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,2BAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,QAAQ,CAAC,MAAM,CAAC,CAAA,CAAC;IAClF,CAAC;IAED,2EAA2E;IAC3E,OAAO,2BAAmB,CAAC,QAAQ,CAAE,MAA4B,CAAC,IAAc,CAAC,CAAC;AACpF,CAAC,CAAC;AAhBW,QAAA,iBAAiB,qBAgB5B"}

package/dist/components/form/expressions/ExpressionField.d.ts

@@ -38,10 +38,16 @@ export interface IExpressionFieldProps {
     recordType?: string;
     /** Initial editor mode (default `visual`). */
     defaultMode?: TExpressionMode;
+    /**
+     * SEAM (reqraft): the host's per-`ui_type` editors, forwarded to the
+     * builder's operand fields. Without them an operand typed with one of the
+     * CONSUMER's ui_types renders "Unknown type!".
+     */
+    componentOverrides?: Record<string, React.FC<any>>;
     size?: string;
     /** Forwarded to the builder — operand reordering for varargs expressions. */
     reorder?: TExpressionReorder;
 }
-export declare const ExpressionField: import("react").MemoExoticComponent<({ value, onChange, type, returnType, readOnly, expressions: expressionsOverride, expressionsUrl, localTemplates, serverHandled, extraActions, provider, recordType, defaultMode, size, reorder, }: IExpressionFieldProps) => import("react/jsx-runtime").JSX.Element>;
+export declare const ExpressionField: import("react").MemoExoticComponent<({ value, onChange, type, returnType, readOnly, expressions: expressionsOverride, expressionsUrl, localTemplates, serverHandled, extraActions, provider, recordType, defaultMode, size, componentOverrides, reorder, }: IExpressionFieldProps) => import("react/jsx-runtime").JSX.Element>;
 export default ExpressionField;
 //# sourceMappingURL=ExpressionField.d.ts.map

package/dist/components/form/expressions/ExpressionField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpressionField.d.ts","sourceRoot":"","sources":["../../../../src/components/form/expressions/ExpressionField.tsx"],"names":[],"mappings":";AAYA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mDAAmD,CAAC;AAGzF,OAAO,EAAqB,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAoB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAI/F,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,CAAC;AAShD,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC,cAAc,CAAC,CAAC;IACvD,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,eAAO,MAAM,eAAe,0OAiBvB,qBAAqB,6CAgMzB,CAAC;AAEF,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ExpressionField.d.ts","sourceRoot":"","sources":["../../../../src/components/form/expressions/ExpressionField.tsx"],"names":[],"mappings":";AAaA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mDAAmD,CAAC;AAGzF,OAAO,EAAqB,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAoB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAI/F,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,CAAC;AAkBhD,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC,cAAc,CAAC,CAAC;IACvD,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,eAAO,MAAM,eAAe,8PAkBvB,qBAAqB,6CA4XzB,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/components/form/expressions/ExpressionField.js

@@ -43,8 +43,9 @@ var jsx_runtime_1 = require("react/jsx-runtime");
 // Owns the `IExpression` value and offers two views of the same AST —
 // Visual (the builder, Phase 3) and Text (DPQL, this phase). The DPQL text
 // editor bridges to the AST via the LSP `dpql/parse` (text → AST on edit)
-// and `dpql/serialize` (AST → text on entering Text mode); a live "Parsed"
-// line renders the current AST (`dpql/renderExpression`).
+// and `dpql/serialize` (AST → text on entering Text mode); a debounced
+// "Preview" box renders the current AST (`dpql/renderExpression`) when that
+// rendering differs from the text the author typed.
 var reqore_1 = require("@qoretechnologies/reqore");
 var react_1 = require("react");
 var dpqlEditor_1 = require("../../dpqlEditor");
@@ -52,13 +53,22 @@ var builder_1 = require("./builder");
 var useExpressions_1 = require("./useExpressions");
 var useRenderExpression_1 = require("./useRenderExpression");
 var PARSE_DEBOUNCE_MS = 300;
+/**
+ * How long the Preview waits before catching up with the editor.
+ *
+ * It mirrors the AST, so without this it re-renders on every keystroke — a box
+ * appearing, changing and vanishing under the line being typed. Slightly
+ * SLOWER than the parse it follows, so the preview settles once after the text
+ * has stopped moving rather than twitching on the way there.
+ */
+var PREVIEW_DEBOUNCE_MS = 400;
 /** Retry cadence for seeding the Text editor while its LSP session opens. */
 var SEED_RETRY_MS = 400;
 var SEED_MAX_TRIES = 20;
 var noop = function () { return undefined; };
 exports.ExpressionField = (0, react_1.memo)(function (_a) {
     var _b;
-    var value = _a.value, onChange = _a.onChange, type = _a.type, returnType = _a.returnType, readOnly = _a.readOnly, expressionsOverride = _a.expressions, expressionsUrl = _a.expressionsUrl, localTemplates = _a.localTemplates, serverHandled = _a.serverHandled, extraActions = _a.extraActions, provider = _a.provider, recordType = _a.recordType, _c = _a.defaultMode, defaultMode = _c === void 0 ? 'visual' : _c, size = _a.size, reorder = _a.reorder;
+    var value = _a.value, onChange = _a.onChange, type = _a.type, returnType = _a.returnType, readOnly = _a.readOnly, expressionsOverride = _a.expressions, expressionsUrl = _a.expressionsUrl, localTemplates = _a.localTemplates, serverHandled = _a.serverHandled, extraActions = _a.extraActions, provider = _a.provider, recordType = _a.recordType, _c = _a.defaultMode, defaultMode = _c === void 0 ? 'visual' : _c, size = _a.size, componentOverrides = _a.componentOverrides, reorder = _a.reorder;
     var expressions = (0, useExpressions_1.useExpressions)({
         override: expressionsOverride,
         expressionsUrl: expressionsUrl,
@@ -72,65 +82,196 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
     // Text mode state. `text` is the DPQL string the editor shows; the AST
     // (`value`) stays the source of truth, kept in sync via parse-on-edit.
     var _f = (0, react_1.useState)(''), text = _f[0], setText = _f[1];
+    /* The text the current AST was parsed FROM.
+     *
+     * The preview renders the AST, and the AST only moves on a SUCCESSFUL
+     * parse — so while an edit is mid-flight or simply invalid, the AST still
+     * describes the last thing that parsed. Showing it then states something
+     * the editor does not contain: deleting the `2` from `1 + 2` left
+     * "Unexpected end of input" sitting directly above a Preview confidently
+     * reading `1 + 2`. */
+    var _g = (0, react_1.useState)(''), astText = _g[0], setAstText = _g[1];
+    /**
+     * The server's answer to "can this expression's result satisfy the type
+     * this field declares?". `null` when nothing has been asked, or when the
+     * field declares no type worth asking about.
+     */
+    var _h = (0, react_1.useState)(null), typeCheck = _h[0], setTypeCheck = _h[1];
     var dpqlRef = (0, react_1.useRef)(null);
     var parseTimer = (0, react_1.useRef)(null);
     var ast = (0, react_1.useMemo)(function () { return value === null || value === void 0 ? void 0 : value.value; }, [value]);
+    /**
+     * The type the expression's result has to satisfy, sent with every parse.
+     *
+     * `auto` and `any` are left out deliberately: they accept anything, so the
+     * server would answer "compatible" for everything and the round trip would
+     * buy nothing. A field offering a CHOICE of return types has no single
+     * answer either, so it asks nothing rather than asking about the wrong one.
+     */
+    var targetType = (0, react_1.useMemo)(function () {
+        var declared = Array.isArray(returnType) ? undefined : (returnType !== null && returnType !== void 0 ? returnType : type);
+        return declared && declared !== 'auto' && declared !== 'any' ? declared : undefined;
+    }, [returnType, type]);
+    /** Read the type analysis off a parse result, or clear it. */
+    var readTypeCheck = (0, react_1.useCallback)(function (result) {
+        var _a;
+        if (!result || result.type_compatible === undefined) {
+            setTypeCheck(null);
+            return;
+        }
+        setTypeCheck({
+            compatible: !!result.type_compatible,
+            mayFail: !!result.coercion_may_fail,
+            inferred: result.inferred_type,
+            target: result.target_type,
+            fix: (_a = result.suggested_fix) === null || _a === void 0 ? void 0 : _a.text,
+        });
+    }, []);
     // Keep a readable rendering of the current expression in sync — the
     // single live mirror of the AST (server `dpql/renderExpression` when
     // reachable, the client-side approximation otherwise).
+    //
+    // Debounced: it follows the AST, which follows the text, so rendering it
+    // eagerly put a box under the cursor that appeared, changed and vanished
+    // while the author was still typing.
     (0, react_1.useEffect)(function () {
         var live = true;
-        renderRich(ast !== null && ast !== void 0 ? ast : {}, expressions).then(function (r) {
-            if (live)
-                setPreview({ text: r.text, server: r.server });
-        });
+        var timer = setTimeout(function () {
+            renderRich(ast !== null && ast !== void 0 ? ast : {}, expressions).then(function (r) {
+                if (live)
+                    setPreview({ text: r.text, server: r.server });
+            });
+        }, PREVIEW_DEBOUNCE_MS);
         return function () {
             live = false;
+            clearTimeout(timer);
         };
     }, [renderRich, ast, expressions]);
     // Tracks whether the user has typed since entering Text mode, so a
     // slow seed response can't clobber their input.
     var userTypedRef = (0, react_1.useRef)(false);
-    var astRef = (0, react_1.useRef)(ast);
+    /* A cleared value must clear the editor with it.
+     *
+     * "Clear value" empties the option (`handleValueChange(name, undefined)`),
+     * but the DPQL text is local state seeded once on entering Text mode, and
+     * the seeding effect returns early for an empty AST — it exists to fill the
+     * editor, not to empty it. So the value went and the text stayed: the row
+     * reported "This field is required" while still showing `1 + 2`, which
+     * reads as the clear having silently failed.
+     *
+     * Only an AST that HAD content and lost it clears the box. A field that
+     * simply starts empty is left alone, so this cannot wipe what an author is
+     * part-way through typing before their first parse lands.
+     */
+    var hadExpression = (0, react_1.useRef)(false);
     (0, react_1.useEffect)(function () {
-        astRef.current = ast;
+        /* GONE, not merely incomplete.
+         *
+         * The first cut asked whether the AST still had an `exp`, and that is a
+         * state the value passes THROUGH while the author types: a half-written
+         * expression parses to something without one. So typing `1 + 2` cleared
+         * the editor mid-keystroke and the text vanished under the cursor.
+         *
+         * A clear removes the value itself, so that is what to watch: `value`
+         * empty, not an AST that is between shapes. Typing never produces that —
+         * `handleDpqlChange` only emits on a SUCCESSFUL parse, so an incomplete
+         * expression leaves the previous value in place. */
+        if (ast) {
+            hadExpression.current = true;
+            return;
+        }
+        if (hadExpression.current) {
+            hadExpression.current = false;
+            userTypedRef.current = false;
+            setText('');
+        }
     }, [ast]);
     // Text mode: parse the DPQL into the AST (debounced).
+    /* The session may not be attached when the debounce fires — the editor
+       mounts on the render that flips the mode, and its LSP session comes up
+       after that. `dpqlRef.current?.parse?.()` is optional all the way down, so
+       an early call resolves `undefined`, `readTypeCheck` CLEARS the analysis,
+       and nothing asks again: the author types once into a fresh Text field and
+       is told nothing about the type until they happen to type another
+       character.
+
+       The seeding effect below already retries for this exact reason
+       ("`serialize` resolves '' until the editor's LSP session is ready"); the
+       parse path needed the same care and did not have it. Same budget as
+       seeding, so a session that never arrives gives up rather than spinning.
+
+       Found by CI, not locally: the session is up before the debounce on a
+       fast machine, so the story asserting the type message passed here every
+       time and failed on the runner. */
     var handleDpqlChange = (0, react_1.useCallback)(function (next) {
         userTypedRef.current = true;
         setText(next);
         if (parseTimer.current)
             clearTimeout(parseTimer.current);
-        parseTimer.current = setTimeout(function () { return __awaiter(void 0, void 0, void 0, function () {
-            var result;
-            var _a, _b;
-            return __generator(this, function (_c) {
-                switch (_c.label) {
-                    case 0: return [4 /*yield*/, ((_b = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.parse) === null || _b === void 0 ? void 0 : _b.call(_a, next))];
+        var tries = 0;
+        var runParse = function () { return __awaiter(void 0, void 0, void 0, function () {
+            var parse, result;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        parse = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.parse;
+                        if (!parse) {
+                            if (++tries < SEED_MAX_TRIES) {
+                                parseTimer.current = setTimeout(runParse, SEED_RETRY_MS);
+                            }
+                            return [2 /*return*/];
+                        }
+                        return [4 /*yield*/, parse(next, targetType)];
                     case 1:
-                        result = _c.sent();
+                        result = _b.sent();
+                        readTypeCheck(result);
                         if ((result === null || result === void 0 ? void 0 : result.success) && result.expression) {
+                            setAstText(next);
                             // `dpql/parse` returns the field-ready `{ is_expression, value }`.
                             onChange(result.expression);
                         }
                         return [2 /*return*/];
                 }
             });
-        }); }, PARSE_DEBOUNCE_MS);
-    }, [onChange]);
-    // Seed the Text editor from the AST whenever Text mode becomes active
-    // (including a `defaultMode='text'` mount). This must run as an
-    // effect: the editor only mounts on the same render that flips the
-    // mode (so `dpqlRef` is null inside the click handler), and
-    // `serialize` resolves '' until the editor's LSP session is ready —
-    // hence the brief retry loop.
+        }); };
+        parseTimer.current = setTimeout(runParse, PARSE_DEBOUNCE_MS);
+    }, [onChange, targetType, readTypeCheck]);
+    /** Whether this visit to Text mode has already put the AST in the editor. */
+    var seededRef = (0, react_1.useRef)(false);
+    /* Seed the Text editor from the AST whenever Text mode becomes active
+     * (including a `defaultMode='text'` mount). This must run as an effect: the
+     * editor only mounts on the same render that flips the mode (so `dpqlRef`
+     * is null inside the click handler), and `serialize` resolves '' until the
+     * editor's LSP session is ready — hence the brief retry loop.
+     *
+     * It waits for an AST, because the AST can arrive AFTER the mode does. A
+     * host flips this shell into Text mode on the very render that accepts an
+     * expression, and the value it passes on that render is still the TEXT the
+     * author typed — the parsed AST only comes back through the form one render
+     * later. Keyed on the mode alone, the effect had already had its only turn
+     * by then: it found nothing to serialize, returned, and nothing asked
+     * again. The author landed in an empty editor with a Preview of their own
+     * expression sitting beside it, which reads as the text having been thrown
+     * away.
+     *
+     * Seeding happens at most ONCE per visit, and that is what makes watching
+     * the AST safe: `userTypedRef` guards what is being typed, but the AST
+     * MOVES as the author types — every successful parse replaces it — so an
+     * effect that re-seeded on each new AST would fight them for the editor. */
     (0, react_1.useEffect)(function () {
-        if (mode !== 'text')
+        if (mode !== 'text') {
+            // Leaving Text asks the question again on the next visit; the typing
+            // flag goes with it, or a stale one would suppress that visit's seed.
+            seededRef.current = false;
+            userTypedRef.current = false;
+            return undefined;
+        }
+        if (seededRef.current || userTypedRef.current)
             return undefined;
-        var seedAst = astRef.current;
-        if (!(seedAst === null || seedAst === void 0 ? void 0 : seedAst.exp))
+        if (!(ast === null || ast === void 0 ? void 0 : ast.exp))
             return undefined;
-        userTypedRef.current = false;
+        var seedAst = ast;
         var cancelled = false;
         var timer = null;
         var tries = 0;
@@ -145,7 +286,9 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
                         if (cancelled || userTypedRef.current)
                             return [2 /*return*/];
                         if (t) {
+                            seededRef.current = true;
                             setText(t);
+                            setAstText(t);
                         }
                         else if (++tries < SEED_MAX_TRIES) {
                             timer = setTimeout(seed, SEED_RETRY_MS);
@@ -160,7 +303,7 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
             if (timer)
                 clearTimeout(timer);
         };
-    }, [mode]);
+    }, [mode, ast]);
     // Switch to Text: the seeding effect above serializes the AST once
     // the editor's session is up.
     var enterTextMode = (0, react_1.useCallback)(function () {
@@ -176,9 +319,10 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
                     if (parseTimer.current)
                         clearTimeout(parseTimer.current);
                     if (!(mode === 'text' && text)) return [3 /*break*/, 2];
-                    return [4 /*yield*/, ((_b = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.parse) === null || _b === void 0 ? void 0 : _b.call(_a, text))];
+                    return [4 /*yield*/, ((_b = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.parse) === null || _b === void 0 ? void 0 : _b.call(_a, text, targetType))];
                 case 1:
                     result = _c.sent();
+                    readTypeCheck(result);
                     if ((result === null || result === void 0 ? void 0 : result.success) && result.expression) {
                         onChange(result.expression);
                     }
@@ -188,12 +332,16 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
                     return [2 /*return*/];
             }
         });
-    }); }, [mode, text, onChange]);
+    }); }, [mode, text, onChange, targetType, readTypeCheck]);
     (0, react_1.useEffect)(function () { return function () {
         if (parseTimer.current)
             clearTimeout(parseTimer.current);
     }; }, []);
-    return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, gapSize: 'small', className: 'expression-field', children: [(0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { gapSize: 'small', fluid: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'NodeTree', active: mode === 'visual', onClick: enterVisualMode, disabled: readOnly, size: size, children: "Visual" }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'CodeLine', active: mode === 'text', onClick: enterTextMode, disabled: readOnly, size: size, children: "Text" })] }), mode === 'text' ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(dpqlEditor_1.DpqlEditor, { ref: dpqlRef, value: text, onChange: handleDpqlChange, provider: provider, recordType: recordType, readOnly: readOnly, height: '48px' }), preview.text ? ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'info', size: 'small', title: 'Parsed', flat: true, opaque: false, children: preview.server ? (
+    return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, gapSize: 'small', className: 'expression-field', children: [(0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { gapSize: 'small', fluid: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'NodeTree', active: mode === 'visual', onClick: enterVisualMode, disabled: readOnly, size: size, children: "Visual" }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'CodeLine', active: mode === 'text', onClick: enterTextMode, disabled: readOnly, size: size, children: "Text" })] }), mode === 'text' ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(dpqlEditor_1.DpqlEditor, { ref: dpqlRef, value: text, onChange: handleDpqlChange, provider: provider, recordType: recordType, readOnly: readOnly, height: '48px' }), typeCheck && !typeCheck.compatible && ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreMessage, { intent: typeCheck.mayFail ? 'warning' : 'danger', size: 'small', flat: true, opaque: false, title: typeCheck.mayFail ? 'This may not fit' : 'This does not fit', children: ["The expression returns ".concat(typeCheck.inferred, ", and this field holds ").concat(typeCheck.target, "."), typeCheck.mayFail ?
+                                ' That conversion is attempted rather than guaranteed, so the value itself is checked when it runs.'
+                                : '', typeCheck.fix ? ((0, jsx_runtime_1.jsx)("div", { style: { marginTop: '6px' }, children: (0, jsx_runtime_1.jsx)("code", { "data-testid": 'expression-type-fix', children: typeCheck.fix }) })) : null] })), preview.text &&
+                        astText.trim() === text.trim() &&
+                        preview.text.trim() !== text.trim() ? ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'info', size: 'small', title: 'Preview', flat: true, opaque: false, children: preview.server ? (
                         // Server rendering shown through a read-only DpqlEditor:
                         // template-ref chips + LSP token colours; diagnostics off
                         // (the rendering is readable text, not parseable DPQL).
@@ -201,7 +349,7 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
                 // Default to `auto` when the field declares no return type, so a
                 // valid expression renders `muted` rather than `danger` (the
                 // builder's intent requires a truthy returnType).
-                returnType: ((_b = returnType !== null && returnType !== void 0 ? returnType : type) !== null && _b !== void 0 ? _b : 'auto'), readOnly: readOnly, localTemplates: localTemplates !== null && localTemplates !== void 0 ? localTemplates : { items: [] }, serverHandled: serverHandled, extraActions: extraActions, size: size, reorder: reorder }))] }));
+                returnType: ((_b = returnType !== null && returnType !== void 0 ? returnType : type) !== null && _b !== void 0 ? _b : 'auto'), readOnly: readOnly, localTemplates: localTemplates !== null && localTemplates !== void 0 ? localTemplates : { items: [] }, serverHandled: serverHandled, componentOverrides: componentOverrides, extraActions: extraActions, size: size, reorder: reorder }))] }));
 });
 exports.default = exports.ExpressionField;
 //# sourceMappingURL=ExpressionField.js.map