tea

README

This contains a Go library for writing client-side web interfaces, in the model-view-update style of the Elm architecture ("TEA").

It contains a simple package vdom for working with Virtual DOMs, as popularized by React.JS. When compiled to WASM, package vdom supports patching the DOM via the syscall/js package. vdom can be used stand-alone.

This library is experimental, but I am currently using it in Tempest.

There are some example applications in the examples/ directory.

Documentation

Overview

Package tea implements a high-level framework for building web user interfaces, using the Elm architecture.

The user interface consists of an App, which manages a model representing application state. The app responds to messages by updating its model, and re-renders via a virtual dom when the model changes. Messages are processed sequentially in a single goroutine.

Applications should define a model type M which implements AppModel[M], and some number of types that implement Message[M]. The app can then be constructed by passing the initial model to NewApp, and then attached to the DOM and executed with App.Run().

Index

• type App
  • func NewApp[M AppModel[M]](model M) *App[M]
  • func (app *App[Model]) Run(ctx context.Context, node vdom.DomNode)
  • func (app *App[Model]) SendMessage(msg Message[Model])
• type AppModel
• type Message
• type MessageSender

Types

type App

type App[M AppModel[M]] struct {
	// contains filtered or unexported fields
}

An App[M] manages an application with model/state type M.

func NewApp

func NewApp[M AppModel[M]](model M) *App[M]

NewApp creates a new application with model/state type M.

func (*App[Model]) Run

func (app *App[Model]) Run(ctx context.Context, node vdom.DomNode)

Run replaces node in the DOM with a node managed by the application, and then runs the application.

func (*App[Model]) SendMessage

func (app *App[Model]) SendMessage(msg Message[Model])

SendMessage sends a message to the application

type AppModel

type AppModel[Model any] interface {
	// View renders a virtual DOM from the model. The MessageSender
	// can be used to implement event handlers which send update messages
	// to the app.
	View(MessageSender[Model]) vdom.VNode
}

An AppModel holds application state, and knows how to render itself as a virtual DOM. The Model type parameter will typically be the same as the type of the receiver.

type Message

type Message[Model any] interface {
	// Update updates the model, and returns a function to be run
	// asynchronously with the ability to send more messages.
	//
	// Update MUST NOT block, as doing so could hang the user interface.
	// Anything that could block must instead be done in the returned
	// callback, whose second parameter can be used to send messages
	// for further updates.
	Update(*Model) func(context.Context, func(Message[Model]))
}

A Message[Model] is a message carrying updates to make to a Model.

type MessageSender

type MessageSender[Model any] interface {
	// Send sends a message to the application.
	Send(Message[Model])

	// Event returns a vdom event handler which sends the specified
	// message when triggered.
	Event(Message[Model]) vdom.EventHandler
}

A MessageSender[M] sends messages to an application with model type M.