@qoretechnologies/reqraft 0.10.62 → 0.10.63-pr.142.g0b675cd

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

@@ -1,4 +1,15 @@
 "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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -49,11 +60,15 @@ var jsx_runtime_1 = require("react/jsx-runtime");
 var reqore_1 = require("@qoretechnologies/reqore");
 var react_1 = require("react");
 var dpqlEditor_1 = require("../../dpqlEditor");
+var TemplateBrowser_1 = require("../fields/template/TemplateBrowser");
 var dpqlHelpers_1 = require("../../dpqlEditor/dpqlHelpers");
 var builder_1 = require("./builder");
 var DpqlRendering_1 = require("./DpqlRendering");
+var textOfExpression_1 = require("./textOfExpression");
 var useExpressions_1 = require("./useExpressions");
 var useRenderExpression_1 = require("./useRenderExpression");
+var expressions_1 = require("../../../helpers/expressions");
+var useQorusTypes_1 = require("../../../hooks/useQorusTypes");
 var optionUiTypes_1 = require("../../../helpers/optionUiTypes");
 var PARSE_DEBOUNCE_MS = 300;
 /**
@@ -65,24 +80,159 @@ var PARSE_DEBOUNCE_MS = 300;
  * 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;
+/** A diagnostic that is an error: the server marks one severity 1, or `error`. */
+var isErrorDiagnostic = function (diagnostic) {
+    return diagnostic.severity === 1 || diagnostic.severity === 'error';
+};
+/** What the server says of a condition as a condition: drawn by the builder, on the cards it is about. */
+var CONDITION_DIAGNOSTIC_CODES = ['NOT_A_CONDITION', 'CONDITION_BY_TRUTHINESS'];
+/**
+ * What the server says of an expression built in the Visual view: its errors, in its words, at the danger
+ * intent. It writes the expression as DPQL (`dpql/serialize`) and reads it back (`dpql/parse`) on a document
+ * bound to the record's fields, as the Text view's document is - so the server judges what is built as it
+ * judges what is written. Mounted only while the Visual view shows a whole expression it can type.
+ *
+ * A condition is read as one (`condition: true`): what the server says of the whole condition and of each part
+ * of its `&&`, `||` and `!` goes to `onConditionParts`, for the builder to draw on the cards it is about, and is
+ * not repeated here.
+ */
+var ExpressionServerErrors = (0, react_1.memo)(function (_a) {
+    var expression = _a.expression, fields = _a.fields, provider = _a.provider, recordType = _a.recordType, condition = _a.condition, onConditionParts = _a.onConditionParts;
+    var dpql = (0, dpqlEditor_1.useDpqlSession)({ fields: fields, provider: provider, recordType: recordType });
+    var ready = dpql.session.isReady && dpql.session.isContextReady;
+    var _b = (0, react_1.useState)([]), errors = _b[0], setErrors = _b[1];
+    var expressionKey = JSON.stringify(expression);
+    var serialize = dpql.serialize, parse = dpql.parse;
+    (0, react_1.useEffect)(function () {
+        if (!ready)
+            return undefined;
+        var cancelled = false;
+        var check = function () { return __awaiter(void 0, void 0, void 0, function () {
+            var said, parts, whole, text, result, _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        said = [];
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 5, , 6]);
+                        return [4 /*yield*/, serialize(JSON.parse(expressionKey))];
+                    case 2:
+                        text = _b.sent();
+                        if (!text) return [3 /*break*/, 4];
+                        return [4 /*yield*/, parse(text, undefined, condition ? { condition: true } : undefined)];
+                    case 3:
+                        result = _b.sent();
+                        parts = (0, expressions_1.conditionPartsWithMessages)(result.parts, result.inferred_type, result.diagnostics);
+                        whole =
+                            condition ? (0, expressions_1.conditionWholeMessage)(result.inferred_type, result.diagnostics) : undefined;
+                        said = result.diagnostics
+                            .filter(function (d) {
+                            var _a;
+                            return isErrorDiagnostic(d) &&
+                                !(condition && CONDITION_DIAGNOSTIC_CODES.includes(String((_a = d.code) !== null && _a !== void 0 ? _a : '')));
+                        })
+                            .map(function (d) { return d.message; });
+                        _b.label = 4;
+                    case 4: return [3 /*break*/, 6];
+                    case 5:
+                        _a = _b.sent();
+                        // a server that cannot write or read it says nothing about it here
+                        said = [];
+                        parts = undefined;
+                        whole = undefined;
+                        return [3 /*break*/, 6];
+                    case 6:
+                        if (cancelled)
+                            return [2 /*return*/];
+                        setErrors(said);
+                        onConditionParts === null || onConditionParts === void 0 ? void 0 : onConditionParts(expressionKey, parts, whole);
+                        return [2 /*return*/];
+                }
+            });
+        }); };
+        void check();
+        return function () {
+            cancelled = true;
+        };
+    }, [ready, expressionKey, serialize, parse, condition, onConditionParts]);
+    if (!errors.length)
+        return null;
+    return ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, size: 'small', className: 'expression-server-errors', children: errors.map(function (message, index) { return ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'danger', "data-severity": 'danger', size: 'small', flat: true, opaque: false, children: message }, index)); }) }));
+});
 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, fields = _a.fields, recordType = _a.recordType, _c = _a.defaultMode, defaultMode = _c === void 0 ? 'visual' : _c, size = _a.size, componentOverrides = _a.componentOverrides, reorder = _a.reorder;
+    var _b, _c;
+    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, condition = _a.condition, extraActions = _a.extraActions, provider = _a.provider, fields = _a.fields, recordType = _a.recordType, _d = _a.defaultMode, defaultMode = _d === void 0 ? 'text' : _d, initialText = _a.initialText, heldAsValue = _a.heldAsValue, requestedMode = _a.requestedMode, hideModeToggle = _a.hideModeToggle, onTextUnavailable = _a.onTextUnavailable, onModeChange = _a.onModeChange, flushRef = _a.flushRef, size = _a.size, componentOverrides = _a.componentOverrides, reorder = _a.reorder;
     var expressions = (0, useExpressions_1.useExpressions)({
         override: expressionsOverride,
         expressionsUrl: expressionsUrl,
     }).expressions;
     var renderRich = (0, useRenderExpression_1.useRenderExpression)().renderRich;
-    var _d = (0, react_1.useState)(defaultMode), mode = _d[0], setMode = _d[1];
+    var _e = (0, react_1.useState)(defaultMode), mode = _e[0], setMode = _e[1];
+    var onModeChangeRef = (0, react_1.useRef)(onModeChange);
+    onModeChangeRef.current = onModeChange;
+    (0, react_1.useEffect)(function () {
+        var _a;
+        (_a = onModeChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onModeChangeRef, mode);
+    }, [mode]);
     /* The server's rendering of the current AST; empty until it has one. There is
        no client-side stand-in — see `useRenderExpression`. */
-    var _e = (0, react_1.useState)(''), preview = _e[0], setPreview = _e[1];
+    var _f = (0, react_1.useState)(''), preview = _f[0], setPreview = _f[1];
     // 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];
