@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/ticketThread/index.ts

@@ -0,0 +1,6 @@
+export { TicketThread, ticketMessageDomId } from './TicketThread';
+export type {
+  ITicketThreadAttachment,
+  ITicketThreadMessage,
+  ITicketThreadProps,
+} from './TicketThread';

package/src/helpers/common.ts

@@ -174,6 +174,25 @@ export const splitByteSize = (value?: string): [number | undefined, string | und
   return [amount?.[0] ? Number(amount[0]) : undefined, unit?.[0]];
 };
 
+/** Human-readable file size, e.g. `"12.3 KB"` — whole bytes below 1 KiB, one
+ *  decimal above. Shared by the ticket thread / references attachment rows. */
+export const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(1)} ${units[unit]}`;
+};
+
+/** True when a MIME content type is an image (`image/*`). */
+export const isImage = (contentType: string): boolean => contentType.startsWith('image/');
+
 // URL value splitting (IDE `urlField.tsx` behavior). Lives here rather than
 // in the Url component so `validations.ts` can use it without pulling the
 // component chain into non-DOM consumers (jest).

package/src/helpers/scrollbar.ts

@@ -0,0 +1,32 @@
+import { css } from 'styled-components';
+
+/*
+ * The thin, unobtrusive scrollbar the Qorus surfaces use — a transparent track and a
+ * translucent rounded thumb — in place of the platform default, which reads as heavy
+ * chrome inside a dark panel. Drop it into any `styled` scroll container:
+ *
+ *   const Scroll = styled.div`
+ *     overflow-y: auto;
+ *     ${thinScrollbar}
+ *   `;
+ *
+ * webkit-only on purpose: setting `scrollbar-width` as well lets Chromium override this
+ * custom 6px with its own wider "thin", so the two disagree. Firefox keeps its native
+ * bar, which is already slim.
+ */
+export const thinScrollbar = css`
+  &::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  &::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.15);
+    border-radius: 3px;
+  }
+  &::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.28);
+  }
+`;

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

