From 25c308cf573067736777e4a676d9754f933aa576 Mon Sep 17 00:00:00 2001
From: Matt de Courcelle <mjdecour@gmail.com>
Date: Mon, 18 May 2026 02:24:07 -0500
Subject: [PATCH 1/2] feat(live_ui): add AskSidebar Phoenix.Component Stage 4
 (Wave 3.7-B)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 4 of the canonical ask_sidebar widget pipeline:
- LiveUi.Widgets.AskSidebar Phoenix.Component with full render template
- Recent rail (capped at 10, relative timestamps, running-status indicator)
- Saved rail (★ glyph, cadence or last_run_at meta)
- Map jump affordance with optional blocker-count badge
- Scoped ARIA heading ids, aria-current on active row
- 39 Stage-4 tests (all pass)

Stages 1-3 were pre-committed by parallel Wave 3.7-B agents:
- Stage 1 (IUR constructor): commit 95b0233 (ThreadCard batch)
- Stage 2 (catalog entry): commit 95b0233 (ThreadCard batch)
- Stage 3 (renderer clause): commit 931a440 (tree_view extension)

DRAFT: 8 open questions for Pascal review flagged in @moduledoc.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../lib/live_ui/widgets/ask_sidebar.ex        | 314 ++++++++++++
 .../test/live_ui/widgets/ask_sidebar_test.exs | 465 ++++++++++++++++++
 2 files changed, 779 insertions(+)
 create mode 100644 packages/live_ui/lib/live_ui/widgets/ask_sidebar.ex
 create mode 100644 packages/live_ui/test/live_ui/widgets/ask_sidebar_test.exs

