diff --git a/react-haskell.cabal b/react-haskell.cabal --- a/react-haskell.cabal +++ b/react-haskell.cabal @@ -1,5 +1,5 @@ name: react-haskell -version: 2.0.0 +version: 2.0.1 synopsis: Haskell React bindings description: This package provides high level bindings to Facebook's library, meant for use with GHCJS. @@ -10,24 +10,29 @@ . Here's a simple example which demonstrates basic elements, attributes, state, and handling events. . - > -- We're creating a class with JSString state - > data Example - > instance ReactKey Example where - > type ClassState Example = JSString - > type AnimationState Example = () - > type Signal Example = JSString + > page_ :: ReactNode Void + > page_ = + > let cls = smartClass + > -- this is a record and these should really be curly braces, + > -- but haddock breaks on them. + > [ name = "page" > - > -- updating to the new state without animation - > transition :: JSString -> JSString -> (JSString, [AnimConfig Example]) - > transition oldState signal = (signal, []) + > -- initially the input is empty + > , initialState = "" > - > view :: JSString -> React Example () - > view str = div_ [ class_ "container" ] $ do - > input_ [ value_ str, onChange (Just . value . target) ] + > -- 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 = withElem "id" $ \elem -> - > render elem =<< createClass view transition "" () [] + > main = do + > Just doc <- currentDocument + > Just elem <- documentGetElementById doc ("elem" :: JSString) + > render page_ elem license: MIT license-file: LICENSE author: Joel Burget diff --git a/src/React.hs b/src/React.hs --- a/src/React.hs +++ b/src/React.hs @@ -1,15 +1,56 @@ - +-- | -- Module : React -- Copyright : (C) 2014-15 Joel Burget -- License : MIT -- Maintainer : Joel Burget -- Stability : experimental -- Portability : non-portable +-- +-- Usage: +-- +-- This tutorial assumes only a basic understanding of React, the DOM, and +-- browser events. I recomment at least skimming the [official React +-- tutorial](https://facebook.github.io/react/docs/tutorial.html). +-- +-- 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. module React ( -- * Classes ReactClass() , ClassConfig(..) + , ClassCtx , smartClass , dumbClass @@ -38,6 +79,11 @@ -- * JS Interop , ImportedClass + + -- * PropTypes + , PropRequired(IsRequired, IsntRequired) + , PropType(..) + , PropTypable ) where -- TODO @@ -55,3 +101,4 @@ import React.Elements import React.Events import React.Rebindable +import React.PropTypes diff --git a/src/React/Class.hs b/src/React/Class.hs --- a/src/React/Class.hs +++ b/src/React/Class.hs @@ -54,6 +54,7 @@ } +-- | Defaults for a stateless ("layout") class. dumbClass :: ClassConfig props () sig sig JSString dumbClass = ClassConfig { name = "Anonymous Stateless Class" @@ -65,6 +66,7 @@ } +-- | Defaults for a stateful ("controller") class. smartClass :: ClassConfig props state insig exsig JSString smartClass = ClassConfig { name = "Anonymous Stateful Class" @@ -90,6 +92,11 @@ deallocRegistry registry componentId +-- | 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'. type ClassCtx a = (ToJSRef a, PropTypable a) diff --git a/src/React/PropTypes.hs b/src/React/PropTypes.hs --- a/src/React/PropTypes.hs +++ b/src/React/PropTypes.hs @@ -50,6 +50,7 @@ data PropRequired = IsRequired | IsntRequired +-- | The equivalent to React propTypes. data PropType -- = PropArrayOf PropType = PropBool PropRequired @@ -74,6 +75,16 @@ ptReq IsRequired = fIsRequired ptReq IsntRequired = id + +-- | Describe the PropType of a type +-- +-- Examples: +-- +-- @ +-- propType (_ :: JSString) = PropString IsRequired +-- +-- propType (_ :: Bool) = PropBool IsRequired +-- @ class PropTypable a where propType :: a -> PropType diff --git a/src/React/Render.hs b/src/React/Render.hs --- a/src/React/Render.hs +++ b/src/React/Render.hs @@ -13,17 +13,18 @@ import React.Types --- `Void` forces our top-level class `transition` to always choose `Nothing` --- over outputting a signal. +-- | Render a top-level component. +-- +-- Note that the rendered component can't possibly emit signals. render :: ReactNode Void -> Element -> IO () render node elem = do - -- XXX node' <- reactNodeToJSAny undefined 0 node js_render node' elem +-- | Unlike 'render', 'debugRender' can render components that emit signals, as +-- long as they can be shown. debugRender :: Show sig => ReactNode sig -> Element -> IO () debugRender node elem = do - -- XXX node' <- reactNodeToJSAny print 0 node js_render node' elem diff --git a/src/React/Types.hs b/src/React/Types.hs --- a/src/React/Types.hs +++ b/src/React/Types.hs @@ -49,6 +49,12 @@ -- 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 ReactClass props state insig exsig ctx = ReactClass { classForeign :: JSAny , classTransition :: (state, insig) -> (state, Maybe exsig)