Copyright	(C) 2016-2026 David M. Johnson
License	BSD3-style (see the file LICENSE)
Maintainer	David M. Johnson <code@dmj.io>
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Miso.Types

Contents

Types
Classes
Smart Constructors
Event handler smart constructor
Component mounting
Fragment combinators
Utils
- Combinators
- MisoString

Description

Overview

Miso.Types defines every core type that miso applications are built from. It is re-exported in its entirety by Miso, so most application code never needs to import it directly.

The Component record

Component context props model action is the central record type. It wires together the MVU loop and all supporting runtime configuration:

data Component context props model action = Component
  { model           :: model
  , hydrateModel    :: Maybe (IO model)
  , update          :: action -> Effect context props model action
  , view            :: context -> props -> model -> View context action
  , useContext      :: Bool
  , subs            :: [Sub action]
  , styles          :: [CSS]
  , scripts         :: [JS]
  , mountPoint      :: Maybe MountPoint
  , logLevel        :: LogLevel
  , mailbox         :: Value -> Maybe action
  , eventPropagation :: Bool
  , mount           :: Maybe action
  , unmount         :: Maybe action
  , onPropsChanged  :: Maybe (props -> props -> action)
  }

Use the component smart constructor to build one with sane defaults, then override only the fields you need:

myApp :: App Model Action
myApp = (component initialModel update view)
  { subs   = [ mySub ]
  , styles = [ Href "style.css" (False :: CacheBust) ]
  }

The View type

View context action is miso's virtual DOM tree. Its four constructors map to the four node kinds the runtime handles:

VNode — a regular DOM element (<div>, <svg>, …)
VText — a text node
VComp — an embedded child Component
VFrag — a keyless group of siblings (no wrapper element)

Key types at a glance

Component: full MVU application/component record
App: alias for Component () () model action
View: virtual DOM node
Attribute: DOM property, class list, event handler, or style
Namespace: HTML | SVG | MATHML
Key: reconciliation hint for list diffing
CSS: stylesheet reference (Href, Style, Sheet)
JS: script reference (Src, Script, Module, …)
LogLevel: debug verbosity (Off, DebugHydrate, …)
URI: parsed URL (path + query string + fragment)

Text combinators

text — create a text node (HTML-escaped in SSR mode)
textRaw — create a text node without HTML escaping
text_ — concatenate a list of strings with a space separator
textKey / textKey_ — keyed variants for efficient list diffing
htmlEncode — manually escape & " '

Component mounting

"key" +> comp — mount a child component with a key
mount_ — mount without a key (unsafe in dynamic lists)
mountWithProps / mountWithProps_ — mount with explicit props
mountUseContext — mount without a key, subscribed to context updates
vcomp / vcomp_ (with mountStatic_ / mountStaticWithProps / mountStaticUseContext) — static-key mounting; the compile-time StaticKey already provides identity, so unlike the non-static combinators there is no keyed variant

__Under the Lynx dual-thread (1) backend, always use vcomp / vcomp_ — never +> / mount_ / mountWithProps / mountWithProps_ / mountUseContext.__ The non-static combinators build a component with no StaticKey; anything mounted with them after the initial frame (e.g. inside a list or behind a conditional) never registers a main-thread mirror on the MTS, which silently drops every OnStatic (main-thread) event handler inside that subtree for the component's whole lifetime. This is invisible outside of a console error — there is no type error and no runtime crash. GHC emits a warning at every use site of the non-static combinators when built with 1 as a reminder.

Fragment combinators

fragment / vfrag — group siblings without a wrapper element
fragment_ / vfrag_ — keyed fragment

Conditional view utilities

optionalAttrs — add attributes conditionally
optionalVoidAttrs — same for void (no-children) elements
optionalChildren — add children conditionally

