From b871d8a3405ac52076b547e48ba92a9c2862c5f7 Mon Sep 17 00:00:00 2001
From: JohnnyT <ubergeek3141@gmail.com>
Date: Wed, 30 Sep 2026 00:05:46 -0600
Subject: [PATCH] Returns focus when a Plan picker closes

Closing a picker on the Plan page removed the control that held the
focus, and a keyboard fell back to the document. Every way a picker
closes now names the control the focus goes to: the row's "+" after
Cancel or a refused pick in a row's picker, the row of the slot's
block after Cancel or a refused pick in a slot's picker, and the new
step's row after a pick that lands (the first new row on the page for
a recipe).

The page adds a hidden element on every close whose phx-mounted is
JS.focus/1 naming that control, so the command runs after the patch
has drawn it. The row's "+" and sentence buttons gain ids built from
the block id. LiveView tests cover each closing path.

Refs: se-9cpa
---
 lib/statifier_examples_web/live/plan_live.ex  | 156 ++++++++++--
 .../live/plan_live_test.exs                   | 238 ++++++++++++++++++
 2 files changed, 379 insertions(+), 15 deletions(-)

diff --git a/lib/statifier_examples_web/live/plan_live.ex b/lib/statifier_examples_web/live/plan_live.ex
index 0f9912b..ac2efb8 100644
--- a/lib/statifier_examples_web/live/plan_live.ex
+++ b/lib/statifier_examples_web/live/plan_live.ex
@@ -174,6 +174,26 @@ defmodule StatifierExamplesWeb.PlanLive do
   control held: it moves focus to its first control when it is added to
   the page (`JS.focus_first/0`, as its `phx-mounted`).
 
+  Closing a picker removes the control that held the focus too, so every
+  way it closes hands the focus to a control that is on the page once it
+  has closed:
+
+  | The picker closes by | Focus goes to |
+  |---|---|
+  | Cancel, or a refused pick, in a row's picker | that row's "+" |
+  | Cancel, or a refused pick, in a slot's picker | the row of the block whose slot it was |
+  | a pick that lands | the new step's row, the first new one on the page for a recipe |
+
+  A refused pick is one the page or the package turns away: a gap or a
+  type the page cannot resolve, a recipe that does not land at the gap,
+  or a command the session refuses.
+  The row's "+" and each row's sentence carry ids built from the block id
+  (`plan-add-` and `plan-step-`), and the page moves the focus with
+  `JS.focus/1` from a hidden element it adds each time a picker closes,
+  as that element's `phx-mounted`, so the command runs after the patch
+  has drawn the control it names. Each close adds a new element with an
+  id of its own, which is what makes the command run again.
+
   ## The description region
 
   The panel is always drawn, and at its top is the package's description
@@ -259,7 +279,9 @@ defmodule StatifierExamplesWeb.PlanLive do
        fixtures: Charts.fixtures(),
        session: nil,
        selected_id: nil,
-       inserting: nil
+       inserting: nil,
+       focus_return: nil,
+       focus_seq: 0
      )}
   end
 
@@ -368,7 +390,7 @@ defmodule StatifierExamplesWeb.PlanLive do
   end
 
   def handle_event("insert-close", _params, socket) do
-    {:noreply, socket |> assign(:inserting, nil) |> assign_insertable()}
+    {:noreply, close_picker(socket)}
   end
 
   # A recipe row. The package answers what the arrangement IS at this
@@ -389,27 +411,18 @@ defmodule StatifierExamplesWeb.PlanLive do
 
     with {_parent_id, _slot, _index} = target <- gap_target(socket, gap_key(params)),
          {:ok, commands} <- Targets.recipe_inserts(document, palette, name, target) do
-      {:noreply,
-       socket
-       |> assign(:inserting, nil)
-       |> apply_session(Session.commit(socket.assigns.session, {:compound, commands}))}
+      {:noreply, commit_pick(socket, {:compound, commands})}
     else
-      _no_gap_or_refused_recipe ->
-        {:noreply, socket |> assign(:inserting, nil) |> assign_insertable()}
+      _no_gap_or_refused_recipe -> {:noreply, close_picker(socket)}
     end
   end
 
   def handle_event("insert", %{"block-id" => _id, "type" => type} = params, socket) do
     with {_parent_id, _slot, _index} = target <- gap_target(socket, gap_key(params)),
          {:ok, %Block{} = block} <- Palette.new_block(socket.assigns.session.palette, type) do
