Add BitMap component (#10110)

.gitignore

@@ -222,6 +222,12 @@ ModelManifest.xml
 # Rider
 .idea
 
+#kiro
+.kiro
+
+#cursor
+.cursor
+
 profile.arm.json
 
 # bit
@@ -243,6 +249,7 @@ _book
 /src/BlazorUI/Bit.BlazorUI.Extras/wwwroot/scripts/*.js
 /src/BlazorUI/Bit.BlazorUI.Extras/wwwroot/**/*.css.gz
 !/src/BlazorUI/Bit.BlazorUI.Extras/wwwroot/quilljs/*.css
+!/src/BlazorUI/Bit.BlazorUI.Extras/wwwroot/leaflet/*.css
 
 /src/BlazorUI/Bit.BlazorUI.Assets/**/*.css
 /src/BlazorUI/Bit.BlazorUI.Assets/wwwroot/scripts/*.js

src/BlazorUI/Bit.BlazorUI.Extras/Components/Map/BitMap.razor

@@ -0,0 +1,21 @@
+@namespace Bit.BlazorUI
+@inherits BitComponentBase
+@typeparam TMapProvider where TMapProvider : class, IBitMapProvider, new()
+
+<div @ref="RootElement"
+     @attributes="HtmlAttributes"
+     id="@_Id"
+     style="@StyleBuilder.Value"
+     class="@ClassBuilder.Value"
+     dir="@Dir?.ToString().ToLowerInvariant()">
+    <div id="@_canvasId"
+         @ref="_mapElement"
+         class="bit-map-canvas"
+         tabindex="0"
+         role="region"
+         aria-label="@(AriaLabel ?? "Map")"></div>
+    @if (ChildContent is not null)
+    {
+        <div class="bit-map-overlay">@ChildContent</div>
+    }
+</div>

src/BlazorUI/Bit.BlazorUI.Extras/Components/Map/BitMap.scss

@@ -0,0 +1,65 @@
+.bit-map {
+    width: 100%;
+    height: 100%;
+    box-sizing: border-box;
+    position: relative;
+    overflow: hidden;
+}
+
+.bit-map-canvas {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+}
+
+.bit-map-canvas:focus-visible {
+    outline: 2px solid Highlight;
+    outline: 2px solid -webkit-focus-ring-color;
+    outline-offset: -2px;
+}
+
+.bit-map-overlay {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 1;
+
+    > * {
+        pointer-events: auto;
+    }
+}
+
+// OpenLayers popup. Styles live here (instead of inline cssText in the TS provider)
+// so they aren't blocked under strict CSP configurations that disallow inline styles
+// and so consumers can theme them from their own stylesheets.
+.bit-map-ol-popup {
+    position: relative;
+    max-width: 280px;
+    padding: 10px 12px;
+    background: #fff;
+    border-radius: 6px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+    overflow-wrap: break-word;
+}
+
+.bit-map-ol-popup--hidden {
+    display: none;
+}
+
+.bit-map-ol-popup__close {
+    position: absolute;
+    top: 2px;
+    right: 6px;
+    padding: 2px 4px;
+    border: none;
+    background: transparent;
+    color: #666;
+    font-size: 16px;
+    line-height: 1;
+    cursor: pointer;
+}
+
+.bit-map-ol-popup__content {
+    margin-top: 4px;
+}

src/BlazorUI/Bit.BlazorUI.Extras/Components/Map/BitMapInteropErrorArgs.cs

@@ -0,0 +1,44 @@
+namespace Bit.BlazorUI;
+
+/// <summary>
+/// Source of a <see cref="BitMap{TMapProvider}.OnInteropError"/> event.
+/// </summary>
+public enum BitMapInteropErrorSource
+{
+    /// <summary>Loading the provider's external scripts failed.</summary>
+    ScriptLoad,
+
+    /// <summary>Loading the provider's external stylesheets failed.</summary>
+    StylesheetLoad,
+
+    /// <summary>The provider's <c>init</c> JS call failed.</summary>
+    Init,
+
+    /// <summary>The provider's <c>sync</c> JS call failed.</summary>
+    Sync,
+
+    /// <summary>The provider's <c>dispose</c> JS call failed.</summary>
+    Dispose,
+
+    /// <summary>An imperative call (add/remove/update) into the provider failed.</summary>
+    Imperative,
+
+    /// <summary>A consumer-supplied event handler threw while processing a JS-invoked callback.</summary>
+    Callback,
+}
+
+/// <summary>
+/// Payload for <see cref="BitMap{TMapProvider}.OnInteropError"/>. Carries the underlying
+/// exception and a tag indicating which interop call site produced it.
+/// </summary>
+public sealed class BitMapInteropErrorArgs
+{
+    /// <summary>Where the error originated.</summary>
+    public required BitMapInteropErrorSource Source { get; init; }
+
+    /// <summary>The exception that was caught.</summary>
+    public required Exception Exception { get; init; }
+
+    /// <summary>Optional context (e.g. method name, marker id) for diagnostics.</summary>
+    public string? Context { get; init; }
+}

src/BlazorUI/Bit.BlazorUI.Extras/Components/Map/BitMapJsRuntimeExtensions.cs

@@ -0,0 +1,148 @@
+namespace Bit.BlazorUI;
+
+/// <summary>
+/// Provider-agnostic JS runtime helpers for <see cref="BitMap{TMapProvider}"/>.
+/// All calls go through <c>BitBlazorUI.&lt;JsObjectName&gt;.&lt;method&gt;</c> so each
+/// provider exposes its own implementation under the same shape.
+/// </summary>
+internal static class BitMapJsRuntimeExtensions
+{
+    public static ValueTask BitMapInit<TProvider>(this IJSRuntime jsRuntime,
+                                                  string jsObjectName,
+                                                  string id,
+                                                  string canvasId,
+                                                  ElementReference element,
+                                                  DotNetObjectReference<BitMap<TProvider>>? dotnetObj,
+                                                  object options)
+        where TProvider : class, IBitMapProvider, new()
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.init", id, canvasId, element, dotnetObj, options);
+    }
+
+    public static ValueTask BitMapSync(this IJSRuntime jsRuntime, string jsObjectName, string id, object options)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.sync", id, options);
+    }
+
+    public static ValueTask BitMapDispose(this IJSRuntime jsRuntime, string jsObjectName, string id)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.dispose", id);
+    }
+
+    public static ValueTask BitMapInvalidateSize(this IJSRuntime jsRuntime, string jsObjectName, string id)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.invalidateSize", id);
+    }
+
+    public static ValueTask<System.Text.Json.JsonElement> BitMapGetView(this IJSRuntime jsRuntime, string jsObjectName, string id)
+    {
+        return jsRuntime.Invoke<System.Text.Json.JsonElement>($"BitBlazorUI.{jsObjectName}.getView", id);
+    }
+
+    public static ValueTask BitMapSetView(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                          double lat, double lng, double? zoom, bool animate)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.setView", id, lat, lng, zoom, animate);
+    }
+
+    public static ValueTask BitMapFlyTo(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                        double lat, double lng, double? zoom)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.flyTo", id, lat, lng, zoom);
+    }
+
+    public static ValueTask BitMapFitBounds(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                            double swLat, double swLng,
+                                            double neLat, double neLng,
+                                            int paddingPixels)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.fitBounds", id, swLat, swLng, neLat, neLng, paddingPixels);
+    }
+
+    public static ValueTask BitMapFitBoundsToMarkers(this IJSRuntime jsRuntime, string jsObjectName, string id, int paddingPixels)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.fitBoundsToMarkers", id, paddingPixels);
+    }
+
+    public static ValueTask BitMapAddMarker(this IJSRuntime jsRuntime, string jsObjectName, string id, string markerId, object marker)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addMarker", id, markerId, marker);
+    }
+
+    public static ValueTask BitMapRemoveMarker(this IJSRuntime jsRuntime, string jsObjectName, string id, string markerId)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.removeMarker", id, markerId);
+    }
+
+    public static ValueTask BitMapClearMarkers(this IJSRuntime jsRuntime, string jsObjectName, string id)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.clearMarkers", id);
+    }
+
+    public static ValueTask BitMapSyncMarkers(this IJSRuntime jsRuntime, string jsObjectName, string id, string[] markerIds, object[] markers)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.syncMarkers", id, markerIds, markers);
+    }
+
+    public static ValueTask BitMapSetMarkerPosition(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                                    string markerId, double lat, double lng)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.setMarkerPosition", id, markerId, lat, lng);
+    }
+
+    public static ValueTask BitMapOpenMarkerPopup(this IJSRuntime jsRuntime, string jsObjectName, string id, string markerId)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.openMarkerPopup", id, markerId);
+    }
+
+    public static ValueTask BitMapAddPolyline(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                              string layerId, object[] path, object? style)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addPolyline", id, layerId, path, style);
+    }
+
+    public static ValueTask BitMapAddPolygon(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                             string layerId, object[] ring, object? style)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addPolygon", id, layerId, ring, style);
+    }
+
+    public static ValueTask BitMapAddCircle(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                            string layerId, double lat, double lng, double radiusMeters, object? style)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addCircle", id, layerId, lat, lng, radiusMeters, style);
+    }
+
+    public static ValueTask BitMapAddRectangle(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                               string layerId, double swLat, double swLng,
+                                               double neLat, double neLng, object? style)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addRectangle", id, layerId, swLat, swLng, neLat, neLng, style);
+    }
+
+    public static ValueTask BitMapAddGeoJson(this IJSRuntime jsRuntime, string jsObjectName, string id,
+                                             string layerId, string geoJson, object? style)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addGeoJson", id, layerId, geoJson, style);
+    }
+
+    public static ValueTask BitMapRemoveLayer(this IJSRuntime jsRuntime, string jsObjectName, string id, string layerId)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.removeLayer", id, layerId);
+    }
+
+    public static ValueTask BitMapClearVectorLayers(this IJSRuntime jsRuntime, string jsObjectName, string id)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.clearVectorLayers", id);
+    }
+
+    public static ValueTask BitMapAddTileOverlay(this IJSRuntime jsRuntime, string jsObjectName, string id, object overlay)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.addTileOverlay", id, overlay);
+    }
+
+    public static ValueTask BitMapRemoveTileOverlay(this IJSRuntime jsRuntime, string jsObjectName, string id, string overlayId)
+    {
+        return jsRuntime.InvokeVoid($"BitBlazorUI.{jsObjectName}.removeTileOverlay", id, overlayId);
+    }
+}

src/BlazorUI/Bit.BlazorUI.Extras/Components/Map/BitMapLatLng.cs

@@ -0,0 +1,72 @@
+namespace Bit.BlazorUI;
+
+/// <summary>
+/// Geographic coordinate in WGS84 (EPSG:4326).
+/// </summary>
+public readonly record struct BitMapLatLng
+{
+    private readonly double _latitude;
+    private readonly double _longitude;
+
+    /// <summary>
+    /// Creates a new <see cref="BitMapLatLng"/> with the given coordinates.
+    /// </summary>
+    /// <param name="latitude">Latitude in degrees. Must be within [-90, 90].</param>
+    /// <param name="longitude">Longitude in degrees. Must be within [-180, 180].</param>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when either value is outside its valid range or NaN.</exception>
+    public BitMapLatLng(double latitude, double longitude)
+    {
+        _latitude = ValidateLatitude(latitude);
+        _longitude = ValidateLongitude(longitude);
+    }
+
+    /// <summary>
+    /// Latitude in degrees. Must be within [-90, 90].
+    /// </summary>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when the value is outside the valid range.</exception>
+    public double Latitude
+    {
+        get => _latitude;
+        init => _latitude = ValidateLatitude(value);
+    }
+
+    /// <summary>
+    /// Longitude in degrees. Must be within [-180, 180].
+    /// </summary>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when the value is outside the valid range.</exception>
+    public double Longitude
+    {
+        get => _longitude;
+        init => _longitude = ValidateLongitude(value);
+    }
+
+    /// <summary>Shorthand for <see cref="Latitude"/>.</summary>
+    public double Lat => Latitude;
+
+    /// <summary>Shorthand for <see cref="Longitude"/>.</summary>
+    public double Lng => Longitude;
+
+    private static double ValidateLatitude(double value)
+    {
+        if (double.IsNaN(value) || value < -90 || value > 90)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(Latitude),
+                value,
+                $"{nameof(BitMapLatLng)}.{nameof(Latitude)} must be a number between -90 and 90 (inclusive).");
+        }
+        return value;
+    }
+
+    private static double ValidateLongitude(double value)
+    {
+        if (double.IsNaN(value) || value < -180 || value > 180)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(Longitude),
+                value,
+                $"{nameof(BitMapLatLng)}.{nameof(Longitude)} must be a number between -180 and 180 (inclusive).");
+        }
+        return value;
+    }
+}