internal_link [nfc]: Add ApiIsNarrow.

This replaces ApiNarrowIsMentioned and ApiNarrowIsUnread with the
generic ApiNarrowIs element.

This does not change the internal links behavior, hence the nfc.
This is also why this commit hasn't introduced new tests yet.

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

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/api/model/narrow.g.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;
+  ApiNarrowIs? isMentionedElement;
 
   for (var i = 0; i < segments.length; i += 2) {
     final (operator, negated) = _parseOperator(segments[i]);
@@ -185,7 +183,7 @@ Narrow? _interpretNarrowSegments(List<String> segments, PerAccountStore store) {
       case _NarrowOperator.is_:
         if (isMentionedElement != null) return null;
         if (operand == 'mentioned') {
-          isMentionedElement = ApiNarrowIsMentioned();
+          isMentionedElement = ApiNarrowIs(IsOperand.mentioned);
         } else {
           return null;
         }

lib/model/internal_link.dart

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

lib/model/narrow.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

lib/widgets/actions.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/actions_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')