Add TypeScript-based JS interop infrastructure

Introduces comprehensive TypeScript-based JavaScript interop for Blazouter, including five specialized services: NavigationInterop, DocumentInterop, StorageInterop, ViewportInterop, and ClipboardInterop. Adds TypeScript source project, compiled JS modules with type definitions, and global namespace exposure for C# interop. Updates documentation and sample app to demonstrate new APIs, and enhances RouterNavigationService with true browser navigation. All interop services are optional, type-safe, and backward compatible.

Author: Taiizor

ATTRIBUTE_ROUTING.md

@@ -247,8 +247,9 @@ Mix attribute-based routes with programmatic routes:
 
 ```csharp
 // In App.razor.cs or Routes.razor.cs
-using Blazouter.Extensions;
+using Blazouter.Enums;
 using Blazouter.Models;
+using Blazouter.Extensions;
 
 public partial class App
 {
@@ -277,8 +278,8 @@ Create routes entirely from attributes:
 
 ```csharp
 // In App.razor.cs or Routes.razor.cs
-using Blazouter.Extensions;
 using Blazouter.Models;
+using Blazouter.Extensions;
 
 public partial class App
 {

CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.13] - 2025-11-26
+
+### Added
+- **TypeScript-Based JavaScript Interop Infrastructure**: Comprehensive type-safe browser API access
+  - TypeScript compilation pipeline with `.d.ts` generation for IntelliSense support
+  - Global namespace exposure pattern for C# interop: `window.blazouterNavigation`, `window.blazouterDocument`, `window.blazouterStorage`, `window.blazouterViewport`, `window.blazouterClipboard`
+  - Separate `Blazouter.TypeScript` project at `src/Blazouter.TypeScript/` for TypeScript source files
+  - NPM package with TypeScript compiler configuration (tsconfig.json)
+  - Compiled JavaScript modules with source maps and type definitions in `src/Blazouter/wwwroot/js/`
+  
+- **NavigationInterop Service**: Browser history and navigation API wrapper
+  - History API: `GoBackAsync()`, `GoForwardAsync()`, `GoAsync()`, `GetHistoryLengthAsync()`, `GetHistoryStateAsync()`
+  - URL helpers: `GetCurrentUrlAsync()`, `GetPathnameAsync()`
+  - Hash navigation: `GetHashAsync()`, `SetHashAsync()`
+  - Query parameters: `GetQueryStringAsync()`, `GetQueryParamAsync()`, `GetAllQueryParamsAsync()`
+  - Page control: `ReloadAsync()`
+  - Integration with `RouterNavigationService` providing `GoBackAsync()`, `GoForwardAsync()`, `CanGoBackAsync()`
+  
+- **DocumentInterop Service**: Document manipulation and SEO support
+  - Title management: `SetTitleAsync()`, `GetTitleAsync()`
+  - Meta tags: `SetMetaTagAsync()`, `GetMetaTagAsync()`, `RemoveMetaTagAsync()`
+  - Open Graph support: `SetOpenGraphTagAsync()`
+  - Canonical URLs: `SetCanonicalUrlAsync()`, `GetCanonicalUrlAsync()`
+  - Scroll control: `ScrollToTopAsync()`, `ScrollToBottomAsync()`, `ScrollToElementAsync()`, `GetScrollPositionAsync()`, `SetScrollPositionAsync()`
+  - Element management: `FocusElementAsync()`, `IsElementVisibleAsync()`
+  - CSS classes: `AddClassAsync()`, `RemoveClassAsync()`, `ToggleClassAsync()`
+  - Document state: `GetReadyStateAsync()`, `IsDocumentReadyAsync()`
+  
+- **StorageInterop Service**: Type-safe localStorage and sessionStorage access
+  - LocalStorage operations: `SetLocalStorageAsync<T>()`, `GetLocalStorageAsync<T>()`, `RemoveLocalStorageAsync()`, `ClearLocalStorageAsync()`, `GetLocalStorageKeysAsync()`, `HasLocalStorageAsync()`
+  - SessionStorage operations: `SetSessionStorageAsync<T>()`, `GetSessionStorageAsync<T>()`, `RemoveSessionStorageAsync()`, `ClearSessionStorageAsync()`, `GetSessionStorageKeysAsync()`, `HasSessionStorageAsync()`
+  - Generic type support with automatic JSON serialization/deserialization
+  
+- **ViewportInterop Service**: Viewport, screen, and device detection
+  - Viewport dimensions: `GetViewportSizeAsync()` returning `Size` record with width and height
+  - Screen information: `GetScreenSizeAsync()`
+  - Device pixel ratio: `GetPixelRatioAsync()`
+  - Orientation: `IsPortraitAsync()`, `IsLandscapeAsync()`, `GetOrientationAsync()`
+  - Device type detection: `IsMobileAsync()`, `IsTabletAsync()`, `IsDesktopAsync()`, `GetDeviceTypeAsync()`
+  - Fullscreen API: `IsFullscreenAsync()`, `RequestFullscreenAsync()`, `ExitFullscreenAsync()`
+  
+- **ClipboardInterop Service**: Clipboard operations with permission support
+  - Text operations: `CopyTextAsync()`, `ReadTextAsync()`
+  - Feature detection: `IsClipboardSupportedAsync()`
+  - Permission checks: `HasClipboardReadPermissionAsync()`, `HasClipboardWritePermissionAsync()`
+  - Fallback support for older browsers in `copyText()` implementation
+  
+- **Service Organization**: All interop services in `Blazouter.Interops` namespace
+  - Located at `src/Blazouter/Interops/` folder
+  - `AddBlazouterInterop()` extension method for DI registration (optional, non-breaking)
+  - Services injected as nullable dependencies for backward compatibility
+  
+- **Documentation**: Comprehensive guides and API references
+  - `TYPESCRIPT_INTEGRATION.md`: Complete documentation with usage examples, API references, migration guide, and hosting-specific instructions for WebAssembly, Hybrid, and Server models
+  - `FEATURES.md`: Feature #13 with detailed descriptions of all 5 interop services and their capabilities
+  - `README.md`: Installation instructions with JavaScript module import requirement, updated Project Structure
+  - `src/Blazouter/README.md` (NuGet): Concise TypeScript Integration section for package consumers
+  - All documentation includes required module import: `<script type="module" src="_content/Blazouter/js/index.js"></script>`
+
+### Changed
+- Project structure updated to include:
+  - `src/Blazouter.TypeScript/` - Separate project for TypeScript source files
+  - `src/Blazouter/Interops/` - All interop service implementations
+  - `src/Blazouter/wwwroot/js/` - Compiled JavaScript modules (.js, .d.ts, .js.map files)
+- `RouterNavigationService` enhanced with navigation interop integration
+- Service registration extended via `AddBlazouterInterop()` method
+
+### Technical Details
+- TypeScript source files: navigation.ts, document.ts, storage.ts, viewport.ts, clipboard.ts, index.ts
+- ES module format with explicit .js extensions for browser compatibility
+- TypeScript compilation generates declaration files for IntelliSense
+- JavaScript modules exposed via window object for C# JSRuntime interop
+- Optional module import - services gracefully handle missing JavaScript modules
+- Backward compatible - existing applications continue working without changes
+
 ## [1.0.12] - 2025-11-25
 
 ### Added
