Merge pull request #1692 from storybooks/deprecate-left-down

Deprecate confusing option names

addons/options/.storybook/config.js

@@ -5,10 +5,10 @@ setOptions({
   name: 'CUSTOM-OPTIONS',
   url: 'https://github.com/storybooks/storybook',
   // goFullScreen: false,
-  // showLeftPanel: true,
-  showDownPanel: false,
+  // showStoriesPanel: true,
+  showAddonPanel: false,
   // showSearchBox: false,
-  // downPanelInRight: false,
+  // addonPanelInRight: false,
 });
 
 storybook.configure(() => require('./stories'), module);

addons/options/README.md

@@ -53,25 +53,25 @@ setOptions({
    */
   goFullScreen: false,
   /**
-   * display left panel that shows a list of stories
+   * display panel that shows a list of stories
    * @type {Boolean}
    */
-  showLeftPanel: true,
+  showStoriesPanel: true,
   /**
-   * display horizontal panel that displays addon configurations
+   * display panel that shows addon configurations
    * @type {Boolean}
    */
-  showDownPanel: true,
+  showAddonPanel: true,
   /**
    * display floating search box to search through stories
    * @type {Boolean}
    */
   showSearchBox: false,
   /**
-   * show horizontal addons panel as a vertical panel on the right
+   * show addon panel as a vertical panel on the right
    * @type {Boolean}
    */
-  downPanelInRight: false,
+  addonPanelInRight: false,
   /**
    * sorts stories
    * @type {Boolean}
@@ -98,7 +98,7 @@ setOptions({
    * id to select an addon panel
    * @type {String}
    */
-  selectedAddonPanel: undefined, // The order of addons in the "Addons Panel" is the same as you import them in 'addons.js'. The first panel will be opened by default as you run Storybook
+  selectedAddonPanel: undefined, // The order of addons in the "Addon panel" is the same as you import them in 'addons.js'. The first panel will be opened by default as you run Storybook
 });
 
 storybook.configure(() => require('./stories'), module);

docs/pages/basics/guide-vue/index.md

@@ -1,7 +1,8 @@
----
+* * *
+
 id: 'guide-vue'
-title: 'Storybook for Vue'
----
+
+## title: 'Storybook for Vue'
 
 You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
 

examples/cra-kitchen-sink/.storybook/config.js

@@ -6,10 +6,10 @@ setOptions({
   name: 'CRA Kitchen Sink',
   url: 'https://github.com/storybooks/storybook/tree/master/examples/cra-kitchen-sink',
   goFullScreen: false,
-  showLeftPanel: true,
-  showDownPanel: true,
+  showStoriesPanel: true,
+  showAddonsPanel: true,
   showSearchBox: false,
-  downPanelInRight: true,
+  addonsPanelInRight: true,
   sortStoriesByKind: false,
   hierarchySeparator: /\/|\./,
 });

lib/ui/src/libs/key_events.js

