Vue3: Rollback v7 breaking change and keep reactive v6-compatible API

[kasperpeulen]

In v7 an unplanned/undocumented breaking change was introduced. We apply now args as props to the component returned from the render function:

export const SomeStory = {
  render: (args) => ({
    components: { TestBtn },
    setup() {
      return { args };
    },
    template: `
    <div>
      <TestBtn v-bind="args"></TestBtn>
    </div>`,
  }),
  argTypes: {
    onClick: { action: 'clicked' },
  },
  args: {
    disabled: false,
  }
};

In this example, that means that the onClick action and the disabled arg are not only applied to TestBtn, but also to the outer div. This is because of fall through attributes:
https://vuejs.org/guide/components/attrs.html#fallthrough-attributes

// simplistic Storyook vue3 implementation
createApp({
  setup() {
    // modify args in the storyContext to make them reactive
    storyContext.args = reactive(storyContext.args);
    // apply args to user provided render function
    const Component = SomeStory.render(storyContext.args);
    return () => {
      // Behavior in v7: Apply args also as props to component options returned from the story render
      return h(Component, storyContext.args);
      // Behavior in v6: Just render the Component without props, args are already provided in the closure.
      return h(Component);
    };
  }
})

This breaking change has as benefit that the user doesn't have to write v-bind="args" here:
template: '<MyComponent v-bind="args" />',
They can leave out v-bind="args", but only if the component is on the root.

The major downside of this change is if you have something else than your component on the root:
template: '<div><MyComponent v-bind="args" /></div>',
Now, the args are "magically" spread into a div, but the user didn't write the args for the div, they are written and meant for MyComponent. We are getting feedback from multiple Storybook users that people don't expect this, causing unexpected issues.

I think the reason that people don't expect this isn't because they don't understand Vue. It's more that they don't expect the template that they give to Storybook to be invoked as a component with their args as props. The user cannot see how SB will invoke the component, and args are already available in the closure. It is not intuitive that args are also available via a second route.

This is different from all our other renderers (or at least the ones I know):
React: render: (args) => <Component {...args} />
Svelte: render: (args) => { Component, props: args }
Html: render: (args) => createButton(args)
Lit: render: (args) => <lit-element label=${args.label}></lit-element>
Args are just available in the closure and the element returned from render is not invoked a second time.

Also, our TS types and the add-on controls will match the shape of the component, not the root tag of the template. So even our tools don't expect this, and you will get warnings from TS if you would write an arg that is not compatible with the component (even if it would be compatible with the root tag/component).

That being said, @chakAs3 is going to write up a RFC for doing this breaking change behind a feature flag in V7 and if this gains popularity, we can enable this feature by default for v8!

[chakAs3]

I think the reason that people don't expect this isn't because they don't understand Vue. It's more that they don't expect the template that they give to Storybook to be invoked as a component with their args as props. The user cannot see how SB will invoke the component

i completely agree with you, and moreover they don't understand how Storybook works. we need to work on this to make it clear for newbie and experts. better documentation and code examples.

[kasperpeulen]

@chakAs3 I think I can remove the whole slotsMap. All the reactive test passes without it.
My gut feeling is that line 25, fixes this.
Without it, the slots are basically static, and need to updated forcefully.
But now we fix the render function to be lazy, we don't need this code anymore.

[chakAs3]

We are getting feedback from multiple Storybook users that people don't expect this, causing unexpected issues.

Hi Kasper I'm quite available most time on Discord answering, and github answering users issues,i'm not getting any feedback apart from the one that you forwarded to me and even these guys are not coming back to us although all this their unique use case, if there is any other channel that you use to receive feedback please share with me, i can't tackle vue issues.

[chakAs3]

This is different from all our other renderers (or at least the ones I know):
React: render: (args) => <Component {...args} />
Svelte: render: (args) => { Component, props: args }
Html: render: (args) => createButton(args)
Lit: render: (args) => <lit-element label=${args.label}></lit-element>
Args are just available in the closure and the element returned from render is not invoked a second time.

Here to be honest i don't see any difference in Storybook api, render function return a Renderer Component.
the difference that you don't seem to accept is that Vue , React, Svelte, ... are by definition different, everyone has its api and rendering mecanism.
what i see here is the opposite, you are traiting Vue renderer with kind of discrimination by saying i don't like your fallthough attribute feature.

Args are just available in the closure and the element returned from render is not invoked a second time.

??? again i don't know how you saw it invoked a second time ?

 const vueApp = createApp({
    setup() {
      storyContext.args = reactive(storyContext.args);
      const rootElement = storyFn(); // call the story function to get the root element with all the decorators
      const args = getArgs(rootElement, storyContext); // get args in case they are altered by decorators otherwise use the args from the context
      const appState = {
        vueApp,
        reactiveArgs: reactive(args),
      };
      map.set(canvasElement, appState);

      return () => {
        return h(rootElement, appState.reactiveArgs);
      };
    },
  });

[chakAs3]

Also, our TS types and the add-on controls will match the shape of the component, not the root tag of the template. So even our tools don't expect this, and you will get warnings from TS if you would write an arg that is not compatible with the component (even if it would be compatible with the root tag/component).

is this a confident statement? i feel like i don't know Storybook really this is not anymore about Vue, but about How Storybook real works . @shilman @yannbf @tmeasday . Please correct me if i'm wrong.

