Permalink service updates added event for perma value detection and update link.

Author: majorimi

.github/docs/PermaLink.md

@@ -32,9 +32,15 @@ For more details see Usage section.
 ### Functions
 - **`WatchPermaLinks()`**: **`void WatchPermaLinks()`** <br />
 Starts a navigation watcher which will check for Permalinks in the URLs.
+- **`ChangePermalink()`**: **`void ChangePermalink(string? newPermalink, bool doNotNavigate)`** <br />
+Modify the current URL with given new peralink value and trigger navigation or just update browser History.
 - **`Dispose()`: `@implements IDisposable` interface** <br />
 Component implements `IDisposable` interface Blazor framework will call it when parent removed from render tree.
 
+### Events
+- **`PermalinkDetected`: `event EventHandler<PermalinkDetectedEventArgs>** <br />
+Event handler for parmalinks detected on navigation.
+
 ## `PermaLinkElement` component
 
 ### Properties
@@ -68,9 +74,17 @@ Callback function called when Permalink icon clicked and **`PermaLinkIconActions
 ## PermaLinkBlazorServerInitializer
 Available from v1.4.0 It is convenient wrapper component to initialize navigation watcher in your Blazor Server App `MainLayout.razor` page. **Only one Initializer component allowed per Application.**
 
+### Properties
+- **`SmootScroll`: `bool { get; set; }` (default: false)** <br />
+Scroll should be jump or smoothly scroll. **Note: smooth scroll on element level might not supported by all browsers.**
+
 ## PermalinkBlazorWasmInitializer
 Available from v1.4.0 It is convenient wrapper component to initialize navigation watcher in your Blazor WebAssembly App `MainLayout.razor` page. **Only one Initializer component allowed per Application.**
 
+### Properties
+- **`SmootScroll`: `bool { get; set; }` (default: false)** <br />
+Scroll should be jump or smoothly scroll. **Note: smooth scroll on element level might not supported by all browsers.**
+
 # Configuration
 
 ## Installation
@@ -141,7 +155,7 @@ Also instance should be disposed.
 ```
 @*Permalink initialize*@
 @using Majorsoft.Blazor.Components.PermaLink
-<PermalinkBlazorWasmInitializer />
+<PermalinkBlazorWasmInitializer  SmoothScroll="false" />
 ```
 
 #### Server hosted projects
@@ -208,7 +222,7 @@ It has to be instantiated manually by using the following code. Also instance sh
 ```
 @*Permalink initialize*@
 @using Majorsoft.Blazor.Components.PermaLink
-<PermaLinkBlazorServerInitializer />
+<PermaLinkBlazorServerInitializer SmoothScroll="false" />
 ```
 
 #### Creating permalink (#) navigation points inside a Blazor page

src/Majorsoft.Blazor.Components.PermaLink/IPermaLinkWatcherService.cs

@@ -8,6 +8,24 @@ namespace Majorsoft.Blazor.Components.PermaLink
 	/// </summary>
 	public interface IPermaLinkWatcherService : IDisposable
 	{
+		/// <summary>
+		/// Should scroll smoothly to the found permalink element or jump.
+		/// Note: smooth scroll on element level might not supported by all Browsers.
+		/// </summary>
+		bool SmoothScroll { get; set; }
+
+		/// <summary>
+		/// Event handler for parmalinks detected on navigation.
+		/// </summary>
+		public event EventHandler<PermalinkDetectedEventArgs> PermalinkDetected;
+
+		/// <summary>
+		/// Modify the current URL with given new peralink value and trigger navigation or just update browser History.
+		/// </summary>
+		/// <param name="newPermalink">New peramlink value, NULL will remove permalink part from URL</param>
+		/// <param name="doNotNavigate">False, will trigger a navigation. When true, just add new URL to the History</param>
+		void ChangePermalink(string? newPermalink, bool doNotNavigate);
+
 		/// <summary>
 		/// Starts a navigation watcher which will check for Permalinks in the URLs.
 		/// </summary>

src/Majorsoft.Blazor.Components.PermaLink/Majorsoft.Blazor.Components.PermaLink.xml

@@ -31,6 +31,16 @@
         }
     }
 
