Bosatsu packages

Yichus/UI

Builtin package (resource ui.bosatsu). This is the complete package source used by this build. The export list names its public API; definitions below give the types and behavior.

New to the API? Start with Make a data app or Build an API, then use this page to look up a definition.

package Yichus/UI

from Bosatsu/Predef import String, Int, List, Unit, Option
from Yichus/IO import IO

export (
  VNode,
  State,
  ListState,
  Key(),
  key_name,
  h, text, fragment,
  state, read, write,
  list_state, list_read, list_append, list_remove_at, list_length, list_view, list_view_indexed, list_write,
  on_click, on_click_pos, on_input, on_change, on_keydown, on_keyup,
  on_dragstart, on_dragover, on_drop, on_dragleave,
  on_touchstart, on_touchmove, on_touchend,
  on_frame,
  url_param, set_url_param, remove_url_param,
  StoredRead(),
  stored, store
)

exposes Yichus/IO

external type VNode

# Mutable handles both read and write a; their element type is invariant.
external type State[a: *]
external type ListState[a: *]

external def h(tag: String, props: List[(String, String)], children: List[VNode]) -> VNode
external def text(content: String) -> VNode
external def fragment(children: List[VNode]) -> VNode
external def state[a](initial: a) -> IO[State[a]]
external def read[a](state: State[a]) -> IO[a]
external def write[a](state: State[a], value: a) -> IO[Unit]
external def list_state[a](initial: List[a]) -> IO[ListState[a]]
external def list_read[a](state: ListState[a]) -> IO[List[a]]
external def list_append[a](state: ListState[a], value: a) -> IO[Unit]
external def list_remove_at[a](state: ListState[a], index: Int) -> IO[Unit]
external def list_length[a](state: ListState[a]) -> IO[Int]
external def list_view[a](state: ListState[a], render: a -> VNode) -> VNode
external def list_view_indexed[a](state: ListState[a], render: a -> Int -> VNode) -> VNode
external def list_write[a](state: ListState[a], value: List[a]) -> IO[Unit]
external def on_click(handler: IO[Unit]) -> (String, String)
# The pointer position relative to the element, in the element's own
# pixels (a canvas's drawing-buffer pixels when its CSS size differs).
external def on_click_pos(handler: (Int, Int) -> IO[Unit]) -> (String, String)
external def on_input(handler: String -> IO[Unit]) -> (String, String)
external def on_change(handler: String -> IO[Unit]) -> (String, String)
external def on_dragstart(handler: IO[Unit]) -> (String, String)
external def on_dragover(handler: IO[Unit]) -> (String, String)
external def on_drop(handler: IO[Unit]) -> (String, String)
external def on_dragleave(handler: IO[Unit]) -> (String, String)
# The first touch point's position in the page viewport, in CSS pixels.
external def on_touchstart(handler: (Int, Int) -> IO[Unit]) -> (String, String)
external def on_touchmove(handler: (Int, Int) -> IO[Unit]) -> (String, String)
external def on_touchend(handler: (Int, Int) -> IO[Unit]) -> (String, String)
external def on_frame(handler: IO[Unit]) -> (String, String)

# The page URL's query string, read and rewritten only when the IO runs.
# `url_param(key)` is None when the key is absent and Some("") when it is
# present with no value. `set_url_param` replaces the current history
# entry (history.replaceState) rather than pushing one, so Back leaves
# the page instead of replaying every value written.
external def url_param(key: String) -> IO[Option[String]]
external def set_url_param(key: String, value: String) -> IO[Unit]
# `remove_url_param(key)` drops `key` from the query string, replacing
# the current history entry the same way; an absent key changes nothing.
external def remove_url_param(key: String) -> IO[Unit]

# The browser's local storage for the page's origin, read and written
# only when the IO runs, so progress outlives a reload with no query in
# the URL. `stored(key)` says what one read found (`StoredRead`):
# `NothingKept` when storage was read and holds nothing under `key`,
# `Kept(text)` when it holds `text` (Kept("") for an empty value), and
# `Unreadable` when storage could not be read at all (no browser, a
# private window, blocked site data, a read that threw). Unreadable is
# not nothing kept: a page that writes back what it read (a merge, a
# union) must not write the key then, since storage it could not read may
# still hold progress a write would replace; and a page must play the
# same with nothing kept. `store(key, value)` keeps `value` under `key`,
# and does nothing where storage is unavailable or refuses (also when
# full). A kept value is data the page wrote, or anything a person
# edited since: parse it fail-closed, and put a version in the key so
# its format can change.
enum StoredRead:
  NothingKept
  Kept(text: String)
  Unreadable

external def stored(key: String) -> IO[StoredRead]
external def store(key: String, value: String) -> IO[Unit]

# A key as the browser reports it (KeyboardEvent.key). The named keys
# have constructors; every other key, a typed character among them,
# arrives as OtherKey carrying the name the browser gave it.
enum Key:
  ArrowUp
  ArrowDown
  ArrowLeft
  ArrowRight
  Enter
  Escape
  Space
  Backspace
  Delete
  OtherKey(name: String)

def key_named(name: String) -> Key:
  match name:
    case "ArrowUp": ArrowUp
    case "ArrowDown": ArrowDown
    case "ArrowLeft": ArrowLeft
    case "ArrowRight": ArrowRight
    case "Enter": Enter
    case "Escape": Escape
    case " ": Space
    case "Backspace": Backspace
    case "Delete": Delete
    case _: OtherKey(name)

# The name the browser reports for the key: key_name(key) is the
# KeyboardEvent.key the key was decoded from.
def key_name(key: Key) -> String:
  match key:
    case ArrowUp: "ArrowUp"
    case ArrowDown: "ArrowDown"
    case ArrowLeft: "ArrowLeft"
    case ArrowRight: "ArrowRight"
    case Enter: "Enter"
    case Escape: "Escape"
    case Space: " "
    case Backspace: "Backspace"
    case Delete: "Delete"
    case OtherKey(name): name

# The runtime delivers the reported name; the handler receives the Key.
external def on_keydown_name(handler: String -> IO[Unit]) -> (String, String)
external def on_keyup_name(handler: String -> IO[Unit]) -> (String, String)

def on_keydown(handler: Key -> IO[Unit]) -> (String, String):
  on_keydown_name(name -> handler(key_named(name)))

def on_keyup(handler: Key -> IO[Unit]) -> (String, String):
  on_keyup_name(name -> handler(key_named(name)))