Merge pull request #15192 from storybookjs/enableShortcuts-query-param

Core: Add `shortcuts` URL param to disable keyboard shortcuts

MIGRATION.md

@@ -8,6 +8,7 @@
     - [Deprecated addon-knobs](#deprecated-addon-knobs)
     - [Deprecated scoped blocks imports](#deprecated-scoped-blocks-imports)
     - [Deprecated `argType.defaultValue`](#deprecated-argtypedefaultvalue)
+    - [Deprecated layout URL params](#deprecated-layout-url-params)
 - [From version 6.1.x to 6.2.0](#from-version-61x-to-620)
   - [MDX pattern tweaked](#mdx-pattern-tweaked)
   - [6.2 Angular overhaul](#62-angular-overhaul)
@@ -241,6 +242,16 @@ export default {
 };
 ```
 
+#### Deprecated layout URL params
+
+Several URL params to control the manager layout have been deprecated and will be removed in 7.0:
+
+- `addons=0`: use `panel=false` instead
+- `panelRight=1`: use `panel=right` instead
+- `stories=0`: use `nav=false` instead
+
+Additionally, support for legacy URLs using `selectedKind` and `selectedStory` will be removed in 7.0. Use `path` instead.
+
 ## From version 6.1.x to 6.2.0
 
 ### MDX pattern tweaked

docs/configure/features-and-behavior.md

@@ -2,7 +2,7 @@
 title: 'Features and behavior'
 ---
 
-To control the layout of Storybook’s UI you can use the `setConfig` addons API in your [`.storybook/manager.js`](./overview.md#configure-story-rendering):
+To control the layout of Storybook’s UI you can use `addons.setConfig` in your [`.storybook/manager.js`](./overview.md#configure-story-rendering):
 
 <!-- prettier-ignore-start -->
 
@@ -25,7 +25,7 @@ The following table details how to use the API values:
 | **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`                                      |
+| **selectedPanel**     | String        |Id to select an addon panel                                    |`storybook/actions/panel`                       |
 | **initialActive**     | String        |Select the default active tab on Mobile                        |`sidebar` or `canvas` or `addons`               |
 | **sidebar**           | Object        |Sidebar options, see below                                     |`{ showRoots: false }`                          |
 | **toolbar**           | Object        |Modify the tools in the toolbar using the addon id             |`{ fullscreen: { hidden: false } } }`           |
@@ -43,3 +43,15 @@ The following options are configurable under the `toolbar` namespace:
 | Name                  | Type          | Description                                                   | Example Value                                  |
 | ----------------------|:-------------:|:-------------------------------------------------------------:|:----------------------------------------------:|
 | **id**                | String        |Toggle visibility for toolbar item                             |`{ hidden: false }`                            |
+
+## Configuring through URL parameters
+
+Some features can be controlled through URL parameters:
+
+| Config option         | Query param   | Supported values           |
+| ----------------------|:-------------:|:--------------------------:|
+| **enableShortcuts**   | `shortcuts`   | `false`                    |
+| **isFullscreen**      | `full`        | `true`                     |
+| **showNav**           | `nav`         | `false`                    |
+| **showPanel**         | `panel`       | `false`, `right`, `bottom` |
+| **selectedPanel**     | `addonPanel`  | Any panel ID               |

lib/api/src/modules/url.ts

@@ -1,4 +1,5 @@
 import { navigate as navigateRouter, NavigateOptions } from '@reach/router';
+import { once } from '@storybook/client-logger';
 import {
   NAVIGATE_URL,
   STORY_ARGS_UPDATED,
@@ -9,22 +10,14 @@ import { queryFromLocation, navigate as queryNavigate, buildArgsParam } from '@s
 import { toId, sanitize } from '@storybook/csf';
 import deepEqual from 'fast-deep-equal';
 import global from 'global';
+import dedent from 'ts-dedent';
 
 import { ModuleArgs, ModuleFn } from '../index';
-import { PanelPositions } from './layout';
+import { Layout, UI } from './layout';
 import { isStory } from '../lib/stories';
 
 const { window: globalWindow } = global;
 
-interface Additions {
-  isFullscreen?: boolean;
-  showPanel?: boolean;
-  panelPosition?: PanelPositions;
-  showNav?: boolean;
-  selectedPanel?: string;
-  viewMode?: string;
-}
-
 export interface SubState {
   customQueryParams: QueryParams;
 }
@@ -42,7 +35,8 @@ let prevParams: ReturnType<typeof queryFromLocation>;
 const initialUrlSupport = ({
   state: { location, path, viewMode, storyId: storyIdFromUrl },
 }: ModuleArgs) => {
-  const addition: Additions = {};
+  const layout: Partial<Layout> = {};
+  const ui: Partial<UI> = {};
   const query = queryFromLocation(location);
   let selectedPanel;
 
@@ -50,61 +44,83 @@ const initialUrlSupport = ({
     full,
     panel,
     nav,
-    addons,
-    panelRight,
-    stories,
+    shortcuts,
     addonPanel,
-    selectedKind,
-    selectedStory,
+    addons, // deprecated
+    panelRight, // deprecated
+    stories, // deprecated
+    selectedKind, // deprecated
+    selectedStory, // deprecated
     path: queryPath,
-    ...otherParams
+    ...otherParams // the rest gets passed to the iframe
   } = query;
 
-  if (full === '1') {
-    addition.isFullscreen = true;
+  if (full === 'true' || full === '1') {
+    layout.isFullscreen = true;
   }
   if (panel) {
     if (['right', 'bottom'].includes(panel)) {
-      addition.panelPosition = panel;
-    } else if (panel === '0') {
-      addition.showPanel = false;
+      layout.panelPosition = panel;
+    } else if (panel === 'false' || panel === '0') {
+      layout.showPanel = false;
     }
   }
-  if (nav === '0') {
-    addition.showNav = false;
+  if (nav === 'false' || nav === '0') {
+    layout.showNav = false;
   }
-
-  // Legacy URLs
-  if (addons === '0') {
-    addition.showPanel = false;
+  if (shortcuts === 'false' || shortcuts === '0') {
+    ui.enableShortcuts = false;
   }
-  if (panelRight === '1') {
-    addition.panelPosition = 'right';
-  }
-  if (stories === '0') {
-    addition.showNav = false;
-  }
-
   if (addonPanel) {
     selectedPanel = addonPanel;
   }
 
+  // @deprecated Superceded by `panel=false`, to be removed in 7.0
+  if (addons === '0') {
+    once.warn(dedent`
+      The 'addons' query param is deprecated and will be removed in Storybook 7.0. Use 'panel=false' instead.
+
+      More info: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-layout-url-params
+    `);
+    layout.showPanel = false;
+  }
+  // @deprecated Superceded by `panel=right`, to be removed in 7.0
+  if (panelRight === '1') {
+    once.warn(dedent`
+      The 'panelRight' query param is deprecated and will be removed in Storybook 7.0. Use 'panel=right' instead.
+
+      More info: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-layout-url-params
+    `);
+    layout.panelPosition = 'right';
+  }
+  // @deprecated Superceded by `nav=false`, to be removed in 7.0
+  if (stories === '0') {
+    once.warn(dedent`
+      The 'stories' query param is deprecated and will be removed in Storybook 7.0. Use 'nav=false' instead.
+
+      More info: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-layout-url-params
+    `);
+    layout.showNav = false;
+  }
+
+  // @deprecated To be removed in 7.0
   // If the user hasn't set the storyId on the URL, we support legacy URLs (selectedKind/selectedStory)
   // NOTE: this "storyId" can just be a prefix of a storyId, really it is a storyIdSpecifier.
   let storyId = storyIdFromUrl;
-  if (!storyId) {
-    if (selectedKind && selectedStory) {
-      storyId = toId(selectedKind, selectedStory);
-    } else if (selectedKind) {
-      storyId = sanitize(selectedKind);
-    }
+  if (!storyId && selectedKind) {
+    once.warn(dedent`
+      The 'selectedKind' and 'selectedStory' query params are deprecated and will be removed in Storybook 7.0. Use 'path' instead.
+
+      More info: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-layout-url-params
+    `);
+    storyId = selectedStory ? toId(selectedKind, selectedStory) : sanitize(selectedKind);
   }
 
   // Avoid returning a new object each time if no params actually changed.
   const customQueryParams = deepEqual(prevParams, otherParams) ? prevParams : otherParams;
   prevParams = customQueryParams;
 
-  return { viewMode, layout: addition, selectedPanel, location, path, customQueryParams, storyId };
+  return { viewMode, layout, ui, selectedPanel, location, path, customQueryParams, storyId };
 };
 
 export interface QueryParams {

lib/api/src/tests/url.test.js

@@ -2,6 +2,7 @@ import qs from 'qs';
 
 import { init as initURL } from '../modules/url';
 
+jest.mock('@storybook/client-logger');
 jest.useFakeTimers();
 
 describe('initial state', () => {
@@ -30,6 +31,17 @@ describe('initial state', () => {
       expect(layout).toEqual({ showNav: false });
     });
 
+    it('handles shortcuts parameter', () => {
+      const navigate = jest.fn();
+      const location = { search: qs.stringify({ shortcuts: '0' }) };
+
+      const {
+        state: { ui },
+      } = initURL({ navigate, state: { location } });
+
+      expect(ui).toEqual({ enableShortcuts: false });
+    });
+
     it('handles panel parameter, bottom', () => {
       const navigate = jest.fn();
       const location = { search: qs.stringify({ panel: 'bottom' }) };