README
¶
reactea
Rather simple Bubbletea companion for handling hierarchy and support for lifting state up.
It Reactifies Bubbletea philosophy and makes it especially easy to work with in bigger projects.
For me, personally - It's a must in project with multiple pages and component communication
Check our example code right here!
Installation
go get -u github.com/londek/reactea
Example code
There is no tutorial yet so I suggest checking our example!
General info
The goal is to create components which are
- dimensions-aware (especially unify all setSize conventions)
- propful
- easy to lift the state up
- able to communicate with parent without importing it (I spent too many hours solving import cycles hehe)
- easier to code
- all of that without code duplication
The extreme performance is not main goal of this package, because either way Bubbletea
refresh rate is only 60hz and 50 allocations in entire runtime won't really hurt anyone.
Most info is currently in source code so I suggest checking it out
Always return reactea.Destroy instead of tea.Quit in order to follow our convention\
As of now Go doesn't support type aliases for generics, so Renderer[TProps] has to be explicitely casted.
It's planned for Go 1.20
Component lifecycle
reactea takes pointer approach for components
making state modifiable in any lifecycle method
There are also 2 additional lifecycle methods: AfterUpdate() and UpdateProps()
AfterUpdate()
AfterUpdate() is the only lifecycle method that is not controlled by parent. It's called right after root component finishes Update(). Components should queue itself with reactea.AfterUpdate(component) in Update()
UpdateProps()
UpdateProps() is a lifecycle method that derives state from props, It can happen anytime during lifecycle. Usually called by Init()
Notes
Update() IS NOT guaranteed to be called on first-run, Init() for most part is, and critical logic should be there
Lifecycle is (almost, see AfterUpdate()) fully controlled by parent component making graph above fully theoretical and possibly invalid for third-party components
Stateless components
Stateless components are represented by following function types
| Renderer[TProps any] | ProplessRenderer | DumbRenderer | |
|---|---|---|---|
| Properties | ✅ | ❌ | ❌ |
| Dimensions | ✅ | ✅ | ❌ |
| Arguments | TProps, int, int |
int, int |
❌ |
There are many utility functions for transforming stateless into stateful components or for rendering any component without knowing its type (reactea.RenderAny, reactea.RenderPropless)
Reactea Routes API
Routes API allows developers for easy development of multi-page apps. They are kind of substitute for window.Location inside bubbletea
reactea.CurrentRoute() Route
Returns current route
reactea.LastRoute() Route
Returns last route
reactea.WasRouteChanged() bool
returns LastRoute() != CurrentRoute()
Router Component
Router Component is basic implementation of how routing could look in your application. It doesn't support wildcards yet or relative pathing. All data is provided from within props
router.Props
router.Props is a map of route initializers keyed by routes
What is RouteInitializer?
RouteInitializer is function that initializes the current route component
Documentation
¶
Index ¶
- func AfterUpdate(afterUpdater AfterUpdater)
- func CurrentRoute() string
- func Destroy() tea.Msg
- func New(root Component[NoProps]) model
- func RenderAny[TProps any, TRenderer AnyRenderer[TProps]](renderer TRenderer, props TProps, width, height int) string
- func SetCurrentRoute(newRoute string)
- func WasRouteChanged() bool
- type AfterUpdater
- type AnyProplessRenderer
- type AnyRenderer
- type BasicComponent
- type BasicPropfulComponent
- type Component
- type DumbRenderer
- type InvisibleComponent
- type NoProps
- type ProplessRenderer
- type Renderer
- type SomeComponent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AfterUpdate ¶
func AfterUpdate(afterUpdater AfterUpdater)
Queue component for AfterUpdate event
func CurrentRoute ¶
func CurrentRoute() string
func RenderAny ¶
func RenderAny[TProps any, TRenderer AnyRenderer[TProps]](renderer TRenderer, props TProps, width, height int) string
Renders all AnyRenderers in one function
func SetCurrentRoute ¶
func SetCurrentRoute(newRoute string)
func WasRouteChanged ¶
func WasRouteChanged() bool
Types ¶
type AfterUpdater ¶
type AnyProplessRenderer ¶ added in v0.2.0
type AnyProplessRenderer interface {
ProplessRenderer | DumbRenderer
}
type AnyRenderer ¶ added in v0.2.0
type AnyRenderer[TProps any] interface { func(TProps, int, int) string | AnyProplessRenderer }
Why not Renderer[TProps]? It would have to be type alias there are no type aliases yet for generics, but they are planned for Go 1.20. Something to keep in mind for future
type BasicComponent ¶
type BasicComponent struct{}
The most basic form of reactea component It implements all not required methods so you don't have to
func (*BasicComponent) AfterUpdate ¶
func (c *BasicComponent) AfterUpdate() tea.Cmd
func (*BasicComponent) Destroy ¶
func (c *BasicComponent) Destroy()
type BasicPropfulComponent ¶
type BasicPropfulComponent[TProps any] struct { // contains filtered or unexported fields }
Stores props in struct. If you want to derive state from UpdateProps() you're probably looking at wrong thing
func (*BasicPropfulComponent[TProps]) Init ¶
func (c *BasicPropfulComponent[TProps]) Init(props TProps) tea.Cmd
func (*BasicPropfulComponent[TProps]) Props ¶
func (c *BasicPropfulComponent[TProps]) Props() TProps
func (*BasicPropfulComponent[TProps]) UpdateProps ¶
func (c *BasicPropfulComponent[TProps]) UpdateProps(props TProps)
type Component ¶
type Component[TProps any] interface { // You always have to initialize component with some kind of // props - it can even be zero value // Init() Is meant to both initialize subcomponents and run // long IO operations through tea.Cmd Init(TProps) tea.Cmd // It's called when component is about to be destroyed // // Note: It's parent component's job to call it so // relying on it outside of reactea builtins is // not reliable Destroy() // Typical tea.Model Update(), we handle all IO events here Update(tea.Msg) tea.Cmd // Callee already knows at which size should it render at Render(int, int) string // It's an Update() but for props, the state derive stage // happens here UpdateProps(TProps) // AfterUpdate is stage useful for components like routers // to prepare content. Saying that you will probably never // need to use it AfterUpdate() tea.Cmd }
func Componentify ¶ added in v0.2.0
func Componentify[TProps any, TRenderer AnyRenderer[TProps]](renderer TRenderer) Component[TProps]
Componentifies AnyRenderer Returns uninitialized component with renderer taking care of .Render()
type DumbRenderer ¶
type DumbRenderer = func() string
Doesn't have state, props, even scalling for target dimensions = DumbRenderer, or Stringer
type InvisibleComponent ¶
type InvisibleComponent struct{}
Utility component for displaying empty string on Render()
type ProplessRenderer ¶
SUPEEEEEER shorthand for components
func PropfulToLess ¶
func PropfulToLess[TProps any](renderer Renderer[TProps], props TProps) ProplessRenderer
Wraps propful into propless renderer
type Renderer ¶
Ultra shorthand for components = just renderer One could say it's a stateless component Also note that it doesn't handle any IO by itself
TODO: Change to type alias after type aliases for generics support is released (planned Go 1.20). For now explicit type conversion is required
type SomeComponent ¶
type SomeComponent interface {
Destroy()
Update(tea.Msg) tea.Cmd
Render(int, int) string
AfterUpdate() tea.Cmd
}
Interface which is basically reactea.Component just without the props part
func SomeComponentify ¶ added in v0.2.0
func SomeComponentify[TProps any, TRenderer AnyRenderer[TProps]](renderer TRenderer, initialProps TProps) SomeComponent
I don't care about props, just give me SomeComponent
Source Files
Directories