{- |
Module      : Hypermedia.Datastar.Types
Description : Core types for the Datastar SSE protocol

This module defines the types that model the Datastar server-sent events
protocol. Most users won't import this module directly — the types are
re-exported from "Hypermedia.Datastar".

Default values for protocol fields ('defaultPatchMode', 'defaultRetryDuration',
etc.) follow the Datastar ADR specification at
<https://data-star.dev/reference/action_plugins>.
-}
module Hypermedia.Datastar.Types where

import Data.Text (Text)

{- | The two SSE event types defined by the Datastar protocol.

Every event the server sends is one of these. 'EventPatchElements' covers
both DOM patching and script execution (the protocol encodes @executeScript@
as a special case of element patching). 'EventPatchSignals' updates the
browser's reactive signal store.
-}
data EventType
  = {- | Sent as @datastar-patch-elements@ on the wire. Used by both
    'Hypermedia.Datastar.PatchElements.PatchElements' and
    'Hypermedia.Datastar.ExecuteScript.ExecuteScript'.
    -}
    EventPatchElements
  | {- | Sent as @datastar-patch-signals@ on the wire. Used by
    'Hypermedia.Datastar.PatchSignals.PatchSignals'.
    -}
    EventPatchSignals
  deriving (EventType -> EventType -> Bool
(EventType -> EventType -> Bool)
-> (EventType -> EventType -> Bool) -> Eq EventType
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: EventType -> EventType -> Bool
== :: EventType -> EventType -> Bool
$c/= :: EventType -> EventType -> Bool
/= :: EventType -> EventType -> Bool
Eq, Int -> EventType -> ShowS
[EventType] -> ShowS
EventType -> String
(Int -> EventType -> ShowS)
-> (EventType -> String)
-> ([EventType] -> ShowS)
-> Show EventType
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> EventType -> ShowS
showsPrec :: Int -> EventType -> ShowS
$cshow :: EventType -> String
show :: EventType -> String
$cshowList :: [EventType] -> ShowS
showList :: [EventType] -> ShowS
Show)

eventTypeToText :: EventType -> Text
eventTypeToText :: EventType -> Text
eventTypeToText EventType
EventPatchElements = Text
"datastar-patch-elements"
eventTypeToText EventType
EventPatchSignals = Text
"datastar-patch-signals"

{- | How the patched HTML should be applied to the DOM.

The default mode is 'Outer', which replaces the target element (matched by
its @id@ attribute) including the element itself. This works well with
Datastar's morphing algorithm, which preserves focus, scroll position, and
CSS transitions during the replacement.
-}
data ElementPatchMode
  = -- | Replace the target element and its contents (the default).
    Outer
  | -- | Replace only the target element's children, keeping the element itself.
    Inner
  | -- | Remove the target element from the DOM entirely.
    Remove
  | -- | Replace the target element without morphing (a hard swap).
    Replace
  | -- | Insert the new content as the first child of the target element.
    Prepend
  | -- | Insert the new content as the last child of the target element.
    Append
  | -- | Insert the new content immediately before the target element.
    Before
  | -- | Insert the new content immediately after the target element.
    After
  deriving (ElementPatchMode -> ElementPatchMode -> Bool
(ElementPatchMode -> ElementPatchMode -> Bool)
-> (ElementPatchMode -> ElementPatchMode -> Bool)
-> Eq ElementPatchMode
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: ElementPatchMode -> ElementPatchMode -> Bool
== :: ElementPatchMode -> ElementPatchMode -> Bool
$c/= :: ElementPatchMode -> ElementPatchMode -> Bool
/= :: ElementPatchMode -> ElementPatchMode -> Bool
Eq, Int -> ElementPatchMode -> ShowS
[ElementPatchMode] -> ShowS
ElementPatchMode -> String
(Int -> ElementPatchMode -> ShowS)
-> (ElementPatchMode -> String)
-> ([ElementPatchMode] -> ShowS)
-> Show ElementPatchMode
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> ElementPatchMode -> ShowS
showsPrec :: Int -> ElementPatchMode -> ShowS
$cshow :: ElementPatchMode -> String
show :: ElementPatchMode -> String
$cshowList :: [ElementPatchMode] -> ShowS
showList :: [ElementPatchMode] -> ShowS
Show)

patchModeToText :: ElementPatchMode -> Text
patchModeToText :: ElementPatchMode -> Text
patchModeToText ElementPatchMode
Outer = Text
"outer"
patchModeToText ElementPatchMode
Inner = Text
"inner"
patchModeToText ElementPatchMode
Remove = Text
"remove"
patchModeToText ElementPatchMode
Replace = Text
"replace"
patchModeToText ElementPatchMode
Prepend = Text
"prepend"
patchModeToText ElementPatchMode
Append = Text
"append"
patchModeToText ElementPatchMode
Before = Text
"before"
patchModeToText ElementPatchMode
After = Text
"after"

