RFC: Support Host (Teams) Shortcuts in Apps

[YuanboXue-Amber]

RFC: Support Host Shortcuts in Apps

Summary

This proposal introduces APIs to support host keyboard shortcuts when pressed within app iframes.

Problem statement

Apps integrated with host run inside their own iframes. Currently, host shortcuts do not function within these iframes.

Example: "GoToPowerBar" shortcut in Teams host:

• On Mac browsers: "option+cmd+e"
• On Windows browsers: "ctrl+alt+e"

This shortcut should focus the search input box at the top of Teams. If the search box is not visible (e.g., in a narrow window), it should be made visible.

Currently, pressing this shortcut inside an app iframe has no effect.

Additionally, apps may need to override certain host shortcuts. For example, "ctrl+b" bolds text in the Teams compose box, but if an app has its own compose box, it may want to handle "ctrl+b" itself.

Detailed Design or Proposal

The design consists of two parts:

1. Supporting host shortcuts in apps
2. Allowing apps to override certain host shortcuts

Part 1 - Support Host Shortcuts

• Introduce a new API: shortcutRelay.enableShortcutRelayCapability

• When an app calls this API:

  1. teams-js posts a message to request all mapped host shortcuts:

     callFunctionInHostAndHandleResponse(
       ApiName.ShortcutRelay_RequestHostShortcuts, // New function in Hub/Hub SDK
       [],
       new HostShortcutsResponseHandler(),
       getApiVersionTag(ApiVersionNumber.V_2, ApiName.App_RequestTeamsShortcut),
     );

     The response from the host will be an object like:

     {
       "shortcuts": ["ctrl+/", "ctrl+shift+/"]
     }

     teams-js stores this response in memory.

  2. teams-js attaches a keydown event handler to the app’s document. Using the shortcut map, it checks if the event matches a host shortcut. If so, it forwards the event to host:

     if (matchingShortcut) {
       const payload = serializeKeydownEvent(event);
       callFunctionInHost(
         ApiName.ShortcutRelay_ForwardShortcutEvent, // New function in Hub/Hub SDK
         [payload],
         getApiVersionTag(ApiVersionNumber.V_2, ApiName.ShortcutRelay_ForwardShortcutEvent),
       );
     }

  3. [Update Aug. 5th] Allow apps to define zones where shortcuts should not be forwarded to the host:

     • teams-js exports the attribute 'data-disable-shortcuts-forwarding'. Apps can add this attribute to DOM elements.
     • If the shortcut is pressed within a DOM element that has this attribute, the event will not be forwarded to the host.

Part 2 - Allow Certain Host Shortcuts to Be Overridden by Apps

• Host will define which shortcuts can be overridden to ensure consistent user experience.

• When receiving request ShortcutRelay_RequestHostShortcuts, Host will also send a list of overridable shortcuts:

  {
    "shortcuts": ["ctrl+/", "ctrl+shift+/", "ctrl+b"],
    "overridableShortcuts": ["ctrl+b"]
  }

• Introduce a new API: shortcutRelay.setOverridableShortcutHandler. Apps can use this API to specify a handler that returns true when it wants to override the shortcut. The function is of type:

  (event: KeyboardEvent, data: OverridableShortcutHandlerData) => boolean;

• hen an overridable shortcut is detected, teams-js will call the handler above. If it returns true, the shortcut will not be forwarded to the host.

The Next Step

API for Runtime Shortcut Updates
There is a follow-up plan to introduce an API for runtime shortcut updates.

Since Teams allows users to customize shortcuts during runtime, Teams should notify apps whenever shortcut mappings change.

Open for Discussion

1. Imagine an app has its own shortcuts, such as ctrl+1+2, which aren't currently used by Teams. When app developers integrate with Teams, they might choose to use the ctrl+1+2 shortcut since it's available. However, if Teams later introduces this shortcut and makes it non-overridable, it could unexpectedly stop working for those app developers.

Discarded Solution

• teamsCore.enableTeamsShortcutCapability was changed to shortcutRelay.enableShortcutRelayCapability
  Reason Discarded: the ability to support shortcut is not unique to Teams host.

• enableShortcutRelayCapability was originally designed to accept an argument to allow apps to override shortcuts:

  onOverridableShortcut: (shortcut: Shortcut) => boolean;

  Reason Discarded: This discarded solution assumes apps’ overridable shortcuts are known right when we register the host shortcuts. We want to provide a way to override them over time, as shortcuts may change depending on the app state.

• Sending Shortcut ID in Host-App Messages:
  There was a consideration to send shortcut IDs or descriptions (e.g., "Bold") in the message between host and app, rather than just the key combinations.
  Reason Discarded: A shortcut description or ID does not provide much actionable context to app developers.

[YuanboXue-Amber]

Draft implementation on teams-js side: #2868

[juanscr]

If I am understanding correctly, this RFC has the following assumptions:

1. The app must opt-in by calling this new API, in order for the host to handle the shortcuts inside the app.
2. This functionality will and is only used by Teams, as the new APIs are local to the teamsCore capability instead of a new one.

So, from this, just some questions:

1. Is the first assumption correct? I like the idea for apps to opt-in to this behavior, just want to know if its something intentional.
2. Shouldn't we add a new capability for shortcuts handling independent of the host? Of course, we'll start with Teams implementation, but I would attempt to create something more generic to scale between different hosts.
3. With this design, we are assuming that the apps overridable shortcuts are known right when we register the Teams shortcuts. Shouldn't there be a native way to override more over time? Shortcuts, depending of the app state, can change and do different things.