Component Story in its default mission, is to document different state of a specific Component. so basic and simple format is

const meta = {
 
  component: Button,

} satisfies Meta<typeof Button;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

It's important to note that this is just the basic format of a Component Story, the custom one does not necessarily require the args to match the component's props. As @kasperpeulen stated, the default purpose of a Component Story is to document different states of a component. Therefore, it's possible to use the args to specify any relevant information for the particular story being documented, even if it doesn't directly relate to the component's props.

For example, you can define a CustomStory that doesn't need the Button component and uses custom arguments instead. The following code shows an example of such a CustomStory:

export const CustomStory: Story = {
  args: { 
    customStoryArg: 'customStoryArg',
  },
  render: (args: any) = ({
    setup() {
      return { args };
    },
    template: '<div I don\'t need the Button in this Story. Hello, some custom args: {{ args.customStoryArg }} </div',
  }),
};

In this example, the CustomStory defines a custom customStoryArg argument that is used in the template. The render function uses the setup() function to return the args object, which is then passed to the template as a property. This way, the CustomStory is documenting a custom use case that doesn't require the Button component.

You can still document your component while also creating custom stories by customizing the render, which allows for greater flexibility and creativity. However, as Kasper points out, there may be downsides to this approach if something other than the component is on the root of the template, such as in the case of <div><MyComponent v-bind="args" /</div>. Despite these potential downsides (only for people don't understand Vue/Storybook ), customization of the render remains an effective tool empower fast UI development .

Regardless of the template you use to create your custom rendering component - whether it's
<div><MyComponent v-bind="args" /</div>, <div></div><MyComponent v-bind="args" /> or <div></div>
or something else entirely - it's important to have a good understanding of the Vue renderer and how it works. Storybook is delegating rendering to the specific Renderer, so the reliability shifts to Vue renderer, it's important to rely on the Vue renderer for reliability and not on Storybook API. Any interference by Storybook API with the behavior of the Vue renderer could be risky and should be avoided. Finally, it's crucial to keep in mind that the end user developing their UI library (Vue/Svelte/Preact/React/Angular) needs full access to the features provided by their Renderer Framework to effectively test and develop their library.

[chakAs3]

In general, I disagree with the approach of completely wiping out a unit test suite and reverting back to an old implementation (last major version) when we receive a specific issue from a user who might not have a good understanding of how Vue and Storybook work. Instead, I prefer trying to fix the user's issue within the current implementation and teach them how Storybook and Vue really work. This presents a good opportunity to showcase what Storybook can do with Vue and can also attract new developers. Reverting back to a poor implementation is a significant regression that doesn't benefit anyone.

So as storybook@vue maintainer i can't approve this PR, anyone from the team @yannbf @shilman can do that if he feels confident.

[shilman]

@kasperpeulen

Thanks so much for this. We didn't realize the new API had been introduced in v7. @chakAs3 and I will write an RFC for why it's important and more Vue-like to automatically pass args as props to stories, and we will seriously consider updating the story API to make it more idiomatic for Vue users.

@chakAs3

If you consider the new API as a feature, removing it is a breaking change and should only happen in a major release with proper deprecation, etc.

However, the new API was not documented until Kasper wrote tests for it, and is still not documented--our official docs for Vue3 all recommend using the setup function (the v6 API). So it's more like an accidental change that snuck in. Removing it is still breaking for anybody who uses it, and it sucks. But it sucks less than committing ourselves to an API that we are not yet comfortable with.

I appreciate your passion around the alternative, your patience to discuss this via an RFC, and of course all of the hard work you're doing to make Storybook the best way to develop, document, and test Vue components in isolation.

[chakAs3]

@shilman @kasperpeulen I got your point maybe we did not do things properly, I just wanna mention this may not have a lot to do with this specific issue but it is a really good opportunity to be more explicit, and document our API before any release, I guess even with Old v6 Vue developers were confused as they don't find much content for vue, it was more about react, we will put more effort, @kasperpeulen, @jonniebigodes, @kylegach, @integrayshaun and myself I will provide necessary info and examples.

[chakAs3]

our official docs for Vue3 all recommend using the setup function (the v6 API)

Here is the problem I saw that, and the guy who proposed the implementation was giving this as a solution, he said clearly in His PR I'm not sure if the Vue community will agree with that, unfortunately, that was no one to veille on Vue implementation, and no one has commented this so you went ahead and merged this, and here we had the real breaking change happened for me.
his solution was very clever but was limited. in the first place, it was just to migrate from Vue2 to Vue3 format.

My RFC will not be the PR for fallthrough attributes but more exposing and normalizing Storybook API.

[MineDrum]

Just to chime in. I'm very glad to see this getting rolled back for now. All of a sudden when I upgraded to v7 my tests were failing because when I applied a 'placeholder' prop to my components and tried to get the element by placeholder text in my test, storybook was finding two elements instead of one. This is because I originally had a decorator div where I would apply spacing and dark tailwind styling. The placeholder prop was being applied to the div and to the component which made no sense and forced me to remove any decorators that I had.

@chakAs3

[SimmeNilsson]

Also glad to see it rolled back.
For me it was causing issues when wanting to use things like v-model="myRef" and then suddenly :myRef="myRef" was added "for free".
#22156

@chakAs3