@qoretechnologies/reqraft 0.10.41-pr.95.g294e5aa → 0.10.41

package/src/helpers/optionUiTypes.ts

@@ -0,0 +1,153 @@
+/**
+ * The Qorus option `ui_type` vocabulary.
+ *
+ * A `ui_type` names the widget an option is rendered with, and — because the
+ * widget decides what a complete value looks like — it is also what
+ * `validateField` switches on. Both readers have to agree about which strings
+ * are in the vocabulary, so the lists live here rather than beside either one.
+ *
+ * Grouped by what the group means to a reader, not by alphabet: the scalar
+ * types hold a single value, the collection types hold several, the choice
+ * types pick from a supplied set, and the interface types name another Qorus
+ * object by its name — which is why `isOptionInterfaceUiType` is enough for
+ * validation to treat the whole group as a non-empty string.
+ */
+
+export const OPTION_SCALAR_UI_TYPES = [
+  'string',
+  'long-string',
+  'data',
+  'binary',
+  'richtext',
+  'bool',
+  'boolean',
+  'date',
+  'int',
+  'integer',
+  'float',
+  'number',
+  'byte-size',
+  'url',
+  'code-editor',
+  'rgbcolor',
+  'any',
+  'auto',
+  // semantic string formats (string-backed types that carry a UI-renderable identity; see the qore
+  // DataProvider QoreStringFormatDataType)
+  'email',
+  'uri',
+  'uuid',
+  'hostname',
+  'ipv4',
+  'ipv6',
+  'phone',
+] as const;
+
+export const OPTION_COLLECTION_UI_TYPES = [
+  'hash',
+  'free-hash',
+  'list',
+  'free-list',
+  'option_hash',
+  'file',
+  'file-as-string',
+  'collection-documents',
+] as const;
+
+export const OPTION_CHOICE_UI_TYPES = [
+  'enum',
+  'select-string',
+  'select-array',
+  'multi-select',
+] as const;
+
+export const OPTION_INTERFACE_UI_TYPES = [
+  'workflow',
+  'service',
+  'job',
+  'connection',
+  'mapper',
+  'class',
+  'value-map',
+  'fsm',
+  'qog',
+  'api-schema',
+  'auth-profile',
+  'ai-collection',
+  'ai-endpoint',
+  'ai-guardrail',
+  'ml-model',
+  'release-config',
+  'alertrule',
+  'alertsilence',
+  'installed-release',
+  'business-process',
+  'schema',
+  'test',
+] as const;
+
+export const OPTION_CUSTOM_UI_TYPES = [
+  'processor',
+  'processor-mappings',
+  'data-provider',
+  'tool-catalog',
+  'schema-definition',
+  'test-cases',
+  'test-value-contract',
+  'dpql',
+  'active-windows',
+] as const;
+
+export const OPTION_UI_TYPES = [
+  ...OPTION_SCALAR_UI_TYPES,
+  ...OPTION_COLLECTION_UI_TYPES,
+  ...OPTION_CHOICE_UI_TYPES,
+  ...OPTION_INTERFACE_UI_TYPES,
+  ...OPTION_CUSTOM_UI_TYPES,
+] as const;
+
+export type TOptionUiType = (typeof OPTION_UI_TYPES)[number];
+export type TOptionInterfaceUiType = (typeof OPTION_INTERFACE_UI_TYPES)[number];
+
+export const LEGACY_FIELD_UI_TYPES = [
+  'api-manager',
+  'array',
+  'array-auto',
+  'array-of-pairs',
+  'class-array',
+  'class-connectors',
+  'constant-array',
+  'context-selector',
+  'cron',
+  'data-provider-options',
+  'file-array',
+  'fsm-list',
+  'function-array',
+  'http-content',
+  'method-name',
+  'opcua-method-arguments',
+  'opcua-write-values',
+  'options',
+  'select',
+  'service-events',
+  'service-webhooks',
+  'type-selector',
+] as const;
+
+export const KNOWN_QORUS_UI_TYPES = [...OPTION_UI_TYPES, ...LEGACY_FIELD_UI_TYPES] as const;
+
+export type TLegacyFieldUiType = (typeof LEGACY_FIELD_UI_TYPES)[number];
+export type TKnownQorusUiType = (typeof KNOWN_QORUS_UI_TYPES)[number];
+
+const optionUiTypeSet = new Set<string>(OPTION_UI_TYPES);
+const interfaceUiTypeSet = new Set<string>(OPTION_INTERFACE_UI_TYPES);
+const knownQorusUiTypeSet = new Set<string>(KNOWN_QORUS_UI_TYPES);
+
+export const isOptionUiType = (type: unknown): type is TOptionUiType =>
+  typeof type === 'string' && optionUiTypeSet.has(type);
+
+export const isOptionInterfaceUiType = (type: unknown): type is TOptionInterfaceUiType =>
+  typeof type === 'string' && interfaceUiTypeSet.has(type);
+
+export const isKnownQorusUiType = (type: unknown): type is TKnownQorusUiType =>
+  typeof type === 'string' && knownQorusUiTypeSet.has(type);