-      socket =
-        socket
-        |> assign(:inserting, nil)
-        |> apply_session(Session.commit(socket.assigns.session, {:insert, target, block}))
-
-      {:noreply, socket}
+      {:noreply, commit_pick(socket, {:insert, target, block})}
     else
-      _no_gap_or_type -> {:noreply, socket |> assign(:inserting, nil) |> assign_insertable()}
+      _no_gap_or_type -> {:noreply, close_picker(socket)}
     end
   end
 
@@ -454,6 +467,14 @@ defmodule StatifierExamplesWeb.PlanLive do
       data-theme={@theme}
       data-readonly={if @readonly?, do: "true"}
     >
+      <span
+        :if={@focus_return}
+        id={"plan-focus-return-#{@focus_return.seq}"}
+        hidden
+        data-plan-focus-return={@focus_return.to}
+        phx-mounted={JS.focus(to: id_selector(@focus_return.to))}
+      />
+
       <div class="sb-editor myapp-plan">
         <div class="myapp-header">
           <div class="myapp-header__identity">
@@ -619,6 +640,13 @@ defmodule StatifierExamplesWeb.PlanLive do
   # `JS.focus_first/0` on itself when it is added to the page, and its id
   # names its slot, so arming another slot adds a new picker rather than
   # patching this one. The row's picker does the same for its "+".
