Document tabId

MIGRATION.md

@@ -399,7 +399,7 @@ Example:
 import { addons, types } from "@storybook/manager-api";
 
 addons.register("my-addon", () => {
-  addons.add("my-addon/panel", {
+  addons.add("my-addon/tab", {
     type: types.TAB,
     title: "My Addon",
     render: () => <div>Hello World</div>,
@@ -421,7 +421,7 @@ addons.register("my-addon", () => {
   addons.add("my-addon/tool", {
     type: types.TOOL,
     title: "My Addon",
-    match: ({ tabId }) => tabId === "my-addon/panel",
+    match: ({ tabId }) => tabId === "my-addon/tab",
     render: () => <div>👀</div>,
   });
 });

docs/addons/addon-types.md

@@ -46,6 +46,10 @@ Use this boilerplate code to add a new `button` to Storybook's Toolbar:
 
 <Callout variant="info">
 
+The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.md#conditionally-render-the-addon).
+
+<hr style="margin: -0.75em 0 0.75em" />
+
 The `icon` element used in the example loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.
 
 </Callout>

docs/addons/writing-addons.md

@@ -155,7 +155,14 @@ Moving onto the manager, here we register the addon with Storybook using a uniqu
 
 <!-- prettier-ignore-end -->
 
-Notice the `match` property. It allows you to control the view mode where the addon is visible. If you only want to show it in a single mode, you must adjust the property to match the specific mode you aim for. In this case, it will be available in both story and documentation.
+### Conditionally render the addon
+
+Notice the `match` property. It allows you to control the view mode (story or docs) and tab (the story canvas or [custom tabs](./addon-types.md#tabs)) where the toolbar addon is visible. For example:
+
+- `({ tabId }) => tabId === 'my-addon/tab'` will show your addon when viewing the tab with the ID `my-addon/tab`.
+- `({ viewMode }) => viewMode === 'story'` will show your addon when viewing a story in the canvas.
+- `({ viewMode }) => viewMode === 'docs'` will show your addon when viewing the documentation for a component.
+- `({ tabId, viewMode }) => !tabId && viewMode === 'story'` will show your addon when viewing a story in the canvas and not in a custom tab (i.e. when `tabId === undefined`).
 
 Run the `start` script to build and start Storybook and verify that the addon is registered correctly and showing in the UI.
 

docs/snippets/common/storybook-addon-manager-initial-state.ts.mdx

@@ -11,7 +11,7 @@ addons.register(ADDON_ID, () => {
   addons.add(TOOL_ID, {
     type: types.TOOL,
     title: 'My addon',
-    match: ({ viewMode }) => !!(viewMode && viewMode.match(/^(story|docs)$/)),
+    match: ({ tabId, viewMode }) => !tabId && viewMode === 'story',
     render: Tool,
   });
 });

docs/snippets/common/storybook-addon-tab-example.js.mdx

@@ -5,14 +5,10 @@ import React from 'react';
 
 import { addons, types } from '@storybook/manager-api';
 
-addons.register('my/tab', () => {
-  addons.add('my-panel-addon/tab', {
+addons.register('my-addon', () => {
+  addons.add('my-addon/tab', {
     type: types.TAB,
     title: 'Example Storybook tab',
-    //👇 Checks the current route for the story
-    route: ({ storyId, refId }) => (refId ? `/mytab/${refId}_${storyId}` : `/mytab/${storyId}`),
-    //👇 Shows the Tab UI element in mytab view mode
-    match: ({ viewMode }) => viewMode === 'mytab',
     render: () => (
       <div>
         <h2>I'm a tabbed addon in Storybook</h2>

docs/snippets/common/storybook-addon-toolbar-example.js.mdx

@@ -7,13 +7,13 @@ import { addons, types } from '@storybook/manager-api';
 
 import { Icons, IconButton } from '@storybook/components';
 
-addons.register('my/toolbar', () => {
-  addons.add('my-toolbar-addon/toolbar', {
+addons.register('my-addon', () => {
+  addons.add('my-addon/toolbar', {
     title: 'Example Storybook toolbar',
     //👇 Sets the type of UI element in Storybook
     type: types.TOOL,
-    //👇 Shows the Toolbar UI element if either the Canvas or Docs tab is active
-    match: ({ viewMode }) => !!(viewMode && viewMode.match(/^(story|docs)$/)),
+    //👇 Shows the Toolbar UI element if the story canvas is being viewed
+    match: ({ tabId, viewMode }) => !tabId && viewMode === 'story',
     render: ({ active }) => (
       <IconButton active={active} title="Show a Storybook toolbar">
         <OutlineIcon />