Seems like a reasonable request, although likely no one on the team will be able to get to it anytime soon. We'd be open to reviewing patches if someone wants to try and contribute one though. 

The following revision refers to this bug:
  https://chrome-internal.googlesource.com/chromeos/chromeos-admin/+/3c336dcee117503acee10db6b3bf241b67af1eae

commit 3c336dcee117503acee10db6b3bf241b67af1eae
Author: Paul Hobbs <phobbs@google.com>
Date: Tue Sep 06 18:53:32 2016

This issue has been Available for over a year. If it's no longer important or seems unlikely to be fixed, please consider closing it out. If it is important, please re-triage the issue.

Sorry for the inconvenience if the bug really should have been left as Available. If you change it back, also remove the "Hotlist-Recharge-Cold" label.

For more details visit https://www.chromium.org/issue-tracking/autotriage - Your friendly Sheriffbot

Adding omnibox label so we are aware of this effort as it proceeds.

I see I was sent a changelist.  It's hard for me to review the change without clear documentation of what the feature entails.

What's the intended semantics of when onKeywordEntered will be called?  Is there documentation about it?  How is this different than the existing API onInputStarted ("User has started a keyword input session by typing the extension's keyword. This is guaranteed to be sent exactly once per input session, and before any onInputChanged events.")

If it's different, then when will it be called?
* on the first time the user entered keyword mode for this keyword during a particular omnibox edit session or every time?  For example, if I enter keyword mode, press backspace to leave it, then enter it again, should it be called again?
* should it be called if I have an omnibox-edit-in-progress with that keyword on a tab, I switch tabs, and then I switch back? (The omnibox remembers the keyword state and the fact that it has focus.)
* should it be called only upon entering keyword mode with no additional text (and hence the extension would not normally be notified) or can be it be called when entering keyword mode and I have text.  For example, if I have an extension with the keyword "ssh" and I type "sshfoo" in the omnibox, then press the space between "ssh" and "foo" to enter keyword mode.  Should that cause an onKeywordEntered call or not?  This will also trigger an onInputChanged() call.  Should there be a guarantee about the ordering of these two calls?

Answering questions inline below.

> How is onKeywordEntered different than the existing API onInputStarted? If it's different, then when will it be called?

onInputStarted fires right after the first *input* is entered. For example, if the keyword is "key", then onInputStarted would fire at "key i", where "i" is the starting input. onKeywordEntered would fire as soon as "key" is entered. 

Another difference between onInputStarted and onKeywordEntered is that onKeywordEntered would be able to surface suggestion matches/results specified by the extension developer. onInputStarted does not permit customized suggestions; this can only be done via onInputChanged.

> on the first time the user entered keyword mode for this keyword during a particular omnibox edit session or every time?  For example, if I enter keyword mode, press backspace to leave it, then enter it again, should it be called again?

Every time. If the user is entering keyboard mode multiple times in a single omnibox edit session, then for consistency onKeyboardEntered should be called each time.
 
Do you foresee any downsides to this approach?

> should it be called if I have an omnibox-edit-in-progress with that keyword on a tab, I switch tabs, and then I switch back? (The omnibox remembers the keyword state and the fact that it has focus.)

I think we should match existing omnibox behavior. For example, for onInputChanged, if the there is an omnibox-edit-in-progress and you switch tabs and then switch bach, the omnibox remembers the keyword state and is still in focus. The suggestion results are no longer shown. We should do the same for onKeywordEntered.

> should it be called only upon entering keyword mode with no additional text (and hence the extension would not normally be notified) or can be it be called when entering keyword mode and I have text.  For example, if I have an extension with the keyword "ssh" and I type "sshfoo" in the omnibox, then press the space between "ssh" and "foo" to enter keyword mode.  Should that cause an onKeywordEntered call or not?  This will also trigger an onInputChanged() call.  Should there be a guarantee about the ordering of these two calls?

Similar to the previous question, I think we should match existing omnibox behavior. If we consider the case of "sshfoo" => "ssh foo", onInputStarted is called first. Its callback parameter |text| is undefined. Then onInputChanged is called, and its callback parameter |text| is "foo". If we were to add onKeyboardEntered in this situation, the sequence of calls should be: onKeyboardEntered, onInputStarted, and onInputChanged.

So to directly answer your question, onKeyboardEntered can be called in both the situations that you specified above: when there is no additional text and when there is text (e.g. "sshfoo" => "ssh foo"). In the latter situation, we would enforce an ordering such that onKeyboardEntered precedes onInputChanged.

