api [nfc]: Rename resolveDmElements to resolveApiNarrowElements

And refactor the implementation to prepare for a new [ApiNarrow]
feature.

We're about to add ApiNarrowWith, which new in Zulip Server 9. This
function seems like a good place to resolve ApiNarrows into the
expected form for servers before 9 (without "with") and 9 or later
(with "with"). First we have to make its name and dartdoc more
generic, as done here.

Author: chrisbobbe

lib/api/model/narrow.dart

@@ -4,14 +4,22 @@ part 'narrow.g.dart';
 
 typedef ApiNarrow = List<ApiNarrowElement>;
 
-/// Resolve any [ApiNarrowDm] elements appropriately.
+/// Resolve any [ApiNarrowElement]s, such as [ApiNarrowDm]s, appropriately.
 ///
 /// This encapsulates a server-feature check.
-ApiNarrow resolveDmElements(ApiNarrow narrow, int zulipFeatureLevel) {
-  if (!narrow.any((element) => element is ApiNarrowDm)) {
-    return narrow;
+// TODO(server-7) remove [ApiNarrowDm] reference in dartdoc
+ApiNarrow resolveApiNarrowElements(ApiNarrow narrow, int zulipFeatureLevel) {
+  bool hasDmElement = false;
+  for (final element in narrow) {
+    switch (element) {
+      case ApiNarrowDm(): hasDmElement = true;
+      default:
+    }
   }
+  if (!hasDmElement) return narrow;
+
   final supportsOperatorDm = zulipFeatureLevel >= 177; // TODO(server-7)
+
   return narrow.map((element) => switch (element) {
     ApiNarrowDm() => element.resolve(legacy: !supportsOperatorDm),
     _             => element,
@@ -70,7 +78,7 @@ class ApiNarrowTopic extends ApiNarrowElement {
 /// and more generally its [operator] getter must not be called.
 /// Instead, call [resolve] and use the object it returns.
 ///
-/// If part of [ApiNarrow] use [resolveDmElements].
+/// If part of [ApiNarrow] use [resolveApiNarrowElements].
 class ApiNarrowDm extends ApiNarrowElement {
   @override String get operator {
     assert(false,

lib/api/route/messages.dart

@@ -91,7 +91,7 @@ Future<GetMessagesResult> getMessages(ApiConnection connection, {
   // bool? useFirstUnreadAnchor // omitted because deprecated
 }) {
   return connection.get('getMessages', GetMessagesResult.fromJson, 'messages', {
-    'narrow': resolveDmElements(narrow, connection.zulipFeatureLevel!),
+    'narrow': resolveApiNarrowElements(narrow, connection.zulipFeatureLevel!),
     'anchor': RawParameter(anchor.toJson()),
     if (includeAnchor != null) 'include_anchor': includeAnchor,
     'num_before': numBefore,
@@ -367,7 +367,7 @@ Future<UpdateMessageFlagsForNarrowResult> updateMessageFlagsForNarrow(ApiConnect
     if (includeAnchor != null) 'include_anchor': includeAnchor,
     'num_before': numBefore,
     'num_after': numAfter,
-    'narrow': resolveDmElements(narrow, connection.zulipFeatureLevel!),
+    'narrow': resolveApiNarrowElements(narrow, connection.zulipFeatureLevel!),
     'op': RawParameter(op.toJson()),
     'flag': RawParameter(flag.toJson()),
   });

lib/model/internal_link.dart

@@ -58,7 +58,7 @@ String? decodeHashComponent(String str) {
 // you do so by passing the `anchor` param.
 Uri narrowLink(PerAccountStore store, Narrow narrow, {int? nearMessageId}) {
   // TODO(server-7)
-  final apiNarrow = resolveDmElements(
+  final apiNarrow = resolveApiNarrowElements(
     narrow.apiEncode(), store.connection.zulipFeatureLevel!);
   final fragment = StringBuffer('narrow');
   for (ApiNarrowElement element in apiNarrow) {

test/api/route/messages_test.dart

@@ -176,7 +176,7 @@ void main() {
   test('Narrow.toJson', () {
     return FakeApiConnection.with_((connection) async {
       void checkNarrow(ApiNarrow narrow, String expected) {
-        narrow = resolveDmElements(narrow, connection.zulipFeatureLevel!);
+        narrow = resolveApiNarrowElements(narrow, connection.zulipFeatureLevel!);
         check(jsonEncode(narrow)).equals(expected);
       }
 
@@ -263,7 +263,7 @@ void main() {
       });
     });
 
-    test('narrow uses resolveDmElements to encode', () {
+    test('narrow uses resolveApiNarrowElements to encode', () {
       return FakeApiConnection.with_(zulipFeatureLevel: 176, (connection) async {
         connection.prepare(json: fakeResult.toJson());
         await checkGetMessages(connection,
@@ -650,7 +650,7 @@ void main() {
       });
     });
 
-    test('narrow uses resolveDmElements to encode', () {
+    test('narrow uses resolveApiNarrowElements to encode', () {
       return FakeApiConnection.with_(zulipFeatureLevel: 176, (connection) async {
         connection.prepare(json: mkResult(foundOldest: true).toJson());
         await checkUpdateMessageFlagsForNarrow(connection,