@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/form/fields/binary/Binary.stories.tsx

@@ -0,0 +1,122 @@
+import { ReqoreControlGroup } from '@qoretechnologies/reqore';
+import { StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { StoryMeta } from '../../../../types';
+import { ReqraftBinaryFormField } from './Binary';
+
+const meta = {
+  component: ReqraftBinaryFormField,
+  title: 'Components/Form/Binary',
+  args: {
+    onChange: fn(),
+    'aria-label': 'Binary',
+  },
+  render(args) {
+    const [value, setValue] = useState(args.value);
+
+    return (
+      <ReqoreControlGroup>
+        <ReqraftBinaryFormField
+          {...args}
+          value={value}
+          onChange={(value) => {
+            args.onChange?.(value);
+            setValue(value);
+          }}
+        />
+      </ReqoreControlGroup>
+    );
+  },
+} as StoryMeta<typeof ReqraftBinaryFormField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithValue: Story = {
+  args: {
+    value: 'cGFzc3dvcmQ=',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Binary field pre-populated with a base64 payload — the textarea shows the encoded string.',
+      },
+    },
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByLabelText('Binary');
+
+    await expect(textarea).toBeInTheDocument();
+    await expect(textarea).toHaveValue('cGFzc3dvcmQ=');
+  },
+};
+
+export const TypingUpdatesValue: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the empty Binary field. Typing a base64 string into the textarea updates the value and fires onChange after the debounce.',
+      },
+    },
+  },
+  async play({ canvasElement, args }) {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByLabelText('Binary');
+
+    await userEvent.type(textarea, 'YWJj');
+    await expect(textarea).toHaveValue('YWJj');
+    await waitFor(() => expect(args.onChange).toHaveBeenLastCalledWith('YWJj'), {
+      timeout: 500,
+    });
+  },
+};
+
+export const UploadEncodesFileAsBase64: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Binary field with its file drop zone. Uploading a file encodes it as base64 (data-URL prefix stripped) and fires onChange with the encoded string.',
+      },
+    },
+  },
+  async play({ canvasElement, args }) {
+    const file = new File(['hello'], 'test.bin', { type: 'application/octet-stream' });
+    // the hidden file input rendered by the reused ReqraftFileFormField drop zone
+    const input = canvasElement.querySelector('input[type="file"]') as HTMLInputElement;
+
+    await expect(input).toBeInTheDocument();
+    await userEvent.upload(input, file);
+
+    // base64 of "hello" is "aGVsbG8="; the data: URL prefix must be stripped
+    await waitFor(() => expect(args.onChange).toHaveBeenLastCalledWith('aGVsbG8='), {
+      timeout: 1000,
+    });
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    value: 'cGFzc3dvcmQ=',
+    disabled: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Binary field with a base64 value but disabled — the textarea is non-interactive.',
+      },
+    },
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByLabelText('Binary');
+
+    await expect(textarea).toBeDisabled();
+  },
+};

package/src/components/form/fields/binary/Binary.tsx