Note that if onKeyboardEntered has search suggestions, they could be overridden (removed and replaced with) by the search suggestions posed by onInputChanged. Alternatively, onKeyboardEntered's search suggestions could persist, and onInputChanged search suggestions would simply be added to the set. wdyt? Any preference?

>  If the user is entering keyboard mode multiple times in a single omnibox
> edit session, then for consistency onKeyboardEntered should be called
> each time.
>
> Do you foresee any downsides to this approach?
No.

> I think we should match existing omnibox behavior. For example, for
> onInputChanged, if the there is an omnibox-edit-in-progress and you switch
> tabs and then switch back, the omnibox remembers the keyword state and is
> still in focus. The suggestion results are no longer shown. We should do
> the same for onKeywordEntered.
Okay, let's match it.  That means onKeywordEntered should not be called. (If it was called, then the extension could return suggestions, thus forcing the popup open.)

> Similar to the previous question, I think we should match existing omnibox
> behavior. If we consider the case of "sshfoo" => "ssh foo", onInputStarted
> is called first. Its callback parameter |text| is undefined. Then
> onInputChanged is called, and its callback parameter |text| is "foo". If
> we were to add onKeyboardEntered in this situation, the sequence of calls
> should be: onKeyboardEntered, onInputStarted, and onInputChanged.
> Note that if onKeyboardEntered has search suggestions, they could be
> overridden (removed and replaced with) by the search suggestions posed by
> onInputChanged. Alternatively, onKeyboardEntered's search suggestions could
> persist, and onInputChanged search suggestions would simply be added to the
> set. wdyt? Any preference?
I think the current solution is disruptive.  I think there ought to be a better answer here (either don't call it, or call it but don't let it return anything).  That would better match omnibox behavior.  Appending the onInputChanged suggestions is not very useful because those by far the more relevant ones.  Replacing suggestions wholesale is better but visually disruptive--they probably shouldn't have been displayed in the first place if we're going to immediately replace them.

> I think the current solution is disruptive.  I think there ought to be a better answer here (either don't call it, or call it but don't let it return anything).

IIUC, it appears that we're fine adding support for onKeywordEntered (wydt?), but we still need to determine if we should support the ability to specify suggest results.

Summarizing and thinking aloud here, if we were to support the suggest result ability, then:

- persisting the results and appending onInputChanged results is not great since the onInputChanged results are more relevant
- replacing the results with onInputChanged results is better but visually disruptive. Though the omnibox already appears to replace and change results as you type, so this seems fine?

If supporting the ability to specify suggest results in onKeywordEntered worsens the omnibox experience, then I'm fine excluding it. 

> IIUC, it appears that we're fine adding support for onKeywordEntered (wydt?)
Yes, I think this makes sense.  Chrome supports on-focus actions and suggestions for the default search provider.  I think it's reasonable for extensions to move in this direction as well.

I think there are two solutions that allow onKeywordEntered to offer suggestions.
1. Make the semantics of onKeywordEntered be that it's called when the keyword mode is entered without any additional text.  In this case, "sshfoo" => "ssh foo" would cause an onInputChanged but not an onKeywordEntered call.
2. Keep the semantics the same (any entry into keyword mode causes onKeywordEntered), but in cases like "sshfoo" => "ssh foo" make sure in code to suppress the onKeywordEntered suggestions.  Don't display them.  After all, they're not useful or relevant if you're about to call onInputChanged.

Thanks for the attention to detail, mpearson@!  These are great examples.  It sounds like most of the events have been ironed out, with the exception of the user types sshfoo -> ssh foo case.  catmullings@ and I mulled that over for a bit, and I think the best thing to do would be:
- Dispatch both the onKeywordEntered and onInputChanged (and also onInputStarted, though that doesn't return suggestions) events.
- If the extension has listeners for both onKeywordEntered and onInputChanged, only update the visible suggestions with the results of onInputChanged.
- If the extension has a listener for only one of the events, use the suggestions from that.

This way, we can have a defined flow for event dispatching, and extensions can rely on onKeywordEntered being called before onInputChanged.  Additionally, an extension that only cares about supplying default suggestions can do so through onKeywordEntered.  But we don't have the user-visible churn of cycling through two sets of suggestions for a single user action (putting a space between "ssh" and "foo").

mpearson@, does the above sound reasonable to you for that scenario?

Whoops, looks like mpearson@ posted while I was replying.  My suggestion sounds pretty much like #2 from yours - does that sound right to you?

> does that sound right to you?
Yup.

mpearson@: I will go ahead and implement comments 14 and 15 in the current CL.

Let me know if you would prefer to review the current patch first before I make these additional changes.

I'd prefer to see the new patch rather than a review a patch in which parts of it will be removed. :-)

Friendly ping on this. The new patch is ready for review.