From 7e988c42ea5c7796e0d6de7883cc9e088461797c Mon Sep 17 00:00:00 2001
From: Maccesch <maccesch@synphonyte.com>
Date: Thu, 28 Sep 2023 10:58:59 +0100
Subject: [PATCH] added websocket docs for use in context

---
 CHANGELOG.md         |   1 +
 src/use_websocket.rs | 104 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27d0472..9977d74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - The options `reconnect_limit` and `reconnect_interval` now take a `u64` instead of `Option<u64>` to improve DX.
     - The option `manual` has been renamed to `immediate` to make it more consistent with other functions.
       To port please note that `immediate` is the inverse of `manual` (`immediate` = `!manual`).
+    - Added documentation how pass it ergonomically as context.
 - `use_color_mode`:
     - The optional `on_changed` handler parameters have changed slightly. Please refer to the docs for more details.
 - Throttled or debounced functions cannot be `FnOnce` anymore.
diff --git a/src/use_websocket.rs b/src/use_websocket.rs
index cc7d3c4..c50d308 100644
--- a/src/use_websocket.rs
+++ b/src/use_websocket.rs
@@ -67,8 +67,8 @@ use web_sys::{BinaryType, CloseEvent, Event, MessageEvent, WebSocket};
 ///         <button on:click=open_connection disabled=connected>"Open"</button>
 ///         <button on:click=close_connection disabled=move || !connected()>"Close"</button>
 ///
-///         <p>"Receive message: " {move || format!("{:?}", message())}</p>
-///         <p>"Receive byte message: " {move || format!("{:?}", message_bytes())}</p>
+///         <p>"Receive message: " {move || format!("{:?}", message.get())}</p>
+///         <p>"Receive byte message: " {move || format!("{:?}", message_bytes.get())}</p>
 ///     </div>
 /// }
 /// # }
@@ -87,6 +87,106 @@ use web_sys::{BinaryType, CloseEvent, Event, MessageEvent, WebSocket};
 /// | https://example.com/some/where | //otherdomain.com/api/ws | wss://otherdomain.com/api/ws        |
 ///
 ///
+/// ## Usage with `provide_context`
+///
+/// The return value of `use_websocket` utilizes several type parameters which can make it
+/// cumbersome to use with `provide_context` + `expect_context`.
+/// The following example shows how to avoid type parameters with dynamic dispatch.
+/// This sacrifices a little bit of performance for the sake of ergonomics. However,
+/// compared to network transmission speeds this loss of performance is negligible.
+///
+/// First we define the `struct` that is going to be passed around as context.
+///
+/// ```
+/// # use leptos::*;
+/// use std::rc::Rc;
+///
+/// #[derive(Clone)]
+/// pub struct WebsocketContext {
+///     pub message: Signal<Option<String>>,
+///     send: Rc<dyn Fn(&str)>,  // use Rc to make it easily cloneable
+/// }
+///
+/// impl WebsocketContext {
+///     pub fn new(message: Signal<Option<String>>, send: Rc<dyn Fn(&str)>) -> Self {
+///         Self {
+///             message,
+///             send,
+///         }
+///     }
+///
+///     // create a method to avoid having to use parantheses around the field
+///     #[inline(always)]
+///     pub fn send(&self, message: &str) {
+///         (self.send)(message)
+///     }
+/// }
+/// ```
+///
+/// Now you can provide the context like the following.
+///
+/// ```
+/// # use leptos::*;
+/// # use leptos_use::{use_websocket, UseWebsocketReturn};
+/// # use std::rc::Rc;
+/// # #[derive(Clone)]
+/// # pub struct WebsocketContext {
+/// #     pub message: Signal<Option<String>>,
+/// #     send: Rc<dyn Fn(&str)>,
+/// # }
+/// #
+/// # impl WebsocketContext {
+/// #     pub fn new(message: Signal<Option<String>>, send: Rc<dyn Fn(&str)>) -> Self {
+/// #         Self {
+/// #             message,
+/// #             send,
+/// #         }
+/// #     }
+/// # }
+///
+/// # #[component]
+/// # fn Demo() -> impl IntoView {
+/// let UseWebsocketReturn {
+///     message,
+///     send,
+///     ..
+/// } = use_websocket("ws:://some.websocket.io");
+///
+/// provide_context(WebsocketContext::new(message, Rc::new(send.clone())));
+/// #
+/// # view! {}
+/// # }
+/// ```
+///
+/// Finally let's use the context:
+///
+/// ```
+/// # use leptos::*;
+/// # use leptos_use::{use_websocket, UseWebsocketReturn};
+/// # use std::rc::Rc;
+/// # #[derive(Clone)]
+/// # pub struct WebsocketContext {
+/// #     pub message: Signal<Option<String>>,
+/// #     send: Rc<dyn Fn(&str)>,
+/// # }
+/// #
+/// # impl WebsocketContext {
+/// #     #[inline(always)]
+/// #     pub fn send(&self, message: &str) {
+/// #         (self.send)(message)
+/// #     }
+/// # }
+///
+/// # #[component]
+/// # fn Demo() -> impl IntoView {
+/// let websocket = expect_context::<WebsocketContext>();
+///
+/// websocket.send("Hello World!");
+/// #
+/// # view! {}
+/// # }
+/// ```
+///
 /// ## Server-Side Rendering
 ///
 /// On the server the returned functions amount to no-ops.