showRoots Setting Does Not Work as Expected

[driponfleek]

Describe the bug
When utilizing showRoots, not getting the expected result in Storybook navigation when using default export and named export or name param on a story.

To Reproduce
Steps to reproduce the behavior:

1. Set showRoots to true
2. Create a story similar to what is under Code snippets.
3. See error

Expected behavior
Expected: Root-level Components title, My Button nav item
Result: Collapsible Components item, My Button sub-nav item

See Screenshots for expected result vs actual result.

Screenshots
Expected:

Actual:

With Unwanted Collapsible Nav Item:

Code snippets

export default {
    title: 'Components'
};

export const Button = () => <Button {...} />;

Button.story = {
    name: 'My Button',
};

Additional context
The only way I'm able to get showRoots to work is if I add an additional 3rd collapsible item in the title of the default export. For example, I'd have to do:

export default {
    title: 'Components/Buttons'
};

export const Button = () => <Button {...} />;

Button.story = {
    name: 'My Button',
};

This creates an unwanted collapsible item Buttons in the navigation (See 3rd screenshot attached). Reading the documentation, showRoots seems to be the setting we would use to enforce the default export title would always appear as expected, but it doesn't seem to work as expected. Thanks for all the awesome work you all do on this project!

[shilman]

@tmeasday can you help out here?

[tmeasday]

Hi @danielyearwood, apologies if this is a bit confusing, I'm not quite sure how we could document this better.

You cannot have a story directly beneath a root. You've got to have at least one level of "grouping" beneath the root. This is what is leading to the behaviour you are seeing -- when the title of the component is "Button", Storybook will put it in the "Others" root (so implicitly it becomes "Others/Button").

Recently we changed it so that if you only have the "Others" root it is pulled to the top and not displayed (#8784), which ends up looking like it isn't there at all. You'd see it if you had a second story that did have a legitimate root.

Anyway, like I said, confusing. I'm not quite sure of the best way forward to make it clearer. Any ideas?

[driponfleek]

Well, I think basically from what I can understand is there really isn't any point to having showRoots? Even if we set it, storybook will not implement it unless the formatting of the title is at least a top level - grouping - story? I couldn't find anything that stated it was a requirement, and the docs seem to be a bit lacking on it so I was hesitant to reach out because I know you guys are rocking out improvements and doing really awesome stuff with this.

Personally, this makes the feature completely unusable for me due to the lack of flexibility it needs to provide to allow me to structure my navigation as I'd like. For example, I'm being forced to create a grouping with no meaning or purpose other than to meet the technical requirement which actually hurts the experience for the end user consuming it. But if it's a requirement there's little I can do about it lol. Ideally, I'd be able to mix and match this kind of thing, but I do understand the complexity of making this work is not an easy thing.

If what I'm assuming about showRoots being an unneeded setting if you have no choice but to use a specific format to make it work, then maybe it would be better to remove it all together? Or is it also that when setting this if you have a 3 layer grouping then that is when it shows this structure, otherwise it shows some other type of structure? If that's the case, then I would probably rethink the name of this to have a more accurate meaning. On the surface showRoots gives an expectation of always working when set to true regardless of how far down the rabbit hole your groupings go. Perhaps showRootsForDeeplyNestedStories (I know it's long and not exactly what you'd want to use, but you can see how something like this more accurately explains the expectation of what it does)?

[driponfleek]

@tmeasday Just to kind of clarify why I am saying it is unusable for my purposes is because I'm trying to use Storybook to create a design system.

I'm trying to break out the structure of that left nav into something like this:

• Welcome
  • Intro
• Branding
  • Colors
  • Typography
• Components
  • Buttons
    • Menu Button
    • Split Button
• Designers
  • Something here
• Developers
  • Something here

You can see how this would be beneficial from an end user perspective to be able to create a navigation that allows them to find what they are looking for easily. I saw the potential of the showRoots functionality for creating something like this, but as you can see with what I have there's only one place where I would need the additional grouping and that would be in the components hierarchy.

Hope this helps to explain why I was looking for it to work this way.

[shilman]

@danielyearwood can’t you just set showRoots to false if you don’t want any roots? I think your desired hierarchy should be easy to create that way.

[driponfleek]

@shilman I do want the visual treatment that comes with it. Without it, how would I achieve the bold top-level treatment for each section of the navigation and also the spacing between each section? That visual hierarchy helps to improve the readability and usability of the navigation, so I'm looking to preserve that. From what I've been able to tell, if I don't do that, then everything is lumped together in a long list which makes it harder for an end user to tell that these are sections of grouped content. Instead it appears as if everything is related to each other. It's hard to convey with bullet points. Here's a better example of what I'm looking to achieve:

[shilman]

@danielyearwood have you looked at docs-only MDX? I think most if not all of those contents (like “intro”) are best achieved in MDX. And it would have exactly the navigation structure you’re looking for.

[driponfleek]

@shilman I started down the road of MDX and that's where I noticed I could achieve that navigation structure, but at this point I think it hasn't matured enough to be usable for what I'm trying to build. There are too many things missing or too many bugs and I feel that MDX is not at the point where it is ready for adoption yet. I need to control layout and style the content of a page, do more creative things than markdown currently allows, and Markdown with JSX doesn't really give the full control like I would like from what I'm able to tell. Also linting and controlling things like indentation etc of MDX files is not available to my knowledge. Overall, I'm trying to put in the right governance and a standard and MDX is too loose for me to do that with and still has some growing to do capability-wise before I could consider it.

[shilman]

Why not just drop your own custom components in MDX then? That’s what you’d be doing anyways in stories, right? The only difference is that storybook supports the docs-only MDX thing out of the box, but it doesn’t support standalone stories the way you want.

Just so we’re clear it would look something like:

<Meta title=‘Welcome/intro’ />

<YourIntroComponentWithYourFormatting />

Of course you could also use markdown etc. but it sounds like you’ve already considered that and decided against it. A story in storybook is meant to be an isolated component example. I think what you want to do is going against the grain and if you’re trying to put a solid system in place, I’d consider that before trying to cram random content into stories. People did that in the past, and I’m sure still do. But storybook won’t go out of its way to support that unless there’s a very good reason to. We have an official documentation system now—let’s figure out what we need to do to make it support people’s use cases :)