+    var _g = (0, react_1.useState)(initialText !== null && initialText !== void 0 ? initialText : ''), text = _g[0], setText = _g[1];
+    /** The text the editor was given, for its echo of that text to be told from typing. */
+    var textRef = (0, react_1.useRef)(text);
+    textRef.current = text;
+    /* No language server to parse or write the text: the Text view cannot work, so the field shows the
+       Visual view, which needs none, and says why (qorus#646). */
+    var _h = (0, react_1.useState)(false), textUnavailable = _h[0], setTextUnavailable = _h[1];
+    /* Why the server would not write this value as text, or null. The field is then built in Visual: an empty
+       Text view would be one the author types over, replacing the value (qorus#646). */
+    var _j = (0, react_1.useState)(null), textRefused = _j[0], setTextRefused = _j[1];
+    // read when a refusal lands, so a host's new callback on each render does not restart the seed
+    var onTextUnavailableRef = (0, react_1.useRef)(onTextUnavailable);
+    onTextUnavailableRef.current = onTextUnavailable;
+    /* Whether the Text view's language server can parse and write its text - the session's own signal
+       (`onReady`), never a guess by time. Typed text waits for it; it is not asked of a session that is not
+       up, whose answer is "nothing parsed" (qorus#646: under load, text typed before the session was up
+       never reached the value). Each visit to the Text view opens a session of its own. */
+    var _k = (0, react_1.useState)(false), sessionReady = _k[0], setSessionReady = _k[1];
+    var sessionReadyRef = (0, react_1.useRef)(false);
+    /** Who waits for the session: told true when it is ready, false when it cannot be reached or goes. */
+    var sessionWaiters = (0, react_1.useRef)([]);
+    var settleSessionWaiters = (0, react_1.useCallback)(function (ready) {
+        var waiters = sessionWaiters.current;
+        sessionWaiters.current = [];
+        waiters.forEach(function (resolve) { return resolve(ready); });
+    }, []);
+    var whenSessionReady = (0, react_1.useCallback)(function () {
+        return sessionReadyRef.current ?
+            Promise.resolve(true)
+            : new Promise(function (resolve) { return sessionWaiters.current.push(resolve); });
+    }, []);
+    var handleTextReady = (0, react_1.useCallback)(function () {
+        sessionReadyRef.current = true;
+        setSessionReady(true);
+        settleSessionWaiters(true);
+    }, [settleSessionWaiters]);
+    (0, react_1.useEffect)(function () {
+        if (mode === 'text')
+            return;
+        sessionReadyRef.current = false;
+        setSessionReady(false);
+        settleSessionWaiters(false);
+    }, [mode, settleSessionWaiters]);
+    (0, react_1.useEffect)(function () { return function () { return settleSessionWaiters(false); }; }, [settleSessionWaiters]);
+    var handleTextUnavailable = (0, react_1.useCallback)(function () {
+        setTextUnavailable(true);
+        settleSessionWaiters(false);
+        onTextUnavailable === null || onTextUnavailable === void 0 ? void 0 : onTextUnavailable();
+        // text typed and not read stays as typed, in the Text view, with the reason under it: nothing is lost
+        if (pendingParse.current !== null)
+            return;
+        setMode('visual');
+    }, [onTextUnavailable, settleSessionWaiters]);
     /* The text the current AST was parsed FROM.
      *
      * The preview renders the AST, and the AST only moves on a SUCCESSFUL
@@ -91,15 +241,17 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
      * 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];
+    var _l = (0, react_1.useState)(''), astText = _l[0], setAstText = _l[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 _m = (0, react_1.useState)(null), typeCheck = _m[0], setTypeCheck = _m[1];
     var dpqlRef = (0, react_1.useRef)(null);
     var parseTimer = (0, react_1.useRef)(null);
+    /** The text typed whose parse is still waiting on the debounce, or null. */
+    var pendingParse = (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.
@@ -113,6 +265,36 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
         var declared = Array.isArray(returnType) ? undefined : (returnType !== null && returnType !== void 0 ? returnType : type);
         return declared && !(0, optionUiTypes_1.isUntypedOptionType)(declared) ? declared : undefined;
     }, [returnType, type]);
