Add documentation for entity and device filters (#26145)

source/_docs/blueprint/selectors.markdown

@@ -115,8 +115,9 @@ area:
 device:
   description: >
     When device options are provided, the list of areas is filtered by areas
-    that at least provide one device that matches the given conditions.
+    that at least provide one device that matches the given conditions. Can be
-  type: map
+    either a object or a list of object.
+  type: list
   keys:
     integration:
       description: >
@@ -140,8 +141,9 @@ device:
 entity:
   description: >
     When entity options are provided, the list of areas is filtered by areas
-    that at least provide one entity that matches the given conditions.
+    that at least provide one entity that matches the given conditions. Can be
-  type: map
+    either a object or a list of object.
+  type: list
   required: false
   keys:
     integration:
@@ -162,8 +164,10 @@ entity:
     device_class:
       description: >
         Limits the list of areas to areas that have entities with a certain
-        device class, for example, `motion` or `window`.
+        device class(es), for example, `motion` or `window`. Can be either a string
-      type: device_class
+        with a single device_class, or a list of string device_class to limit
+        the selection to.
+      type: [device_class, list]
       required: false
 multiple:
   description: >
@@ -208,8 +212,7 @@ integration. Multiple areas can be selected.
 area:
   multiple: true
   device:
-    multiple: true
+    - integration: deconz
-    integration: deconz
       manufacturer: IKEA of Sweden
       model: TRADFRI remote control
 ```
@@ -354,28 +357,12 @@ device:
 ```
 
 {% configuration device %}
-integration:
-  description: >
-    Can be set to an integration domain. Limits the list of devices to devices
-    provided by the set integration domain.
-  type: string
-  required: false
-manufacturer:
-  description: >
-    When set, it limits the list of devices to devices provided by the set
-    manufacturer name.
-  type: string
-  required: false
-model:
-  description: >
-    When set, it limits the list of devices to devices that have the set model.
-  type: string
-  required: false
 entity:
   description: >
     When entity options are provided, the list of devices is filtered by devices
-    that at least provide one entity that matches the given conditions.
+    that at least provide one entity that matches the given conditions. Can be
-  type: map
+    either a object or a list of object.
+  type: list
   required: false
   keys:
     integration:
@@ -397,8 +384,35 @@ entity:
     device_class:
       description: >
         Limits the list of entities to entities that have a certain device
-        class, for example, `motion` or `window`.
+        class(es), for example, `motion` or `window`. Can be either a string
-      type: device_class
+        with a single device_class, or a list of string device_class to limit
+        the selection to.
+      type: [device_class, list]
+      required: false
+filter:
+  description: >
+    When filter options are provided, the list of devices is filtered by devices
+    that at least provide one entity that matches the given conditions. Can be either
+    a object or a list of object.
+  type: list
+  required: false
+  keys:
+    integration:
+      description: >
+        Can be set to an integration domain. Limits the list of devices to devices
+        provided by the set integration domain.
+      type: string
+      required: false
+    manufacturer:
+      description: >
+        When set, it limits the list of devices to devices provided by the set
+        manufacturer name.
+      type: string
+      required: false
+    model:
+      description: >
+        When set, it limits the list of devices to devices that have the set model.
+      type: string
       required: false
 multiple:
   description: >
@@ -433,11 +447,12 @@ And this is what is looks like in YAML:
 
 ```yaml
 device:
-  integration: deconz
+  filter:
+    - integration: deconz
       manufacturer: Philips
       model: RWL021  
   entity:
-    domain: sensor
+    - domain: sensor
       device_class: battery
 ```
 
@@ -499,14 +514,22 @@ include_entities:
   description: List of entity IDs to limit the selectable list to.
   type: list
   required: false
-integration:
+filter:
+  description: >
+    When filter options are provided, the entities are limited by entities
+    that at least match the given conditions. Can be either a object or a list of object.
+    Can be either a object or a list of object.
+  type: list
+  required: false
+  keys:
+    integration:
       description: >
         Can be set to an integration domain. Limits the list of entities to entities
         provided by the set integration domain, for example,
         [`zha`](/integrations/zha).
       type: string
       required: false
-domain:
+    domain:
       description: >
         Limits the list of entities to entities of a certain domain(s), for example,
         [`light`](/integrations/light) or
@@ -515,11 +538,12 @@ domain:
         to.
       type: [string, list]
       required: false
-device_class:
+    device_class:
       description: >
-    Limits the list of entities to entities that have a certain device class,
+        Limits the list of entities to entities that have a certain device class(es),
-    for example, `motion` or `window`.
+        for example, `motion` or `window`. Can be either a string with a single device_class,
-  type: device_class
+        or a list of string device_class to limit the selection to.
+      type: [device_class, list]
       required: false
 multiple:
   description: >
@@ -556,7 +580,8 @@ And this is what it looks like in YAML:
 ```yaml
 entity:
   multiple: true
-  integration: zha
+  filter:
+    - integration: zha
       domain: binary_sensor
       device_class: motion
 ```
@@ -895,8 +920,9 @@ target:
 device:
   description: >
     When device options are provided, the targets are limited by devices
-    that at least match the given conditions.
+    that at least match the given conditions. Can be either a object or a list
-  type: map
+    of object.
+  type: list
   keys:
     integration:
       description: >
@@ -918,8 +944,9 @@ device:
 entity:
   description: >
     When entity options are provided, the targets are limited by entities
-    that at least match the given conditions.
+    that at least match the given conditions. Can be either a object or a list
-  type: map
+    of object.
+  type: list
   required: false
   keys:
     integration:
@@ -940,9 +967,10 @@ entity:
       required: false
     device_class:
       description: >
-        Limits the targets to entities with a certain
+        Limits the targets to entities with a certain device class(es), for example,
-        device class, for example, `motion` or `window`.
+        `motion` or `window`. Can be either a string with a single device_class,
-      type: device_class
+        or a list of string device_class to limit the selection to.
+      type: [device_class, list]
       required: false
 {% endconfiguration %}
 
@@ -967,7 +995,7 @@ or more lights, provided by the [ZHA](/integrations/zha) integration.
 ```yaml
 target:
   entity:
-    integration: zha
+    - integration: zha
       domain: light
 ```
 
@@ -978,7 +1006,7 @@ provide one or more remote controls, provided by the
 ```yaml
 target:
   device:
-    integration: deconz
+    - integration: deconz
       manufacturer: IKEA of Sweden
       model: TRADFRI remote control
 ```