Merge pull request #18501 from storybookjs/future/docs2-core

.gitignore

@@ -36,6 +36,7 @@ lib/manager-webpack5/prebuilt
 lib/manager-webpack5/prebuilt
 examples/angular-cli/addon-jest.testresults.json
 junit.xml
+.next
 
 # Yarn stuff
 /**/.yarn/*

addons/a11y/src/components/A11yContext.test.tsx

@@ -50,16 +50,16 @@ const axeResult: Partial<AxeResults> = {
 };
 
 describe('A11YPanel', () => {
+  const getCurrentStoryData = jest.fn();
   beforeEach(() => {
     mockedApi.useChannel.mockReset();
-    mockedApi.useStorybookState.mockReset();
+    mockedApi.useStorybookApi.mockReset();
     mockedApi.useAddonState.mockReset();
 
     mockedApi.useAddonState.mockImplementation((_, defaultState) => React.useState(defaultState));
     mockedApi.useChannel.mockReturnValue(jest.fn());
-    const storyState: Partial<api.State> = { storyId };
-    // Lazy to mock entire state
-    mockedApi.useStorybookState.mockReturnValue(storyState as any);
+    getCurrentStoryData.mockReset().mockReturnValue({ id: storyId, type: 'story' });
+    mockedApi.useStorybookApi.mockReturnValue({ getCurrentStoryData } as any);
   });
 
   it('should render children', () => {

addons/a11y/src/components/A11yContext.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { themes, convert } from '@storybook/theming';
 import { Result } from 'axe-core';
-import { useChannel, useStorybookState, useAddonState } from '@storybook/api';
+import { useChannel, useAddonState, useStorybookApi } from '@storybook/api';
 import { STORY_CHANGED, STORY_RENDERED } from '@storybook/core-events';
 import { ADDON_ID, EVENTS } from '../constants';
 
@@ -55,7 +55,8 @@ export const A11yContextProvider: React.FC<A11yContextProviderProps> = ({ active
   const [results, setResults] = useAddonState<Results>(ADDON_ID, defaultResult);
   const [tab, setTab] = React.useState(0);
   const [highlighted, setHighlighted] = React.useState<string[]>([]);
-  const { storyId } = useStorybookState();
+  const api = useStorybookApi();
+  const storyEntry = api.getCurrentStoryData();
 
   const handleToggleHighlight = React.useCallback((target: string[], highlight: boolean) => {
     setHighlighted((prevHighlighted) =>
@@ -89,12 +90,12 @@ export const A11yContextProvider: React.FC<A11yContextProviderProps> = ({ active
   }, [highlighted, tab]);
 
   React.useEffect(() => {
-    if (active) {
-      handleRun(storyId);
+    if (active && storyEntry?.type === 'story') {
+      handleRun(storyEntry.id);
     } else {
       handleClearHighlights();
     }
-  }, [active, handleClearHighlights, emit, storyId]);
+  }, [active, handleClearHighlights, emit, storyEntry]);
 
   if (!active) return null;
 

addons/docs/src/blocks/Canvas.tsx

@@ -42,16 +42,18 @@ const getPreviewProps = (
   }
   const childArray: ReactNodeArray = Array.isArray(children) ? children : [children];
   const storyChildren = childArray.filter(
-    (c: ReactElement) => c.props && (c.props.id || c.props.name)
+    (c: ReactElement) => c.props && (c.props.id || c.props.name || c.props.of)
   ) as ReactElement[];
-  const targetIds = storyChildren.map(
-    (s) =>
-      s.props.id ||
-      toId(
-        mdxComponentAnnotations.id || mdxComponentAnnotations.title,
-        storyNameFromExport(mdxStoryNameToKey[s.props.name])
-      )
-  );
+  const targetIds = storyChildren.map(({ props: { id, of, name } }) => {
+    if (id) return id;
+    if (of) return docsContext.storyIdByModuleExport(of);
+
+    return toId(
+      mdxComponentAnnotations.id || mdxComponentAnnotations.title,
+      storyNameFromExport(mdxStoryNameToKey[name])
+    );
+  });
+
   const sourceProps = getSourceProps({ ids: targetIds }, docsContext, sourceContext);
   if (!sourceState) sourceState = sourceProps.state;
   const storyIds = targetIds.map((targetId) =>

addons/docs/src/blocks/DocsContainer.tsx

@@ -36,17 +36,21 @@ const warnOptionsTheme = deprecate(
 );
 
 export const DocsContainer: FunctionComponent<DocsContainerProps> = ({ context, children }) => {
-  const { id: storyId, storyById } = context;
-  const {
-    parameters: { options = {}, docs = {} },
-  } = storyById(storyId);
-  let themeVars = docs.theme;
-  if (!themeVars && options.theme) {
-    warnOptionsTheme();
-    themeVars = options.theme;
+  const { id: storyId, type, storyById } = context;
+  const allComponents = { ...defaultComponents };
+  let theme = ensureTheme(null);
+  if (type === 'legacy') {
+    const {
+      parameters: { options = {}, docs = {} },
+    } = storyById(storyId);
+    let themeVars = docs.theme;
+    if (!themeVars && options.theme) {
+      warnOptionsTheme();
+      themeVars = options.theme;
+    }
+    theme = ensureTheme(themeVars);
+    Object.assign(allComponents, docs.components);
   }
-  const theme = ensureTheme(themeVars);
-  const allComponents = { ...defaultComponents, ...docs.components };
 
   useEffect(() => {
     let url;

addons/docs/src/blocks/DocsContext.ts

@@ -13,10 +13,10 @@ export type { DocsContextProps };
 // This was specifically a problem with the Vite builder.
 /* eslint-disable no-underscore-dangle */
 if (globalWindow && globalWindow.__DOCS_CONTEXT__ === undefined) {
-  globalWindow.__DOCS_CONTEXT__ = createContext({});
+  globalWindow.__DOCS_CONTEXT__ = createContext(null);
   globalWindow.__DOCS_CONTEXT__.displayName = 'DocsContext';
 }
 
 export const DocsContext: Context<DocsContextProps<AnyFramework>> = globalWindow
   ? globalWindow.__DOCS_CONTEXT__
-  : createContext({});
+  : createContext(null);

addons/docs/src/blocks/DocsRenderer.tsx

@@ -0,0 +1,51 @@
+import React, { ComponentType } from 'react';
+import ReactDOM from 'react-dom';
+import { AnyFramework, Parameters } from '@storybook/csf';
+import { DocsRenderFunction } from '@storybook/preview-web';
+
+import { DocsContainer } from './DocsContainer';
+import { DocsPage } from './DocsPage';
+import { DocsContextProps } from './DocsContext';
+
+export class DocsRenderer<TFramework extends AnyFramework> {
+  public render: DocsRenderFunction<TFramework>;
+
+  public unmount: (element: HTMLElement) => void;
+
+  constructor() {
+    this.render = (
+      docsContext: DocsContextProps<TFramework>,
+      docsParameters: Parameters,
+      element: HTMLElement,
+      callback: () => void
+    ): void => {
+      renderDocsAsync(docsContext, docsParameters, element).then(callback);
+    };
+
+    this.unmount = (element: HTMLElement) => {
+      ReactDOM.unmountComponentAtNode(element);
+    };
+  }
+}
+
+async function renderDocsAsync<TFramework extends AnyFramework>(
+  docsContext: DocsContextProps<TFramework>,
+  docsParameters: Parameters,
+  element: HTMLElement
+) {
+  const Container: ComponentType<{ context: DocsContextProps<TFramework> }> =
+    docsParameters.container || (await docsParameters.getContainer?.()) || DocsContainer;
+
+  const Page: ComponentType = docsParameters.page || (await docsParameters.getPage?.()) || DocsPage;
+
+  // Use `title` as a key so that we force a re-render every time we switch components
+  const docsElement = (
+    <Container key={docsContext.title} context={docsContext}>
+      <Page />
+    </Container>
+  );
+
+  await new Promise<void>((resolve) => {
+    ReactDOM.render(docsElement, element, resolve);
+  });
+}

addons/docs/src/blocks/ExternalDocsContainer.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+
+import { ThemeProvider, themes, ensure } from '@storybook/theming';
+import { DocsContextProps } from '@storybook/preview-web';
+import { ModuleExport, ModuleExports, Story } from '@storybook/store';
+import { AnyFramework, StoryId } from '@storybook/csf';
+
+import { DocsContext } from './DocsContext';
+import { ExternalPreview } from './ExternalPreview';
+
+let preview: ExternalPreview<AnyFramework>;
+
+export const ExternalDocsContainer: React.FC<{ projectAnnotations: any }> = ({
+  projectAnnotations,
+  children,
+}) => {
+  if (!preview) preview = new ExternalPreview(projectAnnotations);
+
+  let pageMeta: ModuleExport;
+  const setMeta = (m: ModuleExport) => {
+    pageMeta = m;
+  };
+
+  const docsContext: DocsContextProps = {
+    type: 'external',
+
+    id: 'external-docs',
+    title: 'External',
+    name: 'Docs',
+
+    storyIdByModuleExport: (storyExport: ModuleExport, metaExport: ModuleExports) => {
+      return preview.storyIdByModuleExport(storyExport, metaExport || pageMeta);
+    },
+
+    storyById: (id: StoryId) => {
+      return preview.storyById(id);
+    },
+
+    getStoryContext: () => {
+      throw new Error('not implemented');
+    },
+
+    componentStories: () => {
+      // TODO: could implement in a very similar way to in DocsRender. (TODO: How to share code?)
+      throw new Error('not implemented');
+    },
+
+    loadStory: async (id: StoryId) => {
+      return preview.storyById(id);
+    },
+
+    renderStoryToElement: (story: Story<AnyFramework>, element: HTMLElement) => {
+      return preview.renderStoryToElement(story, element);
+    },
+
+    setMeta,
+  };
+
+  return (
+    <DocsContext.Provider value={docsContext}>
+      <ThemeProvider theme={ensure(themes.normal)}>{children}</ThemeProvider>
+    </DocsContext.Provider>
+  );
+};

addons/docs/src/blocks/ExternalPreview.test.ts

@@ -0,0 +1,80 @@
+import { StoryId } from '@storybook/csf';
+import { ExternalPreview } from './ExternalPreview';
+
+const projectAnnotations = { render: jest.fn(), renderToDOM: jest.fn() };
+const csfFileWithTitle = {
+  default: { title: 'Component' },
+
+  one: { args: { a: 'foo' } },
+  two: { args: { b: 'bar' } },
+};
+const csfFileWithoutTitle = {
+  default: {},
+
+  one: { args: { a: 'foo' } },
+};
+
+describe('ExternalPreview', () => {
+  describe('storyIdByModuleExport and storyById', () => {
+    it('handles csf files with titles', async () => {
+      const preview = new ExternalPreview(projectAnnotations);
+
+      const storyId = preview.storyIdByModuleExport(
+        csfFileWithTitle.one,
+        csfFileWithTitle
+      ) as StoryId;
+      const story = preview.storyById(storyId);
+
+      expect(story).toMatchObject({
+        title: 'Component',
+        initialArgs: { a: 'foo' },
+      });
+    });
+
+    it('returns consistent story ids and objects', () => {
+      const preview = new ExternalPreview(projectAnnotations);
+
+      const storyId = preview.storyIdByModuleExport(
+        csfFileWithTitle.one,
+        csfFileWithTitle
+      ) as StoryId;
+      const story = preview.storyById(storyId);
+
+      expect(preview.storyIdByModuleExport(csfFileWithTitle.one, csfFileWithTitle)).toEqual(
+        storyId
+      );
+      expect(preview.storyById(storyId)).toBe(story);
+    });
+
+    it('handles more than one export', async () => {
+      const preview = new ExternalPreview(projectAnnotations);
+
+      preview.storyById(
+        preview.storyIdByModuleExport(csfFileWithTitle.one, csfFileWithTitle) as StoryId
+      );
+
+      const story = preview.storyById(
+        preview.storyIdByModuleExport(csfFileWithTitle.two, csfFileWithTitle) as StoryId
+      );
+      expect(story).toMatchObject({
+        title: 'Component',
+        initialArgs: { b: 'bar' },
+      });
+    });
+
+    it('handles csf files without titles', async () => {
+      const preview = new ExternalPreview(projectAnnotations);
+
+      const storyId = preview.storyIdByModuleExport(
+        csfFileWithoutTitle.one,
+        csfFileWithoutTitle
+      ) as StoryId;
+      const story = preview.storyById(storyId);
+
+      expect(story).toMatchObject({
+        title: expect.any(String),
+        initialArgs: { a: 'foo' },
+      });
+    });
+  });
+});

addons/docs/src/blocks/ExternalPreview.ts

@@ -0,0 +1,93 @@
+import { Preview } from '@storybook/preview-web';
+import { Path, ModuleExports, StoryIndex, ModuleExport } from '@storybook/store';
+import { toId, AnyFramework, ComponentTitle, StoryId, ProjectAnnotations } from '@storybook/csf';
+
+type StoryExport = ModuleExport;
+type MetaExport = ModuleExports;
+type ExportName = string;
+
+class ConstantMap<TKey, TValue extends string> {
+  entries = new Map<TKey, TValue>();
+
+  // eslint-disable-next-line no-useless-constructor
+  constructor(private prefix: string) {}
+
+  get(key: TKey) {
+    if (!this.entries.has(key)) {
+      this.entries.set(key, `${this.prefix}${this.entries.size}` as TValue);
+    }
+    return this.entries.get(key);
+  }
+}
+
+export class ExternalPreview<TFramework extends AnyFramework> extends Preview<TFramework> {
+  private initialized = false;
+
+  private importPaths = new ConstantMap<MetaExport, Path>('./importPath/');
+
+  private titles = new ConstantMap<MetaExport, ComponentTitle>('title-');
+
+  public storyIds = new Map<StoryExport, StoryId>();
+
+  private storyIndex: StoryIndex = { v: 4, entries: {} };
+
+  private moduleExportsByImportPath: Record<Path, ModuleExports> = {};
+
+  constructor(public projectAnnotations: ProjectAnnotations) {
+    super();
+  }
+
+  storyIdByModuleExport(storyExport: StoryExport, meta: MetaExport) {
+    if (!this.storyIds.has(storyExport)) this.addStoryFromExports(storyExport, meta);
+    return this.storyIds.get(storyExport);
+  }
+
+  addStoryFromExports(storyExport: StoryExport, meta: MetaExport) {
+    const importPath = this.importPaths.get(meta);
+    this.moduleExportsByImportPath[importPath] = meta;
+
+    const title = meta.default.title || this.titles.get(meta);
+
+    const exportEntry = Object.entries(meta).find(
+      ([_, moduleExport]) => moduleExport === storyExport
+    );
+    if (!exportEntry)
+      throw new Error(`Didn't find \`of\` used in Story block in the provided CSF exports`);
+    const storyId = toId(title, exportEntry[0]);
+    this.storyIds.set(storyExport, storyId);
+
+    this.storyIndex.entries[storyId] = {
+      id: storyId,
+      importPath,
+      title,
+      name: 'Name',
+      type: 'story',
+    };
+
+    if (!this.initialized) {
+      this.initialized = true;
+      return this.initialize({
+        getStoryIndex: () => this.storyIndex,
+        importFn: (path: Path) => {
+          return Promise.resolve(this.moduleExportsByImportPath[path]);
+        },
+        getProjectAnnotations: () => this.projectAnnotations,
+      });
+    }
+    // else
+    return this.onStoriesChanged({ storyIndex: this.storyIndex });
+  }
+
+  storyById(storyId: StoryId) {
+    const entry = this.storyIndex.entries[storyId];
+    if (!entry) throw new Error(`Unknown storyId ${storyId}`);
+    const { importPath, title } = entry;
+    const moduleExports = this.moduleExportsByImportPath[importPath];
+    const csfFile = this.storyStore.processCSFFileWithCache<TFramework>(
+      moduleExports,
+      importPath,
+      title
+    );
+    return this.storyStore.storyFromCSFFile({ storyId, csfFile });
+  }
+}

addons/docs/src/blocks/Meta.tsx

@@ -1,12 +1,14 @@
 import React, { FC, useContext } from 'react';
 import global from 'global';
 import { BaseAnnotations } from '@storybook/csf';
+import type { ModuleExports } from '@storybook/store';
+
 import { Anchor } from './Anchor';
 import { DocsContext, DocsContextProps } from './DocsContext';
 
 const { document } = global;
 
