@storybook/server 6.5.9 → 7.0.0-alpha.2

package/README.md

@@ -1,317 +1 @@
-# Storybook for Server
-
----
-
-Storybook for Server is a UI development environment for your plain HTML snippets rendered by your server backend.
-With it, you can visualize different states of your UI components and develop them interactively.
-
-![Storybook Screenshot](https://github.com/storybookjs/storybook/blob/main/media/storybook-intro.gif)
-
-Storybook runs outside of your app.
-So you can develop UI components in isolation without worrying about app specific dependencies and requirements.
-
-## Getting Started
-
-```sh
-cd my-app
-npx sb init -t server
-```
-
-To configure the server that Storybook will connect to, export a global parameter `parameters.server.url` in `.storybook/preview.js`:
-
-```js
-export const parameters = {
-  server: {
-    url: `http://localhost:${port}/storybook_preview`,
-  },
-};
-```
-
-The URL you connect to should have the ability to render a story, see [server rendering](#server-rendering) below.
-
-For more information visit: [storybook.js.org](https://storybook.js.org)
-
-## Writing Stories
-
-To write a story, use whatever API is natural for your server-side rendering framework to generate set of JSON or YAML files of stories analogous to CSF files (see the [`server-kitchen-sink`](../../examples/server-kitchen-sink/stories) example for ideas).
-
-```json
-{
-  "title": "Component",
-  "parameters": {
-    "options": { "component": "my_widget" }
-  },
-  "stories": [
-    {
-      "name": "Default",
-      "parameters": {
-        "server": { "id": "path/of/your/story" }
-      }
-    }
-  ]
-}
-```
-
-In your `.storybook/main.js` you simply provide a glob specifying the location of those JSON files, e.g.
-
-```js
-module.exports = {
-  stories: ['../stories/**/*.stories.json'],
-};
-```
-
-Notice that the JSON does not specify a rendering function -- `@storybook/server` will instead call your `parameters.server.url` with the story's server id appended.
-
-For example the JSON story above is requivalent to the CSF3 definition:
-
-```javascript
-export default {
-  title: 'Component',
-  parameters: {
-    options: {
-      component: 'my_widget',
-    },
-  },
-};
-
-export const Default = {
-  name: 'Default',
-  parameters: {
-    server: {
-      id: 'path/of/your/story"',
-    },
-  },
-};
-```
-
-With the story HTML will be fetched from the server by making a GET request to http://localhost/storybook_preview/path/of/your/story`
-
-### Ruby/Rails support
-
-In particular the [View Component::Storybook](https://github.com/jonspalmer/view_component_storybook) gem provides a Ruby API for easily creating the above with a Ruby/Rails DSL (as well as providing a server rendering endpoint).
-
-## Server rendering
-
-The server rendering side of things is relatively straightfoward. When you browse to a story in the sidebar, Storybook will make a `fetch` request to `${parameters.server.url}/{parameters.server.id}` and display the HTML that is returned.
-
-You need to ensure the route in your server app renders the appropriate HTML when called in that fashion.
-
-### Passing parameters to the server
-
-Many components are likely to be dynamic - responding to parameters that change their content or appearance. `@storybook\server` has two mechanisms for passing those parameters to the server - `params` and `args`. Parameters defined in this way are appended to the fetch url as query string parameters. The server endpoint is responsible for interpreting those parameters and vary the returned html appropriately
-
-#### Constant parameters with `params`
-
-Static parameters can be defined using the `params` story parameter. For example suppose you have a Button component that has a label and color options:
-
-```json
-{
-  "title": "Buttons",
-  "stories": [
-    {
-      "name": "Red",
-      "parameters": {
-        "server": {
-          "id": "button",
-          "params": { "color": "red", "label": "Stop" }
-        }
-      }
-    },
-    {
-      "name": "Green",
-      "parameters": {
-        "server": {
-          "id": "button",
-          "params": { "color": "green", "label": "OK" }
-        }
-      }
-    }
-  ]
-}
-```
-
-The Red and Green story HTML will be fetched from the urls `server.url/controls/button?color=red&label=Stop` and `server.url/controls/button?color=green&label=OK`
-
-Like all story parameters server params can be defined in the default export and overridden in stories.
-
-```json
-{
-  "title": "Buttons",
-  "parameters": {
-    "server": {
-      "params": { "color": "red" }
-    }
-  },
-  "stories": [
-    {
-      "name": "Default",
-      "parameters": {
-        "server": {
-          "id": "button",
-          "params": { "label": "Stop" }
-        }
-      }
-    },
-    {
-      "name": "Green",
-      "parameters": {
-        "server": {
-          "id": "button",
-          "params": { "color": "green", "label": "OK" }
-        }
-      }
-    }
-  ]
-}
-```
-
-#### Dynamic parameters with `args` and Controls
-
-Dynamic parameters can be defined using args and the Controls addon
-
-```json
-{
-  "title": "Buttons",
-  "stories": [
-    {
-      "name": "Red",
-      "parameters": {
-        "server": {
-          "id": "button"
-        }
-      },
-      "args": { "color": "red", "label": "Stop" }
-    },
-    {
-      "name": "Green",
-      "parameters": {
-        "server": {
-          "id": "button"
-        }
-      },
-      "args": { "color": "green", "label": "Go" }
-    }
-  ]
-}
-```
-
-Story args are passed to the server as url query parameters just like `params` except now they can be varied on the Controls addon panel.
-
-Just like CSF stories we can define `argTypes` to specify the controls used in the controls panel. `argTypes` can be defined at the default or story level.
-
-```json
-{
-  "title": "Buttons",
-  "argTypes": {
-    "color": { "control": { "type": "color" } }
-  },
-  "stories": [
-    {
-      "name": "Red",
-      "parameters": {
-        "server": {
-          "id": "button"
-        }
-      },
-      "args": { "color": "red", "label": "Stop" }
-    },
-    {
-      "name": "Green",
-      "parameters": {
-        "server": {
-          "id": "button"
-        }
-      },
-      "args": { "color": "green", "label": "Go" }
-    }
-  ]
-}
-```
-
-## Addon compatibility
-
-Storybook also comes with a lot of [addons](https://storybook.js.org/addons) and a great API to customize as you wish. As some addons assume the story is rendered in JS, they may not work with `@storybook/server` (yet!).
-
-Many addons that act on the manager side (such as `backgrounds` and `viewport`) will work out of the box with `@storybook/server` -- you can configure them with parameters written on the server as usual.
-
-### Controls
-
-To configure controls, simple add `args` and `argTypes` keys to the story JSON much like you would CSF:
-
-```json
-{
-  "title": "Controls",
-  "stories": [
-    {
-      "name": "Button",
-      "parameters": {
-        "server": { "id": "controls/button" }
-      },
-      "args": { "button_text": "Push Me", "color": "red" },
-      "argTypes": { "button_text": { "control": { "type": "color" } } }
-    }
-  ]
-}
-```
-
-The controls values will be added to your story URL as query parameters.
-
-### Actions
-
-To use actions, use the `parameters.actions.handles` parameter:
-
-```json
-{
-  "title": "Actions",
-  "stories": [
-    {
-      "name": "Button",
-      "parameters": {
-        "server": { "id": "actions/button" },
-        "actions": {
-          "handles": ["mouseover", "click .btn"]
-        }
-      }
-    }
-  ]
-}
-```
-
-## Advanced Configuration
-
-### fetchStoryHtml
-
-For control over how `@storybook/server` fetches Html from the server you can provide a `fetchStoryHtml` function as a parameter. You would typically set this in `.storybook/preview.js` but it's just a regular Storybook parameter so could be overridden at the stories or story level.
-
-```javascript
-// .storybook/preview.js
-
-const fetchStoryHtml = async (url, path, params, context) => {
-  // Custom fetch implementation
-  // ....
-  return html;
-};
-
-export const parameters = {
-  server: {
-    url: `http://localhost:${port}/storybook_preview`,
-    fetchStoryHtml,
-  },
-};
-```
-
-`fetchStoryHtml` should be an async function with the following signature
-
-```javascript
-type FetchStoryHtmlType = (
-  url: string,
-  id: string,
-  params: any,
-  context: StoryContext
-) => Promise<string | Node>;
-```
-
-- url: Server url configured by the `parameters.server.url`
-- id: Id of the story being rendered given by `parameters.server.id`
-- params: Merged story params `parameters.server.params`and story args
-- context: The context of the story
+# Storybook Server renderer

package/dist/cjs/{client/index.js → index.js}

@@ -5,55 +5,56 @@ Object.defineProperty(exports, "__esModule", {
 });
 Object.defineProperty(exports, "addDecorator", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.addDecorator;
   }
 });
 Object.defineProperty(exports, "addParameters", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.addParameters;
   }
 });
 Object.defineProperty(exports, "configure", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.configure;
   }
 });
 Object.defineProperty(exports, "forceReRender", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.forceReRender;
   }
 });
 Object.defineProperty(exports, "getStorybook", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.getStorybook;
   }
 });
 Object.defineProperty(exports, "raw", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.raw;
   }
 });
 Object.defineProperty(exports, "setAddon", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.setAddon;
   }
 });
 Object.defineProperty(exports, "storiesOf", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _preview.storiesOf;
   }
 });
 
 var _preview = require("./preview");
 
-if (module && module.hot && module.hot.decline) {
-  module.hot.decline();
-}
+var _module, _module$hot;
+
+// optimization: stop HMR propagation in webpack
+(_module = module) === null || _module === void 0 ? void 0 : (_module$hot = _module.hot) === null || _module$hot === void 0 ? void 0 : _module$hot.decline();

package/dist/cjs/{client/preview → preview}/config.js

@@ -6,20 +6,20 @@ Object.defineProperty(exports, "__esModule", {
 exports.parameters = void 0;
 Object.defineProperty(exports, "render", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _render.render;
   }
 });
 Object.defineProperty(exports, "renderToDOM", {
   enumerable: true,
-  get: function get() {
+  get: function () {
     return _render.renderToDOM;
   }
 });
 
 var _render = require("./render");
 
-var parameters = {
+const parameters = {
   framework: 'server'
 };
 exports.parameters = parameters;

package/dist/cjs/{client/preview → preview}/globals.js

@@ -4,5 +4,7 @@ var _global = _interopRequireDefault(require("global"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-var globalWindow = _global.default.window;
+const {
+  window: globalWindow
+} = _global.default;
 globalWindow.STORYBOOK_ENV = 'SERVER';

package/dist/cjs/preview/index.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.storiesOf = exports.setAddon = exports.raw = exports.getStorybook = exports.forceReRender = exports.configure = exports.clearDecorators = exports.addParameters = exports.addDecorator = void 0;
+
+var _coreClient = require("@storybook/core-client");
+
+require("./globals");
+
+var _render = require("./render");
+
+const framework = 'server';
+const api = (0, _coreClient.start)(_render.renderToDOM, {
+  render: _render.render
+});
+
+const storiesOf = (kind, m) => {
+  return api.clientApi.storiesOf(kind, m).addParameters({
+    framework
+  });
+};
+
+exports.storiesOf = storiesOf;
+
+const configure = (...args) => api.configure(framework, ...args);
+
+exports.configure = configure;
+const {
+  addDecorator,
+  addParameters,
+  clearDecorators,
+  setAddon,
+  getStorybook,
+  raw
+} = api.clientApi;
+exports.raw = raw;
+exports.getStorybook = getStorybook;
+exports.setAddon = setAddon;
+exports.clearDecorators = clearDecorators;
+exports.addParameters = addParameters;
+exports.addDecorator = addDecorator;
+const {
+  forceReRender
+} = api;
+exports.forceReRender = forceReRender;

package/dist/cjs/preview/render.js

@@ -0,0 +1,113 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.render = void 0;
+exports.renderToDOM = renderToDOM;
+
+var _global = _interopRequireDefault(require("global"));
+
+var _tsDedent = _interopRequireDefault(require("ts-dedent"));
+
+var _previewWeb = require("@storybook/preview-web");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/* eslint-disable no-param-reassign */
+const {
+  fetch,
+  Node
+} = _global.default;
+
+const defaultFetchStoryHtml = async (url, path, params, storyContext) => {
+  const fetchUrl = new URL(`${url}/${path}`);
+  fetchUrl.search = new URLSearchParams(Object.assign({}, storyContext.globals, params)).toString();
+  const response = await fetch(fetchUrl);
+  return response.text();
+};
+
+const buildStoryArgs = (args, argTypes) => {
+  const storyArgs = Object.assign({}, args);
+  Object.keys(argTypes).forEach(key => {
+    const argType = argTypes[key];
+    const {
+      control
+    } = argType;
+    const controlType = control && control.type.toLowerCase();
+    const argValue = storyArgs[key];
+
+    switch (controlType) {
+      case 'date':
+        // For cross framework & language support we pick a consistent representation of Dates as strings
+        storyArgs[key] = new Date(argValue).toISOString();
+        break;
+
+      case 'object':
+        // send objects as JSON strings
+        storyArgs[key] = JSON.stringify(argValue);
+        break;
+
+      default:
+    }
+  });
+  return storyArgs;
+};
+
+const render = args => {};
+
+exports.render = render;
+
+async function renderToDOM({
+  id,
+  title,
+  name,
+  showMain,
+  showError,
+  forceRemount,
+  storyFn,
+  storyContext,
+  storyContext: {
+    parameters,
+    args,
+    argTypes
+  }
+}, domElement) {
+  // Some addons wrap the storyFn so we need to call it even though Server doesn't need the answer
+  storyFn();
+  const storyArgs = buildStoryArgs(args, argTypes);
+  const {
+    server: {
+      url,
+      id: storyId,
+      fetchStoryHtml = defaultFetchStoryHtml,
+      params
+    }
+  } = parameters;
+  const fetchId = storyId || id;
+  const storyParams = Object.assign({}, params, storyArgs);
+  const element = await fetchStoryHtml(url, fetchId, storyParams, storyContext);
+  showMain();
+
+  if (typeof element === 'string') {
+    domElement.innerHTML = element;
+    (0, _previewWeb.simulatePageLoad)(domElement);
+  } else if (element instanceof Node) {
+    // Don't re-mount the element if it didn't change and neither did the story
+    if (domElement.firstChild === element && forceRemount === false) {
+      return;
+    }
+
+    domElement.innerHTML = '';
+    domElement.appendChild(element);
+    (0, _previewWeb.simulateDOMContentLoaded)();
+  } else {
+    showError({
+      title: `Expecting an HTML snippet or DOM node from the story: "${name}" of "${title}".`,
+      description: (0, _tsDedent.default)`
+        Did you forget to return the HTML snippet from the story?
+        Use "() => <your snippet or node>" or when defining the story.
+      `
+    });
+  }
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { storiesOf, setAddon, addDecorator, addParameters, configure, getStorybook, forceReRender, raw } from './preview'; // optimization: stop HMR propagation in webpack
+
+module?.hot?.decline();

package/dist/{modern/client → esm}/preview/index.js

@@ -1,4 +1,4 @@
-import { start } from '@storybook/core';
+import { start } from '@storybook/core-client';
 import './globals';
 import { renderToDOM, render } from './render';
 const framework = 'server';

package/dist/{ts3.9/client → types}/preview/index.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="webpack-env" />
-/// <reference types="node" />
 import type { ClientStoryApi, Loadable } from '@storybook/addons';
 import './globals';
 import type { IStorybookSection, ServerFramework } from './types';
@@ -16,6 +15,6 @@ export declare const configure: ClientApi['configure'];
 export declare const addDecorator: (() => never) | ((decorator: import("@storybook/csf").DecoratorFunction<ServerFramework, import("@storybook/addons").Args>) => void), addParameters: (({ globals, globalTypes, ...parameters }: import("@storybook/csf").Parameters & {
     globals?: import("@storybook/csf").Globals;
     globalTypes?: import("@storybook/csf").GlobalTypes;
-}) => void) | (() => never), clearDecorators: (() => void) | (() => never), setAddon: ((addon: any) => void) | (() => never), getStorybook: (() => never) | (() => import("@storybook/client-api/dist/ts3.9/ClientApi").GetStorybookKind<ServerFramework>[]), raw: (() => never) | (() => import("@storybook/store").BoundStory<ServerFramework>[]);
+}) => void) | (() => never), clearDecorators: (() => void) | (() => never), setAddon: ((addon: any) => void) | (() => never), getStorybook: (() => never) | (() => import("lib/client-api/dist/types/ClientApi").GetStorybookKind<ServerFramework>[]), raw: (() => never) | (() => import("lib/store/dist/types").BoundStory<ServerFramework>[]);
 export declare const forceReRender: (() => never) | (() => void);
 export {};

package/dist/{ts3.9/client → types}/preview/types.d.ts

@@ -1,5 +1,5 @@
 import type { StoryContext } from '@storybook/csf';
-export type { RenderContext } from '@storybook/core';
+export type { RenderContext } from '@storybook/core-client';
 export declare type StoryFnServerReturnType = any;
 export declare type ServerFramework = {
     component: string;