Module

Elmish

Package: purescript-elmish
Repository: collegevine/purescript-elmish

Re-exports from Elmish.Boot

#BootRecord Source

type BootRecord props = { hydrate :: String -> props -> Effect Unit, mount :: String -> props -> Effect Unit, renderToString :: props -> String }

Support for the most common case entry point - i.e. mounting an Elmish component (i.e. ComponentDef' structure) to an HTML DOM element with a known ID, with support for server-side rendering.

The function boot returns what we call BootRecord - a record of three functions:

mount - takes HTML element ID and props¹, creates an instance of the component, and mounts it to the HTML element in question
hydrate - same as mount, but expects the HTML element to already contain pre-rendered HTML inside. See React docs for more on server-side rendering: https://reactjs.org/docs/react-dom.html#hydrate
renderToString - meant to be called on the server (e.g. by running the code under NodeJS) to perform the server-side render. Takes props¹ and returns a String containing the resulting HTML.

The idea is that the PureScript code would export such BootRecord for consumption by bootstrap JavaScript code in the page and/or server-side NodeJS code (which could be written in PureScript or not). For "plain React" scenario, the JavaScript code in the page would just call mount. For "server-side rendering", the server would first call renderToString and serve the HTML to the client, and then the client-side JavaScript code would call hydrate.

¹ "props" here is a parameter used to instantiate the component (see example below). It is recommended that this parameter is a JavaScript record (hence the name "props"), because it would likely need to be supplied by some bootstrap JavaScript code.

Example:

-- PureScript:
module Foo(bootRecord) where

type Props = { hello :: String, world :: Int }

component :: Props -> ComponentDef' Aff Message State
component = ...

bootRecord :: BootRecord Props
bootRecord = boot component


// Server-side JavaScript NodeJS code
const foo = require('output/Foo/index.js')
const fooHtml = foo.bootRecord.renderToString({ hello: "Hi!", world: 42 })
serveToClient("<html><body><div id='foo'>" + fooHtml + "</div></body></html>")


// Client-side HTML + JS:
<html>
   <body>
     <div id='foo'>
       ... server-side-rendered HTML goes here
     </div>
   </body>
   <script src="foo_bundle.js" />
   <script>
     Foo.bootRecord.hydrate('foo', { hello: "Hi!", world: 42 })
   </script>
</html>

#boot Source

boot :: forall msg state props. (props -> ComponentDef msg state) -> BootRecord props

Creates a boot record for the given component. See comments for BootRecord.

Re-exports from Elmish.Component

#Transition' Source

data Transition' :: (Type -> Type) -> Type -> Type -> Typedata Transition' m msg state

A UI component state transition: wraps the new state value together with a (possibly empty) list of effects that the transition has caused (called "commands"), with each command possibly producing some new messages.

Instances of this type may be created either by using the smart constructor:

update :: State -> Message -> Transition' Aff Message State
update state m = transition state [someCommand]

or in monadic style (see comments on fork for more on this):

update :: State -> Message -> Transition' Aff Message State
update state m = do
    s1 <- Child1.update state.child1 Child1.SomeMessage # lmap Child1Msg
    s2 <- Child2.modifyFoo state.child2 # lmap Child2Msg
    fork someEffect
    pure state { child1 = s1, child2 = s2 }

or, for simple sub-component delegation, the BiFunctor instance may be used:

update :: State -> Message -> Transition' Aff Message State
update state (ChildMsg m) =
    Child.update state.child m
    # bimap ChildMsg (state { child = _ })

Constructors

Transition state (Array (Command m msg))

Instances

(Functor m) => Bifunctor (Transition' m)
Functor (Transition' m msg)
Apply (Transition' m msg)
Applicative (Transition' m msg)
Bind (Transition' m msg)
Monad (Transition' m msg)

#Transition Source

type Transition msg state = Transition' Aff msg state

#ComponentDef' Source

type ComponentDef' :: (Type -> Type) -> Type -> Type -> Typetype ComponentDef' m msg state = { init :: Transition' m msg state, update :: state -> msg -> Transition' m msg state, view :: state -> Dispatch msg -> ReactElement }

Definition of a component according to The Elm Architecture. Consists of three functions - init, view, update, - that together describe the lifecycle of a component.

Type parameters:

m - a monad in which the effects produced by update and init functions run.
msg - component's message.
state - component's state.

#ComponentDef Source

type ComponentDef msg state = ComponentDef' Aff msg state

A ComponentDef' in which effects run in Aff.

#withTrace Source

withTrace :: forall m msg state. DebugWarning => ComponentDef' m msg state -> ComponentDef' m msg state

Wraps the given component, intercepts its update cycle, and traces (i.e. prints to dev console) every command and every state value (as JSON objects), plus timing of renders and state transitions.

#transition Source

transition :: forall m state msg. Bind m => MonadEffect m => state -> Array (m msg) -> Transition' m msg state

Smart constructor for the Transition' type. See comments there. This function takes the new (i.e. updated) state and an array of commands - i.e. effects producing messages - and constructs a Transition' out of them

#rmap Source

rmap :: forall f a b c. Bifunctor f => (b -> c) -> f a b -> f a c

Map a function over the second type arguments of a Bifunctor.

#nat Source

nat :: forall m n msg state. (m ~> n) -> ComponentDef' m msg state -> ComponentDef' n msg state

Monad transformation applied to ComponentDef'

#lmap Source

lmap :: forall f a b c. Bifunctor f => (a -> b) -> f a c -> f b c

Map a function over the first type argument of a Bifunctor.

#forks Source

forks :: forall m message. Command m message -> Transition' m message Unit

Similar to fork (see comments there for detailed explanation), but the parameter is a function that takes a message-dispatching callback. This structure allows the command to produce zero or multiple messages, unlike fork, whose callback has to produce exactly one.

Example:

update :: State -> Message -> Transition' Aff Message State
update state msg = do
    forks countTo10
    pure state

countTo10 :: Command Aff Message
countTo10 msgSink =
    for_ (1..10) \n ->
        delay $ Milliseconds 1000.0
        msgSink $ Count n

#forkVoid Source

forkVoid :: forall m message. m Unit -> Transition' m message Unit

Similar to fork (see comments there for detailed explanation), but the effect doesn't produce any messages, it's a fire-and-forget sort of effect.

#forkMaybe Source

forkMaybe :: forall m message. MonadEffect m => m (Maybe message) -> Transition' m message Unit

Similar to fork (see comments there for detailed explanation), but the effect may or may not produce a message, as modeled by returning Maybe.

#fork Source

fork :: forall m message. MonadEffect m => m message -> Transition' m message Unit

Creates a Transition' that contains the given command (i.e. a message-producing effect). This is intended to be used for "accumulating" effects while constructing a transition in imperative-ish style. When used as an action inside a do block, this function will have the effect of "adding the command to the list" to be executed. The name fork reflects the fact that the given effect will be executed asynchronously, after the update function returns.

In more precise terms, the following:

trs :: Transition' m Message State
trs = do
    fork f
    fork g
    pure s

Is equivalent to this:

trs :: Transition' m Message State
trs = transition s [f, g]

At first glance it may seem that it's shorter to just call the transition smart constructor, but monadic style comes in handy for composing the update out of smaller pieces. Here's a more full example:

data Message = ButtonClicked | OnNewItem String

update :: State -> Message -> Transition' Aff Message State
update state ButtonClick = do
    fork $ insertItem "new list"
    incButtonClickCount state
update state (OnNewItem str) =
    ...

insertItem :: Aff Message
insertItem name = do
    delay $ Milliseconds 1000.0
    pure $ OnNewItem name

incButtonClickCount :: Transition' Aff Message State
incButtonClickCount state = do
    forkVoid $ trackingEvent "Button click"
    pure $ state { buttonsClicked = state.buttonsClicked + 1 }

#construct Source

construct :: forall msg state. ComponentDef msg state -> Effect ReactElement

Given a ComponentDef', binds that def to a freshly created React class, instantiates that class, and returns a rendering function. Note that the return type of this function is almost the same as that of ComponentDef'::view - except for state. This is not a coincidence: it is done this way on purpose, so that the result of this call can be used to construct another ComponentDef'.

Unlike wrapWithLocalState, this function uses the bullet-proof strategy of storing the component state in a dedicated mutable cell, but that happens at the expense of being effectful.

#bimap Source

bimap :: forall f a b c d. Bifunctor f => (a -> b) -> (c -> d) -> f a c -> f b d

Re-exports from Elmish.Dispatch

#EffectFn2 Source

data EffectFn2 t0 t1 t2

Instances

(Semigroup r) => Semigroup (EffectFn2 a b r)
(Monoid r) => Monoid (EffectFn2 a b r)

#EffectFn1 Source

data EffectFn1 t0 t1

Instances

(Semigroup r) => Semigroup (EffectFn1 a r)
(Monoid r) => Monoid (EffectFn1 a r)

#Dispatch Source

type Dispatch msg = msg -> Effect Unit

A function that a view can use to report messages originating from JS/DOM.

#mkEffectFn2 Source

mkEffectFn2 :: forall a b r. (a -> b -> Effect r) -> EffectFn2 a b r

#mkEffectFn1 Source

mkEffectFn1 :: forall a r. (a -> Effect r) -> EffectFn1 a r

#handleMaybe Source

handleMaybe :: forall arg msg. Dispatch msg -> (arg -> Maybe msg) -> EffectFn1 arg Unit

Same as handle, but dispatches a message optionally. See comments on handle for an example.

#handle Source

handle :: forall arg msg. Dispatch msg -> (arg -> msg) -> EffectFn1 arg Unit

A convenience function to make construction of event handlers with arguments (i.e. EffectFn1) a bit shorter. The function takes a Dispatch and a mapping from the event argument to a message which the given Dispatch accepts, and it's also available in operator form.

The following example demonstrates expected usage of both handle (in its operator form <|) and handleMaybe (in its operator form <?|):

textarea
  { value: state.text
  , onChange: dispatch <?| \e -> TextChanged <$> eventTargetValue e
  , onMouseDown: dispatch <| \_ -> TextareaClicked
  }

  where
    eventTargetValue = readForeign >=> lookup "target" >=> readForeign >=> lookup "value"

#(<|) Source

Operator alias for Elmish.Dispatch.handle (right-associative / precedence 9)

#(<?|) Source

Operator alias for Elmish.Dispatch.handleMaybe (right-associative / precedence 9)

Re-exports from Elmish.React

#Ref Source

data Ref (el :: Type)

An opaque type representing the type for React ref props

Instances

CanPassToJavaScript (Ref a)

#ReactElement Source

data ReactElement

Instantiated subtree of React DOM. JSX syntax produces values of this type.

Instances

#ReactComponent Source

data ReactComponent t0

This type represents constructor of a React component with a particular behavior. The type prameter is the record of props (in React lingo) that this component expects. Such constructors can be "rendered" into ReactElement via createElement.

#createElement' Source

createElement' :: forall props. ValidReactProps props => ReactComponent props -> props -> ReactElement

Variant of createElement for creating an element without children.

#createElement Source

createElement :: forall props content. ValidReactProps props => ReactChildren content => ReactComponent props -> props -> content -> ReactElement

The PureScript import of the React’s createElement function. Takes a component constructor, a record of props, some children, and returns a React DOM element.

To represent HTML data- attributes, createElement supports the _data :: Object prop.

Example

import Elmish.HTML as H
import Foreign.Object as FO

H.div
  { _data: FO.fromHomogenous { toggle: "buttons" } }
  [...]

represents the <div data-toggle="buttons"> DOM element.

#callbackRef Source

callbackRef :: forall el. Maybe el -> (Maybe el -> Effect Unit) -> Ref el

Takes the current ref value and a callback function (el -> Effect Unit) and returns a Ref. The current ref value is needed so that we can decide whether the callback function should be run (by comparing the current ref and the new one by reference). The callback function should add the el parameter to some state. E.g.:

data Message = RefChanged (Maybe HTMLInputElement) | …

view :: State -> Dispatch Message -> ReactElement
view state dispatch =
  H.input_ "" { ref: callbackRef state.inputElement (dispatch <<< RefChanged), … }

Modules: Elmish; Elmish.Boot; Elmish.Component; Elmish.Dispatch; Elmish.Foreign; Elmish.Opaque; Elmish.React; Elmish.React.DOM; Elmish.React.Import; Elmish.React.Ref; Elmish.State; Elmish.Trace