+  #
+  # Closing a picker takes its focused control away as well, so every way
+  # out of one hands the focus on (`close_picker/1`, `commit_pick/2`):
+  # Cancel or a refused pick sends it to the row's "+" for a row's picker
+  # and to the row of the slot's block for this one, and a pick that
+  # lands sends it to the new step's row. The page's hidden
+  # `plan-focus-return-` element carries the `JS.focus/1` that does it.
   defp panel(assigns) do
     ~H"""
     <aside
@@ -772,6 +800,7 @@ defmodule StatifierExamplesWeb.PlanLive do
     >
       <div class="myapp-plan__line">
         <button
+          id={step_dom_id(@node.block_id)}
           class="myapp-plan__sentence"
           type="button"
           aria-describedby="plan-description"
@@ -830,6 +859,7 @@ defmodule StatifierExamplesWeb.PlanLive do
       <div :if={not @readonly?} class="myapp-plan__gap">
         <button
           :if={@inserting != @node.block_id}
+          id={add_dom_id(@node.block_id)}
           class="myapp-plan__add"
           type="button"
           phx-click="insert-open"
@@ -953,6 +983,102 @@ defmodule StatifierExamplesWeb.PlanLive do
   defp apply_session(socket, {:error, %Session{} = session}),
     do: socket |> assign(:session, session) |> rebuild()
 
+  # ----------------------------------------------------------------- focus
+
+  # A picker closing without a step landing: Cancel, or a pick refused
+  # before or at the write. The focus goes back to the control that armed
+  # the gap, or to the row standing for the block whose slot it was
+  # (`gap_control/1`). A close with no picker open moves nothing.
+  @spec close_picker(Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
+  defp close_picker(socket) do
+    armed = socket.assigns.inserting
+
+    socket
+    |> assign(:inserting, nil)
+    |> assign_insertable()
+    |> return_focus(gap_control(armed))
+  end
+
+  # A pick committed through the session. When the step lands, the focus
+  # goes to its row: the first row on the page whose block was not in the
+  # document before the pick. A type puts down one block; a recipe can put
+  # down more than one, and not always at the armed gap (the core
+  # `"deadline"` recipe writes the head of the group's body and its
+  # interrupts rail), so the row is found by what is new rather than by
+  # where the gap was. When the session refuses the command, the picker
+  # has still closed, and the focus goes where a Cancel sends it.
+  @spec commit_pick(Phoenix.LiveView.Socket.t(), Edit.t()) :: Phoenix.LiveView.Socket.t()
+  defp commit_pick(socket, command) do
+    armed = socket.assigns.inserting
+    before = row_ids(socket)
+
+    case Session.commit(socket.assigns.session, command) do
+      {:ok, _session} = landed ->
+        socket = socket |> assign(:inserting, nil) |> apply_session(landed)
+        return_focus(socket, new_step_row(socket, before) || gap_control(armed))
+
+      {:error, _session} = refused ->
+        socket
+        |> assign(:inserting, nil)
+        |> apply_session(refused)
+        |> return_focus(gap_control(armed))
+    end
+  end
+
+  # The row's control an armed gap stands for once its picker is gone: a
+  # row's "+" for the gap after that row, the row of the slot's block for
+  # the head of a slot.
+  @spec gap_control(gap() | nil) :: String.t() | nil
+  defp gap_control(nil), do: nil
+  defp gap_control({:slot, id, _name}), do: step_dom_id(id)
+  defp gap_control(id), do: add_dom_id(id)
+
+  # The first row, in the page's order, whose block was not among
+  # `before`, the rows from ahead of the pick.
+  @spec new_step_row(Phoenix.LiveView.Socket.t(), MapSet.t(Block.id())) :: String.t() | nil
+  defp new_step_row(socket, before) do
+    socket
+    |> rows()
+    |> Enum.find_value(fn {node, _depth, _kind} ->
+      if not MapSet.member?(before, node.block_id), do: step_dom_id(node.block_id)
+    end)
+  end
+
+  # The page's rows in the order it draws them: the plan, the rails, the
+  # trays.
+  @spec rows(Phoenix.LiveView.Socket.t()) :: [{ViewModel.Node.t(), non_neg_integer(), atom()}]
+  defp rows(%{assigns: %{plan: plan, rails: rails, trays: trays}}), do: plan ++ rails ++ trays
+
+  @spec row_ids(Phoenix.LiveView.Socket.t()) :: MapSet.t(Block.id())
+  defp row_ids(socket),
+    do: socket |> rows() |> MapSet.new(fn {node, _depth, _kind} -> node.block_id end)
+
+  # Names the element the focus goes to next. Every call bumps the
+  # sequence the hidden element's id carries, so each close adds a new
+  # element and its `phx-mounted` runs again.
+  @spec return_focus(Phoenix.LiveView.Socket.t(), String.t() | nil) ::
+          Phoenix.LiveView.Socket.t()
+  defp return_focus(socket, nil), do: socket
+
+  defp return_focus(socket, dom_id) do
+    seq = socket.assigns.focus_seq + 1
+    assign(socket, focus_seq: seq, focus_return: %{seq: seq, to: dom_id})
+  end
+
+  @spec add_dom_id(Block.id()) :: String.t()
+  defp add_dom_id(id), do: "plan-add-#{id}"
+
+  @spec step_dom_id(Block.id()) :: String.t()
+  defp step_dom_id(id), do: "plan-step-#{id}"
+
+  # A block id is opaque, so the selector quotes the element's id rather
+  # than writing it after a `#`, which only some characters survive.
+  @spec id_selector(String.t()) :: String.t()
+  defp id_selector(dom_id) do
+    escaped = dom_id |> String.replace("\\", "\\\\") |> String.replace("\"", "\\\"")
+    ~s([id="#{escaped}"])
+  end
+
   # `key` is the field's identity, and a key naming no field in the
   # selected block edits nothing - the same crafted-payload guard
   # `ConfigForm.decode/3` applies. What the gesture then MEANS is
diff --git a/test/statifier_examples_web/live/plan_live_test.exs b/test/statifier_examples_web/live/plan_live_test.exs
index 2f8afee..0befec0 100644
--- a/test/statifier_examples_web/live/plan_live_test.exs
+++ b/test/statifier_examples_web/live/plan_live_test.exs
@@ -861,6 +861,195 @@ defmodule StatifierExamplesWeb.PlanLiveTest do
     end
   end
 
+  describe "focus when a picker closes" do
+    # Closing a picker takes its focused control away with it, the same
+    # loss opening one had: Cancel, a pick and a refused pick all remove
+    # the picker, and a browser whose focused element is gone falls back to
+    # the document. So every way out of a picker names the control the
+    # focus goes to next - the row's "+" after Cancel or a refused pick in
+    # a row's picker, the row of the slot's block after Cancel or a refused
+    # pick in a slot's picker, and the new step's row after a pick that
+    # lands.
+    #
+    # LiveViewTest runs no JavaScript, so what these hold is the command
+    # the browser runs: the hidden `plan-focus-return-` element the page
+    # adds on every close, whose `phx-mounted` is `JS.focus/1` naming that
+    # control, and the control itself, on the page under that id.
+
+    @patron "patron_registration"
+    @welcome_plus ~s(li[data-block-id="blk_pr_welcome"] button.myapp-plan__add)
+    @welcome_picker ~s(li[data-block-id="blk_pr_welcome"] [data-plan-picker="open"] button)
+    @slot_picker ~s(#plan-panel [data-plan-picker="open"] button)
+
+    # Sabotage: sent "insert-close" back to clearing the gap without
+    # `return_focus/2`; no focus element was drawn and this went red.
+    # Reverted from a copy.
+    test "Cancel in a row's picker hands the focus to that row's \"+\"", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      view |> element(@welcome_plus) |> render_click()
+
+      html = view |> element(@welcome_picker, "Cancel") |> render_click()
+
+      assert focus_return(html) == "plan-add-blk_pr_welcome"
+      assert has_element?(view, "#plan-add-blk_pr_welcome", "+")
+    end
+
+    # Sabotage: made `gap_control/1` answer a slot with its block's "+";
+    # the focus named the "+" and this went red. Reverted from a copy.
+    test "Cancel in a slot's picker hands the focus to the row of the slot's block",
+         %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      select(view, "blk_pr_age")
+      view |> element(~s(#plan-panel button[data-plan-empty-slot="otherwise"])) |> render_click()
+
+      html = view |> element(@slot_picker, "Cancel") |> render_click()
+
+      assert focus_return(html) == "plan-step-blk_pr_age"
+      assert has_element?(view, ~s(li[data-block-id="blk_pr_age"] #plan-step-blk_pr_age))
+    end
+
+    # Sabotage: made a landed pick return the focus as a Cancel does; the
+    # focus named the "+" rather than the new row and this went red.
+    # Reverted from a copy.
+    test "a pick in a row's picker hands the focus to the new step's row", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      view |> element(@welcome_plus) |> render_click()
+
+      html = view |> element(@welcome_picker, ~r/^\s*Wait\s*$/) |> render_click()
+
+      new_id = block_after(@patron, "blk_pr_verify", "body", "blk_pr_welcome")
+      refute new_id in [nil | original_ids(@patron)]
+      assert focus_return(html) == "plan-step-#{new_id}"
+      assert has_element?(view, ~s(li[data-block-id="#{new_id}"] #plan-step-#{new_id}))
+    end
+
+    # A recipe can put down more than one block, and not at the armed gap:
+    # the core "deadline" recipe writes the head of the group's body and
+    # its interrupts rail. The focus goes to the first new row on the page,
+    # the send now heading the group's body.
+    #
+    # Sabotage: made the focus go to the last new row on the page rather
+    # than the first; it named the rail's new row and this went red.
+    # Reverted from a copy.
+    test "a recipe pick hands the focus to its first new row", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      view |> element(@welcome_plus) |> render_click()
+
+      html = view |> element(@welcome_picker, ~r/^\s*Deadline\s*$/) |> render_click()
+
+      [new_id | _rest] = slot_ids_in(@patron, "blk_pr_verify", "body")
+      refute new_id in [nil | original_ids(@patron)]
+      assert focus_return(html) == "plan-step-#{new_id}"
+      assert has_element?(view, "#plan-step-#{new_id}")
+    end
+
+    # Sabotage: made a landed pick return the focus as a Cancel does; the
+    # focus named the slot's block rather than the new row and this went
+    # red. Reverted from a copy.
+    test "a pick in a slot's picker hands the focus to the new step's row", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      select(view, "blk_pr_age")
+      view |> element(~s(#plan-panel button[data-plan-empty-slot="otherwise"])) |> render_click()
+
+      html = view |> element(@slot_picker, ~r/^\s*Wait\s*$/) |> render_click()
+
+      [new_id] = slot_ids_in(@patron, "blk_pr_age", "otherwise")
+      assert focus_return(html) == "plan-step-#{new_id}"
+      assert has_element?(view, "#plan-step-#{new_id}")
+    end
+
+    # Sabotage: sent the type handler's refusal branch back to clearing the
+    # gap without `return_focus/2`; no focus element was drawn and this
+    # went red. Reverted from a copy.
+    test "a refused type pick in a row's picker hands the focus to the row's \"+\"",
+         %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      view |> element(@welcome_plus) |> render_click()
+
+      html =
+        render_hook(view, "insert", %{"block-id" => "blk_pr_welcome", "type" => "no.such.type"})
+
+      refute html =~ ~s(data-plan-picker="open")
+      assert document(@patron) == fixture(@patron).document
+      assert focus_return(html) == "plan-add-blk_pr_welcome"
+    end
+
+    # Sabotage: sent the recipe handler's refusal branch back to clearing
+    # the gap without `return_focus/2`; no focus element was drawn and this
+    # went red. Reverted from a copy.
+    test "a refused recipe pick in a row's picker hands the focus to the row's \"+\"",
+         %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      view |> element(@welcome_plus) |> render_click()
+
+      html =
+        render_hook(view, "insert", %{
+          "block-id" => "blk_pr_welcome",
+          "kind" => "recipe",
+          "type" => "no.such.recipe"
+        })
+
+      refute html =~ ~s(data-plan-picker="open")
+      assert document(@patron) == fixture(@patron).document
+      assert focus_return(html) == "plan-add-blk_pr_welcome"
+    end
+
+    # Sabotage: made `gap_control/1` answer a slot with its block's "+";
+    # the focus named the "+" and this went red. Reverted from a copy.
+    test "a refused pick in a slot's picker hands the focus to the row of the slot's block",
+         %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+      select(view, "blk_pr_age")
+      view |> element(~s(#plan-panel button[data-plan-empty-slot="otherwise"])) |> render_click()
+
+      html =
+        render_hook(view, "insert", %{
+          "block-id" => "blk_pr_age",
+          "slot" => "otherwise",
+          "type" => "no.such.type"
+        })
+
+      refute html =~ "data-plan-slot-insert"
+      assert focus_return(html) == "plan-step-blk_pr_age"
+    end
+
+    # The command runs when its element is added to the page, so a second
+    # close has to add a second element rather than patch the first.
+    #
+    # Sabotage: gave every focus element the one sequence number 1; the
+    # two closes drew the same id and this went red. Reverted from a copy.
+    test "each close adds a focus element of its own", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+
+      first =
+        view
+        |> tap(&(&1 |> element(@welcome_plus) |> render_click()))
+        |> element(@welcome_picker, "Cancel")
+        |> render_click()
+        |> focus_element_id()
+
+      second =
+        view
+        |> tap(&(&1 |> element(@welcome_plus) |> render_click()))
+        |> element(@welcome_picker, "Cancel")
+        |> render_click()
+        |> focus_element_id()
+
+      refute first == second
+    end
+
+    # Sabotage: made `gap_control/1` answer no armed gap with the panel;
+    # a close with no picker open drew a focus element and this went red.
+    # Reverted from a copy.
+    test "a close with no picker open moves nothing", %{conn: conn} do
+      {:ok, view, _html} = live(conn, ~p"/plan?#{[doc: @patron]}")
+
+      html = render_hook(view, "insert-close", %{})
+
+      refute html =~ "data-plan-focus-return"
+    end
+  end
+
   describe "the transparent-container readers" do
     # `se-6jn`. `sb-6xkf` promoted the three readers a host that FLATTENS
     # containers out of its own outline needs - `ViewModel.transparent?/2`,
@@ -1718,6 +1907,55 @@ defmodule StatifierExamplesWeb.PlanLiveTest do
     end
   end
 
+  # The control a closed picker hands the focus to: the one hidden focus
+  # element in `html`, its `phx-mounted` checked to be `JS.focus/1` on the
+  # element its `data-plan-focus-return` names, and that name returned.
+  defp focus_return(html) do
+    assert [element] =
+             html
+             |> LazyHTML.from_fragment()
+             |> LazyHTML.query("[data-plan-focus-return]")
+             |> Enum.to_list()
+
+    [target] = LazyHTML.attribute(element, "data-plan-focus-return")
+    assert focus_command(element) == [["focus", %{"to" => ~s([id="#{target}"])}]]
+    target
+  end
+
+  # The id of the one hidden focus element in `html`.
+  defp focus_element_id(html) do
+    assert [element] =
+             html
+             |> LazyHTML.from_fragment()
+             |> LazyHTML.query("[data-plan-focus-return]")
+             |> Enum.to_list()
+
+    LazyHTML.attribute(element, "id")
+  end
+
+  # The ids of `key`'s document as its fixture ships it.
+  defp original_ids(key), do: key |> fixture() |> Map.fetch!(:document) |> block_ids()
+
+  defp block_ids(document), do: document |> Document.blocks() |> Enum.map(& &1.id)
+
+  # The ids in one slot of a block, as the store holds them.
+  defp slot_ids_in(key, block_id, slot) do
+    key
+    |> document()
+    |> Document.blocks()
+    |> Enum.find(&(&1.id == block_id))
+    |> Map.fetch!(:slots)
+    |> Map.get(slot, [])
+    |> Enum.map(& &1.id)
+  end
+
+  # The id standing right after `sibling` in one slot of a block, as the
+  # store holds it.
+  defp block_after(key, block_id, slot, sibling) do
+    ids = slot_ids_in(key, block_id, slot)
+    Enum.at(ids, Enum.find_index(ids, &(&1 == sibling)) + 1)
+  end
+
   # The tag of the first control inside the picker, the element
   # `focus_first` lands on.
   defp first_control(picker) do