🥮 mooncakes.io

rabbita

functional Web UI framework for MoonBit

functional
html
UI
web
TEA
moon add moonbit-community/rabbita@0.15.2
Download zip
Version
0.15.2
License
Apache-2.0
Repository
Last updated
22 hours ago
Downloads
51K

Dependencies

README

#Rabbita

A declarative, functional web UI framework inspired by The Elm Architecture.

This project was previously named Rabbit-TEA and is now renamed to rabbita .

#Features

  • Predictable flow

    State changes follow a single, predictable update path, with explicit side‑effect management.

  • Strict Types

    Rigorous types. No Any sprawl. No stringly-typed APIs.

  • Balanced bundle size

    ~15 KB min+gzip, includes streaming VDOM diff and the MoonBit standard library (DCE via moonc).

  • Modular

    Use Cell to split logic and reuse stateful views. Skip diff and patching for non-dirty cells.

#Quick Start

Use the rabbita-template to get started quickly.

#Examples

#Counter

///|
using @html {div, h1, button}

///|
#cfg(target="js")
test {
  struct Model {
    count : Int
  }
  enum Msg {
    Inc
    Dec
  }
  let app = @rabbita.simple_cell(
    model={ count: 0 },
    update=(msg, model) => {
      let { count } = model
      match msg {
        Inc => { count: count + 1 }
        Dec => { count: count - 1 }
      }
    },
    view=(dispatch, model) => {
      div([
        h1("\{model.count}"),
        button(on_click=dispatch(Inc), "+"),
        button(on_click=dispatch(Dec), "-"),
      ])
    },
  )
  new(app).mount("main")
}

#Multiple cells

Each cell maintains its own model, view, and update logic, and only dirty cells need VDOM diffing and patching.

///|
#cfg(target="js")
using @html {fragment, input, nothing, ul, li, p}

///|
#cfg(target="js")
using @list {type List, empty}

///|
/// The todo plan
#cfg(target="js")
fn plan(name : String) -> Cell {
  struct Model {
    value : String
    items : Map[String, Bool]
  }
  enum Msg {
    Add
    Change(String)
    Done(String)
  }
  @rabbita.simple_cell(
    model={ value: "", items: {} },
    update=(msg, model) => {
      let { value, items } = model
      match msg {
        Add => { value: "", items: items..set(value, false) }
        Done(key) => { ..model, items: items..set(key, true) }
        Change(value) => { ..model, value, }
      }
    },
    view=(dispatch, model) => {
      let { value, items } = model
      let items = items.map((todo, done) => {
        let text_style = if done { "text-decoration: line-through" } else { "" }
        li(style=[text_style], [
          p(todo),
          button(on_click=dispatch(Done(todo)), "done"),
        ])
      })
      div(style=["border: 1px solid black", "padding: 1em"], [
        h1(name),
        ul(items),
        input(
          input_type=Text,
          value~,
          on_change=s => dispatch(Change(s)),
          nothing,
        ),
        button(on_click=dispatch(Add), "add"),
      ])
    },
  )
}

///|
/// Main app
#cfg(target="js")
test {
  struct Model {
    plans : List[Cell]
  }
  enum Msg {
    NewPlan
  }
  let app = @rabbita.simple_cell(
    model={ plans: empty() },
    update=(msg, model) => {
      let id = model.plans.length()
      match msg {
        NewPlan => { plans: model.plans.add(plan("plan \{id}")) }
      }
    },
    view=(dispatch, model) => {
      fragment([
        div(model.plans.map(x => x.view())),
        button(on_click=dispatch(NewPlan), "new plan"),
      ])
    },
  )
  @rabbita.new(app).mount("app")
}

Cell is an opaque model: it is still managed by the outer model, but internal details are hidden. Cell::view() is a pure function that maps state to HTML.

Unlike the hooks-style mental model, a cell's lifecycle is explicit: if its view is not present in the real DOM, the cell is inactive and messages to it are ignored. If the model is removed from the outer model, the cell is destroyed by the garbage collector.

#Used By

mooncakes.io

#
Cmd

source

A deferred command handled by the Rabbita runtime.

Cmd models side effects in the update loop. Commands are returned from update or embedded in Html event handlers, and are executed later by the runtime.

#
Dispatch

source

Message dispatcher type used by a Cell.

Calling dispatch(msg) returns a Cmd that enqueues msg into the cell's update loop.

#
Html

source

