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

package/src/components/form/fields/template/TemplateField.tsx

@@ -28,8 +28,8 @@ import {
   IReqoreTextareaProps,
 } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { IQorusFormFieldSchemaBase, TQorusType } from '@qoretechnologies/ts-toolkit';
-import { size } from 'lodash';
-import React, { memo, useCallback, useEffect, useMemo, useState } from 'react';
+import { omit, size } from 'lodash';
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useUpdateEffect } from 'react-use';
 import {
   filterTemplatesByType as templatesFilterFunc,
@@ -40,7 +40,14 @@ import {
   describeTemplateReference,
   isValueTemplate,
 } from '../../../../helpers/templates';
+import { classifyTypedText, mightBeDpqlExpression } from '../../../../helpers/dpqlDetection';
+import {
+  renderTemplateItemDescriptions,
+  templateItemsToShow,
+} from '../../../../helpers/templateItems';
+import { useMarkdownRenderer } from '../../../Description/markdownRendererContext';
 import { getTypeFromValue } from '../../../../helpers/validations';
+import { useDpqlProbe } from '../../../dpqlEditor/useDpqlProbe';
 import { useQorusTypes } from '../../../../hooks/useQorusTypes';
 import { useWhyDidYouUpdate } from '../../../../hooks/useWhyDidYouUpdate';
 import { ExpressionBuilder, IExpressionBuilderProps } from '../../expressions/builder';
@@ -57,11 +64,27 @@ import LongStringFormField from '../long-string/LongString';
 import NumberFormField from '../number/Number';
 import { ReadOnlyTemplateTag } from './ReadOnlyTemplateTag';
 import { RichTextFormField } from '../rich-text/RichText';
+import { richtextToString } from '../../../../helpers/common';
+import { isSingleLineStringType } from '../../../../helpers/singleLineString';
+import {
+  IRowMenuRegistration,
+  RowMenuContext,
+  useRowMenu,
+  useRowMenuPublisher,
+} from '../../engine/rowMenuContext';
 
 // Re-export template utilities for consumers
 export { getTemplateKey, getTemplateValue, isValueTemplate };
 export type { IQorusFormType as IQorusType };
 
+/**
+ * How long the author must pause before typed text is sent to the DPQL
+ * probe. Long enough that a probe is not sent for every prefix of what is
+ * being typed, short enough that the offer appears while they are still
+ * looking at the field.
+ */
+const DPQL_DETECT_DEBOUNCE_MS = 400;
+
 export const TemplatesListProps: IReqoreDropdownProps = {
   useTargetWidth: true,
   handler: 'focus',
@@ -160,6 +183,14 @@ export interface ITemplateFieldProps extends Partial<
    * out of `rest` and never spread onto a leaf input.
    */
   extraActions?: IExpressionBuilderProps['extraActions'];
+  /**
+   * SEAM (reqraft): the host's per-`ui_type` editors, forwarded to the field
+   * component and to the expression editor's operand rows. Declared here — not
+   * left to the index signature — for the same reason as `extraActions` above:
+   * so it is destructured out of `rest` and never spread onto a leaf input or a
+   * Reqore layout component, both of which pass unknown props to the DOM.
+   */
+  componentOverrides?: Record<string, React.FC<any>>;
   [key: string]: any;
   default_value?: unknown;
 }
@@ -297,10 +328,9 @@ export const CustomMenuItems = memo(
     return (
       <ReqoreMenuSection label='Set Custom Value' isCollapsed transparent icon='Text' {...rest}>
         {items.map((menuItem, index) =>
-          'isDivider' in menuItem ? (
+          'isDivider' in menuItem ?
             <ReqoreMenuDivider key={index} {...menuItem} />
-          ) : (
-            <ReqoreButton
+          : <ReqoreButton
               {...(rest as any)}
               {...menuItem}
               key={index}
@@ -312,7 +342,6 @@ export const CustomMenuItems = memo(
                 });
               }}
             />
-          )
         )}
       </ReqoreMenuSection>
     );
