Address PR #1749 review — docs fixes and small hygiene

Bundles: B6, M8, M9, m11, m12 (docs); m2, m3, m7, m8, m9, m10 (code hygiene)

Author: Flo0807

guides/get_started/installation.md

@@ -174,6 +174,8 @@ To get you started quickly, we provide a layout component you can copy & paste i
 </Backpex.HTML.Layout.app_shell>
 ```
 
+These assigns (`@current_theme`, `@sidebar_open`, `@sidebar_section_states`) are populated by `Backpex.InitAssigns` — see [Add resource routes](#add-resource-routes) below for setup.
+
 In addition we recommend to add a bodyless function definition and to configure declarative assigns for your layout component.
 
 ```elixir

guides/live_resource/user-preferences.md

@@ -290,13 +290,21 @@ end
 
 defmodule MyApp.Preferences.UserPreference do
   use Ecto.Schema
+  import Ecto.Changeset
 
   schema "backpex_user_preferences" do
     field :user_id, :integer
     field :key,     :string
     field :value,   :map, default: %{}
     timestamps(type: :utc_datetime_usec)
   end
+
+  def changeset(user_preference, attrs) do
+    user_preference
+    |> cast(attrs, [:user_id, :key, :value])
+    |> validate_required([:user_id, :key, :value])
+    |> unique_constraint([:user_id, :key])
+  end
 end
 
 defmodule MyApp.Preferences.EctoAdapter do
@@ -339,11 +347,10 @@ defmodule MyApp.Preferences.EctoAdapter do
   def put(%{identity: user_id}, key, value, opts) do
     repo = Keyword.fetch!(opts, :repo)
 
+    attrs = %{user_id: user_id, key: key, value: wrap_value(value)}
+
     %UserPreference{}
-    |> UserPreference.__struct__()
-    |> Map.put(:user_id, user_id)
-    |> Map.put(:key, key)
-    |> Map.put(:value, wrap_value(value))
+    |> UserPreference.changeset(attrs)
     |> repo.insert!(on_conflict: {:replace, [:value, :updated_at]}, conflict_target: [:user_id, :key])
 
     {:ok, [:noop]}
@@ -393,53 +400,11 @@ Use when you already have a user settings table (one row per user) with
 typed JSON columns. Lets each Backpex prefix write into a named column
 rather than a generic rows table.
 
