-
Notifications
You must be signed in to change notification settings - Fork 354
Channel link autocomplete #1902
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
|
Exciting! Thanks for building this. Just to record here what I said on the team call yesterday: for this PR, we can start the reviews in parallel with you writing the tests. So I'd suggest going ahead and adding those docs and comments next — then once you consider the PR all ready except for the tests, just mention that here and add the "maintainer review" label. |
5a8171d to
6671cfa
Compare
|
Thanks @gnprice for mentioning this. This is now ready for an initial review. (While working on the first todo, I realized that there were a few other places that needed some changes, which caused a delay 😀) |
6671cfa to
fe25a32
Compare
|
(just rebased atop main with conflicts resolved) |
fe25a32 to
480e787
Compare
6b2fb06 to
5072dce
Compare
|
@chrisbobbe Pushed a new revision with tests included. |
|
Thanks for this, and apologies for my delay in reviewing! Here's a review of the first six commits: 05c8437 channel: Add isRecentlyActive field plus some comments on later commits where I happened to see something interesting. 🙂 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh no—thanks for the ping in DMs, somehow I didn't actually submit that review yesterday! Here it is.
test/example_data.dart
Outdated
| historyPublicToSubscribers: historyPublicToSubscribers ?? true, | ||
| messageRetentionDays: messageRetentionDays, | ||
| channelPostPolicy: channelPostPolicy ?? ChannelPostPolicy.any, | ||
| isRecentlyActive: isRecentlyActive ?? false, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think true might be a more natural default value for this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changed to true. The false default value was to make the tests in "ranking across signals" and "final results end-to-end" of "ChannelLinkAutocompleteView" group a little less verbose.🙂
lib/api/model/model.dart
Outdated
| @JsonKey(name: 'stream_post_policy') | ||
| ChannelPostPolicy? channelPostPolicy; // TODO(server-10) remove | ||
| // final bool isAnnouncementOnly; // deprecated for `channelPostPolicy`; ignore | ||
| bool? isRecentlyActive; // TODO(server-10) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
channel: Add isRecentlyActive field
Since we're already not matching the order in the API doc (see e.g. #1894 (comment) ), I'd put this next to the related-looking field streamWeeklyTraffic, perhaps just above it without an empty line in between.
Similarly elsewhere in this commit.
lib/api/model/events.dart
Outdated
| required super.id, | ||
| required this.streams, | ||
| required this.streamIds, | ||
| }) : assert(streams != null || streamIds != null); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We try to reserve assert for invariants that are our own responsibility, i.e. those that won't be broken except for some broken logic in the client. Here, the invariant exists, but it's one that can be broken by something out of our control, in particular a badly-behaving server.
Also, asserts don't run in production, so this won't work as "crunchy shell" validation. It makes sense to want such validation, so the "soft center" of the app can rely on this invariant. But let's do it in ChannelDeleteEvent.fromJson; for an example to follow, see DeleteMessageEvent.fromJson.
lib/api/model/events.dart
Outdated
|
|
||
| final List<ZulipStream> streams; | ||
| final List<ZulipStreamId>? streams; // TODO(server-10): remove | ||
| final List<int>? streamIds; // TODO(server-10): remove nullability |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: we'd normally say TODO(server-10) make required or just TODO(server-10).
lib/model/channel.dart
Outdated
| streams.remove(stream.streamId); | ||
| streamsByName.remove(stream.name); | ||
| subscriptions.remove(stream.streamId); | ||
| final channelIds = event.streamIds ?? event.streams!.map((e) => e.streamId); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh actually, we can make this nicer by encapsulating this conditional in the API-binding layer—ChannelDeleteEvent can have just final List<int> streamIds (maybe channelIds, as the more modern name?), and it can read its value depending on what the JSON looks like.
Something like this (untested)?:
/// A [ChannelEvent] with op `delete`: https://zulip.com/api/get-events#stream-delete
@JsonSerializable(fieldRename: FieldRename.snake)
class ChannelDeleteEvent extends ChannelEvent {
@override
@JsonKey(includeToJson: true)
String get op => 'delete';
@JsonKey(readValue: _readChannelIds)
final List<int> channelIds;
// TODO(server-10) simplify away; rely on stream_ids
static List<int> _readChannelIds(Map<dynamic, dynamic> json, String key) {
final channelIds = json['stream_ids'] as List<int>?;
if (channelIds != null) return channelIds;
final channels = json['streams'] as List<dynamic>;
return channels
.map((c) => (c as Map<String, dynamic>)['stream_id'] as int)
.toList();
}
ChannelDeleteEvent({
required super.id,
required this.channelIds,
});
factory ChannelDeleteEvent.fromJson(Map<String, dynamic> json) =>
_$ChannelDeleteEventFromJson(json);
@override
Map<String, dynamic> toJson() => _$ChannelDeleteEventToJson(this);
}There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(In that code, the crunchy-shell validation is done by the final channels = json['streams'] as List<dynamic>; line, which will throw if both .stream_ids and .streams are absent in the json.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changed to the new version. One thing that this does is that in toJson, there will be an entry with key channel_ids; not exactly what the server gives us (stream_ids or streams). Should we edit the toJson method to match the server data, or is it not that important since we don't use it to send it back to the server?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ahh, so there was a test failing in test/model/store_test.dart and the fix was to include streams in toJson.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, streams is deprecated and may be removed, so I think we should treat it as valid if streams is absent and stream_ids is present. I'd want our tests to tolerate that form without failing.
I took a look and found a bug in _readChannelIds in this revision 🙂:
diff --git lib/api/model/events.dart lib/api/model/events.dart
index 6a0d9ffa4..4d9c5121c 100644
--- lib/api/model/events.dart
+++ lib/api/model/events.dart
@@ -622,7 +622,7 @@ class ChannelDeleteEvent extends ChannelEvent {
// TODO(server-10) simplify away; rely on stream_ids
static List<int> _readChannelIds(Map<dynamic, dynamic> json, String key) {
final channelIds = json['stream_ids'] as List<dynamic>?;
- if (channelIds != null) channelIds.map((id) => id as int).toList();
+ if (channelIds != null) return channelIds.map((id) => id as int).toList();
final channels = json['streams'] as List<dynamic>;
return channels
lib/widgets/autocomplete.dart
Outdated
| overflow: TextOverflow.ellipsis, | ||
| color: designVariables.contextMenuItemMeta)), | ||
| child: BlockContentList( | ||
| nodes: parseContent(channel!.renderedDescription).nodes), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Neat! Unfortunately we're not ready to show the rendered channel description; some of our content widgets will break if they appear outside the context of a message, because they use InheritedMessage.of(context), and we need to address that systematically, which is #488. See related issues:
- Show channel description in channel action sheet #1896
- content: Support Zulip content outside messages (even outside per-account contexts) #488
For now let's do as I did in #1877:
- Not try to show the channel description here
- File an issue for it and leave a TODO
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Filed #1945. Also, looking at https://github.com/zulip/zulip-flutter/blob/main/lib/widgets/content.dart, it seems like InheritedMessage.of(context) is used in two places, MessageImagePreview and MessageInlineVideo, and by manually testing, it seems like the server is not sending the related HTML for rendering these widgets when there is an image or video in the channel description. So I think it will be safe to show the channel description now. But as it’s possible that InheritedMessage.of(context) will be used in other widgets, it's good to wait for #488 as you mentioned.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
by manually testing, it seems like the server is not sending the related HTML for rendering these widgets when there is an image or video in the channel description. So I think it will be safe to show the channel description now.
For this sort of detail I'd want to rely on API guarantees rather than manual testing on a current server. It's at least plausible that we could run into different behavior with some old server we still support (like 7), or even on any server, including a modern one like CZO, for a channel that was last updated when the server version was ancient, like 3 or something.
But as it’s possible that
InheritedMessage.of(context)will be used in other widgets, it's good to wait for #488 as you mentioned.
Yep, this is also true :) it'll be nice to be systematic about it.
| // Behavior we have that web doesn't and might like to follow: | ||
| // - A "word-prefixes" match quality on channel names: | ||
| // see [NameMatchQuality.wordPrefixes], which we rank on. | ||
| // | ||
| // Behavior web has that seems undesired, which we don't plan to follow: | ||
| // - A "word-boundary" match quality on channel names: | ||
| // special rank when the whole query appears contiguously | ||
| // right after a word-boundary character. | ||
| // Our [NameMatchQuality.wordPrefixes] seems smarter. | ||
| // - Ranking some case-sensitive matches differently from case-insensitive | ||
| // matches. Users will expect a lowercase query to be adequate. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Am I reading web's sort_streams correctly that it also considers channel descriptions in the filtering and ranking? I don't personally think we need to do that, but it probably deserves a mention here.
lib/model/autocomplete.dart
Outdated
| return switch((tryCast<Subscription>(a), tryCast<Subscription>(b))) { | ||
| (Subscription(), null) => -1, | ||
| (null, Subscription()) => 1, | ||
| (Subscription(isMuted: false), Subscription(isMuted: true)) => -1, | ||
| (Subscription(isMuted: true), Subscription(isMuted: false)) => 1, | ||
| (Subscription(pinToTop: true), Subscription(pinToTop: false)) => -1, | ||
| (Subscription(pinToTop: false), Subscription(pinToTop: true)) => 1, | ||
| _ => 0, | ||
| }; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd prefer not to add and use tryCast for this, and instead do something like:
| return switch((tryCast<Subscription>(a), tryCast<Subscription>(b))) { | |
| (Subscription(), null) => -1, | |
| (null, Subscription()) => 1, | |
| (Subscription(isMuted: false), Subscription(isMuted: true)) => -1, | |
| (Subscription(isMuted: true), Subscription(isMuted: false)) => 1, | |
| (Subscription(pinToTop: true), Subscription(pinToTop: false)) => -1, | |
| (Subscription(pinToTop: false), Subscription(pinToTop: true)) => 1, | |
| _ => 0, | |
| }; | |
| if (a is Subscription && b is! Subscription) return -1; | |
| if (a is! Subscription && b is Subscription) return 1; | |
| return switch((a, b)) { | |
| (Subscription(isMuted: false), Subscription(isMuted: true)) => -1, | |
| (Subscription(isMuted: true), Subscription(isMuted: false)) => 1, | |
| (Subscription(pinToTop: true), Subscription(pinToTop: false)) => -1, | |
| (Subscription(pinToTop: false), Subscription(pinToTop: true)) => 1, | |
| _ => 0, | |
| }; |
which is equivalent and doesn't add a step for the reader to interpret where null comes from and what it means. It also separates the main, headline logic from the rest, corresponding to the dartdoc's choice of what goes in its first line vs. the body:
/// Comparator that puts subscribed channels before unsubscribed ones.
///
/// For subscribed channels, it puts them in the following way:
/// pinned unmuted > unpinned unmuted > pinned muted > unpinned mutedThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(also nit: s/way/order/ in that dartdoc)
lib/model/autocomplete.dart
Outdated
| /// Comparator that puts channels with more weekly traffic first. | ||
| /// | ||
| /// A channel with undefined weekly traffic (`null`) is put after the channel | ||
| /// with a weekly traffic defined (even if it is zero). | ||
| /// | ||
| /// Weekly traffic is the average number of messages sent to the channel per | ||
| /// week, which is determined by [ZulipStream.streamWeeklyTraffic]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| /// Comparator that puts channels with more weekly traffic first. | |
| /// | |
| /// A channel with undefined weekly traffic (`null`) is put after the channel | |
| /// with a weekly traffic defined (even if it is zero). | |
| /// | |
| /// Weekly traffic is the average number of messages sent to the channel per | |
| /// week, which is determined by [ZulipStream.streamWeeklyTraffic]. | |
| /// Comparator that puts channels with more [ZulipStream.streamWeeklyTraffic] first. | |
| /// | |
| /// A channel with undefined weekly traffic (`null`) is put after the channel | |
| /// with a weekly traffic defined (even if it is zero). |
This is a very reasonable definition of "weekly traffic" 🙂 and so isn't likely to bitrot i.e. become incorrect over time. But since we're just using ZulipStream.streamWeeklyTraffic directly (no computations on it), let's leave that field's definition as the single place where we write its definition, so we only have to change that one thing if the meaning changes.
…I see that we haven't actually written down the field's meaning, which we might've done in dartdoc on the field. But that's quite normal and appropriate; by leaving it blank, we mean to defer to the API documentation, which is linked in the class ZulipStream dartdoc.
test/model/compose_test.dart
Outdated
| eg.stream(streamId: 5, name: 'UI [v2]'), | ||
| eg.stream(streamId: 6, name: r'Save $$'), | ||
| ]; | ||
| store.addStreams(channels); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be awaited; similarly in a few other places.
Thanks to the discarded_futures lint for catching this, actually; I was playing with it for #731 this morning 🙂
8cde339 to
ea64c45
Compare
|
Thanks @chrisbobbe for the review. Pushed new changes, PTAL. |
ea64c45 to
d1abf20
Compare
chrisbobbe
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! This is working great; comments below, this time from reading the whole branch.
lib/api/model/events.dart
Outdated
| case ChannelPropertyName.isRecentlyActive: | ||
| return value as bool?; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: bump on #1902 (comment)
test/example_data.dart
Outdated
| case ChannelPropertyName.isRecentlyActive: | ||
| assert(value is bool?); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: bump on #1902 (comment)
lib/model/channel.dart
Outdated
| streams.remove(stream.streamId); | ||
| streamsByName.remove(stream.name); | ||
| subscriptions.remove(stream.streamId); | ||
| final channelIds = event.streamIds ?? event.streams!.map((e) => e.streamId); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, streams is deprecated and may be removed, so I think we should treat it as valid if streams is absent and stream_ids is present. I'd want our tests to tolerate that form without failing.
I took a look and found a bug in _readChannelIds in this revision 🙂:
diff --git lib/api/model/events.dart lib/api/model/events.dart
index 6a0d9ffa4..4d9c5121c 100644
--- lib/api/model/events.dart
+++ lib/api/model/events.dart
@@ -622,7 +622,7 @@ class ChannelDeleteEvent extends ChannelEvent {
// TODO(server-10) simplify away; rely on stream_ids
static List<int> _readChannelIds(Map<dynamic, dynamic> json, String key) {
final channelIds = json['stream_ids'] as List<dynamic>?;
- if (channelIds != null) channelIds.map((id) => id as int).toList();
+ if (channelIds != null) return channelIds.map((id) => id as int).toList();
final channels = json['streams'] as List<dynamic>;
return channels| for (final view in _channelLinkAutocompleteViews) { | ||
| view.reassemble(); | ||
| } | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure! Sounds like that would help us avoid a bug like the one fixed here.
lib/model/autocomplete.dart
Outdated
| // Similar reasoning as in _mentionIntentRegex. | ||
| const before = r'(?<=^|\s|\p{Punctuation})'; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| // As Web, match both '#channel' and '#**channel'. In both cases, the raw | ||
| // query is going to be 'channel'. Matching the second case ('#**channel') | ||
| // is useful when the user selects a channel from the autocomplete list, but | ||
| // then starts pressing "backspace" to edit the query and choose another | ||
| // option, instead of clearing the entire query and starting from scratch. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Interesting. Looks like web also does the corresponding thing for @-mentions: https://github.com/zulip/zulip/blob/1e78447c5/web/src/composebox_typeahead.ts#L516-L531
function filter_mention_name(current_token: string): string | undefined {
if (current_token.startsWith("**")) {
current_token = current_token.slice(2);
} else if (current_token.startsWith("*")) {
current_token = current_token.slice(1);
}
if (current_token.includes("*")) {
return undefined;
}
// Don't autocomplete if there is a space following an '@'
if (current_token.startsWith(" ")) {
return undefined;
}
return current_token;
}This is maybe more important for channel/topic autocomplete, right? Because (once the topic part is implemented) you might backspace as part of figuring out how to get just a channel link without a topic. But this is a good prompt to file an issue and add a TODO for doing this with @-mention autocomplete; would you do those?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, that would be an improvement. I have always missed that feature for @-mentions; filed #1967.
| } else { | ||
| icon = null; | ||
| iconColor = null; | ||
| label = zulipLocalizations.unknownChannelName; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we normally show "(unknown channel)" in italics, to distinguish it from a potential channel with that name.
lib/widgets/autocomplete.dart
Outdated
| padding: EdgeInsetsDirectional.fromSTEB(12, 4, 10, 4), | ||
| child: Row(spacing: 10, children: [ | ||
| SizedBox.square(dimension: 24, | ||
| child: Icon(size: 18, color: iconColor, icon)), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The rows have 44px height in the Figma, but this gives 32px height (unless increased via the device text-size setting).
To bring it up to 44px, we could structure it similarly to MentionAutocompleteItem—
| padding: EdgeInsetsDirectional.fromSTEB(12, 4, 10, 4), | |
| child: Row(spacing: 10, children: [ | |
| SizedBox.square(dimension: 24, | |
| child: Icon(size: 18, color: iconColor, icon)), | |
| padding: EdgeInsetsDirectional.fromSTEB(4, 4, 8, 4), | |
| child: Row(spacing: 6, children: [ | |
| SizedBox.square(dimension: 36, | |
| child: Center( | |
| child: Icon(size: 18, color: iconColor, icon))), |
—which could be helpful in a potential future where we made a generic AutocompleteItem widget that serves both kinds of autocomplete.
lib/model/compose.dart
Outdated
| /// | ||
| /// [fallbackMarkdownLink] will be used if the channel name includes some faulty | ||
| /// characters that will break normal #**channel** rendering. | ||
| String channelLinkSyntax(ZulipStream channel, { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just channelLink, I think; the "syntax" part is implied. (As in existing functions in this file, like quoteAndReply which creates quote-and-reply syntax, or userMention which creates user-mention syntax.)
| /// Markdown link for channel, topic, or message when the channel or topic name | ||
| /// includes characters that will break normal markdown rendering. | ||
| /// | ||
| /// Refer to [_channelTopicFaultyCharsReplacements] for a complete list of | ||
| /// these characters. | ||
| // Corresponds to `topic_link_util.get_fallback_markdown_link` in Zulip web; | ||
| // https://github.com/zulip/zulip/blob/b42d3e77e/web/src/topic_link_util.ts#L96-L108 | ||
| String fallbackMarkdownLink({ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
channel: Finish channel link autocomplete for compose box
Could you separate this special character-replacement logic into its own commit? I want to see if we can ground our reasoning in API documentation. As far as that goes, there's nothing "invalid" or "faulty" about these characters appearing in channel names.
d1abf20 to
acb6615
Compare
|
Thanks @chrisbobbe for the previous review. Pushed a new revision, with some new commits added, PTAL. 65ad611 api: Add InitialSnapshot.maxChannelNameLength (The media in the PR description has also been updated.) |
acb6615 to
513bc80
Compare
|
Ah I see this has gathered some conflicts; would you resolve those please? |
513bc80 to
6d28107
Compare
Right now, this is useful in how far back from the cursor we look to find a channel-link autocomplete (actually any autocomplete) interaction in compose box.
In the following commits, this will be used as one of the criteria for sorting channels in channel link autocomplete.
b654dd1 to
be582cd
Compare
|
Thanks @gnprice for the review. Changes pushed, PTAL. |
gnprice
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! Comments below just on that revision / following up on my first review.
lib/model/channel.dart
Outdated
| for (final channelId in event.channelIds) { | ||
| final channel = streams.remove(channelId); | ||
| if (channel == null) break; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, this condition shouldn't happen, right? It'd mean our state was out of sync with the server.
But if it does happen, it's best to carry on with removing any other channels that were in the list, so we don't get out of sync in a new way.
So two changes:
| for (final channelId in event.channelIds) { | |
| final channel = streams.remove(channelId); | |
| if (channel == null) break; | |
| for (final channelId in event.channelIds) { | |
| final channel = streams.remove(channelId); | |
| if (channel == null) continue; // TODO(log) |
The TODO(log) comment is a marker for when we someday sweep through and add error reporting through Sentry or something like it, so that we can learn about unexpected conditions the client is hitting in the wild.
lib/model/autocomplete.dart
Outdated
| // Check `typeahead_helper.compare_by_activity` in Zulip web; | ||
| // https://github.com/zulip/zulip/blob/c3fdee6ed/web/src/typeahead_helper.ts#L972-L988 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: this is part of the implementation comment, so goes inside the method body
(and really part of the same thought as the paragraph after it, which in this version is inside the method body)
lib/model/autocomplete.dart
Outdated
| // shouldn't be possible — can only compose to one channel at a time | ||
| (true, true) => 0, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The way this would happen is if a and b are the same channel (same .streamId).
Which probably also shouldn't happen here — List.sort shouldn't bother calling its comparator to compare an element to itself, and the list shouldn't have the same channel twice. But that's a pretty nonlocal fact to convince oneself of, which is why this method should go ahead and do the right thing if it happens.
I think simplest to just not comment, and say _ => 0 for both this and the previous case together.
lib/model/autocomplete.dart
Outdated
| static int compareByRecentActivity(ZulipStream a, ZulipStream b) { | ||
| // Compare `stream_list_sort.has_recent_activity` in Zulip web: | ||
| // https://github.com/zulip/zulip/blob/925ae0f9b/web/src/stream_list_sort.ts#L84-L96 | ||
| // There are a few other criteria that Web considers for a channel being | ||
| // recently-active, for which we don't have all the data at the moment, | ||
| // e.g., whether the channel is newly subscribed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool. Can you write down the full list of differences? That's helpful (a) for convincing ourselves we're happy with not handling them now, and (b) for later coming back and filling them in.
For (a) in particular, writing down the list is helpful because the web app's code for autocomplete can get very tangly, and it often takes some work to pin down the full list of things it's considering and how they interact. So it'd be easy to miss something; and once you've done the work to pin down that full list, it's helpful to write it down so the work doesn't have to be repeated the next time you/we want to think about it again.
| static int compareByRecentActivity(ZulipStream a, ZulipStream b) { | ||
| return switch((a.isRecentlyActive, b.isRecentlyActive)) { | ||
| (true, false) => -1, | ||
| (false, true) => 1, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No need to add those in this PR 🙂.
I'd like to have the complete list of differences in a comment in the code, though — or at least the full list of what you're aware of.
There are new changes made to `stream op: delete` event in server-10:
- The `streams` field which used to be an array of the just-deleted
channel objects is now an array of objects which only contains IDs
of the just-deleted channels (the app throws away its event queue
and reregisters before this commit).
- The same `streams` field is also deprecated and will be removed in a
future release.
- As a replacement to `streams`, `stream_ids` is introduced which is
an array of the just-deleted channels IDs.
Related CZO discussion:
https://chat.zulip.org/#narrow/channel/378-api-design/topic/stream.20deletion.20events/near/2284969
So to call AutocompleteViewManager.unregisterEmojiAutocomplete.
…iews` This set replaces the three sets of different `AutocompleteView` subclasses, simplifying the code.
These two methods were introduced but never called.
Also, generalize the dartdoc of NameMatchQuality. For almost all types of autocompletes, the matching mechanism/quality to an autocomplete query seems to be the same with rare exceptions (at the time of writing this —— 2025-11, only the emoji autocomplete matching mechanism is different).
gnprice
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, and here's a review of the tests for that 10th commit:
eeb7ee9 autocomplete: Add view-model ChannelLinkAutocompleteView
I skipped some of the details in the "ranking across signals" tests; I'll look closer after some simplifications mentioned below.
test/model/autocomplete_test.dart
Outdated
| int compareAB(int a, int b, {required int composingToChannelId}) => | ||
| ChannelLinkAutocompleteView.compareByComposingTo( | ||
| eg.stream(streamId: a), eg.stream(streamId: b), | ||
| composingToChannelId: composingToChannelId); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This name doesn't really fit, because the function doesn't compare some existing thing called "A" to an existing thing called "B" — it just compares its two arguments. So "compare" would be an accurate name.
Similarly the helpers below with the same name.
In some of the existing tests in this file, there are helpers with that name, like this one:
int compareAB() => MentionAutocompleteView.compareByDms(
eg.user(userId: idA),
eg.user(userId: idB),
store: store,
);But the point there is that the function's meaning is "compare user A with user B", where the helper and its callers have these shared locals:
const idA = 1;
const idB = 2;that define the meaning of "user A" and "user B".
test/model/autocomplete_test.dart
Outdated
| group('ranking across signals', () { | ||
| store = eg.store(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This creates shared mutable state between the tests. That's a classic source of bugs that can be a pain to diagnose: a test passes when run after some other tests but fails when run alone, or vice versa.
In principle we run that risk already in a lot of our tests by having some shared variables, often called store and/or connection. But the key to making that pattern work is that every test case that uses the shared variables starts by resetting them all to fresh values. That way, whatever changes a previous test case might have made get wiped away and have no effect. As long as we stick to that pattern, we avoid truly having any shared mutable state between tests, and we're safe from that class of bugs.
That resetting from scratch is typically done via a helper function with a name like prepare. In turn, the shared variables are typically declared right next to the function that sets them; that helps make the relationship clear.
If you look back at the group "MentionAutocompleteView sorting results" above in this file, you'll see it's an example of that pattern.
test/model/autocomplete_test.dart
Outdated
| }); | ||
| }); | ||
|
|
||
| group('ranking across signals', () { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's one more signal to test directly first: comparing by name.
That doesn't need to be a detailed test of all the nuances of comparing names (that's what tests for ChannelStore.compareChannelsByName would do) — just check that this code is comparing by name at all.
In particular when reading these across-signals tests, one needs to know that the name is one of the signals in order to understand what these tests are saying.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IIUC, then I think "compare by name" is included in "ranking across signals" tests with the comment "Runner-up by name". 🙂
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, but it's easier to think about when there's a test which focuses on that aspect. The "ranking across signals" tests have a lot of other stuff going on.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ohh, so that means a standalone test for "compare by name". Ok, that make sense.
test/model/autocomplete_test.dart
Outdated
| final channels = [ | ||
| // Wins by being the composing-to channel. | ||
| eg.stream(streamId: 1, name: 'Z'), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In order to properly make the point, this needs to also be not recently active, and have zero (or null) weekly traffic.
Otherwise, it might be beating some of the other channels for one or more of those other reasons, rather than because it's the composing-to channel.
See the comment on the similar pattern above in this file:
test('TopicNarrow: topic recency > stream recency > DM recency > human/bot > name', () async {
// The user with the greatest topic recency ranks last on each of the
// other criteria, but comes out first in the end, showing that
// topic recency comes first. Then among the remaining users, the one
// with the greatest stream recency ranks last on each of the remaining
// criteria, but comes out second in the end; and so on.
test/model/autocomplete_test.dart
Outdated
| // Runner-up by being unmuted pinned. | ||
| eg.subscription(eg.stream(streamId: 2, name: 'Y'), isMuted: false, pinToTop: true), | ||
| // Runner-up by being unmuted unpinned. | ||
| eg.subscription(eg.stream(streamId: 3, name: 'X'), isMuted: false, pinToTop: false), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Similarly, the first runner-up should be unmuted but have everything else working to rank it at the end (except in comparison to the winner). That way we can tell from reading the test that "unmuted" beats all the other criteria, except for "composing to".
(And we only need one unmuted channel in this list. The fact that pinned beats unpinned was covered in one of the test cases above.)
test/model/autocomplete_test.dart
Outdated
| eg.subscription(eg.stream(streamId: 5, name: 'V'), isMuted: true, pinToTop: false), | ||
|
|
||
| // The rest are runners-up by not being subscribed to. | ||
| // Runner-up by being recently active. | ||
| eg.stream(streamId: 6, name: 'U', isRecentlyActive: true), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we need these channel/stream IDs? I think we can simplify by leaving them out.
In particular, it looks like the only one we actually use is the one for the composing-to channel. And we could get that one like channels[0].streamId.
test/model/autocomplete_test.dart
Outdated
| final channels = [ | ||
| // Next four are runners-up by being subscribed to. | ||
| // Runner-up by being unmuted pinned. | ||
| eg.subscription(eg.stream(streamId: 1, name: 'Y'), isMuted: false, pinToTop: true), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This one is the winner, not the runner-up 🙂
test/model/autocomplete_test.dart
Outdated
| }); | ||
|
|
||
| group('ChannelLinkAutocompleteQuery', () { | ||
| test('testChannel: channel is included if name words match the query', () { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking at the corresponding tests for user mentions, there's this:
test('user is always excluded when not active regardless of other criteria', () {That gives me the thought that we should probably be doing something similar here: excluding channels with isArchived: true.
Does web lack that behavior? If so then that'd be another difference to note in the comment that compares our behavior to web's (similar to the existing example of such a comment which I mentioned earlier).
| doCheck('Four C', eg.stream(name: 'Channel Name Four Words'), false); | ||
| }); | ||
|
|
||
| group('ranking', () { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
At the end of this group, I'd like to also include the "full list of ranks" type of test case, similar to our tests for other types of autocomplete. It's helpful for seeing a global view of the ranking.
For this one it'll be quite short — that means we could do pretty OK without it, but also means it's cheap to include. And by including it, we'll help make sure that we include such a test case if we later extend this ranking and make it more complex, so that that test case becomes more necessary.
be582cd to
accc796
Compare
|
Thanks for the review. New revision pushed. |
As of this commit, it's not yet possible in the app to initiate a channel link autocomplete interaction. So in the widgets code that would consume the results of such an interaction, we just throw for now, leaving that to be implemented in a later commit.
This way, subclasses can use the reference to the store for different purposes, such as using `max_topic_length` for the topic length instead of the hard-coded limit of 60, or using `max_stream_name_length` for how far back from the cursor we look to find a channel-link autocomplete interaction in compose box.
For this commit we temporarily intercept the query at the AutocompleteField widget, to avoid invoking the widgets that are still unimplemented. That lets us defer those widgets' logic to a separate later commit.
This will make it easy to use the fragment string in several other places, such as in the next commits where we need to create a fallback markdown link for a channel.
accc796 to
020c2bd
Compare
|
(Pushed with the test mentioned in #1902 (comment) included.) |
gnprice
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the revision! Comments below on those same first 10 commits.
| group('ranking', () { | ||
| // This gets filled here at the start of the group, but never reset. | ||
| // We're counting on this group's tests never doing anything to mutate it. | ||
| store = eg.store(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This comment isn't right, because this is setting the store local that was declared in the outer group. That one gets overwritten in that group's other tests above.
In general it's best if the code outside of test cases (outside of test bodies) never creates large objects like instances of PerAccountStore. This code is declaring the tests, not part of running any specific test, so it runs unconditionally even when you use --name to filter down which tests run.
Hence why the "MentionAutocompleteQuery ranking" group (a) declares its own store local, (b) leaves it to be initialized lazily by a test case.
| group('compareChannelsByName', () { | ||
| int compare(String a, String b) => ChannelStore.compareChannelsByName( | ||
| eg.stream(name: a), eg.stream(name: b)); | ||
|
|
||
| test("favor channel with name coming first", () async { | ||
| check(compare('announce', 'backend')).isLessThan(0); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(cont'd from #1902 (comment))
This is a test for ChannelStore.compareChannelsByName. But it still doesn't test that the channel-link autocomplete code ever actually compares by name 🙂
There should be a test here that would fail if this line in the implementation:
return ChannelStore.compareChannelsByName(a, b);were removed (replaced with return 0;).
Conversely there's no need for this test. That's the job of tests in channel_test.dart.
| // The composing-to channel ranks last on each of the other criteria, | ||
| // but comes out first in the end, showing that composing-to channel | ||
| // comes first. Then among the remaining channels, the subscribed ones | ||
| // rank last on each of the remaining criteria, but comes out top | ||
| // in the end; and so on. | ||
| final channels = [ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool, this structure looks right.
| // in the end; and so on. | ||
| final channels = [ | ||
| // Wins by being the composing-to channel. | ||
| eg.stream(name: 'Z', isRecentlyActive: false, streamWeeklyTraffic: null), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This null case for traffic feels like kind of an odd edge case. I think this test would be simpler to think about if those null values were all replaced with 0 — it's clear that a channel with zero traffic should rank last on the traffic criterion.
| // Runner-up by having weekly traffic defined. | ||
| eg.stream(name: 'T', isRecentlyActive: false, streamWeeklyTraffic: 10), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And "weekly traffic defined" isn't really a criterion we use in the ranking — we're treating null equivalent to zero, after all. So I think this item can be dropped from the list.
gnprice
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, and here's a review of the next 3 commits:
7f03226 autocomplete test [nfc]: Use MarkedTextParse as the return type of parseMarkedText
6b2ef9c compose: Introduce PerAccountStore in ComposeController
ed7fda0 autocomplete: Identify when the user intends a channel link autocomplete
That leaves 5 commits still for the future:
c638335 autocomplete [nfc]: Add a TODO(#1967) for ignoring starting "**" after "#"
3d2b974 autocomplete test: Make setupToComposeInput accept channels param
1715d1b internal_link [nfc]: Factor out constructing fragment in its own method
36229c7 compose: Introduce fallbackMarkdownLink function
020c2bd channel: Finish channel link autocomplete for compose box
A couple of the more interesting comments below are about the autocompleteIntent tests. Please revise those tests to try to apply those points more generally: think through the user-facing behavior we're aiming to achieve and think of various cases where a lower-quality implementation might get an answer that's wrong from the user perspective, then write the test cases and comments to reflect those.
For examples of that structure, see the emoji tests below these tests. E.g. these are all about user-facing situations and reasons why users would want one behavior vs. another:
// Avoid interpreting colons in normal prose as queries.
// …
// Avoid interpreting already-entered `:foo:` syntax as queries.
// …
// Avoid interpreting emoticons as queries.(I think the tests for @-mentions above these are also designed that way — but they don't have comments narrating the story, so it's a bit harder to see that. The narrative is helpful.)
| _update(); | ||
| } | ||
|
|
||
| PerAccountStore store; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit:
compose: Introduce PerAccountStore in ComposeController
Instead can say:
compose: Move PerAccountStore up to ComposeController
That reflects the fact that although this commit adds a PerAccountStore reference on ComposeController, there already was one on the ComposeTopicController subclass.
That in turn helps reassure the reader by diminishing the scope of what's changing. When I see "introduce PerAccountStore", I have to worry: hmm, is that reference going to go out of date? Should we be doing something else to avoid keeping such a reference around? IOW, the sort of concerns that @chrisbobbe raised above at #1902 (comment) 🙂
When the verb is instead "move", though, then that's reassuring because it means that if there is such a problem it's not entirely a new problem. Also that we likely have some logic (as it turns out we do, per that thread) for dealing with the problem already, which hopefully resolves it (as indeed I think it does here).
In general, it's reassuring to have a given change be smaller rather than larger. So when you can write the commit message to clarify that's the case, with verbs like "move" or "extract" rather than "introduce" or "add", that's helpful.
|
|
||
| extension ComposeContentAutocomplete on ComposeContentController { | ||
| int get _maxLookbackForAutocompleteIntent { | ||
| return 1 // intent character e.g., "#" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit:
| return 1 // intent character e.g., "#" | |
| return 1 // intent character, e.g. "#" |
| // To avoid spending a lot of time searching for autocomplete intents | ||
| // in long messages, we bound how far back we look for the intent's start. | ||
| final earliest = max(0, selection.end - 30); | ||
| final earliest = max(0, selection.end - _maxLookbackForAutocompleteIntent); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: This comment should move to _maxLookbackForAutocompleteIntent, as it's basically explaining what that's about.
| // Also, make sure that the remaining query doesn't contain '**', | ||
| // otherwise '#**channel**' (which is a complete channel link syntax) and | ||
| // any text followed by that will always match. | ||
| + r'\*\*(?!\s)((?:(?!\*\*).)*)' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, I worry this would be slow: it's doing lookahead ((?!…)) at every point in the string.
How about this version?
| + r'\*\*(?!\s)((?:(?!\*\*).)*)' | |
| + r'\*\*(?!\s)((?:[^*]|\*[^*])*)' |
| // and typing "@#user" for the mention query "#user", because in 2025-11 | ||
| // channel and user name words can start with "#". (They can also contain "#" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit:
| // and typing "@#user" for the mention query "#user", because in 2025-11 | |
| // channel and user name words can start with "#". (They can also contain "#" | |
| // and typing "@#user" for the mention query "#user", because as of 2025-11 | |
| // channel and user name words can start with "#". (They can also contain "#" |
Otherwise it sounds like you're suggesting it was different before, or will be different later. With "as of", it means it's this way now and you're just not saying anything about other times. The code is effectively presuming it's that way at all times.
| // #channel link. | ||
|
|
||
| doTest('^#', null); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: put tests in same order as the code they test: @-mentions vs #-mentions vs emoji.
| // "#" sign can be (3 + 2 * maxChannelName) utf-16 code units | ||
| // away to the left of cursor. | ||
| doTest('If ~@chris^ is around, please ask him.', mention('chris'), maxChannelName: 10); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This comment doesn't agree with the code — there's no "#".
| doTest(' ~#abc^', channelLink('abc')); | ||
| doTest('xyz ~#abc^', channelLink('abc')); | ||
|
|
||
| // Accept punctuations before channel link syntax. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit:
| // Accept punctuations before channel link syntax. | |
| // Accept punctuation before channel link syntax. |
"Punctuation" is a mass noun, like "water".
| // Allow all other sorts of characters in query. | ||
| doTest('~#\u0000^', channelLink('\u0000')); // control | ||
| doTest('~#\u061C^', channelLink('\u061C')); // format character | ||
| doTest('~#\u0600^', channelLink('\u0600')); // format | ||
| doTest('~#\uD834^', channelLink('\uD834')); // leading surrogate |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yuck. Are these really desirable? 🙂
We don't need to add logic to exclude these cases; I don't think they're important. But I'd like these tests to focus on the behavior we actually want, not on the behavior that our implementation happens to have by accident. That way we're not spending attention on thinking about these cases either in the implementation or the tests.
| // Two leading stars ('**') in the query are omitted. | ||
| doTest('~#**^', channelLink('')); | ||
| doTest('~#**abc^', channelLink('abc')); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Similarly, the description of these test cases is focused on the logic in the implementation, and I'd like to instead focus on the user-facing goal which we want this code to accomplish and which this test verifies it accomplishes. Like this:
| // Two leading stars ('**') in the query are omitted. | |
| doTest('~#**^', channelLink('')); | |
| doTest('~#**abc^', channelLink('abc')); | |
| // Accept syntax like "#**foo" (as from the user finishing an autocomplete | |
| // and then hitting backspace to edit it), but leave the "**" out of the query. | |
| doTest('~#**^', channelLink('')); | |
| doTest('~#**abc^', channelLink('abc')); |
Fixes-partly: #124 (topic link autocomplete will be its own PR)
Screenshots
Screen recording
Channel.autocomplete.recording.mov