@@ -0,0 +1,81 @@
+import { ReqoreControlGroup, ReqoreTextarea } from '@qoretechnologies/reqore';
+import { IReqoreTextareaProps } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { ChangeEvent, memo, useCallback, useEffect, useState } from 'react';
+import { useDebounce } from 'react-use';
+import { IFileFormFieldValue, ReqraftFileFormField } from '../file/File';
+
+export interface IReqraftBinaryFormFieldProps extends Omit<IReqoreTextareaProps, 'onChange' | 'value'> {
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+/**
+ * Strip a `data:<mime-type>;base64,` prefix so the emitted value carries raw base64, matching the
+ * canonical binary wire form the Qorus server expects. `ReqraftFileFormField` reads uploads with
+ * `readAsDataURL`, so its `content` always carries that prefix.
+ */
+const stripDataUrlPrefix = (dataUrl: string): string => {
+  const commaIndex = dataUrl.indexOf(',');
+  return commaIndex === -1 ? dataUrl : dataUrl.slice(commaIndex + 1);
+};
+
+/**
+ * A field for binary values encoded as base64. The value can be typed or pasted directly into the
+ * textarea, or populated by uploading a file — the upload reuses {@link ReqraftFileFormField} (the
+ * shared Reqraft file picker / drop zone) rather than a bespoke dropzone; its data-URL content is
+ * decoded to raw base64 for the field value.
+ */
+export const ReqraftBinaryFormField = memo(
+  ({ value, onChange, ...rest }: IReqraftBinaryFormFieldProps) => {
+    const [localValue, setLocalValue] = useState<string>(value ?? '');
+
+    useEffect(() => {
+      if (value !== localValue) {
+        setLocalValue(value ?? '');
+      }
+    }, [value]);
+
+    useDebounce(
+      () => {
+        if (localValue !== value) {
+          onChange?.(localValue);
+        }
+      },
+      100,
+      [localValue, onChange]
+    );
+
+    const handleChange = useCallback((event: ChangeEvent<HTMLTextAreaElement>): void => {
+      setLocalValue(event.target.value);
+    }, []);
+
+    const handleFileChange = useCallback(
+      (file?: IFileFormFieldValue) => {
+        const base64 = stripDataUrlPrefix(file?.content ?? '');
+        setLocalValue(base64);
+        onChange?.(base64);
+      },
+      [onChange]
+    );
+
+    return (
+      <ReqoreControlGroup vertical fluid>
+        <ReqoreTextarea
+          scaleWithContent
+          fluid
+          value={localValue}
+          onChange={handleChange}
+          onClearClick={() => {
+            setLocalValue('');
+            onChange?.('');
+          }}
+          placeholder='Base64-encoded binary value'
+          {...rest}
+        />
+        <ReqraftFileFormField disabled={rest.disabled} onChange={handleFileChange} />
+      </ReqoreControlGroup>
+    );
+  }
+);
+
+export default ReqraftBinaryFormField;

package/src/components/form/fields/boolean/Boolean.stories.tsx

@@ -34,6 +34,14 @@ export const Checked: Story = {
   args: {
     checked: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Boolean field in the checked state. Clicking the toggle flips it to unchecked and fires onChange with false.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const canvas = within(canvasElement);
 
@@ -49,6 +57,14 @@ export const Unchecked: Story = {
   args: {
     checked: false,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Boolean field in the unchecked state. Clicking the toggle flips it to checked and fires onChange with true.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const canvas = within(canvasElement);
 
@@ -59,9 +75,51 @@ export const Unchecked: Story = {
   },
 };
 
+export const Unset: Story = {
+  args: {
+    checked: undefined,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Boolean field without a default choice. The switch remains visibly unset until the user explicitly chooses Yes or No.',
+      },
+    },
+  },
+};
+
+export const UnsetSelectsYes: Story = {
+  args: {
+    checked: undefined,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Verifies that an unset Boolean field saves the first explicit Yes selection instead of treating the missing value as No.',
+      },
+    },
+  },
+  async play({ canvasElement, args }) {
+    const canvas = within(canvasElement);
+
+    await userEvent.click(canvas.getByLabelText('Boolean'));
+    await expect(args.onChange).toHaveBeenLastCalledWith(true);
+  },
+};
+
 export const Disabled: Story = {
   args: {
     checked: true,
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Boolean field checked and disabled — the toggle is visible but non-interactive.',
+      },
+    },
+  },
 };

package/src/components/form/fields/boolean/Boolean.tsx

