Refactor threshold trigger and condition docs into shared includes

source/_conditions/humidity.is_value.markdown

@@ -13,38 +13,16 @@ When you target more than one entity, the condition's **Condition passes if** op
 
 {% include conditions/ui_header.md %}
 
-To use **Relative humidity** in an automation:
-
-1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}.
-2. Open an existing automation, or select **Create automation** > **Create new automation**.
-3. In the **And if** section, select **Add condition**.
-4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your humidity sensor is in (like your bedroom or bathroom). You can also select a device, a specific entity, or a label.
-5. From the conditions shown for that target, select **Relative humidity**.
-6. Under **Threshold type**, set the humidity level the condition checks against:
-   1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold.
-   2. Select **Number** or **Entity**:
-      - **Number**: Enter a fixed percentage directly, for example `65` for 65%. For **In range** or **Outside range**, enter both a lower and upper bound.
-      - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold:
-        - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value.
-        - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes. This is useful for comparing two humidity readings, for example to check whether indoor humidity is higher than outdoor humidity.
-        - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers).
-        - If you don't have a number helper, you can create one by selecting **Create a new number helper**.
-7. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**.
-8. Select **Save**.
+{% include conditions/threshold_value_steps.md
+   title="Relative humidity"
+   sensor="humidity sensor"
+   areas="bedroom or bathroom"
+   value_long="a fixed percentage directly, for example `65` for 65%" %}
 
 ### Options in the UI
 
-{% options_ui %}
-Threshold type:
-  description: |
-    The humidity level the entity has to meet for the condition to pass. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter a fixed percentage (0–100), or **Entity** to use a sensor or number helper as a dynamic threshold.
-Condition passes if:
-  description: |
-    When multiple entities are targeted, controls how results combine:
-
-    - **Any**: The condition passes if at least one targeted entity meets the threshold (default).
-    - **All**: The condition passes only when every targeted entity meets the threshold.
-{% endoptions_ui %}
+{% include conditions/threshold_value_options_ui.md
+   value_short="a fixed percentage (0–100)" %}
 
 {% include conditions/yaml_header.md %}
 
@@ -140,29 +118,9 @@ This passes when the bedroom humidity sensor reads above the number helper´s va
 
 ### Options in YAML
 
-{% options_yaml %}
-threshold:
-  description: |
-    The humidity level the entity has to meet for the condition to pass:
-
-    - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass. Provide `value` with a `number` key (0–100) or an `entity` key.
-    - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass. Provide `value` with a `number` key (0–100) or an `entity` key.
-    - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass. Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.
-    - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass. Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.
-
-    For the `number` key, use a percentage value (0–100). For the `entity` key, use an `input_number`, `number`, or `sensor` entity.
-  required: false
-  type: map
-behavior:
-  description: |
-    When multiple entities are targeted, controls how results combine:
-
-    - `any`: The condition passes if at least one targeted entity meets the threshold.
-    - `all`: The condition passes only when every targeted entity meets the threshold.
-  required: false
-  type: string
-  default: any
-{% endoptions_yaml %}
+{% include conditions/threshold_value_options_yaml.md
+   range_note="0–100"
+   number_final="a percentage value (0–100)" %}
 
 {% include conditions/targets.md %}
 

source/_conditions/temperature.is_value.markdown

@@ -13,38 +13,23 @@ When you target more than one entity, the condition's **Condition passes if** op
 
 {% include conditions/ui_header.md %}
 
-To use **Temperature** in an automation:
-
-1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}.
-2. Open an existing automation, or select **Create automation** > **Create new automation**.
-3. In the **And if** section, select **Add condition**.
-4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your temperature sensor is in (like your bedroom or living room). You can also select a device, a specific entity, or a label.
-5. From the conditions shown for that target, select **Temperature value**.
-6. Under **Threshold type**, set the temperature level the condition checks against:
-   1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold.
-   2. Select **Number** or **Entity**:
-      - **Number**: Enter a fixed temperature directly, for example `20` for 20°C. For **In range** or **Outside range**, enter both a lower and upper bound.
-      - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold:
-        - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value.
-        - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes. This is useful for comparing two temperature readings, for example to check whether indoor temperature is higher than outdoor temperature.
-        - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers).
-        - If you don't have a number helper, you can create one by selecting **Create a new number helper**.
-7. Under **Unit**, select the temperature unit (°C or °F) to use for the threshold comparison.
-8. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**.
-9. Select **Save**.
+{% include conditions/threshold_value_steps.md
+   title="Temperature value"
+   sensor="temperature sensor"
+   areas="bedroom or living room"
+   value_long="a fixed temperature directly, for example `20` for 20°C"
+   has_unit="true"
+   unit_label="temperature unit"
+   unit_options="°C or °F" %}
 
 ### Options in the UI
 
