Addon-Docs: Scope slugger to docs render

code/addons/docs/src/blocks/blocks/DocsContainer.tsx

@@ -1,5 +1,5 @@
 import type { FC, PropsWithChildren } from 'react';
-import React, { useEffect } from 'react';
+import React, { useEffect, useMemo } from 'react';
 
 import type { Renderer } from 'storybook/internal/types';
 
@@ -10,6 +10,7 @@ import { DocsPageWrapper } from '../components';
 import { TableOfContents } from '../components/TableOfContents';
 import type { DocsContextProps } from './DocsContext';
 import { DocsContext } from './DocsContext';
+import { createDocsSlugger, DocsSluggerContext } from './DocsSluggerContext';
 import { SourceContainer } from './SourceContainer';
 import { scrollToElement } from './utils';
 
@@ -25,6 +26,7 @@ export const DocsContainer: FC<PropsWithChildren<DocsContainerProps>> = ({
   theme,
   children,
 }) => {
+  const slugger = useMemo(() => createDocsSlugger(), []);
   let toc;
 
   try {
@@ -54,24 +56,26 @@ export const DocsContainer: FC<PropsWithChildren<DocsContainerProps>> = ({
   });
 
   return (
-    <DocsContext.Provider value={context}>
-      <SourceContainer channel={context.channel}>
-        <ThemeProvider theme={ensureTheme(theme as ThemeVars)}>
-          <DocsPageWrapper
-            toc={
-              toc ? (
-                <TableOfContents
-                  className="sbdocs sbdocs-toc--custom"
-                  channel={context.channel}
-                  {...toc}
-                />
-              ) : null
-            }
-          >
-            {children}
-          </DocsPageWrapper>
-        </ThemeProvider>
-      </SourceContainer>
-    </DocsContext.Provider>
+    <DocsSluggerContext.Provider value={slugger}>
+      <DocsContext.Provider value={context}>
+        <SourceContainer channel={context.channel}>
+          <ThemeProvider theme={ensureTheme(theme as ThemeVars)}>
+            <DocsPageWrapper
+              toc={
+                toc ? (
+                  <TableOfContents
+                    className="sbdocs sbdocs-toc--custom"
+                    channel={context.channel}
+                    {...toc}
+                  />
+                ) : null
+              }
+            >
+              {children}
+            </DocsPageWrapper>
+          </ThemeProvider>
+        </SourceContainer>
+      </DocsContext.Provider>
+    </DocsSluggerContext.Provider>
   );
 };

code/addons/docs/src/blocks/blocks/DocsContext.ts

@@ -11,10 +11,10 @@ export type { DocsContextProps };
 // the React component tree.
 // This was specifically a problem with the Vite builder.
 if (globalThis && globalThis.__DOCS_CONTEXT__ === undefined) {
-  globalThis.__DOCS_CONTEXT__ = createContext(null);
+  globalThis.__DOCS_CONTEXT__ = createContext<DocsContextProps<Renderer>>(null!);
   globalThis.__DOCS_CONTEXT__.displayName = 'DocsContext';
 }
 
 export const DocsContext: Context<DocsContextProps<Renderer>> = globalThis
   ? globalThis.__DOCS_CONTEXT__
-  : createContext(null);
+  : createContext<DocsContextProps<Renderer>>(null!);

code/addons/docs/src/blocks/blocks/DocsSluggerContext.ts

@@ -0,0 +1,12 @@
+import type { Context } from 'react';
+import { createContext } from 'react';
+
+import GithubSlugger from 'github-slugger';
+
+export type DocsSlugger = GithubSlugger;
+
+export const createDocsSlugger = () => new GithubSlugger();
+
+export const DocsSluggerContext: Context<DocsSlugger | null> = createContext<DocsSlugger | null>(
+  null
+);

code/addons/docs/src/blocks/blocks/Heading.tsx

@@ -5,13 +5,15 @@ import { H2 } from 'storybook/internal/components';
 
 import GithubSlugger from 'github-slugger';
 
+import { DocsSluggerContext } from './DocsSluggerContext';
 import { HeaderMdx } from './mdx';
 import { withMdxComponentOverride } from './with-mdx-component-override';
 
 export interface HeadingProps {
   disableAnchor?: boolean;
 }
 
+// Preserve the legacy singleton when Heading is rendered outside a Docs tree.
 export const slugs = new GithubSlugger();
 
 const HeadingImpl: FC<PropsWithChildren<HeadingProps>> = ({
@@ -22,7 +24,8 @@ const HeadingImpl: FC<PropsWithChildren<HeadingProps>> = ({
   if (disableAnchor || typeof children !== 'string') {
     return <H2>{children}</H2>;
   }
-  const tagID = slugs.slug(children.toLowerCase());
+  const slugger = React.useContext(DocsSluggerContext) ?? slugs;
+  const tagID = slugger.slug(children.toLowerCase());
   return (
     <HeaderMdx as="h2" id={tagID} {...props}>
       {children}

code/addons/docs/src/blocks/blocks/Subheading.tsx

@@ -5,14 +5,16 @@ import { H3 } from 'storybook/internal/components';
 
 import type { HeadingProps } from './Heading';
 import { slugs } from './Heading';
+import { DocsSluggerContext } from './DocsSluggerContext';
 import { HeaderMdx } from './mdx';
 import { withMdxComponentOverride } from './with-mdx-component-override';
 
 const SubheadingImpl: FC<PropsWithChildren<HeadingProps>> = ({ children, disableAnchor }) => {
   if (disableAnchor || typeof children !== 'string') {
     return <H3>{children}</H3>;
   }
-  const tagID = slugs.slug(children.toLowerCase());
+  const slugger = React.useContext(DocsSluggerContext) ?? slugs;
+  const tagID = slugger.slug(children.toLowerCase());
   return (
     <HeaderMdx as="h3" id={tagID}>
       {children}

code/addons/docs/src/typings.d.ts

@@ -3,8 +3,10 @@ declare module 'acorn-jsx';
 declare module 'vue/dist/vue';
 
 declare var FEATURES: import('storybook/internal/types').StorybookConfigRaw['features'];
-declare var __DOCS_CONTEXT__: any;
-declare var PREVIEW_URL: any;
+declare var __DOCS_CONTEXT__: import('react').Context<
+  import('storybook/internal/types').DocsContextProps<import('storybook/internal/types').Renderer>
+>;
+declare var PREVIEW_URL: string | undefined;
 declare var LOGLEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
 declare var TAGS_OPTIONS: import('storybook/internal/types').TagsOptions;