diff --git a/packages/live_ui/lib/live_ui/widgets/ask_sidebar.ex b/packages/live_ui/lib/live_ui/widgets/ask_sidebar.ex
new file mode 100644
index 00000000..3dcddf5b
--- /dev/null
+++ b/packages/live_ui/lib/live_ui/widgets/ask_sidebar.ex
@@ -0,0 +1,314 @@
+defmodule LiveUi.Widgets.AskSidebar do
+  @moduledoc """
+  Native Ask-mode sidebar shell widget.
+
+  The Ask-mode sidebar replaces `:sidebar_shell` while the operator is in Ask
+  mode. It provides two persistent navigation rails:
+
+  - **Recent** — chronological query history, capped at 10, with relative
+    timestamps and a running-status indicator.
+  - **Saved** — pinned or named queries with a ★ glyph, optional cadence label,
+    and a "+ new" action.
+
+  A **Map jump** affordance at the bottom lets the operator switch back to Map
+  mode without losing the Ask surface. It carries an optional blocker-count badge.
+
+  The widget is a pure display surface — all state is host-managed. No internal
+  state; all transitions are driven by parent assigns.
+
+  ## Required attributes
+
+    * `:sidebar_id` — root identity string; used as `data-sidebar-id` and as the
+      suffix for scoped ARIA heading ids.
+    * `:on_map_jump_event` — canonical Interaction intent string for the Map jump
+      button (emitted as `data-live-ui-intent`).
+
+  ## Optional attributes
+
+    * `:recent_items` — list of `%{id, query, last_run_at, status, on_open_event}`
+      maps. Renderer caps display at 10.
+    * `:saved_items` — list of `%{id, title, query, on_open_event}` maps. Optional
+      per-item keys: `:cadence`, `:last_run_at`.
+    * `:active_item_id` — id of the currently-open item; row gets `aria-current="true"`.
+    * `:on_new_saved_event` — intent string for the "+ new" save button in the Saved rail.
+    * `:on_see_all_event` — intent string for "see all ▸" (visible when `recent_items`
+      exceeds 6).
+    * `:empty_recent_label` — message when Recent rail is empty
+      (default `"No recent queries"`).
+    * `:empty_saved_label` — message when Saved rail is empty
+      (default `"No saved queries yet"`).
+    * `:blocker_count` — non-negative integer badge on the Map jump button; `0`
+      hides the badge (default `0`).
+
+  ## Selector / hook contract
+
+  Root: `data-live-ui-widget="ask-sidebar"` + `data-sidebar-id="{id}"`.
+  Recent rail: `.live-ui-ask-sidebar__section[aria-labelledby="ask-recent-h-{id}"]`.
+  Saved rail: `.live-ui-ask-sidebar__section[aria-labelledby="ask-saved-h-{id}"]`.
+  Active item: `.live-ui-ask-sidebar__item--active` + `aria-current="true"`.
+  Running status: `.live-ui-ask-sidebar__status-running`.
+  Map jump: `.live-ui-ask-sidebar__map-jump-btn`.
+  Blocker badge: `.live-ui-ask-sidebar__blocker-badge`.
+
+  ## ARIA
+
+  - Root `<aside aria-label="Ask sidebar">` — distinguishes from the standard sidebar.
+  - Recent and Saved `<section aria-labelledby="...">` with scoped heading ids.
+  - Active row: `aria-current="true"`.
+  - Running-status indicator: `aria-label="running"`.
+  - Map jump button: `aria-label="Switch to Map mode"`.
+  - Blocker badge: `aria-label="{N} blockers"`.
+
+  ## Open questions for Pascal (Wave 3.7-B)
+
+  1. **Shell-swap vs section composition vs ariston-local?** — Top design call.
+     Current draft assumes option (a): new canonical widget swapping for `:sidebar_shell`.
+  2. **Mode-switch mechanism**: IUR re-render vs LiveView hot-swap?
+  3. **"See all" overlay**: internal vs event-to-host (current draft) vs deferred?
+  4. **Saved rail filter** at 20+ items: renderer threshold, host-supplied value, or v2?
+  5. **Map jump placement**: bottom of scroll vs sticky footer?
+  6. **Width/position parity with `:sidebar_shell`**: share CSS tokens or distinct?
+  7. **Empty state for first-time user**: combined onboarding vs per-rail labels (current draft).
+  8. **Bottom identity bar** (`sb-bottom`): part of widget contract or host-injected?
+  """
+
+  use LiveUi.Component,
+    family: :overlay,
+    name: :ask_sidebar,
+    events: [:click]
+
+  LiveUi.Component.common_attrs()
+  attr(:sidebar_id, :string, required: true)
+  attr(:on_map_jump_event, :string, required: true)
+  attr(:recent_items, :list, default: [])
+  attr(:saved_items, :list, default: [])
+  attr(:active_item_id, :string, default: nil)
+  attr(:on_new_saved_event, :string, default: nil)
+  attr(:on_see_all_event, :string, default: nil)
+  attr(:empty_recent_label, :string, default: "No recent queries")
+  attr(:empty_saved_label, :string, default: "No saved queries yet")
+  attr(:blocker_count, :integer, default: 0)
+
+  @impl true
+  def render(assigns) do
+    assigns =
+      assign(assigns,
+        recent_display: Enum.take(assigns.recent_items, 10),
+        show_see_all: assigns.on_see_all_event != nil and length(assigns.recent_items) > 6
+      )
+
+    ~H"""
+    <aside
+      id={@id}
+      data-live-ui-widget="ask-sidebar"
+      data-sidebar-id={@sidebar_id}
+      data-live-ui-tone={@tone}
+      data-live-ui-variant={@variant}
+      data-live-ui-state={@state}
+      aria-label="Ask sidebar"
+      class={["live-ui-ask-sidebar", @class]}
+      {@rest}
+    >
+      <div class="live-ui-ask-sidebar__scroll">
+
+        <%!-- Recent rail --%>
+        <section
+          class="live-ui-ask-sidebar__section"
+          aria-labelledby={"ask-recent-h-#{@sidebar_id}"}
+        >
+          <div class="live-ui-ask-sidebar__section-header">
+            <span
+              id={"ask-recent-h-#{@sidebar_id}"}
+              class="live-ui-ask-sidebar__section-label"
+            >
+              Recent
+            </span>
+            <span class="live-ui-ask-sidebar__section-cap">
+              last <%= min(length(@recent_items), 10) %>
+            </span>
+            <%= if @show_see_all do %>
+              <button
+                type="button"
+                class="live-ui-ask-sidebar__see-all"
+                data-live-ui-intent={@on_see_all_event}
+                data-sidebar-id={@sidebar_id}
+              >
+                see all &#x25B8;
+              </button>
+            <% end %>
+          </div>
+
+          <div class="live-ui-ask-sidebar__rail">
+            <%= if Enum.empty?(@recent_items) do %>
+              <p class="live-ui-ask-sidebar__empty"><%= @empty_recent_label %></p>
+            <% else %>
+              <%= for item <- @recent_display do %>
+                <button
+                  type="button"
+                  class={[
+                    "live-ui-ask-sidebar__item",
+                    "live-ui-ask-sidebar__item--recent",
+                    item_active_class(@active_item_id, item_id(item))
+                  ]}
+                  aria-current={aria_current(@active_item_id, item_id(item))}
+                  title={item_field(item, :query)}
+                  data-live-ui-intent={item_field(item, :on_open_event)}
+                  data-live-ui-value={item_id(item)}
+                  data-item-id={item_id(item)}
+                >
+                  <span class="live-ui-ask-sidebar__item-glyph" aria-hidden="true">&#x1F553;</span>
+                  <span class="live-ui-ask-sidebar__item-label"><%= item_field(item, :query) %></span>
+                  <span class="live-ui-ask-sidebar__item-meta">
+                    <%= relative_time(item_field(item, :last_run_at)) %>
+                    <%= if item_status_running?(item) do %>
+                      <span class="live-ui-ask-sidebar__status-running" aria-label="running"></span>
+                    <% end %>
+                  </span>
+                </button>
+              <% end %>
+            <% end %>
+          </div>
+        </section>
+
+        <%!-- Saved rail --%>
+        <section
+          class="live-ui-ask-sidebar__section"
+          aria-labelledby={"ask-saved-h-#{@sidebar_id}"}
+        >
+          <div class="live-ui-ask-sidebar__section-header">
+            <span
+              id={"ask-saved-h-#{@sidebar_id}"}
+              class="live-ui-ask-sidebar__section-label"
+            >
+              Saved
+            </span>
+            <span class="live-ui-ask-sidebar__section-cap"><%= length(@saved_items) %></span>
+            <%= if @on_new_saved_event do %>
+              <button
+                type="button"
+                class="live-ui-ask-sidebar__new-saved"
+                title="Save current query"
+                data-live-ui-intent={@on_new_saved_event}
+                data-sidebar-id={@sidebar_id}
+              >
+                + new
+              </button>
+            <% end %>
+          </div>
+
+          <div class="live-ui-ask-sidebar__rail">
+            <%= if Enum.empty?(@saved_items) do %>
+              <p class="live-ui-ask-sidebar__empty"><%= @empty_saved_label %></p>
+            <% else %>
+              <%= for item <- @saved_items do %>
+                <button
+                  type="button"
+                  class={[
+                    "live-ui-ask-sidebar__item",
+                    "live-ui-ask-sidebar__item--saved",
+                    item_active_class(@active_item_id, item_id(item))
+                  ]}
+                  aria-current={aria_current(@active_item_id, item_id(item))}
+                  title={item_field(item, :title)}
+                  data-live-ui-intent={item_field(item, :on_open_event)}
+                  data-live-ui-value={item_id(item)}
+                  data-item-id={item_id(item)}
+                >
+                  <span
+                    class="live-ui-ask-sidebar__item-glyph live-ui-ask-sidebar__item-glyph--star"
+                    aria-hidden="true"
+                  >
+                    &#x2605;
+                  </span>
+                  <span class="live-ui-ask-sidebar__item-label"><%= item_field(item, :title) %></span>
+                  <span class="live-ui-ask-sidebar__item-meta">
+                    <%= saved_item_meta(item) %>
+                  </span>
+                </button>
+              <% end %>
+            <% end %>
+          </div>
+        </section>
+
+        <%!-- Map jump affordance --%>
+        <div class="live-ui-ask-sidebar__map-jump">
+          <button
+            type="button"
+            class="live-ui-ask-sidebar__map-jump-btn"
+            aria-label="Switch to Map mode"
+            title="Map (&#x2318;2)"
+            data-live-ui-intent={@on_map_jump_event}
+            data-live-ui-value="map"
+            data-sidebar-id={@sidebar_id}
+          >
+            <span class="live-ui-ask-sidebar__map-jump-glyph" aria-hidden="true">&#x25BE;</span>
+            <span class="live-ui-ask-sidebar__map-jump-label">Map</span>
+            <%= if @blocker_count > 0 do %>
+              <span
+                class="live-ui-ask-sidebar__blocker-badge"
+                aria-label={"#{@blocker_count} blockers"}
+              >
+                <%= @blocker_count %>
+              </span>
+            <% end %>
+          </button>
+        </div>
+
+      </div>
+    </aside>
+    """
+  end
+
+  # ---------------------------------------------------------------------------
+  # Private helpers
+  # ---------------------------------------------------------------------------
+
+  defp item_id(item) when is_map(item) do
+    Map.get(item, :id) || Map.get(item, "id") || ""
+  end
+
+  defp item_field(item, key) when is_map(item) do
+    Map.get(item, key) || Map.get(item, Atom.to_string(key))
+  end
+
+  defp item_active_class(nil, _item_id), do: nil
+
+  defp item_active_class(active_id, item_id) when active_id == item_id,
+    do: "live-ui-ask-sidebar__item--active"
+
+  defp item_active_class(_active_id, _item_id), do: nil
+
+  defp aria_current(nil, _item_id), do: "false"
+  defp aria_current(active_id, item_id) when active_id == item_id, do: "true"
+  defp aria_current(_active_id, _item_id), do: "false"
+
+  defp item_status_running?(item) do
+    item_field(item, :status) == :running
+  end
+
+  defp saved_item_meta(item) do
+    cadence = item_field(item, :cadence)
+    last_run_at = item_field(item, :last_run_at)
+
+    cond do
+      is_binary(cadence) and cadence != "" -> cadence
+      last_run_at != nil -> relative_time(last_run_at)
+      true -> ""
+    end
+  end
+
+  defp relative_time(%DateTime{} = dt) do
+    now = DateTime.utc_now()
+    diff_seconds = DateTime.diff(now, dt, :second)
+
+    cond do
+      diff_seconds < 60 -> "just now"
+      diff_seconds < 3600 -> "#{div(diff_seconds, 60)}m ago"
+      diff_seconds < 86_400 -> "#{div(diff_seconds, 3600)}h ago"
+      diff_seconds < 604_800 -> "#{div(diff_seconds, 86_400)}d ago"
+      true -> "#{div(diff_seconds, 604_800)}w ago"
+    end
+  end
+
+  defp relative_time(_other), do: ""
+end
diff --git a/packages/live_ui/test/live_ui/widgets/ask_sidebar_test.exs b/packages/live_ui/test/live_ui/widgets/ask_sidebar_test.exs
new file mode 100644
index 00000000..a94f1aae
--- /dev/null
+++ b/packages/live_ui/test/live_ui/widgets/ask_sidebar_test.exs
@@ -0,0 +1,465 @@
+defmodule LiveUi.Widgets.AskSidebarTest do
+  use ExUnit.Case, async: true
+
+  import Phoenix.LiveViewTest
+
+  alias LiveUi.Component
+
+  # ---------------------------------------------------------------------------
+  # Component metadata
+  # ---------------------------------------------------------------------------
+
+  describe "component metadata" do
+    test "has the ask_sidebar name" do
+      metadata = Component.metadata(LiveUi.Widgets.AskSidebar)
+      assert metadata.name == :ask_sidebar
+    end
+
+    test "is in the overlay family" do
+      metadata = Component.metadata(LiveUi.Widgets.AskSidebar)
+      assert metadata.family == :overlay
+    end
+
+    test "is mountable" do
+      metadata = Component.metadata(LiveUi.Widgets.AskSidebar)
+      assert metadata.mountable?
+    end
+
+    test "declares click events" do
+      metadata = Component.metadata(LiveUi.Widgets.AskSidebar)
+      assert :click in metadata.events
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Render: structural attributes
+  # ---------------------------------------------------------------------------
+
+  describe "render/1 structural HTML" do
+    test "renders with data-live-ui-widget=ask-sidebar" do
+      html = render_empty()
+      assert html =~ ~s(data-live-ui-widget="ask-sidebar")
+    end
+
+    test "renders with data-sidebar-id" do
+      html = render_empty()
+      assert html =~ ~s(data-sidebar-id="sb-main")
+    end
+
+    test "renders aside element with aria-label=Ask sidebar" do
+      html = render_empty()
+      assert html =~ ~s(aria-label="Ask sidebar")
+    end
+
+    test "renders scroll wrapper" do
+      html = render_empty()
+      assert html =~ "live-ui-ask-sidebar__scroll"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Render: Recent rail
+  # ---------------------------------------------------------------------------
+
+  describe "render/1 Recent rail" do
+    test "renders Recent section with scoped heading id" do
+      html = render_empty()
+      assert html =~ ~s(id="ask-recent-h-sb-main")
+      assert html =~ "Recent"
+    end
+
+    test "renders section with aria-labelledby pointing to heading" do
+      html = render_empty()
+      assert html =~ ~s(aria-labelledby="ask-recent-h-sb-main")
+    end
+
+    test "renders empty label when no recent items" do
+      html = render_empty()
+      assert html =~ "No recent queries"
+    end
+
+    test "renders recent items" do
+      now = DateTime.utc_now()
+
+      html =
+        render_with_recent([
+          %{
+            id: "r1",
+            query: "show blockers",
+            last_run_at: now,
+            status: :done,
+            on_open_event: "open"
+          }
+        ])
+
+      assert html =~ "show blockers"
+    end
+
+    test "renders data-item-id on recent item buttons" do
+      now = DateTime.utc_now()
+
+      html =
+        render_with_recent([
+          %{id: "r1", query: "q1", last_run_at: now, status: :done, on_open_event: "open"}
+        ])
+
+      assert html =~ ~s(data-item-id="r1")
+    end
+
+    test "caps recent items at 10" do
+      now = DateTime.utc_now()
+
+      items =
+        for i <- 1..15,
+            do: %{
+              id: "r#{i}",
+              query: "query #{i}",
+              last_run_at: now,
+              status: :done,
+              on_open_event: "open"
+            }
+
+      html = render_with_recent(items)
+      # item 11 through 15 should not appear
+      refute html =~ "query 11"
+      assert html =~ "query 10"
+    end
+
+    test "renders see-all button when recent > 6 and on_see_all_event provided" do
+      now = DateTime.utc_now()
+
+      items =
+        for i <- 1..7,
+            do: %{
+              id: "r#{i}",
+              query: "q#{i}",
+              last_run_at: now,
+              status: :done,
+              on_open_event: "open"
+            }
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          recent_items: items,
+          on_see_all_event: "see_all"
+        })
+
+      assert html =~ "see all"
+      assert html =~ ~s(data-live-ui-intent="see_all")
+    end
+
+    test "does NOT render see-all when recent <= 6" do
+      now = DateTime.utc_now()
+
+      items =
+        for i <- 1..6,
+            do: %{
+              id: "r#{i}",
+              query: "q#{i}",
+              last_run_at: now,
+              status: :done,
+              on_open_event: "open"
+            }
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          recent_items: items,
+          on_see_all_event: "see_all"
+        })
+
+      refute html =~ "see all"
+    end
+
+    test "does NOT render see-all when on_see_all_event is nil" do
+      now = DateTime.utc_now()
+
+      items =
+        for i <- 1..8,
+            do: %{
+              id: "r#{i}",
+              query: "q#{i}",
+              last_run_at: now,
+              status: :done,
+              on_open_event: "open"
+            }
+
+      html = render_with_recent(items)
+      refute html =~ "see all"
+    end
+
+    test "recent item with status :running renders running status indicator" do
+      now = DateTime.utc_now()
+
+      html =
+        render_with_recent([
+          %{
+            id: "r1",
+            query: "running q",
+            last_run_at: now,
+            status: :running,
+            on_open_event: "open"
+          }
+        ])
+
+      assert html =~ "live-ui-ask-sidebar__status-running"
+      assert html =~ ~s(aria-label="running")
+    end
+
+    test "recent item without :running status does NOT render status indicator" do
+      now = DateTime.utc_now()
+
+      html =
+        render_with_recent([
+          %{id: "r1", query: "done q", last_run_at: now, status: :done, on_open_event: "open"}
+        ])
+
+      refute html =~ "live-ui-ask-sidebar__status-running"
+    end
+
+    test "uses custom empty_recent_label" do
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          empty_recent_label: "Nothing yet"
+        })
+
+      assert html =~ "Nothing yet"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Render: Saved rail
+  # ---------------------------------------------------------------------------
+
+  describe "render/1 Saved rail" do
+    test "renders Saved section with scoped heading id" do
+      html = render_empty()
+      assert html =~ ~s(id="ask-saved-h-sb-main")
+      assert html =~ "Saved"
+    end
+
+    test "renders empty label when no saved items" do
+      html = render_empty()
+      assert html =~ "No saved queries yet"
+    end
+
+    test "renders saved items with star glyph" do
+      html =
+        render_with_saved([
+          %{id: "s1", title: "Weekly blockers", query: "q", on_open_event: "open"}
+        ])
+
+      assert html =~ "Weekly blockers"
+      assert html =~ "&#x2605;"
+    end
+
+    test "renders data-item-id on saved item buttons" do
+      html = render_with_saved([%{id: "s1", title: "T1", query: "q", on_open_event: "open"}])
+      assert html =~ ~s(data-item-id="s1")
+    end
+
+    test "renders + new button when on_new_saved_event provided" do
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          on_new_saved_event: "new_saved"
+        })
+
+      assert html =~ "+ new"
+      assert html =~ ~s(data-live-ui-intent="new_saved")
+    end
+
+    test "does NOT render + new button when on_new_saved_event is nil" do
+      html = render_empty()
+      refute html =~ "+ new"
+    end
+
+    test "saved item uses cadence when present" do
+      html =
+        render_with_saved([
+          %{id: "s1", title: "T1", query: "q", cadence: "weekly", on_open_event: "open"}
+        ])
+
+      assert html =~ "weekly"
+    end
+
+    test "saved item falls back to relative_time when no cadence" do
+      now = DateTime.utc_now()
+
+      html =
+        render_with_saved([
+          %{id: "s1", title: "T1", query: "q", last_run_at: now, on_open_event: "open"}
+        ])
+
+      assert html =~ "just now"
+    end
+
+    test "uses custom empty_saved_label" do
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          empty_saved_label: "No saves yet"
+        })
+
+      assert html =~ "No saves yet"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Render: active item selection
+  # ---------------------------------------------------------------------------
+
+  describe "render/1 active item selection" do
+    test "active recent item has --active class" do
+      now = DateTime.utc_now()
+      items = [%{id: "r1", query: "q1", last_run_at: now, status: :done, on_open_event: "open"}]
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          recent_items: items,
+          active_item_id: "r1"
+        })
+
+      assert html =~ "live-ui-ask-sidebar__item--active"
+    end
+
+    test "active recent item has aria-current=true" do
+      now = DateTime.utc_now()
+      items = [%{id: "r1", query: "q1", last_run_at: now, status: :done, on_open_event: "open"}]
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          recent_items: items,
+          active_item_id: "r1"
+        })
+
+      assert html =~ ~s(aria-current="true")
+    end
+
+    test "inactive items have aria-current=false" do
+      now = DateTime.utc_now()
+      items = [%{id: "r1", query: "q1", last_run_at: now, status: :done, on_open_event: "open"}]
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          recent_items: items,
+          active_item_id: "r99"
+        })
+
+      assert html =~ ~s(aria-current="false")
+      refute html =~ "live-ui-ask-sidebar__item--active"
+    end
+
+    test "active saved item has --active class" do
+      items = [%{id: "s1", title: "T1", query: "q", on_open_event: "open"}]
+
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          saved_items: items,
+          active_item_id: "s1"
+        })
+
+      assert html =~ "live-ui-ask-sidebar__item--active"
+      assert html =~ ~s(aria-current="true")
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Render: Map jump affordance
+  # ---------------------------------------------------------------------------
+
+  describe "render/1 Map jump affordance" do
+    test "renders Map jump button with aria-label" do
+      html = render_empty()
+      assert html =~ ~s(aria-label="Switch to Map mode")
+    end
+
+    test "map jump button carries on_map_jump_event as data-live-ui-intent" do
+      html = render_empty()
+      assert html =~ ~s(data-live-ui-intent="map_jump")
+    end
+
+    test "map jump button has data-live-ui-value=map" do
+      html = render_empty()
+      assert html =~ ~s(data-live-ui-value="map")
+    end
+
+    test "renders Map label" do
+      html = render_empty()
+      assert html =~ "live-ui-ask-sidebar__map-jump-label"
+    end
+
+    test "renders blocker badge when blocker_count > 0" do
+      html =
+        render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+          id: "sb-test",
+          sidebar_id: "sb-main",
+          on_map_jump_event: "map_jump",
+          blocker_count: 4
+        })
+
+      assert html =~ "live-ui-ask-sidebar__blocker-badge"
+      assert html =~ ~s(aria-label="4 blockers")
+      assert html =~ "4"
+    end
+
+    test "does NOT render blocker badge when blocker_count is 0" do
+      html = render_empty()
+      refute html =~ "live-ui-ask-sidebar__blocker-badge"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Helpers
+  # ---------------------------------------------------------------------------
+
+  defp render_empty do
+    render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+      id: "sb-test",
+      sidebar_id: "sb-main",
+      on_map_jump_event: "map_jump"
+    })
+  end
+
+  defp render_with_recent(items) do
+    render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+      id: "sb-test",
+      sidebar_id: "sb-main",
+      on_map_jump_event: "map_jump",
+      recent_items: items
+    })
+  end
+
+  defp render_with_saved(items) do
+    render_component(&LiveUi.Widgets.AskSidebar.component/1, %{
+      id: "sb-test",
+      sidebar_id: "sb-main",
+      on_map_jump_event: "map_jump",
+      saved_items: items
+    })
+  end
+end

