From c263d1d1b9d1c6d604ce0edf9149e57e737b47f1 Mon Sep 17 00:00:00 2001 From: Gert Hengeveld Date: Fri, 26 Feb 2021 16:52:50 +0100 Subject: [PATCH] Deprecate 'showRoots' in favor of 'sidebar.showRoots', and remove sidebarAnimations altogether --- MIGRATION.md | 16 ++++++++++++++++ docs/configure/features-and-behavior.md | 11 ++++++++--- docs/configure/sidebar-and-urls.md | 6 ++---- .../common/storybook-config-layout.js.mdx | 8 +++++--- .../storybook-manager-disable-roots.js.mdx | 6 +++++- examples/official-storybook/manager.js | 4 +++- lib/api/src/lib/stories.ts | 15 ++++++++++++++- lib/api/src/modules/layout.ts | 2 -- lib/api/src/modules/provider.ts | 6 ++++++ lib/api/src/modules/stories.ts | 1 - lib/api/src/tests/layout.test.js | 1 - lib/api/src/tests/stories.test.js | 6 +++--- 12 files changed, 62 insertions(+), 20 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 7de591ad2951..4175b5833d42 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -9,6 +9,7 @@ - [6.2 Deprecations](#62-deprecations) - [Deprecated implicit PostCSS loader](#deprecated-implicit-postcss-loader) - [Deprecated default PostCSS plugins](#deprecated-default-postcss-plugins) + - [Deprecated showRoots config option](#deprecated-showroots-config-option) - [From version 6.0.x to 6.1.0](#from-version-60x-to-610) - [Addon-backgrounds preset](#addon-backgrounds-preset) - [Single story hoisting](#single-story-hoisting) @@ -230,6 +231,21 @@ module.exports = { }; ``` +#### Deprecated showRoots config option + +Config options for the sidebar are now under the `sidebar` namespace. The `showRoots` option should be set as follows: + +```js +addons.setConfig({ + sidebar: { + showRoots: false, + }, + // showRoots: false <- this is deprecated +}); +``` + +The top-level `showRoots` option will be removed in Storybook 7.0. + ## From version 6.0.x to 6.1.0 ### Addon-backgrounds preset diff --git a/docs/configure/features-and-behavior.md b/docs/configure/features-and-behavior.md index 2dc5b27049f7..3dc9c0fc33b6 100644 --- a/docs/configure/features-and-behavior.md +++ b/docs/configure/features-and-behavior.md @@ -22,11 +22,16 @@ The following table details how to use the API values: | **showNav** | Boolean |Display panel that shows a list of stories |`true` | | **showPanel** | Boolean |Display panel that shows addon configurations |`true` | | **panelPosition** | String/Object |Where to show the addon panel |`bottom` or `right` | -| **sidebarAnimations** | Boolean |Sidebar tree animations |`true` | | **enableShortcuts** | Boolean |Enable/disable shortcuts |`true` | | **isToolshown** | String |Show/hide tool bar |`true` | | **theme** | Object |Storybook Theme, see next section |`undefined` | | **selectedPanel** | String |Id to select an addon panel |`my-panel` | -| **initialActive** | String |Select the default active tab on Mobile. |`sidebar` or `canvas` or `addons` | -| **showRoots** | Boolean |Display the top-level grouping as a "root" in the sidebar |`false` | +| **initialActive** | String |Select the default active tab on Mobile |`sidebar` or `canvas` or `addons` | +| **sidebar** | Object |Sidebar options, see below |`{ showRoots: false }` | +The following options are configurable under the `sidebar` namespace: + +| Name | Type | Description | Example Value | +| ----------------------|:-------------:|:-------------------------------------------------------------:|:----------------------------------------------:| +| **showRoots** | Boolean |Display the top-level nodes as a "root" in the sidebar |`false` | +| **collapsedRoots** | Array |Set of root node IDs to visually collapse by default |`['misc', 'other']` | diff --git a/docs/configure/sidebar-and-urls.md b/docs/configure/sidebar-and-urls.md index 161ad961aa0b..bcf9cb2d3161 100644 --- a/docs/configure/sidebar-and-urls.md +++ b/docs/configure/sidebar-and-urls.md @@ -10,11 +10,11 @@ We recommend using a nesting scheme that mirrors the filesystem path of the comp ## Roots -By default, Storybook will treat your highest level of groups as “roots”--which are displayed in the UI as “sections” of the hierarchy. Lower level groups are displayed as expandable items in the hierarchy: +By default, Storybook will treat your top-level nodes as “roots”. Roots are displayed in the UI as “sections” of the hierarchy. Lower level groups are displayed as folders: ![Storybook sidebar story roots](./sidebar-roots.jpg) -If you’d prefer all groups to be expandable, you can set the `showRoots` option to `false` in [`./storybook/manager.js`](./overview.md#configure-story-rendering): +If you’d prefer to show top-level nodes as folders rather than roots, you can set the `sidebar.showRoots` option to `false` in [`./storybook/manager.js`](./overview.md#configure-story-rendering): @@ -30,7 +30,6 @@ If you’d prefer all groups to be expandable, you can set the `showRoots` optio As a CSF file is a JavaScript file, the exports (including the default export) can be generated dynamically. In particular you can use the `__dirname` variable to generate the title based on the path name (this example uses the paths.macro): - - ## Permalinking to stories By default, Storybook generates an `id` for each story based on the component title and the story name. This `id` in particular is used in the URL for each story and that URL can serve as a permalink (especially when you [publish](../workflows/publish-storybook.md) your Storybook). diff --git a/docs/snippets/common/storybook-config-layout.js.mdx b/docs/snippets/common/storybook-config-layout.js.mdx index 6f06abb551c7..a73cbd0ef46c 100644 --- a/docs/snippets/common/storybook-config-layout.js.mdx +++ b/docs/snippets/common/storybook-config-layout.js.mdx @@ -8,12 +8,14 @@ addons.setConfig({ showNav: true, showPanel: true, panelPosition: 'bottom', - sidebarAnimations: true, enableShortcuts: true, isToolshown: true, theme: undefined, selectedPanel: undefined, initialActive: 'sidebar', - showRoots: false, + sidebar: { + showRoots: false, + collapsedRoots: ['other'], + }, }); -``` \ No newline at end of file +``` diff --git a/docs/snippets/common/storybook-manager-disable-roots.js.mdx b/docs/snippets/common/storybook-manager-disable-roots.js.mdx index 5776c86769c8..3cf13c00b4a6 100644 --- a/docs/snippets/common/storybook-manager-disable-roots.js.mdx +++ b/docs/snippets/common/storybook-manager-disable-roots.js.mdx @@ -2,5 +2,9 @@ // ./storybook/manager.js import { addons } from '@storybook/addons'; -addons.setConfig({ showRoots: false }); +addons.setConfig({ + sidebar: { + showRoots: false, + }, +}); ``` diff --git a/examples/official-storybook/manager.js b/examples/official-storybook/manager.js index b3c7f0839ac9..cd74ecf5fd6f 100644 --- a/examples/official-storybook/manager.js +++ b/examples/official-storybook/manager.js @@ -15,5 +15,7 @@ addons.setConfig({ hidden: true, }, }, - collapsedRoots: ['other'], + sidebar: { + collapsedRoots: ['other'], + }, }); diff --git a/lib/api/src/lib/stories.ts b/lib/api/src/lib/stories.ts index ddc2128eb041..c6e0991da219 100644 --- a/lib/api/src/lib/stories.ts +++ b/lib/api/src/lib/stories.ts @@ -111,6 +111,14 @@ export type SetStoriesPayload = stories: StoriesRaw; } & Record); +const warnLegacyShowRoots = deprecate( + () => {}, + dedent` + The 'showRoots' config option is deprecated and will be removed in Storybook 7.0. Use 'sidebar.showRoots' instead. + Read more about it in the migration guide: https://github.com/storybookjs/storybook/blob/master/MIGRATION.md + ` +); + const warnChangedDefaultHierarchySeparators = deprecate( () => {}, dedent` @@ -144,7 +152,12 @@ export const transformStoriesRawToStoriesHash = ( const storiesHashOutOfOrder = values.reduce((acc, item) => { const { kind, parameters } = item; - const { showRoots, collapsedRoots = [] } = provider.getConfig(); + const { sidebar = {}, showRoots: deprecatedShowRoots } = provider.getConfig(); + const { showRoots = deprecatedShowRoots, collapsedRoots = [] } = sidebar; + + if (typeof deprecatedShowRoots !== 'undefined') { + warnLegacyShowRoots(); + } const setShowRoots = typeof showRoots !== 'undefined'; if (usesOldHierarchySeparator && !setShowRoots) { diff --git a/lib/api/src/modules/layout.ts b/lib/api/src/modules/layout.ts index 0118fa325c4c..41c4a16bdae0 100644 --- a/lib/api/src/modules/layout.ts +++ b/lib/api/src/modules/layout.ts @@ -27,7 +27,6 @@ export interface UI { name?: string; url?: string; enableShortcuts: boolean; - sidebarAnimations: boolean; docsMode: boolean; } @@ -63,7 +62,6 @@ export interface UIOptions { const defaultState: SubState = { ui: { enableShortcuts: true, - sidebarAnimations: true, docsMode: false, }, layout: { diff --git a/lib/api/src/modules/provider.ts b/lib/api/src/modules/provider.ts index d79822034188..b0766d71e0e0 100644 --- a/lib/api/src/modules/provider.ts +++ b/lib/api/src/modules/provider.ts @@ -6,6 +6,11 @@ import { API, State, ModuleFn } from '../index'; import { StoryMapper, Refs } from './refs'; import { UIOptions } from './layout'; +interface SidebarOptions { + showRoots?: boolean; + collapsedRoots?: string[]; +} + type IframeRenderer = ( storyId: string, viewMode: State['viewMode'], @@ -20,6 +25,7 @@ export interface Provider { renderPreview?: IframeRenderer; handleAPI(api: API): void; getConfig(): { + sidebar?: SidebarOptions; theme?: ThemeVars; refs?: Refs; StoryMapper?: StoryMapper; diff --git a/lib/api/src/modules/stories.ts b/lib/api/src/modules/stories.ts index 775b3254e829..aa9407152eba 100644 --- a/lib/api/src/modules/stories.ts +++ b/lib/api/src/modules/stories.ts @@ -77,7 +77,6 @@ interface Meta { } const deprecatedOptionsParameterWarnings: Record void> = [ - 'sidebarAnimations', 'enableShortcuts', 'theme', 'showRoots', diff --git a/lib/api/src/tests/layout.test.js b/lib/api/src/tests/layout.test.js index ed729cc06f42..30acdf9abcd6 100644 --- a/lib/api/src/tests/layout.test.js +++ b/lib/api/src/tests/layout.test.js @@ -16,7 +16,6 @@ describe('layout API', () => { currentState = { ui: { enableShortcuts: true, - sidebarAnimations: true, docsMode: false, }, layout: { diff --git a/lib/api/src/tests/stories.test.js b/lib/api/src/tests/stories.test.js index b700c9be51d6..d76257575a9c 100644 --- a/lib/api/src/tests/stories.test.js +++ b/lib/api/src/tests/stories.test.js @@ -93,7 +93,7 @@ describe('stories API', () => { api: { setStories }, } = initStories({ store, navigate, provider }); - provider.getConfig.mockReturnValue({ showRoots: false }); + provider.getConfig.mockReturnValue({ sidebar: { showRoots: false } }); setStories(storiesHash); const { storiesHash: storedStoriesHash } = store.getState(); @@ -255,7 +255,7 @@ describe('stories API', () => { api: { setStories }, } = initStories({ store, navigate, provider }); - provider.getConfig.mockReturnValue({ showRoots: true }); + provider.getConfig.mockReturnValue({ sidebar: { showRoots: true } }); setStories({ 'a-b--1': { kind: 'a/b', @@ -302,7 +302,7 @@ describe('stories API', () => { api: { setStories }, } = initStories({ store, navigate, provider }); - provider.getConfig.mockReturnValue({ showRoots: true }); + provider.getConfig.mockReturnValue({ sidebar: { showRoots: true } }); setStories({ 'a--1': { kind: 'a',