Navigation

crates/core/src/live_socket/channel.rs

@@ -60,6 +60,7 @@ impl LiveFile {
 
 // For non FFI functions
 impl LiveChannel {
+    /// Retrieves the initial document received upon joining the channel.
     pub fn join_document(&self) -> Result<Document, LiveSocketError> {
         let new_root = match self.join_payload {
             Payload::JSONPayload {
@@ -137,8 +138,8 @@ impl LiveChannel {
         Ok(upload_id)
     }
 
-    // Blocks indefinitely, processing changes to the document using the user provided callback
-    // In `set_event_handler`
+    /// Blocks indefinitely, processing changes to the document using the user provided callback
+    /// In `set_event_handler`
     pub async fn merge_diffs(&self) -> Result<(), LiveSocketError> {
         // TODO: This should probably take the event closure to send changes back to swift/kotlin
         let document = self.document.clone();

crates/core/src/live_socket/mod.rs

@@ -1,5 +1,6 @@
 mod channel;
 mod error;
+mod navigation;
 mod socket;
 
 #[cfg(test)]

crates/core/src/live_socket/navigation/ffi.rs

@@ -0,0 +1,101 @@
+use reqwest::Url;
+
+pub type HistoryId = u64;
+
+#[uniffi::export(callback_interface)]
+pub trait NavEventHandler: Send + Sync {
+    /// This callback instruments events that occur when your user navigates to a
+    /// new view. You can add serialized metadata to these events as a byte buffer
+    /// through the [NavOptions] object.
+    fn handle_event(&self, event: NavEvent) -> HandlerResponse;
+}
+
+#[derive(uniffi::Enum, Clone, Debug, PartialEq, Default)]
+pub enum HandlerResponse {
+    #[default]
+    Default,
+    PreventDefault,
+}
+
+#[derive(uniffi::Enum, Clone, Debug, PartialEq)]
+pub enum NavEventType {
+    Push,
+    Replace,
+    Reload,
+    Traverse,
+}
+
+#[derive(uniffi::Record, Clone, Debug, PartialEq)]
+pub struct NavHistoryEntry {
+    /// The target url.
+    pub url: String,
+    /// Unique id for this piece of nav entry state.
+    pub id: HistoryId,
+    /// state passed in by the user, to be passed in to the navigation event callback.
+    pub state: Option<Vec<u8>>,
+}
+
+/// An event emitted when the user navigates between views.
+#[derive(uniffi::Record, Clone, Debug, PartialEq)]
+pub struct NavEvent {
+    pub event: NavEventType,
+    pub same_document: bool,
+    /// The previous location of the page, if there was one
+    pub from: Option<NavHistoryEntry>,
+    /// Destination URL
+    pub to: NavHistoryEntry,
+    /// Additional user provided metadata handed to the event handler.
+    pub info: Option<Vec<u8>>,
+    /// Persistent state kept in history for as long as the even is in the history stack.
+    pub state: Option<Vec<u8>>,
+}
+
+#[derive(Default, uniffi::Enum)]
+pub enum NavAction {
+    /// Push the navigation event onto the history stack.
+    #[default]
+    Push,
+    /// Replace the current top of the history stack with this navigation event.
+    Replace,
+}
+
+#[derive(Default, uniffi::Record)]
+pub struct NavOptions {
+    pub action: NavAction,
+    pub extra_event_info: Option<Vec<u8>>,
+    pub state: Option<Vec<u8>>,
+}
+
+impl NavEvent {
+    /// Create a new nav event from the details of a [NavCtx::navigate] event
+    pub fn new_from_navigate(
+        new_dest: NavHistoryEntry,
+        old_dest: Option<NavHistoryEntry>,
+        opts: NavOptions,
+    ) -> NavEvent {
+        let event = match opts.action {
+            NavAction::Push => NavEventType::Push,
+            NavAction::Replace => NavEventType::Replace,
+        };
+
+        let new_url = Url::parse(&new_dest.url).ok();
+        let old_url = old_dest
+            .as_ref()
+            .and_then(|dest| Url::parse(&dest.url).ok());
+
+        let same_document = if let (Some(old_url), Some(new_url)) = (old_url, new_url) {
+            old_url.path() == new_url.path()
+        } else {
+            false
+        };
+
+        NavEvent {
+            event,
+            same_document,
+            from: old_dest,
+            to: new_dest,
+            info: opts.extra_event_info,
+            state: opts.state,
+        }
+    }
+}

crates/core/src/live_socket/navigation/mod.rs

@@ -0,0 +1,85 @@
+mod ffi;
+
+use super::socket::LiveSocket;
+pub use ffi::*;
+use reqwest::Url;
+use std::sync::Arc;
+
+#[derive(Clone)]
+struct HandlerInternal(pub Option<Arc<dyn NavEventHandler>>);
+
+impl std::fmt::Debug for HandlerInternal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if self.0.is_some() {
+            write!(f, "Handler Active")?;
+        } else {
+            write!(f, "No Handler Present")?;
+        };
+        Ok(())
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct NavCtx {
+    history: Vec<NavHistoryEntry>,
+    current_id: HistoryId,
+    navigation_event_handler: HandlerInternal,
+    current_dest: Option<NavHistoryEntry>,
+}
+
+impl NavHistoryEntry {
+    pub fn new(url: Url, id: HistoryId, state: Option<Vec<u8>>) -> Self {
+        Self {
+            url: url.to_string(),
+            id,
+            state,
+        }
+    }
+}
+
+impl NavCtx {
+    pub fn new() -> Self {
+        Self {
+            history: vec![],
+            current_id: 0,
+            navigation_event_handler: HandlerInternal(None),
+            current_dest: None,
+        }
+    }
+
+    /// Navigate to `url` with behavior and metadata specified in `opts`.
+    pub fn navigate(&mut self, url: Url, opts: NavOptions) {
+        let next_dest = self.speculative_next_dest(&url, opts.state.clone());
+        let event = NavEvent::new_from_navigate(next_dest.clone(), self.current_dest.clone(), opts);
+
+        match self.handle_event(event) {
+            HandlerResponse::Default => {}
+            HandlerResponse::PreventDefault => return,
+        };
+
+        self.current_id += 1;
+        self.history.push(next_dest)
+    }
+
+    pub fn set_event_handler(&mut self, handler: Arc<dyn NavEventHandler>) {
+        self.navigation_event_handler.0 = Some(handler)
+    }
+
+    pub fn handle_event(&mut self, event: NavEvent) -> HandlerResponse {
+        if let Some(handler) = self.navigation_event_handler.0.as_ref() {
+            handler.handle_event(event)
+        } else {
+            HandlerResponse::Default
+        }
+    }
+
+    fn speculative_next_dest(&self, url: &Url, state: Option<Vec<u8>>) -> NavHistoryEntry {
+        NavHistoryEntry {
+            id: self.current_id + 1,
+            url: url.to_string(),
+            state,
+        }
+    }
+}
+
+impl LiveSocket {}

crates/core/src/live_socket/socket.rs

@@ -1,5 +1,7 @@
 use std::{collections::HashMap, sync::Arc, time::Duration};
 
+use super::navigation::{NavCtx, NavOptions};
+
 use log::debug;
 use phoenix_channels_client::{url::Url, Number, Payload, Socket, Topic, JSON};
 use reqwest::Method as ReqMethod;
@@ -80,6 +82,7 @@ pub struct LiveSocket {
     pub dead_render: Document,
     pub style_urls: Vec<String>,
     pub has_live_reload: bool,
+    navigation_ctx: NavCtx,
     cookies: Vec<String>,
     timeout: Duration,
 }
@@ -305,6 +308,8 @@ impl LiveSocket {
             .last();
 
         let has_live_reload = live_reload_iframe.is_some();
+        let mut navigation_ctx = NavCtx::new();
+        navigation_ctx.navigate(url.clone(), NavOptions::default());
 
         debug!("iframe src: {live_reload_iframe:?}");
 
@@ -321,6 +326,7 @@ impl LiveSocket {
             has_live_reload,
             cookies,
             format,
+            navigation_ctx,
         })
     }
 

crates/core/src/live_socket/tests/mod.rs

@@ -2,6 +2,7 @@ use std::time::Duration;
 
 use super::*;
 mod error;
+mod navigation;
 mod streaming;
 mod upload;
 

crates/core/src/live_socket/tests/navigation.rs

@@ -0,0 +1,81 @@
+use std::sync::{Arc, Mutex};
+
+use crate::live_socket::navigation::*;
+use pretty_assertions::{assert_eq, assert_ne};
+use reqwest::Url;
+use serde::{Deserialize, Serialize};
+
+// Mock event handler used to validate the internal
+// navigation objects state.
+pub struct NavigationInspector {
+    last_event: Mutex<Option<NavEvent>>,
+    event_ct: Mutex<usize>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct EventMetadata {
+    prevent_default: bool,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct HistoryState {
+    name: String,
+}
+
+impl NavEventHandler for NavigationInspector {
+    fn handle_event(&self, event: NavEvent) -> HandlerResponse {
+        *self.last_event.lock().expect("Lock poisoned!") = Some(event);
+        *self.event_ct.lock().expect("Lock poisoned!") += 1;
+        HandlerResponse::Default
+    }
+}
+
+impl NavigationInspector {
+    pub fn new() -> Self {
+        Self {
+            last_event: None.into(),
+            event_ct: 0.into(),
+        }
+    }
+
+    pub fn last_event(&self) -> Option<NavEvent> {
+        self.last_event.lock().expect("Lock poisoned!").clone()
+    }
+
+    pub fn event_ct(&self) -> usize {
+        self.event_ct.lock().expect("Lock poisoned!").clone()
+    }
+}
+
+#[test]
+fn basic_internal_nav() {
+    let handler = Arc::new(NavigationInspector::new());
+    let mut ctx = NavCtx::new();
+    ctx.set_event_handler(handler.clone());
+
+    // sanity check
+    assert_eq!(handler.event_ct(), 0);
+    assert!(handler.last_event().is_none());
+
+    // simple push nav
+    let url_str = "https://www.website.com/live";
+    let url = Url::parse(url_str).expect("URL failed to parse");
+    ctx.navigate(url, NavOptions::default());
+
+    assert_eq!(handler.event_ct(), 1);
+    assert_eq!(
+        NavEvent {
+            info: None,
+            state: None,
+            event: NavEventType::Push,
+            same_document: false,
+            from: None,
+            to: NavHistoryEntry {
+                state: None,
+                id: 1,
+                url: url_str.to_string(),
+            }
+        },
+        handler.last_event().expect("Missing Event")
+    );
+}