Add description placeholders to SchemaFlowFormStep (#147544)

* test description placeholders

* Update test_schema_config_entry_flow.py

* fix copy and paste indentation

* Apply suggestions from code review

---------

Co-authored-by: Erik Montnemery <erik@montnemery.com>

homeassistant/helpers/schema_config_entry_flow.py

@@ -95,6 +95,12 @@ class SchemaFlowFormStep(SchemaFlowStep):
     preview: str | None = None
     """Optional preview component."""
 
+    description_placeholders: (
+        Callable[[SchemaCommonFlowHandler], Coroutine[Any, Any, dict[str, str]]]
+        | UndefinedType
+    ) = UNDEFINED
+    """Optional property to populate description placeholders."""
+
 
 @dataclass(slots=True)
 class SchemaFlowMenuStep(SchemaFlowStep):
@@ -257,6 +263,10 @@ class SchemaCommonFlowHandler:
         if (data_schema := await self._get_schema(form_step)) is None:
             return await self._show_next_step_or_create_entry(form_step)
 
+        description_placeholders: dict[str, str] | None = None
+        if form_step.description_placeholders is not UNDEFINED:
+            description_placeholders = await form_step.description_placeholders(self)
+
         suggested_values: dict[str, Any] = {}
         if form_step.suggested_values is UNDEFINED:
             suggested_values = self._options
@@ -285,6 +295,7 @@ class SchemaCommonFlowHandler:
         return self._handler.async_show_form(
             step_id=next_step_id,
             data_schema=data_schema,
+            description_placeholders=description_placeholders,
             errors=errors,
             last_step=last_step,
             preview=form_step.preview,

tests/helpers/test_schema_config_entry_flow.py

@@ -591,6 +591,45 @@ async def test_suggested_values(
     assert result["type"] == data_entry_flow.FlowResultType.CREATE_ENTRY
 
 
+async def test_description_placeholders(
+    hass: HomeAssistant, manager: data_entry_flow.FlowManager
+) -> None:
+    """Test description_placeholders handling in SchemaFlowFormStep."""
+    manager.hass = hass
+
+    OPTIONS_SCHEMA = vol.Schema(
+        {vol.Optional("option1", default="a very reasonable default"): str}
+    )
+
+    async def _get_description_placeholders(
+        _: SchemaCommonFlowHandler,
+    ) -> dict[str, Any]:
+        return {"option1": "a dynamic string"}
+
+    OPTIONS_FLOW: dict[str, SchemaFlowFormStep | SchemaFlowMenuStep] = {
+        "init": SchemaFlowFormStep(
+            OPTIONS_SCHEMA,
+            next_step="step_1",
+            description_placeholders=_get_description_placeholders,
+        ),
+    }
+
+    class TestFlow(MockSchemaConfigFlowHandler, domain="test"):
+        config_flow = {}
+        options_flow = OPTIONS_FLOW
+
+    mock_integration(hass, MockModule("test"))
+    mock_platform(hass, "test.config_flow", None)
+    config_entry = MockConfigEntry(data={}, domain="test")
+    config_entry.add_to_hass(hass)
+
+    # Start flow and check the description_placeholders is populated
+    result = await hass.config_entries.options.async_init(config_entry.entry_id)
+    assert result["type"] == data_entry_flow.FlowResultType.FORM
+    assert result["step_id"] == "init"
+    assert result["description_placeholders"] == {"option1": "a dynamic string"}
+
+
 async def test_options_flow_state(hass: HomeAssistant) -> None:
     """Test flow_state handling in SchemaFlowFormStep."""