-type MetaProps = BaseAnnotations;
+type MetaProps = BaseAnnotations & { of?: ModuleExports };
 
 function getFirstStoryId(docsContext: DocsContextProps): string {
   const stories = docsContext.componentStories();
@@ -16,6 +18,9 @@ function getFirstStoryId(docsContext: DocsContextProps): string {
 
 function renderAnchor() {
   const context = useContext(DocsContext);
+  if (context.type !== 'legacy') {
+    return null;
+  }
   const anchorId = getFirstStoryId(context) || context.id;
 
   return <Anchor storyId={anchorId} />;
@@ -25,9 +30,15 @@ function renderAnchor() {
  * This component is used to declare component metadata in docs
  * and gets transformed into a default export underneath the hood.
  */
-export const Meta: FC<MetaProps> = () => {
-  const params = new URL(document.location).searchParams;
-  const isDocs = params.get('viewMode') === 'docs';
+export const Meta: FC<MetaProps> = ({ of }) => {
+  let isDocs = true;
+  if (document) {
+    const params = new URL(document.location).searchParams;
+    isDocs = params.get('viewMode') === 'docs';
+  }
+
+  const context = useContext(DocsContext);
+  if (of) context.setMeta(of);
 
   return isDocs ? renderAnchor() : null;
 };

addons/docs/src/blocks/Source.tsx

@@ -1,6 +1,6 @@
 import React, { ComponentProps, FC, useContext } from 'react';
 import { Source as PureSource, SourceError } from '@storybook/components';
-import type { StoryId } from '@storybook/api';
+import type { StoryId, Parameters } from '@storybook/api';
 import type { Story } from '@storybook/store';
 
 import { DocsContext, DocsContextProps } from './DocsContext';
@@ -94,7 +94,12 @@ export const getSourceProps = (
   sourceContext: SourceContextProps
 ): PureSourceProps & SourceStateProps => {
   const { id: currentId, storyById } = docsContext;
-  const { parameters } = storyById(currentId);
+  let parameters = {} as Parameters;
+  try {
+    ({ parameters } = storyById(currentId));
+  } catch (err) {
+    // TODO: in external mode, there is no "current"
+  }
 
   const codeProps = props as CodeProps;
   const singleProps = props as SingleSourceProps;

addons/docs/src/blocks/Story.tsx

@@ -11,7 +11,7 @@ import React, {
 import { MDXProvider } from '@mdx-js/react';
 import { resetComponents, Story as PureStory, StorySkeleton } from '@storybook/components';
 import { StoryId, toId, storyNameFromExport, StoryAnnotations, AnyFramework } from '@storybook/csf';
-import type { Story as StoryType } from '@storybook/store';
+import type { ModuleExport, ModuleExports, Story as StoryType } from '@storybook/store';
 
 import { CURRENT_SELECTION } from './types';
 import { DocsContext, DocsContextProps } from './DocsContext';
@@ -33,6 +33,8 @@ type StoryDefProps = {
 
 type StoryRefProps = {
   id?: string;
+  of?: ModuleExport;
+  meta?: ModuleExports;
 };
 
 type StoryImportProps = {
@@ -52,7 +54,12 @@ export const lookupStoryId = (
   );
 
 export const getStoryId = (props: StoryProps, context: DocsContextProps): StoryId => {
-  const { id } = props as StoryRefProps;
+  const { id, of, meta } = props as StoryRefProps;
+
+  if (of) {
+    return context.storyIdByModuleExport(of, meta);
+  }
+
   const { name } = props as StoryDefProps;
   const inputId = id === CURRENT_SELECTION ? context.id : id;
   return inputId || lookupStoryId(name, context);
@@ -62,7 +69,7 @@ export const getStoryProps = <TFramework extends AnyFramework>(
   { height, inline }: StoryProps,
   story: StoryType<TFramework>
 ): PureStoryProps => {
-  const { name: storyName, parameters } = story;
+  const { name: storyName, parameters = {} } = story || {};
   const { docs = {} } = parameters;
 
   if (docs.disable) {
@@ -75,7 +82,7 @@ export const getStoryProps = <TFramework extends AnyFramework>(
 
   return {
     inline: storyIsInline,
-    id: story.id,
+    id: story?.id,
     height: height || (storyIsInline ? undefined : iframeHeight),
     title: storyName,
     ...(storyIsInline && {
@@ -110,7 +117,8 @@ const Story: FunctionComponent<StoryProps> = (props) => {
     return null;
   }
 
-  if (storyProps.inline) {
+  const inline = context.type === 'external' || storyProps.inline;
+  if (inline) {
     // We do this so React doesn't complain when we replace the span in a secondary render
     const htmlContents = `<span></span>`;
 
@@ -120,7 +128,7 @@ const Story: FunctionComponent<StoryProps> = (props) => {
       <div id={storyBlockIdFromId(story.id)}>
         <MDXProvider components={resetComponents}>
           {height ? (
-            <style>{`#story--${story.id} { min-height: ${height}; transform: translateZ(0); overflow: auto }`}</style>
+            <style>{`#story--${story.id} { min-height: ${height}px; transform: translateZ(0); overflow: auto }`}</style>
           ) : null}
           {showLoader && <StorySkeleton />}
           <div

addons/docs/src/blocks/index.ts

@@ -7,6 +7,8 @@ export * from './Description';
 export * from './DocsContext';
 export * from './DocsPage';
 export * from './DocsContainer';
+export * from './DocsRenderer'; // For testing
+export * from './ExternalDocsContainer';
 export * from './DocsStory';
 export * from './Heading';
 export * from './Meta';

addons/docs/src/blocks/useStory.ts

@@ -16,12 +16,9 @@ export function useStories<TFramework extends AnyFramework = AnyFramework>(
   storyIds: StoryId[],
   context: DocsContextProps<TFramework>
 ): (Story<TFramework> | void)[] {
-  const initialStoriesById = context.componentStories().reduce((acc, story) => {
-    acc[story.id] = story;
-    return acc;
-  }, {} as Record<StoryId, Story<TFramework>>);
-
-  const [storiesById, setStories] = useState(initialStoriesById as typeof initialStoriesById);
+  // Legacy docs pages can reference any story by id. Those stories will need to be
+  // asyncronously loaded; we use the state for this
+  const [storiesById, setStories] = useState<Record<StoryId, Story<TFramework>>>({});
 
   useEffect(() => {
     Promise.all(
@@ -40,5 +37,14 @@ export function useStories<TFramework extends AnyFramework = AnyFramework>(
     );
   });
 
-  return storyIds.map((storyId) => storiesById[storyId]);
+  return storyIds.map((storyId) => {
+    if (storiesById[storyId]) return storiesById[storyId];
+
+    try {
+      // If we are allowed to load this story id synchonously, this will work
+      return context.storyById(storyId);
+    } catch (err) {
+      return null;
+    }
+  });
 }

addons/docs/src/preview.ts

@@ -1,6 +1,8 @@
 export const parameters = {
   docs: {
-    getContainer: async () => (await import('./blocks')).DocsContainer,
-    getPage: async () => (await import('./blocks')).DocsPage,
+    renderer: async () => {
+      const { DocsRenderer } = await import('./blocks/DocsRenderer');
+      return new DocsRenderer();
+    },
   },
 };

addons/storysource/src/StoryPanel.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { API, Story, useParameter } from '@storybook/api';
+import { API, useParameter } from '@storybook/api';
 import { styled } from '@storybook/theming';
 import { Link } from '@storybook/router';
 import {
@@ -48,7 +48,7 @@ interface SourceParams {
   locationsMap?: LocationsMap;
 }
 export const StoryPanel: React.FC<StoryPanelProps> = ({ api }) => {
-  const story: Story | undefined = api.getCurrentStoryData() as Story;
+  const story = api.getCurrentStoryData();
   const selectedStoryRef = React.useRef<HTMLDivElement>(null);
   const { source, locationsMap }: SourceParams = useParameter('storySource', {
     source: 'loading source...',
@@ -114,10 +114,10 @@ export const StoryPanel: React.FC<StoryPanelProps> = ({ api }) => {
       const location = locationsMap[key];
       const first = location.startLoc.line - 1;
       const last = location.endLoc.line;
-      const { kind, refId } = story;
+      const { title, refId } = story;
       // source loader ids are different from story id
       const sourceIdParts = key.split('--');
-      const id = api.storyId(kind, sourceIdParts[sourceIdParts.length - 1]);
+      const id = api.storyId(title, sourceIdParts[sourceIdParts.length - 1]);
       const start = createPart({ rows: rows.slice(lastRow, first), stylesheet, useInlineStyles });
       const storyPart = createStoryPart({ rows, stylesheet, useInlineStyles, location, id, refId });
 

docs/configure/telemetry.md

@@ -87,7 +87,7 @@ Will generate the following output:
     },
     "packageManager": {
       "name": "yarn",
-      "version": "3.1.1",
+      "version": "3.1.1"
     },
     "monorepo": "Nx",
     "features": {

docs/get-started/install.md

@@ -99,4 +99,4 @@ If all else fails, try asking for [help](https://storybook.js.org/support)
 
 </details>
 
-Now that you installed Storybook successfully, let’s take a look at a story that was written for us.
+Now that you installed Storybook successfully, let’s take a look at a story that was written for us.

docs/versions/next.json

@@ -1 +1,6 @@
-{"version":"6.5.0-rc.1","info":{"plain":"### Bug Fixes\n\n- CLI: Improve webpack version and add detection of nextjs ([#18220](https://github.com/storybookjs/storybook/pull/18220))\n- ArgsTable: Gracefully handle conditional args failures ([#18248](https://github.com/storybookjs/storybook/pull/18248))\n- Controls: Fix reset button broken for !undefined URL values ([#18231](https://github.com/storybookjs/storybook/pull/18231))\n- Vue3: Add support for TSX in single file components ([#18038](https://github.com/storybookjs/storybook/pull/18038))"}}
+{
+  "version": "6.5.0-rc.1",
+  "info": {
+    "plain": "### Bug Fixes\n\n- CLI: Improve webpack version and add detection of nextjs ([#18220](https://github.com/storybookjs/storybook/pull/18220))\n- ArgsTable: Gracefully handle conditional args failures ([#18248](https://github.com/storybookjs/storybook/pull/18248))\n- Controls: Fix reset button broken for !undefined URL values ([#18231](https://github.com/storybookjs/storybook/pull/18231))\n- Vue3: Add support for TSX in single file components ([#18038](https://github.com/storybookjs/storybook/pull/18038))"
+  }
+}

examples/external-docs/.babelrc

@@ -1,7 +1,13 @@
 {
   "presets": [
-    "@babel/preset-env",
-    "@babel/preset-react",
-    "@babel/preset-typescript"
+    "next/babel",
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "chrome": "100"
+        }
+      }
+    ]
   ]
-}
+}

examples/external-docs/.storybook/main.cjs

@@ -1,6 +1,4 @@
-import type { StorybookConfig } from '@storybook/react-webpack5/types';
-
-const config: StorybookConfig = {
+const config = {
   stories: [
     {
       directory: '../components',

examples/external-docs/components/AccountForm.mdx

@@ -0,0 +1,8 @@
+import { Meta, Story } from '@storybook/addon-docs';
+import * as AccountFormStories from './AccountForm.stories';
+
+## Docs for Account form
+
+<Meta of={AccountFormStories} />
+
+<Story of={AccountFormStories.Standard} />

examples/external-docs/components/Introduction.mdx

@@ -0,0 +1,3 @@
+## Introduction to the Design system
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

examples/external-docs/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

examples/external-docs/next.config.js

@@ -0,0 +1,22 @@
+const { IgnorePlugin } = require('webpack');
+
+// next.config.js
+const withNextra = require('nextra')({
+  theme: 'nextra-theme-docs',
+  themeConfig: './theme.config.js',
+  // optional: add `unstable_staticImage: true` to enable Nextra's auto image import
+});
+
+module.exports = withNextra({
+  reactStrictMode: true,
+
+  // We use a custom webpack config here to work around https://github.com/storybookjs/storybook/issues/17926
+  // We can remove this when the monorepo is upgraded to `react@18`.
+  //   (Currently external docs do not work with React <18, without a simlar workaround)
+  webpack(config) {
+    return {
+      ...config,
+      plugins: [...config.plugins, new IgnorePlugin({ resourceRegExp: /react-dom\/client$/ })],
+    };
+  },
+});

examples/external-docs/package.json

@@ -3,36 +3,40 @@
   "version": "7.0.0-alpha.5",
   "private": true,
   "scripts": {
-    "build-storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true storybook build -c ./src/.storybook",
-    "debug": "cross-env NODE_OPTIONS=--inspect-brk STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true start-storybook -p 9011",
-    "start": "SKIP_PREFLIGHT_CHECK=true react-scripts start",
-    "storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true storybook dev -p 9011 --no-manager-cache -c ./src/.storybook"
+    "build": "next build",
+    "build-storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true storybook build -c .storybook",
+    "dev": "next dev",
+    "lint": "next lint",
+    "start": "next start",
+    "storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true storybook dev -p 9011 --no-manager-cache -c .storybook"
   },
   "dependencies": {
+    "@storybook/addon-docs": "7.0.0-alpha.5",
     "@storybook/addon-essentials": "7.0.0-alpha.5",
     "@storybook/components": "7.0.0-alpha.5",
     "@storybook/csf": "0.0.2--canary.4566f4d.1",
     "@storybook/preview-web": "7.0.0-alpha.5",
     "@storybook/react": "7.0.0-alpha.5",
     "@storybook/react-webpack5": "7.0.0-alpha.5",
-    "@storybook/store": "7.0.0-alpha.5",
     "@storybook/theming": "7.0.0-alpha.5",
     "formik": "^2.2.9",
-    "prop-types": "15.7.2",
+    "next": "^12.1.0",
+    "nextra": "^1.1.0",
+    "nextra-theme-docs": "^1.2.6",
+    "prop-types": "^15.8.1",
     "react": "16.14.0",
-    "react-dom": "16.14.0",
-    "react-scripts": "^5.0.1"
+    "react-dom": "16.14.0"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.12.11",
-    "@babel/preset-react": "^7.12.10",
-    "@babel/preset-typescript": "^7.12.7",
+    "@babel/preset-env": "^7.17.10",
     "@testing-library/dom": "^7.31.2",
     "@testing-library/user-event": "^13.1.9",
     "@types/babel__preset-env": "^7",
-    "@types/react": "^16.14.23",
-    "@types/react-dom": "^16.9.14",
+    "@types/prop-types": "^15",
+    "@types/react": "^17.0.39",
     "cross-env": "^7.0.3",
+    "eslint": "8.7.0",
+    "eslint-config-next": "12.0.8",
     "storybook": "7.0.0-alpha.5",
     "typescript": "~4.6.3",
     "webpack": "5"

examples/external-docs/pages/AccountForm.mdx

@@ -0,0 +1 @@
+../components/AccountForm.mdx

examples/external-docs/pages/_app.js

@@ -0,0 +1,19 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import 'nextra-theme-docs/style.css';
+import { ExternalDocsContainer } from '@storybook/addon-docs';
+import * as reactAnnotations from '@storybook/react/preview';
+import * as previewAnnotations from '../.storybook/preview';
+
+const projectAnnotations = {
+  ...reactAnnotations,
+  ...previewAnnotations,
+};
+
+export default function Nextra({ Component, pageProps }) {
+  return (
+    <ExternalDocsContainer projectAnnotations={projectAnnotations}>
+      <Component {...pageProps} />
+    </ExternalDocsContainer>
+  );
+}

examples/external-docs/pages/api/hello.js

@@ -0,0 +1,5 @@
+// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
+
+export default function handler(req, res) {
+  res.status(200).json({ name: 'John Doe' })
+}

examples/external-docs/pages/index.mdx

@@ -0,0 +1,22 @@
+import Callout from 'nextra-theme-docs/callout';
+import { Title, Meta, Story, Canvas } from '@storybook/addon-docs';
+import * as AccountFormStories from '../components/AccountForm.stories';
+import * as ButtonStories from '../components/button.stories';
+
+<Title>Embedded docs demo</Title>
+
+<Meta of={AccountFormStories} />
+
+This is an example of an MDX file that embeds Doc Blocks and CSF stories.
+
+<Canvas withSource={{ language: 'html', code: '<h1>hahaha</h1>' }}>
+  <Story of={AccountFormStories.Standard} />
+</Canvas>
+
+<Story of={ButtonStories.Basic} meta={ButtonStories} />
+
+<Callout emoji="✅">
+  **MDX** (the library), at its core, transforms MDX (the syntax) to JSX. It receives an MDX string
+  and outputs a _JSX string_. It does this by parsing the MDX document to a syntax tree and then
+  generates a JSX document from that tree.
+</Callout>

examples/external-docs/pages/nested/item1.mdx

@@ -0,0 +1,3 @@
+# Item 1
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Partiendo adversarium no mea. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Et mazim recteque nam. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec. Ad doctus gubergren duo, mel te postea suavitate. Vivendum intellegat et qui, ei denique consequuntur vix. Scripta periculis ei eam, te pro movet reformidans. Te cum aeque repudiandae delicatissimi, cu populo dictas ponderum vel, dolor consequat ut vix. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec.

examples/external-docs/pages/nested/item2.mdx

@@ -0,0 +1,3 @@
+# Item 2
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Vivendum intellegat et qui, ei denique consequuntur vix. Tritani reprehendunt pro an, his ne liber iusto. Vivendum intellegat et qui, ei denique consequuntur vix. Scripta periculis ei eam, te pro movet reformidans. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Per ea omnis decore, eu mei appareat tincidunt. Et clita interesset quo. Vivendum intellegat et qui, ei denique consequuntur vix. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec. Et mazim recteque nam. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec. Pri veritus expetendis ex. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec.

examples/external-docs/pages/setup.mdx

@@ -0,0 +1,3 @@
+# Setup instructions
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Errem laboramus sit ei, te sed brute viderer. Scripta periculis ei eam, te pro movet reformidans. Vivendum intellegat et qui, ei denique consequuntur vix. Pri posse graeco definitiones cu, id eam populo quaestio adipiscing, usu quod malorum te. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec. Scripta periculis ei eam, te pro movet reformidans. Scripta periculis ei eam, te pro movet reformidans. Accusam explicari sed ei. Vivendum intellegat et qui, ei denique consequuntur vix. Offendit eleifend moderatius ex vix, quem odio mazim et qui, purto expetendis cotidieque quo cu, veri persius vituperata ei nec. Scripta periculis ei eam, te pro movet reformidans. Offendit eleifend moderatius ex vix, quem odio mazim et qui, ei denique consequuntur vix. Vivendum intellegat et qui, ei denique consequuntur vix.

examples/external-docs/public/index.html

@@ -1,43 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="theme-color" content="#000000" />
-    <meta
-      name="description"
-      content="Web site created using create-react-app"
-    />
-    <link rel="apple-touch-icon" href="logo192.png" />
-    <!--
-      manifest.json provides metadata used when your web app is installed on a
-      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
-    -->
-    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
-    <!--
-      Notice the use of %PUBLIC_URL% in the tags above.
-      It will be replaced with the URL of the `public` folder during the build.
-      Only files inside the `public` folder can be referenced from the HTML.
-
-      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
-      work correctly both with client-side routing and a non-root public URL.
-      Learn how to configure a non-root public URL by running `npm run build`.
-    -->
-    <title>React App</title>
-  </head>
-  <body>
-    <noscript>You need to enable JavaScript to run this app.</noscript>
-    <div id="root"></div>
-    <!--
-      This HTML file is a template.
-      If you open it directly in the browser, you will see an empty page.
-
-      You can add webfonts, meta tags, or analytics to this file.
-      The build step will place the bundled scripts into the <body> tag.
-
-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
-    -->
-  </body>
-</html>

examples/external-docs/public/manifest.json

@@ -1,25 +0,0 @@
-{
-  "short_name": "React App",
-  "name": "Create React App Sample",
-  "icons": [
-    {
-      "src": "favicon.ico",
-      "sizes": "64x64 32x32 24x24 16x16",
-      "type": "image/x-icon"
-    },
-    {
-      "src": "logo192.png",
-      "type": "image/png",
-      "sizes": "192x192"
-    },
-    {
-      "src": "logo512.png",
-      "type": "image/png",
-      "sizes": "512x512"
-    }
-  ],
-  "start_url": ".",
-  "display": "standalone",
-  "theme_color": "#000000",
-  "background_color": "#ffffff"
-}

examples/external-docs/public/robots.txt

@@ -1,2 +0,0 @@
-# https://www.robotstxt.org/robotstxt.html
-User-agent: *

examples/external-docs/public/vercel.svg

@@ -0,0 +1,4 @@
+<svg width="283" height="64" viewBox="0 0 283 64" fill="none" 
+    xmlns="http://www.w3.org/2000/svg">
+    <path d="M141.04 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.46 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM248.72 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.45 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM200.24 34c0 6 3.92 10 10 10 4.12 0 7.21-1.87 8.8-4.92l7.68 4.43c-3.18 5.3-9.14 8.49-16.48 8.49-11.05 0-19-7.2-19-18s7.96-18 19-18c7.34 0 13.29 3.19 16.48 8.49l-7.68 4.43c-1.59-3.05-4.68-4.92-8.8-4.92-6.07 0-10 4-10 10zm82.48-29v46h-9V5h9zM36.95 0L73.9 64H0L36.95 0zm92.38 5l-27.71 48L73.91 5H84.3l17.32 30 17.32-30h10.39zm58.91 12v9.69c-1-.29-2.06-.49-3.2-.49-5.81 0-10 4-10 10V51h-9V17h9v9.2c0-5.08 5.91-9.2 13.2-9.2z" fill="#000"/>
+</svg>

examples/external-docs/src/SecondStoriesPage.tsx

@@ -1,14 +0,0 @@
-import React from 'react';
-import { DocsProvider, Meta, Story } from './blocks';
-
-import meta, { Standard } from './components/AccountForm.stories';
-
-export default () => (
-  <DocsProvider>
-    <div>
-      <Meta of={meta} />
-
-      <Story of={Standard} />
-    </div>
-  </DocsProvider>
-);

examples/external-docs/src/StoriesPage.tsx

@@ -1,18 +0,0 @@
-import React from 'react';
-import { DocsProvider, Meta, Story } from './blocks';
-
-import meta, { WithArgs, Basic } from './components/button.stories';
-import EmojiMeta, { WithArgs as EmojiWithArgs } from './components/emoji-button.stories';
-
-export default () => (
-  <DocsProvider>
-    <div>
-      <Meta of={meta} />
-
-      <Story of={WithArgs} />
-      <Story of={Basic} />
-
-      <Story of={EmojiWithArgs} meta={EmojiMeta} />
-    </div>
-  </DocsProvider>
-);

examples/external-docs/src/blocks.tsx

@@ -1,167 +0,0 @@
-import React, { createContext, useContext, useRef, useEffect } from 'react';
-
-import { Preview } from '@storybook/preview-web';
-import { Path, ModuleExports, StoryIndex } from '@storybook/store';
-import { toId, AnyFramework, ComponentTitle, StoryId } from '@storybook/csf';
-
-// @ts-ignore
-import * as reactAnnotations from '@storybook/react/dist/esm/client/preview/config';
-// @ts-ignore
-import * as previewAnnotations from './.storybook/preview';
-
-type StoryExport = any;
-type MetaExport = any;
-type ExportName = string;
-
-const projectAnnotations = {
-  ...reactAnnotations,
-  ...previewAnnotations,
-};
-
-const DocsContext = createContext<{
-  setMeta: (meta: MetaExport) => void;
-  addStory: (story: StoryExport, storyMeta?: MetaExport) => void;
-  renderStory: (story: StoryExport, element: HTMLElement) => void;
-}>({
-  setMeta: () => {},
-  addStory: () => {},
-  renderStory: () => {},
-});
-
-export const DocsProvider: React.FC = ({ children }) => {
-  let pageMeta: MetaExport;
-  const setMeta = (m: MetaExport) => {
-    pageMeta = m;
-  };
-
-  let nextImportPath = 0;
-  const importPaths = new Map<MetaExport, Path>();
-  const getImportPath = (meta: MetaExport) => {
-    if (!importPaths.has(meta)) {
-      importPaths.set(meta, `importPath-${nextImportPath}`);
-      nextImportPath += 1;
-    }
-    return importPaths.get(meta) as Path;
-  };
-
-  let nextTitle = 0;
-  const titles = new Map<MetaExport, ComponentTitle>();
-  const getTitle = (meta: MetaExport) => {
-    if (!titles.has(meta)) {
-      titles.set(meta, `title-${nextTitle}`);
-      nextTitle += 1;
-    }
-    return titles.get(meta);
-  };
-
-  let nextExportName = 0;
-  const exportNames = new Map<StoryExport, ExportName>();
-  const getExportName = (story: StoryExport) => {
-    if (!exportNames.has(story)) {
-      exportNames.set(story, `export-${nextExportName}`);
-      nextExportName += 1;
-    }
-    return exportNames.get(story) as ExportName;
-  };
-
-  const storyIds = new Map<StoryExport, StoryId>();
-
-  const storyIndex: StoryIndex = { v: 3, stories: {} };
-  const knownCsfFiles: Record<Path, ModuleExports> = {};
-
-  const addStory = (storyExport: StoryExport, storyMeta?: MetaExport) => {
-    const meta = storyMeta || pageMeta;
-    const importPath: Path = getImportPath(meta);
-    const title: ComponentTitle = meta.title || getTitle(meta);
-
-    const exportName = getExportName(storyExport);
-    const storyId = toId(title, exportName);
-    storyIds.set(storyExport, storyId);
-
-    if (!knownCsfFiles[importPath]) {
-      knownCsfFiles[importPath] = {
-        default: meta,
-      };
-    }
-    knownCsfFiles[importPath][exportName] = storyExport;
-
-    storyIndex.stories[storyId] = {
-      id: storyId,
-      importPath,
-      title,
-      name: 'Name',
-    };
-  };
-
-  let previewPromise: Promise<Preview<AnyFramework>>;
-  const getPreview = () => {
-    const importFn = (importPath: Path) => {
-      console.log(knownCsfFiles, importPath);
-      return Promise.resolve(knownCsfFiles[importPath]);
-    };
-
-    if (!previewPromise) {
-      previewPromise = (async () => {
-        // @ts-ignore
-        if (window.preview) {
-          // @ts-ignore
-          (window.preview as PreviewWeb<AnyFramework>).onStoriesChanged({
-            importFn,
-            storyIndex,
-          });
-        } else {
-          const preview = new Preview();
-          await preview.initialize({
-            getStoryIndex: () => storyIndex,
-            importFn,
-            getProjectAnnotations: () => projectAnnotations,
-          });
-          // @ts-ignore
-          window.preview = preview;
-        }
-
-        // @ts-ignore
-        return window.preview;
-      })();
-    }
-
-    return previewPromise;
-  };
-
-  const renderStory = async (storyExport: any, element: HTMLElement) => {
-    const preview = await getPreview();
-
-    const storyId = storyIds.get(storyExport);
-    if (!storyId) throw new Error(`Didn't find story id '${storyId}'`);
-    const story = await preview.storyStore.loadStory({ storyId });
-
-    console.log({ story });
-
-    preview.renderStoryToElement(story, element);
-  };
-
-  return (
-    <DocsContext.Provider value={{ setMeta, addStory, renderStory }}>
-      {children}
-    </DocsContext.Provider>
-  );
-};
-
-export function Meta({ of }: { of: any }) {
-  const { setMeta } = useContext(DocsContext);
-  setMeta(of);
-  return null;
-}
-
-export function Story({ of, meta }: { of: any; meta?: any }) {
-  const { addStory, renderStory } = useContext(DocsContext);
-
-  addStory(of, meta);
-
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    if (ref.current) renderStory(of, ref.current);
-  });
-
-  return <div ref={ref} />;
-}

examples/external-docs/src/index.tsx

@@ -1,24 +0,0 @@
-/* global document */
-
-import React, { useState } from 'react';
-import ReactDOM from 'react-dom';
-import StoriesPage from './StoriesPage';
-import SecondStoriesPage from './SecondStoriesPage';
-
-const Router = ({ routes }: { routes: (() => JSX.Element)[] }) => {
-  const [routeNumber, setRoute] = useState(0);
-  const Route = routes[routeNumber];
-
-  console.log(routeNumber);
-  return (
-    <div>
-      <Route />
-      {/* eslint-disable-next-line react/button-has-type */}
-      <button onClick={() => setRoute((routeNumber + 1) % routes.length)}>Next Route</button>
-    </div>
-  );
-};
-
-const App = () => <Router routes={[StoriesPage, SecondStoriesPage]} />;
-
-ReactDOM.render(<App />, document.getElementById('root'));

examples/external-docs/src/react-app-env.d.ts

@@ -1 +0,0 @@
-/// <reference types="react-scripts" />

examples/external-docs/styles/Home.module.css

@@ -0,0 +1,116 @@
+.container {
+  padding: 0 2rem;
+}
+
+.main {
+  min-height: 100vh;
+  padding: 4rem 0;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+}
+
+.footer {
+  display: flex;
+  flex: 1;
+  padding: 2rem 0;
+  border-top: 1px solid #eaeaea;
+  justify-content: center;
+  align-items: center;
+}
+
+.footer a {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  flex-grow: 1;
+}
+
+.title a {
+  color: #0070f3;
+  text-decoration: none;
+}
+
+.title a:hover,
+.title a:focus,
+.title a:active {
+  text-decoration: underline;
+}
+
+.title {
+  margin: 0;
+  line-height: 1.15;
+  font-size: 4rem;
+}
+
+.title,
+.description {
+  text-align: center;
+}
+
+.description {
+  margin: 4rem 0;
+  line-height: 1.5;
+  font-size: 1.5rem;
+}
+
+.code {
+  background: #fafafa;
+  border-radius: 5px;
+  padding: 0.75rem;
+  font-size: 1.1rem;
+  font-family: Menlo, Monaco, Lucida Console, Liberation Mono, DejaVu Sans Mono,
+    Bitstream Vera Sans Mono, Courier New, monospace;
+}
+
+.grid {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-wrap: wrap;
+  max-width: 800px;
+}
+
+.card {
+  margin: 1rem;
+  padding: 1.5rem;
+  text-align: left;
+  color: inherit;
+  text-decoration: none;
+  border: 1px solid #eaeaea;
+  border-radius: 10px;
+  transition: color 0.15s ease, border-color 0.15s ease;
+  max-width: 300px;
+}
+
+.card:hover,
+.card:focus,
+.card:active {
+  color: #0070f3;
+  border-color: #0070f3;
+}
+
+.card h2 {
+  margin: 0 0 1rem 0;
+  font-size: 1.5rem;
+}
+
+.card p {
+  margin: 0;
+  font-size: 1.25rem;
+  line-height: 1.5;
+}
+
+.logo {
+  height: 1em;
+  margin-left: 0.5rem;
+}
+
+@media (max-width: 600px) {
+  .grid {
+    width: 100%;
+    flex-direction: column;
+  }
+}

examples/external-docs/styles/globals.css

@@ -0,0 +1,16 @@
+html,
+body {
+  padding: 0;
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,
+    Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+* {
+  box-sizing: border-box;
+}

examples/external-docs/theme.config.js

@@ -0,0 +1,29 @@
+import React from 'react';
+
+// theme.config.js
+export default {
+  projectLink: 'https://github.com/shuding/nextra', // GitHub link in the navbar
+  docsRepositoryBase: 'https://github.com/shuding/nextra/blob/master', // base URL for the docs repository
+  titleSuffix: ' – Nextra',
+  nextLinks: true,
+  prevLinks: true,
+  search: true,
+  customSearch: null, // customizable, you can use algolia for example
+  darkMode: true,
+  footer: true,
+  footerText: `MIT ${new Date().getFullYear()} © Shu Ding.`,
+  footerEditLink: `Edit this page on GitHub`,
+  logo: (
+    <>
+      <svg>...</svg>
+      <span>Next.js Static Site Generator</span>
+    </>
+  ),
+  head: (
+    <>
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <meta name="description" content="Nextra: the next docs builder" />
+      <meta name="og:title" content="Nextra: the next docs builder" />
+    </>
+  ),
+};

examples/external-docs/tsconfig.json

@@ -1,26 +1,20 @@
 {
   "compilerOptions": {
-    "baseUrl": ".",
-    "esModuleInterop": true,
-    "jsx": "react",
-    "skipLibCheck": true,
-    "target": "ES2020",
-    "module": "CommonJS",
-    "strict": true,
-    "lib": [
-      "dom",
-      "esnext"
-    ],
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
     "allowJs": true,
-    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "strict": false,
     "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
+    "noEmit": false,
+    "incremental": true,
+    "esModuleInterop": true,
+    "module": "esnext",
     "moduleResolution": "node",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "noEmit": true
+    "jsx": "preserve"
   },
-  "include": [
-    "src/*"
-  ]
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
 }

examples/official-storybook/stories/addon-docs/mdx.stories.js

@@ -34,6 +34,7 @@ DarkModeDocs.decorators = [
   (storyFn) => (
     <DocsContainer
       context={{
+        type: 'legacy',
         componentStories: () => [],
         storyById: () => ({ parameters: { docs: { theme: themes.dark } } }),
       }}

examples/react-ts/.storybook/main.ts

@@ -9,11 +9,11 @@ const config: StorybookConfig = {
     {
       directory: '../src',
       titlePrefix: 'Demo',
-      files: '*.stories.(js|ts|tsx|mdx)',
+      files: '*.stories.(js|ts|tsx)',
     },
     {
-      directory: '../src/addon-docs',
-      files: '*.stories.mdx',
+      directory: '../src',
+      files: '**/*.mdx',
     },
   ],
   logLevel: 'debug',

examples/react-ts/src/docs2/MetaOf.mdx

@@ -0,0 +1,12 @@
+import { Meta, Story, Stories } from '@storybook/addon-docs';
+import * as ButtonStories from '../button.stories';
+
+<Meta of={ButtonStories} />
+
+# Docs with of
+
+hello docs
+
+<Story of={ButtonStories.Basic} />
+
+<Stories />

examples/react-ts/src/docs2/NoTitle.mdx

@@ -0,0 +1,3 @@
+# Docs with no title
+
+hello docs

examples/react-ts/src/docs2/Title.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Docs2/Yabbadabbadooo" />
+
+# Docs with title
+
+hello docs

lib/api/src/index.tsx

@@ -25,9 +25,16 @@ import type { Listener } from '@storybook/channels';
 import { createContext } from './context';
 import Store, { Options } from './store';
 import getInitialState from './initial-state';
-import type { StoriesHash, Story, Root, Group } from './lib/stories';
+import type {
+  StoriesHash,
+  RootEntry,
+  GroupEntry,
+  ComponentEntry,
+  DocsEntry,
+  StoryEntry,
+  HashEntry,
+} from './lib/stories';
 import type { ComposedRef, Refs } from './modules/refs';
-import { isGroup, isRoot, isStory } from './lib/stories';
 
 import * as provider from './modules/provider';
 import * as addons from './modules/addons';
@@ -139,18 +146,27 @@ export const combineParameters = (...parameterSets: Parameters[]) =>
     return undefined;
   });
 
-export type ModuleFn = (m: ModuleArgs) => Module;
-
-interface Module {
-  init?: () => void;
-  api?: unknown;
-  state?: unknown;
+interface ModuleWithInit<APIType = unknown, StateType = unknown> {
+  init: () => void | Promise<void>;
+  api: APIType;
+  state: StateType;
 }
 
+type ModuleWithoutInit<APIType = unknown, StateType = unknown> = Omit<
+  ModuleWithInit<APIType, StateType>,
+  'init'
+>;
+
+export type ModuleFn<APIType = unknown, StateType = unknown, HasInit = false> = (
+  m: ModuleArgs
+) => HasInit extends true
+  ? ModuleWithInit<APIType, StateType>
+  : ModuleWithoutInit<APIType, StateType>;
+
 class ManagerProvider extends Component<ManagerProviderProps, State> {
   api: API = {} as API;
 
-  modules: Module[];
+  modules: (ModuleWithInit | ModuleWithoutInit)[];
 
   static displayName = 'Manager';
 
@@ -252,9 +268,9 @@ class ManagerProvider extends Component<ManagerProviderProps, State> {
   initModules = () => {
     // Now every module has had a chance to set its API, call init on each module which gives it
     // a chance to do things that call other modules' APIs.
-    this.modules.forEach(({ init }) => {
-      if (init) {
-        init();
+    this.modules.forEach((module) => {
+      if ('init' in module) {
+        module.init();
       }
     });
   };
@@ -331,8 +347,18 @@ export function useStorybookApi(): API {
   return api;
 }
 
-export type { StoriesHash, Story, Root, Group, ComposedRef, Refs };
-export { ManagerConsumer as Consumer, ManagerProvider as Provider, isGroup, isRoot, isStory };
+export type {
+  StoriesHash,
+  RootEntry,
+  GroupEntry,
+  ComponentEntry,
+  DocsEntry,
+  StoryEntry,
+  HashEntry,
+  ComposedRef,
+  Refs,
+};
+export { ManagerConsumer as Consumer, ManagerProvider as Provider };
 
 export interface EventMap {
   [eventId: string]: Listener;
@@ -446,13 +472,13 @@ export function useArgs(): [Args, (newArgs: Args) => void, (argNames?: string[])
   const { getCurrentStoryData, updateStoryArgs, resetStoryArgs } = useStorybookApi();
 
   const data = getCurrentStoryData();
-  const args = isStory(data) ? data.args : {};
+  const args = data.type === 'story' ? data.args : {};
   const updateArgs = useCallback(
-    (newArgs: Args) => updateStoryArgs(data as Story, newArgs),
+    (newArgs: Args) => updateStoryArgs(data as StoryEntry, newArgs),
     [data, updateStoryArgs]
   );
   const resetArgs = useCallback(
-    (argNames?: string[]) => resetStoryArgs(data as Story, argNames),
+    (argNames?: string[]) => resetStoryArgs(data as StoryEntry, argNames),
     [data, resetStoryArgs]
   );
 
@@ -468,12 +494,13 @@ export function useGlobalTypes(): ArgTypes {
   return useStorybookApi().getGlobalTypes();
 }
 
-function useCurrentStory(): Story {
+function useCurrentStory(): StoryEntry | DocsEntry {
   const { getCurrentStoryData } = useStorybookApi();
 
-  return getCurrentStoryData() as Story;
+  return getCurrentStoryData();
 }
 
 export function useArgTypes(): ArgTypes {
-  return useCurrentStory()?.argTypes || {};
+  const current = useCurrentStory();
+  return (current?.type === 'story' && current.argTypes) || {};
 }

lib/api/src/initial-state.ts

@@ -9,6 +9,6 @@ type Additions = Addition[];
 
 // Returns the initialState of the app
 const main = (...additions: Additions): State =>
-  additions.reduce((acc: State, item) => merge(acc, item), {});
+  additions.reduce((acc: State, item) => merge<State>(acc, item), {} as any);
 
 export default main;

lib/api/src/lib/merge.ts

@@ -3,8 +3,8 @@ import isEqual from 'lodash/isEqual';
 
 import { logger } from '@storybook/client-logger';
 
-export default (a: any, b: any) =>
-  mergeWith({}, a, b, (objValue: any, srcValue: any) => {
+export default <TObj = any>(a: TObj, b: Partial<TObj>) =>
+  mergeWith({}, a, b, (objValue: TObj, srcValue: Partial<TObj>) => {
     if (Array.isArray(srcValue) && Array.isArray(objValue)) {
       srcValue.forEach((s) => {
         const existing = objValue.find((o) => o === s || isEqual(o, s));

lib/api/src/lib/stories.ts

@@ -25,68 +25,122 @@ const { FEATURES } = global;
 
 export type { StoryId };
 
-export interface Root {
+export interface BaseEntry {
+  id: StoryId;
+  depth: number;
+  name: string;
+  refId?: string;
+  renderLabel?: (item: BaseEntry) => React.ReactNode;
+
+  /** @deprecated */
+  isRoot: boolean;
+  /** @deprecated */
+  isComponent: boolean;
+  /** @deprecated */
+  isLeaf: boolean;
+}
+
+export interface RootEntry extends BaseEntry {
   type: 'root';
-  id: StoryId;
-  depth: 0;
-  name: string;
-  refId?: string;
-  children: StoryId[];
-  isComponent: false;
-  isRoot: true;
-  isLeaf: false;
-  renderLabel?: (item: Root) => React.ReactNode;
   startCollapsed?: boolean;
-}
-
-export interface Group {
-  type: 'group' | 'component';
-  id: StoryId;
-  depth: number;
-  name: string;
   children: StoryId[];
-  refId?: string;
-  parent?: StoryId;
-  isComponent: boolean;
-  isRoot: false;
+
+  /** @deprecated */
+  isRoot: true;
+  /** @deprecated */
+  isComponent: false;
+  /** @deprecated */
   isLeaf: false;
-  renderLabel?: (item: Group) => React.ReactNode;
-  // MDX docs-only stories are "Group" type
-  parameters?: {
-    docsOnly?: boolean;
-    viewMode?: ViewMode;
-  };
 }
 
-export interface Story {
-  type: 'story' | 'docs';
-  id: StoryId;
-  depth: number;
-  parent: StoryId;
-  name: string;
-  kind: StoryKind;
-  refId?: string;
-  children?: StoryId[];
-  isComponent: boolean;
+export interface GroupEntry extends BaseEntry {
+  type: 'group';
+  parent?: StoryId;
+  children: StoryId[];
+
+  /** @deprecated */
   isRoot: false;
+  /** @deprecated */
+  isComponent: false;
+  /** @deprecated */
+  isLeaf: false;
+}
+
+export interface ComponentEntry extends BaseEntry {
+  type: 'component';
+  parent?: StoryId;
+  children: StoryId[];
+
+  /** @deprecated */
+  isRoot: false;
+  /** @deprecated */
+  isComponent: true;
+  /** @deprecated */
+  isLeaf: false;
+}
+
+export interface DocsEntry extends BaseEntry {
+  type: 'docs';
+  parent: StoryId;
+  title: ComponentTitle;
+  /** @deprecated */
+  kind: ComponentTitle;
+  importPath: Path;
+
+  /** @deprecated */
+  isRoot: false;
+  /** @deprecated */
+  isComponent: false;
+  /** @deprecated */
   isLeaf: true;
-  renderLabel?: (item: Story) => React.ReactNode;
+}
+
+export interface StoryEntry extends BaseEntry {
+  type: 'story';
+  parent: StoryId;
+  title: ComponentTitle;
+  /** @deprecated */
+  kind: ComponentTitle;
+  importPath: Path;
   prepared: boolean;
   parameters?: {
-    fileName: string;
-    options: {
-      [optionName: string]: any;
-    };
-    docsOnly?: boolean;
-    viewMode?: ViewMode;
     [parameterName: string]: any;
   };
   args?: Args;
   argTypes?: ArgTypes;
   initialArgs?: Args;
+
+  /** @deprecated */
+  isRoot: false;
+  /** @deprecated */
+  isComponent: false;
+  /** @deprecated */
+  isLeaf: true;
 }
 
-export interface StoryInput {
+/** @deprecated */
+export type Root = RootEntry;
+
+/** @deprecated */
+export type Group = GroupEntry | ComponentEntry;
+
+/** @deprecated */
+export type Story = DocsEntry | StoryEntry;
+
+export type HashEntry = RootEntry | GroupEntry | ComponentEntry | DocsEntry | StoryEntry;
+
+/**
+ * The `StoriesHash` is our manager-side representation of the `StoryIndex`.
+ * We create entries in the hash not only for each story or docs entry, but
+ * also for each "group" of the component (split on '/'), as that's how things
+ * are manipulated in the manager (i.e. in the sidebar)
+ */
+export interface StoriesHash {
+  [id: string]: HashEntry;
+}
+
+// The data received on the (legacy) `setStories` event
+export interface SetStoriesStory {
   id: StoryId;
   name: string;
   refId?: string;
@@ -100,35 +154,13 @@ export interface StoryInput {
     viewMode?: ViewMode;
     [parameterName: string]: any;
   };
+  argTypes?: ArgTypes;
   args?: Args;
   initialArgs?: Args;
 }
 
-export interface StoriesHash {
-  [id: string]: Root | Group | Story;
-}
-
-export type StoriesList = (Group | Story)[];
-
-export type GroupsList = (Root | Group)[];
-
-export interface StoriesRaw {
-  [id: string]: StoryInput;
-}
-
-type Path = string;
-export interface StoryIndexStory {
-  id: StoryId;
-  name: StoryName;
-  title: ComponentTitle;
-  importPath: Path;
-
-  // v2 or v2-compatible story index includes this
-  parameters?: Parameters;
-}
-export interface StoryIndex {
-  v: number;
-  stories: Record<StoryId, StoryIndexStory>;
+export interface SetStoriesStoryData {
+  [id: string]: SetStoriesStory;
 }
 
 export type SetStoriesPayload =
@@ -137,16 +169,50 @@ export type SetStoriesPayload =
       error?: Error;
       globals: Args;
       globalParameters: Parameters;
-      stories: StoriesRaw;
+      stories: SetStoriesStoryData;
       kindParameters: {
         [kind: string]: Parameters;
       };
     }
   | ({
       v?: number;
-      stories: StoriesRaw;
+      stories: SetStoriesStoryData;
     } & Record<string, never>);
 
+// The data recevied via the story index
+type Path = string;
+
+interface BaseIndexEntry {
+  id: StoryId;
+  name: StoryName;
+  title: ComponentTitle;
+  importPath: Path;
+}
+
+export type StoryIndexEntry = BaseIndexEntry & {
+  type?: 'story';
+};
+
+interface V3IndexEntry extends BaseIndexEntry {
+  parameters?: Parameters;
+}
+
+export interface StoryIndexV3 {
+  v: 3;
+  stories: Record<StoryId, V3IndexEntry>;
+}
+
+export type DocsIndexEntry = BaseIndexEntry & {
+  storiesImports: Path[];
+  type: 'docs';
+};
+
+export type IndexEntry = StoryIndexEntry | DocsIndexEntry;
+export interface StoryIndex {
+  v: number;
+  entries: Record<StoryId, IndexEntry>;
+}
+
 const warnLegacyShowRoots = deprecate(
   () => {},
   dedent`
@@ -168,7 +234,7 @@ export const denormalizeStoryParameters = ({
   globalParameters,
   kindParameters,
   stories,
-}: SetStoriesPayload): StoriesRaw => {
+}: SetStoriesPayload): SetStoriesStoryData => {
   return mapValues(stories, (storyData) => ({
     ...storyData,
     parameters: combineParameters(
@@ -179,181 +245,258 @@ export const denormalizeStoryParameters = ({
   }));
 };
 
-const STORY_KIND_PATH_SEPARATOR = /\s*\/\s*/;
+const TITLE_PATH_SEPARATOR = /\s*\/\s*/;
 
-export const transformStoryIndexToStoriesHash = (
-  index: StoryIndex,
+// We used to received a bit more data over the channel on the SET_STORIES event, including
+// the full parameters for each story.
+type PreparedIndexEntry = IndexEntry & {
+  parameters?: Parameters;
+  argTypes?: ArgTypes;
+  args?: Args;
+  initialArgs?: Args;
+};
+export interface PreparedStoryIndex {
+  v: number;
+  entries: Record<StoryId, PreparedIndexEntry>;
+}
+
+export const transformSetStoriesStoryDataToStoriesHash = (
+  data: SetStoriesStoryData,
   { provider }: { provider: Provider }
-): StoriesHash => {
-  const countByTitle = countBy(Object.values(index.stories), 'title');
-  const input = Object.entries(index.stories).reduce(
-    (acc, [id, { title, name, importPath, parameters }]) => {
-      const docsOnly = name === 'Page' && countByTitle[title] === 1;
-      acc[id] = {
+) =>
+  transformStoryIndexToStoriesHash(transformSetStoriesStoryDataToPreparedStoryIndex(data), {
+    provider,
+  });
+
+const transformSetStoriesStoryDataToPreparedStoryIndex = (
+  stories: SetStoriesStoryData
+): PreparedStoryIndex => {
+  const entries: PreparedStoryIndex['entries'] = Object.entries(stories).reduce(
+    (acc, [id, story]) => {
+      if (!story) return acc;
+
+      const { docsOnly, fileName, ...parameters } = story.parameters;
+      const base = {
+        title: story.kind,
         id,
-        kind: title,
-        name,
-        parameters: { fileName: importPath, options: {}, docsOnly, ...parameters },
+        name: story.name,
+        importPath: fileName,
       };
+      if (docsOnly) {
+        acc[id] = {
+          type: 'docs',
+          storiesImports: [],
+          ...base,
+        };
+      } else {
+        const { argTypes, args, initialArgs } = story;
+        acc[id] = {
+          type: 'story',
+          ...base,
+          parameters,
+          argTypes,
+          args,
+          initialArgs,
+        };
+      }
       return acc;
     },
-    {} as StoriesRaw
+    {} as PreparedStoryIndex['entries']
   );
 
-  return transformStoriesRawToStoriesHash(input, { provider, prepared: false });
+  return { v: 4, entries };
 };
 
-export const transformStoriesRawToStoriesHash = (
-  input: StoriesRaw,
-  { provider, prepared = true }: { provider: Provider; prepared?: Story['prepared'] }
+const transformStoryIndexV3toV4 = (index: StoryIndexV3): PreparedStoryIndex => {
+  const countByTitle = countBy(Object.values(index.stories), 'title');
+  return {
+    v: 4,
+    entries: Object.values(index.stories).reduce((acc, entry) => {
+      let type: IndexEntry['type'] = 'story';
+      if (
+        entry.parameters?.docsOnly ||
+        (entry.name === 'Page' && countByTitle[entry.title] === 1)
+      ) {
+        type = 'docs';
+      }
+      acc[entry.id] = {
+        type,
+        ...(type === 'docs' && { storiesImports: [] }),
+        ...entry,
+      };
+      return acc;
+    }, {} as PreparedStoryIndex['entries']),
+  };
+};
+
+export const transformStoryIndexToStoriesHash = (
+  index: PreparedStoryIndex,
+  {
+    provider,
+  }: {
+    provider: Provider;
+  }
 ): StoriesHash => {
-  const values = Object.values(input).filter(Boolean);
-  const usesOldHierarchySeparator = values.some(({ kind }) => kind.match(/\.|\|/)); // dot or pipe
+  if (!index.v) throw new Error('Composition: Missing stories.json version');
 
-  const storiesHashOutOfOrder = values.reduce((acc, item) => {
-    const { kind, parameters } = item;
-    const { sidebar = {}, showRoots: deprecatedShowRoots } = provider.getConfig();
-    const { showRoots = deprecatedShowRoots, collapsedRoots = [], renderLabel } = sidebar;
+  const v4Index = index.v === 4 ? index : transformStoryIndexV3toV4(index as any);
 
-    if (typeof deprecatedShowRoots !== 'undefined') {
-      warnLegacyShowRoots();
-    }
+  const entryValues = Object.values(v4Index.entries);
+  const { sidebar = {}, showRoots: deprecatedShowRoots } = provider.getConfig();
+  const { showRoots = deprecatedShowRoots, collapsedRoots = [], renderLabel } = sidebar;
+  const usesOldHierarchySeparator = entryValues.some(({ title }) => title.match(/\.|\|/)); // dot or pipe
+  if (typeof deprecatedShowRoots !== 'undefined') {
+    warnLegacyShowRoots();
+  }
 
-    const setShowRoots = typeof showRoots !== 'undefined';
-    if (usesOldHierarchySeparator && !setShowRoots && FEATURES?.warnOnLegacyHierarchySeparator) {
-      warnChangedDefaultHierarchySeparators();
-    }
+  const setShowRoots = typeof showRoots !== 'undefined';
+  if (usesOldHierarchySeparator && !setShowRoots && FEATURES?.warnOnLegacyHierarchySeparator) {
+    warnChangedDefaultHierarchySeparators();
+  }
 
-    const groups = kind.trim().split(STORY_KIND_PATH_SEPARATOR);
+  const storiesHashOutOfOrder = Object.values(entryValues).reduce((acc, item) => {
+    // First, split the title into a set of names, separated by '/' and trimmed.
+    const { title } = item;
+    const groups = title.trim().split(TITLE_PATH_SEPARATOR);
     const root = (!setShowRoots || showRoots) && groups.length > 1 ? [groups.shift()] : [];
+    const names = [...root, ...groups];
 
-    const rootAndGroups = [...root, ...groups].reduce((list, name, index) => {
-      const parent = index > 0 && list[index - 1].id;
+    // Now create a "path" or sub id for each name
+    const paths = names.reduce((list, name, idx) => {
+      const parent = idx > 0 && list[idx - 1];
       const id = sanitize(parent ? `${parent}-${name}` : name);
 
       if (parent === id) {
         throw new Error(
           dedent`
-              Invalid part '${name}', leading to id === parentId ('${id}'), inside kind '${kind}'
-
-              Did you create a path that uses the separator char accidentally, such as 'Vue <docs/>' where '/' is a separator char? See https://github.com/storybookjs/storybook/issues/6128
-            `
+          Invalid part '${name}', leading to id === parentId ('${id}'), inside title '${title}'
+          
+          Did you create a path that uses the separator char accidentally, such as 'Vue <docs/>' where '/' is a separator char? See https://github.com/storybookjs/storybook/issues/6128
+          `
         );
       }
+      list.push(id);
+      return list;
+    }, [] as string[]);
 
-      if (root.length && index === 0) {
-        list.push({
+    // Now, let's add an entry to the hash for each path/name pair
+    paths.forEach((id, idx) => {
+      // The child is the next path, OR the story/docs entry itself
+      const childId = paths[idx + 1] || item.id;
+
+      if (root.length && idx === 0) {
+        acc[id] = merge<RootEntry>((acc[id] || {}) as RootEntry, {
           type: 'root',
           id,
-          name,
-          depth: index,
-          children: [],
-          isComponent: false,
-          isLeaf: false,
-          isRoot: true,
+          name: names[idx],
+          depth: idx,
           renderLabel,
           startCollapsed: collapsedRoots.includes(id),
-        });
-      } else {
-        list.push({
-          type: 'group',
-          id,
-          name,
-          parent,
-          depth: index,
-          children: [],
+          // Note that this will later get appended to the previous list of children (see below)
+          children: [childId],
+
+          // deprecated fields
+          isRoot: true,
           isComponent: false,
           isLeaf: false,
-          isRoot: false,
+        });
+        // Usually the last path/name pair will be displayed as a component,
+        // *unless* there are other stories that are more deeply nested under it
+        //
+        // For example, if we had stories for both
+        //   - Atoms / Button
+        //   - Atoms / Button / LabelledButton
+        //
+        // In this example the entry for 'atoms-button' would *not* be a component.
+      } else if ((!acc[id] || acc[id].type === 'component') && idx === paths.length - 1) {
+        acc[id] = merge<ComponentEntry>((acc[id] || {}) as ComponentEntry, {
+          type: 'component',
+          id,
+          name: names[idx],
+          parent: paths[idx - 1],
+          depth: idx,
           renderLabel,
-          parameters: {
-            docsOnly: parameters?.docsOnly,
-            viewMode: parameters?.viewMode,
-          },
+          ...(childId && {
+            children: [childId],
+          }),
+          // deprecated fields
+          isRoot: false,
+          isComponent: true,
+          isLeaf: false,
+        });
+      } else {
+        acc[id] = merge<GroupEntry>((acc[id] || {}) as GroupEntry, {
+          type: 'group',
+          id,
+          name: names[idx],
+          parent: paths[idx - 1],
+          depth: idx,
+          renderLabel,
+          ...(childId && {
+            children: [childId],
+          }),
+          // deprecated fields
+          isRoot: false,
+          isComponent: false,
+          isLeaf: false,
         });
       }
-
-      return list;
-    }, [] as GroupsList);
-
-    const paths = [...rootAndGroups.map(({ id }) => id), item.id];
-
-    // Ok, now let's add everything to the store
-    rootAndGroups.forEach((group, index) => {
-      const child = paths[index + 1];
-      const { id } = group;
-      acc[id] = merge(acc[id] || {}, {
-        ...group,
-        ...(child && { children: [child] }),
-      });
     });
 
+    // Finally add an entry for the docs/story itself
     acc[item.id] = {
-      type: item.parameters?.docsOnly ? 'docs' : 'story',
+      type: 'story',
       ...item,
-      depth: rootAndGroups.length,
-      parent: rootAndGroups[rootAndGroups.length - 1].id,
-      isLeaf: true,
-      isComponent: false,
-      isRoot: false,
+      depth: paths.length,
+      parent: paths[paths.length - 1],
       renderLabel,
-      prepared,
-    };
+      ...(item.type !== 'docs' && { prepared: !!item.parameters }),
+
+      // deprecated fields
+      kind: item.title,
+      isRoot: false,
+      isComponent: false,
+      isLeaf: true,
+    } as DocsEntry | StoryEntry;
 
     return acc;
   }, {} as StoriesHash);
 
-  function addItem(acc: StoriesHash, item: Story | Group) {
-    if (!acc[item.id]) {
-      // If we were already inserted as part of a group, that's great.
-      acc[item.id] = item;
-      const { children } = item;
-      if (children) {
-        const childNodes = children.map((id) => storiesHashOutOfOrder[id]) as (Story | Group)[];
-        if (childNodes.every((childNode) => childNode.isLeaf)) {
-          acc[item.id].isComponent = true;
-          acc[item.id].type = 'component';
-        }
-        childNodes.forEach((childNode) => addItem(acc, childNode));
-      }
+  // This function adds a "root" or "orphan" and all of its descendents to the hash.
+  function addItem(acc: StoriesHash, item: HashEntry) {
+    // If we were already inserted as part of a group, that's great.
+    if (acc[item.id]) {
+      return acc;
+    }
+
+    acc[item.id] = item;
+    // Ensure we add the children depth-first *before* inserting any other entries
+    if (item.type === 'root' || item.type === 'group' || item.type === 'component') {
+      item.children.forEach((childId) => addItem(acc, storiesHashOutOfOrder[childId]));
     }
     return acc;
   }
 
-  return Object.values(storiesHashOutOfOrder).reduce(addItem, {});
+  // We'll do two passes over the data, adding all the orphans, then all the roots
+  const orphanHash = Object.values(storiesHashOutOfOrder)
+    .filter((i) => i.type !== 'root' && !i.parent)
+    .reduce(addItem, {});
+
+  return Object.values(storiesHashOutOfOrder)
+    .filter((i) => i.type === 'root')
+    .reduce(addItem, orphanHash);
 };
 
-export type Item = StoriesHash[keyof StoriesHash];
-
-export function isRoot(item: Item): item is Root {
-  if (item as Root) {
-    return item.isRoot;
-  }
-  return false;
-}
-export function isGroup(item: Item): item is Group {
-  if (item as Group) {
-    return !item.isRoot && !item.isLeaf;
-  }
-  return false;
-}
-export function isStory(item: Item): item is Story {
-  if (item as Story) {
-    return item.isLeaf;
-  }
-  return false;
-}
-
 export const getComponentLookupList = memoize(1)((hash: StoriesHash) => {
   return Object.entries(hash).reduce((acc, i) => {
     const value = i[1];
-    if (value.isComponent) {
-      acc.push([...i[1].children]);
+    if (value.type === 'component') {
+      acc.push([...value.children]);
     }
     return acc;
   }, [] as StoryId[][]);
 });
 
 export const getStoriesLookupList = memoize(1)((hash: StoriesHash) => {
-  return Object.keys(hash).filter((k) => !(hash[k].children || Array.isArray(hash[k])));
+  return Object.keys(hash).filter((k) => ['story', 'docs'].includes(hash[k].type));
 });

lib/api/src/modules/addons.ts

@@ -3,9 +3,8 @@ import type { RenderData } from '@storybook/router';
 import deprecate from 'util-deprecate';
 import dedent from 'ts-dedent';
 
-import type { ModuleFn } from '../index';
-import type { Options } from '../store';
-import { isStory } from '../lib/stories';
+import { ModuleFn } from '../index';
+import { Options } from '../store';
 
 const warnDisabledDeprecated = deprecate(
   () => {},
@@ -64,10 +63,9 @@ type Panels = Collection<Addon>;
 
 type StateMerger<S> = (input: S) => S;
 
-interface StoryInput {
-  parameters: {
-    [parameterName: string]: any;
-  };
+export interface SubState {
+  selectedPanel: string;
+  addons: Record<string, never>;
 }
 
 export interface SubAPI {
@@ -97,7 +95,7 @@ export function ensurePanel(panels: Panels, selectedPanel?: string, currentPanel
   return currentPanel;
 }
 
-export const init: ModuleFn = ({ provider, store, fullAPI }) => {
+export const init: ModuleFn<SubAPI, SubState> = ({ provider, store, fullAPI }) => {
   const api: SubAPI = {
     getElements: (type) => provider.getElements(type),
     getPanels: () => api.getElements(types.PANEL),
@@ -106,7 +104,7 @@ export const init: ModuleFn = ({ provider, store, fullAPI }) => {
       const { storyId } = store.getState();
       const story = fullAPI.getData(storyId);
 
-      if (!allPanels || !story || !isStory(story)) {
+      if (!allPanels || !story || story.type !== 'story') {
         return allPanels;
       }
 

lib/api/src/modules/channel.ts

@@ -14,7 +14,9 @@ export interface SubAPI {
   expandAll: () => void;
 }
 
-export const init: ModuleFn = ({ provider }) => {
+export type SubState = Record<string, never>;
+
+export const init: ModuleFn<SubAPI, SubState> = ({ provider }) => {
   const api: SubAPI = {
     getChannel: () => provider.channel,
     on: (type, cb) => {
@@ -33,5 +35,5 @@ export const init: ModuleFn = ({ provider }) => {
       api.emit(STORIES_EXPAND_ALL);
     },
   };
-  return { api };
+  return { api, state: {} };
 };

lib/api/src/modules/provider.ts

@@ -2,14 +2,14 @@ import type { ReactNode } from 'react';
 import { Channel } from '@storybook/channels';
 import type { ThemeVars } from '@storybook/theming';
 
-import type { API, State, ModuleFn, Root, Group, Story } from '../index';
+import type { API, State, ModuleFn, HashEntry } from '../index';
 import type { StoryMapper, Refs } from './refs';
 import type { UIOptions } from './layout';
 
 interface SidebarOptions {
   showRoots?: boolean;
   collapsedRoots?: string[];
-  renderLabel?: (item: Root | Group | Story) => ReactNode;
+  renderLabel?: (item: HashEntry) => ReactNode;
 }
 
 type IframeRenderer = (
@@ -40,9 +40,10 @@ export interface SubAPI {
   renderPreview?: Provider['renderPreview'];
 }
 
-export const init: ModuleFn = ({ provider, fullAPI }) => {
+export const init: ModuleFn<SubAPI, {}, true> = ({ provider, fullAPI }) => {
   return {
     api: provider.renderPreview ? { renderPreview: provider.renderPreview } : {},
+    state: {},
     init: () => {
       provider.handleAPI(fullAPI);
     },

lib/api/src/modules/refs.ts

@@ -1,15 +1,15 @@
 import global from 'global';
 import dedent from 'ts-dedent';
 import {
-  transformStoriesRawToStoriesHash,
-  StoriesRaw,
-  StoryInput,
+  transformSetStoriesStoryDataToStoriesHash,
+  SetStoriesStory,
   StoriesHash,
   transformStoryIndexToStoriesHash,
-  StoryIndexStory,
+  SetStoriesStoryData,
+  StoryIndex,
 } from '../lib/stories';
 
-import type { ModuleFn, StoryId } from '../index';
+import type { ModuleFn } from '../index';
 
 const { location, fetch } = global;
 
@@ -20,9 +20,9 @@ export interface SubState {
 type Versions = Record<string, string>;
 
 export type SetRefData = Partial<
-  Omit<ComposedRef, 'stories'> & {
-    v: number;
-    stories?: StoriesRaw;
+  ComposedRef & {
+    setStoriesData: SetStoriesStoryData;
+    storyIndex: StoryIndex;
   }
 >;
 
@@ -36,7 +36,7 @@ export interface SubAPI {
   changeRefState: (id: string, ready: boolean) => void;
 }
 
-export type StoryMapper = (ref: ComposedRef, story: StoryInput) => StoryInput;
+export type StoryMapper = (ref: ComposedRef, story: SetStoriesStory) => SetStoriesStory;
 export interface ComposedRef {
   id: string;
   title?: string;
@@ -99,30 +99,43 @@ const addRefIds = (input: StoriesHash, ref: ComposedRef): StoriesHash => {
   }, {} as StoriesHash);
 };
 
-const handle = async (request: Response | false): Promise<SetRefData> => {
-  if (request) {
-    return Promise.resolve(request)
-      .then((response) => (response.ok ? response.json() : {}))
-      .catch((error) => ({ error }));
+async function handleRequest(request: Response | false): Promise<SetRefData> {
+  if (!request) return {};
+
+  try {
+    const response = await request;
+    if (!response.ok) return {};
+
+    const json = await response.json();
+
+    if (json.entries || json.stories) {
+      return { storyIndex: json };
+    }
+
+    return json as SetRefData;
+  } catch (error) {
+    return { error };
   }
-  return {};
-};
+}
 
 const map = (
-  input: StoriesRaw,
+  input: SetStoriesStoryData,
   ref: ComposedRef,
   options: { storyMapper?: StoryMapper }
-): StoriesRaw => {
+): SetStoriesStoryData => {
   const { storyMapper } = options;
   if (storyMapper) {
     return Object.entries(input).reduce((acc, [id, item]) => {
       return { ...acc, [id]: storyMapper(ref, item) };
-    }, {} as StoriesRaw);
+    }, {} as SetStoriesStoryData);
   }
   return input;
 };
 
-export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = true } = {}) => {
+export const init: ModuleFn<SubAPI, SubState, void> = (
+  { store, provider, singleStory },
+  { runCheck = true } = {}
+) => {
   const api: SubAPI = {
     findRef: (source) => {
       const refs = api.getRefs();
@@ -164,18 +177,34 @@ export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = tr
       const query = version ? `?version=${version}` : '';
       const credentials = isPublic ? 'omit' : 'include';
 
-      // In theory the `/iframe.html` could be private and the `stories.json` could not exist, but in practice
-      // the only private servers we know about (Chromatic) always include `stories.json`. So we can tell
-      // if the ref actually exists by simply checking `stories.json` w/ credentials.
+      const [indexFetch, storiesFetch] = await Promise.all(
+        ['index.json', 'stories.json'].map(async (file) =>
+          fetch(`${url}/${file}${query}`, {
+            headers: { Accept: 'application/json' },
+            credentials,
+          })
+        )
+      );
 
-      const storiesFetch = await fetch(`${url}/stories.json${query}`, {
-        headers: {
-          Accept: 'application/json',
-        },
-        credentials,
-      });
+      if (indexFetch.ok || storiesFetch.ok) {
+        const [index, metadata] = await Promise.all([
+          indexFetch.ok ? handleRequest(indexFetch) : handleRequest(storiesFetch),
+          handleRequest(
+            fetch(`${url}/metadata.json${query}`, {
+              headers: {
+                Accept: 'application/json',
+              },
+              credentials,
+              cache: 'no-cache',
+            }).catch(() => false)
+          ),
+        ]);
 
-      if (!storiesFetch.ok && !isPublic) {
+        Object.assign(loadedData, { ...index, ...metadata });
+      } else if (!isPublic) {
+        // In theory the `/iframe.html` could be private and the `stories.json` could not exist, but in practice
+        // the only private servers we know about (Chromatic) always include `stories.json`. So we can tell
+        // if the ref actually exists by simply checking `stories.json` w/ credentials.
         loadedData.error = {
           message: dedent`
             Error: Loading of ref failed
@@ -189,21 +218,6 @@ export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = tr
             Please check your dev-tools network tab.
           `,
         } as Error;
-      } else if (storiesFetch.ok) {
-        const [stories, metadata] = await Promise.all([
-          handle(storiesFetch),
-          handle(
-            fetch(`${url}/metadata.json${query}`, {
-              headers: {
-                Accept: 'application/json',
-              },
-              credentials,
-              cache: 'no-cache',
-            }).catch(() => false)
-          ),
-        ]);
-
-        Object.assign(loadedData, { ...stories, ...metadata });
       }
 
       const versions =
@@ -214,8 +228,7 @@ export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = tr
         url,
         ...loadedData,
         ...(versions ? { versions } : {}),
-        error: loadedData.error,
-        type: !loadedData.stories ? 'auto-inject' : 'lazy',
+        type: !loadedData.storyIndex ? 'auto-inject' : 'lazy',
       });
     },
 
@@ -225,26 +238,23 @@ export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = tr
       return refs;
     },
 
-    setRef: (id, { stories, v, ...rest }, ready = false) => {
+    setRef: (id, { storyIndex, setStoriesData, ...rest }, ready = false) => {
       if (singleStory) return;
       const { storyMapper = defaultStoryMapper } = provider.getConfig();
       const ref = api.getRefs()[id];
 
       let storiesHash: StoriesHash;
-
-      if (stories) {
-        if (v === 2) {
-          storiesHash = transformStoriesRawToStoriesHash(map(stories, ref, { storyMapper }), {
+      if (setStoriesData) {
+        storiesHash = transformSetStoriesStoryDataToStoriesHash(
+          map(setStoriesData, ref, { storyMapper }),
+          {
             provider,
-          });
-        } else if (!v) {
-          throw new Error('Composition: Missing stories.json version');
-        } else {
-          const index = stories as unknown as Record<StoryId, StoryIndexStory>;
-          storiesHash = transformStoryIndexToStoriesHash({ v, stories: index }, { provider });
-        }
-        storiesHash = addRefIds(storiesHash, ref);
+          }
+        );
+      } else if (storyIndex) {
+        storiesHash = transformStoryIndexToStoriesHash(storyIndex, { provider });
       }
+      if (storiesHash) storiesHash = addRefIds(storiesHash, ref);
 
       api.updateRef(id, { stories: storiesHash, ...rest, ready });
     },
@@ -272,8 +282,8 @@ export const init: ModuleFn = ({ store, provider, singleStory }, { runCheck = tr
   const initialState: SubState['refs'] = refs;
 
   if (runCheck) {
-    Object.entries(refs).forEach(([k, v]) => {
-      api.checkRef(v as SetRefData);
+    Object.entries(refs).forEach(([id, ref]) => {
+      api.checkRef({ ...ref, stories: {} } as SetRefData);
     });
   }
 

lib/api/src/modules/release-notes.ts

@@ -29,7 +29,7 @@ export interface SubState {
   releaseNotesViewed: string[];
 }
 
-export const init: ModuleFn = ({ store }) => {
+export const init: ModuleFn<SubAPI, SubState> = ({ store }) => {
   const releaseNotesData = getReleaseNotesData();
   const getReleaseNotesViewed = () => {
     const { releaseNotesViewed: persistedReleaseNotesViewed } = store.getState();
@@ -58,7 +58,5 @@ export const init: ModuleFn = ({ store }) => {
     },
   };
 
-  const initModule = () => {};
-
-  return { init: initModule, api };
+  return { state: { releaseNotesViewed: [] }, api };
 };

lib/api/src/modules/settings.ts

@@ -15,7 +15,7 @@ export interface SubState {
   settings: Settings;
 }
 
-export const init: ModuleFn = ({ store, navigate, fullAPI }) => {
+export const init: ModuleFn<SubAPI, SubState> = ({ store, navigate, fullAPI }) => {
   const isSettingsScreenActive = () => {
     const { path } = fullAPI.getUrlState();
     return !!(path || '').match(/^\/settings/);
@@ -49,9 +49,5 @@ export const init: ModuleFn = ({ store, navigate, fullAPI }) => {
     },
   };
 
-  const initModule = async () => {
-    await store.setState({ settings: { lastTrackedStoryId: null } });
-  };
-
-  return { init: initModule, api };
+  return { state: { settings: { lastTrackedStoryId: null } }, api };
 };

lib/api/src/modules/stories.ts

@@ -19,21 +19,19 @@ import { logger } from '@storybook/client-logger';
 import { getEventMetadata } from '../lib/events';
 import {
   denormalizeStoryParameters,
-  transformStoriesRawToStoriesHash,
-  isStory,
-  isRoot,
+  transformSetStoriesStoryDataToStoriesHash,
   transformStoryIndexToStoriesHash,
   getComponentLookupList,
   getStoriesLookupList,
+  HashEntry,
+  DocsEntry,
 } from '../lib/stories';
 
 import type {
   StoriesHash,
-  Story,
-  Group,
+  StoryEntry,
   StoryId,
-  Root,
-  StoriesRaw,
+  SetStoriesStoryData,
   SetStoriesPayload,
   StoryIndex,
 } from '../lib/stories';
@@ -42,13 +40,13 @@ import type { Args, ModuleFn } from '../index';
 import type { ComposedRef } from './refs';
 
 const { DOCS_MODE, FEATURES, fetch } = global;
-const STORY_INDEX_PATH = './stories.json';
+const STORY_INDEX_PATH = './index.json';
 
 type Direction = -1 | 1;
 type ParameterName = string;
 
 type ViewMode = 'story' | 'info' | 'settings' | string | undefined;
-type StoryUpdate = Pick<Story, 'parameters' | 'initialArgs' | 'argTypes' | 'args'>;
+type StoryUpdate = Pick<StoryEntry, 'parameters' | 'initialArgs' | 'argTypes' | 'args'>;
 
 export interface SubState {
   storiesHash: StoriesHash;
@@ -60,26 +58,27 @@ export interface SubState {
 
 export interface SubAPI {
   storyId: typeof toId;
-  resolveStory: (storyId: StoryId, refsId?: string) => Story | Group | Root;
+  resolveStory: (storyId: StoryId, refsId?: string) => HashEntry;
   selectFirstStory: () => void;
   selectStory: (
-    kindOrId: string,
+    kindOrId?: string,
     story?: string,
     obj?: { ref?: string; viewMode?: ViewMode }
   ) => void;
-  getCurrentStoryData: () => Story | Group;
-  setStories: (stories: StoriesRaw, failed?: Error) => Promise<void>;
+  getCurrentStoryData: () => DocsEntry | StoryEntry;
+  setStories: (stories: SetStoriesStoryData, failed?: Error) => Promise<void>;
   jumpToComponent: (direction: Direction) => void;
   jumpToStory: (direction: Direction) => void;
-  getData: (storyId: StoryId, refId?: string) => Story | Group;
+  getData: (storyId: StoryId, refId?: string) => DocsEntry | StoryEntry;
   isPrepared: (storyId: StoryId, refId?: string) => boolean;
   getParameters: (
     storyId: StoryId | { storyId: StoryId; refId: string },
     parameterName?: ParameterName
-  ) => Story['parameters'] | any;
+  ) => StoryEntry['parameters'] | any;
   getCurrentParameter<S>(parameterName?: ParameterName): S;
-  updateStoryArgs(story: Story, newArgs: Args): void;
-  resetStoryArgs: (story: Story, argNames?: string[]) => void;
+  updateStoryArgs(story: StoryEntry, newArgs: Args): void;
+  resetStoryArgs: (story: StoryEntry, argNames?: string[]) => void;
+  findLeafEntry(StoriesHash: StoriesHash, storyId: StoryId): DocsEntry | StoryEntry;
   findLeafStoryId(StoriesHash: StoriesHash, storyId: StoryId): StoryId;
   findSiblingStoryId(
     storyId: StoryId,
@@ -92,16 +91,6 @@ export interface SubAPI {
   updateStory: (storyId: StoryId, update: StoryUpdate, ref?: ComposedRef) => Promise<void>;
 }
 
-interface Meta {
-  ref?: ComposedRef;
-  source?: string;
-  sourceType?: 'local' | 'external';
-  sourceLocation?: string;
-  refId?: string;
-  v?: number;
-  type: string;
-}
-
 const deprecatedOptionsParameterWarnings: Record<string, () => void> = [
   'enableShortcuts',
   'theme',
@@ -126,7 +115,7 @@ function checkDeprecatedOptionParameters(options?: Record<string, any>) {
   });
 }
 
-export const init: ModuleFn = ({
+export const init: ModuleFn<SubAPI, SubState, true> = ({
   fullAPI,
   store,
   navigate,
@@ -138,16 +127,14 @@ export const init: ModuleFn = ({
     storyId: toId,
     getData: (storyId, refId) => {
       const result = api.resolveStory(storyId, refId);
-
-      return isRoot(result) ? undefined : result;
+      if (result?.type === 'story' || result?.type === 'docs') {
+        return result;
+      }
+      return undefined;
     },
     isPrepared: (storyId, refId) => {
       const data = api.getData(storyId, refId);
-      if (data.isLeaf) {
-        return data.prepared;
-      }
-      // Groups are always prepared :shrug:
-      return true;
+      return data.type === 'story' ? data.prepared : true;
     },
     resolveStory: (storyId, refId) => {
       const { refs, storiesHash } = store.getState();
@@ -168,7 +155,7 @@ export const init: ModuleFn = ({
           : storyIdOrCombo;
       const data = api.getData(storyId, refId);
 
-      if (isStory(data)) {
+      if (data?.type === 'story') {
         const { parameters } = data;
 
         if (parameters) {
@@ -226,7 +213,7 @@ export const init: ModuleFn = ({
     },
     setStories: async (input, error) => {
       // Now create storiesHash by reordering the above by group
-      const hash = transformStoriesRawToStoriesHash(input, {
+      const hash = transformSetStoriesStoryDataToStoriesHash(input, {
         provider,
       });
 
@@ -238,9 +225,7 @@ export const init: ModuleFn = ({
     },
     selectFirstStory: () => {
       const { storiesHash } = store.getState();
-      const firstStory = Object.keys(storiesHash).find(
-        (k) => !(storiesHash[k].children || Array.isArray(storiesHash[k]))
-      );
+      const firstStory = Object.keys(storiesHash).find((id) => storiesHash[id].type === 'story');
 
       if (firstStory) {
         api.selectStory(firstStory);
@@ -249,7 +234,7 @@ export const init: ModuleFn = ({
 
       navigate('/');
     },
-    selectStory: (kindOrId = undefined, story = undefined, options = {}) => {
+    selectStory: (titleOrId = undefined, name = undefined, options = {}) => {
       const { ref, viewMode: viewModeFromArgs } = options;
       const {
         viewMode: viewModeFromState = 'story',
@@ -262,38 +247,51 @@ export const init: ModuleFn = ({
 
       const kindSlug = storyId?.split('--', 2)[0];
 
-      if (!story) {
-        const s = kindOrId ? hash[kindOrId] || hash[sanitize(kindOrId)] : hash[kindSlug];
-        // eslint-disable-next-line no-nested-ternary
-        const id = s ? (s.children ? s.children[0] : s.id) : kindOrId;
-        let viewMode =
-          s && !isRoot(s) && (viewModeFromArgs || s.parameters.viewMode)
-            ? s.parameters.viewMode
-            : viewModeFromState;
+      if (!name) {
+        // Find the entry (group, component or story) that is referred to
+        const entry = titleOrId ? hash[titleOrId] || hash[sanitize(titleOrId)] : hash[kindSlug];
 
-        // Some viewModes are not story-specific, and we should reset viewMode
-        //  to 'story' if one of those is active when navigating to another story
-        if (['settings', 'about', 'release'].includes(viewMode)) {
-          viewMode = 'story';
+        if (!entry) throw new Error(`Unknown id or title: '${titleOrId}'`);
+
+        // We want to navigate to the first ancestor entry that is a leaf
+        const leafEntry = api.findLeafEntry(hash, entry.id);
+
+        // We would default to the viewMode passed in or maintain the current
+        const desiredViewMode = viewModeFromArgs || viewModeFromState;
+
+        // By default we would render a story as a story
+        let viewMode = 'story';
+        // However, any story can be rendered as docs if required
+        if (desiredViewMode === 'docs') {
+          viewMode = 'docs';
         }
 
-        const p = s && s.refId ? `/${viewMode}/${s.refId}_${id}` : `/${viewMode}/${id}`;
+        // NOTE -- we currently still render docs entries in story view mode,
+        // (even though in the preview they will appear in docs mode)
+        // in order to maintain the viewMode as you browse around.
+        // This will change later.
 
-        navigate(p);
-      } else if (!kindOrId) {
+        // On the other hand, docs entries can *only* be rendered as docs
+        // if (leafEntry.type === 'docs') {
+        //   viewMode = 'docs';
+        // }
+
+        const fullId = leafEntry.refId ? `${leafEntry.refId}_${leafEntry.id}` : leafEntry.id;
+        navigate(`/${viewMode}/${fullId}`);
+      } else if (!titleOrId) {
         // This is a slugified version of the kind, but that's OK, our toId function is idempotent
-        const id = toId(kindSlug, story);
+        const id = toId(kindSlug, name);
 
         api.selectStory(id, undefined, options);
       } else {
-        const id = ref ? `${ref}_${toId(kindOrId, story)}` : toId(kindOrId, story);
+        const id = ref ? `${ref}_${toId(titleOrId, name)}` : toId(titleOrId, name);
         if (hash[id]) {
           api.selectStory(id, undefined, options);
         } else {
           // Support legacy API with component permalinks, where kind is `x/y` but permalink is 'z'
-          const k = hash[sanitize(kindOrId)];
-          if (k && k.children) {
-            const foundId = k.children.find((childId) => hash[childId].name === story);
+          const entry = hash[sanitize(titleOrId)];
+          if (entry?.type === 'component') {
+            const foundId = entry.children.find((childId) => hash[childId].name === name);
             if (foundId) {
               api.selectStory(foundId, undefined, options);
             }
@@ -301,13 +299,17 @@ export const init: ModuleFn = ({
         }
       }
     },
-    findLeafStoryId(storiesHash, storyId) {
-      if (storiesHash[storyId].isLeaf) {
-        return storyId;
+    findLeafEntry(storiesHash, storyId) {
+      const entry = storiesHash[storyId];
+      if (entry.type === 'docs' || entry.type === 'story') {
+        return entry;
       }
 
-      const childStoryId = storiesHash[storyId].children[0];
-      return api.findLeafStoryId(storiesHash, childStoryId);
+      const childStoryId = entry.children[0];
+      return api.findLeafEntry(storiesHash, childStoryId);
+    },
+    findLeafStoryId(storiesHash, storyId) {
+      return api.findLeafEntry(storiesHash, storyId)?.id;
     },
     findSiblingStoryId(storyId, hash, direction, toSiblingGroup) {
       if (toSiblingGroup) {
@@ -370,7 +372,7 @@ export const init: ModuleFn = ({
         const storyIndex = (await result.json()) as StoryIndex;
 
         // We can only do this if the stories.json is a proper storyIndex
-        if (storyIndex.v !== 3) {
+        if (storyIndex.v < 3) {
           logger.warn(`Skipping story index with version v${storyIndex.v}, awaiting SET_STORIES.`);
           return;
         }
@@ -404,14 +406,14 @@ export const init: ModuleFn = ({
         storiesHash[storyId] = {
           ...storiesHash[storyId],
           ...update,
-        } as Story;
+        } as StoryEntry;
         await store.setState({ storiesHash });
       } else {
         const { id: refId, stories } = ref;
         stories[storyId] = {
           ...stories[storyId],
           ...update,
-        } as Story;
+        } as StoryEntry;
         await fullAPI.updateRef(refId, { stories });
       }
     },
@@ -490,19 +492,19 @@ export const init: ModuleFn = ({
 
     fullAPI.on(SET_STORIES, function handler(data: SetStoriesPayload) {
       const { ref } = getEventMetadata(this, fullAPI);
-      const stories = data.v ? denormalizeStoryParameters(data) : data.stories;
+      const setStoriesData = data.v ? denormalizeStoryParameters(data) : data.stories;
 
       if (!ref) {
         if (!data.v) {
           throw new Error('Unexpected legacy SET_STORIES event from local source');
         }
 
-        fullAPI.setStories(stories);
+        fullAPI.setStories(setStoriesData);
         const options = fullAPI.getCurrentParameter('options');
         checkDeprecatedOptionParameters(options);
         fullAPI.setOptions(options);
       } else {
-        fullAPI.setRef(ref.id, { ...ref, ...data, stories }, true);
+        fullAPI.setRef(ref.id, { ...ref, setStoriesData }, true);
       }
     });
 

lib/api/src/modules/url.ts

@@ -13,9 +13,8 @@ import deepEqual from 'fast-deep-equal';
 import global from 'global';
 import dedent from 'ts-dedent';
 
-import type { ModuleArgs, ModuleFn } from '../index';
-import type { Layout, UI } from './layout';
-import { isStory } from '../lib/stories';
+import { ModuleArgs, ModuleFn } from '../index';
+import { Layout, UI } from './layout';
 
 const { window: globalWindow } = global;
 
@@ -184,7 +183,7 @@ export const init: ModuleFn = ({ store, navigate, state, provider, fullAPI, ...r
       if (viewMode !== 'story') return;
 
       const currentStory = fullAPI.getCurrentStoryData();
-      if (!isStory(currentStory)) return;
+      if (currentStory?.type !== 'story') return;
 
       const { args, initialArgs } = currentStory;
       const argsString = buildArgsParam(initialArgs, args);

lib/api/src/tests/addons.test.js

@@ -75,7 +75,7 @@ describe('Addons API', () => {
       const storyId = 'story 1';
       const storiesHash = {
         [storyId]: {
-          isLeaf: true,
+          type: 'story',
           parameters: {
             a11y: { disable: true },
           },

lib/api/src/tests/refs.test.js

@@ -50,51 +50,55 @@ const store = {
   setState: jest.fn(() => {}),
 };
 
-const emptyResponse = Promise.resolve({
-  ok: true,
-  json: async () => ({}),
-});
-
-const setupResponses = (
-  a = emptyResponse,
-  b = emptyResponse,
-  c = emptyResponse,
-  d = emptyResponse
-) => {
+const setupResponses = ({
+  indexPrivate,
+  indexPublic,
+  storiesPrivate,
+  storiesPublic,
+  iframe,
+  metadata,
+}) => {
   fetch.mockClear();
   store.setState.mockClear();
 
   fetch.mockImplementation((l, o) => {
-    if (l.includes('stories') && o.credentials === 'omit') {
+    if (l.includes('index') && o.credentials === 'include' && indexPrivate) {
       return Promise.resolve({
-        ok: a.ok,
-        json: a.response,
+        ok: indexPrivate.ok,
+        json: indexPrivate.response,
       });
     }
-    if (l.includes('stories') && o.credentials === 'include') {
+    if (l.includes('index') && o.credentials === 'omit' && indexPublic) {
       return Promise.resolve({
-        ok: b.ok,
-        json: b.response,
+        ok: indexPublic.ok,
+        json: indexPublic.response,
       });
     }
-    if (l.includes('iframe')) {
+    if (l.includes('stories') && o.credentials === 'include' && storiesPrivate) {
       return Promise.resolve({
-        ok: c.ok,
-        json: c.response,
+        ok: storiesPrivate.ok,
+        json: storiesPrivate.response,
       });
     }
-    if (l.includes('metadata')) {
+    if (l.includes('stories') && o.credentials === 'omit' && storiesPublic) {
       return Promise.resolve({
-        ok: d.ok,
-        json: d.response,
+        ok: storiesPublic.ok,
+        json: storiesPublic.response,
       });
     }
-    return Promise.resolve({
-      ok: false,
-      json: () => {
-        throw new Error('not ok');
-      },
-    });
+    if (l.includes('iframe') && iframe) {
+      return Promise.resolve({
+        ok: iframe.ok,
+        json: iframe.response,
+      });
+    }
+    if (l.includes('metadata') && metadata) {
+      return Promise.resolve({
+        ok: metadata.ok,
+        json: metadata.response,
+      });
+    }
+    throw new Error(`Called URL ${l} without setting up mock`);
   });
 };
 
@@ -139,6 +143,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -168,6 +181,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json?version=2.1.3-rc.2",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json?version=2.1.3-rc.2",
             Object {
@@ -185,26 +207,20 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
+      setupResponses({
+        indexPrivate: {
           ok: false,
           response: async () => {
             throw new Error('Failed to fetch');
           },
         },
-        {
+        storiesPrivate: {
           ok: false,
           response: async () => {
             throw new Error('Failed to fetch');
           },
         },
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        }
-      );
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -214,6 +230,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -257,28 +282,22 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
+      setupResponses({
+        indexPrivate: {
           ok: true,
-          response: async () => ({ v: 2, stories: {} }),
+          response: async () => ({ v: 4, entries: {} }),
         },
-        {
+        storiesPrivate: {
           ok: true,
           response: async () => ({ v: 3, stories: {} }),
         },
-        {
-          ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        },
-        {
+        metadata: {
           ok: true,
           response: async () => ({
             versions: {},
           }),
-        }
-      );
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -288,6 +307,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -314,7 +342,6 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": undefined,
               "id": "fake",
               "ready": false,
               "stories": Object {},
@@ -332,28 +359,22 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
+      setupResponses({
+        indexPrivate: {
           ok: true,
-          response: async () => ({ v: 2, stories: {} }),
+          response: async () => ({ v: 4, entries: {} }),
         },
-        {
+        storiesPrivate: {
           ok: true,
           response: async () => ({ v: 3, stories: {} }),
         },
-        {
-          ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        },
-        {
+        metadata: {
           ok: true,
           response: async () => ({
             versions: {},
           }),
-        }
-      );
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -364,6 +385,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -390,7 +420,6 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": undefined,
               "id": "fake",
               "ready": false,
               "stories": Object {},
@@ -411,30 +440,20 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
+      setupResponses({
+        indexPrivate: {
           ok: true,
           response: async () => ({ loginUrl: 'https://example.com/login' }),
         },
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        },
-        {
+        storiesPrivate: {
           ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
+          response: async () => ({ loginUrl: 'https://example.com/login' }),
         },
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        }
-      );
+        metadata: {
+          ok: true,
+          response: async () => ({ loginUrl: 'https://example.com/login' }),
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -444,6 +463,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -453,6 +481,16 @@ describe('Refs API', () => {
               },
             },
           ],
+          Array [
+            "https://example.com/metadata.json",
+            Object {
+              "cache": "no-cache",
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
         ]
       `);
 
@@ -460,18 +498,8 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": Object {
-                "message": "Error: Loading of ref failed
-          at fetch (lib/api/src/modules/refs.ts)
-
-        URL: https://example.com
-
-        We weren't able to load the above URL,
-        it's possible a CORS error happened.
-
-        Please check your dev-tools network tab.",
-              },
               "id": "fake",
+              "loginUrl": "https://example.com/login",
               "ready": false,
               "stories": undefined,
               "title": "Fake",
@@ -490,28 +518,22 @@ describe('Refs API', () => {
       fetch.mockClear();
       store.setState.mockClear();
 
-      setupResponses(
-        {
+      setupResponses({
+        indexPrivate: {
           ok: true,
           response: async () => ({ loginUrl: 'https://example.com/login' }),
         },
-        {
+        storiesPrivate: {
           ok: true,
-          response: async () => ({ v: 2, stories: {} }),
+          response: async () => ({ loginUrl: 'https://example.com/login' }),
         },
-        {
-          ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
-        },
-        {
+        metadata: {
           ok: true,
           response: async () => ({
             versions: { '1.0.0': 'https://example.com/v1', '2.0.0': 'https://example.com' },
           }),
-        }
-      );
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -521,6 +543,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -547,12 +578,12 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": undefined,
               "id": "fake",
+              "loginUrl": "https://example.com/login",
               "ready": false,
-              "stories": Object {},
+              "stories": undefined,
               "title": "Fake",
-              "type": "lazy",
+              "type": "auto-inject",
               "url": "https://example.com",
               "versions": Object {
                 "1.0.0": "https://example.com/v1",
@@ -568,26 +599,22 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('Failed to fetch');
-          },
-        },
-        {
+      setupResponses({
+        indexPublic: {
           ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
+          response: async () => ({ v: 4, entries: {} }),
         },
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('Failed to fetch');
-          },
-        }
-      );
+        storiesPublic: {
+          ok: true,
+          response: async () => ({ v: 3, stories: {} }),
+        },
+        metadata: {
+          ok: true,
+          response: async () => ({
+            versions: {},
+          }),
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -598,6 +625,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "omit",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -607,6 +643,16 @@ describe('Refs API', () => {
               },
             },
           ],
+          Array [
+            "https://example.com/metadata.json",
+            Object {
+              "cache": "no-cache",
+              "credentials": "omit",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
         ]
       `);
 
@@ -614,13 +660,13 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": undefined,
               "id": "fake",
               "ready": false,
-              "stories": undefined,
+              "stories": Object {},
               "title": "Fake",
-              "type": "auto-inject",
+              "type": "lazy",
               "url": "https://example.com",
+              "versions": Object {},
             },
           },
         }
@@ -631,26 +677,22 @@ describe('Refs API', () => {
       // given
       const { api } = initRefs({ provider, store }, { runCheck: false });
 
-      setupResponses(
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('Failed to fetch');
-          },
-        },
-        {
+      setupResponses({
+        indexPrivate: {
           ok: true,
-          response: async () => {
-            throw new Error('not ok');
-          },
+          response: async () => ({ v: 4, entries: {} }),
         },
-        {
-          ok: false,
-          response: async () => {
-            throw new Error('Failed to fetch');
-          },
-        }
-      );
+        storiesPrivate: {
+          ok: true,
+          response: async () => ({ v: 3, stories: {} }),
+        },
+        metadata: {
+          ok: true,
+          response: async () => ({
+            versions: {},
+          }),
+        },
+      });
 
       await api.checkRef({
         id: 'fake',
@@ -661,6 +703,15 @@ describe('Refs API', () => {
 
       expect(fetch.mock.calls).toMatchInlineSnapshot(`
         Array [
+          Array [
+            "https://example.com/index.json",
+            Object {
+              "credentials": "include",
+              "headers": Object {
+                "Accept": "application/json",
+              },
+            },
+          ],
           Array [
             "https://example.com/stories.json",
             Object {
@@ -687,46 +738,159 @@ describe('Refs API', () => {
         Object {
           "refs": Object {
             "fake": Object {
-              "error": [Error: not ok],
               "id": "fake",
               "ready": false,
-              "stories": undefined,
+              "stories": Object {},
               "title": "Fake",
-              "type": "auto-inject",
+              "type": "lazy",
               "url": "https://example.com",
+              "versions": Object {},
             },
           },
         }
       `);
     });
+
+    describe('v3 compatibility', () => {
+      it('infers docs only if there is only one story and it has the name "Page"', async () => {
+        // given
+        const { api } = initRefs({ provider, store }, { runCheck: false });
+
+        const index = {
+          v: 3,
+          stories: {
+            'component-a--page': {
+              id: 'component-a--page',
+              title: 'Component A',
+              name: 'Page', // Called "Page" but not only story
+              importPath: './path/to/component-a.ts',
+            },
+            'component-a--story-2': {
+              id: 'component-a--story-2',
+              title: 'Component A',
+              name: 'Story 2',
+              importPath: './path/to/component-a.ts',
+            },
+            'component-b--page': {
+              id: 'component-b--page',
+              title: 'Component B',
+              name: 'Page', // Page and only story
+              importPath: './path/to/component-b.ts',
+            },
+            'component-c--story-4': {
+              id: 'component-c--story-4',
+              title: 'Component c',
+              name: 'Story 4', // Only story but not page
+              importPath: './path/to/component-c.ts',
+            },
+          },
+        };
+
+        setupResponses({
+          indexPrivate: { ok: false },
+          storiesPrivate: {
+            ok: true,
+            response: async () => index,
+          },
+          metadata: {
+            ok: true,
+            response: async () => ({
+              versions: {},
+            }),
+          },
+        });
+
+        await api.checkRef({
+          id: 'fake',
+          url: 'https://example.com',
+          title: 'Fake',
+        });
+
+        const { refs } = store.setState.mock.calls[0][0];
+        const hash = refs.fake.stories;
+
+        // We need exact key ordering, even if in theory JS doesn't guarantee it
+        expect(Object.keys(hash)).toEqual([
+          'component-a',
+          'component-a--page',
+          'component-a--story-2',
+          'component-b',
+          'component-b--page',
+          'component-c',
+          'component-c--story-4',
+        ]);
+        expect(hash['component-a--page'].type).toBe('story');
+        expect(hash['component-a--story-2'].type).toBe('story');
+        expect(hash['component-b--page'].type).toBe('docs');
+        expect(hash['component-c--story-4'].type).toBe('story');
+      });
+
+      it('prefers parameters.docsOnly to inferred docsOnly status', async () => {
+        const { api } = initRefs({ provider, store }, { runCheck: false });
+
+        const index = {
+          v: 3,
+          stories: {
+            'component-a--docs': {
+              id: 'component-a--docs',
+              title: 'Component A',
+              name: 'Docs', // Called 'Docs' rather than 'Page'
+              importPath: './path/to/component-a.ts',
+              parameters: {
+                docsOnly: true,
+              },
+            },
+          },
+        };
+        setupResponses({
+          indexPrivate: { ok: false },
+          storiesPrivate: {
+            ok: true,
+            response: async () => index,
+          },
+          metadata: {
+            ok: true,
+            response: async () => ({
+              versions: {},
+            }),
+          },
+        });
+
+        await api.checkRef({
+          id: 'fake',
+          url: 'https://example.com',
+          title: 'Fake',
+        });
+
+        const { refs } = store.setState.mock.calls[0][0];
+        const hash = refs.fake.stories;
+
+        // We need exact key ordering, even if in theory JS doesn't guarantee it
+        expect(Object.keys(hash)).toEqual(['component-a', 'component-a--docs']);
+        expect(hash['component-a--docs'].type).toBe('docs');
+      });
+    });
   });
 
   it('errors on unknown version', async () => {
     // given
     const { api } = initRefs({ provider, store }, { runCheck: false });
 
-    setupResponses(
-      {
-        ok: true,
-        response: async () => ({ v: 2, stories: {} }),
+    setupResponses({
+      indexPrivate: {
+        ok: false,
       },
-      {
+      storiesPrivate: {
         ok: true,
         response: async () => ({ stories: {} }),
       },
-      {
-        ok: true,
-        response: async () => {
-          throw new Error('not ok');
-        },
-      },
-      {
+      metadata: {
         ok: true,
         response: async () => ({
           versions: {},
         }),
-      }
-    );
+      },
+    });
 
     await expect(
       api.checkRef({

lib/api/src/tests/url.test.js

@@ -203,6 +203,7 @@ describe('initModule', () => {
     const { api, init } = initURL({ store, state: { location: {} }, navigate, fullAPI });
     Object.assign(fullAPI, api, {
       getCurrentStoryData: () => ({
+        type: 'story',
         args: { a: 1, b: 2 },
         initialArgs: { a: 1, b: 1 },
         isLeaf: true,
@@ -241,7 +242,7 @@ describe('initModule', () => {
 
     const { api, init } = initURL({ store, state: { location: {} }, navigate, fullAPI });
     Object.assign(fullAPI, api, {
-      getCurrentStoryData: () => ({ args: { a: 1 }, isLeaf: true }),
+      getCurrentStoryData: () => ({ type: 'story', args: { a: 1 }, isLeaf: true }),
     });
     init();
 

lib/cli/src/js-package-manager/PackageJson.ts

@@ -1,7 +1,6 @@
 import type { PackageJson } from '@storybook/core-common';
 
 export type { PackageJson } from '@storybook/core-common';
-
 export type PackageJsonWithDepsAndDevDeps = PackageJson &
   Required<Pick<PackageJson, 'dependencies' | 'devDependencies'>>;
 

lib/client-api/src/ClientApi.test.ts

@@ -125,14 +125,14 @@ describe('ClientApi', () => {
       clientApi.storiesOf('kind1', module1 as unknown as NodeModule).add('story1', jest.fn());
       clientApi.storiesOf('kind2', module2 as unknown as NodeModule).add('story2', jest.fn());
 
-      expect(Object.keys(clientApi.getStoryIndex().stories)).toEqual([
+      expect(Object.keys(clientApi.getStoryIndex().entries)).toEqual([
         'kind1--story1',
         'kind2--story2',
       ]);
 
       disposeCallback();
       clientApi.storiesOf('kind1', module1 as unknown as NodeModule).add('story1', jest.fn());
-      expect(Object.keys(clientApi.getStoryIndex().stories)).toEqual([
+      expect(Object.keys(clientApi.getStoryIndex().entries)).toEqual([
         'kind1--story1',
         'kind2--story2',
       ]);

lib/client-api/src/ClientApi.ts

@@ -357,13 +357,13 @@ export class ClientApi<TFramework extends AnyFramework> {
       };
       counter += 1;
 
-      this.facade.stories[storyId] = {
+      this.facade.entries[storyId] = {
         id: storyId,
         title: csfExports.default.title,
         name: storyName,
         importPath: fileName,
+        type: 'story',
       };
-
       return api;
     };
 
@@ -399,10 +399,12 @@ Read more here: https://github.com/storybookjs/storybook/blob/master/MIGRATION.m
   };
 
   getStorybook = (): GetStorybookKind<TFramework>[] => {
-    const { stories } = this.storyStore.storyIndex;
+    const { entries } = this.storyStore.storyIndex;
 
     const kinds: Record<ComponentTitle, GetStorybookKind<TFramework>> = {};
-    Object.entries(stories).forEach(([storyId, { title, name, importPath }]) => {
+    Object.entries(entries).forEach(([storyId, { title, name, importPath, type }]) => {
+      if (type && type !== 'story') return;
+
       if (!kinds[title]) {
         kinds[title] = { kind: title, fileName: importPath, stories: [] };
       }

lib/client-api/src/StoryStoreFacade.ts

@@ -12,9 +12,10 @@ import type {
   StoryIndex,
   ModuleExports,
   Story,
-  StoryIndexEntry,
+  IndexEntry,
 } from '@storybook/store';
 import { logger } from '@storybook/client-logger';
+import deprecate from 'util-deprecate';
 
 export interface GetStorybookStory<TFramework extends AnyFramework> {
   name: string;
@@ -27,10 +28,13 @@ export interface GetStorybookKind<TFramework extends AnyFramework> {
   stories: GetStorybookStory<TFramework>[];
 }
 
+const docs2Warning = deprecate(() => {},
+`You cannot use \`.mdx\` files without using \`storyStoreV7\`. Consider upgrading to the new store.`);
+
 export class StoryStoreFacade<TFramework extends AnyFramework> {
   projectAnnotations: NormalizedProjectAnnotations<TFramework>;
 
-  stories: StoryIndex['stories'];
+  entries: StoryIndex['entries'];
 
   csfExports: Record<Path, ModuleExports>;
 
@@ -45,7 +49,7 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
       argTypes: {},
     };
 
-    this.stories = {};
+    this.entries = {};
 
     this.csfExports = {};
   }
@@ -64,7 +68,7 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
     const fileNameOrder = Object.keys(this.csfExports);
     const storySortParameter = this.projectAnnotations.parameters?.options?.storySort;
 
-    const storyEntries = Object.entries(this.stories);
+    const storyEntries = Object.entries(this.entries);
     // Add the kind parameters and global parameters to each entry
     const sortableV6: [StoryId, Story<TFramework>, Parameters, Parameters][] = storyEntries.map(
       ([storyId, { importPath }]) => {
@@ -84,7 +88,7 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
     );
 
     // NOTE: the sortStoriesV6 version returns the v7 data format. confusing but more convenient!
-    let sortedV7: StoryIndexEntry[];
+    let sortedV7: IndexEntry[];
 
     try {
       sortedV7 = sortStoriesV6(sortableV6, storySortParameter, fileNameOrder);
@@ -102,16 +106,16 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
       }
       throw err;
     }
-    const stories = sortedV7.reduce((acc, s) => {
+    const entries = sortedV7.reduce((acc, s) => {
       // We use the original entry we stored in `this.stories` because it is possible that the CSF file itself
       // exports a `parameters.fileName` which can be different and mess up our `importFn`.
       // In fact, in Storyshots there is a Jest transformer that does exactly that.
       // NOTE: this doesn't actually change the story object, just the index.
-      acc[s.id] = this.stories[s.id];
+      acc[s.id] = this.entries[s.id];
       return acc;
-    }, {} as StoryIndex['stories']);
+    }, {} as StoryIndex['entries']);
 
-    return { v: 3, stories };
+    return { v: 4, entries };
   }
 
   clearFilenameExports(fileName: Path) {
@@ -120,9 +124,9 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
     }
 
     // Clear this module's stories from the storyList and existing exports
-    Object.entries(this.stories).forEach(([id, { importPath }]) => {
+    Object.entries(this.entries).forEach(([id, { importPath }]) => {
       if (importPath === fileName) {
-        delete this.stories[id];
+        delete this.entries[id];
       }
     });
 
@@ -132,6 +136,11 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
 
   // NOTE: we could potentially share some of this code with the stories.json generation
   addStoriesFromExports(fileName: Path, fileExports: ModuleExports) {
+    if (fileName.match(/\.mdx$/) && !fileName.match(/\.stories\.mdx$/)) {
+      docs2Warning();
+      return;
+    }
+
     // if the export haven't changed since last time we added them, this is a no-op
     if (this.csfExports[fileName] === fileExports) {
       return;
@@ -190,11 +199,12 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
           storyExport.story?.name ||
           exportName;
 
-        this.stories[id] = {
+        this.entries[id] = {
           id,
           name,
           title,
           importPath: fileName,
+          type: 'story',
         };
       });
   }

lib/components/src/Zoom/ZoomElement.tsx

@@ -10,7 +10,7 @@ const ZoomElementWrapper = styled.div<{ scale: number; height: number }>(({ scal
         },
       }
     : {
-        height: height + 50,
+        height: height ? height + 50 : 'auto',
         transformOrigin: 'top left',
         transform: `scale(${1 / scale})`,
       }

lib/core-client/src/manager/index.ts

@@ -5,5 +5,9 @@ import Provider from './provider';
 
 const { document } = global;
 
-const rootEl = document.getElementById('root');
-renderStorybookUI(rootEl, new Provider());
+// We need to wait a promise "tick" to allow all subsequent addons etc to execute
+// (alternatively, we could ensure this entry point is always loaded last)
+Promise.resolve().then(() => {
+  const rootEl = document.getElementById('root');
+  renderStorybookUI(rootEl, new Provider());
+});

lib/core-client/src/preview/start.test.ts

@@ -946,6 +946,7 @@ describe('start', () => {
           "v": 2,
         }
       `);
+      await waitForRender();
 
       mockChannel.emit.mockClear();
       disposeCallback(module.hot.data);
@@ -1341,6 +1342,8 @@ describe('start', () => {
           "v": 2,
         }
       `);
+
+      await waitForRender();
     });
   });
 });

lib/core-common/package.json

@@ -55,6 +55,7 @@
     "@babel/preset-react": "^7.12.10",
     "@babel/preset-typescript": "^7.12.7",
     "@babel/register": "^7.12.1",
+    "@storybook/csf": "0.0.2--canary.4566f4d.1",
     "@storybook/node-logger": "7.0.0-alpha.5",
     "@storybook/semver": "^7.3.2",
     "@types/babel__core": "^7.0.0",

lib/core-common/src/types.ts

@@ -2,6 +2,7 @@ import type { Options as TelejsonOptions } from 'telejson';
 import type { TransformOptions } from '@babel/core';
 import { Router } from 'express';
 import { Server } from 'http';
+import type { Parameters } from '@storybook/csf';
 import { FileSystemCache } from './utils/file-cache';
 
 /**
@@ -87,12 +88,6 @@ export interface LoadedPreset {
   options: any;
 }
 
-export interface PresetsOptions {
-  corePresets: string[];
-  overridePresets: string[];
-  frameworkPresets: string[];
-}
-
 export type PresetConfig =
   | string
   | {
@@ -240,6 +235,7 @@ export interface IndexerOptions {
 export interface IndexedStory {
   id: string;
   name: string;
+  parameters?: Parameters;
 }
 export interface StoryIndex {
   meta: { title?: string };

lib/core-common/src/utils/__tests__/normalize-stories.test.ts

@@ -230,7 +230,7 @@ describe('normalizeStoriesEntry', () => {
       {
         "titlePrefix": "",
         "directory": ".",
-        "files": "**/*.stories.@(mdx|tsx|ts|jsx|js)",
+        "files": "**/*.(stories|docs).@(mdx|tsx|ts|jsx|js)",
         "importPathMatcher": {}
       }
     `);
@@ -241,7 +241,7 @@ describe('normalizeStoriesEntry', () => {
     expect(specifier).toMatchInlineSnapshot(`
       {
         "titlePrefix": "",
-        "files": "**/*.stories.@(mdx|tsx|ts|jsx|js)",
+        "files": "**/*.(stories|docs).@(mdx|tsx|ts|jsx|js)",
         "directory": ".",
         "importPathMatcher": {}
       }
@@ -265,7 +265,7 @@ describe('normalizeStoriesEntry', () => {
     expect(specifier).toMatchInlineSnapshot(`
       {
         "titlePrefix": "atoms",
-        "files": "**/*.stories.@(mdx|tsx|ts|jsx|js)",
+        "files": "**/*.(stories|docs).@(mdx|tsx|ts|jsx|js)",
         "directory": ".",
         "importPathMatcher": {}
       }

lib/core-common/src/utils/normalize-stories.ts

@@ -10,7 +10,7 @@ import { normalizeStoryPath } from './paths';
 import { globToRegexp } from './glob-to-regexp';
 
 const DEFAULT_TITLE_PREFIX = '';
-const DEFAULT_FILES = '**/*.stories.@(mdx|tsx|ts|jsx|js)';
+const DEFAULT_FILES = '**/*.(stories|docs).@(mdx|tsx|ts|jsx|js)';
 
 // TODO: remove - LEGACY support for bad glob patterns we had in SB 5 - remove in SB7
 const fixBadGlob = deprecate(

lib/core-server/package.json

@@ -38,6 +38,7 @@
     "@storybook/core-events": "7.0.0-alpha.5",
     "@storybook/csf": "0.0.2--canary.4566f4d.1",
     "@storybook/csf-tools": "7.0.0-alpha.5",
+    "@storybook/docs-mdx": "0.0.1-canary.1.4bea5cc.0",
     "@storybook/manager-webpack5": "7.0.0-alpha.5",
     "@storybook/node-logger": "7.0.0-alpha.5",
     "@storybook/semver": "^7.3.2",

lib/core-server/src/build-static.ts

@@ -7,7 +7,6 @@ import global from 'global';
 
 import { logger } from '@storybook/node-logger';
 import { telemetry } from '@storybook/telemetry';
-
 import type {
   LoadOptions,
   CLIOptions,
@@ -29,7 +28,7 @@ import {
   copyAllStaticFilesRelativeToMain,
 } from './utils/copy-all-static-files';
 import { getBuilders } from './utils/get-builders';
-import { extractStoriesJson } from './utils/stories-json';
+import { extractStoriesJson, convertToIndexV3 } from './utils/stories-json';
 import { extractStorybookMetadata } from './utils/metadata';
 import { StoryIndexGenerator } from './utils/StoryIndexGenerator';
 
@@ -141,9 +140,13 @@ export async function buildStaticStandalone(
     extractTasks.push(
       extractStoriesJson(
         path.join(options.outputDir, 'stories.json'),
-        initializedStoryIndexGenerator
+        initializedStoryIndexGenerator,
+        convertToIndexV3
       )
     );
+    extractTasks.push(
+      extractStoriesJson(path.join(options.outputDir, 'index.json'), initializedStoryIndexGenerator)
+    );
   }
 
   const core = await presets.apply<CoreConfig>('core');
@@ -157,7 +160,7 @@ export async function buildStaticStandalone(
       const payload = storyIndex
         ? {
             storyIndex: {
-              storyCount: Object.keys(storyIndex.stories).length,
+              storyCount: Object.keys(storyIndex.entries).length,
               version: storyIndex.v,
             },
           }

lib/core-server/src/core-presets.test.ts

@@ -172,6 +172,7 @@ describe.each([
       ['prod', buildStaticStandalone],
       ['dev', buildDevStandalone],
     ])('%s', async (mode, builder) => {
+      console.log('running for ', mode, builder);
       const options = {
         ...baseOptions,
         configDir: path.resolve(`${__dirname}/../../../examples/${example}/.storybook`),

lib/core-server/src/dev-server.ts

@@ -80,7 +80,7 @@ export async function storybookDevServer(options: Options) {
       const payload = storyIndex
         ? {
             storyIndex: {
-              storyCount: Object.keys(storyIndex.stories).length,
+              storyCount: Object.keys(storyIndex.entries).length,
               version: storyIndex.v,
             },
           }

lib/core-server/src/utils/StoryIndexGenerator.test.ts

@@ -3,11 +3,31 @@ import fs from 'fs-extra';
 import { normalizeStoriesEntry } from '@storybook/core-common';
 import type { NormalizedStoriesSpecifier } from '@storybook/core-common';
 import { loadCsf, getStorySortParameter } from '@storybook/csf-tools';
+import { toId } from '@storybook/csf';
 
 import { StoryIndexGenerator } from './StoryIndexGenerator';
 
 jest.mock('@storybook/csf-tools');
+jest.mock('@storybook/csf', () => {
+  const csf = jest.requireActual('@storybook/csf');
+  return {
+    ...csf,
+    toId: jest.fn(csf.toId),
+  };
+});
 
+// FIXME: can't figure out how to import ESM
+jest.mock('@storybook/docs-mdx', async () => ({
+  analyze(content: string) {
+    const importMatches = content.matchAll(/'(.[^']*\.stories)'/g);
+    const imports = Array.from(importMatches).map((match) => match[1]);
+    const title = content.match(/title=['"](.*)['"]/)?.[1];
+    const ofMatch = content.match(/of=\{(.*)\}/)?.[1];
+    return { title, imports, of: ofMatch && imports.length && imports[0] };
+  },
+}));
+
+const toIdMock = toId as jest.Mock<ReturnType<typeof toId>>;
 const loadCsfMock = loadCsf as jest.Mock<ReturnType<typeof loadCsf>>;
 const getStorySortParameterMock = getStorySortParameter as jest.Mock<
   ReturnType<typeof getStorySortParameter>
@@ -44,15 +64,16 @@ describe('StoryIndexGenerator', () => {
 
         expect(await generator.getIndex()).toMatchInlineSnapshot(`
           Object {
-            "stories": Object {
+            "entries": Object {
               "a--story-one": Object {
                 "id": "a--story-one",
                 "importPath": "./src/A.stories.js",
                 "name": "Story One",
                 "title": "A",
+                "type": "story",
               },
             },
-            "v": 3,
+            "v": 4,
           }
         `);
       });
@@ -69,21 +90,23 @@ describe('StoryIndexGenerator', () => {
 
         expect(await generator.getIndex()).toMatchInlineSnapshot(`
           Object {
-            "stories": Object {
+            "entries": Object {
               "nested-button--story-one": Object {
                 "id": "nested-button--story-one",
                 "importPath": "./src/nested/Button.stories.ts",
                 "name": "Story One",
                 "title": "nested/Button",
+                "type": "story",
               },
               "second-nested-g--story-one": Object {
                 "id": "second-nested-g--story-one",
                 "importPath": "./src/second-nested/G.stories.ts",
                 "name": "Story One",
                 "title": "second-nested/G",
+                "type": "story",
               },
             },
-            "v": 3,
+            "v": 4,
           }
         `);
       });
@@ -101,73 +124,157 @@ describe('StoryIndexGenerator', () => {
 
         expect(await generator.getIndex()).toMatchInlineSnapshot(`
           Object {
-            "stories": Object {
+            "entries": Object {
               "a--story-one": Object {
                 "id": "a--story-one",
                 "importPath": "./src/A.stories.js",
                 "name": "Story One",
                 "title": "A",
+                "type": "story",
               },
               "b--story-one": Object {
                 "id": "b--story-one",
                 "importPath": "./src/B.stories.ts",
                 "name": "Story One",
                 "title": "B",
+                "type": "story",
               },
               "d--story-one": Object {
                 "id": "d--story-one",
                 "importPath": "./src/D.stories.jsx",
                 "name": "Story One",
                 "title": "D",
+                "type": "story",
               },
               "first-nested-deeply-f--story-one": Object {
                 "id": "first-nested-deeply-f--story-one",
                 "importPath": "./src/first-nested/deeply/F.stories.js",
                 "name": "Story One",
                 "title": "first-nested/deeply/F",
+                "type": "story",
               },
               "nested-button--story-one": Object {
                 "id": "nested-button--story-one",
                 "importPath": "./src/nested/Button.stories.ts",
                 "name": "Story One",
                 "title": "nested/Button",
+                "type": "story",
               },
               "second-nested-g--story-one": Object {
                 "id": "second-nested-g--story-one",
                 "importPath": "./src/second-nested/G.stories.ts",
                 "name": "Story One",
                 "title": "second-nested/G",
+                "type": "story",
               },
             },
-            "v": 3,
+            "v": 4,
           }
         `);
       });
     });
+
+    describe('docs specifier', () => {
+      it('extracts stories from the right files', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([storiesSpecifier, docsSpecifier], options);
+        await generator.initialize();
+
+        expect(await generator.getIndex()).toMatchInlineSnapshot(`
+          Object {
+            "entries": Object {
+              "a--docs": Object {
+                "id": "a--docs",
+                "importPath": "./src/docs2/MetaOf.mdx",
+                "name": "docs",
+                "storiesImports": Array [
+                  "./src/A.stories.js",
+                ],
+                "title": "A",
+                "type": "docs",
+              },
+              "a--story-one": Object {
+                "id": "a--story-one",
+                "importPath": "./src/A.stories.js",
+                "name": "Story One",
+                "title": "A",
+                "type": "story",
+              },
+              "docs2-notitle--docs": Object {
+                "id": "docs2-notitle--docs",
+                "importPath": "./src/docs2/NoTitle.mdx",
+                "name": "docs",
+                "storiesImports": Array [],
+                "title": "docs2/NoTitle",
+                "type": "docs",
+              },
+              "docs2-yabbadabbadooo--docs": Object {
+                "id": "docs2-yabbadabbadooo--docs",
+                "importPath": "./src/docs2/Title.mdx",
+                "name": "docs",
+                "storiesImports": Array [],
+                "title": "docs2/Yabbadabbadooo",
+                "type": "docs",
+              },
+            },
+            "v": 4,
+          }
+        `);
+      });
+
+      it('errors when docs dependencies are missing', async () => {
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/MetaOf.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([docsSpecifier], options);
+        await expect(() => generator.initialize()).rejects.toThrowErrorMatchingInlineSnapshot(
+          `"Could not find \\"../A.stories\\" for docs file \\"src/docs2/MetaOf.mdx\\"."`
+        );
+      });
+    });
   });
 
   describe('sorting', () => {
     it('runs a user-defined sort function', async () => {
-      const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+      const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
         './src/**/*.stories.(ts|js|jsx)',
         options
       );
+      const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+        './src/**/*.mdx',
+        options
+      );
 
-      const generator = new StoryIndexGenerator([specifier], options);
+      const generator = new StoryIndexGenerator([docsSpecifier, storiesSpecifier], options);
       await generator.initialize();
 
       (getStorySortParameter as jest.Mock).mockReturnValueOnce({
-        order: ['D', 'B', 'nested', 'A', 'second-nested', 'first-nested/deeply'],
+        order: ['docs2', 'D', 'B', 'nested', 'A', 'second-nested', 'first-nested/deeply'],
       });
 
-      expect(Object.keys((await generator.getIndex()).stories)).toEqual([
-        'd--story-one',
-        'b--story-one',
-        'nested-button--story-one',
-        'a--story-one',
-        'second-nested-g--story-one',
-        'first-nested-deeply-f--story-one',
-      ]);
+      expect(Object.keys((await generator.getIndex()).entries)).toMatchInlineSnapshot(`
+        Array [
+          "docs2-notitle--docs",
+          "docs2-yabbadabbadooo--docs",
+          "d--story-one",
+          "b--story-one",
+          "nested-button--story-one",
+          "a--docs",
+          "a--story-one",
+          "second-nested-g--story-one",
+          "first-nested-deeply-f--story-one",
+        ]
+      `);
     });
   });
 
@@ -190,6 +297,26 @@ describe('StoryIndexGenerator', () => {
         expect(loadCsfMock).not.toHaveBeenCalled();
       });
 
+      it('does not extract docs files a second time', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([storiesSpecifier, docsSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        toIdMock.mockClear();
+        await generator.getIndex();
+        expect(toId).not.toHaveBeenCalled();
+      });
+
       it('does not call the sort function a second time', async () => {
         const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
           './src/**/*.stories.(ts|js|jsx)',
@@ -229,6 +356,50 @@ describe('StoryIndexGenerator', () => {
         expect(loadCsfMock).toHaveBeenCalledTimes(1);
       });
 
+      it('calls extract docs file for just the one file', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([storiesSpecifier, docsSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        generator.invalidate(docsSpecifier, './src/docs2/Title.mdx', false);
+
+        toIdMock.mockClear();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(1);
+      });
+
+      it('calls extract for a csf file and any of its docs dependents', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([storiesSpecifier, docsSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        generator.invalidate(storiesSpecifier, './src/A.stories.js', false);
+
+        toIdMock.mockClear();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(2);
+      });
+
       it('does call the sort function a second time', async () => {
         const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
           './src/**/*.stories.(ts|js|jsx)',
@@ -248,63 +419,136 @@ describe('StoryIndexGenerator', () => {
         await generator.getIndex();
         expect(sortFn).toHaveBeenCalled();
       });
+    });
 
-      describe('file removed', () => {
-        it('does not extract csf files a second time', async () => {
-          const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
-            './src/**/*.stories.(ts|js|jsx)',
-            options
-          );
+    describe('file removed', () => {
+      it('does not extract csf files a second time', async () => {
+        const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.stories.(ts|js|jsx)',
+          options
+        );
 
-          loadCsfMock.mockClear();
-          const generator = new StoryIndexGenerator([specifier], options);
-          await generator.initialize();
-          await generator.getIndex();
-          expect(loadCsfMock).toHaveBeenCalledTimes(7);
+        loadCsfMock.mockClear();
+        const generator = new StoryIndexGenerator([specifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(loadCsfMock).toHaveBeenCalledTimes(7);
 
-          generator.invalidate(specifier, './src/B.stories.ts', true);
+        generator.invalidate(specifier, './src/B.stories.ts', true);
 
-          loadCsfMock.mockClear();
-          await generator.getIndex();
-          expect(loadCsfMock).not.toHaveBeenCalled();
-        });
+        loadCsfMock.mockClear();
+        await generator.getIndex();
+        expect(loadCsfMock).not.toHaveBeenCalled();
+      });
 
-        it('does call the sort function a second time', async () => {
-          const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
-            './src/**/*.stories.(ts|js|jsx)',
-            options
-          );
+      it('does call the sort function a second time', async () => {
+        const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.stories.(ts|js|jsx)',
+          options
+        );
 
-          const sortFn = jest.fn();
-          getStorySortParameterMock.mockReturnValue(sortFn);
-          const generator = new StoryIndexGenerator([specifier], options);
-          await generator.initialize();
-          await generator.getIndex();
-          expect(sortFn).toHaveBeenCalled();
+        const sortFn = jest.fn();
+        getStorySortParameterMock.mockReturnValue(sortFn);
+        const generator = new StoryIndexGenerator([specifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(sortFn).toHaveBeenCalled();
 
-          generator.invalidate(specifier, './src/B.stories.ts', true);
+        generator.invalidate(specifier, './src/B.stories.ts', true);
 
-          sortFn.mockClear();
-          await generator.getIndex();
-          expect(sortFn).toHaveBeenCalled();
-        });
+        sortFn.mockClear();
+        await generator.getIndex();
+        expect(sortFn).toHaveBeenCalled();
+      });
 
-        it('does not include the deleted stories in results', async () => {
-          const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
-            './src/**/*.stories.(ts|js|jsx)',
-            options
-          );
+      it('does not include the deleted stories in results', async () => {
+        const specifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.stories.(ts|js|jsx)',
+          options
+        );
 
-          loadCsfMock.mockClear();
-          const generator = new StoryIndexGenerator([specifier], options);
-          await generator.initialize();
-          await generator.getIndex();
-          expect(loadCsfMock).toHaveBeenCalledTimes(7);
+        loadCsfMock.mockClear();
+        const generator = new StoryIndexGenerator([specifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(loadCsfMock).toHaveBeenCalledTimes(7);
 
-          generator.invalidate(specifier, './src/B.stories.ts', true);
+        generator.invalidate(specifier, './src/B.stories.ts', true);
 
-          expect(Object.keys((await generator.getIndex()).stories)).not.toContain('b--story-one');
-        });
+        expect(Object.keys((await generator.getIndex()).entries)).not.toContain('b--story-one');
+      });
+
+      it('does not include the deleted docs in results', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([docsSpecifier, storiesSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        expect(Object.keys((await generator.getIndex()).entries)).toContain('docs2-notitle--docs');
+
+        generator.invalidate(docsSpecifier, './src/docs2/NoTitle.mdx', true);
+
+        expect(Object.keys((await generator.getIndex()).entries)).not.toContain(
+          'docs2-notitle--docs'
+        );
+      });
+
+      it('errors on dependency deletion', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([docsSpecifier, storiesSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        expect(Object.keys((await generator.getIndex()).entries)).toContain('a--story-one');
+
+        generator.invalidate(storiesSpecifier, './src/A.stories.js', true);
+
+        await expect(() => generator.getIndex()).rejects.toThrowErrorMatchingInlineSnapshot(
+          `"Could not find \\"../A.stories\\" for docs file \\"src/docs2/MetaOf.mdx\\"."`
+        );
+      });
+
+      it('cleans up properly on dependent docs deletion', async () => {
+        const storiesSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/A.stories.(ts|js|jsx)',
+          options
+        );
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([docsSpecifier, storiesSpecifier], options);
+        await generator.initialize();
+        await generator.getIndex();
+        expect(toId).toHaveBeenCalledTimes(4);
+
+        expect(Object.keys((await generator.getIndex()).entries)).toContain('a--docs');
+
+        generator.invalidate(docsSpecifier, './src/docs2/MetaOf.mdx', true);
+
+        expect(Object.keys((await generator.getIndex()).entries)).not.toContain('a--docs');
+
+        // this will throw if MetaOf is not removed from A's dependents
+        generator.invalidate(storiesSpecifier, './src/A.stories.js', false);
       });
     });
   });

lib/core-server/src/utils/StoryIndexGenerator.ts

@@ -3,7 +3,14 @@ import fs from 'fs-extra';
 import glob from 'globby';
 import slash from 'slash';
 
-import type { Path, StoryIndex, V2CompatIndexEntry, StoryId } from '@storybook/store';
+import type {
+  Path,
+  StoryIndex,
+  V2CompatIndexEntry,
+  StoryId,
+  IndexEntry,
+  DocsIndexEntry,
+} from '@storybook/store';
 import { userOrAutoTitleFromSpecifier, sortStoriesV7 } from '@storybook/store';
 import type {
   StoryIndexer,
@@ -14,13 +21,27 @@ import { normalizeStoryPath } from '@storybook/core-common';
 import { logger } from '@storybook/node-logger';
 import { getStorySortParameter } from '@storybook/csf-tools';
 import type { ComponentTitle } from '@storybook/csf';
+import { toId } from '@storybook/csf';
 
-type SpecifierStoriesCache = Record<Path, StoryIndex['stories'] | false>;
+type DocsCacheEntry = DocsIndexEntry;
+type StoriesCacheEntry = { entries: IndexEntry[]; dependents: Path[]; type: 'stories' };
+type CacheEntry = false | StoriesCacheEntry | DocsCacheEntry;
+type SpecifierStoriesCache = Record<Path, CacheEntry>;
+
+const makeAbsolute = (otherImport: Path, normalizedPath: Path, workingDir: Path) =>
+  otherImport.startsWith('.')
+    ? slash(
+        path.resolve(
+          workingDir,
+          normalizeStoryPath(path.join(path.dirname(normalizedPath), otherImport))
+        )
+      )
+    : otherImport;
 
 export class StoryIndexGenerator {
   // An internal cache mapping specifiers to a set of path=><set of stories>
   // Later, we'll combine each of these subsets together to form the full index
-  private storyIndexEntries: Map<NormalizedStoriesSpecifier, SpecifierStoriesCache>;
+  private specifierToCache: Map<NormalizedStoriesSpecifier, SpecifierStoriesCache>;
 
   // Cache the last value of `getStoryIndex`. We invalidate (by unsetting) when:
   //  - any file changes, including deletions
@@ -37,7 +58,7 @@ export class StoryIndexGenerator {
       storyIndexers: StoryIndexer[];
     }
   ) {
-    this.storyIndexEntries = new Map();
+    this.specifierToCache = new Map();
   }
 
   async initialize() {
@@ -61,7 +82,7 @@ export class StoryIndexGenerator {
           pathToSubIndex[absolutePath] = false;
         });
 
-        this.storyIndexEntries.set(specifier, pathToSubIndex);
+        this.specifierToCache.set(specifier, pathToSubIndex);
       })
     );
 
@@ -69,20 +90,149 @@ export class StoryIndexGenerator {
     await this.ensureExtracted();
   }
 
-  async ensureExtracted(): Promise<StoryIndex['stories'][]> {
-    return (
-      await Promise.all(
-        this.specifiers.map(async (specifier) => {
-          const entry = this.storyIndexEntries.get(specifier);
-          return Promise.all(
-            Object.keys(entry).map(
-              async (absolutePath) =>
-                entry[absolutePath] || this.extractStories(specifier, absolutePath)
-            )
-          );
-        })
-      )
-    ).flat();
+  /**
+   * Run the updater function over all the empty cache entries
+   */
+  async updateExtracted(
+    updater: (specifier: NormalizedStoriesSpecifier, absolutePath: Path) => Promise<CacheEntry>
+  ) {
+    await Promise.all(
+      this.specifiers.map(async (specifier) => {
+        const entry = this.specifierToCache.get(specifier);
+        return Promise.all(
+          Object.keys(entry).map(async (absolutePath) => {
+            entry[absolutePath] = entry[absolutePath] || (await updater(specifier, absolutePath));
+          })
+        );
+      })
+    );
+  }
+
+  isDocsMdx(absolutePath: Path) {
+    return /(?<!\.stories)\.mdx$/i.test(absolutePath);
+  }
+
+  async ensureExtracted(): Promise<IndexEntry[]> {
+    // First process all the story files. Then, in a second pass,
+    // process the docs files. The reason for this is that the docs
+    // files may use the `<Meta of={XStories} />` syntax, which requires
+    // that the story file that contains the meta be processed first.
+    await this.updateExtracted(async (specifier, absolutePath) =>
+      this.isDocsMdx(absolutePath) ? false : this.extractStories(specifier, absolutePath)
+    );
+    await this.updateExtracted(async (specifier, absolutePath) =>
+      this.extractDocs(specifier, absolutePath)
+    );
+
+    return this.specifiers.flatMap((specifier) => {
+      const cache = this.specifierToCache.get(specifier);
+      return Object.values(cache).flatMap((entry) => {
+        if (!entry) return [];
+        if (entry.type === 'docs') return [entry];
+        return entry.entries;
+      });
+    });
+  }
+
+  findDependencies(absoluteImports: Path[]) {
+    const dependencies = [] as StoriesCacheEntry[];
+    const foundImports = new Set();
+    this.specifierToCache.forEach((cache) => {
+      const fileNames = Object.keys(cache).filter((fileName) => {
+        const foundImport = absoluteImports.find((storyImport) => fileName.startsWith(storyImport));
+        if (foundImport) foundImports.add(foundImport);
+        return !!foundImport;
+      });
+      fileNames.forEach((fileName) => {
+        const cacheEntry = cache[fileName];
+        if (cacheEntry && cacheEntry.type === 'stories') {
+          dependencies.push(cacheEntry);
+        } else {
+          throw new Error(`Unexpected dependency: ${cacheEntry}`);
+        }
+      });
+    });
+
+    // imports can include non-story imports, so it's ok if
+    // there are fewer foundImports than absoluteImports
+    // if (absoluteImports.length !== foundImports.size) {
+    //   throw new Error(`Missing dependencies: ${absoluteImports.filter((p) => !foundImports.has(p))}`));
+    // }
+
+    return dependencies;
+  }
+
+  async extractDocs(specifier: NormalizedStoriesSpecifier, absolutePath: Path) {
+    const relativePath = path.relative(this.options.workingDir, absolutePath);
+    try {
+      if (!this.options.storyStoreV7) {
+        throw new Error(`You cannot use \`.mdx\` files without using \`storyStoreV7\`.`);
+      }
+
+      const normalizedPath = normalizeStoryPath(relativePath);
+      const importPath = slash(normalizedPath);
+
+      // This `await require(...)` is a bit of a hack. It's necessary because
+      // `docs-mdx` depends on ESM code, which must be asynchronously imported
+      // to be used in CJS. Unfortunately, we cannot use `import()` here, because
+      // it will be transpiled down to `require()` by Babel. So instead, we require
+      // a CJS export from `@storybook/docs-mdx` that does the `async import` for us.
+
+      // eslint-disable-next-line global-require
+      const { analyze } = await require('@storybook/docs-mdx');
+      const content = await fs.readFile(absolutePath, 'utf8');
+      // { title?, of?, imports? }
+      const result = analyze(content);
+
+      const absoluteImports = (result.imports as string[]).map((p) =>
+        makeAbsolute(p, normalizedPath, this.options.workingDir)
+      );
+
+      // Go through the cache and collect all of the cache entries that this docs file depends on.
+      // We'll use this to make sure this docs cache entry is invalidated when any of its dependents
+      // are invalidated.
+      const dependencies = this.findDependencies(absoluteImports);
+
+      // Also, if `result.of` is set, it means that we're using the `<Meta of={XStories} />` syntax,
+      // so find the `title` defined the file that `meta` points to.
+      let ofTitle: string;
+      if (result.of) {
+        const absoluteOf = makeAbsolute(result.of, normalizedPath, this.options.workingDir);
+        dependencies.forEach((dep) => {
+          if (dep.entries.length > 0) {
+            const first = dep.entries[0];
+            if (path.resolve(this.options.workingDir, first.importPath).startsWith(absoluteOf)) {
+              ofTitle = first.title;
+            }
+          }
+        });
+
+        if (!ofTitle)
+          throw new Error(`Could not find "${result.of}" for docs file "${relativePath}".`);
+      }
+
+      // Track that we depend on this for easy invalidation later.
+      dependencies.forEach((dep) => {
+        dep.dependents.push(absolutePath);
+      });
+
+      const title = userOrAutoTitleFromSpecifier(importPath, specifier, result.title || ofTitle);
+      const name = 'docs';
+      const id = toId(title, name);
+
+      const docsEntry: DocsCacheEntry = {
+        id,
+        title,
+        name,
+        importPath,
+        storiesImports: dependencies.map((dep) => dep.entries[0].importPath),
+        type: 'docs',
+      };
+      return docsEntry;
+    } catch (err) {
+      logger.warn(`🚨 Extraction error on ${relativePath}: ${err}`);
+      throw err;
+    }
   }
 
   async index(filePath: string, options: IndexerOptions) {
@@ -95,21 +245,19 @@ export class StoryIndexGenerator {
 
   async extractStories(specifier: NormalizedStoriesSpecifier, absolutePath: Path) {
     const relativePath = path.relative(this.options.workingDir, absolutePath);
-    const fileStories = {} as StoryIndex['stories'];
-    const entry = this.storyIndexEntries.get(specifier);
+    const entries = [] as IndexEntry[];
     try {
       const importPath = slash(normalizeStoryPath(relativePath));
       const makeTitle = (userTitle?: string) => {
         return userOrAutoTitleFromSpecifier(importPath, specifier, userTitle);
       };
       const csf = await this.index(absolutePath, { makeTitle });
-      csf.stories.forEach(({ id, name }) => {
-        fileStories[id] = {
-          id,
-          title: csf.meta.title,
-          name,
-          importPath,
-        };
+      csf.stories.forEach(({ id, name, parameters }) => {
+        const base = { id, title: csf.meta.title, name, importPath };
+        const entry: IndexEntry = parameters?.docsOnly
+          ? { ...base, type: 'docs', storiesImports: [], legacy: true }
+          : { ...base, type: 'story' };
+        entries.push(entry);
       });
     } catch (err) {
       if (err.name === 'NoMetaError') {
@@ -119,18 +267,17 @@ export class StoryIndexGenerator {
         throw err;
       }
     }
-    entry[absolutePath] = fileStories;
-    return fileStories;
+    return { entries, type: 'stories', dependents: [] } as StoriesCacheEntry;
   }
 
-  async sortStories(storiesList: StoryIndex['stories'][]) {
-    const stories: StoryIndex['stories'] = {};
+  async sortStories(storiesList: IndexEntry[]) {
+    const entries: StoryIndex['entries'] = {};
 
-    storiesList.forEach((subStories) => {
-      Object.assign(stories, subStories);
+    storiesList.forEach((entry) => {
+      entries[entry.id] = entry;
     });
 
-    const sortableStories = Object.values(stories);
+    const sortableStories = Object.values(entries);
 
     // Skip sorting if we're in v6 mode because we don't have
     // all the info we need here
@@ -143,7 +290,7 @@ export class StoryIndexGenerator {
     return sortableStories.reduce((acc, item) => {
       acc[item.id] = item;
       return acc;
-    }, {} as StoryIndex['stories']);
+    }, {} as StoryIndex['entries']);
   }
 
   async getIndex() {
@@ -152,7 +299,6 @@ export class StoryIndexGenerator {
     // Extract any entries that are currently missing
     // Pull out each file's stories into a list of stories, to be composed and sorted
     const storiesList = await this.ensureExtracted();
-
     const sorted = await this.sortStories(storiesList);
 
     let compat = sorted;
@@ -162,11 +308,13 @@ export class StoryIndexGenerator {
         return acc;
       }, {} as Record<ComponentTitle, number>);
 
+      // @ts-ignore
       compat = Object.entries(sorted).reduce((acc, entry) => {
         const [id, story] = entry;
+        if (story.type === 'docs') return acc;
+
         acc[id] = {
           ...story,
-          id,
           kind: story.title,
           story: story.name,
           parameters: {
@@ -180,8 +328,8 @@ export class StoryIndexGenerator {
     }
 
     this.lastIndex = {
-      v: 3,
-      stories: compat,
+      v: 4,
+      entries: compat,
     };
 
     return this.lastIndex;
@@ -189,12 +337,43 @@ export class StoryIndexGenerator {
 
   invalidate(specifier: NormalizedStoriesSpecifier, importPath: Path, removed: boolean) {
     const absolutePath = slash(path.resolve(this.options.workingDir, importPath));
-    const pathToEntries = this.storyIndexEntries.get(specifier);
+    const cache = this.specifierToCache.get(specifier);
+
+    const cacheEntry = cache[absolutePath];
+    if (cacheEntry && cacheEntry.type === 'stories') {
+      const { dependents } = cacheEntry;
+
+      const invalidated = new Set();
+      // the dependent can be in ANY cache, so we loop over all of them
+      this.specifierToCache.forEach((otherCache) => {
+        dependents.forEach((dep) => {
+          if (otherCache[dep]) {
+            invalidated.add(dep);
+            // eslint-disable-next-line no-param-reassign
+            otherCache[dep] = false;
+          }
+        });
+      });
+
+      const notFound = dependents.filter((dep) => !invalidated.has(dep));
+      if (notFound.length > 0) {
+        throw new Error(`Could not invalidate ${notFound.length} deps: ${notFound.join(', ')}`);
+      }
+    }
 
     if (removed) {
-      delete pathToEntries[absolutePath];
+      if (cacheEntry && cacheEntry.type === 'docs') {
+        const absoluteImports = cacheEntry.storiesImports.map((p) =>
+          path.resolve(this.options.workingDir, p)
+        );
+        const dependencies = this.findDependencies(absoluteImports);
+        dependencies.forEach((dep) =>
+          dep.dependents.splice(dep.dependents.indexOf(absolutePath), 1)
+        );
+      }
+      delete cache[absolutePath];
     } else {
-      pathToEntries[absolutePath] = false;
+      cache[absolutePath] = false;
     }
     this.lastIndex = null;
   }
@@ -214,6 +393,6 @@ export class StoryIndexGenerator {
 
   // Get the story file names in "imported order"
   storyFileNames() {
-    return Array.from(this.storyIndexEntries.values()).flatMap((r) => Object.keys(r));
+    return Array.from(this.specifierToCache.values()).flatMap((r) => Object.keys(r));
   }
 }

lib/core-server/src/utils/__mockdata__/src/docs2/MetaOf.mdx

@@ -0,0 +1,7 @@
+import meta from '../A.stories';
+
+<Meta of={meta} />
+
+# Docs with of
+
+hello docs

lib/core-server/src/utils/__mockdata__/src/docs2/NoTitle.mdx

@@ -0,0 +1,3 @@
+# Docs with no title
+
+hello docs

lib/core-server/src/utils/__mockdata__/src/docs2/Title.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="docs2/Yabbadabbadooo" />
+
+# Docs with title
+
+hello docs

lib/core-server/src/utils/__mockdata__/src/nested/Page.mdx

@@ -1 +0,0 @@
-<h1>Some MDX</h1>

lib/core-server/src/utils/stories-json.test.ts

@@ -3,25 +3,47 @@ import { Router, Request, Response } from 'express';
 import Watchpack from 'watchpack';
 import path from 'path';
 import debounce from 'lodash/debounce';
-import Events from '@storybook/core-events';
+import { STORY_INDEX_INVALIDATED } from '@storybook/core-events';
+import type { StoryIndex } from '@storybook/store';
 import { loadCsf } from '@storybook/csf-tools';
+import { normalizeStoriesEntry } from '@storybook/core-common';
 
-import { useStoriesJson, DEBOUNCE } from './stories-json';
+import { useStoriesJson, DEBOUNCE, convertToIndexV3 } from './stories-json';
 import { ServerChannel } from './get-server-channel';
 import { StoryIndexGenerator } from './StoryIndexGenerator';
 
 jest.mock('watchpack');
 jest.mock('lodash/debounce');
 
+// FIXME: can't figure out how to import ESM
+jest.mock('@storybook/docs-mdx', async () => ({
+  analyze(content: string) {
+    const importMatches = content.matchAll(/'(.[^']*\.stories)'/g);
+    const imports = Array.from(importMatches).map((match) => match[1]);
+    const title = content.match(/title=['"](.*)['"]/)?.[1];
+    const ofMatch = content.match(/of=\{(.*)\}/)?.[1];
+    return { title, imports, of: ofMatch && imports.length && imports[0] };
+  },
+}));
+
 const workingDir = path.join(__dirname, '__mockdata__');
 const normalizedStories = [
-  {
-    titlePrefix: '',
-    directory: './src',
-    files: '**/*.stories.@(ts|js|jsx)',
-    importPathMatcher:
-      /^\.[\\/](?:src(?:\/(?!\.)(?:(?:(?!(?:^|\/)\.).)*?)\/|\/|$)(?!\.)(?=.)[^/]*?\.stories\.(ts|js|jsx))$/,
-  },
+  normalizeStoriesEntry(
+    {
+      titlePrefix: '',
+      directory: './src',
+      files: '**/*.stories.@(ts|js|jsx)',
+    },
+    { workingDir, configDir: workingDir }
+  ),
+  normalizeStoriesEntry(
+    {
+      titlePrefix: '',
+      directory: './src',
+      files: '**/*.mdx',
+    },
+    { workingDir, configDir: workingDir }
+  ),
 ];
 
 const csfIndexer = async (fileName: string, opts: any) => {
@@ -29,13 +51,17 @@ const csfIndexer = async (fileName: string, opts: any) => {
   return loadCsf(code, { ...opts, fileName }).parse();
 };
 
-const getInitializedStoryIndexGenerator = async () => {
-  const generator = new StoryIndexGenerator(normalizedStories, {
+const getInitializedStoryIndexGenerator = async (
+  overrides: any = {},
+  inputNormalizedStories = normalizedStories
+) => {
+  const generator = new StoryIndexGenerator(inputNormalizedStories, {
     storyIndexers: [{ test: /\.stories\..*$/, indexer: csfIndexer }],
     configDir: workingDir,
     workingDir,
-    storiesV2Compatibility: true,
+    storiesV2Compatibility: false,
     storyStoreV7: true,
+    ...overrides,
   });
   await generator.initialize();
   return generator;
@@ -70,7 +96,7 @@ describe('useStoriesJson', () => {
   } as any;
 
   describe('JSON endpoint', () => {
-    it('scans and extracts stories', async () => {
+    it('scans and extracts index', async () => {
       const mockServerChannel = { emit: jest.fn() } as any as ServerChannel;
       useStoriesJson({
         router,
@@ -80,11 +106,382 @@ describe('useStoriesJson', () => {
         initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
       });
 
-      expect(use).toHaveBeenCalledTimes(1);
+      expect(use).toHaveBeenCalledTimes(2);
       const route = use.mock.calls[0][1];
 
       await route(request, response);
 
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(send.mock.calls[0][0])).toMatchInlineSnapshot(`
+        Object {
+          "entries": Object {
+            "a--docs": Object {
+              "id": "a--docs",
+              "importPath": "./src/docs2/MetaOf.mdx",
+              "name": "docs",
+              "storiesImports": Array [
+                "./src/A.stories.js",
+              ],
+              "title": "A",
+              "type": "docs",
+            },
+            "a--story-one": Object {
+              "id": "a--story-one",
+              "importPath": "./src/A.stories.js",
+              "name": "Story One",
+              "title": "A",
+              "type": "story",
+            },
+            "b--story-one": Object {
+              "id": "b--story-one",
+              "importPath": "./src/B.stories.ts",
+              "name": "Story One",
+              "title": "B",
+              "type": "story",
+            },
+            "d--story-one": Object {
+              "id": "d--story-one",
+              "importPath": "./src/D.stories.jsx",
+              "name": "Story One",
+              "title": "D",
+              "type": "story",
+            },
+            "docs2-notitle--docs": Object {
+              "id": "docs2-notitle--docs",
+              "importPath": "./src/docs2/NoTitle.mdx",
+              "name": "docs",
+              "storiesImports": Array [],
+              "title": "docs2/NoTitle",
+              "type": "docs",
+            },
+            "docs2-yabbadabbadooo--docs": Object {
+              "id": "docs2-yabbadabbadooo--docs",
+              "importPath": "./src/docs2/Title.mdx",
+              "name": "docs",
+              "storiesImports": Array [],
+              "title": "docs2/Yabbadabbadooo",
+              "type": "docs",
+            },
+            "first-nested-deeply-f--story-one": Object {
+              "id": "first-nested-deeply-f--story-one",
+              "importPath": "./src/first-nested/deeply/F.stories.js",
+              "name": "Story One",
+              "title": "first-nested/deeply/F",
+              "type": "story",
+            },
+            "nested-button--story-one": Object {
+              "id": "nested-button--story-one",
+              "importPath": "./src/nested/Button.stories.ts",
+              "name": "Story One",
+              "title": "nested/Button",
+              "type": "story",
+            },
+            "second-nested-g--story-one": Object {
+              "id": "second-nested-g--story-one",
+              "importPath": "./src/second-nested/G.stories.ts",
+              "name": "Story One",
+              "title": "second-nested/G",
+              "type": "story",
+            },
+          },
+          "v": 4,
+        }
+      `);
+    });
+
+    it('scans and extracts stories v3', async () => {
+      const mockServerChannel = { emit: jest.fn() } as any as ServerChannel;
+      useStoriesJson({
+        router,
+        initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
+        workingDir,
+        serverChannel: mockServerChannel,
+        normalizedStories,
+      });
+
+      expect(use).toHaveBeenCalledTimes(2);
+      const route = use.mock.calls[1][1];
+
+      await route(request, response);
+
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(send.mock.calls[0][0])).toMatchInlineSnapshot(`
+        Object {
+          "stories": Object {
+            "a--docs": Object {
+              "id": "a--docs",
+              "importPath": "./src/docs2/MetaOf.mdx",
+              "kind": "A",
+              "name": "docs",
+              "parameters": Object {
+                "__id": "a--docs",
+                "docsOnly": true,
+                "fileName": "./src/docs2/MetaOf.mdx",
+              },
+              "storiesImports": Array [
+                "./src/A.stories.js",
+              ],
+              "story": "docs",
+              "title": "A",
+            },
+            "a--story-one": Object {
+              "id": "a--story-one",
+              "importPath": "./src/A.stories.js",
+              "kind": "A",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "a--story-one",
+                "docsOnly": false,
+                "fileName": "./src/A.stories.js",
+              },
+              "story": "Story One",
+              "title": "A",
+            },
+            "b--story-one": Object {
+              "id": "b--story-one",
+              "importPath": "./src/B.stories.ts",
+              "kind": "B",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "b--story-one",
+                "docsOnly": false,
+                "fileName": "./src/B.stories.ts",
+              },
+              "story": "Story One",
+              "title": "B",
+            },
+            "d--story-one": Object {
+              "id": "d--story-one",
+              "importPath": "./src/D.stories.jsx",
+              "kind": "D",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "d--story-one",
+                "docsOnly": false,
+                "fileName": "./src/D.stories.jsx",
+              },
+              "story": "Story One",
+              "title": "D",
+            },
+            "docs2-notitle--docs": Object {
+              "id": "docs2-notitle--docs",
+              "importPath": "./src/docs2/NoTitle.mdx",
+              "kind": "docs2/NoTitle",
+              "name": "docs",
+              "parameters": Object {
+                "__id": "docs2-notitle--docs",
+                "docsOnly": true,
+                "fileName": "./src/docs2/NoTitle.mdx",
+              },
+              "storiesImports": Array [],
+              "story": "docs",
+              "title": "docs2/NoTitle",
+            },
+            "docs2-yabbadabbadooo--docs": Object {
+              "id": "docs2-yabbadabbadooo--docs",
+              "importPath": "./src/docs2/Title.mdx",
+              "kind": "docs2/Yabbadabbadooo",
+              "name": "docs",
+              "parameters": Object {
+                "__id": "docs2-yabbadabbadooo--docs",
+                "docsOnly": true,
+                "fileName": "./src/docs2/Title.mdx",
+              },
+              "storiesImports": Array [],
+              "story": "docs",
+              "title": "docs2/Yabbadabbadooo",
+            },
+            "first-nested-deeply-f--story-one": Object {
+              "id": "first-nested-deeply-f--story-one",
+              "importPath": "./src/first-nested/deeply/F.stories.js",
+              "kind": "first-nested/deeply/F",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "first-nested-deeply-f--story-one",
+                "docsOnly": false,
+                "fileName": "./src/first-nested/deeply/F.stories.js",
+              },
+              "story": "Story One",
+              "title": "first-nested/deeply/F",
+            },
+            "nested-button--story-one": Object {
+              "id": "nested-button--story-one",
+              "importPath": "./src/nested/Button.stories.ts",
+              "kind": "nested/Button",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "nested-button--story-one",
+                "docsOnly": false,
+                "fileName": "./src/nested/Button.stories.ts",
+              },
+              "story": "Story One",
+              "title": "nested/Button",
+            },
+            "second-nested-g--story-one": Object {
+              "id": "second-nested-g--story-one",
+              "importPath": "./src/second-nested/G.stories.ts",
+              "kind": "second-nested/G",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "second-nested-g--story-one",
+                "docsOnly": false,
+                "fileName": "./src/second-nested/G.stories.ts",
+              },
+              "story": "Story One",
+              "title": "second-nested/G",
+            },
+          },
+          "v": 3,
+        }
+      `);
+    });
+
+    it('scans and extracts stories v2', async () => {
+      const mockServerChannel = { emit: jest.fn() } as any as ServerChannel;
+      useStoriesJson({
+        router,
+        initializedStoryIndexGenerator: getInitializedStoryIndexGenerator({
+          storiesV2Compatibility: true,
+        }),
+        workingDir,
+        serverChannel: mockServerChannel,
+        normalizedStories,
+      });
+
+      expect(use).toHaveBeenCalledTimes(2);
+      const route = use.mock.calls[1][1];
+
+      await route(request, response);
+
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(send.mock.calls[0][0])).toMatchInlineSnapshot(`
+        Object {
+          "stories": Object {
+            "a--story-one": Object {
+              "id": "a--story-one",
+              "importPath": "./src/A.stories.js",
+              "kind": "A",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "a--story-one",
+                "docsOnly": false,
+                "fileName": "./src/A.stories.js",
+              },
+              "story": "Story One",
+              "title": "A",
+            },
+            "b--story-one": Object {
+              "id": "b--story-one",
+              "importPath": "./src/B.stories.ts",
+              "kind": "B",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "b--story-one",
+                "docsOnly": false,
+                "fileName": "./src/B.stories.ts",
+              },
+              "story": "Story One",
+              "title": "B",
+            },
+            "d--story-one": Object {
+              "id": "d--story-one",
+              "importPath": "./src/D.stories.jsx",
+              "kind": "D",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "d--story-one",
+                "docsOnly": false,
+                "fileName": "./src/D.stories.jsx",
+              },
+              "story": "Story One",
+              "title": "D",
+            },
+            "first-nested-deeply-f--story-one": Object {
+              "id": "first-nested-deeply-f--story-one",
+              "importPath": "./src/first-nested/deeply/F.stories.js",
+              "kind": "first-nested/deeply/F",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "first-nested-deeply-f--story-one",
+                "docsOnly": false,
+                "fileName": "./src/first-nested/deeply/F.stories.js",
+              },
+              "story": "Story One",
+              "title": "first-nested/deeply/F",
+            },
+            "nested-button--story-one": Object {
+              "id": "nested-button--story-one",
+              "importPath": "./src/nested/Button.stories.ts",
+              "kind": "nested/Button",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "nested-button--story-one",
+                "docsOnly": false,
+                "fileName": "./src/nested/Button.stories.ts",
+              },
+              "story": "Story One",
+              "title": "nested/Button",
+            },
+            "second-nested-g--story-one": Object {
+              "id": "second-nested-g--story-one",
+              "importPath": "./src/second-nested/G.stories.ts",
+              "kind": "second-nested/G",
+              "name": "Story One",
+              "parameters": Object {
+                "__id": "second-nested-g--story-one",
+                "docsOnly": false,
+                "fileName": "./src/second-nested/G.stories.ts",
+              },
+              "story": "Story One",
+              "title": "second-nested/G",
+            },
+          },
+          "v": 3,
+        }
+      `);
+    });
+
+    it('disallows .mdx files without storyStoreV7', async () => {
+      const mockServerChannel = { emit: jest.fn() } as any as ServerChannel;
+      useStoriesJson({
+        router,
+        initializedStoryIndexGenerator: getInitializedStoryIndexGenerator({
+          storyStoreV7: false,
+        }),
+        workingDir,
+        serverChannel: mockServerChannel,
+        normalizedStories,
+      });
+
+      expect(use).toHaveBeenCalledTimes(2);
+      const route = use.mock.calls[1][1];
+
+      await route(request, response);
+
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(send.mock.calls[0][0]).toEqual(
+        'You cannot use `.mdx` files without using `storyStoreV7`.'
+      );
+    });
+
+    it('allows disabling storyStoreV7 if no .mdx files are used', async () => {
+      const mockServerChannel = { emit: jest.fn() } as any as ServerChannel;
+      useStoriesJson({
+        router,
+        initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(
+          { storyStoreV7: false },
+          normalizedStories.slice(0, 1)
+        ),
+        workingDir,
+        serverChannel: mockServerChannel,
+        normalizedStories,
+      });
+
+      expect(use).toHaveBeenCalledTimes(2);
+      const route = use.mock.calls[1][1];
+
+      await route(request, response);
+
       expect(send).toHaveBeenCalledTimes(1);
       expect(JSON.parse(send.mock.calls[0][0])).toMatchInlineSnapshot(`
         Object {
@@ -184,7 +581,7 @@ describe('useStoriesJson', () => {
         initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
       });
 
-      expect(use).toHaveBeenCalledTimes(1);
+      expect(use).toHaveBeenCalledTimes(2);
       const route = use.mock.calls[0][1];
 
       const firstPromise = route(request, response);
@@ -216,7 +613,7 @@ describe('useStoriesJson', () => {
         initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
       });
 
-      expect(use).toHaveBeenCalledTimes(1);
+      expect(use).toHaveBeenCalledTimes(2);
       const route = use.mock.calls[0][1];
 
       await route(request, response);
@@ -232,7 +629,7 @@ describe('useStoriesJson', () => {
 
       await onChange('src/nested/Button.stories.ts');
       expect(mockServerChannel.emit).toHaveBeenCalledTimes(1);
-      expect(mockServerChannel.emit).toHaveBeenCalledWith(Events.STORY_INDEX_INVALIDATED);
+      expect(mockServerChannel.emit).toHaveBeenCalledWith(STORY_INDEX_INVALIDATED);
     });
 
     it('only sends one invalidation when multiple event listeners are listening', async () => {
@@ -245,7 +642,7 @@ describe('useStoriesJson', () => {
         initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
       });
 
-      expect(use).toHaveBeenCalledTimes(1);
+      expect(use).toHaveBeenCalledTimes(2);
       const route = use.mock.calls[0][1];
 
       // Don't wait for the first request here before starting the second
@@ -265,7 +662,7 @@ describe('useStoriesJson', () => {
 
       await onChange('src/nested/Button.stories.ts');
       expect(mockServerChannel.emit).toHaveBeenCalledTimes(1);
-      expect(mockServerChannel.emit).toHaveBeenCalledWith(Events.STORY_INDEX_INVALIDATED);
+      expect(mockServerChannel.emit).toHaveBeenCalledWith(STORY_INDEX_INVALIDATED);
     });
 
     it('debounces invalidation events', async () => {
@@ -280,7 +677,7 @@ describe('useStoriesJson', () => {
         initializedStoryIndexGenerator: getInitializedStoryIndexGenerator(),
       });
 
-      expect(use).toHaveBeenCalledTimes(1);
+      expect(use).toHaveBeenCalledTimes(2);
       const route = use.mock.calls[0][1];
 
       await route(request, response);
@@ -301,7 +698,7 @@ describe('useStoriesJson', () => {
       await onChange('src/nested/Button.stories.ts');
 
       expect(mockServerChannel.emit).toHaveBeenCalledTimes(1);
-      expect(mockServerChannel.emit).toHaveBeenCalledWith(Events.STORY_INDEX_INVALIDATED);
+      expect(mockServerChannel.emit).toHaveBeenCalledWith(STORY_INDEX_INVALIDATED);
 
       await new Promise((r) => setTimeout(r, 2 * DEBOUNCE));
 
@@ -309,3 +706,85 @@ describe('useStoriesJson', () => {
     });
   });
 });
+
+describe('convertToIndexV3', () => {
+  it('converts v7 index.json to v6 stories.json', () => {
+    const indexJson: StoryIndex = {
+      v: 4,
+      entries: {
+        'a--docs': {
+          id: 'a--docs',
+          importPath: './src/docs2/MetaOf.mdx',
+          name: 'docs',
+          storiesImports: ['./src/A.stories.js'],
+          title: 'A',
+          type: 'docs',
+        },
+        'a--story-one': {
+          id: 'a--story-one',
+          importPath: './src/A.stories.js',
+          name: 'Story One',
+          title: 'A',
+          type: 'story',
+        },
+        'b--story-one': {
+          id: 'b--story-one',
+          importPath: './src/B.stories.ts',
+          name: 'Story One',
+          title: 'B',
+          type: 'story',
+        },
+      },
+    };
+
+    expect(convertToIndexV3(indexJson)).toMatchInlineSnapshot(`
+      Object {
+        "stories": Object {
+          "a--docs": Object {
+            "id": "a--docs",
+            "importPath": "./src/docs2/MetaOf.mdx",
+            "kind": "A",
+            "name": "docs",
+            "parameters": Object {
+              "__id": "a--docs",
+              "docsOnly": true,
+              "fileName": "./src/docs2/MetaOf.mdx",
+            },
+            "storiesImports": Array [
+              "./src/A.stories.js",
+            ],
+            "story": "docs",
+            "title": "A",
+          },
+          "a--story-one": Object {
+            "id": "a--story-one",
+            "importPath": "./src/A.stories.js",
+            "kind": "A",
+            "name": "Story One",
+            "parameters": Object {
+              "__id": "a--story-one",
+              "docsOnly": false,
+              "fileName": "./src/A.stories.js",
+            },
+            "story": "Story One",
+            "title": "A",
+          },
+          "b--story-one": Object {
+            "id": "b--story-one",
+            "importPath": "./src/B.stories.ts",
+            "kind": "B",
+            "name": "Story One",
+            "parameters": Object {
+              "__id": "b--story-one",
+              "docsOnly": false,
+              "fileName": "./src/B.stories.ts",
+            },
+            "story": "Story One",
+            "title": "B",
+          },
+        },
+        "v": 3,
+      }
+    `);
+  });
+});