-```elixir
-# Migration: adds JSON columns to an existing user_settings table
-alter table(:user_settings) do
-  add :ordering_preferences,  :map, null: false, default: %{}
-  add :filter_preferences,    :map, null: false, default: %{}
-  add :column_visibility,     :map, null: false, default: %{}
-end
-
-defmodule MyApp.Preferences.EctoAdapter do
-  @behaviour Backpex.Preferences.Adapter
-
-  import Ecto.Query
-  alias MyApp.Settings.UserSettings
-
-  @column_map %{
-    ["resource", _mod, "order"]   => :ordering_preferences,
-    ["resource", _mod, "filters"] => :filter_preferences,
-    ["resource", _mod, "columns"] => :column_visibility
-  }
-
-  @impl true
-  def get(%{identity: :unidentified}, _key, _opts), do: {:ok, :not_found}
-  def get(%{identity: user_id}, key, opts) do
-    repo = Keyword.fetch!(opts, :repo)
-    [_, module_name, _] = segments = Backpex.Preferences.Key.parse(key)
-
-    column = segments_to_column(segments)
-
-    case repo.one(from s in UserSettings, where: s.user_id == ^user_id, select: field(s, ^column)) do
-      nil -> {:ok, :not_found}
-      map -> {:ok, Map.get(map, module_name, :not_found) |> to_ok_not_found()}
-    end
-  end
-
-  # get_map/3, put/4 follow the same "which column?" lookup.
-
-  defp segments_to_column(["resource", _mod, "order"]),   do: :ordering_preferences
-  defp segments_to_column(["resource", _mod, "filters"]), do: :filter_preferences
-  defp segments_to_column(["resource", _mod, "columns"]), do: :column_visibility
-
-  defp to_ok_not_found(:not_found), do: :not_found
-  defp to_ok_not_found(value), do: value
-end
-```
-
-This pattern matches apps that already manage preferences through a
-purpose-shaped settings table; Backpex just becomes another writer.
+When you already have a typed settings table, adapt Recipe A by replacing
+the k/v schema: route each prefix to its own column and dispatch reads and
+writes based on the key's segments. See the
+[ash_backpex](https://github.com/enoonan/ash_backpex) community example for
+a working implementation.
 
 ## Opt-in persistence for ordering, filters, columns
 
@@ -521,7 +486,7 @@ BackpexPreferences.set('custom.dashboard.view_mode', 'list')
 
 ### Writing from the server
 
-From a LiveView `handle_event`, use `Backpex.Preferences.put_async/3`:
+From a LiveView `handle_event`, use `Backpex.Preferences.put_async/4`:
 
 ```elixir
 def handle_event("toggle_view_mode", _params, socket) do
@@ -533,7 +498,7 @@ def handle_event("toggle_view_mode", _params, socket) do
 end
 ```
 
-Under the hood `put_async/3` tries the configured adapter first. When the
+Under the hood `put_async/4` tries the configured adapter first. When the
 adapter is session-backed (no HTTP request in a LiveView event), it falls
 back to a `push_event/3` round-trip so the browser persists via the
 preferences controller on its next paint. DB-backed adapters just write

guides/upgrading/v0.19.md

@@ -85,6 +85,10 @@ The `BackpexSidebarSections` hook has been replaced by `BackpexSidebar`, which n
 
 ## User Preferences System Overhaul
 
+> #### Warning {: .warning}
+>
+> All assigns in this migration fail at render time, not compile time — `@current_theme`, `@sidebar_open`, and `@sidebar_section_states` silently fall back to defaults if missing. After each step below, verify in the browser that the feature works (toggle theme, toggle sidebar, reload page).
+
 This version introduces a unified preference system that eliminates UI flickering. User preferences (theme, sidebar state, column visibility, etc.) are now server-rendered from a configurable storage backend on every request.
 
 Backpex ships with a Phoenix-session adapter out of the box (matches the legacy behavior — no action needed). Route individual prefixes to a per-user database adapter when you outgrow the ~4KB cookie ceiling or need preferences to follow a user across devices. See the [User Preferences guide](../live_resource/user-preferences.md) for adapter recipes and the opt-in persistence flag for ordering / filters / columns.

lib/backpex/controllers/preferences_controller.ex

@@ -22,7 +22,7 @@ defmodule Backpex.PreferencesController do
       ]}
 
   The batch form is **all-or-nothing**: if any adapter refuses a write, no
-  side effects are applied, the response is `200 {ok: false, errors: [...]}`,
+  side effects are applied, the response is `422 {ok: false, errors: [...]}`,
   and the session cookie is left unchanged. A partial-success state for
   preferences is more confusing than a clean failure.
   """
@@ -53,7 +53,7 @@ defmodule Backpex.PreferencesController do
 
       {:error, errors} ->
         conn
-        |> put_status(200)
+        |> put_status(422)
         |> json(%{ok: false, errors: Enum.map(errors, &format_error/1)})
     end
   end

lib/backpex/html/layout.ex

@@ -502,12 +502,14 @@ defmodule Backpex.HTML.Layout do
 
   attr :sidebar_section_states, :map,
     default: %{},
-    doc: "map of section states (populated automatically from assigns if not provided)"
+    doc:
+      "map of section states. Read from the parent's `@sidebar_section_states` assign when not passed explicitly; falls back to `%{}` (all sections open by default)."
 
   slot :inner_block
   slot :label, required: true, doc: "label to be displayed on the section."
 
   def sidebar_section(assigns) do
+    assigns = assign_new(assigns, :sidebar_section_states, fn -> %{} end)
     open = Map.get(assigns.sidebar_section_states, assigns.id, true)
 
     assigns =

lib/backpex/html/resource.ex

@@ -561,7 +561,7 @@ defmodule Backpex.HTML.Resource do
         </span>
       </:trigger>
       <:menu class="min-w-52 max-w-72 p-4">
-        <.toggle_columns_inputs active_fields={@active_fields} live_resource={@live_resource} />
+        <.toggle_columns_inputs active_fields={@active_fields} />
       </:menu>
     </.dropdown>
     """
