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

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

@@ -1,51 +1,36 @@
 // Copyright 2026 Qore Technologies, s.r.o.
-// The "Explain" seam. Turns an expression AST into a readable string.
+// The "Explain" seam. Turns an expression AST into its readable rendering.
 //
-// The canonical rendering is the server's `DataProvider::renderExpression`,
-// reached over the LSP custom method `dpql/renderExpression` (added next to
-// `dpql/serialize` in `QorusLspWebSocketHandler.qc`). All consumers share ONE
-// render socket: the module-level `ReqraftLspClient` below rides the per-endpoint
-// `LspSharedConnection`, and JSON-RPC request ids associate each response
-// with the caller — N expression builders on one form means N independent
-// in-flight requests on one connection, no cross-wiring.
+// The rendering is the server's `DataProvider::renderExpression`, reached over
+// the LSP custom method `dpql/renderExpression` (added next to `dpql/serialize`
+// in `QorusLspWebSocketHandler.qc`). All consumers share ONE render socket: the
+// module-level `ReqraftLspClient` below rides the per-endpoint
+// `LspSharedConnection`, and JSON-RPC request ids associate each response with
+// the caller — N expression builders on one form means N independent in-flight
+// requests on one connection, no cross-wiring.
 //
-// When the LSP is unreachable (or the server predates the method), `render`
-// falls back to the client-side approximation below; `serverRendering` tells
-// consumers which path served.
+// There is no client-side stand-in. A Qorus form does not work without Qorus,
+// so the only time the server was "unreachable" in practice was while the
+// page's first connection was still opening — and racing that with a 1.5s timer
+// replaced the real rendering with an approximation labelled "Approximate", on
+// exactly the first Explain of every page. A rendering now waits for the
+// connection; `null` means the server cannot render at all (it predates the
+// method, or the connection gave up), which the caller says plainly.
 import { nanoid } from 'nanoid';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { ReqraftLspClient } from '../../../utils/lspClient';
-import { IExpressionSchema, IExpressionValue } from './types';
+import { IExpressionValue } from './types';
 
+/* The synchronous summary a collapsed row prints — see `readFirst.ts`. It is
+   not a stand-in for this rendering and is never shown in its place. */
 export { renderExpressionToText } from './renderExpressionToText';
-import { renderExpressionToText } from './renderExpressionToText';
-
-// ── The shared render transport ───────────────────────────────────────
-// One lazy module-level client for ALL `useRenderExpression` consumers.
-// Rendering needs no document/context state, so a single connection (shared
-// further with any open DPQL editors via `LspSharedConnection`) serves
-// every builder on the page.
 
 /** Coalesce rapid re-renders per consumer (live typing) — trailing edge. */
 const RENDER_DEBOUNCE_MS = 300;
-/** How long a render call waits for the socket before falling back. */
-const CONNECT_WAIT_MS = 1500;
-/** After a failed wait, fall back instantly for this long before re-waiting. */
-const CONNECT_RETRY_COOLDOWN_MS = 10000;
 
 let renderClient: ReqraftLspClient | null = null;
 /** Set after a `-32601 method not found` — the server predates the method. */
 let methodUnsupported = false;
