@qoretechnologies/reqraft 0.10.16 → 0.10.18

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

@@ -15,10 +15,7 @@ import {
 } from '@qoretechnologies/reqore';
 import { IReqoreCollectionProps } from '@qoretechnologies/reqore/dist/components/Collection';
 import { IReqoreCollectionItemProps } from '@qoretechnologies/reqore/dist/components/Collection/item';
-import {
-  IReqorePanelAction,
-  IReqorePanelProps,
-} from '@qoretechnologies/reqore/dist/components/Panel';
+import { IReqorePanelProps } from '@qoretechnologies/reqore/dist/components/Panel';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
 import {
@@ -41,6 +38,8 @@ import {
   TQorusFormOperatorValue,
   TQorusType,
 } from '@qoretechnologies/ts-toolkit';
+import { resolveOptionActions, TOptionActions } from './optionActions';
+import { createRendererOnlyUiTypeCheck, isRendererOnlyUiType } from './rendererTypes';
 import { cloneDeep, findKey, flatten, forEach, isEqual, isPlainObject, last } from 'lodash';
 import isArray from 'lodash/isArray';
 import map from 'lodash/map';
@@ -245,12 +244,16 @@ const StyledCommitDock = styled.div<{ $bg: string; $border: string }>`
 `;
 
 export const getType = (
-  type: TQorusType | TQorusType[],
+  type?: TQorusType | TQorusType[],
   operators?: IOperatorsSchema,
   operator?: TOperatorValue
 ): TQorusType => {
   const finalType = getTypeFromOperator(operators, fixOperatorValue(operator)) || type;
-  return (isArray(finalType) ? finalType[0] : finalType) as TQorusType;
+  const resolvedType = isArray(finalType) ? finalType[0] : finalType;
+
+  // A value can be received before its server-driven option schema. Keep the
+  // renderer type-safe during that transition without guessing a concrete type.
+  return (resolvedType || 'any') as TQorusType;
 };
 
 const getTypeFromOperator = (
@@ -267,6 +270,38 @@ export const fixOperatorValue = (operator: TOperatorValue): (string | null | und
   return isArray(operator) ? operator : [operator];
 };
 
+/**
+ * The renderer-only predicate. Defaults to reqraft's built-ins; a FormEngine
+ * instance passes its own (built-ins + the `rendererOnlyUiTypes` prop) so a
+ * consumer's injected editors are recognised too. See `./rendererTypes`.
+ */
+type TRendererOnlyCheck = (type?: TQorusType | TQorusType[]) => boolean;
+
+const getOptionSchemaStorageType = (
+  option?: TQorusFormFieldSchema,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
+): TQorusType =>
+  ((isRendererOnly(option?.ui_type)
+    ? option?.type || option?.ui_type
+    : option?.ui_type || option?.type) || 'any') as TQorusType;
+
+const getOptionFieldStorageType = (
+  optionName: string,
+  fieldType: TQorusType | TQorusType[] | undefined,
+  schema?: IQorusFormSchema,
+  operators?: IOperatorsSchema,
+  operatorData?: TOperatorValue,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
+): TQorusType => {
+  const schemaOption = schema?.[optionName];
+  const storedType =
+    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType))
+      ? fieldType
+      : getOptionSchemaStorageType(schemaOption, isRendererOnly);
+
+  return getType(storedType as TQorusType, operators, operatorData);
+};
+
 export const hasRequiredOptions = (options: IQorusFormSchema = {}) => {
   return !!findKey(options, (option) => option.required);
 };
