Introduce Interactions API

[pjleonard37]

What does this pull request do?

This PR introduces the experimental Interactions API introduced on iOS and Android in 11.8.0-beta.1. Specifically it:

• Introduces the experimental MapboxMap.addInteractions method, which allows you to add interactions to the map.
  • Introduces TapInteraction and LongTapInteraction, which allow you to add tap and longTap interactions to the map.
  • Introduces FeaturesetDescriptor -- and convenience descriptors for StandardBuildings, StandardPOIs, and StandardPlaceLabels -- which allow you to describe the Featuresets you want Interactions to target.
• Introduces new methods for queryRenderedFeatures, querySourceFeatures, setFeatureState, getFeatureState, removeFeatureState, resetFeatureState and adds interfaces for iOS and Android
• Adds all necessary extensions for conversions on iOS and Android
• Adds an example showing how to query features in featuresets and set feature states.
• Adds necessary Turf adapters
• Adds tests

Simulator.Screen.Recording.-.iPhone.16.-.2025-01-08.at.19.57.40.mp4

Work for another PR:

• Tests which use a mocked interaction
• Expand on current example to better show use cases for API

What is the motivation and context behind this change?

• Platform alignment and enable Interactive Features

Pull request checklist:

• Add a changelog entry.
• Write tests for all new functionality. If tests were not written, please explain why.
• Add documentation comments for any added or updated public APIs.

[persidskiy]

some small bits of review

[pjleonard37]

I feel that this could be simplified somehow, but I can't think of exactly how. Recommendations are most welcome.

[pjleonard37]

@evil159 -- I'd appreciate a particularly thorough review of this section (setting up the listener and message channel. I model it broadly after our approach to gestures, but would welcome any suggested improvements. What do you think of this system of using both _InteractionListener and _InteractionsList?

[evil159]

Given the limitations - I think this is perfectly fine way to do it(it is also probably the only way to do it :)

[evil159]

I think the only thing that is missing here is the ability to remove interaction.

[pjleonard37]

@evil159 - any better approach here you can think of?

[evil159]

Could it be a way to go to define an internal structure in pigeon templates to carry all of this data and define a method that accepts this structure. It will not change much conceptually, but at least basics(serialization, message sending) will be handled by Pigeon.

[pjleonard37]

@persidskiy and @evil159 - I've introduced these Standard-specific types here which also have corresponding FeatureStates which can be used like this:

  StandardBuildingState featureState = StandardBuildingState(highlight: true);

  mapboxMap.addInteraction(tapInteraction, (_, FeaturesetFeature feature) {
    mapboxMap.setFeatureStateForFeaturesetFeature(feature, featureState);
    var buildingFeature = StandardBuildingsFeature(
        feature.geometry, feature.properties, feature.state,
        id: feature.id);
    print("Building feature id: ${buildingFeature.id}");
  });

I'd like to push the concept farther and return them instead of the generic FeaturesetFeature, but I'm running into some limits of what we can do with our Dart and Pigeon setup. I can't think of how we'd pass a typed version of FeaturesetFeature with OnInteraction. Any ideas?

typedef void OnInteraction(
    MapContentGestureContext context, FeaturesetFeature feature);

[evil159]

Seems that the type system allows this:

interface class MyInterface {}
class MyImplementation implements MyInterface {
  String? bar = "bar";
}
class MyImplementation2 implements MyInterface {
  String? baz = "baz";
}

class MyInteraction<T extends MyInterface> {
  final T impl;
  MyInteraction(this.impl);
}


void foo<T extends MyInterface>(MyInteraction<T> i, void Function(T) callback) {
  callback(i.impl);
}

void main() {
  final i = MyInteraction(MyImplementation());
  foo(i, (MyImplementation i) {
    print(i.bar);
  });

  final i2 = MyInteraction(MyImplementation2());
  foo(i2, (MyImplementation2 i) {
    print(i.baz);
  });
}

[pjleonard37]

Note that I've included this here rather than in the callback

[persidskiy]

It is in callback originally because the decision can depend on the feature itself, so you can decide it only in the callback. Let's aligh on this?

