@qoretechnologies/reqraft 0.10.66-pr.152.g3349989 → 0.10.66

package/dist/components/smartEditor/useLspAutocomplete.js

@@ -1,5 +1,16 @@
 "use strict";
 // Copyright 2026 Qore Technologies, s.r.o.
+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) {
@@ -46,12 +57,30 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useLspAutocomplete = void 0;
+exports.useLspAutocomplete = exports.useCompletionKeys = exports.toDropdownItems = exports.groupCompletionItems = exports.COMPLETION_KIND_CHIPS = void 0;
 var lodash_1 = require("lodash");
 var react_1 = require("react");
 var slate_1 = require("slate");
 var slate_react_1 = require("slate-react");
 var helpers_1 = require("./helpers");
+var templateCompletions_1 = require("./templateCompletions");
+/** What is typed before the editor's caret in the text it is in: never anything across a chip. */
+var typedInTextOf = function (editor) {
+    var _a, _b;
+    var at = (_a = editor === null || editor === void 0 ? void 0 : editor.selection) === null || _a === void 0 ? void 0 : _a.anchor;
+    if (!editor || !at)
+        return undefined;
+    // the leaf at the caret, read along its path: a paragraph's child
+    var node = editor;
+    for (var _i = 0, _c = at.path; _i < _c.length; _i++) {
+        var index = _c[_i];
+        node = (_b = node === null || node === void 0 ? void 0 : node.children) === null || _b === void 0 ? void 0 : _b[index];
+    }
+    return typeof (node === null || node === void 0 ? void 0 : node.text) === 'string' ?
+        node.text.slice(0, at.offset)
+        : undefined;
+};
+var templateRowMarks = function (item) { var _a, _b; return ((_b = (_a = (('raw' in item ? item.raw : item))) === null || _a === void 0 ? void 0 : _a.data) !== null && _b !== void 0 ? _b : {}); };
 var DEFAULT_TRIGGER_CHARS = new Set(['.', ':', ' ']);
 var DEBOUNCE_MS = 150;
 // Defer `isFetching=true` so the "Loading…" stub only shows for genuinely
@@ -65,7 +94,7 @@ var COMPLETION_KIND_LABELS = {
     14: 'Keywords',
     15: 'Snippets',
 };
-var COMPLETION_KIND_CHIPS = {
+exports.COMPLETION_KIND_CHIPS = {
     1: 'Text',
     2: 'Method',
     3: 'Function',
@@ -92,35 +121,184 @@ var COMPLETION_KIND_CHIPS = {
     24: 'Operator',
     25: 'TypeParameter',
 };
+/**
+ * The list's rows in groups: as ranked when the server ranked them (`sortText`), otherwise by kind - Field,
+ * Variable, Function... - when there is more than one.
+ */
+var groupCompletionItems = function (items) {
+    var _a;
+    if (items.length === 0)
+        return [];
+    // When the server populates `sortText` it has already ranked items;
+    // use the flat list directly rather than re-ordering across kinds.
+    // Qonsole takes this path; DPQL has no sortText and falls through.
+    var hasSortText = items.some(function (i) { return i.raw.sortText; });
+    if (hasSortText) {
+        return [{ label: '', items: items }];
+    }
+    var groupMap = new Map();
+    for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
+        var item = items_1[_i];
+        var kind = (_a = item.metadata) === null || _a === void 0 ? void 0 : _a.kind;
+        // a template row says its own section: the field's templates, its record fields, or none (Browse all)
+        var section = templateRowMarks(item).section;
+        var groupLabel = section !== undefined ? section : (kind && COMPLETION_KIND_LABELS[kind]) || 'Other';
+        if (!groupMap.has(groupLabel)) {
+            groupMap.set(groupLabel, []);
+        }
+        groupMap.get(groupLabel).push(item);
+    }
+    if (groupMap.size <= 1) {
+        return [{ label: '', items: items }];
+    }
+    return Array.from(groupMap.entries()).map(function (_a) {
+        var label = _a[0], groupItems = _a[1];
+        return ({
+            label: label,
+            items: groupItems,
+        });
+    });
+};
+exports.groupCompletionItems = groupCompletionItems;
+/** Completion items as the list's rows. */
+var toDropdownItems = function (lspItems) {
+    return lspItems.map(function (item) {
+        var _a;
+        var insertText = item.insertText || item.label;
+        return {
+            label: item.label,
+            value: insertText,
+            icon: (0, helpers_1.mapCompletionKindToIcon)(item.kind),
+            description: item.detail,
+            documentation: item.documentation,
+            // a template says what it is (State data, Context...), not the LSP kind it is sent as (Variable)
+            kindLabel: (_a = templateRowMarks(item).kindLabel) !== null && _a !== void 0 ? _a : (item.kind !== undefined && !templateRowMarks(item).browseAll ?
+                exports.COMPLETION_KIND_CHIPS[item.kind]
+                : undefined),
+            warning: item.warning,
+            raw: item,
+            metadata: {
+                insertTextFormat: item.insertTextFormat,
+                retrigger: insertText.endsWith(':'),
+                kind: item.kind,
+            },
+        };
+    });
+};
+exports.toDropdownItems = toDropdownItems;
+/**
+ * The list's keys, the same wherever it is open, and as the browse list's (`TemplateBrowser`): ArrowDown and
+ * ArrowUp move through it, Enter takes the row the keyboard is on, Escape puts it away, Tab leaves it as it
+ * leaves any control. Heard before anything else on the page while the list is
+ * open - the focus stays where it is (an editor, a picker's button), the list never takes it.
+ */
+var useCompletionKeys = function (_a) {
+    var isOpen = _a.isOpen, count = _a.count, setFocusedIndex = _a.setFocusedIndex, onAccept = _a.onAccept, onClose = _a.onClose, onOtherKey = _a.onOtherKey;
+    var handlers = (0, react_1.useRef)({ onAccept: onAccept, onClose: onClose, onOtherKey: onOtherKey });
+    handlers.current = { onAccept: onAccept, onClose: onClose, onOtherKey: onOtherKey };
+    (0, react_1.useEffect)(function () {
+        if (!isOpen || count === 0)
+            return undefined;
+        var handleKeyDown = function (e) {
+            var _a, _b;
+            var take = function () {
+                e.preventDefault();
+                e.stopPropagation();
+            };
+            switch (e.key) {
+                case 'ArrowDown':
+                    take();
+                    setFocusedIndex(function (prev) { return Math.min(prev + 1, count - 1); });
+                    break;
+                case 'ArrowUp':
+                    take();
+                    setFocusedIndex(function (prev) { return Math.max(prev - 1, 0); });
+                    break;
+                case 'Enter':
+                    take();
+                    handlers.current.onAccept();
+                    break;
+                case 'Tab':
+                    /* takes the row the keyboard is on, as Enter does (a code editor's key), and the text keeps the focus:
+                       leaving the list instead left a half-typed reference standing as if it were one (qorus#646, David's
+                       review) */
+                    take();
+                    handlers.current.onAccept();
+                    break;
+                case 'Escape':
+                    take();
+                    handlers.current.onClose();
+                    break;
+                default:
+                    if ((_b = (_a = handlers.current).onOtherKey) === null || _b === void 0 ? void 0 : _b.call(_a, e))
+                        take();
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown, true);
+        return function () { return document.removeEventListener('keydown', handleKeyDown, true); };
+    }, [isOpen, count, setFocusedIndex]);
+};
+exports.useCompletionKeys = useCompletionKeys;
 function useLspAutocomplete(opts) {
     var _this = this;
-    var getCompletions = opts.getCompletions, isReady = opts.isReady, _a = opts.triggerCharacters, triggerCharacters = _a === void 0 ? DEFAULT_TRIGGER_CHARS : _a, converter = opts.converter, inserter = opts.inserter;
+    var getCompletions = opts.getCompletions, isReady = opts.isReady, _a = opts.triggerCharacters, triggerCharacters = _a === void 0 ? DEFAULT_TRIGGER_CHARS : _a, converter = opts.converter, inserter = opts.inserter, emptyMessageAt = opts.emptyMessage, commitTyped = opts.commitTyped, noteAt = opts.noteAt;
+    var commitTypedRef = (0, react_1.useRef)(commitTyped);
+    commitTypedRef.current = commitTyped;
     var _b = (0, react_1.useState)([]), items = _b[0], setItems = _b[1];
     var _c = (0, react_1.useState)(false), isOpen = _c[0], setIsOpen = _c[1];
     var _d = (0, react_1.useState)({ top: 0, left: 0 }), position = _d[0], setPosition = _d[1];
     var _e = (0, react_1.useState)(0), focusedIndex = _e[0], setFocusedIndex = _e[1];
     var _f = (0, react_1.useState)(false), isFetching = _f[0], setIsFetching = _f[1];
+    var _g = (0, react_1.useState)(), emptyMessage = _g[0], setEmptyMessage = _g[1];
+    var _h = (0, react_1.useState)(), note = _h[0], setNote = _h[1];
+    var noteRef = (0, react_1.useRef)();
+    noteRef.current = note;
+    // asked for and not answered yet: the debounce running, or the answer on its way (`pendingRequestRef`)
+    var _j = (0, react_1.useState)(false), isRequested = _j[0], setIsRequested = _j[1];
     // Handle for the deferred `setIsFetching(true)`; cleared on resolve or
     // close so the loader never flashes on a fast-resolved request.
     var fetchingTimerRef = (0, react_1.useRef)(null);
     // Partial token typed since the trigger opened the dropdown; the list
     // narrows to items whose `filterText || label` matches it.
-    var _g = (0, react_1.useState)(''), filterPrefix = _g[0], setFilterPrefix = _g[1];
+    var _k = (0, react_1.useState)(''), filterPrefix = _k[0], setFilterPrefix = _k[1];
     var focusedIndexRef = (0, react_1.useRef)(0);
     var editorRef = (0, react_1.useRef)(null);
     // "Replace mode": the user clicked a chip and the chosen completion
     // should replace that node. Holds the chip's Slate path, consumed by
     // the inserter via `ctx.replacementPath`.
     var replacingChipPathRef = (0, react_1.useRef)(null);
+    /* The chip the list was opened at, kept until the list is drawn closed. A click on that chip closes the list,
+       and the popover hears the same click as one outside it first and closes the list then, which forgets the
+       chip (`close`): told by `replacingChipPathRef` alone, the chip's own click found no chip and opened the list
+       again. */
+    var anchoredChipPathRef = (0, react_1.useRef)(null);
     // Holds a chip-click request made before `isReady`; fired by the effect
     // below once the session connects so the click isn't dropped.
     var pendingChipRequestRef = (0, react_1.useRef)(null);
-    // Timestamp of the last `openAtChip`; `handleExternalClose` uses it to
-    // suppress the close Reqore fires on the same mousedown that opened it.
-    var justOpenedAtChipAtRef = (0, react_1.useRef)(0);
-    var _h = (0, react_1.useState)(false), isReplaceMode = _h[0], setIsReplaceMode = _h[1];
-    // See `popoverKey` in the result interface — forces a popover re-mount.
-    var _j = (0, react_1.useState)(0), popoverKey = _j[0], setPopoverKey = _j[1];
+    var _l = (0, react_1.useState)(false), isReplaceMode = _l[0], setIsReplaceMode = _l[1];
+    // See `popoverKey` in the result interface — forces a popover re-mount. The ref is the key now, before the
+    // list is drawn again: a close from the popover it replaced is told apart by it (`handleExternalClose`).
+    var _m = (0, react_1.useState)(0), popoverKey = _m[0], setPopoverKey = _m[1];
+    var popoverKeyRef = (0, react_1.useRef)(0);
+    var _o = (0, react_1.useState)(null), docsFor = _o[0], setDocsFor = _o[1];
+    // the template picker in place of the rows, and where it is open
+    var _p = (0, react_1.useState)(null), browse = _p[0], setBrowseState = _p[1];
+    var browseRef = (0, react_1.useRef)(null);
+    var setBrowse = (0, react_1.useCallback)(function (next) {
+        browseRef.current = next;
+        setBrowseState(next);
+    }, []);
+    /* Which request is the one the list is waiting for. A newer request, or the list put away (`close`),
+       makes an answer still on its way stale, and a stale answer is dropped: it used to open the list after
+       the author had dismissed it - typed, pressed Escape before the list came, and the list came anyway,
+       under the next tap, which then took one of its rows (qorus#646). */
+    var requestGenerationRef = (0, react_1.useRef)(0);
+    /* A request typing has asked for and the list has not shown yet: the debounce running, or the server's
+       answer on its way. An Escape then puts it away too, as it puts away an open list. */
+    var pendingRequestRef = (0, react_1.useRef)(false);
+    /* The caret a click, a tap or Tab asked at (`openAtCaret`). Setting Slate's selection to it is a change of
+       selection only, which puts an open list away; this one asked for the list, and is not heard as moving off. */
+    var askedAtRef = (0, react_1.useRef)(null);
     (0, react_1.useEffect)(function () {
         focusedIndexRef.current = focusedIndex;
     }, [focusedIndex]);
@@ -144,6 +322,9 @@ function useLspAutocomplete(opts) {
             return items;
         return items.filter(function (item) {
             var _a;
+            // the row that opens the picker is there whatever is typed
+            if (templateRowMarks(item).browseAll)
+                return true;
             var haystack = ((_a = item.raw.filterText) !== null && _a !== void 0 ? _a : item.label)
                 .toLowerCase()
                 .replace(/^[@$/-]+/, '');
@@ -155,38 +336,39 @@ function useLspAutocomplete(opts) {
             setFocusedIndex(Math.max(0, filteredItems.length - 1));
         }
     }, [filteredItems.length, focusedIndex]);
-    var groups = (0, react_1.useMemo)(function () {
-        var _a;
-        if (filteredItems.length === 0)
-            return [];
-        // When the server populates `sortText` it has already ranked items;
-        // use the flat list directly rather than re-ordering across kinds.
-        // Qonsole takes this path; DPQL has no sortText and falls through.
-        var hasSortText = filteredItems.some(function (i) { return i.raw.sortText; });
-        if (hasSortText) {
-            return [{ label: '', items: filteredItems }];
-        }
-        var groupMap = new Map();
-        for (var _i = 0, filteredItems_1 = filteredItems; _i < filteredItems_1.length; _i++) {
-            var item = filteredItems_1[_i];
-            var kind = (_a = item.metadata) === null || _a === void 0 ? void 0 : _a.kind;
-            var groupLabel = (kind && COMPLETION_KIND_LABELS[kind]) || 'Other';
-            if (!groupMap.has(groupLabel)) {
-                groupMap.set(groupLabel, []);
-            }
-            groupMap.get(groupLabel).push(item);
+    var groups = (0, react_1.useMemo)(function () { return (0, exports.groupCompletionItems)(filteredItems); }, [filteredItems]);
+    /* A list of nothing but Browse all templates, with nothing said above it, is a step for nothing: the picker
+       opens in its place, at its top, as taking that row would open it (Foxhoundn on qlip #425: "automatically show
+       all the templates if it's the only available option"; David: the picker offers every completion in every
+       state). Where the list says something with it (no record fields here, what to write after a context), the
+       list stays, for what it says. */
+    var onlyBrowseAll = isOpen &&
+        !browse &&
+        !isFetching &&
+        !note &&
+        !emptyMessage &&
+        filteredItems.length === 1 &&
+        !!templateRowMarks(filteredItems[0]).browseAll;
+    /* A layout effect, not a passive one: it runs within the commit that leaves only Browse all templates, before
+       the next event - an Escape closing the list - can be heard. A passive effect runs after paint, so a close
+       landing in that window reopened the picker it had just put away (a flake only a loaded machine lost). */
+    (0, react_1.useLayoutEffect)(function () {
+        if (!onlyBrowseAll)
+            return;
+        var editor = editorRef.current;
+        var empty = false;
+        try {
+            empty = !!editor && !converter.fromSlateNodes(editor.children).trim();
         }
-        if (groupMap.size <= 1) {
-            return [{ label: '', items: filteredItems }];
+        catch (_a) {
+            // the editor is not drawn: the picker opens without the arrows
         }
-        return Array.from(groupMap.entries()).map(function (_a) {
-            var label = _a[0], groupItems = _a[1];
-            return ({
-                label: label,
-                items: groupItems,
-            });
-        });
-    }, [filteredItems]);
+        setDocsFor(null);
+        // in an empty text the arrows have nowhere else to go: they move through the picker, as a click there opens it
+        setBrowse({ arrows: empty || undefined });
+        popoverKeyRef.current += 1;
+        setPopoverKey(popoverKeyRef.current);
+    }, [onlyBrowseAll, converter, setBrowse]);
     // Fires the LSP request and commits results into state. Separate from
     // the debounced wrapper so imperative callers (`openAtChip`) can bypass
     // the typing debounce.
@@ -196,7 +378,7 @@ function useLspAutocomplete(opts) {
             args_1[_i - 2] = arguments[_i];
         }
         return __awaiter(_this, __spreadArray([plainText_1, offset_1], args_1, true), void 0, function (plainText, offset, opts) {
-            var _a, eager, editor, domRange, rect, lspItems, sortedLspItems, mapped, _b;
+            var _a, eager, generation, current, editor, domRange, rect, lspItems, said, substantive, sortedLspItems, mapped, _b;
             if (opts === void 0) { opts = {}; }
             return __generator(this, function (_c) {
                 switch (_c.label) {
@@ -204,8 +386,12 @@ function useLspAutocomplete(opts) {
                         _a = opts.eager, eager = _a === void 0 ? true : _a;
                         if (!isReady)
                             return [2 /*return*/];
+                        generation = ++requestGenerationRef.current;
+                        pendingRequestRef.current = true;
+                        setIsRequested(true);
+                        current = function () { return generation === requestGenerationRef.current; };
                         editor = editorRef.current;
-                        if (editor && editor.selection) {
+                        if (editor && editor.selection && !anchoredChipPathRef.current) {
                             try {
                                 domRange = slate_react_1.ReactEditor.toDOMRange(editor, editor.selection);
                                 rect = domRange.getBoundingClientRect();
@@ -232,70 +418,104 @@ function useLspAutocomplete(opts) {
                         _c.label = 1;
                     case 1:
                         _c.trys.push([1, 3, 4, 5]);
-                        return [4 /*yield*/, getCompletions(plainText, offset)];
+                        return [4 /*yield*/, getCompletions(plainText, offset, typedInTextOf(editorRef.current))];
                     case 2:
                         lspItems = _c.sent();
+                        if (!current())
+                            return [2 /*return*/];
                         if (lspItems.length === 0) {
                             setItems([]);
+                            said = replacingChipPathRef.current ? undefined : emptyMessageAt === null || emptyMessageAt === void 0 ? void 0 : emptyMessageAt(plainText, offset);
+                            setEmptyMessage(said);
+                            if (said) {
+                                setIsOpen(true);
+                                return [2 /*return*/];
+                            }
                             // Replace mode keeps the popover open to show "No alternatives".
                             if (!replacingChipPathRef.current) {
                                 setIsOpen(false);
                             }
                             return [2 /*return*/];
                         }
+                        setEmptyMessage(undefined);
+                        substantive = lspItems.filter(function (item) {
+                            var _a;
+                            var marks = ((_a = item.data) !== null && _a !== void 0 ? _a : {});
+                            return !marks.browseAll && !marks.whole;
+                        });
+                        setNote(substantive.length ? undefined : noteAt === null || noteAt === void 0 ? void 0 : noteAt(plainText, offset));
                         sortedLspItems = lspItems.some(function (i) { return i.sortText; })
                             ? __spreadArray([], lspItems, true).sort(function (a, b) { var _a, _b; return ((_a = a.sortText) !== null && _a !== void 0 ? _a : a.label).localeCompare((_b = b.sortText) !== null && _b !== void 0 ? _b : b.label); })
                             : lspItems;
-                        mapped = sortedLspItems.map(function (item) {
-                            var insertText = item.insertText || item.label;
-                            return {
-                                label: item.label,
-                                value: insertText,
-                                icon: (0, helpers_1.mapCompletionKindToIcon)(item.kind),
-                                description: item.detail,
-                                documentation: item.documentation,
-                                kindLabel: item.kind !== undefined
-                                    ? COMPLETION_KIND_CHIPS[item.kind]
-                                    : undefined,
-                                warning: item.warning,
-                                raw: item,
-                                metadata: {
-                                    insertTextFormat: item.insertTextFormat,
-                                    retrigger: insertText.endsWith(':'),
-                                    kind: item.kind,
-                                },
-                            };
-                        });
+                        mapped = (0, exports.toDropdownItems)(sortedLspItems);
                         setItems(mapped);
                         setFocusedIndex(0);
                         setIsOpen(true);
                         return [3 /*break*/, 5];
                     case 3:
                         _b = _c.sent();
+                        if (!current())
+                            return [2 /*return*/];
                         setItems([]);
                         setIsOpen(false);
                         return [3 /*break*/, 5];
                     case 4:
-                        if (fetchingTimerRef.current !== null) {
-                            clearTimeout(fetchingTimerRef.current);
-                            fetchingTimerRef.current = null;
+                        // a stale answer leaves the state to the request that replaced it, or to `close`
+                        if (current()) {
+                            pendingRequestRef.current = false;
+                            setIsRequested(false);
+                            if (fetchingTimerRef.current !== null) {
+                                clearTimeout(fetchingTimerRef.current);
+                                fetchingTimerRef.current = null;
+                            }
+                            setIsFetching(false);
                         }
-                        setIsFetching(false);
                         return [7 /*endfinally*/];
                     case 5: return [2 /*return*/];
                 }
             });
         });
-    }, [getCompletions, isReady]);
-    var requestCompletions = (0, react_1.useMemo)(function () { return (0, lodash_1.debounce)(performCompletionRequest, DEBOUNCE_MS); }, [performCompletionRequest]);
+    }, [getCompletions, isReady, emptyMessageAt, noteAt]);
+    /* One debounced request for the editor's life, sending with the latest `performCompletionRequest`: remade when
+       that changed (a host's new catalogue or callback on a re-render), the request waiting to be sent was dropped,
+       and what had just been written asked nothing - a context picked listed nothing in it (qorus#646). */
+    var performRef = (0, react_1.useRef)(performCompletionRequest);
+    performRef.current = performCompletionRequest;
+    var requestCompletions = (0, react_1.useMemo)(function () {
+        var debounced = (0, lodash_1.debounce)(function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            return performRef.current.apply(performRef, args);
+        }, DEBOUNCE_MS);
+        // asked for: pending from now, not only once the debounce runs out
+        var request = (function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            pendingRequestRef.current = true;
+            setIsRequested(true);
+            return debounced.apply(void 0, args);
+        });
+        request.cancel = debounced.cancel;
+        request.flush = debounced.flush;
+        return request;
+    }, []);
     (0, react_1.useEffect)(function () {
         return function () {
             requestCompletions.cancel();
         };
     }, [requestCompletions]);
     var close = (0, react_1.useCallback)(function () {
+        setDocsFor(null);
+        setBrowse(null);
         setIsOpen(false);
         setItems([]);
+        setEmptyMessage(undefined);
+        setNote(undefined);
+        setIsRequested(false);
         setFocusedIndex(0);
         setFilterPrefix('');
         setIsReplaceMode(false);
@@ -305,9 +525,63 @@ function useLspAutocomplete(opts) {
             fetchingTimerRef.current = null;
         }
         replacingChipPathRef.current = null;
+        // a list put away is at no chip, from now: the next one asked by typing is at the caret
+        anchoredChipPathRef.current = null;
         pendingChipRequestRef.current = null;
+        askedAtRef.current = null;
         requestCompletions.cancel();
+        // an answer still on its way is for a list that has been put away
+        requestGenerationRef.current++;
+        pendingRequestRef.current = false;
     }, [requestCompletions]);
+    /* Escape in the editor before the list has come puts the request away, as Escape puts a list with rows
+       away (`useCompletionKeys`, which hears it then). Not taken from the page: with no list shown, an Escape
+       may mean something else there too. */
+    var showsRows = isOpen && filteredItems.length > 0;
+    // the list open with what it says in place of rows: Escape puts it away, and nothing else
+    var showsMessage = isOpen && !showsRows && !!emptyMessage;
+    (0, react_1.useEffect)(function () {
+        if (showsRows)
+            return undefined;
+        var handleKeyDown = function (event) {
+            var editor = editorRef.current;
+            /* Enter or Tab where the list has nothing more to offer - a context of free keys and its key written,
+               `$static:order.id` - takes what is written: a whole reference, drawn as its chip (`commitTyped`), as a row
+               taken is (qorus#646, David's review). */
+            if ((event.key === 'Enter' || event.key === 'Tab') && showsMessage && editor && commitTypedRef.current) {
+                try {
+                    if (!slate_react_1.ReactEditor.toDOMNode(editor, editor).contains(event.target))
+                        return;
+                }
+                catch (_a) {
+                    return;
+                }
+                if (commitTypedRef.current(editor)) {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    close();
+                }
+                return;
+            }
+            if (event.key !== 'Escape' || !(pendingRequestRef.current || showsMessage))
+                return;
+            try {
+                if (!editor || !slate_react_1.ReactEditor.toDOMNode(editor, editor).contains(event.target))
+                    return;
+            }
+            catch (_b) {
+                // the editor is not drawn: nothing of it is in the page to have had the key
+                return;
+            }
+            if (showsMessage) {
+                event.preventDefault();
+                event.stopPropagation();
+            }
+            close();
+        };
+        document.addEventListener('keydown', handleKeyDown, true);
+        return function () { return document.removeEventListener('keydown', handleKeyDown, true); };
+    }, [showsRows, showsMessage, close]);
     var positionTrigger = (0, react_1.useCallback)(function (editor) {
         if (!editor.selection)
             return;
@@ -343,12 +617,25 @@ function useLspAutocomplete(opts) {
     // own (intentionally narrow) deps closed over. Same workaround as
     // `stableOnTagClick` in SmartEditor.
     var onSlateChangeImplRef = (0, react_1.useRef)(function () { return undefined; });
+    // `completeAtCaret`, defined below, for a pick that goes on to ask again
+    var completeAtCaretRef = (0, react_1.useRef)(function () { return undefined; });
     var selectItem = (0, react_1.useCallback)(function (item) {
-        var _a;
+        var _a, _b, _c, _d;
         var editor = editorRef.current;
         if (!editor)
             return;
         var replacementPath = replacingChipPathRef.current;
+        /* A group, or Browse all: the picker opens there, in the list's place, for the pick to go where the row's
+           would have gone - in the place of what is typed, or of the chip being replaced. */
+        var marks = templateRowMarks(item);
+        if (marks.opens || marks.browseAll) {
+            setDocsFor(null);
+            setBrowse({ levelId: marks.opens ? marks.templateNodeId : undefined });
+            setIsOpen(true);
+            popoverKeyRef.current += 1;
+            setPopoverKey(popoverKeyRef.current);
+            return;
+        }
         // The typing path needs a live selection so the inserter knows how
         // much partial token to delete; replace mode works off a path.
         if (!editor.selection && !replacementPath)
@@ -358,81 +645,109 @@ function useLspAutocomplete(opts) {
         var cursorOffset = editor.selection
             ? converter.selectionToOffset(nodes, editor.selection.anchor.path, editor.selection.anchor.offset)
             : converter.selectionToOffset(nodes, replacementPath, 0);
-        inserter(item.raw, editor, {
+        /* The text takes the focus back before the pick is written, where the pick was made elsewhere (the picker's
+           search box): focused after, with the edit not yet drawn, slate-react puts the focus off to a later timer,
+           and the editor's state changes there, outside the event that made the pick. */
+        try {
+            if (!slate_react_1.ReactEditor.isFocused(editor))
+                slate_react_1.ReactEditor.focus(editor);
+        }
+        catch (_e) {
+            // the editor is not in the document: the pick is written all the same
+        }
+        /* A context, a state or a record taken is written as the text of its reference, and what is in it is
+           listed next, as the text is completed on (the edit asks again: it ends with a `:` or a `.`); only a
+           whole reference is a chip (qorus#646, David's review: a context picked was an unfinished template). */
+        (marks.continues ? templateCompletions_1.templateTextInserter : inserter)(item.raw, editor, {
             plainText: plainText,
             cursorOffset: cursorOffset,
             replacementPath: replacementPath !== null && replacementPath !== void 0 ? replacementPath : undefined,
         });
+        /* What is written goes on (a context, `$data:`, or a path, `$data:receive_order.`): the list stays open
+           and is asked again where the text now ends, so what is in it is listed next. Put away and opened again,
+           its popover's close came after the new request and dropped it. */
+        var written = (_c = (_b = (_a = item.raw.textEdit) === null || _a === void 0 ? void 0 : _a.newText) !== null && _b !== void 0 ? _b : item.raw.insertText) !== null && _c !== void 0 ? _c : item.raw.label;
+        if (marks.continues || (!replacementPath && /^[$@][^\s]*[:.]$/.test(written))) {
+            // the rows stay until the next level's come: a list left empty is put away, and its close drops the request
+            setDocsFor(null);
+            // taken from the picker: what follows is listed as typing lists it, in a list of its own (`completeAtCaret`)
+            if (browseRef.current) {
+                browseRef.current = null;
+                setBrowse(null);
+                popoverKeyRef.current += 1;
+                setPopoverKey(popoverKeyRef.current);
+            }
+            setFocusedIndex(0);
+            replacingChipPathRef.current = null;
+            anchoredChipPathRef.current = null;
+            completeAtCaretRef.current(editor, editor.children);
+            return;
+        }
         close();
         // Re-trigger completions for partial items (e.g. `$timestamp:` shows
         // sub-completions for the value).
-        if ((_a = item.metadata) === null || _a === void 0 ? void 0 : _a.retrigger) {
+        if ((_d = item.metadata) === null || _d === void 0 ? void 0 : _d.retrigger) {
             setTimeout(function () {
                 var newNodes = editor.children;
                 onSlateChangeImplRef.current(editor, newNodes);
             }, 50);
         }
     }, [close, inserter, converter]);
-    (0, react_1.useEffect)(function () {
-        // Keyboard nav operates on the filtered list, not the raw items.
-        if (!isOpen || filteredItems.length === 0)
-            return undefined;
-        var handleKeyDown = function (e) {
+    var toggleDocs = (0, react_1.useCallback)(function (value) {
+        var _a, _b;
+        var target = (_b = value !== null && value !== void 0 ? value : (_a = filteredItems[focusedIndexRef.current]) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : null;
+        setDocsFor(function (shown) { return (shown === target ? null : target); });
+    }, [filteredItems]);
+    var toggleDocsRef = (0, react_1.useRef)(toggleDocs);
+    toggleDocsRef.current = toggleDocs;
+    (0, exports.useCompletionKeys)({
+        // the picker hears its own keys (`TemplatePicker`)
+        isOpen: isOpen && !browse && filteredItems.length > 0,
+        count: filteredItems.length,
+        setFocusedIndex: setFocusedIndex,
+        onAccept: function () {
+            var _a;
+            /* where none of the rows is what is written (the note says so) and what is written is a whole reference -
+               a context of free keys and its key, `$dynamic:order.id` - Enter or Tab takes what is written, its chip;
+               else the row the keyboard is on (qorus#646, David's review) */
+            var editor = editorRef.current;
+            if (noteRef.current && editor && ((_a = commitTypedRef.current) === null || _a === void 0 ? void 0 : _a.call(commitTypedRef, editor))) {
+                close();
+                return;
+            }
+            var item = filteredItems[focusedIndexRef.current];
+            if (item && editor)
+                selectItem(item);
+        },
+        onClose: close,
+        onOtherKey: function (e) {
             var _a, _b, _c;
-            switch (e.key) {
-                case 'ArrowDown':
-                    e.preventDefault();
-                    e.stopPropagation();
-                    setFocusedIndex(function (prev) { return Math.min(prev + 1, filteredItems.length - 1); });
-                    break;
-                case 'ArrowUp':
-                    e.preventDefault();
-                    e.stopPropagation();
-                    setFocusedIndex(function (prev) { return Math.max(prev - 1, 0); });
-                    break;
-                case 'Enter':
-                case 'Tab': {
-                    e.preventDefault();
-                    e.stopPropagation();
-                    var item = filteredItems[focusedIndexRef.current];
-                    if (item && editorRef.current) {
-                        selectItem(item);
-                    }
-                    break;
-                }
-                case 'Escape':
-                    e.preventDefault();
-                    e.stopPropagation();
-                    close();
-                    break;
-                default: {
-                    // `commitCharacters`: typing a commit char accepts the item and
-                    // inserts the char (VS Code semantics).
-                    if (e.key.length !== 1)
-                        break;
-                    var focusedItem = filteredItems[focusedIndexRef.current];
-                    var commits = focusedItem === null || focusedItem === void 0 ? void 0 : focusedItem.raw.commitCharacters;
-                    if (!commits || !commits.includes(e.key))
-                        break;
-                    var editor = editorRef.current;
-                    if (!editor)
-                        break;
-                    e.preventDefault();
-                    e.stopPropagation();
-                    // Don't double-insert when the server's edit already ends with
-                    // the committed char (e.g. `--limit=` for an `=`-committed flag).
-                    var inserted = (_c = (_b = (_a = focusedItem.raw.textEdit) === null || _a === void 0 ? void 0 : _a.newText) !== null && _b !== void 0 ? _b : focusedItem.raw.insertText) !== null && _c !== void 0 ? _c : focusedItem.raw.label;
-                    selectItem(focusedItem);
-                    if (!inserted.endsWith(e.key)) {
-                        slate_1.Transforms.insertText(editor, e.key);
-                    }
-                    break;
-                }
+            // Ctrl+Space: the documentation of the row the keyboard is on, shown under it or put away (VS Code's key)
+            if (e.key === ' ' && e.ctrlKey && !e.metaKey && !e.altKey) {
+                toggleDocsRef.current();
+                return true;
             }
-        };
-        document.addEventListener('keydown', handleKeyDown, true);
-        return function () { return document.removeEventListener('keydown', handleKeyDown, true); };
-    }, [isOpen, filteredItems, close, selectItem]);
+            // `commitCharacters`: typing a commit char accepts the item and
+            // inserts the char (VS Code semantics).
+            if (e.key.length !== 1)
+                return false;
+            var focusedItem = filteredItems[focusedIndexRef.current];
+            var commits = focusedItem === null || focusedItem === void 0 ? void 0 : focusedItem.raw.commitCharacters;
+            if (!commits || !commits.includes(e.key))
+                return false;
+            var editor = editorRef.current;
+            if (!editor)
+                return false;
+            // Don't double-insert when the server's edit already ends with
+            // the committed char (e.g. `--limit=` for an `=`-committed flag).
+            var inserted = (_c = (_b = (_a = focusedItem.raw.textEdit) === null || _a === void 0 ? void 0 : _a.newText) !== null && _b !== void 0 ? _b : focusedItem.raw.insertText) !== null && _c !== void 0 ? _c : focusedItem.raw.label;
+            selectItem(focusedItem);
+            if (!inserted.endsWith(e.key)) {
+                slate_1.Transforms.insertText(editor, e.key);
+            }
+            return true;
+        },
+    });
     /**
      * Opens, narrows or closes the completions for what the editor holds at its caret, after a content
      * edit: a trigger character just typed, typing inside a sigil token, narrowing an open list, or
@@ -443,6 +758,14 @@ function useLspAutocomplete(opts) {
             close();
             return;
         }
+        /* Typing puts the picker away: what is typed is completed in the rows, or nothing is. Under a key of its own:
+           the picker's popover says it closed as it goes, and that is not the list put away. */
+        if (browseRef.current) {
+            browseRef.current = null;
+            setBrowse(null);
+            popoverKeyRef.current += 1;
+            setPopoverKey(popoverKeyRef.current);
+        }
         var anchor = editor.selection.anchor;
         var plainText = converter.fromSlateNodes(nodes);
         var cursorOffset = converter.selectionToOffset(nodes, anchor.path, anchor.offset);
@@ -500,6 +823,7 @@ function useLspAutocomplete(opts) {
         }
         close();
     }, [isOpen, close, findTokenStart, positionTrigger, requestCompletions, triggerCharacters, converter]);
+    completeAtCaretRef.current = completeAtCaret;
     /* An edit made before the session is ready - typing `$` or `@` while the connection is still being
        made, or its context bound - would otherwise be dropped: the list is closed and nothing asks again,
        so the trigger the author typed never opens anything. The editor is kept, and once the session is
@@ -529,6 +853,14 @@ function useLspAutocomplete(opts) {
         // op batch is selection-only.
         var isContentChange = editor.operations.some(function (op) { return op.type !== 'set_selection'; });
         if (!isContentChange) {
+            // the caret a click asked at, set: the list it asked for stays
+            var askedAt = askedAtRef.current;
+            if (askedAt &&
+                editor.selection &&
+                slate_1.Range.isCollapsed(editor.selection) &&
+                slate_1.Point.equals(editor.selection.anchor, askedAt)) {
+                return;
+            }
             // Replace mode anchors on a chip; the selection echo from the
             // opening click must not close it (outside-click handler does).
             if (isOpen && !replacingChipPathRef.current) {
@@ -536,6 +868,7 @@ function useLspAutocomplete(opts) {
             }
             return;
         }
+        askedAtRef.current = null;
         // A content edit in replace mode means the user typed instead of
         // picking a replacement — fall back to normal flow.
         if (replacingChipPathRef.current) {
@@ -560,12 +893,11 @@ function useLspAutocomplete(opts) {
     // Imperative entry for the "replace this chip" flow. Anchors at the
     // chip's viewport rect and fires a request immediately, bypassing the
     // typing debounce.
-    var openAtChip = (0, react_1.useCallback)(function (editor, chipPath, chipRect) {
-        var _a, _b;
-        // Clicking the chip the dropdown is already anchored to closes it;
-        // without this the outside-click suppression below re-opens it on
-        // every chip click.
-        var prevPath = replacingChipPathRef.current;
+    var openAtChip = (0, react_1.useCallback)(function (editor, chipPath, chipRect, _a) {
+        var _b, _c;
+        var _d = _a === void 0 ? {} : _a, _e = _d.inItsPlace, inItsPlace = _e === void 0 ? false : _e;
+        // Clicking the chip the dropdown is already anchored to closes it.
+        var prevPath = anchoredChipPathRef.current;
         if (isOpen &&
             prevPath &&
             prevPath.length === chipPath.length &&
@@ -575,7 +907,7 @@ function useLspAutocomplete(opts) {
         }
         editorRef.current = editor;
         replacingChipPathRef.current = chipPath;
-        justOpenedAtChipAtRef.current = Date.now();
+        anchoredChipPathRef.current = chipPath;
         setFilterPrefix('');
         setPosition({ left: chipRect.left, top: chipRect.bottom });
         // Pre-open for immediate feedback even before the LSP is ready (the
@@ -584,7 +916,8 @@ function useLspAutocomplete(opts) {
         setFocusedIndex(0);
         setIsReplaceMode(true);
         setIsOpen(true);
-        setPopoverKey(function (k) { return k + 1; });
+        popoverKeyRef.current += 1;
+        setPopoverKey(popoverKeyRef.current);
         var nodes = editor.children;
         var plainText = converter.fromSlateNodes(nodes);
         // Request at the END of the chip's span — the natural "what could
@@ -592,28 +925,76 @@ function useLspAutocomplete(opts) {
         // candidates.
         var chipChildIdx = chipPath[chipPath.length - 1];
         var paragraph = nodes[chipPath[0]];
-        var chipNode = (_a = paragraph === null || paragraph === void 0 ? void 0 : paragraph.children) === null || _a === void 0 ? void 0 : _a[chipChildIdx];
+        var chipNode = (_b = paragraph === null || paragraph === void 0 ? void 0 : paragraph.children) === null || _b === void 0 ? void 0 : _b[chipChildIdx];
         var chipText = chipNode && 'value' in chipNode
-            ? String((_b = chipNode.value) !== null && _b !== void 0 ? _b : '')
+            ? String((_c = chipNode.value) !== null && _c !== void 0 ? _c : '')
             : '';
         var chipStart = converter.selectionToOffset(nodes, chipPath, 0);
         var chipEnd = chipStart + chipText.length;
+        var asked = inItsPlace ?
+            { plainText: plainText.slice(0, chipStart) + plainText.slice(chipEnd), offset: chipStart }
+            : { plainText: plainText, offset: chipEnd };
         if (isReady) {
-            performCompletionRequest(plainText, chipEnd);
+            performCompletionRequest(asked.plainText, asked.offset);
         }
         else {
-            pendingChipRequestRef.current = { plainText: plainText, offset: chipEnd };
+            pendingChipRequestRef.current = asked;
         }
     }, [isReady, isOpen, close, converter, performCompletionRequest]);
-    var handleExternalClose = (0, react_1.useCallback)(function (open) {
-        if (open)
-            return;
-        // Within ~300ms of `openAtChip`, this close is the popover reacting
-        // to the same mousedown that opened it — ignore.
-        if (Date.now() - justOpenedAtChipAtRef.current < 300) {
+    /* A click, a tap or Tab into the editor asks what can be written at the caret it put there, as typing asks
+       (qorus#646, David: one list for what can be written, opened by a click as by typing). The caret is the
+       page's, given as a Slate point: Slate's own selection follows the page's later, so it is set to it here, for
+       the pick to go where the caret is. What is being written at the caret, in the text it is in, filters the
+       list as typing does; nothing opens where nothing can be written (`eager: false`). */
+    var openAtCaret = (0, react_1.useCallback)(function (editor, caret, rect) {
+        var _a, _b, _c, _d;
+        editorRef.current = editor;
+        replacingChipPathRef.current = null;
+        anchoredChipPathRef.current = null;
+        setIsReplaceMode(false);
+        askedAtRef.current = caret;
+        try {
+            slate_1.Transforms.select(editor, caret);
+        }
+        catch (_e) {
+            // a point the editor no longer has: nothing is asked
             return;
         }
-        close();
+        var nodes = editor.children;
+        var plainText = converter.fromSlateNodes(nodes);
+        var offset = converter.selectionToOffset(nodes, caret.path, caret.offset);
+        var caretPath = caret.path;
+        var textNode = (_b = (_a = nodes[caretPath[0]]) === null || _a === void 0 ? void 0 : _a.children) === null || _b === void 0 ? void 0 : _b[caretPath[1]];
+        var written = typeof (textNode === null || textNode === void 0 ? void 0 : textNode.text) === 'string' ?
+            ((_d = (_c = /[@$/]?[\w.:{}-]*$/.exec(textNode.text.slice(0, caret.offset))) === null || _c === void 0 ? void 0 : _c[0]) !== null && _d !== void 0 ? _d : '')
+            : '';
+        setFilterPrefix(written);
+        setDocsFor(null);
+        setItems([]);
+        setFocusedIndex(0);
+        setEmptyMessage(undefined);
+        setPosition({ left: rect.left, top: rect.bottom });
+        popoverKeyRef.current += 1;
+        setPopoverKey(popoverKeyRef.current);
+        requestCompletions.cancel();
+        void performCompletionRequest(plainText, offset, { eager: false });
+    }, [converter, performCompletionRequest, requestCompletions]);
+    /* A click outside the list puts it away, whenever it comes; a close from a popover a chip has replaced does not.
+       A click on another chip while the list is open opens the list at that chip, under a new key, and the popover
+       it replaces says it closed only after that. Every close was ignored for 300 ms after a chip opened the list
+       instead, so a tap on Details soon after the chip's left the list open behind the card, and a later one put it
+       away: the frame showed it or not from run to run (qorus#646, DpqlEditor · Details On A Chip On A Touch
+       Screen); and a second click on the chip the list was at, later than that, closed it and opened it again. */
+    // the list drawn closed is at no chip
+    (0, react_1.useEffect)(function () {
+        if (!isOpen) {
+            anchoredChipPathRef.current = null;
+        }
+    }, [isOpen]);
+    var handleExternalClose = (0, react_1.useCallback)(function (open, key) {
+        if (!open && key === popoverKeyRef.current) {
+            close();
+        }
     }, [close]);
     // Fire a deferred chip-click request once the session connects — covers
     // a click made during the initialize handshake.
@@ -626,6 +1007,59 @@ function useLspAutocomplete(opts) {
             performCompletionRequest(plainText, offset);
         }
     }, [isReady, performCompletionRequest]);
+    var openBrowse = (0, react_1.useCallback)(function (editor, _a) {
+        var _b, _c;
+        var rect = _a.rect, caret = _a.caret, replacementPath = _a.replacementPath, levelId = _a.levelId, query = _a.query, selectedValue = _a.selectedValue, arrows = _a.arrows;
+        editorRef.current = editor;
+        requestCompletions.cancel();
+        requestGenerationRef.current++;
+        pendingRequestRef.current = false;
+        replacingChipPathRef.current = replacementPath !== null && replacementPath !== void 0 ? replacementPath : null;
+        anchoredChipPathRef.current = replacementPath !== null && replacementPath !== void 0 ? replacementPath : null;
+        setIsReplaceMode(!!replacementPath);
+        if (!replacementPath) {
+            // the pick goes at the caret given, the editor's own, or its end
+            try {
+                var at = (_c = caret !== null && caret !== void 0 ? caret : (_b = editor.selection) === null || _b === void 0 ? void 0 : _b.anchor) !== null && _c !== void 0 ? _c : slate_1.Editor.end(editor, []);
+                askedAtRef.current = at;
+                slate_1.Transforms.select(editor, at);
+            }
+            catch (_d) {
+                // a point the editor no longer has: the pick goes where the editor puts it
+                askedAtRef.current = null;
+            }
+        }
+        setItems([]);
+        setEmptyMessage(undefined);
+        setFilterPrefix('');
+        setDocsFor(null);
+        setPosition({ left: rect.left, top: rect.bottom });
+        setBrowse({ levelId: levelId, query: query, selectedValue: selectedValue, arrows: arrows });
+        setIsOpen(true);
+        popoverKeyRef.current += 1;
+        setPopoverKey(popoverKeyRef.current);
+    }, [requestCompletions]);
+    var pickTemplate = (0, react_1.useCallback)(function (node, written) {
+        // a context gone on into writes its reference (`$local:`); taken whole, its value (`$local:*`)
+        var value = written !== null && written !== void 0 ? written : (node.continues ? node.reference : node.value);
+        if (!value)
+            return;
+        /* what it is, for the editor to write it as it is: a field or a template as its chip, a function, a value or
+           a keyword as text, a template context as text that is completed on (`continues`) */
+        var kind = node.kind === 'field' ? 5
+            : node.kind === 'function' ? 3
+                : node.kind === 'keyword' ? 14
+                    : 6;
+        var item = (0, exports.toDropdownItems)([
+            {
+                label: node.label,
+                insertText: value,
+                kind: kind,
+                data: __assign({ templateNodeId: node.id }, (node.continues && !written ? { continues: true } : {})),
+            },
+        ])[0];
+        selectItem(__assign(__assign({}, item), { metadata: __assign(__assign({}, item.metadata), { retrigger: false }) }));
+    }, [selectItem]);
     return {
         // Expose the post-filter list as `items`; `groups` is filter-derived too.
         items: filteredItems,
@@ -633,14 +1067,23 @@ function useLspAutocomplete(opts) {
         isOpen: isOpen,
         isReplaceMode: isReplaceMode,
         isFetching: isFetching,
+        emptyMessage: isOpen ? emptyMessage : undefined,
+        note: isOpen ? note : undefined,
+        isActive: isOpen || isRequested,
         focusedIndex: focusedIndex,
         close: close,
         onSlateChange: onSlateChangeImpl,
         onItemSelect: onItemSelect,
+        openAtCaret: openAtCaret,
         openAtChip: openAtChip,
         handleExternalClose: handleExternalClose,
         popoverKey: popoverKey,
         position: position,
+        docsFor: docsFor,
+        toggleDocs: toggleDocs,
+        browse: isOpen ? browse : null,
+        openBrowse: openBrowse,
+        pickTemplate: pickTemplate,
     };
 }
 exports.useLspAutocomplete = useLspAutocomplete;