Storybook: Addon-docs: Generate escape hatches automatically for blocks

[patricklafrance]

Is your feature request related to a problem? Please describe.
Currently, the escape hatches for the doc blocks are inconsistent.

Some use sbdocs sbdocs-<docBlockName> format and other use docblock-<docBlockName> format.

For example, the PropsTable use the following docblock format:

      <Table className="docblock-propstable">
        <thead className="docblock-propstable-head">
          <tr>
            <th>Name</th>
            <th>Description</th>
            <th>Default</th>
          </tr>
        </thead>
        <tbody className="docblock-propstable-body">
          {allRows.map(row => (
            <PropsTableRow key={row.key} {...row.value} />
          ))}
        </tbody>
      </Table>

But one of his sub-component use the docblock format:

      <Expandable className="sbdocs-expandable">
        <span>{summary}</span>
        <ArrowIcon icon={isOpen ? 'arrowup' : 'arrowdown'} />
      </Expandable>

This is unclear to me when to use sbdocs and when to use docblock.

After talking with @domyen we think the best approach would be to use some kind of automation to generate the escape hatch based on the component name. It could also something else like an utility function, at least it would ensure consistency.

If we go forward with this, it should be done before releasing 5.3.

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

[domyen]

Thanks @patricklafrance! Naming is hard. The responsibility for naming should be automatic based on the component name rather than having themers adhere to a naming convention – which can be pretty tough to remember as evidenced above.

@shilman what do you think?

[shilman]

I'm fine with an automatic solution based on the component name provided it's not too complicated. Here's a really simple version:

export const escapeHatch = (id: string) => (
  `sbdocs sbdocs-${kebabCase(id)}`
)

WDYT @domyen @patricklafrance

[patricklafrance]

Looks good to me, where do you plug this to make it "automatic" ?

[shilman]

Could do something like this, except for blocks?

https://github.com/storybookjs/storybook/blob/master/lib/components/src/html.tsx#L6

I was just thinking to convert all of our existing escape hatch declarations to use this helper

[patricklafrance]

I think using the helper would be easier.

As far as I know there isn't any central location where we loop through all the block components.

Also we must support MDX AND DocsPage

[shilman]

Maybe here? https://github.com/storybookjs/storybook/blob/next/addons/docs/src/blocks/index.ts#L3-L20

[patricklafrance]

Not sure it will work for "inner" components.

I do think the helper function is the simplest and best solution even if it rely on the block author to remember to use it.

[patricklafrance]

@shilman if we close this PR for 5.3 should we replace the escape hatches following the docblock format for sbdocs or wait for 6.0 ? This is a breaking change.

Easy way to solve this would be add sbdocs to those and then in 6.0 remove all docblock.

[patricklafrance]

@shilman Does it make sense to you if we had sbdocs on component that are part of @storybook/components ?

Ex: the PropsTable component

[shilman]

@patricklafrance I'm fine with having sbdocs on the doc blocks in lib/components, and the transition plan sounds good

[stale[bot]]

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!