+    /** A condition is asked as one, not as a type to fit. */
+    var parseOptions = (0, react_1.useMemo)(function () { return (condition ? { condition: true } : undefined); }, [condition]);
+    /**
+     * The expression built in the Visual view, as the server is asked about it (qorus#646): whole, and only
+     * where the server can type its operands - with the record's fields or a provider's. The server refuses
+     * operands its operators cannot combine (DPQL-E050, `@create + 1` with `create` a hash), which nothing
+     * on this side can tell; the Text view shows it as the server publishes it, and so does this view.
+     */
+    var serverCheckable = (0, react_1.useMemo)(function () {
+        return (mode === 'visual' &&
+            ((!!fields && Object.keys(fields).length > 0) || !!provider || !!condition)) ?
+            (0, textOfExpression_1.serializableExpression)(ast)
+            : undefined;
+    }, [mode, fields, provider, condition, ast]);
+    /* What the server said of each part of the condition built in the Visual view (qorus#646), for the
+       expression it was said of: an answer about an expression since edited is not drawn on it. */
+    var _o = (0, react_1.useState)(), conditionParts = _o[0], setConditionParts = _o[1];
+    var onConditionParts = (0, react_1.useCallback)(function (key, parts, whole) {
+        return setConditionParts({ key: key, parts: parts, whole: whole });
+    }, []);
+    var currentCondition = serverCheckable && (conditionParts === null || conditionParts === void 0 ? void 0 : conditionParts.key) === JSON.stringify(serverCheckable) ?
+        conditionParts
+        : undefined;
+    var currentConditionParts = currentCondition === null || currentCondition === void 0 ? void 0 : currentCondition.parts;
+    /* What the server says of the whole condition built in the Visual view, in its words: drawn there as the
+       Text view draws it, in place of the builder's own fallback. */
+    var currentConditionMessage = currentCondition === null || currentCondition === void 0 ? void 0 : currentCondition.whole;
+    var qorusTypes = (0, useQorusTypes_1.useQorusTypes)();
+    /** A type named inside a sentence: the sentence form of what it is ("a whole number"), or nothing (qorus#646). */
+    var typeInSentence = (0, react_1.useCallback)(function (type) { var _a; return (_a = qorusTypes.getTypeSentenceForm((0, expressions_1.conditionBaseType)(type))) !== null && _a !== void 0 ? _a : 'nothing'; }, [qorusTypes]);
     /**
      * Read the type analysis off a parse result, or clear it.
      *
@@ -122,7 +304,27 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
      * noise the message below is written to avoid.
      */
     var readTypeCheck = (0, react_1.useCallback)(function (result) {
-        var _a;
+        var _a, _b, _c;
+        /* A condition is not a type to fit (qorus#646): the server reads it as true unless its value is
+           zero or empty, so it is said as every condition editor says it - a number accepted with a warning,
+           text refused. The server's reading, with its own words, when it gave one; the inferred type read
+           the same way when it did not (a server that does not know the question). */
+        if (condition) {
+            if (!result) {
+                setTypeCheck(null);
+                return;
+            }
+            var reading = result.condition_reading;
+            var verdict_1 = reading === 'not_a_condition' ? 'error'
+                : reading === 'truthiness' ? 'warning'
+                    : reading ? undefined
+                        : (0, expressions_1.conditionVerdict)(result.inferred_type);
+            var said = (_b = (_a = result.diagnostics) === null || _a === void 0 ? void 0 : _a.find(function (d) {
+                return verdict_1 === 'error' ? d.code === 'NOT_A_CONDITION' : d.code === 'CONDITION_BY_TRUTHINESS';
+            })) === null || _b === void 0 ? void 0 : _b.message;
+            setTypeCheck(verdict_1 ? __assign({ compatible: verdict_1 !== 'error', mayFail: false, inferred: result.inferred_type, condition: verdict_1 }, (said ? { message: said } : {})) : null);
+            return;
+        }
         if (!result || result.type_compatible === undefined) {
             setTypeCheck(null);
             return;
@@ -133,9 +335,9 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
             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,
+            fix: (_c = result.suggested_fix) === null || _c === void 0 ? void 0 : _c.text,
         });
-    }, []);
+    }, [condition]);
     // Keep a readable rendering of the current expression in sync — the
     // single live mirror of the AST (the server's `dpql/renderExpression`).
     //
@@ -189,65 +391,70 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
             hadExpression.current = true;
             return;
         }