@@ -18,7 +18,7 @@ export const BooleanFormField = ({
 
   return (
     <ReqoreCheckbox
-      checked={checked ?? false}
+      checked={checked}
       onClick={toggle}
       asSwitch
       onText='Yes'

package/src/components/form/fields/byte-size/ByteSize.stories.tsx

@@ -30,6 +30,14 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ByteSize field with no value. Typing a number into the amount input fires onChange with the composed byte-size expression.',
+      },
+    },
+  },
   play: async ({ canvasElement, args }) => {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Byte size amount');
@@ -43,6 +51,14 @@ export const WithValue: Story = {
   args: {
     value: '512MiB',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ByteSize field pre-populated with "512MiB" — the amount and unit are split across the number input and the MiB unit selector.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     await expect(await canvas.findByDisplayValue('512')).toBeInTheDocument();
@@ -55,6 +71,14 @@ export const ReadOnly: Story = {
     value: '512MiB',
     readOnly: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ByteSize field with "512MiB" in read-only mode — the amount input is marked readonly and rejects further edits.',
+      },
+    },
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const input = await canvas.findByDisplayValue('512');

package/src/components/form/fields/color/Color.stories.tsx

@@ -34,6 +34,14 @@ export const WithValue: Story = {
   args: {
     value: { r: 100, g: 149, b: 237, a: 1 },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Color field with a cornflower-blue RGBA value pre-selected in the sketch picker.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const picker = canvasElement.querySelector('.sketch-picker');
     const colorPanel = canvasElement.querySelector('.saturation-white');
@@ -47,12 +55,26 @@ export const Red: Story = {
   args: {
     value: { r: 220, g: 53, b: 69, a: 1 },
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the Color field with a red RGBA value pre-selected in the sketch picker.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     await expect(canvasElement.querySelector('.sketch-picker')).toBeInTheDocument();
   },
 };
 
 export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the Color field with no value — the sketch picker mounts empty.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     await expect(canvasElement.querySelector('.sketch-picker')).toBeInTheDocument();
   },
@@ -63,6 +85,14 @@ export const Disabled: Story = {
     value: { r: 100, g: 149, b: 237, a: 1 },
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Color field with a value but disabled — the sketch picker is visible but non-interactive.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     await expect(canvasElement.querySelector('.sketch-picker')).toBeInTheDocument();
   },

package/src/components/form/fields/cron/Cron.stories.tsx

@@ -39,6 +39,14 @@ export const Default: Story = {
       'aria-label': label,
     })),
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Cron field with a "1 1 1 1 1" schedule split across the Minute / Hour / Day / Month / Weekday inputs. Typing into a segment fires onChange with the recomposed expression; the clear button resets the value.',
+      },
+    },
+  },
 
   async play({ args, canvasElement }) {
     const canvas = within(canvasElement);

package/src/components/form/fields/date/Date.stories.tsx

@@ -30,6 +30,13 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the Date field with no value — the input mounts empty.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const input = canvasElement.querySelector('input');
     await expect(input).toBeInTheDocument();
@@ -40,6 +47,14 @@ export const WithValue: Story = {
   args: {
     value: '2025-01-15',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Date field pre-populated with 2025-01-15 — the input shows the initial value without firing onChange.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const input = canvasElement.querySelector('input');
     await expect(input).toBeInTheDocument();
@@ -52,4 +67,11 @@ export const Disabled: Story = {
     value: '2025-06-01',
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the Date field with a value but disabled — the input is non-interactive.',
+      },
+    },
+  },
 };

package/src/components/form/fields/file/File.stories.tsx

