React

Usage:

This tutorial assumes only a basic understanding of React, the DOM, and browser events. I recomment at least skimming the official React tutorial.

Let's start with a basic example:

page_ :: ReactNode Void
page_ =
    let cls = smartClass
            { name = "page"

            -- initially the input is empty
            , initialState = ""

            -- always transition to the input's new value
            , transition = (_, value) -> (value, Nothing)

            , renderFn = _ str -> div_ [ class_ "container" ] $ do
                input_ [ value_ str, onChange (Just . value . target) ]
            }
    in classLeaf cls ()

main :: IO ()
main = do
    Just doc <- currentDocument
    Just elem <- documentGetElementById doc ("elem" :: JSString)
    render page_ elem

In this example we defined a React class with Text state, but taking only () as a prop. It's possible to use anything for props and state -- numbers, JSON, even React classes.

In the example the input always contains the state from the class, and the state is updated on every input change event -- effectively, every keystroke.

Classes

data ReactClass props state insig exsig ctx

A ReactClass is a standalone component of a user interface which contains the state necessary to render itself. Classes are a tool for scoping.

Use createClass to construct.

• props: The type of props passed in.
• state: The type of state this class maintains.
• insig: The type of signals this class handles (see classTransition)
• exsig: The type of signals this class emits (see classTransition)
• ctx: This is only used for React's mythical context feature -- If you know what that is, see childContext for usage.

data ClassConfig props state insig exsig ctx

Constructors

ClassConfig

Fields

renderFn :: props -> state -> ReactNode insig

initialState :: state

name :: JSString

transition :: (state, insig) -> (state, Maybe exsig)

startupSignals :: [insig]

childContext :: Maybe (HashMap Text ctx)

type ClassCtx a = (ToJSRef a, PropTypable a)

A type that can be used in a child context.

React manages context (unlike props and state, which are managed entirely within Haskell), so anything used in child context must be convertable to a JSRef and must be describable by a PropType.

smartClass :: ClassConfig props state insig exsig JSString

Defaults for a stateful ("controller") class.

dumbClass :: ClassConfig props () sig sig JSString

Defaults for a stateless ("layout") class.

Rendering

render :: ReactNode Void -> Element -> IO ()

Render a top-level component.

Note that the rendered component can't possibly emit signals.

debugRender :: Show sig => ReactNode sig -> Element -> IO ()

Unlike render, debugRender can render components that emit signals, as long as they can be shown.

React Nodes

data ReactNode sig

Instances

IsString (ReactNode sig)

Monoid (ReactNode sig)

Events

data EventProperties e

Low level properties common to all events

Constructors

EventProperties

Fields

bubbles :: !Bool

cancelable :: !Bool

currentTarget :: !e

defaultPrevented :: !Bool

eventPhase :: !Int

isTrusted :: !Bool

evtTarget :: !e

eventType :: !JSString

Instances

NFData e => NFData (EventProperties e)

data Target

Constructors

Target

Fields

value :: !JSString

tagName :: !JSString

Instances

Show Target

Generic Target

FromJSRef Target

type Rep Target

data ModifierKeys

Constructors

ModifierKeys

Fields

altKey :: !Bool

ctrlKey :: !Bool

metaKey :: !Bool

shiftKey :: !Bool

Instances

Eq ModifierKeys

Show ModifierKeys

Generic ModifierKeys

NFData ModifierKeys

FromJSRef ModifierKeys

type Rep ModifierKeys

data MouseEvent

Constructors

MouseEvent

Fields

clientX :: !Double

clientY :: !Double

pageX :: !Double

pageY :: !Double

screenX :: !Double

screenY :: !Double

Instances

Show MouseEvent

Generic MouseEvent

NFData MouseEvent

FromJSRef MouseEvent

type Rep MouseEvent

data KeyboardEvent

Constructors

KeyboardEvent

Fields

charCode :: !Int

key :: !JSString

keyCode :: !Int

location :: !Int

repeat :: !Bool

which :: !Int

Instances

Show KeyboardEvent

Generic KeyboardEvent

NFData KeyboardEvent

FromJSRef KeyboardEvent

type Rep KeyboardEvent

data ChangeEvent

Constructors

ChangeEvent

Fields

target :: !Target

timeStamp :: !Int

Instances

Show ChangeEvent

Generic ChangeEvent

NFData ChangeEvent

FromJSRef ChangeEvent

type Rep ChangeEvent

data FocusEvent

Constructors

FocusEvent

Instances

Generic FocusEvent

NFData FocusEvent

FromJSRef FocusEvent

type Rep FocusEvent

data BlurEvent

Constructors

BlurEvent

Instances

Show BlurEvent

Generic BlurEvent

NFData BlurEvent

FromJSRef BlurEvent

type Rep BlurEvent

Native Events

onBlur :: (BlurEvent -> Maybe s) -> AttrOrHandler s

onFocus :: (FocusEvent -> Maybe s) -> AttrOrHandler s

onChange :: (ChangeEvent -> Maybe s) -> AttrOrHandler s

