@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/form/fields/object/Object.stories.tsx

@@ -50,6 +50,14 @@ export const Object: Story = {
     dataType: 'json',
     resultDataType: 'json',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in JSON object mode with no value. Clicking "New Object" seeds an empty JSON object in the editor.',
+      },
+    },
+  },
   async play() {
     await testsWaitForText('New Object');
     await testsClickButton({ label: 'New Object' });
@@ -64,6 +72,14 @@ export const List: Story = {
     dataType: 'yaml',
     resultDataType: 'yaml',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in YAML list mode with no value. Clicking "New List" seeds an empty list in the editor.',
+      },
+    },
+  },
   async play() {
     await testsWaitForText('New List');
     await testsClickButton({ label: 'New List' });
@@ -79,6 +95,14 @@ export const Disabled: Story = {
     resultDataType: 'native',
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in native-array mode but disabled — the field is visible and non-interactive.',
+      },
+    },
+  },
 };
 
 export const Small: Story = {
@@ -96,6 +120,14 @@ export const Small: Story = {
       false,
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in native-array mode at "small" size with mixed item types — object, string, number and boolean.',
+      },
+    },
+  },
 };
 
 export const DisabledWithValue: Story = {
@@ -113,6 +145,14 @@ export const DisabledWithValue: Story = {
     ],
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in native-array mode with a populated value but disabled — the items are visible in read-only form.',
+      },
+    },
+  },
 };
 
 export const NativeOnly: Story = {
@@ -129,6 +169,14 @@ export const NativeOnly: Story = {
       false,
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field in native-array mode with mixed item types — the native editor shows the items without a YAML/JSON textarea alternative.',
+      },
+    },
+  },
   async play() {
     await testsWaitForText('"value"');
   },
@@ -148,6 +196,14 @@ export const ValueCanBeRemoved: Story = {
       false,
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field with a populated native array. Clicking Remove clears the value and the field falls back to the "New List" placeholder.',
+      },
+    },
+  },
   async play() {
     await testsWaitForText('"value"');
     await testsClickButton({ label: 'Remove' });
@@ -166,6 +222,14 @@ export const Json: Story = {
     }),
     resultDataType: 'json',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field with a JSON string value. Switching to Text mode, editing the JSON and clicking Save fires onChange with the new JSON serialization.',
+      },
+    },
+  },
   async play({ args }) {
     await testsWaitForText('"value"');
     await testsClickButton({ label: 'Text' });
@@ -213,6 +277,14 @@ export const Yaml: Story = {
     }),
     resultDataType: 'yaml',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field with a YAML string value. Switching to Text mode, editing the YAML and clicking Save fires onChange with the new YAML serialization.',
+      },
+    },
+  },
   async play({ args }) {
     await testsWaitForText('"value"');
     await testsClickButton({ label: 'Text' });
@@ -247,6 +319,14 @@ export const YamlToJson: Story = {
     }),
     resultDataType: 'json',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field with a YAML input value and JSON output — editing the YAML in Text mode and saving fires onChange with the equivalent JSON string.',
