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

package/src/helpers/templateText.ts

@@ -0,0 +1,92 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// A string holding template references, as the nodes a rich-text editor draws.
+//
+// A field whose value is a plain string can still hold references —
+// `Dear $local:name` — and those should read as the names they were chosen by,
+// not as their spelling. These convert between the stored string and the
+// editor's paragraphs, where each reference is a chip, so the editor can draw
+// chips while the field keeps storing exactly the string it always stored.
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { getTagLabel } from '../components/dpqlEditor/dpqlHelpers';
+import { describeTemplateReference, TEMPLATE_TOKEN_SOURCE } from './templates';
+
+/* Stated here rather than borrowed from Reqore's editor props: those resolve
+   to Reqore's `CustomElement`, which it does not export, so the published
+   declarations could not name this module's types (TS4023 on `yarn build`). */
+
+/** A run of text. */
+export interface ITemplateTextLeaf {
+  text: string;
+}
+
+/** A template reference, drawn as a chip. */
+export interface ITemplateTextTag {
+  type: 'tag';
+  value: string;
+  label: string;
+  metadata?: unknown;
+  children: ITemplateTextLeaf[];
+}
+
+/** One line of the string. */
+export interface ITemplateTextParagraph {
+  type: 'paragraph';
+  children: Array<ITemplateTextLeaf | ITemplateTextTag>;
+}
+
+/**
+ * What a reference chip says: the name the catalogue gives the reference, else
+ * the reference as the DPQL Text view labels it (`local: name`), so the same
+ * reference reads alike in the Visual builder and the Text view.
+ */
+export const templateChipLabel = (templates: IReqoreFormTemplates | undefined, value: string): string => {
+  const { label, item } = describeTemplateReference(templates, value);
+  return item ? label : getTagLabel(value);
+};
+
+/**
+ * `text` as paragraphs, one per line, with each template reference a chip.
+ *
+ * A chip is an inline VOID and holds no text of its own, so a cursor can only
+ * sit in the text nodes around it; one is kept on each side even when empty.
+ * The chip's label is `templateChipLabel`.
+ */
+export const templateTextToNodes = (
+  text: string,
+  templates?: IReqoreFormTemplates
+): ITemplateTextParagraph[] =>
+  (text ?? '').split('\n').map((line) => {
+    const children: ITemplateTextParagraph['children'] = [];
+    // A fresh expression per line: a shared /g instance carries `lastIndex`.
+    const pattern = new RegExp(TEMPLATE_TOKEN_SOURCE, 'g');
+    let last = 0;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(line)) !== null) {
+      const { item } = describeTemplateReference(templates, match[0]);
+      children.push({ text: line.slice(last, match.index) });
+      children.push({
+        type: 'tag',
+        value: match[0],
+        label: templateChipLabel(templates, match[0]),
+        metadata: item?.metadata,
+        children: [{ text: '' }],
+      });
+      last = match.index + match[0].length;
+    }
+    children.push({ text: line.slice(last) });
+    return { type: 'paragraph' as const, children };
+  });
+
+/** The string the paragraphs stand for: each chip written as its reference. */
+export const templateNodesToText = (nodes?: ReadonlyArray<{ children?: unknown[] }>): string =>
+  (nodes ?? [])
+    .map((paragraph: any) =>
+      (paragraph?.children ?? [])
+        .map((node: any) =>
+          typeof node?.text === 'string' ? node.text
+          : node?.type === 'tag' ? String(node.value ?? '')
+          : ''
+        )
+        .join('')
+    )
+    .join('\n');

package/src/helpers/templates.ts

@@ -1,4 +1,5 @@
 import { modalStore } from '@qoretechnologies/reqore';
