@qoretechnologies/reqraft 0.10.54 → 0.10.55-pr.115.g37abdfc

package/src/components/dpqlEditor/dpqlProbe.ts

@@ -0,0 +1,165 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * One shared, lazily-opened DPQL document used to ask the server "is this
+ * text really an expression?" on behalf of plain form fields that have no
+ * editor of their own.
+ *
+ * ## Why a singleton, and why it is cheap
+ *
+ * `ReqraftLspClient` multiplexes every document over ONE socket per endpoint
+ * (`LspSharedConnection`), and `initialize` runs once for that socket. A
+ * probe is therefore not a new connection — it is one extra `didOpen`, and
+ * one `QorusDpqlActionSession` in the server's `uriToDpqlSession` map. Even
+ * so it is a single shared document rather than one per field: a form with
+ * forty expression-capable options would otherwise open forty of them to ask
+ * the same question.
+ *
+ * Nothing is opened until a field actually probes, so a form whose author
+ * never types anything expression-shaped costs nothing at all.
+ *
+ * The document is opened with NO provider context. Verified against the live
+ * server: `textDocument/didOpen` with `languageId: 'dpql'` and no metadata
+ * still builds a session, and `dpql/parse` answers on it. Record-field
+ * references (`@name`) do not resolve to a provider's fields without that
+ * context, which is fine — detection asks about the SHAPE of the expression,
+ * and the editor the author lands in binds the real context.
+ *
+ * No `target_type` is sent. Detection asks "is this an expression", not "is
+ * it the right type"; a type mismatch is a thing to show the author INSIDE
+ * the expression editor, not a reason to refuse to open it.
+ */
+import { ReqraftLspClient } from '../../utils/lspClient';
+
+/** What a probe answers. Never throws — a failure is `success: false`. */
+export interface IDpqlProbeResult {
+  success: boolean;
+  expression: Record<string, any> | null;
+  diagnostics: Array<{ severity?: number | string; message?: string; code?: string | number }>;
+}
+
+const FAILED: IDpqlProbeResult = { success: false, expression: null, diagnostics: [] };
+
+/** Opaque, non-secret document URI — the server keys its session by this. */
+const PROBE_URI = 'dpql://probe/detection';
+
+/**
+ * How many parsed texts to remember. Typing walks through many prefixes of
+ * the same expression, and an author re-typing a value should not re-ask.
+ */
+const MAX_CACHE_ENTRIES = 200;
+
+class DpqlProbe {
+  private client: ReqraftLspClient | null = null;
+  private opened: Promise<ReqraftLspClient> | null = null;
+  private users = 0;
+  private readonly cache = new Map<string, IDpqlProbeResult>();
+
+  /** Register a consumer; the document is still not opened until it probes. */
+  acquire(): void {
+    this.users += 1;
+  }
+
+  /** Drop a consumer, closing the shared document when the last one goes. */
+  release(): void {
+    this.users = Math.max(0, this.users - 1);
+
+    if (this.users === 0) {
+      this.close();
+    }
+  }
+
+  /**
+   * Parse `text` on the shared probe document. Resolves to `FAILED` rather
+   * than rejecting, for any reason at all — a field must never break because
+   * the instance is unreachable.
+   */
+  async parse(text: string): Promise<IDpqlProbeResult> {
+    const cached = this.cache.get(text);
+
+    if (cached) {
+      return cached;
+    }
+
+    let result = FAILED;
+
+    try {
+      const client = await this.open();
+      const response = await client.customRequest<Partial<IDpqlProbeResult>>('dpql/parse', {
+        uri: PROBE_URI,
+        text,
+      });
+
+      result = {
+        success: response?.success ?? false,
+        expression: response?.expression ?? null,
+        diagnostics: response?.diagnostics ?? [],
+      };
+    } catch {
+      // Unreachable instance, closed socket, request timeout: the field
+      // simply learns nothing and leaves the typed text exactly as it is.
+      result = FAILED;
+    }
+
+    this.remember(text, result);
+
+    return result;
+  }
+
+  /** Open (once) and return the shared document's client. */
+  private open(): Promise<ReqraftLspClient> {
+    if (this.opened) {
+      return this.opened;
+    }
+
+    this.opened = (async (): Promise<ReqraftLspClient> => {
+      const client = new ReqraftLspClient({ languageId: 'dpql', uri: PROBE_URI });
+
+      await client.connect();
+      // `didOpen` is a notification on the same socket as the request that
+      // follows it, so the server has the session by the time the parse
+      // arrives — no readiness poll needed.
+      client.didOpen('');
+      this.client = client;
+
+      return client;
+    })().catch((error) => {
+      // Allow a later probe to retry a connection that failed once.
+      this.opened = null;
+      throw error;
+    });
+
+    return this.opened;
+  }
+
+  private remember(text: string, result: IDpqlProbeResult): void {
+    if (this.cache.size >= MAX_CACHE_ENTRIES) {
+      const oldest = this.cache.keys().next();
+
+      if (!oldest.done) {
+        this.cache.delete(oldest.value);
+      }
+    }
+
+    this.cache.set(text, result);
+  }
+
+  private close(): void {
+    const client = this.client;
+
+    this.client = null;
+    this.opened = null;
+    this.cache.clear();
+
+    try {
+      client?.disconnect();
+    } catch {
+      // best-effort teardown
+    }
+  }
+}
+
+/**
+ * The process-wide probe. Exported for tests, which reset it between cases;
+ * application code goes through `useDpqlProbe`.
+ */
+export const dpqlProbe = new DpqlProbe();

