document signals crate

packages/hooks/src/computed.rs

@@ -1,210 +0,0 @@
-use dioxus_core::{ScopeId, ScopeState};
-use slab::Slab;
-use std::{
-    cell::{RefCell, RefMut},
-    collections::HashSet,
-    ops::{Deref, DerefMut},
-    rc::Rc,
-};
-
-/// Create a new tracked state.
-/// Tracked state is state that can drive Selector state
-///
-/// It state will efficiently update any Selector state that is reading from it, but it is not readable on it's own.
-///
-/// ```rust
-/// use dioxus::prelude::*;
-///
-/// fn Parent(cx: Scope) -> Element {
-///    let count = use_tracked_state(cx, || 0);
-///
-///    render! {
-///        Child {
-///            count: count.clone(),
-///        }
-///    }
-/// }
-///
-/// #[inline_props]
-/// fn Child(cx: Scope, count: Tracked<usize>) -> Element {
-///    let less_than_five = use_selector(cx, count, |count| *count < 5);
-///
-///    render! {
-///        "{less_than_five}"
-///    }
-/// }
-/// ```
-pub fn use_tracked_state<T: 'static>(cx: &ScopeState, init: impl FnOnce() -> T) -> &Tracked<T> {
-    cx.use_hook(|| {
-        let init = init();
-        Tracked::new(cx, init)
-    })
-}
-
-/// Tracked state is state that can drive Selector state
-///
-/// Tracked state will efficiently update any Selector state that is reading from it, but it is not readable on it's own.
-#[derive(Clone)]
-pub struct Tracked<I> {
-    state: Rc<RefCell<I>>,
-    update_any: std::sync::Arc<dyn Fn(ScopeId)>,
-    subscribers: SubscribedCallbacks<I>,
-}
-
-impl<I: PartialEq> PartialEq for Tracked<I> {
-    fn eq(&self, other: &Self) -> bool {
-        self.state == other.state
-    }
-}
-
-impl<I> Tracked<I> {
-    /// Create a new tracked state
-    pub fn new(cx: &ScopeState, state: I) -> Self {
-        let subscribers = std::rc::Rc::new(std::cell::RefCell::new(Slab::new()));
-        Self {
-            state: Rc::new(RefCell::new(state)),
-            subscribers,
-            update_any: cx.schedule_update_any(),
-        }
-    }
-
-    /// Create a new Selector state from this tracked state
-    pub fn compute<O: PartialEq + 'static>(
-        &self,
-        mut compute: impl FnMut(&I) -> O + 'static,
-    ) -> Selector<O, I> {
-        let subscribers = Rc::new(RefCell::new(HashSet::new()));
-        let state = Rc::new(RefCell::new(compute(&self.state.borrow())));
-        let update_any = self.update_any.clone();
-
-        Selector {
-            value: state.clone(),
-            subscribers: subscribers.clone(),
-            _tracker: Rc::new(self.track(move |input_state| {
-                let new = compute(input_state);
-                let different = {
-                    let state = state.borrow();
-                    *state != new
-                };
-                if different {
-                    let mut state = state.borrow_mut();
-                    *state = new;
-                    for id in subscribers.borrow().iter().copied() {
-                        (update_any)(id);
-                    }
-                }
-            })),
-        }
-    }
-
-    pub(crate) fn track(&self, update: impl FnMut(&I) + 'static) -> Tracker<I> {
-        let mut subscribers = self.subscribers.borrow_mut();
-        let id = subscribers.insert(Box::new(update));
-        Tracker {
-            subscribers: self.subscribers.clone(),
-            id,
-        }
-    }
-
-    /// Write to the tracked state
-    pub fn write(&self) -> TrackedMut<'_, I> {
-        TrackedMut {
-            state: self.state.borrow_mut(),
-            subscribers: self.subscribers.clone(),
-        }
-    }
-}
-
-/// A mutable reference to tracked state
-pub struct TrackedMut<'a, I> {
-    state: RefMut<'a, I>,
-    subscribers: SubscribedCallbacks<I>,
-}
-
-impl<'a, I> Deref for TrackedMut<'a, I> {
-    type Target = I;
-
-    fn deref(&self) -> &Self::Target {
-        &self.state
-    }
-}
-
-impl<'a, I> DerefMut for TrackedMut<'a, I> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.state
-    }
-}
-
-impl<'a, I> Drop for TrackedMut<'a, I> {
-    fn drop(&mut self) {
-        let state = self.state.deref();
-        for (_, sub) in &mut *self.subscribers.borrow_mut() {
-            sub(state);
-        }
-    }
-}
-
-type SubscribedCallbacks<I> = std::rc::Rc<std::cell::RefCell<Slab<Box<dyn FnMut(&I) + 'static>>>>;
-
-pub(crate) struct Tracker<I> {
-    subscribers: SubscribedCallbacks<I>,
-    id: usize,
-}
-
-impl<I> Drop for Tracker<I> {
-    fn drop(&mut self) {
-        let _ = self.subscribers.borrow_mut().remove(self.id);
-    }
-}
-
-pub fn use_selector<I: 'static, O: Clone + PartialEq + 'static>(
-    cx: &ScopeState,
-    tracked: &Tracked<I>,
-    init: impl FnMut(&I) -> O + 'static,
-) -> O {
-    let selector = cx.use_hook(|| tracked.compute(init));
-    selector.use_state(cx)
-}
-
-/// Selector state is state that is derived from tracked state
-///
-/// Whenever the tracked state changes, the Selector state will be updated and any components reading from it will be rerun
-#[derive(Clone)]
-pub struct Selector<T, I> {
-    _tracker: Rc<Tracker<I>>,
-    value: Rc<RefCell<T>>,
-    subscribers: Rc<RefCell<HashSet<ScopeId>>>,
-}
-
-impl<T, I> PartialEq for Selector<T, I> {
-    fn eq(&self, other: &Self) -> bool {
-        std::rc::Rc::ptr_eq(&self.value, &other.value)
-    }
-}
-
-impl<T: Clone + PartialEq, I> Selector<T, I> {
-    /// Read the Selector state and subscribe to updates
-    pub fn use_state(&self, cx: &ScopeState) -> T {
-        cx.use_hook(|| {
-            let id = cx.scope_id();
-            self.subscribers.borrow_mut().insert(id);
-
-            ComputedRead {
-                scope: cx.scope_id(),
-                subscribers: self.subscribers.clone(),
-            }
-        });
-        self.value.borrow().clone()
-    }
-}
-
-struct ComputedRead {
-    scope: ScopeId,
-    subscribers: std::rc::Rc<std::cell::RefCell<std::collections::HashSet<ScopeId>>>,
-}
-
-impl Drop for ComputedRead {
-    fn drop(&mut self) {
-        self.subscribers.borrow_mut().remove(&self.scope);
-    }
-}