+        // a template or a literal written here is held as itself: the text stands for it, and stays
+        if (heldAsValue) {
+            hadExpression.current = false;
+            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. */
+    }, [ast, heldAsValue]);
+    /* Read the text typed and not yet read: once the session is ready, however long that takes, and the
+       latest text typed by then. Gives the expression it is, or nothing. The debounce, the host leaving the
+       Text view (its tabs) and the session coming up all read through here. */
+    var flushPendingParse = (0, react_1.useCallback)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        var pending, parse, result;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    if (pendingParse.current === null)
+                        return [2 /*return*/, undefined];
+                    return [4 /*yield*/, whenSessionReady()];
+                case 1:
+                    if (!(_b.sent()))
+                        return [2 /*return*/, undefined];
+                    pending = pendingParse.current;
+                    parse = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.parse;
+                    if (pending === null || !parse)
+                        return [2 /*return*/, undefined];
+                    if (parseTimer.current)
+                        clearTimeout(parseTimer.current);
+                    pendingParse.current = null;
+                    return [4 /*yield*/, parse(pending, targetType, parseOptions)];
+                case 2:
+                    result = _b.sent();
+                    readTypeCheck(result);
+                    if (!(result === null || result === void 0 ? void 0 : result.success) || !result.expression)
+                        return [2 /*return*/, undefined];
+                    setAstText(pending);
+                    // `dpql/parse` returns the field-ready `{ is_expression, value }`.
+                    onChange(result.expression);
+                    return [2 /*return*/, result.expression];
+            }
+        });
+    }); }, [onChange, targetType, parseOptions, readTypeCheck, whenSessionReady]);
+    // Text mode: parse the DPQL into the AST, debounced, once the session can read it.
     var handleDpqlChange = (0, react_1.useCallback)(function (next) {
+        /* The editor reports the text it was given back as a change (Slate's first operation after the
+           value is set). That is not typing: counted as such it stopped the session from writing the
+           expression into the view once it was ready. */
+        if (next === textRef.current)
+            return;
         userTypedRef.current = true;
         setText(next);
         if (parseTimer.current)
             clearTimeout(parseTimer.current);
-        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 = _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*/];
-                }
-            });
-        }); };
-        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);
+        pendingParse.current = next;
+        parseTimer.current = setTimeout(function () { return void flushPendingParse(); }, PARSE_DEBOUNCE_MS);
+    }, [flushPendingParse]);
+    /** Whether this visit to Text mode has already put the AST in the editor. The host's own text for the
+     *  first visit (`initialText`, such as the value written as `concat("SUP-", $record:{pos})`) is that visit's
+     *  text: the session does not write over it once it is ready. */
+    var seededRef = (0, react_1.useRef)(!!initialText);
     /* 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`
@@ -280,39 +487,78 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
             return undefined;
         if (!(ast === null || ast === void 0 ? void 0 : ast.exp))
             return undefined;
-        var seedAst = ast;
+        /* Only what DPQL can write is serialized. An operand whose operation is not
+           chosen yet, or that is not filled in, has no text; handed to serialize as
+           it was, it came back as the server's (or a stand-in's) rendering of a hash:
+           `{args=(null)} > {type=int}`. The Text view shows the expression with a hole
+           for each part not filled in instead - `… > …`, as the row's summary does -
+           and serialize gets custom Text values as the strings or templates they are. */
+        var seedAst = (0, textOfExpression_1.serializableExpression)(ast);
+        if (!seedAst) {
+            var holes = (0, textOfExpression_1.incompleteExpressionText)(ast, expressions);
+            seededRef.current = true;
+            setText(holes);
+            setAstText(holes);
+            return undefined;
+        }
+        // written by the session once it is ready, as the session says it - not asked of it before
+        if (!sessionReady)
+            return undefined;
         var cancelled = false;