type App model action = Component () () model action
data Component context props model action = Component {
- model :: model
- hydrateModel :: Maybe (IO model)
- update :: action -> Effect context props model action
- view :: context -> props -> model -> View context model action
- useContext :: Bool
- subs :: [Sub action]
- styles :: [CSS]
- scripts :: [JS]
- mountPoint :: Maybe MountPoint
- logLevel :: LogLevel
- mailbox :: Value -> Maybe action
- eventPropagation :: Bool
- mount :: Maybe action
- unmount :: Maybe action
- onPropsChanged :: Maybe (props -> props -> action)
}
type ComponentId = Int
data SomeComponent context = (FromJSON model, ToJSON model, FromJSON action, ToJSON action, FromJSON props, ToJSON props, Eq context, Eq model, Eq props) => SomeComponent (Maybe Key) props (Component context props model action)
data SomeStaticComponent props context = (Eq props, FromJSON props, ToJSON props) => SomeStaticComponent (props -> SomeComponent context)
data EventHandler model action = EventHandler {
- eventHandlerInstall :: model -> Sink action -> VTree -> LogLevel -> Events -> IO ()
- eventHandlerDecoder :: Decoder result
- eventHandlerConvert :: result -> model -> DOMRef -> action
}
data View context model action
- = VNode Namespace Tag [Attribute model action] [View context model action] DirectEvents
- | VText (Maybe Key) MisoString
- | VComp (SomeComponent context)
- | VCompStatic (StaticPtr (SomeStaticComponent props context)) props
- | VFrag (Maybe Key) [View context model action]
newtype Key = Key MisoString
data Attribute model action
- = Property MisoString Value
- | ClassList [MisoString]
- | On (model -> Sink action -> VTree -> LogLevel -> Events -> IO ())
- | OnStatic (StaticPtr (EventHandler model action))
- | Styles (Map MisoString MisoString)
data Namespace
- = HTML
- | SVG
- | MATHML
data CSS
- = Href MisoString CacheBust
- | Style MisoString
- | Sheet StyleSheet
data JS
- = Src MisoString CacheBust
- | Script MisoString
- | Module MisoString
- | ImportMap [(MisoString, MisoString)]
data LogLevel
- = Off
- | DebugHydrate
- | DebugEvents
- | DebugAll
newtype VTree = VTree {
- getTree :: Object
}
data VTreeType
- = VCompType
- | VNodeType
- | VTextType
- | VFragType
data Hydrate
- = Draw
- | Hydrate
type Tag = MisoString
type DirectEvents = Set MisoString
type CacheBust = Bool
type MountPoint = MisoString
type DOMRef = JSVal
type Events = Map MisoString Phase
data Phase
- = CAPTURE
- | BUBBLE
data URI = URI {
- uriPath :: MisoString
- uriFragment :: MisoString
- uriQueryString :: Map MisoString (Maybe MisoString)
}
class ToKey key where
- toKey :: key -> Key
emptyURI :: URI
component :: model -> (action -> Effect context props model action) -> (context -> props -> model -> View context model action) -> Component context props model action
event :: StaticPtr (EventHandler model action) -> Attribute model action
vcomp :: props -> StaticPtr (SomeStaticComponent props context) -> View context model action
vcomp_ :: StaticPtr (SomeStaticComponent () context) -> View context model action
(+>) :: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction) => MisoString -> Component context () childModel childAction -> View context model action
mount_ :: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction) => Component context () childModel childAction -> View context model action
mountUseContext :: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction) => Component context () childModel childAction -> View context model action
mountWithProps_ :: (Eq context, Eq props, Eq childModel, FromJSON childAction, FromJSON childModel, ToJSON childModel, ToJSON childAction, FromJSON props, ToJSON props) => MisoString -> props -> Component context props childModel childAction -> View context model action
mountWithProps :: (Eq context, Eq props, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction, FromJSON props, ToJSON props) => props -> Component context props childModel childAction -> View context model action
mountStatic_ :: (Eq context, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action) => Component context () model action -> SomeStaticComponent () context
mountStaticWithProps :: (Eq context, Eq props, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action, FromJSON props, ToJSON props) => Component context props model action -> SomeStaticComponent props context
mountStaticUseContext :: (Eq context, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action) => Component context () model action -> SomeStaticComponent () context
fragment :: [View context model action] -> View context model action
fragment_ :: MisoString -> [View context model action] -> View context model action
vfrag :: [View context model action] -> View context model action
vfrag_ :: MisoString -> [View context model action] -> View context model action
getMountPoint :: Maybe MisoString -> MisoString
optionalAttrs :: ([Attribute model action] -> [View context model action] -> View context model action) -> [Attribute model action] -> Bool -> [Attribute model action] -> [View context model action] -> View context model action
optionalVoidAttrs :: ([Attribute model action] -> View context model action) -> [Attribute model action] -> Bool -> [Attribute model action] -> View context model action
optionalChildren :: ([Attribute model action] -> [View context model action] -> View context model action) -> [Attribute model action] -> [View context model action] -> Bool -> [View context model action] -> View context model action
prettyURI :: URI -> MisoString
prettyQueryString :: URI -> MisoString
node :: Namespace -> MisoString -> [Attribute model action] -> [View context model action] -> View context model action
nodeDirectEvents :: Namespace -> MisoString -> [Attribute model action] -> [MisoString] -> [View context model action] -> View context model action
vnode :: Namespace -> MisoString -> [Attribute model action] -> [View context model action] -> View context model action
text :: MisoString -> View context model action
vtext :: MisoString -> View context model action
text_ :: [MisoString] -> View context model action
textRaw :: MisoString -> View context model action
textKey :: ToKey key => key -> MisoString -> View context model action
textKey_ :: ToKey key => key -> [MisoString] -> View context model action
htmlEncode :: MisoString -> MisoString
type MisoString = Text
toMisoString :: ToMisoString str => str -> MisoString
fromMisoString :: FromMisoString a => MisoString -> a
ms :: ToMisoString str => str -> MisoString

Types

type App model action = Component () () model action Source #

A miso application is a top-level Component. Its app-global context defaults to () (see startAppWithContext to supply a non-trivial context), and its props are fixed to ().

data Component context props model action Source #

Application entry point

Constructors

Component

Fields

