@qoretechnologies/reqraft 0.10.8 → 0.10.9

package/dist/components/form/fields/binary/Binary.js

@@ -0,0 +1,74 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReqraftBinaryFormField = void 0;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var reqore_1 = require("@qoretechnologies/reqore");
+var react_1 = require("react");
+var react_use_1 = require("react-use");
+var File_1 = require("../file/File");
+/**
+ * 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.
+ */
+var stripDataUrlPrefix = function (dataUrl) {
+    var 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.
+ */
+exports.ReqraftBinaryFormField = (0, react_1.memo)(function (_a) {
+    var value = _a.value, onChange = _a.onChange, rest = __rest(_a, ["value", "onChange"]);
+    var _b = (0, react_1.useState)(value !== null && value !== void 0 ? value : ''), localValue = _b[0], setLocalValue = _b[1];
+    (0, react_1.useEffect)(function () {
+        if (value !== localValue) {
+            setLocalValue(value !== null && value !== void 0 ? value : '');
+        }
+    }, [value]);
+    (0, react_use_1.useDebounce)(function () {
+        if (localValue !== value) {
+            onChange === null || onChange === void 0 ? void 0 : onChange(localValue);
+        }
+    }, 100, [localValue, onChange]);
+    var handleChange = (0, react_1.useCallback)(function (event) {
+        setLocalValue(event.target.value);
+    }, []);
+    var handleFileChange = (0, react_1.useCallback)(function (file) {
+        var _a;
+        var base64 = stripDataUrlPrefix((_a = file === null || file === void 0 ? void 0 : file.content) !== null && _a !== void 0 ? _a : '');
+        setLocalValue(base64);
+        onChange === null || onChange === void 0 ? void 0 : onChange(base64);
+    }, [onChange]);
+    return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { vertical: true, fluid: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTextarea, __assign({ scaleWithContent: true, fluid: true, value: localValue, onChange: handleChange, onClearClick: function () {
+                    setLocalValue('');
+                    onChange === null || onChange === void 0 ? void 0 : onChange('');
+                }, placeholder: 'Base64-encoded binary value' }, rest)), (0, jsx_runtime_1.jsx)(File_1.ReqraftFileFormField, { disabled: rest.disabled, onChange: handleFileChange })] }));
+});
+exports.default = exports.ReqraftBinaryFormField;
+//# sourceMappingURL=Binary.js.map

package/dist/components/form/fields/binary/Binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Binary.js","sourceRoot":"","sources":["../../../../../src/components/form/fields/binary/Binary.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,mDAA8E;AAE9E,+BAA4E;AAC5E,uCAAwC;AACxC,qCAAyE;AAOzE;;;;GAIG;AACH,IAAM,kBAAkB,GAAG,UAAC,OAAe;IACzC,IAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,IAAA,YAAI,EACxC,UAAC,EAA0D;IAAxD,IAAA,KAAK,WAAA,EAAE,QAAQ,cAAA,EAAK,IAAI,cAA1B,qBAA4B,CAAF;IACnB,IAAA,KAA8B,IAAA,gBAAQ,EAAS,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,EAAE,CAAC,EAA1D,UAAU,QAAA,EAAE,aAAa,QAAiC,CAAC;IAElE,IAAA,iBAAS,EAAC;QACR,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YACzB,aAAa,CAAC,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,EAAE,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,IAAA,uBAAW,EACT;QACE,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;YACzB,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,UAAU,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,EACD,GAAG,EACH,CAAC,UAAU,EAAE,QAAQ,CAAC,CACvB,CAAC;IAEF,IAAM,YAAY,GAAG,IAAA,mBAAW,EAAC,UAAC,KAAuC;QACvE,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,IAAM,gBAAgB,GAAG,IAAA,mBAAW,EAClC,UAAC,IAA0B;;QACzB,IAAM,MAAM,GAAG,kBAAkB,CAAC,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,OAAO,mCAAI,EAAE,CAAC,CAAC;QACvD,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,MAAM,CAAC,CAAC;IACrB,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,CACL,wBAAC,2BAAkB,IAAC,QAAQ,QAAC,KAAK,mBAChC,uBAAC,uBAAc,aACb,gBAAgB,QAChB,KAAK,QACL,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE;oBACZ,aAAa,CAAC,EAAE,CAAC,CAAC;oBAClB,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,EAAE,CAAC,CAAC;gBACjB,CAAC,EACD,WAAW,EAAC,6BAA6B,IACrC,IAAI,EACR,EACF,uBAAC,2BAAoB,IAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,GAAI,IAC1D,CACtB,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,kBAAe,8BAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/reqraft",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "description": "ReQraft is a collection of React components and hooks that are used across Qore Technologies' products made using the ReQore component library from Qore.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -56,7 +56,7 @@
     "@chromatic-com/storybook": "^5.2.1",
     "@netsells/storybook-mockdate": "^0.3.3",
     "@qoretechnologies/qlip": "^0.1.3-beta.20260622084321",
