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

package/src/components/form/index.tsx

@@ -24,6 +24,7 @@ export * from './fields/string/String';
 export * from './fields/template/ExampleValueModal';
 export * from './fields/template/TemplateField';
 export * from './engine/FormEngine';
+export * from './engine/FormFieldsSkeleton';
 export * from './engine/optionActions';
 export * from './engine/rendererTypes';
 export * from './expressions/types';

package/src/components/log/Log.stories.tsx

@@ -2,6 +2,7 @@ import { StoryObj } from '@storybook/react-vite';
 import { expect, fireEvent, fn } from 'storybook/test';
 import { Server } from 'mock-socket';
 import { sleep, testsClickButton, testsWaitForText } from '../../../__tests__/utils';
+import { storySocketUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { ReqraftLog } from './Log';
 
@@ -24,7 +25,7 @@ const meta = {
     mockdate: new Date('2024-01-01T08:00:00.000Z'),
   },
   async beforeEach() {
-    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;
     let fakeInterval: NodeJS.Timeout;

package/src/components/smartEditor/SmartEditor.tsx

@@ -18,7 +18,16 @@ import {
 } from '@qoretechnologies/reqore/dist/components/RichTextEditor';
 import { getReadableColor } from '@qoretechnologies/reqore/dist/helpers/colors';
 import { IReqoreTooltip } from '@qoretechnologies/reqore/dist/types/global';
-import React, { forwardRef, memo, useCallback, useImperativeHandle, useMemo, useRef } from 'react';
+import React, {
+  forwardRef,
+  memo,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useReducer,
+  useRef,
+} from 'react';
 import { Editor, NodeEntry, Range, Transforms } from 'slate';
 import { ReactEditor, RenderLeafProps } from 'slate-react';
 import { ILspSignatureHelp } from '../../utils/lspClient.types';
@@ -320,6 +329,14 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
     // ReqoreRichTextEditor's tokenizer mid-token (typed `@s` collapses to a
     // tag chip, making the rest of the field name impossible to type).
     const slateValueRef = useRef<ISlateElement[] | null>(null);
+    /* Counts the node trees the editor has reported. The tree a value converts
+       to is not always the tree the editor holds: Slate normalises a value set
+       from outside — a leading chip gains an empty text leaf before it — without
+       changing its text, so `value` never changes and the cache above kept the
+       tree the editor no longer had. Every offset computed from it (token
+       colours, diagnostics, signature help) then pointed one leaf off: a Text
+       view seeded with `"$local:name" == "John"` was never highlighted. */
+    const [editorTreeVersion, noteEditorTree] = useReducer((count: number) => count + 1, 0);
 
     useImperativeHandle(ref, () => editorRef.current as TReqoreRichTextEditorRef, []);
 
@@ -350,7 +367,17 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
       const next = converter.toSlateNodes(value);
       slateValueRef.current = next;
       return next;
-    }, [value, converter]);
+      // `editorTreeVersion` re-reads the cache once the editor reports its own tree.
+    }, [value, converter, editorTreeVersion]);
+
+    /* A value set from outside is a change to the document as much as typing
+       is — a Text view seeded after mount, a Preview following the author. The
+       server colours and diagnoses its own copy of the text, so it must hold
+       this one; typing already sent its text, and is not resent. */
+    const { didChange: syncDocument } = session;
+    useEffect(() => {
+      syncDocument(value);
+    }, [syncDocument, value]);
 
     const diagnosticDecorate = useLspDiagnosticDecorations(
       session.diagnostics,
@@ -450,15 +477,20 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
       (newNodes: ISlateElement[]) => {
         const plainText = converter.fromSlateNodes(newNodes);
 
+        // A selection change reports the same tree; anything else is the tree
+        // the editor now holds, and the one every offset is computed against.
+        if (newNodes !== slateValueRef.current) {
+          slateValueRef.current = newNodes;
+          noteEditorTree();
+        }
+
         if (plainText !== lastPlainTextRef.current) {
           lastPlainTextRef.current = plainText;
-          // CRITICAL: refresh `slateValueRef` to the live nodes too. The
-          // next render's `value` equals `lastPlainTextRef` (the typing
-          // echo), so `slateValue`'s cache returns this ref — leave it
-          // stale and downstream hooks (signature help, semantic tokens)
-          // never recompute, so the signature pill's active parameter
-          // never advances.
-          slateValueRef.current = newNodes;
+          // CRITICAL: the next render's `value` equals `lastPlainTextRef` (the
+          // typing echo), so `slateValue`'s cache returns the live nodes set
+          // above — leave them stale and downstream hooks (signature help,
+          // semantic tokens) never recompute, so the signature pill's active
+          // parameter never advances.
           onChange(plainText);
           session.didChange(plainText);
         }

package/src/components/smartEditor/__fixtures__/mockLspServer.ts

@@ -2,8 +2,10 @@
 // (heartbeat, initialize, document tracking, request dispatch); story files
 // register only their language-specific handlers.
 import { Client, Server } from 'mock-socket';
+import { storySocketUrl } from '../../../stories/storyNetwork';
 
-export const MOCK_LSP_URL = `wss://hq.qoretechnologies.com:8092/lsp?token=${process.env.REACT_APP_QORUS_TOKEN}`;
+/** Where `ReqraftLspClient` dials by default, on the instance stories use. */
+export const MOCK_LSP_URL = storySocketUrl('lsp');
 
 // LSP-standard 16-type / 6-modifier legend, as the real Qorus server
 // advertises in `initialize` (qorus/Classes/QorusLspWebSocketHandler.qc:847).
@@ -76,31 +78,69 @@ export interface IMockLspServer {
   received: IMockLspMessage[];
   connectionCount: number;
   getOpenConnectionCount: () => number;
-  // Most-recent document text from didOpen / didChange.
+  // Most-recent document text from didOpen / didChange, whichever document.
   documentText: string;
+  /**
+   * The text of every open document, by URI. Clients share ONE socket per
+   * endpoint and open a document each — an editor and several read-only
+   * renderings at once — so a per-document answer (semantic tokens) must read
+   * its own document, not whichever one changed last.
+   */
+  textOf: (uri?: string) => string;
   delays: Record<string, number>;
   notify: (method: string, params: unknown) => void;
   close: () => void;
 }
 
+/* One mock per URL at a time. `.storybook/preview.tsx` starts a default DPQL
+   language server for every story, and a story that needs its own handlers
+   creates a server on the same URL; mock-socket refuses a second server there,
+   so creating one replaces whichever is listening. */
+const activeServers = new Map<string, IMockLspServer>();
+
 export const createMockLspServer = (
   url: string,
   options: IMockLspServerOptions = {}
 ): IMockLspServer => {
+  // No connection reset here: `.storybook/preview.tsx` resets the shared LSP
+  // connections (and the expression render client) before every story, which
+  // covers stories that never create a mock server as well as those that do.
+  activeServers.get(url)?.close();
   const server = new Server(url);
   const sockets: Client[] = [];
+  const documents = new Map<string, string>();
+  let closed = false;
   const lsp: IMockLspServer = {
     received: [],
     connectionCount: 0,
     getOpenConnectionCount: () => sockets.filter((socket) => socket.readyState === 1).length,
     documentText: '',
+    textOf: (uri) => (uri !== undefined && documents.has(uri) ? documents.get(uri)! : lsp.documentText),
     delays: { ...options.delays },
     notify: (method, params) =>
       sockets.forEach((socket) =>
         socket.send(JSON.stringify({ jsonrpc: '2.0', method, params }))
       ),
-    close: () => server.close(),
+    close: () => {
+      /* Once only. mock-socket finds clients by URL, not by server, so closing a
+         server that was already replaced would close its REPLACEMENT's clients
+         — and the default server is closed twice when a story replaces it: once
+         on replacement, once in the preview's teardown. */
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (activeServers.get(url) === lsp) {
+        activeServers.delete(url);
+      }
+      server.close();
+      // `close()` drops the clients but leaves mock-socket's WebSocket installed
+      // on the page; only `stop()` puts the real one back. Without it a story
+      // that reaches a real server (`parameters.live`) dials the mock instead.
+      server.stop();
+    },
   };
+  activeServers.set(url, lsp);
 
   server.on('connection', (socket) => {
     lsp.connectionCount++;
@@ -119,14 +159,23 @@ export const createMockLspServer = (
       }
       lsp.received.push(msg);
 
+      const uri = msg.params?.textDocument?.uri;
       if (msg.method === 'textDocument/didOpen') {
         lsp.documentText = msg.params?.textDocument?.text ?? '';
+        if (uri !== undefined) {
+          documents.set(uri, lsp.documentText);
+        }
       } else if (msg.method === 'textDocument/didChange') {
         // The client sends a single full-document content change.
         const change = msg.params?.contentChanges?.[0];
         if (change && typeof change.text === 'string') {
           lsp.documentText = change.text;
+          if (uri !== undefined) {
+            documents.set(uri, change.text);
+          }
         }
+      } else if (msg.method === 'textDocument/didClose' && uri !== undefined) {
+        documents.delete(uri);
       }
 
       const handler = options.handlers?.[msg.method];

package/src/components/smartEditor/useLspSession.ts

@@ -77,7 +77,11 @@ export interface IUseLspSessionResult {
    * only fires when `capabilities?.signatureHelpProvider` exists).
    */
   capabilities: ILspServerCapabilities | null;
-  /** Forward content changes to the server via `didChange`. */
+  /**
+   * The editor now holds `text`: the server is sent it via `didChange`, or via
+   * `didOpen` if the document is not open yet. Text the server already holds
+   * is not resent, so it is safe to call for every value the editor shows.
+   */
   didChange: (text: string) => void;
   /**
    * Request `textDocument/completion` at a plain-text offset. Converts
@@ -96,6 +100,13 @@ export function useLspSession(
 
   const clientRef = useRef<ReqraftLspClient | null>(null);
   const versionRef = useRef(1);
+  /* The text the editor holds, and the text the server holds for this
+     document — `null` until the document is open. The server tokenises and
+     diagnoses ITS copy, so every text the editor shows has to reach it, however
+     it got there: typed, or set from outside after mount (a Text view seeded
+     once `dpql/serialize` answers, a Preview following the typing). */
+  const editorTextRef = useRef(initialText);
+  const serverTextRef = useRef<string | null>(null);
   const uriRef = useRef(uriProp ?? `${languageId}://session/${++lspUriCounter}`);
 
   const [client, setClient] = useState<ReqraftLspClient | null>(null);
@@ -129,8 +140,11 @@ export function useLspSession(
         // result.
         setSemanticTokensLegend(c.semanticTokensLegend);
         setCapabilities(c.capabilities);
+        // Opened with the text the editor holds NOW, which may have been set
+        // while the connection was opening.
+        serverTextRef.current = editorTextRef.current;
         c.didOpen(
-          initialText,
+          editorTextRef.current,
           initialMetadata && Object.keys(initialMetadata).length > 0
             ? initialMetadata
             : undefined
@@ -146,6 +160,7 @@ export function useLspSession(
     return () => {
       c.disconnect();
       clientRef.current = null;
+      serverTextRef.current = null;
       setClient(null);
       setIsReady(false);
       setSemanticTokensLegend(null);
@@ -158,8 +173,11 @@ export function useLspSession(
   }, []);
 
   const didChange = useCallback((text: string) => {
+    editorTextRef.current = text;
     const c = clientRef.current;
-    if (!c) return;
+    // Not open yet: `didOpen` will carry it. Already held: nothing to send.
+    if (!c || serverTextRef.current === null || serverTextRef.current === text) return;
+    serverTextRef.current = text;
     c.didChange(text, ++versionRef.current);
   }, []);
 

package/src/helpers/dpqlDetection.ts

@@ -0,0 +1,209 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * Noticing that text typed into a PLAIN (non-expression) field is really a
+ * DPQL expression, and deciding what to do about it.
+ *
+ * The rule this implements, in one sentence: **switch the field into
+ * expression mode only when the text cannot be a valid literal for the
+ * field's type but IS a real expression; otherwise offer, never silently
+ * reinterpret.** Quietly turning the string `a + b` into a concatenation on a
+ * `string` field would destroy a legitimate literal, so a type that accepts
+ * any text never auto-switches — it only ever offers.
+ *
+ * ## Why the server has the last word
+ *
+ * "Does this parse as DPQL?" is NOT a usable test, which is the trap here.
+ * Verified against the live LSP: `dpql/parse` reports `success: true` for
+ * `hello`, for `42`, for `2026-09-06` and for `@a` — it wraps each of them in
+ * a trivial `{exp: 'value', args: [...]}` node. Everything is a valid DPQL
+ * program, because a bare literal is one. So a text that parses tells us
+ * nothing; what tells us something is the SHAPE of the AST that comes back:
+ *
+ * | typed text        | `exp`      | verdict    |
+ * |-------------------|------------|------------|
+ * | `hello`, `42`     | `value`    | a literal  |
+ * | `$local:count`    | `template` | a template |
+ * | `@a > 5`          | `>`        | expression |
+ * | `"a" + "b"`       | `+`        | expression |
+ * | `toInt("5")`      | `toInt`    | expression |
+ *
+ * `isRealExpressionAst` is that test, and it is the only authority. The
+ * lexical pass below decides nothing — its sole job is to keep a server
+ * round-trip off every keystroke of every field.
+ */
+import { validateField } from './validations';
+
+/** What to do about text that turned out to be an expression. */
+export type TDpqlDetectionOutcome =
+  /** Not an expression, or not one we may act on — leave the field alone. */
+  | 'none'
+  /** A real expression, but the text is also a valid literal here: ask. */
+  | 'offer'
+  /** A real expression, and the text cannot be a literal here: switch. */
+  | 'switch';
+
+/**
+ * The `exp` values that mean "this is not an expression": a bare literal and
+ * a bare template reference. A template is already the template field's job
+ * (`isValueTemplate`), and a literal is what the plain field is for.
+ */
+const NON_EXPRESSION_OPS = new Set(['value', 'template']);
+
+/**
+ * Operators and calls whose presence makes a server probe worth the trip.
+ * Deliberately generous — a false positive costs one debounced request that
+ * comes back `exp: 'value'`, while a false negative silently loses the whole
+ * feature.
+ *
+ * ## Why the spacing rules differ per operator
+ *
+ * `-` and `/` are ambiguous: they appear inside values nobody means as
+ * arithmetic — dates (`2026-09-06`), negative numbers (`-5`), paths (`a/b`),
+ * hyphenated names (`well-known-name`). A space next to one is what separates
+ * `@a - 1` from those, so they keep a spacing requirement.
+ *
+ * `+` is NOT ambiguous in that way, and requiring spaces around it lost the
+ * feature for the most natural way to type arithmetic: `2 + 1` was offered as
+ * an expression while `2+1` and `2+ 1` were not, which reads as the detection
+ * working only sometimes. Reported from the live IDE. `+` now counts wherever
+ * it appears; if the text turns out to be an ordinary literal the server says
+ * so and the offer never appears.
+ *
+ * The `-`/`/` rule is also relaxed from "spaces on BOTH sides" to "a space on
+ * either side", so `@a -1` and `@a- 1` are probed too while every ambiguous
+ * value above still is not.
+ */
+const DPQL_OPERATOR_PATTERN = new RegExp(
+  [
+    '(==|!=|<>|>=|<=)', // two-character comparisons
+    '[<>*%]', // unambiguous single-character operators
+    '(?<!=)=(?!=)', // a lone `=`, not part of `==`
+    '\\+', // `+` — unambiguous, so spacing is irrelevant
+    '(\\s[-/]|[-/]\\s)', // `-` and `/` need a space on at least one side
+    '\\b(and|or|not|like|in|contains)\\b', // word operators
+  ].join('|'),
+  'i'
+);
+
+/** A function call — `toInt("5")`, `upper(@name)`. */
+const DPQL_CALL_PATTERN = /\b[a-z_]\w*\s*\(/i;
+
+/**
+ * The longest text worth probing. An expression a person types into a form
+ * field is short; anything longer is a document, and probing it on every
+ * keystroke would be a waste of a round-trip.
+ */
+const MAX_PROBE_LENGTH = 512;
+
+/**
+ * Cheap, purely lexical "might this be worth asking the server about?".
+ * Never decides anything on its own — see the module comment.
+ */
+export const mightBeDpqlExpression = (text: unknown): boolean => {
+  if (typeof text !== 'string') {
+    return false;
+  }
+
+  const trimmed = text.trim();
+
+  if (!trimmed || trimmed.length > MAX_PROBE_LENGTH) {
+    return false;
+  }
+
+  return DPQL_OPERATOR_PATTERN.test(trimmed) || DPQL_CALL_PATTERN.test(trimmed);
+};
+
+/**
+ * The authority: does this `dpql/parse` result describe a REAL expression
+ * rather than a literal or a bare template reference? Accepts either the
+ * field-ready envelope (`{is_expression, value: {exp, args}}`) the server
+ * returns or a bare `{exp, args}` node.
+ */
+export const isRealExpressionAst = (expression: unknown): boolean => {
+  if (!expression || typeof expression !== 'object') {
+    return false;
+  }
+
+  const envelope = expression as { value?: unknown; exp?: unknown };
+  const node = (
+    envelope.exp === undefined && envelope.value && typeof envelope.value === 'object'
+      ? envelope.value
+      : envelope
+  ) as { exp?: unknown };
+
+  return typeof node.exp === 'string' && !!node.exp && !NON_EXPRESSION_OPS.has(node.exp);
+};
+
+/**
+ * `true` when any diagnostic is an outright error. The server reports
+ * severity as the string `'error'` on this route and LSP proper uses `1`;
+ * both are accepted rather than assuming one.
+ */
+export const hasErrorDiagnostic = (
+  diagnostics?: Array<{ severity?: number | string } | undefined | null>
+): boolean =>
+  !!diagnostics?.some((diagnostic) => {
+    const severity = diagnostic?.severity;
+    return severity === 1 || severity === 'error';
+  });
+
+/**
+ * Could this text stand as a literal value of the field's own type? A type
+ * that accepts any text (`string`, and every type the form validator passes
+ * by default) always can, which is exactly why such a field never
+ * auto-switches. Delegates to the form's own validator so the answer is the
+ * same one the field itself would give.
+ */
+export const canBeLiteralOfType = (
+  text: string,
+  type?: string,
+  field?: Record<string, any>
+): boolean => {
+  if (!type) {
+    return true;
+  }
+
+  try {
+    return validateField(type, text, field as any);
+  } catch {
+    // A validator that throws must not be read as "this cannot be a
+    // literal" — that would auto-switch the field on the strength of a bug.
+    return true;
+  }
+};
+
+export interface IClassifyTypedTextArgs {
+  /** The text the author typed into the plain field. */
+  text: string;
+  /** The field's declared type (`ui_type ?? type`). */
+  type?: string;
+  /** The field schema, for validators that consult `validation_regex` etc. */
+  field?: Record<string, any>;
+  /** The `dpql/parse` result for `text`, or `undefined` if it has not run. */
+  parsed?: {
+    success?: boolean;
+    expression?: unknown;
+    diagnostics?: Array<{ severity?: number | string }>;
+  };
+}
+
+/**
+ * The whole decision, in one pure function so it can be tested without a
+ * server, a socket or a rendered field.
+ */
+export const classifyTypedText = ({
+  text,
+  type,
+  field,
+  parsed,
+}: IClassifyTypedTextArgs): TDpqlDetectionOutcome => {
+  if (!parsed?.success || !parsed.expression) {
+    return 'none';
+  }
+
+  if (!isRealExpressionAst(parsed.expression) || hasErrorDiagnostic(parsed.diagnostics)) {
+    return 'none';
+  }
+
+  return canBeLiteralOfType(text, type, field) ? 'offer' : 'switch';
+};

package/src/helpers/optionUiTypes.ts

@@ -159,3 +159,25 @@ export const isOptionInterfaceUiType = (type: unknown): type is TOptionInterface
 
 export const isKnownQorusUiType = (type: unknown): type is TKnownQorusUiType =>
   typeof type === 'string' && knownQorusUiTypeSet.has(type);
+
+/** The spellings that mean "no concrete type" wherever they appear. */
+export const UNTYPED_OPTION_TYPES = ['any', 'auto'] as const;
+
+export type TUntypedOptionType = (typeof UNTYPED_OPTION_TYPES)[number];
+
+const untypedOptionTypeSet = new Set<string>(UNTYPED_OPTION_TYPES);
+
+/**
+ * `auto` and `any` declare no type: they say the AUTHOR chooses one, and the
+ * chosen type is recorded beside the value, not in the schema. A reader that
+ * takes the schema's word therefore learns nothing about what the value has to
+ * look like — `validateField` handles these two by auto-detecting from the
+ * value, which accepts whatever is there.
+ *
+ * This list lives here, with the rest of the type vocabulary, rather than in
+ * `engine/typeChoices` where it started: a helper cannot import from a
+ * component, and the rule was already spelled out by hand in seven other
+ * places.
+ */
+export const isUntypedOptionType = (type: unknown): type is TUntypedOptionType =>
+  typeof type === 'string' && untypedOptionTypeSet.has(type);

package/src/helpers/options.ts

@@ -52,3 +52,73 @@ export const getListElementValue = (element: unknown): unknown =>
   element && typeof element === 'object' && !Array.isArray(element) && 'value' in element ?
     (element as { value: unknown }).value
   : element;
+
+/**
+ * The schema with every one-of group that offers no choice turned back into a
+ * plain required field.
+ *
+ * A `required_groups` group says *"at least one of these"*, and the whole
+ * affordance built on it — the ONE OF header, the `Covers` / `Covered by “X”`
+ * chips, the *"this field or X is required"* message — exists to tell an author
+ * that they have a CHOICE and which way they have answered it. When the group
+ * has a single member in the schema in hand, there is no choice: that field
+ * must be set, which is exactly what `required` already means. Saying it in the
+ * one-of grammar instead is worse than saying nothing, because a green tick
+ * beside a value reads as confirmation of the VALUE — a Qorus test author read
+ * `✓ COVERS` beside their service as "yes, this is the service your test is
+ * about", which the form never said and cannot know.
+ *
+ * This is not a hypothetical: a server may legitimately declare a group over an
+ * API-only alternative it then hides from the form (Qorus test steps put
+ * `target` in a group with `service`, and hide `target`), so the form is handed
+ * one member of a two-member group. The group is still real for the API and
+ * must stay in the schema the server serves; it is only this form that has
+ * nothing to offer.
+ *
+ * The rewrite is exact rather than cosmetic: a one-of over one option and a
+ * required option are the same constraint, so validation, the completion meter
+ * and the required-only filter all keep saying what they said — in the grammar
+ * that fits.
+ *
+ * A field in a degenerate group is required by that group ALONE, so it is
+ * marked required even when it also belongs to a group that does offer a
+ * choice; that other group keeps its affordance and is satisfied by this field
+ * either way. The key is deleted rather than emptied because `[]` is truthy,
+ * and every consumer tests `option.required_groups` for existence.
+ *
+ * Returns the schema unchanged — the same object — when no group degenerates,
+ * so it can sit on a memo without giving every render a new schema identity.
+ */
+export const resolveDegenerateRequiredGroups = <T extends IQorusFormSchema | undefined>(
+  schema: T
+): T => {
+  if (!schema) return schema;
+
+  const membersPerGroup: Record<string, number> = {};
+  Object.values(schema).forEach((option) => {
+    (option as TQorusFormFieldSchema)?.required_groups?.forEach((group) => {
+      membersPerGroup[group] = (membersPerGroup[group] ?? 0) + 1;
+    });
+  });
+
+  const degenerate = (group: string): boolean => membersPerGroup[group] < 2;
+  if (!Object.keys(membersPerGroup).some(degenerate)) return schema;
+
+  const resolved: IQorusFormSchema = {};
+  Object.entries(schema).forEach(([name, option]) => {
+    const groups = (option as TQorusFormFieldSchema)?.required_groups;
+    if (!groups?.some(degenerate)) {
+      resolved[name] = option;
+      return;
+    }
+    const kept = groups.filter((group) => !degenerate(group));
+    const rest = { ...(option as TQorusFormFieldSchema) };
+    delete rest.required_groups;
+    resolved[name] = {
+      ...rest,
+      required: true,
+      ...(kept.length ? { required_groups: kept } : {}),
+    } as TQorusFormFieldSchema;
+  });
+  return resolved as T;
+};

package/src/helpers/templateItems.ts

@@ -0,0 +1,81 @@
+import type { TMarkdownRenderer } from '../components/Description/markdownRendererContext';
+
+/**
+ * What a template picker should actually list.
+ *
+ * Pickers group templates by category, which is what makes a long catalogue
+ * scannable. A LONE category buys nothing and costs a click: the author opens
+ * the picker, sees one row naming the category, clicks it, and only then sees
+ * the values — with a back arrow as the only other thing on offer. So a single
+ * category is opened for them.
+ *
+ * Two or more categories keep the grouping, because there the headers are doing
+ * real work. This only ever removes a step that could not have gone any other
+ * way.
+ *
+ * Lives here rather than beside either picker: `TemplateField` renders the
+ * "Select Template" dropdown and `RichText` renders the in-editor `$` list, and
+ * `TemplateField` already imports `RichText` — so a shared home is the only one
+ * that does not close an import cycle.
+ */
+export const templateItemsToShow = <T,>(items: T[] | undefined): T[] | undefined => {
+  if (items?.length !== 1) {
+    return items;
+  }
+  const only = items[0] as { items?: unknown[] };
+  return Array.isArray(only.items) && only.items.length ? (only.items as T[]) : items;
+};
+
+/**
+ * A picker row's description, DRAWN.
+ *
+ * A description is prose, and a host that writes prose writes markdown: the
+ * same author, in the same dialect, as the field descriptions and schema
+ * messages this package already draws through the host's renderer. Left as a
+ * string, a row explaining that a step needs a **Fixture Output** printed the
+ * asterisks at the reader.
+ *
+ * WHERE THIS MAY BE CALLED, and why it is not simply done at the source: the
+ * template list is a memo KEY in several places — `TemplateField` stringifies
+ * both the incoming `templates` and the resolved `filteredTemplates`, and the
+ * list is handed down to nested fields that stringify it again. `JSON.stringify`
+ * throws on a React element's circular `_owner`, so an element anywhere in the
+ * list takes the whole form down to a blank panel.
+ *
+ * So this runs at the LAST hop only — the call that hands items to a Reqore
+ * control, after every key has been computed — and its result is never passed
+ * on to anything that might stringify it. Reqore itself does not: it draws the
+ * description into a `ReqoreTextEffect` and styled-components filters the prop
+ * off the DOM.
+ *
+ * Without a host renderer the items are returned untouched, so a host that has
+ * no markdown keeps exactly what it had.
+ */
+export const renderTemplateItemDescriptions = <T,>(
+  items: T[] | undefined,
+  render: TMarkdownRenderer | undefined
+): T[] | undefined => {
+  if (!render || !items?.length) {
+    return items;
+  }
+
+  return items.map((item) => {
+    const entry = item as { description?: unknown; items?: unknown };
+    const next = { ...entry } as Record<string, unknown>;
+
+    if (typeof entry.description === 'string' && entry.description.trim()) {
+      /* `compact`, for the reason the context gives: a row is a constrained
+         container, and markdown authored as a document opens with a heading
+         that would outgrow the label above it. */
+      next.description = render({ value: entry.description, compact: true });
+    }
+
+    // Only when the item HAS children — writing the key unconditionally would
+    // give every leaf an `items` a picker could read as an empty submenu.
+    if (Array.isArray(entry.items)) {
+      next.items = renderTemplateItemDescriptions(entry.items, render);
+    }
+
+    return next as T;
+  });
+};