@@ -17,7 +17,7 @@ The following documents the expected conventions and best practices when definin

## Exports

All widgets should export at the minimum the following:

-```

+```haskell

module Glazier.React.Widgets.Input

( Command(..)

, Action(..)

@@ -42,7 +42,7 @@ Since all widgets export the same names, any widget should be imported qualified

## Command

`Command`s are the result of the `Gadget` stateful processing of `Action`. It is a pure value that is interpreted effectfully.

-```

+```haskell

data Command

= RenderCommand (SuperModel Model Plan) [Property] JSVal

| DisposeCommand SomeDisposable

@@ -51,26 +51,26 @@ data Command

Some common commands are:

### RenderCommand

-```

+```haskell

RenderCommand (SuperModel Model Plan) [Property] JSVal

```

This is send by `Gadget` when the re-rendering is required. It contains the`SuperModel` of the widget (to swap the latest `Design` into the `Frame`), the new React component state as a list of properties (usually just a sequence number), and the javascript reference to the javascript component.

### DisposeCommand

-```

+```haskell

DisposeCommand SomeDisposable

```

This contains the list of callbacks to dispose after the next render frame (after [`componentDidUpdate`](https://facebook.github.io/react/docs/react-component.html#componentdidupdate) is called.

### MakerCommand

-```

+```haskell

MakerCommand (F (Maker Action) Action)

```

This is the command to run the `Maker` instruction in the `Maker` interpreter which results in an `Action` to dispatch back tot he gadget.

## Action

This contains the events that the widget `Gadget` processes.

-```

+```haskell

data Action

= ComponentRefAction JSVal

| RenderAction

@@ -81,19 +81,19 @@ makeClassyPrisms ''Action

Some common `Action`s are:

### ComponentRefAction

-```

+```haskell

ComponentRefAction JSVal

```

This action is generated by the [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html) event listener and contains a javascript reference to the react component. This ref is used in the `RenderCommand`.

### RenderAction

-```

+```haskell

RenderAction

```

You can generate this action to force a widget to return the `RenderCommand` to force a re-render.

### ComponentDidUpdateAction

-```

+```haskell

ComponentDidUpdateAction JSVal

```

@@ -101,7 +101,7 @@ This action is generated by the [`componentDidUpdate`](https://facebook.github.i

## Model

This contains the pure data for state processing logic and rendering (the nouns).

-```

+```haskell

data Model = Model

{ _uid :: J.JSString

, _componentRef :: J.JSVal

@@ -114,25 +114,25 @@ makeClassy ''Model

Some common Model fields are

### uid

-```

+```haskell

_uid :: JSString

```

`uid` is used to ensure a unique [key](https://facebook.github.io/react/docs/lists-and-keys.html) for React's efficient rendering of a list.

### componentRef

-```

+```haskell

_componentRef :: JSVal

```

`componentRef` is used to store the reference to the instance of the React shim component from the `ComponentRefAction` and used in the `RenderCommand`

### frameNum

-```

+```haskell

_frameNum :: Int

```

`frameNum` is the sequence number used in `RenderCommand`.

### _deferredCommands

-```

+```haskell

_deferredCommands :: DList Command

```

`deferredCommands` keep the list of commands to run at the next `ComponentDidUpdateAction`. It usually contains `DisposeCommand`.

@@ -140,7 +140,7 @@ _deferredCommands :: DList Command

## Plan

The `Plan` contains the callbacks for integrating with React (the verbs). It also contains a javascript reference to the instance of shim component used for the widget. This reference is used to trigger rendering with [`setState`](https://facebook.github.io/react/docs/react-component.html#setstate).

-```

+```haskell

data Plan = Plan

{ _component :: R.ReactComponent

, _onRender :: J.Callback (J.JSVal -> IO J.JSVal)

@@ -152,25 +152,25 @@ data Plan = Plan

Some common `Plan` fields are

### _component

-```

+```haskell

_component :: ReactComponent

```

This contains the reference to the shim `React.PureComponent` class that is used to start the rendering.

### _onRender

-```

+```haskell

_onRender :: Callback (JSVal -> IO JSVal)

```

The is the callback from the shim component's [`render`](https://facebook.github.io/react/docs/react-component.html#render) handler. It contains a javascript reference to the shim component's state, which is currently not used, but might be in the future.

### _onComponentRef

-```

+```haskell

_onComponentRef :: Callback (JSVal -> IO ())

```

The is the callback from the shim component's [`ref`](https://facebook.github.io/react/docs/refs-and-the-dom.html) event listener. The callback is expected to generate the `ComponentRefAction`.

### _onComponentDidUpdate

-```

+```haskell

_onComponentDidUpdate :: Callback (JSVal -> IO ())

```

The is the callback from the shim component's [`componentDidUpdate`](https://facebook.github.io/react/docs/react-component.html#componentdidupdate) event listener. The callback is expected to generate the `ComponentDidUpdateAction`.

@@ -180,7 +180,7 @@ This is the missing piece required to construct a widget's `SuperModel`.

It contains the code to create a widget's `Plan` using the `Maker` DSL.

The `Applicative` typeclass makes this easy to define.

-```

+```haskell

mkPlan :: Frame Model Plan -> F (Maker Action) Plan

mkPlan frm = Plan

<$> getComponent

@@ -194,7 +194,7 @@ mkPlan frm = Plan

All widgets should have implementation of the following

### Disposing Model and Plan

-```

+```haskell

instance Disposing Plan

instance Disposing Model where

disposing _ = DisposeNone

@@ -203,7 +203,7 @@ instance Disposing Model where

### Link HasPlan and HasModel

Link `Glazier.React.Model`'s genericHasPlan/HasModel with this widget's specific `HasPlan`/`HasModel` from generated from `makeClassy`

-```

+```haskell

instance HasPlan (R.Design Model Plan) where

plan = R.plan

instance HasModel (R.Design Model Plan) where

@@ -215,7 +215,7 @@ instance HasModel (R.SuperModel Model Plan) where

```

### Synonums to Design, Frame, and SuperModel

-```

+```haskell

type Design = R.Design Model Plan

type Frame = R.Frame Model Plan

type SuperModel = R.SuperModel Model Plan

@@ -223,7 +223,7 @@ type SuperModel = R.SuperModel Model Plan

### Widget definitions

`widget` is a record of functions of the essential functions required to make, render and interact with the widget. By convention, `mkPlan`, `window`, and `gadget` is exported, but sometimes it's convenient to have all three grouped together in a record.

This is the starting rendering function to start the rendering. It always only renders the shim React component with the specific callbacks:

-```

+```haskell

window :: WindowT (Design Model Plan) (ReactMlT Identity) ()

window = do

s <- ask

@@ -255,14 +255,14 @@ This a a monad transformer stack over `Identity`. This ensures only pure effects

This is the inner rendering function. React will render the shim component from `window` above, and then call the `Plan`'s `onRender` callback of the shim component, which triggers this rendering function.

This contains the widget specific rendering instructions.

-```

+```haskell

render :: WindowT (Design Model Plan) (ReactMlT Identity) ()

```

This a a monad transformer stack over `Identity`. This ensures only pure effects are allowed.