# Components

> The Component record, composition with (+>), keys and the mount / unmount lifecycle.

Source: https://haskell-miso.org/docs/components/

A `Component` bundles a model, the `update` that evolves it and the `view` that renders it — plus everything around the edges: subscriptions, lifecycle hooks, a mailbox. Components nest, forming a typed UI tree.

> **Note:** Always build components with the `component` smart constructor — `component m u v` — rather than the `Component` record constructor directly. It fills every other field with sane defaults; override the ones you need with record-update syntax, e.g. `(component m u v) { subs = [...] }`.

## The record

The `component` smart constructor fills in sane defaults; you override fields with record update syntax:

```haskell
data Component context props model action = Component
  { model :: model
    -- initial model
  , hydrateModel :: Maybe (IO model)
    -- optional model to hydrate from (SSR)
  , update
      :: action
      -> Effect context props model action
  , view
      :: model
      -> View context props model action
  , useContext :: Bool
    -- re-render when the global context changes
  , subs :: [ Sub action ]
    -- long-running subscriptions
  , styles :: [ CSS ]
    -- dev only: append <style>/<link> to <head>
  , scripts :: [ JS ]
    -- dev only: append <script> to <head>
  , mountPoint :: Maybe MountPoint
    -- defaults to <body>
  , logLevel :: LogLevel
    -- Off | DebugHydrate | DebugEvents | DebugAll
  , mailbox :: Value -> Maybe action
    -- receive mail from other components
  , eventPropagation :: Bool
    -- let events bubble past this component
  , mount :: Maybe action
    -- action dispatched on mount
  , unmount :: Maybe action
    -- action dispatched on unmount
  , onPropsChanged
      :: Maybe (props -> props -> action)
  }
```

## Composition

Components can contain other components. This is accomplished through the mounting combinator `(+>)`, which encodes a typed component hierarchy. All components in a tree share the same global `context` type.

```haskell
(+>)
  :: (Eq context, Eq model)
  => MisoString
  -> Component context () model action
  -> View context props parentModel parentAction
key +> comp = VComp (SomeComponent (Just (toKey key)) () comp)
```

Practically, using this combinator looks like:

```haskell
viewModel
  :: Int
  -> View context props Int Action
viewModel _ =
  H.div_ [ HP.id_ "container" ]
    [ "counter" +> counter ]
```

The `"counter"` string is a unique `Key` that identifies the component at runtime. Keys matter when diffing two components: when intentionally replacing a component it is important to specify a new key, otherwise the old one will not be unmounted.

It is possible to mount a component with `mount_`, which avoids specifying a key, but this should only be used when you are certain the component will never be diffed against another component. When in doubt, use `(+>)` and key your component. To pass [props](https://haskell-miso.org/docs/props/) use `mountWithProps_` (keyed) or `mountWithProps`.

## Lifecycle hooks

Components are mounted during diffing. All components are equipped with `mount` and `unmount` hooks, allowing custom actions to be dispatched in response to lifecycle events:

```haskell
child :: Component ctx () Model Action
child = (component m u v)
  { mount   = Just Connect
  , unmount = Just Disconnect
  }
```

Element nodes have their own hooks (`onCreated`, `onDestroyed`, …) — see [the View DSL](https://haskell-miso.org/docs/view-dsl/).

**Live example: mount, unmount, subs and the mailbox**

```haskell
-- A parent that mounts and unmounts a keyed child, and
-- logs what the child reports through the mailbox.
data ParentModel = ParentModel
  { _mounted :: Bool
  , _entries :: [MisoString]
  } deriving (Show, Eq)

mounted :: Lens ParentModel Bool
mounted = lens _mounted $ \p x -> p { _mounted = x }

entries :: Lens ParentModel [MisoString]
entries = lens _entries $ \p x -> p { _entries = x }

data ParentAction
  = ToggleChild
  | ChildSaid MisoString
  | BadMail MisoString

parent
  :: Eq ctx
  => Component ctx () ParentModel ParentAction
parent = (component (ParentModel True []) update view)
  { mailbox = checkMail ChildSaid BadMail
    -- receive mail from the child
  }
  where
    update = \case
      ToggleChild -> mounted %= not
      ChildSaid s -> entries %= take 6 . (s :)
      BadMail _   -> pure ()

    view m =
      H.div_ []
        [ H.button_ [ HE.onClick ToggleChild ]
            [ text $ if m ^. mounted
                then "Unmount the clock"
                else "Mount the clock"
            ]
        , if m ^. mounted then "clock" +> clock else "no clock"
        , H.ul_ [ HP.class_ "log" ]
            [ H.li_ [] [ text e ] | e <- m ^. entries ]
        ]

-- The child: a clock that ticks from a subscription and
-- reports its lifecycle to the parent.
data ClockAction = Tick | Mounted | Unmounted

clock
  :: Component ctx () Int ClockAction
clock = (component 0 update view)
  { mount = Just Mounted
    -- dispatched when the component appears
  , unmount = Just Unmounted
    -- ...and when it goes away
  , subs = [ everySecond ]
    -- runs for the component's lifetime
  }
  where
    everySecond sink _ =
      forever (threadDelay 1000000 >> sink Tick)

    update = \case
      Tick      -> this += 1
      Mounted   -> mailParent ("clock mounted" :: MisoString)
      Unmounted -> mailParent ("clock unmounted" :: MisoString)

    view secs =
      H.p_ [] [ "⏱ ", text (ms secs), "s since mount" ]
```

Toggle the clock: the child's `mount` and `unmount` actions run, its `subs` start and stop with it, and it reports back through the parent's `mailbox`. Note the `"clock" +> clock` key — that is what makes the diff mount and unmount rather than patch.