From 32fdeb7cb753b95abcacb9b84dde05d2304c9323 Mon Sep 17 00:00:00 2001
From: Matt de Courcelle <mjdecour@gmail.com>
Date: Mon, 18 May 2026 13:05:59 -0500
Subject: [PATCH 2/2] align ask_sidebar canonical integration footprint

Apply registry-threading discipline per the updated widget skill
(project-ariston PR #62 + memory entry [[new-canonical-widget-needs-
registry-threading]]). Mirrors Pascal's a902750 (PresenceDot) pattern.

Touch points (delta): widgets aggregation (overlay.ex) + both adapters
(iur_adapter + live_ui_adapter) + multi-layer tests (renderer, iur_adapter,
live_ui_adapter).

Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
---
 lib/ash_ui/rendering/iur_adapter.ex           | 25 +++++
 lib/ash_ui/rendering/live_ui_adapter.ex       | 95 +++++++++++++++++++
 .../live_ui/lib/live_ui/widgets/overlay.ex    |  4 +-
 .../live_ui/test/live_ui/renderer_test.exs    | 40 ++++++++
 test/ash_ui/rendering/iur_adapter_test.exs    | 49 ++++++++++
 .../ash_ui/rendering/live_ui_adapter_test.exs | 56 +++++++++++
 6 files changed, 268 insertions(+), 1 deletion(-)

