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

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.
@@ -106,9 +125,42 @@ const matchesTemplateValue = (item: TReqoreDropdownItem, value: string): boolean
 /** Splits `$data:{a.b.c}` into its key (`$data`) and inner path (`a.b.c`). */
 const TEMPLATE_TOKEN_PATH = /^(\$[A-Za-z_][\w-]*):\{(.*)\}$/;
 
+/**
+ * The KEY-LESS spelling — `$.create.status`, `$._case.mode`, `$.order[0].sku`.
+ *
+ * A host may name its own references without a key and without braces: a Qorus
+ * test reads what a step captured as `$.create`, and that is the whole token.
+ * The path is captured WITH its leading `.`, so a prefix comparison is between
+ * two strings of the same shape and `$.create` still ends at a path boundary
+ * inside `$.create.status`.
+ *
+ * Deliberately strict — a root segment, then any number of further `.field`
+ * steps and `[0]` indices, and nothing else — so it cannot claim a keyed token
+ * (which carries a `:`) or a bare `$word`.
+ */
+const KEYLESS_TOKEN_PATH = /^\$((?:\.[A-Za-z_][\w-]*|\[\d+\])+)$/;
+
+/**
+ * "No key" is a key of its own.
+ *
+ * `findTemplateByPath` refuses to name a value from an item under a different
+ * key, and the key-less grammar has to take part in that rule rather than sit
+ * outside it: a `$data:{create.status}` item must not name `$.create.status`,
+ * and a `$.create` item must not name `$data:{create.status}`. Every keyed
+ * token's key begins with `$`, so the empty string can never collide with one.
+ */
+const NO_TOKEN_KEY = '';
+
 const getTokenPath = (value?: unknown): { key: string; path: string } | undefined => {
-  const match = typeof value === 'string' ? TEMPLATE_TOKEN_PATH.exec(value) : null;
-  return match ? { key: match[1], path: match[2] } : undefined;
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const keyed = TEMPLATE_TOKEN_PATH.exec(value);
+  if (keyed) {
+    return { key: keyed[1], path: keyed[2] };
+  }
+  const keyless = KEYLESS_TOKEN_PATH.exec(value);
+  return keyless ? { key: NO_TOKEN_KEY, path: keyless[1] } : undefined;
 };
 
 /**
@@ -124,7 +176,12 @@ const getTokenPath = (value?: unknown): { key: string; path: string } | undefine
  *
  * The match must break at a path boundary (`.` or `[`) so `choicesOther` is
  * never named after `choices`, and the token keys must agree so a `$config:`
- * item never names a `$data:` value.
+ * item never names a `$data:` value — "no key" included, so the key-less
+ * grammar and the keyed one never name each other's references.
+ *
+ * Both grammars arrive here: `$data:{create.choices[0]}` and the key-less
+ * `$.create.status` are the same question asked in two spellings, and a
+ * catalogue written in either one names the walks its author took past it.
  */
 export const findTemplateByPath = (
   templates: IReqoreFormTemplates,
@@ -239,9 +296,14 @@ export const resolveTemplateLabel = (
  * never fetches one), and there the raw token is the only thing left to show.
  * Showing it as `$data:{…}` renders a value as code; showing the path renders
  * it as a name, which is the honest floor.
+ *
+ * Only a BRACED wrapper is stripped, because only a braced wrapper is one.
+ * A key-less `$._case.mode` stripped of its `$` reads as `._case.mode`, which
+ * is neither the reference nor a name for it; with nothing to call it, the
+ * reference as written is the honest answer.
  */
 export const getTemplateReferencePath = (value: string): string =>
-  getTokenPath(value)?.path ?? value;
+  (typeof value === 'string' ? TEMPLATE_TOKEN_PATH.exec(value)?.[2] : undefined) ?? value;
 
 /**
  * The best available name for a reference, for a surface that must show
@@ -258,43 +320,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 +559,7 @@ export const buildTemplates = (
 
         return item;
       }
-    );
+    ).sort(byLabel);
 
   return {
     items: Object.values(templates).map(
@@ -544,6 +597,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']) {
@@ -1295,6 +1320,22 @@ export const _validateField = (
             continue;
           }
 
+          /* An option whose dependencies are not fulfilled is not part of this
+             object, so it cannot make the object invalid.
+
+             The form already takes that view — it HIDES such an option — and
+             the two disagreeing is a trap with no way out of it: a test whose
+             subject moved from a versioned kind to a service keeps the
+             `subject_iface_version` it no longer has a field for, and Submit
+             goes dead naming an option that is nowhere on screen. Nulling the
+             value does not help either, because a null is still a value the
+             loop reaches.
+
+             A REQUIRED option with unfulfilled dependencies is unaffected:
+             `getUnresolvedRequiredOptions` above reports it as `dependency`
+             before this loop runs, and it is the only owner of that question.
+             This branch was therefore only ever able to fail an option the
+             author could not see and did not need. */
           if (
             (optionSchema?.[option] as TQorusFormFieldSchema)?.depends_on &&
             !hasAllDependenciesFullfilled(
@@ -1303,7 +1344,7 @@ export const _validateField = (
               optionSchema
             )
           ) {
-            return invalidResult(`Option ${option} dependencies are not fulfilled`);
+            continue;
           }
 
           const optionResult =
@@ -1512,6 +1553,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,30 +1592,34 @@ 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;
         }
 
-        // A slot with no operand at all is a missing value, not a crash:
-        // judge it as an empty value of the type the catalogue expects.
-        const result = validateFieldWithResult(
-          argValue?.type ?? argDefinition?.ui_type,
-          argValue?.value,
-          {
-            expressions,
-            allowed_values: argDefinition?.allowed_values,
-            element_allowed_values: argDefinition?.element_allowed_values,
-            has_to_have_value: argDefinition?.required,
-          }
-        );
+        /* A slot with no operand at all is judged as what it is — a missing
+           value — rather than read for a `type` it does not have.
+
+           An operand that HOLDS something is judged by the envelope's own type,
+           or — when the envelope carries none (a raw parse operand widened
+           without a `ui_type`, a slot reset by a type change) — by the type the
+           catalogue declares. Without that fallback `_validateField` refuses it
+           for "Missing type" however right the value is. */
+        const operandType =
+          argValue?.type ?? (argValue?.value === undefined ? undefined : argDefinition?.ui_type);
+        const result = validateFieldWithResult(operandType, argValue?.value, {
+          expressions,
+          allowed_values: argDefinition?.allowed_values,
+          element_allowed_values: argDefinition?.element_allowed_values,
+          has_to_have_value: argDefinition?.required,
+        });
 
         if (!result.isValid) {
           return withContext(
             result,
-            `Value for argument ${index + 1} ("${argDefinition?.display_name}") is invalid`
+            `Value for argument ${index + 1} ("${argLabel}") is invalid`
           );
         }
       }
