added docs

x-pack/plugins/triggers_actions_ui/README.md

@@ -25,6 +25,7 @@ Table of Contents
       - [GROUPED BY expression component](#grouped-by-expression-component)
       - [FOR THE LAST expression component](#for-the-last-expression-component)
       - [THRESHOLD expression component](#threshold-expression-component)
+    - [Alert Conditions Components](#alert-conditions-components)
     - [Embed the Create Alert flyout within any Kibana plugin](#embed-the-create-alert-flyout-within-any-kibana-plugin)
   - [Build and register Action Types](#build-and-register-action-types)
     - [Built-in Action Types](#built-in-action-types)
@@ -634,6 +635,155 @@ interface ThresholdExpressionProps {
 |customComparators|(Optional) List of comparators that replaces the default options defined in constants `x-pack/plugins/triggers_actions_ui/public/common/constants/comparators.ts`.|
 |popupPosition|(Optional) expression popup position. Default is `downLeft`. Recommend changing it for a small parent window space.|
 
+## Alert Conditions Components
+To aid in creating a uniform UX across Alert Types, we provide two components for specifying the conditions for detection of a certain alert under within any specific Action Groups:
+1. `AlertConditions`: A component that generates a container which renders custom component for each Action Group which has had its _conditions_ specified.
+2. `AlertConditionsGroup`: A component that provides a unified container for the Action Group with its name and a button for resetting its condition.
+
+These can be used by any Alert Type to easily create the UI for adding action groups along with an Alert Type specific component.
+
+For Example:
+Given an Alert Type which requires different thresholds for each detected Action Group (for example), you might have a `ThresholdSpecifier` component for specifying the threshold for a specific Action Group.
+
+```
+const ThresholdSpecifier = (
+  {
+    actionGroup,
+    setThreshold
+  } : {
+    actionGroup?: ActionGroupWithCondition<number>;
+    setThreshold: (actionGroup: ActionGroupWithCondition<number>) => void;
+}) => {
+  if (!actionGroup) {
+    // render empty if no condition action group is specified
+    return <Fragment />;
+  }
+
+  return (
+    <EuiFieldNumber
+      value={actionGroup.conditions}
+      onChange={(e) => {
+        const conditions = parseInt(e.target.value, 10);
+        if (e.target.value && !isNaN(conditions)) {
+          setThreshold({
+            ...actionGroup,
+            conditions,
+          });
+        }
+      }}
+    />
+  );
+};
+
+```
+
+This component takes two props, one which is required (`actionGroup`) and one which is alert type specific (`setThreshold`).
+The `actionGroup` will be populated by the `AlertConditions` component, but `setThreshold` will have to be provided by the AlertType itself.
+
+To understand how this is used, lets take a closer look at `actionGroup`:
+
+```
+type ActionGroupWithCondition<T> = ActionGroup &
+  (
+    | // allow isRequired=false with or without conditions
+    {
+        conditions?: T;
+        isRequired?: false;
+      }
+    // but if isRequired=true then conditions must be specified
+    | {
+        conditions: T;
+        isRequired: true;
+      }
+  )
+```
+
+The `condition` field is Alert Type specific, and holds whichever type an Alert Type needs for specifying the condition under which a certain detection falls under that specific Action Group.
+In our example, this is a `number` as that's all we need to speciufy the threshold which dictates whether an alert falls into one actio ngroup rather than another.
+
+The `isRequired` field specifies whether this specific action group is _required_, that is, you can't reset its condition and _have_ to specify a some condition for it.
+
+Using this `ThresholdSpecifier` component, we can now use `AlertConditionsGroup` & `AlertConditions` to enable the user to specify these thresholds for each action group in the alert type.
+
+Like so:
+```
+interface ThresholdAlertTypeParams {
+  thresholds?: {
+    alert?: number;
+    warning?: number;
+    error?: number;
+  };
+}
+
+const DEFAULT_THRESHOLDS: ThresholdAlertTypeParams['threshold] = {
+  alert: 50,
+  warning: 80,
+  error: 90,
+};
+```
+
+```
+<AlertConditions
+  headline={'Set different thresholds for each level'}
+  actionGroups={[
+    {
+      id: 'alert',
+      name: 'Alert',
+      condition: DEFAULT_THRESHOLD
+    },
+    {
+      id: 'warning',
+      name: 'Warning',
+    },
+    {
+      id: 'error',
+      name: 'Error',
+    },
+  ]}
+  onInitializeConditionsFor={(actionGroup) => {
+    setAlertParams('thresholds', {
+      ...thresholds,
+      ...pick(DEFAULT_THRESHOLDS, actionGroup.id),
+    });
+  }}
+>
+  <AlertConditionsGroup
+    onResetConditionsFor={(actionGroup) => {
+      setAlertParams('thresholds', omit(thresholds, actionGroup.id));
+    }}
+  >
+    <TShirtSelector
+      setTShirtThreshold={(actionGroup) => {
+        setAlertParams('thresholds', {
+          ...thresholds,
+          [actionGroup.id]: actionGroup.conditions,
+        });
+      }}
+    />
+  </AlertConditionsGroup>
+</AlertConditions>
+```
+
+### The AlertConditions component 
+
+This component will render the `Conditions` header & headline, along with the selectors for adding every Action Group you specity.
+Additionally it will clone its `children` for _each_ action group which has a `condition` specified for it, passing in the appropriate `actionGroup` prop for each one.
+
+|Property|Description|
+|---|---|
+|headline|The headline title displayed above the fields |
+|actionGroups|A list of `ActionGroupWithCondition` which includes all the action group you wish to offer the user and what conditions they are already configured to follow|
+|onInitializeConditionsFor|A callback which is called when the user ask for a certain actionGroup to be initialized with an initial default condition. If you have no specific default, that's fine, as the component will render the action group's field even if the condition is empty (using a `null` or an `undefined`) and determines whether to render these fields by _the very presence_ of a `condition` field|
+
+### The AlertConditionsGroup component 
+
+This component renders a standard EuiTitle foe each action group, wrapping the Alert Type specific component, in addition to a "reset" button which allows the user to reset the condition for that action group. The definition of what a _reset_ actually means is Alert Type specific, and up to the implementor to decide. In some case it might mean removing the condition, in others it might mean to reset it to some default value on the server side. In either case, it should _delete_ the `condition` field from the appropriate `actionGroup` as per the above example.
+
+|Property|Description|
+|---|---|
+|onResetConditionsFor|A callback which is called when the user clicks the _reset_ button besides the action group's title. The implementor should use this to remove the `condition` from the specified actionGroup|
+
+
 ## Embed the Create Alert flyout within any Kibana plugin
 
 Follow the instructions bellow to embed the Create Alert flyout within any Kibana plugin: