Storybook: Provide proper documentation for storiesOf API.

Created on 27 Aug 2020 · 8Comments · Source: storybookjs/storybook

The storiesOf API is still important to StoryBookJS functionality. We rely on it for React Native, and the fact that it doesn't rely on module default exports makes the storiesOf API much more usable from languages such as ClojureScript. But the storiesOf API is poorly documented for a new user. I had to dig into source code just to learn about the .addParameters and addDecorator methods.

It's clear that the Storybook team wants to push the CSF workflow, but I think the storiesOf API still needs first-class documentation. The current documentation is not comprehensive at all. I'd be happy to give a new user's feedback on new docs, but because it doesn't currently exist I really don't know the full capabilities of the storiesOf API.

For what it's worth, I actually like the storiesOf API more than the CSF workflow. I'm writing a ClojureScript wrapper for StorybookJS right now, and I'm finding storiesOf far easier to design an interface for than CSF. I hope it sticks around!

documentation inactive

Source

neilyio

👍1

Most helpful comment

Here is a codesandbox with three storiesOf examples. https://codesandbox.io/s/nervous-violet-l7mxf?file=/src/stories/stories-of-example.stories.tsx

The following snippet is just the code from the codesandbox example, incase it stops working:

import { storiesOf } from "@storybook/react";
import React from "react";

import { Thing } from "../Thing";

/**
 * Adding Controls support to individual stories.
 *
 * "Thing1" has controls configured.
 * "Thing2" does not have controls configured.
 */
storiesOf("StoriesOf/Basic", module)
  .add("Thing1", (args) => <Thing {...args}>Example</Thing>, {
    component: Thing
  })
  .add("Thing2", (args) => <Thing {...args}>Example</Thing>);

/**
 * Adding Controls support to multiple stories at once.
 */
storiesOf("StoriesOf/WithAddParameters", module)
  .addParameters({ component: Thing })

  .add("Thing1", (args) => <Thing {...args}>Example</Thing>)
  .add("Thing2", (args) => <Thing {...args}>Example</Thing>);

/**
 * Manually configuring Controls, without the warning.
 *
 * Without `controls: { hideNoControlsWarning: true }` the warning
 * about the component not being configured for controls will be
 * visible.
 */
storiesOf("StoriesOf/NoWarning", module).add(
  "Thing1",
  ({ something, ...args }) => <Thing {...args}>{something}</Thing>,
  {
    argTypes: {
      something: "text"
    },
    controls: { hideNoControlsWarning: true }
  }
);

Marklb on 4 Sep 2020

❤2

All 8 comments

@neilyio what's missing? cc @tmeasday

shilman on 28 Aug 2020

I'd say:

What does the second "module" argument to storiesOf do? I had to find the answer by stumbling on this issue.
In the "Decorators and Parameters" section, it says "Decorators and parameters can be specified globally, at the component level, or locally at the story level." It then only describes how to accomplish this at the story level, not globally or at the component level.
The docs need a description of the arguments for .addParameters and .addDecorator methods, and how they work. I was able to guess that they're "chainable" the way that add is, but I shouldn't have to guess. It would be worth providing a usage example, particularly because it doesn't seem like they work quite the same way as the story-level parameters in the example given (e.g. .addParameters only needs to be called once with an object map, where .addDecorator must be called once for each decorator you add... this is inconsistent with story-level parameters which take a list of decorators on the the decorators key).
How does one use args and argTypes with the storiesOf API? Are they just passed as parameters? I genuinely don't know the answer to this one. Trial and error will probably tell me, but users shouldn't have to do that. As of now, I have no idea how to configure add-ons like Controls with storiesOf.
Be extremely clear about what features, if any, are not available with the storiesOf API. It would be a shame for React Native users (or other language users, like myself), to spend huge amounts of time getting their projects set up with Storybook only to find out through trial and error that necessary features aren't supported. I'm getting a sinking feeling that args (and thus add-ons like Controls) aren't going to work properly with the storiesOf API, which would be a dealbreaker for me. If this is true (please let me know ASAP if so), I'll have to drop Storybook + my ClojureScript wrapper after having spent a couple days on it.

I had to do quite a bit of digging on Google and console inspection to find all this out, because all the literature out there caters to the CSF format now. It would save a lot of time for future users to have the whole API laid out clearly.

neilyio on 28 Aug 2020

👍1

Hi @neilyio