-{% options_ui %}
-Threshold type:
-  description: |
-    The temperature level the entity has to meet for the condition to pass. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter a fixed temperature value, or **Entity** to use a sensor or number helper as a dynamic threshold.
-Unit:
-  description: The temperature unit to use for threshold comparison. Accepts `°C` or `°F`. Required when using numerical thresholds (not required when using entity references).
-  default: °C
-Condition passes if:
-  description: When multiple entities are targeted, controls how results combine. Pick **Any** to pass if at least one targeted entity meets the threshold, or **All** to pass only when every targeted entity does. Default is **Any**.
-{% endoptions_ui %}
+{% include conditions/threshold_value_options_ui.md
+   value_short="a fixed temperature value"
+   has_unit="true"
+   unit_label="temperature unit"
+   unit_options_code="`°C` or `°F`"
+   unit_default="°C" %}
 
 {% include conditions/yaml_header.md %}
 
@@ -107,38 +92,12 @@ This passes when the living room temperature sensor reads between 20 and 22°C.
 
 ### Options in YAML
 
-{% options_yaml %}
-threshold:
-  description: |
-    The temperature level the entity has to meet for the condition to pass:
-
-    - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass.
-    - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass.
-    - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass.
-    - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass.
-
-    For `type: above` and `type: below`, use `value` with either `number` and `unit_of_measurement`, or `entity`. For `type: between` and `type: outside`, use `value_min` and `value_max`, each with either `number` and `unit_of_measurement`, or `entity`. For example:
-
-    ```yaml
-    threshold:
-      type: between
-      value_min:
-        entity: input_number.comfort_temperature_min
-      value_max:
-        number: 22
-        unit_of_measurement: °C
-    ```
-
-    When using an `entity`, its current reading is used as the threshold at the moment the condition is evaluated, which lets you compare two temperature readings dynamically.
-  required: true
-  type: map
-behavior:
-  description: >
-    Controls how results combine when multiple entities are targeted. Accepts `all` or `any`.
-  required: false
-  type: string
-  default: any
-{% endoptions_yaml %}
+{% include conditions/threshold_value_options_yaml.md
+   has_unit="true"
+   unit_default="°C"
+   unit_example_entity="input_number.comfort_temperature_min"
+   unit_example_value="22"
+   threshold_required="true" %}
 
 {% include conditions/targets.md %}
 

source/_includes/conditions/threshold_value_options_ui.md

@@ -0,0 +1,28 @@
+{% comment %}
+Reusable "Options in the UI" block for entity conditions that test a reading
+against the threshold-mapping schema.
+
+Parameters:
+  value_short        Number-entry phrasing. For example: "a fixed percentage (0–100)".
+  has_unit           Set (to anything) to add a "Unit" row. Requires unit_label,
+                     unit_options_code, and unit_default.
+  unit_label         Unit label. For example: "temperature unit", "energy unit".
+  unit_options_code  Inline code list of allowed units. For example: "`°C` or `°F`".
+  unit_default       Default unit. For example: "°C"
+{% endcomment %}
+{% options_ui %}
+Threshold type:
+  description: |
+    The threshold the entity's reading is compared against. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter {{ include.value_short }}, or **Entity** to use a sensor or number helper as a dynamic threshold.
+{% if include.has_unit %}
+Unit:
+  description: The {{ include.unit_label }} to use for threshold comparison. Accepts {{ include.unit_options_code }}. Required when using numerical thresholds (not required when using entity references).
+  default: {{ include.unit_default }}
+{% endif %}
+Condition passes if:
+  description: |
+    When multiple entities are targeted, controls how results combine:
+
+    - **Any**: The condition passes if at least one targeted entity meets the threshold (default).
+    - **All**: The condition passes only when every targeted entity meets the threshold.
+{% endoptions_ui %}

source/_includes/conditions/threshold_value_options_yaml.md

@@ -0,0 +1,58 @@
+{% comment %}
+Reusable "Options in YAML" block for entity conditions that test a reading
+against the threshold-mapping schema. The `behavior` description is shared
+across the family. Unitless members (humidity, brightness, counter) get the
+per-type "Provide value..." guidance; members with a unit (temperature, energy,
+etc.) get the unit_of_measurement guidance and a unit-style example instead.
+
+Parameters:
+  range_note          Parenthetical range for above/below (unitless). For example: "0–100".
+  number_final        Closing number guidance (unitless). For example: "a percentage value (0–100)".
+  has_unit            Set (to anything) for unit_of_measurement guidance and example.
+                      Requires unit_default, unit_example_entity, and unit_example_value.
+  unit_default        Default unit used in the example. For example: "°C".
+  unit_example_entity Entity reference used in the example. For example:
+                      "input_number.comfort_temperature_min".
+  unit_example_value  Literal number used in the example. For example: "22".
+  threshold_required  "true" or "false" for the threshold field. Default "false".
+{% endcomment %}
+{% options_yaml %}
+threshold:
+  description: |
+    The threshold the entity's reading is compared against:
+
+    - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass.{% unless include.has_unit %} Provide `value` with a `number` key ({{ include.range_note }}) or an `entity` key.{% endunless %}
+    - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass.{% unless include.has_unit %} Provide `value` with a `number` key ({{ include.range_note }}) or an `entity` key.{% endunless %}
+    - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass.{% unless include.has_unit %} Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.{% endunless %}
+    - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass.{% unless include.has_unit %} Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.{% endunless %}
+{% if include.has_unit %}
+
+    For `type: above` and `type: below`, use `value` with either `number` and `unit_of_measurement`, or `entity`. For `type: between` and `type: outside`, use `value_min` and `value_max`, each with either `number` and `unit_of_measurement`, or `entity`. For example:
+
+    ```yaml
+    threshold:
+      type: between
+      value_min:
+        entity: {{ include.unit_example_entity }}
+      value_max:
+        number: {{ include.unit_example_value }}
+        unit_of_measurement: {{ include.unit_default }}
+    ```
+
+    When using an `entity`, its current reading is used as the threshold at the moment the condition is evaluated, which lets you compare two readings dynamically.
+{% else %}
+
+    For the `number` key, use {{ include.number_final }}. For the `entity` key, use an `input_number`, `number`, or `sensor` entity.
+{% endif %}
+  required: {{ include.threshold_required | default: "false" }}
+  type: map
+behavior:
+  description: |
+    When multiple entities are targeted, controls how results combine:
+
+    - `any`: The condition passes if at least one targeted entity meets the threshold.
+    - `all`: The condition passes only when every targeted entity meets the threshold.
+  required: false
+  type: string
+  default: any
+{% endoptions_yaml %}

