rustolio_web/hooks/signal/

mod.rs

//
// SPDX-License-Identifier: MPL-2.0
//
// Copyright (c) 2026 Tobias Binnewies. All rights reserved.
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
//

mod store;

use super::{Dependency, Scope};

pub(super) use store::SignalStore;

pub trait SignalBase<T> {
    /// Returns the underlying signal of the concrete implementation.
    ///
    /// This is used the implement all other common signal methods, but can be useful to "flatten" other Hooks so they can be used as a "standard" signal
    fn base(&self) -> Signal<T>;

    /// Should only called using the [`global!`] macro.
    ///
    /// # Unsafe
    /// Breaks if this is not called directly after signal creation.
    ///
    /// [`global!`]: crate::prelude::global!
    #[doc(hidden)]
    unsafe fn globalize(&self) {
        unsafe {
            // SAFETY: Caller is responsible for safe call.
            Scope::deregister_signal(self.base().slot)
        };
    }
}

pub trait SignalGetter<T>: SignalBase<T>
where
    T: Clone + 'static,
{
    // /// Calls all dependencies of the signal without changing its value.
    // fn refresh(&self) {
    //     let s = self.signal();
    //     SignalStore::refresh(s.slot);
    // }

    /// Returns the current value of the signal without tracking updates.
    ///
    /// If updates should be tracked, use [`Self::value()`].
    #[track_caller]
    fn peek(&self) -> T {
        let s = self.base();
        SignalStore::read::<T>(s.slot)
    }

    /// Return the value of the signal and appends it to the current scope's dependencies.
    /// If the values changes, the scope gets reexecuted to update to the new value.
    ///
    /// If update should not be tracked, use [`Self::peek()`].
    #[track_caller]
    fn value(&self) -> T {
        let s = self.base();

        #[cfg(debug_assertions)]
        if s.is_immutable() {
            panic!(
                r#"
A signal value was accessed within the same scope in which it was created, so the signal itself will be recreated with every update. This makes the signal effectively immutable.

Wrap the signal access in a dynamic element (e.g., `move || my_signal.value()`) to fix this.
                "#
            );
        }

        SignalStore::update_read(s.slot)
    }
}

pub trait SignalSetter<T>: SignalBase<T>
where
    T: PartialEq + 'static,
{
    /// Sets the value of the signal and notifies all dependencies.
    ///
    /// If the value is the same as the current value, nothing happens.
    ///
    /// Returns the old value of the signal.
    #[track_caller]
    fn set(&self, value: impl Into<T>) -> T {
        let s = self.base();
        SignalStore::set(s.slot, value.into())
    }
}

pub trait SignalUpdater<T>: SignalBase<T>
where
    T: 'static,
{
    /// Updates the signal value without cloning it using the provided updater function and notifies all dependencies.
    /// This will happen, no matter if the value acually changed or not.
    ///
    /// Returns whatever the updater function returns.
    ///
    /// # Panic
    /// This will panic if other signals are read or created in the updater closure.
    /// Do this beforehand if its needed.
    #[track_caller]
    fn update<U>(&self, updater: impl FnOnce(&mut T) -> U) -> U {
        let s = self.base();
        SignalStore::update(s.slot, updater)
    }

    /// Sets the value of the signal and notifies all its dependencies.
    ///
    /// This does not check if the value is the same as the current value.
    #[track_caller]
    fn set_unchecked(&self, value: impl Into<T>) {
        let s = self.base();
        SignalStore::set_unchecked(s.slot, value.into());
    }
}

pub trait SignalToggle: SignalUpdater<bool> {
    #[track_caller]
    fn toggle(&self) -> bool {
        self.update(|s| {
            let old = *s;
            *s = !old;
            old
        })
    }
}
impl<S> SignalToggle for S where S: SignalUpdater<bool> {}

#[derive(Debug, PartialEq, Eq)]
pub struct Signal<T> {
    pub(super) slot: usize,
    _value: std::marker::PhantomData<T>,

    #[cfg(debug_assertions)]
    always_mutable: bool,
}