packages/hooks/src/lib.rs

@@ -52,9 +52,6 @@ macro_rules! to_owned {
     };
 }
 
-mod computed;
-pub use computed::*;
-
 mod use_on_unmount;
 pub use use_on_unmount::*;
 

packages/signals/src/effect.rs

@@ -20,6 +20,13 @@ pub(crate) fn get_effect_stack() -> EffectStack {
     }
 }
 
+/// Create a new effect. The effect will be run immediately and whenever any signal it reads changes.
+/// The signal will be owned by the current component and will be dropped when the component is dropped.
+pub fn use_effect(cx: &ScopeState, callback: impl FnMut() + 'static) {
+    cx.use_hook(|| Effect::new(callback));
+}
+
+/// Effects allow you to run code when a signal changes. Effects are run immediately and whenever any signal it reads changes.
 #[derive(Copy, Clone, PartialEq)]
 pub struct Effect {
     pub(crate) callback: CopyValue<Box<dyn FnMut()>>,
@@ -36,6 +43,9 @@ impl Effect {
         get_effect_stack().effects.read().last().copied()
     }
 
+    /// Create a new effect. The effect will be run immediately and whenever any signal it reads changes.
+    ///
+    /// The signal will be owned by the current component and will be dropped when the component is dropped.
     pub fn new(callback: impl FnMut() + 'static) -> Self {
         let myself = Self {
             callback: CopyValue::new(Box::new(callback)),

packages/signals/src/impls.rs

@@ -43,6 +43,7 @@ macro_rules! read_impls {
         }
 
         impl<T: 'static> $ty<Option<T>> {
+            /// Unwraps the inner value and clones it.
             pub fn unwrap(&self) -> T
             where
                 T: Clone,
@@ -50,6 +51,7 @@ macro_rules! read_impls {
                 self.with(|v| v.clone()).unwrap()
             }
 
+            /// Attemps to read the inner value of the Option.
             pub fn as_ref(&self) -> Option<Ref<'_, T>> {
                 Ref::filter_map(self.read(), |v| v.as_ref()).ok()
             }
@@ -59,6 +61,14 @@ macro_rules! read_impls {
 
 macro_rules! write_impls {
     ($ty:ident) => {
+        impl<T: Add<Output = T> + Copy + 'static> std::ops::Add<T> for $ty<T> {
+            type Output = T;
+
+            fn add(self, rhs: T) -> Self::Output {
+                self.with(|v| *v + rhs)
+            }
+        }
+
         impl<T: Add<Output = T> + Copy + 'static> std::ops::AddAssign<T> for $ty<T> {
             fn add_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v + rhs)
@@ -71,73 +81,111 @@ macro_rules! write_impls {
             }
         }
 
+        impl<T: Sub<Output = T> + Copy + 'static> std::ops::Sub<T> for $ty<T> {
+            type Output = T;
+
+            fn sub(self, rhs: T) -> Self::Output {
+                self.with(|v| *v - rhs)
+            }
+        }
+
         impl<T: Mul<Output = T> + Copy + 'static> std::ops::MulAssign<T> for $ty<T> {
             fn mul_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v * rhs)
             }
         }
 