package/src/helpers/options.ts

@@ -29,3 +29,26 @@ export const getRequiredOptionMessage = (
 
   return `This field or ${requiredOptions} is required`;
 };
+
+/**
+ * The value of one element of a list field.
+ *
+ * A list element arrives in either of two shapes, and both are legitimate. The
+ * editor keeps each element in a `{value, type}` envelope while the form is
+ * being worked on — that is what `formatToServerValue` writes — while a value
+ * read back from storage holds what the server contract asks for, which for a
+ * list of strings is the bare strings.
+ *
+ * Reaching straight for `.value` answered `undefined` for every stored element.
+ * On a read that emptied the row; on a validation pass it failed the element as
+ * empty; and on an autosaving form the emptiness was then written back over the
+ * stored value. One helper so the readers cannot disagree about which shape
+ * they are looking at.
+ *
+ * An array is never an envelope — a rich-text document is itself an array, and
+ * `'value' in []` is false anyway, but saying so keeps the intent legible.
+ */
+export const getListElementValue = (element: unknown): unknown =>
+  element && typeof element === 'object' && !Array.isArray(element) && 'value' in element ?
+    (element as { value: unknown }).value
+  : element;

package/src/helpers/providerValue.ts

@@ -0,0 +1,125 @@
+import { TQorusForm } from '@qoretechnologies/ts-toolkit';
+
+export type TRecordType = 'search' | 'search-single' | 'create' | 'update' | 'delete';
+export type TRealRecordType = 'read' | 'create' | 'update' | 'delete';
+
+export type TProviderTypeSupports = {
+  [key in `supports_${TRealRecordType}`]?: boolean;
+};
+
+export type TProviderTypeArgs = {
+  [key in `${TRecordType}_args`]?: TQorusForm | TQorusForm[];
+};
+
+/**
+ * A data-provider selection, in the shape the form holds it.
+ *
+ * The `supports_*` flags say which record operations the selected provider can
+ * perform; validation reads them to decide whether a provider is a legitimate
+ * target for the operation the field was configured for.
+ */
+export interface IProviderType extends TProviderTypeSupports, TProviderTypeArgs {
+  type: string;
+  name: string;
+  path?: string;
+  options?: TQorusForm;
+  subtype?: 'request' | 'response';
+  hasApiContext?: boolean;
+  optionsChanged?: boolean;
+  searchOptionsChanged?: boolean;
+  desc?: string;
+  use_args?: boolean;
+  args?: any;
+  up?: boolean;
+  supports_request?: boolean;
+  supports_messages?: 'ASYNC' | 'SYNC' | 'NONE';
+  supports_observable?: boolean;
+  transaction_management?: boolean;
+  record_requires_search_options?: boolean;
+  create_args_freeform?: TQorusForm[];
+  is_api_call?: boolean;
+  search_options?: TQorusForm;
+  descriptions?: string[];
+  message_id?: string;
+  message?: {
+    type: string;
+    value: any;
+  };
+}
+
+/**
+ * A provider value as an object, from either representation a caller may hold.
+ *
+ * A provider reaches the form either already expanded into `IProviderType`, or
+ * as the flat path string the server stores — `"factory/db{driver=pgsql}/table"`
+ * or the plain `"type/name/path"`. Returns `null` for anything that is neither,
+ * so a caller reports an invalid value rather than reading fields off nothing.
+ */
+export const maybeBuildOptionProvider = (provider: unknown): IProviderType | null => {
+  if (!provider) {
+    return null;
+  }
+  if (typeof provider === 'object') {
+    return provider as IProviderType;
+  }
+  if (typeof provider !== 'string') {
+    return null;
+  }
+
+  if (provider.startsWith('factory')) {
+    const fixedProvider = provider.endsWith('/') ? provider : `${provider}/`;
+    const [factoryType] = fixedProvider.split('/');
+    const factoryName = fixedProvider.substring(
+      fixedProvider.indexOf('/') + 1,
+      fixedProvider.lastIndexOf('{')
+    );
+    const options = fixedProvider.substring(
+      fixedProvider.indexOf('{') + 1,
+      fixedProvider.lastIndexOf('}')
+    );
+    const optionsObject = options
+      .split(',')
+      .filter(Boolean)
+      .reduce<Record<string, string>>((result, option) => {
+        const [key, value] = option.split('=');
+        result[key] = value;
+        return result;
+      }, {});
+    const result: IProviderType = {
+      type: factoryType,
+      name: factoryName,
+      path: fixedProvider.substring(fixedProvider.lastIndexOf('}/') + 2),
+      options: optionsObject as unknown as TQorusForm,
+    };
+    if (provider.includes('?options_changed')) {
+      result.optionsChanged = true;
+    }
+    return result;
+  }
+
+  const [type, name, ...path] = provider.split('/');
+  return { type, name, path: path.join('/') };
+};
+
+/**
+ * An FSM variable action — which variable, and what is done to it.
+ *
+ * The provider half is `Partial<IProviderType>` because the action's own
+ * `action_type` decides which provider fields have to be there; validation
+ * re-runs the matching provider validator over the merged value rather than
+ * duplicating those rules here.
+ */
+export type TVariableActionValue = {
+  var_type: 'globalvar' | 'localvar' | 'autovar';
+  var_name: string;
+  transaction_action?: 'commit' | 'rollback' | 'begin-transaction';
+  action_type?:
+    | 'search'
+    | 'search-single'
+    | 'update'
+    | 'create'
+    | 'delete'
+    | 'transaction'
+    | 'send-message'
+    | 'apicall';
+} & Partial<IProviderType>;

