/**
 * Imperative handle for a `<Map>`.
 *
 * @description
 * Exposed through the dedicated `controlRef` prop, **not** through `ref`. The
 * component's `ref` has always resolved to the container `HTMLDivElement`, and
 * consumers of 4.x depend on that; swapping it for an imperative object would
 * break them silently. A second ref keeps both contracts intact.
 *
 * @example
 * ```tsx
 * const control = useRef<MapControl>(null);
 * <Map controlRef={control} markers={markers} onPopupAction={handleAction} />
 * control.current?.openPopup('unit-14');
 * ```
 */
export interface MapControl {
  /** Opens the popup of the marker with this id. No-op when it has none. */
  openPopup(featureId: string): void;
  /** Closes whatever popup is open. */
  closePopup(): void;
  /** Id of the marker whose popup is open, or `null`. */
  getOpenPopupId(): string | null;
}