@qoretechnologies/reqraft 0.10.55-pr.124.g77dd26c → 0.10.55

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

package/src/stories/storyNetwork.ts

@@ -0,0 +1,92 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// Where a story's network goes: the instance its Reqraft points at, the URLs
+// its mocks must intercept, and the requests every story is mocked for.
+//
+// `query()` and `ReqraftWebSocket` build absolute URLs from the configured
+// instance, and both mock layers match on the host as well as the path —
+// storybook-addon-mock keys on `host + pathname`, mock-socket on the URL minus
+// its query. A mock written against a hard-coded host stops matching the moment
+// the instance is overridden, and the request goes out to the real network
+// instead, silently. Build mock URLs with the helpers below.
+import { defaultQorusTypes } from '../hooks/useQorusTypes';
+import { buildReqraftApiUrl } from '../utils/fetch';
+import { buildReqraftSocketUrl } from '../utils/websocket';
+
+/**
+ * What storybook-addon-mock accepts as a response. Anything else — a bare
+ * number or string — fails the addon's validation and the entry is kept but
+ * never matched, so the request goes out to the network with no warning.
+ */
+export type TStoryMockResponse = object | ((request: unknown) => unknown);
+
+export interface IStoryMockRequest {
+  url: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  status: number;
+  response: TStoryMockResponse;
+}
+
+/**
+ * The instance every story's Reqraft is initialized with. Override it with
+ * `REACT_APP_QORUS_INSTANCE` (or `QORUS_INSTANCE`) to run live stories against
+ * your own Qorus; mocks built from it follow the override.
+ */
+export const STORY_QORUS_INSTANCE =
+  process.env.REACT_APP_QORUS_INSTANCE || 'https://hq.qoretechnologies.com:8092/';
+
+/** The URL `query()` requests for `path`. */
+export const storyApiUrl = (path: string): string =>
+  buildReqraftApiUrl(STORY_QORUS_INSTANCE, path);
+
+/**
+ * The URL `ReqraftWebSocket` dials for `path`, token omitted — mock-socket
+ * matches servers without the query string.
+ */
+export const storySocketUrl = (path: string): string =>
+  buildReqraftSocketUrl(STORY_QORUS_INSTANCE, path);
+
+/** A GET of `path` answered with `response`. */
+const mockGet = (path: string, response: TStoryMockResponse): IStoryMockRequest[] => [
+  { url: storyApiUrl(path), method: 'GET', status: 200, response },
+];
+
+/**
+ * The type catalogue, pinned to the built-in list. `useQorusTypes` uses a
+ * reachable server's list *instead of* the built-in one, so an unmocked story
+ * renders whichever labels that server happens to have — and every FormEngine
+ * shows its loading skeleton until the request settles, which against an
+ * unreachable instance is never.
+ */
+const QORUS_TYPE_INFO_MOCK_DATA = mockGet('system/qorus-type-info', defaultQorusTypes);
+
+/**
+ * The system expression catalogue, empty. `useExpressions` fetches it whenever
+ * functions are allowed — even when the story passes its own list, which is
+ * merged in as extras — and TemplateField shows a skeleton in place of "Use
+ * Expression" until it arrives. Stories that need functions provide them
+ * (`expressions`, or their own `mockData` for this URL).
+ */
+const EXPRESSIONS_CATALOGUE_MOCK_DATA = mockGet('system?action=expressions&context=ui', []);
+
+/**
+ * `ReqraftWebSocket`'s server probe, which every reconnect attempt awaits
+ * before it dials. Unanswered, no attempt is ever made — a mock socket server
+ * that comes back is never reconnected to, and one that stays down is never
+ * given up on. The probe only needs an answer; its body is not read.
+ */
+const SERVER_STATUS_MOCK_DATA = mockGet('system/pid', {});
+
+/**
+ * Requests components make on their own, whatever the story is about —
+ * mounting a FormEngine fetches the type catalogue; allowing functions fetches
+ * the expression catalogue; a reconnecting socket probes the server.
+ * Registered for every story as storybook-addon-mock's `globalMockData`
+ * (`.storybook/preview.tsx`, and mirrored for the Vitest run in
+ * `.storybook/vitest.setup.ts`); a story's own `mockData` entry for the same
+ * URL takes precedence.
+ */
+export const GLOBAL_STORY_MOCK_DATA: IStoryMockRequest[] = [
+  ...QORUS_TYPE_INFO_MOCK_DATA,
+  ...EXPRESSIONS_CATALOGUE_MOCK_DATA,
+  ...SERVER_STATUS_MOCK_DATA,
+];