ExecuteScript.hs

{- |
Module      : Hypermedia.Datastar.ExecuteScript
Description : Execute JavaScript in the browser via SSE

Sometimes you need a one-shot browser-side effect that doesn't fit neatly
into DOM patching or signal updates — redirecting to another page, focusing
an input, triggering a download, or calling a browser API.
'executeScript' lets the server push arbitrary JavaScript to the browser.

Under the hood, Datastar appends a @\<script\>@ tag to @\<body\>@. By default
the script tag removes itself from the DOM after executing (see 'esAutoRemove').

Note: per the Datastar protocol, script execution uses the
@datastar-patch-elements@ event type — there is no separate event type for
scripts.

@
sendExecuteScript gen (executeScript \"window.location = \\\"/dashboard\\\"\")
@

To add attributes to the generated @\<script\>@ tag:

@
sendExecuteScript gen
  (executeScript \"import(\\\"/modules\/chart.js\\\").then(m => m.render())\")
    { esAttributes = [\"type=\\\"module\\\"\"] }
@
-}
module Hypermedia.Datastar.ExecuteScript where

import Data.Text (Text)
import Data.Text qualified as T
import Hypermedia.Datastar.Types

{- | Configuration for executing a script in the browser.

Construct values with 'executeScript', then customise with record updates.
-}
data ExecuteScript = ExecuteScript
  { esScript :: Text
  -- ^ The JavaScript code to execute.
  , esAutoRemove :: Bool
  {- ^ Whether the @\<script\>@ tag should remove itself from the DOM after
  executing. Default: 'True'. Set to 'False' if the script defines
  functions or variables that need to persist in the page.
  -}
  , esAttributes :: [Text]
  {- ^ Extra attributes to add to the @\<script\>@ tag. For example,
  @[\"type=\\\"module\\\"\"]@ to use ES module imports, or
  @[\"nonce=\\\"abc123\\\"\"]@ for CSP compliance.
  -}
  , esEventId :: Maybe Text
  -- ^ Optional SSE event ID for reconnection.
  , esRetryDuration :: Int
  -- ^ SSE retry interval in milliseconds. Default: @1000@.
  }
  deriving (Eq, Show)

{- | Build an 'ExecuteScript' event with sensible defaults.

The argument is the JavaScript source code to run in the browser.

@
executeScript \"document.getElementById(\\\"name\\\").focus()\"
@
-}
executeScript :: Text -> ExecuteScript
executeScript js =
  ExecuteScript
    { esScript = js
    , esAutoRemove = defaultAutoRemove
    , esAttributes = []
    , esEventId = Nothing
    , esRetryDuration = defaultRetryDuration
    }

toDatastarEvent :: ExecuteScript -> DatastarEvent
toDatastarEvent es =
  DatastarEvent
    { eventType = EventPatchElements -- Correct, there is no EventExecuteScript, see the ADR
    , eventId = esEventId es
    , retry = esRetryDuration es
    , dataLines =
        [ "selector body"
        , "mode append"
        ]
          <> buildScriptLines es
    }

buildScriptLines :: ExecuteScript -> [Text]
buildScriptLines es =
  case T.lines (esScript es) of
    [] -> ["elements " <> openTag <> closeTag]
    [single] -> ["elements " <> openTag <> single <> closeTag]
    multiple ->
      ["elements " <> openTag]
        <> map ("elements " <>) multiple
        <> ["elements " <> closeTag]
 where
  openTag :: Text
  openTag =
    "<script"
      <> (if esAutoRemove es then " data-effect=\"el.remove()\"" else "")
      <> foldMap (" " <>) (esAttributes es)
      <> ">"

  closeTag :: Text
  closeTag = "</script>"