+import { TReqoreTooltipProp } from '@qoretechnologies/reqore/dist/types/global';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import {
   TReqoreDropdownItem,
@@ -20,6 +21,24 @@ import { areQorusTypesCompatible } from './expressions';
  */
 export const TEMPLATE_EXAMPLE_PREVIEW_LENGTH = 150;
 
+/**
+ * How template picker entries are ordered: by the label a reader actually sees.
+ *
+ * The server sends groups and their items in whatever order it assembled them —
+ * for the test vocabulary that is step order, for an app's actions it is the
+ * connector's own. Neither is an order a reader can predict, and a picker
+ * holding 29 items is navigated by looking for a NAME.
+ *
+ * `localeCompare` with `numeric` so `item2` sorts before `item10`, and
+ * `sensitivity: 'base'` so case and accents do not split otherwise-adjacent
+ * neighbours.
+ */
+const byLabel = (a: { label?: unknown }, b: { label?: unknown }): number =>
+  String(a?.label ?? '').localeCompare(String(b?.label ?? ''), undefined, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+
 /**
  * Shared template string utilities.
  * Used by both validations and TemplateField.
@@ -258,43 +277,34 @@ export const describeTemplateReference = (
   return resolved.item ? resolved : { label: getTemplateReferencePath(value) };
 };
 
-const EMBEDDED_TEMPLATE_TOKEN = new RegExp(TEMPLATE_TOKEN_SOURCE, 'g');
-
-export type TTemplateTextSegment =
-  | { kind: 'text'; text: string }
-  | { kind: 'token'; text: string };
-
 /**
- * Splits prose that embeds template tokens into its literal and token parts —
- * `trim("$data:{…}")` becomes `trim("`, the token, `")`. Used to chip the
- * references inside a rendered expression instead of printing them raw.
+ * What a chosen template's hover should say.
+ *
+ * The reference itself — `$._case.title`, `$data:{dc_ai_reply.choices[0]…}` —
+ * is an implementation detail of the grammar, and it was what every template
+ * chip put in its tooltip. An author hovering a chip wants to know WHAT VALUE
+ * this is, and the catalogue already carries that: the entry's `description`
+ * is the prose the picker lists it under, written from the schema that declares
+ * it, with its type appended.
+ *
+ * So the hover reads as a small card — the value's name as the title, its
+ * description as the body — and the path stays where it is genuinely needed:
+ * the field's own help, which teaches the grammar with a worked example, and
+ * the picker, for the walks no list can hold.
+ *
+ * Falls back to the resolved label (itself the stripped path when the catalogue
+ * explains nothing), because a surface with no catalogue must still say what
+ * the value is rather than nothing at all.
  */
-export const splitTemplateTokens = (text?: string): TTemplateTextSegment[] => {
-  if (!text) {
-    return [];
-  }
-
-  const segments: TTemplateTextSegment[] = [];
-  let lastIndex = 0;
-
-  // A fresh regex per call: a shared /g instance carries `lastIndex` between
-  // calls and would skip tokens on the second string it is given.
-  const pattern = new RegExp(EMBEDDED_TEMPLATE_TOKEN.source, 'g');
-  let match: RegExpExecArray | null;
-
-  while ((match = pattern.exec(text)) !== null) {
-    if (match.index > lastIndex) {
-      segments.push({ kind: 'text', text: text.slice(lastIndex, match.index) });
-    }
-    segments.push({ kind: 'token', text: match[0] });
-    lastIndex = match.index + match[0].length;
-  }
-
-  if (lastIndex < text.length) {
-    segments.push({ kind: 'text', text: text.slice(lastIndex) });
-  }
-
-  return segments;
+export const templateTooltip = (
+  templates: IReqoreFormTemplates | undefined,
+  value: string
+): TReqoreTooltipProp => {
+  const { label, item } = describeTemplateReference(templates, value);
+  const description = (item as { description?: unknown } | undefined)?.description;
+  return typeof description === 'string' && description.trim() ?
+      { title: label, content: description, maxWidth: '360px' }
+    : label || value;
 };
 
 // Ported verbatim from qorus-ide `helpers/functions.tsx` (FIELD_STACK_REPORT
@@ -506,7 +516,7 @@ export const buildTemplates = (
 
         return item;
       }
-    );
+    ).sort(byLabel);
 
   return {
     items: Object.values(templates).map(
@@ -544,6 +554,6 @@ export const buildTemplates = (
           data_role
         ),
       })
-    ),
+    ).sort(byLabel),
   } as IReqoreFormTemplates;
 };

