@qoretechnologies/reqraft 0.10.53 → 0.10.54-pr.115.g9bc96ed

package/src/components/form/fields/rich-text/RichText.tsx

@@ -4,10 +4,27 @@ import {
 } from '@qoretechnologies/reqore/dist/components/RichTextEditor';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { IReqoreTagProps } from '@qoretechnologies/reqore/dist/components/Tag';
+import { IReqoreTooltip } from '@qoretechnologies/reqore/dist/types/global';
 import { isEqual, size } from 'lodash';
-import { memo, useCallback, useEffect, useMemo, useState } from 'react';
+import { KeyboardEvent, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
-import { getTemplateTagStyle } from '../../../../helpers/templates';
+import { flattenToSingleLine, hasLineBreak } from '../../../../helpers/singleLineString';
+import {
+  renderTemplateItemDescriptions,
+  templateItemsToShow,
+} from '../../../../helpers/templateItems';
+import {
+  templateChipLabel,
+  templateNodesToText,
+  templateTextToNodes,
+} from '../../../../helpers/templateText';
+import {
+  describeTemplateReference,
+  getTemplateTagStyle,
+  templateTooltip,
+  TTemplateMeta,
+} from '../../../../helpers/templates';
+import { useMarkdownRenderer } from '../../../Description/markdownRendererContext';
 
 export interface IRichTextFormFieldProps extends Omit<
   IReqoreRichTextEditorProps,
@@ -17,18 +34,85 @@ export interface IRichTextFormFieldProps extends Omit<
   onChange?: (value: string | IReqoreRichTextEditorProps['value']) => void;
   allowTemplates?: boolean;
   templates?: IReqoreFormTemplates;
+  /**
+   * What the value is. `richtext` (the default) stores the editor's document.
+   * `text` stores a plain string: each template reference in it is drawn as a
+   * chip named from `templates`, and what is emitted is the string again — for
+   * a string field whose value may hold references (`Dear $local:name`).
+   */
+  valueFormat?: 'richtext' | 'text';
+  /** With `valueFormat: 'text'`: the value holds one line, so Enter adds none. */
+  singleLine?: boolean;
 }
 
