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.

We convert the IsOperand value into a String when constructing
ApiNarrowIs, so that we don't need to mingle with
ApiNarrowElement.toJson to take care of the enum.

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

Author: PIG208

lib/api/model/narrow.dart

@@ -1,3 +1,5 @@
+import '../../model/internal_link.dart';
+
 typedef ApiNarrow = List<ApiNarrowElement>;
 
 /// Resolve any [ApiNarrowDm] elements appropriately.
@@ -114,19 +116,17 @@ 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 String operand;
 
-class ApiNarrowIsUnread extends ApiNarrowElement {
-  @override String get operator => 'is';
-  @override String get operand => 'unread';
+  ApiNarrowIs(IsOperand operand, {super.negated}) : operand = operand.toString();
 
-  ApiNarrowIsUnread({super.negated});
+  factory ApiNarrowIs.fromJson(Map<String, dynamic> json) => ApiNarrowIs(
+    IsOperand.fromRawString(json['operand'] as String),
+    negated: json['negated'] as bool? ?? false,
+  );
 }
 
 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;
+  ApiNarrowIs? isMentionedElement;
 
   for (var i = 0; i < segments.length; i += 2) {
     final (operator, negated) = _parseOperator(segments[i]);
@@ -184,7 +182,7 @@ Narrow? _interpretNarrowSegments(List<String> segments, PerAccountStore store) {
 
       case _NarrowOperator.is_:
         if (isMentionedElement != null) return null;
-        if (operand == 'mentioned') isMentionedElement = ApiNarrowIsMentioned();
+        if (operand == 'mentioned') isMentionedElement = ApiNarrowIs(IsOperand.mentioned);
         return null;
 
       case _NarrowOperator.near: // TODO(#82): support for near
@@ -293,3 +291,28 @@ List<int>? _parseDmOperand(String operand) {
     return null;
   }
 }
+
+/// 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,
+  private, // This is deprecated in FL 177 and equivalent to [dm].
+  alerted,
+  mentioned,
+  starred,
+  followed,
+  resolved,
+  unread,
+  unknown;
+
+  static IsOperand fromRawString(String raw) => $enumDecode(
+    _$IsOperandEnumMap, raw, unknownValue: unknown);
+
+  @override
+  String toString() => _$IsOperandEnumMap[this]!;
+}

lib/model/internal_link.g.dart

@@ -5,6 +5,7 @@ import '../api/model/model.dart';
 import '../api/model/narrow.dart';
 import '../api/route/messages.dart';
 import 'algorithms.dart';
+import 'internal_link.dart';
 
 /// A Zulip narrow.
 sealed class Narrow {
@@ -309,7 +310,7 @@ class MentionsNarrow extends Narrow {
   }
 
   @override
-  ApiNarrow apiEncode() => [ApiNarrowIsMentioned()];
+  ApiNarrow apiEncode() => [ApiNarrowIs(IsOperand.mentioned)];
 
   @override
   bool operator ==(Object other) {

lib/model/narrow.dart

@@ -12,6 +12,7 @@ import 'package:flutter_gen/gen_l10n/zulip_localizations.dart';
 import '../api/model/model.dart';
 import '../api/model/narrow.dart';
 import '../api/route/messages.dart';
+import '../model/internal_link.dart';
 import '../model/narrow.dart';
 import 'dialog.dart';
 import 'store.dart';
@@ -44,7 +45,7 @@ Future<void> markNarrowAsRead(
   // 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`.
-  final apiNarrow = narrow.apiEncode()..add(ApiNarrowIsUnread());
+  final apiNarrow = narrow.apiEncode()..add(ApiNarrowIs(IsOperand.unread));
 
   while (true) {
     final result = await updateMessageFlagsForNarrow(connection,

lib/widgets/actions.dart

@@ -8,6 +8,7 @@ import 'package:zulip/api/model/initial_snapshot.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/model/narrow.dart';
 import 'package:zulip/api/route/messages.dart';
+import 'package:zulip/model/internal_link.dart';
 import 'package:zulip/model/localizations.dart';
 import 'package:zulip/model/narrow.dart';
 import 'package:zulip/model/store.dart';
@@ -54,7 +55,7 @@ void main() {
         foundOldest: true, foundNewest: true).toJson());
       markNarrowAsRead(context, narrow, false);
       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')
@@ -104,7 +105,7 @@ void main() {
         firstProcessedId: 1, lastProcessedId: 1989,
         foundOldest: true, foundNewest: false).toJson());
       markNarrowAsRead(context, narrow, false);
-      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')
@@ -164,7 +165,7 @@ void main() {
         foundOldest: true, foundNewest: false).toJson());
       markNarrowAsRead(context, narrow, false);
       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')

test/widgets/actions_test.dart

@@ -11,6 +11,7 @@ import 'package:zulip/api/model/initial_snapshot.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/model/narrow.dart';
 import 'package:zulip/api/route/messages.dart';
+import 'package:zulip/model/internal_link.dart';
 import 'package:zulip/model/localizations.dart';
 import 'package:zulip/model/narrow.dart';
 import 'package:zulip/model/store.dart';
@@ -540,7 +541,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')