Page MenuHomePhabricator

Provide a mechanism for in-surface autocomplete
Open, Needs TriagePublic

Description

Currently there is no way to provide autocomplete suggestions while the user is typing directly in the document. This technique is commonly used for '@' mentions:

Phabricator (desktop)Twitter (mobile)

The lack of this feature has led to a workaround in Flow which uses an inspector triggered by an '@' sequence, but this results in a clunky user experience, and bugs such as T147408:

Guiding principles

The design we implement should increase the likelihood of the following two things being true:

  1. The username results list makes it possible for people to quickly and easily find the person they are wanting to notify.
  2. The username results list makes it clear to people how to find the username of someone who is not currently shown.

Requirements

This section describes how the first iteration of this feature should function.

  • When someone types @ , the username completion list should show the usernames of the people who have commented in the section where the reply is being drafted.
    • The usernames in the results list will be sorted alphabetically.
    • Usernames will appear in the username results list exactly as they appear in the database not as they appear in the page. Meaning, if someone has a custom signature (read: alias) such that the username that is appended to the comments they post on talk pages [1] is different from the username that appears in the link to their user page [2], their alias will not show up in the username results list.
    • We will explore making it so aliases appear in the username completion list in this task: T250329.
  • The moment someone types @ + any other character, the username results list will return results (read: usernames) of the registered users on the wiki that resemble the username the person invoking auto-complete has typed.
    • Meaning, the suggestion list will start returning results as soon as people start typing and the list of results will update dynamically without needing to wait for a full-word match to be made.
    • Example: Typing @pe should return "peter", but not "snape"
    • We will explore implementing more robust search functionality in this task: T250334.
  • People can select a username from the username results list in either of the following ways:
    • Use arrow keys ( or ) to highlight the specific person + press enter to complete selection
    • Use mouse to highlight the specific person + click to complete selection
    • Note: we are limiting selections to explicit actions (e.g. enter or mouse click) because username conventions (e.g. spaces) make it difficult to correctly assume when the software should stop searching for matches.
  • When you select a username from the username results list, the following will show up in the reply text input:
    • Link: link to selected user's user page
    • Display text: @ + selected user's username (the display text should be the same as what is shown in the username results list.)
    • Here is the task for exploring whether this behavior should be configurable: T250332.
  • When you select a username from the username results list for someone who has not yet created a user page, their username will appear as a red link both when the comment is being drafted and when the comment is published to the talk page.
    • In source, people will see the red-linked username in the preview; in visual, people will see it in the text input area
    • Whether or not someone has created a user page should not affect whether they receive a notification or not.
  • When a comment is posted containing a valid link(s) to other user pages, those "mentioned users" should receive an "Alert" in the format described in Help:Notifications/Types#Mentions
  • The username completion list should be dismissed and typed text remain in place when:
    • escape is pressed
    • space is pressed immediately after typing @
  • People should be able to trigger a ping when they type an exact match
    • Where "exact match" means: @exactusername<space>

