@qoretechnologies/reqraft 0.10.62 → 0.10.63-pr.142.g0b675cd

package/src/helpers/templates.ts

@@ -1,602 +0,0 @@
-import { modalStore } from '@qoretechnologies/reqore';
-import { TReqoreTooltipProp } from '@qoretechnologies/reqore/dist/types/global';
-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;
-
-/**
- * How template picker entries are ordered: by the label a reader actually sees.
- *
- * The server sends groups and their items in whatever order it assembled them —
- * for the test vocabulary that is step order, for an app's actions it is the
- * connector's own. Neither is an order a reader can predict, and a picker
- * holding 29 items is navigated by looking for a NAME.
- *
- * `localeCompare` with `numeric` so `item2` sorts before `item10`, and
- * `sensitivity: 'base'` so case and accents do not split otherwise-adjacent
- * neighbours.
- */
-const byLabel = (a: { label?: unknown }, b: { label?: unknown }): number =>
-  String(a?.label ?? '').localeCompare(String(b?.label ?? ''), undefined, {
-    numeric: true,
-    sensitivity: 'base',
-  });
-
-/**
- * Shared template string utilities.
- * Used by both validations and TemplateField.
- */
-
-export type TTemplateMeta = { image?: string; builtIn?: boolean; isEventTrigger?: boolean };
-
-export const getTemplateTagStyle = (
-  meta?: TTemplateMeta
-): { intent: 'success' | 'info' | 'custom1' } => {
-  if (meta?.isEventTrigger) return { intent: 'success' };
-  if (meta?.builtIn) return { intent: 'custom1' };
-  return { intent: 'info' };
-};
-
-export const isValueTemplate = (value: string): boolean => {
-  if (!value || typeof value !== 'string') {
-    return false;
-  }
-  return value.startsWith('$') && value.includes(':');
-};
-
-export const getTemplateKey = (value: string): string => {
-  const [key] = value.split(':');
-  return key.replace('$', '');
-};
-
-export const getTemplateValue = (value: string): string => {
-  const colonIndex = value.indexOf(':');
-  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-]*):\{(.*)\}$/;
-
-/**
- * The KEY-LESS spelling — `$.create.status`, `$._case.mode`, `$.order[0].sku`.
- *
- * A host may name its own references without a key and without braces: a Qorus
- * test reads what a step captured as `$.create`, and that is the whole token.
- * The path is captured WITH its leading `.`, so a prefix comparison is between
- * two strings of the same shape and `$.create` still ends at a path boundary
- * inside `$.create.status`.
- *
- * Deliberately strict — a root segment, then any number of further `.field`
- * steps and `[0]` indices, and nothing else — so it cannot claim a keyed token
- * (which carries a `:`) or a bare `$word`.
- */
-const KEYLESS_TOKEN_PATH = /^\$((?:\.[A-Za-z_][\w-]*|\[\d+\])+)$/;
-
-/**
- * "No key" is a key of its own.
- *
- * `findTemplateByPath` refuses to name a value from an item under a different
- * key, and the key-less grammar has to take part in that rule rather than sit
- * outside it: a `$data:{create.status}` item must not name `$.create.status`,
- * and a `$.create` item must not name `$data:{create.status}`. Every keyed
- * token's key begins with `$`, so the empty string can never collide with one.
- */
-const NO_TOKEN_KEY = '';
-
-const getTokenPath = (value?: unknown): { key: string; path: string } | undefined => {
-  if (typeof value !== 'string') {
-    return undefined;
-  }
-  const keyed = TEMPLATE_TOKEN_PATH.exec(value);
-  if (keyed) {
-    return { key: keyed[1], path: keyed[2] };
-  }
-  const keyless = KEYLESS_TOKEN_PATH.exec(value);
-  return keyless ? { key: NO_TOKEN_KEY, path: keyless[1] } : 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 — "no key" included, so the key-less
- * grammar and the keyed one never name each other's references.
- *
- * Both grammars arrive here: `$data:{create.choices[0]}` and the key-less
- * `$.create.status` are the same question asked in two spellings, and a
- * catalogue written in either one names the walks its author took past it.
- */
-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
-): TReqoreDropdownItem | undefined => {
-  if (!value) return undefined;
-
-  let result: TReqoreDropdownItem | undefined = undefined;
-
-  const findItem = (items: TReqoreDropdownItems) => {
-    items?.forEach((item) => {
-      if (matchesTemplateValue(item, value)) {
-        result = item;
-        return;
-      }
-
-      if (item.items) {
-        findItem(item.items);
-      }
-    });
-  };
-
-  findItem(templates?.items);
-  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.
- *
- * Only a BRACED wrapper is stripped, because only a braced wrapper is one.
- * A key-less `$._case.mode` stripped of its `$` reads as `._case.mode`, which
- * is neither the reference nor a name for it; with nothing to call it, the
- * reference as written is the honest answer.
- */
-export const getTemplateReferencePath = (value: string): string =>
-  (typeof value === 'string' ? TEMPLATE_TOKEN_PATH.exec(value)?.[2] : undefined) ?? 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) };
-};
-
-/**
- * What a chosen template's hover should say.
- *
- * The reference itself — `$._case.title`, `$data:{dc_ai_reply.choices[0]…}` —
- * is an implementation detail of the grammar, and it was what every template
- * chip put in its tooltip. An author hovering a chip wants to know WHAT VALUE
- * this is, and the catalogue already carries that: the entry's `description`
- * is the prose the picker lists it under, written from the schema that declares
- * it, with its type appended.
- *
- * So the hover reads as a small card — the value's name as the title, its
- * description as the body — and the path stays where it is genuinely needed:
- * the field's own help, which teaches the grammar with a worked example, and
- * the picker, for the walks no list can hold.
- *
- * Falls back to the resolved label (itself the stripped path when the catalogue
- * explains nothing), because a surface with no catalogue must still say what
- * the value is rather than nothing at all.
- */
-export const templateTooltip = (
-  templates: IReqoreFormTemplates | undefined,
-  value: string
-): TReqoreTooltipProp => {
-  const { label, item } = describeTemplateReference(templates, value);
-  const description = (item as { description?: unknown } | undefined)?.description;
-  return typeof description === 'string' && description.trim() ?
-      { title: label, content: description, maxWidth: '360px' }
-    : label || value;
-};
-
-// 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
-// etc.) and keeps top-level groups with their (possibly emptied) sub-items.
-export const filterTemplatesByType = (
-  templates: IReqoreFormTemplates = {},
-  fieldType = 'string',
-  hasArgSchema?: boolean
-): IReqoreFormTemplates => {
-  if ((fieldType === 'hash' || fieldType === 'list') && hasArgSchema) {
-    return templates;
-  }
-
-  const newTemplates = cloneDeep(templates);
-
-  const filterItems = (items: TReqoreDropdownItems = []): TReqoreDropdownItems => {
-    return items?.reduce((newItems: TReqoreDropdownItem[], subItem): TReqoreDropdownItem[] => {
-      const newSubItem = cloneDeep(subItem);
-      const isCompatible = areQorusTypesCompatible(fieldType, subItem.badge as string);
-
-      if (subItem.items) {
-        newSubItem.items = filterItems(subItem.items);
-
-        if (!size(newSubItem.items)) {
-          delete newSubItem.items;
-        }
-      }
-
-      if (size(newSubItem.items)) {
-        if (!isCompatible) {
-          return [
-            ...newItems,
-            {
-              ...newSubItem,
-              leftAction: undefined,
-            },
-          ];
-        }
-
-        return [...newItems, newSubItem];
-      }
-
-      if (isCompatible) {
-        return [
-          ...newItems,
-          {
-            ...newSubItem,
-            leftAction: undefined,
-          },
-        ];
-      }
-
-      return newItems;
-    }, []);
-  };
-
-  newTemplates.items = newTemplates.items?.reduce((newItems: TReqoreDropdownItem[], item) => {
-    if (item.divider) {
-      return [...newItems, item];
-    }
-    const subItems = filterItems(item.items);
-
-    return [
-      ...newItems,
-      {
-        ...item,
-        items: subItems,
-      },
-    ];
-  }, []);
-
-  return newTemplates;
-};
-
-// --- buildTemplates — ported verbatim from qorus-ide `helpers/functions.tsx`
-// (line ~870). Converts the server's `system/getContextData` payload into
-// ReQore dropdown templates. SEAM (reqraft): the IDE's optional `states`
-// (FSM validity) parameter is dropped — without it every group is valid.
-
-interface ITemplateItemPayload {
-  display_name?: string;
-  value?: string;
-  example_value?: unknown;
-  type?: string;
-  items?: ITemplateItemPayload[];
-  data_role?: string;
-}
-
-export interface ITemplatesPayload {
-  [dataId: string]: {
-    display_name?: string;
-    items?: ITemplateItemPayload[];
-    app?: string;
-    action?: string;
-    short_desc?: string;
-    internal?: boolean;
-    builtin?: boolean;
-    is_event_trigger?: boolean;
-    data_role?: string;
-    logo?: string;
-  };
-}
-
-export const buildTemplates = (
-  templates?: ITemplatesPayload
-): IReqoreFormTemplates | undefined => {
-  if (!templates || !Object.keys(templates).length) {
-    return undefined;
-  }
-
-  const mapTemplates = (
-    items: ITemplateItemPayload[] = [],
-    app?: string,
-    action?: string,
-    logo?: string,
-    display_name?: string,
-    builtIn?: boolean,
-    isEventTrigger?: boolean,
-    dataRole?: string
-  ): TReqoreDropdownItems =>
-    items.map(
-      ({
-        display_name: itemDisplayName,
-        value,
-        example_value,
-        type,
-        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: 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,
-            displayName: display_name,
-            builtIn,
-            isEventTrigger,
-            app,
-            action,
-            dataRole: itemDataRole || dataRole,
-          },
-          value,
-          flat: false,
-          transparent: false,
-          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,
-            app,
-            action,
-            logo,
-            display_name,
-            builtIn,
-            isEventTrigger,
-            dataRole
-          );
-          item.stackWithActions = false;
-          item.leftAction = {
-            icon: 'AddCircleLine',
-            compact: true,
-            tooltip: 'Select this item',
-            onClick: (_event, _itemId, _closePopover, metadata) => {
-              (metadata as { selectItem?: () => void })?.selectItem?.();
-            },
-          };
-        }
-
-        return item;
-      }
-    ).sort(byLabel);
-
-  return {
-    items: Object.values(templates).map(
-      ({
-        display_name,
-        items,
-        app,
-        action,
-        short_desc,
-        builtin,
-        is_event_trigger,
-        data_role,
-        logo,
-      }): TReqoreDropdownItem => ({
-        label: display_name,
-        description: short_desc,
-        flat: false,
-        transparent: false,
-        minimal: true,
-        leftIconProps: {
-          image: logo,
-        },
-        badge: app,
-        metadata: {
-          dataRole: data_role,
-        },
-        items: mapTemplates(
-          items,
-          app,
-          action,
-          logo,
-          display_name,
-          builtin,
-          is_event_trigger,
-          data_role
-        ),
-      })
-    ).sort(byLabel),
-  } as IReqoreFormTemplates;
-};