+    /// <summary>
+    /// Gets or sets if peramlink should be scrolled smoothly into view or not.
+    /// Note: smooth scroll on element level might not supported by all Browsers.
+    /// </summary>
+    [Parameter] public bool SmoothScroll
+    {
+        get => _permalinkWatcher.SmoothScroll;
+        set { _permalinkWatcher.SmoothScroll = value; }
+    }
+
     public async ValueTask DisposeAsync()
     {
         if (_scrollHandler is not null)

src/Majorsoft.Blazor.Components.PermaLink/PermaLinkBlazorServerInitializer.razor

@@ -1,4 +1,5 @@
-using System.Text.RegularExpressions;
+using System;
+using System.Text.RegularExpressions;
 
 using Majorsoft.Blazor.Components.Common.JsInterop.Scroll;
 
@@ -19,11 +20,17 @@ public class PermaLinkWatcherService : IPermaLinkWatcherService
 		private readonly NavigationManager _navigationManager;
 		private readonly ILogger<IPermaLinkWatcherService> _logger;
 
-		public PermaLinkWatcherService(IScrollHandler scrollHandler, NavigationManager navigationManager, ILogger<IPermaLinkWatcherService> logger)
+		public event EventHandler<PermalinkDetectedEventArgs> PermalinkDetected;
+
+		public bool SmoothScroll { get; set; }
+
+		public PermaLinkWatcherService(IScrollHandler scrollHandler, NavigationManager navigationManager, ILogger<IPermaLinkWatcherService> logger, bool smoothScroll = false)
 		{
 			_scrollHandler = scrollHandler;
 			_navigationManager = navigationManager;
 			_logger = logger;
+
+			SmoothScroll = smoothScroll;
 		}
 
 		public void WatchPermaLinks()
@@ -39,14 +46,67 @@ public void WatchPermaLinks()
 		private void HandleLocationChanged(object sender, LocationChangedEventArgs e)
 		{
 			_logger.LogDebug($"{nameof(PermaLinkWatcherService)} - {nameof(HandleLocationChanged)}: navigation happened new URL: {e.Location}");
-			var match = _poundRegex.Match(e.Location);
+			var perma = DetectPermalink(e.Location);
 
-			if(match.Success && match.Groups.Count == 2)
+			if(!string.IsNullOrWhiteSpace(perma))
 			{
-				var perma = match.Groups[1].Value;
 				_logger.LogDebug($"{nameof(PermaLinkWatcherService)} - {nameof(HandleLocationChanged)}: PermaLink found: {perma}");
-				_scrollHandler.ScrollToElementByNameAsync(perma);
+
+				if(PermalinkDetected is not null)
+				{
+					PermalinkDetected.Invoke(this, new PermalinkDetectedEventArgs(e, perma));
+				}	
+
+				_scrollHandler.ScrollToElementByNameAsync(perma, SmoothScroll);
+			}
+		}
+
+		public void ChangePermalink(string? newPermalink, bool doNotNavigate)
+		{
+			var perma = DetectPermalink(_navigationManager.Uri);
+			if (!string.IsNullOrWhiteSpace(perma))
+			{
+				if (newPermalink?.ToLower() == perma?.ToLower()) //same
+				{
+					return;
+				}
+
+				var newUri = _navigationManager.Uri.Replace($"#{perma}", "");
+				if (string.IsNullOrWhiteSpace(newPermalink)) //remove
+				{
+					_navigationManager.NavigateTo(newUri);
+					return;
+				}
+
+				SetBrowserUrl($"{newUri}#{newPermalink}", doNotNavigate);
+			}
+			else
+			{
+				SetBrowserUrl($"{_navigationManager.Uri}#{newPermalink}", doNotNavigate);
+			}
+		}
+
+		private void SetBrowserUrl(string uri, bool doNotNavigate)
+		{
+			if(doNotNavigate)
+			{
+				//TODO: history.pushState(null, '', url);
+				return;
+			}
+
+			_navigationManager.NavigateTo(uri, false);
+		}
+
+		private string DetectPermalink(string uri)
+		{
+			var match = _poundRegex.Match(uri);
+			if (match.Success && match.Groups.Count == 2)
+			{
+				var perma = match.Groups[1].Value;
+				return perma;
 			}
+
+			return null;
 		}
 
 		public void Dispose()

src/Majorsoft.Blazor.Components.PermaLink/PermaLinkWatcherService.cs

@@ -17,6 +17,17 @@
         _permalinkWatcher.WatchPermaLinks();
     }
 
+    /// <summary>
+    /// Gets or sets if peramlink should be scrolled smoothly into view or not.
+    /// Note: smooth scroll on element level might not supported by all Browsers.
+    /// </summary>
+    [Parameter]
+    public bool SmoothScroll
+    {
+        get => _permalinkWatcher.SmoothScroll;
+        set { _permalinkWatcher.SmoothScroll = value; }
+    }
+
     public void Dispose()
     {
         _permalinkWatcher?.Dispose();

src/Majorsoft.Blazor.Components.PermaLink/PermalinkBlazorWasmInitializer.razor

@@ -0,0 +1,33 @@
+using System;
+
+using Microsoft.AspNetCore.Components.Routing;
+
+namespace Majorsoft.Blazor.Components.PermaLink
+{
+	/// <summary>
+	/// Event arguments for <see cref="PermaLinkWatcherService"/> PermalinkDetected event.
+	/// </summary>
+	public class PermalinkDetectedEventArgs : EventArgs
+	{
+		/// <summary>
+		/// System.EventArgs for Microsoft.AspNetCore.Components.NavigationManager.LocationChanged.
+		/// </summary>
+		public LocationChangedEventArgs LocationChangedEventArgs { get; }
+
+		/// <summary>
+		/// Detected permalink value.
+		/// </summary>
+		public string Permalink { get; } = "";
+
+		/// <summary>
+		/// Default constructor
+		/// </summary>
+		/// <param name="locationChangedEventArgs">NavigationManager event</param>
+		/// <param name="permalink">Detected permalink value</param>
+		public PermalinkDetectedEventArgs(LocationChangedEventArgs locationChangedEventArgs, string permalink)
+		{
+			LocationChangedEventArgs = locationChangedEventArgs;
+			Permalink = permalink;
+		}
+	}
+}

src/Majorsoft.Blazor.Components.PermaLink/PermalinkDetectedEventArgs.cs

@@ -49,6 +49,7 @@ textarea {
 
 <div class="container-fluid p-3 mb-3 border rounded">
 	<h3>Internal page Permalink examles:</h3>
+	Smooth scroll: <input type="checkbox" @bind="_permalinkWatcher.SmoothScroll"/>
 	<ul>
 		<li><NavLink href="permalink">No permalink</NavLink></li>
 		<li><NavLink href="permalink#does-not_exists">Non existing permalink</NavLink></li>
@@ -148,7 +149,9 @@ textarea {
 	</div>
 </div>
 
-@code{
+@inject IPermaLinkWatcherService _permalinkWatcher
+
+@code {
 	private ShowPermaLinkIcon _showIcon = ShowPermaLinkIcon.OnHover;
 	private PermaLinkIconPosition _iconPosition = PermaLinkIconPosition.Right;
 	private PermaLinkStyle _iconStyle;