Internal_link: Add ApiIsNarrow.

lib/api/model/narrow.dart

@@ -1,3 +1,7 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'narrow.g.dart';
+
 typedef ApiNarrow = List<ApiNarrowElement>;
 
 /// Resolve any [ApiNarrowDm] elements appropriately.
@@ -114,19 +118,44 @@ class ApiNarrowPmWith extends ApiNarrowDm {
   ApiNarrowPmWith._(super.operand, {super.negated});
 }
 
-// TODO: generalize into ApiNarrowIs
-class ApiNarrowIsMentioned extends ApiNarrowElement {
+class ApiNarrowIs extends ApiNarrowElement {
   @override String get operator => 'is';
-  @override String get operand => 'mentioned';
 
-  ApiNarrowIsMentioned({super.negated});
-}
+  @override final IsOperand operand;
 
-class ApiNarrowIsUnread extends ApiNarrowElement {
-  @override String get operator => 'is';
-  @override String get operand => 'unread';
+  ApiNarrowIs(this.operand, {super.negated});
 
-  ApiNarrowIsUnread({super.negated});
+  factory ApiNarrowIs.fromJson(Map<String, dynamic> json) => ApiNarrowIs(
+    IsOperand.fromRawString(json['operand'] as String),
+    negated: json['negated'] as bool? ?? false,
+  );
+}
+
+/// An operand value of "is" operator.
+///
+/// See also:
+///   - https://zulip.com/api/construct-narrow
+///   - https://zulip.com/help/search-for-messages#search-your-important-messages
+///   - https://zulip.com/help/search-for-messages#search-by-message-status
+@JsonEnum(alwaysCreate: true)
+enum IsOperand {
+  dm,        // TODO(server-7) new in FL 177
+  private,   // TODO(server-7) deprecated in FL 177, equivalent to [dm].
+  alerted,
+  mentioned,
+  starred,
+  followed,  // TODO(server-9) new in FL 265
+  resolved,
+  unread,
+  unknown;
+
+  static IsOperand fromRawString(String raw) => $enumDecode(
+    _$IsOperandEnumMap, raw, unknownValue: unknown);
+
+  @override
+  String toString() => _$IsOperandEnumMap[this]!;
+
+  String toJson() => toString();
 }
 
 class ApiNarrowMessageId extends ApiNarrowElement {

lib/model/internal_link.dart

@@ -85,9 +85,7 @@ Uri narrowLink(PerAccountStore store, Narrow narrow, {int? nearMessageId}) {
         fragment.write('${element.operand.join(',')}-$suffix');
       case ApiNarrowDm():
         assert(false, 'ApiNarrowDm should have been resolved');
-      case ApiNarrowIsMentioned():
-        fragment.write(element.operand.toString());
-      case ApiNarrowIsUnread():
+      case ApiNarrowIs():
         fragment.write(element.operand.toString());
       case ApiNarrowMessageId():
         fragment.write(element.operand.toString());
@@ -154,7 +152,7 @@ Narrow? _interpretNarrowSegments(List<String> segments, PerAccountStore store) {
   ApiNarrowStream? streamElement;
   ApiNarrowTopic? topicElement;
   ApiNarrowDm? dmElement;
-  ApiNarrowIsMentioned? isMentionedElement;
+  Set<IsOperand> isElementOperands = {};
 
   for (var i = 0; i < segments.length; i += 2) {
     final (operator, negated) = _parseOperator(segments[i]);
@@ -183,8 +181,8 @@ Narrow? _interpretNarrowSegments(List<String> segments, PerAccountStore store) {
         dmElement = ApiNarrowDm(dmIds, negated: negated);
 
       case _NarrowOperator.is_:
-        if (isMentionedElement != null) return null;
-        if (operand == 'mentioned') isMentionedElement = ApiNarrowIsMentioned();
+        // It is fine to have duplicates of the same [IsOperand].
+        isElementOperands.add(IsOperand.fromRawString(operand));
 
       case _NarrowOperator.near: // TODO(#82): support for near
       case _NarrowOperator.with_: // TODO(#683): support for with
@@ -195,9 +193,22 @@ Narrow? _interpretNarrowSegments(List<String> segments, PerAccountStore store) {
     }
   }
 
-  if (isMentionedElement != null) {
+  if (isElementOperands.isNotEmpty) {
     if (streamElement != null || topicElement != null || dmElement != null) return null;
-    return const MentionsNarrow();
+    if (isElementOperands.length > 1) return null;
+    switch (isElementOperands.single) {
+      case IsOperand.mentioned:
+        return const MentionsNarrow();
+      case IsOperand.dm:
+      case IsOperand.private:
+      case IsOperand.alerted:
+      case IsOperand.starred:
+      case IsOperand.followed:
+      case IsOperand.resolved:
+      case IsOperand.unread:
+      case IsOperand.unknown:
+        return null;
+    }
   } else if (dmElement != null) {
     if (streamElement != null || topicElement != null) return null;
     return DmNarrow.withUsers(dmElement.operand, selfUserId: store.selfUserId);

lib/model/narrow.dart

@@ -309,7 +309,7 @@ class MentionsNarrow extends Narrow {
   }
 
   @override
-  ApiNarrow apiEncode() => [ApiNarrowIsMentioned()];
+  ApiNarrow apiEncode() => [ApiNarrowIs(IsOperand.mentioned)];
 
   @override
   bool operator ==(Object other) {

lib/widgets/actions.dart

@@ -41,7 +41,7 @@ Future<void> markNarrowAsRead(BuildContext context, Narrow narrow) async {
     // The server applies the same optimization within the (deprecated)
     // specialized endpoints for marking messages as read; see
     // `do_mark_stream_messages_as_read` in `zulip:zerver/actions/message_flags.py`.
-    apiNarrow: narrow.apiEncode()..add(ApiNarrowIsUnread()),
+    apiNarrow: narrow.apiEncode()..add(ApiNarrowIs(IsOperand.unread)),
     // Use [AnchorCode.oldest], because [AnchorCode.firstUnread]
     // will be the oldest non-muted unread message, which would
     // result in muted unreads older than the first unread not

test/model/internal_link_test.dart

@@ -2,6 +2,7 @@
 import 'package:checks/checks.dart';
 import 'package:test/scaffolding.dart';
 import 'package:zulip/api/model/model.dart';
+import 'package:zulip/api/model/narrow.dart';
 import 'package:zulip/model/internal_link.dart';
 import 'package:zulip/model/narrow.dart';
 import 'package:zulip/model/store.dart';
@@ -221,18 +222,39 @@ void main() {
       testExpectedNarrows(testCases, streams: streams);
     });
 
-    group('"/#narrow/is/mentioned returns expected MentionsNarrow', () {
-      final testCases = [
-        ('/#narrow/is/mentioned',                                     const MentionsNarrow()),
-        ('/#narrow/is/mentioned/near/1',                              const MentionsNarrow()),
-        ('/#narrow/is/mentioned/with/2',                              const MentionsNarrow()),
-        ('/#narrow/channel/7-test-here/is/mentioned',                 null),
-        ('/#narrow/channel/check/topic/test/is/mentioned',            null),
-        ('/#narrow/topic/test/is/mentioned',                          null),
-        ('/#narrow/dm/17327-Chris-Bobbe-(Test-Account)/is/mentioned', null),
-        ('/#narrow/-is/mentioned',                                    null),
-      ];
-      testExpectedNarrows(testCases, streams: streams);
+    group('/#narrow/is/<...> returns corresponding narrow', () {
+      // For these tests, we are more interested in the internal links
+      // containing a single effective `is` operator.
+      // Internal links with multiple operators should be tested separately.
+      for (final operand in IsOperand.values) {
+        List<(String, Narrow?)> sharedCases(Narrow? narrow) => [
+            ('/#narrow/is/$operand',                                     narrow),
+            ('/#narrow/is/$operand/is/$operand',                         narrow),
+            ('/#narrow/is/$operand/near/1',                              narrow),
+            ('/#narrow/is/$operand/with/2',                              narrow),
+            ('/#narrow/channel/7-test-here/is/$operand',                 null),
+            ('/#narrow/channel/check/topic/test/is/$operand',            null),
+            ('/#narrow/topic/test/is/$operand',                          null),
+            ('/#narrow/dm/17327-Chris-Bobbe-(Test-Account)/is/$operand', null),
+            ('/#narrow/-is/$operand',                                    null),
+          ];
+        final List<(String, Narrow?)> testCases;
+        switch (operand) {
+          case IsOperand.mentioned:
+            testCases = sharedCases(const MentionsNarrow());
+          case IsOperand.dm:
+          case IsOperand.private:
+          case IsOperand.alerted:
+          case IsOperand.starred:
+          case IsOperand.followed:
+          case IsOperand.resolved:
+          case IsOperand.unread:
+          case IsOperand.unknown:
+            // Unsupported operands should not return any narrow.
+            testCases = sharedCases(null);
+        }
+        testExpectedNarrows(testCases, streams: streams);
+      }
     });
 
     group('unexpected link shapes are rejected', () {

test/widgets/actions_test.dart

@@ -54,7 +54,7 @@ void main() {
         foundOldest: true, foundNewest: true).toJson());
       markNarrowAsRead(context, narrow);
       await tester.pump(Duration.zero);
-      final apiNarrow = narrow.apiEncode()..add(ApiNarrowIsUnread());
+      final apiNarrow = narrow.apiEncode()..add(ApiNarrowIs(IsOperand.unread));
       check(connection.lastRequest).isA<http.Request>()
         ..method.equals('POST')
         ..url.path.equals('/api/v1/messages/flags/narrow')
@@ -208,7 +208,7 @@ void main() {
     const progressMessage = 'progressMessage';
     const onFailedTitle = 'onFailedTitle';
     final narrow = TopicNarrow.ofMessage(eg.streamMessage());
-    final apiNarrow = narrow.apiEncode()..add(ApiNarrowIsUnread());
+    final apiNarrow = narrow.apiEncode()..add(ApiNarrowIs(IsOperand.unread));
 
     Future<bool> invokeUpdateMessageFlagsStartingFromAnchor() =>
       updateMessageFlagsStartingFromAnchor(

test/widgets/message_list_test.dart

@@ -536,7 +536,7 @@ void main() {
           firstProcessedId: null, lastProcessedId: null,
           foundOldest: true, foundNewest: true).toJson());
         await tester.tap(find.byType(MarkAsReadWidget));
-        final apiNarrow = narrow.apiEncode()..add(ApiNarrowIsUnread());
+        final apiNarrow = narrow.apiEncode()..add(ApiNarrowIs(IsOperand.unread));
         check(connection.lastRequest).isA<http.Request>()
           ..method.equals('POST')
           ..url.path.equals('/api/v1/messages/flags/narrow')