model :: model
Initial model
hydrateModel :: Maybe (IO model)
Optional IO to load component model state, such as reading data from page. The resulting model is only used during initial hydration, not on remounts.
Note: only synchronous IO should be used here (e.g. reading from localStorage via getLocalStorage).
update :: action -> Effect context props model action
Updates model, optionally providing effects.
view :: context -> props -> model -> View context model action
Draws View. Receives the app-global context, the props passed by the parent, and the current model.
useContext :: Bool
Whether this Component should be re-rendered when the app-global context changes (see modifyContext).
This controls whether a component reacts to context changes, not whether it may change the context. A component may call modifyContext / putContext with useContext = False; it simply won't re-render in response. Enable it on the (usually nested) components whose view reads the context and must refresh when it changes.
Defaults to False.
Since: 1.9.0.0
subs :: [Sub action]
Subscriptions to run during application lifetime
styles :: [CSS]
CSS styles expressed as either a URL (Href) or as Style text. These styles are appended dynamically to the <head> section of your HTML page before the initial draw on <body> occurs.
Note: This field should only be used in development mode.
Since: 1.9.0.0
scripts :: [JS]
JavaScript scripts expressed as either a URL (Src) or raw JS text. These scripts are appended dynamically to the <head> section of your HTML page before the initial draw on <body> occurs.
Note: This field should only be used in development mode.
Since: 1.9.0.0
mountPoint :: Maybe MountPoint
ID of the root element for DOM diff. If Nothing is provided, the entire document body is used as a mount point.
logLevel :: LogLevel
Debugging configuration for prerendering and event delegation
mailbox :: Value -> Maybe action
Receives mail from other components
Since: 1.9.0.0
eventPropagation :: Bool
Should events bubble up past the Component barrier.
Defaults to False
Since: 1.9.0.0
mount :: Maybe action
action to execute during Component mount phase.
Since: 1.9.0.0
unmount :: Maybe action
action to execute during Component unmount phase.
Since: 1.9.0.0
onPropsChanged :: Maybe (props -> props -> action)
action to execute when Component props have changed (a.k.a. props phase). Receives previous props and current props as arguments.
Since: 1.11.0.0

type ComponentId = Int Source #

ComponentId of the current Component

data SomeComponent context Source #

Existential wrapper allowing nesting of Component in Component.

The context type parameter is shared with the enclosing View, so every nested Component participates in the same app-global context.

Constructors

(FromJSON model, ToJSON model, FromJSON action, ToJSON action, FromJSON props, ToJSON props, Eq context, Eq model, Eq props) => SomeComponent (Maybe Key) props (Component context props model action)

data SomeStaticComponent props context Source #

A closed props -> component constructor, bundled with the serialization dictionaries needed to move props across the dual-thread (Lynx) boundary.

Unlike SomeComponent, the props type parameter is preserved (not existential). This lets vcompWith statically require the runtime props value to match the constructor, while the packed FromJSON / ToJSON dictionaries are recovered on the MTS after unsafeLookupStaticPtr derefs the StaticPtr — so the MTS can decode the wire props at exactly this type and rebuild the SomeComponent.

Built with mount_ / mountWithProps / (+>); consumed by vcomp.

Constructors

(Eq props, FromJSON props, ToJSON props) => SomeStaticComponent (props -> SomeComponent context)

data EventHandler model action Source #

Wrapper for event handler callbacks, used for cross-thread communication.

Carries two independent things built from the same (decoder, convert) pair:

eventHandlerInstall — attaches a real JS listener to a live vnode. Used by setAttrs during diffing, on both threads.
eventHandlerDecoder / eventHandlerConvert — the decode step exposed directly, with no JS installer round-trip. Used by the MTS's dispatchMainThreadEvent to decode + dispatch a main-thread event synchronously, without reconstructing (and discarding) a JS callback via a throwaway scratch node on every single event.

Constructors

EventHandler
Fields eventHandlerInstall :: model -> Sink action -> VTree -> LogLevel -> Events -> IO () eventHandlerDecoder :: Decoder result eventHandlerConvert :: result -> model -> DOMRef -> action

data View context model action Source #

Core type for constructing a virtual DOM in Haskell

Constructors

VNode Namespace Tag [Attribute model action] [View context model action] DirectEvents	The final `Set` names the events this element dispatches directly on itself rather than by bubbling to the delegated mount listener (Lynx native `input`/`scroll`/… events). Empty for all HTML/SVG/MathML elements. See `nodeDirectEvents`.
VText (Maybe Key) MisoString
VComp (SomeComponent context)
VCompStatic (StaticPtr (SomeStaticComponent props context)) props	An embedded child `Component`. The `StaticPtr` holds only the closed `props -> component` constructor (`SomeStaticComponent`); the `props` value — often derived from the parent's `model` — rides alongside and crosses the dual-thread (Lynx) boundary as JSON. The no-props case uses `props ~ ()` (see `mount_`). This split is what lets a mount escape `static`'s closedness restriction. See `vcomp`. This is necessary for lynx dual-thread in order to transfer context, props, event handlers etc.
VFrag (Maybe Key) [View context model action]

Instances

Instances details

ToHtml [View context model action] Source #	Render a `[Miso.Types.View]` to a `L.ByteString`
Instance details Defined in Miso.Html.Render Methods toHtml :: [View context model action] -> ByteString Source #
IsString (View context model action) Source #	`IsString` instance
Instance details Defined in Miso.Types Methods fromString :: String -> View context model action #
ToHtml (View context model action) Source #	Render a `Miso.Types.View` to a `L.ByteString`
Instance details Defined in Miso.Html.Render Methods toHtml :: View context model action -> ByteString Source #

newtype Key Source #

Unique key for a DOM node.

This key is only used to speed up diffing the children of a DOM node, the actual content is not important. The keys of the children of a given DOM node must be unique. Failure to satisfy this invariant gives undefined behavior at runtime.

Constructors

Key MisoString

Instances

Instances details

