From 83958f57ac1e6bbaa0e6198d8e54497bdda5b738 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Wed, 31 Jan 2024 21:11:13 -0700 Subject: [PATCH] Document `tabId` --- MIGRATION.md | 4 ++-- docs/addons/addon-types.md | 4 ++++ docs/addons/writing-addons.md | 9 ++++++++- .../common/storybook-addon-manager-initial-state.ts.mdx | 2 +- docs/snippets/common/storybook-addon-tab-example.js.mdx | 8 ++------ .../common/storybook-addon-toolbar-example.js.mdx | 8 ++++---- 6 files changed, 21 insertions(+), 14 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 6cc5bb0377fb..5e928fd00885 100644 --- a/MIGRATION.md +++ b/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: () =>
Hello World
, @@ -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: () =>
👀
, }); }); diff --git a/docs/addons/addon-types.md b/docs/addons/addon-types.md index f46e4f41ff03..481640bec3ae 100644 --- a/docs/addons/addon-types.md +++ b/docs/addons/addon-types.md @@ -46,6 +46,10 @@ Use this boilerplate code to add a new `button` to Storybook's Toolbar: +The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.md#conditionally-render-the-addon). + +
+ 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. diff --git a/docs/addons/writing-addons.md b/docs/addons/writing-addons.md index dd99775dbdd5..ff02eca31843 100644 --- a/docs/addons/writing-addons.md +++ b/docs/addons/writing-addons.md @@ -155,7 +155,14 @@ Moving onto the manager, here we register the addon with Storybook using a uniqu -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. diff --git a/docs/snippets/common/storybook-addon-manager-initial-state.ts.mdx b/docs/snippets/common/storybook-addon-manager-initial-state.ts.mdx index cccdd53fe226..b3f40090d1d1 100644 --- a/docs/snippets/common/storybook-addon-manager-initial-state.ts.mdx +++ b/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, }); }); diff --git a/docs/snippets/common/storybook-addon-tab-example.js.mdx b/docs/snippets/common/storybook-addon-tab-example.js.mdx index 951f10793d3a..b3ff6c6d37d2 100644 --- a/docs/snippets/common/storybook-addon-tab-example.js.mdx +++ b/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: () => (

I'm a tabbed addon in Storybook

diff --git a/docs/snippets/common/storybook-addon-toolbar-example.js.mdx b/docs/snippets/common/storybook-addon-toolbar-example.js.mdx index 5877b8cad7a8..bb0cf2bb4677 100644 --- a/docs/snippets/common/storybook-addon-toolbar-example.js.mdx +++ b/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 }) => (