Apologies about the oversight about .addParameters()/.addDecorators(), I think this was an honest mistake in getting everything together for 6.0. Can you send a PR to fix it?
Re: args/argTypes -- I'm not sure exactly how to do it, @shilman are they still done as parameters? The CSF API still calls .storiesOf behind the scenes so it certainly is possible. For that reason I don't think you need to worry about feature compat.

Having said that, rather than putting effort into making storiesOf first class, can we instead resolve the issues that stop you from using CSF in ClosureScript?

tmeasday on 28 Aug 2020

Args with storiesOf:

import { storiesOf } from '@storybook/react';
import { Button } from './button';
import React from 'react';

storiesOf('Example/Button', module).add(
  'with text',
  (args: any) => <Button {...args}/>,
  {
    component: Button, // This would tell it what component for auto-generated controls.
    args: {
      label: 'With Args'
    },
    argTypes: {
      label: { type: 'string' }
    }
  }
);

Marklb on 28 Aug 2020

🎉1

Just submitted #12302 for points 1. 2. 3. above.

I'd like to add another line to address 5., something along the lines of "CSF uses storiesOf under the hood, so you don't have to worry about feature incompatibility". I thought I should ask about this first because it feels like a big promise, but there's so little literature out there for storiesOf that I think users need some reassurance like this.

I think there should also be a new section on the storiesOf page for args and argTypes, but I didn't include that in my PR because I still have no idea how they work.

Thanks for the code example @Marklb, I'm afraid it's still not working for me, but I think it might related to issue #11769. I'm getting the same symptoms (even in 6.0.20).

Thanks for letting me vent my frustration @tmeasday, I'm a fan of Storybook so far and I would love to see more people in the Clojure community using it. I like your point about trying to get CSF to suit everyone's needs; I'm going to do my best to describe my challenges with it:

Doesn't work with React Native. Will it ever, or is that an inherent limitation?
Relying on the default export means that you can only have one component per file. More files means more import-related boilerplate, etc. Clojure/ClojureScript is a very concise language, and because of this I find the community likes to pack a lot into one file. I like the storiesOf API because it doesn't care about my file structure (outside of the module argument, which I'm able to abstract away with a nice Clojure macro).
Relying on module exports/default exports creates inconsistencies in Storybook setup for different build tools. I can only speak for ClojureScript, where some slightly nasty (and tool-specific) syntax is required to get the compiler to work properly with explicit module exports like in CSF. This would make my little wrapper for it uglier and less portable. Currently it looks like this, and I'm really enjoying using it. I think other Clojurians will too:

;; Two separate component storybooks in the same file.
(defstory "Testbox"
  ["Testbox1"
   [testbox]])

;; Component-level decorators/parameters.
(defstory "Sidebar"
  {:decorators [with-h-700 #(views/modal-left true)]
   :argTypes   {:backgroundColor {:control "color"}}}
  ["Open Sidebar"
   [sidebar/sidebar sidebar-test-props]])

I hope we can get this args/argTypes thing sorted out here!

neilyio on 28 Aug 2020

Here is a codesandbox with three storiesOf examples. https://codesandbox.io/s/nervous-violet-l7mxf?file=/src/stories/stories-of-example.stories.tsx

The following snippet is just the code from the codesandbox example, incase it stops working:

import { storiesOf } from "@storybook/react";
import React from "react";

import { Thing } from "../Thing";

/**
 * Adding Controls support to individual stories.
 *
 * "Thing1" has controls configured.
 * "Thing2" does not have controls configured.
 */
storiesOf("StoriesOf/Basic", module)
  .add("Thing1", (args) => <Thing {...args}>Example</Thing>, {
    component: Thing
  })
  .add("Thing2", (args) => <Thing {...args}>Example</Thing>);

/**
 * Adding Controls support to multiple stories at once.
 */
storiesOf("StoriesOf/WithAddParameters", module)
  .addParameters({ component: Thing })

  .add("Thing1", (args) => <Thing {...args}>Example</Thing>)
  .add("Thing2", (args) => <Thing {...args}>Example</Thing>);

/**
 * Manually configuring Controls, without the warning.
 *
 * Without `controls: { hideNoControlsWarning: true }` the warning
 * about the component not being configured for controls will be
 * visible.
 */
storiesOf("StoriesOf/NoWarning", module).add(
  "Thing1",
  ({ something, ...args }) => <Thing {...args}>{something}</Thing>,
  {
    argTypes: {
      something: "text"
    },
    controls: { hideNoControlsWarning: true }
  }
);

Marklb on 4 Sep 2020

❤2

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. Unfortunately, we don't have time to get to every issue. We are always open to contributions so please send us a pull request if you would like to help. Inactive issues will be closed after 30 days. Thanks!