tmeasday/Proposal.md

## Proposal.md

      
    Raw
  

              Proposal.md
            
          
    Decorator / addon preview API proposal.

Currently the principal way addons work in the preview context (ie acting on the story) is via decorators.
Types of decorator

There are 3 types of thing that the decorators do:

Altering the story in a very real way: "modifiers"
Inspecting the story, and sending telemetry somewhere (typically to the manager context via the addon channel): "inspectors"
Adding context to the story: "wrappers" -- this includes both:

CSS/Visual things like a wrapping class or background color, setting viewport size
React context things like redux/router providers.


Ultimately all decorators are HOCs: they take as input a story component[1] and output a decorated story component.
[1] Currently stories don't take {props, context} but they behave like stateless functional components in all other ways.
Usage of decorators

There are also 3 ways of applying a decorator:

Globally (addDecorator(decorator)),
Per-chapter (storiesOf(X).addDecorator(decorator))
Per-story (storiesOf(X).add('name', decorator(() => <story/>))).

Configuration

It is possible to configure a decorator on a per-story basis via making it a function that takes options and returns a HOC:
// implementation
export default function myDecorator(params) {
  return (storyFn) => (context) => {
    // do stuff
    return storyFn(context); // (or wrap it, etc)
  }
}

// usage
addDecorator(myDecorator({ option: 'value'}));
Issues with the current system

I. It is the user's resposibility to apply decorators in the right order

You need to ensure all your "inspector" decorators apply before any "wrapper" decorators.
However, you might not realise that. This leads to bugs that are entirely avoidable (see below).
II. It is difficult/impossible to apply decorators in the right order

Also, suppose you are using the wrapper globally:
addDecorator(mockedI18nProvider);
There's no way to add a "per-chapter" inspector that applies before that wrapper:
storiesOf('X')
  .addDecorator(jsxDecorator); // <- this will apply *after* the i18n decorator
Conversely, if you want to add a wrapper decorator at the story level, it will apply before any existing inspectors etc.
III. per-story decorators "pollute" the story.

If your story looks like:
  .add('name', barInspector(() =>
     <FooWrapper>
       <Component />
     </FooWrapper>
  ));
It is pretty unclear which parts are integral to the story we are looking at and which parts are there for contextual or diagnostic purposes.
It would be good to separate them.
Proposal


We add a third optional argument to the .add() API that takes an object of per-story options.

Adding the decorators applies one or more decorators to that story:
storiesOf('X')
  .add('name', () => <story/>, { decorators: [myDecorator, foo] });
This solves problem III.

Decorators remain as HOCs, however they can optionally have a property type which indicates which sort of decorator they are:

export default function myDecorator() { ... }

myDecorator.type = 'inspector';
Decorators are applied in a special order:

All "modifier" decorators (you'll probably need to closely control the order of these, but chances are they are all added at the story level)
All "inspector" decorators.
All "wrapper" decorators.

Within each type, they are applied in the order the user specified them.
Decorators without the property are assumed to be wrappers.
This takes the onus of ordering decorators off the user and places it on the addon writer. It solves problem I and mostly solves problem II.

[OPTIONAL] We also add tools that make it really easy to create inspector decorators that post to the channel:

export default createInspectorDecorator(name, (storyElement, emit) => {
  emit(elementToJSX(storyElement));
});