Unable to use Canvas in doc-only MDX after upgrading to Storybook 8

[axelboc]

Describe the bug

I'm running into this issue again with Canvas after upgrading to Storybook 8.

I'm just trying to wrap a piece of JSX in a Canvas inside a documentation-only MDX file. I've tried importing Canvas and Meta from @storybook/addon-docs and from @storybook/blocks (I tried all possible import combinations) but in all cases I get the same error: "No primary story defined for docs entry. Did you forget to use <Meta>?". Same if I don't use Meta at all and let the title be inferred from the first heading.

Originally posted by @axelboc in #19964 (comment)

[AimenKhalidArbisoft]

This is because Canvas block no longer accepts children. It now refers to a single story with of prop. Try removing the Canvas wrapper altogether. I tried this and it worked. Apparently in v6, you needed the canvas wrapper to render jsx in mdx but this is no longer the case. I assume it is due to the fact that sb v8 used mdx3 instead of mdx1 now.

[axelboc]

Oh that's a shame. It works if I remove the wrapper, of course, but the point is to show the Canvas UI (i.e. mostly the ability to show the source code). I guess I could turn the code that was previously wrapped in Canvas into a story, but I really don't want it to appear in the navigation. Is there a way to "hide" a story in the sidebar? Reading through #9209, it doesn't seem straightforward...

[benfosterlitmos]

I have run into this issue as well after migrating to Storybook 8. I have some documentation-only MDX pages with examples embedded in a Canvas so that I can have isolated CSS and code examples. The examples render when I remove the Canvas, but they don't render correctly because Storybook's CSS conflicts with my component's CSS.

[nachten]

Same problem here, I would like to know if there is another alternative ?

[JReinhold]

This is because Canvas block no longer accepts children. It now refers to a single story with of prop.

Spot on @AimenKhalidArbisoft

I guess I could turn the code that was previously wrapped in Canvas into a story, but I really don't want it to appear in the navigation. Is there a way to "hide" a story in the sidebar?

@axelboc We're introducing a built-in way to do this in 8.1 using tags. See the docs on the tags-API here (alpha): https://storybook.js.org/docs/8.1/writing-stories/tags

In short, removing the 'dev' tag from a story by giving it '!dev' will hide it from the sidebar, but still be targetable with <Canvas of={...} />. This makes it possible to define any story you want, and have it shown/hidden in the sidebar/docs however you want.

... so that I can have isolated CSS and code examples. The examples render when I remove the Canvas, but they don't render correctly because Storybook's CSS conflicts with my component's CSS.

@benfosterlitmos have you looked into the <Unstyled> doc-block to disable Storybook's styles? https://storybook.js.org/docs/8.1/api/doc-block-unstyled
It doesn't remove all styles because of some inheritance limitations, but the default styles have so low specificity that they should easily be overridable with your own styles if you want to.

I'm closing this as this is intended behavior and not a bug - but keeping the discussion open if you have further questions. If you need a way to wrap arbitrary JSX in a Canvas-like element, please open an RFC explaining the use cases, and how it would be better than the current state of things. I'd propose you come at it with fresh eyes, disregard what you know from the old behavior but come at it with a "what is my current problem, how would I like it to be solved"-mentality

[flippidippi]

I have tried also looking at this with "fresh eyes", and I'm struggling to find a way to accomplish what we have done in the past. We basically have a lot of CSS helpers that we document for our users to use. So the Canvas elements are to show what the resulting code looks like, and in addition, give the user a way to see what classes where used. This is similar to bootstrap's documentation. We aren't documenting components, but the underlying CSS itself.

[JReinhold]

@flippidippi can't you make a single story that contains all the headings and reference that story with <Canvas of={HeadingStories.All} />?

And potentially hide it from the sidebar with tags as described above, if you want this to be a docs-only story.

[flippidippi]

I'm able to get kinda close but it stills extra wrappers that don't need to be there.

import { StoryObj } from '@storybook/react'
import { ReactNode } from 'react'

interface DocsCanvasProps {
  children?: ReactNode
}

function DocsCanvas ({ children }: DocsCanvasProps) {
  return <>{children}</>
}

export default {
  title: 'DocsCanvas',
  component: DocsCanvas
}

export const All: StoryObj<typeof DocsCanvas> = {
  args: {
    children: (
      <>
        <h1>Example heading <span className="badge text-bg-secondary">New</span></h1>
        <h2>Example heading <span className="badge text-bg-secondary">New</span></h2>
        <h3>Example heading <span className="badge text-bg-secondary">New</span></h3>
        <h4>Example heading <span className="badge text-bg-secondary">New</span></h4>
        <h5>Example heading <span className="badge text-bg-secondary">New</span></h5>
        <h6>Example heading <span className="badge text-bg-secondary">New</span></h6>
      </>
    )
  }
}