[Feature Request]: Subcomponents support

[konsalex]

Is your feature request related to a problem? Please describe

Currently the roadmap involves dropping support for subcomponents, which is already done in the latest beta if i'm not mistaken, because it was a half-baked feature, but unfortunately there is no real alternative in place.

It's a frequent architecture to have subcomponents in elements like Navigations for example, that need to share the same context.

For example in our case we used this feature in many cases to document sub-components that can be used only in a specific context:

Describe the solution you'd like

Keep the subcomponents functionality, or make a convenient alternative.

As proposed from @JReinhold in the discord forum, grouping in ArgsTable could be used: https://storybook.js.org/docs/react/writing-docs/doc-block-argstable#grouping

which have the following pros and cons:

Pros	Cons
Can control the subcomponents	Really hard to set this up, as the controls need explicit definition, while the subcomponents feature was implicitly inferring the props
	Less cluttered screen

Describe alternatives you've considered

Keep the subcomponents until there is a valuable alternative, and maybe to avoid confusion, flag the subcomponent tabs, so users can understand that those tabs are not interactive rather than demonstrating the props the components can use.

Are you able to assist to bring the feature to reality?

no

Additional context

No response

[keisha-rw]

Our team would also appreciate this feature!

[JReinhold]

Thanks for the feedback, keep it coming! Let's try to keep this issue as the canonical place for subcomponents, for everyone to chime in with what their specific needs and use cases are.

There are definitely real use cases where functionality like this is valuable. Specifically compound components, where it doesn't make sense to use a single component in isolation.

Deprecation Reason

The biggest issue with the subcomponents API is that it is documentation-only, and doesn't do anything in use cases when you want to develop or test the components. This is most notable by the fact that it doesn't add anything to the Controls panel, subcomponents are uncontrollable, and they only show up in the Docs view - where they are also uncontrollable.

And the current API doesn't leave much room to add features on top of that later, which is why we've decided to deprecate them now, because we're fairly certain that whatever the evolution of the feature will be, it will be in another form.

For 7.0 we did a lot of restructuring of doc blocks and docs in general, and we decided to not move subcomponents over to the new structure in the interest of time.
That means that subcomponents are still shown in the deprecated ArgsTable block, but not in the new ArgTypes nor Controls blocks (see workarounds below).
If anyone is willing to do that work of porting over subcomponents support to ArgTypes and Controls, feel free to submit a PR.

Workaround

We have documentation for different ways to have multiple components for a story at https://storybook.js.org/docs/7.0/react/writing-stories/stories-for-multiple-components (at the time of writing it still references the subcomponents API, we're working on that).

Use ArgsTable

If you just want to keep the functionality from 6.5, you can build your own docs template, and replace the Controls block with the old ArgsTable block, which should bring back your subcomponent tabs. You can replace the template globally as described here, and it would look something like this:

// .storybook/preview.tsx

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';

import { Title, Subtitle, Description, Primary, ArgsTable, Stories } from '@storybook/blocks';

const preview: Preview = {
  parameters: {
    docs: {
      page: () => (
        <>
          <Title />
          <Subtitle />
          <Description />
          <Primary />
          <ArgsTable />
          <Stories />
        </>
      ),
    },
  },
};

export default preview;

If you're not using React, you can use an MDX template instead as described here.

Use categories

As briefly described in the original issue, and documented here, you can specify categories when writing argTypes, which means you could create a category for each subcomponent and specify the arg types in the categories. This won't give you tabs, but instead collapsible sections in the same table. The downside of this is that you have to specify each arg type manually, as you can't automatically infer arg types for other components than the main one. This is cumbersome.

The Future

We want to evolve this feature, to be more coherent with the rest of Storybook, ie. make subcomponents controllable and/or testable. We don't know how yet.

Ideally you should be able to document and control all the sub-components in the story, and maybe even dynamically control how, where, and how many subcomponents are rendered, so a user can more seamlessly try out different scenarios.

I'd love to talk through this with @cdedreuille at some point.

[wilkinsjade]

@JReinhold How long will the workaround to keep the existing 6.5 behavior be available? Are there plans to eventually deprecate the ArgsTable block

[JReinhold]

@wilkinsjade the ArgsTable block is already deprecated. For now, the plan is to keep it around until we have an alternative ready.

[Flcwl]

Nice! but have a little bit bug...

[Flcwl]

I also want to have autodocs support for Utils or React Hooks functions demos. because of I often write Utils and React Hooks In Storybook and not only for React components.

[alasdair009]

We found this feature particularly useful for our composite structure. I understand why you removed it but I feel this feature does add a lot of value for onboarding our team.

[anambl]

I'm not sure I see the problem with "the subcomponents API is that it is documentation-only". Many projects use Storybook for documentation and don't necessarily need the controls.
We have a lot of components which are exporting inner components that don't make sense on their own (e.g. an accordion and accordion item) so it makes sense to have them within one table.

Happy to hear that it's not going away until there's an alternative, as for us this feature is very useful!

[toljaEmbroker]

+1 for this, we have namespaced components with dot notation

Like this example:

<Card>
  <Card.Body>
  </Card.Body>
</Card>

[SergeyRoyt]

We in monday-ui-react-core also use subcomponents
For now using deprecated ArgsTable as a workaround and would appreciate finding a similar solution for this in the future

[oncet]

Also looking for a way to add documentation for compund components using dot notation.

How can I use the ArgsTable workaround with the *.stories.tsx file?

Tried something like this but it doesn't work:

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  subcomponents: {
    MySubComponent: MyComponent.MySubComponent,
  },
  tags: ['autodocs'],
};

It yields an error like:

Types of parameters '__0' and 'props' are incompatible.
      Type 'unknown' is not assignable to type 'SubComponentProps'

[nobleach]

I have the same question as @oncet. "Use the ArgsTable" is a bit hand-wavy as I'm having trouble finding any docs explaining how this can be used with subcomponents.

[JReinhold]

Time flies and we haven't been able to carve out a new API that would holistically solve the issues that we want, and we don't expect to be able to in the near future.

Therefore we've decided to undeprecate the subcomponents API in Storybook 8.0, bringing back the feature as it was, as a permanent solution. I'm very sorry for any confusion and added work this has caused you all. We were surprised by how many users that used and liked this feature.

This means that we'll:

• Port over subcomponents support to the ArgTypes and Controls doc blocks so you don't have to implement your own workarounds
• Remove the ArgsTable doc block completely, as this was the last blocker to remove it
• Remove any deprecation warnings about subcomponents
• Document subcomponents properly again