[evil159]

Given the limitations - I think this is perfectly fine way to do it(it is also probably the only way to do it :)

[evil159]

I think the only thing that is missing here is the ability to remove interaction.

[evil159]

Seems that the type system allows this:

interface class MyInterface {}
class MyImplementation implements MyInterface {
  String? bar = "bar";
}
class MyImplementation2 implements MyInterface {
  String? baz = "baz";
}

class MyInteraction<T extends MyInterface> {
  final T impl;
  MyInteraction(this.impl);
}


void foo<T extends MyInterface>(MyInteraction<T> i, void Function(T) callback) {
  callback(i.impl);
}

void main() {
  final i = MyInteraction(MyImplementation());
  foo(i, (MyImplementation i) {
    print(i.bar);
  });

  final i2 = MyInteraction(MyImplementation2());
  foo(i2, (MyImplementation2 i) {
    print(i.baz);
  });
}

[persidskiy]

@pjleonard37 The PR looks good. I left some comments here and there discussing different design choices

[persidskiy]

On iOS/Android the Interaction itself consumes the callback upon construction, but in Flutter the callback is supplied into addInteraction method. Is it some Flutter limitation?

[pjleonard37]

Is it some Flutter limitation?

Yes, because we need to serialize the Interaction here.

[persidskiy]

Can we make the interaction generic so that the callback automatically return you the StandardBuildingsFeature?

[persidskiy]

In Android/iOS we allow the propagation to be decided dynamically in the callback, because the decision can depend on the feature itself. Can we align on this in Flutter?

[persidskiy]

It is in callback originally because the decision can depend on the feature itself, so you can decide it only in the callback. Let's aligh on this?

[persidskiy]

Can we make this to be generic over the feature type, like in iOS/Android?

[persidskiy]

We don't expose anything like this enum in iOS/Android to avoid problems with extensibility. Instead, only the distinct interaction classes are available.

Can we align on that?

[persidskiy]

In Android/iOS we started with manual implementation of those classes, but quickly realized that there's no way to align on it, if we don't generate them from the style.

Can we generate them as well in Flutter?

[persidskiy]

From the hashCode documentation:

/// Objects that are not equal are allowed to have the same hash code.

So we cannot use hashcode as a key in the dictionary.

Can we generate some Id in the Interaction itself?

[persidskiy]

Why do we need to set-up this communication each time we use addInteraction?

[pjleonard37]

We need to pass the list with all interactions, but there is no way to know when the final interaction has been added (unlike gestures where we have a limited set so we can just set up once). This approach overwrites the channel with the new list of all interactions each time one is added so that we can be sure messages can be sent through all of them. Though correct me if I'm thinking about channels incorrectly, @evil159.

This .setup() is generated by pigeon, so we do not have much flexibility in how we implement it.

[persidskiy]

Also by design the interactions order matters, so that latest added interaction executes first. If it returns true, then execution stops. If it returns false, then the next interaction is invoked.

We need to check this works.

[pjleonard37]

The behavior in Flutter matches the platform behavior. But that behavior is not as you describe. It varies based on the featureset. Standard Place Labels & Standard POIs work as you describe, and the last added interaction executes first. Standard Buildings is the opposite with the first added triggering first. You can test this in the iOS SDK example:

LongPressInteraction(.standardBuildings) { _, _ in
    print("Buildings 1")
    return false
}
LongPressInteraction(.standardPoi) { _, _  in
    print("POIs 1")
    return false
}
LongPressInteraction(.standardBuildings) { _, _ in
    print("Buildings 2")
    return false
}
LongPressInteraction(.standardPoi) { _, _  in
    print("POIs 2")
    return false
}
LongPressInteraction(.standardBuildings) { _, _  in
    print("Buildings 3")
    return false
}
LongPressInteraction(.standardPoi) { _, _  in
    print("POIs 3")
    return false
}

If you long press (or tap) on a POI over a building this will print:

POIs 3
POIs 2
POIs 1
Buildings 1
Buildings 2
Buildings 3

I replicated this on Android as well. I'm not sure why this is, and we should ticket for investigation.