@qoretechnologies/reqraft 0.10.20 → 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/searchFilterBar/SearchFilterBar.tsx

@@ -0,0 +1,131 @@
+import { ReqoreControlGroup, ReqoreDropdown, ReqoreInput } from '@qoretechnologies/reqore';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
+import styled, { css } from 'styled-components';
+
+/*
+ * A search box with filter dropdowns beside it — the strip that sits above a list
+ * and narrows it.
+ *
+ * This existed twice, built independently either side of the package boundary: the
+ * ticket list in qorus-ide and the References tab here in reqraft. Same
+ * composition (ReqoreControlGroup > ReqoreInput + N ReqoreDropdowns), but they had
+ * drifted — one sized the group, the other sized each control; one wrapped, the
+ * other stacked; one moved the dropdown caret to the right slot and suppressed the
+ * default, the other did not. Two strips that should be indistinguishable ended up
+ * visibly different, and any fix had to be made twice.
+ *
+ * It lives in reqraft rather than Reqore because it is a composition of Reqore
+ * primitives, not a new primitive — there is nothing here Reqore is missing.
+ *
+ * The frosted container is part of the component, not the caller's job. Extracting
+ * only the controls left the two surfaces still looking different: one bar sat in a
+ * bordered, blurred card, the other bare on the page. If the bar is meant to read
+ * the same everywhere then its own chrome has to travel with it.
+ */
+
+const Container = styled.div<{ $sticky?: boolean }>`
+  padding: 8px;
+  border-radius: 8px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(255, 255, 255, 0.04);
+  backdrop-filter: blur(6px);
+
+  ${({ $sticky }) =>
+    $sticky &&
+    css`
+      position: sticky;
+      top: 0;
+      z-index: 2;
+    `}
+`;
+
+export interface ISearchFilterOption {
+  label: string;
+  icon?: IReqoreIconName;
+  selected?: boolean;
+  onClick: () => void;
+}
+
+export interface ISearchFilter {
+  /** Icon for the trigger — usually the selected option's. */
+  icon?: IReqoreIconName;
+  /** Trigger label — usually the selected option's. */
+  label: string;
+  items: ISearchFilterOption[];
+}
+
+export interface ISearchFilterBarProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder: string;
+  filters?: ISearchFilter[];
+  /**
+   * Stack the search over its filters. On a phone the box and two dropdowns
+   * cannot share a row without the input collapsing to a few characters, so the
+   * caller passes its own breakpoint result rather than this guessing.
+   */
+  stacked?: boolean;
+  /**
+   * Pin the bar to the top of its scroll container. For a bar inside a scrolling
+   * panel (the References tab); a bar above a page-level list does not need it.
+   */
+  sticky?: boolean;
+}
+
+export const SearchFilterBar = ({
+  value,
+  onChange,
+  placeholder,
+  filters = [],
+  stacked,
+  sticky,
+}: ISearchFilterBarProps) => (
+  <Container $sticky={sticky}>
+    {/* `size='small'` on the GROUP, not per control: the bar filters the content, it
+        is not content — at the default size the dropdowns read as primary actions and
+        crowd the search field. */}
+    <ReqoreControlGroup
+      fluid
+      wrap
+      gapSize='small'
+      size='small'
+      vertical={stacked}
+      verticalAlign={stacked ? undefined : 'center'}
+    >
+      <ReqoreInput
+        icon='Search2Line'
+        placeholder={placeholder}
+        value={value}
+        onChange={(event) => onChange((event.currentTarget as HTMLInputElement).value)}
+        onClearClick={value ? () => onChange('') : undefined}
+        minimal
+        fluid
+      />
+      {filters.length ?
+        <ReqoreControlGroup gapSize='small' size='small' fluid={stacked}>
+          {filters.map((filter, index) => (
+            <ReqoreDropdown
+              key={index}
+              icon={filter.icon}
+              label={filter.label}
+              minimal
+              flat
+              /* stretch to share the row when stacked; hug the label otherwise */
+              fixed={!stacked}
+              /* the caret defaults to the LEFT slot, where the filter's own icon
+               already sits — without this each trigger shows two glyphs */
+              rightIcon='ArrowDownSLine'
+              showCaret={false}
+              items={filter.items.map((item) => ({
+                label: item.label,
+                icon: item.icon,
+                selected: item.selected,
+                onClick: item.onClick,
+              }))}
+            />
+          ))}
+        </ReqoreControlGroup>
+      : null}
+    </ReqoreControlGroup>
+  </Container>
+);

package/src/components/searchFilterBar/index.ts

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