@@ -573,7 +573,6 @@ defmodule Backpex.HTML.Resource do
   @doc type: :component
 
   attr :active_fields, :list, required: true, doc: "list of active fields to be displayed"
-  attr :live_resource, :atom, required: true, doc: "the live resource"
 
   def toggle_columns_inputs(assigns) do
     ~H"""

lib/backpex/preferences.ex

@@ -59,6 +59,15 @@ defmodule Backpex.Preferences do
     * `:default` — returned when nothing is stored for `key` (default: `nil`).
 
   Extra options are forwarded to the adapter.
+
+  ## Examples
+
+      iex> session = %{"backpex_preferences" => %{"global" => %{"theme" => "dark"}}}
+      iex> Backpex.Preferences.get(session, "global.theme")
+      "dark"
+
+      iex> Backpex.Preferences.get(%{}, "global.theme", default: "light")
+      "light"
   """
   @spec get(Context.t() | map(), String.t(), keyword()) :: term()
   def get(ctx_or_session, key, opts \\ []) do
@@ -81,6 +90,19 @@ defmodule Backpex.Preferences do
 
   Returns `%{}` when nothing is stored, the adapter cannot identify the user,
   or the adapter fails for any other reason.
+
+  ## Examples
+
+      iex> session = %{
+      ...>   "backpex_preferences" => %{
+      ...>     "global" => %{"sidebar_section" => %{"blog" => true, "users" => false}}
+      ...>   }
+      ...> }
+      iex> Backpex.Preferences.get_map(session, "global.sidebar_section")
+      %{"blog" => true, "users" => false}
+
+      iex> Backpex.Preferences.get_map(%{}, "global.sidebar_section")
+      %{}
   """
   @spec get_map(Context.t() | map(), String.t(), keyword()) :: map()
   def get_map(ctx_or_session, prefix, opts \\ []) do
@@ -110,6 +132,19 @@ defmodule Backpex.Preferences do
     * `{:error, reason}` — the adapter refused the write for a non-transport
       reason. Callers typically ignore the failure (preferences are best
       effort) but can surface it if needed.
+
+  ## Examples
+
+  From a Plug controller (session is updated in-place):
+
+      Backpex.Preferences.put_async(conn, "global.theme", "dark")
+      #=> {:ok, %Plug.Conn{}}
+
+  From a LiveView `handle_event` (session adapter returns `:requires_http`,
+  so the dispatcher falls back to a `push_event` for the browser to retry):
+
+      Backpex.Preferences.put_async(socket, "global.theme", "dark")
+      #=> {:ok, %Phoenix.LiveView.Socket{}}
   """
   @spec put_async(Plug.Conn.t() | Phoenix.LiveView.Socket.t(), String.t(), term(), keyword()) ::
           {:ok, Plug.Conn.t() | Phoenix.LiveView.Socket.t()} | {:error, term()}
@@ -148,6 +183,16 @@ defmodule Backpex.Preferences do
   writes under the same session key compose correctly. The caller applies
   the returned effects in order; for `:put_session` effects targeting the
   same key, the last effect holds the fully-merged value.
