[maps-ios] Document view annotation shadow padding workaround (#9767)

## Summary
- Add documentation to `ViewAnnotation` (UIKit) and `MapViewAnnotation`
(SwiftUI) explaining that shadows and other visual effects extending
beyond view bounds may cause premature annotation hiding

## Context
View annotations calculate visibility using the view's frame, which
doesn't account for layer effects like shadows. When a view with a
shadow moves off-screen, the annotation hides while the shadow is still
visible, causing a jarring visual "pop".

The SDK team decided not to address this on the SDK side, so this
documentation helps customers implement the workaround themselves.

cc @mapbox/maps-ios

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
GitOrigin-RevId: 07bcd5bb3784c7c8ffaa77c55d79a9631886f05b

Author: 2 people

Sources/MapboxMaps/Annotations/ViewAnnotation.swift

@@ -31,6 +31,13 @@ import MapboxCommon
 ///
 /// - Important: Don't set `UIView.isHidden` property to hide the annotation. Instead, use ``visible`` property.
 ///
+/// - Important: When using shadows, blur, or other visual effects that extend beyond the view's bounds
+///   (such as `CALayer.shadow*` properties), the annotation may disappear while the effect is still visible.
+///   This occurs because visibility is calculated using the view's frame, which doesn't include the shadow extent.
+///   To prevent this, wrap your content in a container view with padding that accounts for the effect.
+///   For shadows, use padding of approximately `shadowRadius * 2 + max(abs(shadowOffset.width), abs(shadowOffset.height))`.
+///   See `FrameViewAnnotationsExample` in the Examples app for a reference implementation.
+///
 /// When view content or layout is updated, use ``setNeedsUpdateSize()`` to update the the annotation size. It's safe to use it multiple times, only one update will be performed.
 ///
 /// ```swift

Sources/MapboxMaps/SwiftUI/Annotations/MapViewAnnotation.swift

@@ -19,6 +19,11 @@ import SwiftUI
 /// The view annotations are great for displaying unique interactive features. However, they may be suboptimal for large amounts of data and don't support clustering. For those cases use ``PointAnnotation`` or Runtime Styling API, for example, ``SymbolLayer`` with ``GeoJSONSource``.
 ///
 /// - Note: View Annotations appear above all content of MapView (e.g. layers, annotations, puck). If you need to display annotation between layers or below puck, use ``PointAnnotation``.
+///
+/// - Important: When using shadows, blur, or other visual effects that extend beyond the view's bounds,
+///   the annotation may disappear while the effect is still visible. This occurs because visibility is calculated
+///   using the view's frame, which doesn't include the shadow extent. To prevent this, wrap your content in a
+///   container view with padding that accounts for the effect. See ``ViewAnnotation`` documentation for details.
 
 public struct MapViewAnnotation {
     struct Actions {