@@ -1,15 +1,15 @@
 import keycode from 'keycode';
 
 export const features = {
-  FULLSCREEN: 1,
-  DOWN_PANEL: 2,
-  LEFT_PANEL: 3,
-  SHORTCUTS_HELP: 4,
-  ESCAPE: 5,
-  NEXT_STORY: 6,
-  PREV_STORY: 7,
-  SHOW_SEARCH: 8,
-  DOWN_PANEL_IN_RIGHT: 9,
+  FULLSCREEN: 'FULLSCREEN',
+  ADDON_PANEL: 'ADDON_PANEL',
+  STORIES_PANEL: 'STORIES_PANEL',
+  SHORTCUTS_HELP: 'SHORTCUTS_HELP',
+  ESCAPE: 'ESCAPE',
+  NEXT_STORY: 'NEXT_STORY',
+  PREV_STORY: 'PREV_STORY',
+  SHOW_SEARCH: 'SHOW_SEARCH',
+  ADDON_PANEL_IN_RIGHT: 'ADDON_PANEL_IN_RIGHT',
 };
 
 export function isModifierPressed(e) {
@@ -42,10 +42,10 @@ export default function handle(e) {
       return features.FULLSCREEN;
     case keycode('D'):
       e.preventDefault();
-      return features.DOWN_PANEL;
+      return features.ADDON_PANEL;
     case keycode('L'):
       e.preventDefault();
-      return features.LEFT_PANEL;
+      return features.STORIES_PANEL;
     case keycode('right'):
       e.preventDefault();
       return features.NEXT_STORY;
@@ -57,7 +57,7 @@ export default function handle(e) {
       return features.SHOW_SEARCH;
     case keycode('J'):
       e.preventDefault();
-      return features.DOWN_PANEL_IN_RIGHT;
+      return features.ADDON_PANEL_IN_RIGHT;
     default:
       return false;
   }

lib/ui/src/modules/api/actions/api.test.js

@@ -216,7 +216,7 @@ describe('manager.api.actions.api', () => {
       expect(stateUpdates.selectedAddonPanel).toEqual('storybooks/storybook-addon-knobs');
     });
 
-    it('should keep current downPanel and output panel IDs', () => {
+    it('should keep current addonPanel and output panel IDs', () => {
       const clientStore = new MockClientStore();
       actions.setOptions({ clientStore, provider }, { selectedAddonPanel: null });
 

lib/ui/src/modules/shortcuts/actions/shortcuts.js

@@ -2,23 +2,32 @@ import pick from 'lodash.pick';
 import { features } from '../../../libs/key_events';
 import apiActions from '../../api/actions';
 
+const deprecationMessage = (oldName, newName) =>
+  `The ${oldName} option has been renamed to ${newName} and will not be available in the next major Storybook release. Please update your config.`;
+
 export function keyEventToOptions(currentOptions, event) {
   switch (event) {
     case features.FULLSCREEN:
       return { goFullScreen: !currentOptions.goFullScreen };
-    case features.DOWN_PANEL:
-      return { showDownPanel: !currentOptions.showDownPanel };
-    case features.LEFT_PANEL:
-      return { showLeftPanel: !currentOptions.showLeftPanel };
+    case features.ADDON_PANEL:
+      return { showAddonPanel: !currentOptions.showAddonPanel };
+    case features.STORIES_PANEL:
+      return { showStoriesPanel: !currentOptions.showStoriesPanel };
     case features.SHOW_SEARCH:
       return { showSearchBox: true };
-    case features.DOWN_PANEL_IN_RIGHT:
-      return { downPanelInRight: !currentOptions.downPanelInRight };
+    case features.ADDON_PANEL_IN_RIGHT:
+      return { addonPanelInRight: !currentOptions.addonPanelInRight };
     default:
       return {};
   }
 }
 
+const renamedOptions = {
+  showLeftPanel: 'showStoriesPanel',
+  showDownPanel: 'showAddonPanel',
+  downPanelInRight: 'addonPanelInRight',
+};
+
 export default {
   handleEvent(context, event) {
     const { clientStore } = context;
@@ -51,8 +60,26 @@ export default {
         ...pick(options, Object.keys(state.shortcutOptions)),
       };
 
+      const withNewNames = Object.keys(renamedOptions).reduce((acc, oldName) => {
+        const newName = renamedOptions[oldName];
+
+        if (oldName in options && !(newName in options)) {
+          if (process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.warn(deprecationMessage(oldName, newName));
+          }
+
+          return {
+            ...acc,
+            [newName]: options[oldName],
+          };
+        }
+
+        return acc;
+      }, updatedOptions);
+
       return {
-        shortcutOptions: updatedOptions,
+        shortcutOptions: withNewNames,
       };
     });
   },

lib/ui/src/modules/shortcuts/actions/shortcuts.test.js

@@ -35,5 +35,34 @@ describe('manager.shortcuts.actions.shortcuts', () => {
         shortcutOptions: { bbc: 50, abc: 10 },
       });
     });
+
+    test('should warn about deprecated option names', () => {
+      const clientStore = new MockClientStore();
+      const spy = jest.spyOn(console, 'warn');
+      actions.setOptions(
+        { clientStore },
+        {
+          showLeftPanel: 1,
+          showDownPanel: 2,
+          downPanelInRight: 3,
+        }
+      );
+
+      const state = {
+        shortcutOptions: {},
+      };
+      const stateUpdates = clientStore.updateCallback(state);
+      expect(spy).toHaveBeenCalledTimes(3);
+      expect(stateUpdates).toEqual({
+        shortcutOptions: {
+          showStoriesPanel: 1,
+          showAddonPanel: 2,
+          addonPanelInRight: 3,
+        },
+      });
+
+      spy.mockReset();
+      spy.mockRestore();
+    });
   });
 });

lib/ui/src/modules/shortcuts/index.js

