Enhance timer.markdown with attributes and examples

source/_integrations/timer.markdown

@@ -82,6 +82,20 @@ Pick an icon from [Material Design Icons](https://pictogrammers.com/library/mdi/
 | `timer.restarted` | Fired when a timer has been restarted |
 | `timer.paused` | Fired when a timer has been paused |
 
+## Attributes
+
+Each `timer` entity provides a few useful attributes that describe its current configuration and runtime.
+
+- `duration`: Total configured length of the timer, in seconds or `HH:MM:SS`
+- `remaining`: How much time is left when the timer is active or paused; updates only when paused, restarted, or canceled
+- `finishes_at`: The timestamp when the timer will finish; available only when running
+- `restore`: Whether the timer will resume after a Home Assistant restart
+- 'editable': Whether the timer are manageable by UI 
+
+{% note %}
+The `remaining` value does not count down in real time. For dynamic countdowns or dashboards, rely on the `finishes_at` attribute.
+{% endnote %}
+
 ## Actions
 
 ### Action `timer.start`
@@ -135,6 +149,51 @@ Reload `timer`'s configuration without restarting Home Assistant itself. This ac
 
 Navigate to **Developer Tools** > **Actions** and select the `timer.start` action, then click the **Fill Example Data** button. Now change the `entity_id` and `duration` and select **Perform action** button.
 
+## Templates
+
+Timers can be combined with templates to show remaining time or end time dynamically.
+
+### Remaining time
+
+Create a template sensor that calculates how long the timer has left.
+It uses the `finishes_at` timestamp to compute the difference between now and the expected end.
+
+{% raw %}
+
+```yaml
+template:
+  - sensor:
+      - name: "Laundry Timer - Remaining"
+        state: >
+          {% set fin = state_attr('timer.laundry', 'finishes_at') %}
+          {% if fin %}
+            {% set s = (as_datetime(fin) - now()).total_seconds() | int %}
+            {{ (s if s > 0 else 0) | timestamp_custom('%H:%M:%S', false) }}
+          {% else %}
+            00:00:00
+          {% endif %}
+```
+{% endraw %}
+
+### End time
+
+A simpler version that shows when the timer will finish.
+With `device_class: timestamp`, it displays as a proper time value in the dashboard.
+
+{% raw %}
+
+```yaml
+template:
+  - sensor:
+      - name: "Laundry Timer - Ends at"
+        state: >
+          {% set fin = state_attr('timer.laundry', 'finishes_at') %}
+          {{ as_datetime(fin) if fin else none }}
+        device_class: timestamp
+```
+
+{% endraw %}
+
 ## Examples
 
 Set a timer called `test` to a duration of 30 seconds.
@@ -207,3 +266,47 @@ script:
         target:
           entity_id: timer.test
 ```
+
+### Motion light with auto-off
+
+The light turns on when motion is detected and stays on while movement continues.
+When motion stops and the timer finishes, the light turns off.
+
+```yaml
+alias: Motion-Activated Hall Light
+description: >-
+  Turn on hall light when motion is detected and turn it off after 2 minutes of
+  inactivity.
+triggers:
+  - trigger: state
+    entity_id: binary_sensor.motion_hall
+    to: "on"
+    id: motion_on
+  - trigger: event
+    event_type: timer.finished
+    event_data:
+      entity_id: timer.hall_light
+    id: timer_done
+actions:
+  - choose:
+      - conditions:
+          - condition: trigger
+            id: motion_on
+        sequence:
+          - action: light.turn_on
+            target:
+              entity_id: light.hall
+          - action: timer.start
+            target:
+              entity_id: timer.hall_light
+            data:
+              duration: "00:02:00"
+      - conditions:
+          - condition: trigger
+            id: timer_done
+        sequence:
+          - action: light.turn_off
+            target:
+              entity_id: light.hall
+```
+