Open questions

  • 1. What are the different ways the in-surface picker can be initiated (typing @, clicking the "👤" in the Visual mode's toolbar, etc.)
    • Per T232601#6091882, in the initial version, there will be one way to initiate the username suggestion list: typing @. Read: there will not be a "👤" or analogous icon in the visual mode toolbar to start.
  • 2. What should the username picker look like? How should it be have (e.g. how should results be populated?)?
    • Creating the UI will happen in: T251478; how the username suggestion list should behave is described in "Requirements" (above).
  • 3. What is going to be inserted into the page once a user is "picked" (e.g. a template like {{FlowMention:NAME|NAME}}, link to their user page [[User:NAME|NAME]] )
    • Per T232601#5960614, currently a link to the person being mentioned's user page is inserted. In the future, we will consider enabling wikis to customize this behavior. That work would happen in: T250332.
  • 4. When @ is typed, should the username completion list show the username of people who have commented in other sections on the page?
    • No. When @ is typed, the username completion list should show the usernames of the people who have commented in the section where the reply is being drafted. Thinking: T232601#6073976.
  • 5. Will you be able to ping/@-mention people who have not created user pages?
    • Yes and their username will appear as a red link. See T232601#6073962 for details.
  • 6. Will the whitespace the tool can add to the page (e.g. T249958) affect its ability to send pings?
    • We do not think it will.

  1. Notice how this person's signature renders on this talk page as קיפודנחש (aka kipod)
  2. Notice how the username that appears in the link to their user page is קיפודנחש

Related Objects

StatusSubtypeAssignedTask
OpenNone
OpenNone
Resolvedppelberg
Resolvediamjessklein
ResolvedWhatamidoing-WMF
Resolvedppelberg
Resolvedppelberg
ResolvedEsanders
Resolvediamjessklein
OpenNone
OpenNone
OpenDLynch
Openppelberg
Openppelberg
OpenNone
Resolvediamjessklein
Openiamjessklein
ResolvedEsanders
OpenEsanders
OpenNone
OpenDLynch
ResolvedEsanders
ResolvedEsanders
OpenNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Change 540436 had a related patch set uploaded (by DLynch; owner: DLynch):
[VisualEditor/VisualEditor@master] [WIP] Completion framework

https://gerrit.wikimedia.org/r/540436

Change 540437 had a related patch set uploaded (by DLynch; owner: DLynch):
[mediawiki/extensions/VisualEditor@master] [WIP] Username autocomplete via completion framework

https://gerrit.wikimedia.org/r/540437

Change 550897 had a related patch set uploaded (by DLynch; owner: DLynch):
[mediawiki/extensions/VisualEditor@master] [WIP] Username completion action, split out

https://gerrit.wikimedia.org/r/550897

That last patch is a not-to-be-merged-but-useful-to-exist-for-testing one. The actual username completion will exist over in DiscussionTools, but that's not actually in a state where it's easy to use yet.

Change 570514 had a related patch set uploaded (by DLynch; owner: DLynch):
[mediawiki/extensions/DiscussionTools@master] WIP: @Username completion in VE mode

https://gerrit.wikimedia.org/r/570514

The current patch puts the autocomplete list right under the cursor's bounding box:

This is pretty tight, so we should some a top margin (0.5em?) as seen in Phab:

This is pretty tight, so we should some a top margin (0.5em?) as seen in Phab:

Mm, I do agree. I've updated the patch with a top margin 0.5ex, which looked better to me than 0.5em:

(This hasn't yet had any design refinement done by @iamjessklein, so as-is it's utterly standard OOUI components with no CSS customization at all.)

Change 540436 merged by jenkins-bot:
[VisualEditor/VisualEditor@master] Completion framework

https://gerrit.wikimedia.org/r/540436

Change 540437 merged by jenkins-bot:
[mediawiki/extensions/VisualEditor@master] Update VE core submodule to master (e1760b7f7)

https://gerrit.wikimedia.org/r/540437

Esanders added a subscriber: Ed.Feb 7 2020, 1:45 AM
  1. We appear to not include exact matches in the result list, nor do we do anything special with an exact match. This means if I type "@Ed" to metion user:ed, I get no options
  2. If I type one or more spaces after an exact match (e.g. "@Ed<space>") the autocomplete list re-appears. I initially claimed that typing a space should kill the autocomplete feature, but given that usernames can contain spaces this becomes more complicated, especially if we start including API results in the autocomplete. We may have to introduce logic to stop searching as soon as we get a combined results list (local + API) of zero results.
DLynch added a comment.Feb 7 2020, 2:54 AM

@Esanders: I'm actually not sure what's going on there with 1. For me, locally, exact matches are working just fine. See:

That said, I see 2. I think I recently broke that with some when-should-I-stop changes.

Esanders added a subscriber: admin.Feb 7 2020, 7:03 PM

Yes, but if you type "@admin" all the results go away. This line in the filter is responsible:

return word.slice( 0, input.length ) === input && word !== input;

We should just remove word !== input.

Change 570946 had a related patch set uploaded (by DLynch; owner: DLynch):
[VisualEditor/VisualEditor@master] Completion: bugs related to the current input

https://gerrit.wikimedia.org/r/570946

matmarex moved this task from To Triage to Triaged on the VisualEditor board.Feb 12 2020, 5:24 PM
ppelberg added a comment.EditedFeb 27 2020, 6:21 PM

Notes from 27-Feb standup

@dchan: we need to think now about how this feature might be extended.

  • If scope of feature is limited to @ this should be fine
  • Concerns arise if we are intending to generalize the auto-complete to use cases that do not require someone to explicitly "ask" for it to be invoked? E.g. Gmail's sentence auto-complete
  • If we are intending for the auto-complete to "always" be triggered by a special character (e.g. /), we might not need to worry about IME compatibility issues.

Meeting notes: 10-March

Documenting the questions Ed, Jess and I talked about that are needing to be answered:

  • 1. What are the different ways the in-surface picker can be initiated (typing @, clicking the "👤" in the Visual mode's toolbar, etc.)
  • 2. What should the username picker look like? How should it be have (e.g. how should results be populated?)?
  • 3. What is going to be inserted into the page once a user is "picked" (e.g. a template like {{FlowMention:NAME|NAME}}, link to their user page [[User:NAME|NAME]] )
ppelberg updated the task description. (Show Details)Mar 11 2020, 3:44 PM
Restricted Application added a subscriber: Liuxinyu970226. · View Herald TranscriptMar 11 2020, 3:44 PM

Current behaviors for reference:

  1. just @ triggers it.
  2. screenshots higher on the page are still accurate, it's entirely stock OOUI styles for a list menu. It's populated by scanning existing usernames on the page (and then alphabetically sorting them).
  3. inserts the userpage link, but I've been meaning to make that customizable per-wiki. I figure that either a config value or a specific imported JSON page (akin to how we handle citoid config) would work -- it just needs to be a string that has a username substituted in, after all, unless you can think of any other data that might need to be imported.

Following up on notes from 27-Feb

Considering our plans for auto-complete are limited to use cases that require someone to explicitly "ask" for it to be invoked (e.g. typing @ or typing /) I think we can safely ignore IME compatibility issues, at least in the context of what we were discussing here: T232601#5924225

@dchan, if you think differently, please let me know.

In planning @DLynch and @ppelberg discussed this and it was decided we want to suggest users who have commented on the page, before falling back to searching the entire database of users.

ppelberg added a subscriber: Pbsouthwood.EditedApr 15 2020, 1:17 AM

Update: 14-April
What follows is a description of the approach to @ mentioning we've implemented so far ("Current implementation"), the improvements we would like to make to it ("Improvements to current implementation"), the guiding principles ("Guiding principles") that informed these two things.

Before I update the task description to include what's below, @DLynch, @Esanders and @iamjessklein can you please review what I am describing here to ensure it matches up with what you left this morning's meeting thinking?


Guiding principles
The design we implement should increase the likelihood of the following two things being true:

  1. The username results list makes it possible for people to quickly and easily find the person they are wanting to notify.
  2. The username results list makes it clear to people how to find the username of someone who is not currently shown.

Current implementation
The current implementation attempts to satisfy the "Guiding principles" above in the following ways:

  • When someone types @, they will see the username results list, populated with the usernames of the people who have already commented anywhere on the talk page they are viewing. The usernames in the results list will be sorted alphabetically.
    • Note: usernames will appear in the username results list exactly as they appear on the page. Meaning, if someone has a custom signature such that the username that is appended to the comments they post on talk pages [1] is different from the username that appears in the link to their user page [2], their alias will show up in the username results list. Pings to aliases will work the same way they do for non-aliases.[3]
  • The moment someone types @ + any other character, the username results list will return results (read: usernames) of the registered users on the wiki that resemble the username the person invoking auto-complete has typed.
    • Note: the username results list currently depends on "prefix matching." Meaning, the suggestion list will start returning results as soon as people start typing and the list of results will update dynamically without needing to wait for a full-word match to be made.
  • When you select a username from the username results list, a link to said person's userpage will be inserted in their comment, regardless of whether or not they have an alias set. The display text for the link should be the same as what is shown in the username results list. Which, in this case, is their alias.

Improvements to current implementation

  • ADD support for people to be able to search for aliases.
    • Note: the software would only be able to return results for aliases that appear on the talk page where the "username results list" is being invoked.
  • ADD support to enable wikis to customize what is inserted into the reply once a username is selected from the username results list.
    • This work will happen in this task: #todo: @ppelberg add task
  • ADD more robust search (@Esanders can you add details here? I don't recall precisely what you had mentioned...)

  1. Notice how this person's signature renders on this talk page as קיפודנחש (aka kipod)
  2. Notice how the username that appears in the link to their user page is קיפודנחש
  3. @Pbsouthwood, thank you for leading us to think about this use case.

Note: usernames will appear in the username results list exactly as they appear on the page. Meaning, if someone has a custom signature such that the username that is appended to the comments they post on talk pages [1] is different from the username that appears in the link to their user page [2], their alias will show up in the username results list. Pings to aliases will work the same way they do for non-aliases.[3]

Incorrect -- the only thing that appears in the completion list at the moment is the username that the signature links to. (I.e. the text of the link doesn't matter, just the URL it points to.)

Pings to aliases will work the same way they do for non-aliases.[3]

Only in the sense that so long as they get translated down to a link to the real username (which we don't currently do), they'll get picked up as a ping by Echo. Attempting to write @alias isn't going to do what the user expects in the current implementation.

The display text for the link should be the same as what is shown in the username results list. Which, in this case, is their alias.

But not in the current implementation.

ADD support for people to be able to search for aliases.

I thought the outcome of the meeting was that we weren't going to do this unless it came up as an issue in practice that people complained about? If we're going to do it, there's a few behavior / UI questions we need to work out first.

  • What if a custom signature and a real username collide?
  • What if multiple people on a page have the same alias?
  • Will it confuse the user if they pick @alias in the dropdown and what's output in the wikitext is [[User:RealName]]?
  • Do we indicate alias-status in the completion dropdown?
  • Will it confuse the user that completion of some names only works on some pages for inscrutable reasons?
  • Do we assume everything that links to a user-page is intended as an alias?

Note: usernames will appear in the username results list exactly as they appear on the page. Meaning, if someone has a custom signature such that the username that is appended to the comments they post on talk pages [1] is different from the username that appears in the link to their user page [2], their alias will show up in the username results list. Pings to aliases will work the same way they do for non-aliases.[3]

Incorrect -- the only thing that appears in the completion list at the moment is the username that the signature links to. (I.e. the text of the link doesn't matter, just the URL it points to.)

Pings to aliases will work the same way they do for non-aliases.[3]

Only in the sense that so long as they get translated down to a link to the real username (which we don't currently do), they'll get picked up as a ping by Echo. Attempting to write @alias isn't going to do what the user expects in the current implementation.

The display text for the link should be the same as what is shown in the username results list. Which, in this case, is their alias.

But not in the current implementation.

Roger that. I created T250329 to implement all that's described above.

@DLynch, please let me know if you think anything needs to be made more clear there.

ADD support for people to be able to search for aliases.

I thought the outcome of the meeting was that we weren't going to do this unless it came up as an issue in practice...

You're right. Let's hold off on this for now.

  • ADD support to enable wikis to customize what is inserted into the reply once a username is selected from the username results list.
    • This work will happen in this task: #todo: @ppelberg add task

See: T250332

ppelberg added a comment.EditedApr 16 2020, 12:42 AM
  • ADD more robust search (@Esanders can you add details here? I don't recall precisely what you had mentioned...)

During this morning's meeting Ed outlined the different approaches we could take to make search more robust.

These options are explained in detail in this task: T250334.


For context, we have currently implemented the following approach:
Current implementation: pre-fix search

  • Typing @pe would return "peter`, but not "snape"
ppelberg updated the task description. (Show Details)Apr 16 2020, 12:55 AM
ppelberg updated the task description. (Show Details)Apr 16 2020, 1:00 AM

Updates from today's conversation with @Esanders and @iamjessklein...

5. Will you be able to ping/@-mention people who have not created user pages?
Yes and their username will appear as a red link both when the comment in being drafted [i] and when the comment is published to the talk page.

We will revisit this behavior if/when people are confused by it.


i. in source, people will see the red-linked username in the preview; in visual, people will see it in the text input area

4. When @ is typed, should the username completion list show the username of people who have commented in other sections on the page?
Initially, no. When @ is typed, the username completion list should show the usernames of the people who have commented in the section where the reply is being drafted.

  • Rationale: we assume it is most likely for people to want to ping someone who has already participated in the conversations they are replying in and broadening the definition of which usernames are initially included in the username suggestion list could make it less "quick" and "easy" for people to find the person they are wanting to notify.
ppelberg updated the task description. (Show Details)Apr 21 2020, 1:24 AM
ppelberg updated the task description. (Show Details)Apr 29 2020, 1:09 AM

What are the different ways the in-surface picker can be initiated (typing @, clicking the "👤" in the Visual mode's toolbar, etc.)

During the meeting @Esanders, @iamjessklein and I had on 27-April, we came to think that in the initial version, there will be one way to initiate the username suggestion list: typing @.

Read: there will not be a "👤" or analogous icon in the visual mode toolbar to start.

  • Reasoning: we assume that typing @ is a known design pattern/convention that does not need to be visually communicated in the interface.
  • Caveat: at least one person has mentioned something counter to the above. [i] They have said it not being intuitive that the @ is magic considering they, and potentially others, are used to typing {{ and [[ to trigger interactive functionality, not @.
  • Next step: if the @ ends up not being intuitive, we will explore interventions to make it more so in this task: ADD TASK.

i. https://www.mediawiki.org/w/index.php?title=Topic:Vju7lfcav875rt8r&topic_showPostId=vkpxssh1ty6lue6t#flow-post-vkpxssh1ty6lue6t

ppelberg updated the task description. (Show Details)Apr 29 2020, 1:24 AM
ppelberg updated the task description. (Show Details)Apr 29 2020, 2:34 AM
ppelberg updated the task description. (Show Details)
ppelberg updated the task description. (Show Details)
ppelberg added a comment.EditedApr 29 2020, 2:37 AM

Will the whitespace the tool can add to the page (e.g. T249958) affect its ability to send pings?

Per the conversation Ed and I had on 21-April, we do not think the issue described in T249958, or others like it (e.g. T250184), will interfere with pings/notifications being sent.

The above is represented in the task description.

What will happen if you want to use @ for another reason? Email addresses are the obvious example, but there could be others too.

@Pbsouthwood Right now it'll show the popup as you're typing the email address -- I've been meaning to have it not trigger if there's a non-whitespace character immediately before the @, but haven't done so yet. Fortunately, the popup triggering doesn't inherently do/insert anything, so you can just keep typing and ignore it and it'll go away.

ppelberg updated the task description. (Show Details)Apr 30 2020, 2:18 AM
ppelberg updated the task description. (Show Details)EditedApr 30 2020, 5:20 AM

Open questions

  • 2. What should the username picker look like? How should it be have (e.g. how should results be populated?)?

Creating the UI will happen in: T251478.

How the username suggestion list should behave is described in "Requirements" (task description).

All of the above is now reflected in the task description.

Change 570514 merged by jenkins-bot:
[mediawiki/extensions/DiscussionTools@master] @Username completion in VE (source or visual) mode

https://gerrit.wikimedia.org/r/570514

Change 550897 abandoned by Bartosz Dziewoński:
[WIP] Username completion action, split out

Reason:
Superseded by https://gerrit.wikimedia.org/r/570514

https://gerrit.wikimedia.org/r/550897

Change 570946 merged by jenkins-bot:
[VisualEditor/VisualEditor@master] Completion: bugs related to the current input

https://gerrit.wikimedia.org/r/570946

Change 608317 had a related patch set uploaded (by Bartosz Dziewoński; owner: Bartosz Dziewoński):
[mediawiki/extensions/VisualEditor@master] Update VE core submodule to master (4e1435871)

https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VisualEditor/ /608317

Change 608317 merged by jenkins-bot:
[mediawiki/extensions/VisualEditor@master] Update VE core submodule to master (4e1435871)

https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VisualEditor/ /608317

@ppelberg to disassociate the non-blocking tasks and close