impl<T> SignalBase<T> for Signal<T> {
    fn base(&self) -> Signal<T> {
        *self
    }
}
impl<T> SignalGetter<T> for Signal<T> where T: Clone + 'static {}
impl<T> SignalSetter<T> for Signal<T> where T: PartialEq + 'static {}
impl<T> SignalUpdater<T> for Signal<T> where T: 'static {}

// Impl `Clone` and `Copy` manually to avoid requiring `T: Clone + Copy`
impl<T> Clone for Signal<T> {
    fn clone(&self) -> Self {
        *self
    }
}
impl<T> Copy for Signal<T> {}

impl<T> Default for Signal<T>
where
    T: Default + 'static,
{
    fn default() -> Self {
        Self::new(T::default())
    }
}

impl<T> Signal<T>
where
    T: 'static,
{
    /// Creates a new signal with the given initial value.
    ///
    /// A signal is a reactive value that can be read and updated. When a signal is updated, all function components that read the signal will be re-run to reflect the new value.
    ///
    /// The signal is removed when the component which created it goes out of scope.
    ///
    /// # Example
    /// ```
    /// use rustolio_web::prelude::*;
    ///
    /// let s = Signal::new("Hello World".to_string());
    /// div! {
    ///     class: "container",
    ///     move || s.value(),
    /// };
    /// ```
    ///
    /// # Caveats
    /// All caveats will throw an runtime error in debug mode.
    ///
    /// ## Immutable Signals
    /// When creating a signal, it is important to ensure that the signal is read in a function component (e.g., `move || s.value()`). If this is not done, the signal itself will be recreated on every update, making it effectively immutable.
    ///
    /// Dont do this:
    /// ``` ignore
    /// use rustolio_web::prelude::*;
    ///
    /// let s = Signal::new("Hello World".to_string());
    /// div! {
    ///    s.value()
    /// };
    /// ```
    /// Do this instead:
    /// ```
    /// use rustolio_web::prelude::*;
    ///
    /// let s = Signal::new("Hello World".to_string());
    /// div! {
    ///    move || s.value()
    /// };
    /// // OR
    /// move || div! {
    ///    s.value()
    /// };
    /// ```
    ///
    /// ## Breaking Signals
    /// When reading a signal value, it is important to ensure that the next component is not a function component. This would break the signal's updater, as it would replace the component without notifying the signal's updater.
    ///
    /// Dont do this:
    /// ``` ignore
    /// use rustolio_web::prelude::*;
    ///
    /// let s = Signal::new("Hello World".to_string());
    /// let s1 = Signal::new("Hello World 2".to_string());
    /// div! {
    ///    move || {
    ///       let value = s.value();
    ///       move || div! {
    ///          format!("S: {} - S1: {}", value, s1.value())
    ///       }
    ///    }
    /// };
    /// ```
    /// Do this instead:
    /// ```
    /// use rustolio_web::prelude::*;
    ///
    /// let s = Signal::new("Hello World".to_string());
    /// let s1 = Signal::new("Hello World 2".to_string());
    /// div! {
    ///    move || {
    ///       let value = s.value();
    ///       div! {
    ///          move || div! {
    ///             format!("S: {} - S1: {}", value, s1.value())
    ///          }
    ///       }
    ///    }
    /// };
    /// ```
    ///
    pub fn new(initial: T) -> Self {
        let slot = SignalStore::insert(initial);
        Scope::register_signal(slot);
        Signal {
            slot,
            _value: std::marker::PhantomData,
            #[cfg(debug_assertions)]
            always_mutable: false,
        }
    }

    /// Creates the Signal (same as [`Self::new`]) but the check for immutablility will alway succeed.
    ///
    /// This can be useful for Signal-Wrapper which are allowed the be read in the same scope.
    pub fn always_mutable(initial: T) -> Self {
        let slot = SignalStore::insert(initial);
        Scope::register_signal(slot);
        Signal {
            slot,
            _value: std::marker::PhantomData,
            #[cfg(debug_assertions)]
            always_mutable: true,
        }
    }

    /// Creates a new signal without setting an initial value.
    ///
    /// This is unsafe because reading, updating or setting the signal before it has been initialized will cause a panic.
    ///
    /// The signal must be set by using the [`Self::set_unchecked`] method before using any other method.
    pub(super) unsafe fn empty_always_mutable(scoped: bool) -> Self {
        let slot = SignalStore::insert(());
        if scoped {
            Scope::register_signal(slot);
        }
        Signal {
            slot,
            _value: std::marker::PhantomData,
            #[cfg(debug_assertions)]
            always_mutable: true,
        }
    }

    pub(super) fn from_slot(slot: usize) -> Self {
        Signal {
            slot,
            _value: std::marker::PhantomData,
            #[cfg(debug_assertions)]
            always_mutable: false,
        }
    }

    #[cfg(debug_assertions)]
    fn is_immutable(&self) -> bool {
        !self.always_mutable && Scope::signal_created_in_current_scope(*self)
    }

    // #[cfg(debug_assertions)]
    // #[track_caller]
    // fn check_breaking_read(&self) -> Option<HashSet<SignalReadInfo>> {
    //     BreakingSignalChecker::signal_read(self.slot)
    // }
}

