api [nfc]: Rename resolveDmElements to resolveApiNarrowForServer

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

@@ -6,14 +6,24 @@ part 'narrow.g.dart';
 
 typedef ApiNarrow = List<ApiNarrowElement>;
 
-/// Resolve any [ApiNarrowDm] elements appropriately.
+/// Adapt the given narrow to be sent to the given Zulip server version.
 ///
-/// This encapsulates a server-feature check.
-ApiNarrow resolveDmElements(ApiNarrow narrow, int zulipFeatureLevel) {
-  if (!narrow.any((element) => element is ApiNarrowDm)) {
-    return narrow;
-  }
+/// Any elements that take a different name on old vs. new servers
+/// will be resolved to the specific name to use.
+/// Any elements that are unknown to old servers and can
+/// reasonably be omitted will be omitted.
+ApiNarrow resolveApiNarrowForServer(ApiNarrow narrow, int zulipFeatureLevel) {
   final supportsOperatorDm = zulipFeatureLevel >= 177; // TODO(server-7)
+
+  bool hasDmElement = false;
+  for (final element in narrow) {
+    switch (element) {
+      case ApiNarrowDm(): hasDmElement = true;
+      default:
+    }
+  }
+  if (!hasDmElement) return narrow;
+
   return narrow.map((element) => switch (element) {
     ApiNarrowDm() => element.resolve(legacy: !supportsOperatorDm),
     _             => element,
@@ -102,7 +112,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 [resolveApiNarrowForServer].
 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': resolveApiNarrowForServer(narrow, connection.zulipFeatureLevel!),
     'anchor': RawParameter(anchor.toJson()),
     if (includeAnchor != null) 'include_anchor': includeAnchor,
     'num_before': numBefore,
@@ -400,7 +400,7 @@ Future<UpdateMessageFlagsForNarrowResult> updateMessageFlagsForNarrow(ApiConnect
     if (includeAnchor != null) 'include_anchor': includeAnchor,
     'num_before': numBefore,
     'num_after': numAfter,
-    'narrow': resolveDmElements(narrow, connection.zulipFeatureLevel!),
+    'narrow': resolveApiNarrowForServer(narrow, connection.zulipFeatureLevel!),
     'op': RawParameter(op.toJson()),
     'flag': RawParameter(flag.toJson()),
   });

lib/model/internal_link.dart

@@ -59,7 +59,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 = resolveApiNarrowForServer(
     narrow.apiEncode(), store.connection.zulipFeatureLevel!);
   final fragment = StringBuffer('narrow');
   for (ApiNarrowElement element in apiNarrow) {

test/api/route/messages_test.dart

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