+
+  ## Examples
+
+      ctx = Backpex.Preferences.Context.from_conn(conn)
+
+      Backpex.Preferences.put_batch(ctx, [
+        {"global.theme", "dark"},
+        {"global.sidebar_open", false}
+      ])
+      #=> {:ok, [{:put_session, "backpex_preferences", %{...}}]}
   """
   @spec put_batch(Context.t(), [{String.t(), term()}], keyword()) ::
           {:ok, [Backpex.Preferences.Adapter.side_effect()]} | {:error, [term()]}

lib/backpex/preferences/key.ex

@@ -21,6 +21,21 @@ defmodule Backpex.Preferences.Key do
   `"resource.Elixir.DemoWeb.PostLive.columns"` splits into five path segments,
   making stored preferences hard to reason about. Switching the whole key to
   colons lets the module live as a single atomic segment.
+
+  ## Separator precedence (read carefully)
+
+  A single `":"` anywhere in the key flips the whole key to colon-split
+  parsing. There is no "mixed" mode. Concretely:
+
+  - `"global.theme"` — no colon → dot-split → `["global", "theme"]`
+  - `"resource:Backpex.Users:columns"` — colon present → colon-split →
+    `["resource", "Backpex.Users", "columns"]`
+  - `"custom.bad:key"` — stray colon wins → colon-split →
+    `["custom.bad", "key"]` (the `.` inside `"custom.bad"` is *not* split)
+
+  The last example is almost certainly not what the caller intended. Prefer
+  `Backpex.Preferences.Key.resource_key/2` when building keys that embed a
+  module name so the colon form is applied deliberately.
   """
 
   @doc """

lib/backpex/preferences/router.ex

@@ -62,6 +62,15 @@ defmodule Backpex.Preferences.Router do
 
   Exposed as a public function so `Backpex.Preferences` and test helpers can
   reuse it without re-implementing the match logic.
+
+  ## Examples
+
+      iex> routes = [
+      ...>   {"global.*", Backpex.Preferences.Adapters.Session, []},
+      ...>   {:default, Backpex.Preferences.Adapters.Session, []}
+      ...> ]
+      iex> Backpex.Preferences.Router.resolve("global.theme", routes)
+      {Backpex.Preferences.Adapters.Session, []}
   """
   @spec resolve(String.t()) :: {module(), keyword()}
   @spec resolve(String.t(), [route()]) :: {module(), keyword()}
@@ -99,12 +108,39 @@ defmodule Backpex.Preferences.Router do
   defp matches?({:default, _module, _opts}, _key), do: true
   defp matches?({pattern, _module, _opts}, key) when is_binary(pattern), do: Key.match?(pattern, key)
 
-  defp specificity({:default, _module, _opts}), do: -1
+  @doc """
+  Returns a tuple representing the specificity of a route pattern.
+
+  The tuple is designed so that `Enum.sort_by/2` (and `Enum.max_by/2`) sort
+  in the correct precedence order: exact-match patterns beat wildcards of
+  the same length, longer patterns beat shorter ones, and `:default` always
+  loses to any named pattern.
 
-  defp specificity({pattern, _module, _opts}) when is_binary(pattern) do
-    case String.split(pattern, ".") do
-      [_single] -> 100
-      segments -> length(segments) * 10 - if(List.last(segments) == "*", do: 1, else: 0)
-    end
+  The exact tuple shape is an implementation detail; rely only on ordering.
+
+  ## Examples
+
+      iex> Backpex.Preferences.Router.specificity({"global.theme", Foo, []}) >
+      ...>   Backpex.Preferences.Router.specificity({"global.*", Foo, []})
+      true
+
+      iex> Backpex.Preferences.Router.specificity({"resource.*", Foo, []}) >
+      ...>   Backpex.Preferences.Router.specificity({:default, Foo, []})
+      true
+  """
+  @spec specificity(route()) :: tuple()
+  def specificity({:default, _module, _opts}), do: {0, 0, 0}
+
+  def specificity({pattern, _module, _opts}) when is_binary(pattern) do
+    segments = String.split(pattern, ".")
+    length = length(segments)
+    exact? = List.last(segments) != "*"
+
+    # Sort order: named patterns beat :default, longer patterns beat shorter,
+    # exact matches beat wildcards at the same depth.
+    {1, length, bool_to_int(exact?)}
   end
+
+  defp bool_to_int(true), do: 1
+  defp bool_to_int(false), do: 0
 end

test/controllers/preferences_controller_test.exs

@@ -130,7 +130,7 @@ defmodule Backpex.PreferencesControllerTest do
       :ok
     end
 
-    test "returns {ok: false, errors: [...]} and leaves the session untouched", %{conn: conn} do
+    test "returns 422 with {ok: false, errors: [...]} and leaves the session untouched", %{conn: conn} do
       params = %{
         "preferences" => [
           %{"key" => "global.theme", "value" => "dark"},
@@ -140,7 +140,7 @@ defmodule Backpex.PreferencesControllerTest do
 
       conn = PreferencesController.update(conn, params)
 
-      assert conn.status == 200
+      assert conn.status == 422
       body = Jason.decode!(conn.resp_body)
       assert body["ok"] == false
       assert [%{"key" => "test.thing", "reason" => _reason}] = body["errors"]