Feature Request: Provide Support for CircleOverlay #79
Description
Description
Expand API support to include Apple MapKit JS CircleOverlay.
Implementation Plan
Component
Adding Circle.tsx and CircleProps.tsx to src/components to wrap the Apple MapKit JS CircleOverlay object. Implementation and supported props will be very similar to the Polygon and Polyline overlays.
Corresponding to how a CircleOverlay is defined in Apple MapKit JS, required props will include
/**
* The coordinate of the circle overlay’s center.
* @see {@link https://developer.apple.com/documentation/mapkitjs/circleoverlay/coordinate}
*/
coordinate: Coordinate;
/**
* The radius of the circle overlay, in meters.
* @see {@link https://developer.apple.com/documentation/mapkitjs/circleoverlay/radius}
*/
radius: number;
Corresponding to OverlayOptions, optional Props will include
/**
* A Boolean value that determines whether the circle is visible.
* @see {@link https://developer.apple.com/documentation/mapkitjs/overlay/visible}
*/
visible?: boolean;
/**
* A Boolean value that determines whether the circle responds to user interaction.
* @see {@link https://developer.apple.com/documentation/mapkitjs/overlay/enabled}
*/
enabled?: boolean;
/**
* A Boolean value that determines whether the map displays the circle in a selected state.
* @see {@link https://developer.apple.com/documentation/mapkitjs/overlay/selected}
*/
selected?: boolean;
/**
* Event fired when the circle is selected.
*/
onSelect?: () => void;
/**
* Event fired when the circle is deselected.
*/
onDeselect?: () => void;
/**
* The stroke color of the line. Accepts any valid CSS color value.
* The default is `rgb(0, 122, 255)`.
* Set this to `null` to remove the line stroke.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/strokeColor}
*/
strokeColor?: string | null;
/**
* The opacity of the stroke as a number between 0 and 1.
* The default value is `1`.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/strokeOpacity}
*/
strokeOpacity?: number;
/**
* The line width of the stroke for overlays, in CSS pixels.
* The default value is `1`.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/lineWidth}
*/
lineWidth?: number;
/**
* An array defining the line’s dash pattern, where numbers represent line and gap lengths in CSS pixels.
* For example, `[10, 5]` means draw for 10 pixels and leave a 5‑pixel gap repeatedly.
* Set to `[]` for solid lines (default).
* MapKit JS duplicates the array if it has an odd number of elements.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/lineDash}
*/
lineDash?: number[];
/**
* The number of CSS pixels to offset the start of the dash pattern.
* Has no effect when `lineDash` is set to draw solid lines.
* The default value is `0`.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/lineDashOffset}
*/
lineDashOffset?: number;
/**
* The fill color used for the shape. Accepts any valid CSS color value.
* The default is `rgb(0, 122, 255)`.
* Set this to `null` for no fill.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/fillColor}
*/
fillColor?: string | null;
/**
* The opacity to apply to the fill, as a number between 0 and 1.
* The default value is `0.1`.
* @see {@link https://developer.apple.com/documentation/mapkitjs/style/fillOpacity}
*/
fillOpacity?: number;
Note: I excluded lineCap, lineJoin, and fillRule since Apple MapKit ignores these properties.
Story
Adding a default story in Circle.stories.tsx to src/stories to demonstrate the circle overlay feature
Use Cases
CMU Maps Visualizer
The circle overlays are heavily used to visualize the outside graph for developers.
CMU Maps
We will use the circle overlay to display a smaller user-location circle on the map. The default user-location circle from Apple Map (see screenshot below) is too large and not ideal for room level navigation provided in CMU Maps.
To avoid misleading users about location accuracy, we will keep the larger circle from Apple Maps and overlay a smaller circle at the center to represent the user’s position, similar to how it is displayed in Google Maps.
This is necessary because when the user zoom in on a floor, the large blue circle can cover the entire view, making it hard for the user to see their exact position and the indoor navigation feature less effective.