@@ -331,6 +360,15 @@ export const TemplateDropdownSelector = memo(
     size,
     ...rest
   }: ITemplateDropdownSelectorProps) => {
+    /* The LAST hop before Reqore, which is the only place a drawn description
+       may be made: `filteredTemplates` upstream is a `JSON.stringify` memo key,
+       and an element in it throws on its own circular owner. */
+    const renderMarkdown = useMarkdownRenderer();
+    const shownItems = useMemo(
+      () => renderTemplateItemDescriptions(templateItemsToShow(items), renderMarkdown),
+      [items, renderMarkdown]
+    );
+
     // One resolver for every surface that names a reference — the picker chip
     // here, the read-only tag, and the compact row's expression summary. The
     // row and this editor must agree: a reference that reads as its path when
@@ -364,7 +402,7 @@ export const TemplateDropdownSelector = memo(
             minimal
             compact
             onItemSelect={onItemSelect}
-            items={items}
+            items={shownItems}
             label={label}
             leftIconProps={leftIconProps}
             caretPosition='right'
@@ -372,7 +410,7 @@ export const TemplateDropdownSelector = memo(
             size={size}
             {...TemplatesListProps}
           />
-          {allowCustomValues || value ? (
+          {allowCustomValues || value ?
             <ReqoreButton
               customTheme={TemplatesListProps.listCustomTheme}
               fixed
@@ -384,15 +422,48 @@ export const TemplateDropdownSelector = memo(
               size={size}
               onClick={onRemoveClick}
             />
-          ) : null}
+          : null}
         </ReqoreControlGroup>
       </ReqoreControlGroup>
     );
   }
 );
 
-export const TemplateField = memo(
+/**
+ * `ui_type`s whose OWN editor renders templates as chips inline.
+ *
+ * For these the template SELECTOR must not take over: it replaces a control the
+ * author can type in with one they can only pick from. A Qorus test assertion's
+ * `Value` is the case this was written for — the IDE's own `auto.tsx` already
+ * renders it as template rich text (type freely, references become chips), and
+ * the same field reached through this form engine offered a dropdown and no way
+ * to type at all.
+ *
+ * `richtext` is reqraft's own; a consumer adds its types through the
+ * `templateAwareUiTypes` prop, exactly as it adds `rendererOnlyUiTypes`.
+ */
+export const BuiltInTemplateAwareUiTypes = ['richtext'];
+
+export const isTemplateAwareUiType = (uiType?: string, extra?: string[]): boolean =>
+  !!uiType && [...BuiltInTemplateAwareUiTypes, ...(extra ?? [])].includes(uiType);
+
+/**
+ * One entry of the "set a value of this type" menu an untyped field offers.
+ *
+ * `onClick` is typed by what the caller actually invokes it with — the chosen
+ * value and a reset callback — rather than as `Function`, which accepts a class
+ * declaration as readily as a handler and gives no help at the call site.
+ */
+interface IUntypedFieldMenuItem {
+  label?: unknown;
+  description?: unknown;
+  isDivider?: boolean;
+  onClick?: (value: unknown, reset: () => void) => void;
+}
+
+const TemplateFieldImpl = memo(
   ({
+    rowMenu,
     value,
     name,
     onChange,
@@ -403,6 +474,7 @@ export const TemplateField = memo(
     allowFunctions,
     allowTextExpressions,
     extraActions,
+    componentOverrides,
     allowCustomValues = true,
     filterTemplatesByType = true,
     filterTemplatesFunc,
@@ -418,7 +490,7 @@ export const TemplateField = memo(
     reorder,
     label,
     ...rest
-  }: ITemplateFieldProps) => {
+  }: ITemplateFieldProps & { rowMenu?: IRowMenuRegistration }) => {
     const qorusTypes = useQorusTypes();
     const functions = useExpressions({
       allow: !!allowFunctions,
@@ -427,9 +499,22 @@ export const TemplateField = memo(
     });
     const type = rest.ui_type || rest.type || rest.defaultType;
 
+    /* The type an EXPRESSION must return, and is stored with, is a DATA type.
+       `type` above deliberately prefers `ui_type`, because that is what decides
+       which editor to render — but a ui_type says how a value is EDITED, not
+       what it is. The IDE's reference fields carry `ui_type: 'test-reference'`
+       (a rich-text editor that turns `$.` paths into chips), and feeding that
+       to the expression builder asked it for an expression RETURNING
+       `test-reference`: no expression returns one, so every choice was refused
+       with *"the expected return type is test-reference"*, and the ui_type was
+       then stored on the saved expression as its declared type.
+
+       The declared data type is the constraint; the ui_type is only a fallback
+       for a field that declares no type at all. */
+    const expressionDataType = rest.type || rest.defaultType || rest.ui_type;
+
     const filteredTemplates = useMemo<IReqoreFormTemplates>(():
-      | IReqoreFormTemplates
-      | undefined => {
+      IReqoreFormTemplates | undefined => {
       if (!allowTemplates) {
         return undefined;
       }
@@ -444,7 +529,20 @@ export const TemplateField = memo(
         result = filterTemplatesFunc(result);
       }
 
-      return result;
+      /* A lone category is opened, once, HERE — where this control resolves the
+         templates every one of its pickers then reads: the "Select Template"
+         dropdown, the in-editor `$` list, the numeric field's focus dropdown and
+         the expression builder's argument picker. Applying it per picker meant
+         each new one had to remember, and the ones that forgot made the author
+         click through a header naming the only category on offer to reach the
+         only values on offer.
+
+         LAST, after both filters. `filterTemplatesFunc` is given the grouped
+         shape on purpose — the Qog expression builder filters top-level items by
+         `metadata.dataRole`, which is a property of the CATEGORY — so flattening
+         before it would hand it values and quietly change what it keeps. This
+         only changes what is finally shown. */
+      return { ...result, items: templateItemsToShow(result?.items) };
     }, [
       JSON.stringify(templates),
       type,
@@ -469,24 +567,74 @@ export const TemplateField = memo(
     // Only while the field is EMPTY. A field already holding a literal must
     // open showing that literal — flipping to the template view would hide a
     // value the author put there and make it look lost.
-    // ...and only when there is actually something to pick. A field with no
-    // templates on offer would otherwise open on an EMPTY picker, which is a
-    // worse place to start than the type picker it replaced.
+    //
+    // A field that may hold a custom value opens there whether or not templates
+    // are on offer, and whether or not they have ARRIVED: template mode gives it
+    // a typable editor, which offers the list once there is one. Waiting for the
+    // list decided the landing from data that is async — on a cold load the
+    // type-filtered list did not exist at mount, so the field fell to the type
+    // picker and stayed there. A pick-only field (no custom values) is in
+    // template mode regardless, by the `!allowCustomValues` term.
     const typeIsAnyLike = type === 'any' || type === 'auto';
-    const isEmptyValue = value === undefined || value === null || value === '';
+    /* An EMPTY field, for the purpose of offering the template selector.
+   
+       `null` is deliberately not empty. It is the DPQL null literal — a value
+       an author writes to say "this is nothing", and the only way to assert
+       that a call returned no value. Counted as emptiness here, an argument
+       holding it was treated as a field the author had just cleared: with a
+       type of `any` and templates on offer, the selector-restore effect below
+       flipped the field into template mode with a null template value, and
+       that reported the field as cleared — so writing `null` in the Text tab
+       and switching to Visual silently erased it, leaving `{type: "any"}` in
+       the draft and the message "Value for argument 1 ("any") is invalid:
+       Value is empty".
+   
+       `undefined` is the cleared state; `null` is a value. Same rule as
+       `expressions/argumentPresence`, which states it canonically. */
+    const isEmptyValue = value === undefined || value === '';
     const hasTemplatesOnOffer = !!size(filteredTemplates?.items);
-    const [isTemplate, setIsTemplate] = useState<boolean>(
-      (isDefaultTemplate ||
-        isValueTemplate(value) ||
-        !allowCustomValues ||
-        (typeIsAnyLike && isEmptyValue && hasTemplatesOnOffer)) &&
+    /* The field's own editor already renders templates inline, so the selector
+       is not merely unnecessary here — it is a downgrade, swapping a typable
+       control for a pick-only one. Derived rather than folded into the state
+       below so every `setIsTemplate` path keeps working untouched; they simply
+       stop having anything to say for these fields. */
+    const editorHandlesTemplates =
+      !!allowTemplates && isTemplateAwareUiType(type as string, (rest as any).templateAwareUiTypes);
+
+    const hasOnlyAllowedValues = useMemo(
+      () => !!size(rest.allowed_values) && !rest.allowed_values_creatable,
+      [rest.allowed_values, rest.allowed_values_creatable]
+    );
+
+    /** Where this field lands when it is empty: an untyped one in template mode — see above. */
+    const emptyLandsOnTemplates =
+      typeIsAnyLike && (hasTemplatesOnOffer || (!!allowCustomValues && !hasOnlyAllowedValues));
+    const opensOnTemplates = isEmptyValue && emptyLandsOnTemplates;
+
+    const [isTemplateState, setIsTemplate] = useState<boolean>(
+      (isDefaultTemplate || isValueTemplate(value) || !allowCustomValues || opensOnTemplates) &&
         allowTemplates
     );
+
+    const isTemplate = editorHandlesTemplates ? false : isTemplateState;
     const [internalIsFunction, setInternalIsFunction] = useState<boolean>(
       !!isDefaultFunction && !!allowFunctions
     );
     const [templateValue, setTemplateValue] = useState<string | null>(value);
 
+    // Typed text that turned out to be an expression the author may accept.
+    const [dpqlOffer, setDpqlOffer] = useState<{ text: string; expression: any } | null>(null);
+    // The literal this field held before typed text switched it into
+    // expression mode — kept so the switch is undoable, and so the editor
+    // opens on the Text view the author was already writing in.
+    const [expressionFromText, setExpressionFromText] = useState<string | null>(null);
+    // Texts the author has said no to. Without this, dismissing an offer (or
+    // undoing a switch) would re-detect the same text on the next render and
+    // ask again forever.
+    const declinedTexts = useRef<Set<string>>(new Set());
+    const detectTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const probeDpql = useDpqlProbe();
+
     const effectiveIsFunction = isFunction || internalIsFunction;
 
     useWhyDidYouUpdate(`Template field ${name}`, {
@@ -502,6 +650,63 @@ export const TemplateField = memo(
       }
     }, [JSON.stringify(value)]);
 
+    /* Clearing an untyped field returns it to the template selector, which is
+       where mounting it empty already lands.
+
+       The rule above that opens an `any`-like field on the template selector is
+       a `useState` INITIALISER, so it only ever ran on mount. Clearing a value
+       in place does not remount anything, so the field fell through to the TYPE
+       picker and demanded `string`/`int`/`hash` before it would let the author
+       name a value they had already captured -- the very question that rule
+       exists to stop asking. Reloading the page fixed it, which is the tell:
+       same field, same empty value, different landing, because only one of the
+       two paths ran the rule.
+
+       Watched as a TRANSITION from a value to no value, not as "the value is
+       empty": an author who picks `Set Custom Value` on an empty field is
+       asking for the type picker, and re-asserting the template view on every
+       render while the field sat empty would take it away again immediately. */
+    const hadValue = useRef(!isEmptyValue);
+    /* A clear is REMEMBERED rather than acted on in the same render.
+
+       While the field holds a value its resolved type is that VALUE's type — a
+       reference reads as `test-reference`, not `auto` — and clearing reverts it
+       to the schema's `auto` one render LATER than the value empties. Acting
+       only on the transition therefore ran while `typeIsAnyLike` was still
+       false and did nothing, and by the time the type settled the transition
+       had passed. Measured in the live IDE at the moment of the clear:
+       `{ wasCleared: true, typeIsAnyLike: false, type: "test-reference",
+       hasTemplatesOnOffer: true }`, then `typeIsAnyLike: true` on the very next
+       render with `wasCleared` already false. */
+    const restoreSelectorWhenSettled = useRef(false);
+    /** Set by the template control's own `×`, which is an author saying "not a
+     *  template" — that clear must not be answered with the selector again. */
+    const suppressSelectorRestore = useRef(false);
+
+    useEffect(() => {
+      if (hadValue.current && isEmptyValue) {
+        restoreSelectorWhenSettled.current = !suppressSelectorRestore.current;
+        suppressSelectorRestore.current = false;
+      }
+      if (!isEmptyValue) {
+        // A value arrived: whatever the author did, they are not sitting on an
+        // empty field waiting to be offered the list.
+        restoreSelectorWhenSettled.current = false;
+      }
+      hadValue.current = !isEmptyValue;
+
+      if (
+        restoreSelectorWhenSettled.current &&
+        opensOnTemplates &&
+        allowTemplates &&
+        !effectiveIsFunction
+      ) {
+        restoreSelectorWhenSettled.current = false;
+        setTemplateValue(null);
+        setIsTemplate(true);
+      }
+    }, [isEmptyValue, opensOnTemplates, allowTemplates, effectiveIsFunction]);
+
     useEffect(() => {
       if (allowCustomValues && isTemplate && value && !isValueTemplate(value)) {
         setIsTemplate(false);
@@ -522,6 +727,17 @@ export const TemplateField = memo(
           return;
         }
 
+        // A template reference with an OPERATOR on it (`$local:count + 1`) is
+        // an expression, not a template. The loose check above passes it —
+        // it starts with `$` and has a colon — so without this every such
+        // string was swallowed into template mode, where the arithmetic is
+        // dead text and no affordance can reach it. A token standing alone
+        // (`$local:count`, `$data:{1.field}`) has no operator and still
+        // flips, which is the case template mode is for.
+        if (!isCompleteTemplateToken(value) && mightBeDpqlExpression(value)) {
+          return;
+        }
+
         setIsTemplate(true);
         setTemplateValue(value);
       }
@@ -534,11 +750,6 @@ export const TemplateField = memo(
       }
     }, [JSON.stringify(templateValue)]);
 
-    const hasOnlyAllowedValues = useMemo(
-      () => !!size(rest.allowed_values) && !rest.allowed_values_creatable,
-      [rest.allowed_values, rest.allowed_values_creatable]
-    );
-
     const showTemplateToggle = allowCustomValues && allowTemplates && !rest.arg_schema;
 
     // Only a BRACED context ref (`$data:{…}` — machine-written, nobody types
@@ -550,8 +761,23 @@ export const TemplateField = memo(
     // the rich-text string mode.
     const templateValueIsBracedToken = isBracedTemplateToken(templateValue);
 
+    /* An UNTYPED field can be typed into as well as picked from.
+    
+       Template mode has a typable editor whenever the field's type can hold
+       arbitrary text, and `any`/`auto` can — it is the type that has not been
+       narrowed yet, not a type that excludes text. Restricting this to
+       `string` meant an empty untyped field opened on template mode with no
+       editor to offer, so it fell through to the pick-only "Select Template"
+       dropdown: a control that can only choose from a list, on exactly the
+       fields where an author most often needs to write something the list
+       cannot hold — a deeper walk, a literal, or an expression.
+    
+       Reported against a Qorus assertion's Expected Value, and it was never
+       specific to that field: every empty untyped field with templates on
+       offer got the same downgrade. The editor still offers the same templates
+       on focus, so nothing is lost by being able to type as well. */
     const templateSupportsCustomValues =
-      allowCustomValues && type === 'string' && !hasOnlyAllowedValues;
+      allowCustomValues && (type === 'string' || typeIsAnyLike) && !hasOnlyAllowedValues;
     const showTemplatesDropdown =
       allowTemplates && (!allowCustomValues || (isTemplate && !templateSupportsCustomValues));
     const hasOnlyExpressions = !allowCustomValues && !allowTemplates && allowFunctions;
@@ -572,18 +798,28 @@ export const TemplateField = memo(
     const componentTypeProp = componentFromType ? { type } : {};
     const fieldAriaLabel = rest['aria-label'] ?? label ?? rest.display_name ?? name;
 
-
     const handleTemplateFieldChange = useCallback(
       (_name: string, val: string) => {
         if (!val) {
-          setIsTemplate(false);
+          /* Emptying the text leaves the field where an empty field lands. For
+             an untyped field that is THIS editor: switching to custom mode here
+             mounted a different editor in its place, so deleting the last
+             character lost the cursor. */
+          if (!(emptyLandsOnTemplates && allowTemplates)) {
+            setIsTemplate(false);
+          }
           setTemplateValue(null);
           onChange(name, undefined);
         } else {
           setTemplateValue(val);
         }
       },
-      [name, onChange]
+      [name, onChange, emptyLandsOnTemplates, allowTemplates]
+    );
+
+    const handleTemplateTextChange = useCallback(
+      (val: unknown) => handleTemplateFieldChange(name, typeof val === 'string' ? val : ''),
+      [handleTemplateFieldChange, name]
     );
 
     const handleSelectTemplateFromList = useCallback(
@@ -591,24 +827,38 @@ export const TemplateField = memo(
       (item) => {
         // If the template type is richtext, we need to wrap the template value in the richtext template format
         const value =
-          item.badge === 'richtext'
-            ? ([
-                {
-                  type: 'paragraph',
-                  children: [
-                    {
-                      children: [{ text: '' }],
-                      label: item.label,
-                      type: 'tag',
-                      value: item.value,
-                      metadata: item.metadata,
-                    },
-                  ],
-                },
-              ] as IReqoreRichTextEditorProps['value'])
-            : item.value;
-
-        onChange(name, value, hasOnlyAllowedValues ? (type as TQorusType) : (item.badge as TQorusType));
+          item.badge === 'richtext' ?
+            ([
+              {
+                type: 'paragraph',
+                /* The empty text nodes on either side are load-bearing. A
+                     chip is an inline VOID: it holds no text of its own, so the
+                     only places a cursor can go are the text nodes AROUND it.
+                     Slate treats that as an invariant and repairs it during
+                     normalisation, which runs on edits but NOT on a document
+                     handed in whole as a controlled value — which is what this
+                     is. Without them the picked template renders as a chip that
+                     cannot be typed after, so it can never be extended by hand. */
+                children: [
+                  { text: '' },
+                  {
+                    children: [{ text: '' }],
+                    label: item.label,
+                    type: 'tag',
+                    value: item.value,
+                    metadata: item.metadata,
+                  },
+                  { text: '' },
+                ],
+              },
+            ] as IReqoreRichTextEditorProps['value'])
+          : item.value;
+
+        onChange(
+          name,
+          value,
+          hasOnlyAllowedValues ? (type as TQorusType) : (item.badge as TQorusType)
+        );
       },
       [name, onChange]
     );
@@ -618,7 +868,15 @@ export const TemplateField = memo(
     // IDE-only, so the menu item is dropped (`allowSaving` is inert).
 
     const handleRemoveTemplateClick = useCallback(() => {
+      /* This is the `×` ON the template control, and it means "I do not want a
+         template here" — on a field whose menu offers no `Set Custom Value` it
+         is the ONLY way to reach a literal. So it still drops to the custom
+         value editor, and it tells the empty-field rule below to keep its hands
+         off this particular clear: that rule watches the value going away, and
+         this handler clears the value too, so without the flag it would send
+         the author straight back to the selector they just dismissed. */
       if (allowCustomValues) {
+        suppressSelectorRestore.current = true;
         setIsTemplate(false);
       }
 
@@ -668,12 +926,245 @@ export const TemplateField = memo(
       (expressionValue: IExpression | undefined, remove: boolean) => {
         if (remove) {
           setInternalIsFunction(false);
+          // The expression is gone, so there is no longer a switch to undo.
+          setExpressionFromText(null);
         }
-        onChange(name, expressionValue?.value, type as TQorusType, !remove);
+        onChange(name, expressionValue?.value, expressionDataType as TQorusType, !remove);
+      },
+      [name, onChange, expressionDataType, value]
+    );
+
+    // ─── Text typed into a plain field that is really a DPQL expression ───
+    //
+    // A field that accepts expressions still gets DPQL TYPED into it, in the
+    // ordinary editor, by an author who never opened the expression view.
+    // What happens then depends on the field's own type, and the asymmetry is
+    // deliberate: text that could stand as a literal here is only ever
+    // OFFERED, because silently rewriting the string `a + b` into a
+    // concatenation would destroy a value the author meant. Text that could
+    // NOT be a literal here was already an error the moment it was typed, so
+    // switching costs nothing and explains the error.
+    //
+    // The server decides whether the text is an expression at all — see
+    // `helpers/dpqlDetection` for why a successful parse alone means nothing.
+    const validationField = useMemo(
+      () => ({
+        validation_regex: rest.validation_regex,
+        has_to_be_valid_identifier: rest.has_to_be_valid_identifier,
+        has_to_have_value: rest.has_to_have_value,
+        rules: rest.rules,
+        arg_schema: rest.arg_schema,
+      }),
+      [
+        rest.validation_regex,
+        rest.has_to_be_valid_identifier,
+        rest.has_to_have_value,
+        JSON.stringify(rest.rules),
+        JSON.stringify(rest.arg_schema),
+      ]
+    );
+
+    const enterExpressionFromText = useCallback(
+      (text: string, expression: any) => {
+        setDpqlOffer(null);
+        setExpressionFromText(text);
+        setInternalIsFunction(true);
+        setIsTemplate(false);
+        setTemplateValue(null);
+        // `dpql/parse` answers with the field-ready envelope
+        // (`{is_expression, value}`); this field stores the inner AST and
+        // signals the flag through `onChange`'s fourth argument, exactly as
+        // `handleExpressionChange` does.
+        onChange?.(name, expression?.value ?? expression, expressionDataType as TQorusType, true);
       },
-      [name, onChange, type, value]
+      [name, onChange, expressionDataType]
     );
 
+    const undoExpressionFromText = useCallback(() => {
+      if (expressionFromText === null) {
+        return;
+      }
+
+      declinedTexts.current.add(expressionFromText);
+      setInternalIsFunction(false);
+      setExpressionFromText(null);
+      onChange?.(name, expressionFromText, type as TQorusType, false);
+    }, [expressionFromText, name, onChange, type]);
+
+    const declineDpqlOffer = useCallback(() => {
+      if (dpqlOffer) {
+        declinedTexts.current.add(dpqlOffer.text);
+      }
+
+      setDpqlOffer(null);
+    }, [dpqlOffer]);
+
+    const acceptDpqlOffer = useCallback(() => {
+      if (dpqlOffer) {
+        enterExpressionFromText(dpqlOffer.text, dpqlOffer.expression);
+      }
+    }, [dpqlOffer, enterExpressionFromText]);
+
+    // Held in a ref so the debounce below does not depend on it. `onChange`
+    // comes from the host form and can be a fresh function on any render;
+    // with the callback in the effect's deps, a re-render caused by a
+    // DIFFERENT field would restart this field's timer, and a form the
+    // author is typing in re-renders constantly.
+    const enterExpressionRef = useRef(enterExpressionFromText);
+    useEffect(() => {
+      enterExpressionRef.current = enterExpressionFromText;
+    }, [enterExpressionFromText]);
+
+    // Detection only runs on a field that could hold an expression and is
+    // currently showing a plain editor — never on a read-only field, a
+    // fixed-value list, or one already in template or expression mode.
+    const canDetectDpql =
+      !!allowFunctions &&
+      !!allowTextExpressions &&
+      !effectiveIsFunction &&
+      !isTemplate &&
+      !hasOnlyAllowedValues &&
+      !rest.readonly &&
+      !rest.readOnly &&
+      !rest.disabled;
+
+    useEffect(() => {
+      if (detectTimer.current) {
+        clearTimeout(detectTimer.current);
+        detectTimer.current = null;
+      }
+
+      /* A richtext field is still text. It hands its value back as a Slate
+         DOCUMENT rather than a flattened string — deliberately, so a chosen
+         reference cannot fuse with text typed beside it — and reading only
+         `typeof value === 'string'` here silently switched detection off for
+         every one of them the moment the field changed shape. A test
+         assertion's Value is exactly that field, and `1 + 2` typed into it
+         stopped being offered as an expression.
+
+         `richtextToString` flattens a tag to its raw value, so a document
+         holding only a chosen reference reads as `$.result` — no operator, so
+         `mightBeDpqlExpression` rejects it below and the server is never
+         asked. */
+      const text =
+        typeof value === 'string' ? value
+        : Array.isArray(value) ? richtextToString(value as never)
+        : undefined;
+
+      if (
+        !canDetectDpql ||
+        !text ||
+        declinedTexts.current.has(text) ||
+        !mightBeDpqlExpression(text)
+      ) {
+        setDpqlOffer(null);
+        return undefined;
+      }
+
+      let cancelled = false;
+
+      detectTimer.current = setTimeout(() => {
+        detectTimer.current = null;
+
+        void probeDpql(text)
+          .then((parsed) => {
+            if (cancelled) {
+              return;
+            }
+
+            const outcome = classifyTypedText({ text, type, field: validationField, parsed });
+
+            if (outcome === 'switch') {
+              enterExpressionRef.current(text, parsed.expression);
+            } else if (outcome === 'offer') {
+              setDpqlOffer({ text, expression: parsed.expression });
+            } else {
+              setDpqlOffer(null);
+            }
+          })
+          .catch(() => {
+            // Detection is an offer of help, never a reason for a field to
+            // break: an unreachable instance or a classifier that threw leaves
+            // the author's text exactly where they put it.
+            if (!cancelled) {
+              setDpqlOffer(null);
+            }
+          });
+      }, DPQL_DETECT_DEBOUNCE_MS);
+
+      return () => {
+        cancelled = true;
+
+        if (detectTimer.current) {
+          clearTimeout(detectTimer.current);
+          detectTimer.current = null;
+        }
+      };
+    }, [value, canDetectDpql, type, validationField, probeDpql]);
+
+    const canOfferExpression =
+      allowFunctions && !hasOnlyAllowedValues && !rest.readonly && !internalIsFunction;
+    const canOfferTemplate = showTemplateToggle && !isTemplate;
+
+    const publishedItems = useMemo(
+      () => [
+        ...(canOfferExpression && !functions.loading
+          ? [
+              {
+                label: 'Use Expression',
+                icon: 'Functions' as const,
+                tooltip: 'Run a function on this value',
+                onClick: handleSelectFunctionChange,
+              },
+            ]
+          : []),
+        ...(canOfferTemplate
+          ? [
+              {
+                label: 'Use Template',
+                icon: 'MoneyDollarCircleLine' as const,
+                tooltip: 'Use a template',
+                onClick: handleTemplateToggleClick,
+              },
+            ]
+          : []),
+        /* The "set a value of this type" choices an untyped field offers.
+           Dividers are dropped: they grouped items in a menu this field drew
+           itself, and in the row's shared menu they would divide other
+           people's. */
+        ...((menuItems ?? []) as IUntypedFieldMenuItem[])
+          .filter((item) => !('isDivider' in item))
+          .map((item) => ({
+            label: item.label as string,
+            description: item.description as string | undefined,
+            onClick: () =>
+              item.onClick?.(undefined, () => {
+                setIsTemplate(false);
+                setTemplateValue(null);
+              }),
+          })),
+      ],
+      [
+        canOfferExpression,
+        functions.loading,
+        canOfferTemplate,
+        menuItems,
+        handleSelectFunctionChange,
+        handleTemplateToggleClick,
+      ]
+    );
+
+    /* Keyed on WHICH items are offered, never on the items: they carry
+       handlers, so they are a new array every render and a row comparing them
+       by value would loop. */
+    const publishedKey = [
+      canOfferExpression && !functions.loading ? 'expression' : '',
+      canOfferTemplate ? 'template' : '',
+      `custom:${((menuItems ?? []) as { label?: unknown }[]).map((item) => String(item.label ?? '')).join('|')}`,
+    ].join(',');
+
+    useRowMenuPublisher(rowMenu, publishedKey, publishedItems as never);
+
     const renderControls = useCallback(() => {
       const showFunctionsDropdown =
         allowFunctions && !hasOnlyAllowedValues && !rest.readonly && !internalIsFunction;
@@ -681,33 +1172,44 @@ export const TemplateField = memo(
       // The "Set value" label promises a way to set one — reorder rows alone don't.
       const hasValueRows = showFunctionsDropdown || showTemplatesButton || size(menuItems) > 0;
 
+      /* ONE menu per control. Where this field sits in a form ROW, the row
+         already renders a ⋮ of its own, and drawing a second one beside it
+         put two menus of slightly different widths on the same control —
+         with the type choices an `any` field offers hidden in the narrower
+         one. The items are published to the row instead (see
+         `rowMenuContext`); outside a row there is nothing to publish into,
+         so the field goes on drawing its own. */
+      if (rowMenu) {
+        return null;
+      }
+
       if (hasOnlyExpressions) {
-        return showFunctionsDropdown ? (
-          functions.loading ? (
-            <ReqoreSkeleton size={rest.size} />
-          ) : (
-            <ReqoreButton
-              compact
-              minimal
-              label='Create New Expression'
-              className='function-selector'
-              icon='Functions'
-              tooltip='This field only accepts expressions'
-              onClick={() => {
-                setIsTemplate(false);
-                setTemplateValue(null);
-                onChange?.(
-                  name,
-                  {
-                    args: [],
-                  },
-                  undefined,
-                  true
-                );
-              }}
-            />
-          )
-        ) : null;
+        return (
+          showFunctionsDropdown ?
+            functions.loading ?
+              <ReqoreSkeleton size={rest.size} />
+            : <ReqoreButton
+                compact
+                minimal
+                label='Create New Expression'
+                className='function-selector'
+                icon='Functions'
+                tooltip='This field only accepts expressions'
+                onClick={() => {
+                  setIsTemplate(false);
+                  setTemplateValue(null);
+                  onChange?.(
+                    name,
+                    {
+                      args: [],
+                    },
+                    undefined,
+                    true
+                  );
+                }}
+              />
+          : null
+        );
       }
 
       if (hasValueRows || size(menuActions?.items) > 0) {
@@ -728,10 +1230,18 @@ export const TemplateField = memo(
                 transparent: true,
                 size: rest.size,
                 fixed: true,
-                // Centre the trailing menu in its flex line so it lines up with
-                // sibling action buttons (reqore alignSelf; replaces a reqraft
-                // `align-self !important` override of this button).
-                alignSelf: 'center',
+                /* Centre the trailing menu in its flex line so it lines up
+                   with sibling action buttons (reqore alignSelf; replaces a
+                   reqraft `align-self !important` override of this button).
+                
+                   Centring is only right beside a ONE-LINE editor. The
+                   expression shell is a toolbar with an editor, a type message
+                   and a preview stacked under it, so centring put this menu
+                   somewhere down the side of that block — level with nothing,
+                   over the editor, and a long way from the Undo it belongs
+                   beside. There it goes to the top, which is where the shell's
+                   own toolbar is. */
+                alignSelf: effectiveIsFunction ? 'flex-start' : 'center',
                 label: hasInputAffordance || !hasValueRows ? undefined : 'Set value',
                 style:
                   hasInputAffordance ?
@@ -757,11 +1267,10 @@ export const TemplateField = memo(
             handler='click'
             content={
               <ReqoreMenu size={rest.size} maxHeight='400px' style={{ overflow: 'auto' }}>
-                {showFunctionsDropdown ? (
-                  functions.loading ? (
+                {showFunctionsDropdown ?
+                  functions.loading ?
                     <ReqoreSkeleton size={rest.size} />
-                  ) : (
-                    <ReqoreButton
+                  : <ReqoreButton
                       compact
                       transparent
                       label='Use Expression'
@@ -770,10 +1279,10 @@ export const TemplateField = memo(
                       tooltip='Run a function on this value'
                       onClick={handleSelectFunctionChange}
                     />
-                  )
-                ) : null}
 
-                {showTemplatesButton ? (
+                : null}
+
+                {showTemplatesButton ?
                   <ReqoreButton
                     transparent
                     icon='MoneyDollarCircleLine'
@@ -786,19 +1295,19 @@ export const TemplateField = memo(
                     {' '}
                     Use Template{' '}
                   </ReqoreButton>
-                ) : null}
+                : null}
 
-                {size(menuActions?.items) > 0 ? (
+                {size(menuActions?.items) > 0 ?
                   <MenuActionsSection actions={menuActions} size={rest.size} />
-                ) : null}
+                : null}
 
-                {size(menuItems) > 0 ? (
+                {size(menuItems) > 0 ?
                   <CustomMenuItems
                     items={menuItems}
                     setIsTemplate={setIsTemplate}
                     setTemplateValue={setTemplateValue}
                   />
-                ) : null}
+                : null}
               </ReqoreMenu>
             }
           />
@@ -822,7 +1331,10 @@ export const TemplateField = memo(
       menuItems,
       menuActions,
       internalIsFunction,
+      effectiveIsFunction,
       hasInputAffordance,
+      // the row decides whether this field draws a menu at all
+      rowMenu,
     ]);
 
     // When the type is a list, and it has an element type - that element type is different
@@ -831,12 +1343,12 @@ export const TemplateField = memo(
     // This is a special case only for lists with element types
     const componentTemplates = useMemo(
       () =>
-        type === 'list' && (rest.ui_element_type || rest.element_type)
-          ? templates
-          : {
-              ...filteredTemplates,
-              ...TemplatesListProps,
-            },
+        type === 'list' && (rest.ui_element_type || rest.element_type) ?
+          templates
+        : {
+            ...filteredTemplates,
+            ...TemplatesListProps,
+          },
       [JSON.stringify(filteredTemplates), rest.ui_element_type, rest.element_type, type]
     );
 
@@ -854,9 +1366,14 @@ export const TemplateField = memo(
                   is_expression: true,
                   value,
                 }}
+                // The host's per-ui_type editors reach this field through the
+                // rest-spread; the expression shell needs them explicitly or the
+                // builder's operands render "Unknown type!" for any consumer
+                // ui_type (an assertion's `test-reference` Value, for one).
+                componentOverrides={componentOverrides}
                 localTemplates={templates}
                 type={type as string}
-                returnType={(returnType || type) as any}
+                returnType={(returnType || expressionDataType) as any}
                 onChange={handleExpressionChange}
                 readOnly={rest.readOnly || rest.disabled}
                 expressions={rest.expressions}
@@ -864,9 +1381,29 @@ export const TemplateField = memo(
                 serverHandled={rest.server_expression_handling}
                 extraActions={extraActions}
                 size={rest.size}
+                // An author who typed the expression as text is already
+                // writing in that language — dropping them into the visual
+                // builder would make them find their own sentence again.
+                defaultMode={expressionFromText !== null ? 'text' : 'visual'}
                 reorder={reorder}
               />
             </ReqoreErrorBoundary>
+            {expressionFromText !== null ?
+              <ReqoreButton
+                fixed
+                compact
+                minimal
+                icon='ArrowGoBackLine'
+                // No `intent` with `minimal`: a Reqore intent is a FILL, and
+                // `muted` as TEXT is 1.3:1 on the app surface.
+                size={rest.size}
+                className='dpql-detected-undo'
+                tooltip={`Keep "${expressionFromText}" as plain text instead`}
+                onClick={undoExpressionFromText}
+              >
+                Undo
+              </ReqoreButton>
+            : null}
             {renderControls()}
           </ReqoreControlGroup>
         );
@@ -880,10 +1417,11 @@ export const TemplateField = memo(
                 is_expression: true,
                 value,
               }}
+              componentOverrides={componentOverrides}
               localTemplates={templates}
               level={level}
               type={type as string}
-              returnType={(returnType || type) as any}
+              returnType={(returnType || expressionDataType) as any}
               onChange={handleExpressionChange}
               readOnly={rest.readOnly || rest.disabled}
               expressions={rest.expressions}
@@ -907,7 +1445,15 @@ export const TemplateField = memo(
         return <ReadOnlyTemplateTag value={templateValue} templates={templates} size={rest.size} />;
       }
 
-      return <Comp value={value} onChange={onChange} name={name} {...rest} />;
+      return (
+        <Comp
+          value={value}
+          onChange={onChange}
+          name={name}
+          {...rest}
+          componentOverrides={componentOverrides}
+        />
+      );
     }
 
     return (
@@ -919,7 +1465,7 @@ export const TemplateField = memo(
         stack={false}
         verticalAlign='flex-start'
       >
-        {!isTemplate && allowCustomValues ? (
+        {!isTemplate && allowCustomValues ?
           <Component
             value={value}
             allowTemplates={allowTemplates}
@@ -927,32 +1473,61 @@ export const TemplateField = memo(
             name={name}
             level={level}
             {...rest}
+            componentOverrides={componentOverrides}
             {...componentTypeProp}
             aria-label={fieldAriaLabel}
             className={`${className} template-selector`}
             templates={componentTemplates}
           />
-        ) : null}
-
-        {isTemplate && templateSupportsCustomValues && !templateValueIsBracedToken ? (
-          <LongStringField
+        : null}
+
+        {/* Template mode's editor for a value that can also be typed: each
+            reference in it is a chip named as the catalogue names it, while the
+            field still stores the plain string. A textarea spelled a chosen
+            template `$local:name` wherever it was edited — in the Visual
+            builder's operands, in every string field that takes templates. */}
+        {isTemplate && templateSupportsCustomValues && !templateValueIsBracedToken ?
+          <RichTextFormField
             className='template-selector'
-            type='string'
-            name='templateVal'
-            level={level}
-            value={templateValue}
-            templates={{
-              ...filteredTemplates,
-              ...TemplatesListProps,
-            }}
-            onChange={handleTemplateFieldChange}
-            {...rest}
+            valueFormat='text'
+            singleLine={isSingleLineStringType('string')}
+            value={typeof templateValue === 'string' ? templateValue : ''}
+            templates={filteredTemplates}
+            allowTemplates
+            onChange={handleTemplateTextChange}
+            // `tags` here are the field's own chips; the editor's `tags` are its template list.
+            {...omit(rest, 'tags')}
             aria-label={fieldAriaLabel}
           />
-        ) : null}
+        : null}
 
-        {showTemplatesDropdown ||
-        (isTemplate && templateSupportsCustomValues && templateValueIsBracedToken) ? (
+        {dpqlOffer ?
+          <ReqoreControlGroup fixed stack size={rest.size}>
+            <ReqoreButton
+              compact
+              icon='Functions'
+              intent='info'
+              className='dpql-detected-offer'
+              tooltip={`"${dpqlOffer.text}" reads as an expression. It is also valid text here, so nothing has been changed — use it as an expression?`}
+              onClick={acceptDpqlOffer}
+            >
+              Use as expression
+            </ReqoreButton>
+            <ReqoreButton
+              compact
+              icon='CloseLine'
+              intent='info'
+              className='dpql-detected-dismiss'
+              tooltip='Keep it as plain text'
+              onClick={declineDpqlOffer}
+            />
+          </ReqoreControlGroup>
+        : null}
+
+        {(
+          showTemplatesDropdown ||
+          (isTemplate && templateSupportsCustomValues && templateValueIsBracedToken)
+        ) ?
           <TemplateDropdownSelector
             allowCustomValues={allowCustomValues}
             templates={templates}
@@ -964,10 +1539,27 @@ export const TemplateField = memo(
             label={label}
             hasOnlyAllowedValues={hasOnlyAllowedValues}
           />
-        ) : null}
+        : null}
 
         {renderControls()}
       </ReqoreControlGroup>
     );
   }
 );
+
+/**
+ * The row channel belongs to the row's OWN editor: this field. It is read here
+ * and hidden from everything this field renders, so a field nested inside it —
+ * an expression operand, a list item — keeps drawing its own menu instead of
+ * publishing actions into a row menu that cannot say which value they act on.
+ * `undefined` outside a row, where this field draws its own menu too.
+ */
+export const TemplateField = memo((props: ITemplateFieldProps) => {
+  const rowMenu = useRowMenu();
+
+  return (
+    <RowMenuContext.Provider value={undefined}>
+      <TemplateFieldImpl {...props} rowMenu={rowMenu} />
+    </RowMenuContext.Provider>
+  );
+});