From fa0b2bae2435864fadeeb23f617270f51a321cb5 Mon Sep 17 00:00:00 2001
From: Maxim Palenov <maxim.palenov@elastic.co>
Date: Thu, 5 Dec 2024 14:06:11 +0100
Subject: [PATCH] improve description comment

---
 .../use_form_with_warn/use_form_with_warn.ts  | 33 +++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/x-pack/plugins/security_solution/public/common/hooks/use_form_with_warn/use_form_with_warn.ts b/x-pack/plugins/security_solution/public/common/hooks/use_form_with_warn/use_form_with_warn.ts
index cefcc86aeb4a7..5feb43fd52127 100644
--- a/x-pack/plugins/security_solution/public/common/hooks/use_form_with_warn/use_form_with_warn.ts
+++ b/x-pack/plugins/security_solution/public/common/hooks/use_form_with_warn/use_form_with_warn.ts
@@ -32,12 +32,41 @@ interface UseFormWithWarnReturn<T extends FormData = FormData, I extends FormDat
 }
 
 /**
+ * Form lib implements warning functionality via non blocking validators. `validations` allows to
+ * specify validation configuration with validator functions and extra parameters including
+ * `isBlocking`. Validators marked as `isBlocking` will produce non blocking validation errors
+ * a.k.a. warnings.
+ *
+ * The problem with the supported approach is lack of flexibility and necessary API like one for getting
+ * only blocking or non blocking errors. Flexibility requirement comes from complex async validators
+ * producing blocking and non blocking validation errors. There is no way to use `isBlocking` configuration
+ * option to separate errors. Separating such validating functions in two would lead to sending two
+ * HTTP requests and performing another async operations twice.
+ *
+ * On top of just having an ability to mark validation errors as non blocking via `isBlocking: false`
+ * configuration we require a way to return blocking and non blocking errors from a single validation
+ * function. It'd be possible by returning an error with `isBlocking` (or `isWarning`) flag along with
+ * `message` and `code` fields from a validator function. Attempts to reuse `__isBlocking__` internal
+ * field lead to inconsistent behavior.
+ *
+ * `useFormWithWarn` implements warnings (non blocking errors) on top of `FormHook` using validation
+ * error codes as a flexible way to determine whether an error is a blocking error or it's a warning.
+ * It provides little interface extension to simplify errors and warnings consumption
+ *
  * In some cases business logic requires implementing functionality to allow users perform an action
  * despite non-critical validation errors a.k.a. warnings. Usually it's also required to inform users
  * about warnings they got before proceeding for example via a modal.
  *
- * Since `FormHook` returned by `useForm` lacks of such functionality. `useFormWithWarn` is here to
- * provide warnings functionality. Besides that it it's replaceable with `useForm`.
+ * Since `FormHook` returned by `useForm` lacks of such functionality `useFormWithWarn` is here to
+ * provide warnings functionality. It could be used and passed as `FormHook` when warnings functionality
+ * isn't required making absolutely transparent.
+ *
+ * **Important:** Validators use short circuiting by default. It means that any failed validation in
+ * `validations` configuration array will prevent the rest validators from running. When used with warnings
+ * it may lead to bugs when validator checks first for warnings. You have to make sure a value is validated
+ * for errors first and then for warnings.
+ *
+ * There is a ticket to move this functionality to Form lib https://github.com/elastic/kibana/issues/203097.
  */
 export function useFormWithWarn<T extends FormData = FormData, I extends FormData = T>(
   formConfig: FormWithWarnConfig<T, I>