defmodule PlausibleWeb.Live.Components.ComboBox do
@moduledoc """
Phoenix LiveComponent for a combobox UI element with search and selection
functionality.
The component allows users to select an option from a list of options,
which can be searched by typing in the input field.
The component renders an input field with a dropdown anchor and a
hidden input field for submitting the selected value.
The number of options displayed in the dropdown is limited to 15
by default but can be customized. When a user types into the input
field, the component searches the available options and provides
suggestions based on the input.
Any function can be supplied via `suggest_fun` attribute
- see the provided `ComboBox.StaticSearch`.
In most cases the `suggest_fun` runs an operation that could be deferred,
so by default, the `async={true}` attr calls it in a background Task
and updates the suggestions asynchronously. This way, you can render
the component without having to wait for suggestions to load.
If you explicitly need to make the operation sychronous, you may
pass `async={false}` option.
If your initial `options` are not provided up-front at initial render,
lack of `options` attr value combined with `async=true` calls the
`suggest_fun.("", [])` asynchronously - that special clause can be used
to provide the initial set of suggestions updated right after the initial render.
To simplify integration testing, suggestions load up synchronously during
tests. This lets you skip waiting for suggestions messages
to arrive. The asynchronous behaviour alone is already tested in
ComboBox own test suite, so there is no need for additional
verification.
"""
use Phoenix.LiveComponent
alias Phoenix.LiveView.JS
@default_suggestions_limit 15
def update(assigns, socket) do
socket = assign(socket, assigns)
socket =
if connected?(socket) do
socket
|> assign_options()
|> assign_suggestions()
else
socket
end
{:ok, socket}
end
attr(:placeholder, :string, default: "Select option or search by typing")
attr(:id, :any, required: true)
attr(:options, :list, default: [])
attr(:submit_name, :string, required: true)
attr(:display_value, :string, default: "")
attr(:submit_value, :string, default: "")
attr(:suggest_fun, :any, required: true)
attr(:suggestions_limit, :integer)
attr(:class, :string, default: "")
attr(:required, :boolean, default: false)
attr(:creatable, :boolean, default: false)
attr(:errors, :list, default: [])
attr(:async, :boolean, default: Mix.env() != :test)
def render(assigns) do
assigns =
assign_new(assigns, :suggestions, fn ->
Enum.take(assigns.options, suggestions_limit(assigns))
end)
~H"""
"""
end
attr(:id, :any, required: true)
def dropdown_anchor(assigns) do
~H"""
"""
end
attr(:ref, :string, required: true)
attr(:suggestions, :list, default: [])
attr(:suggest_fun, :any, required: true)
attr(:target, :any)
attr(:creatable, :boolean, required: true)
attr(:display_value, :string, required: true)
def dropdown(assigns) do
~H"""
<.option
:if={display_creatable_option?(assigns)}
idx={0}
submit_value={@display_value}
display_value={@display_value}
target={@target}
ref={@ref}
creatable
/>
<.option
:for={
{{submit_value, display_value}, idx} <-
Enum.with_index(
@suggestions,
fn {option_value, option}, idx -> {{option_value, to_string(option)}, idx + 1} end
)
}
:if={@suggestions != []}
idx={idx}
submit_value={submit_value}
display_value={display_value}
target={@target}
ref={@ref}
/>
No matches found. Try searching for something different.
Create an item by typing.
"""
end
attr(:display_value, :string, required: true)
attr(:submit_value, :string, required: true)
attr(:ref, :string, required: true)
attr(:target, :any)
attr(:idx, :integer, required: true)
attr(:creatable, :boolean, default: false)
def option(assigns) do
assigns = assign(assigns, :suggestions_limit, suggestions_limit(assigns))
~H"""
<%= if @creatable do %>
Create "<%= @display_value %>"
<% else %>
<%= @display_value %>
<% end %>
Max results reached. Refine your search by typing.
"""
end
def select_option(js \\ %JS{}, _id, submit_value, display_value) do
js
|> JS.push("select-option",
value: %{"submit-value" => submit_value, "display-value" => display_value}
)
end
def handle_event(
"select-option",
%{"submit-value" => submit_value, "display-value" => display_value},
socket
) do
socket = do_select(socket, submit_value, display_value)
{:noreply, socket}
end
def handle_event(
"search",
%{"_target" => [target]} = params,
%{assigns: %{options: options}} = socket
) do
input = params[target]
input_len = input |> String.trim() |> String.length()
socket =
if socket.assigns[:creatable] do
assign(socket, display_value: input, submit_value: input)
else
socket
end
suggestions =
if input_len > 0 do
run_suggest_fun(input, options, socket.assigns, :suggestions)
else
options
end
|> Enum.take(suggestions_limit(socket.assigns))
{:noreply, assign(socket, %{suggestions: suggestions})}
end
defp do_select(socket, submit_value, display_value) do
id = socket.assigns.id
socket =
socket
|> push_event("update-value", %{id: id, value: display_value, fire: false})
|> push_event("update-value", %{id: "submit-#{id}", value: submit_value, fire: true})
|> assign(:display_value, display_value)
|> assign(:submit_value, submit_value)
send(
self(),
{:selection_made,
%{
by: id,
submit_value: submit_value
}}
)
socket
end
defp suggestions_limit(assigns) do
Map.get(assigns, :suggestions_limit, @default_suggestions_limit)
end
defp display_creatable_option?(assigns) do
empty_input? = String.length(assigns.display_value) == 0
input_matches_suggestion? =
Enum.any?(assigns.suggestions, fn {suggestion, _} -> assigns.display_value == suggestion end)
assigns.creatable && not empty_input? && not input_matches_suggestion?
end
defp assign_options(socket) do
assign_new(socket, :options, fn ->
run_suggest_fun("", [], socket.assigns, :options)
end)
end
defp assign_suggestions(socket) do
if socket.assigns[:suggestions] do
assign(
socket,
suggestions: Enum.take(socket.assigns.suggestions, suggestions_limit(socket.assigns))
)
else
socket
end
end
defp run_suggest_fun(input, options, %{id: id, suggest_fun: fun} = assigns, key_to_update) do
if assigns[:async] do
pid = self()
Task.start(fn ->
result = fun.(input, options)
send_update(
pid,
__MODULE__,
Keyword.new([
{:id, id},
{key_to_update, result}
])
)
end)
# This prevents flashing the suggestions container
# before the update is received on a subsequent render
assigns[key_to_update] || []
else
fun.(input, options)
end
end
end