#
App

source
type App

A running Rabbita application.

#
App::mount

source
fn App::mount(self : App, element_id : String) -> Unit

Mount the app into the DOM element identified by element_id.

This initializes the runtime and schedules the first render flush. If routing is configured, the current URL is also dispatched on mount.

#
App::with_init

source
#internal(unstable, "Experimental API")
fn App::with_init(self : App, cmd : 
Cmd) -> Unit

Registers a one-shot command to be queued when mount runs. This API is still evolving and may change in future releases.

#
App::with_route

source
#deprecated("use subscriptions and @sub.on_url_changed/@sub.on_url_request instead")
fn App::with_route(self : App, url_changed? : 
Dispatch[
Url], url_request? : 
Dispatch[
UrlRequest]) -> Unit

Configure routing callbacks for this app.

  • url_changed is triggered for browser history navigation and when push_url / replace_url commands are used.
  • url_request is triggered when captured links @html.a() are clicked.

If the app is already mounted, a url_changed command for the current URL will be enqueued immediately.

#
Cell

source
type Cell

A cell that encapsulates model, update, and view.

#
Cell::view

source

Render this cell as Html.

#
attempt

source
fn[A, E : Error] attempt(msg : (Result[A, E]) -> 
Cmd, f : async () -> A raise E) -> 
Cmd

Create a command that runs an async function and handles errors.

Similar to perform, but captures errors and passes Result[A, E] to msg.

#
batch

source

Combine multiple commands into one command.

#
cell

source

Create a stateful cell with full model/update/view functionality.

Type parameters:

  • Model: a custom type you need to defined, represent the state of this cell.
  • Msg: a custom enum you need to defined, represent the events of this cell.

Parameters:

  • model : Model: initial Model value of the cell.

  • update : (Dispatch[Msg], Msg,Model) -> (Cmd,Model): Describe how to compute new Model from Msg and old Model. This callback also receives a Dispatch[Msg], which converts a Msg into a Cmd.

  • view : (Dispatch[Msg], Model) -> Html: Describe how to compute Html from Model. This callback also receives a Dispatch[Msg], which converts a Msg into a Cmd.

The update loop

┌─────────────────┐
│                 ▼
│            ┌──────────┐
│            │   user   │
│            └────┬─────┘
│                 │ msg,model
│                 ▼
│           ┌────────────┐   msg,model
│           │  update()  │◄────────────┐
│           └──┬───────┬─┘             │
│    none,model│       │               │
│              ▼       │               │
│         ┌────────┐   │cmd,model      │
│         │ view() │   │               │
│         └────┬───┘   │               │
│              │       │               │
│          html│       ▼               │
│              │   ┌─────────┐         │
└──────────────┘   │ runtime │─────────┘
                   └─────────┘

This update loop is a bit more complex than simple_cell, but follows the same model -> update -> view flow.

The difference is that update also returns a command representing a managed side effect. That side effect is executed by the runtime and may produce another message.

#
cell_with_dispatch

source

Create a cell and also return its Dispatch.

This is useful when messages need to be sent from outside.

Type parameters:

  • Model: a custom type you need to defined, represent the state of this cell.
  • Msg: a custom enum you need to defined, represent the events of this cell.

Parameters:

  • model : Model: initial Model value of the cell.

  • update : (Dispatch[Msg], Msg,Model) -> (Cmd,Model): Describe how to compute new Model from Msg and old Model. This callback also receives a Dispatch[Msg], which converts a Msg into a Cmd.

  • view : (Dispatch[Msg], Model) -> Html: Describe how to compute Html from Model. This callback also receives a Dispatch[Msg], which converts a Msg into a Cmd.

The update loop

┌─────────────────┐
│                 ▼
│            ┌──────────┐
│            │   user   │
│            └────┬─────┘
│                 │ msg,model
│                 ▼
│           ┌────────────┐   msg,model
│           │  update()  │◄────────────┐
│           └──┬───────┬─┘             │
│    none,model│       │               │
│              ▼       │               │
│         ┌────────┐   │cmd,model      │
│         │ view() │   │               │
│         └────┬───┘   │               │
│              │       │               │
│          html│       ▼               │
│              │   ┌─────────┐         │
└──────────────┘   │ runtime │─────────┘
                   └─────────┘

This update loop is a bit more complex than simple_cell, but follows the same model -> update -> view flow.

The difference is that update also returns a command representing a managed side effect. That side effect is executed by the runtime and may produce another message.