package/src/components/dpqlEditor/dpqlTags.ts

@@ -3,6 +3,8 @@
 // `getTagProps` callback for ReqoreRichTextEditor.
 
 import { IReqoreTagProps } from '@qoretechnologies/reqore/dist/components/Tag';
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { describeTemplateReference, templateTooltip } from '../../helpers/templates';
 import { ISlateElement } from '../smartEditor/types';
 import { IDpqlFieldMeta } from './useDpqlSession';
 
@@ -55,6 +57,13 @@ export interface IDpqlTagRendererOptions {
    * keeps the per-prefix palette for telling prefixes apart at a glance.
    */
   templateTagsUseIntent?: boolean;
+  /**
+   * The template catalogue the surface offers. A reference found in it reads
+   * as the name it was chosen by — `trim(Choices[0].message.content)` rather
+   * than the `$data:{…}` path — with the entry's description as its hover; one
+   * that is not found keeps its path.
+   */
+  templates?: IReqoreFormTemplates;
 }
 
 /**
@@ -88,8 +97,12 @@ export function makeDpqlTagRenderer(
     }
 
     if (tagValue.startsWith('$')) {
+      const named = options.templates && describeTemplateReference(options.templates, tagValue);
       return {
         icon: 'ExchangeDollarLine',
+        ...(named?.item ?
+          { label: named.label, tooltip: templateTooltip(options.templates, tagValue) }
+        : {}),
         ...(options.templateTagsUseIntent
           ? { intent: 'info' as const }
           : { color: getTemplatePrefixColor(tagValue) as `#${string}` }),

package/src/components/dpqlEditor/index.ts

@@ -10,6 +10,10 @@ export type {
   ISlateText,
   TSlateNode,
 } from './types';
+export { dpqlProbe } from './dpqlProbe';
+export type { IDpqlProbeResult } from './dpqlProbe';
+export { useDpqlProbe } from './useDpqlProbe';
+export type { TDpqlProbeFn } from './useDpqlProbe';
 export { useDpqlSession } from './useDpqlSession';
 export type {
   IDpqlFieldMeta,

package/src/components/dpqlEditor/types.ts

@@ -2,6 +2,7 @@
 // Type definitions for the DpqlEditor component. Slate node types
 // (`ISlateElement`, `ISlateText`, `TSlateNode`) live in the smartEditor
 // primitive's `types.ts` — re-export them here for backward compat.
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 
 export type {
   ISlateElement,
@@ -13,6 +14,24 @@ export type {
 export interface IDpqlParseResult {
   success: boolean;
   expression: Record<string, any> | null;
+  /** The type the server inferred for the expression's result. */
+  inferred_type?: string;
+  /** Echo of the `target_type` the request asked about, when one was sent. */
+  target_type?: string;
+  /** `true` when the inferred type already satisfies the target. */
+  type_compatible?: boolean;
+  /** `true` when a conversion to the target exists at all. */
+  auto_coercible?: boolean;
+  /**
+   * `true` when that conversion is only ATTEMPTED, not guaranteed — text used
+   * as a number, whose outcome depends on what the text turns out to hold.
+   * A total conversion (a number used as text) reports `false`, and the server
+   * emits no diagnostic for it: warning about something that cannot fail
+   * teaches authors to ignore the warnings that can.
+   */
+  coercion_may_fail?: boolean;
+  /** The conversion that would make the expression fit, when one would. */
+  suggested_fix?: { text: string; description?: string };
   diagnostics: Array<{
     range: {
       start: { line: number; character: number };
@@ -72,6 +91,17 @@ export interface IDpqlEditorProps {
    * palette, the editor's at-a-glance prefix coloring).
    */
   templateTagsUseIntent?: boolean;
+  /**
+   * The overlay shown while the language server connects. Forwarded to
+   * `SmartEditor`; pass `null` to show the text without one — a read-only
+   * rendering already has its text, and only its colours wait for the server.
+   */
+  loadingIndicator?: React.ReactNode;
+  /**
+   * The template catalogue the surface offers: a `$…` reference found in it
+   * is labelled by its catalogue name. See `IDpqlTagRendererOptions.templates`.
+   */
+  templates?: IReqoreFormTemplates;
   /** Called when the editor loses focus. */
   onBlur?: () => void;
   /**
@@ -150,8 +180,14 @@ export interface IDpqlEditorRef {
    * when the document has no diagnostics, otherwise an array of errors.
    */
   validate: () => Promise<{ valid: boolean; errors?: Array<{ message: string }> }>;
-  /** Parse DPQL text into an expression AST via `dpql/parse`. */
-  parse: (text: string) => Promise<IDpqlParseResult>;
+  /**
+   * Parse DPQL text into an expression AST via `dpql/parse`.
+   *
+   * `targetType` asks the server, in the same round trip, whether the
+   * expression's result can satisfy that type — see `coercion_may_fail` on
+   * the result. Omit it to ask only whether the text parses.
+   */
+  parse: (text: string, targetType?: string) => Promise<IDpqlParseResult>;
   /** Serialize an expression AST back to DPQL text via `dpql/serialize`. */
   serialize: (expression: Record<string, any>) => Promise<string>;
 }

package/src/components/dpqlEditor/useDpqlProbe.ts

@@ -0,0 +1,33 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// React access to the shared DPQL detection probe (`dpqlProbe`). The hook
+// itself opens nothing: a field becomes a consumer of the shared document
+// only once it actually asks a question, and stops being one when it
+// unmounts. A form full of fields that never see expression-shaped text
+// therefore never opens the document at all.
+import { useCallback, useEffect, useRef } from 'react';
+import { dpqlProbe, IDpqlProbeResult } from './dpqlProbe';
+
+export type TDpqlProbeFn = (text: string) => Promise<IDpqlProbeResult>;
+
+export const useDpqlProbe = (): TDpqlProbeFn => {
+  const acquired = useRef(false);
+
+  useEffect(
+    () => () => {
+      if (acquired.current) {
+        acquired.current = false;
+        dpqlProbe.release();
+      }
+    },
+    []
+  );
+
+  return useCallback((text: string): Promise<IDpqlProbeResult> => {
+    if (!acquired.current) {
+      acquired.current = true;
+      dpqlProbe.acquire();
+    }
+
+    return dpqlProbe.parse(text);
+  }, []);
+};

package/src/components/dpqlEditor/useDpqlSession.ts

@@ -50,8 +50,11 @@ export interface IUseDpqlSessionResult {
   fieldMeta: Record<string, IDpqlFieldMeta>;
   /** Most recent `publishDiagnostics`. */
   diagnostics: ILspDiagnostic[];
-  /** `dpql/parse` — DPQL text → expression AST. */
-  parse: (text: string) => Promise<IDpqlParseResult>;
+  /**
+   * `dpql/parse` — DPQL text → expression AST, and, when `targetType` is
+   * given, whether that result can satisfy the type the field declares.
+   */
+  parse: (text: string, targetType?: string) => Promise<IDpqlParseResult>;
   /** `dpql/serialize` — expression AST → DPQL text. */
   serialize: (expression: Record<string, any>) => Promise<string>;
   /**
@@ -314,18 +317,31 @@ export function useDpqlSession(
   );
 
   const parse = useCallback(
-    async (text: string): Promise<IDpqlParseResult> => {
+    async (text: string, targetType?: string): Promise<IDpqlParseResult> => {
       if (!session.client) {
         return { success: false, expression: null, diagnostics: [] };
       }
       try {
         const result = await session.client.customRequest<Partial<IDpqlParseResult>>(
           'dpql/parse',
-          { uri: session.uri, text }
+          {
+            uri: session.uri,
+            text,
+            // Only sent when the field declares one. Without it the server
+            // does no type analysis at all, which is the right answer for a
+            // caller that only wants to know whether the text parses.
+            ...(targetType ? { target_type: targetType } : {}),
+          }
         );
         return {
           success: result?.success ?? false,
           expression: result?.expression ?? null,
+          inferred_type: result?.inferred_type,
+          target_type: result?.target_type,
+          type_compatible: result?.type_compatible,
+          auto_coercible: result?.auto_coercible,
+          coercion_may_fail: result?.coercion_may_fail,
+          suggested_fix: result?.suggested_fix,
           diagnostics: result?.diagnostics ?? [],
         };
       } catch {