@spec component_tag() :: :option_list

The component tag this widget registers under.

iex> Drafter.Widget.OptionList.component_tag()
:option_list

@spec from_component_opts(
  list() | nil,
  keyword()
) :: Drafter.Widget.props()

Builds the props map for an {:option_list, items, opts} element.

items is used when it is a non-empty list, otherwise opts[:options], defaulting to []. Each entry is normalised: a {label, id} tuple, a plain string used as both id and label, or a map already carrying :id, which keeps its own :selected and :disabled when it has them. The option whose id matches :selected is marked selected.

:on_select and :on_highlight given as atoms are wrapped so the app event carries the option's :id; given as functions they are passed through and receive the whole option map. The emitted :highlighted_index and :classes keys are not read by mount/1.

iex> props = Drafter.Widget.OptionList.from_component_opts([{"A", "a"}, "b"], selected: "b")
iex> props.options
[%{id: "a", label: "A", selected: false, disabled: false}, %{id: "b", label: "b", selected: true, disabled: false}]

iex> props = Drafter.Widget.OptionList.from_component_opts(["a", "b"], selected: "b")
iex> {props.highlighted_index, props.visible_height, props.trigger}
{1, 10, :press}

@spec handle_custom_event(term(), t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Confirms the highlighted option on :activate, exactly as enter does, and returns {:bubble, state} for every other custom event.

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> {:ok, chosen} = Drafter.Widget.OptionList.handle_custom_event(:activate, state)
iex> chosen.selected_index
0

iex> state = Drafter.Widget.OptionList.mount(%{})
iex> Drafter.Widget.OptionList.handle_custom_event(:something, state) == {:bubble, state}
true

@spec handle_event(term(), t()) :: term()

Routes an event, taking {:focus} itself and delegating everything else to the dispatch use Drafter.Widget generated.

{:focus} moves the highlight onto the first enabled option when there is none yet, and sets :focused on the state. {:blur} reaches the generated dispatch, which clears the same field.

@spec handle_key(atom(), t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Moves the highlight or confirms the highlighted option.

Handles :up, :down, :home, :end, :page_up, :page_down, :enter and :" "; every other key returns {:bubble, state}. :up and :down bubble when there is no further enabled option, while :home and :end return {:noreply, state} when the list has none at all. A move that fires a callback returns {:ok, state, actions}.

iex> options = [Drafter.Widget.OptionList.option("a", "A"), Drafter.Widget.OptionList.option("b", "B")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> {:ok, moved} = Drafter.Widget.OptionList.handle_key(:down, state)
iex> {moved.highlighted_index, moved.selected_index}
{1, nil}

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> Drafter.Widget.OptionList.handle_key(:up, state) == {:bubble, state}
true

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> {:ok, chosen} = Drafter.Widget.OptionList.handle_key(:enter, state)
iex> chosen.selected_index
0

iex> state = Drafter.Widget.OptionList.mount(%{})
iex> Drafter.Widget.OptionList.handle_key(:x, state) == {:bubble, state}
true

@spec handle_mouse_up(integer(), integer(), t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Confirms the option on row y when :trigger is :mouse_up, and returns {:bubble, state} otherwise. Otherwise identical to handle_press/3.

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options, trigger: :mouse_up})
iex> {:ok, clicked} = Drafter.Widget.OptionList.handle_mouse_up(0, 0, state)
iex> clicked.selected_index
0

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> Drafter.Widget.OptionList.handle_mouse_up(0, 0, state) == {:bubble, state}
true

@spec handle_press(integer(), integer(), t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Confirms the option on row y when :trigger is :press, and returns {:bubble, state} otherwise.

y is relative to the widget's rect and is offset by :scroll_offset to find the option. A row outside the list, or one holding a disabled option, returns {:noreply, state}. x is ignored.

iex> options = [Drafter.Widget.OptionList.option("a", "A"), Drafter.Widget.OptionList.option("b", "B")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> {:ok, clicked} = Drafter.Widget.OptionList.handle_press(0, 1, state)
iex> {clicked.highlighted_index, clicked.selected_index}
{1, 1}

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options, trigger: :mouse_up})
iex> Drafter.Widget.OptionList.handle_press(0, 0, state) == {:bubble, state}
true

@spec handle_scroll(:up | :down, t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Moves the highlight one enabled option per wheel step.

direction is :up or :down, swapped when :inverted_scroll is set. Steps arriving less than :scroll_throttle_ms after the previous one return {:noreply, state} with only the timestamp updated; the first step after mount is never throttled. :last_scroll_time is stamped from System.system_time(:millisecond).

@spec mount(Drafter.Widget.props()) :: t()

Builds the widget state from props.

Every option listed in the module doc is read here with the default stated there, except :selected and :highlighted_index, which are ignored: the highlight always starts on the first option whose :disabled is falsy, and is nil for an empty or fully disabled list. :selected_index, :scroll_offset and :last_scroll_time all start at their zero values.

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> {state.highlighted_index, state.selected_index, state.visible_height}
{0, nil, 10}

iex> options = [Drafter.Widget.OptionList.option("a", "A", true), Drafter.Widget.OptionList.option("b", "B")]
iex> Drafter.Widget.OptionList.mount(%{options: options}).highlighted_index
1

iex> state = Drafter.Widget.OptionList.mount(%{})
iex> {state.highlighted_index, state.expand_height, state.trigger, state.scroll_throttle_ms}
{nil, :content, :press, 150}

iex> Drafter.Widget.OptionList.mount(%{focused: true}).focused
true

@spec option(String.t(), String.t(), boolean()) :: option()

Builds a single option map for the :options list.

id is the value handed to :on_select and :on_highlight; label is the text drawn in the row. Both must be binaries. A disabled option is drawn but skipped by keyboard navigation and cannot be selected.

Returns a map with :id, :label, :disabled and :selected, where :selected starts as false.

iex> Drafter.Widget.OptionList.option("two", "Option Two")
%{id: "two", label: "Option Two", disabled: false, selected: false}

iex> Drafter.Widget.OptionList.option("three", "Option Three", true)
%{id: "three", label: "Option Three", disabled: true, selected: false}

@spec preferred_height(
  list() | nil,
  keyword()
) :: non_neg_integer()

The number of rows the element asks for.

Returns opts[:height] when given, otherwise the length of the positional items list — which is 0 when the options were passed under opts[:options] instead.

iex> Drafter.Widget.OptionList.preferred_height(["a", "b"], [])
2

iex> Drafter.Widget.OptionList.preferred_height(nil, options: ["a"])
0

iex> Drafter.Widget.OptionList.preferred_height(nil, height: 6)
6

@spec render(t(), Drafter.Widget.rect()) :: [Drafter.Draw.Strip.t()]

Draws the visible slice of the list into rect.

The number of strips comes from :expand_height, not from rect.height: :content gives min(option_count, visible_height), :fill gives rect.height, and an integer gives itself. Rows start at :scroll_offset, each is truncated and padded to rect.width, and the highlighted row is prefixed with ▶ when :focused is true.

Callback implementation for Drafter.Widget.unmount/1.

@spec update(Drafter.Widget.props(), t()) :: t()

Merges props into state verbatim.

Every key in props lands on the state as given, including keys the struct does not declare and :options entries that have not been normalised.

iex> options = [Drafter.Widget.OptionList.option("a", "A")]
iex> state = Drafter.Widget.OptionList.mount(%{options: options})
iex> Drafter.Widget.OptionList.update(%{visible_height: 4}, state).visible_height
4

@spec update_props_from_mount(Drafter.Widget.props(), t(), keyword()) ::
  Drafter.Widget.props()

Narrows a re-render to :options, :visible_height, :on_select, :on_highlight, :trigger and :classes, adding :highlighted_index only when the id of the selected option changed.

:expand_height, :scroll_throttle_ms and :inverted_scroll are dropped, so they are mount-only through the component tree, and the highlight the user moved survives a re-render that does not change the selection.

iex> props = Drafter.Widget.OptionList.from_component_opts(["a", "b"], [])
iex> state = Drafter.Widget.OptionList.mount(props)
iex> Drafter.Widget.OptionList.update_props_from_mount(props, state, []) |> Map.keys() |> Enum.sort()
[:classes, :on_highlight, :on_select, :options, :trigger, :visible_height]

iex> props = Drafter.Widget.OptionList.from_component_opts(["a", "b"], selected: "b")
iex> state = Drafter.Widget.OptionList.mount(Drafter.Widget.OptionList.from_component_opts(["a", "b"], []))
iex> Drafter.Widget.OptionList.update_props_from_mount(props, state, []).highlighted_index
1