-    "@qoretechnologies/reqore": "^0.70.5",
+    "@qoretechnologies/reqore": "^0.70.6",
     "@storybook/addon-docs": "^10.4.6",
     "@storybook/addon-links": "^10.4.6",
     "@storybook/addon-vitest": "^10.4.6",

package/src/components/form/engine/CompactRow.tsx

@@ -143,6 +143,7 @@ export const CompactRow = memo(
     const isExpanded = useContextSelector(CompactRowContext, (v) =>
       v.expandedOptions.includes(optionName)
     );
+    const autoFocusNameRef = useContextSelector(CompactRowContext, (v) => v.autoFocusNameRef);
     const isHighlighted = useContextSelector(CompactRowContext, (v) =>
       v.highlightedOptions.includes(optionName)
     );
@@ -437,10 +438,13 @@ export const CompactRow = memo(
         const el = editorRef.current?.querySelector<HTMLElement>(
           'input:not([type="hidden"]):not([disabled]), textarea, [contenteditable="true"]'
         );
-        el?.focus();
+        // A user-driven expand scrolls the just-opened editor into view; the
+        // programmatic `autoFocusFirstRequired` expand must NOT — otherwise an
+        // off-screen / below-the-fold form scrolls itself into view on mount.
+        el?.focus(autoFocusNameRef?.current === optionName ? { preventScroll: true } : undefined);
       }, 60);
       return () => window.clearTimeout(id);
-    }, [isExpanded]);
+    }, [isExpanded, optionName, autoFocusNameRef]);
 
     const revertButton =
       changed ?

package/src/components/form/engine/FormEngine.stories.tsx

@@ -4402,3 +4402,172 @@ export const CompactFieldSortWithinGroups: Story = {
     await expect(document.querySelectorAll('.readfirst-cluster-first')).toHaveLength(2);
   },
 };
