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

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

@@ -3,8 +3,9 @@
 // Owns the `IExpression` value and offers two views of the same AST —
 // Visual (the builder, Phase 3) and Text (DPQL, this phase). The DPQL text
 // editor bridges to the AST via the LSP `dpql/parse` (text → AST on edit)
-// and `dpql/serialize` (AST → text on entering Text mode); a live "Parsed"
-// line renders the current AST (`dpql/renderExpression`).
+// and `dpql/serialize` (AST → text on entering Text mode); a debounced
+// "Preview" box renders the current AST (`dpql/renderExpression`) when that
+// rendering differs from the text the author typed.
 import {
   ReqoreButton,
   ReqoreControlGroup,
@@ -21,6 +22,15 @@ import { useRenderExpression } from './useRenderExpression';
 export type TExpressionMode = 'visual' | 'text';
 
 const PARSE_DEBOUNCE_MS = 300;
+/**
+ * How long the Preview waits before catching up with the editor.
+ *
+ * It mirrors the AST, so without this it re-renders on every keystroke — a box
+ * appearing, changing and vanishing under the line being typed. Slightly
+ * SLOWER than the parse it follows, so the preview settles once after the text
+ * has stopped moving rather than twitching on the way there.
+ */
+const PREVIEW_DEBOUNCE_MS = 400;
 /** Retry cadence for seeding the Text editor while its LSP session opens. */
 const SEED_RETRY_MS = 400;
 const SEED_MAX_TRIES = 20;
@@ -62,6 +72,12 @@ export interface IExpressionFieldProps {
   recordType?: string;
   /** Initial editor mode (default `visual`). */
   defaultMode?: TExpressionMode;
+  /**
+   * SEAM (reqraft): the host's per-`ui_type` editors, forwarded to the
+   * builder's operand fields. Without them an operand typed with one of the
+   * CONSUMER's ui_types renders "Unknown type!".
+   */
+  componentOverrides?: Record<string, React.FC<any>>;
   size?: string;
   /** Forwarded to the builder — operand reordering for varargs expressions. */
   reorder?: TExpressionReorder;
@@ -83,6 +99,7 @@ export const ExpressionField = memo(
     recordType,
     defaultMode = 'visual',
     size,
+    componentOverrides,
     reorder,
   }: IExpressionFieldProps) => {
     const { expressions } = useExpressions({
@@ -100,60 +117,204 @@ 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('');
+    /* The text the current AST was parsed FROM.
+     *
+     * The preview renders the AST, and the AST only moves on a SUCCESSFUL
+     * parse — so while an edit is mid-flight or simply invalid, the AST still
+     * describes the last thing that parsed. Showing it then states something
+     * the editor does not contain: deleting the `2` from `1 + 2` left
+     * "Unexpected end of input" sitting directly above a Preview confidently
+     * reading `1 + 2`. */
+    const [astText, setAstText] = useState('');
+    /**
+     * The server's answer to "can this expression's result satisfy the type
+     * this field declares?". `null` when nothing has been asked, or when the
+     * field declares no type worth asking about.
+     */
+    const [typeCheck, setTypeCheck] = useState<{
+      compatible: boolean;
+      mayFail: boolean;
+      inferred?: string;
+      target?: string;
+      fix?: string;
+    } | null>(null);
     const dpqlRef = useRef<IDpqlEditorRef>(null);
     const parseTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
     const ast = useMemo<IExpressionValue | undefined>(() => value?.value, [value]);
 
+    /**
+     * The type the expression's result has to satisfy, sent with every parse.
+     *
+     * `auto` and `any` are left out deliberately: they accept anything, so the
+     * server would answer "compatible" for everything and the round trip would
+     * buy nothing. A field offering a CHOICE of return types has no single
+     * answer either, so it asks nothing rather than asking about the wrong one.
+     */
+    const targetType = useMemo<string | undefined>(() => {
+      const declared = Array.isArray(returnType) ? undefined : (returnType ?? type);
+      return declared && declared !== 'auto' && declared !== 'any' ? declared : undefined;
+    }, [returnType, type]);
+
+    /** Read the type analysis off a parse result, or clear it. */
+    const readTypeCheck = useCallback(
+      (result?: { type_compatible?: 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;
+        }
+        setTypeCheck({
+          compatible: !!result.type_compatible,
+          mayFail: !!result.coercion_may_fail,
+          inferred: result.inferred_type,
+          target: result.target_type,
+          fix: result.suggested_fix?.text,
+        });
+      },
+      []
+    );
+
     // Keep a readable rendering of the current expression in sync — the
     // single live mirror of the AST (server `dpql/renderExpression` when
     // reachable, the client-side approximation otherwise).
+    //
+    // Debounced: it follows the AST, which follows the text, so rendering it
+    // eagerly put a box under the cursor that appeared, changed and vanished
+    // while the author was still typing.
     useEffect(() => {
       let live = true;
-      renderRich(ast ?? {}, expressions).then((r) => {
-        if (live) setPreview({ text: r.text, server: r.server });
-      });
+      const timer = setTimeout(() => {
+        renderRich(ast ?? {}, expressions).then((r) => {
+          if (live) setPreview({ text: r.text, server: r.server });
+        });
+      }, PREVIEW_DEBOUNCE_MS);
       return () => {
         live = false;
+        clearTimeout(timer);
       };
     }, [renderRich, ast, expressions]);
 
     // Tracks whether the user has typed since entering Text mode, so a
     // slow seed response can't clobber their input.
     const userTypedRef = useRef(false);
-    const astRef = useRef(ast);
+
+    /* A cleared value must clear the editor with it.
+     *
+     * "Clear value" empties the option (`handleValueChange(name, undefined)`),
+     * but the DPQL text is local state seeded once on entering Text mode, and
+     * the seeding effect returns early for an empty AST — it exists to fill the
+     * editor, not to empty it. So the value went and the text stayed: the row
+     * reported "This field is required" while still showing `1 + 2`, which
+     * reads as the clear having silently failed.
+     *
+     * Only an AST that HAD content and lost it clears the box. A field that
+     * simply starts empty is left alone, so this cannot wipe what an author is
+     * part-way through typing before their first parse lands.
+     */
+    const hadExpression = useRef(false);
     useEffect(() => {
-      astRef.current = ast;
+      /* GONE, not merely incomplete.
+       *
+       * The first cut asked whether the AST still had an `exp`, and that is a
+       * state the value passes THROUGH while the author types: a half-written
+       * expression parses to something without one. So typing `1 + 2` cleared
+       * the editor mid-keystroke and the text vanished under the cursor.
+       *
+       * A clear removes the value itself, so that is what to watch: `value`
+       * empty, not an AST that is between shapes. Typing never produces that —
+       * `handleDpqlChange` only emits on a SUCCESSFUL parse, so an incomplete
+       * expression leaves the previous value in place. */
+      if (ast) {
+        hadExpression.current = true;
+        return;
+      }
+      if (hadExpression.current) {
+        hadExpression.current = false;
+        userTypedRef.current = false;
+        setText('');
+      }
     }, [ast]);
 
     // Text mode: parse the DPQL into the AST (debounced).
+    /* The session may not be attached when the debounce fires — the editor
+       mounts on the render that flips the mode, and its LSP session comes up
+       after that. `dpqlRef.current?.parse?.()` is optional all the way down, so
+       an early call resolves `undefined`, `readTypeCheck` CLEARS the analysis,
+       and nothing asks again: the author types once into a fresh Text field and
+       is told nothing about the type until they happen to type another
+       character.
+
+       The seeding effect below already retries for this exact reason
+       ("`serialize` resolves '' until the editor's LSP session is ready"); the
+       parse path needed the same care and did not have it. Same budget as
+       seeding, so a session that never arrives gives up rather than spinning.
+
+       Found by CI, not locally: the session is up before the debounce on a
+       fast machine, so the story asserting the type message passed here every
+       time and failed on the runner. */
     const handleDpqlChange = useCallback(
       (next: string) => {
         userTypedRef.current = true;
         setText(next);
         if (parseTimer.current) clearTimeout(parseTimer.current);
-        parseTimer.current = setTimeout(async () => {
-          const result = await dpqlRef.current?.parse?.(next);
+        let tries = 0;
+        const runParse = async (): Promise<void> => {
+          const parse = dpqlRef.current?.parse;
+          if (!parse) {
+            if (++tries < SEED_MAX_TRIES) {
+              parseTimer.current = setTimeout(runParse, SEED_RETRY_MS);
+            }
+            return;
+          }
+          const result = await parse(next, targetType);
+          readTypeCheck(result);
           if (result?.success && result.expression) {
+            setAstText(next);
             // `dpql/parse` returns the field-ready `{ is_expression, value }`.
             onChange(result.expression as IExpression);
           }
-        }, PARSE_DEBOUNCE_MS);
+        };
+        parseTimer.current = setTimeout(runParse, PARSE_DEBOUNCE_MS);
       },
-      [onChange]
+      [onChange, targetType, readTypeCheck]
     );
 
-    // Seed the Text editor from the AST whenever Text mode becomes active
-    // (including a `defaultMode='text'` mount). This must run as an
-    // effect: the editor only mounts on the same render that flips the
-    // mode (so `dpqlRef` is null inside the click handler), and
-    // `serialize` resolves '' until the editor's LSP session is ready —
-    // hence the brief retry loop.
+    /** Whether this visit to Text mode has already put the AST in the editor. */
+    const seededRef = useRef(false);
+
+    /* Seed the Text editor from the AST whenever Text mode becomes active
+     * (including a `defaultMode='text'` mount). This must run as an effect: the
+     * editor only mounts on the same render that flips the mode (so `dpqlRef`
+     * is null inside the click handler), and `serialize` resolves '' until the
+     * editor's LSP session is ready — hence the brief retry loop.
+     *
+     * It waits for an AST, because the AST can arrive AFTER the mode does. A
+     * host flips this shell into Text mode on the very render that accepts an
+     * expression, and the value it passes on that render is still the TEXT the
+     * author typed — the parsed AST only comes back through the form one render
+     * later. Keyed on the mode alone, the effect had already had its only turn
+     * by then: it found nothing to serialize, returned, and nothing asked
+     * again. The author landed in an empty editor with a Preview of their own
+     * expression sitting beside it, which reads as the text having been thrown
+     * away.
+     *
+     * Seeding happens at most ONCE per visit, and that is what makes watching
+     * the AST safe: `userTypedRef` guards what is being typed, but the AST
+     * MOVES as the author types — every successful parse replaces it — so an
+     * effect that re-seeded on each new AST would fight them for the editor. */
     useEffect(() => {
-      if (mode !== 'text') return undefined;
-      const seedAst = astRef.current;
-      if (!seedAst?.exp) return undefined;
-      userTypedRef.current = false;
+      if (mode !== 'text') {
+        // Leaving Text asks the question again on the next visit; the typing
+        // flag goes with it, or a stale one would suppress that visit's seed.
+        seededRef.current = false;
+        userTypedRef.current = false;
+        return undefined;
+      }
+      if (seededRef.current || userTypedRef.current) return undefined;
+      if (!ast?.exp) return undefined;
+      const seedAst = ast;
       let cancelled = false;
       let timer: ReturnType<typeof setTimeout> | null = null;
       let tries = 0;
@@ -161,7 +322,9 @@ export const ExpressionField = memo(
         const t = await dpqlRef.current?.serialize?.(seedAst);
         if (cancelled || userTypedRef.current) return;
         if (t) {
+          seededRef.current = true;
           setText(t);
+          setAstText(t);
         } else if (++tries < SEED_MAX_TRIES) {
           timer = setTimeout(seed, SEED_RETRY_MS);
         }
@@ -171,7 +334,7 @@ export const ExpressionField = memo(
         cancelled = true;
         if (timer) clearTimeout(timer);
       };
-    }, [mode]);
+    }, [mode, ast]);
 
     // Switch to Text: the seeding effect above serializes the AST once
     // the editor's session is up.
@@ -183,13 +346,14 @@ export const ExpressionField = memo(
     const enterVisualMode = useCallback(async () => {
       if (parseTimer.current) clearTimeout(parseTimer.current);
       if (mode === 'text' && text) {
-        const result = await dpqlRef.current?.parse?.(text);
+        const result = await dpqlRef.current?.parse?.(text, targetType);
+        readTypeCheck(result);
         if (result?.success && result.expression) {
           onChange(result.expression as IExpression);
         }
       }
       setMode('visual');
-    }, [mode, text, onChange]);
+    }, [mode, text, onChange, targetType, readTypeCheck]);
 
     useEffect(
       () => () => {
@@ -232,11 +396,51 @@ export const ExpressionField = memo(
               readOnly={readOnly}
               height='48px'
             />
-            {/* An empty query has nothing to parse — the box appears once a
-                parse result exists rather than sitting there holding a
-                placeholder token. */}
-            {preview.text ? (
-              <ReqoreMessage intent='info' size='small' title='Parsed' flat opaque={false}>
+            {/* What the server said about the result's type, when the field
+                declares one to check against.
+
+                Nothing is shown when the expression already fits, and nothing
+                is shown when the conversion is CERTAIN either — a number used
+                as text always works, and a warning about something that cannot
+                fail is what teaches people to ignore the ones that can. So this
+                appears for exactly two cases: the conversion is impossible
+                (danger), or it is attempted and may fail on the day (warning,
+                and the run checks the value itself). */}
+            {typeCheck && !typeCheck.compatible && (
+              <ReqoreMessage
+                intent={typeCheck.mayFail ? 'warning' : 'danger'}
+                size='small'
+                flat
+                opaque={false}
+                title={typeCheck.mayFail ? 'This may not fit' : 'This does not fit'}
+              >
+                {`The expression returns ${typeCheck.inferred}, and this field holds ${typeCheck.target}.`}
+                {typeCheck.mayFail ?
+                  ' That conversion is attempted rather than guaranteed, so the value itself is checked when it runs.'
+                : ''}
+                {typeCheck.fix ? (
+                  <div style={{ marginTop: '6px' }}>
+                    <code data-testid='expression-type-fix'>{typeCheck.fix}</code>
+                  </div>
+                ) : null}
+              </ReqoreMessage>
+            )}
+
+            {/* Shown only when it ADDS something.
+
+                It is a rendering of the AST, so for most text it repeats the
+                line directly above it — `1 + 2` previewing as `1 + 2` is a
+                second copy that flickers as you type. It earns the space when
+                the rendering DIFFERS: a template reference resolved to a chip,
+                or a normalised form. Comparison ignores surrounding whitespace,
+                which the renderer does not preserve.
+
+                An empty query has nothing to render either, so the box appears
+                once there is a result rather than holding a placeholder. */}
+            {preview.text &&
+            astText.trim() === text.trim() &&
+            preview.text.trim() !== text.trim() ? (
+              <ReqoreMessage intent='info' size='small' title='Preview' flat opaque={false}>
                 {preview.server ? (
                   // Server rendering shown through a read-only DpqlEditor:
                   // template-ref chips + LSP token colours; diagnostics off
@@ -268,6 +472,7 @@ export const ExpressionField = memo(
             readOnly={readOnly}
             localTemplates={localTemplates ?? { items: [] }}
             serverHandled={serverHandled}
+            componentOverrides={componentOverrides}
             extraActions={extraActions}
             size={size}
             reorder={reorder}

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

@@ -0,0 +1,200 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * Is this expression argument SUPPLIED, or is it still missing?
+ *
+ * DPQL has a null literal: `null` parses to `{exp: "value", args: [null]}` and
+ * round-trips, and an author writing it in the text editor means *"this is the
+ * value — nothing"*. It is the only way to assert that a call returned no
+ * value, which is how it was reported.
+ *
+ * The rule, stated once here because three different places had drawn it
+ * differently: **an argument that is explicitly null is supplied; one that is
+ * absent or `undefined` is still missing.**
+ *
+ * The builder used to ask `size(arg) === 0`, and lodash answers `0` for `null`
+ * as readily as for `{}`. So an explicit null was read as a missing argument
+ * and reset from the catalogue's declaration — which is how a saved draft ended
+ * up holding `{"type": "any", "required": true}`, an argument DEFINITION where
+ * its value should be, with the author's `null` gone and `required` (a schema
+ * key, never a value key) left behind to give it away.
+ */
+
+/**
+ * True when `arg` carries no value yet — `undefined`, the `{}` the builder
+ * writes when a type change resets an argument, or any envelope with no
+ * `value` in it.
+ *
+ * `null` is NOT missing: it is the null literal.
+ *
+ * The rule used to be "an object with no keys at all", which let an envelope
+ * holding nothing but SCHEMA keys pass as a supplied value. That is how a saved
+ * draft kept `{type: 'any', required: true}` — an argument DEFINITION where the
+ * author's value belonged — and why re-opening the expression never repaired
+ * it: the builder looked at those two keys, concluded the argument was already
+ * supplied, and left the definition in place as data. `required` is a schema
+ * key; nothing ever reads it back off a stored value.
+ *
+ * Asking for the `value` instead makes the question the one that was always
+ * meant: has the author put something here?
+ *
+ * @param arg one entry of an expression's `args`
+ */
+export const isExpressionArgumentMissing = (arg: unknown): boolean => {
+  if (arg === null) {
+    return false;
+  }
+
+  if (arg === undefined) {
+    return true;
+  }
+
+  if (typeof arg !== 'object') {
+    // a raw scalar argument — `0`, `false` and `''` are values too
+    return false;
+  }
+
+  return (arg as { value?: unknown }).value === undefined;
+};
+
+/**
+ * The shape the builder stores an argument in: `{type, value}`.
+ *
+ * A parse result carries its arguments RAW — `args: [null]`, `args: [3]` —
+ * because that is what the grammar produced. The builder's editors read
+ * `arg.value`, so a raw argument has to be widened before it is stored, and
+ * widening `null` is the whole point: dropped instead, the author's null
+ * becomes an argument with no `value` key at all, which every later reader
+ * treats as an empty field.
+ *
+ * An argument that is already an envelope is returned untouched.
+ *
+ * @param arg one entry of an expression's `args`
+ * @param uiType the type the catalogue declares for that position
+ */
+export const asExpressionArgumentEnvelope = (arg: unknown, uiType?: string): unknown => {
+  if (arg !== null && (arg === undefined || typeof arg === 'object')) {
+    return arg;
+  }
+
+  return { value: arg, ...(uiType ? { type: uiType } : {}) };
+};
+
+/**
+ * Does this value still look like an expression AST?
+ *
+ * `{exp, args}` is the shape the builder and `dpql/parse` both produce. The
+ * check is structural on purpose: the flag that marks an option as holding an
+ * expression describes its VALUE, so the value is what should decide whether
+ * the flag survives a change that said nothing about it.
+ */
+export const looksLikeExpressionAst = (value: unknown): boolean =>
+  !!value &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  typeof (value as { exp?: unknown }).exp === 'string';
+
+/**
+ * Whether an option should still be marked as holding an expression.
+ *
+ * The form engine used to delete the flag on ANY change that did not re-assert
+ * it, and most changes do not: an editor re-mounting, a revert, a validation
+ * pass. The value stayed the AST while the flag went, so the option degraded
+ * into a plain hash — which is how an assertion's Expected Value came back
+ * from a saved draft as a two-field object showing `exp` and `args`, and why
+ * `encodeTestValue` then stored it with `source: "literal"`.
+ *
+ * @param isFunction what the caller said: `true` sets the flag, `false` clears
+ * it deliberately (choosing a concrete type does this), `undefined` is no
+ * opinion at all
+ * @param value the option's new value
+ * @param wasExpression whether the option was marked before this change
+ */
+export const shouldMarkAsExpression = (
+  isFunction: boolean | undefined,
+  value: unknown,
+  wasExpression: boolean | undefined
+): boolean => {
+  if (isFunction === true) {
+    return true;
+  }
+
+  if (isFunction === false) {
+    return false;
+  }
+
+  // No opinion: the flag belongs to the value, so it survives exactly as long
+  // as the value is still an expression.
+  return !!wasExpression && looksLikeExpressionAst(value);
+};
+
+/**
+ * Fill in an expression's missing arguments, leaving the supplied ones alone.
+ *
+ * Extracted from the builder so the decision it makes can be tested directly:
+ * a component test of the same behaviour passed just as happily with the defect
+ * in place, because the builder normalises on an interaction the harness never
+ * performed. A test that cannot fail is worse than none.
+ *
+ * @param expressions the served expression catalogue
+ * @param expression the chosen expression's `name`
+ * @param args the arguments so far — raw from a parse, or envelopes from the
+ * builder's own editors
+ */
+export const addMissingExpressionArgs = (
+  expressions: any[] | undefined,
+  expression: string,
+  args: any[] = []
+): any[] => {
+  const newArgs = [...args];
+  const selected = expressions?.find((exp) => exp?.name === expression);
+
+  if (!selected) {
+    return newArgs;
+  }
+
+  if (selected.varargs) {
+    if (selected.subtype === 2) {
+      newArgs.push({ is_expression: true, value: { args: [] } });
+    } else {
+      newArgs.push(
+        ...Array.from({ length: (selected.min_args ?? 1) - 1 }, () => ({
+          type:
+            selected.args[0].ui_type === 'richtext' || selected.args[0].ui_type === 'number'
+              ? selected.args[0].ui_type
+              : undefined,
+        }))
+      );
+    }
+
+    return newArgs;
+  }
+
+  selected.args.forEach((arg: any, index: number) => {
+    /* A RAW argument, as `dpql/parse` produces it — `args: [null]`, `args: [3]`
+       — is widened into the `{type, value}` envelope the editors read. Widening
+       the null is the point: dropped instead, the author's `null` became an
+       argument with no `value` key, and the branch below then filled the gap
+       from the catalogue's DECLARATION, which is how a saved draft came back
+       holding `{type: "any", required: true}` where its value belonged. */
+    newArgs[index] = asExpressionArgumentEnvelope(newArgs[index], arg.ui_type);
+
+    /* "Missing" already means "carries no value", so an argument waiting for
+       its catalogue default is simply a missing one — it needs no separate
+       test. */
+    if (!isExpressionArgumentMissing(newArgs[index])) {
+      return;
+    }
+
+    newArgs[index] =
+      arg.default_value ?
+        { value: arg.default_value, type: arg.ui_type }
+      : {
+          type:
+            arg.ui_type === 'richtext' || arg.ui_type === 'number' || arg.ui_type === 'bool' ?
+              arg.ui_type
+            : undefined,
+        };
+  });
+
+  return newArgs;
+};

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

@@ -49,9 +49,15 @@ export const ExpressionBuilderArgumentLabel = ({
     ...types.getExactMatches(schema.ui_type),
     ...types.getAcceptedTypes(schema.ui_type),
   ]);
-  const { isValid, reason } = arg.is_expression
-    ? validateFieldWithResult('expression', arg, { expressions })
-    : validateFieldWithResult(argumentType, arg.value, schema, !schema.required);
+  /* `arg` is optional — an operand the author has not filled in yet has no
+     entry at all, and a literal carried straight from a parse can be the null
+     literal itself. Both were dereferenced unguarded here, which took the whole
+     expression editor down to its error boundary rather than drawing an empty
+     argument. */
+  const { isValid, reason } =
+    arg?.is_expression ?
+      validateFieldWithResult('expression', arg, { expressions })
+    : validateFieldWithResult(argumentType, arg?.value, schema, !schema.required);
 
   return (
     <ReqoreP
@@ -94,7 +100,7 @@ export const ExpressionBuilderArgumentLabel = ({
       {!matchesType ? (
         <ReqoreIcon icon='ErrorWarningLine' color='warning' size='10px' margin='both' />
       ) : null}
-      {(argumentType || (arg.is_expression && arg.value?.exp)) &&
+      {(argumentType || (arg?.is_expression && arg.value?.exp)) &&
       types.getTypeDisplayName(argumentType) !== types.getTypeDisplayName(schema.ui_type) &&
       !matchesTypeExactly ? (
         <>