#[derive(Debug, PartialEq, Eq)]
pub struct GlobalSignal<T>(Signal<T>);

impl<T> GlobalSignal<T>
where
    T: 'static,
{
    /// Will not be removed when the component which created it goes out of scope.
    ///
    /// This is useful for signals that should be globally accessible.
    pub fn new(initial: T) -> Self {
        let slot = SignalStore::insert(initial);
        Self(Signal {
            slot,
            _value: std::marker::PhantomData,
            #[cfg(debug_assertions)]
            always_mutable: true,
        })
    }
}

impl<T> Default for GlobalSignal<T>
where
    T: Default + 'static,
{
    fn default() -> Self {
        Self::new(T::default())
    }
}

impl<T> SignalBase<T> for GlobalSignal<T> {
    fn base(&self) -> Signal<T> {
        self.0
    }
    unsafe fn globalize(&self) {
        // Nothing to do - the underlying signal was never registered
    }
}
impl<T> SignalGetter<T> for GlobalSignal<T> where T: Clone + 'static {}
impl<T> SignalSetter<T> for GlobalSignal<T> where T: PartialEq + 'static {}
impl<T> SignalUpdater<T> for GlobalSignal<T> where T: 'static {}

impl<T> From<GlobalSignal<T>> for Signal<T>
where
    T: Clone + 'static,
{
    fn from(val: GlobalSignal<T>) -> Self {
        val.base()
    }
}

// Impl `Clone` and `Copy` manually to avoid requiring `T: Clone + Copy`
impl<T> Clone for GlobalSignal<T> {
    fn clone(&self) -> Self {
        *self
    }
}
impl<T> Copy for GlobalSignal<T> {}

#[cfg(test)]
mod tests {
    use crate::prelude::*;

    #[test]
    fn test_signal() {
        let s = Signal::new(0);
        assert_eq!(s.value(), 0);
        assert_eq!(s.peek(), 0);
        let old = s.set(42);
        assert_eq!(old, 0);
        assert_eq!(s.value(), 42);
        assert_eq!(s.peek(), 42);
        let res = s.update(|v| {
            *v += 1;
            "Some random return value"
        });
        assert_eq!(res, "Some random return value");
        assert_eq!(s.value(), 43);
        assert_eq!(s.peek(), 43);
        s.set_unchecked(100);
        assert_eq!(s.value(), 100);
        assert_eq!(s.peek(), 100);

        // Test that signal impls `Copy` with `T: !Copy`
        let s = Signal::new("Hello".to_string());
        let _s1 = s;
        let _s2 = s;

        // Test that signal impls `Copy` with `T: !Copy`
        let s = GlobalSignal::new("Hello".to_string());
        let _s1 = s;
        let _s2 = s;
    }
}