package/src/helpers/validations.ts

@@ -1064,14 +1064,39 @@ export const _validateField = (
         }
       }
 
-      if (parsedData) {
-        return withContext(
-          validateFieldWithResult(getTypeFromValue(parsedData), value),
-          'Auto-detected type is invalid'
-        );
+      /* A FALSY value is not an ABSENT one. `null`, `0`, `false` and `""` are
+         all values an author may hold in an `auto`/`any` field — a test
+         assertion expecting a count of zero, a flag that is off, or a blank
+         string — and the truthiness gate that used to stand here refused every
+         one of them as *"Value is empty"*. It surfaced on an assertion's
+         Expected Value holding `null`: opening it reported *"Value for argument
+         1 ("any") is invalid: Value is empty"* on the value the author had
+         deliberately chosen. Only `undefined` is actually empty.
+
+         `null` and `""` are answered here rather than delegated, for two
+         different reasons: `getTypeFromValue(null)` answers `auto`, which would
+         re-enter this very branch, and the `string` validator rejects `""`
+         because that is the rule for a REQUIRED text field — a different
+         question from whether an untyped field may hold a blank string. */
+      if (parsedData === undefined) {
+        return invalidResult('Value is empty');
+      }
+
+      if (parsedData === null || parsedData === '') {
+        return validResult();
       }
 
-      return invalidResult('Value is empty');
+      /* Validate what was PARSED, against the type detected from the same
+         parse. Validating the raw `value` instead made the two disagree
+         whenever parsing changed the shape: typing `1` into an `auto` field
+         parsed to the number 1, detected `int`, and then validated the STRING
+         "1" against it — "Value must be an integer", on a value that is one.
+         The author saw their field go invalid on the first character they
+         typed. */
+      return withContext(
+        validateFieldWithResult(getTypeFromValue(parsedData), parsedData),
+        'Auto-detected type is invalid'
+      );
     }
     case 'processor': {
       if (!value || !value['processor-input-type'] || !value['processor-output-type']) {
@@ -1512,6 +1537,31 @@ export const _validateField = (
         const argDefinition = expressionDefinition.varargs
           ? expressionDefinition.args[0]
           : expressionDefinition.args[index];
+        /* The argument's name for the message.
+        
+           `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}`;
+
+        /* An explicit null is a VALUE, and DPQL says so: `null` is a literal
+           that parses, serializes and round-trips like any other.
+        
+           Treated as a missing one, it made "this returns no value"
+           unsayable. Typing `null` into the text editor produces the literal
+           expression `{exp: "value", args: [null]}`; the visual view then
+           called it invalid and refused to render a summary, and a raw null
+           argument crashed the validator outright on `argValue.type`. Reported
+           from the live IDE by an author with no other way to assert that a
+           service method returns nothing.
+        
+           Only an EXPLICIT null counts. An argument that is simply absent, or
+           an envelope holding `undefined`, is still missing — which is the
+           distinction the author is making when they write it. */
+        if (argValue === null || (isObject(argValue) && (argValue as any).value === null)) {
+          continue;
+        }
 
         if (!argValue?.value && !argDefinition?.required) {
           continue;
@@ -1526,14 +1576,14 @@ export const _validateField = (
           if (!result.isValid) {
             return withContext(
               result,
-              `Sub-expression for argument ${index + 1} ("${argDefinition?.display_name}") is invalid`
+              `Sub-expression for argument ${index + 1} ("${argLabel}") is invalid`
             );
           }
 
           continue;
         }
 
-        const result = validateFieldWithResult(argValue.type, argValue.value, {
+        const result = validateFieldWithResult(argValue?.type, argValue?.value, {
           expressions,
           allowed_values: argDefinition?.allowed_values,
           element_allowed_values: argDefinition?.element_allowed_values,
@@ -1543,7 +1593,7 @@ export const _validateField = (
         if (!result.isValid) {
           return withContext(
             result,
-            `Value for argument ${index + 1} ("${argDefinition?.display_name}") is invalid`
+            `Value for argument ${index + 1} ("${argLabel}") is invalid`
           );
         }
       }

package/src/hooks/useFetch/useFetch.stories.tsx

@@ -1,6 +1,7 @@
 import { ReqoreSpinner, ReqoreTree } from '@qoretechnologies/reqore';
 import { StoryObj } from '@storybook/react-vite';
 import { testsWaitForText } from '../../../__tests__/utils';
+import { storyApiUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { useFetch } from './useFetch';
 
@@ -44,7 +45,7 @@ export const Get: Story = {
     mockData: [
       {
         // An array of mock objects which will add in every story
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/public/info',
+        url: storyApiUrl('public/info'),
         method: 'GET',
         status: 200,
         delay: 200,
@@ -81,7 +82,7 @@ export const Put: Story = {
     mockData: [
       {
         // An array of mock objects which will add in every story
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/public/info',
+        url: storyApiUrl('public/info'),
         method: 'PUT',
         status: 200,
         response: {
@@ -109,7 +110,7 @@ export const Post: Story = {
     mockData: [
       {
         // An array of mock objects which will add in every story
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/public/info',
+        url: storyApiUrl('public/info'),
         method: 'POST',
         status: 200,
         response: {
@@ -137,7 +138,7 @@ export const Del: Story = {
     mockData: [
       {
         // An array of mock objects which will add in every story
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/public/info',
+        url: storyApiUrl('public/info'),
         method: 'DELETE',
         status: 200,
         response: {
@@ -165,7 +166,7 @@ export const Error409: Story = {
     mockData: [
       {
         // An array of mock objects which will add in every story
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/public/info',
+        url: storyApiUrl('public/info'),
         method: 'POST',
         status: 409,
         response: {

package/src/hooks/useFetch/useFetch.tsx

@@ -1,8 +1,10 @@
+import { QueryClient, useQueryClient } from '@tanstack/react-query';
 import { useCallback, useMemo, useState } from 'react';
 import { useEffectOnce } from 'react-use';
 import { useContextSelector } from 'use-context-selector';
 import { FetchContext } from '../../contexts/FetchContext';
-import { IReqraftQueryConfig } from '../../utils/fetch';
+import { ReqraftQueryClient } from '../../providers/ReqraftProvider';
+import { IReqraftQueryConfig, reqraftCacheKey } from '../../utils/fetch';
 
 export interface IReqraftUseFetch<T> {
   data: T | undefined;
@@ -41,8 +43,40 @@ export function useFetch<T>({
     }
   });
 
-  const [loading, setLoading] = useState(loadOnMount);
-  const [data, setData] = useState<T | undefined>(defaultData);
+  /* An answer we ALREADY HAVE is not a loading state.
+     `loading` started at `loadOnMount` unconditionally, so every consumer that
+     mounted reported "loading" for at least one async turn even when the
+     response was sitting in the cache — and `FormEngine` renders its
+     `options-loading-skeleton` whenever any of its sources says that. So each
+     form appearing on a page flashed a skeleton whether or not anything was
+     actually fetched, which is what the repeated skeletons on an IDE page are:
+     measured on a fully warm SECOND visit to one page, three skeleton waves
+     against two requests, the last wave with no request anywhere near it.
+     Seeded from the query cache instead, so a resource already in hand renders
+     immediately. */
+  /* The provider is OPTIONAL here. `useQueryClient` THROWS when no
+     `QueryClientProvider` is above it, and plenty of consumers mount a form
+     with only a `FetchContext` — requiring one turned a rendering optimisation
+     into a hard dependency and took 131 tests down with it. `useContext` runs
+     before that throw, so hook order is unaffected and catching is safe. The
+     fallback is the same client `query` itself defaults to, so a cache hit is
+     found either way. */
+  let queryClient: QueryClient;
+  try {
+    queryClient = useQueryClient();
+  } catch {
+    queryClient = ReqraftQueryClient;
+  }
+
+  const cached = queryClient.getQueryData([
+    reqraftCacheKey({ url, method, body, noApiPrefix }),
+  ]) as { data?: T; ok?: boolean } | undefined;
+  const hasCachedAnswer = !!cached && cached.ok !== false && cached.data !== undefined;
+
+  const [loading, setLoading] = useState(!!loadOnMount && !hasCachedAnswer);
+  const [data, setData] = useState<T | undefined>(
+    hasCachedAnswer ? (cached?.data as T) : defaultData
+  );
   const [response, setResponse] = useState<Response | undefined>();
   const [error, setError] = useState<Error | undefined>();
   const [errorData, setErrorData] = useState<any>();
@@ -51,13 +85,23 @@ export function useFetch<T>({
     async ({
       body: customBody,
       mergeBodies,
-    }: { body?: Record<string | number, any>; mergeBodies?: boolean } = {}) => {
-      setLoading(true);
+      silent,
+    }: {
+      body?: Record<string | number, any>;
+      mergeBodies?: boolean;
+      /** Revalidate without announcing a loading state — see the note above. */
+      silent?: boolean;
+    } = {}) => {
+      if (!silent) {
+        setLoading(true);
+      }
 
       const _body = mergeBodies ? { ...body, ...customBody } : customBody || body;
       const response = await query<T>({ url, body: _body, cache, noApiPrefix });
 
-      setLoading(false);
+      if (!silent) {
+        setLoading(false);
+      }
 
       if (response.ok) {
         setError(undefined);
@@ -75,7 +119,9 @@ export function useFetch<T>({
 
   useEffectOnce(() => {
     if (loadOnMount) {
-      load();
+      // Still revalidates when the entry is cached — `query` honours its own
+      // staleness — but silently, so a cached answer never flashes a skeleton.
+      load({ silent: hasCachedAnswer });
     }
   });
 

package/src/hooks/useStorage/useStorage.stories.tsx

@@ -4,6 +4,7 @@ import { useRef } from 'react';
 import { fireEvent, within } from 'storybook/test';
 import { storiesStorageMock } from '../../../__tests__/ mock';
 import { testsWaitForText } from '../../../__tests__/utils';
+import { storyApiUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { useReqraftStorage } from './useStorage';
 
@@ -44,7 +45,7 @@ export const DefaultValue: Story = {
     },
     mockData: [
       {
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/users?action=current',
+        url: storyApiUrl('users?action=current'),
         method: 'GET',
         status: 200,
         response: {},

package/src/hooks/useTemplates.ts

@@ -13,6 +13,39 @@ export interface IUseTemplates {
 
 export const TemplatesCache = new Map<string, IReqoreFormTemplates>();
 
+/**
+ * Hand this hook a `getContextData` payload the host has already fetched.
+ *
+ * The host and this library keep SEPARATE caches over one API, so a page that
+ * has already paid for the context data pays again here — and, worse, waits for
+ * it: `FormEngine` will not render a field before its templates exist, because
+ * an any-typed field with no templates falls back to the type picker and asks
+ * the author to choose `string`/`int`/`hash` for a value they already captured.
+ *
+ * Measured on the live alert rule: three form sections were placeholders from
+ * 1459ms to 2039ms and, when they cleared, 193 elements that had been on screen
+ * for ~590ms dropped 67px, because the placeholder is not the height of the
+ * form it stands in for. Seeded, the form has its templates on its FIRST render
+ * and there is no placeholder to swap out at all.
+ *
+ * Same shape as `seedQueryCache` for the type catalogue, and deliberately
+ * first-write-wins: a real fetch that has already answered is not overwritten.
+ */
+export const seedTemplatesCache = (
+  interfaceContext: string,
+  payload: ITemplatesPayload
+): void => {
+  if (!interfaceContext || TemplatesCache.has(interfaceContext)) {
+    return;
+  }
+
+  const templates = buildTemplates(payload);
+
+  if (templates) {
+    TemplatesCache.set(interfaceContext, templates);
+  }
+};
+
 /**
  * Templates for form fields. Ported from qorus-ide `useTemplates` with one
  * deliberate difference: fetching `system/getContextData` is **opt-in** via
@@ -29,6 +62,14 @@ export const useTemplates = (
 
   const globalTemplates = useAsyncRetry(async () => {
     if (shouldFetch) {
+      /* Already answered — by a previous mount or by the host seeding it. The
+         cache was consulted for `loading` and for the value but not here, so a
+         seeded page still issued the request it had been handed the answer to. */
+      const cached = TemplatesCache.get(interfaceContext!);
+      if (cached) {
+        return cached;
+      }
+
       const serverTemplates = await query<ITemplatesPayload>({
         url: `system/getContextData?interface_context=${interfaceContext}`,
         method: 'PUT',

package/src/hooks/useWebSocket/useWebsocket.stories.tsx

@@ -6,6 +6,7 @@ import { Server } from 'mock-socket';
 import { useEffect, useState } from 'react';
 import { useMount } from 'react-use';
 import { sleep, testsClickButton, testsWaitForText } from '../../../__tests__/utils';
+import { storySocketUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { ReqraftWebSocketsManager } from '../../utils/websocket';
 import { IUseReqraftWebSocketOptions, useReqraftWebSocket } from './useWebSocket';
@@ -40,7 +41,7 @@ const CompWithHook = (args: IUseReqraftWebSocketOptions) => {
 const meta = {
   title: 'Hooks/useWebSocket',
   async beforeEach({ parameters }: { parameters: Record<string, any> }) {
-    const url = `wss://hq.qoretechnologies.com:8092/log-test?token=${process.env.REACT_APP_QORUS_TOKEN}`;
+    const url = storySocketUrl('log-test');
     let server = new Server(url);
     let killTimeout: NodeJS.Timeout;
     /** Set while the server is dead: every connection that lands is closed. */

package/src/index.tsx

@@ -36,7 +36,20 @@ export type {
   ICurrentUser,
   ICurrentUserStore,
 } from './stores/currentUser/currentUser';
-export { fetchConfig, query } from './utils/fetch';
+export {
+  fetchConfig,
+  query,
+  queryRaw,
+  reqraftApiPath,
+  reqraftCacheKey,
+  setupFetch,
+} from './utils/fetch';
+export type {
+  IReqraftFetchConfig,
+  IReqraftFetchResponse,
+  IReqraftQueryConfig,
+  IReqraftRawResponse,
+} from './utils/fetch';
 export * from './utils/websocket';
 export { ReqraftLspClient } from './utils/lspClient';
 export type { IReqraftLspClientOptions } from './utils/lspClient';

package/src/stores/currentUser/currentUser.stories.tsx

@@ -1,6 +1,7 @@
 import { ReqoreP, ReqoreSpinner, ReqoreTree } from '@qoretechnologies/reqore';
 import { StoryObj } from '@storybook/react-vite';
 import { testsWaitForText } from '../../../__tests__/utils';
+import { storyApiUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { currentUserStore } from './currentUser';
 
@@ -9,7 +10,7 @@ const meta = {
   parameters: {
     mockData: [
       {
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/users?action=current',
+        url: storyApiUrl('users?action=current'),
         method: 'GET',
         status: 200,
         response: {