Types.hs

-- |
-- 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 (Eq, Show)

eventTypeToText :: EventType -> Text
eventTypeToText EventPatchElements = "datastar-patch-elements"
eventTypeToText EventPatchSignals = "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 (Eq, Show)

patchModeToText :: ElementPatchMode -> Text
patchModeToText Outer = "outer"
patchModeToText Inner = "inner"
patchModeToText Remove = "remove"
patchModeToText Replace = "replace"
patchModeToText Prepend = "prepend"
patchModeToText Append = "append"
patchModeToText Before = "before"
patchModeToText After = "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 (Eq, Show)

namespaceToText :: ElementNamespace -> Text
namespaceToText HtmlNs = "html"
namespaceToText SvgNs = "svg"
namespaceToText MathmlNs = "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
  { eventType :: EventType
  , eventId :: Maybe Text
  , retry :: Int
  , 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 = 1000

-- | Default element patch mode: 'Outer'.
--
-- Replaces the target element (matched by @id@) and its contents using
-- Datastar's morphing algorithm.
defaultPatchMode :: ElementPatchMode
defaultPatchMode = 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 = 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 = 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 = True

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