[Draft] Add documentation for Alternative selectors

source/_docs/blueprint/selectors.markdown

@@ -17,6 +17,7 @@ The following selectors are currently available:
 
 - [Action selector](#action-selector)
 - [Add-on selector](#add-on-selector)
+- [Alternative selector](#alternative-selector)
 - [Area selector](#area-selector)
 - [Attribute selector](#attribute-selector)
 - [Assist pipeline selector](#assist-pipeline-selector)
@@ -102,6 +103,133 @@ addon:
 The output of this selector is the slug of the selected add-on.
 For example: `core_ssh`.
 
+## Alternative selector
+
+_<small>See also: [Object selector](#object-selector) and [Select selector](#select-selector)</small>_
+
+The alternative selector allows choosing between multiple mutually exclusive sets of parameters. This is useful e.g. for choosing & configuring a DNS provider.
+
+```yaml
+alternative:
+  options:
+    - value: aws
+      label: Amazon Web Services (AWS)
+      fields:
+        access_key_id:
+          label: AWS Access Key ID
+          required: true
+          selector:
+            text:
+        secret_access_key:
+          label: AWS Secret Access Key
+          selector:
+            text:
+    - value: azure
+      label: Microsoft Azure
+      fields:
+        azure_config:
+          label: Azure Configuration
+          selector:
+            object: {}
+    - value: cloudflare
+      fields:
+        api_key:
+          label: Cloudflare API Key
+          selector:
+            text:
+        api_token: str?
+          label: Cloudflare API Token
+          selector:
+            text:
+        email:
+          label: Cloudflare Email Address
+          selector:
+            text:
+```
+
+The output of this selector is a YAML object. For example, given the configuration above, one possible output would look like this:
+
+```yaml
+aws:
+  access_key_id: "abc"
+  secret_access_key: "def"
+```
+
+When a `discriminator_field` is specified, the output would look this instead:
+
+```yaml
+# Modified schema:
+#
+# alternative:
+#   discriminator_field: provider
+#   options:
+#     aws: { ... }
+#     azure: { ... }
+#     cloudflare: { ... }
+provider: aws
+access_key_id: "abc"
+secret_access_key: "def"
+```
+
+{% configuration alternative %}
+options:
+  description: >
+    List of mutually exclusive options.
+  type: list
+  required: true
+  keys:
+    value:
+      description: The key of the option.
+      required: true
+      type: string
+    label:
+      description: The label of the option.
+      required: false
+      type: string
+    fields:
+      description: >
+        List of fields for this option.
+      type: map
+      required: false
+      keys:
+        label:
+          description: The label of the field.
+          required: false
+          type: string
+        selector:
+          description: The selector to use for this field. It can be any available selector.
+          required: true
+          type: string
+discriminator_field:
+  description: >
+    The field to use as the discriminator, for example `type` or `action`. If not set,
+    the value will instead be wrapped in a dict whose single key is used as the discriminator.
+  type: string
+  required: false
+multiple:
+  description: >
+    Allows adding multiple objects. If set to `true`, the resulting value
+    of this selector will be a list instead of a single map value.
+  type: boolean
+  required: false
+  default: false
+translation_key:
+  description: >
+    Allows translations provided by an integration where `translation_key`
+    is the translation key that is providing the selector option strings
+    translation. See the documentation on
+    [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors)
+    for more information.
+  type: string
+  required: false
+sort:
+  description: >
+    Display options in alphabetical order.
+  type: boolean
+  required: false
+  default: false
+{% endconfiguration %}
+
 ## Area selector
 
 The area selector shows an area finder that can pick a single or multiple areas
@@ -1187,6 +1315,8 @@ number:
 
 ## Object selector
 
+_<small>See also: [Alternative selector](#alternative-selector)</small>_
+
 The object selector can be used to input arbitrary data in YAML form. This is useful for e.g. lists and dictionaries containing data for actions. The value of the input will contain the provided data.
 
 When used without options, the selector will accept a free form object.
@@ -1312,6 +1442,8 @@ The output of this selector is a list with the three (RGB) color value, for exam
 
 ## Select selector
 
+_<small>See also: [Alternative selector](#alternative-selector)</small>_
+
 The select selector shows a list of available options from which the user can choose. The value of the input contains the value of the selected option. Only a single option can be selected at a time.
 
 ![Screenshot of a select selector](/images/blueprints/selector-select.png)