+
+// `autoFocusFirstRequired` drops the user straight into the first field they
+// must fill. Here `name` is required-but-filled and `description` is
+// required-but-empty, so the engine expands the `description` row on mount and
+// its editor takes focus — no click, no DOM scraping.
+export const CompactAutoFocusFirstRequired: Story = {
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactSchema,
+    value: CompactValue,
+    groups: CompactGroups,
+    autoFocusFirstRequired: true,
+  },
+  play: async () => {
+    await _testsWaitForText('order-fulfilment');
+
+    // The first empty required field (`description`) auto-expands into its
+    // inline editor without any interaction.
+    await waitFor(
+      () =>
+        expect(
+          document.querySelector(
+            '[data-field="description"] input, [data-field="description"] textarea'
+          )
+        ).toBeTruthy(),
+      { timeout: 10000 }
+    );
+
+    // …and that editor receives focus (CompactRow focuses the expanded row's
+    // control). `name` is required but already filled, so it is skipped.
+    await waitFor(
+      () => {
+        const active = document.activeElement as HTMLElement | null;
+        const field = document.querySelector('[data-field="description"]');
+        expect(!!active && !!field && field.contains(active)).toBe(true);
+      },
+      { timeout: 10000 }
+    );
+
+    // The already-satisfied required field is NOT expanded/focused.
+    const nameField = document.querySelector('[data-field="name"]');
+    expect(nameField?.contains(document.activeElement)).toBeFalsy();
+  },
+};
+
+// A required field can be FILLED yet INVALID — here `endpoint` has a value that
+// fails its own `validation_regex` (it must be an http(s) URL). It still "needs
+// attention", so autofocus must land on IT and not skip ahead to the empty
+// `description` (which the old empty-only selector would have chosen). This is
+// the regression guard for the "filled-but-invalid" drift.
+const CompactInvalidFilledSchema: Record<string, TCompactField> = {
+  endpoint: {
+    type: 'string',
+    ui_type: 'string',
+    display_name: 'Endpoint URL',
+    required: true,
+    group: 'info',
+    // Real format constraint: the value must be an http(s) URL. `validation_regex`
+    // is read by the engine's own validation (helpers/validations.ts); it's not on
+    // the base schema type, so cast.
+    validation_regex: '^https?://',
+  } as TCompactField,
+  description: {
+    type: 'string',
+    ui_type: 'string',
+    display_name: 'Description',
+    required: true,
+    group: 'general',
+  },
+};
+
+const CompactInvalidFilledValue: IOptions = {
+  endpoint: { type: 'string', value: 'bad-endpoint' }, // filled, but not an http(s) URL → fails validation_regex
+  // description left empty
+};
+
+export const CompactAutoFocusTargetsInvalidFilledField: Story = {
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactInvalidFilledSchema,
+    value: CompactInvalidFilledValue,
+    groups: CompactGroups,
+    autoFocusFirstRequired: true,
+  },
+  play: async () => {
+    await _testsWaitForText('Endpoint URL');
+
+    // Sanity: the value genuinely fails the field's own validation (it isn't an
+    // http(s) URL), using the very same validator the engine runs — so this is a
+    // real filled-but-INVALID field, not a synthetically-flagged one.
+    expect(validateField('string', 'bad-endpoint', { validation_regex: '^https?://' })).toBe(false);
+
+    // `endpoint` has a value but is invalid, so it needs attention and must be
+    // the target — even though `description` is the empty required field the old
+    // empty-only logic would have picked.
+    await waitFor(
+      () =>
+        expect(
+          document.querySelector('[data-field="endpoint"] input, [data-field="endpoint"] textarea')
+        ).toBeTruthy(),
+      { timeout: 10000 }
+    );
+
+    await waitFor(
+      () => {
+        const active = document.activeElement as HTMLElement | null;
+        const field = document.querySelector('[data-field="endpoint"]');
+        expect(!!active && !!field && field.contains(active)).toBe(true);
+      },
+      { timeout: 10000 }
+    );
+
+    // The empty `description` is NOT the one expanded/focused.
+    const descField = document.querySelector('[data-field="description"]');
+    expect(descField?.contains(document.activeElement)).toBeFalsy();
+  },
+};
+
+// DEMO / manual-test story: the first "needs attention" field is a BOOLEAN,
+// whose compact editor is a `<div tabindex=0>` (ReqoreCheckbox) — NOT an
+// input/textarea/contenteditable that CompactRow's focus selector matches. Both
+// `enabled` and `name` are required and unset, so both need attention; `enabled`
+// is first. Open this in Storybook to see the UX: autofocus TARGETS the boolean
+// (its row expands) and does NOT skip ahead to the focusable `name` field — but
+// no element inside actually receives keyboard focus, so the caret is left
+// nowhere. (This is the non-text-editor focus gap; kept as a playground rather
+// than a hard assertion until we decide how CompactRow should focus such rows.)
+const CompactNonFocusableFirstSchema: Record<string, TCompactField> = {
+  enabled: {
+    type: 'bool',
+    ui_type: 'bool',
+    display_name: 'Enabled',
+    short_desc: 'A boolean — the first field that needs attention',
+    required: true,
+    preselected: true,
+    group: 'info',
+  },
+  name: {
+    type: 'string',
+    ui_type: 'string',
+    display_name: 'Name',
+    short_desc: 'A focusable text field — comes second',
+    required: true,
+    preselected: true,
+    group: 'general',
+  },
+};
+
+const CompactNonFocusableFirstValue: IOptions = {}; // both unset → both need attention
+
+export const CompactAutoFocusNonFocusableFirstField: Story = {
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactNonFocusableFirstSchema,
+    value: CompactNonFocusableFirstValue,
+    groups: CompactGroups,
+    autoFocusFirstRequired: true,
+  },
+  play: async () => {
+    // Smoke: both required-but-unset fields render (both land in "needs
+    // attention"), with the boolean first. Focus behaviour is intentionally left
+    // for manual observation — see the note above.
+    await _testsWaitForText('Enabled');
+    await _testsWaitForText('Name');
+  },
+};

package/src/components/form/engine/FormEngine.tsx

@@ -94,6 +94,7 @@ import {
 import { OptionFieldMessages } from './OptionFieldMessages';
 import { OptionsHelpDialog } from './OptionsHelpDialog';
 import {
+  getFirstAttentionOptionName,
   getOptionGroup,
   getOptionGroupLabel,
   getReadFirstBucket,
@@ -564,6 +565,22 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * plumbing for the inherit_props scope-forwarding contract.
    */
   inheritedFromParent?: Record<string, unknown>;
+
+  /**
+   * Opt-in: on mount, drop the user straight into the first field they must
+   * fill — the first empty, focusable field (in schema/sort order) that is
+   * `required` or a member of a still-unsatisfied one-of `required_groups`
+   * group. Disabled, readonly, read-only-form, and dependency-locked fields are
+   * skipped. In compact (read-first) mode the target row is expanded through
+   * the engine's own `expandedOptions` state, so its editor gains focus with no
+   * DOM scraping or synthetic clicks. Strictly one-shot: it fires the first
+   * time the form has focusable content (so an async-loaded schema is covered)
+   * and then never again — a later value edit, server-driven field update, or
+   * in-place schema reload will not re-focus; only a remount re-arms it. It also
+   * never steals focus from a control the user has already moved into. No-op in
+   * classic (non-compact) mode. Default: off.
+   */
+  autoFocusFirstRequired?: boolean;
 }
 
 // Option types rendered full-width (IDE Options parity, commit 8e6b7781).
@@ -602,6 +619,7 @@ export const FormEngine = ({
   optionActions,
   componentOverrides,
   inheritedFromParent,
+  autoFocusFirstRequired,
   ...rest
 }: IFormEngineProps) => {
   const [options, setOptions] = useState<IQorusFormSchema | undefined>(rest?.options || undefined);
@@ -1517,6 +1535,94 @@ export const FormEngine = ({
     [expandMode]
   );
 
+  // --- First-attention-field autofocus (opt-in) -----------------------------
+  // With `autoFocusFirstRequired`, drop the user straight into the first field
+  // they must fix. We reuse the engine's own ordering (`availableOptions`), the
+  // very same `getOptionBucket` the status boxes use to decide "needs attention"
+  // (so we cover empty-required, unsatisfied one-of, AND filled-but-invalid rows
+  // without ever drifting from what the user sees), and dependency gating
+  // (`dependencyLockedNames`), then expand the target row through
+  // `expandedOptions` — the row's editor-focus effect does the rest. No DOM
+  // scraping, no synthetic clicks, no polling.
+  //
+  // Strictly one-shot: it fires the first time the form has focusable content
+  // (so an async-loaded schema is still covered — the empty first pass doesn't
+  // count), then never again for the life of this instance. A server-driven
+  // field update or an in-place schema reload will NOT re-grab focus; only a
+  // genuine remount (a fresh instance) auto-focuses again, which is the intended
+  // on-mount behaviour.
+  const hasAutoFocusedRef = useRef(false);
+  // The field expanded programmatically for autofocus. A ref (not state) so
+  // CompactRow's 60ms focus timer reads the current value regardless of render
+  // batching; CompactRow focuses this one with `preventScroll` so an off-screen
+  // (or below-the-fold) form is never scrolled into view on mount.
+  const autoFocusNameRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!autoFocusFirstRequired || !compact || !options) {
+      return;
+    }
+    if (hasAutoFocusedRef.current) {
+      return;
+    }
+
+    const orderedNames = Object.keys(availableOptions);
+    if (!orderedNames.length) {
+      return;
+    }
+
+    // Never grab focus from a control the user is already in — including a field
+    // *inside* this form. If a slow/async schema lets the user start typing
+    // before this first-required scan runs, we must not steal their caret. On a
+    // clean mount focus rests on the body, so the intended "drop into the first
+    // field" still fires. Bailing here leaves `hasAutoFocusedRef` false, so it
+    // retries once focus is free.
+    const active = document.activeElement as HTMLElement | null;
+    if (active && active !== document.body) {
+      return;
+    }
+
+    const target = getFirstAttentionOptionName(orderedNames, (fieldName) => {
+      const schema = options[fieldName];
+      if (!schema) {
+        return undefined;
+      }
+      return {
+        focusable:
+          !readOnly &&
+          !schema.disabled &&
+          !(schema as { readonly?: boolean }).readonly &&
+          !dependencyLockedNames.includes(fieldName),
+        // Single source of truth: the same bucket the read-first status boxes
+        // show, so a filled-but-invalid required row is a target too.
+        needsAttention: getOptionBucket(fieldName) === 'attention',
+      };
+    });
+
+    // Mark done even when nothing needs attention, so later value edits or an
+    // in-place schema reload never re-scan or re-focus. Only a remount arms it
+    // again.
+    hasAutoFocusedRef.current = true;
+
+    if (target) {
+      // Set the ref before the state update so CompactRow's focus timer sees it.
+      autoFocusNameRef.current = target;
+      setExpandedOptions((prev) =>
+        prev.includes(target) ? prev
+        : expandMode === 'multi' ? [...prev, target]
+        : [target]
+      );
+    }
+  }, [
+    autoFocusFirstRequired,
+    compact,
+    options,
+    availableOptions,
+    readOnly,
+    dependencyLockedNames,
+    getOptionBucket,
+    expandMode,
+  ]);
+
   // Read-first completion summary (how many shown options have a value set),
   // surfaced as a progress meter at the top of the compact form.
   const readFirstCompletion = useMemo(
@@ -1871,6 +1977,7 @@ export const FormEngine = ({
       showFieldTypes,
       showAllDescriptions,
       expandedOptions,
+      autoFocusNameRef,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,
@@ -1915,6 +2022,7 @@ export const FormEngine = ({
       showFieldTypes,
       showAllDescriptions,
       expandedOptions,
+      autoFocusNameRef,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,

package/src/components/form/engine/compactRowContext.ts

@@ -34,6 +34,12 @@ export interface ICompactRowContext {
   // display name in the read-first chip.
   templates?: IReqoreFormTemplates;
   expandedOptions: string[];
+  // Name of the field the engine expanded programmatically for
+  // `autoFocusFirstRequired`. CompactRow focuses this one with `preventScroll`
+  // so an off-screen / below-the-fold form is never scrolled into view on
+  // mount. A ref (not state) so it's current when the 60ms focus timer fires,
+  // regardless of render batching.
+  autoFocusNameRef?: MutableRefObject<string | undefined>;
   highlightedOptions: string[];
   flashedOptions: string[];
   infoPanelOverrides: Record<string, boolean>;

package/src/components/form/engine/readFirst.ts

@@ -502,3 +502,45 @@ export const getReadFirstCompletion = (
 
   return { total, set, pct };
 };
+
+/** What the "first field to fix" selector needs to know about one field.
+ * Kept deliberately minimal — both verdicts are supplied by the caller — so the
+ * selector is decoupled from the engine's value/schema shapes and unit-testable
+ * in isolation. */
+export interface IFirstAttentionFieldMeta {
+  /** Whether the field can actually receive focus — the caller folds in
+   *  disabled / readonly / read-only-form / unmet-dependency gating here. */
+  focusable: boolean;
+  /** Whether the form considers this field to "need attention". The caller
+   *  supplies this from the SAME `getOptionBucket` the read-first status boxes
+   *  use, so it covers every attention case — empty-required, an unsatisfied
+   *  one-of group, AND a filled-but-invalid value — and the autofocus target can
+   *  never drift from the visible needs-attention set. */
+  needsAttention: boolean;
+}
+
+/**
+ * Pick the first field the user must fix: the first focusable field — in the
+ * supplied (already ordered) name list — that the form buckets as "needs
+ * attention".
+ *
+ * Pure and side-effect free. It deliberately does NOT re-derive emptiness /
+ * required / validity itself; the caller passes `needsAttention` straight from
+ * the engine's own `getOptionBucket`, so there is a single source of truth and
+ * the "focus the first field to fix" affordance can never disagree with the
+ * per-row status the user sees (including filled-but-invalid rows). Returns
+ * `undefined` when nothing needs attention.
+ */
+export const getFirstAttentionOptionName = (
+  orderedNames: string[],
+  getFieldMeta: (name: string) => IFirstAttentionFieldMeta | undefined
+): string | undefined => {
+  for (const name of orderedNames) {
+    const meta = getFieldMeta(name);
+    if (meta?.focusable && meta.needsAttention) {
+      return name;
+    }
+  }
+
+  return undefined;
+};

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

@@ -0,0 +1,90 @@
+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=',
+  },
+  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 = {
+  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 = {
+  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,
+  },
+  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;