@spec component_tag() :: :switch

The component tag this widget registers under.

iex> Drafter.Widget.Switch.component_tag()
:switch

@spec from_component_opts(
  term(),
  keyword()
) :: Drafter.Widget.props()

Builds the props map for a {:switch, opts} element.

The positional argument is ignored. :enabled is the bound value for that key, so bind: :key reads it from opts[:__app_state__] and plain enabled: is used otherwise, defaulting to false. :on_change is the binding's writer, a one-argument function or nil. :width and :height fall back to opts[:__rect__], itself defaulting to %{width: 12, height: 1}. :on_color and :off_color are not forwarded.

iex> props = Drafter.Widget.Switch.from_component_opts(nil, label: "Dark")
iex> {props.enabled, props.label, props.size, props.width, props.height, props.on_change}
{false, "Dark", :normal, 12, 1, nil}

iex> opts = [bind: :dark_mode, __app_state__: %{dark_mode: true}]
iex> Drafter.Widget.Switch.from_component_opts(nil, opts).enabled
true

@spec handle_event(term(), t()) :: {:ok, t()} | {:noreply, t()}

Handles the switch's own events, replacing the dispatch use Drafter.Widget would otherwise generate.

Recognised events:

• :activate, {:key, :enter}, {:key, :" "} - toggle
• {:key, :right} - turn on; {:key, :left} - turn off
• {:mouse, %{type: :mouse_up}} - focus and toggle
• :hover / :unhover - set or clear :hovered
• {:focus} / {:blur} - set or clear :focused
• :tick - advance the animation

Starting an animation returns {:ok, state} and schedules the next :tick on the calling process. A toggle that has nothing to do — turning on a switch that is already on, or any event during an animation other than :tick — returns {:noreply, state}, and so does every unrecognised event.

iex> state = Drafter.Widget.Switch.mount(%{})
iex> {:ok, toggled} = Drafter.Widget.Switch.handle_event({:key, :enter}, state)
iex> {toggled.state, toggled.slider_position}
{:animating_on, 0.0}

iex> state = Drafter.Widget.Switch.mount(%{})
iex> Drafter.Widget.Switch.handle_event({:key, :left}, state)
...> |> elem(0)
:noreply

iex> state = Drafter.Widget.Switch.mount(%{})
iex> {:ok, hovered} = Drafter.Widget.Switch.handle_event(:hover, state)
iex> hovered.hovered
true

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

Builds the widget state from props.

:enabled decides both :state (:on or :off) and :slider_position (1.0 or 0.0); there is no way to mount mid-animation.

iex> state = Drafter.Widget.Switch.mount(%{})
iex> {state.state, state.slider_position, state.size, state.width, state.height}
{:off, 0.0, :normal, 12, 1}

iex> state = Drafter.Widget.Switch.mount(%{enabled: true, label: "Dark mode"})
iex> {state.state, state.slider_position, state.label}
{:on, 1.0, "Dark mode"}

@spec preferred_height(
  term(),
  keyword()
) :: 3

The number of rows the element asks for: always 3. There is no :height override.

iex> Drafter.Widget.Switch.preferred_height(nil, height: 1)
3

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

Draws the switch into rect, returning exactly rect.height strips.

state may be a plain props map, in which case it is passed through mount/1 first. The first strip holds the label followed by the track, padded with spaces to rect.width; the rest are blank. The thumb is lightened while hovered, and by half as much while focused.

Callback implementation for Drafter.Widget.unmount/1.

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

Folds props into widget_state, applying :label, :on_change, :width, :height and :size in every case and dropping every other key.

:enabled is compared with the current state rather than assigned:

• settled at :on or :off — an :enabled that differs jumps straight to the other state with no animation; one that matches changes nothing. Absent, it defaults to the current state, so the switch stays put.
• mid-animation — an :enabled that agrees with where the animation is heading lets it finish; one that disagrees cancels it and snaps to that state. Absent, it defaults to the animation's destination, so the animation continues.

Examples

iex> state = Drafter.Widget.Switch.mount(%{})
iex> updated = Drafter.Widget.Switch.update(%{enabled: true, label: "On"}, state)
iex> {updated.state, updated.slider_position, updated.label}
{:on, 1.0, "On"}

iex> state = Drafter.Widget.Switch.mount(%{enabled: true})
iex> updated = Drafter.Widget.Switch.update(%{label: "Kept"}, state)
iex> {updated.state, updated.label}
{:on, "Kept"}

iex> state = %{Drafter.Widget.Switch.mount(%{}) | state: :animating_on, slider_position: 0.5}
iex> updated = Drafter.Widget.Switch.update(%{enabled: false}, state)
iex> {updated.state, updated.slider_position}
{:off, 0.0}

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

Narrows a re-render to :on_change, :label and :size.

:enabled is added only when opts carries :bind and the bound value differs from the widget's current state, so an unbound switch keeps whatever the user toggled it to and :width and :height are mount-only.

iex> props = Drafter.Widget.Switch.from_component_opts(nil, label: "Dark")
iex> state = Drafter.Widget.Switch.mount(props)
iex> Drafter.Widget.Switch.update_props_from_mount(props, state, []) |> Map.keys() |> Enum.sort()
[:label, :on_change, :size]

iex> opts = [bind: :dark_mode, __app_state__: %{dark_mode: true}]
iex> props = Drafter.Widget.Switch.from_component_opts(nil, opts)
iex> state = Drafter.Widget.Switch.mount(%{enabled: false})
iex> Drafter.Widget.Switch.update_props_from_mount(props, state, opts).enabled
true