onKeyDown :: (KeyboardEvent -> Maybe s) -> AttrOrHandler s

onKeyPress :: (KeyboardEvent -> Maybe s) -> AttrOrHandler s

onKeyUp :: (KeyboardEvent -> Maybe s) -> AttrOrHandler s

onMouseEnter :: (MouseEvent -> Maybe s) -> AttrOrHandler s

onMouseLeave :: (MouseEvent -> Maybe s) -> AttrOrHandler s

onDoubleClick :: (MouseEvent -> Maybe s) -> AttrOrHandler s

onClick :: (MouseEvent -> Maybe s) -> AttrOrHandler s

Synthetic Events

onEnter :: s -> AttrOrHandler s

Local

class GeneralizeSignal sigloc siggen where

Implement when a local signal can be generalized to a higher level one. Used by locally

Methods

generalizeSignal :: sigloc -> siggen

Instances

GeneralizeSignal a a

GeneralizeSignal Void a

locally :: GeneralizeSignal sigloc siggen => ReactNode sigloc -> ReactNode siggen

locally exists to make it simple to embed classes with local concerns. An example will be helpful:

We have some page which can respond to many different events.

data Transition
    = UserTyping JSString
    | Toggle
    ...

globalPage_ :: [AttrOrHandler Transition] -> ReactNode Transition

And we want to be able to embed some components that don't care about all that. inputBox_ can only output JSString and pageHeader_ can't send any signals at all.

inputBox_ :: ReactNode JSString
pageHeader_ :: ReactNode Void

With locally we can easily embed them in globalPage_:

instance GeneralizeSignal JSString Transition where
    generalizeSignal = UserTyping

-- (globalPage_)
renderFn = props state -> div_ [ class_ "global-page" ] $ do
    locally pageHeader_
    ...
    locally inputBox_
    ...

data AttrOrHandler signal

Attributes

newtype NoProps

When importing a foreign class you must specify the props it takes. In the common case where it takes no props, only handles layout, it's convenient to specify the type of props as NoProps.

Example:

pageLayout_ :: ReactNode () -> ReactNode () pageLayout_ = importParentClass pageLayout noProps

Constructors

NoProps ()

Instances

ToJSRef NoProps

noProps :: NoProps

Used when importing a foreign class taking no props. See above example.

mkStaticAttr :: ToJSON a => Text -> a -> AttrOrHandler sig

key_ :: Text -> AttrOrHandler sig

class_ :: Text -> AttrOrHandler sig

href_ :: Text -> AttrOrHandler sig

id_ :: Text -> AttrOrHandler sig

src_ :: Text -> AttrOrHandler sig

value_ :: Text -> AttrOrHandler sig

placeholder_ :: Text -> AttrOrHandler sig

for_ :: Text -> AttrOrHandler sig

type_ :: Text -> AttrOrHandler sig

checked_ :: Bool -> AttrOrHandler sig

autofocus_ :: Bool -> AttrOrHandler sig

width_ :: Double -> AttrOrHandler sig

height_ :: Double -> AttrOrHandler sig

cx_ :: Double -> AttrOrHandler sig

cy_ :: Double -> AttrOrHandler sig

d_ :: Double -> AttrOrHandler sig

dx_ :: Double -> AttrOrHandler sig

dy_ :: Double -> AttrOrHandler sig

x_ :: Double -> AttrOrHandler sig

y_ :: Double -> AttrOrHandler sig

r_ :: Double -> AttrOrHandler sig

fill_ :: Text -> AttrOrHandler sig

viewBox_ :: Text -> AttrOrHandler sig

points_ :: Text -> AttrOrHandler sig

transform_ :: Text -> AttrOrHandler sig

Creating Elements

Class creation

classParent :: ClassCtx ctx => ClassConfig props state insig exsig ctx -> ReactNode insig -> props -> ReactNode exsig

classLeaf :: ClassCtx ctx => ClassConfig props state insig exsig ctx -> props -> ReactNode exsig

JS Interop

exportClassLeaf :: ClassCtx ctx => ClassConfig props state insig exsig ctx -> ExportedClass

importLeafClass :: ToJSRef props => ImportedClass props sig -> props -> ReactNode sig

importParentClass :: ToJSRef props => ImportedClass props sig -> props -> ReactNode sig -> ReactNode sig

data ExportedNode sig

Instances

ToJSRef (ExportedNode sig)

type ExportedClass = JSRef ExportedClass_

JS Interop

type ImportedClass props sig = JSRef (ImportedClass_ props sig)

PropTypes

data PropRequired

Constructors

IsRequired

IsntRequired

data PropType

The equivalent to React propTypes.

Constructors

PropBool PropRequired

PropFunc PropRequired

PropNumber PropRequired

PropString PropRequired

PropObject PropRequired

class PropTypable a

Describe the PropType of a type

Examples:

propType (_ :: JSString) = PropString IsRequired

propType (_ :: Bool) = PropBool IsRequired

Minimal complete definition

propType

Instances

PropTypable JSString

PropTypable (JSRef ())