source/_includes/conditions/threshold_value_steps.md

@@ -0,0 +1,36 @@
+{% comment %}
+Reusable "To use ... in an automation" steps for entity conditions that test a
+reading against the threshold-mapping schema (above/below/in range/outside
+range). Used by humidity.is_value; reusable by climate.target_humidity,
+light.is_brightness, counter.is_value, and similar.
+
+Parameters:
+  title         UI display name. For example: "Relative humidity".
+  sensor        Sensor noun. For example: "humidity sensor".
+  areas         Example areas. For example: "bedroom or bathroom".
+  value_long    Number-entry phrasing. For example: "a fixed percentage directly, for example `65` for 65%".
+  has_unit      Set (to anything) to add a "Unit" step. Requires unit_label and unit_options.
+  unit_label    Unit label. For example: "temperature unit", "energy unit".
+  unit_options  Bare list of allowed units for prose. For example: "°C or °F".
+{% endcomment %}
+To use **{{ include.title }}** in an automation:
+
+1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}.
+2. Open an existing automation, or select **Create automation** > **Create new automation**.
+3. In the **And if** section, select **Add condition**.
+4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your {{ include.sensor }} is in (like your {{ include.areas }}). You can also select a device, a specific entity, or a label.
+5. From the conditions shown for that target, select **{{ include.title }}**.
+6. Under **Threshold type**, set the level the condition checks against:
+   1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold.
+   2. Select **Number** or **Entity**:
+      - **Number**: Enter {{ include.value_long }}. For **In range** or **Outside range**, enter both a lower and upper bound.
+      - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold:
+        - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value.
+        - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes.
+        - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers).
+        - If you don't have a number helper, you can create one by selecting **Create a new number helper**.
+{%- if include.has_unit %}
+7. Under **Unit**, select the {{ include.unit_label }} ({{ include.unit_options }}) to use for the threshold comparison.
+{%- endif %}
+8. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**.
+9. Select **Save**.

source/_includes/triggers/threshold_changed_options_ui.md

@@ -0,0 +1,28 @@
+{% comment %}
+Reusable "Options in the UI" block for "changed" entity triggers that use the
+threshold-mapping schema.
+
+Parameters:
+  unit_phrase_ui     Value-entry phrasing. For example: "a fixed percentage (0–100%)".
+  has_unit           Set (to anything) to add a "Unit" row. Requires unit_label,
+                     unit_options_code, and unit_default.
+  unit_label         Unit label. For example: "temperature unit", "energy unit".
+  unit_options_code  Inline code list of allowed units. For example: "`°C` or `°F`".
+  unit_default       Default unit. For example: "°C".
+{% endcomment %}
+{% options_ui %}
+Threshold type:
+  description: |
+    Controls which changes fire the trigger:
+
+    - **Any change**: fires on any change, regardless of direction or new value.
+    - **Above** or **Below** (exclusive): fires only when the new reading is strictly above or below the threshold. A reading equal to the threshold does not fire the trigger.
+    - **In range** (exclusive): fires only when the new reading is strictly between the two bounds. A reading equal to either bound does not fire the trigger.
+    - **Outside range** (inclusive): fires when the new reading is at or below the lower bound, or at or above the upper bound. A reading equal to either bound fires the trigger.
+
+    For each mode you can enter {{ include.unit_phrase_ui }} or reference a sensor entity or a [number helper](/integrations/input_number/) entity.
+{% if include.has_unit %}
+Unit:
+  description: The {{ include.unit_label }} to use for threshold comparison. Accepts {{ include.unit_options_code }}. Required when using numerical thresholds (not required when using entity references). Default is `{{ include.unit_default }}`.
+{% endif %}
+{% endoptions_ui %}