Add new vacuum state property and enum (#2360)

* Add new vacuum state property and enum

* Fix review comments

* New date

Author: gjohansson-ST

blog/2024-12-08-new-vacuum-state-property.md

@@ -0,0 +1,33 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+authorImageURL: https://avatars.githubusercontent.com/u/62932417?v=4
+authorTwitter: GJohansson
+title: "New vacuum state property"
+---
+
+As of Home Assistant Core 2025.1, the constants used to return state in `StateVacuumEntity` are deprecated and replaced by the `VacuumActivity` enum.
+
+Also with this change, integrations should set the `activity` property instead of directly setting the `state` property.
+
+There is a one-year deprecation period, and the constants will stop working from 2026.1 to ensure all custom integration authors have time to adjust.
+
+### Example
+
+```python
+
+from homeassistant.components.vacuum import VacuumActivity
+
+class MyVacuumCleaner(StateVacuumEntity):
+    """My vacuum cleaner."""
+
+    @property
+    def activity(self) -> VacuumActivity | None:
+        """Return the state of the vacuum."""
+        if self.device.is_cleaning():
+            return VacuumActivity.CLEANING
+        return VacuumActivity.DOCKED
+
+```
+
+More details can be found in the [vacuum documentation](/docs/core/entity/vacuum#states).

docs/core/entity/vacuum.md

@@ -22,18 +22,20 @@ Properties should always only return information from memory and not do I/O (lik
 | fan_speed | string | `none` | The current fan speed.
 | fan_speed_list | list | `NotImplementedError()`| List of available fan speeds.
 | name | string | **Required** | Name of the entity.
-| state | string | **Required** | One of the states listed in the states section.
+| activity | VacuumActivity | **Required** | Return one of the states listed in the states section.
 
 ## States
 
-| State | Description
+Setting the state should return an enum from VacuumActivity in the `activity` property.
+
+| Value | Description
 | ----- | -----------
-| `STATE_CLEANING` | The vacuum is currently cleaning.
-| `STATE_DOCKED` | The vacuum is currently docked, it is assumed that docked can also mean charging.
-| `STATE_IDLE` | The vacuum is not paused, not docked and does not have any errors.
-| `STATE_PAUSED` | The vacuum was cleaning but was paused without returning to the dock.
-| `STATE_RETURNING` | The vacuum is done cleaning and is currently returning to the dock, but not yet docked.
-| `STATE_ERROR` | The vacuum encountered an error while cleaning.
+| `CLEANING` | The vacuum is currently cleaning.
+| `DOCKED` | The vacuum is currently docked, it is assumed that docked can also mean charging.
+| `IDLE` | The vacuum is not paused, not docked and does not have any errors.
+| `PAUSED` | The vacuum was cleaning but was paused without returning to the dock.
+| `RETURNING` | The vacuum is done cleaning and is currently returning to the dock, but not yet docked.
+| `ERROR` | The vacuum encountered an error while cleaning.
 
 ## Supported features