IsString Key Source #
Instance details Defined in Miso.Types Methods fromString :: String -> Key #
Show Key Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> Key -> ShowS # show :: Key -> String # showList :: [Key] -> ShowS #
Eq Key Source #
Instance details Defined in Miso.Types Methods (==) :: Key -> Key -> Bool # (/=) :: Key -> Key -> Bool #
ToJSVal Key Source #	ToJSVal instance for `Key`
Instance details Defined in Miso.Types Methods toJSVal :: Key -> IO JSVal Source #
ToJSON Key Source #
Instance details Defined in Miso.Types Methods toJSON :: Key -> Value Source # toJSONList :: [Key] -> Value
ToMisoString Key Source #
Instance details Defined in Miso.Types Methods toMisoString :: Key -> MisoString Source #
ToKey Key Source #	Identity instance
Instance details Defined in Miso.Types Methods toKey :: Key -> Key Source #

data Attribute model action Source #

Attribute of a vnode in a View.

Constructors

Property MisoString Value
ClassList [MisoString]
On (model -> Sink action -> VTree -> LogLevel -> Events -> IO ())	A fully-applied `static` event handler; the main thread rebuilds it from the `StaticKey` alone. See `event`.
OnStatic (StaticPtr (EventHandler model action))	A `static` handler constructor plus a runtime `payload` (often `model` data) supplied separately and JSON-shipped across the dual-thread boundary, so the handler can reach the main thread with runtime data. The `action` stays outside the existential; only `payload` is hidden. Handler-identity diffing is by `StaticKey` (JS-side, `ts/miso/dom.ts`). See `eventWith`.
Styles (Map MisoString MisoString)

Instances

Instances details

Show (Attribute model action) Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> Attribute model action -> ShowS # show :: Attribute model action -> String # showList :: [Attribute model action] -> ShowS #
Eq (Attribute model action) Source #
Instance details Defined in Miso.Types Methods (==) :: Attribute model action -> Attribute model action -> Bool # (/=) :: Attribute model action -> Attribute model action -> Bool #

data Namespace Source #

DOM element namespace.

Constructors

HTML	HTML Namespace
SVG	SVG Namespace
MATHML	MATHML Namespace

Instances

Instances details

Show Namespace Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> Namespace -> ShowS # show :: Namespace -> String # showList :: [Namespace] -> ShowS #
Eq Namespace Source #
Instance details Defined in Miso.Types Methods (==) :: Namespace -> Namespace -> Bool # (/=) :: Namespace -> Namespace -> Bool #
ToJSVal Namespace Source #
Instance details Defined in Miso.Types Methods toJSVal :: Namespace -> IO JSVal Source #

data CSS Source #

Allow users to express CSS and append it to <head> before the first draw

'Href' "http://domain.com/style.css" ('True' :: 'CacheBust')
'Style' "body { background-color: red; }"

Constructors

Href MisoString CacheBust	`URL` linking to hosted `CSS`
Style MisoString	Raw `CSS` content in a `style_` tag
Sheet StyleSheet	`CSS` built with Miso.CSS

Instances

Instances details

Show CSS Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> CSS -> ShowS # show :: CSS -> String # showList :: [CSS] -> ShowS #
Eq CSS Source #
Instance details Defined in Miso.Types Methods (==) :: CSS -> CSS -> Bool # (/=) :: CSS -> CSS -> Bool #

data JS Source #

Allow users to express JS and append it to <head> before the first draw

This is meant to be useful in development only.

Src "http://example.com/script.js" (False :: CacheBust)
Script "alert("hi");"
ImportMap [ "key" =: "value" ]
Module "console.log("hi");"

Since: 1.9.0.0

Constructors

Src MisoString CacheBust	URL linking to hosted JS
Script MisoString	Raw JS content that you would enter in a <script> tag
Module MisoString	Raw JS module content that you would enter in a <script type="module"> tag. See script type
ImportMap [(MisoString, MisoString)]	Import map content in a <script type="importmap"> tag. See importmap

Instances

Instances details

Show JS Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> JS -> ShowS # show :: JS -> String # showList :: [JS] -> ShowS #
Eq JS Source #
Instance details Defined in Miso.Types Methods (==) :: JS -> JS -> Bool # (/=) :: JS -> JS -> Bool #

data LogLevel Source #

Logging configuration for debugging Miso internals (useful to see if prerendering is successful)

Constructors

Off	No debug logging, the default value used in `component`
DebugHydrate	Will warn if the structure or properties of the DOM vs. Virtual DOM differ during prerendering.
DebugEvents	Will warn if an event cannot be routed to the Haskell event handler that raised it. Also will warn if an event handler is being used, yet it's not being listened for by the event delegator mount point.
DebugAll	Logs on all of the above

Instances

Instances details

Show LogLevel Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> LogLevel -> ShowS # show :: LogLevel -> String # showList :: [LogLevel] -> ShowS #
Eq LogLevel Source #
Instance details Defined in Miso.Types Methods (==) :: LogLevel -> LogLevel -> Bool # (/=) :: LogLevel -> LogLevel -> Bool #

newtype VTree Source #

Virtual DOM implemented as a JavaScript Object. Used for diffing, patching and event delegation. Not meant to be constructed directly, see View instead.

Constructors

VTree
Fields getTree :: Object Underlying JavaScript object representing the virtual DOM tree

Instances

Instances details

ToJSVal VTree Source #
Instance details Defined in Miso.Types Methods toJSVal :: VTree -> IO JSVal Source #
ToObject VTree Source #
Instance details Defined in Miso.Types Methods toObject :: VTree -> IO Object Source #

data VTreeType Source #

VTreeType ADT for matching TypeScript enum

Constructors