@@ -197,6 +272,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - FEATURES.md detailing all capabilities
 - Sample application demonstrating key features
 
+[1.0.13]: https://github.com/Taiizor/Blazouter/compare/v1.0.12...v1.0.13
 [1.0.12]: https://github.com/Taiizor/Blazouter/compare/v1.0.11...v1.0.12
 [1.0.11]: https://github.com/Taiizor/Blazouter/compare/v1.0.10...v1.0.11
 [1.0.10]: https://github.com/Taiizor/Blazouter/compare/v1.0.9...v1.0.10

FEATURES.md

@@ -147,6 +147,56 @@ Blazouter is a comprehensive routing library for Blazor applications, available
 - Sample application demonstrates all features in Navigation.razor and UserList.razor
 - 15 `Add()` method overloads for all common types (string, int, long, decimal, double, bool, DateTime, Guid, enum, and nullable variants)
 
+### ✅ 13. TypeScript Integration for JavaScript Interop
+- Tested and verified working
+- Type-safe JavaScript modules with `.d.ts` definition files for IntelliSense
+- Comprehensive browser API integration with 5 specialized interop services
+- Automatic TypeScript compilation to JavaScript with source maps
+- Global namespace exposure pattern (`window.blazouterNavigation`, `window.blazouterDocument`, `window.blazouterStorage`, `window.blazouterViewport`, `window.blazouterClipboard`)
+- Optional service registration via `AddBlazouterInterop()`
+- **`NavigationInterop`** service for History API access
+  - Navigate back/forward/go in browser history
+  - URL and path information (getCurrentUrl, getPathname)
+  - Hash navigation (getHash, setHash)
+  - Query parameter helpers (getQueryString, getQueryParam, getAllQueryParams)
+  - Page reload functionality
+  - Check navigation availability
+  - Manage history state (push and replace entries)
+- **`DocumentInterop`** service for document manipulation
+  - Dynamic title updates
+  - Meta tag management (description, keywords, Open Graph tags)
+  - Canonical URL support for SEO
+  - Scroll position tracking (getScrollPosition, setScrollPosition)
+  - Scroll to top/element with smooth scrolling
+  - Element visibility detection (isElementVisible)
+  - CSS class manipulation (addClass, removeClass, toggleClass)
+  - Document ready state checks
+  - Element focus management
+- **`StorageInterop`** service for browser storage
+  - Complete localStorage operations (set, get, remove, clear, keys, has)
+  - Complete sessionStorage operations (set, get, remove, clear, keys, has)
+  - Generic type support with JSON serialization
+  - Type-safe storage access for complex objects
+- **`ViewportInterop`** service for viewport and device info
+  - Viewport dimensions (getViewportSize, width, height)
+  - Screen information (getScreenSize)
+  - Device pixel ratio detection
+  - Orientation detection (isPortrait, isLandscape, getOrientation)
+  - Device type detection (isMobile, isTablet, isDesktop, getDeviceType)
+  - Fullscreen API (isFullscreen, requestFullscreen, exitFullscreen)
+- **`ClipboardInterop`** service for clipboard operations
+  - Copy text to clipboard with fallback for older browsers
+  - Read text from clipboard
+  - Feature detection (isClipboardSupported)
+  - Permission checks (hasClipboardReadPermission, hasClipboardWritePermission)
+- Integration with `RouterNavigationService`
+  - `GoBackAsync()` - True browser back navigation
+  - `GoForwardAsync()` - Browser forward navigation
+  - `CanGoBackAsync()` - Check if back navigation is available
+- Requires JavaScript module import: `<script type="module" src="_content/Blazouter/js/index.js"></script>`
+- Full documentation in [TYPESCRIPT_INTEGRATION.md](https://github.com/Taiizor/Blazouter/blob/develop/TYPESCRIPT_INTEGRATION.md)
+- Comprehensive demo page in WebAssembly sample at `/typescript-demo` showcasing all 5 interop services
+
 ## Components
 
 ### Router
@@ -197,6 +247,26 @@ Nested route renderer that:
 - Query parameter handling and URL building
 - Programmatic navigation API with NavigateTo(path)
 - Wrapper around NavigationManager for enhanced functionality
+- Async methods for browser navigation: GoBackAsync(), GoForwardAsync(), CanGoBackAsync()
+
+### NavigationInterop (Optional)
+- Registered as scoped service via AddBlazouterInterop()
+- Type-safe access to browser History API
+- Navigate back and forward in history
+- Check history length and navigation availability
+- Manage history state (push, replace, get)
+- Requires JavaScript module import for functionality
+- Used by RouterNavigationService async navigation methods
+
+### DocumentInterop (Optional)
+- Registered as scoped service via AddBlazouterInterop()
+- Type-safe document and DOM manipulation
+- Dynamic page title updates
+- Meta tag management (description, keywords, Open Graph)
+- Canonical URL support for SEO
+- Scroll management (scroll to top, scroll to element)
+- Element focus management
+- Requires JavaScript module import for functionality
 
 ### RouteAttributeDiscoveryService
 - Supports all 8 route attributes

README.md

@@ -760,6 +760,82 @@ builder.Services.AddBlazouterErrorHandler<CustomRouterErrorHandler>();
 - `NavigationFailed` - Navigation operation failed
 - `ComponentLoadFailed` - Component failed to load
 
+## 🔧 TypeScript Integration
+
+Blazouter includes TypeScript-based JavaScript interop for enhanced browser integration with full type safety.
+
+### Features
+
+- **SEO Support**: Set meta tags, Open Graph tags, and canonical URLs
+- **Type Safety**: Full TypeScript definitions with `.d.ts` files for IntelliSense
+- **Browser Navigation**: True browser back/forward navigation using the History API
+- **Document Manipulation**: Dynamic title updates, meta tags, scrolling, and focus management
+
+### Installation
+
+Enable JavaScript interop by registering the services:
+
+```csharp
+builder.Services.AddBlazouter();
+builder.Services.AddBlazouterInterop();  // Enable TypeScript interop
+```
+
+Add the JavaScript module import to your `index.html`:
+
+```html
+<!-- In wwwroot/index.html, add this in the <head> section -->
+<script type="module" src="_content/Blazouter/js/index.js"></script>
+```
+
+### Browser Navigation Example
+
+```csharp
+@inject RouterNavigationService NavService
+
+<button @onclick="GoBack">← Back</button>
+<button @onclick="GoForward">Forward →</button>
+
+@code {
+    private async Task GoBack()
+    {
+        await NavService.GoBackAsync();  // Uses browser History API
+    }
+
+    private async Task GoForward()
+    {
+        await NavService.GoForwardAsync();
+    }
+}
+```
+
+### Document Manipulation Example
+
+```csharp
+@inject DocumentInterop DocumentInterop
+
+@code {
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            // Update page title
+            await DocumentInterop.SetTitleAsync("Home - My App");
+            
+            // Set meta tags for SEO
+            await DocumentInterop.SetMetaTagAsync("description", "Welcome to my app");
+            
+            // Set Open Graph tags for social sharing
+            await DocumentInterop.SetOpenGraphTagAsync("og:title", "My App");
+            
+            // Scroll to top on navigation
+            await DocumentInterop.ScrollToTopAsync();
+        }
+    }
+}
+```
+
+**[📚 Full TypeScript Integration Documentation →](TYPESCRIPT_INTEGRATION.md)**
+
 ## 🏗️ Project Structure
 
 ```
@@ -774,11 +850,17 @@ Blazouter/
 │   │   ├── Guards/                # Route guard implementations (AuthGuard)
 │   │   ├── Handlers/              # Error handler implementations (DefaultRouterErrorHandler)
 │   │   ├── Interfaces/            # Interface definitions (IRouteGuard, IRouteMiddleware, IRouteMatcherService, IRouterErrorHandler)
+│   │   ├── Interops/              # JavaScript interop services (NavigationInterop, DocumentInterop, StorageInterop, ViewportInterop, ClipboardInterop)
 │   │   ├── Models/                # Route models (RouteConfig, RouteMatch, RouterErrorContext, etc.)
 │   │   ├── Resources/             # Embedded resources
-│   │   ├── Services/              # Routing services (RouterStateService, RouteMatcherService, RouterNavigationService, etc.)
+│   │   ├── Services/              # Routing services (RouterStateService, RouteMatcherService, RouterNavigationService)
 │   │   ├── Utilities/             # Query string builder and helper utilities
 │   │   └── wwwroot/               # CSS and assets (blazouter.css, blazouter.min.css)
+│   │       └── js/                # Compiled JavaScript modules with TypeScript definitions (.js, .d.ts, .js.map)
+│   ├── Blazouter.TypeScript/      # TypeScript source files for JavaScript interop
+│   │   ├── TypeScript/            # TypeScript source files (navigation.ts, document.ts, storage.ts, viewport.ts, clipboard.ts, index.ts)
+│   │   ├── package.json           # NPM dependencies for TypeScript compilation
+│   │   └── tsconfig.json          # TypeScript compiler configuration
 │   ├── Blazouter.Server/          # Server-specific extensions
 │   │   ├── Extensions/            # Server integration (AddBlazouterSupport)
 │   │   ├── Pages/                 # Server pages
@@ -861,6 +943,7 @@ This project is licensed under the MIT License.
 - [Documentation](https://github.com/Taiizor/Blazouter/blob/develop/FEATURES.md)
 - [Contributing Guide](https://github.com/Taiizor/Blazouter/blob/develop/CONTRIBUTING.md)
 - [Sample Applications](https://github.com/Taiizor/Blazouter/tree/develop/samples)
+- [TypeScript Integration](https://github.com/Taiizor/Blazouter/blob/develop/TYPESCRIPT_INTEGRATION.md)
 
 ## 🙏 Acknowledgments
 
@@ -872,7 +955,7 @@ Inspired by React Router and built to bring similar capabilities to the Blazor e
 - [ ] Performance optimizations
 - [ ] Advanced caching strategies
 - [x] Query string helpers and utilities
-- [ ] Better TypeScript integration for JS interop
+- [x] Better TypeScript integration for JS interop
 
 ## ⭐ Show Your Support