From 074685acab19032d646f0483f55cc60d36542f30 Mon Sep 17 00:00:00 2001 From: Maccesch Date: Wed, 28 Aug 2024 02:57:26 +0100 Subject: [PATCH] updated docs and changelog --- CHANGELOG.md | 17 +++++-- Cargo.toml | 2 +- README.md | 14 +++--- docs/book/src/introduction.md | 2 +- src/lib.rs | 8 ++-- src/sync_signal.rs | 89 ++++++++++++++++++++++++++++------- src/use_clipboard.rs | 1 + src/use_device_orientation.rs | 1 + src/use_event_listener.rs | 1 + src/use_geolocation.rs | 1 + src/use_toggle.rs | 8 ++-- src/use_user_media.rs | 1 + src/use_web_notification.rs | 1 + 13 files changed, 107 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e33639d..97999cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,20 +3,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] - +## [0.13.0] - 2024-08-28 ### New Functions 🚀 - `use_toggle` -- `use_prefers_reduced_motion` +- `use_prefers_reduced_motion` (thanks to @hcandelaria) -### Breaking Change 🛠 +### Breaking Changes 🛠 - `use_websocket` now supports different types for sending and receiving messages +- `SyncSignalOptions` now can take now either transformations or assignment functions but not both. -### Change 🔥 +### Fixes 🍕 -- There is now a feature for almost every function to get better compile and rust-analyzer times. +- `use_websocket` fixed error with cleanup and reconnect (thanks to @BakerNet). + +### New Features 🚀 + +- There is now a feature for almost every function to get better compile and rust-analyzer times. +- `use_web_notification` now supports the `vibrate` option (thanks to @hcandelaria). +- `UseDocument` now supports a whole bunch of methods more from `document` (thanks to @luckynumberke7in). ## [0.12.0] - 2024-08-14 diff --git a/Cargo.toml b/Cargo.toml index a35148d..78ea78a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "leptos-use" -version = "0.12.0" +version = "0.13.0" edition = "2021" authors = ["Marc-Stefan Cassola"] categories = ["gui", "web-programming"] diff --git a/README.md b/README.md index 933f07f..1c4d8da 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Crates.io SSR Docs & Demos - 82 Functions + 84 Functions


@@ -87,9 +87,9 @@ This will create the function file in the src directory, scaffold an example dir ## Leptos compatibility -| Crate version | Compatible Leptos version | -|------------------|---------------------------| -| <= 0.3 | 0.3 | -| 0.4, 0.5, 0.6 | 0.4 | -| 0.7, 0.8, 0.9 | 0.5 | -| 0.10, 0.11, 0.12 | 0.6 | +| Crate version | Compatible Leptos version | +|---------------|---------------------------| +| <= 0.3 | 0.3 | +| 0.4, 0.5, 0.6 | 0.4 | +| 0.7, 0.8, 0.9 | 0.5 | +| 0.10 – 0.13 | 0.6 | diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md index 8bcc1c1..0719a54 100644 --- a/docs/book/src/introduction.md +++ b/docs/book/src/introduction.md @@ -12,6 +12,6 @@ Crates.io SSR Docs & Demos - 82 Functions + 84 Functions

\ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index 79e59ef..a2f8292 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -28,8 +28,6 @@ mod is_ok; mod is_some; #[cfg(feature = "on_click_outside")] mod on_click_outside; -#[cfg(feature = "use_toggle")] -mod use_toggle; #[cfg(feature = "signal_debounced")] mod signal_debounced; #[cfg(feature = "signal_throttled")] @@ -136,6 +134,8 @@ mod use_timeout_fn; mod use_timestamp; #[cfg(feature = "use_to_string")] mod use_to_string; +#[cfg(feature = "use_toggle")] +mod use_toggle; #[cfg(feature = "use_user_media")] mod use_user_media; #[cfg(feature = "use_web_notification")] @@ -169,8 +169,6 @@ pub use is_ok::*; pub use is_some::*; #[cfg(feature = "on_click_outside")] pub use on_click_outside::*; -#[cfg(feature = "use_toggle")] -pub use use_toggle::*; #[cfg(feature = "signal_debounced")] pub use signal_debounced::*; #[cfg(feature = "signal_throttled")] @@ -277,6 +275,8 @@ pub use use_timeout_fn::*; pub use use_timestamp::*; #[cfg(feature = "use_to_string")] pub use use_to_string::*; +#[cfg(feature = "use_toggle")] +pub use use_toggle::*; #[cfg(feature = "use_user_media")] pub use use_user_media::*; #[cfg(feature = "use_web_notification")] diff --git a/src/sync_signal.rs b/src/sync_signal.rs index 145c0f7..a288e4c 100644 --- a/src/sync_signal.rs +++ b/src/sync_signal.rs @@ -7,8 +7,8 @@ use std::rc::Rc; /// /// > Note: Please consider first if you can achieve your goals with the /// > ["Good Options" described in the Leptos book](https://book.leptos.dev/reactivity/working_with_signals.html#making-signals-depend-on-each-other) -/// > firstly. Only if you really have to, use this function. This is in effect the -/// > ["If you really must..."](https://book.leptos.dev/reactivity/working_with_signals.html#if-you-really-must). +/// > Only if you really have to, use this function. This is, in effect, the +/// > ["If you really must..." option](https://book.leptos.dev/reactivity/working_with_signals.html#if-you-really-must). /// /// ## Demo /// @@ -112,9 +112,10 @@ use std::rc::Rc; /// let stop = sync_signal_with_options( /// (a, set_a), /// (b, set_b), -/// SyncSignalOptions::default() -/// .transform_ltr(|left| *left * 2) -/// .transform_rtl(|right| *right / 2) +/// SyncSignalOptions::with_transforms( +/// |left| *left * 2, +/// |right| *right / 2, +/// ), /// ); /// /// logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 10, b: 20 @@ -129,20 +130,60 @@ use std::rc::Rc; /// /// #### Different Types /// -/// `SyncSignalOptions::default()` is only defined if the two signal types are identical or -/// implement `From` for each other. Otherwise, you have to initialize the options with -/// `with_transforms` instead of `default`. +/// `SyncSignalOptions::default()` is only defined if the two signal types are identical. +/// Otherwise, you have to initialize the options with `with_transforms` or `with_assigns` instead +/// of `default`. /// /// ``` -/// # use leptos_use::SyncSignalOptions; +/// # use leptos::*; +/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions}; /// # use std::str::FromStr; /// # -/// let options = SyncSignalOptions::with_transforms( -/// |left: &String| i32::from_str(left).unwrap_or_default(), -/// |right: &i32| right.to_string(), +/// # #[component] +/// # fn Demo() -> impl IntoView { +/// let (a, set_a) = create_signal("10".to_string()); +/// let (b, set_b) = create_signal(2); +/// +/// let stop = sync_signal_with_options( +/// (a, set_a), +/// (b, set_b), +/// SyncSignalOptions::with_transforms( +/// |left: &String| i32::from_str(left).unwrap_or_default(), +/// |right: &i32| right.to_string(), +/// ), /// ); +/// # +/// # view! { } +/// # } /// ``` /// +/// ``` +/// # use leptos::*; +/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions}; +/// # use std::str::FromStr; +/// # +/// #[derive(Clone)] +/// pub struct Foo { +/// bar: i32, +/// } +/// +/// # #[component] +/// # fn Demo() -> impl IntoView { +/// let (a, set_a) = create_signal(Foo { bar: 10 }); +/// let (b, set_b) = create_signal(2); +/// +/// let stop = sync_signal_with_options( +/// (a, set_a), +/// (b, set_b), +/// SyncSignalOptions::with_assigns( +/// |b: &mut i32, a: &Foo| *b = a.bar, +/// |a: &mut Foo, b: &i32| a.bar = *b, +/// ), +/// ); +/// # +/// # view! { } +/// # } +/// ``` pub fn sync_signal( left: impl Into>, right: impl Into>, @@ -166,7 +207,7 @@ where let SyncSignalOptions { immediate, direction, - transforms + transforms, } = options; let (assign_ltr, assign_rtl) = transforms.assigns(); @@ -228,13 +269,19 @@ pub enum SyncDirection { pub type AssignFn = Rc; +/// Transforms or assigns for syncing. pub enum SyncTransforms { + /// Transform the signal into each other by calling the transform functions. + /// The values are then simply assigned. Transforms { /// Transforms the left signal into the right signal. ltr: Rc R>, /// Transforms the right signal into the left signal. rtl: Rc L>, }, + + /// Assign the signals to each other. Instead of using `=` to assign the signals, + /// these functions are called. Assigns { /// Assigns the left signal to the right signal. ltr: AssignFn, @@ -256,13 +303,16 @@ where } impl SyncTransforms -where L: 'static, R: 'static +where + L: 'static, + R: 'static, { + /// Returns assign functions for both directions that respect the value of this enum. pub fn assigns(&self) -> (AssignFn, AssignFn) { match self { SyncTransforms::Transforms { ltr, rtl } => { - let ltr = Rc::clone(<r); - let rtl = Rc::clone(&rtl); + let ltr = Rc::clone(ltr); + let rtl = Rc::clone(rtl); ( Rc::new(move |right, left| *right = ltr(left)), Rc::new(move |left, right| *left = rtl(right)), @@ -285,13 +335,15 @@ pub struct SyncSignalOptions { direction: SyncDirection, /// How to transform or assign the values to each other - /// Defaults to identity. + /// If `L` and `R` are identical this defaults to the simple `=` operator. If the types are + /// not the same, then you have to choose to either use [`SyncSignalOptions::with_transforms`] + /// or [`SyncSignalOptions::with_assigns`]. #[builder(skip)] transforms: SyncTransforms, } impl SyncSignalOptions { - /// Initializes options with transforms + /// Initializes options with transforms functions that convert the signals into each other. pub fn with_transforms( transform_ltr: impl Fn(&L) -> R + 'static, transform_rtl: impl Fn(&R) -> L + 'static, @@ -306,6 +358,7 @@ impl SyncSignalOptions { } } + /// Initializes options with assign functions that replace the default `=` operator. pub fn with_assigns( assign_ltr: impl Fn(&mut R, &L) + 'static, assign_rtl: impl Fn(&mut L, &R) + 'static, diff --git a/src/use_clipboard.rs b/src/use_clipboard.rs index 0bd0e03..2f2128d 100644 --- a/src/use_clipboard.rs +++ b/src/use_clipboard.rs @@ -4,6 +4,7 @@ use leptos::ev::{copy, cut}; use leptos::*; /// Reactive [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API). +/// /// Provides the ability to respond to clipboard commands (cut, copy, and paste) /// as well as to asynchronously read from and write to the system clipboard. /// Access to the contents of the clipboard is gated behind the diff --git a/src/use_device_orientation.rs b/src/use_device_orientation.rs index 7836a17..82ba68f 100644 --- a/src/use_device_orientation.rs +++ b/src/use_device_orientation.rs @@ -2,6 +2,7 @@ use cfg_if::cfg_if; use leptos::*; /// Reactive [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent). +/// /// Provide web developers with information from the physical orientation of /// the device running the web page. /// diff --git a/src/use_event_listener.rs b/src/use_event_listener.rs index 8f35a51..07dfa66 100644 --- a/src/use_event_listener.rs +++ b/src/use_event_listener.rs @@ -13,6 +13,7 @@ cfg_if! { if #[cfg(not(feature = "ssr"))] { }} /// Use EventListener with ease. +/// /// Register using [addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) on mounted, /// and [removeEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener) automatically on cleanup. /// diff --git a/src/use_geolocation.rs b/src/use_geolocation.rs index 7494ef3..f1d9241 100644 --- a/src/use_geolocation.rs +++ b/src/use_geolocation.rs @@ -3,6 +3,7 @@ use default_struct_builder::DefaultBuilder; use leptos::*; /// Reactive [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API). +/// /// It allows the user to provide their location to web applications if they so desire. For privacy reasons, /// the user is asked for permission to report location information. /// diff --git a/src/use_toggle.rs b/src/use_toggle.rs index 390b510..d3909fa 100644 --- a/src/use_toggle.rs +++ b/src/use_toggle.rs @@ -1,5 +1,5 @@ -use leptos::*; use crate::core::MaybeRwSignal; +use leptos::*; /// A boolean switcher with utility functions. /// @@ -25,7 +25,9 @@ use crate::core::MaybeRwSignal; /// /// * [`fn@crate::use_cycle_list`] // #[doc(cfg(feature = "use_toggle"))] -pub fn use_toggle(initial_value: impl Into>) -> UseToggleReturn { +pub fn use_toggle( + initial_value: impl Into>, +) -> UseToggleReturn { let initial_value = initial_value.into(); let (value, set_value) = initial_value.into_signal(); @@ -52,4 +54,4 @@ where pub value: Signal, /// Sets the current value to the given value. pub set_value: WriteSignal, -} \ No newline at end of file +} diff --git a/src/use_user_media.rs b/src/use_user_media.rs index 76b1eed..b9cdeb3 100644 --- a/src/use_user_media.rs +++ b/src/use_user_media.rs @@ -151,6 +151,7 @@ async fn create_media(video: bool, audio: bool) -> Result for web_sys::NotificationOptions { } /// Options for [`UseWebNotificationReturn::show`]. +/// /// This can be used to override options passed to [`use_web_notification`]. /// See [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/API/notification) for more info. ///