@@ -5,10 +5,10 @@ export default {
   defaultState: {
     shortcutOptions: {
       goFullScreen: false,
-      showLeftPanel: true,
-      showDownPanel: true,
+      showStoriesPanel: true,
+      showAddonPanel: true,
       showSearchBox: false,
-      downPanelInRight: false,
+      addonPanelInRight: false,
     },
   },
 };

lib/ui/src/modules/ui/actions/ui.js

@@ -7,7 +7,7 @@ export default {
     clientStore.toggle('showShortcutsHelp');
   },
 
-  selectDownPanel({ clientStore }, panelName) {
+  selectAddonPanel({ clientStore }, panelName) {
     clientStore.set('selectedAddonPanel', panelName);
   },
 };

lib/ui/src/modules/ui/actions/ui.test.js

@@ -24,13 +24,13 @@ describe('manager.ui.actions.ui', () => {
     });
   });
 
-  describe('selectDownPanel', () => {
+  describe('selectAddonPanel', () => {
     it('should set the given panel name', () => {
       const clientStore = {
         set: jest.fn(),
       };
       const panelName = 'kkkind';
-      actions.selectDownPanel({ clientStore }, panelName);
+      actions.selectAddonPanel({ clientStore }, panelName);
 
       expect(clientStore.set).toHaveBeenCalledWith('selectedAddonPanel', panelName);
     });

lib/ui/src/modules/ui/components/down_panel/index.js → lib/ui/src/modules/ui/components/addon_panel/index.js

@@ -2,7 +2,7 @@ import PropTypes from 'prop-types';
 import React, { Component } from 'react';
 import style from './style';
 
-class DownPanel extends Component {
+class AddonPanel extends Component {
   renderTab(name, panel) {
     let tabStyle = style.tablink;
     if (this.props.selectedPanel === name) {
@@ -69,16 +69,16 @@ class DownPanel extends Component {
   }
 }
 
-DownPanel.defaultProps = {
+AddonPanel.defaultProps = {
   panels: {},
   onPanelSelect: () => {},
   selectedPanel: null,
 };
 
-DownPanel.propTypes = {
+AddonPanel.propTypes = {
   panels: PropTypes.object, // eslint-disable-line react/forbid-prop-types
   onPanelSelect: PropTypes.func,
   selectedPanel: PropTypes.string,
 };
 
-export default DownPanel;
+export default AddonPanel;

lib/ui/src/modules/ui/components/down_panel/index.test.js → lib/ui/src/modules/ui/components/addon_panel/index.test.js

@@ -1,8 +1,8 @@
 import React from 'react';
 import { shallow } from 'enzyme';
-import DownPanel from './index';
+import AddonPanel from './index';
 
-describe('manager.ui.components.down_panel.index', () => {
+describe('manager.ui.components.addon_panel.index', () => {
   test('should render only the selected panel with display set other than "none"', () => {
     const panels = {
       test1: {
@@ -20,7 +20,7 @@ describe('manager.ui.components.down_panel.index', () => {
     const onPanelSelect = () => 'onPanelSelect';
 
     const wrapper = shallow(
-      <DownPanel panels={panels} onPanelSelect={onPanelSelect} selectedPanel={'test2'} />
+      <AddonPanel panels={panels} onPanelSelect={onPanelSelect} selectedPanel={'test2'} />
     );
 
     expect(wrapper.find('#test1').parent()).toHaveStyle('display', 'none');
@@ -38,7 +38,7 @@ describe('manager.ui.components.down_panel.index', () => {
     const onPanelSelect = jest.fn();
     const preventDefault = jest.fn();
     const wrapper = shallow(
-      <DownPanel panels={panels} onPanelSelect={onPanelSelect} selectedPanel={'test1'} />
+      <AddonPanel panels={panels} onPanelSelect={onPanelSelect} selectedPanel={'test1'} />
     );
     wrapper.find('a').simulate('click', { preventDefault });
 
@@ -50,7 +50,7 @@ describe('manager.ui.components.down_panel.index', () => {
     test('should render "no panels available"', () => {
       const panels = {};
       const onPanelSelect = () => 'onPanelSelect';
-      const wrapper = shallow(<DownPanel panels={panels} onPanelSelect={onPanelSelect} />);
+      const wrapper = shallow(<AddonPanel panels={panels} onPanelSelect={onPanelSelect} />);
 
       expect(wrapper.contains('no panels available')).toBe(true);
     });