@@ -278,11 +313,19 @@ export const OptionsContext = createContext<{
 
 export const fixOptions = (
   value: TQorusForm | TQorusFlatForm = {},
-  options: IQorusFormSchema,
-  operators?: IOperatorsSchema
+  options?: IQorusFormSchema,
+  operators?: IOperatorsSchema,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
 ): TQorusForm => {
   const fixedValue = cloneDeep(value);
 
+  // Server-driven schemas can arrive after the persisted value. Preserve that
+  // value verbatim until its schema is available instead of manufacturing
+  // partially typed form fields that can crash the following render.
+  if (!size(options)) {
+    return fixedValue as TQorusForm;
+  }
+
   forEach(options, (option, name) => {
     if (
       option.value ||
@@ -292,7 +335,7 @@ export const fixOptions = (
     ) {
       let obj: IQorusFormField;
       const type = getType(
-        (option.ui_type || option.type) as TQorusType,
+        getOptionSchemaStorageType(option, isRendererOnly),
         operators,
         (fixedValue[name] as IQorusFormField)?.op
       );
@@ -328,20 +371,35 @@ export const fixOptions = (
       let newOption = option as IQorusFormField;
 
       if (!isPlainObject(newOption) || !(newOption as IQorusFormField)?.type) {
+        const isUntypedEnvelope = isPlainObject(newOption) && 'value' in newOption;
+        const untypedFieldValue =
+          isUntypedEnvelope ? (newOption as IQorusFormField).value : newOption;
+        // Spread the original envelope first so every key it carried survives —
+        // rebuilding from just {type, value} silently dropped `op`, `is_expression`
+        // and anything else a field needs to render, which emptied the card.
         const fixedOption: IQorusFormField = {
+          ...(isPlainObject(newOption) ? (newOption as IQorusFormField) : {}),
           type: getType(
-            (options?.[optionName]?.ui_type || options?.[optionName]?.type) as TQorusType,
+            getOptionSchemaStorageType(options?.[optionName], isRendererOnly),
             operators,
             (newOption as IQorusFormField)?.op
           ),
-          value: newOption,
+          value: untypedFieldValue,
         };
 
-        if ((newOption as IQorusFormField)?.is_expression) {
-          fixedOption.is_expression = true;
-        }
-
         newOption = fixedOption;
+      } else if (
+        newOption.type === options?.[optionName]?.ui_type &&
+        isRendererOnly(newOption.type)
+      ) {
+        newOption = {
+          ...newOption,
+          type: getType(
+            getOptionSchemaStorageType(options?.[optionName], isRendererOnly),
+            operators,
+            newOption.op
+          ),
+        };
       }
 
       if (
@@ -411,7 +469,7 @@ export const flattenOptions = (options: TQorusForm): TQorusFlatForm => {
 };
 
 export const getTypeAndCanBeNull = (
-  type: TQorusType | TQorusType[],
+  type?: TQorusType | TQorusType[],
   allowed_values?: any[],
   operatorData?: TOperatorValue,
   operators?: IOperatorsSchema
@@ -546,19 +604,36 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * option's name/schema/value (the context the IDE's `AiAssistanceAction`
    * captures); the consumer injects the button, reqraft stays AI-free.
    */
-  optionActions?:
-    | IReqorePanelAction[]
-    | ((context: {
-        name: string;
-        schema: IQorusFormSchema[string];
-        value?: TOption;
-      }) => IReqorePanelAction[]);
+  optionActions?: TOptionActions;
+  /**
+   * Whether per-option injected actions collapse into the row's overflow menu
+   * instead of rendering as inline buttons.
+   *
+   * `'auto'` (default) collapses when the device cannot hover or the viewport is
+   * narrow — on a phone a hover-gated action would otherwise be unreachable, and
+   * a row has no width for a button strip. `'always'` / `'never'` force it, which
+   * consumers can use for a known-mobile surface and stories use to capture the
+   * collapsed state deterministically.
+   *
+   * Actions beyond `MAX_INLINE_OPTION_ACTIONS` always overflow into the menu, so
+   * a consumer injecting many actions can never blow out the row.
+   */
+  optionActionsCollapse?: 'auto' | 'always' | 'never';
   /**
    * SEAM (reqraft): consumer-injected field editors for types reqraft doesn't
    * ship (IDE domain fields). Keyed by field `type`/`ui_type`; forwarded through
    * `TemplateField` to the `AutoFormField` override seam.
    */
   componentOverrides?: Record<string, React.FC<any>>;
+  /**
+   * The `ui_type` names among `componentOverrides` that select a bespoke editor
+   * but store their value as the schema's plainer `type` (a `cron` editor stores
+   * a string). Declaring them here keeps the field's stored `type` correct —
+   * without it the renderer name is written into the value and validation and
+   * round-tripping both break. Merged with reqraft's own built-in list, so a
+   * consumer's new editor no longer needs a reqraft release to be handled.
+   */
+  rendererOnlyUiTypes?: string[];
 
   /**
    * Bag of values forwarded from an outer FormEngine scope, used as a
@@ -644,12 +719,35 @@ export const FormEngine = ({
   optionsLoader,
   onValidityChange,
   optionActions,
+  optionActionsCollapse = 'auto',
   componentOverrides,
+  rendererOnlyUiTypes,
   inheritedFromParent,
   autoFocusFirstRequired,
   initialExpandedOptions,
   ...rest
 }: IFormEngineProps) => {
+  // Built-ins + whatever the consumer declared for its own injected editors.
+  const isRendererOnly = useMemo(
+    () => createRendererOnlyUiTypeCheck(rendererOnlyUiTypes),
+    [JSON.stringify(rendererOnlyUiTypes)]
+  );
+  // Pointer CAPABILITY and viewport WIDTH are different questions and both
+  // matter here: a hover-gated action is unreachable without a hover, and a
+  // phone-width row has no space for a button strip either way. Both now come
+  // from Reqore's context (one subscription for the whole app) rather than a
+  // reqraft-local matchMedia hook.
+  //
+  // `isHoverCapable` defaults to `true` in Reqore, but fall back explicitly so
+  // an older Reqore — where the property does not exist — degrades to "this
+  // pointer hovers" (the pre-existing behaviour) instead of collapsing every
+  // action into a menu for everyone.
+  const isHoverCapable = useReqoreProperty('isHoverCapable') ?? true;
+  const isMobile = useReqoreProperty('isMobile');
+  const collapseOptionActions =
+    optionActionsCollapse === 'always' ? true
+    : optionActionsCollapse === 'never' ? false
+    : !isHoverCapable || !!isMobile;
   const [options, setOptions] = useState<IQorusFormSchema | undefined>(rest?.options || undefined);
   // optionsLoader lifecycle: loading feeds the skeleton gate, error the banner.
   const [optionsLoading, setOptionsLoading] = useState<boolean>(!!optionsLoader && !rest?.options);
@@ -785,7 +883,7 @@ export const FormEngine = ({
     fields: TQorusForm | TQorusFlatForm;
     meta?: IOptionsOnChangeMeta;
   }>(() => ({
-    fields: fixOptions(value, options || {}),
+    fields: fixOptions(value, options || {}, undefined, isRendererOnly),
     meta: undefined,
   }));
   const originalValue = useRef<any>();
@@ -878,7 +976,7 @@ export const FormEngine = ({
           setOptions({});
           return;
         }
-        setLocalValue({ fields: fixOptions(value, data.data), meta: undefined });
+        setLocalValue({ fields: fixOptions(value, data.data, undefined, isRendererOnly), meta: undefined });
         if (!operatorsUrl) {
           setLoading(false);
         }
@@ -923,7 +1021,7 @@ export const FormEngine = ({
         }
         setOptions(data.data);
         onOptionsLoaded?.(data.data);
-        setLocalValue({ fields: fixOptions({}, data.data), meta: undefined });
+        setLocalValue({ fields: fixOptions({}, data.data, undefined, isRendererOnly), meta: undefined });
       })();
     }
   }, [url, customUrl]);
@@ -947,7 +1045,7 @@ export const FormEngine = ({
   }, [operatorsUrl]);
 
   useUpdateEffect(() => {
-    const fixedValue = fixOptions(value, options || {});
+    const fixedValue = fixOptions(value, options || {}, undefined, isRendererOnly);
 
     // When the value we're receiving is the one we just emitted AND fixOptions has nothing to
     // meaningfully add or change, skip the update. This breaks the controlled-component loop for
@@ -971,19 +1069,21 @@ export const FormEngine = ({
     }
 
     setLocalValue?.({ fields: fixedValue, meta: undefined });
-  }, [JSON.stringify(options), JSON.stringify(value)]);
+  }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly]);
 
   const handleValueChange = useCallback(
     (optionName: string, val?: any, _type?: string, isFunction?: boolean) => {
       setLocalValue(({ fields = {} }) => {
-        const schemaType = (options?.[optionName]?.ui_type ||
-          options?.[optionName]?.type) as TQorusType;
+        const schemaType = getOptionSchemaStorageType(options?.[optionName], isRendererOnly);
         const isAnyLike = schemaType === 'any' || schemaType === 'auto';
         // For any/auto schema types, preserve the user's chosen type stored in the field
         const resolvedSchemaType =
-          isAnyLike && (fields[optionName] as IQorusFormField)?.type ?
-            ((fields[optionName] as IQorusFormField).type as TQorusType)
-          : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
+          isAnyLike && (fields[optionName] as IQorusFormField)?.type
+            ? ((fields[optionName] as IQorusFormField).type as TQorusType)
+            : (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
+                isRendererOnly((fields[optionName] as IQorusFormField)?.type)
+              ? schemaType
+              : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
         const type =
           _type ||
           getTypeAndCanBeNull(resolvedSchemaType, options?.[optionName]?.allowed_values).type;
@@ -1066,6 +1166,7 @@ export const FormEngine = ({
     [
       onSingleOptionsChange,
       onDependableOptionChange,
+      isRendererOnly,
       JSON.stringify(options),
       JSON.stringify(operators),
     ]
@@ -1186,8 +1287,7 @@ export const FormEngine = ({
         optionName as string,
         getDefaultValue(options?.[optionName as string]),
         getTypeAndCanBeNull(
-          (options?.[optionName as string]?.ui_type ||
-            options?.[optionName as string]?.type) as TQorusType,
+          getOptionSchemaStorageType(options?.[optionName as string], isRendererOnly),
           options?.[optionName as string]?.allowed_values
         ).type
       );
@@ -1215,36 +1315,37 @@ export const FormEngine = ({
           return newValue;
         }
 
-        const schemaType = getType(
+        const rendererType = getType(
           (options[optionName].ui_type || options[optionName].type) as TQorusType,
           operators,
           (option as IQorusFormField)?.op
         );
+        const storageType = getOptionFieldStorageType(
+          optionName,
+          (option as IQorusFormField)?.type,
+          options,
+          operators,
+          (option as IQorusFormField)?.op,
+          isRendererOnly
+        );
 
         if (!isPlainObject(option)) {
           return {
             ...newValue,
             [optionName]: {
-              type: schemaType,
+              type: storageType || rendererType,
               value: option,
             },
           };
         }
 
-        // any/auto: preserve the user-picked type; otherwise normalize to the
-        // schema type (ui_type wins) so rendering and validation agree.
-        const isAnyLike = schemaType === 'any' || schemaType === 'auto';
-        const effectiveType =
-          isAnyLike && (option as IQorusFormField)?.type ?
-            (option as IQorusFormField).type
-          : schemaType;
-
         return {
           ...newValue,
-          [optionName]: { ...(option as IQorusFormField), type: effectiveType },
+          [optionName]: { ...(option as IQorusFormField), type: storageType || rendererType },
         };
       }, {});
   }, [
+    isRendererOnly,
     JSON.stringify(fixedValue),
     JSON.stringify(options),
     unavailableOptionsCount.current,
@@ -1341,10 +1442,14 @@ export const FormEngine = ({
     const fields: IFormFieldValidityData[] = reduce(
       availableOptions,
       (result, option, optionName) => {
-        const type =
-          (option as IQorusFormField).type ||
-          (options?.[optionName]?.ui_type as TQorusType) ||
-          (options?.[optionName]?.type as TQorusType);
+        const type = getOptionFieldStorageType(
+          optionName,
+          (option as IQorusFormField).type,
+          options,
+          operators,
+          (option as IQorusFormField).op,
+          isRendererOnly
+        );
         const optionValue = (option as IQorusFormField).value;
 
         const isRequired = options?.[optionName]?.required;
@@ -1386,8 +1491,10 @@ export const FormEngine = ({
       invalidFields,
     };
   }, [
+    isRendererOnly,
     JSON.stringify(availableOptions),
     JSON.stringify(options),
+    JSON.stringify(operators),
     JSON.stringify(localValue.fields),
   ]);
 
@@ -1406,8 +1513,14 @@ export const FormEngine = ({
           showInvalidOptionsOnly &&
           isOptionValid(
             optionName,
-            (options?.[optionName]?.ui_type as TQorusType) ||
-              (options?.[optionName]?.type as TQorusType),
+            getOptionFieldStorageType(
+              optionName,
+              (option as IQorusFormField).type,
+              options,
+              operators,
+              (option as IQorusFormField).op,
+              isRendererOnly
+            ),
             (option as IQorusFormField).value
           )
         ) {
@@ -1417,7 +1530,13 @@ export const FormEngine = ({
       },
       {}
     );
-  }, [showInvalidOptionsOnly, JSON.stringify(availableOptions)]);
+  }, [
+    showInvalidOptionsOnly,
+    isRendererOnly,
+    JSON.stringify(availableOptions),
+    JSON.stringify(options),
+    JSON.stringify(operators),
+  ]);
 
   // Read-first STATUS / BOX for one option — lifted to component scope so the
   // status boxes (renderCompact) and the header's "needs attention" count share
@@ -1437,7 +1556,14 @@ export const FormEngine = ({
     (name: string, hidden = false): TReadFirstStatus => {
       if (hidden) return 'optional';
       const schema = options?.[name];
-      const type = (schema?.ui_type || schema?.type) as TQorusType;
+      const type = getOptionFieldStorageType(
+        name,
+        (availableOptions as TQorusForm)?.[name]?.type,
+        options,
+        operators,
+        (availableOptions as TQorusForm)?.[name]?.op,
+        isRendererOnly
+      );
       const value = (availableOptions as TQorusForm)?.[name]?.value;
       const empty = isOptionValueEmpty(value);
       const reqGroups = (schema?.required_groups as string[] | undefined) || [];
@@ -1459,8 +1585,10 @@ export const FormEngine = ({
       });
     },
     [
+      isRendererOnly,
       JSON.stringify(options),
       JSON.stringify(availableOptions),
+      JSON.stringify(operators),
       isOptionValid,
       requiredGroupsInfo,
       schemaMsgIntent,
@@ -1726,10 +1854,10 @@ export const FormEngine = ({
           next[optionName] = value as IQorusFormField;
         }
       });
-      return { fields: fixOptions(next, options || {}, operators), meta: undefined };
+      return { fields: fixOptions(next, options || {}, operators, isRendererOnly), meta: undefined };
     });
     setRequiredOnly(false);
-  }, [JSON.stringify(options), JSON.stringify(operators)]);
+  }, [JSON.stringify(options), JSON.stringify(operators), isRendererOnly]);
 
   const getCustomMenuTemplateItems = useCallback<(optionName: string) => TCustomTemplateItems>(
     (optionName) => {
@@ -1759,6 +1887,25 @@ export const FormEngine = ({
       suppressSchemaMessages?: boolean
     ) => {
       const operatorParts = fixOperatorValue(other.op);
+      // The RENDERER type for this row — which editor mounts. Distinct from the
+      // storage type on the value envelope: a `richtext` field stores a string
+      // but must render the richtext editor, so `ui_type` wins here.
+      //
+      // The exception is an any-like `ui_type`. Those schemas say
+      // `ui_type: 'any'` precisely so the user can pick a concrete type, and
+      // that pick lives on the field's stored `type` — letting 'any' win would
+      // pin the row to the untyped editor forever.
+      //
+      // The trailing fallbacks keep the row rendering when a server-driven
+      // schema has not arrived yet (`type` undefined) instead of crashing.
+      const schemaUiType = options?.[optionName]?.ui_type as TQorusType;
+      const uiTypeIsAnyLike = schemaUiType === 'any' || schemaUiType === 'auto';
+      const resolvedType =
+        (schemaUiType && !uiTypeIsAnyLike ? schemaUiType : undefined) ||
+        type ||
+        schemaUiType ||
+        (options?.[optionName]?.type as TQorusType) ||
+        'any';
       return (
         <>
           {(() => {
@@ -1900,15 +2047,18 @@ export const FormEngine = ({
             // (DPQL text mode); opt out per-form via `templateFieldProps`.
             allowTextExpressions
             allowCustomValues={
-              options?.[optionName]?.supports_custom_values !== false && type !== 'any'
+              options?.[optionName]?.supports_custom_values !== false && resolvedType !== 'any'
             }
             templates={templates.value}
             {...getTypeAndCanBeNull(
-              type as TQorusType,
+              // The RENDERER type picks the editor — the storage type lives on
+              // the value envelope. Passing storage here rendered a `richtext`
+              // field as a plain string input.
+              resolvedType,
               options?.[optionName]?.allowed_values,
               other.op
             )}
-            ui_type={type}
+            ui_type={resolvedType}
             name={optionName}
             uniqueName={`${uniqueName ? `${uniqueName}.` : `${name ? `${name}.` : ''}`}${optionName}`}
             onChange={
@@ -1949,7 +2099,7 @@ export const FormEngine = ({
             schema={options || {}}
             allOptions={availableOptions}
             name={optionName}
-            option={{ type, ...other }}
+            option={{ type: resolvedType, ...other }}
             getType={getTypeForOption}
           />
           {operators && size(operators) && size(other.op) ?
@@ -1964,7 +2114,7 @@ export const FormEngine = ({
                     intent='info'
                     label={
                       other.value ?
-                        type === 'richtext' ?
+                        resolvedType === 'richtext' ?
                           richtextToString(other.value)
                         : JSON.stringify(other.value)
                       : ''
@@ -2057,6 +2207,8 @@ export const FormEngine = ({
       getTypeForOption,
       isOptionValid,
       confirmAction,
+      optionActions,
+      collapseOptionActions,
       renderOption,
       theme,
       cText,
@@ -2102,6 +2254,8 @@ export const FormEngine = ({
       getTypeForOption,
       isOptionValid,
       confirmAction,
+      optionActions,
+      collapseOptionActions,
       renderOption,
       theme,
       cText,
@@ -2238,7 +2392,14 @@ export const FormEngine = ({
       const isFieldInvalid = (name: string) =>
         !isOptionValid(
           name,
-          (options?.[name]?.ui_type || options?.[name]?.type) as TQorusType,
+          getOptionFieldStorageType(
+            name,
+            (shownOptions as TQorusForm)[name]?.type,
+            options,
+            operators,
+            (shownOptions as TQorusForm)[name]?.op,
+            isRendererOnly
+          ),
           (shownOptions as TQorusForm)[name]?.value
         );
       const comparator = (a: { name: string }, b: { name: string }): number => {
@@ -2347,7 +2508,7 @@ export const FormEngine = ({
           optionField={
             entry.hidden ?
               ({
-                type: (options?.[entry.name]?.ui_type || options?.[entry.name]?.type) as TQorusType,
+                type: getOptionSchemaStorageType(options?.[entry.name], isRendererOnly),
                 value: undefined,
               } as IQorusFormField)
             : ((shownOptions as TQorusForm)[entry.name] as IQorusFormField)
@@ -2808,13 +2969,11 @@ export const FormEngine = ({
                 // option's schema as context). The consumer (the IDE) injects
                 // it; same factory pattern as the ExpressionBuilder's
                 // `extraActions`.
-                ...(typeof optionActions === 'function' ?
-                  optionActions({
-                    name: optionName,
-                    schema: options[optionName],
-                    value: availableOptions?.[optionName] as TOption,
-                  })
-                : (optionActions ?? [])),
+                ...resolveOptionActions(optionActions, {
+                  name: optionName,
+                  schema: options[optionName],
+                  value: availableOptions?.[optionName] as TOption,
+                }),
                 {
                   size: 'tiny',
                   icon: 'FullscreenLine',