@qoretechnologies/reqraft 0.10.10 → 0.10.12

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

@@ -93,6 +93,14 @@ export default meta;
 export type Story = StoryObj<typeof meta>;
 
 export const Basic: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog wired to a mock WebSocket that emits a stream of test log lines — the messages accumulate in the log panel as they arrive.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('This is a message with a link: https://www.qoretechnologies.com');
   },
@@ -103,6 +111,14 @@ export const Filterable: Story = {
   args: {
     filterable: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with the filter input enabled. Typing "error" narrows the visible list to the single ERROR message.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
     await fireEvent.change(document.querySelector('.reqore-input'), { target: { value: 'error' } });
@@ -115,6 +131,14 @@ export const WithTimestamps: Story = {
   args: {
     showTimestamps: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with per-message timestamps enabled — each streamed line is prefixed with its arrival time.',
+      },
+    },
+  },
 };
 
 export const WithDefaultMessages: Story = {
@@ -126,6 +150,14 @@ export const WithDefaultMessages: Story = {
       { message: 'This is another default message', timestamp: '08:00:00.000' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog seeded with two default messages — those lines appear before any messages arrive from the socket.',
+      },
+    },
+  },
 };
 
 export const WithCopyableMessages: Story = {
@@ -133,6 +165,14 @@ export const WithCopyableMessages: Story = {
   args: {
     allowMessageCopy: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with allowMessageCopy — each message row exposes a copy action next to its content.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
   },
@@ -144,6 +184,14 @@ export const WithDeletableMessages: Story = {
     allowMessageCopy: true,
     allowMessageDeletion: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with copy and delete actions on every message. Clicking a message\'s delete action removes just that row from the log.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
     await testsClickButton({ selector: '.reqraft-log-delete-message', nth: 4 });
@@ -155,6 +203,14 @@ export const Pause: Story = {
   args: {
     allowMessageDeletion: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog while messages stream in. Clicking the pause/resume action halts appending new messages until it is clicked again.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('This is another message');
     await testsClickButton({ selector: '.reqraft-log-pause-resume' });
@@ -166,6 +222,14 @@ export const Clear: Story = {
   args: {
     allowMessageDeletion: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with messages streamed in. Clicking the clear action empties the log and the "No messages" empty state is shown.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
     await testsClickButton({ selector: '.reqraft-log-clear' });
@@ -192,6 +256,14 @@ export const FormattedMessages: Story = {
       return { message, ...rest };
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with a messageFormatter that assigns intents by content — WARNING lines colour warning, ERROR lines danger and ALL-CAPS lines info.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
   },
@@ -203,6 +275,14 @@ export const CanSendMessages: Story = {
     canSendMessages: true,
     showTimestamps: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with canSendMessages — an input at the bottom lets the operator send a message back through the socket alongside the incoming stream.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
   },
@@ -214,6 +294,14 @@ export const WithAutoScroll: Story = {
     autoScroll: true,
     style: { height: '200px' },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with autoScroll in a fixed 200px viewport — the log stays pinned to the newest message as new lines arrive.',
+      },
+    },
+  },
   play: async (args) => {
     await Basic.play(args);
   },
@@ -225,6 +313,14 @@ export const WithAutoScrollAndManualScroll: Story = {
     autoScroll: true,
     style: { height: '200px' },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftLog with autoScroll while the operator scrolls the panel manually — auto-scroll pauses so the operator can inspect older messages without being yanked back to the tail.',
+      },
+    },
+  },
   play: async (args) => {
     await WithAutoScroll.play(args);
     await sleep(3000);

package/src/components/menu/Menu.stories.tsx

@@ -27,6 +27,14 @@ export const Basic: Story = {
   args: {
     menu: typedMenu,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with the mock Qorus navigation — sections and items appear in the sidebar with no active path highlighted.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
   },
@@ -36,6 +44,14 @@ export const ActivePath: Story = {
     path: '/Interfaces/mapper',
     menu: typedMenu,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with the /Interfaces/mapper path — the matching menu entry is highlighted as active.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
   },
@@ -47,6 +63,14 @@ export const ActiveMenuItemIntent: Story = {
     menu: typedMenu,
     activeItemIntent: 'success',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with the /Interfaces/mapper path and a "success" activeItemIntent — the active entry uses the success intent for its highlight colour.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
   },
@@ -57,6 +81,14 @@ export const WithDefaultQuery: Story = {
     menu: typedMenu,
     defaultQuery: 'mapper',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with a defaultQuery of "mapper" — the search input is pre-filled and the visible items are narrowed to those matching the query.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
     await expect(document.querySelector('.reqore-input')).toHaveValue('mapper');
@@ -69,6 +101,14 @@ export const Filtered: Story = {
     menu: typedMenu,
     onQueryChange: fn(),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with an onQueryChange handler. Typing "step" into the search filter narrows the visible items to just the matching entries.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
     await fireEvent.change(document.querySelector('.reqore-input'), { target: { value: 'step' } });
@@ -82,6 +122,12 @@ export const Filtered: Story = {
 export const WidthFromStorage: Story = {
   ...ActivePath,
   parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu backed by user storage that already holds a persisted width — the menu mounts at the stored width rather than the default.',
+      },
+    },
     mockData: [...storiesStorageMock],
   },
 };
@@ -93,6 +139,14 @@ export const WithCustomChildren: Story = {
     topChildren: <div style={{ padding: 10 }}>Top Custom Child</div>,
     bottomChildren: <div style={{ padding: 10 }}>Bottom Custom Child</div>,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ReqraftMenu with topChildren and bottomChildren slots — custom nodes appear above and below the menu list.',
+      },
+    },
+  },
   play: async () => {
     await testsWaitForText('Interfaces & More');
     await testsWaitForText('Top Custom Child');

package/src/components/qonsoleSmartInput/QonsoleSmartInput.stories.tsx

@@ -398,6 +398,14 @@ export const BasicMock: Story = {
   args: {
     initialValue: '/list services ',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the QonsoleSmartInput against a mocked Qonsole LSP. Typing "-" after "/list services " opens the flag dropdown with --desc, --limit and --search; pressing Enter accepts the first item without producing a stray double dash.',
+      },
+    },
+  },
   async beforeEach() {
     const server = setupBasicQonsoleMockServer();
     return () => server.close();
@@ -509,6 +517,12 @@ export const LiveQonsoleWithContext: Story = {
   },
   parameters: {
     chromatic: { disable: true },
+    docs: {
+      description: {
+        story:
+          'Renders the QonsoleSmartInput against the real Qonsole LSP with a pre-bound "/use services" context — predictive text is scoped to the services resource via the qonsole/setContext call.',
+      },
+    },
   },
 };
 

package/src/components/smartEditor/SmartEditor.stories.tsx

@@ -72,6 +72,14 @@ export const BasicMock: Story = {
     initialValue: '',
     triggerCharacters: new Set([' ', '.']),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SmartEditor against a mocked LSP server. Typing the "." trigger character sends a completion request and the dropdown mounts with the apple and banana suggestions.',
+      },
+    },
+  },
   async beforeEach() {
     const lsp = createMockLspServer(MOCK_LSP_URL, {
       capabilities: {},
@@ -295,6 +303,14 @@ export const WithDiagnostics: Story = {
     languageId: 'demo',
     initialValue: 'list services in pricing',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SmartEditor against a mocked LSP server that pushes diagnostics on didOpen — the text is decorated with wavy underlines and the stacked message panel below the editor lists both diagnostics.',
+      },
+    },
+  },
   async beforeEach() {
     const lsp = createMockLspServer(MOCK_LSP_URL, {
       capabilities: {},
@@ -342,6 +358,14 @@ export const ReadOnly: Story = {
     initialValue: 'frozen content',
     readOnly: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SmartEditor in read-only mode over an initial value — the Slate editor mounts as contenteditable=false so the content shows but cannot be edited.',
+      },
+    },
+  },
   async beforeEach() {
     const lsp = createMockLspServer(MOCK_LSP_URL, { capabilities: {} });
     return () => lsp.close();
@@ -367,6 +391,14 @@ export const LoadingOverlay: Story = {
     languageId: 'demo',
     initialValue: 'visible under the overlay',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SmartEditor against a mock LSP that never finishes initialize — the "Connecting to language server" overlay stays over the editor for the whole session.',
+      },
+    },
+  },
   async beforeEach() {
     const lsp = createMockLspServer(MOCK_LSP_URL, {
       capabilities: {},

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);