package/src/helpers/singleLineString.ts

@@ -0,0 +1,61 @@
+/**
+ * Which string field types hold one line, and how to keep them that way.
+ *
+ * The server already draws this distinction and the IDE was throwing it away:
+ * a service's `name` is declared `ui_type: "string"` while its `description` is
+ * `ui_type: "long-string"` with `markdown: True` (see `ServiceMetadata.qc`).
+ * Every one of them — plus `email`, `uuid`, `hostname`, `ipv4`, `ipv6` and
+ * `phone` — rendered through the same growing textarea, so a technical name, a
+ * version and an IP address all accepted Enter.
+ *
+ * That is not a cosmetic problem. These values become YAML keys, class names,
+ * URLs and identifiers; a newline in one of them is invalid input that the form
+ * happily accepted and passed on, and the operator had no way to see it.
+ *
+ * The rule is the server's own contract, stated once here rather than guessed
+ * per field, and it is enforced in `LongString.tsx`.
+ *
+ * It lives in reqraft rather than in a consumer because the consumer is not the
+ * only renderer: qorus-ide fixed this in its OWN long-string field, and every
+ * form that goes through FormEngine — which is where an alert rule's Internal
+ * Name, Name and Short Description are — reaches THIS one instead. The fix was
+ * real and the field in front of the operator still took Enter.
+ */
+
+/**
+ * The string types that hold exactly one line — the ones routed to a textarea
+ * today.
+ *
+ * Listed explicitly rather than derived by excluding the document types,
+ * because the two directions fail very differently. Missing a single-line type
+ * here leaves it behaving as it does now — no worse. Wrongly treating a new
+ * DOCUMENT type as single-line would flatten a user's text as they typed it,
+ * which is data loss. So an unrecognised type stays multi-line.
+ */
+const SINGLE_LINE_STRING_TYPES = new Set([
+  'string',
+  'email',
+  'uuid',
+  'hostname',
+  'ipv4',
+  'ipv6',
+  'phone',
+]);
+
+/** True when a string field of this type holds a single line. */
+export const isSingleLineStringType = (type?: string): boolean =>
+  !!type && SINGLE_LINE_STRING_TYPES.has(type);
+
+/**
+ * Flattens any line break to a single space.
+ *
+ * A space rather than nothing, because the newline is usually where a word
+ * boundary was — pasting two lines into a name should read as two words, not
+ * one run-together one. CR, LF and CRLF all collapse to one space, and the
+ * result is trimmed of leading/trailing whitespace the break introduced.
+ */
+export const flattenToSingleLine = (value: string): string =>
+  value.replace(/\r\n|\r|\n/g, ' ').replace(/ {2,}/g, ' ');
+
+/** True when the value carries a line break this field should not hold. */
+export const hasLineBreak = (value: string): boolean => /\r|\n/.test(value);