-let lastConnectWaitFailedAt = 0;
-
-let lastServerRendering = false;
-const serverRenderingListeners = new Set<(on: boolean) => void>();
-const setLastServerRendering = (on: boolean): void => {
-  if (on !== lastServerRendering) {
-    lastServerRendering = on;
-    serverRenderingListeners.forEach((listener) => listener(on));
-  }
-};
 
 const getRenderClient = (): ReqraftLspClient => {
   if (!renderClient) {
@@ -59,55 +44,24 @@ const getRenderClient = (): ReqraftLspClient => {
   return renderClient;
 };
 
-/**
- * Wait (briefly) for the shared connection. `connect()` is re-entrant and the
- * underlying socket keeps its own reconnect schedule, so this only bounds how
- * long a single render call blocks before falling back — after a failed wait
- * we fall back instantly for a cooldown period instead of re-blocking.
- */
-const waitForConnection = async (client: ReqraftLspClient): Promise<boolean> => {
-  if (client.isConnected) return true;
-  if (Date.now() - lastConnectWaitFailedAt < CONNECT_RETRY_COOLDOWN_MS) {
-    return false;
-  }
-  const connected = await Promise.race([
-    client.connect().then(
-      () => true,
-      () => false
-    ),
-    new Promise<boolean>((resolve) => {
-      setTimeout(() => resolve(false), CONNECT_WAIT_MS);
-    }),
-  ]);
-  if (!connected || !client.isConnected) {
-    lastConnectWaitFailedAt = Date.now();
-    return false;
-  }
-  return true;
-};
-
 /** One rendered expression — what `renderRich` resolves with. */
 export interface IRenderedExpression {
   /** The readable rendering (plain text). */
   text: string;
   /**
    * The server's richtext form — template references arrive as `tag` nodes
-   * (the IDE renders them as chips). `null` on the client-side fallback.
-   * Convert with `richtextResponseToSlate` for `RichTextFormField`.
+   * (the IDE renders them as chips). Convert with `richtextResponseToSlate`.
    */
   richtext: unknown | null;
-  /** `true` when the server `dpql/renderExpression` produced this result. */
-  server: boolean;
 }
 
-/** Server-side render; `null` means "fall back to the client-side path". */
-const renderViaServer = async (
-  value: IExpressionValue
-): Promise<{ text: string; richtext: unknown | null } | null> => {
+const renderViaServer = async (value: IExpressionValue): Promise<IRenderedExpression | null> => {
   if (methodUnsupported) return null;
   const client = getRenderClient();
-  if (!(await waitForConnection(client))) return null;
   try {
+    // Waits as long as the connection does: it has its own reconnect schedule
+    // and rejects once it gives up, so this never outlives a dead socket.
+    await client.connect();
     const result = await client.customRequest<{ rendered?: string; richtext?: unknown }>(
       'dpql/renderExpression',
       // The server accepts both the bare `{exp, args}` AST and the
@@ -131,75 +85,50 @@ export const _resetRenderExpressionTransportForTests = (): void => {
   renderClient?.disconnect();
   renderClient = null;
   methodUnsupported = false;
-  lastConnectWaitFailedAt = 0;
-  lastServerRendering = false;
 };
 
 interface IPendingRender {
   value: IExpressionValue;
-  expressions: IExpressionSchema[];
-  resolvers: Array<(rendered: IRenderedExpression) => void>;
+  resolvers: Array<(rendered: IRenderedExpression | null) => void>;
 }
 
 export interface IUseRenderExpressionResult {
-  /** Render an expression AST to a readable string. */
-  render: (value: IExpressionValue, expressions?: IExpressionSchema[]) => Promise<string>;
+  /** The readable rendering of an expression AST, or `null` when the server cannot render. */
+  render: (value: IExpressionValue) => Promise<string | null>;
   /**
    * Like `render`, but also resolves the server's richtext form (template
-   * references as `tag` nodes — chips) and which path served. For consumers
-   * that style the rendering, e.g. the builder's Explain panel.
-   */
-  renderRich: (
-    value: IExpressionValue,
-    expressions?: IExpressionSchema[]
-  ) => Promise<IRenderedExpression>;
-  /**
-   * `true` when the server `dpql/renderExpression` path served the last
-   * render; `false` while on the client-side approximation (LSP unreachable
-   * or the server predates the method).
+   * references as `tag` nodes — chips). `null` when there is nothing to render
+   * or the server cannot render it.
    */
-  serverRendering: boolean;
+  renderRich: (value: IExpressionValue) => Promise<IRenderedExpression | null>;
 }
 
 export const useRenderExpression = (): IUseRenderExpressionResult => {
-  const [serverRendering, setServerRendering] = useState(lastServerRendering);
   const pendingRef = useRef<IPendingRender | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastRunRef = useRef(0);
 
-  useEffect(() => {
-    serverRenderingListeners.add(setServerRendering);
-    return () => {
-      serverRenderingListeners.delete(setServerRendering);
+  useEffect(
+    () => () => {
       if (timerRef.current) {
         clearTimeout(timerRef.current);
         timerRef.current = null;
       }
-      // Settle any coalesced callers with the synchronous fallback so no
-      // promise is left hanging past unmount.
+      // Settle any coalesced callers so no promise is left hanging past unmount.
       const pending = pendingRef.current;
       pendingRef.current = null;
-      pending?.resolvers.forEach((resolve) =>
-        resolve({
-          text: renderExpressionToText(pending.value, pending.expressions),
-          richtext: null,
-          server: false,
-        })
-      );
-    };
-  }, []);
+      pending?.resolvers.forEach((resolve) => resolve(null));
+    },
+    []
+  );
 
   const renderRich = useCallback(
-    (
-      value: IExpressionValue,
-      expressions: IExpressionSchema[] = []
-    ): Promise<IRenderedExpression> =>
-      new Promise<IRenderedExpression>((resolve) => {
+    (value: IExpressionValue): Promise<IRenderedExpression | null> =>
+      new Promise<IRenderedExpression | null>((resolve) => {
         // Coalesce calls per consumer: rapid live updates collapse to the
         // newest AST; every awaiting caller gets that newest rendering.
         pendingRef.current = {
           value,
-          expressions,
           resolvers: [...(pendingRef.current?.resolvers ?? []), resolve],
         };
 
@@ -208,20 +137,7 @@ export const useRenderExpression = (): IUseRenderExpressionResult => {
           pendingRef.current = null;
           if (!job) return;
           lastRunRef.current = Date.now();
-          let outcome: IRenderedExpression;
-          if (!job.value?.exp) {
-            outcome = { text: '', richtext: null, server: false };
-          } else {
-            const served = await renderViaServer(job.value);
-            setLastServerRendering(served !== null);
-            outcome = served
-              ? { ...served, server: true }
-              : {
-                  text: renderExpressionToText(job.value, job.expressions),
-                  richtext: null,
-                  server: false,
-                };
-          }
+          const outcome = job.value?.exp ? await renderViaServer(job.value) : null;
           job.resolvers.forEach((r) => r(outcome));
         };
 
@@ -240,10 +156,10 @@ export const useRenderExpression = (): IUseRenderExpressionResult => {
   );
 
   const render = useCallback(
-    (value: IExpressionValue, expressions: IExpressionSchema[] = []): Promise<string> =>
-      renderRich(value, expressions).then((r) => r.text),
+    (value: IExpressionValue): Promise<string | null> =>
+      renderRich(value).then((r) => r?.text ?? null),
     [renderRich]
   );
 
-  return { render, renderRich, serverRendering };
+  return { render, renderRich };
 };

package/src/components/form/fields/Field.tsx

@@ -2,7 +2,6 @@ import {
   IReqoreLabelProps,
   ReqoreCheckbox,
   ReqoreControlGroup,
-  ReqoreSkeleton,
   ReqoreSpan,
 } from '@qoretechnologies/reqore';
 import { IWithReqoreSize } from '@qoretechnologies/reqore/dist/types/global';
@@ -38,6 +37,7 @@ import { IDataSchemaDefinition } from './schema-definition/types';
 // Direct import — circular dep (FormEngine → TemplateField → FormField → FormEngine) is safe
 // because modules are all loaded before any component renders
 import { FormEngine } from '../engine/FormEngine';
+import { FormFieldsSkeleton } from '../engine/FormFieldsSkeleton';
 
 /** Soft Qore types (softint, softstring, …) render as their concrete base —
  * the soft/hard distinction is value-level, not UI. */
@@ -345,7 +345,8 @@ export const FormField = <T extends TFormFieldType>({
 
       case 'hash': {
         if (argSchemaLoading) {
-          return <ReqoreSkeleton height='80px' />;
+          // A hash renders a nested FORM, so it waits in the shape of one.
+          return <FormFieldsSkeleton rows={2} />;
         }
         if (finalArgSchema) {
           return (

package/src/components/form/fields/allowed-values/AllowedValues.tsx

@@ -40,13 +40,23 @@ const DISALLOW_COMPACT_AO_TYPES = ['connection'];
  * Whether a creatable field's value is carried by the chip picker rather than
  * by a raw editor with a suggestion list beside it.
  *
- * `string` only, and only with something to suggest. Every other shape a
+ * String-valued only, and only with something to suggest. Every other shape a
  * creatable field can declare either does not fit a one-line chip (a document
  * — `long-string`, `binary`, `data`; a hash; a list) or would come back out of
  * one as a string (a number, a date), and a field with nothing to offer is
  * better served by the editor it has always had. Those keep today's rendering:
  * the raw editor, with the saved-and-suggested picker under it.
  *
+ * `select-string` counts, and leaving it out was the bug. A picker field
+ * declares its storage type (`*string`) and its `ui_type` (`select-string`),
+ * and by the time a schema reaches here the two have been flattened to one:
+ * `type` arrives as `select-string`. So this returned false for every such
+ * field and NEITHER renderer stood down — the picker drew the value, and the
+ * saved-and-suggested list drew the same candidates again underneath it. A
+ * test's Service and Method fields showed 183 and 7 items twice over, in two
+ * controls that set one value. A select-string's value IS a string and fits the
+ * chip, which is the only thing this predicate is really asking.
+ *
  * Both the renderer of the picker (`FieldAllowedValues`) and the renderer of
  * the raw editor (`AutoFormField`, `FormField`) ask this, so that exactly one
  * of them draws the value.
@@ -55,7 +65,8 @@ export const rendersCreatableValueSelect = (
   type?: string,
   allowCreation?: boolean,
   items?: unknown[]
-): boolean => !!allowCreation && type === 'string' && count(items) > 0;
+): boolean =>
+  !!allowCreation && (type === 'string' || type === 'select-string') && count(items) > 0;
 
 export const FieldAllowedValuesCheckGroup = memo(
   ({

package/src/components/form/fields/auto/AutoFormField.stories.tsx

@@ -54,22 +54,24 @@ const waitForText = async (text: string | RegExp) => {
 
 // --- reqraft behavioral stories (kept from the field-migration batch) -------
 
-/** Auto type, no value — the picker is shown and the field area prompts for a type. */
+/** Untyped, no value — the field opens on an editor to type into, never on a type question. */
 export const Empty: Story = {
   args: {},
   parameters: {
     docs: {
       description: {
         story:
-          'Renders AutoFormField with no value or defaultType — the type picker is shown and the field area prompts the operator to pick a data type.',
+          'Renders AutoFormField with no value or defaultType. The field opens on a text editor to type into; it does not show a type picker or ask for a data type.',
       },
     },
   },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
-    // The IDE auto resolves its type in a mount effect — assert asynchronously.
-    await expect(await canvas.findByText('Please select data type')).toBeInTheDocument();
-    // No concrete field is rendered yet.
+    // The type resolves in a mount effect — assert asynchronously.
+    await waitFor(() => expect(canvasElement.querySelector('textarea')).toBeInTheDocument(), {
+      timeout: 5000,
+    });
+    await expect(canvas.queryByText('Please select data type')).not.toBeInTheDocument();
     await expect(canvasElement.querySelector('input[type="number"]')).not.toBeInTheDocument();
   },
 };
@@ -179,7 +181,7 @@ export const Nullable: Story = {
   },
 };
 
-/** The picker can be restricted to a subset of types via `allowedTypes`. */
+/** A field declaring several allowed types still picks between them. */
 export const AllowedTypesSubset: Story = {
   args: {
     allowedTypes: [
@@ -191,14 +193,14 @@ export const AllowedTypesSubset: Story = {
     docs: {
       description: {
         story:
-          'Renders AutoFormField with allowedTypes restricted to Integer and Text — the picker badge shows 2 available types instead of the full 14.',
+          'Renders AutoFormField with allowedTypes restricted to Integer and Text. The type picker offers those 2 types (its badge reads 2), and the field can be typed into meanwhile without being asked for a data type.',
       },
     },
   },
-  async play() {
+  async play({ canvasElement }) {
     // The picker badge reflects the restricted list — 2 instead of 14.
-    await waitForText('Please select data type');
     await waitForText('2');
+    await expect(within(canvasElement).queryByText('Please select data type')).not.toBeInTheDocument();
   },
 };
 
@@ -206,31 +208,35 @@ export const AllowedTypesSubset: Story = {
 export const NoSoftTypes: Story = {
   args: {
     noSoft: true,
+    /* The picker belongs to a value with a type: an untyped field that is
+       empty is typed into, and one holding text has resolved to `string`. */
+    defaultType: 'auto',
+    value: 'some text',
   },
   parameters: {
     docs: {
       description: {
         story:
-          'Renders AutoFormField with noSoft enabled — the soft* type variants are hidden and the picker badge reads 9 instead of 14.',
+          'Renders an untyped AutoFormField holding a text value with noSoft enabled. The picker for the type the value resolved to leaves out the soft* variants, so its badge reads 9 instead of 14.',
       },
     },
   },
-  async play() {
-    await waitForText('Please select data type');
+  async play({ canvasElement }) {
     await waitForText('9');
+    await expect(within(canvasElement).queryByText('Please select data type')).not.toBeInTheDocument();
   },
 };
 
 /**
  * The whole point of the migration: a `FormEngine` schema with a field typed
- * `auto` renders the picker for free, via FormEngine → TemplateField → auto.
+ * `auto` renders the untyped editor for free, via FormEngine → TemplateField → auto.
  */
 export const ViaFormEngine: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          'Renders a FormEngine schema whose single option is typed as auto — the engine flows through TemplateField and renders the AutoFormField picker without any extra wiring.',
+          'Renders a FormEngine schema whose single option is typed as auto. The engine flows through TemplateField to the untyped editor without any extra wiring: an editor to type into, with no data-type question.',
       },
     },
   },
@@ -255,15 +261,76 @@ export const ViaFormEngine: Story = {
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // Generous timeout: findByText defaults to 1s, which flakes under CI load
-    // while the engine boots the auto field's type picker (the rest of the suite
-    // waits ~10s).
+    // while the engine boots the auto field (the rest of the suite waits ~10s).
     await expect(
       await canvas.findByText('My Auto Field', undefined, { timeout: 10000 })
     ).toBeInTheDocument();
-    // The auto field renders its type picker inside the engine-driven form.
+    // The untyped field opens on an editor inside the engine-driven form, and
+    // never asks for a data type.
+    await waitFor(() => expect(canvasElement.querySelector('textarea')).toBeInTheDocument(), {
+      timeout: 10000,
+    });
+    await expect(canvas.queryByText('Please select data type')).not.toBeInTheDocument();
+  },
+};
+
+/**
+ * The ⋮ on that same field holds one group — "Set Custom Value" and the data
+ * types under it — and opens it, rather than asking for a click to reach the
+ * only thing on offer.
+ */
+export const ViaFormEngineMenuOpensItsOnlyGroup: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The untyped field\'s ⋮ holds nothing but the "Set Custom Value" section, so that section is already open: the data types are one click from the menu, not two. Where a menu holds more than one group the sections stay shut, because there the click is the choice.',
+      },
+    },
+  },
+  render: () => {
+    const [val, setVal] = useState<any>({});
+    return (
+      <FormEngine
+        name='autoFieldMenuDemo'
+        options={{
+          myAutoField: {
+            type: 'auto',
+            ui_type: 'auto',
+            display_name: 'My Auto Field',
+            preselected: true,
+          },
+        }}
+        value={val}
+        onChange={(_n, v) => setVal(v)}
+      />
+    );
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
     await expect(
-      await canvas.findByText('Please select data type', undefined, { timeout: 10000 })
+      await canvas.findByText('My Auto Field', undefined, { timeout: 10000 })
     ).toBeInTheDocument();
+
+    const menu = await waitFor(
+      () => {
+        const el = canvasElement.querySelector('.template-more');
+        expect(el).toBeTruthy();
+        return el as HTMLElement;
+      },
+      { timeout: 10000 }
+    );
+    await userEvent.click(menu);
+
+    // The section still names its rows...
+    await waitFor(
+      () => expect(document.body.textContent).toContain('Set Custom Value'),
+      { timeout: 10000 }
+    );
+    // ...and the rows are there to click, with no header click in between.
+    await waitFor(() => expect(document.body.textContent).toContain('Ordered key-value pair'), {
+      timeout: 10000,
+    });
   },
 };