+        impl<T: Mul<Output = T> + Copy + 'static> std::ops::Mul<T> for $ty<T> {
+            type Output = T;
+
+            fn mul(self, rhs: T) -> Self::Output {
+                self.with(|v| *v * rhs)
+            }
+        }
+
         impl<T: Div<Output = T> + Copy + 'static> std::ops::DivAssign<T> for $ty<T> {
             fn div_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v / rhs)
             }
         }
 
+        impl<T: Div<Output = T> + Copy + 'static> std::ops::Div<T> for $ty<T> {
+            type Output = T;
+
+            fn div(self, rhs: T) -> Self::Output {
+                self.with(|v| *v / rhs)
+            }
+        }
+
         impl<T: 'static> $ty<Vec<T>> {
+            /// Pushes a new value to the end of the vector.
             pub fn push(&self, value: T) {
                 self.with_mut(|v| v.push(value))
             }
 
+            /// Pops the last value from the vector.
             pub fn pop(&self) -> Option<T> {
                 self.with_mut(|v| v.pop())
             }
 
+            /// Inserts a new value at the given index.
             pub fn insert(&self, index: usize, value: T) {
                 self.with_mut(|v| v.insert(index, value))
             }
 
+            /// Removes the value at the given index.
             pub fn remove(&self, index: usize) -> T {
                 self.with_mut(|v| v.remove(index))
             }
 
+            /// Clears the vector, removing all values.
             pub fn clear(&self) {
                 self.with_mut(|v| v.clear())
             }
 
+            /// Extends the vector with the given iterator.
             pub fn extend(&self, iter: impl IntoIterator<Item = T>) {
                 self.with_mut(|v| v.extend(iter))
             }
 
+            /// Truncates the vector to the given length.
             pub fn truncate(&self, len: usize) {
                 self.with_mut(|v| v.truncate(len))
             }
 
+            /// Swaps two values in the vector.
             pub fn swap_remove(&self, index: usize) -> T {
                 self.with_mut(|v| v.swap_remove(index))
             }
 
+            /// Retains only the values that match the given predicate.
             pub fn retain(&self, f: impl FnMut(&T) -> bool) {
                 self.with_mut(|v| v.retain(f))
             }
 
+            /// Splits the vector into two at the given index.
             pub fn split_off(&self, at: usize) -> Vec<T> {
                 self.with_mut(|v| v.split_off(at))
             }
         }
 
         impl<T: 'static> $ty<Option<T>> {
+            /// Takes the value out of the Option.
             pub fn take(&self) -> Option<T> {
                 self.with_mut(|v| v.take())
             }
 
+            /// Replace the value in the Option.
             pub fn replace(&self, value: T) -> Option<T> {
                 self.with_mut(|v| v.replace(value))
             }
 
+            /// Gets the value out of the Option, or inserts the given value if the Option is empty.
             pub fn get_or_insert(&self, default: T) -> Ref<'_, T> {
                 self.get_or_insert_with(|| default)
             }
 
+            /// Gets the value out of the Option, or inserts the value returned by the given function if the Option is empty.
             pub fn get_or_insert_with(&self, default: impl FnOnce() -> T) -> Ref<'_, T> {
                 let borrow = self.read();
                 if borrow.is_none() {
@@ -158,6 +206,7 @@ read_impls!(Signal);
 write_impls!(Signal);
 read_impls!(ReadOnlySignal);
 
+/// An iterator over the values of a `CopyValue<Vec<T>>`.
 pub struct CopyValueIterator<T: 'static> {
     index: usize,
     value: CopyValue<Vec<T>>,
@@ -198,12 +247,13 @@ impl<T: 'static> CopyValue<Option<T>> {
     }
 }
 
-pub struct CopySignalIterator<T: 'static> {
+/// An iterator over items in a `Signal<Vec<T>>`.
+pub struct SignalIterator<T: 'static> {
     index: usize,
     value: Signal<Vec<T>>,
 }
 
