38 lines
2.3 KiB
Markdown
38 lines
2.3 KiB
Markdown
---
|
|
name: blazor-hybrid-bridge
|
|
description: Standards for cross-platform compatibility (Web & MAUI Hybrid)
|
|
---
|
|
# Cross-Platform Integration
|
|
|
|
- **Abstraction Layer:**
|
|
- Define all platform-specific logic in `NexusReader.Application/Abstractions/Services`.
|
|
- Use `IPlatformService` for device hardware (Haptics, Orientation).
|
|
- Use `INativeStorageService` for persistent key-value storage.
|
|
|
|
- **Implementation Strategy:**
|
|
- **MAUI**: Implement in `NexusReader.Infrastructure.Mobile` using `Microsoft.Maui.*` APIs.
|
|
- **Web**: Implement in `NexusReader.Web.Client` using `IJSRuntime` to access Browser APIs (e.g., `navigator.vibrate`, `localStorage`).
|
|
|
|
- **UI Compatibility:**
|
|
- **Notch Support**: Use `env(safe-area-inset-top)` and other safe-area variables in CSS to prevent content from being hidden by hardware notches or home indicators.
|
|
- **Touch Optimization**:
|
|
- Use `user-select: none` for non-text interactive elements.
|
|
- Ensure touch targets are at least `44x44px`.
|
|
- Handle `active` states for immediate feedback on mobile.
|
|
|
|
- **Platform Detection:**
|
|
- Use `IPlatformService.GetDeviceContext()` to determine `DeviceType` (Phone, Tablet, Desktop).
|
|
- Adapt UI layout dynamically based on the context (e.g., sidebars on Tablet/Desktop, bottom navigation on Phone).
|
|
|
|
- **Real-time & Events (SignalR / UI):**
|
|
- **Debouncing**: Implement trailing-edge debouncing using `CancellationTokenSource` and `Task.Delay` for high-frequency UI events (like scrolling). Do not just drop events inside a time window, as the final state might be lost.
|
|
- **Dependency Isolation**: Blazor WebAssembly (`Web.Client`) cannot reference projects that require `Microsoft.AspNetCore.App` (like SignalR Hubs). Keep SignalR abstractions in `UI.Shared` and the Hub implementation strictly on the server (`Infrastructure` or `Web.New`).
|
|
|
|
- **Dependency Injection:**
|
|
- Register implementations in `MauiProgram.cs` for mobile and `Program.cs` for web.
|
|
- Components in `NexusReader.UI.Shared` must only depend on the interfaces.
|
|
|
|
- **JS Interop Standards:**
|
|
- Keep JS Interop calls isolated within service implementations.
|
|
- Use `IJSObjectReference` for module-based scripts to avoid global namespace pollution.
|
|
- Always provide a fallback or graceful failure for browsers that don't support specific APIs. |