diff --git a/lib/ash_ui/rendering/iur_adapter.ex b/lib/ash_ui/rendering/iur_adapter.ex
index 0b263d90..fd2a6b3e 100644
--- a/lib/ash_ui/rendering/iur_adapter.ex
+++ b/lib/ash_ui/rendering/iur_adapter.ex
@@ -624,6 +624,31 @@ defmodule AshUI.Rendering.IURAdapter do
   defp base_attributes(:command_palette, props),
     do: %{command_palette: Map.drop(props, attachment_prop_keys())}
 
+  defp base_attributes(:ask_sidebar = kind, props) do
+    component_attributes(
+      kind,
+      :layer_shell_and_callout,
+      %{
+        ask_sidebar:
+          compact_map(%{
+            sidebar_id: first_present(props, [:sidebar_id, :id_key]),
+            on_map_jump_event: first_present(props, [:on_map_jump_event, :map_jump_event]),
+            recent_items: fetch(props, :recent_items, []),
+            saved_items: fetch(props, :saved_items, []),
+            blocker_count: fetch(props, :blocker_count, 0),
+            empty_recent_label:
+              first_present(props, [:empty_recent_label]) || "No recent queries",
+            empty_saved_label:
+              first_present(props, [:empty_saved_label]) || "No saved queries yet"
+          })
+          |> maybe_put(:active_item_id, first_present(props, [:active_item_id]))
+          |> maybe_put(:on_new_saved_event, first_present(props, [:on_new_saved_event]))
+          |> maybe_put(:on_see_all_event, first_present(props, [:on_see_all_event]))
+      },
+      props
+    )
+  end
+
   defp base_attributes(:list, props), do: %{list: Map.drop(props, attachment_prop_keys())}
   defp base_attributes(:table, props), do: %{table: Map.drop(props, attachment_prop_keys())}
   defp base_attributes(:tree_view, props), do: %{tree: Map.drop(props, attachment_prop_keys())}
