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)))