Allow extensions to contribute getting started content

[JacksonKearl]

We want to allow extensions to contribute items to the welcome page's getting started section:

Using a package.json like this:

		"welcomeCategories": [
			{
				"id": "exampleProject",
				"title": "Turn Markdown into HTML",
				"description": "Use this sample project to learn how to convert Markdown to HTML!"
			}
		],
		"welcomeItems": {
			"exampleProject": [
				{
					"id": "md-to-html.openExample",
					"title": "Open an example folder",
					"description": "To start, try opening an example folder that has been preconfigured for this tutorial. This is optional, but helps for following along!",
					"button": {
						"title": "Open Example",
						"command": "md-to-html.openExample"
					},
					"media": {
						"path": "media/example-project.png",
						"altText": "example project"
					}
				},
				{
					"id": "md-to-html.showPreview",
					"title": "Preview your Markdown",
					"description": "Open a markdown file and click the \"Open Preview\" button at the top of the screen to see a preview of your file. This is technically optional, but it updates live and is helpful to check when creating your content!",
					"button": {
						"title": "Open Markdown File",
						"command": "md-to-html.openMarkdown"
					},
					"media": {
						"path": "media/preview.png",
						"altText": "preview"
					},
					"doneOn": {"command": "markdown.showPreviewToSide" } 
				},
				{
					"id": "md-to-html.convertToHTML",
					"title": "Create your .html file",
					"description": "To create the html file, run \"Convert Document to HTML\" from the editor actions context menu, behind the three dots top of the screen. This will create an .html file along side the markdown file.",
					"button": {
						"title": "Open Markdown File",
						"command": "md-to-html.openMarkdown"
					},
					"media": {
						"path": "media/convert-option.png",
						"altText": "showing editor actions context menu"
					},
					"doneOn": {"command": "md-to-html.convertToHTML" }
				},
				{
					"id": "md-to-html.openInBrowser",
					"title": "Open your .html file in the browser",
					"description": "Test that everything worked by opening the .html file in your browser. First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".",
					"button": {
						"title": "Open HTML File",
						"command": "md-to-html.openHTML"
					},
					"media": {
						"path": "media/open-in-browser.png",
						"altText": "use editor context menu to open an .html file in your browser"
					},
					"doneOn": {"command": "extension.openInDefaultBrowser" }
				},
				{
					"id": "md-to-html.addKeybinding",
					"title": "Create a keyboard shortcut",
					"description": "That's all! You can share that single .html file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.",
					"button": {
						"title": "Add a keybinding",
						"command": "md-to-html.addKeybinding"
					},
					"media": {
						"path": "media/add-keybinding.png",
						"altText": "use the keybindings editor to add a keybinding for this command"
					}
				}
			]
		},

This is the change to the extension contributions interface:

export interface IExtensionContributions {
        .....
	welcomeItems?: { [category: string]: IWelcomeItem[] };
	welcomeCategories?: IWelcomeCategory[];
        .....
}

export interface IWelcomeItem {
	readonly id: string;
	readonly title: string;
	readonly description: string;
	readonly button: { title: string } & ({ command?: never, link: string } | { command: string, link?: never }),
	readonly media: { path: string | { hc: string, light: string, dark: string }, altText: string },
	readonly doneOn?:
	| { event: string; command?: never }
	| { event?: never; command: string };
	readonly when?: string;
}

export interface IWelcomeCategory {
	readonly id: string,
	readonly title: string;
	readonly description: string;
	readonly when?: string;
}

[JacksonKearl]

Updated based on feedback from API discussion:

• Rather than a split categories/items contribution point, use a single large object
• walkthroughs as top level contribution point (generalizable to getting started, tips&tricks, and troubleshooting), tasks for the individual items
• Simplified image contribution - now just a single path
• Removed eventFired doneOn mode, will add API to control programmatically in future revision

Interface:

export interface IWalkthroughTask {
	readonly id: string;
	readonly title: string;
	readonly description: string;
	readonly button:
	| { title: string, link: string, command?: never }
	| { title: string, command: string, link?: never },
	readonly media: { path: string, altText: string },
	readonly doneOn?: { command: string };
	readonly when?: string;
}

export interface IWalkthrough {
	readonly id: string,
	readonly title: string;
	readonly description: string;
	readonly tasks: IWalkthroughTask[];
	readonly primary?: boolean;
	readonly when?: string;
}

Example:

"walkthroughs": [ 
			{
				"id": "exampleProject",
				"title": "Turn Markdown into HTML",
				"description": "Use this sample project to learn how to convert Markdown to HTML!",
				"primary": true,
				"tasks": [
					{
						"id": "md-to-html.openExample",
						"title": "Open an example folder",
						"description": "To start, try opening an example folder that has been preconfigured for this tutorial. This is optional, but helps for following along!",
						"button": {
							"title": "Open Example",
							"command": "md-to-html.openExample"
						},
						"media": {
							"path": "media/example-project.png",
							"altText": "example project"
						}
					},
					{
						"id": "md-to-html.showPreview",
						"title": "Preview your Markdown",
						"description": "Open a markdown file and click the \"Open Preview\" button at the top of the screen to see a preview of your file. This is technically optional, but it updates live and is helpful to check when creating your content!",
						"button": {
							"title": "Open Markdown File",
							"command": "md-to-html.openMarkdown"
						},
						"media": {
							"path": "media/preview.png",
							"altText": "preview"
						},
						"doneOn": {"command": "markdown.showPreviewToSide" } 
					},
					{
						"id": "md-to-html.convertToHTML",
						"title": "Create your .html file",
						"description": "To create the html file, run \"Convert Document to HTML\" from the editor actions context menu, behind the three dots top of the screen. This will create an .html file along side the markdown file.",
						"button": {
							"title": "Open Markdown File",
							"command": "md-to-html.openMarkdown"
						},
						"media": {
							"path": "media/convert-option.png",
							"altText": "showing editor actions context menu"
						},
						"doneOn": {"command": "md-to-html.convertToHTML" }
					},
					{
						"id": "md-to-html.openInBrowser",
						"title": "Open your .html file in the browser",
						"description": "Test that everything worked by opening the .html file in your browser. First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".",
						"button": {
							"title": "Open HTML File",
							"command": "md-to-html.openHTML"
						},
						"media": {
							"path": "media/open-in-browser.png",
							"altText": "use editor context menu to open an .html file in your browser"
						},
						"doneOn": {"command": "extension.openInDefaultBrowser" }
					},
					{
						"id": "md-to-html.addKeybinding",
						"title": "Create a keyboard shortcut",
						"description": "That's all! You can share that single .html file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.",
						"button": {
							"title": "Add a keybinding",
							"command": "md-to-html.addKeybinding"
						},
						"media": {
							"path": "media/add-keybinding.png",
							"altText": "use the keybindings editor to add a keybinding for this command"
						}
					}
				]
			}
		]

