@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/form/fields/select/SelectCollection.tsx

@@ -4,7 +4,6 @@ import {
   ReqoreControlGroup,
   ReqoreMessage,
   ReqoreModal,
-  ReqoreP,
 } from '@qoretechnologies/reqore';
 import { IReqoreCollectionItemProps } from '@qoretechnologies/reqore/dist/components/Collection/item';
 import { TReqoreBadge } from '@qoretechnologies/reqore/dist/components/Button';
@@ -12,7 +11,7 @@ import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
 import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import { capitalize, isEqual, size } from 'lodash';
 import { useMemo, useState } from 'react';
-import ReactMarkdown from 'react-markdown';
+import { Description } from '../../../Description';
 
 const PositiveColorEffect = {
   gradient: {
@@ -25,6 +24,7 @@ const PositiveColorEffect = {
 
 export interface ISelectFieldCollectionItem {
   value?: unknown;
+  name?: unknown;
   display_name?: string;
   desc?: string;
   short_desc?: string;
@@ -42,16 +42,76 @@ export interface ISelectFieldCollectionItem {
 export interface ISelectFieldCollectionProps {
   onClose: () => void;
   items: ISelectFieldCollectionItem[];
-  getItemDescription: (value: unknown) => string;
   value?: unknown;
   onItemSelect: (item: ISelectFieldCollectionItem) => void;
   filters?: string[];
 }
 
+const normalizeSelectItemDescription = (value: unknown): string | undefined => {
+  if (typeof value !== 'string' || !value.trim()) {
+    return undefined;
+  }
+
+  const seen = new Set<string>();
+
+  return value
+    .split('\n')
+    .filter((line) => {
+      const normalized = line.trim().replace(/\s+/g, ' ').toLocaleLowerCase();
+
+      if (!normalized) {
+        return true;
+      }
+
+      if (seen.has(normalized)) {
+        return false;
+      }
+
+      seen.add(normalized);
+      return true;
+    })
+    .join('\n')
+    .trim();
+};
+
+export const getSelectItemDescription = (
+  item: Pick<ISelectFieldCollectionItem, 'desc' | 'short_desc'>
+): string | undefined => {
+  const desc = normalizeSelectItemDescription(item.desc);
+  const shortDesc = normalizeSelectItemDescription(item.short_desc);
+  return desc ?? shortDesc;
+};
+
+export const getSelectItemShortDescription = (
+  item: Pick<ISelectFieldCollectionItem, 'desc' | 'short_desc'> | undefined,
+  defaultDesc = ''
+): string | undefined => {
+  if (!item) {
+    return defaultDesc || undefined;
+  }
+
+  const shortDescription = normalizeSelectItemDescription(item.short_desc);
+
+  return shortDescription || defaultDesc || undefined;
+};
+
+export const getSelectItemDescriptionProps = (
+  item: Pick<ISelectFieldCollectionItem, 'desc' | 'short_desc'>
+): { longDescription?: string; shortDescription?: string } => {
+  const longDescription = normalizeSelectItemDescription(item.desc);
+
+  if (longDescription) {
+    return { longDescription };
+  }
+
+  const shortDescription = normalizeSelectItemDescription(item.short_desc);
+
+  return { shortDescription };
+};
+
 export const SelectFieldCollection = ({
   onClose,
   items,
-  getItemDescription,
   value,
   onItemSelect,
   filters,
@@ -100,8 +160,10 @@ export const SelectFieldCollection = ({
         transparent={false}
         size='tiny'
         showLayoutSwitch={false}
-        items={filteredItems.map(
-          (item): IReqoreCollectionItemProps => ({
+        items={filteredItems.map((item): IReqoreCollectionItemProps => {
+          const { longDescription, shortDescription } = getSelectItemDescriptionProps(item);
+
+          return {
             label: item.display_name || item.value?.toString(),
             size: 'tiny',
             groups: item.groups,
@@ -109,8 +171,14 @@ export const SelectFieldCollection = ({
             responsiveTitle: false,
             content: (
               <ReqoreControlGroup vertical fluid>
-                {item.short_desc && <ReqoreP size='small'>{item.short_desc}</ReqoreP>}
-                {item.desc && <ReqoreP size='small'>{item.desc}</ReqoreP>}
+                {longDescription || shortDescription ? (
+                  <Description
+                    longDescription={longDescription || ''}
+                    shortDescription={shortDescription}
+                    size='small'
+                    margin='none'
+                  />
+                ) : null}
                 {item.actions?.map(({ as: Component = ReqoreButton, props, ...rest }, index) => (
                   <Component
                     key={index}
@@ -148,13 +216,6 @@ export const SelectFieldCollection = ({
               size: '20px',
               rounded: true,
             },
-            tooltip: !!item.desc
-              ? {
-                  delay: 800,
-                  content: <ReactMarkdown>{getItemDescription(item.value)}</ReactMarkdown>,
-                  maxWidth: '70vw',
-                }
-              : undefined,
             onClick: !item.disabled
               ? (e) => {
                   if (e.currentTarget.contains(e.target as Node)) {
@@ -163,8 +224,8 @@ export const SelectFieldCollection = ({
                   }
                 }
               : undefined,
-          })
-        )}
+          };
+        })}
         actions={filters?.map((filter) => ({
           label: capitalize(filter.replace('_', ' ')),
           badge: items.filter((item) => item[filter]).length,

package/src/components/form/fields/string/String.stories.tsx

@@ -38,6 +38,14 @@ export const Default: Story = {
   args: {
     value: 'Qore',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the String field pre-populated with "Qore". Clicking clear empties the input and fires onClearClick; typing new text updates the value and fires onChange.',
+      },
+    },
+  },
   play: async ({ canvasElement, args }) => {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Name');
@@ -60,6 +68,14 @@ export const Sensitive: Story = {
     sensitive: true,
     value: 'password',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the String field in sensitive mode — the input renders as type="password" so the value is masked.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Name');

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

@@ -209,6 +209,14 @@ export const StringComponent: StoryObj<typeof meta> = {
     value: 'Some string',
     type: 'string',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField wrapping a LongString component with a plain string value — the field shows the literal string in a textarea, no template selected.',
+      },
+    },
+  },
 };
 
 export const BooleanComponent: StoryObj<typeof meta> = {
@@ -218,6 +226,14 @@ export const BooleanComponent: StoryObj<typeof meta> = {
     allowTemplates: true,
     componentFromType: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for a boolean value with templates allowed — the boolean toggle is shown with the template toggle available on the side.',
+      },
+    },
+  },
 };
 
 export const NumberComponent: StoryObj<typeof meta> = {
@@ -227,6 +243,14 @@ export const NumberComponent: StoryObj<typeof meta> = {
     allowTemplates: true,
     componentFromType: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for an int value of 25 with templates allowed — the numeric input is shown alongside the template toggle.',
+      },
+    },
+  },
 };
 
 export const AutoComponent: StoryObj<typeof meta> = {
@@ -235,6 +259,14 @@ export const AutoComponent: StoryObj<typeof meta> = {
     allowTemplates: true,
     component: auto,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField wrapping the AutoFormField dispatcher — the operator can pick a type from the auto picker or switch to a template value.',
+      },
+    },
+  },
 };
 
 export const AllowedValuesWithTemplate: StoryObj<typeof meta> = {
@@ -249,6 +281,14 @@ export const AllowedValuesWithTemplate: StoryObj<typeof meta> = {
     ],
     component: auto,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField restricted to a single allowed value ("Test") but with templates also allowed — the operator can pick the allowed value or switch to a template.',
+      },
+    },
+  },
 };
 
 export const TemplateValue: StoryObj<typeof meta> = {
@@ -257,6 +297,14 @@ export const TemplateValue: StoryObj<typeof meta> = {
     type: 'int',
     value: '$local:id',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for an int wrapped over the Number component with a template value ($local:id) — the template selector replaces the number input.',
+      },
+    },
+  },
 };
 
 export const ElementTypeInListShowsCorrectTemplates: StoryObj<typeof meta> = {
@@ -271,6 +319,14 @@ export const ElementTypeInListShowsCorrectTemplates: StoryObj<typeof meta> = {
       { type: 'number', value: 3 },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField in list mode with three number items. Adding a new item and opening the templates popover shows the templates that resolve to the number element type.',
+      },
+    },
+  },
   play: async () => {
     await _testsClickButton({ label: 'Add new item for "Test"' });
     await _testsOpenTemplates();
@@ -280,6 +336,14 @@ export const ElementTypeInListShowsCorrectTemplates: StoryObj<typeof meta> = {
 
 export const ShowsTemplatesList: StoryObj<typeof meta> = {
   ...TemplateValue,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField with the $local:id template value, then opens the templates popover — the operator sees the available templates that resolve to an int.',
+      },
+    },
+  },
   play: async () => {
     await _testsOpenTemplates();
   },
@@ -287,6 +351,14 @@ export const ShowsTemplatesList: StoryObj<typeof meta> = {
 
 export const ShowsTemplatesListForString: StoryObj<typeof meta> = {
   ...StringComponent,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField over a LongString component with a plain string value, then opens the templates popover — the templates list is shown for a string target type.',
+      },
+    },
+  },
   play: async () => {
     await _testsOpenTemplates();
   },
@@ -294,6 +366,14 @@ export const ShowsTemplatesListForString: StoryObj<typeof meta> = {
 
 export const ShowsTemplatesListForBoolean: StoryObj<typeof meta> = {
   ...BooleanComponent,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for a boolean value, switches to template mode and opens the templates popover — the templates list is shown for a boolean target type.',
+      },
+    },
+  },
   play: async () => {
     await _testsSetTemplate();
     await _testsOpenTemplates();
@@ -302,6 +382,14 @@ export const ShowsTemplatesListForBoolean: StoryObj<typeof meta> = {
 
 export const ShowsTemplatesListForNumber: StoryObj<typeof meta> = {
   ...NumberComponent,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for an int value, then opens the templates popover — the templates list is shown for an int target type.',
+      },
+    },
+  },
   play: async () => {
     await _testsOpenTemplates();
   },
@@ -314,6 +402,14 @@ export const TemplateValueCanBeRemoved: StoryObj<typeof meta> = {
     allowTemplates: true,
     componentFromType: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField holding a $config:boolean template value. Clicking the template-remove action clears the template and the underlying boolean checkbox is shown instead.',
+      },
+    },
+  },
   play: async () => {
     await expect(document.querySelector('.template-selector')).toBeInTheDocument();
 
@@ -333,6 +429,14 @@ export const TemplateWithFunctions: StoryObj<typeof meta> = {
     fluid: false,
     expressions: storyExpressions as any,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField with allowFunctions enabled — the template menu now exposes a "Use Expression" entry alongside the plain templates.',
+      },
+    },
+  },
   play: async () => {
     await _testsOpenTemplateMenu();
     await _testsWaitForText('Use Expression');
@@ -358,6 +462,14 @@ export const TemplateWithFunctionValue: StoryObj<typeof meta> = {
     fluid: false,
     expressions: storyExpressions as any,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField holding a substr function value with three arguments — the expression builder shows the function name and each argument slot.',
+      },
+    },
+  },
 };
 
 export const TemplateWithNestedFunctionValue: StoryObj<typeof meta> = {
@@ -389,6 +501,14 @@ export const TemplateWithNestedFunctionValue: StoryObj<typeof meta> = {
     fluid: false,
     expressions: storyExpressions as any,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField holding a substr function whose second argument is itself a PLUS-INT expression — the expression builder shows the nested function inline within the outer call.',
+      },
+    },
+  },
 };
 
 export const TemplateCanBeSelected: StoryObj<typeof meta> = {
@@ -397,6 +517,14 @@ export const TemplateCanBeSelected: StoryObj<typeof meta> = {
     defaultType: 'string',
     defaultInternalType: 'string',
   },
+  parameters: {
+    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.',
+      },
+    },
+  },
   play: async ({ canvasElement, ...rest }) => {
     const canvas = within(canvasElement);
 
@@ -410,6 +538,14 @@ export const TemplateCanBeSelected: StoryObj<typeof meta> = {
 };
 
 export const ValueIsResetWhenChangingToCustom: StoryObj<typeof meta> = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField over a number type holding a $config:something template value. Clicking template-remove resets the value to undefined and fires onChange with the cleared value.',
+      },
+    },
+  },
   render: (args) => {
     const [value, setValue] = useState(args.value);
 
@@ -449,6 +585,14 @@ export const TemplatesWithMultipleLevels: StoryObj<typeof meta> = {
     type: 'string',
     templates: buildTemplates(multiLevelTemplates as any),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for a string with a hierarchical template catalogue. Drilling into "Testing Hash" narrows the list to templates that resolve to a string (Testing Int Item is filtered out).',
+      },
+    },
+  },
   play: async () => {
     await _testsOpenTemplates();
     await _testsClickButton({ label: 'Testing Hash' });
@@ -458,6 +602,14 @@ export const TemplatesWithMultipleLevels: StoryObj<typeof meta> = {
 };
 
 export const TemplatesWithMultipleLevelsAndHashField: StoryObj<typeof meta> = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for a hash type with a hierarchical template catalogue — switching to template mode and opening the popover exposes the nested template groups.',
+      },
+    },
+  },
   render: (args) => {
     const [value, setValue] = useState(args.value);
 
@@ -486,6 +638,14 @@ export const TemplatesWithMultipleLevelsAndHashField: StoryObj<typeof meta> = {
 
 export const TemplateWithItemsCanBeSelected: StoryObj<typeof meta> = {
   ...TemplatesWithMultipleLevelsAndHashField,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders TemplateField for a hash type with a hierarchical catalogue. Selecting an item from a nested group updates the template value to the picked entry (Testing Hash).',
+      },
+    },
+  },
   play: async (args) => {
     await TemplatesWithMultipleLevelsAndHashField.play(args);
     await _testsClickButton({ selector: '.reqore-menu-item-left-action' });

package/src/components/form/fields/url/Url.stories.tsx

@@ -30,6 +30,14 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Url field with no value. Typing into the address input recomposes the URL and fires onChange after the debounce; because no protocol is selected, the composed value keeps a bare "://" prefix.',
+      },
+    },
+  },
   play: async ({ canvasElement, args }) => {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('URL address');
@@ -49,6 +57,14 @@ export const WithValue: Story = {
   args: {
     value: 'https://example.com',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Url field pre-populated with "https://example.com" — the URL is split across the https protocol selector and the example.com address input.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     await expect(await canvas.findByDisplayValue('example.com')).toBeInTheDocument();
@@ -60,6 +76,14 @@ export const KeepsSeparatorInsideAddress: Story = {
   args: {
     value: 'https://proxy/forward?to=http://inner',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Url field with a URL whose query-string embeds a second "://". The protocol split only consumes the leading separator; the inner "://" survives inside the address input.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     // `://` inside the address survives the protocol/address split.

package/src/components/form/index.tsx

@@ -22,6 +22,8 @@ export * from './fields/select/SelectCollection';
 export * from './fields/string/String';
 export * from './fields/template/TemplateField';
 export * from './engine/FormEngine';
+export * from './engine/optionActions';
+export * from './engine/rendererTypes';
 export * from './expressions/types';
 export * from './expressions/useExpressions';
 // Named (not wildcard) so the `_resetRenderExpressionTransportForTests`