#
delay

source

Delay execution of a command by ms milliseconds.

The delayed command is added back to the message queue after the timer fires.

#
effect

source
fn effect(f : async () -> Unit noraise) -> 
Cmd

Create a command that runs an effectful async function

#
new

source
fn new(root : Cell) -> App

Create an application from a root Cell.

Use simple_cell(), static_cell(), cell(), cell_with_dispatch() to create a cell. Call mount to attach it to a DOM element. Optionally call with_route to install routing callbacks.

For beginners, simple_cell is recommended. See its documentation for more details.

Example

test "minimal static page" {
  let app = @rabbita.static_cell(div("hello world"))
  ignore(app)
  // use `@rabbita.new(app).mount("id")` in client
}

#
none

source

A command that does nothing.

#
perform

source
fn[A] perform(msg : (A) -> 
Cmd, f : async () -> A noraise) -> 
Cmd

Create a command that runs an async function.

The async function f is executed, then its result is converted into a new command by msg and scheduled back into the update loop.

#
render_to_string

source
#internal(unstable, "Experimental API")
fn render_to_string(root : Cell) -> String

Render a Cell tree into an HTML string.

This is the server-side rendering entrypoint for Rabbita. It evaluates view and serializes the resulting virtual DOM into static HTML.

Hydration is currently not supported. If you later call mount on the client, Rabbita will do a fresh client-side render instead of attaching to the existing server-rendered DOM.

Example

#warnings("-alert_unstable")
test "render html to string" {
  enum Msg {}
  struct Model {
    todos : Array[String]
  }
  let page = @rabbita.simple_cell(
    model={ todos: ["todo1", "todo2"] },
    update=(_ : Msg, model) => model,
    view=(_, model) => @html.ul(model.todos.map(x => @html.li(x))),
  )
  inspect(
    @rabbita.render_to_string(page),
    content=(
      #|<ul><li>todo1</li><li>todo2</li></ul>
    ),
  )
}

#
simple_cell

source
fn[Model, Msg] simple_cell(model~ : Model, update~ : (Msg, Model) -> Model, view~ : (
Dispatch[Msg], Model) -> 
Html) -> Cell

Create a cell with simplified model/update/view.

Type parameters:

  • Model: a custom type you need to defined, represent the state of this cell.
  • Msg: a custom enum you need to defined, represent the events of this cell.

Parameters:

  • model : Model: initial Model value of the cell.
  • update : (Msg, Model) -> Model: describe how to compute new Model from Msg and old Model.
  • view : (Dispatch[Msg], Model) -> Html: describes how to render Html from Model. This callback also receives a dispatch argument, which converts a Msg into a Cmd.

The update loop

   ┌──────┐
   │ user │◀─────────┐
   └──────┘          │
       │ msg, model  │
       ▼             │
 ┌──────────┐        │
 │ update() │        │ html
 └──────────┘        │
       │ model       │
       ▼             │
  ┌────────┐         │
  │ view() │─────────┘
  └────────┘

At startup, the initial model is rendered as Html by view. The rendered HTML can include message-producing command, for example:

button(on_click=dispatch(MyMsg), "click me")

When the user clicks the button, MyMsg is sent to update with the current model. update then computes the next model from that message, and the new model is rendered again by view.

Example

test "counter" {
  struct Model {
    count : Int
  }
  enum Msg {
    Click
  }
  let app = @rabbita.simple_cell(
    model={ count: 0 },
    update=(msg, model) => {
      match msg {
        Click => { count: model.count + 1 }
      }
    },
    view=(dispatch, model) => {
      div([
        h1("You clicked \{model.count} times."),
        button(on_click=dispatch(Click), "+"),
      ])
    },
  )
  ignore(app) // use `new(app).mount("id")` in client
}

#
simple_cell_with_dispatch

source
fn[Model, Msg] simple_cell_with_dispatch(model~ : Model, update~ : (Msg, Model) -> Model, view~ : (
Dispatch[Msg], Model) -> 
Html, subscriptions? : (
Dispatch[Msg], Model) -> 
Sub) -> (
Dispatch[Msg], Cell)

#
static_cell

source

Create a static cell that always renders the same Html.

Rather than use static_cell, it's recommend to wrap a function that return html directly:

fn button(text : String, on_click~ : Cmd) -> Html {
  @html.button(style=["..."], on_click~, text)
}

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io