`contribShareMenu` proposed menus

[joyceerhl]

I'm filing this issue to track the finalization of the contribShareMenu API proposal since I was not able to find a tracking issue, cc @alexr00.

Current state

The contribShareMenu API proposal tracks the following menu points:

• file/share
• editor/context/share

This proposal has been in place for several months without changes, and was previously discussed in #146309 and #157722, but has not yet been finalized. This means it can't yet be used by most extensions, limiting its utility. An example of an extension that IMO would be a great fit for the Share submenus is Live Share (cc @jramsay):

Additional share submenus

As part of #175676 I'm looking at integrating link sharing more deeply into our product surface area, with the goal of making collaboration via links as seamless as possible. Therefore I'm proposing to expand this API proposal to also include

• editor/title/context/share
• explorer/context/share

(Note, there is also editor/lineNumber/context via #175945, but I have not added a share submenu for that context menu yet because we are introducing that context menu for the first time all up and it would be odd to only have one item in the menu which is itself a submenu.)

[joyceerhl]

Feedback from API sync:

• Could be some opportunity for consolidation across all share menus (and then just inline share actions into all menus)
  • At the same point in time, don't want to show all the same share actions everywhere, and the context object is different
  • e.g. file/share includes export/import profiles which wouldn't be relevant in editor/context/share
• Unsure whether to include active editor selection if coming via editor/title/context/share or explorer/context/share, waiting for more feedback

[mjbvz]

@joyceerhl One thing I just thought of: how do we support sharing documents from other views, such as the open editors view, or potentially even sharing from custom tree views, such as the Find All References view?

One option would be to create contribution points for each case. That would let extensions control where their menus show up, but would also require knowing about and adopting a lot of contribution points

Another option though would be to have a generic shareFile contribution point. This would let VS Code show these contributions in any places where we think a share menu makes sense. It would also let VS Code surface the share commands in other ways, such as a Share... command in the command palette

I believe we may have considered something similar last week. Were there any concerns about this approach?

[joyceerhl]

The main issue that we discussed last week is that we don't want to show the same share actions everywhere, e.g. file/share has Export/Import Profile... which doesn't make sense in any of the other share submenus.

how do we support sharing documents from other views, such as the open editors view, or potentially even sharing from custom tree views, such as the Find All References view?

This is a really good point though. Having a single contribution point would allow us to avoid a continuous adoption cost across extensions anytime we introduce a new area in the product where sharing makes sense.

It would also let VS Code surface the share commands in other ways, such as a Share... command in the command palette

@bamurtaugh had a proposal to add a Share button next to the command center if that ever becomes default, and a single share contribution point would also support that scenario.

If we go with this approach, here is the work that I think should happen:

• Introduce a shareResource contribution point (I think file might be a little too limiting, e.g. I have wanted to copy links to a specific folder or workspace as well). The contribution point would be responsible for creating share submenus in the following places and ensuring that the right context (both command args and when clauses via overlays) is passed to contributed actions:
  • editor/context
  • editor/title/context
  • editor/lineNumber/context
  • explorer/context
  • file/share
  • editor line number context in diff editors
  • open editors view
  • find all references view
  • SCM view resource state context
• Keep file/share as a separate menu identifier for now, since at the moment that is the only menu where we want to show actions that wouldn't make sense in all the other cases that we are discussing)
• Standardize what context gets passed to actions, should be one of:
  1. { uri: vscode.Uri }: indicates generating a link for just the resource but not including range/selection
  2. { uri: vscode.Uri, selections: vscode.Selection }: indicates generating a link for the resource and a specific selection
     -if the start line and end line are the same or if the start and end line are off by 1 and the end column is 0, extensions should generate links for just one line
     • @rebornix we had a related conversation around supporting links for notebooks, I think that maybe we want to support passing NotebookCell ranges as well?
  3. undefined: command palette context
• Adopt the share contribution in:
  • GitHub Repositories
  • GitHub Pull Requests
  • GitHub
• Remove previous duplicated link code

@mjbvz let me know if I missed anything or if you have other suggestions.

[joyceerhl]

Two more places that would be nice to have share menus in:

• references view
• search view

It should be possible to deeplink to a line in a file from the share actions for those views.

[joyceerhl]

@jrieken and I discussed this and there are a few complications:

• we need to perform the appropriate renderer <-> ext host type conversions for the arguments that we pass, e.g. an internal ISelection object needs to be properly transformed into a vscode.Selection object if it's being passed to the ext host
• some of the views where we want to introduce share links in the context menu are actually controlled by extensions rather than core, in which case the context that gets passed is always the data model object of the corresponding extension and is not influenced by core:
  • references view
  • call hierarchy
  • scm view
  • timeline
• the command/arg approach suffers from the problem that the extension never really knows what args it receives and there is no contract or explicit typing

In order to be able to provide a consistent context from both core and extension-controlled contexts--without layer breaking--to extensions which want to generate a shareable link, we may be better off with an explicit data provider api. Here is a sketch of how I think this would work:

• extensions like builtin GitHub, GitHub Pull Requests, Remote Repositories, and Live Share would declare a share contribution in package.json
• core would inline the contributed command into various menus where it makes sense
• core and extensions would register SharableDataProviders for various sharable contexts
• when an extension's share contribution is selected, core would first call a registered ShareableDataProvider capable of providing info about the sharable context
• the context then gets passed to the extension to generate a link, start a collaboration session, etc

Currently we're most interested in sharing editor and view context, so here's a sketch of what that api could look like:

declare module 'vscode' {

	export namespace window {
		/**
		 *
		 * @param viewId The id of the view that the provider can share data about.
		 * @param provider A provider that can generate {@link ShareableData} for the specified view.
		 */
		export function registerShareableTreeDataProvider(viewId: string, provider: ShareableTreeDataProvider): Disposable;

		/**
		 *
		 * @param document A selector for editors that the provider can share data about.
		 * @param provider A provider that can generate {@link ShareableData} for the specified document.
		 */
		export function registerShareableDocumentDataProvider(document: DocumentSelector, provider: ShareableDocumentDataProvider): Disposable;
	}

	interface ShareableTreeDataProvider {
		provideShareableData(context: TreeItem, token: CancellationToken): ProviderResult<ShareableData>;
	}

	interface ShareableDocumentDataProvider {
		provideShareableData(context: DocumentSelector, token: CancellationToken): ProviderResult<ShareableData>;
	}

	interface ShareableData {
		readonly uri?: Uri;
		readonly ranges?: Range[];
	}
}

Another option is to expand the existing TreeDataProvider to include a provideShareableData method:

	/**
	 * A data provider that provides tree data
	 */
	export interface TreeDataProvider<T> {
		
		provideShareableData?(item: TreeItem, token: CancellationToken): ProviderResult<ShareableData>;
	}