@qoretechnologies/reqraft 0.10.57 → 0.10.58-pr.129.g43f4175

package/src/components/supportTicket/InterfaceReferenceTags.tsx

@@ -1,17 +1,24 @@
 import { ReqoreControlGroup, ReqoreP, ReqoreTag } from '@qoretechnologies/reqore';
 import { TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
-import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import { ComponentProps } from 'react';
-import { defaultInterfaceIcon, IInterfaceReference } from './meta';
+import {
+  defaultInterfaceIcon,
+  IInterfaceReference,
+  toInterfaceKindMark,
+  TResolveInterfaceIcon,
+} from './meta';
+import { useLoadedImages } from './useLoadedImages';
 
 export interface IInterfaceReferenceTagsProps {
   references?: IInterfaceReference[];
   /** Optional leading label, e.g. "References" in a ticket header. Omitted (the
    *  default) inside the thread, where the chips sit under a message. */
   label?: string;
-  /** Resolve a per-kind icon. Consumers with their own icon vocabulary (the IDE)
+  /** Resolve a per-kind icon: a font icon, or a mark `{ icon, image }` whose image
+   *  (e.g. the Qog logo) is drawn once it loads, with the font icon before that and
+   *  instead of it if it fails. Consumers with their own icon vocabulary (the IDE)
    *  pass one; when omitted the built-in per-kind default is used. */
-  resolveInterfaceIcon?: (kind: string) => IReqoreIconName;
+  resolveInterfaceIcon?: TResolveInterfaceIcon;
   /** Open a referenced interface; chips are static (informational) when omitted —
    *  e.g. the staff view, which can't reach the customer's instance. */
   onInterfaceClick?: (reference: IInterfaceReference) => void;
@@ -32,6 +39,21 @@ export interface IInterfaceReferenceTagsProps {
    *  qogs list does. When this (or the reference's own `logo`) returns a value, the
    *  chip shows the image in place of the kind icon. */
   resolveInterfaceImage?: (reference: IInterfaceReference) => string | undefined;
+  /**
+   * Which image a chip draws when there is more than one:
+   *
+   * - `false` (the default): the reference's own image first — its stored `logo`,
+   *   then `resolveInterfaceImage` — and the kind's image (from
+   *   `resolveInterfaceIcon`) only when it has neither. This is how chips have
+   *   always looked: an app-triggered Qog shows its trigger app's logo.
+   * - `true`: the kind's image first, then the reference's own. For a host that
+   *   draws every interface of a kind with one mark (the IDE's green Qog), so a
+   *   Qog reads as a Qog whatever app triggers it.
+   *
+   * Either way the kind's font icon shows until the chosen image loads, and
+   * instead of it if it cannot.
+   */
+  preferKindImage?: boolean;
 }
 
 /**
@@ -51,11 +73,22 @@ export const InterfaceReferenceTags = ({
   intent,
   customTheme,
   resolveInterfaceImage,
+  preferKindImage = false,
 }: IInterfaceReferenceTagsProps) => {
+  const resolveIcon = resolveInterfaceIcon ?? defaultInterfaceIcon;
+  const marks = (references ?? []).map((reference) => {
+    const mark = toInterfaceKindMark(resolveIcon(reference.interface_kind));
+    const own = reference.logo ?? resolveInterfaceImage?.(reference);
+    return {
+      reference,
+      icon: mark.icon,
+      image: preferKindImage ? (mark.image ?? own) : (own ?? mark.image),
+    };
+  });
+  const isLoaded = useLoadedImages(marks.map(({ image }) => image));
   if (!references?.length) {
     return null;
   }
-  const resolveIcon = resolveInterfaceIcon ?? defaultInterfaceIcon;
   return (
     <ReqoreControlGroup verticalAlign='center' wrap gapSize='small'>
       {label ? (
@@ -63,18 +96,18 @@ export const InterfaceReferenceTags = ({
           {label}
         </ReqoreP>
       ) : null}
-      {references.map((reference) => {
-        // an app-triggered qog shows the trigger app's logo (stored, or resolved by
-        // a viewer with the app catalogue); everything else shows its kind glyph.
-        const image = reference.logo ?? resolveInterfaceImage?.(reference);
+      {marks.map(({ reference, icon, image }) => {
+        // The chosen image (see `preferKindImage`) once it has loaded; the kind's
+        // font icon until then, and if it fails.
+        const loaded = isLoaded(image);
         return (
           <ReqoreTag
             key={
               reference.reference_id ??
               `${reference.interface_kind}:${reference.interface_name}`
             }
-            icon={image ? undefined : resolveIcon(reference.interface_kind)}
-            leftIconProps={image ? { image } : undefined}
+            icon={icon}
+            leftIconProps={loaded ? { image } : undefined}
             labelKey={reference.interface_kind}
             label={reference.interface_name}
             size={size}

package/src/components/supportTicket/ReferencePicker.stories.tsx

@@ -4,6 +4,13 @@ import { ComponentProps, useState } from 'react';
 import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 import { StoryMeta } from '../../types';
 import { InterfaceReferenceTags } from './InterfaceReferenceTags';
+import {
+  STORY_BROKEN_IMAGE,
+  STORY_QOG_IMAGE,
+  storyBrokenKindMark,
+  storyKindMark,
+} from './__fixtures__/kindMarks';
+import { whenImageSettled } from './useLoadedImages';
 import { IInterfaceReference } from './meta';
 import { ReferencePicker, TReferencePickerItem } from './ReferencePicker';
 import { TicketReplyBox } from './TicketReplyBox';
@@ -517,3 +524,47 @@ export const AboveTheComposer: Story = {
     await expect(canvas.getAllByText('order-sync:1.2').length).toBeGreaterThan(0);
   },
 };
+
+const menuImages = (canvasElement: HTMLElement) =>
+  Array.from(canvasElement.querySelectorAll('.reqore-menu-item img')).map((img) =>
+    img.getAttribute('src')
+  );
+
+export const KindImage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the picker with a host resolver that gives Qogs an image: the Qogs kind and each Qog in the list show the green Qog mark; every other kind keeps its font icon.',
+      },
+    },
+  },
+  decorators: [darkTheme],
+  render: () => <Hosted initialKind='qog' resolveInterfaceIcon={storyKindMark} />,
+  async play({ canvasElement }) {
+    // the Qogs kind row plus its four interfaces
+    await waitFor(() =>
+      expect(menuImages(canvasElement).filter((src) => src === STORY_QOG_IMAGE)).toHaveLength(5)
+    );
+  },
+};
+
+export const KindImageFailsToLoad: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the picker with a Qog image that cannot load: the Qogs kind and its interfaces keep the font icon instead of a broken picture.',
+      },
+    },
+  },
+  decorators: [darkTheme],
+  render: () => <Hosted initialKind='qog' resolveInterfaceIcon={storyBrokenKindMark} />,
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await canvas.findByRole('button', { name: 'telegram-intake' });
+    // Once the load has failed, no picture is drawn.
+    await whenImageSettled(STORY_BROKEN_IMAGE);
+    await expect(menuImages(canvasElement)).toEqual([]);
+  },
+};

package/src/components/supportTicket/ReferencePicker.tsx

@@ -6,7 +6,6 @@ import {
   ReqoreSpinner,
 } from '@qoretechnologies/reqore';
 import { TReqoreBadge } from '@qoretechnologies/reqore/dist/components/Button';
-import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import { ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import styled from 'styled-components';
 import { thinScrollbar } from '../../helpers/scrollbar';
@@ -15,7 +14,10 @@ import {
   defaultInterfaceIcon,
   defaultInterfaceKindLabel,
   IInterfaceReference,
+  toInterfaceKindMark,
+  TResolveInterfaceIcon,
 } from './meta';
+import { useLoadedImages } from './useLoadedImages';
 
 /*
  * The interface browser: kinds on one side, the selected kind's interfaces on the
@@ -227,9 +229,11 @@ export interface IReferencePickerProps {
   onRemove?: (reference: IInterfaceReference) => void;
   /** the whole picker is inert (e.g. a reply is in flight) */
   disabled?: boolean;
-  /** Per-kind icon. Consumers with their own icon vocabulary (the IDE) pass one; the
+  /** Per-kind icon: a font icon, or a mark `{ icon, image }` whose image (e.g. the Qog
+   *  logo) is drawn once it loads, with the font icon before that and instead of it if
+   *  it fails. Consumers with their own icon vocabulary (the IDE) pass one; the
    *  built-in per-kind default is used when omitted. */
-  resolveInterfaceIcon?: (kind: string) => IReqoreIconName;
+  resolveInterfaceIcon?: TResolveInterfaceIcon;
   /**
    * Per-kind reading name — "Value maps" for `value-map`. The kind id is a wire value
    * and never reaches the user; this is what does. Search matches both, so typing
@@ -401,11 +405,28 @@ export const ReferencePicker = ({
      still own the scroll and the layout; the menus render transparent inside them.
      Only menu items go inside a `ReqoreMenu`: it clones every child with its own props,
      so a spinner or a note nested in one would be handed props it can't take. */
+  /* A kind's icon on a menu item: its font icon, and its image (the Qog logo) once
+     that has loaded — never a broken picture while it loads or if it fails. */
+  const kindMarks = new Map(
+    Array.from(new Set([...visibleKinds, kind].filter(Boolean) as string[])).map((option) => [
+      option,
+      toInterfaceKindMark(resolveInterfaceIcon(option)),
+    ])
+  );
+  const isImageLoaded = useLoadedImages(Array.from(kindMarks.values()).map((mark) => mark.image));
+  const kindIconProps = (option: string) => {
+    const mark = kindMarks.get(option) ?? toInterfaceKindMark(resolveInterfaceIcon(option));
+    return {
+      icon: mark.icon,
+      leftIconProps: isImageLoaded(mark.image) ? { image: mark.image } : undefined,
+    };
+  };
+
   const kindItems = visibleKinds.map((option) => (
     <ReqoreMenuItem
       key={option}
       className={matchesKind(option) ? undefined : DIMMED_CLASS}
-      icon={resolveInterfaceIcon(option)}
+      {...kindIconProps(option)}
       label={resolveKindLabel(option)}
       selected={option === kind}
       disabled={disabled}
@@ -452,7 +473,7 @@ export const ReferencePicker = ({
             <ReqoreMenuItem
               key={name}
               className={isPicked ? PICKED_CLASS : undefined}
-              icon={resolveInterfaceIcon(kind)}
+              {...kindIconProps(kind)}
               rightIcon={isPicked ? 'CheckLine' : 'AddLine'}
               label={name}
               description={description}

package/src/components/supportTicket/TicketReplyBox.stories.tsx

@@ -284,8 +284,11 @@ export const QogTriggerAppLogo: Story = {
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('telegram-intake')).toBeInTheDocument();
-    // the trigger-app / stored-logo qogs render their app logo image
-    await expect(canvasElement.innerHTML).toContain('data:image');
+    // the trigger-app / stored-logo qogs render their app logo image once it has
+    // loaded (the qog glyph stands in until then)
+    await waitFor(() =>
+      expect(canvasElement.querySelectorAll('.reqore-tag img').length).toBe(3)
+    );
   },
 };
 

package/src/components/supportTicket/__fixtures__/kindMarks.ts

@@ -0,0 +1,28 @@
+import { defaultInterfaceIcon, TInterfaceKindIcon } from '../meta';
+
+/* Stand-ins for a host's kind marks in stories. Inline, so they load offline. */
+
+/** A green Qog-like mark: loads. */
+export const STORY_QOG_IMAGE = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" rx="6" fill="#2e9d4f"/><circle cx="12" cy="12" r="5" fill="#fff"/></svg>'
+)}`;
+
+/** A trigger app's logo: loads. */
+export const STORY_APP_LOGO = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" rx="12" fill="#229ed9"/></svg>'
+)}`;
+
+/** An image that can never load (malformed data URI). */
+export const STORY_BROKEN_IMAGE = 'data:image/png;base64,not-an-image';
+
+/** The IDE's resolver: a Qog is its green mark (font icon fallback); the rest, font icons. */
+export const storyKindMark = (kind: string): TInterfaceKindIcon =>
+  kind === 'fsm' || kind === 'qog' ?
+    { icon: 'FlowChart', image: STORY_QOG_IMAGE }
+  : defaultInterfaceIcon(kind);
+
+/** The same, with a Qog image that fails to load. */
+export const storyBrokenKindMark = (kind: string): TInterfaceKindIcon =>
+  kind === 'fsm' || kind === 'qog' ?
+    { icon: 'FlowChart', image: STORY_BROKEN_IMAGE }
+  : defaultInterfaceIcon(kind);

package/src/components/supportTicket/meta.ts

@@ -144,6 +144,27 @@ const DEFAULT_INTERFACE_ICONS: Record<string, IReqoreIconName> = {
 export const defaultInterfaceIcon = (kind: string): IReqoreIconName =>
   DEFAULT_INTERFACE_ICONS[kind] ?? 'CodeBoxLine';
 
+/**
+ * An interface kind's mark: a font icon, and optionally an image (e.g. the green
+ * Qog logo). The font icon is what shows while the image loads, and instead of it
+ * when there is none or it cannot load. Same shape as qorus-ide's
+ * `interfaceKindMark()`, so the IDE can return that directly.
+ */
+export interface IInterfaceKindMark {
+  icon: IReqoreIconName;
+  image?: string;
+}
+
+/** What a `resolveInterfaceIcon` may return: a font icon, or a mark with an image. */
+export type TInterfaceKindIcon = IReqoreIconName | IInterfaceKindMark;
+
+/** Resolve the icon for an interface kind (see `TInterfaceKindIcon`). */
+export type TResolveInterfaceIcon = (kind: string) => TInterfaceKindIcon;
+
+/** A resolver's answer as a mark, so callers handle one shape. */
+export const toInterfaceKindMark = (icon: TInterfaceKindIcon): IInterfaceKindMark =>
+  typeof icon === 'string' ? { icon } : icon;
+
 // The reading name for each interface kind. The kind id (`value-map`, `ai-collection`)
 // is a wire value — it's what a host fetches with and what gets stored on the reference
 // — so it must never be what the user reads. These are plural because they name a

package/src/components/supportTicket/useLoadedImages.ts

@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react';
+
+/* What is known about each image URL, shared by every surface for the life of
+   the page: an image that loaded once is drawn at once the next time, and one
+   that failed is not tried again on every render. */
+const imageStatus = new Map<string, 'loaded' | 'failed'>();
+const pending = new Map<string, Promise<void>>();
+
+const loadImage = (src: string): Promise<void> => {
+  let promise = pending.get(src);
+  if (!promise) {
+    promise = new Promise<void>((resolve) => {
+      const image = new Image();
+      image.onload = () => {
+        imageStatus.set(src, 'loaded');
+        resolve();
+      };
+      image.onerror = () => {
+        imageStatus.set(src, 'failed');
+        resolve();
+      };
+      image.src = src;
+    }).finally(() => pending.delete(src));
+    pending.set(src, promise);
+  }
+  return promise;
+};
+
+/**
+ * Which of `sources` have loaded. An icon that has an image draws its font icon
+ * until this says the image loaded, and keeps the font icon when it fails — the
+ * image is never drawn as a broken picture or an empty box.
+ *
+ * One hook for a whole list, so a component that maps over references (or a
+ * `ReqoreMenu`, which clones its children and so cannot hold per-item hooks)
+ * asks once.
+ */
+export const useLoadedImages = (sources: Array<string | undefined>): ((src?: string) => boolean) => {
+  const [, setVersion] = useState(0);
+  const key = sources.filter(Boolean).join('\u0000');
+
+  useEffect(() => {
+    let active = true;
+    const unknown = Array.from(new Set(sources.filter((src): src is string => !!src))).filter(
+      (src) => !imageStatus.has(src)
+    );
+    unknown.forEach((src) => {
+      loadImage(src).then(() => {
+        if (active) {
+          setVersion((version) => version + 1);
+        }
+      });
+    });
+    return () => {
+      active = false;
+    };
+  }, [key]);
+
+  return (src?: string) => !!src && imageStatus.get(src) === 'loaded';
+};
+
+/**
+ * Resolves once `src` has loaded or failed — so a test or story can check the
+ * settled state instead of waiting an arbitrary time.
+ */
+export const whenImageSettled = (src: string): Promise<void> =>
+  imageStatus.has(src) ? Promise.resolve() : loadImage(src);
+
+/** Forget every image's status. For tests only. */
+export const resetLoadedImagesForTests = (): void => {
+  imageStatus.clear();
+  pending.clear();
+};

package/src/components/ticketReferences/TicketReferences.tsx

@@ -23,8 +23,11 @@ import { ImageLightbox } from '../imageLightbox';
 import {
   defaultInterfaceIcon,
   IInterfaceReference,
+  toInterfaceKindMark,
+  TResolveInterfaceIcon,
   TTicketViewerRole,
 } from '../supportTicket/meta';
+import { useLoadedImages } from '../supportTicket/useLoadedImages';
 import type { ITicketThreadAttachment, ITicketThreadMessage } from '../ticketThread/TicketThread';
 
 /*
@@ -74,8 +77,13 @@ export interface ITicketReferencesProps {
    *  Omitted ⇒ the action is not offered. It is also omitted per-row for anything filed
    *  against the ticket itself rather than a reply, which has no message to reveal. */
   onShowInChat?: (messageId: string) => void;
-  /** resolve a per-kind icon for a referenced interface (the IDE passes its own vocabulary) */
-  resolveInterfaceIcon?: (kind: string) => IReqoreIconName;
+  /** resolve a per-kind icon for a referenced interface (the IDE passes its own
+   *  vocabulary): a font icon, or a mark `{ icon, image }` whose image is drawn once
+   *  it loads, with the font icon before that and instead of it if it fails */
+  resolveInterfaceIcon?: TResolveInterfaceIcon;
+  /** Draw the kind's image ahead of a reference's own logo; see `preferKindImage` on
+   *  `InterfaceReferenceTags`. Off by default. */
+  preferKindImage?: boolean;
   loading?: boolean;
 }
 
@@ -415,6 +423,7 @@ export const TicketReferences = ({
   onInterfaceClick,
   onShowInChat,
   resolveInterfaceIcon,
+  preferKindImage = false,
   loading,
 }: ITicketReferencesProps) => {
   // references: ticket-level + every message's, deduped. Rendered as rows carrying
@@ -433,6 +442,17 @@ export const TicketReferences = ({
     [references, messages]
   );
   const resolveIcon = resolveInterfaceIcon ?? defaultInterfaceIcon;
+  /* Each reference's icon: the kind's font icon, and the image chosen by the same
+     precedence as the chips (`preferKindImage`), drawn once it has loaded. */
+  const markOf = (reference: IInterfaceReference) => {
+    const mark = toInterfaceKindMark(resolveIcon(reference.interface_kind));
+    const own = reference.logo;
+    return {
+      icon: mark.icon,
+      image: preferKindImage ? (mark.image ?? own) : (own ?? mark.image),
+    };
+  };
+  const isImageLoaded = useLoadedImages(allRefs.map((reference) => markOf(reference).image));
 
   /**
    * The trailing controls for a row: its primary action, plus a "three dots" menu when
@@ -768,17 +788,17 @@ export const TicketReferences = ({
               the group's size reaches every row (ControlGroup/index.tsx:436) */}
           <ReqoreControlGroup vertical fluid gapSize='small' size='small'>
             {visibleRefs.map((reference) => {
-              // an app-triggered qog carries its trigger app's logo; everything else
-              // shows its kind glyph — the same vocabulary the reference chips use.
-              const image = reference.logo;
+              // the same vocabulary and precedence as the reference chips: the kind's
+              // font icon, and the chosen image once it has loaded
+              const { icon, image } = markOf(reference);
               return (
                 <ReqoreEntityRow
                   key={
                     reference.reference_id ??
                     `${reference.interface_kind}:${reference.interface_name}`
                   }
-                  icon={image ? undefined : resolveIcon(reference.interface_kind)}
-                  iconImage={image}
+                  icon={icon}
+                  iconImage={isImageLoaded(image) ? image : undefined}
                   label={reference.interface_name}
                   metadata={
                     <ReqoreTextEffect effect={META_EFFECT}>

package/src/components/ticketThread/TicketThread.tsx

@@ -21,6 +21,7 @@ import { ImageLightbox } from '../imageLightbox';
 import {
   IInterfaceReference,
   InterfaceReferenceTags,
+  TResolveInterfaceIcon,
   TTicketMessageAuthor,
   TTicketViewerRole,
 } from '../supportTicket';
@@ -84,10 +85,15 @@ export interface ITicketThreadProps {
    * where a consumer hasn't wired it. Non-image attachments never use it.
    */
   fetchAttachmentUrl?: (attachmentId: string) => Promise<string>;
-  /** resolve a per-kind icon for a referenced interface. Consumers with their own
-   *  icon vocabulary (e.g. the qorus-ide IDE) pass one; when omitted, a built-in
+  /** resolve a per-kind icon for a referenced interface: a font icon, or a mark
+   *  `{ icon, image }` whose image (e.g. the Qog logo) is drawn once it loads, with
+   *  the font icon before that and instead of it if it fails. Consumers with their
+   *  own icon vocabulary (e.g. the qorus-ide IDE) pass one; when omitted, a built-in
    *  per-kind default is used so every surface shows consistent chips. */
-  resolveInterfaceIcon?: (kind: string) => IReqoreIconName;
+  resolveInterfaceIcon?: TResolveInterfaceIcon;
+  /** Draw the kind's image ahead of a reference's own logo on the reference chips;
+   *  see `preferKindImage` on `InterfaceReferenceTags`. Off by default. */
+  preferKindImage?: boolean;
   /** open a referenced interface; reference chips are static when omitted (e.g. the staff
    *  view, which can't reach the customer's instance, leaves this out). */
   onInterfaceClick?: (reference: IInterfaceReference) => void;
@@ -557,6 +563,7 @@ export const TicketThread = ({
   onDownloadAttachment,
   fetchAttachmentUrl,
   resolveInterfaceIcon,
+  preferKindImage,
   onInterfaceClick,
   ticketReferences,
 }: ITicketThreadProps) => {
@@ -694,6 +701,7 @@ export const TicketThread = ({
                       customTheme={ACCENT}
                       references={refsFor(message)}
                       resolveInterfaceIcon={resolveInterfaceIcon}
+                      preferKindImage={preferKindImage}
                       onInterfaceClick={onInterfaceClick}
                     />
                   </div>