Edit: Added a "primary" boolean to category items indicating whether the category should be auto-opened on install.

[JacksonKearl]

Moving to April for continued API discussion.

[pixieaka]

@JacksonKearl Is it option here to add images for [ light, dark, HC ] color themes from extensions?

[JacksonKearl]

@pixieaka that is not currently surfaced, though we support it internally and could potentially. Is this something you would use?

[pixieaka]

@JacksonKearl Yeah I could use this feature to unify my extension experience to mate user interface like HC or Light. Can this be optional if extension slides need to display code photos it would be better to be customizable for user UI.

[JacksonKearl]

That sounds reasonable, can you create a new issue for it?

[pixieaka]

@JacksonKearl Absolutely! #120122 .

[Eskibear]

For those who want to try this new feature, I just want to mention that, setting workbench.welcomePage.experimental.extensionContributions to true (for the insiders built on 2021/04/28) is a pre-requisite. Otherwise you don't see anything.

[JacksonKearl]

New API:

"walkthroughs": [
  {
    "id": "exampleProject",
    "title": "Turn Markdown into HTML",
    "description": "Use this sample project to learn how to convert Markdown to HTML!",
    "primary": true,
    "steps": [
      {
        "id": "md-to-html.openExample",
        "title": "Open an example folder",
        "description": "To start, try opening an example folder that has been preconfigured for this tutorial. **This is optional**, but helps for following along!\n[Open Example](command:md-to-html.openExample)",
        "media": {
          "path": "media/openExample.md"
        },
        "completionEvents": ["extensionInstalled:tyriar.luna-paint"] 
      },
      {
        "id": "md-to-html.showPreview",
        "title": "Preview your Markdown",
        "description": "Open a markdown file and click the __\"Open Preview\"__ button at the top of the screen to see a preview of your file. **This is technically optional**, but it updates live and is helpful to check when creating your content!\n[Open Markdown File](command:toSide:workbench.action.quickOpen?%22.md%22)",
        "media": {
          "path": "media/preview.png",
          "altText": "preview"
        },
        "completionEvents": ["onCommand:markdown.showPreviewToSide"]
      },
      {
        "id": "md-to-html.convertToHTML",
        "title": "Create your .html file",
        "description": "To create the ``.html`` file, run __\"Convert Document to HTML\"__ from the editor actions context menu, behind the three dots top of the screen. This will create an ``.html`` file along side the markdown file.\n[Open Markdown File](command:toSide:workbench.action.quickOpen?%22.md%22)",
        "media": {
          "path": "media/convert-option.png",
          "altText": "showing editor actions context menu"
        },
        "completionEvents": ["onCommand:md-to-html.convertToHTML"]
      },
      {
        "id": "md-to-html.openInBrowser",
        "title": "Open your .html file in the browser",
        "description": "Test that everything worked by opening the ``.html`` file in your browser. This requires [installing the open in broswer extension](command:workbench.extensions.installExtension?%22techer.open-in-browser%22).\n First open the html file in vscode, then right click in the editor and choose \"Open in Default Browser\".\n[Open HTML File](command:toSide:workbench.action.quickOpen?%22.html%22)",
        "media": {
          "path": "media/open-in-browser.png",
          "altText": "use editor context menu to open an .html file in your browser"
        },
        "completionEvents": ["onCommand:extension.openInDefaultBrowser"]
      },
      {
        "id": "md-to-html.addKeybinding",
        "title": "Create a keyboard shortcut",
        "description": "That's all! You can share that single ``.html`` file with anyone without needing to bundle the images. To make this even easier in the future, consider adding a keybinding for the \"Convert Document to HTML\" command.\n[Add a keybinding](command:workbench.action.openGlobalKeybindings?%22md-to-html.convertToHTML%22)",
        "media": {
          "path": "media/add-keybinding.png",
          "altText": "use the keybindings editor to add a keybinding for this command"
        }
      }
    ]
  }
],

Where completionEvents follows same basic flow as avtivationEvents, and takes keys like: onCommand: onLink: onView: onSettingChanged: onContextKeyDefined: extensionInstalled: stepSelected

[JacksonKearl]

Notes from API review:

• onContextKeyDefined => onContext
• Consider supporting configuration in a separate file (see snippets)
• Better name for "primary" Removed entirely
• media.path => media.image, media.markdown

[JacksonKearl]

Implemented remaining items from API review. Will consider supporting separate config files as needed by implementors