@spec on_blur(payload() | term()) :: blur_attr()

Register a blur payload for a focusable element.

@spec on_change(payload() | term()) :: change_attr()

Register a value-change payload for a text input.

Use on_change/1 with Emerge.UI.Input.text/2 or Emerge.UI.Input.multiline/2.

Text editing still works without this handler; on_change/1 only controls whether a message is emitted when the value changes.

When delivered through a viewport, the changed value is wrapped into the stored message using wrap_payload/3. Multiline values use the same payload shape; newline characters remain part of the emitted binary.

Examples

This example keeps the input value in viewport state and updates that state whenever the field changes.

def render(state) do
  Input.text(
    [
      key(:search),
      Event.on_change(:search_changed)
    ],
    state.query
  )
end

def handle_info({:search_changed, value}, state) do
  {:noreply, %{state | query: value} |> Viewport.rerender()}
end

@spec on_click(payload() | term()) :: click_attr()

Register a pointer click payload for this element.

Use this when you specifically want click behavior from the pointer.

For normal button-like activation, prefer on_press/1.

@spec on_focus(payload() | term()) :: focus_attr()

Register a focus payload for a focusable element.

@spec on_key_down(key_matcher(), payload() | term()) :: key_down_attr()

Register a focused key-down payload for this element.

matcher can be a key atom like :enter or a keyword matcher such as [key: :digit_1, mods: [:ctrl], match: :all].

:match defaults to :exact.

Example

This lets one focused button respond both to Ctrl+1 and to plain Enter.

Input.button(
  [
    Event.on_key_down([key: :digit_1, mods: [:ctrl], match: :all], :select_tab_1),
    Event.on_key_down(:enter, :submit)
  ],
  text("Save")
)

On focused Emerge.UI.Input.text/2 and Emerge.UI.Input.multiline/2 elements, a matching on_key_down/2 suppresses the input's default keydown behavior for that keydown. This lets apps override built-in editing such as character insertion or multiline Enter handling.

For example, on_key_down(:enter, :submit) on a focused Emerge.UI.Input.multiline/2 intercepts Enter before the default newline is inserted.

@spec on_key_press(key_matcher(), payload() | term()) :: key_press_attr()

Register a focused completed key-press payload for this element.

on_key_press/2 is for completed key gestures and fires on release after a matching press.

@spec on_key_up(key_matcher(), payload() | term()) :: key_up_attr()

Register a focused key-up payload for this element.

Key-up handlers use the same matcher forms as on_key_down/2.

@spec on_mouse_down(payload() | term()) :: mouse_down_attr()

Register a mouse-down payload for this element. Left mouse button only.

@spec on_mouse_enter(payload() | term()) :: mouse_enter_attr()

Register a mouse-enter payload for this element. Delivered without cursor coordinates.

@spec on_mouse_leave(payload() | term()) :: mouse_leave_attr()

Register a mouse-leave payload for this element. Delivered without cursor coordinates.

@spec on_mouse_move(payload() | term()) :: mouse_move_attr()

Register a mouse-move payload for this element. Delivered without cursor coordinates.

@spec on_mouse_up(payload() | term()) :: mouse_up_attr()

Register a mouse-up payload for this element. Left mouse button only.

@spec on_press(payload() | term()) :: press_attr()

Register a press payload for this element.

This is the recommended default for buttons and other action controls. For standard activation, prefer on_press/1 over on_click/1 because it also works with focused Enter.

Examples

This is a conventional action button: pressing it sends :save to the target process while the surrounding attrs provide the visual styling.

Input.button(
  [
    Event.on_press(:save),
    Background.color(color(:sky, 500)),
    Border.rounded(8),
    Font.color(color(:white)),
    padding(12)
  ],
  text("Save")
)

@spec on_swipe_down(payload() | term()) :: swipe_down_attr()

Register a swipe-down payload for this element. Fires when the gesture resolves downward.

@spec on_swipe_left(payload() | term()) :: swipe_left_attr()

Register a swipe-left payload for this element. Fires when the gesture resolves leftward.

@spec on_swipe_right(payload() | term()) :: swipe_right_attr()

Register a swipe-right payload for this element. Fires when the gesture resolves rightward.

@spec on_swipe_up(payload() | term()) :: swipe_up_attr()

Register a swipe-up payload for this element. Fires when the gesture resolves upward.

@spec virtual_key(virtual_key_spec() | keyword()) :: virtual_key_attr()

Register virtual-key behavior for an element.

This is useful for on-screen keyboards and similar soft-key controls.

The spec must include :tap. Optional keys are :hold, :hold_ms, and :repeat_ms.

virtual_key/1 cannot be combined with on_click/1 or on_press/1 on the same element.

Example

This virtual key inserts an uppercase A on tap and sends a separate :show_alternates event when the key is held.

Input.button(
  [
    width(px(56)),
    height(px(56)),
    Event.virtual_key(
      tap: {:text_and_key, "A", :a, [:shift]},
      hold: {:event, {self(), :show_alternates}}
    )
  ],
  text("A")
)

{:text_and_key, text, key, mods} participates in the same text-input keydown suppression rules as a physical key press. {:text, text} does not, because it inserts text without a preceding keydown. See on_key_down/2 for the suppression behavior on focused Input.text/2 and Input.multiline/2.