package/src/helpers/templates.ts

@@ -1,11 +1,25 @@
+import { modalStore } from '@qoretechnologies/reqore';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import {
   TReqoreDropdownItem,
   TReqoreDropdownItems,
 } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
 import { cloneDeep, size } from 'lodash';
+import { createElement } from 'react';
+import { ReqraftTemplateExampleValueModal } from '../components/form/fields/template/ExampleValueModal';
 import { areQorusTypesCompatible } from './expressions';
 
+/**
+ * The DOM ceiling for a serialized example value in a picker item — a
+ * binary-carrying field's example (e.g. an email attachment body) can be an
+ * entire base64 file, and it must not enter the item wholesale. The VISUAL
+ * truncation is not this number: past the ceiling the item also gets a
+ * single-line-ellipsis description (`descriptionEffect.noWrap`), which cuts at
+ * the popover's ACTUAL rendered width — container-intrinsic, no breakpoints —
+ * paired with the "?" action that shows the full value.
+ */
+export const TEMPLATE_EXAMPLE_PREVIEW_LENGTH = 150;
+
 /**
  * Shared template string utilities.
  * Used by both validations and TemplateField.
@@ -38,6 +52,119 @@ export const getTemplateValue = (value: string): string => {
   return value.substring(colonIndex + 1);
 };
 
+/**
+ * The canonical template-token grammar (twin of the IDE's
+ * `helpers/templateValue.ts` — keep the two in step). A token is
+ * `$<key>:<segment>(:<segment>)*` where the key may carry dashes
+ * (`-expr`) and every segment is either a plain word or a braced
+ * context reference — `{W2n….filename}` — whose content may hold dots,
+ * colons, spaces and dashes (`:{deep:test:list}`,
+ * `{id.Created by.name}`). `isValueTemplate` above stays deliberately
+ * LOOSER (starts with `$`, has `:`): it answers "does the user mean a
+ * template here" while typing; use the strict check below when a decision
+ * must not misfire on user-typed dollar-strings.
+ */
+export const TEMPLATE_TOKEN_SOURCE =
+  '\\$[A-Za-z_][\\w-]*(?::(?:\\{[^}]*\\}|[A-Za-z_][\\w-]*))+';
+
+const COMPLETE_TEMPLATE_TOKEN = new RegExp(`^${TEMPLATE_TOKEN_SOURCE}$`);
+
+/** STRICT whole-value check: the entire string is one well-formed template
+ *  token (`:{id.path}`, `:item`, …) — nothing before or after.
+ *  `'$foo: hello'` passes the loose check but not this one. */
+export const isCompleteTemplateToken = (value?: unknown): value is string =>
+  typeof value === 'string' && COMPLETE_TEMPLATE_TOKEN.test(value);
+
+/** A complete token carrying at least one BRACED context segment —
+ *  `$data:{W2n….filename}`, `$qore-expr:{1 + 2}`. These are machine-written
+ *  references nobody types by hand, so a surface may render them as a picker
+ *  chip. Plain word-path tokens (`$local:id`) stay typeable and belong in the
+ *  template-offering input (build #123 review). Word segments cannot contain
+ *  `{`, so `:{` inside a complete token always starts a braced segment. */
+export const isBracedTemplateToken = (value?: unknown): value is string =>
+  isCompleteTemplateToken(value) && value.includes(':{');
+
+/**
+ * An FSM state carries TWO identities: the key it occupies in the `states`
+ * hash and its own `id`. The IDE gives both the same nanoid, so nothing
+ * authored there can tell them apart — but a template hand-writes numbered
+ * keys (`'1'`, `'2'`, …) over meaningful ids (`dc_ai_reply`), its saved
+ * `$data:{…}` references use the **id**, and the server's design-time
+ * catalogue spells its item values with the **key**. The two never match as
+ * text, so a template-derived Qog renders the raw token where a named chip
+ * belongs.
+ *
+ * The producer of the catalogue (the IDE, which is the side that holds the
+ * states) attaches the alternate spelling here rather than rewriting either
+ * side — a picked value must keep storing exactly what the catalogue says.
+ * Consuming it is therefore purely a display concern.
+ */
+const matchesTemplateValue = (item: TReqoreDropdownItem, value: string): boolean =>
+  item.value === value ||
+  !!(item.metadata as { aliasValues?: string[] } | undefined)?.aliasValues?.includes(value);
+
+/** Splits `$data:{a.b.c}` into its key (`$data`) and inner path (`a.b.c`). */
+const TEMPLATE_TOKEN_PATH = /^(\$[A-Za-z_][\w-]*):\{(.*)\}$/;
+
+const getTokenPath = (value?: unknown): { key: string; path: string } | undefined => {
+  const match = typeof value === 'string' ? TEMPLATE_TOKEN_PATH.exec(value) : null;
+  return match ? { key: match[1], path: match[2] } : undefined;
+};
+
+/**
+ * The longest catalogue item whose path is a PREFIX of `value`, plus the part
+ * of the path it does not cover.
+ *
+ * A catalogue can only offer what the action's output type declares, so it
+ * stops at a list: `choices` is offered, `choices[0].message.content` is not —
+ * an operator hand-extends the path past the named field. Such a value has no
+ * item to match and used to render as its own raw token. Naming it by its
+ * nearest ancestor (`Choices[0].message.content`) keeps the chip readable
+ * without inventing a catalogue entry that does not exist.
+ *
+ * The match must break at a path boundary (`.` or `[`) so `choicesOther` is
+ * never named after `choices`, and the token keys must agree so a `$config:`
+ * item never names a `$data:` value.
+ */
+export const findTemplateByPath = (
+  templates: IReqoreFormTemplates,
+  value: string
+): { item: TReqoreDropdownItem; remainder: string } | undefined => {
+  const ref = getTokenPath(value);
+  if (!ref) return undefined;
+
+  let best: { item: TReqoreDropdownItem; path: string; remainder: string } | undefined;
+
+  const consider = (item: TReqoreDropdownItem, candidate?: string) => {
+    const itemPath = getTokenPath(candidate);
+    if (!itemPath || itemPath.key !== ref.key || !ref.path.startsWith(itemPath.path)) {
+      return;
+    }
+    const boundary = ref.path[itemPath.path.length];
+    if (boundary !== '.' && boundary !== '[') {
+      return;
+    }
+    if (!best || itemPath.path.length > best.path.length) {
+      best = { item, path: itemPath.path, remainder: ref.path.slice(itemPath.path.length) };
+    }
+  };
+
+  const walk = (items?: TReqoreDropdownItems) => {
+    items?.forEach((item) => {
+      consider(item, item.value as string);
+      (item.metadata as { aliasValues?: string[] } | undefined)?.aliasValues?.forEach((alias) =>
+        consider(item, alias)
+      );
+      if (item.items) {
+        walk(item.items);
+      }
+    });
+  };
+
+  walk(templates?.items);
+  return best ? { item: best.item, remainder: best.remainder } : undefined;
+};
+
 export const findTemplate = (
   templates: IReqoreFormTemplates,
   value: string
@@ -48,7 +175,7 @@ export const findTemplate = (
 
   const findItem = (items: TReqoreDropdownItems) => {
     items?.forEach((item) => {
-      if (item.value === value) {
+      if (matchesTemplateValue(item, value)) {
         result = item;
         return;
       }
@@ -63,6 +190,113 @@ export const findTemplate = (
   return result;
 };
 
+/**
+ * Joins a catalogue item's name to the part of the path it does not cover.
+ * A field step reads as a step (`Choices › message`), while an array index
+ * binds to the name it indexes (`Choices[0]`) rather than floating off it.
+ */
+const composeExtendedLabel = (label: string, remainder: string): string =>
+  remainder.startsWith('.') ? `${label} › ${remainder.slice(1)}` : `${label}${remainder}`;
+
+/**
+ * The one answer to "what is this reference called?", so a value reads the
+ * same in the picker chip, the read-only tag and the compact row's summary.
+ * Exact match first (aliases included), then the nearest catalogue ancestor
+ * for a hand-extended path, and finally the raw token — which is honest when
+ * the catalogue holds nothing that explains the value.
+ */
+export const resolveTemplateLabel = (
+  templates: IReqoreFormTemplates | undefined,
+  value: string
+): { label: string; item?: TReqoreDropdownItem } => {
+  if (!templates || !value) {
+    return { label: value };
+  }
+
+  const exact = findTemplate(templates, value);
+  if (exact) {
+    return { label: (exact.label as string) || value, item: exact };
+  }
+
+  const extended = findTemplateByPath(templates, value);
+  if (extended) {
+    return {
+      label: composeExtendedLabel(extended.item.label as string, extended.remainder),
+      item: extended.item,
+    };
+  }
+
+  return { label: value };
+};
+
+/**
+ * What to call a reference when the catalogue explains nothing about it — the
+ * reference's own path, with the token wrapper stripped:
+ * `$data:{dc_ai_reply.choices[0].message.content}` reads as
+ * `dc_ai_reply.choices[0].message.content`.
+ *
+ * Surfaces exist with no catalogue at all (the Automation Hub template preview
+ * never fetches one), and there the raw token is the only thing left to show.
+ * Showing it as `$data:{…}` renders a value as code; showing the path renders
+ * it as a name, which is the honest floor.
+ */
+export const getTemplateReferencePath = (value: string): string =>
+  getTokenPath(value)?.path ?? value;
+
+/**
+ * The best available name for a reference, for a surface that must show
+ * something readable no matter what: the catalogue's name when it has one,
+ * otherwise the bare path. `resolveTemplateLabel` keeps falling back to the
+ * raw token, because a picker that cannot resolve a value should say exactly
+ * what the value is.
+ */
+export const describeTemplateReference = (
+  templates: IReqoreFormTemplates | undefined,
+  value: string
+): { label: string; item?: TReqoreDropdownItem } => {
+  const resolved = resolveTemplateLabel(templates, value);
+  return resolved.item ? resolved : { label: getTemplateReferencePath(value) };
+};
+
+const EMBEDDED_TEMPLATE_TOKEN = new RegExp(TEMPLATE_TOKEN_SOURCE, 'g');
+
+export type TTemplateTextSegment =
+  | { kind: 'text'; text: string }
+  | { kind: 'token'; text: string };
+
+/**
+ * Splits prose that embeds template tokens into its literal and token parts —
+ * `trim("$data:{…}")` becomes `trim("`, the token, `")`. Used to chip the
+ * references inside a rendered expression instead of printing them raw.
+ */
+export const splitTemplateTokens = (text?: string): TTemplateTextSegment[] => {
+  if (!text) {
+    return [];
+  }
+
+  const segments: TTemplateTextSegment[] = [];
+  let lastIndex = 0;
+
+  // A fresh regex per call: a shared /g instance carries `lastIndex` between
+  // calls and would skip tokens on the second string it is given.
+  const pattern = new RegExp(EMBEDDED_TEMPLATE_TOKEN.source, 'g');
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      segments.push({ kind: 'text', text: text.slice(lastIndex, match.index) });
+    }
+    segments.push({ kind: 'token', text: match[0] });
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < text.length) {
+    segments.push({ kind: 'text', text: text.slice(lastIndex) });
+  }
+
+  return segments;
+};
+
 // Ported verbatim from qorus-ide `helpers/functions.tsx` (FIELD_STACK_REPORT
 // batch) — the previous reqraft version used naive badge equality; the IDE
 // routes compatibility through `areQorusTypesCompatible` (int↔string coercion
@@ -192,11 +426,26 @@ export const buildTemplates = (
         items: childItems,
         data_role: itemDataRole,
       }): TReqoreDropdownItem => {
+        const serializedExample =
+          example_value !== undefined ? JSON.stringify(example_value) : undefined;
+        const exampleIsLong =
+          serializedExample !== undefined &&
+          serializedExample.length > TEMPLATE_EXAMPLE_PREVIEW_LENGTH;
+
         const item: TReqoreDropdownItem = {
           label: itemDisplayName,
-          description: example_value
-            ? `Example value: ${JSON.stringify(example_value)}`
+          description: serializedExample
+            ? `Example value: ${
+                exampleIsLong
+                  ? `${serializedExample.slice(0, TEMPLATE_EXAMPLE_PREVIEW_LENGTH)}…`
+                  : serializedExample
+              }`
             : undefined,
+          // Ellipsize ONLY where the "?" full-value affordance exists — for a
+          // short value an ellipsis would hide information with no way to
+          // reveal it. The single line cuts at the rendered width, so the
+          // preview adapts to any popover/panel width without breakpoints.
+          descriptionEffect: exampleIsLong ? { noWrap: true } : undefined,
           badge: type,
           metadata: {
             image: logo,
@@ -213,6 +462,26 @@ export const buildTemplates = (
           minimal: true,
         };
 
+        if (exampleIsLong) {
+          // Menu-item actions stop propagation, so the click never selects or
+          // expands the item. The modal rides reqore's global modal queue
+          // (rendered by the provider portal), so no host component is needed
+          // — the modals wrapper injects `isOpen`/`onClose` itself.
+          item.rightAction = {
+            icon: 'QuestionLine',
+            compact: true,
+            tooltip: 'Show the full example value',
+            onClick: () => {
+              modalStore.getState().addModal(
+                createElement(ReqraftTemplateExampleValueModal, {
+                  label: itemDisplayName,
+                  value: serializedExample,
+                })
+              );
+            },
+          };
+        }
+
         if (childItems?.length) {
           item.items = mapTemplates(
             childItems,