@@ -1818,19 +1888,28 @@ export const getUnresolvedRequiredOptions = (
 /**
  * Split a dependency entry into the sibling it names and how its value is compared.
  *
- * Three forms: `name` (the sibling must simply have a value), `name=value` (it must
- * have exactly that value) and `name!=value` (it must have a value, and not that
- * one). The negative form is what lets a field say it applies to every variant of a
- * record but one — spelling that as an `any-of` list of every other variant is both
- * unreadable in the "Depends on" lock and silently wrong the moment a variant is
- * added.
+ * Four forms: `name` (the sibling must simply have a value), `!name` (it must have
+ * none), `name=value` (it must have exactly that value) and `name!=value` (it must
+ * have a value, and not that one). The negative comparison is what lets a field say
+ * it applies to every variant of a record but one — spelling that as an `any-of`
+ * list of every other variant is both unreadable in the "Depends on" lock and
+ * silently wrong the moment a variant is added.
  *
  * `!=` deliberately requires the sibling to be answered: "not X" is a statement about
  * an answer, so an unanswered sibling does not satisfy it and the field stays locked.
+ *
+ * `!name` is the form that statement cannot make. Two options that exclude one
+ * another (a converter that reads NodeSet2 and one that writes OpenAPI 3) each
+ * apply only while the OTHER has not been answered at all, and `name!=value` cannot
+ * say that: it requires an answer. Being a predicate like any other, it composes
+ * with the AND of the top-level entries and the OR of a nested list for free.
+ *
+ * `!` binds to the whole entry, so `!name` never carries a value; `!=` is checked
+ * first, which is what keeps `name!=value` from being read as a leading `!`.
  */
 export const parseDependency = (
   dependency: string
-): { name: string; op?: '=' | '!='; value?: string } => {
+): { name: string; op?: '=' | '!=' | '!'; value?: string } => {
   const neqIdx = dependency.indexOf('!=');
   if (neqIdx !== -1) {
     return {
@@ -1849,9 +1928,25 @@ export const parseDependency = (
     };
   }
 
+  if (dependency.startsWith('!')) {
+    return { name: dependency.substring(1), op: '!' };
+  }
+
   return { name: dependency };
 };
 
+/** Whether the named sibling currently holds a value this form accepts. */
+const siblingHasValue = (
+  name: string,
+  options: TQorusForm,
+  optionsSchema?: IQorusFormSchema
+): boolean =>
+  validateField(options?.[name]?.type, options?.[name]?.value, {
+    ...(optionsSchema?.[name] as unknown as IFieldValidationProps),
+    options,
+    optionSchema: optionsSchema,
+  });
+
 /** Whether one dependency entry holds against the current form values. */
 const isDependencyFulfilled = (
   dependency: string,
@@ -1860,6 +1955,15 @@ const isDependencyFulfilled = (
 ): boolean => {
   const { name, op, value } = parseDependency(dependency);
 
+  if (op === '!') {
+    // "Has no value" is true of a field the form has not materialized at all —
+    // there is nothing there to be the value. So an absent sibling satisfies
+    // this, exactly as it satisfies the bare form below: neither has an answer
+    // to judge, and a mutual exclusion that locked both halves until one of
+    // them was added would offer the author no way in.
+    return !options?.[name] || !siblingHasValue(name, options, optionsSchema);
+  }
+
   if (op) {
     const optValue = options?.[name]?.value;
     if (optValue == null) {
@@ -1868,17 +1972,12 @@ const isDependencyFulfilled = (
     return op === '=' ? String(optValue) === value : String(optValue) !== value;
   }
 
-  return options?.[name]
-    ? validateField(options[name].type, options[name].value, {
-        ...(optionsSchema?.[name] as unknown as IFieldValidationProps),
-        options,
-        optionSchema: optionsSchema,
-      })
-    : true;
+  return options?.[name] ? siblingHasValue(name, options, optionsSchema) : true;
 };
 
 export const hasAllDependenciesFullfilled = (
-  dependencies: string[] | string[][],
+  /** Every entry must hold; a nested list is an ANY of its entries. Mixed freely. */
+  dependencies: ReadonlyArray<string | readonly string[]>,
   options: TQorusForm,
   optionsSchema?: IQorusFormSchema
 ): boolean => {
@@ -1886,20 +1985,20 @@ export const hasAllDependenciesFullfilled = (
     return true;
   }
 
-  return dependencies.every((dependency: string | string[]) => {
+  return dependencies.every((dependency) => {
     // A nested list is an ANY. It used to look each entry up as a whole form-field
     // name, so a `name=value` entry inside one found no field and returned `true`
     // unconditionally — the any-of group was satisfied by anything at all, while
     // CompactRow's lock rendered those same entries as real comparisons. Both halves
     // now go through one parser, so the grammar cannot mean two things.
     if (isArray(dependency)) {
-      return (dependency as string[]).some((dep) =>
+      return (dependency as readonly string[]).some((dep) =>
         isDependencyFulfilled(dep, options, optionsSchema)
       );
     }
 
     return isString(dependency)
-      ? isDependencyFulfilled(dependency as string, options, optionsSchema)
+      ? isDependencyFulfilled(dependency, options, optionsSchema)
       : true;
   });
 };

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: {},