-        var timer = null;
-        var tries = 0;
         var seed = function () { return __awaiter(void 0, void 0, void 0, function () {
-            var t;
-            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.serialize) === null || _b === void 0 ? void 0 : _b.call(_a, seedAst))];
+            var t, error_1, result;
+            var _a, _b, _c, _d, _e, _f;
+            return __generator(this, function (_g) {
+                switch (_g.label) {
+                    case 0:
+                        _g.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, ((_b = (_a = dpqlRef.current) === null || _a === void 0 ? void 0 : _a.serialize) === null || _b === void 0 ? void 0 : _b.call(_a, seedAst))];
                     case 1:
-                        t = _c.sent();
+                        t = _g.sent();
+                        return [3 /*break*/, 3];
+                    case 2:
+                        error_1 = _g.sent();
                         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);
-                        }
+                        setTextRefused(String((_c = error_1 === null || error_1 === void 0 ? void 0 : error_1.message) !== null && _c !== void 0 ? _c : error_1));
+                        setMode('visual');
+                        // a host drawing the views as tabs follows: the Visual tab
+                        (_d = onTextUnavailableRef.current) === null || _d === void 0 ? void 0 : _d.call(onTextUnavailableRef);
                         return [2 /*return*/];
+                    case 3:
+                        if (cancelled || userTypedRef.current)
+                            return [2 /*return*/];
+                        setTextRefused(null);
+                        if (!t) return [3 /*break*/, 5];
+                        seededRef.current = true;
+                        setText(t);
+                        setAstText(t);
+                        if (!(targetType || condition)) return [3 /*break*/, 5];
+                        return [4 /*yield*/, ((_f = (_e = dpqlRef.current) === null || _e === void 0 ? void 0 : _e.parse) === null || _f === void 0 ? void 0 : _f.call(_e, t, targetType, parseOptions))];
+                    case 4:
+                        result = _g.sent();
+                        if (!cancelled && !userTypedRef.current)
+                            readTypeCheck(result);
+                        _g.label = 5;
+                    case 5: return [2 /*return*/];
                 }
             });
         }); };
         void seed();
         return function () {
             cancelled = true;
-            if (timer)
-                clearTimeout(timer);
         };