VCompType
VNodeType
VTextType
VFragType

Instances

Instances details

Show VTreeType Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> VTreeType -> ShowS # show :: VTreeType -> String # showList :: [VTreeType] -> ShowS #
Eq VTreeType Source #
Instance details Defined in Miso.Types Methods (==) :: VTreeType -> VTreeType -> Bool # (/=) :: VTreeType -> VTreeType -> Bool #
ToJSVal VTreeType Source #
Instance details Defined in Miso.Types Methods toJSVal :: VTreeType -> IO JSVal Source #

data Hydrate Source #

Hydrate avoids calling diff, and instead calls hydrate Draw invokes diff

Constructors

Draw
Hydrate

Instances

Instances details

Show Hydrate Source #
Instance details Defined in Miso.Types Methods showsPrec :: Int -> Hydrate -> ShowS # show :: Hydrate -> String # showList :: [Hydrate] -> ShowS #
Eq Hydrate Source #
Instance details Defined in Miso.Types Methods (==) :: Hydrate -> Hydrate -> Bool # (/=) :: Hydrate -> Hydrate -> Bool #

type Tag = MisoString Source #

Tag type, (e.g. div_, p_)

Meant to indicate the type of element being created. Used as the first argument to document.createElement for the web backend.

type DirectEvents = Set MisoString Source #

The set of events an element dispatches directly on itself rather than by bubbling to the delegated mount listener. Empty for HTML/SVG/MathML; populated for Lynx native elements (see nodeDirectEvents).

type CacheBust = Bool Source #

Parameter used to indicate cache busting logic should be used. If True this will append a timestamp to the query. This will force cache invalidation on the browser, causing a fetch of the resources.

type MountPoint = MisoString Source #

mountPoint for Component, e.g "body"

type DOMRef = JSVal Source #

Type to represent a DOM reference

type Events = Map MisoString Phase Source #

Convenience type for Events

The map declares which DOM events are delegated and at which Phase. Whether an individual handler runs on the Lynx main thread (MTS) or background thread (BTS) is decided per handler (see Miso.Event.mainThread), not per event name — mirroring Lynx's main-thread:bind vs bind prefix.

data Phase Source #

Phase during which event listener is invoked.

Since: 1.9.0.0

Constructors

CAPTURE
BUBBLE

Instances

Instances details

Show Phase Source #
Instance details Defined in Miso.Event.Types Methods showsPrec :: Int -> Phase -> ShowS # show :: Phase -> String # showList :: [Phase] -> ShowS #
Eq Phase Source #
Instance details Defined in Miso.Event.Types Methods (==) :: Phase -> Phase -> Bool # (/=) :: Phase -> Phase -> Bool #
ToJSVal Phase Source #
Instance details Defined in Miso.Event.Types Methods toJSVal :: Phase -> IO JSVal Source #

data URI Source #

URI type. See the official specification

Constructors

URI
Fields uriPath :: MisoString Path component, e.g. `"users/42"` uriFragment :: MisoString Fragment identifier (without the leading `#`), e.g. `"section-1"` uriQueryString :: Map MisoString (Maybe MisoString) Query parameters. `Just v` for `?key=v` pairs; `Nothing` for bare flags (`?flag`).

Instances

Instances details

Generic URI Source #

Instance details

Defined in Miso.Types

Associated Types

type Rep URI

Instance details

Defined in Miso.Types