-impl<T: Clone> Iterator for CopySignalIterator<T> {
+impl<T: Clone> Iterator for SignalIterator<T> {
     type Item = T;
 
     fn next(&mut self) -> Option<Self::Item> {
@@ -214,12 +264,12 @@ impl<T: Clone> Iterator for CopySignalIterator<T> {
 }
 
 impl<T: Clone + 'static> IntoIterator for Signal<Vec<T>> {
-    type IntoIter = CopySignalIterator<T>;
+    type IntoIter = SignalIterator<T>;
 
     type Item = T;
 
     fn into_iter(self) -> Self::IntoIter {
-        CopySignalIterator {
+        SignalIterator {
             index: 0,
             value: self,
         }
@@ -227,12 +277,14 @@ impl<T: Clone + 'static> IntoIterator for Signal<Vec<T>> {
 }
 
 impl<T: 'static> Signal<Vec<T>> {
+    /// Returns a reference to an element or `None` if out of bounds.
     pub fn get_mut(&self, index: usize) -> Option<Write<'_, T, Vec<T>>> {
         Write::filter_map(self.write(), |v| v.get_mut(index))
     }
 }
 
 impl<T: 'static> Signal<Option<T>> {
+    /// Returns a reference to an element or `None` if out of bounds.
     pub fn as_mut(&self) -> Option<Write<'_, T, Option<T>>> {
         Write::filter_map(self.write(), |v| v.as_mut())
     }

packages/signals/src/rt.rs

@@ -40,12 +40,18 @@ fn owner_in_scope(scope: ScopeId) -> Rc<Owner> {
     }
 }
 
+/// CopyValue is a wrapper around a value to make the value mutable and Copy.
+///
+/// It is internally backed by [`generational_box::GenerationalBox`].
 pub struct CopyValue<T: 'static> {
     pub(crate) value: GenerationalBox<T>,
     origin_scope: ScopeId,
 }
 
 impl<T: 'static> CopyValue<T> {
+    /// Create a new CopyValue. The value will be stored in the current component.
+    ///
+    /// Once the component this value is created in is dropped, the value will be dropped.
     pub fn new(value: T) -> Self {
         let owner = current_owner();
 

packages/signals/src/selector.rs

@@ -2,6 +2,23 @@ use dioxus_core::prelude::*;
 
 use crate::{get_effect_stack, signal::SignalData, CopyValue, Effect, ReadOnlySignal, Signal};
 
+/// Creates a new Selector. The selector will be run immediately and whenever any signal it reads changes.
+///
+/// Selectors can be used to efficiently compute derived data from signals.
+///
+/// ```rust
+/// use dioxus::prelude::*;
+/// use dioxus_signals::*;
+///
+/// fn App(cx: Scope) -> Element {
+///     let mut count = use_signal(cx, || 0);
+///     let double = use_selector(cx, move || count * 2);
+///     count += 1;
+///     assert_eq!(double.value(), count * 2);
+///  
+///     render! { "{double}" }
+/// }
+/// ```
 pub fn use_selector<R: PartialEq>(
     cx: &ScopeState,
     f: impl FnMut() -> R + 'static,
@@ -9,6 +26,9 @@ pub fn use_selector<R: PartialEq>(
     *cx.use_hook(|| selector(f))
 }
 
+/// Creates a new Selector. The selector will be run immediately and whenever any signal it reads changes.
+///
+/// Selectors can be used to efficiently compute derived data from signals.
 pub fn selector<R: PartialEq>(mut f: impl FnMut() -> R + 'static) -> ReadOnlySignal<R> {
     let state = Signal::<R> {
         inner: CopyValue::invalid(),

packages/signals/src/signal.rs

@@ -12,6 +12,37 @@ use dioxus_core::{
 
 use crate::{CopyValue, Effect};
 
+/// Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.
+///
+/// ```rust
+/// use dioxus::prelude::*;
+/// use dioxus_signals::*;
+///
+/// fn App(cx: Scope) -> Element {
+///     let mut count = use_signal(cx, || 0);
+///
+///     // Because signals have automatic dependency tracking, if you never read them in a component, that component will not be re-rended when the signal is updated.
+///     // The app component will never be rerendered in this example.
+///     render! { Child { state: count } }
+/// }
+///
+/// #[inline_props]
+/// fn Child(cx: Scope, state: Signal<u32>) -> Element {
+///     let state = *state;
+///
+///     use_future!(cx,  |()| async move {
+///         // Because the signal is a Copy type, we can use it in an async block without cloning it.
+///         *state.write() += 1;
+///     });
+///
+///     render! {
+///         button {
+///             onclick: move |_| *state.write() += 1,
+///             "{state}"
+///         }
+///     }
+/// }
+/// ```
 pub fn use_signal<T: 'static>(cx: &ScopeState, f: impl FnOnce() -> T) -> Signal<T> {
     *cx.use_hook(|| Signal::new(f()))
 }