Behaviour for a Drafter widget: a component that owns state, draws itself into a rect, and handles events.

A widget module does use Drafter.Widget, opts and implements at least mount/1 and render/2. Everything else is optional and has a default.

defmodule MyWidgets.Counter do
  use Drafter.Widget, handles: [:keyboard, :press], focusable: true

  alias Drafter.Draw.{Segment, Strip}

  defstruct count: 0, focused: false

  def component_tag, do: :counter
  def from_component_opts(_args, opts), do: %{count: Keyword.get(opts, :count, 0)}

  @impl true
  def mount(props), do: %__MODULE__{count: Map.get(props, :count, 0)}

  @impl true
  def render(%__MODULE__{count: count}, _rect) do
    [Strip.new([Segment.new("count: #{count}", %{})])]
  end

  def handle_key(:up, state), do: {:ok, %{state | count: state.count + 1}}
  def handle_key(_key, state), do: {:bubble, state}

  def handle_press(_x, _y, state), do: {:ok, %{state | count: state.count + 1}}
end

component_tag/0 and from_component_opts/2 are what let the widget appear in a component tree as {:counter, count: 3}; they belong to the widget registry, not to this behaviour. Without them a widget is still usable as {MyWidgets.Counter, %{count: 3}}.

use Drafter.Widget options

Handles mode — the default, chosen whenever :traits is absent or empty:

• :handles - the event kinds the widget wants, as a list of atoms. Default []. :keyboard, :char, :paste, :press (:click is accepted for it), :mouse_up, :drag, :hover, :scroll. An event kind that is not declared is never routed to the widget, whatever callbacks it exports.
• :focusable - boolean(). Default :keyboard in handles. A focusable widget takes part in tab order and gets :focused set on its state by {:focus} and {:blur}.
• :capture_handles - event kinds the widget sees during the capture phase, before they reach their target. Default []; requires handle_event_capture/2.
• :scroll - keyword list configuring default scrolling: :direction (:horizontal default), :step (5 default), :wrap (false default). Default nil, which becomes %{direction: :horizontal, step: 5} when :scroll is in :handles.
• :layout_impact - how far a state change invalidates layout: :self (default), :below, :above, :left, :right, :parent, or :all.

Trait mode — chosen when :traits is a non-empty list:

• :traits - trait specs resolved by Drafter.Widget.Trait, e.g. [:focusable, :scrollable]. The traits supply the handles, focusability, default state, and the handle_event/2 pipeline.
• :handles - extra event kinds merged with the ones the traits declare.
• :scroll - passed to the traits as Drafter.Widget.Trait.scroll_config/2 reads it.
• :layout_impact - as above.

Trait mode reads no :focusable and no :capture_handles: focusability comes from the traits and the generated __widget_capabilities__/0 reports capture_handles: [].

Both modes generate handle_event/2, __widget_capabilities__/0, and __layout_impact__/0, and overridable defaults for mount/1, render/2, update/2, unmount/1, focused/1, update_props_from_mount/3, and preferred_height/2. Trait mode additionally generates __widget_traits__/0, __widget_capabilities_bitmap__/0, __render_affecting_fields__/0, __layout_static__/0, and __trait_default_state__/0.

Event callbacks and their results

Drafter.Widget.EventRouter turns each event into the matching callback, and only when the kind is declared and the function is exported. Every event callback returns one of:

• {:ok, new_state} - handled. The event stops here and does not reach the parent.
• {:ok, new_state, actions} - handled, plus a list of actions for the app; see Drafter.EventResult.
• {:bubble, new_state} / {:bubble, new_state, actions} - the state is kept and the event continues to the parent widget, and then to the app.
• {:noreply, state} - treated as not handled: the event continues and the returned state is discarded. Return {:bubble, new_state} to keep a change while still letting the event through.
• an action tuple — {:pop, result}, {:push, module, props}, {:replace, module, props}, {:app_callback, name, data} - the action is recorded, the event stops, and the widget's state is left as it was before the event.

Anything else counts as not handled and the state is left unchanged.

Paste

A widget receives pasted text only if it declares :paste:

use Drafter.Widget, handles: [:keyboard, :paste], focusable: true

def handle_paste(text, state), do: {:ok, %{state | value: state.value <> text}}

text has already been through Drafter.Clipboard.sanitize/1 and carries no escape sequences. A widget that does not declare :paste bubbles the event instead. Drafter.Clipboard.copy/1 is the other direction.