@qoretechnologies/reqraft 0.10.61 → 0.10.62-pr.137.g86641aa

package/src/components/form/expressions/ExpressionField.tsx

@@ -9,6 +9,7 @@
 import {
   ReqoreButton,
   ReqoreControlGroup,
+  ReqoreDropdown,
   ReqoreMessage,
   ReqoreVerticalSpacer,
 } from '@qoretechnologies/reqore';
@@ -20,6 +21,7 @@ import { TDpqlFields } from '../../dpqlEditor/types';
 import { ExpressionBuilder, IExpressionBuilderProps } from './builder';
 import { DpqlRendering } from './DpqlRendering';
 import { IExpression, IExpressionSchema, IExpressionValue, TExpressionReorder } from './types';
+import { incompleteExpressionText, serializableExpression } from './textOfExpression';
 import { useExpressions } from './useExpressions';
 import { useRenderExpression } from './useRenderExpression';
 import { isUntypedOptionType } from '../../../helpers/optionUiTypes';
@@ -80,6 +82,26 @@ export interface IExpressionFieldProps {
   fields?: TDpqlFields;
   /** Initial editor mode (default `visual`). */
   defaultMode?: TExpressionMode;
+  /**
+   * The Text view's text when the value is not an expression yet: a template or a literal the field held
+   * when "Use Template / Expression" opened it. Nothing is emitted until it is edited.
+   */
+  initialText?: string;
+  /**
+   * The field holds a plain value the text stands for - a template or a literal written in the Text view
+   * (stored as itself, not as an expression). The expression is then gone from `value` but the field is not
+   * cleared, so the text being written stays.
+   */
+  heldAsValue?: boolean;
+  /**
+   * The view a host's own tabs ask for (Value · Expression · Visual, qorus#646). Followed as the field's own
+   * Visual / Text toggle is: leaving the Text view parses what is written first, so nothing is lost.
+   */
+  requestedMode?: TExpressionMode;
+  /** The host draws the views as tabs of its own: the field's Visual / Text toggle is not drawn. */
+  hideModeToggle?: boolean;
+  /** No language server: the Text view cannot work, and the field shows the Visual view instead. */
+  onTextUnavailable?: () => void;
   /**
    * SEAM (reqraft): the host's per-`ui_type` editors, forwarded to the
    * builder's operand fields. Without them an operand typed with one of the
@@ -107,6 +129,11 @@ export const ExpressionField = memo(
     fields,
     recordType,
     defaultMode = 'visual',
+    initialText,
+    heldAsValue,
+    requestedMode,
+    hideModeToggle,
+    onTextUnavailable,
     size,
     componentOverrides,
     reorder,
@@ -124,7 +151,15 @@ export const ExpressionField = memo(
 
     // Text mode state. `text` is the DPQL string the editor shows; the AST
     // (`value`) stays the source of truth, kept in sync via parse-on-edit.
-    const [text, setText] = useState('');
+    const [text, setText] = useState(initialText ?? '');
+    /* No language server to parse or write the text: the Text view cannot work, so the field shows the
+       Visual view, which needs none, and says why (qorus#646). */
+    const [textUnavailable, setTextUnavailable] = useState(false);
+    const handleTextUnavailable = useCallback(() => {
+      setTextUnavailable(true);
+      setMode('visual');
+      onTextUnavailable?.();
+    }, [onTextUnavailable]);
     /* The text the current AST was parsed FROM.
      *
      * The preview renders the AST, and the AST only moves on a SUCCESSFUL
@@ -173,9 +208,14 @@ export const ExpressionField = memo(
      * noise the message below is written to avoid.
      */
     const readTypeCheck = useCallback(
-      (result?: { type_compatible?: boolean; auto_coercible?: boolean;
-        coercion_may_fail?: boolean; inferred_type?: string; target_type?: string;
-        suggested_fix?: { text: string } }): void => {
+      (result?: {
+        type_compatible?: boolean;
+        auto_coercible?: boolean;
+        coercion_may_fail?: boolean;
+        inferred_type?: string;
+        target_type?: string;
+        suggested_fix?: { text: string };
+      }): void => {
         if (!result || result.type_compatible === undefined) {
           setTypeCheck(null);
           return;
@@ -245,12 +285,17 @@ export const ExpressionField = memo(
         hadExpression.current = true;
         return;
       }
+      // a template or a literal written here is held as itself: the text stands for it, and stays
+      if (heldAsValue) {
+        hadExpression.current = false;
+        return;
+      }
       if (hadExpression.current) {
         hadExpression.current = false;
         userTypedRef.current = false;
         setText('');
       }
-    }, [ast]);
+    }, [ast, heldAsValue]);
 
     // Text mode: parse the DPQL into the AST (debounced).
     /* The session may not be attached when the debounce fires — the editor
@@ -329,7 +374,20 @@ export const ExpressionField = memo(
       }
       if (seededRef.current || userTypedRef.current) return undefined;
       if (!ast?.exp) return undefined;
-      const seedAst = ast;
+      /* Only what DPQL can write is serialized. An operand whose operation is not
+         chosen yet, or that is not filled in, has no text; handed to serialize as
+         it was, it came back as the server's (or a stand-in's) rendering of a hash:
+         `{args=(null)} > {type=int}`. The Text view shows the expression with a hole
+         for each part not filled in instead - `… > …`, as the row's summary does -
+         and serialize gets custom Text values as the strings or templates they are. */
+      const seedAst = serializableExpression(ast);
+      if (!seedAst) {
+        const holes = incompleteExpressionText(ast, expressions);
+        seededRef.current = true;
+        setText(holes);
+        setAstText(holes);
+        return undefined;
+      }
       let cancelled = false;
       let timer: ReturnType<typeof setTimeout> | null = null;
       let tries = 0;
@@ -349,7 +407,23 @@ export const ExpressionField = memo(
         cancelled = true;
         if (timer) clearTimeout(timer);
       };
-    }, [mode, ast]);
+    }, [mode, ast, expressions]);
+
+    /** The field's templates, its catalogue's entries, for the Text view's picker. */
+    const templateItems = useMemo(
+      () => (localTemplates?.items ?? []) as NonNullable<IReqoreFormTemplates['items']>,
+      [localTemplates]
+    );
+    /* A template chosen from the picker goes in after the text, as a chip, and is parsed as typed text is:
+       the editor keeps no caret the field can reach, so the end of the text is where it is put. */
+    const insertTemplate = useCallback(
+      (item: { value?: unknown }) => {
+        if (typeof item?.value !== 'string' || !item.value) return;
+        const current = text.trimEnd();
+        handleDpqlChange(current ? `${current} ${item.value}` : item.value);
+      },
+      [text, handleDpqlChange]
+    );
 
     // Switch to Text: the seeding effect above serializes the AST once
     // the editor's session is up.