@@ -30,6 +30,14 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field with no value — the "Click or drop files here to upload" drop zone is visible.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('Click or drop files here to upload')).toBeInTheDocument();
@@ -44,6 +52,14 @@ export const WithValue: Story = {
       size: 28736,
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field pre-populated with a PDF value — the file name is displayed in place of the drop zone.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('report.pdf')).toBeInTheDocument();
@@ -58,6 +74,14 @@ export const WithImageValue: Story = {
       size: 1024,
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field pre-populated with a PNG image value — the file name and an inline preview thumbnail are shown.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('photo.png')).toBeInTheDocument();
@@ -75,6 +99,14 @@ export const WithAcceptedExtensions: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field with an accept option limiting uploads to PNG, JPEG and PDF — the allowed extensions are listed below the drop zone.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('Click or drop files here to upload')).toBeInTheDocument();
@@ -86,6 +118,14 @@ export const Multiple: Story = {
   args: {
     multiple: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field with multiple-selection enabled — the underlying input carries the multiple attribute and the drop zone stays visible after files are added.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('Click or drop files here to upload')).toBeInTheDocument();
@@ -105,6 +145,14 @@ export const WithBuildTab: Story = {
       content: { type: 'string', ui_type: 'string', display_name: 'Content', required: true },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the File field with an argSchema — a "Build a File" tab appears alongside the "Upload a File" drop zone so the user can synthesize a file from schema fields.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     await expect(canvas.getByText('Upload a File')).toBeInTheDocument();

package/src/components/form/fields/long-string/LongString.stories.tsx

@@ -39,6 +39,14 @@ export const WithValue: Story = {
   args: {
     value: 'Hello world',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the LongString field pre-populated with "Hello world". Clicking clear empties the textarea and fires onChange; typing new content updates the value after the debounce.',
+      },
+    },
+  },
   async play({ canvasElement, args, step }) {
     const canvas = within(canvasElement);
     const textarea = canvas.getByLabelText('LongString');
@@ -66,6 +74,14 @@ export const WithValue: Story = {
 };
 
 export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the LongString field with no value. Typing into the empty textarea updates the value and fires onChange after the debounce.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const canvas = within(canvasElement);
     const textarea = canvas.getByLabelText('LongString');
@@ -86,6 +102,14 @@ export const Disabled: Story = {
     value: 'Cannot edit this',
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the LongString field with a value but disabled — the textarea shows the value and rejects further edits.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     const textarea = canvas.getByLabelText('LongString');

package/src/components/form/fields/markdown/Markdown.stories.tsx

@@ -35,6 +35,14 @@ export const Default: Story = {
   args: {
     'aria-label': 'MarkdownEditor',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Markdown field pre-populated with the sample markdown fixture — the editor and the live preview render side by side.',
+      },
+    },
+  },
   async play({ canvasElement, args }) {
     const canvas = within(canvasElement);
     const editor = canvas.getByLabelText('MarkdownEditor');

package/src/components/form/fields/multi-select/MultiSelectFormField.tsx

@@ -2,6 +2,7 @@ import { ReqoreMultiSelect } from '@qoretechnologies/reqore';
 import { TReqoreMultiSelectItem } from '@qoretechnologies/reqore/dist/components/MultiSelect';
 import { IQorusAllowedValue } from '@qoretechnologies/ts-toolkit';
 import { memo, useMemo } from 'react';
+import { getSelectItemShortDescription } from '../select/SelectCollection';
 
 export interface IMultiSelectFormFieldProps {
   /** Currently selected values (plain scalars) */
@@ -33,16 +34,19 @@ export const MultiSelectFormField = memo(
 
     const reqoreItems = useMemo<TReqoreMultiSelectItem[]>(() => {
       const base = items.map(
-        (item): TReqoreMultiSelectItem => ({
-          value: item.value?.value as string,
-          label: item.display_name ?? String(item.value?.value ?? ''),
-          description: item.short_desc || item.desc,
-          tooltip: item.desc || item.short_desc,
-          wrap: true,
-          // IDE parity: when `*` is selected, every other item is disabled.
-          disabled:
-            !!item.disabled || (selectedValues.includes('*') && item.value?.value !== '*'),
-        })
+        (item): TReqoreMultiSelectItem => {
+          const description = getSelectItemShortDescription(item);
+
+          return {
+            value: item.value?.value as string,
+            label: item.display_name ?? String(item.value?.value ?? ''),
+            description,
+            wrap: true,
+            // IDE parity: when `*` is selected, every other item is disabled.
+            disabled:
+              !!item.disabled || (selectedValues.includes('*') && item.value?.value !== '*'),
+          };
+        }
       );
 
       // IDE parity: selected values that aren't in the allowed list still

package/src/components/form/fields/number/Number.stories.tsx

@@ -38,6 +38,14 @@ export const Integer: Story = {
     value: 42,
     type: 'int',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Number field in integer mode with 42 pre-populated. Typing a new integer updates the value and fires onChange after the debounce.',
+      },
+    },
+  },
   async play({ args, canvasElement }) {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Number');
@@ -58,6 +66,14 @@ export const Float: Story = {
     value: 3.14,
     type: 'float',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Number field in float mode with 3.14 pre-populated — the input uses a 0.1 step and accepts decimals.',
+      },
+    },
+  },
   async play({ args, canvasElement }) {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Number');
@@ -76,6 +92,13 @@ export const Empty: Story = {
   args: {
     type: 'int',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Renders the Number field in integer mode with no value — the input mounts empty.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Number');
@@ -91,6 +114,14 @@ export const Disabled: Story = {
     type: 'int',
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the Number field with a value but disabled — the input shows the value and rejects further edits.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
     const input = canvas.getByLabelText('Number');