-    }, [mode, ast]);
+    }, [mode, ast, expressions, targetType, parseOptions, condition, readTypeCheck, sessionReady]);
+    /** The field's templates, its catalogue's entries, for the Text view's picker. */
+    var templateItems = (0, react_1.useMemo)(function () { var _a; return ((_a = localTemplates === null || localTemplates === void 0 ? void 0 : localTemplates.items) !== null && _a !== void 0 ? _a : []); }, [localTemplates]);
+    /* A template chosen from the picker goes in after the text, as a chip, and is parsed as typed text is:
+       the editor keeps no caret the field can reach, so the end of the text is where it is put. */
+    var insertTemplate = (0, react_1.useCallback)(function (item) {
+        if (typeof (item === null || item === void 0 ? void 0 : item.value) !== 'string' || !item.value)
+            return;
+        var current = text.trimEnd();
+        handleDpqlChange(current ? "".concat(current, " ").concat(item.value) : item.value);
+    }, [text, handleDpqlChange]);
     // Switch to Text: the seeding effect above serializes the AST once
     // the editor's session is up.
     var enterTextMode = (0, react_1.useCallback)(function () {
@@ -320,28 +566,55 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
     }, []);
     // Switch to Visual: flush any pending parse so the AST is current.
     var enterVisualMode = (0, react_1.useCallback)(function () { return __awaiter(void 0, void 0, void 0, function () {
-        var result;
-        var _a, _b;
-        return __generator(this, function (_c) {
-            switch (_c.label) {
+        var edited, _a, result;
+        var _b, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
                 case 0:
                     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, targetType))];
+                    pendingParse.current = null;
+                    edited = text !== astText && userTypedRef.current;
+                    _a = mode === 'text' && text && edited;
+                    if (!_a) return [3 /*break*/, 2];
+                    return [4 /*yield*/, whenSessionReady()];
                 case 1:
-                    result = _c.sent();
+                    _a = (_d.sent());
+                    _d.label = 2;
+                case 2:
+                    if (!_a) return [3 /*break*/, 4];
+                    return [4 /*yield*/, ((_c = (_b = dpqlRef.current) === null || _b === void 0 ? void 0 : _b.parse) === null || _c === void 0 ? void 0 : _c.call(_b, text, targetType, parseOptions))];
+                case 3:
+                    result = _d.sent();
                     readTypeCheck(result);
                     if ((result === null || result === void 0 ? void 0 : result.success) && result.expression) {
                         onChange(result.expression);
                     }
-                    _c.label = 2;
-                case 2:
+                    _d.label = 4;
+                case 4:
                     setMode('visual');
                     return [2 /*return*/];
             }
         });
-    }); }, [mode, text, onChange, targetType, readTypeCheck]);
+    }); }, [mode, text, astText, onChange, targetType, parseOptions, readTypeCheck, whenSessionReady]);
+    // the host's tabs: followed as the toggle is (see `requestedMode`)
+    (0, react_1.useEffect)(function () {
+        if (!requestedMode || requestedMode === mode)
+            return;
+        if (requestedMode === 'visual')
+            void enterVisualMode();
+        else if (!textUnavailable)
+            enterTextMode();
+    }, [requestedMode]);
+    (0, react_1.useEffect)(function () {
+        if (!flushRef)
+            return undefined;
+        flushRef.current = flushPendingParse;
+        return function () {
+            if (flushRef.current === flushPendingParse)
+                flushRef.current = null;
+        };
+    }, [flushRef, flushPendingParse]);
     (0, react_1.useEffect)(function () { return function () {
         if (parseTimer.current)
             clearTimeout(parseTimer.current);
@@ -353,13 +626,37 @@ exports.ExpressionField = (0, react_1.memo)(function (_a) {
     var previewState = !preview || astText.trim() !== text.trim() ? 'none'
         : (0, dpqlHelpers_1.dpqlDisplayedText)(preview).trim() === (0, dpqlHelpers_1.dpqlDisplayedText)(text).trim() ? 'repeats'
             : 'shown';
-    return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, gapSize: 'small', className: 'expression-field', "data-preview": mode === 'text' ? previewState : undefined, 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, fields: fields, 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.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 6 }), (0, jsx_runtime_1.jsx)(DpqlRendering_1.DpqlRendering, { text: typeCheck.fix, "data-testid": 'expression-type-fix' })] })) : null] })), previewState === 'shown' ? ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'info', size: 'small', title: 'Preview', flat: true, opaque: false, children: (0, jsx_runtime_1.jsx)(DpqlRendering_1.DpqlRendering, { text: preview, "data-testid": 'expression-preview' }) })) : null] })) : ((0, jsx_runtime_1.jsx)(builder_1.ExpressionBuilder, { value: value, onChange: function (v, remove) { return onChange(v, remove); }, expressions: expressions, 
-                // 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, componentOverrides: componentOverrides, extraActions: extraActions, size: size, reorder: reorder }))] }));
+    return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, gapSize: 'small', className: 'expression-field', "data-preview": mode === 'text' ? previewState : undefined, children: [hideModeToggle ? null : ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { gapSize: 'small', fluid: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'CodeLine', active: mode === 'text', onClick: enterTextMode, disabled: readOnly || textUnavailable, tooltip: textUnavailable ? 'The expression language server is not available' : undefined, size: size, children: "Text" }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { icon: 'NodeTree', active: mode === 'visual', onClick: enterVisualMode, disabled: readOnly, size: size, children: "Visual" })] })), mode === 'text' ?
+                (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [textUnavailable ?
+                            (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'warning', size: 'small', flat: true, opaque: false, className: 'expression-text-unavailable', children: "The expression language server is not available, so this text cannot be read yet. It is kept as you typed it; the Visual view builds the expression without the server." })
+                            : null, (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { gapSize: 'small', fluid: true, verticalAlign: 'flex-start', children: [(0, jsx_runtime_1.jsx)(dpqlEditor_1.DpqlEditor, { ref: dpqlRef, value: text, onChange: handleDpqlChange, provider: provider, recordType: recordType, fields: fields, 
+                                    // the field's own templates name the chips as its catalogue names them
+                                    templates: localTemplates, readOnly: readOnly, 
+                                    // no floor of its own: one line as tall as the text it shows, growing with its lines - a
+                                    // 48px floor left an empty strip under the text, which the picker beside it could not match
+                                    onUnavailable: handleTextUnavailable, onReady: handleTextReady }), templateItems.length && !readOnly ?
+                                    (0, jsx_runtime_1.jsx)(TemplateBrowser_1.TemplateBrowser, { className: 'expression-text-template-picker', icon: 'MoneyDollarCircleLine', "aria-label": 'Insert a template', tooltip: 'Insert a template', 
+                                        // the size of the text it inserts into - the DPQL editor is drawn at the normal size in
+                                        // any form - so the two are as tall as each other
+                                        size: 'normal', fixed: true, templates: localTemplates, focusFilter: true, onItemSelect: insertTemplate })
+                                    : null] }), (typeCheck === null || typeCheck === void 0 ? void 0 : typeCheck.condition) && ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { className: 'expression-condition-verdict', intent: typeCheck.condition === 'error' ? 'danger' : 'warning', size: 'small', flat: true, opaque: false, children: (_b = typeCheck.message) !== null && _b !== void 0 ? _b : (typeCheck.condition === 'error' ?
+                                (0, expressions_1.conditionErrorText)(typeInSentence(typeCheck.inferred), typeCheck.inferred)
+                                : (0, expressions_1.conditionByTruthinessText)(typeCheck.inferred)) })), typeCheck && !typeCheck.compatible && !typeCheck.condition && ((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 gives ".concat(typeInSentence(typeCheck.inferred), ", and this field takes ").concat(typeInSentence(typeCheck.target), "."), typeCheck.mayFail ? ' Qorus converts the value when it runs, and checks it then.' : '', typeCheck.fix ?
+                                    (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 6 }), (0, jsx_runtime_1.jsx)(DpqlRendering_1.DpqlRendering, { text: typeCheck.fix, "data-testid": 'expression-type-fix' })] })
+                                    : null] })), previewState === 'shown' ?
+                            (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'info', size: 'small', title: 'Preview', flat: true, opaque: false, children: (0, jsx_runtime_1.jsx)(DpqlRendering_1.DpqlRendering, { text: preview, "data-testid": 'expression-preview' }) })
+                            : null] })
+                : (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [textRefused ?
+                            (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreMessage, { intent: 'warning', size: 'small', flat: true, opaque: false, className: 'expression-text-refused', children: ["This expression cannot be shown as text, so it is built here: ", textRefused] })
+                            : null, textUnavailable ?
+                            (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'muted', size: 'small', flat: true, opaque: false, className: 'expression-text-unavailable', children: "The Text view needs the expression language server, which is not available: the expression is built here instead." })
+                            : null, (0, jsx_runtime_1.jsx)(builder_1.ExpressionBuilder, { value: value, onChange: function (v, remove) { return onChange(v, remove); }, expressions: expressions, 
+                            // 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: ((_c = returnType !== null && returnType !== void 0 ? returnType : type) !== null && _c !== void 0 ? _c : 'auto'), readOnly: readOnly, localTemplates: localTemplates !== null && localTemplates !== void 0 ? localTemplates : { items: [] }, serverHandled: serverHandled, condition: condition, conditionParts: currentConditionParts, conditionMessage: currentConditionMessage, componentOverrides: componentOverrides, extraActions: extraActions, size: size, reorder: reorder }), serverCheckable ?
+                            (0, jsx_runtime_1.jsx)(ExpressionServerErrors, { expression: serverCheckable, fields: fields, provider: provider, recordType: recordType, condition: condition, onConditionParts: condition ? onConditionParts : undefined })
+                            : null] })] }));
 });
 exports.default = exports.ExpressionField;
 //# sourceMappingURL=ExpressionField.js.map