@@ -370,6 +444,13 @@ export const ExpressionField = memo(
       setMode('visual');
     }, [mode, text, onChange, targetType, readTypeCheck]);
 
+    // the host's tabs: followed as the toggle is (see `requestedMode`)
+    useEffect(() => {
+      if (!requestedMode || requestedMode === mode) return;
+      if (requestedMode === 'visual') void enterVisualMode();
+      else if (!textUnavailable) enterTextMode();
+    }, [requestedMode]);
+
     useEffect(
       () => () => {
         if (parseTimer.current) clearTimeout(parseTimer.current);
@@ -394,39 +475,64 @@ export const ExpressionField = memo(
         className='expression-field'
         data-preview={mode === 'text' ? previewState : undefined}
       >
-        <ReqoreControlGroup gapSize='small' fluid>
-          <ReqoreButton
-            icon='NodeTree'
-            active={mode === 'visual'}
-            onClick={enterVisualMode}
-            disabled={readOnly}
-            size={size as any}
-          >
-            Visual
-          </ReqoreButton>
-          <ReqoreButton
-            icon='CodeLine'
-            active={mode === 'text'}
-            onClick={enterTextMode}
-            disabled={readOnly}
-            size={size as any}
-          >
-            Text
-          </ReqoreButton>
-        </ReqoreControlGroup>
+        {hideModeToggle ? null : (
+          <ReqoreControlGroup gapSize='small' fluid>
+            <ReqoreButton
+              icon='NodeTree'
+              active={mode === 'visual'}
+              onClick={enterVisualMode}
+              disabled={readOnly}
+              size={size as any}
+            >
+              Visual
+            </ReqoreButton>
+            <ReqoreButton
+              icon='CodeLine'
+              active={mode === 'text'}
+              onClick={enterTextMode}
+              disabled={readOnly || textUnavailable}
+              tooltip={
+                textUnavailable ? 'The expression language server is not available' : undefined
+              }
+              size={size as any}
+            >
+              Text
+            </ReqoreButton>
+          </ReqoreControlGroup>
+        )}
 
-        {mode === 'text' ? (
+        {mode === 'text' ?
           <>
-            <DpqlEditor
-              ref={dpqlRef}
-              value={text}
-              onChange={handleDpqlChange}
-              provider={provider}
-              recordType={recordType}
-              fields={fields}
-              readOnly={readOnly}
-              height='48px'
-            />
+            <ReqoreControlGroup gapSize='small' fluid verticalAlign='flex-start'>
+              <DpqlEditor
+                ref={dpqlRef}
+                value={text}
+                onChange={handleDpqlChange}
+                provider={provider}
+                recordType={recordType}
+                fields={fields}
+                // the field's own templates name the chips as its catalogue names them
+                templates={localTemplates}
+                readOnly={readOnly}
+                height='48px'
+                onUnavailable={handleTextUnavailable}
+              />
+              {/* The field's templates and fields, as its catalogue names them, inserted as chips - next to
+                  the server's `$` completion, which offers every context but not these names. */}
+              {templateItems.length && !readOnly ?
+                <ReqoreDropdown
+                  className='expression-text-template-picker'
+                  icon='MoneyDollarCircleLine'
+                  aria-label='Insert a template'
+                  tooltip='Insert a template'
+                  size={size as any}
+                  filterable
+                  fixed
+                  items={templateItems}
+                  onItemSelect={insertTemplate}
+                />
+              : null}
+            </ReqoreControlGroup>
             {/* What the server said about the result's type, when the field
                 declares one to check against.
 
@@ -449,12 +555,12 @@ export const ExpressionField = memo(
                 {typeCheck.mayFail ?
                   ' That conversion is attempted rather than guaranteed, so the value itself is checked when it runs.'
                 : ''}
-                {typeCheck.fix ? (
+                {typeCheck.fix ?
                   <>
                     <ReqoreVerticalSpacer height={6} />
                     <DpqlRendering text={typeCheck.fix} data-testid='expression-type-fix' />
                   </>
-                ) : null}
+                : null}
               </ReqoreMessage>
             )}
 
@@ -471,30 +577,43 @@ export const ExpressionField = memo(
 
                 An empty query has nothing to render either, so the box appears
                 once there is a result rather than holding a placeholder. */}
-            {previewState === 'shown' ? (
+            {previewState === 'shown' ?
               <ReqoreMessage intent='info' size='small' title='Preview' flat opaque={false}>
                 <DpqlRendering text={preview} data-testid='expression-preview' />
               </ReqoreMessage>
-            ) : null}
+            : null}
           </>
-        ) : (
-          <ExpressionBuilder
-            value={value}
-            onChange={(v, remove) => onChange(v, remove)}
-            expressions={expressions}
-            // Default to `auto` when the field declares no return type, so a
-            // valid expression renders `muted` rather than `danger` (the
-            // builder's intent requires a truthy returnType).
-            returnType={(returnType ?? type ?? 'auto') as any}
-            readOnly={readOnly}
-            localTemplates={localTemplates ?? { items: [] }}
-            serverHandled={serverHandled}
-            componentOverrides={componentOverrides}
-            extraActions={extraActions}
-            size={size}
-            reorder={reorder}
-          />
-        )}
+        : <>
+            {textUnavailable ?
+              <ReqoreMessage
+                intent='muted'
+                size='small'
+                flat
+                opaque={false}
+                className='expression-text-unavailable'
+              >
+                The Text view needs the expression language server, which is not available: the
+                expression is built here instead.
+              </ReqoreMessage>
+            : null}
+            <ExpressionBuilder
+              value={value}
+              onChange={(v, remove) => onChange(v, remove)}
+              expressions={expressions}
+              // Default to `auto` when the field declares no return type, so a
+              // valid expression renders `muted` rather than `danger` (the
+              // builder's intent requires a truthy returnType).
+              returnType={(returnType ?? type ?? 'auto') as any}
+              readOnly={readOnly}
+              localTemplates={localTemplates ?? { items: [] }}
+              serverHandled={serverHandled}
+              componentOverrides={componentOverrides}
+              extraActions={extraActions}
+              size={size}
+              reorder={reorder}
+            />
+          </>
+        }
       </ReqoreControlGroup>
     );
   }

package/src/components/form/expressions/builder/ExpressionBuilder.stories.tsx

@@ -200,12 +200,19 @@ export const WithSimpleValue: Story = {
     docs: {
       description: {
         story:
-          'Renders the ExpressionBuilder holding a single "contains" expression with three arguments — the card shows the operation and each operand slot.',
+          'Renders the ExpressionBuilder holding a single "contains" expression with three arguments — the card shows the operation and each operand slot. Each text value is 150px wide, the one holding a template as well as the one holding text: in a row with room, a text field is no narrower than that.',
       },
     },
   },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
+    await waitFor(() =>
+      expect(
+        [...document.querySelectorAll<HTMLElement>('.expression-arg [data-slate-editor]')].map((editor) =>
+          Math.round((editor.closest('.reqore-panel') as HTMLElement).getBoundingClientRect().width)
+        )
+      ).toEqual([150, 150])
+    );
   },
 };
 

