storybookjs · shilman · Feb 27, 2021 · Feb 26, 2021
diff --git 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

@@ -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']`                             |
@@ -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):
 
 <!-- prettier-ignore-start -->
 
@@ -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):
 
-
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
@@ -41,7 +40,6 @@ As a CSF file is a JavaScript file, the exports (including the default export) c
 
 <!-- prettier-ignore-end -->
 
-
 ## 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).

@@ -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'],
+  },
 });
-```
+```
@@ -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
@@ -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
@@ -111,6 +111,14 @@ export type SetStoriesPayload =
       stories: StoriesRaw;
     } & Record<string, never>);
 
+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
@@ -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
@@ -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
@@ -77,7 +77,6 @@ interface Meta {
 }
 
 const deprecatedOptionsParameterWarnings: Record<string, () => void> = [
-  'sidebarAnimations',
   'enableShortcuts',
   'theme',
   'showRoots',

diff --git 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
@@ -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',