#:########################################################################################:#
# Low Battery Device Summary Package                                                     #
#:########################################################################################:#
#
# TITLE:
#   Low Battery Device Summary
#
# FILE:
#   packages/low_battery_device_quantity.yaml
#
# VERSION:
#   V1.1 2026-07-20
#
# VERSION HISTORY:
#   V1.1 2026-07-20
#     - Changed the low-battery threshold from 97% to 20%.
#     - Added structured documentation for scope, exclusions, and outputs.
#
#   V1.0
#     - Initial low-battery count and list sensors.
#
# PURPOSE:
#   Finds numeric sensor entities with device_class battery whose value is 20%
#   or lower, then exposes a count and a human-readable device list.
#
# SCOPE AND EXCLUSIONS:
#   - Only entities in the sensor domain with device_class battery are checked.
#   - Unknown, unavailable, non-numeric, and "Ok" states are excluded.
#   - Battery entities in other domains are not included.
#
# OUTPUTS:
#   - sensor.devices_with_low_battery reports the number of matching sensors.
#   - sensor.devices_with_low_battery_list reports names and percentages.
#   - The list sensor also exposes count, entities, and names attributes.
#
#:########################################################################################:#

template:
  - sensor:
      - name: "Devices with low battery"
        unique_id: devices_with_low_battery_count
        unit_of_measurement: "devices"
        state: >
          {% set ns = namespace(c=0) %}
          {% for s in states.sensor %}
            {% if s.attributes.device_class == 'battery' %}
              {% set st = s.state %}
              {% if st not in ['unknown', 'unavailable', 'Ok'] %}
                {% if st | int(-1) != -1 and (st | int(0)) <= 20 %}
                  {% set ns.c = ns.c + 1 %}
                {% endif %}
              {% endif %}
            {% endif %}
          {% endfor %}
          {{ ns.c }}
        icon: >
          {% if this.state | int(0) == 0 %}
            mdi:check-circle
          {% else %}
            mdi:battery-alert
          {% endif %}

      - name: "Devices with low battery list"
        unique_id: devices_with_low_battery_list
        icon: >
          {% if states('sensor.devices_with_low_battery') | int(0) == 0 %}
            mdi:check-circle
          {% else %}
            mdi:battery-alert
          {% endif %}
        state: >
          {% set ns = namespace(names=[]) %}
          {% for s in states.sensor %}
            {% if s.attributes.device_class == 'battery' %}
              {% set st = s.state %}
              {% if st not in ['unknown', 'unavailable', 'Ok'] %}
                {% if st | int(-1) != -1 and (st | int(0)) <= 20 %}
                  {% set ns.names = ns.names + [s.name ~ ' (' ~ (st | int(0)) ~ '%)'] %}
                {% endif %}
              {% endif %}
            {% endif %}
          {% endfor %}
          {% if ns.names | length == 0 %}
            None
          {% else %}
            {{ ns.names | join(', ') }}
          {% endif %}
        attributes:
          count: "{{ states('sensor.devices_with_low_battery') | int(0) }}"
          entities: >
            {% set ns = namespace(e=[]) %}
            {% for s in states.sensor %}
              {% if s.attributes.device_class == 'battery' %}
                {% set st = s.state %}
                {% if st not in ['unknown', 'unavailable', 'Ok'] %}
                  {% if st | int(-1) != -1 and (st | int(0)) <= 20 %}
                    {% set ns.e = ns.e + [s.entity_id] %}
                  {% endif %}
                {% endif %}
              {% endif %}
            {% endfor %}
            {{ ns.e }}
          names: >
            {% set ns = namespace(n=[]) %}
            {% for s in states.sensor %}
              {% if s.attributes.device_class == 'battery' %}
                {% set st = s.state %}
                {% if st not in ['unknown', 'unavailable', 'Ok'] %}
                  {% if st | int(-1) != -1 and (st | int(0)) <= 20 %}
                    {% set ns.n = ns.n + [s.name] %}
                  {% endif %}
                {% endif %}
              {% endif %}
            {% endfor %}
            {{ ns.n }}