package/src/components/form/expressions/builder/index.tsx

@@ -32,6 +32,7 @@ import {
   isTextOrDateType,
 } from '../../../../helpers/expressions';
 import { addMissingExpressionArgs } from '../argumentPresence';
+import { isUntypedOptionType } from '../../../../helpers/optionUiTypes';
 import { findTemplate } from '../../../../helpers/templates';
 import { validateField, validateFieldWithResult } from '../../../../helpers/validations';
 import { IQorusTypeObject, useQorusTypes } from '../../../../hooks/useQorusTypes';
@@ -520,9 +521,16 @@ export const Expression = ({
   }, [onValueChange, path]);
 
   const firstArgSchema = selectedExpression?.args[0];
+  /* An empty untyped operand is of the type the catalogue declares for it, as the other operands are:
+     falling back to the builder's own type gave the first value of a condition (the builder's `bool`)
+     or of an untyped builder (`context`) a type it is not, which rendered as "Unknown type!" once an
+     untyped operand was written as text. */
   const firstParamType = firstArgument?.is_expression
     ? firstArgSchema?.ui_type
-    : firstArgument?.type || type || 'context';
+    : firstArgument?.type ||
+      (isUntypedOptionType(firstArgSchema?.ui_type) ? firstArgSchema?.ui_type : undefined) ||
+      type ||
+      'context';
   let restOfArgs = selectedExpression?.args.slice(1);
   const argCount = size(value.value?.args);
   const canReorderArgs =
