@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/form/expressions/builder/ExpressionBuilder.stories.tsx

@@ -16,7 +16,8 @@ import { ExpressionBuilder } from './index';
 // --- inlined test helpers (equivalents of the IDE `../Tests/utils`) ---------
 
 /** Count regular expression cards (`.expression`). */
-const expressionCount = () => document.querySelectorAll('.expression').length;
+const expressionCount = (scope: ParentNode = document) =>
+  scope.querySelectorAll('.expression').length;
 
 /** Click a ReqoreButton by visible label (anywhere in the document). */
 const clickButtonByLabel = async (label: string) => {
@@ -26,14 +27,14 @@ const clickButtonByLabel = async (label: string) => {
 };
 
 /** Click a button by CSS selector. */
-const clickSelector = async (selector: string, nth = 0) => {
-  const els = document.querySelectorAll(selector);
+const clickSelector = async (selector: string, nth = 0, scope: ParentNode = document) => {
+  const els = scope.querySelectorAll(selector);
   await fireEvent.click(els[nth]);
 };
 
 /** Wait for some text to appear in the document. */
-const waitForText = async (text: string | RegExp) => {
-  const body = within(document.body);
+const waitForText = async (text: string | RegExp, scope: HTMLElement = document.body) => {
+  const body = within(scope);
   await waitFor(() => expect(body.queryAllByText(text)[0]).toBeTruthy(), { timeout: 10000 });
 };
 
@@ -44,15 +45,19 @@ const waitForText = async (text: string | RegExp) => {
  * toolkit `Select` opens a `SelectFieldCollection` modal (not an inline
  * dropdown) — the item is a collection button with the display name as text.
  */
-const selectOperation = async (currentLabel: string, itemLabel: string) => {
-  const body = within(document.body);
+const selectOperation = async (
+  currentLabel: string,
+  itemLabel: string,
+  ownerDocument: Document = document
+) => {
+  const body = within(ownerDocument.body);
   // Open the picker (placeholder when empty, or the current operation name).
   const trigger = await body.findByText(currentLabel, undefined, { timeout: 10000 });
   await fireEvent.click(trigger);
   // Click the item inside the now-open collection modal.
   const item = await waitFor(
     () => {
-      const el = within(document.body).queryAllByText(itemLabel)[0];
+      const el = within(ownerDocument.body).queryAllByText(itemLabel)[0];
       if (!el) throw new Error(`collection item "${itemLabel}" not ready`);
       return el;
     },
@@ -113,8 +118,16 @@ export const Default: Story = {
   args: {
     returnType: ['string', 'int'],
   },
-  play: async () => {
-    await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with no value and a string-or-int return type — a single empty expression card is shown so the operator can pick an operation.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(expressionCount(canvasElement)).toBe(1), { timeout: 10000 });
   },
 };
 
@@ -122,6 +135,14 @@ export const DefaultBoolean: Story = {
   args: {
     returnType: ['boolean'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with no value and a boolean return type — a single empty expression card is shown so the operator can pick a boolean-returning operation.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -142,6 +163,14 @@ export const WithSimpleValue: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder holding a single "contains" expression with three arguments — the card shows the operation and each operand slot.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -234,6 +263,14 @@ export const WithComplexValue: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder holding a nested &&/|| expression with six leaf expressions — the builder shows the full expression tree with the AND/OR group cards and their operand cards.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(6), { timeout: 10000 });
   },
@@ -241,6 +278,15 @@ export const WithComplexValue: Story = {
 
 export const ShowsExplanation: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree and clicks Explain — the plain-language explanation of the whole expression is shown alongside the builder.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     await clickButtonByLabel('Explain');
@@ -260,6 +306,15 @@ export const Readonly: Story = {
     ...WithComplexValue.args,
     readOnly: true,
   },
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree with readOnly enabled — the tree is visible but the AND/OR add-group controls are hidden so the operator cannot mutate it.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     expect(document.querySelector('.expression-and')).toBeNull();
@@ -268,6 +323,15 @@ export const Readonly: Story = {
 
 export const FocusedEditing: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree, hovers a card and clicks its fullscreen action — the focused-editing modal opens over that subtree.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     await userEvent.hover(document.querySelectorAll('.expression')[0]);
@@ -288,6 +352,14 @@ export const WithArgWithAllowedValues: Story = {
   args: {
     returnType: ['bool'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders an empty ExpressionBuilder and selects "Matches Regular Expression" — the third operand ("Regex Options") carries element_allowed_values and renders the "Select one or more" picker.',
+      },
+    },
+  },
   play: async (args) => {
     await Default.play!(args);
 
@@ -311,6 +383,14 @@ export const WithIntType: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with an int-typed >= expression comparing $local:input to 20 — the operands render as Number fields inside the expression card.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -326,6 +406,15 @@ export const WithIntType: Story = {
  */
 export const ArgsChangeWhenOperatorChanges: Story = {
   ...WithSimpleValue,
+  parameters: {
+    ...WithSimpleValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded "String Contains" expression, then switches the operation to "Matches Regular Expression" — the string operands carry over and the new "Regex Options" allowed-values operand appears.',
+      },
+    },
+  },
   play: async () => {
     // Both string operands of the seeded `contains` render as textareas.
     await waitFor(
@@ -344,6 +433,14 @@ export const NewGroupsCanBeCreated: Story = {
     ...WithSimpleValue.args,
     returnType: ['bool'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the seeded "String Contains" expression, then clicks the AND and OR add-group actions — the tree grows from 1 to 3 expression cards as new grouping levels are added.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
 
@@ -357,6 +454,15 @@ export const NewGroupsCanBeCreated: Story = {
 
 export const GroupsCanBeDeleted: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree (6 cards) and removes one group — the tree shrinks to 5 cards after the delete.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(6), { timeout: 10000 });
 
@@ -377,6 +483,14 @@ export const GroupsCanBeDeleted: Story = {
  * inline `AiAssistanceAction({ context: selectedExpression })` captured.
  */
 export const WithInjectedExtraActions: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree with an extraActions factory that injects an AI-assist button per card. Hovering an expression reveals the injected action alongside the built-in ones.',
+      },
+    },
+  },
   args: {
     ...WithComplexValue.args,
     extraActions: ({ selectedExpression }) => [
@@ -428,6 +542,14 @@ export const ExpressionWithIntReturnType: Story = {
       is_expression: true,
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with a "+" (Addition) varargs expression holding four int operands — the three "rest" args each expose a remove-argument button.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
     // Three "rest" args → three remove-argument buttons.
@@ -438,6 +560,15 @@ export const ExpressionWithIntReturnType: Story = {
 /** Remove one variable argument — the remove-arg count drops from 3 to 2. */
 export const VariableArgumentsCanBeRemoved: Story = {
   ...ExpressionWithIntReturnType,
+  parameters: {
+    ...ExpressionWithIntReturnType.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the "+" varargs expression and clicks one remove-argument button — one operand disappears and the remove-arg count drops from 3 to 2.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionWithIntReturnType.play!(args);
 
@@ -450,6 +581,15 @@ export const VariableArgumentsCanBeRemoved: Story = {
 /** Remove one then add one back — the count returns to 3. */
 export const VariableArgumentsCanBeAdded: Story = {
   ...ExpressionWithIntReturnType,
+  parameters: {
+    ...ExpressionWithIntReturnType.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the "+" varargs expression, removes one operand and then adds one back — the remove-arg count moves 3 → 2 → 3.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionWithIntReturnType.play!(args);
 
@@ -487,34 +627,53 @@ export const ExpressionCanBeWrapped: Story = {
     returnType: ['string', 'int'],
     value: seededConvert,
   },
-  play: async () => {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a seeded "Convert to Boolean" expression, hovers the card and picks "Join List Elements" from the Wrap picker — the outer op mounts and the original expression becomes its first operand.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
     // Seeded base op + its operand render.
-    await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
-    await waitForText('Value To Convert');
+    await waitFor(() => expect(expressionCount(canvasElement)).toBe(1), { timeout: 10000 });
+    await waitForText('Value To Convert', canvasElement);
 
     // Hover the card to reveal the floating "Wrap" picker, then wrap it in
     // `Join List Elements` — the wrapped op becomes its first operand and the
     // outer card shows "List To Join". The card count goes 1 → 2.
-    await userEvent.hover(document.querySelectorAll('.expression')[0]);
+    await userEvent.hover(canvasElement.querySelectorAll('.expression')[0]);
     await sleep(500);
-    await selectOperation('Wrap', 'Join List Elements');
-    await waitForText('List To Join');
-    await waitFor(() => expect(expressionCount()).toBe(2), { timeout: 10000 });
+    await selectOperation('Wrap', 'Join List Elements', canvasElement.ownerDocument);
+    await waitForText('List To Join', canvasElement);
+    await waitFor(() => expect(expressionCount(canvasElement)).toBe(2), { timeout: 10000 });
   },
 };
 
 /** Wrap, then unwrap — back to a single expression card. */
 export const ExpressionCanBeUnwrapped: Story = {
   ...ExpressionCanBeWrapped,
+  parameters: {
+    ...ExpressionCanBeWrapped.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the wrapped expression from ExpressionCanBeWrapped, then hovers and unwraps the outer op — the inner "Convert to Boolean" survives and the outer wrapper is removed.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionCanBeWrapped.play!(args);
 
     // Unwrap the outer op (keep the child) — the `.expression-unwrap` action.
-    await userEvent.hover(document.querySelectorAll('.expression')[0]);
+    await userEvent.hover(args.canvasElement.querySelectorAll('.expression')[0]);
     await sleep(500);
+    // The card's actions are ReQore *floating* actions, so they are portalled out
+    // of the canvas — this one lookup stays document-scoped on purpose.
     await clickSelector('.expression-unwrap');
 
-    await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
+    await waitFor(() => expect(expressionCount(args.canvasElement)).toBe(1), { timeout: 10000 });
   },
 };
 
@@ -579,6 +738,14 @@ const SeededMismatchBase: Story = {
  * exact, so the builder flags it and the confirmation modal mounts.
  */
 export const FunctionArgsArePassedToNewFunctionAndNeedConfirmation: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a valued "Format Date" expression and switches the operation to "Matches Regular Expression" — the carried date arg is accepted-but-not-exact for the new richtext operand and the mismatched-arguments confirmation modal mounts.',
+      },
+    },
+  },
   args: {
     returnType: 'string',
     value: {
@@ -616,6 +783,15 @@ export const FunctionArgsArePassedToNewFunctionAndNeedConfirmation: Story = {
 /** "Confirm selection" keeps the (still-selected) mismatched arg, transformed. */
 export const AcceptIncompatibleFunctionArgsSelection: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Confirm selection" on the mismatched-arguments modal — the (still-selected) argument is kept and transformed to the new expected type.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);
 
@@ -636,6 +812,15 @@ export const AcceptIncompatibleFunctionArgsSelection: Story = {
 /** "Accept all" — every mismatched arg is transformed and kept. */
 export const AcceptAllIncompatibleFunctionArgs: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Accept all" on the mismatched-arguments modal — every flagged argument is transformed and kept.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);
 
@@ -655,6 +840,15 @@ export const AcceptAllIncompatibleFunctionArgs: Story = {
 /** "Discard all" — every mismatched arg is cleared. */
 export const DiscardAllIncompatibleFunctionArgs: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Discard all" on the mismatched-arguments modal — every flagged argument is cleared.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);
 

package/src/components/form/expressions/builder/index.tsx

@@ -651,7 +651,10 @@ export const Expression = ({
     return value.value?.args?.some((arg) => arg?.types_mismatch);
   }, [JSON.stringify(value)]);
 
-  if (expressions.loading || types.loading) {
+  // The type hook is seeded with the complete built-in catalogue and refreshes
+  // it in the background.  Do not hide an otherwise usable expression behind
+  // a skeleton while that optional refresh is in flight.
+  if (expressions.loading || (types.loading && !size(types.value))) {
     return <ReqorePanelSkeleton size='small' />;
   }
 
@@ -687,6 +690,11 @@ export const Expression = ({
           fluid={false}
           fixed={true}
           flat
+          // The operation catalogue is long and every entry carries a description,
+          // so it belongs in the searchable collection modal rather than an inline
+          // dropdown. `SelectFormField` defaults `forceDropdown` to `true`, which
+          // would otherwise collapse this picker into the dropdown presentation.
+          forceDropdown={false}
           minimal
           items={defaultItems}
           onChange={handleOperatorChange}
@@ -732,6 +740,9 @@ export const Expression = ({
             transparent: false,
             fixed: true,
             minimal: false,
+            // Same catalogue as the operation selector above — keep the collection
+            // modal rather than the `forceDropdown` default's inline dropdown.
+            forceDropdown: false,
             items: defaultItems,
             hideItemCount: true,
             onChange: handleWrapExpressionClick,

package/src/components/form/expressions/useExpressions.ts

@@ -84,7 +84,10 @@ export const useExpressions = (
 
   return {
     expressions,
-    loading: system.loading || extra.loading,
+    // `extra` is deliberately not loaded without an expressions URL.  The
+    // generic fetch hook keeps an unstarted request in its initial loading
+    // state, so only include it when that request is actually enabled.
+    loading: system.loading || (!!expressionsUrl && extra.loading),
     error: errorOverride ?? system.error ?? extra.error,
     reload: () => {
       system.load();

package/src/components/form/fields/Field.stories.tsx

@@ -40,6 +40,14 @@ export const SoftInteger: Story = {
     type: 'softint',
     value: 5,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormField for a softint value — the dispatcher resolves the soft type to int and mounts the numeric input.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     // NumberFormField renders an input (a `softint` resolves to `int`).
     await expect(canvasElement.querySelector('input')).toBeInTheDocument();
@@ -52,6 +60,14 @@ export const Binary: Story = {
     type: 'binary',
     value: 'deadbeef',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormField for a binary value — the dispatcher mounts a textarea holding the encoded content.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     await expect(canvasElement.querySelector('textarea')).toBeInTheDocument();
   },
@@ -63,6 +79,14 @@ export const ByteSize: Story = {
     type: 'byte-size',
     value: '512MiB',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormField for a byte-size value — the dispatcher mounts the amount input and the MiB unit selector, split from "512MiB".',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByDisplayValue('512')).toBeInTheDocument();
@@ -76,6 +100,14 @@ export const Url: Story = {
     type: 'url',
     value: 'https://example.com',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormField for a url value — the dispatcher mounts the https protocol selector and the example.com address input, split from "https://example.com".',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(await canvas.findByDisplayValue('example.com')).toBeInTheDocument();
@@ -94,6 +126,14 @@ export const MultiSelect: Story = {
     ],
     value: ['red', 'blue'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormField for a multi-select value — the two picked values (Red and Blue) render as chips using their display_name labels.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // The two selected values render as chips (by their display_name).

package/src/components/form/fields/Field.tsx

@@ -25,6 +25,7 @@ import NumberFormField from './number/Number';
 import { ReqraftObjectFormField } from './object/Object';
 import { RichTextFormField } from './rich-text/RichText';
 import { SelectFormField } from './select/Select';
+import { getSelectItemShortDescription } from './select/SelectCollection';
 import { StringFormField } from './string/String';
 import { ArrayAutoField } from './array/ArrayAutoField';
 import { AutoFormField } from './auto/AutoFormField';
@@ -538,6 +539,10 @@ export const FormField = <T extends TFormFieldType>({
           icon='SaveFill'
           fluid
           hideItemCount
+          forceDropdown={
+            (fieldProps as { forceDropdown?: boolean } | undefined)?.forceDropdown ??
+            (rest as { forceDropdown?: boolean }).forceDropdown
+          }
         />
       );
     }
@@ -557,7 +562,7 @@ export const FormField = <T extends TFormFieldType>({
                 margin='right'
                 key={index}
                 label={item.display_name ?? JSON.stringify(itemValue)}
-                tooltip={item.short_desc || item.desc}
+                tooltip={getSelectItemShortDescription(mapAllowedValue(item))}
                 disabled={item.disabled}
                 checked={checked}
                 intent={checked ? 'info' : undefined}
@@ -578,6 +583,10 @@ export const FormField = <T extends TFormFieldType>({
         value={value}
         onChange={(val) => handleChange(val as TFormFieldValueType<T>)}
         fluid
+        forceDropdown={
+          (fieldProps as { forceDropdown?: boolean } | undefined)?.forceDropdown ??
+          (rest as { forceDropdown?: boolean }).forceDropdown
+        }
       />
     );
   };