[driponfleek]

@shilman Yeah I considered doing that, but then I have no way to prevent others contributing to it from using MDX. I would love to believe in people following the rules, but I also feel that's why we have things like linting, best practices, prettier etc. So If I did take the MDX approach, then I would be opening the flood gates to allow worse case scenario to happen. The only way to prevent it is to architect it so it can't be used until it grows in maturity.

At the end of the day I'm not trying to change the direction you guys are trying to take storybook. Maybe I just had a misunderstanding that it was not just a documentation system. I thought we could use it to bridge the gap between UX, Design and Dev (in one place), so that's what I was hoping to achieve with it. It felt like that was what Storybook was trying to do in the beginning so it is definitely a different approach from what I remember, but that could be just me.

Also, not sure if you are familiar with this, but this is another reason why I was trying to utilize Storybook for this: https://www.learnstorybook.com/design-systems-for-developers/.

Anyways, thanks for the clarification. I'll try to figure something out. I really do like what you guys have done and will be rooting for you either way.

[shilman]

@danielyearwood thanks for the clarification. To help me understand how we might modify storybook’s documentation system to better accommodate your use case, what does your intro story look like?

Storybook is not just a documentation system. It contains a rich collection of integrations with design tools, testing tools, etc etc and this will only grow stronger in the future. But documentation is one of our pillars and from what i can tell from your previous comments “Welcome/Intro” is squarely documentation.

[driponfleek]

@shilman I have to blur most of it out and it's still a work in progress, but I'll see if it helps. I actually have bigger plans for this page than what is shown here, but this is currently where I'm at with it.

In regard to your "Welcome/Intro" is squarely documentation comment, I would like to disagree here. While it will indeed have text, it could be media rich with animations and video etc. It may require layout using either grid or flex system. It can have some level of interaction or gamification as well. I could decide to do parallax or something more trendy. It's really going to be up to the person/people designing and building it.

While it is awesome that MD and JSX can co-exist, and I think can definitely see that somewhere there is a use case other than mine, it creates a whole list of problems. For example, how am I supposed to get MDX to match the branding/style that my design system should be utilizing? And when I pull a React component into my MDX document, how does it adapt styles that MDX is dictating? How do I retain the benefits of MDX formatting things the same way in my react component? How do I control the layout of my page content and make it responsive? There's a huge disconnect between the two that is not easily solved.