+/**
+ * What each offered template value is FOR, keyed by the value itself.
+ *
+ * Built from the templates a field was already given rather than from the
+ * chip's metadata, which carries only `image` / `displayName` / style flags —
+ * putting a description there would mean threading one through every producer
+ * of a template list.
+ *
+ * Exported so the mapping is assertable without rendering a Slate editor.
+ */
+export const getChipTooltipDescriptions = (
+  templates?: IReqoreFormTemplates
+): Record<string, string> => {
+  const out: Record<string, string> = {};
+
+  /* BOTH shapes, because this list arrives in either one. A picker's items are
+     normally grouped by category, but a LONE category is opened onto its values
+     where the templates are resolved (`templateItemsToShow`), so a field with
+     one category hands down a FLAT list of leaves. Walking only groups made
+     that the common case and silently lost every tooltip on it — one category
+     is the ordinary shape for a field, not the exception.
+
+     Recursive rather than two-level: a leaf is recognised by carrying a value
+     rather than by its depth, so a deeper catalogue works too. */
+  const collect = (items: any[] | undefined): void => {
+    items?.forEach((item: any) => {
+      const value = typeof item?.value === 'object' ? item?.value?.value : item?.value;
+      const description = item?.description ?? item?.short_desc;
+      if (typeof value === 'string' && typeof description === 'string' && description) {
+        out[value] = description;
+      }
+      collect(item?.items);
+    });
+  };
+
+  collect((templates as any)?.items);
+
+  return out;
+};
+
 export const RichTextFormField = memo(({
   value,
   onChange,
   allowTemplates,
   templates,
+  valueFormat = 'richtext',
+  singleLine,
   ...rest
 }: IRichTextFormFieldProps) => {
-  const [localValue, setLocalValue] = useState<any>(value);
+  const isText = valueFormat === 'text';
+  const [localValue, setLocalValue] = useState<any>(() =>
+    isText ? templateTextToNodes(String(value ?? ''), templates) : value
+  );
+  /* In text mode, the string the editor's document stands for. The value that
+     comes back from the parent is usually that same string, and rebuilding the
+     document from it would hand the editor a new tree on every keystroke —
+     which it answers by replacing its content and moving the cursor to the end. */
+  const lastTextRef = useRef(isText ? String(value ?? '') : '');
 
   useEffect(() => {
+    if (isText) {
+      const text = String(value ?? '');
+      if (text !== lastTextRef.current) {
+        lastTextRef.current = text;
+        setLocalValue(templateTextToNodes(text, templates));
+      }
+      return;
+    }
     if (JSON.stringify(value) !== JSON.stringify(localValue)) {
       setLocalValue(value);
     }
@@ -36,6 +120,12 @@ export const RichTextFormField = memo(({
 
   useDebounce(
     () => {
+      if (isText) {
+        if (lastTextRef.current !== String(value ?? '')) {
+          onChange?.(lastTextRef.current);
+        }
+        return;
+      }
       if (!isEqual(localValue, value)) {
         onChange?.(localValue);
       }
@@ -50,6 +140,19 @@ export const RichTextFormField = memo(({
   );
 
   const handleChange = (val: any): void => {
+    if (isText) {
+      const text = templateNodesToText(val);
+      // A line break also arrives by paste and by drag-and-drop; Enter alone is
+      // stopped below. Flattened text is shown as the one line it now is.
+      if (singleLine && hasLineBreak(text)) {
+        lastTextRef.current = flattenToSingleLine(text);
+        setLocalValue(templateTextToNodes(lastTextRef.current, templates));
+        return;
+      }
+      lastTextRef.current = text;
+      setLocalValue(val);
+      return;
+    }
     if (JSON.stringify(val) === '[{"type":"paragraph","children":[{"text":""}]}]') {
       setLocalValue(undefined);
       return;
@@ -57,26 +160,91 @@ export const RichTextFormField = memo(({
     setLocalValue(val);
   };
 
-  const handleGetTagProps = useCallback((tag: any): IReqoreTagProps => {
-    const tagValue = tag.value?.toString();
+  // One renderer for both surfaces below — the chip's hover and the picker rows
+  // show the same strings, so they must be drawn the same way.
+  const renderMarkdown = useMarkdownRenderer();
 
-    if (!tagValue) {
-      return {};
-    }
+  const descriptionByValue = useMemo(() => getChipTooltipDescriptions(templates), [
+    JSON.stringify(templates),
+  ]);
 
-    if (tagValue.startsWith('$')) {
-      return {
-        icon: 'ExchangeDollarLine',
-        leftIconProps: {
-          image: tag.metadata?.image,
-        },
-        labelKey: tag.metadata?.displayName,
-        ...getTemplateTagStyle(tag.metadata),
-      };
-    }
+  const handleGetTagProps = useCallback(
+    (tag: any): IReqoreTagProps => {
+      const tagValue = tag.value?.toString();
+
+      if (!tagValue) {
+        return {};
+      }
+
+      /* A reference in a string is drawn exactly as the collapsed row draws the
+         same value (`ReadOnlyTemplateTag`): named from the catalogue, its
+         description on hover. Read at render, so a catalogue that arrives
+         after the value still names it. */
+      if (isText && tagValue.startsWith('$')) {
+        const { item } = describeTemplateReference(templates, tagValue);
+        const metadata = item?.metadata as TTemplateMeta | undefined;
+        return {
+          icon: 'ExchangeDollarLine',
+          leftIconProps: { image: metadata?.image },
+          label: templateChipLabel(templates, tagValue),
+          tooltip: templateTooltip(templates, tagValue),
+          ...getTemplateTagStyle(metadata),
+        };
+      }
 
-    return {};
-  }, []);
+      if (tagValue.startsWith('$')) {
+        return {
+          icon: 'ExchangeDollarLine',
+          leftIconProps: {
+            image: tag.metadata?.image,
+          },
+          labelKey: tag.metadata?.displayName,
+          /* Hovering a chip says what the value IS, not how it is spelled.
+             Reqore otherwise falls back to the tag's own value, so a chip
+             reading "result" reported `$.result` on hover — the reference the
+             author already chose, restating the label in engine syntax instead
+             of telling them anything. The path stays discoverable in the
+             field's help and in the picker row for an unlabelled value. */
+          /* Drawn, for the same reason the picker row is: this description is
+             the SAME string the row shows, so leaving it raw here would print
+             the punctuation the row no longer prints. A tooltip's `content`
+             takes a node, and without a host renderer it stays the plain
+             string it always was. */
+          /* Drawn, for the same reason the picker row is: this is the SAME
+             string the row shows, so leaving it raw here would print the
+             punctuation the row no longer prints. A drawn description travels
+             as the tooltip's `content` — the prop itself is `string |
+             IReqoreTooltip`, and only the object form takes a node. Without a
+             host renderer it stays the plain string it always was. */
+          tooltip:
+            descriptionByValue[tagValue] ?
+              renderMarkdown ?
+                {
+                  content: renderMarkdown({
+                    value: descriptionByValue[tagValue],
+                    compact: true,
+                  }) as IReqoreTooltip['content'],
+                }
+              : descriptionByValue[tagValue]
+            : undefined,
+          ...getTemplateTagStyle(tag.metadata),
+        };
+      }
+
+      return {};
+    },
+    [descriptionByValue, renderMarkdown, isText, templates]
+  );
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>): void => {
+      if (isText && singleLine && event.key === 'Enter') {
+        event.preventDefault();
+      }
+      (rest as { onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void }).onKeyDown?.(event);
+    },
+    [isText, singleLine, (rest as { onKeyDown?: unknown }).onKeyDown]
+  );
 
   const tags = useMemo<IReqoreRichTextEditorProps['tags']>((): IReqoreRichTextEditorProps['tags'] => {
     const _tags: IReqoreRichTextEditorProps['tags'] = {};
@@ -87,12 +255,20 @@ export const RichTextFormField = memo(({
         label: 'Templates',
         flat: false,
         description: 'Universal values that can be used in multiple places',
-        items: templates?.items,
+        /* The in-editor list already nests everything under "Templates", so a
+           lone category makes the author drill through TWO headers to reach
+           the only values on offer. Hoist it. */
+        /* Drawn here, at the hand-off to Reqore. A description is prose written
+           in the same markdown as every other description this package shows,
+           and printing its punctuation at the reader was the last surface still
+           doing that. Never made further up: the list is a `JSON.stringify`
+           memo key in `TemplateField`. */
+        items: renderTemplateItemDescriptions(templateItemsToShow(templates?.items), renderMarkdown),
       };
     }
 
     return _tags;
-  }, [allowTemplates, templates]);
+  }, [allowTemplates, templates, renderMarkdown]);
 
   const formattedValue: IReqoreRichTextEditorProps['value'] =
     typeof localValue !== 'object' ? [{ type: 'paragraph', children: [{ text: String(localValue ?? '') }] }]
@@ -128,6 +304,7 @@ export const RichTextFormField = memo(({
       panelProps={{ fluid: true, style: { minWidth: '150px', ...rest.panelProps?.style } }}
       {...rest}
       readOnly={readOnly}
+      onKeyDown={handleKeyDown}
       actions={
         readOnly ?
           { undo: false, redo: false, styling: false }

package/src/components/form/fields/template/ReadOnlyTemplateTag.tsx

@@ -5,6 +5,7 @@ import { memo } from 'react';
 import {
   getTemplateTagStyle,
   describeTemplateReference,
+  templateTooltip,
   TTemplateMeta,
 } from '../../../../helpers/templates';
 
@@ -18,7 +19,8 @@ export interface IReadOnlyTemplateTagProps {
 
 /**
  * The read-only representation of a selected template — a picker-shaped chip:
- * the `$`-dollar icon, the resolved display name (raw value in the tooltip), the
+ * the `$`-dollar icon, the resolved display name (and what the value IS in the
+ * tooltip, not the reference that names it), the
  * app image when present, coloured by qorus-ide's scheme (info / qorus purple /
  * success — see `getTemplateTagStyle`). Shared by `TemplateField`'s disabled
  * branch and the compact read-first row so a template reads identically wherever
@@ -34,7 +36,7 @@ export const ReadOnlyTemplateTag = memo(
           icon='ExchangeDollarLine'
           leftIconProps={{ image: metadata?.image }}
           label={label}
-          tooltip={value}
+          tooltip={templateTooltip(templates, value)}
           {...getTemplateTagStyle(metadata)}
         />
       </ReqoreTagGroup>

package/src/components/form/fields/template/TemplateField.stories.tsx

@@ -264,10 +264,20 @@ export const AutoComponent: StoryObj<typeof meta> = {
     docs: {
       description: {
         story:
-          'Renders TemplateField over an untyped (`auto`) field that accepts templates. While the field is empty it opens on the template selector rather than the data-type picker, so the author can say which value they mean before answering how it is stored.',
+          'Renders TemplateField over an untyped (`auto`) field that accepts templates. While the field is empty it opens on an editor to type into, which offers the templates — never on a data-type picker, so the author can write the value they mean without answering how it is stored.',
       },
     },
   },
+  play: async ({ canvasElement }) => {
+    /* The editor itself, not a class: TemplateField puts `.template-selector`
+       on every control it draws, the data-type picker included, so asserting
+       the class passed while the story showed "Please select data type". */
+    await waitFor(() => expect(canvasElement.querySelector('[contenteditable="true"]')).toBeTruthy(), {
+      timeout: 5000,
+    });
+    expect(canvasElement.textContent).not.toContain('Please select data type');
+    expect(canvasElement.textContent).not.toContain('Select Template');
+  },
 };
 
 export const AllowedValuesWithTemplate: StoryObj<typeof meta> = {
@@ -674,7 +684,7 @@ export const TemplateCanBeSelected: StoryObj<typeof meta> = {
     docs: {
       description: {
         story:
-          'Renders TemplateField for a string, opens the templates popover and clicks the Interface ID template — the field switches to the $local:id template value inside the template-offering input (plain word tokens stay typeable; only braced context refs chip).',
+          'Renders TemplateField for a string, opens the templates popover and clicks the Interface ID template — the field switches to template mode, where the $local:id reference is a chip named Interface ID inside an editor that can still be typed into.',
       },
     },
   },
@@ -684,9 +694,16 @@ export const TemplateCanBeSelected: StoryObj<typeof meta> = {
     await ShowsTemplatesListForString.play({ canvasElement, ...rest });
     await _testsClickButton({ label: 'Interface ID' });
 
-    await sleep(100);
-
-    await expect(canvas.getByDisplayValue('$local:id')).toBeInTheDocument();
+    // The chosen reference reads as the name it was chosen by, in an editor
+    // that can still be typed into — not as its spelling.
+    await waitFor(
+      () => {
+        const chip = canvasElement.querySelector('.template-selector [contenteditable="true"] .reqore-tag');
+        expect(chip?.textContent).toContain('Interface ID');
+      },
+      { timeout: 5000 }
+    );
+    await expect(canvas.queryByDisplayValue('$local:id')).toBeNull();
   },
 };
 
@@ -991,14 +1008,19 @@ export const EmptyAnyOpensOnTemplates: StoryObj<typeof meta> = {
     docs: {
       description: {
         story:
-          'An untyped, empty field that accepts templates opens showing the template selector rather than a data-type picker.',
+          'An untyped, empty field that accepts templates opens on an editor to type into, which offers the templates — never on a data-type picker.',
       },
     },
   },
   play: async ({ canvasElement }) => {
-    await waitFor(() =>
-      expect(canvasElement.querySelector('.template-selector')).toBeTruthy()
-    );
+    /* The editor itself, not a class: TemplateField puts `.template-selector`
+       on every control it draws, the data-type picker included, so asserting
+       the class passed while the story showed "Please select data type". */
+    await waitFor(() => expect(canvasElement.querySelector('[contenteditable="true"]')).toBeTruthy(), {
+      timeout: 5000,
+    });
+    expect(canvasElement.textContent).not.toContain('Please select data type');
+    expect(canvasElement.textContent).not.toContain('Select Template');
   },
 };