@qoretechnologies/reqraft 0.10.57 → 0.10.58-pr.129.g43f4175

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

@@ -2324,10 +2324,13 @@ const FormEngineImpl = ({
 
   const isOptionValid = useCallback(
     (optionName: string, type: TQorusType, optionValue: any) => {
+      const isEmpty = optionValue === undefined || optionValue === '';
+      // An empty field locked by an unmet `depends_on` does not apply, so it is
+      // not missing — the same rule the read-first status follows.
       if (
-        !options?.[optionName]?.required &&
-        !options?.[optionName]?.required_groups &&
-        (optionValue === undefined || optionValue === '')
+        isEmpty &&
+        ((!options?.[optionName]?.required && !options?.[optionName]?.required_groups) ||
+          dependencyLockedNames.includes(optionName))
       ) {
         return true;
       }
@@ -2342,7 +2345,12 @@ const FormEngineImpl = ({
         isFunction: (availableOptions?.[optionName] as { is_expression?: boolean })?.is_expression,
       } as any);
     },
-    [JSON.stringify(options), JSON.stringify(availableOptions), JSON.stringify(localValue.fields)]
+    [
+      JSON.stringify(options),
+      JSON.stringify(availableOptions),
+      JSON.stringify(localValue.fields),
+      dependencyLockedNames,
+    ]
   );
 
   const getValidityData = useCallback((): IFormValidityData => {
@@ -2366,7 +2374,17 @@ const FormEngineImpl = ({
 
         let validation: IValidationResult;
 
-        if (!isRequired && !hasRequiredGroups && isEmpty) {
+        /* A required field locked by an unmet `depends_on` does not apply
+           while it is locked: it is not in "Needs attention", and an empty one
+           does not make the form incomplete either. Otherwise a check whose
+           kind is Equals could never be saved, because Minimum — required for
+           Between alone — is empty; and a form whose only gaps are fields
+           nobody can fill in would say Incomplete with nothing to act on. A
+           locked field that still HOLDS a value is validated as before. */
+        if (
+          isEmpty &&
+          ((!isRequired && !hasRequiredGroups) || dependencyLockedNames.includes(optionName))
+        ) {
           validation = { isValid: true, reasons: [] };
         } else {
           validation = validateFieldWithResult(getType(type), optionValue, {
@@ -2404,6 +2422,7 @@ const FormEngineImpl = ({
     JSON.stringify(options),
     JSON.stringify(operators),
     JSON.stringify(localValue.fields),
+    dependencyLockedNames,
   ]);
 
   const validityData = useMemo(() => getValidityData(), [getValidityData]);
@@ -2487,7 +2506,14 @@ const FormEngineImpl = ({
       // sub-form it summarises said 0/3 set.
       const empty = isOptionValueEmpty(value) || isUnsetSchemaHash(value, schema);
       const reqGroups = (schema?.required_groups as string[] | undefined) || [];
-      const required = !!(schema?.required || reqGroups.length);
+      // Required only while it applies. A field locked by an unmet `depends_on`
+      // renders disabled with what unlocks it; nothing the author can do to it
+      // is a next step — the next step is the field it depends on, which carries
+      // its own status. Counting it here put a guided check's locked Path /
+      // Minimum / Maximum under "Needs attention" before its kind was even
+      // picked. The moment the dependency holds, it is required again.
+      const required =
+        !dependencyLockedNames.includes(name) && !!(schema?.required || reqGroups.length);
       const covered =
         empty &&
         reqGroups.some((g) => {
@@ -2512,11 +2538,15 @@ const FormEngineImpl = ({
       isOptionValid,
       requiredGroupsInfo,
       schemaMsgIntent,
+      dependencyLockedNames,
     ]
   );
   const getOptionBucket = useCallback(
     (name: string, hidden = false): 'attention' | 'set' | 'optional' => {
-      if (!hidden) {
+      // A locked one-of member cannot be the one that satisfies its group, so it
+      // does not travel with the group into "Needs attention"; its own status
+      // (not required while locked) decides its box.
+      if (!hidden && !dependencyLockedNames.includes(name)) {
         const reqGroups = (options?.[name]?.required_groups as string[] | undefined) || [];
         if (reqGroups.length) {
           return reqGroups.some((g) => !requiredGroupsInfo.satisfiedBy[g]) ? 'attention' : 'set';
@@ -2524,7 +2554,7 @@ const FormEngineImpl = ({
       }
       return getReadFirstBucket(getOptionStatus(name, hidden));
     },
-    [JSON.stringify(options), requiredGroupsInfo, getOptionStatus]
+    [JSON.stringify(options), requiredGroupsInfo, getOptionStatus, dependencyLockedNames]
   );
   // How many fields are in the "Needs attention" box — drives the header link.
   const readFirstAttentionCount = useMemo(

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

@@ -358,6 +358,9 @@ export const getOptionFieldMessages = ({
 }: IOptionFieldMessagesProps): IReqoreTagProps[] => {
   const optionSchema = schema[name];
   const result: IReqoreTagProps[] = [];
+  const locked =
+    !!optionSchema?.depends_on &&
+    !hasAllDependenciesFullfilled(optionSchema.depends_on, allOptions, schema);
 
   if (option.value || option.value === false || option.value === 0 || option.value === null) {
     /* A concrete type the VALUE carries beats an untyped schema.
@@ -392,7 +395,9 @@ export const getOptionFieldMessages = ({
       });
     }
   } else {
-    if (optionSchema?.required && !untouched) {
+    // A locked field is not asked for: the dependency message below says what
+    // unlocks it, and until then there is nothing to fill in.
+    if (optionSchema?.required && !untouched && !locked) {
       result.push({ label: 'This field is required', intent: 'danger' });
     }
 
@@ -413,10 +418,7 @@ export const getOptionFieldMessages = ({
     }
   }
 
-  if (
-    optionSchema?.depends_on &&
-    !hasAllDependenciesFullfilled(optionSchema.depends_on, allOptions, schema)
-  ) {
+  if (locked) {
     const dependsOn = describeDependencies(optionSchema.depends_on, schema);
 
     result.push({

package/src/components/form/engine/variants/VariantCalmTable.tsx

@@ -112,7 +112,9 @@ const Meter = ({ form }: { form: TVariantForm }) => {
             color: (s.attention ? c.warning : c.success) as never,
           }}
         >
-          {s.attention ? 'Draft' : 'Ready'}
+          {/* What the form lacks, not whether it has unsaved changes:
+              "Draft" is the batched mode's per-row chip alone. */}
+          {s.attention ? 'Incomplete' : 'Ready'}
         </ReqoreP>
         <span>
           {s.set} of {s.total} set

package/src/components/form/engine/variants/variantModel.ts

@@ -20,6 +20,7 @@ import {
   isOptionValueEmpty,
 } from '../readFirst';
 import { isValueTemplate } from '../../../../helpers/templates';
+import { hasAllDependenciesFullfilled } from '../../../../helpers/validations';
 
 export type TVariantStatus =
   | 'set' // has a valid value
@@ -153,8 +154,13 @@ export function buildVariantGroups(
     const empty = isOptionValueEmpty(field?.value);
     const ownGroups: string[] = schema?.required_groups || [];
     // Member of a one-of group that nobody has satisfied yet.
-    const inUnmetGroup = ownGroups.some((k) => reqGroups[k] && !reqGroups[k].satisfied);
-    const required = !!schema?.required;
+    // A field locked by an unmet `depends_on` does not apply yet, so it is
+    // neither required nor part of an unmet group — the engine's rule.
+    const locked =
+      !!schema?.depends_on && !hasAllDependenciesFullfilled(schema.depends_on, values, options);
+    const inUnmetGroup =
+      !locked && ownGroups.some((k) => reqGroups[k] && !reqGroups[k].satisfied);
+    const required = !locked && !!schema?.required;
 
     let status: TVariantStatus;
     let reason: string | undefined;
@@ -183,7 +189,8 @@ export function buildVariantGroups(
       label: (schema?.display_name as string) || name,
       shortDesc: schema?.short_desc,
       longDesc: schema?.desc,
-      required: required || ownGroups.length > 0,
+      // The asterisk still marks it: it is required once it applies.
+      required: !!schema?.required || ownGroups.length > 0,
       readOnly: !!schema?.readonly,
       status,
       reason,

package/src/components/form/fields/array/ArrayAuto.tsx

@@ -17,9 +17,10 @@ import {
   ReqoreVerticalSpacer,
   useReqoreProperty,
 } from '@qoretechnologies/reqore';
-import { map, size } from 'lodash';
+import { isEqual, map, size } from 'lodash';
 import { useEffect, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { validateFieldWithResult } from '../../../../helpers/validations';
 import { useWhyDidYouUpdate } from '../../../../hooks/useWhyDidYouUpdate';
 // Direct imports — the cycle (ArrayAuto → TemplateField/auto → ArrayAuto) is
@@ -81,12 +82,20 @@ export const ArrayAuto = ({
     ...rest,
   });
 
+  // The parent's echo of an emit still in flight is not a change: copying it
+  // over the local list lost what was edited since. See `EmittedValues`.
+  const emitted = useEmittedValues<unknown>(isEqual);
+
   useEffect(() => {
+    if (emitted.isEcho(value)) {
+      return;
+    }
     setLocalValue(value);
   }, [JSON.stringify(value)]);
 
   useDebounce(
     () => {
+      emitted.record(localValue);
       onChange?.(name, localValue);
     },
     300,

package/src/components/form/fields/array/ArrayAutoField.tsx

@@ -8,10 +8,11 @@ import {
   useReqoreProperty,
 } from '@qoretechnologies/reqore';
 import { IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
-import { map, size } from 'lodash';
+import { isEqual, map, size } from 'lodash';
 import { recordIdentity } from '../../engine/readFirst';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { validateFieldWithResult } from '../../../../helpers/validations';
 
 export interface IArrayAutoFieldProps {
@@ -77,12 +78,20 @@ export const ArrayAutoField = memo(
     const [editingIndex, setEditingIndex] = useState<number | null>(null);
     const inputKeyRef = useRef(0);
 
+    // The parent's echo of an emit still in flight is not a change: copying it
+    // over the local list lost what was edited since. See `EmittedValues`.
+    const emitted = useEmittedValues<unknown>(isEqual);
+
     useEffect(() => {
+      if (emitted.isEcho(value)) {
+        return;
+      }
       setLocalValue(value);
     }, [JSON.stringify(value)]);
 
     useDebounce(
       () => {
+        emitted.record(localValue);
         onChange(name, localValue);
       },
       300,

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

@@ -2,6 +2,7 @@ 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 { useEmittedValues } from '../emittedValues';
 import { IFileFormFieldValue, ReqraftFileFormField } from '../file/File';
 
 export interface IReqraftBinaryFormFieldProps extends Omit<IReqoreTextareaProps, 'onChange' | 'value'> {
@@ -28,8 +29,14 @@ const stripDataUrlPrefix = (dataUrl: string): string => {
 export const ReqraftBinaryFormField = memo(
   ({ value, onChange, ...rest }: IReqraftBinaryFormFieldProps) => {
     const [localValue, setLocalValue] = useState<string>(value ?? '');
+    // The parent's echo of an emit still in flight is not a change: copying it
+    // over the local value lost what was typed since. See `EmittedValues`.
+    const emitted = useEmittedValues<string | undefined>();
 
     useEffect(() => {
+      if (emitted.isEcho(value)) {
+        return;
+      }
       if (value !== localValue) {
         setLocalValue(value ?? '');
       }
@@ -38,6 +45,7 @@ export const ReqraftBinaryFormField = memo(
     useDebounce(
       () => {
         if (localValue !== value) {
+          emitted.record(localValue);
           onChange?.(localValue);
         }
       },
@@ -53,6 +61,7 @@ export const ReqraftBinaryFormField = memo(
       (file?: IFileFormFieldValue) => {
         const base64 = stripDataUrlPrefix(file?.content ?? '');
         setLocalValue(base64);
+        emitted.record(base64);
         onChange?.(base64);
       },
       [onChange]
@@ -67,6 +76,7 @@ export const ReqraftBinaryFormField = memo(
           onChange={handleChange}
           onClearClick={() => {
             setLocalValue('');
+            emitted.record('');
             onChange?.('');
           }}
           placeholder='Base64-encoded binary value'

package/src/components/form/fields/emittedValues.ts

@@ -0,0 +1,62 @@
+import { useRef } from 'react';
+
+/**
+ * What a debounced field has told its parent and not yet heard back.
+ *
+ * A field that keeps a local copy of what is being typed reports it after a
+ * short pause, and the parent hands that value back down as the `value` prop —
+ * usually after its OWN debounce, so the echo of an emit arrives while the
+ * person is already typing the next character. Treating every incoming value
+ * as an external change copied that stale echo over the newer text: typing
+ * "ship-order" with 150 ms between keys left "shp-order".
+ *
+ * So an incoming value is first checked against what is in flight. One that
+ * matches an emit is the parent catching up, not a change, and it acknowledges
+ * that emit and every one before it (a parent that debounces skips some).
+ * Anything else is a genuine change from outside and replaces the local text;
+ * it also drops whatever was in flight, since the parent has moved past it.
+ *
+ * A genuine external change that happens to equal an emit still in flight is
+ * indistinguishable from its echo, and is treated as one — harmless, because it
+ * sets the very value the field already reported.
+ */
+export class EmittedValues<T> {
+  private pending: T[] = [];
+
+  /** Bounded: a parent that never feeds its value back never acknowledges. */
+  private static readonly LIMIT = 50;
+
+  constructor(private readonly equals: (a: T, b: T) => boolean = Object.is) {}
+
+  /** Record a value just reported to the parent. */
+  record(value: T): void {
+    this.pending.push(value);
+    if (this.pending.length > EmittedValues.LIMIT) {
+      this.pending.shift();
+    }
+  }
+
+  /**
+   * Whether `incoming` is the echo of an emit still in flight. An echo
+   * acknowledges that emit and every earlier one; anything else clears the
+   * in-flight list, because the parent has a value of its own.
+   */
+  isEcho(incoming: T): boolean {
+    const index = this.pending.findIndex((value) => this.equals(value, incoming));
+    if (index === -1) {
+      this.pending = [];
+      return false;
+    }
+    this.pending = this.pending.slice(index + 1);
+    return true;
+  }
+}
+
+/** One `EmittedValues` for the life of the component. */
+export const useEmittedValues = <T>(equals?: (a: T, b: T) => boolean): EmittedValues<T> => {
+  const ref = useRef<EmittedValues<T>>();
+  if (!ref.current) {
+    ref.current = new EmittedValues<T>(equals);
+  }
+  return ref.current;
+};

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

@@ -7,6 +7,7 @@ import {
   hasLineBreak,
   isSingleLineStringType,
 } from '../../../../helpers/singleLineString';
+import { useEmittedValues } from '../emittedValues';
 
 export interface ILongStringFormFieldProps extends Omit<IReqoreTextareaProps, 'onChange'> {
   value?: string;
@@ -38,24 +39,41 @@ export const LongStringFormField = ({
      and reporting that difference marked every form holding an empty text
      field as changed before anyone typed. */
   const lastEmittedRef = useRef<string>(value ?? '');
+  /* The emits the parent has not handed back yet. Its echo of an earlier one
+     arrives while the next keys are being typed, and copying it over the text
+     lost them ("ship-order" typed 150 ms apart became "shp-order"). An echo is
+     the parent catching up, not a change; see `EmittedValues`. */
+  const emitted = useEmittedValues<string>();
+
+  const emit = useCallback(
+    (next: string) => {
+      lastEmittedRef.current = next;
+      emitted.record(next);
+      onChange?.(next);
+    },
+    [onChange, emitted]
+  );
 
   useEffect(() => {
-    if ((value ?? '') !== localValue) {
-      setLocalValue(value ?? '');
+    const incoming = value ?? '';
+    if (emitted.isEcho(incoming)) {
+      return;
+    }
+    if (incoming !== localValue) {
+      setLocalValue(incoming);
     }
     // A value from outside is not something to report back to whoever sent it.
-    lastEmittedRef.current = value ?? '';
+    lastEmittedRef.current = incoming;
   }, [value]);
 
   useDebounce(
     () => {
       if (localValue !== lastEmittedRef.current) {
-        lastEmittedRef.current = localValue;
-        onChange?.(localValue);
+        emit(localValue);
       }
     },
     100,
-    [localValue, onChange]
+    [localValue, emit]
   );
 
   const singleLine = isSingleLineStringType(type);
@@ -87,9 +105,11 @@ export const LongStringFormField = ({
 
   const handleClearClick = useCallback(() => {
     setLocalValue('');
-    onChange?.('');
+    // Reported at once, and recorded like any emit, so the debounce does not
+    // report it a second time and its echo is not mistaken for a change.
+    emit('');
     onClearClick?.();
-  }, [onChange, onClearClick]);
+  }, [emit, onClearClick]);
 
   return (
     <ReqoreTextarea

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

@@ -3,6 +3,7 @@ import { IReqoreInputProps } from '@qoretechnologies/reqore/dist/components/Inpu
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { ChangeEvent, useCallback, useEffect, useMemo, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 // Const-only usage at render time — the cycle (Number → TemplateField → Number)
 // is safe the same way Field → AutoFormField → Field is.
 import { TemplatesListProps } from '../template/TemplateField';
@@ -37,8 +38,14 @@ export const NumberFormField = ({
   ...rest
 }: INumberFormFieldProps) => {
   const [localValue, setLocalValue] = useState<number | string>(value ?? '');
+  // The parent's echo of an emit still in flight is not a change: copying it
+  // over the local value lost what was typed since. See `EmittedValues`.
+  const emitted = useEmittedValues<number | string | undefined>();
 
   useEffect(() => {
+    if (emitted.isEcho(value)) {
+      return;
+    }
     if (value !== localValue) {
       setLocalValue(value ?? '');
     }
@@ -47,6 +54,7 @@ export const NumberFormField = ({
   useDebounce(
     () => {
       if (localValue !== value) {
+        emitted.record(localValue);
         onChange?.(localValue);
       }
     },
@@ -75,6 +83,7 @@ export const NumberFormField = ({
 
   const handleResetClick = useCallback((): void => {
     setLocalValue(0);
+    emitted.record(0);
     onChange?.(0);
   }, [onChange]);
 

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

@@ -8,6 +8,7 @@ import { IReqoreTooltip } from '@qoretechnologies/reqore/dist/types/global';
 import { isEqual, size } from 'lodash';
 import { KeyboardEvent, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { flattenToSingleLine, hasLineBreak } from '../../../../helpers/singleLineString';
 import {
   renderTemplateItemDescriptions,
@@ -129,8 +130,15 @@ export const RichTextFormField = memo(({
      document from it would hand the editor a new tree on every keystroke —
      which it answers by replacing its content and moving the cursor to the end. */
   const lastTextRef = useRef(isText ? String(value ?? '') : '');
+  /* The parent's echo of an emit still in flight is not a change. It arrives
+     while the next keys are typed, and rebuilding the document from it threw
+     them away. See `EmittedValues`. */
+  const emitted = useEmittedValues<unknown>(isEqual);
 
   useEffect(() => {
+    if (emitted.isEcho(isText ? String(value ?? '') : value)) {
+      return;
+    }
     if (isText) {
       const text = String(value ?? '');
       if (text !== lastTextRef.current) {
@@ -148,11 +156,13 @@ export const RichTextFormField = memo(({
     () => {
       if (isText) {
         if (lastTextRef.current !== String(value ?? '')) {
+          emitted.record(lastTextRef.current);
           onChange?.(lastTextRef.current);
         }
         return;
       }
       if (!isEqual(localValue, value)) {
+        emitted.record(localValue);
         onChange?.(localValue);
       }
     },

package/src/components/supportTicket/InterfaceReferenceTags.stories.tsx

@@ -3,6 +3,14 @@ import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 import { StoryMeta } from '../../types';
 import { InterfaceReferenceTags } from './InterfaceReferenceTags';
 import { IInterfaceReference } from './meta';
+import {
+  STORY_APP_LOGO,
+  STORY_BROKEN_IMAGE,
+  STORY_QOG_IMAGE,
+  storyBrokenKindMark,
+  storyKindMark,
+} from './__fixtures__/kindMarks';
+import { whenImageSettled } from './useLoadedImages';
 
 // Several references, including two of the same kind (workflow), as `{kind, name}`
 // snapshots — no `resolveInterfaceIcon` is passed, so the built-in per-kind default
@@ -169,3 +177,81 @@ export const Empty: Story = {
     await expect(within(canvasElement).queryByText('order-sync:1.2')).not.toBeInTheDocument();
   },
 };
+
+const QOG_REFERENCES: IInterfaceReference[] = [
+  { interface_kind: 'fsm', interface_name: 'order-flow', reference_id: 'q1' },
+  {
+    interface_kind: 'fsm',
+    interface_name: 'telegram-intake',
+    reference_id: 'q2',
+    logo: STORY_APP_LOGO,
+  },
+  { interface_kind: 'service', interface_name: 'notification-svc', reference_id: 'q3' },
+];
+
+const chipImages = (canvasElement: HTMLElement) =>
+  Array.from(canvasElement.querySelectorAll('.reqore-tag img')).map((img) =>
+    img.getAttribute('src')
+  );
+
+export const KindImage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders references with a host resolver that gives a Qog an image (the green mark) and a font icon fallback. The plain Qog shows the image; the app-triggered Qog keeps its stored trigger-app logo, because by default a reference's own logo comes first; the service has no image and shows its font icon.",
+      },
+    },
+  },
+  args: { references: QOG_REFERENCES, resolveInterfaceIcon: storyKindMark },
+  async play({ canvasElement }) {
+    await waitFor(() =>
+      expect(chipImages(canvasElement).sort()).toEqual([STORY_APP_LOGO, STORY_QOG_IMAGE].sort())
+    );
+  },
+};
+
+export const KindImagePreferred: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the same references with preferKindImage: the kind image comes before a reference\'s own logo, so both Qogs show the green Qog mark and the service keeps its font icon.',
+      },
+    },
+  },
+  args: {
+    references: QOG_REFERENCES,
+    resolveInterfaceIcon: storyKindMark,
+    preferKindImage: true,
+  },
+  async play({ canvasElement }) {
+    await waitFor(() =>
+      expect(chipImages(canvasElement)).toEqual([STORY_QOG_IMAGE, STORY_QOG_IMAGE])
+    );
+  },
+};
+
+export const KindImageFailsToLoad: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a Qog reference whose kind image cannot load: the chip keeps the font icon instead of drawing a broken picture.',
+      },
+    },
+  },
+  args: {
+    references: [QOG_REFERENCES[0]],
+    resolveInterfaceIcon: storyBrokenKindMark,
+    preferKindImage: true,
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('order-flow')).toBeInTheDocument();
+    // Once the load has failed, no picture is drawn.
+    await whenImageSettled(STORY_BROKEN_IMAGE);
+    await expect(chipImages(canvasElement)).toEqual([]);
+    await expect(canvasElement.querySelector('.reqore-tag .reqore-icon')).toBeTruthy();
+  },
+};