hypp

README

Hypp

Hypp (pronounced /haɪp/, like 'hype') is a library for building user interfaces. Its API is based on Hyperapp. Its name is a combination of the first two letters and last two letters of Hyperapp.

Tests

go test $(GOOS=js GOARCH=wasm go list ./... | grep -vE 'cmd/js|jsd')

License

Hypp is published under the AGPL, which can be found here.

Hypp is derived from Hyperapp. Hyperapp is published under the MIT License which is included here.

Note that Hypp is NOT published under the MIT License.

Development

Dependencies:

• errcheck
• mockery
• staticcheck

Setup

Run the following to configure the git hooks. This ensures everyone is using the same git hooks:

git config core.hooksPath ./hooks

The pre-commit hook will run the linters and tests.

Package dependency graph

Below you'll find the package dependency graph. Note that jsd depends on syscall/js, which only builds with GOOS=js GOARCH=wasm.

flowchart TD

jsd --> js
jsd --> syscall-js["syscall/js"]

tag --> hypp

window --> js

hypp --> js
hypp --> window

Documentation

Overview

Package hypp creates reactive web applications.

Index

• func MustValidateHProps(props HProps)
• func ValidateHProps(props HProps) error
• type Action
• type ActionAndPayload
• type AppProps
  • func (a AppProps[S]) Validate() error
• type Dispatch
  • func App[S State](props AppProps[S]) Dispatch
• type Dispatchable
• type Effect
• type HProps
  • func MergeHProps(props ...HProps) HProps
  • func (h HProps) Has(key string) bool
  • func (h *HProps) Merge(other HProps)
  • func (h *HProps) Set(key string, value any)
• type MemoData
• type Payload
• type State
• type StateAndEffects
• type Subscription
• type Subscriptions
• type Unsubscribe
• type VNode
  • func H(tag string, props HProps, children ...*VNode) *VNode
  • func Memo(view func(data MemoData) *VNode, data MemoData) *VNode
  • func Text(value string) *VNode
  • func Textf(format string, a ...any) *VNode
  • func (n VNode) Children() []*VNode
  • func (n VNode) Kind() VNodeKind
  • func (n VNode) Props() HProps
  • func (n VNode) Tag() string
• type VNodeKind

Functions

func MustValidateHProps

func MustValidateHProps(props HProps)

MustValidateHProps calls ValidateHProps and panics if an error is returned.

func ValidateHProps

func ValidateHProps(props HProps) error

ValidateHProps validates the given HProps. It returns an error if any of the keys have an invalid value. See the description of HProps for a table of the keys and their allowed value types.

Types

type Action

type Action[S State] func(state S, payload Payload) Dispatchable

Action is a function which describes a transition between the current state and the next state. It must not perform any side-effects, but it may return side-effects using StateAndEffects.

An action is dispatched by either a DOM event, the effecter of an Effect, or the subscriber of a Subscription. When dispatched, an action always receives the current State as its first argument and an optional Payload as its second argument. An action that is dispatched by a DOM event will receive a window.Event as payload. An action that is dispatched by an ActionAndPayload will receive the 'Payload' field as payload.

type ActionAndPayload

type ActionAndPayload[S State] struct {
	Action  Action[S]
	Payload Payload
}

ActionAndPayload contains an Action and Payload. When the action is dispatched, it receives the current state as its first argument and the payload as its second argument.

type AppProps

type AppProps[S State] struct {
	// Init is the dispatchable that initializes the app.
	Init Dispatchable
	// Optional slice of subscriptions.
	Subscriptions Subscriptions[S]
	// Optional function that wraps the Dispatch function.
	DispatchWrapper func(dispatch Dispatch) Dispatch
	// View renders the app given the state.
	// It cannot be nil.
	View func(state S) *VNode
	// Node must have a parentNode that is not null.
	Node window.Element
	// contains filtered or unexported fields
}

AppProps is passed as an argument when creating an App.

func (AppProps[S]) Validate

func (a AppProps[S]) Validate() error

Validate returns an error if one of the following is true:

• View is nil.
• Node is falsy.
• Node has a null parentNode.

type Dispatch

type Dispatch func(dispatchable Dispatchable, payload Payload)

Dispatch is a function that controls Hypp's core dispatching process which executes actions, applies state transitions, runs effects, and starts/stops subscriptions that need it.

func App

func App[S State](props AppProps[S]) Dispatch

App creates a new application.

It panics if the js.GetDriver returns nil. It also panics if AppProps.Validate returns an error for the given props.

type Dispatchable

type Dispatchable any

Dispatchable is implemented by types that, when dispatched, change the state. There are four dispatchable types:

• Types that implement the State constraint.
• StateAndEffects
• Action or 'func(state S, payload Payload) Dispatchable'
• ActionAndPayload

type Effect

type Effect struct {
	// Effecter is the function that actually carries out an effect.
	Effecter func(dispatch Dispatch, payload Payload)
	Payload  Payload
}

Effect is used to deal with impure asynchronous interactions with the outside world in a safe, pure, and immutable way. Creating an HTTP request, giving focus to a DOM element, saving data to local storage, sending data over a WebSocket, and so on, are all examples of effects at a conceptual level.