+      },
+    },
+  },
   async play({ args }) {
     await testsWaitForText('"value"');
     await testsClickButton({ label: 'Text' });
@@ -281,6 +361,14 @@ export const NativeToYaml: Story = {
     },
     resultDataType: 'yaml',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Object field with a native object value and YAML output — editing in Text mode and saving fires onChange with the YAML serialization.',
+      },
+    },
+  },
   async play({ args }) {
     await testsWaitForText('"value"');
     await testsClickButton({ label: 'Text' });

package/src/components/form/fields/radio-group/RadioGroup.stories.tsx

@@ -42,6 +42,14 @@ export const Default: Story = {
       { label: 'Python', value: 'Python', 'aria-label': 'Python' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the RadioGroup field with three language options and "Qore" pre-selected. Clicking a different option fires onChange with the new value.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const canvas = within(canvasElement);
     const java = canvas.getByLabelText('Java');
@@ -59,6 +67,14 @@ export const WithImages: Story = {
       { label: 'Python', value: 'Python', image: python },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the RadioGroup field with three language options — each option displays its language logo alongside the label.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     await expect(canvasElement.querySelector(`img[src="${qore}"]`)).toBeInTheDocument();
     await expect(canvasElement.querySelector(`img[src="${java}"]`)).toBeInTheDocument();
@@ -68,4 +84,12 @@ export const WithImages: Story = {
 
 export const Disabled: Story = {
   args: { ...Default.args, disabled: true },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the RadioGroup field with three language options but disabled — the group is visible and non-interactive.',
+      },
+    },
+  },
 };

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

@@ -33,6 +33,14 @@ export const WithValue: Story = {
   args: {
     value: 'Hello world',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the RichText field pre-populated with the plain-string value "Hello world" — the editor mounts with the text rendered as a paragraph.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // Only assert on render — typing assertions would need waitFor due to debounce
@@ -42,6 +50,13 @@ export const WithValue: Story = {
 };
 
 export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the RichText field with no value — the editor mounts empty.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByRole('textbox')).toBeInTheDocument();
@@ -52,6 +67,14 @@ export const WithSlateValue: Story = {
   args: {
     value: [{ type: 'paragraph', children: [{ text: 'Rich text with Slate format' }] }],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the RichText field pre-populated with a Slate document rather than a plain string — the editor mounts with the paragraph node rendered as text.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByRole('textbox')).toBeInTheDocument();

package/src/components/form/fields/schema-definition/SchemaDefinitionField.stories.tsx

@@ -40,6 +40,14 @@ type Story = StoryObj<typeof meta>;
 /** Empty definition — the catalogue drives the full tab set. */
 export const Empty: Story = {
   args: {},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor with no existing value — the Schema, Tables, Sequences and Migrations tabs mount straight from the catalogue.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // Tabs come straight from the catalogue's `definition` sections.
@@ -59,6 +67,14 @@ export const Starter: Story = {
   args: {
     value: starterDefinition,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor seeded with the "example_schema" starter template — the Schema tab shows the single scaffolded table.',
+      },
+    },
+  },
 };
 
 /** A realistic populated schema — two tables, sequence, reference data, migrations. */
@@ -66,6 +82,14 @@ export const Populated: Story = {
   args: {
     value: mockPopulatedDefinition,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor with the populated fixture. Opening the Tables tab shows the customers and addresses tables.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // Open the Tables tab → the two table panels render from the value.
@@ -81,6 +105,14 @@ export const ReadOnly: Story = {
     value: mockPopulatedDefinition,
     readOnly: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor with readOnly enabled — every input becomes a typeset display row and no inputs, textareas or selects are rendered.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(await canvas.findByText('Schema')).toBeInTheDocument();
@@ -94,6 +126,14 @@ export const CatalogError: Story = {
   args: {
     catalogError: 'Schema options are unavailable on this server.',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor when the catalogue fetch fails — a "Could not load schema options" callout replaces the form.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(await canvas.findByText('Could not load schema options')).toBeInTheDocument();
@@ -106,6 +146,14 @@ export const CatalogError: Story = {
  * wired. `catalogOverride` rides in via `fieldProps`.
  */
 export const ViaFormField: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor through the FormField dispatcher (type="schema-definition"). The catalogue is injected via fieldProps and the Schema and Tables tabs mount as usual.',
+      },
+    },
+  },
   render: () => {
     const [value, setValue] = useState<IDataSchemaDefinition | undefined>(mockPopulatedDefinition);
     return (
@@ -132,6 +180,14 @@ export const ViaFormField: Story = {
  * → FormField → SchemaDefinitionEditor).
  */
 export const ViaFormEngineUiType: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a FormEngine schema whose "definition" option declares ui_type: schema-definition — FormEngine flows through TemplateField and FormField and mounts the schema editor with the injected catalogue.',
+      },
+    },
+  },
   render: () => {
     const [value, setValue] = useState<any>({
       definition: { type: 'hash', value: mockPopulatedDefinition },
@@ -177,6 +233,14 @@ export const Sandboxed: Story = {
     wrapperName: 'example_customer_addresses',
     value: mockPopulatedDefinition,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor for an untrusted (sandboxed) caller using the sandboxed catalogue — the Advanced tab and every trusted-only section are hidden.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(await canvas.findByText('Migrations')).toBeInTheDocument();
@@ -195,6 +259,14 @@ export const WithValidationBanner: Story = {
     wrapperName: 'renamed_schema',
     value: mockPopulatedDefinition,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the SchemaDefinition editor when the wrapper interface name and the DataSchema name differ — the "name does not match" banner is shown, and clicking "Sync name" resolves the mismatch.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     // The banner renders the mismatch both as its title and its body text.

package/src/components/form/fields/select/Select.stories.tsx

@@ -35,6 +35,14 @@ export const Items: Story = {
       { display_name: 'Item 2', value: 'item2' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with two simple items and no value. Clicking the trigger opens the popover with the item list.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await fireEvent.click(canvas.getByRole('button'));
@@ -45,7 +53,16 @@ export const Items: Story = {
 };
 
 export const ItemsWithDescription: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with twenty items, each carrying a description, icon or image. Opening the picker mounts a modal collection with all twenty entries.',
+      },
+    },
+  },
   args: {
+    forceDropdown: false,
     items: [
       { display_name: 'Item 1', desc: 'This is item 1', value: 'item1', icon: 'MoneyEuroCircleFill', groups: ['Miscellaneous'] },
       { display_name: 'Item 2', desc: 'This is item 2', value: 'item2', image: 'https://avatars.githubusercontent.com/u/8861481?v=4' },
@@ -81,7 +98,16 @@ export const ItemsWithDescription: Story = {
 };
 
 export const ItemsWithDescriptionAndMessages: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with two items that carry inline messages of different intents. The picker modal shows the messages beneath each item.',
+      },
+    },
+  },
   args: {
+    forceDropdown: false,
     items: [
       {
         display_name: 'Item 1',
@@ -121,6 +147,14 @@ export const DisabledItemsWithIntent: Story = {
       { display_name: 'Disabled Item with Intent', intent: 'danger', disabled: true, value: 'item5' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with a mix of enabled, disabled and intent-tagged items — the disabled entries are non-interactive while success/danger items carry their intent styling.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await fireEvent.click(canvas.getByRole('button'));
@@ -130,6 +164,7 @@ export const DisabledItemsWithIntent: Story = {
 
 export const DisabledItemsWithIntentAndDescriptions: Story = {
   args: {
+    forceDropdown: false,
     items: [
       { display_name: 'Item 1', desc: 'This is item 1', value: 'item1' },
       { display_name: 'Item 2', short_desc: 'This is item 2', value: 'item2' },
@@ -138,6 +173,14 @@ export const DisabledItemsWithIntentAndDescriptions: Story = {
       { display_name: 'Disabled Item with Intent', intent: 'danger', disabled: true, short_desc: 'This is item 5', value: 'item5' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with five items mixing intents, descriptions and disabled states — the picker modal shows all five so their combined presentation can be reviewed.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await fireEvent.click(canvas.getByRole('button'));
@@ -157,6 +200,14 @@ export const WithValue: Story = {
       { display_name: 'Item 2', value: 'item2' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with two items and item2 pre-selected — the trigger shows the selected label and clicking it opens the popover.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByRole('button')).toBeInTheDocument();
@@ -173,6 +224,14 @@ export const WithValueAndErrors: Story = {
       { display_name: 'Item 2', desc: 'This is item 1', value: 'item2', image: 'https://avatars.githubusercontent.com/u/8861481?v=4' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with a danger-intent item in the list, but the selected value points at the healthy item — the trigger stays clean while the picker highlights the danger item.',
+      },
+    },
+  },
 };
 
 export const WithValueAndErrorsSelected: Story = {
@@ -183,6 +242,14 @@ export const WithValueAndErrorsSelected: Story = {
       { display_name: 'Item 2', desc: 'This is item 1', value: 'item2' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with the danger-intent item pre-selected — the trigger carries the danger styling so the operator can see the selected item has an error.',
+      },
+    },
+  },
 };
 
 export const WithValueAndWarningsSelected: Story = {
@@ -193,6 +260,14 @@ export const WithValueAndWarningsSelected: Story = {
       { display_name: 'Item 2', desc: 'This is item 1', value: 'item2' },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with a pre-selected item whose metadata declares needs_auth — the trigger surfaces the warning so the operator knows the item needs configuration.',
+      },
+    },
+  },
 };
 
 export const AutoSelect: Story = {
@@ -200,6 +275,14 @@ export const AutoSelect: Story = {
     autoSelect: true,
     items: [{ display_name: 'Item 1', value: 'item1' }],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with autoSelect and a single item — the field auto-selects the only option and the trigger shows its label on mount.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await waitFor(() => expect(canvas.getByText('Item 1')).toBeInTheDocument(), { timeout: 500 });
@@ -211,6 +294,14 @@ export const AutoSelectWithShortDescriptions: Story = {
     autoSelect: true,
     items: [{ display_name: 'Item 1', short_desc: 'Short item 1 description', value: 'item1' }],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with autoSelect and a single item that carries a short description — the field auto-selects and the trigger shows both the label and the short description.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await waitFor(() => expect(canvas.getByText('Item 1')).toBeInTheDocument(), { timeout: 500 });
@@ -222,6 +313,14 @@ export const AutoSelectWithDescriptions: Story = {
     autoSelect: true,
     items: [{ display_name: 'Item 1', desc: 'This is item 1', value: 'item1' }],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with autoSelect and a single item that carries a full description — the field auto-selects and the trigger shows the label with the description.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await waitFor(() => expect(canvas.getByText('Item 1')).toBeInTheDocument(), { timeout: 500 });
@@ -230,6 +329,7 @@ export const AutoSelectWithDescriptions: Story = {
 
 export const ItemValuesAreObjectsAndCanBeSelected: Story = {
   args: {
+    forceDropdown: false,
     value: { id: { type: 'string', value: 'item1' } },
     items: [
       { value: { id: { type: 'string', value: 'item1' } } },
@@ -240,6 +340,14 @@ export const ItemValuesAreObjectsAndCanBeSelected: Story = {
       },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Select field with items whose values are hashes rather than primitives. The unlabelled first item shows its JSON as the trigger label; picking the second item swaps the selection to its display_name.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await waitFor(

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

@@ -11,7 +11,11 @@ import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
 import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import { isEqual, size } from 'lodash';
 import { memo, useCallback, useEffect, useMemo, useState } from 'react';
-import { ISelectFieldCollectionItem, SelectFieldCollection } from './SelectCollection';
+import {
+  getSelectItemShortDescription,
+  ISelectFieldCollectionItem,
+  SelectFieldCollection,
+} from './SelectCollection';
 
 export type ISelectFormFieldItem = ISelectFieldCollectionItem;
 
@@ -68,7 +72,7 @@ export const SelectFormField = memo(
     showPlaceholder = true,
     showRightIcon = true,
     hideItemCount,
-    forceDropdown,
+    forceDropdown = true,
     fluid,
     flat,
     intent,
@@ -89,6 +93,7 @@ export const SelectFormField = memo(
           return;
         }
         onChange?.(item.value);
+        setCollectionOpen(false);
       },
       [onChange, value]
     );
@@ -96,7 +101,7 @@ export const SelectFormField = memo(
     const getItemDescription = useCallback(
       (itemValue: unknown) => {
         const item = items.find((item) => isEqual(item.value, itemValue));
-        return item?.desc || item?.short_desc;
+        return getSelectItemShortDescription(item);
       },
       [items]
     );
@@ -133,7 +138,7 @@ export const SelectFormField = memo(
         const item = items.find(
           (item) => isEqual(item.display_name, itemName) || isEqual(item.value, itemName)
         );
-        return item?.short_desc || (item?.desc ? 'Hover to see description' : defaultDesc);
+        return getSelectItemShortDescription(item, defaultDesc);
       },
       [items, showDescription]
     );
@@ -230,13 +235,35 @@ export const SelectFormField = memo(
       [size(items), hideItemCount]
     );
 
-    if (autoSelect && filteredItems.length === 1 && !filteredItems[0].disabled) {
-      if (!disabled && !isEqual(filteredItems[0].value, value) && !value) {
-        handleSelectClick(filteredItems[0]);
+    const autoSelectedItem = useMemo(
+      () =>
+        autoSelect && filteredItems.length === 1 && !filteredItems[0].disabled
+          ? filteredItems[0]
+          : undefined,
+      [autoSelect, filteredItems]
+    );
+
+    // Selecting during render causes a parent-controlled field to synchronously
+    // update while this component is still rendering. React rejects that update
+    // and can enter an infinite render loop. Commit the derived default after
+    // rendering instead; the button below already renders the sole item's label
+    // while the controlled value catches up.
+    useEffect(() => {
+      const valueIsUnset = value === undefined || value === null || value === '';
+
+      if (
+        autoSelectedItem &&
+        !disabled &&
+        valueIsUnset &&
+        !isEqual(autoSelectedItem.value, value)
+      ) {
+        handleSelectClick(autoSelectedItem);
       }
+    }, [autoSelectedItem, disabled, handleSelectClick, value]);
 
-      const itemHasError = hasError(items, filteredItems[0].value);
-      const itemHasWarning = hasWarning(items, filteredItems[0].value);
+    if (autoSelectedItem) {
+      const itemHasError = hasError(items, autoSelectedItem.value);
+      const itemHasWarning = hasWarning(items, autoSelectedItem.value);
 
       return (
         <ReqoreButton
@@ -247,12 +274,12 @@ export const SelectFormField = memo(
           fluid={fluid}
           flat={flat ?? false}
           size={componentSize}
-          label={getLabel(items, value ?? filteredItems[0].value)}
+          label={getLabel(items, value ?? autoSelectedItem.value)}
           description={getItemShortDescription(value as string) as string}
           readOnly
           fixed
           minimal
-          {...getIcon(filteredItems, filteredItems[0].value)}
+          {...getIcon(filteredItems, autoSelectedItem.value)}
           intent={
             itemHasError ? 'danger'
             : itemHasWarning ?
@@ -291,7 +318,6 @@ export const SelectFormField = memo(
             <SelectFieldCollection
               items={filteredItems}
               filters={filters}
-              getItemDescription={(v) => getItemDescription(v) as string}
               value={value}
               onItemSelect={handleSelectClick}
               onClose={() => setCollectionOpen(false)}