Add support for menu step (#68203)

homeassistant/data_entry_flow.py

@@ -21,6 +21,7 @@ RESULT_TYPE_EXTERNAL_STEP = "external"
 RESULT_TYPE_EXTERNAL_STEP_DONE = "external_done"
 RESULT_TYPE_SHOW_PROGRESS = "progress"
 RESULT_TYPE_SHOW_PROGRESS_DONE = "progress_done"
+RESULT_TYPE_MENU = "menu"
 
 # Event that is fired when a flow is progressed via external or progress source.
 EVENT_DATA_ENTRY_FLOW_PROGRESSED = "data_entry_flow_progressed"
@@ -82,6 +83,7 @@ class FlowResult(TypedDict, total=False):
     result: Any
     last_step: bool | None
     options: Mapping[str, Any]
+    menu_options: list[str] | Mapping[str, Any]
 
 
 @callback
@@ -249,7 +251,15 @@ class FlowManager(abc.ABC):
         if cur_step.get("data_schema") is not None and user_input is not None:
             user_input = cur_step["data_schema"](user_input)
 
-        result = await self._async_handle_step(flow, cur_step["step_id"], user_input)
+        # Handle a menu navigation choice
+        if cur_step["type"] == RESULT_TYPE_MENU and user_input:
+            result = await self._async_handle_step(
+                flow, user_input["next_step_id"], None
+            )
+        else:
+            result = await self._async_handle_step(
+                flow, cur_step["step_id"], user_input
+            )
 
         if cur_step["type"] in (RESULT_TYPE_EXTERNAL_STEP, RESULT_TYPE_SHOW_PROGRESS):
             if cur_step["type"] == RESULT_TYPE_EXTERNAL_STEP and result["type"] not in (
@@ -343,6 +353,7 @@ class FlowManager(abc.ABC):
             RESULT_TYPE_EXTERNAL_STEP_DONE,
             RESULT_TYPE_SHOW_PROGRESS,
             RESULT_TYPE_SHOW_PROGRESS_DONE,
+            RESULT_TYPE_MENU,
         ):
             raise ValueError(f"Handler returned incorrect type: {result['type']}")
 
@@ -352,6 +363,7 @@ class FlowManager(abc.ABC):
             RESULT_TYPE_EXTERNAL_STEP_DONE,
             RESULT_TYPE_SHOW_PROGRESS,
             RESULT_TYPE_SHOW_PROGRESS_DONE,
+            RESULT_TYPE_MENU,
         ):
             flow.cur_step = result
             return result
@@ -507,6 +519,28 @@ class FlowHandler:
             "step_id": next_step_id,
         }
 
+    @callback
+    def async_show_menu(
+        self,
+        *,
+        step_id: str,
+        menu_options: list[str] | dict[str, str],
+        description_placeholders: dict | None = None,
+    ) -> FlowResult:
+        """Show a navigation menu to the user.
+
+        Options dict maps step_id => i18n label
+        """
+        return {
+            "type": RESULT_TYPE_MENU,
+            "flow_id": self.flow_id,
+            "handler": self.handler,
+            "step_id": step_id,
+            "data_schema": vol.Schema({"next_step_id": vol.In(menu_options)}),
+            "menu_options": menu_options,
+            "description_placeholders": description_placeholders,
+        }
+
 
 @callback
 def _create_abort_data(