PatchSignals.hs

-- |
-- Module      : Hypermedia.Datastar.PatchSignals
-- Description : Update the browser's reactive signal store
--
-- Signals are Datastar's reactive state — key-value pairs that live in the
-- browser and drive the UI. The server can update signals at any time by
-- sending a @datastar-patch-signals@ event.
--
-- Signal patching uses JSON Merge Patch semantics: set a key to update it,
-- set a key to @null@ to remove it, and omit a key to leave it unchanged.
--
-- @
-- sendPatchSignals gen (patchSignals \"{\\\"count\\\": 42}\")
-- @
--
-- To set initial state without overwriting values the user may have already
-- changed (e.g. form inputs), use 'psOnlyIfMissing':
--
-- @
-- sendPatchSignals gen
--   (patchSignals \"{\\\"name\\\": \\\"default\\\"}\")
--     { psOnlyIfMissing = True }
-- @
module Hypermedia.Datastar.PatchSignals where

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

-- | Configuration for a @datastar-patch-signals@ SSE event.
--
-- Construct values with 'patchSignals', then customise with record updates.
data PatchSignals = PatchSignals
  { psSignals :: Text
  -- ^ JSON object containing the signal values to patch. Uses JSON Merge
  -- Patch semantics: set a key to update it, set to @null@ to remove it.
  , psOnlyIfMissing :: Bool
  -- ^ When 'True', signal values are only set if the key doesn't already
  -- exist in the browser's store. Useful for setting initial state that
  -- shouldn't overwrite user changes (e.g. form input defaults).
  -- Default: 'False'.
  , psEventId :: Maybe Text
  -- ^ Optional SSE event ID for reconnection. See 'Hypermedia.Datastar.PatchElements.PatchElements' for details.
  , psRetryDuration :: Int
  -- ^ SSE retry interval in milliseconds. Default: @1000@.
  }
  deriving (Eq, Show)

-- | Build a 'PatchSignals' event with sensible defaults.
--
-- The argument is a JSON object (as 'Text') describing the signals to update.
--
-- @
-- patchSignals \"{\\\"count\\\": 42, \\\"label\\\": \\\"hello\\\"}\"
-- @
patchSignals :: Text -> PatchSignals
patchSignals sigs =
  PatchSignals
    { psSignals = sigs
    , psOnlyIfMissing = defaultOnlyIfMissing
    , psEventId = Nothing
    , psRetryDuration = defaultRetryDuration
    }

toDatastarEvent :: PatchSignals -> DatastarEvent
toDatastarEvent ps =
  DatastarEvent
    { eventType = EventPatchSignals
    , eventId = psEventId ps
    , retry = psRetryDuration ps
    , dataLines = ifMissingLine ++ signalLines
    }
 where
  ifMissingLine = ["onlyIfMissing true" | psOnlyIfMissing ps]
  signalLines = map ("signals " <>) $ T.lines $ psSignals ps