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

package/src/components/form/fields/template/writtenAsText.ts

@@ -0,0 +1,217 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// What a field holds for the text written in its template editor.
+//
+// A field that takes templates and custom values shows ONE editor for both: a text
+// field where a chosen template is a chip, with text typed around it (qorus#646). The
+// field's value is read from that text:
+//
+// - a template standing alone is that template - in an untyped field, of the
+//   template's own type (a whole-number field of the record makes the value a whole
+//   number);
+// - a literal of a scalar field's type (`12` in a whole-number field, `true` in a
+//   yes/no one) is that literal;
+// - null in an untyped field is written `null` (an empty field holds no value at all);
+// - anything else is text: an untyped field's value becomes text, a typed field holds
+//   what was written and says it does not fit (an expression in it is detected and
+//   offered, or switched to, by the field's DPQL detection).
+//
+// Deleting the text around a template makes it a lone template again, and the value
+// takes the template's type again. Pure: no React, no transport.
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { isUntypedOptionType } from '../../../../helpers/optionUiTypes';
+import {
+  findTemplate,
+  isCompleteTemplateToken,
+  isValueTemplate,
+  TEMPLATE_TOKEN_SOURCE,
+} from '../../../../helpers/templates';
+
+/** Scalar types whose value can be written as text: whole numbers, numbers, yes/no. Not a date, which has
+ *  its own control. */
+const TEXTABLE_SCALARS: Record<string, 'int' | 'number' | 'bool'> = {
+  int: 'int',
+  integer: 'int',
+  softint: 'int',
+  number: 'number',
+  float: 'number',
+  softfloat: 'number',
+  softnumber: 'number',
+  bool: 'bool',
+  boolean: 'bool',
+  softbool: 'bool',
+};
+
+/** Whether a field of this type is written in the template editor: text, untyped, or a textable scalar. */
+export const isWrittenAsText = (type?: string): boolean =>
+  type === 'string' || isUntypedOptionType(type) || (!!type && type in TEXTABLE_SCALARS);
+
+/**
+ * Whether a form option of this type is written as text on its Value tab - a text field taking templates as
+ * chips and detecting expressions - rather than on its own control (qorus#646, David): text, untyped values,
+ * whole numbers and numbers. A yes / no, a date and fixed choices keep their own control.
+ */
+export const isWrittenAsTextOnTheValueTab = (type?: string): boolean =>
+  type === 'string' ||
+  isUntypedOptionType(type) ||
+  (!!type && (TEXTABLE_SCALARS[type] === 'int' || TEXTABLE_SCALARS[type] === 'number'));
+
+/** The tabs a field's value is entered on (see `valueTabsOf`). */
+export type TValueTab = 'value' | 'expression' | 'visual' | 'template';
+
+/**
+ * The text a value shows as on the Value tab: text as it is, a number or a yes/no as written, null as
+ * `null` (in an untyped field), nothing for no value.
+ */
+export const valueTextOf = (value: unknown, type?: string): string => {
+  if (value === undefined) return '';
+  if (value === null) return isUntypedOptionType(type) ? NULL_TEXT : '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return '';
+};
+
+/**
+ * A value written as an expression's text: a literal as DPQL writes it (`12`, `true`, `"open"`), a template
+ * as itself, text with templates as the text and the templates joined (`concat("SUP-", $record:{pos})`).
+ * The Expression tab opens on this for a value that is not an expression yet.
+ */
+export const expressionTextOfValue = (value: unknown): string => {
+  if (value === undefined || value === null) return value === null ? 'null' : '';
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (typeof value !== 'string') return '';
+  const text = String(value);
+  if (isCompleteTemplateToken(text)) return String(text);
+  const plain: string = text;
+  const parts = plain.split(new RegExp(`(${TEMPLATE_TOKEN_SOURCE})`)).filter((part) => part !== '');
+  if (parts.length === 1) return JSON.stringify(plain);
+  return `concat(${parts.map((part) => (isCompleteTemplateToken(part) ? part : JSON.stringify(part))).join(', ')})`;
+};
+
+/**
+ * A lone template written in the expression editor's Text view, as the server parses it: the `template`
+ * operation with the reference as its one argument. It is stored as the bare template, which every consumer
+ * evaluates; the expression form of it is not one the server reads back as the template's value.
+ */
+export const loneTemplateOf = (expression: unknown): string | undefined => {
+  const node = (expression as { value?: { exp?: string; args?: unknown[] } } | undefined)?.value;
+  if (node?.exp !== 'template' || node.args?.length !== 1) return undefined;
+  const arg = node.args[0] as { value?: { raw?: unknown } | string } | undefined;
+  const raw = typeof arg?.value === 'string' ? arg.value : arg?.value?.raw;
+  return typeof raw === 'string' && isCompleteTemplateToken(raw) ? raw : undefined;
+};
+
+/**
+ * A lone value written in the expression editor's Text view (`12`, `true`, `"open"`), as the server parses
+ * it: the `value` operation with a plain value as its one argument. It is stored as that value - the field's
+ * own shape - rather than as an expression the Visual view has nothing to show for. A record field is not
+ * such a value: it is read from the row.
+ */
+export const loneValueOf = (expression: unknown): { value: unknown } | undefined => {
+  const node = (expression as { value?: { exp?: string; args?: unknown[] } } | undefined)?.value;
+  if (node?.exp !== 'value' || node.args?.length !== 1) return undefined;
+  const arg = node.args[0] as { value?: unknown; is_expression?: boolean } | undefined;
+  const value = arg?.value;
+  if (!arg || arg.is_expression || (value !== null && typeof value === 'object')) return undefined;
+  if (typeof value === 'string' && isValueTemplate(value)) return undefined;
+  return { value };
+};
+
+/** The text a value is seeded into the Text view as: a template, a number or a yes/no as written. */
+export const expressionSeedOf = (value: unknown): string => {
+  if (typeof value === 'string') return isCompleteTemplateToken(value) ? value : '';
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return '';
+};
+
+const INT_LITERAL = /^\s*[-+]?\d+\s*$/;
+const NUMBER_LITERAL = /^\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?\s*$/i;
+const BOOL_LITERAL = /^\s*(true|false)\s*$/i;
+
+/** The literal `text` writes in a scalar type, or `undefined` when it writes none. */
+export const scalarLiteral = (text: string, type?: string): number | boolean | undefined => {
+  switch (type ? TEXTABLE_SCALARS[type] : undefined) {
+    case 'int':
+      return INT_LITERAL.test(text) ? Number.parseInt(text, 10) : undefined;
+    case 'number':
+      return NUMBER_LITERAL.test(text) ? Number.parseFloat(text) : undefined;
+    case 'bool': {
+      const match = BOOL_LITERAL.exec(text);
+      return match ? match[1].toLowerCase() === 'true' : undefined;
+    }
+    default:
+      return undefined;
+  }
+};
+
+/** How null is written in an untyped field: the word, so it is not taken for an empty field. */
+export const NULL_TEXT = 'null';
+
+/** The text an untyped field shows for its value: `null` for null; for anything else, the text it is. */
+export const untypedTextOf = (value: unknown, type?: string): string | undefined =>
+  value === null && isUntypedOptionType(type) ? NULL_TEXT : undefined;
+
+export interface ITemplateTextValue {
+  value: unknown;
+  /** the value's type: the field's own, or for an untyped field the type the text gives it */
+  type?: string;
+}
+
+/** What the field holds for `text`, written in its template editor. See the top of this file. */
+export const templateTextValue = (
+  text: string,
+  type: string | undefined,
+  templates?: IReqoreFormTemplates
+): ITemplateTextValue => {
+  const trimmed = text.trim();
+  if (isCompleteTemplateToken(trimmed)) {
+    if (isUntypedOptionType(type)) {
+      const badge = templates ? findTemplate(templates, trimmed)?.badge : undefined;
+      return { value: trimmed, type: typeof badge === 'string' && badge ? badge : type };
+    }
+    return { value: trimmed, type };
+  }
+  // null, the literal that says "no value", is a value of an untyped field: written `null`, it is null
+  if (isUntypedOptionType(type) && trimmed === NULL_TEXT) {
+    return { value: null, type };
+  }
+  const literal = scalarLiteral(text, type);
+  if (literal !== undefined) {
+    return { value: literal, type };
+  }
+  return { value: text, type: isUntypedOptionType(type) ? 'string' : type };
+};
+
+/** The kind of value a type holds, for telling whether a template and a field hold the same kind. */
+const valueKindOf = (type?: string): string | undefined => {
+  if (!type) return undefined;
+  const t = type.replace(/^\*/, '').replace(/^soft/, '');
+  if (TEXTABLE_SCALARS[t]) return TEXTABLE_SCALARS[t];
+  if (t === 'string' || t === 'date' || t === 'list' || t === 'hash' || t === 'binary') return t;
+  return undefined;
+};
+
+/** Whether a template of this type is a value of the field's type as it is, with nothing to convert. */
+export const sameValueType = (templateType: string, fieldType?: string): boolean => {
+  const a = valueKindOf(templateType);
+  const b = valueKindOf(fieldType);
+  // a whole number is a number too
+  return !a || !b || a === b || (a === 'int' && b === 'number');
+};
+
+/** A type in words: "a whole number", "text". */
+export const templateTypeName = (type?: string): string => {
+  switch (valueKindOf(type)) {
+    case 'int':
+      return 'A whole number';
+    case 'number':
+      return 'A number';
+    case 'bool':
+      return 'A yes / no value';
+    case 'string':
+      return 'Text';
+    case 'date':
+      return 'A date';
+    default:
+      return type ?? 'A value';
+  }
+};