This last thing is something that we may decide to ignore but it's something to consider. This design, at the end, won't necessarily prevent apps to still register their own event handler for keys that are not overridable. I am not sure if this will create some inconsistencies and we can combat this by using event capturing mechanism to avoid bubbling to different events, but we have to make this clear, so behavior is easily known for apps that use this mechanism.

[jekloudaMSFT]

Thanks for the detailed proposal here!

I would also like to see a handler in this flow so that the host can raise an event when its set of shortcuts changes if we're going to maintain a set of shortcuts on the teams-js side. This should support the case where a user changes the Teams shortcuts while an app is running.

On the shape of the response from the host: is it important that teams-js receive an ID/name for each shortcut? It seems like teams-js would only need a set of the shortcut keys to determine if it should be forwarded to the host. What would the shortcut ID/description be needed for on teams-js? Similarly, on overriding shortcuts, I expect the app only needs the set of shortcut combinations it can override, since the app already knows which shortcut keys it supports.

I also agree with Juan on his second point: this functionality should be host independent even if Teams is the only host planning to support this for now.

On your discussion question: why does the app need to be notified when Teams adds or removes shortcuts if the set of shortcuts is returned from the host at runtime? If the set of Teams shortcuts is configurable by the user, shouldn't the app assume that the shortcuts can always change?

[YuanboXue-Amber]

Thanks @juanscr.

The app must opt-in by calling this new API, in order for the host to handle the shortcuts inside the app.

Yes this assumption below is correct. I recall that @ydogandjiev expressed a concern that providing the shortcut functionality by default in the new platform version could impact users' willingness to adopt it.

Shouldn't we add a new capability for shortcuts handling independent of the host

I thought teams-js was specifically for Teams host. If that's not the case, I think it would make sense to move the API out of teamsCore, to support other hosts like Outlook.

Could you give me some suggestions on where the API could be placed? I'm not very familiar with the current structure of the repository.

@jekloudaMSFT could you share some insight here as well since you raised the same concern.

We are assuming that the apps overridable shortcuts are known right when we register the Teams shortcuts. Shouldn't there be a native way to override more over time

This is a valid call out! As for the implementation, what do you think about below:

Instead of

function enableTeamsShortcutCapability(onOverridableShortcut?: OverrideTeamsShortcutFunctionType)

We have:

function enableTeamsShortcutCapability(overridingShortcuts?: Array<{ id: string; segments: string[] }>)

And store overridingShortcuts in memory. Also providing a new function that allows Apps to update overridingShortcuts.

We should also inform app developers about which shortcuts can be overridden. To do this, we can update enableTeamsShortcutCapability to return an object that specifies which shortcuts in the given overridingShortcuts list are permitted to be overridden.

This is just a quick idea and I personally think this API is odd :D so let me know if you have any suggestions.

4. And lastly I agree with

This design, at the end, won't necessarily prevent apps to still register their own event handler for keys that are not overridable.
...
we can combat this by using event capturing mechanism to avoid bubbling to different events, but we have to make this clear

I will update the proposal to highlight this.

[YuanboXue-Amber]

Thank you @jekloudaMSFT

I would also like to see a handler in this flow so that the host can raise an event when its set of shortcuts changes if we're going to maintain a set of shortcuts on the teams-js side.

I’m planning to add an API similar to registerOnThemeChangeHandlerHelper. Since this will be a separate function, I intend to implement it as the second step after introducing the initial API for shortcut support. I believe its implementation details won’t impact the initial API, but please let me know if you have any concerns.

is it important that teams-js receive an ID/name for each shortcut?

It's true that we really only need the shortcut keys in messages. Initially, I thought including an ID might help Apps understand the function of each shortcut, but on second thought, an ID like 'Bold' doesn't provide much context for developers.

Let's keep things simple and not send IDs?

On your discussion question: why does the app need to be notified when Teams adds or removes shortcuts if the set of shortcuts is returned from the host at runtime? If the set of Teams shortcuts is configurable by the user, shouldn't the app assume that the shortcuts can always change?

Imagine an app has its own shortcuts, such as ctrl+1+2, which aren't currently used by Teams. When app developers integrate with Teams, they might choose to use the ctrl+1+2 shortcut since it's available. However, if Teams later introduces this shortcut and makes it non-overridable, it could unexpectedly stop working for those app developers.

A similar situation occurs if a Teams user manually reassigns an existing Teams shortcut to ctrl+1+2. In this case, the app's shortcut would stop working due to the user's action - for me it seems less problematic.

[lakhveerk]

@YuanboXue-Amber

Could you give me some suggestions on where the API could be placed? I'm not very familiar with the current structure of the repository.

You can add it as a sub-capability in app.ts (We should not add the new functions in the existing capability because that can break the isSupported function. The new functions need to be in a subcapability). Or I think a standalone capability would work too

Listening to every keydown does not seem like a good idea. With this, we could be listening to private data, passwords etc as well? If a user is writing in a text area, we should pass those keystrokes instead of keep trying for a match.

[YuanboXue-Amber]

@lakhveerk this is a good call out:

If a user is writing in a text area, we should pass those keystrokes instead of keep trying for a match

In Teams, shortcuts also work within textareas. I'd like to keep this behavior for iframes as well. We can let apps specify a "no shortcut zone": if the keydown event target is within an element that has the data-disable-shortcuts-forwarding attribute, we would skip shortcut matching. Let me know your thoughts on this approach.

[lakhveerk]

I like the idea but would be good idea to bring this up in a security review to be sure.