{- | The XML namespace for the patched elements.

Almost all content uses 'HtmlNs' (the default). Use 'SvgNs' or 'MathmlNs'
when patching inline SVG or MathML elements so that Datastar creates them
in the correct namespace.
-}
data ElementNamespace
  = -- | Standard HTML namespace (the default).
    HtmlNs
  | -- | SVG namespace — use when patching @\<svg\>@ content.
    SvgNs
  | -- | MathML namespace — use when patching @\<math\>@ content.
    MathmlNs
  deriving (ElementNamespace -> ElementNamespace -> Bool
(ElementNamespace -> ElementNamespace -> Bool)
-> (ElementNamespace -> ElementNamespace -> Bool)
-> Eq ElementNamespace
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: ElementNamespace -> ElementNamespace -> Bool
== :: ElementNamespace -> ElementNamespace -> Bool
$c/= :: ElementNamespace -> ElementNamespace -> Bool
/= :: ElementNamespace -> ElementNamespace -> Bool
Eq, Int -> ElementNamespace -> ShowS
[ElementNamespace] -> ShowS
ElementNamespace -> String
(Int -> ElementNamespace -> ShowS)
-> (ElementNamespace -> String)
-> ([ElementNamespace] -> ShowS)
-> Show ElementNamespace
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> ElementNamespace -> ShowS
showsPrec :: Int -> ElementNamespace -> ShowS
$cshow :: ElementNamespace -> String
show :: ElementNamespace -> String
$cshowList :: [ElementNamespace] -> ShowS
showList :: [ElementNamespace] -> ShowS
Show)

namespaceToText :: ElementNamespace -> Text
namespaceToText :: ElementNamespace -> Text
namespaceToText ElementNamespace
HtmlNs = Text
"html"
namespaceToText ElementNamespace
SvgNs = Text
"svg"
namespaceToText ElementNamespace
MathmlNs = Text
"mathml"

{- | Internal representation of a rendered SSE event.

Users don't construct these directly. Instead, use 'Hypermedia.Datastar.PatchElements.patchElements',
'Hypermedia.Datastar.PatchSignals.patchSignals', or 'Hypermedia.Datastar.ExecuteScript.executeScript'
to build events, and 'Hypermedia.Datastar.WAI.sendPatchElements' (etc.) to send them.
-}
data DatastarEvent = DatastarEvent
  { DatastarEvent -> EventType
eventType :: EventType
  , DatastarEvent -> Maybe Text
eventId :: Maybe Text
  , DatastarEvent -> Int
retry :: Int
  , DatastarEvent -> [Text]
dataLines :: [Text]
  }

{- | Default SSE retry duration in milliseconds.

If the connection drops, the browser waits this long before reconnecting.
Per the Datastar ADR spec, the default is @1000@ ms.
-}
defaultRetryDuration :: Int
defaultRetryDuration :: Int
defaultRetryDuration = Int
1000

{- | Default element patch mode: 'Outer'.

Replaces the target element (matched by @id@) and its contents using
Datastar's morphing algorithm.
-}
defaultPatchMode :: ElementPatchMode
defaultPatchMode :: ElementPatchMode
defaultPatchMode = ElementPatchMode
Outer

{- | Default for the @useViewTransition@ flag: 'False'.

When 'True', Datastar wraps the DOM update in a
<https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API View Transition>,
enabling CSS-animated transitions between states.
-}
defaultUseViewTransition :: Bool
defaultUseViewTransition :: Bool
defaultUseViewTransition = Bool
False

{- | Default for the @onlyIfMissing@ flag: 'False'.

When 'True', signal values are only set if they don't already exist in the
browser's store. See 'Hypermedia.Datastar.PatchSignals.psOnlyIfMissing'.
-}
defaultOnlyIfMissing :: Bool
defaultOnlyIfMissing :: Bool
defaultOnlyIfMissing = Bool
False

{- | Default for the @autoRemove@ flag: 'True'.

When 'True', scripts executed via 'Hypermedia.Datastar.ExecuteScript.executeScript'
are automatically removed from the DOM after running.
-}
defaultAutoRemove :: Bool
defaultAutoRemove :: Bool
defaultAutoRemove = Bool
True

-- | Default element namespace: 'HtmlNs'.
defaultNamespace :: ElementNamespace
defaultNamespace :: ElementNamespace
defaultNamespace = ElementNamespace
HtmlNs