package/src/components/form/index.tsx

@@ -35,6 +35,12 @@ export * from './expressions/useExpressions';
 // Named (not wildcard) so the `_resetRenderExpressionTransportForTests`
 // test hook stays out of the public package surface.
 export { renderExpressionToText, useRenderExpression } from './expressions/useRenderExpression';
+export {
+  expressionOperand,
+  expressionWithOperands,
+  isExpressionComplete,
+} from './expressions/expressionOperands';
+export { EXPRESSION_HOLE } from './expressions/renderExpressionToText';
 export type {
   IRenderedExpression,
   IUseRenderExpressionResult,

package/src/components/smartEditor/useLspSession.ts

@@ -40,6 +40,12 @@ export interface IUseLspSessionResult {
   uri: string;
   /** Becomes `true` once `initialize` + `didOpen` complete. */
   isReady: boolean;
+  /**
+   * `true` once connecting has FAILED: there is no language server to talk to (none configured, or it
+   * cannot be reached). A host that needs one - the expression editor's Text view - shows what works
+   * without it instead of waiting on a session that is not coming.
+   */
+  isUnavailable: boolean;
   /**
    * Becomes `true` once any language-specific context binding the
    * wrapper requires has resolved. For the generic primitive session
@@ -93,9 +99,7 @@ export interface IUseLspSessionResult {
   format: () => Promise<string | null>;
 }
 
-export function useLspSession(
-  options: IUseLspSessionOptions
-): IUseLspSessionResult {
+export function useLspSession(options: IUseLspSessionOptions): IUseLspSessionResult {
   const { languageId, uri: uriProp, initialMetadata, url, initialText = '' } = options;
 
   const clientRef = useRef<ReqraftLspClient | null>(null);
@@ -111,11 +115,12 @@ export function useLspSession(
 
   const [client, setClient] = useState<ReqraftLspClient | null>(null);
   const [isReady, setIsReady] = useState(false);
+  const [isUnavailable, setIsUnavailable] = useState(false);
   const [diagnostics, setDiagnostics] = useState<ILspDiagnostic[]>([]);
-  const [semanticTokensLegend, setSemanticTokensLegend] =
-    useState<ILspSemanticTokensLegend | null>(null);
-  const [capabilities, setCapabilities] =
-    useState<ILspServerCapabilities | null>(null);
+  const [semanticTokensLegend, setSemanticTokensLegend] = useState<ILspSemanticTokensLegend | null>(
+    null
+  );
+  const [capabilities, setCapabilities] = useState<ILspServerCapabilities | null>(null);
 
   useEffect(() => {
     const c = new ReqraftLspClient({
@@ -147,9 +152,7 @@ export function useLspSession(
         serverTextRef.current = editorTextRef.current;
         c.didOpen(
           editorTextRef.current,
-          initialMetadata && Object.keys(initialMetadata).length > 0
-            ? initialMetadata
-            : undefined
+          initialMetadata && Object.keys(initialMetadata).length > 0 ? initialMetadata : undefined
         );
         setIsReady(true);
       })
@@ -162,6 +165,7 @@ export function useLspSession(
         // eslint-disable-next-line no-console
         console.error('[LSP session] Connect failed:', err);
         setIsReady(false);
+        setIsUnavailable(true);
       });
 
     return () => {
@@ -217,6 +221,7 @@ export function useLspSession(
     client,
     uri: uriRef.current,
     isReady,
+    isUnavailable,
     // Generic session has no language-specific context to bind;
     // wrappers (`useDpqlSession`) override this on their returned
     // session by spreading + replacing.

package/src/helpers/templates.ts

@@ -94,6 +94,41 @@ const COMPLETE_TEMPLATE_TOKEN = new RegExp(`^${TEMPLATE_TOKEN_SOURCE}$`);
 export const isCompleteTemplateToken = (value?: unknown): value is string =>
   typeof value === 'string' && COMPLETE_TEMPLATE_TOKEN.test(value);
 
+const TEMPLATE_TOKEN_ANYWHERE = new RegExp(TEMPLATE_TOKEN_SOURCE);
+
+/**
+ * Text with a template in it that is not the template alone: `$record:{pos} Stk.`, `SUP-$record:{pos}`,
+ * two templates side by side. In text it is text; a whole number, a number, a yes/no or a date cannot
+ * hold it (qorus#646).
+ */
+export const hasTextAroundATemplate = (value?: unknown): value is string =>
+  typeof value === 'string' && TEMPLATE_TOKEN_ANYWHERE.test(value) && !isCompleteTemplateToken(value);
+
+/** The text around the templates in a value that is not one template alone, and how many templates it holds. */
+export interface ITextAroundATemplate {
+  /** The pieces of text before, between and after the templates, trimmed; empty pieces left out. */
+  text: string[];
+  templates: number;
+}
+
+/**
+ * What makes a value text rather than one template alone: `$record:{pos} Stk.` holds the text "Stk." and
+ * one template; `$record:{a}$record:{b}` no text and two. `undefined` where the value is not text with a
+ * template in it, or is one template alone (see {@link hasTextAroundATemplate}).
+ */
+export const textAroundATemplate = (value?: unknown): ITextAroundATemplate | undefined => {
+  if (!hasTextAroundATemplate(value)) {
+    return undefined;
+  }
+  const tokens = new RegExp(TEMPLATE_TOKEN_SOURCE, 'g');
+  const templates = value.match(tokens)?.length ?? 0;
+  const text = value
+    .split(tokens)
+    .map((piece) => piece.trim())
+    .filter((piece) => piece !== '');
+  return { text, templates };
+};
+
 /** A complete token carrying at least one BRACED context segment —
  *  `$data:{W2n….filename}`, `$qore-expr:{1 + 2}`. These are machine-written
  *  references nobody types by hand, so a surface may render them as a picker

package/src/helpers/validations.ts

@@ -2,7 +2,7 @@ import { isValidSixCharHex } from '@qoretechnologies/reqore/dist/helpers/colors'
 import { IQorusFormSchema, TQorusForm, TQorusFormFieldSchema } from '@qoretechnologies/ts-toolkit';
 import { isValidCron } from 'cron-validator';
 import jsyaml from 'js-yaml';
-import { isBoolean, isNull, isString, isUndefined, memoize, omit } from 'lodash';
+import { isBoolean, isNull, isString, isUndefined, memoize, omit, upperFirst } from 'lodash';
 import every from 'lodash/every';
 import isArray from 'lodash/isArray';
 import isDate from 'lodash/isDate';
@@ -15,7 +15,7 @@ import { fixOperatorValue, getAddress, getProtocol, splitByteSize } from './comm
 import { isOptionInterfaceUiType } from './optionUiTypes';
 import { getListElementValue, getOptionsFromRequiredGroups } from './options';
 import { IProviderType, TVariableActionValue, maybeBuildOptionProvider } from './providerValue';
-import { getTemplateKey, getTemplateValue, isValueTemplate } from './templates';
+import { getTemplateKey, getTemplateValue, isValueTemplate, textAroundATemplate } from './templates';
 import { getUnlistedChoiceReason } from './allowedValues';
 
 /** The five cron fields, in order, as a schedule hash may name them. */
@@ -244,6 +244,56 @@ const isValueDefined = (type: string, value: any): boolean => {
   return value !== undefined && value !== '';
 };
 
+/** What a value of each type that is not text is called, where text around a template makes it text. */
+const TEXT_AROUND_A_TEMPLATE_NOT_A: Record<string, string> = (() => {
+  const wholeNumber = 'a whole number';
+  const number = 'a number';
+  const yesNo = 'true or false';
+  const date = 'a date';
+  return {
+    int: wholeNumber,
+    integer: wholeNumber,
+    softint: wholeNumber,
+    number,
+    float: number,
+    softfloat: number,
+    softnumber: number,
+    bool: yesNo,
+    boolean: yesNo,
+    softbool: yesNo,
+    date,
+    softdate: date,
+  };
+})();
+
+/**
+ * What is said of a value of a type that is not text, written with text around a template: what makes it
+ * text, and what to do about it (qlip build 20261008-083118: "How does the user fix this? Why has this
+ * happened?"). `undefined` where the type is text, or the value is not text around a template.
+ */
+const textAroundATemplateReason = (type: string, value: unknown): string | undefined => {
+  const notA = TEXT_AROUND_A_TEMPLATE_NOT_A[type];
+  const around = notA ? textAroundATemplate(value) : undefined;
+  if (!around) {
+    return undefined;
+  }
+  if (around.templates > 1) {
+    return around.text.length
+      ? `Text and more than one template make this text, not ${notA}. Keep one template alone.`
+      : `Templates side by side make this text, not ${notA}. Keep one of them alone.`;
+  }
+  return `"${around.text.join(' … ')}" makes this text, not ${notA}. Delete it to keep the template alone.`;
+};
+
+/** 1st, 2nd, 3rd, 4th, … 11th, 12th, 13th, … 21st: a position as it is written. */
+const ordinal = (n: number): string => {
+  const tens = n % 100;
+  if (tens >= 11 && tens <= 13) {
+    return `${n}th`;
+  }
+  return `${n}${({ 1: 'st', 2: 'nd', 3: 'rd' } as Record<number, string>)[n % 10] ?? 'th'}`;
+};
+
 export const _validateField = (
   type: string,
   value?: any,
@@ -272,6 +322,14 @@ export const _validateField = (
   if (pos > 0) {
     type = type.slice(0, pos);
   }
+  /* A value whose type is not text, written with text around a template, is not of that type: a whole
+     number written as "$record:{pos} Stk." passed as a template - anything starting with `$` and holding
+     a `:` did - and the form could be saved with a value its type cannot hold (qorus#646). A template
+     alone, a literal and an expression are judged as before. */
+  const textAroundReason = textAroundATemplateReason(type, value);
+  if (textAroundReason) {
+    return invalidResult(textAroundReason);
+  }
   // Check if the value is a template string
   if (isValueTemplate(value)) {
     const hasKey = !!getTemplateKey(value);
@@ -1617,6 +1675,14 @@ export const _validateField = (
       // Now we need to validate each argument, either as a normal value or as a sub-expression
       const args = castedValue.value?.args ?? [];
 
+      // each operand's name, as the editor shows it
+      const argLabels: string[] = args.map((_arg: unknown, index: number) => {
+        const definition = expressionDefinition.varargs
+          ? expressionDefinition.args[0]
+          : expressionDefinition.args[index];
+        return definition?.display_name ?? definition?.name ?? `argument ${index + 1}`;
+      });
+
       for (let index = 0; index < args.length; index++) {
         const argValue: any = args[index];
         const argDefinition = expressionDefinition.varargs
@@ -1627,8 +1693,13 @@ export const _validateField = (
            `display_name` is what a catalogue MAY carry; the served one carries
            `name`, so every message about an argument read "argument 1
            ("undefined") is invalid" and named a field that does not exist. */
-        const argLabel =
-          argDefinition?.display_name ?? argDefinition?.name ?? `argument ${index + 1}`;
+        const argLabel = argLabels[index];
+        /* Which operand, where its name alone does not say: every operand of a call taking any number of
+           them is "Value" (qlip build 20261008-083118: "which "value" is the message mentioning"). Said by
+           its position too, as the editor shows them, left to right. */
+        const operand = argLabels.some((label, other) => other !== index && label === argLabel)
+          ? `the ${ordinal(index + 1)} "${argLabel}"`
+          : undefined;
 
         /* An explicit null is a VALUE, and DPQL says so: `null` is a literal
            that parses, serializes and round-trips like any other.
@@ -1659,10 +1730,8 @@ export const _validateField = (
           });
 
           if (!result.isValid) {
-            return withContext(
-              result,
-              `Sub-expression for argument ${index + 1} ("${argLabel}") is invalid`
-            );
+            // said by the operand's name, as the editor shows it - not by its position in the call
+            return withContext(result, `The expression in ${operand ?? `"${argLabel}"`} is invalid`);
           }
 
           continue;
@@ -1686,10 +1755,12 @@ export const _validateField = (
         });
 
         if (!result.isValid) {
-          return withContext(
-            result,
-            `Value for argument ${index + 1} ("${argLabel}") is invalid`
-          );
+          // an operand not filled in yet says what to do; one that is wrong says which and why (David's
+          // review of qorus#646: "Value for argument 1 ("Value") is invalid: Missing value" while building)
+          if (argValue?.value === undefined || argValue?.value === null || argValue?.value === '') {
+            return invalidResult(operand ? `Enter ${operand}` : `Enter a value for "${argLabel}"`);
+          }
+          return withContext(result, operand ? `${upperFirst(operand)} is invalid` : `"${argLabel}" is invalid`);
         }
       }