@@ -35,6 +35,12 @@ export const Get: Story = {
     method: 'GET',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useFetch demo that issues a GET against /public/info on mount and displays the returned Qorus system info as a tree.',
+      },
+    },
     mockData: [
       {
         // An array of mock objects which will add in every story
@@ -66,6 +72,12 @@ export const Put: Story = {
     method: 'PUT',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useFetch demo that issues a PUT against /public/info on mount and displays the returned success status.',
+      },
+    },
     mockData: [
       {
         // An array of mock objects which will add in every story
@@ -88,6 +100,12 @@ export const Post: Story = {
     method: 'POST',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useFetch demo that issues a POST against /public/info on mount and displays the returned success status.',
+      },
+    },
     mockData: [
       {
         // An array of mock objects which will add in every story
@@ -110,6 +128,12 @@ export const Del: Story = {
     method: 'DELETE',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useFetch demo that issues a DELETE against /public/info on mount and displays the returned success status.',
+      },
+    },
     mockData: [
       {
         // An array of mock objects which will add in every story
@@ -132,6 +156,12 @@ export const Error409: Story = {
     method: 'POST',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useFetch demo that issues a POST returning a 409 error — the hook exposes errorData and the Qorus stack trace is rendered in place of the response.',
+      },
+    },
     mockData: [
       {
         // An array of mock objects which will add in every story

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

@@ -1,5 +1,6 @@
 import { ReqoreButton, ReqoreControlGroup, ReqoreP } from '@qoretechnologies/reqore';
 import { StoryObj } from '@storybook/react-vite';
+import { useRef } from 'react';
 import { fireEvent, within } from 'storybook/test';
 import { storiesStorageMock } from '../../../__tests__/ mock';
 import { testsWaitForText } from '../../../__tests__/utils';
@@ -35,6 +36,12 @@ export const DefaultValue: Story = {
     method: 'GET',
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useReqraftStorage demo where the server returns no stored value — the hook falls back to the default and displays it.',
+      },
+    },
     mockData: [
       {
         url: 'https://hq.qoretechnologies.com:8092/api/latest/users?action=current',
@@ -51,6 +58,12 @@ export const DefaultValue: Story = {
 
 export const StorageValue: Story = {
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a useReqraftStorage demo with a value already persisted on the server — the hook loads it and displays it in place of the default.',
+      },
+    },
     mockData: [...storiesStorageMock],
   },
   play: async () => {
@@ -60,6 +73,15 @@ export const StorageValue: Story = {
 
 export const ValueCanBeUpdated: Story = {
   ...StorageValue,
+  parameters: {
+    ...StorageValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftStorage demo with a stored value. When "Update storage" is clicked, the setter writes a new value and the display refreshes to match.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 
@@ -72,8 +94,68 @@ export const ValueCanBeUpdated: Story = {
   },
 };
 
+/**
+ * Regression for the "stale updater clobbers other keys" bug: the storage
+ * updater must persist onto the LATEST storage blob, not the one captured in
+ * its closure. Long-lived callers (an imperative store subscription, a ref to
+ * the mount-time setter) hold an old updater; writing through it must not wipe
+ * keys other hooks wrote in the meantime.
+ */
+export const StaleUpdaterDoesNotClobberOtherKeys: Story = {
+  args: { reqraftOptions: { waitForStorage: true } },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders two useReqraftStorage keys and captures the mount-time setter for the first one (a deliberately STALE updater). After a second key is written, writing through the stale updater must keep the second key intact — proving storage writes merge onto the latest blob rather than a closure copy. This is the regression test for page-visit tracking wiping other stored settings.",
+      },
+    },
+    mockData: [...storiesStorageMock],
+  },
+  render: () => {
+    const [someVal, setSomeVal] = useReqraftStorage<string>('some-path', 'default');
+    const [keyB] = useReqraftStorage<string>('key-b', 'b-default');
+    const [, setKeyB] = useReqraftStorage<string>('key-b', 'b-default');
+    // Capture the mount-time setter — it stays stale once other keys change.
+    const staleSetSomeVal = useRef(setSomeVal);
+
+    return (
+      <ReqoreControlGroup vertical>
+        <ReqoreP>{`some-path: ${someVal}`}</ReqoreP>
+        <ReqoreP>{`key-b: ${keyB}`}</ReqoreP>
+        <ReqoreButton onClick={() => setKeyB('b-written')}>Write B</ReqoreButton>
+        <ReqoreButton onClick={() => staleSetSomeVal.current('a-written')}>
+          Write A (stale)
+        </ReqoreButton>
+      </ReqoreControlGroup>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await testsWaitForText('some-path: This is a storage value');
+    // Write a second key through its own (fresh) updater.
+    await fireEvent.click(canvas.getByText('Write B'));
+    await testsWaitForText('key-b: b-written');
+    // Write the first key through the STALE mount-time updater.
+    await fireEvent.click(canvas.getByText('Write A (stale)'));
+    await testsWaitForText('some-path: a-written');
+    // The stale write must NOT have wiped the second key.
+    await testsWaitForText('key-b: b-written');
+  },
+};
+
 export const ValueCanBeRemoved: Story = {
   ...StorageValue,
+  parameters: {
+    ...StorageValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftStorage demo with a stored value. When "Remove value" is clicked, the remover clears storage and the hook falls back to the default value.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 

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

@@ -106,8 +106,25 @@ const meta = {
 export default meta;
 export type Story = StoryObj<typeof meta>;
 
-export const Default: Story = {};
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with no lifecycle options — the socket stays CLOSED until the operator clicks Connect.',
+      },
+    },
+  },
+};
 export const OpenManually: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo and clicks the Connect action — the socket opens and the onOpen callback fires.',
+      },
+    },
+  },
   play: async ({ args }) => {
     await testsClickButton({ label: 'Connect' });
     await testsWaitForText('Websocket Status: OPEN');
@@ -118,6 +135,14 @@ export const OpenOnMount: Story = {
   args: {
     openOnMount: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with openOnMount enabled — the socket opens immediately after mount without any user action.',
+      },
+    },
+  },
   play: async ({ args }) => {
     await testsWaitForText('Websocket Status: OPEN');
     await expect(args.onOpen).toHaveBeenCalled();
@@ -126,6 +151,15 @@ export const OpenOnMount: Story = {
 
 export const CloseManually: Story = {
   ...OpenOnMount,
+  parameters: {
+    ...OpenOnMount.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo opened on mount. When Disconnect is clicked, the socket transitions to CLOSED and the onClose callback fires.',
+      },
+    },
+  },
   play: async ({ args, ...rest }) => {
     await OpenOnMount.play({ args, ...rest });
     await testsClickButton({ label: 'Disconnect' });
@@ -141,6 +175,14 @@ export const Reconnects: Story = {
     maxReconnectTries: 5,
     openOnMount: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with reconnect enabled. When the server is killed, the socket transitions to CONNECTING and then back to OPEN once the server returns.',
+      },
+    },
+  },
   play: async ({ args, ...rest }) => {
     await OpenOnMount.play({ args, ...rest });
     await testsClickButton({ label: 'Kill' });
@@ -159,6 +201,12 @@ export const ReconnectFails: Story = {
     reconnectInterval: 500,
   },
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with a low maxReconnectTries. When the server never returns, the socket exhausts its reconnect attempts and fires onReconnectFailed.',
+      },
+    },
     jest: {
       timeout: 60000,
     },
@@ -178,6 +226,14 @@ export const SendMessage: Story = {
     includeSentMessagesInState: true,
     useState: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with useState enabled. When Send is clicked, the message is dispatched and the echoed reply appears in the accumulated message list.',
+      },
+    },
+  },
   play: async ({ args, ...rest }) => {
     await OpenOnMount.play({ args, ...rest });
     await testsClickButton({ label: 'Send' });
@@ -197,6 +253,14 @@ export const WithLogs: Story = {
     useState: true,
     reconnectInterval: 1500,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo with includeLogMessagesInState. Connect / disconnect / reconnect lifecycle events are captured as log entries alongside regular messages.',
+      },
+    },
+  },
   play: async ({ args, ...rest }) => {
     await Reconnects.play({ args, ...rest });
 
@@ -206,6 +270,15 @@ export const WithLogs: Story = {
 
 export const ClearsMessages: Story = {
   ...SendMessage,
+  parameters: {
+    ...SendMessage.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the useReqraftWebSocket demo after sending a message. When Clear is clicked, the accumulated message list is emptied.',
+      },
+    },
+  },
   play: async ({ args, ...rest }) => {
     await SendMessage.play({ args, ...rest });
     await testsClickButton({ label: 'Clear' });
@@ -353,6 +426,14 @@ export const MultipleConnections: Story = {
     includeLogMessagesInState: true,
     useState: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders three panels that each call useReqraftWebSocket against the same URL — proves the connections share one pooled underlying WebSocket while keeping independent message state.',
+      },
+    },
+  },
   // @ts-expect-error customprops
   render: (args: IUseReqraftWebSocketOptions) => {
     const [conectionStatus, setConnectionStatus] = useState<string>('CLOSED');
@@ -405,6 +486,15 @@ export const MultipleConnectionsOpenOnMount: Story = {
     ...MultipleConnections.args,
     openOnMount: true,
   },
+  parameters: {
+    ...MultipleConnections.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders three pooled useReqraftWebSocket panels with openOnMount — all three transition to OPEN over the shared underlying socket without any user action.',
+      },
+    },
+  },
   play: async ({ args }) => {
     await testsWaitForText('First Connection Status: OPEN');
     await testsWaitForText('Second Connection Status: OPEN');
@@ -420,6 +510,15 @@ export const MultipleConnectionsClosedAtOnce: Story = {
     ...MultipleConnections.args,
     openOnMount: true,
   },
+  parameters: {
+    ...MultipleConnections.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders three pooled useReqraftWebSocket panels. When Close All closes the shared socket, every consumer transitions to CLOSED at once and each panel logs its close handler.',
+      },
+    },
+  },
   play: async (args) => {
     await MultipleConnectionsOpenOnMount.play(args);
 
@@ -436,6 +535,15 @@ export const ConnectionIsClosedWhenAllUsersAreClosed: Story = {
     ...MultipleConnections.args,
     openOnMount: true,
   },
+  parameters: {
+    ...MultipleConnections.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders three pooled useReqraftWebSocket panels. Closing them one by one keeps the shared socket OPEN until the last consumer unmounts, then it closes.',
+      },
+    },
+  },
   play: async (args) => {
     await MultipleConnectionsOpenOnMount.play(args);
 
@@ -454,6 +562,15 @@ export const MultipleConnectionsHaveCustomHandlers: Story = {
     ...MultipleConnections.args,
     openOnMount: true,
   },
+  parameters: {
+    ...MultipleConnections.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders three pooled useReqraftWebSocket panels. Each panel attaches its own message handler, and sending a message triggers the handlers of only the connections still open.',
+      },
+    },
+  },
   play: async (args) => {
     const canvas = within(args.canvasElement);
 
@@ -480,6 +597,15 @@ export const MultipleConnectionsHaveCustomHandlers: Story = {
 
 export const MultipleConnectionsCanBeDisconnectedAndReconnected: Story = {
   ...MultipleConnectionsHaveCustomHandlers,
+  parameters: {
+    ...MultipleConnectionsHaveCustomHandlers.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders three pooled useReqraftWebSocket panels after custom handlers have fired. Disconnecting one and reconnecting another proves individual consumers can toggle without disturbing peers.',
+      },
+    },
+  },
   play: async (args) => {
     await MultipleConnectionsHaveCustomHandlers.play(args);
 

package/src/index.tsx

@@ -10,6 +10,8 @@ export {
   validateOptionWithRequiredGroups,
 } from './helpers/validations';
 export type { IValidationResult } from './helpers/validations';
+export { thinScrollbar } from './helpers/scrollbar';
+export * from './components/imageLightbox';
 export { ReqraftMenu } from './components/menu/Menu';
 export type {
   IReqraftMenuItem,
@@ -33,7 +35,7 @@ export type {
   ICurrentUser,
   ICurrentUserStore,
 } from './stores/currentUser/currentUser';
-export { query } from './utils/fetch';
+export { fetchConfig, query } from './utils/fetch';
 export * from './utils/websocket';
 export { ReqraftLspClient } from './utils/lspClient';
 export type { IReqraftLspClientOptions } from './utils/lspClient';
@@ -52,6 +54,11 @@ export type {
   ILspTextEdit,
   TLspDocumentText,
 } from './utils/lspClient.types';
+export * from './components/composer';
 export * from './components/smartEditor';
 export * from './components/dpqlEditor';
 export * from './components/qonsoleSmartInput';
+export * from './components/supportTicket';
+export * from './components/ticketThread';
+export * from './components/ticketReferences';
+export * from './components/searchFilterBar';

package/src/providers/StorageProvider.tsx

@@ -9,6 +9,23 @@ import { TReqraftStorageValue } from '../hooks/useStorage/useStorage';
 import { currentUserStore } from '../stores/currentUser/currentUser';
 import { IReqraftProviderProps } from './ReqraftProvider';
 
+/**
+ * Apply a single path write onto the current storage blob, seeding a fresh object
+ * when the user has no storage yet.
+ *
+ * `?? {}` is load-bearing: a user who has never written storage has
+ * `storage === undefined | null`, and `set(cloneDeep(undefined), …)` returns
+ * `undefined` (lodash won't set on a nullish target). Without the seed the FIRST
+ * write for such a user — e.g. accepting the cookie-consent banner — persists an
+ * empty body and silently drops the value, so the flag stays unset forever and
+ * the banner never closes. Exported for testing.
+ */
+export const applyStorageWrite = (
+  storage: TReqraftStorage | undefined,
+  path: string,
+  value: unknown
+): TReqraftStorage => set(cloneDeep(storage) ?? {}, path, value);
+
 export interface IReqraftStorageProviderProps
   extends Pick<IReqraftProviderProps, 'waitForStorage'> {
   children: ReactNode;
@@ -53,26 +70,35 @@ export const ReqraftUserProvider = ({ children, waitForStorage }: IReqraftStorag
       includeAppPrefix: boolean = true
     ) {
       const _path = includeAppPrefix ? `${appName}.${path}` : path;
-      const updatedStorage = set(cloneDeep(currentUser?.storage), _path, value);
+      // Base the write on the LATEST storage read straight from the store, not
+      // the blob captured in this callback's closure. A caller holding a stale
+      // updater — e.g. an imperative store subscription created on mount, before
+      // other keys had loaded — would otherwise persist an out-of-date blob and
+      // wipe every key written to storage since its closure was captured.
+      const latestStorage = currentUserStore.getState().currentUser?.storage;
+      const updatedStorage = applyStorageWrite(latestStorage, _path, value);
 
       updateCurrentUserStorage(updatedStorage);
 
       load({ body: { storage: updatedStorage } });
     },
-    [appName, currentUser?.storage, load, updateCurrentUserStorage]
+    [appName, load, updateCurrentUserStorage]
   );
 
   const removeStorageValue = useCallback(
     function (path: string, includeAppPrefix: boolean = true) {
       const _path = includeAppPrefix ? `${appName}.${path}` : path;
 
-      const updatedStorage = set(cloneDeep(currentUser?.storage), _path, null);
+      // Same as `updateStorage`: mutate the LATEST blob (never a stale closure
+      // copy), seeding a fresh object when there's no storage yet.
+      const latestStorage = currentUserStore.getState().currentUser?.storage;
+      const updatedStorage = applyStorageWrite(latestStorage, _path, null);
 
       updateCurrentUserStorage(updatedStorage);
 
       load({ body: { storage_path: _path } });
     },
-    [appName, currentUser?.storage, load, updateCurrentUserStorage]
+    [appName, load, updateCurrentUserStorage]
   );
 
   const contextValue = useMemo(

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

@@ -6,6 +6,38 @@ import { currentUserStore } from './currentUser';
 
 const meta = {
   title: 'Stores/Current User',
+  parameters: {
+    mockData: [
+      {
+        url: 'https://hq.qoretechnologies.com:8092/api/latest/users?action=current',
+        method: 'GET',
+        status: 200,
+        response: {
+          provider: 'local',
+          username: 'david',
+          name: 'David Nichols',
+          has_default: true,
+          roles: ['admin'],
+          permissions: ['USER-CONTROL'],
+          workflows: [],
+          services: [],
+          jobs: [],
+          mappers: [],
+          vmaps: [],
+          groups: [],
+          fsms: [],
+        },
+      },
+    ],
+  },
+  beforeEach: () => {
+    currentUserStore.setState({
+      currentUser: undefined,
+      loading: false,
+      error: undefined,
+      errorData: undefined,
+    });
+  },
   render: () => {
     const { load, loading, currentUser = {}, errorData } = currentUserStore();
 
@@ -26,6 +58,14 @@ export default meta;
 export type Story = StoryObj<typeof meta>;
 
 export const CurrentUserCanBeLoaded: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a demo that reads currentUserStore — the store loads /users?action=current and the returned user object is displayed as a tree.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('"David Nichols"');
   },
@@ -33,6 +73,15 @@ export const CurrentUserCanBeLoaded: Story = {
 
 export const CurrentUserHasPermissions: Story = {
   ...CurrentUserCanBeLoaded,
+  parameters: {
+    ...CurrentUserCanBeLoaded.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders a demo that calls currentUserStore().hasAnyPermission — the affirmative message renders because the loaded user carries at least one of the requested permissions.',
+      },
+    },
+  },
   render: () => {
     const { hasAnyPermission } = currentUserStore();