feat(orchestrator): add 'fetch:response:mandatory selector for ActiveMultiSelect (#1009)

Signed-off-by: Marek Libra <marek.libra@gmail.com>

Author: mareklibra

workspaces/orchestrator/.changeset/lucky-boxes-float.md

@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-orchestrator-form-widgets': patch
+---
+
+Added "fetch:response:mandatory" selector for the ActiveMultiSelect widget.

workspaces/orchestrator/docs/orchestratorFormWidgets.md

@@ -15,12 +15,7 @@ Key Differentiators:
   - Provide default data or option lists.
   - Handle complex validation logic for widgets.
 
-Implementation of the HTTP endpoints is out of the scope of this library.
-
-Deployment Considerations:
-
-- Use one or multiple servers depending on organizational needs.
-- Ensure endpoint structures and response formats exactly match the naming conventions and data structures defined in your schema’s `ui:props` by the creator of workflow's `data input schema`.
+Implementation of the HTTP endpoints is out of the scope of this library, they are expected to be custom developed to match rules and data sources of target environment.
 
 ## Content
 
@@ -29,13 +24,19 @@ The frontend plugin provides implementation of `OrchestratorFormApi` (for `orche
 ## Context
 
 The provided widgets enable forms to incorporate dynamically retrieved data.
+
 This data can be fetched from external HTTP servers, the Backstage API, as well as from other form fields, with all evaluations performed in real time during use.
 
+## Deployment considerations
+
+- Use one or multiple servers depending on organizational needs.
+- Ensure endpoint structures and response formats exactly match the naming conventions and data structures defined in your schema’s `ui:props` by the creator of workflow's `data input schema`.
+
 ## SchemaUpdater widget
 
 Referenced as: `"ui:widget": "SchemaUpdater"`.
 
-A headless widget used for fetching snippets of JSON schema and dynamically updating the RJSF form JSON schema on the fly.
+A **headless** widget used for fetching snippets of JSON schema and dynamically updating the RJSF form JSON schema on the fly.
 
 Thanks to this component, complex subparts of the form can be changed based on data entered in other fields by the user.
 
@@ -163,6 +164,12 @@ For the schema:
 }
 ```
 
+### Default mandatory data
+
+When the optional `fetch:response:mandatory` JSONata selector is provided, it must return an array of strings that act as default values, which the user can not unselect.
+
+Together with `fetch:retrigger` and other fetch-related parameters, the endpoint can continuously update the data for the selector.
+
 ### SchemaUpdater widget ui:props
 
 The widget supports following `ui:props`:
@@ -172,6 +179,7 @@ The widget supports following `ui:props`:
 - fetch:method
 - fetch:body
 - fetch:response:value
+- fetch:response:mandatory
 - fetch:retrigger
 
 [Check mode details](#content-of-uiprops)

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/utils/applySelector.ts

@@ -23,10 +23,15 @@ export function isJsonObject(value?: JsonValue): value is JsonObject {
 export const applySelectorArray = async (
   data: JsonObject,
   selector: string,
+  createArrayIfNeeded: boolean = false,
 ): Promise<string[]> => {
   const expression = jsonata(selector);
   const value = await expression.evaluate(data);
 
+  if (typeof value === 'string' && createArrayIfNeeded) {
+    return [value];
+  }
+
   if (Array.isArray(value) && value.every(item => typeof item === 'string')) {
     return value;
   }

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/widgets/ActiveMultiSelect.tsx

@@ -67,13 +67,15 @@ export const ActiveMultiSelect: Widget<
 
   const autocompleteSelector =
     uiProps['fetch:response:autocomplete']?.toString();
+  const mandatorySelector = uiProps['fetch:response:mandatory']?.toString();
 
   const [localError] = useState<string | undefined>(
     autocompleteSelector
       ? undefined
       : `Missing fetch:response:autocomplete selector for ${id}`,
   );
   const [autocompleteOptions, setAutocompleteOptions] = useState<string[]>();
+  const [mandatoryValues, setMandatoryValues] = useState<string[]>();
 
   const retrigger = useRetriggerEvaluate(
     templateUnitEvaluator,
@@ -97,10 +99,29 @@ export const ActiveMultiSelect: Widget<
         );
         setAutocompleteOptions(autocompleteValues);
       }
+
+      if (mandatorySelector) {
+        const mandatory = await applySelectorArray(
+          data,
+          mandatorySelector,
+          true,
+        );
+        setMandatoryValues(mandatory);
+        if (!mandatory.every(item => value.includes(item))) {
+          onChange([...new Set([...mandatory, ...value])]);
+        }
+      }
     };
 
     doItAsync();
-  }, [autocompleteSelector, data, props.id, value]);
+  }, [
+    autocompleteSelector,
+    mandatorySelector,
+    data,
+    props.id,
+    value,
+    onChange,
+  ]);
 
   const handleChange = (
     _: React.SyntheticEvent,
@@ -152,14 +173,21 @@ export const ActiveMultiSelect: Widget<
             renderTags={(values, getTagProps) =>
               values.map((item, index) => {
                 const tagProps = getTagProps({ index });
-                tagProps.className = clsx(tagProps.className, classes.chip);
+                const { className, onDelete, ...restTagProps } = tagProps;
+
                 return (
                   <Box key={item} title={item}>
                     <Chip
                       data-testid={`${id}-chip-${item}`}
                       variant="outlined"
                       label={item}
-                      {...tagProps}
+                      className={clsx(tagProps.className, classes.chip)}
+                      onDelete={
+                        mandatoryValues?.includes(item)
+                          ? undefined /* mandatory - can not be deleted */
+                          : onDelete
+                      }
+                      {...restTagProps}
                     />
                   </Box>
                 );