Module

Hylograph.ForceEngine.Halogen

Package
purescript-hylograph-simulation-halogen
Repository
afcondon/purescript-hylograph-simulation-halogen

Halogen Integration for Force Simulations

Provides subscription-based API for integrating simulations with Halogen components.

Recommended: High-Level API with Unified Events

import Hylograph.Simulation (runSimulation, SimulationEvent(..))
import Hylograph.ForceEngine.Halogen (toHalogenEmitter)

handleAction Initialize = do
  { handle, events } <- liftEffect $ runSimulation config
  halogenEmitter <- liftEffect $ toHalogenEmitter events
  void $ H.subscribe $ halogenEmitter <#> SimEvent

handleAction (SimEvent event) = case event of
  Tick { alpha } -> H.modify_ _ { alpha = alpha }
  Completed -> liftEffect $ log "Done!"
  _ -> pure unit

Lower level: a simulation made with callbacks

For a Hylograph.ForceEngine.Simulation made with createWithCallbacks:

handleAction Initialize = do
  callbacks <- liftEffect defaultCallbacks
  sim <- liftEffect $ createWithCallbacks config callbacks
  emitter <- liftEffect $ subscribeToSimulation sim
  void $ H.subscribe $ emitter <#> SimulationEvent

#toHalogenEmitter Source

toHalogenEmitter :: SimulationEmitter -> Effect (Emitter SimulationEvent)

Convert a framework-agnostic SimulationEmitter to Halogen's Emitter.

This is the recommended way to integrate simulations with Halogen. It works with either engine, using the same event model.

import Hylograph.Simulation (runSimulation, SimulationEvent(..))
import Hylograph.ForceEngine.Halogen (toHalogenEmitter)

handleAction Initialize = do
  { handle, events } <- liftEffect $ runSimulation config
  halogenEmitter <- liftEffect $ toHalogenEmitter events
  void $ H.subscribe $ halogenEmitter <#> SimEvent

handleAction (SimEvent event) = case event of
  Tick { alpha, nodeCount } -> do
    H.modify_ _ { alpha = alpha }
  Completed -> do
    liftEffect $ log "Simulation converged!"
  Started -> pure unit
  Stopped -> pure unit

#subscribeToSimulation Source

subscribeToSimulation :: forall row linkRow. Simulation row linkRow -> Effect (Emitter SimulationEvent)

A Halogen emitter of the engine's events (Tick, Started, Stopped, AlphaDecayed) for a Hylograph.ForceEngine.Simulation.

The simulation must have been made with createWithCallbacks; made with plain create, it has no callbacks and the emitter never fires.

Re-exports from Hylograph.ForceEngine.Events

#SimulationEvent Source

data SimulationEvent

Events that can occur during simulation lifecycle.

These types are primarily for Halogen integration via subscriptions. Internally, callbacks are invoked directly without constructing these values.

Usage with Halogen:

handleAction (SimEvent event) = case event of
  Tick -> liftEffect updateDOMPositions
  Started -> H.modify_ _ { simRunning = true }
  Stopped -> H.modify_ _ { simRunning = false }
  AlphaDecayed alpha -> when (alpha < 0.1) $ liftEffect doSomething

Constructors

Instances

#SimulationCallbacks Source

type SimulationCallbacks = { onAlphaThreshold :: Ref (Number -> Effect Unit), onStart :: Ref (Effect Unit), onStop :: Ref (Effect Unit), onTick :: Ref (Effect Unit) }

Callbacks for simulation events.

All callbacks are stored in Refs to allow dynamic updates and to keep the tick loop allocation-free (no closures created per-tick).

The callbacks are Effect Unit rather than taking event data because:

  1. Performance: No boxing/unboxing of event data in hot path
  2. Simplicity: Consumers can read simulation state directly if needed
  3. Flexibility: The consumer decides what data they need

Re-exports from Hylograph.Simulation.Emitter

#SimulationEmitter Source

newtype SimulationEmitter

Framework-agnostic event emitter

This is intentionally opaque - use subscribe to listen for events. The internal representation is a list of listeners with unique IDs.