I also want to stress how much I do appreciate what you all are building here. I've been a big fan for a long time. This is my first run with the new version of storybook (my last run was where you only had the storiesOf approach). It just turns out that this time around I'll have to either get creative or find an alternative. I hope that nobody takes it personally and that this is helpful. If expressing my findings with what I see as limitations with MDX and Storybook as a whole helps, I'm glad to do so (even if I'm not using it as intended 😄)

[shilman]

No offense taken whatsoever. I’m digging in with you because I want to cover as many use cases as we can with as compact a surface area as we can manage.

I know how to give you exactly what you want with a minimal change, but it expands the surface are slightly in a way that I’m not necessarily comfortable with.

So is that page you shared a react component?

[driponfleek]

@shilman Thanks! Yeah it is a react component. I've actually created a lot of components to compose stories in storybook so that they can have a uniform feel, take care of laying out content, adapt branding that will be shown in this system, document theming for both dev's and designers, etc. etc. The pages with the components are much more in-depth than the welcome page is currently. I kind of just stubbed that out with a TODO on it to revisit later and make it fancier.

Here's an example of a component for reference (Also still a work in progress)

[tmeasday]

@shilman if @danielyearwood doesn't want to use MDX, can't he similarly create a docs-only story in vanilla CSF and get all the same functionality? That sounds like what he is trying to achieve here? Isn't MDX just a layer over CSF to give folks (that want it, which @danielyearwood doesn't by the sound of it) the ability to write in markdown?

Not to derail that, but I just wanted to add regarding this comment:

Without it, how would I achieve the bold top-level treatment for each section of the navigation and also the spacing between each section?

I think the way the explorer/tree-view was designed it is not intended for stories to be "top-level" elements in the tree (the roots are sort of outside the tree, if you see what I mean). I think that's ultimately what drives the current (confusing) behaviour. We should probably try and figure out in a more intuitive way for 6.0, thanks for bringing this up.

But I think you can maybe get the behaviour you want with a docs only story, which leads us back to the conversation above..

[shilman]

@tmeasday Yeah that's where I was going with that conversation above. The CSF implementation of docs-only stories is currently an undocumented feature, since it's not well thought out. Given @danielyearwood 's use cases, I'm thinking about documenting it and making it an official feature. Question then is do we want to redesign (or at least rename) the API as part of 6.0?

[gsklee]

Would be nice if anyone could post a one-stop comment detailing how to set up the stories structure so that we can get that gray section heading @danielyearwood originally posted. I am not really interested in how the showRoots option works exactly, just wanna get the visual effect. Scrolled through the whole discussion thread and couldn't seem to find that.

[stale]

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!

[stale]

Hey there, it's me again! I am going close this issue to help our maintainers focus on the current development roadmap instead. If the issue mentioned is still a concern, please open a new ticket and mention this old one. Cheers and thanks for using Storybook!

[ghengeveld]

Would be nice if anyone could post a one-stop comment detailing how to set up the stories structure so that we can get that gray section heading @danielyearwood originally posted. I am not really interested in how the showRoots option works exactly, just wanna get the visual effect. Scrolled through the whole discussion thread and couldn't seem to find that.

Currently, the way to get those gray section headings to appear is as follows:

• Make sure showRoots is not disabled. It's enabled by default so if you don't have this configured you're good to go.
• Make sure you're using only slashes / as path separators. Everything else is unsupported in Storybook 6.0.
• Make sure your stories are at least 3 doors down, path-wise. That means the title in your default export should be something like Components/Button and the stories live beneath that, becoming the 3rd part of the path. The reason is that the last part of the title is considered to be the component name, and components will never be displayed as a root. Instead they end up at the top of the tree without any section heading.

export default {
  title: "Components/Button"
};

export const Primary = () => <Button appearance="primary">Label</Button>;

Now, remember this is all how it currently works in Storybook 6.0. Future improvements might change this behavior to support @danielyearwood's use case. Maybe.

[tmeasday]

It is also documented here: https://storybook.js.org/docs/react/writing-stories/naming-components-and-hierarchy#roots