diff --git a/lib/ash_ui/rendering/live_ui_adapter.ex b/lib/ash_ui/rendering/live_ui_adapter.ex
index abdb81b8..d8b5d197 100644
--- a/lib/ash_ui/rendering/live_ui_adapter.ex
+++ b/lib/ash_ui/rendering/live_ui_adapter.ex
@@ -670,6 +670,101 @@ defmodule AshUI.Rendering.LiveUIAdapter do
     """
   end
 
+  defp generate_heex(%{"type" => "ask_sidebar"} = iur, _opts) do
+    props = iur["props"] || %{}
+    sidebar_id = text_prop(props, ["sidebar_id"], "ask-sidebar")
+    on_map_jump_event = text_prop(props, ["on_map_jump_event"], "")
+    recent_items = prop(props, "recent_items", [])
+    saved_items = prop(props, "saved_items", [])
+    active_item_id = prop(props, "active_item_id", nil)
+    on_new_saved_event = text_prop(props, ["on_new_saved_event"], nil)
+    on_see_all_event = text_prop(props, ["on_see_all_event"], nil)
+    empty_recent_label = escaped_text_prop(props, ["empty_recent_label"], "No recent queries")
+    empty_saved_label = escaped_text_prop(props, ["empty_saved_label"], "No saved queries yet")
+    blocker_count_raw = prop(props, "blocker_count", 0)
+
+    blocker_count =
+      case blocker_count_raw do
+        n when is_integer(n) -> n
+        n when is_float(n) -> round(n)
+        s when is_binary(s) -> String.to_integer(s)
+        _ -> 0
+      end
+
+    recent_items_html =
+      Enum.map_join(recent_items, "\n", fn item ->
+        item = normalize_item(item)
+        item_id = text_prop(item, ["id", "item_id"], "")
+        item_label = escaped_text_prop(item, ["label", "title"], "")
+        is_active = active_item_id != nil and item_id == active_item_id
+
+        active_attr =
+          if is_active,
+            do:
+              " aria-current=\"true\" class=\"ash-ask-sidebar__item ash-ask-sidebar__item--active\"",
+            else: " class=\"ash-ask-sidebar__item\""
+
+        "<li#{active_attr} data-item-id=\"#{html_escape(item_id)}\">#{item_label}</li>"
+      end)
+
+    saved_items_html =
+      Enum.map_join(saved_items, "\n", fn item ->
+        item = normalize_item(item)
+        item_id = text_prop(item, ["id", "item_id"], "")
+        item_label = escaped_text_prop(item, ["label", "title"], "")
+        is_active = active_item_id != nil and item_id == active_item_id
+
+        active_attr =
+          if is_active,
+            do:
+              " aria-current=\"true\" class=\"ash-ask-sidebar__item ash-ask-sidebar__item--active\"",
+            else: " class=\"ash-ask-sidebar__item\""
+
+        "<li#{active_attr} data-item-id=\"#{html_escape(item_id)}\">#{item_label}</li>"
+      end)
+
+    see_all_btn =
+      if on_see_all_event && on_see_all_event != "",
+        do:
+          "<button class=\"ash-ask-sidebar__see-all\" phx-click=\"#{html_escape(on_see_all_event)}\">See all</button>",
+        else: ""
+
+    new_saved_btn =
+      if on_new_saved_event && on_new_saved_event != "",
+        do:
+          "<button class=\"ash-ask-sidebar__new-saved\" phx-click=\"#{html_escape(on_new_saved_event)}\">Save query</button>",
+        else: ""
+
+    map_jump_btn =
+      if on_map_jump_event != "" do
+        badge =
+          if blocker_count > 0,
+            do:
+              "<span class=\"ash-ask-sidebar__blocker-badge\" aria-label=\"#{blocker_count} blockers\">#{blocker_count}</span>",
+            else: ""
+
+        "<button class=\"ash-ask-sidebar__map-jump\" phx-click=\"#{html_escape(on_map_jump_event)}\">Map#{badge}</button>"
+      else
+        ""
+      end
+
+    """
+    <aside class="#{css_classes(["ash-ask-sidebar", prop_class(iur)])}" data-live-ui-widget="ask-sidebar" data-sidebar-id="#{html_escape(sidebar_id)}"#{style_attr(prop_style(iur))}>
+      <section class="ash-ask-sidebar__recent">
+        <h2 class="ash-ask-sidebar__section-title">Recent</h2>
+        #{see_all_btn}
+        #{if recent_items == [], do: "<p class=\"ash-ask-sidebar__empty\">#{empty_recent_label}</p>", else: "<ul class=\"ash-ask-sidebar__list\">#{recent_items_html}</ul>"}
+      </section>
+      <section class="ash-ask-sidebar__saved">
+        <h2 class="ash-ask-sidebar__section-title">Saved</h2>
+        #{new_saved_btn}
+        #{if saved_items == [], do: "<p class=\"ash-ask-sidebar__empty\">#{empty_saved_label}</p>", else: "<ul class=\"ash-ask-sidebar__list\">#{saved_items_html}</ul>"}
+      </section>
+      #{map_jump_btn}
+    </aside>
+    """
+  end
+
   defp generate_heex(%{"type" => "sticky_frosted_header"} = iur, opts) do
     props = iur["props"] || %{}
     title = escaped_text_prop(props, ["title", "label"], "")
diff --git a/packages/live_ui/lib/live_ui/widgets/overlay.ex b/packages/live_ui/lib/live_ui/widgets/overlay.ex
index e16b0239..e2057b76 100644
--- a/packages/live_ui/lib/live_ui/widgets/overlay.ex
+++ b/packages/live_ui/lib/live_ui/widgets/overlay.ex
@@ -8,7 +8,9 @@ defmodule LiveUi.Widgets.Overlay do
     LiveUi.Widgets.Dialog,
     LiveUi.Widgets.AlertDialog,
     LiveUi.Widgets.ContextMenu,
-    LiveUi.Widgets.Toast
+    LiveUi.Widgets.Toast,
+    LiveUi.Widgets.AskSidebar,
+    LiveUi.Widgets.ComposerInlineAsk
   ]
 
   @spec modules() :: [module()]
diff --git a/packages/live_ui/test/live_ui/renderer_test.exs b/packages/live_ui/test/live_ui/renderer_test.exs
index e4d0692d..536ff1a5 100644
--- a/packages/live_ui/test/live_ui/renderer_test.exs
+++ b/packages/live_ui/test/live_ui/renderer_test.exs
@@ -341,4 +341,44 @@ defmodule LiveUi.RendererTest do
     assert html =~ ~s(name="element_id" value="profile-name")
     assert html =~ ~s(name="widget" value="text_input")
   end
+
+  test "renderer maps canonical ask_sidebar through the dedicated AskSidebar component" do
+    element =
+      Components.ask_sidebar(
+        id: "ask-sb-test",
+        sidebar_id: "main-sidebar",
+        on_map_jump_event: "open_map",
+        recent_items: [
+          %{id: "r1", query: "Recent query"},
+          %{id: "r2", query: "Another query"}
+        ],
+        saved_items: [],
+        blocker_count: 1
+      )
+
+    html = render_component(&LiveUi.Renderer.render/1, %{element: element})
+
+    assert html =~ ~s(data-live-ui-widget="ask-sidebar")
+    assert html =~ ~s(data-sidebar-id="main-sidebar")
+  end
+
+  test "renderer preserves ask_sidebar active item and rails" do
+    element =
+      Components.ask_sidebar(
+        id: "ask-sb-active",
+        sidebar_id: "rail-sidebar",
+        on_map_jump_event: "jump",
+        recent_items: [%{id: "r1", query: "First query"}],
+        saved_items: [%{id: "s1", title: "Pinned search"}],
+        active_item_id: "r1",
+        blocker_count: 0
+      )
+
+    html = render_component(&LiveUi.Renderer.render/1, %{element: element})
+
+    assert html =~ ~s(data-live-ui-widget="ask-sidebar")
+    assert html =~ ~s(data-item-id="r1")
+    assert html =~ ~s(data-item-id="s1")
+    assert html =~ ~s(aria-current="true")
+  end
 end
diff --git a/test/ash_ui/rendering/iur_adapter_test.exs b/test/ash_ui/rendering/iur_adapter_test.exs
index f41b7f35..bf9c5d09 100644
--- a/test/ash_ui/rendering/iur_adapter_test.exs
+++ b/test/ash_ui/rendering/iur_adapter_test.exs
@@ -219,6 +219,55 @@ defmodule AshUI.Rendering.IURAdapterTest do
     end
   end
 
+  describe "ask_sidebar IUR routing" do
+    test "routes ask_sidebar kind through layer_shell_and_callout family" do
+      ash_iur =
+        IUR.new(:screen,
+          id: "ask-sidebar-screen",
+          name: "ask_sidebar_screen",
+          attributes: %{},
+          children: [
+            IUR.new(:ask_sidebar,
+              id: "ask-sb-1",
+              props: %{
+                "sidebar_id" => "main-ask-sidebar",
+                "on_map_jump_event" => "switch_to_map"
+              }
+            )
+          ]
+        )
+
+      assert {:ok, canonical} = IURAdapter.to_canonical(ash_iur)
+      [child] = canonical.children
+      assert child.element.kind == :ask_sidebar
+      assert child.element.type == :widget
+      assert child.element.attributes.component.family == :layer_shell_and_callout
+    end
+
+    test "preserves sidebar_id in canonical ask_sidebar attributes" do
+      ash_iur =
+        IUR.new(:screen,
+          id: "ask-sidebar-screen-2",
+          name: "ask_sidebar_screen",
+          attributes: %{},
+          children: [
+            IUR.new(:ask_sidebar,
+              id: "ask-sb-2",
+              props: %{
+                "sidebar_id" => "workspace-ask-sidebar",
+                "on_map_jump_event" => "goto_map"
+              }
+            )
+          ]
+        )
+
+      assert {:ok, canonical} = IURAdapter.to_canonical(ash_iur)
+      [child] = canonical.children
+      assert child.element.attributes.ask_sidebar.sidebar_id == "workspace-ask-sidebar"
+      assert child.element.attributes.ask_sidebar.on_map_jump_event == "goto_map"
+    end
+  end
+
   defp assert_valid_canonical(canonical) do
     assert {:ok, %UnifiedIUR.Element{} = normalized} = UnifiedIUR.Normalize.element(canonical)
     assert :ok = UnifiedIUR.Validate.element(normalized)
diff --git a/test/ash_ui/rendering/live_ui_adapter_test.exs b/test/ash_ui/rendering/live_ui_adapter_test.exs
index e960b00c..4c747812 100644
--- a/test/ash_ui/rendering/live_ui_adapter_test.exs
+++ b/test/ash_ui/rendering/live_ui_adapter_test.exs
@@ -1155,4 +1155,60 @@ defmodule AshUI.Rendering.LiveUIAdapterTest do
       "metadata" => %{}
     }
   end
+
+  describe "ask_sidebar adapter dispatch" do
+    test "generates dedicated ask_sidebar markup" do
+      canonical_iur = %{
+        "type" => "ask_sidebar",
+        "id" => "sidebar-1",
+        "props" => %{
+          "sidebar_id" => "main-sidebar",
+          "on_map_jump_event" => "open_map",
+          "recent_items" => [
+            %{"id" => "r1", "label" => "Recent query 1"}
+          ],
+          "saved_items" => [],
+          "blocker_count" => 2,
+          "empty_saved_label" => "Nothing saved yet"
+        },
+        "children" => [],
+        "metadata" => %{}
+      }
+
+      assert {:ok, html} = LiveUIAdapter.render(canonical_iur)
+      assert html =~ ~s(data-live-ui-widget="ask-sidebar")
+      assert html =~ ~s(data-sidebar-id="main-sidebar")
+      assert html =~ "ash-ask-sidebar"
+      assert html =~ "ash-ask-sidebar__recent"
+      assert html =~ "ash-ask-sidebar__saved"
+      assert html =~ "Recent query 1"
+      assert html =~ "ash-ask-sidebar__blocker-badge"
+      assert html =~ "Nothing saved yet"
+    end
+
+    test "ask_sidebar adapter preserves active item aria-current" do
+      canonical_iur = %{
+        "type" => "ask_sidebar",
+        "id" => "sidebar-2",
+        "props" => %{
+          "sidebar_id" => "workspace-sidebar",
+          "on_map_jump_event" => "",
+          "recent_items" => [
+            %{"id" => "item-a", "label" => "Alpha"},
+            %{"id" => "item-b", "label" => "Beta"}
+          ],
+          "saved_items" => [],
+          "active_item_id" => "item-b",
+          "blocker_count" => 0
+        },
+        "children" => [],
+        "metadata" => %{}
+      }
+
+      assert {:ok, html} = LiveUIAdapter.render(canonical_iur)
+      assert html =~ ~s(aria-current="true")
+      assert html =~ "ash-ask-sidebar__item--active"
+      assert html =~ "Beta"
+    end
+  end
 end