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

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,61 @@ export const AboveTheComposer: Story = {
     await expect(canvas.getAllByText('order-sync:1.2').length).toBeGreaterThan(0);
   },
 };
+
+/* The kinds for the image stories: Qogs first, then a few font-icon kinds to
+ * compare against. */
+const IMAGE_KINDS = ['qog', 'workflow', 'service', 'job'];
+
+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],
+  // A short kind list with Qogs first, so the Qogs kind and its mark sit at the
+  // top of the column in the captured frame rather than below its fold.
+  render: () => (
+    <Hosted kinds={IMAGE_KINDS} 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)
+    );
+    // the Qogs kind is the first kind row, so it is in the frame
+    await expect(
+      canvasElement.querySelector('.reqore-menu-item')?.querySelector('img')?.getAttribute('src')
+    ).toBe(STORY_QOG_IMAGE);
+  },
+};
+
+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 kinds={IMAGE_KINDS} 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>

package/src/helpers/allowedValues.ts

@@ -0,0 +1,216 @@
+/**
+ * Is a stored value one of a field's fixed choices?
+ *
+ * Two questions share this one predicate: the read-first row asks it to LABEL a
+ * value with the choice's display name, and the validator asks it to decide
+ * whether a value is one of the choices at all. Answering them differently is
+ * how values were lost: a value the row could name was erased by a narrower
+ * test, and the emptied form was then saved.
+ */
+import { TQorusFormFieldSchema } from '@qoretechnologies/ts-toolkit';
+import isEqual from 'lodash/isEqual';
+import { richtextHasTag, richtextToString } from './common';
+import { getListElementValue } from './options';
+import { isValueTemplate } from './templates';
+
+const isStructured = (value: unknown): boolean => value !== null && typeof value === 'object';
+
+/**
+ * Prefer the matching allowed_values entry's display_name (fallback `name`)
+ * over the raw stored value.
+ *
+ * A LIST carries its options under `element_allowed_values` — they constrain
+ * each element, not the list itself — so a multi-select that was missing here
+ * printed what it stores rather than what you picked: `orders, batch` for
+ * fields whose picker reads "Orders, Batch". The gap shows worst exactly where
+ * allowed values earn their keep, since the stored form is often not readable
+ * at all (a permission code, `PO_REQUIRE_TYPES`, an app-specific id).
+ *
+ * Exported (as `findAllowedValueOption`) because the form engine's value
+ * validation has to answer the SAME question — "is this stored value one of the
+ * declared choices?" — and answering it differently loses data. An
+ * `allowed_values` entry is written three ways: an envelope (`{value: {type,
+ * value}}`), a bare value (`{value: 'default'}`) or a named entry
+ * (`{name: 'default'}`). This has always accepted all three; the engine's
+ * clearing guard accepted only the first and the third, so a schema using the
+ * bare form had its value ERASED on load while this function went on rendering
+ * the display name for it — the row read "Default RBAC" collapsed and "—" when
+ * opened, and the value was gone from the submitted data.
+ */
+export const findAllowedValueOption = (
+  value: unknown,
+  schema?: TQorusFormFieldSchema
+): any | undefined => {
+  const s = schema as
+    { allowed_values?: any[]; element_allowed_values?: any[]; items?: any[] } | undefined;
+  const options =
+    (s?.allowed_values?.length && s.allowed_values) ||
+    (s?.element_allowed_values?.length && s.element_allowed_values) ||
+    s?.items;
+  if (!options?.length) {
+    return undefined;
+  }
+  // A stored element can be the bare value or the typed `{type, value}`
+  // envelope the form engine round-trips; match either against either.
+  const stored =
+    value && typeof value === 'object' && 'value' in (value as Record<string, unknown>) ?
+      (value as Record<string, unknown>).value
+    : value;
+
+  // A rich-text document is its text: a field with fixed choices can hold the document an editor wrote
+  // (for example while its choices could not be loaded), and the document for "Case" is the choice "Case".
+  const text = Array.isArray(stored) ? richtextToString(stored as never) : undefined;
+
+  return options.find(
+    (option) =>
+      option?.value?.value === value ||
+      option?.value === value ||
+      option?.name === value ||
+      option?.value?.value === stored ||
+      option?.value === stored ||
+      option?.name === stored ||
+      (text !== undefined &&
+        (option?.value?.value === text || option?.value === text || option?.name === text)) ||
+      // A hash- or list-valued choice is a fresh object every time the schema
+      // arrives, so identity can never match it; its contents can.
+      (isStructured(stored) &&
+        (isEqual(option?.value?.value, stored) || isEqual(option?.value, stored)))
+  );
+};
+
+/**
+ * A Slate rich-text document: a non-empty array of element nodes, each with
+ * `children`. Told apart from a LIST value, which is an array of elements.
+ */
+const isRichTextDocument = (value: unknown): boolean =>
+  Array.isArray(value) &&
+  value.length > 0 &&
+  value.every(
+    (node) => !!node && typeof node === 'object' && Array.isArray((node as any).children)
+  );
+
+/** A value resolved only when the interface runs — never one of the choices. */
+const isResolvedAtRunTime = (value: unknown): boolean =>
+  (typeof value === 'string' && isValueTemplate(value)) || richtextHasTag(value);
+
+const isEmptyChoiceValue = (value: unknown): boolean =>
+  value === undefined ||
+  value === null ||
+  value === '' ||
+  (Array.isArray(value) && value.length === 0);
+
+/** The fields of a schema entry the choice check reads. */
+export interface IChoiceFieldSchema {
+  allowed_values?: any[];
+  allowed_values_creatable?: boolean;
+  element_allowed_values?: any[];
+  element_allowed_values_creatable?: boolean;
+  multiselect?: boolean;
+  /** Set when the value is an expression, which is resolved at run time. */
+  isFunction?: boolean;
+  is_expression?: boolean;
+}
+
+/**
+ * The parts of a stored value that are not among the field's fixed choices.
+ *
+ * Empty when the value is acceptable, or when there is nothing to judge it
+ * against:
+ * - an empty value (whether one is needed is the required check's question);
+ * - an expression, a template string or a document holding a template tag,
+ *   all of which are resolved when the interface runs;
+ * - `allowed_values: []` — the server has no choices to offer right now, which
+ *   is "unknown", not "nothing is allowed";
+ * - creatable choices, where any value may be added.
+ *
+ * A single-valued field is judged as a whole. A multi-select field, and a list
+ * whose elements are constrained by `element_allowed_values`, are judged per
+ * element, so the answer names exactly the elements that are not choices.
+ */
+export const getUnlistedChoices = (value: unknown, field?: IChoiceFieldSchema): unknown[] => {
+  if (!field || isEmptyChoiceValue(value) || field.isFunction || field.is_expression) {
+    return [];
+  }
+
+  const judgeElements = (elements: unknown[], choices: any[]): unknown[] =>
+    elements.filter((element) => {
+      const stored = getListElementValue(element);
+      if (isEmptyChoiceValue(stored) || isResolvedAtRunTime(stored)) {
+        return false;
+      }
+      if ((element as { is_expression?: boolean })?.is_expression) {
+        return false;
+      }
+      return !findAllowedValueOption(element, { allowed_values: choices } as never);
+    });
+
+  if (isResolvedAtRunTime(value)) {
+    return [];
+  }
+
+  if (field.allowed_values?.length && !field.allowed_values_creatable) {
+    if (findAllowedValueOption(value, { allowed_values: field.allowed_values } as never)) {
+      return [];
+    }
+    // A multi-select holds a list of choices; any list that is not itself a
+    // choice is judged element by element.
+    if (Array.isArray(value) && !isRichTextDocument(value)) {
+      return judgeElements(value, field.allowed_values);
+    }
+    return [value];
+  }
+
+  if (
+    field.element_allowed_values?.length &&
+    !field.element_allowed_values_creatable &&
+    !field.allowed_values_creatable &&
+    Array.isArray(value) &&
+    !isRichTextDocument(value)
+  ) {
+    return judgeElements(value, field.element_allowed_values);
+  }
+
+  return [];
+};
+
+/** How a value not among the choices is named in the message. */
+const describeChoiceValue = (value: unknown): string => {
+  const stored = getListElementValue(value);
+  if (typeof stored === 'string') {
+    return stored;
+  }
+  if (isRichTextDocument(stored)) {
+    return richtextToString(stored as never);
+  }
+  if (stored === null || typeof stored !== 'object') {
+    return String(stored);
+  }
+  try {
+    return JSON.stringify(stored);
+  } catch {
+    return String(stored);
+  }
+};
+
+/**
+ * Why a stored value is not acceptable for a field with fixed choices, or
+ * `undefined` when it is (see {@link getUnlistedChoices} for what is judged).
+ *
+ * The value is kept — it is never erased for not being a choice — and this
+ * reason is what makes the field invalid, so the form shows it under "Needs
+ * attention" and blocks submitting until the author picks a choice.
+ */
+export const getUnlistedChoiceReason = (
+  value: unknown,
+  field?: IChoiceFieldSchema
+): string | undefined => {
+  const unlisted = getUnlistedChoices(value, field);
+  if (!unlisted.length) {
+    return undefined;
+  }
+  const names = unlisted.map((item) => `"${describeChoiceValue(item)}"`);
+  if (names.length === 1) {
+    return `${names[0]} is not one of the choices`;
+  }
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]} are not among the choices`;
+};

package/src/helpers/common.ts

@@ -93,6 +93,20 @@ export const getDefaultValue = (schema?: TQorusFormFieldSchema): unknown | undef
   return undefined;
 };
 
+/**
+ * Whether a rich-text document contains a template tag (a `$local:...`-style reference drawn as a chip).
+ *
+ * Such a value is resolved when the interface runs, so it can never be one of a field's fixed choices and must
+ * not be judged against them.
+ */
+export const richtextHasTag = (richtext: unknown): boolean => {
+  const walk = (node: any): boolean =>
+    !!node &&
+    typeof node === 'object' &&
+    (node.type === 'tag' || (Array.isArray(node.children) && node.children.some(walk)));
+  return Array.isArray(richtext) && richtext.some(walk);
+};
+
 export const richtextToString = (richtext: IReqoreRichTextEditorProps['value']): string => {
   // A `richtext` ui_type option can still hold a plain scalar value (set
   // programmatically or loaded from the server before the editor ever touched