@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/imageLightbox/ImageLightbox.stories.tsx

@@ -0,0 +1,238 @@
+import { StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+import { useEffect, useState } from 'react';
+import { StoryMeta } from '../../types';
+import { IImageLightboxImage, ImageLightbox } from './ImageLightbox';
+
+/**
+ * The shared full-image viewer, on `ReqoreModal`. Opened by the ticket thread (an image
+ * on a message) and the References tab (the screenshot grid) alike. Pages across a set,
+ * click-to-zoom, download; the shell/backdrop/Esc are the modal's.
+ */
+const meta = {
+  component: ImageLightbox,
+  title: 'Components/ImageLightbox',
+} as StoryMeta<typeof ImageLightbox>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const shot = (label: string, hue: number): string =>
+  `data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns='http://www.w3.org/2000/svg' width='640' height='400'>` +
+      `<rect width='640' height='400' fill='hsl(${hue},38%,16%)'/>` +
+      `<text x='24' y='210' fill='white' font-family='sans-serif' font-size='28' opacity='0.7'>${label}</text>` +
+      `</svg>`
+  )}`;
+
+const IMAGES: IImageLightboxImage[] = [
+  { attachment_id: 'i1', filename: 'canvas-error.png' },
+  { attachment_id: 'i2', filename: 'console.png' },
+  { attachment_id: 'i3', filename: 'network.png' },
+];
+
+/** Open on a set of three, so the paging chrome (`1 / 3`, prev/next) shows. */
+export const Paging: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders the lightbox open on a set of three images, so the paging chrome ('1 / 3', prev/next) shows, and arrow keys page through the set.",
+      },
+    },
+  },
+  render: function Render() {
+    const [index, setIndex] = useState<number | null>(0);
+    if (index === null) {
+      return <div>closed</div>;
+    }
+    return (
+      <ImageLightbox
+        images={IMAGES}
+        index={index}
+        onIndex={setIndex}
+        onClose={() => setIndex(null)}
+        fetchAttachmentUrl={async (id) => shot(id, id === 'i1' ? 265 : id === 'i2' ? 205 : 150)}
+        onDownload={fn()}
+      />
+    );
+  },
+  async play() {
+    // the modal portals to the body, so query document-wide
+    await waitFor(() => expect(document.querySelector('[role="dialog"]')).not.toBeNull());
+    const dialog = within(document.body);
+    await expect(await dialog.findByText('canvas-error.png')).toBeInTheDocument();
+    await expect(dialog.getByText('1 / 3')).toBeInTheDocument();
+    // page forward via the keyboard (the action buttons are icon-only)
+    await userEvent.keyboard('{ArrowRight}');
+    await waitFor(() => expect(dialog.getByText('2 / 3')).toBeInTheDocument());
+  },
+};
+
+/**
+ * Regression guard for the "screenshot preview stuck loading" bug.
+ *
+ * Consumers pass `fetchAttachmentUrl` as an inline arrow — a new identity every render —
+ * and re-render for reasons unrelated to the lightbox. Here the parent ticks on a timer
+ * (handing a fresh fetcher each render) while the fetch is deliberately slow, so those
+ * re-renders land WHILE the image is still loading. When the fetch effect depended on
+ * `fetchAttachmentUrl`, each re-render tore down the in-flight fetch and the `requested`
+ * guard blocked a retry — the spinner hung forever. The image resolving proves the effect
+ * now depends on `id` alone. Removing that fix makes this story time out.
+ */
+export const ResolvesDespiteParentReRenders: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the lightbox while the parent re-renders on a timer with a deliberately slow fetch — a regression guard proving the image still resolves instead of the spinner hanging forever.',
+      },
+    },
+  },
+  render: function Render() {
+    const [index, setIndex] = useState<number | null>(0);
+    const [, setTick] = useState(0);
+    useEffect(() => {
+      const timer = setInterval(() => setTick((n) => n + 1), 30);
+      return () => clearInterval(timer);
+    }, []);
+    if (index === null) {
+      return <div>closed</div>;
+    }
+    return (
+      <ImageLightbox
+        images={[IMAGES[0]]}
+        index={index}
+        onIndex={setIndex}
+        onClose={() => setIndex(null)}
+        // a brand-new arrow every render, and a slow fetch so the re-renders overlap it
+        fetchAttachmentUrl={async (id) => {
+          await new Promise((resolve) => setTimeout(resolve, 120));
+          return shot(id, 265);
+        }}
+        onDownload={fn()}
+      />
+    );
+  },
+  async play() {
+    await expect(await within(document.body).findByText('canvas-error.png')).toBeInTheDocument();
+    // the image resolves and paints — it never would while the spinner was hung
+    await waitFor(
+      () => expect(document.body.querySelector('img[alt="canvas-error.png"]')).not.toBeNull(),
+      { timeout: 3000 }
+    );
+  },
+};
+
+/**
+ * Renaming from inside the preview. The pencil (only offered when `onRename` is wired)
+ * swaps in an input row; Enter commits through the host, which owns the actual rename —
+ * here the harness updates its image list, so the modal header shows the new name.
+ * Esc cancels the edit WITHOUT closing the modal. Discriminating: remove the
+ * `onRename` plumbing and the pencil never renders / the title never changes.
+ */
+export const Renamable: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the lightbox with onRename wired — the header pencil opens an inline input; Enter commits the new name through the host and Esc cancels without closing the modal.',
+      },
+    },
+  },
+  render: function Render() {
+    const [index, setIndex] = useState<number | null>(0);
+    const [images, setImages] = useState<IImageLightboxImage[]>([IMAGES[0]]);
+    if (index === null) {
+      return <div>closed</div>;
+    }
+    return (
+      <ImageLightbox
+        images={images}
+        index={index}
+        onIndex={setIndex}
+        onClose={() => setIndex(null)}
+        fetchAttachmentUrl={async (id) => shot(id, 265)}
+        onRename={(id, name) =>
+          setImages((current) =>
+            current.map((img) => (img.attachment_id === id ? { ...img, filename: name } : img))
+          )
+        }
+      />
+    );
+  },
+  async play() {
+    const dialog = within(document.body);
+    await expect(await dialog.findByText('canvas-error.png')).toBeInTheDocument();
+
+    const pencil = await waitFor(() => {
+      const el = document.body.querySelector<HTMLButtonElement>('.imagelightbox-rename');
+      if (!el) {
+        throw new Error('rename action not rendered');
+      }
+      return el;
+    });
+    await userEvent.click(pencil);
+
+    // Esc cancels the edit but keeps the modal open
+    const input = await waitFor(() => {
+      const el = document.body.querySelector<HTMLInputElement>('.reqore-modal input');
+      if (!el) {
+        throw new Error('rename input not shown');
+      }
+      return el;
+    });
+    await expect(input).toHaveValue('canvas-error.png'); // pre-filled with the current name
+    await userEvent.keyboard('{Escape}');
+    await waitFor(() =>
+      expect(document.body.querySelector('.reqore-modal input')).toBeNull()
+    );
+    await expect(document.querySelector('[role="dialog"]')).not.toBeNull();
+
+    // now rename for real: pencil → clear → type → Enter → header carries the new name
+    await userEvent.click(document.body.querySelector<HTMLButtonElement>('.imagelightbox-rename')!);
+    const input2 = await waitFor(() => {
+      const el = document.body.querySelector<HTMLInputElement>('.reqore-modal input');
+      if (!el) {
+        throw new Error('rename input not shown (second open)');
+      }
+      return el;
+    });
+    await userEvent.clear(input2);
+    await userEvent.type(input2, 'mapper-crash.png');
+    await userEvent.keyboard('{Enter}');
+    await waitFor(() => expect(dialog.getByText('mapper-crash.png')).toBeInTheDocument());
+    await expect(dialog.queryByText('canvas-error.png')).not.toBeInTheDocument();
+  },
+};
+
+/** A single image: no paging chrome. */
+export const Single: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the lightbox on a single image, so no paging chrome appears.',
+      },
+    },
+  },
+  render: function Render() {
+    const [index, setIndex] = useState<number | null>(0);
+    if (index === null) {
+      return <div>closed</div>;
+    }
+    return (
+      <ImageLightbox
+        images={[IMAGES[0]]}
+        index={index}
+        onIndex={setIndex}
+        onClose={() => setIndex(null)}
+        fetchAttachmentUrl={async (id) => shot(id, 265)}
+        onDownload={fn()}
+      />
+    );
+  },
+  async play() {
+    const dialog = within(document.body);
+    await expect(await dialog.findByText('canvas-error.png')).toBeInTheDocument();
+    await expect(dialog.queryByText('1 / 1')).not.toBeInTheDocument();
+  },
+};

package/src/components/imageLightbox/ImageLightbox.tsx

@@ -0,0 +1,236 @@
+import {
+  ReqoreInput,
+  ReqoreModal,
+  ReqoreSpan,
+  ReqoreSpinner,
+  useLatestZIndex,
+} from '@qoretechnologies/reqore';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import styled from 'styled-components';
+
+/*
+ * The shared full-image viewer: a `ReqoreModal` holding one image at a time, with
+ * click-to-zoom, keyboard/arrow paging across a set, and a download action. Both the
+ * ticket thread (an image attachment on a message) and the References tab (the ticket's
+ * screenshot grid) open this, so there is one lightbox rather than a Modal-backed one
+ * here and a hand-rolled overlay there.
+ *
+ * reqore has no image-viewer primitive, so the zoom stage below is bespoke — but the
+ * shell, backdrop, focus trap, Esc-to-close and header/actions are all `ReqoreModal`.
+ * When reqore gains a real viewer this collapses onto it. It fetches the shown image's
+ * bytes itself (caching per id), so a consumer only has to hand it `fetchAttachmentUrl`.
+ */
+
+// Compact rename row above the stage while editing — the modal's `label` slot is
+// string-only, so the input can't live in the header itself.
+const RenameRow = styled.div`
+  margin-bottom: 8px;
+`;
+
+const Stage = styled.div<{ $zoom: boolean }>`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 40vh;
+  max-height: 74vh;
+  overflow: auto;
+  background: rgba(0, 0, 0, 0.25);
+  border-radius: 8px;
+
+  img {
+    display: block;
+    cursor: ${({ $zoom }) => ($zoom ? 'zoom-out' : 'zoom-in')};
+    ${({ $zoom }) =>
+      $zoom
+        ? 'max-width: none; max-height: none;'
+        : 'max-width: 100%; max-height: 74vh; object-fit: contain;'}
+  }
+`;
+
+export interface IImageLightboxImage {
+  attachment_id: string;
+  filename: string;
+}
+
+export interface IImageLightboxProps {
+  /** the set the viewer pages across — one image is a set of one (no paging chrome) */
+  images: IImageLightboxImage[];
+  /** which image is shown */
+  index: number;
+  onIndex: (index: number) => void;
+  onClose: () => void;
+  /** resolve an image's bytes as an object URL (the consumer's authed endpoint) */
+  fetchAttachmentUrl: (attachmentId: string) => Promise<string>;
+  onDownload?: (attachmentId: string, filename: string) => void;
+  /** Rename the shown image. Presence of the callback IS the permission — a staged
+   *  (composer) set passes it, server-side attachment sets simply don't, so the
+   *  thread / References viewers stay rename-free without any extra flag. */
+  onRename?: (attachmentId: string, newName: string) => void;
+}
+
+export const ImageLightbox = ({
+  images,
+  index,
+  onIndex,
+  onClose,
+  fetchAttachmentUrl,
+  onDownload,
+  onRename,
+}: IImageLightboxProps) => {
+  const [zoom, setZoom] = useState<boolean>(false);
+  // inline rename state: editing toggles the input row; draftName is the working value
+  const [editing, setEditing] = useState<boolean>(false);
+  const [draftName, setDraftName] = useState<string>('');
+  // url per attachment: undefined = not fetched, null = fetch failed, string = ready
+  const [urls, setUrls] = useState<Record<string, string | null>>({});
+  const requested = useRef<Set<string>>(new Set());
+  // Render above everything currently on screen: the ticket composer that can open this
+  // lightbox floats at its own climbed z-index (also useLatestZIndex), so a modal on a fixed
+  // z-index ends up BEHIND it. Climbing past the current top keeps the viewer on top wherever
+  // it's opened from.
+  const zIndex = useLatestZIndex();
+
+  const image = images[index];
+  const id = image?.attachment_id;
+  const url = id ? urls[id] : undefined;
+  const multiple = images.length > 1;
+
+  // Keep the latest fetcher in a ref so the fetch effect can depend on `id` ALONE.
+  // Consumers routinely pass `fetchAttachmentUrl` as an inline arrow — a new identity
+  // every render. If the effect depended on it, each parent re-render would re-run the
+  // effect: the previous run's cleanup fired first, so its in-flight fetch resolved with
+  // nothing to write to, and because `requested` already held the id nothing re-fetched.
+  // Net result: the spinner hung forever. Depending on `id` only breaks that cycle.
+  const fetchRef = useRef(fetchAttachmentUrl);
+  fetchRef.current = fetchAttachmentUrl;
+  // True only while mounted: a fetch that resolves after unmount is dropped, but one that
+  // resolves after a benign re-render still caches — the distinction a per-run flag missed.
+  const mounted = useRef(true);
+  useEffect(
+    () => () => {
+      mounted.current = false;
+    },
+    []
+  );
+
+  // fetch the shown image's bytes once per id; `requested` guards against re-fetching a
+  // page you've already visited
+  useEffect(() => {
+    if (!id || requested.current.has(id)) {
+      return undefined;
+    }
+    requested.current.add(id);
+    fetchRef.current(id)
+      .then((resolved) => mounted.current && setUrls((current) => ({ ...current, [id]: resolved })))
+      .catch(() => mounted.current && setUrls((current) => ({ ...current, [id]: null })));
+    return undefined;
+  }, [id]);
+
+  const step = useCallback(
+    (delta: number) => {
+      setZoom(false);
+      // paging abandons an in-flight rename — the draft belonged to the image left behind
+      setEditing(false);
+      onIndex((index + delta + images.length) % images.length);
+    },
+    [index, images.length, onIndex]
+  );
+
+  useEffect(() => {
+    if (!multiple || editing) {
+      // while renaming, arrow keys belong to the text input, not the pager
+      return undefined;
+    }
+    const handler = (event: KeyboardEvent) => {
+      if (event.key === 'ArrowRight') {
+        step(1);
+      } else if (event.key === 'ArrowLeft') {
+        step(-1);
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [step, multiple, editing]);
+
+  const startRename = useCallback(() => {
+    setDraftName(images[index]?.filename ?? '');
+    setEditing(true);
+  }, [images, index]);
+
+  const commitRename = useCallback(() => {
+    const current = images[index];
+    const name = draftName.trim();
+    if (onRename && current && name && name !== current.filename) {
+      onRename(current.attachment_id, name);
+    }
+    setEditing(false);
+  }, [draftName, images, index, onRename]);
+
+  if (!image) {
+    return null;
+  }
+
+  return (
+    <ReqoreModal
+      isOpen
+      onClose={onClose}
+      customZIndex={zIndex}
+      blur={3}
+      icon='ImageLine'
+      label={image.filename}
+      badge={multiple ? `${index + 1} / ${images.length}` : undefined}
+      actions={[
+        { icon: 'ArrowLeftSLine', tooltip: 'Previous', onClick: () => step(-1), show: multiple },
+        { icon: 'ArrowRightSLine', tooltip: 'Next', onClick: () => step(1), show: multiple },
+        {
+          icon: 'Edit2Line',
+          tooltip: 'Rename',
+          className: 'imagelightbox-rename',
+          onClick: startRename,
+          show: !!onRename && !editing,
+        },
+        {
+          icon: 'DownloadLine',
+          tooltip: 'Download',
+          onClick: () => onDownload?.(image.attachment_id, image.filename),
+          show: !!onDownload,
+        },
+      ]}
+    >
+      {editing ? (
+        <RenameRow>
+          <ReqoreInput
+            value={draftName}
+            onChange={(event: React.ChangeEvent<HTMLInputElement>) =>
+              setDraftName(event.target.value)
+            }
+            onBlur={commitRename}
+            onKeyDown={(event: React.KeyboardEvent) => {
+              if (event.key === 'Enter') {
+                commitRename();
+              } else if (event.key === 'Escape') {
+                // cancel the edit only — don't let the modal's own Esc-to-close see it
+                event.stopPropagation();
+                setEditing(false);
+              }
+            }}
+            size='small'
+            fluid
+            autoFocus
+          />
+        </RenameRow>
+      ) : null}
+      <Stage $zoom={zoom}>
+        {url ? (
+          <img src={url} alt={image.filename} onClick={() => setZoom((z) => !z)} />
+        ) : url === null ? (
+          <ReqoreSpan effect={{ opacity: 0.6 }}>Preview unavailable — use Download.</ReqoreSpan>
+        ) : (
+          <ReqoreSpinner iconColor='info' size='big'>
+            Loading…
+          </ReqoreSpinner>
+        )}
+      </Stage>
+    </ReqoreModal>
+  );
+};

package/src/components/imageLightbox/index.ts

@@ -0,0 +1 @@
+export * from './ImageLightbox';

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