type Rep URI = D1 ('MetaData "URI" "Miso.Types" "miso-1.13.0.0-inplace" 'False) (C1 ('MetaCons "URI" 'PrefixI 'True) (S1 ('MetaSel ('Just "uriPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: (S1 ('MetaSel ('Just "uriFragment") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: S1 ('MetaSel ('Just "uriQueryString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map MisoString (Maybe MisoString))))))

Methods

from :: URI -> Rep URI x #

to :: Rep URI x -> URI #

Show URI Source #

Instance details

Defined in Miso.Types

Methods

showsPrec :: Int -> URI -> ShowS #

show :: URI -> String #

showList :: [URI] -> ShowS #

Eq URI Source #

Instance details

Defined in Miso.Types

Methods

(==) :: URI -> URI -> Bool #

(/=) :: URI -> URI -> Bool #

ToJSVal URI Source #

Instance details

Defined in Miso.Types

Methods

toJSVal :: URI -> IO JSVal Source #

ToObject URI Source #

Instance details

Defined in Miso.Types

Methods

toObject :: URI -> IO Object Source #

FromJSON URI Source #

Instance details

Defined in Miso.Router

Methods

parseJSON :: Value -> Parser URI Source #

ToJSON URI Source #

Instance details

Defined in Miso.Types

Methods

toJSON :: URI -> Value Source #

toJSONList :: [URI] -> Value

FromMisoString URI Source #

Instance details

Defined in Miso.Router

Methods

fromMisoStringEither :: MisoString -> Either String URI Source #

ToMisoString URI Source #

Instance details

Defined in Miso.Types

Methods

toMisoString :: URI -> MisoString Source #

type Rep URI Source #

Instance details

Defined in Miso.Types

type Rep URI = D1 ('MetaData "URI" "Miso.Types" "miso-1.13.0.0-inplace" 'False) (C1 ('MetaCons "URI" 'PrefixI 'True) (S1 ('MetaSel ('Just "uriPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: (S1 ('MetaSel ('Just "uriFragment") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: S1 ('MetaSel ('Just "uriQueryString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map MisoString (Maybe MisoString))))))

Classes

class ToKey key where Source #

Convert custom key types to Key.

Instances of this class do not have to guarantee uniqueness of the generated keys, it is up to the user to do so. toKey must be an injective function (different inputs must map to different outputs).

Methods

toKey :: key -> Key Source #

Converts any key into Key

Instances

Instances details

ToKey Key Source #	Identity instance
Instance details Defined in Miso.Types Methods toKey :: Key -> Key Source #
ToKey Text Source #	Convert `Text` to `Key`
Instance details Defined in Miso.Types Methods toKey :: Text -> Key Source #
ToKey String Source #	Convert `String` to `Key`
Instance details Defined in Miso.Types Methods toKey :: String -> Key Source #
ToKey Double Source #	Convert `Double` to `Key`
Instance details Defined in Miso.Types Methods toKey :: Double -> Key Source #
ToKey Float Source #	Convert `Float` to `Key`
Instance details Defined in Miso.Types Methods toKey :: Float -> Key Source #
ToKey Int Source #	Convert `Int` to `Key`
Instance details Defined in Miso.Types Methods toKey :: Int -> Key Source #
ToKey Word Source #	Convert `Word` to `Key`
Instance details Defined in Miso.Types Methods toKey :: Word -> Key Source #

Smart Constructors

emptyURI :: URI Source #

Empty URI.

component Source #

Arguments

:: model	model
-> (action -> Effect context props model action)	update
-> (context -> props -> model -> View context model action)	view
-> Component context props model action

Smart constructor for Component with sane defaults.

Event handler smart constructor

event :: StaticPtr (EventHandler model action) -> Attribute model action Source #

Embed a fully-applied static event handler.

The handler is baked into the StaticPtr, so the main thread can rebuild it from the StaticKey alone (no payload to forward). Use this for handlers that take no injected model data — including decoder handlers whose argument is a function (e.g. onScroll HandleScroll).

button_ [ event (static (onClick AddOne)) ]
div_    [ event (static (onScroll HandleScroll)) ]

Component mounting

vcomp :: props -> StaticPtr (SomeStaticComponent props context) -> View context model action Source #

Embed a child Component as a View.

Smart constructor for VComp, mirroring vnode / vtext / vfrag.

The StaticPtr wraps only the closed props -> component constructor (built with mount_, mountWithProps, or (+>)); it must use the static keyword and refer to a closed, top-level binding. The props value is supplied separately — so it may depend on the parent's model — and is serialized across the dual-thread boundary. The no-props case passes ().

No class constraints appear here: the serialization dictionaries are discharged at the static (mount_ child) site and recovered on the MTS from the Props.

div_ [] [ vcomp_ (static (mountStatic_ myComp)) ]

Since: 1.12.0.0

vcomp_ :: StaticPtr (SomeStaticComponent () context) -> View context model action Source #

(+>) infixr 0 Source #

Arguments

:: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction)
=> MisoString	`VComp` `key_`
-> Component context () childModel childAction	`Component`
-> View context model action

Warning: [NATIVE] +> has no StaticKey; a component mounted with it after the initial frame silently drops OnStatic handlers inside it. Use vcomp with mountStaticWithProps instead.

Component mounting combinator

Used in the view function to mount a Component on any VNode.

"component-id" +> component model noop $ \m ->
  div_ [ id_ "foo" ] [ text (ms m) ]

Warning (Lynx dual-thread / 1): this builds a VComp with no StaticKey. A component mounted this way as part of the initial frame is fine (the MTS independently reconstructs it while painting its own first frame). But if it is mounted later — e.g. inside a list or behind a conditional, appearing only after the first frame — the MTS has no other way to learn of it, so it never registers a mirror ComponentState for it, and any main-thread (OnStatic) event handler inside that subtree silently fails to dispatch for the component's whole lifetime, with only a console error as a clue. Use vcomp with mountStaticWithProps instead for anything that may mount after the initial frame under 1 — the compile-time StaticKey already supplies the identity a manual key would, no explicit key needed.

Since: 1.9.0.0

mount_ Source #

Arguments

:: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction)
=> Component context () childModel childAction	`Component` to mount
-> View context model action

Warning: [NATIVE] mount_ has no StaticKey; a component mounted with it after the initial frame silently drops OnStatic handlers inside it. Use vcomp_ with mountStatic_ instead.

Component mounting combinator.

Note: only use this if you're certain you won't be diffing two Component against each other. Otherwise, you will need a key to distinguish between the two Component, to ensure unmounting and mounting occurs.

mount_ $ component model noop $ \m ->
 div_ [ id_ "foo" ] [ text (ms m) ]

Warning (Lynx dual-thread / 1): see the note on (+>) — this also builds a VComp with no StaticKey, so the same caveat applies: mounted after the initial frame, it never gets a main-thread mirror registered, silently breaking OnStatic handlers inside it. Use vcomp_ with mountStatic_ instead for anything that may mount dynamically under 1.

Since: 1.9.0.0

mountUseContext Source #

Arguments

:: (Eq context, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction)
=> Component context () childModel childAction	`Component` to mount
-> View context model action

Warning: [NATIVE] mountUseContext has no StaticKey; a component mounted with it after the initial frame silently drops OnStatic handlers inside it. Use vcomp_ with mountStaticUseContext instead.

Component mounting combinator that opts the child into app-global React-style context updates.

Equivalent to mount_, but sets useContext = True on the mounted Component so it re-renders whenever the context changes (see modifyContext). Like mount_, this is unkeyed and so unsafe when diffing two Component against each other.

mountUseContext $ component model noop $ \ctx m ->
 div_ [ id_ "foo" ] [ text (ms m) ]

Warning (Lynx dual-thread / 1): see the note on mount_ — this also builds a VComp with no StaticKey, so the same caveat applies: mounted after the initial frame, it never gets a main-thread mirror registered, silently breaking OnStatic handlers inside it. Use vcomp_ with mountStaticUseContext instead under 1.

Since: 1.9.0.0

mountWithProps_ Source #

Arguments

:: (Eq context, Eq props, Eq childModel, FromJSON childAction, FromJSON childModel, ToJSON childModel, ToJSON childAction, FromJSON props, ToJSON props)
=> MisoString
-> props
-> Component context props childModel childAction	`Component` to mount
-> View context model action

Warning: [NATIVE] mountWithProps_ has no StaticKey; a component mounted with it after the initial frame silently drops OnStatic handlers inside it. Use vcomp with mountStaticWithProps instead.

Component mounting combinator, keyed, with props supplied directly.

Warning (Lynx dual-thread / 1): see the note on (+>) — this also builds a VComp with no StaticKey (the key here is just the diffing Key, unrelated), so the same caveat applies: mounted after the initial frame, it never gets a main-thread mirror registered, silently breaking OnStatic handlers inside it. Use vcomp with mountStaticWithProps instead for anything that may mount dynamically under 1 — the compile-time StaticKey already supplies the identity a manual key would, no explicit key needed.

mountWithProps Source #

Arguments

:: (Eq context, Eq props, Eq childModel, FromJSON childModel, ToJSON childModel, FromJSON childAction, ToJSON childAction, FromJSON props, ToJSON props)
=> props
-> Component context props childModel childAction	`Component` to mount
-> View context model action

Warning: [NATIVE] mountWithProps has no StaticKey; a component mounted with it after the initial frame silently drops OnStatic handlers inside it. Use vcomp with mountStaticWithProps instead.

Component mounting combinator, with props supplied directly.

Warning (Lynx dual-thread / 1): see the note on (+>) — this also builds an unkeyed VComp with no StaticKey, so the same caveat applies: components mounted with this after the initial frame never get a main-thread mirror registered, silently breaking OnStatic handlers inside them. Use vcomp with mountStaticWithProps instead for anything that may mount dynamically under 1.

mountStatic_ Source #

Arguments

:: (Eq context, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action)
=> Component context () model action	`Component` to mount
-> SomeStaticComponent () context

Component mounting combinator.

Note: only use this if you're certain you won't be diffing two Component against each other. Otherwise, you will need a key to distinguish between the two Component, to ensure unmounting and mounting occurs.

mountStatic_ $ component model noop $ \m ->
 div_ [ id_ "foo" ] [ text (ms m) ]

Since: 1.9.0.0

mountStaticWithProps Source #

Arguments

:: (Eq context, Eq props, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action, FromJSON props, ToJSON props)
=> Component context props model action	`Component` to mount
-> SomeStaticComponent props context

Component mounting combinator.

Note: only use this if you're certain you won't be diffing two Component against each other. Otherwise, you will need a key to distinguish between the two Component, to ensure unmounting and mounting occurs.

It takes only the component and yields a closed props -> component constructor (SomeStaticComponent) suitable for static — the props value is not supplied here, but later at the vcomp site, so a parent can pass runtime props (e.g. derived from its own model) without an explicit lambda:

Static mounting automatically provides the key_ at compile time (via staticKey). So the user doesn't need to use the +> combinators.

vcomp (model ^. field) (static (mountStaticWithProps child))

Since: 1.11.0.0

mountStaticUseContext Source #

Arguments

:: (Eq context, Eq model, FromJSON model, ToJSON model, FromJSON action, ToJSON action)
=> Component context () model action	`Component` to mount
-> SomeStaticComponent () context

Static Component mounting combinator that opts the child into app-global React-style context updates.

Equivalent to mountStatic_, but sets useContext = True on the mounted Component so it re-renders whenever the context changes (see modifyContext). The static-key counterpart of mountUseContext — use this (with vcomp_) instead of mountUseContext under the Lynx dual-thread (1) backend.

vcomp_ (static (mountStaticUseContext myComp))

Since: 1.12.0.0

Fragment combinators

fragment :: [View context model action] -> View context model action Source #

Create a fragment (keyless).

A fragment groups multiple sibling View nodes without introducing an extra DOM element.

Since: 1.10.0.0

fragment_ :: MisoString -> [View context model action] -> View context model action Source #

Like fragment, but keyed for efficient diffing.

Since: 1.10.0.0

vfrag :: [View context model action] -> View context model action Source #

Create a fragment (keyless).

A fragment groups multiple sibling View nodes without introducing an extra DOM element.

Synonym for fragment

Since: 1.10.0.0

vfrag_ :: MisoString -> [View context model action] -> View context model action Source #

Like fragment, but keyed for efficient diffing.

Since: 1.10.0.0

Utils

getMountPoint :: Maybe MisoString -> MisoString Source #

Convenience for extracting mount point

optionalAttrs Source #

Arguments

:: ([Attribute model action] -> [View context model action] -> View context model action)
-> [Attribute model action]	Attributes to be added unconditionally
-> Bool	A condition
-> [Attribute model action]	Additional attributes to add if the condition is True
-> [View context model action]	Children
-> View context model action

Utility function to make it easy to specify conditional attributes

view :: Bool -> View context model action
view danger = optionalAttrs div_ [ id_ "some-div" ] danger [ class_ "danger" ] ["child"]

Since: 1.9.0.0

optionalVoidAttrs Source #

Arguments

:: ([Attribute model action] -> View context model action)
-> [Attribute model action]	Attributes to be added unconditionally
-> Bool	A condition
-> [Attribute model action]	Additional attributes to add if the condition is True
-> View context model action

Utility function to make it easy to specify conditional attributes for void elements.

view :: Bool -> View context model action
view shouldClear = optionalVoidAttrs textarea_ [ value_ "" ] shouldClear [ id_ "text-area-id" ]

Since: 1.9.0.0

optionalChildren Source #

Arguments

:: ([Attribute model action] -> [View context model action] -> View context model action)
-> [Attribute model action]	Attributes to be added unconditionally
-> [View context model action]	Children to be added unconditionally
-> Bool	A condition
-> [View context model action]	Additional children to add if the condition is True
-> View context model action

Conditionally adds children.

view :: Bool -> View context model action
view withChild = optionalChildren div_ [ id_ "txt" ] [] withChild [ "foo" ]

Since: 1.9.0.0

prettyURI :: URI -> MisoString Source #

Pretty-prints a URI.

prettyQueryString :: URI -> MisoString Source #

Pretty-prints a URI query string.

Combinators

node Source #

Arguments

:: Namespace	Element namespace (`HTML`, `SVG`, or `MATHML`)
-> MisoString	Tag name (e.g. `"div"`, `"circle"`)
-> [Attribute model action]	Attributes, properties, and event handlers
-> [View context model action]	Child nodes
-> View context model action

Create a new VNode.

node ns tag attrs children creates a new node with tag tag in the namespace ns. All attrs are called when the node is created and its children are initialized to children.

nodeDirectEvents Source #

Arguments

:: Namespace	Element namespace (`HTML`, `SVG`, or `MATHML`)
-> MisoString	Tag name (e.g. `"input"`, `"scroll-view"`)
-> [Attribute model action]	Attributes, properties, and event handlers
-> [MisoString]	Events dispatched directly on this element
-> [View context model action]	Child nodes
-> View context model action

Like node, but declares the set of events this element dispatches directly on itself instead of by bubbling to the delegated mount listener.

Only relevant to the Lynx native runtime, where component-emitted events (input, scroll, load, …) do not bubble and must be bound on the element. The set is a capability: a listener is bound only for events the element actually handles. Empty on the browser/WASM runtime.

Since: 1.10.0.0

vnode Source #

Arguments

:: Namespace	Element namespace (`HTML`, `SVG`, or `MATHML`)
-> MisoString	Tag name (e.g. `"div"`, `"circle"`)
-> [Attribute model action]	Attributes, properties, and event handlers
-> [View context model action]	Child nodes
-> View context model action

Create a new VNode.

Synonym for node

text :: MisoString -> View context model action Source #

Create a new VText with the given content.

vtext :: MisoString -> View context model action Source #

Synonym for text

text_ :: [MisoString] -> View context model action Source #

Create a new VText containing concatenation of the given strings.

  view :: View context model action
  view = div_
    [ className "container" ]
    [ text_
      [ "foo"
      , "bar"
      ]
    ]

Renders as class="container"foo bar/div

A single additional space is added between elements.

textRaw :: MisoString -> View context model action Source #

Create a new VText, not subject to HTML escaping.

Like text, except will not escape HTML when used on the server.

textKey :: ToKey key => key -> MisoString -> View context model action Source #

Like text, but allow the node to be keyed for efficient diffing.

view :: model -> View context model action
view = x -> div_ [] [ textKey (1 :: Int) "text here" ]

Since: 1.9.0.0

textKey_ :: ToKey key => key -> [MisoString] -> View context model action Source #

Like text_, but allow the node to be keyed for efficient diffing.

view :: model -> View context model action
view = x -> div_ [] [ textKey_ (1 :: Int) [ "text", "goes", "here" ] ]

Since: 1.9.0.0

htmlEncode :: MisoString -> MisoString Source #

HTML-encodes text.

Useful for escaping HTML when delivering on the server. Naive usage of text will ensure this as well.

>>> Data.Text.IO.putStrLn $ text "<a href=\"\">"
&lt;a href=&quot;&quot;&gt;

MisoString

type MisoString = Text Source #

The primary string type in Miso applications.

1 (server/SSR build): alias for Text
WASM / GHC JS backend: alias for JSString — a zero-copy wrapper around a native JavaScript string, giving optimal interop with the DOM and JSON APIs

toMisoString :: ToMisoString str => str -> MisoString Source #

Convert a value to MisoString.

fromMisoString :: FromMisoString a => MisoString -> a Source #

Parse a MisoString, throwing an error on failure. Use fromMisoStringEither as a safe alternative.

ms :: ToMisoString str => str -> MisoString Source #

Short alias for toMisoString. The idiomatic way to construct a MisoString.

Overview

The Component record

The View type

Key types at a glance

Text combinators

Component mounting

Fragment combinators

Conditional view utilities

See also

Types

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Classes

Instances

Smart Constructors

Event handler smart constructor

Component mounting

Fragment combinators

Utils

Combinators

MisoString