An Action can associate its state transition with a list of one or more effects to run alongside the transition. It does this by returning a StateAndEffects.

type HProps

type HProps map[string]any

HProps are the properties to create a VNode.

The allowed value type depends on the key:

| Key               | Value type                                            |
| ----------------- | ----------------------------------------------------- |
| Starts with "on"  | Dispatchable, nil                                     |
| "class"           | bool, int, float64, string, []string, map[string]bool |
| "style"           | map[string]string                                     |
| Other             | bool, int, float64, string                            |

func MergeHProps

func MergeHProps(props ...HProps) HProps

MergeHProps merges a slice of HProps into a new HProps.

The resulting HProps contains all key value pairs of the given HProps. If a key is present in multiple HProps, the value of the last HProps will be used.

func (HProps) Has

func (h HProps) Has(key string) bool

Has returns true if the requested key is found.

func (*HProps) Merge

func (h *HProps) Merge(other HProps)

Merge merges the other HProps into the current HProps.

func (*HProps) Set

func (h *HProps) Set(key string, value any)

Set sets the given key value pair. It is safe to call this method on a nil value.

type MemoData

type MemoData interface {
	Hash() string
}

MemoData is the data passed when creating a Memo. The Memo will only rerender the view if Hash returns a different value.

type Payload

type Payload any

Payload is the value that is dispatched.

type State

type State interface {
	comparable
}

State constrains the state that is used in the Hypp application. It must be comparable.

type StateAndEffects

type StateAndEffects[S State] struct {
	State   S
	Effects []Effect
}

StateAndEffects contains a State and an Effect slice.

type Subscription

type Subscription struct {
	Subscriber func(dispatch Dispatch, payload Payload) Unsubscribe
	Payload    Payload

	Disabled bool
	// contains filtered or unexported fields
}

Subscription is used to deal with impure, asynchronous interactions with the outside world in a safe, pure, and immutable way. It is a streamlined way of responding to events happening outside our application such as time or location changes. It handles resource management for us that we would otherwise need to worry about, like adding and removing event listeners, closing connections, etc.

On every state change, Hypp will check each subscription to see if it's active and compare that with how it was in the previous state. This comparison determines how subscriptions are handled.

| Previously Active | Currently Active | What Happens                                 |
| ----------------- | ---------------- | -------------------------------------------- |
| no                | no               | Nothing.                                     |
| no                | yes              | Subscription starts up.                      |
| yes               | no               | Subscription shuts down and gets cleaned up. |
| yes               | yes              | Subscription remains active.                 |

To restart a subscription you must first deactivate it and then, during the next state change, reactivate it.

A Subscription consists of a Subscriber, a Payload and the Disabled field.

• The Subscriber is the function which implements the active subscription. A Subscriber is allowed to use side-effects and can manually dispatch actions in order to inform your app of any pertinent results from their execution. It returns an Unsubscribe function to clean up the subscription if it gets cancelled.
• The Payload field will be passed as second argument to the Subscriber function.
• The Disabled field is used to control whether a subscription is active or not.

type Subscriptions

type Subscriptions[S State] func(state S) []Subscription

Subscriptions returns the Subscription slice for the current state. The slice must always have the same size and each Subscription must always stay in the same position. Use a Subscription's Disabled field to disable a conditional Subscription.

type Unsubscribe

type Unsubscribe func()

Unsubscribe is a function that cleans up a Subscription when cancelled.

type VNode

type VNode struct {
	// contains filtered or unexported fields
}

VNode is a virtual node that corresponds to a DOM element.

func H

func H(tag string, props HProps, children ...*VNode) *VNode

H creates a new VNode specified by tag.

See the tag package for functions that create specific tags:

package main

import (
	"github.com/macabot/hypp"
	"github.com/macabot/hypp/tag/html"
)

func main() {
	hypp.H("main", hypp.HProps{"class": "example"})
	// Is equivalent to
	html.Main(hypp.HProps{"class": "example"})
}

func Memo

func Memo(view func(data MemoData) *VNode, data MemoData) *VNode

Memo is a wrapper function to cache views based on properties you pass into them. This is an optimization technique known as memoization.

func Text

func Text(value string) *VNode

Text creates a text VNode.

func Textf

func Textf(format string, a ...any) *VNode

Textf creates a text VNode by interpolating the format with the arguments.

func (VNode) Children

func (n VNode) Children() []*VNode

Children returns the VNode's children.

func (VNode) Kind

func (n VNode) Kind() VNodeKind

Kind returns the VNode's VNodeKind.

func (VNode) Props

func (n VNode) Props() HProps

Props returns the VNode's properties.

func (VNode) Tag

func (n VNode) Tag() string

Tag returns the VNode's tag.

type VNodeKind

type VNodeKind int

VNodeKind indicates the type of VNode.

const (
	// ElementNode indicates a VNode that renders an element node.
	ElementNode VNodeKind = 1
	// TextNode indicates a VNode that renders text inside an element node.
	TextNode VNodeKind = 3
)

Each constant corresponds to an element's nodeType. Use H to create an ElementNode VNode. Use Text or Textf to create a TextNode VNode.