@@ -1129,7 +1137,10 @@ export const Expression = ({
               allowCustomValues={
                 !!firstArgument?.allowed_values ||
                 !!firstArgument?.element_allowed_values ||
-                (!!firstArgument?.type && !serverExpression)
+                // an untyped operand is written as text from the start, as a typed one is once
+                // it has a type: a template chosen into it is a chip, with text around it
+                ((!!firstArgument?.type || isUntypedOptionType(firstArgSchema?.ui_type)) &&
+                  !serverExpression)
               }
               filterTemplatesFunc={(templates) => {
                 // PORT NOTE: `?.` on `items` added — with no templates at all
@@ -1242,7 +1253,9 @@ export const Expression = ({
                         !!arg.allowed_values ||
                         !!arg.element_allowed_values ||
                         !!rest[index]?.type ||
-                        !!arg.default_value
+                        !!arg.default_value ||
+                        // an untyped operand is written as text from the start (see the first operand)
+                        isUntypedOptionType(arg.ui_type)
                       }
                       onChange={((_name, value, type, isFunction) => {
                         updateArg(value, index + 1, isFunction ? undefined : type, isFunction);

package/src/components/form/expressions/dpqlMockLanguage.ts

@@ -391,8 +391,13 @@ export const mockParseDpql = (text: string, target?: string): IDpqlMockParseResu
     const tokens = tokenize(trimmed);
     const node = parseTokens(tokens, trimmed.length + 1);
     // A lone value is wrapped in `value(...)`, which is how the server tells a
-    // literal apart from an expression.
-    const root: IDpqlMockNode = node.exp ? node : { exp: 'value', args: [node] };
+    // literal apart from an expression; a lone template reference in `template(...)`,
+    // as the server's parser wraps one (Qore DpqlParser: DP_EXPR_TEMPLATE).
+    const isTemplate = !!(node.value as { tmpl_context?: unknown } | undefined)?.tmpl_context;
+    const root: IDpqlMockNode =
+      node.exp ? node
+      : isTemplate ? { exp: 'template', args: [node] }
+      : { exp: 'value', args: [node] };
     const inferred = inferDpqlMockType(root);
     return {
       success: true,

package/src/components/form/expressions/expressionOperands.ts

@@ -0,0 +1,74 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// The operands of an expression as the Visual view stores them, read as what they hold.
+//
+// The Visual view stores operands in the shapes its editors produce, and two of
+// them are not values at all:
+//
+// - an operand switched to "Use Expression" whose operation is not chosen yet
+//   (`{ is_expression: true, value: { args } }`, no `exp`), and an operand not
+//   filled in (`{}`, `{ type }`): there is nothing in them yet;
+// - a custom Text value, which is a rich-text document (a list of Slate nodes),
+//   not a string.
+//
+// Everything that writes an expression as text reads its operands here - the
+// Text view's `dpql/serialize`, the read-first row summary, and an application's
+// own summaries - so none of them prints a hash or `[object Object]` for them.
+// Pure: no transport/socket import.
+import { richtextToSegments, richtextToString } from '../../../helpers/common';
+import { IExpression, IExpressionValue } from './types';
+
+const isObject = (value: unknown): value is Record<string, any> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+/** A rich-text value as the operand it holds, or `undefined` when it is empty. */
+const richtextOperand = (value: unknown): IExpression | undefined => {
+  const segments = richtextToSegments(value as never).filter(
+    (segment) => segment.kind === 'tag' || segment.text.trim()
+  );
+  if (!segments.length) return undefined;
+  // a single template is that template, as a template picked from the list is
+  if (segments.length === 1 && segments[0].kind === 'tag') {
+    return { type: 'auto', value: segments[0].value };
+  }
+  return { type: 'string', value: richtextToString(value as never) };
+};
+
+/**
+ * One operand as what it holds: a literal, a `{ type, value }`, or a nested
+ * expression whose own operands are read the same way; `undefined` when it is
+ * not filled in yet (an operation not chosen, a value not given).
+ *
+ * A nested expression whose operation is chosen but whose operands are not all
+ * filled in is kept, with its missing operands as `undefined`, so a summary can
+ * write what is there.
+ */
+export const expressionOperand = (arg: unknown): unknown => {
+  if (arg === undefined || arg === null) return undefined;
+  if (!isObject(arg)) return arg;
+  if (arg.is_expression) {
+    if (!isObject(arg.value) || !arg.value.exp) return undefined;
+    return { ...arg, value: expressionWithOperands(arg.value as IExpressionValue) };
+  }
+  if ('exp' in arg) return arg.exp ? expressionWithOperands(arg as IExpressionValue) : undefined;
+  if (!('value' in arg) || arg.value === undefined) return undefined;
+  if (arg.type === 'richtext') return richtextOperand(arg.value);
+  return arg;
+};
+
+/** The expression with each operand read as what it holds (`undefined` where none is given yet). */
+export const expressionWithOperands = (value: IExpressionValue): IExpressionValue => ({
+  ...value,
+  args: (value.args ?? []).map(expressionOperand) as IExpression[],
+});
+
+/** Whether every part of the expression is filled in: an operation, and each of its operands. */
+export const isExpressionComplete = (value: IExpressionValue | undefined): boolean => {
+  if (!value?.exp) return false;
+  return (value.args ?? []).every((arg) => {
+    const operand = expressionOperand(arg);
+    if (operand === undefined) return false;
+    if (isObject(operand) && operand.is_expression) return isExpressionComplete(operand.value as IExpressionValue);
+    if (isObject(operand) && 'exp' in operand) return isExpressionComplete(operand as IExpressionValue);
+    return true;
+  });
+};

package/src/components/form/expressions/mockExpressions.ts

@@ -8,10 +8,7 @@ import { IExpressionSchema } from './types';
 
 // String comparators share this arg shape: a richtext value (with the
 // operator word as `label_after`), a richtext operand, and an Ignore Case flag.
-const stringArgs = (
-  operandLabel: string,
-  operatorWord: string
-): IExpressionSchema['args'] => [
+const stringArgs = (operandLabel: string, operatorWord: string): IExpressionSchema['args'] => [
   {
     name: 'softstring',
     display_name: 'String Value',
@@ -36,6 +33,21 @@ const comparatorArgs = (operatorWord: string): IExpressionSchema['args'] => [
 ];
 
 export const mockExpressions: IExpressionSchema[] = [
+  // As the server defines it (qorus Classes/QorusExpressions.qc QO_VALUE): what a value written alone parses
+  // into, so a value the Visual view starts from is shown as itself.
+  {
+    name: 'value',
+    display_name: 'Value',
+    short_desc: 'Evaluates and returns a field reference value',
+    desc: 'Evaluates the given field reference and returns its value; this allows field references to be used as standalone expressions',
+    symbol: '',
+    type: 1,
+    subtype: 1,
+    return_type: 'any',
+    ui_return_type: 'any',
+    varargs: false,
+    args: [{ name: 'any', display_name: 'Value', ui_type: 'any', required: true }],
+  },
   {
     name: '==',
     display_name: 'Logical Equals',

package/src/components/form/expressions/renderExpressionToText.ts

@@ -4,8 +4,12 @@
 // can wait uses it: Explain and the Text view's Preview wait for the server's
 // `dpql/renderExpression` (see `useRenderExpression`). Pure: no
 // transport/socket import, so it stays out of the LSP/nanoid dependency graph.
+import { expressionOperand } from './expressionOperands';
 import { IExpression, IExpressionSchema, IExpressionValue } from './types';
 
+/** How a part not filled in yet is written: an operation not chosen, a value not given. */
+export const EXPRESSION_HOLE = '…';
+
 /** A symbol made only of non-word characters renders infix (`a == b`). */
 const isOperatorSymbol = (symbol?: string): boolean =>
   !!symbol && /^[^\w\s]+$/.test(symbol);
@@ -109,15 +113,28 @@ const renderInContext = (
   // parentheses and commas already delimit its arguments.
   const isInfix = isLogicalGroup || (args.length === 2 && isOperatorSymbol(symbol));
 
-  const parts = args.map((arg: IExpression, argn: number) =>
-    arg?.is_expression && arg.value?.exp
-      ? renderInContext(
-          arg.value,
-          expressions,
-          isInfix ? argumentContext(value.exp as string, argn) : PREC_LOOSEST
-        )
-      : renderLiteral(arg?.value)
-  );
+  /* Each operand as what it holds (expressionOperands): a custom Text value is the
+     template or the words in it, and one not filled in yet - an operation not chosen,
+     a value not given - is a hole, not `null` and not the editor's rich-text document. */
+  const parts = args.map((raw: IExpression, argn: number) => {
+    const arg = expressionOperand(raw) as IExpression | undefined;
+    if (arg === undefined) return EXPRESSION_HOLE;
+    if (arg?.is_expression && arg.value?.exp) {
+      return renderInContext(
+        arg.value,
+        expressions,
+        isInfix ? argumentContext(value.exp as string, argn) : PREC_LOOSEST
+      );
+    }
+    if (arg && typeof arg === 'object' && 'exp' in arg) {
+      return renderInContext(
+        arg as IExpressionValue,
+        expressions,
+        isInfix ? argumentContext(value.exp as string, argn) : PREC_LOOSEST
+      );
+    }
+    return renderLiteral(arg && typeof arg === 'object' && 'value' in arg ? arg.value : arg);
+  });
 
   if (!isInfix) {
     return `${symbol}(${parts.join(', ')})`;

package/src/components/form/expressions/textOfExpression.ts

@@ -0,0 +1,39 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// What the Text view is given for an expression built in the Visual view.
+//
+// `dpql/serialize` was handed the AST as the Visual view stores it, and wrote what
+// it could of operands that are not DPQL (see expressionOperands): the server
+// `{args=(null)} > {type=int}`, a stand-in `undefined([object Object]) > [object Object]`.
+// The Text view serializes only an expression that is filled in, with its operands
+// read as what they hold, and shows one that is not with a hole for each missing part.
+import { expressionOperand, expressionWithOperands, isExpressionComplete } from './expressionOperands';
+import { EXPRESSION_HOLE, renderExpressionToText } from './renderExpressionToText';
+import { IExpressionSchema, IExpressionValue } from './types';
+
+export { EXPRESSION_HOLE };
+
+/**
+ * The expression as `dpql/serialize` can write it, or `undefined` when part of it
+ * is not filled in yet (an operation not chosen, an operand left empty).
+ */
+export const serializableExpression = (
+  value: IExpressionValue | undefined
+): IExpressionValue | undefined => (isExpressionComplete(value) ? expressionWithOperands(value!) : undefined);
+
+/**
+ * An expression that is not filled in yet, as text: what is there, and a
+ * {@link EXPRESSION_HOLE} for each part that is not - `… > …` for a comparison
+ * whose values are not chosen, as the read-first row writes it. Not DPQL; the
+ * Text view shows it until the author writes the rest.
+ */
+export const incompleteExpressionText = (
+  value: IExpressionValue | undefined,
+  expressions: IExpressionSchema[] = []
+): string =>
+  value?.exp
+    ? renderExpressionToText(value, expressions)
+        // a field of the record, as DPQL names it
+        .replace(/"\$record:\{([^}]+)\}"/g, '@$1')
+    : EXPRESSION_HOLE;
+
+export { expressionOperand };

package/src/components/form/expressions/useRenderExpression.ts

@@ -20,6 +20,7 @@ import { nanoid } from 'nanoid';
 import { useCallback, useEffect, useRef } from 'react';
 import { ReqraftLspClient } from '../../../utils/lspClient';
 import { IExpressionValue } from './types';
+import { expressionWithOperands, isExpressionComplete } from './expressionOperands';
 
 /* The synchronous summary a collapsed row prints — see `readFirst.ts`. It is
    not a stand-in for this rendering and is never shown in its place. */
@@ -137,7 +138,14 @@ export const useRenderExpression = (): IUseRenderExpressionResult => {
           pendingRef.current = null;
           if (!job) return;
           lastRunRef.current = Date.now();
-          const outcome = job.value?.exp ? await renderViaServer(job.value) : null;
+          /* Only what can be rendered is asked for, with its operands read as what they
+             hold (expressionOperands) - as the Text view's serialize is. An expression
+             with a part not filled in yet (an operation not chosen, a value not given)
+             has no rendering; sent as it was, the stories' stand-in server threw on it
+             and the real one writes its operands as hashes. */
+          const outcome = isExpressionComplete(job.value)
+            ? await renderViaServer(expressionWithOperands(job.value))
+            : null;
           job.resolvers.forEach((r) => r(outcome));
         };