Skip to content

Commit

Permalink
Merge branch 'next' into shilman/20145-legacy-mdx1
Browse files Browse the repository at this point in the history
  • Loading branch information
@shilman
shilman committed Jan 25, 2023
2 parents c251281 + cf3ab50 commit 7a495e0
Show file tree
Hide file tree
Showing 220 changed files with 3,709 additions and 2,291 deletions.
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ executors:
default: 'small'
working_directory: /tmp/storybook
docker:
- image: mcr.microsoft.com/playwright:v1.29.1-focal
- image: mcr.microsoft.com/playwright:v1.30.0-focal
environment:
NODE_OPTIONS: --max_old_space_size=6144
resource_class: <<parameters.class>>
Expand Down
47 changes: 47 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,50 @@
## 7.0.0-beta.33 (January 24, 2023)

#### Features

- Addon-docs: Allow `<Story/>` to reference the first story [#20765](https://github.com/storybooks/storybook/pull/20765)

#### Bug Fixes

- Angular: Fix issue if BrowserAnimationsModule is imported [#20709](https://github.com/storybooks/storybook/pull/20709)
- Core: Fix issue with inconsistent CSF ordering in sandboxes [#20705](https://github.com/storybooks/storybook/pull/20705)
- Fixed paths in generated main.cjs for the default sandbox on Windows [#20724](https://github.com/storybooks/storybook/pull/20724)
- Blocks: Ignore known blocks with global CSS selector [#20757](https://github.com/storybooks/storybook/pull/20757)

#### Maintenance

- Docs: Make reference stories consistent [#20759](https://github.com/storybooks/storybook/pull/20759)
- Blocks: New Canvas API [#20723](https://github.com/storybooks/storybook/pull/20723)

#### Build

- Fix vue sandbox: remove the lang=ts in a file, that should remain agnostic [#20768](https://github.com/storybooks/storybook/pull/20768)
- Build: do not treat check as a cache-able operation && cleanup [#20762](https://github.com/storybooks/storybook/pull/20762)

## 7.0.0-beta.32 (January 24, 2023)

#### Features

- CLI: Add init support for qwik projects [#20411](https://github.com/storybooks/storybook/pull/20411)

#### Bug Fixes

- Vue3: Fix reactive args + many vue app creation issue [#20712](https://github.com/storybooks/storybook/pull/20712)
- Docs: Allow "declaring" stories with `story={}` [#20702](https://github.com/storybooks/storybook/pull/20702)
- Addon-links: Fix the d.ts file, deprecate LinkTo [#20671](https://github.com/storybooks/storybook/pull/20671)
- CLI: Fix package execution for npm package manager [#20708](https://github.com/storybooks/storybook/pull/20708)

#### Maintenance

- Upgrade react-popper-tooltip [#20736](https://github.com/storybooks/storybook/pull/20736)
- CLI: Upgrade automigrations to use new safe helpers [#20693](https://github.com/storybooks/storybook/pull/20693)
- Csf-tools: Add helpers to get name from node path [#20691](https://github.com/storybooks/storybook/pull/20691)
- Build: remove preact-webpack5 from babelrc automigration [#20706](https://github.com/storybooks/storybook/pull/20706)

#### Build

- Fix windows snapshot [#20707](https://github.com/storybooks/storybook/pull/20707)

## 7.0.0-beta.31 (January 20, 2023)

#### Features
Expand Down
206 changes: 141 additions & 65 deletions MIGRATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,17 @@
- [Icons API changed](#icons-api-changed)
- [Removed global client APIs](#removed-global-client-apis)
- [Docs Changes](#docs-changes)
- [Standalone docs files](#standalone-docs-files)
- [Referencing stories in docs files](#referencing-stories-in-docs-files)
- [Description block, `parameters.notes` and `parameters.info`](#description-block-parametersnotes-and-parametersinfo)
- [Autodocs](#autodocs)
- [Configuring the Docs Container](#configuring-the-docs-container)
- [External Docs](#external-docs)
- [Autodocs changes](#autodocs-changes)
- [MDX docs files](#mdx-docs-files)
- [Unattached docs files](#unattached-docs-files)
- [Doc Blocks](#doc-blocks)
- [Meta block](#meta-block)
- [Description block, `parameters.notes` and `parameters.info`](#description-block-parametersnotes-and-parametersinfo)
- [Story block](#story-block)
- [Source block](#source-block)
- [Canvas block](#canvas-block)
- [ArgsTable block](#argstable-block)
- [Configuring Autodocs](#configuring-autodocs)
- [MDX2 upgrade](#mdx2-upgrade)
- [Legacy MDX1 support](#legacy-mdx1-support)
- [Default docs styles will leak into non-story user components](#default-docs-styles-will-leak-into-non-story-user-components)
Expand Down Expand Up @@ -744,36 +749,100 @@ Instead, use `export const parameters = {};` and `export const decorators = [];`

### Docs Changes

The information hierarchy of docs in Storybook has changed in 7.0. The main difference is that each docs is listed in the sidebar as a separate entry, rather than attached to individual stories.
The information hierarchy of docs in Storybook has changed in 7.0. The main difference is that each docs is listed in the sidebar as a separate entry underneath the component, rather than attached to individual stories. You can also opt-in to a Autodocs entry rather than having one for every component (previously stories).

These changes are encapsulated in the following:
We've also modernized the API for all the doc blocks (the MDX components you use to write custom docs pages), which we'll describe below.

#### Standalone docs files
#### Autodocs changes

In Storybook 6.x, to create a standalone docs MDX file, you'd have to create a `.stories.mdx` file, and describe its location with the `Meta` doc block:
In 7.0, rather than rendering each story in "docs view mode", Autodocs (formerly known as "Docs Page") operates by adding additional sidebar entries for each component. By default it uses the same template as was used in 6.x, and the entries are entitled `Docs`.

```mdx
import { Meta } from '@storybook/addon-docs';
You can configure Autodocs in `main.js`:

<Meta title="Introduction" />
```js
module.exports = {
docs: {
autodocs: true, // see below for alternatives
defaultName: 'Docs', // set to change the name of generated docs entries
},
};
```

In 7.0, things are a little simpler -- you should call the file `.mdx` (drop the `.stories`). This will mean behind the scenes there is no story attached to this entry. You may also drop the `title` and use autotitle (and leave the `Meta` component out entirely).
If you are migrating from 6.x your `docs.autodocs` option will have been set to `true`, which has the effect of enabling docs page for _every_ CSF file. However, as of 7.0, the new default is `'tag'`, which requires opting into Autodocs per-CSF file, with the `autodocs` **tag** on your component export:

```ts
export default {
component: MyComponent
// Tags are a new feature coming in 7.1, that we are using to drive this behaviour.
tags: ['autodocs']
}
```

You can also set `autodocs: false` to opt-out of Autodocs entirely. Further configuration of Autodocs is described below.

**Parameter changes**

Additionally, you can attach a standalone docs entry to a component, using the new `of={}` syntax on the `Meta` component:
We've renamed many of the parameters that control docs rendering for consistency with the blocks (see below). The old parameters are now deprecated and will be removed in 8.0. Here is a full list of changes:

- `docs.inlineStories` has been renamed `docs.story.inline`
- `docs.iframeHeight` has been renamed `docs.story.iframeHeight`
- `notes` and `info` are no longer supported, instead use `docs.description.story | component`

#### MDX docs files

Previously `.stories.mdx` files were used to both define and document stories. In 7.0, we have deprecated defining stories in MDX files, and consequently have changed the suffix to simply `.mdx`. Our default `stories` glob in `main.js` will now match such files -- if you want to write MDX files that do not appear in Storybook, you may need to adjust the glob accordingly.

If you were using `.stories.mdx` files to write stories, we encourage you to move the stories to a CSF file, and _attach_ an `.mdx` file to that CSF file to document them. You can use the `Meta` block to attach a MDX file to a CSF file, and the `Story` block to render the stories:

```mdx
import { Meta } from '@storybook/blocks';
import { Meta, Story } from '@storybook/blocks';
import * as ComponentStories from './some-component.stories';

<Meta of={ComponentStories} />

<Story of={ComponentStories.Primary} />
```

You can create as many docs entries as you like for a given component. Note that if you attach a docs entry to a component it will replace the automatically generated entry from `DocsPage` (See below).
You can create as many docs entries as you like for a given component. Note that if you attach a docs entry to a component it will replace the automatically generated entry from Autodocs.

By default docs entries are listed first for the component. You can sort them using story sorting.

#### Referencing stories in docs files
#### Unattached docs files

In Storybook 6.x, to create a unattached docs MDX file (that is, one not attached to story or a CSF file), you'd have to create a `.stories.mdx` file, and describe its location with the `Meta` doc block:

```mdx
import { Meta } from '@storybook/addon-docs';

<Meta title="Introduction" />
```

In 7.0, things are a little simpler -- you should call the file `.mdx` (drop the `.stories`). This will mean behind the scenes there is no story attached to this entry. You may also drop the `title` and use autotitle (and leave the `Meta` component out entirely, potentially).

#### Doc Blocks

Additionally to changing the docs information architecture, we've updated the API of the doc blocks themselves to be more consistent and future proof.

**General changes**

- Each block now uses `of={}` as a primary API -- where the argument to the `of` prop is a CSF or story _export_.

- When you've attached to a CSF file (with the `Meta` block, or in Autodocs), you can drop the `of` and the block will reference the first story or the CSF file as a whole.

- Most other props controlling rendering of blocks now correspond precisely to the parameters for that block [defined for autodocs above](#autodocs-changes).

##### Meta block

The primary change of the `Meta` block is the ability to attach to CSF files with `<Meta of={}>` as described above.

##### Description block, `parameters.notes` and `parameters.info`

In 6.5 the Description doc block accepted a range of different props, `markdown`, `type` and `children` as a way to customize the content.
The props have been simplified and the block now only accepts an `of` prop, which can be a reference to either a CSF file, a default export (meta) or a story export, depending on which description you want to be shown. See TDB DOCS LINK for a deeper explanation of the new prop.

`parameters.notes` and `parameters.info` have been deprecated as a way to specify descriptions. Instead use JSDoc comments above the default export or story export, or use `parameters.docs.description.story | component` directly. See TDB DOCS LINK for a deeper explanation on how to write descriptions.

##### Story block

To reference a story in a MDX file, you should reference it with `of`:

Expand All @@ -798,43 +867,70 @@ import * as SecondComponentStories from './second-component.stories';
<Story of={SecondComponentStories.standard} meta={SecondComponentStories} />
```

#### Description block, `parameters.notes` and `parameters.info`
Referencing stories by `id="xyz--abc"` is deprecated and should be replaced with `of={}` as above.

In 6.5 the Description doc block accepted a range of different props, `markdown`, `type` and `children` as a way to customize the content.
The props have been simplified and the block now only accepts an `of` prop, which can be a reference to either a CSF file, a default export (meta) or a story export, depending on which description you want to be shown. See TDB DOCS LINK for a deeper explanation of the new prop.
##### Source block

`parameters.notes` and `parameters.info` have been deprecated as a way to specify descriptions. Instead use JSDoc comments above the default export or story export, or use `parameters.docs.description.story | component` directly. See TDB DOCS LINK for a deeper explanation on how to write descriptions.
The source block now references a single story, the component, or a CSF file itself via the `of={}` parameter.

#### Autodocs
Referencing stories by `id="xyz--abc"` is deprecated and should be replaced with `of={}` as above. Referencing multiple stories via `ids={["xyz--abc"]}` is now deprecated and should be avoided (instead use two source blocks).

In 7.0, rather than rendering each story in "docs view mode", Autodocs (formerly known as "Docs Page") operates by adding additional sidebar entries for each component. By default it uses the same template as was used in 6.x, and the entries are entitled `Docs`.
#### Canvas block

You can configure Autodocs in `main.js`:
The Canvas block follows the same changes as [the Story block described above](#story-block).

```js
module.exports = {
docs: {
autodocs: true, // see below for alternatives
defaultName: 'Docs', // set to change the name of generated docs entries
},
};
```
Previously the Canvas block accepted children (Story blocks) as a way to reference stories. That has now been replaced with the `of={}` prop that accepts a reference to _a story_.
That also means the Canvas block no longer supports containing multiple stories or elements, and thus the props related to that - `isColumn` and `columns` - have also been deprecated.

If you are migrating from 6.x your `docs.autodocs` option will have been set to `true`, which has the effect of enabling docs page for _every_ CSF file. However, as of 7.0, the new default is `'tag'`, which requires opting into Autodocs per-CSF file, with the `autodocs` **tag** on your component export:
- To pass props to the inner Story block use the `story={{ }}` prop
- Similarly, to pass props to the inner Source block use the `source={{ }}` prop.
- The `mdxSource` prop has been deprecated in favor of using `source={{ code: '...' }}`
- The `withSource` prop has been renamed to `sourceState`

```ts
export default {
component: MyComponent
// Tags are a new feature coming in 7.1, that we are using to drive this behaviour.
tags: ['autodocs']
}
Here's a full example of the new API:

```mdx
import { Meta, Canvas } from '@storybook/blocks';
import * as ComponentStories from './some-component.stories';

<Meta of={ComponentStories} />

<Canvas
of={ComponentStories.standard}
story={{
inline: false,
height: '200px'
}}
source={{
language: 'html',
code: 'custom code...'
}}
withToolbar={true}
additionalActions={[...]}
layout="fullscreen"
className="custom-class"
/>
```

You can also set `autodocs: false` to opt-out of Autodocs entirely.
##### ArgsTable block

The `ArgsTable` block is now deprecated, and two new blocks: `ArgsTypes` and `Controls` should be preferred.

- `<ArgTypes of={storyExports OR metaExports OR component} />` will render a readonly table of args/props descriptions for a story, CSF file or component. If `of` ommitted and the MDX file is attached it will render the arg types defined at the CSF file level.

You can change the default template in the same way as in 6.x, using the `docs.page` parameter.
- `<Controls of={storyExports} />` will render the controls for a story (or the primary story if `of` is omitted and the MDX file is attached).

#### Configuring the Docs Container
The following props are not supported in the new blocks:

- `components` - to render more than one component in a single table
- `showComponent` to show the component's props as well as the story's args
- the `subcomponents` annotation to show more components on the table.
- `of="^"` to reference the meta (just omit `of` in that case, for `ArgTypes`).
- `story="^"` to reference the primary story (just omit `of` in that case, for `Controls`).
- `story="."` to reference the current story (this no longer makes sense in Docs 2).
- `story="name"` to reference a story (use `of={}`).

#### Configuring Autodocs

As in 6.x, you can override the docs container to configure docs further. This is the container that each docs entry is rendered inside:

Expand All @@ -848,6 +944,8 @@ export const parameters = {
}
```

Note that the container must be implemented as a _React component_.

You likely want to use the `DocsContainer` component exported by `@storybook/blocks` and consider the following examples:

**Overriding theme**:
Expand Down Expand Up @@ -877,28 +975,6 @@ export const MyDocsContainer = (props) => (

**_NOTE_**: due to breaking changes in MDX2, such override will _only_ apply to elements you create via the MDX syntax, not pure HTML -- ie. `## content` not `<h2>content</h2>`.

#### External Docs

Storybook 7.0 can be used in the above way in externally created projects (i.e. custom docs sites). Your `.mdx` files defined as above should be portable to other contexts. You simply need to render them in an `ExternalDocs` component:

```js
// In your project somewhere:
import { ExternalDocs } from '@storybook/blocks';

// Import all the preview entries from addons that need to operate in your external docs,
// at a minimum likely your project's and your renderer's.
import * as reactAnnotations from '@storybook/react/preview';
import * as previewAnnotations from '../.storybook/preview';

export default function App({ Component, pageProps }) {
return (
<ExternalDocs projectAnnotationsList={[reactAnnotations, previewAnnotations]}>
<Component {...pageProps} />
</ExternalDocs>
);
}
```

#### MDX2 upgrade

Storybook 7 Docs uses MDXv2 instead of MDXv1. This means an improved syntax, support for inline JS expression, and improved performance among [other benefits](https://mdxjs.com/blog/v2/).
Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ For additional help, join us in the [Storybook Discord](https://discord.gg/story
| [Svelte](code/renderers/svelte) | [![Storybook demo](https://img.shields.io/npm/v/@storybook/svelte/latest?style=flat-square&color=blue&label)](https://storybookjs.netlify.com/svelte-kitchen-sink/) | [![Svelte](https://img.shields.io/npm/dm/@storybook/svelte?style=flat-square&color=eee)](code/renderers/svelte) |
| [Preact](code/renderers/preact) | [![Storybook demo](https://img.shields.io/npm/v/@storybook/preact/latest?style=flat-square&color=blue&label)](https://storybookjs.netlify.com/preact-kitchen-sink/) | [![Preact](https://img.shields.io/npm/dm/@storybook/preact?style=flat-square&color=eee)](code/renderers/preact) |
| [Marionette.js](https://github.com/storybookjs/marionette) | - | [![Marionette.js](https://img.shields.io/npm/dm/@storybook/marionette?style=flat-square&color=eee)](https://github.com/storybookjs/marionette) |
| [Qwik](https://github.com/literalpie/storybook-framework-qwik) | - | [![Qwik](https://img.shields.io/npm/dm/storybook-framework-qwik?style=flat-square&color=eee)](https://github.com/literalpie/storybook-framework-qwik) |
| [Android, iOS, Flutter](https://github.com/storybookjs/native) | [![Storybook demo](https://img.shields.io/npm/v/@storybook/native/latest?style=flat-square&color=blue&label)](https://storybookjs.github.io/native/@storybook/native-flutter-example/index.html) | [![Native](https://img.shields.io/npm/dm/@storybook/native?style=flat-square&color=eee)](https://github.com/storybookjs/native) |

### Sub Projects
Expand Down
Loading

0 comments on commit 7a495e0

Please sign in to comment.