feat: toc as dsfr side menu

Author: lsagetlethias

.storybook/DocsContainer.tsx

@@ -12,6 +12,7 @@ import { useIsDark } from "../dist/useIsDark";
 import { startReactDsfr } from "../dist/spa";
 import { fr } from "../dist/fr";
 import { MuiDsfrThemeProvider } from "../dist/mui";
+import { TableOfContentsCustom, TocType } from "./TableOfContents";
 
 startReactDsfr({
     "defaultColorScheme": "system",
@@ -28,6 +29,16 @@ export const DocsContainer = ({ children, context }: PropsWithChildren<DocsConta
 
     const backgroundColor = fr.colors.decisions.background.default.grey.default;
 
+    // took from addon-docs/src/blocks/DocsContainer.tsx
+    let toc: TocType | undefined;
+    try {
+        const meta = context.resolveOf("meta", ["meta"]);
+        toc = meta.preparedMeta.parameters?.docs?.toc;
+    } catch (err) {
+        // No meta, falling back to project annotations
+        toc = context?.projectAnnotations?.parameters?.docs?.toc;
+    }
+
     return (
         <>
             <style>{`
@@ -54,7 +65,10 @@ export const DocsContainer = ({ children, context }: PropsWithChildren<DocsConta
             `}</style>
             <BaseContainer context={context} theme={isStorybookUiDark ? darkTheme : lightTheme}>
                 <MuiDsfrThemeProvider>
-                    <Unstyled>{children}</Unstyled>
+                    <Unstyled>
+                        {toc && <TableOfContentsCustom channel={context.channel} />}
+                        {children}
+                    </Unstyled>
                 </MuiDsfrThemeProvider>
             </BaseContainer>
         </>

.storybook/Stories.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+import { Stories as BaseStories } from "@storybook/addon-docs/blocks";
+import { type PropsOf } from "@emotion/react";
+
+export const Stories = (props: PropsOf<typeof BaseStories>) => {
+    return <BaseStories {...props} />;
+};

.storybook/TableOfContents.tsx

@@ -0,0 +1,156 @@
+import { styled } from "storybook/theming";
+import SideMenu, { SideMenuProps } from "../dist/SideMenu";
+import Channel from "storybook/internal/channels";
+import { NAVIGATE_URL } from "storybook/internal/core-events";
+import React, { useEffect, useState } from "react";
+import { DocsTypes } from "@storybook/addon-docs";
+
+export type TocType = Exclude<Required<DocsTypes["parameters"]>["docs"]["toc"], undefined>;
+
+const Aside = styled.div`
+    position: fixed;
+    right: 4rem;
+    top: 0;
+    bottom: 0;
+    width: 16rem;
+    z-index: 1;
+    overflow: auto;
+    padding-top: 4rem;
+    padding-bottom: 2rem;
+    padding-left: 1rem;
+    padding-right: 1rem;
+
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+    -webkit-overflow-scrolling: touch;
+
+    @media (max-width: 768px) {
+        display: none;
+    }
+
+    & .fr-sidemenu__inner {
+        padding: 0;
+    }
+
+    & .fr-sidemenu__link {
+        padding: 0.5rem 0.75rem;
+    }
+`;
+
+/**
+ * Hook pour détecter le heading actuellement visible avec IntersectionObserver
+ */
+function useActiveHeading(headings: HTMLHeadingElement[]) {
+    const [activeId, setActiveId] = useState<string>("");
+
+    useEffect(() => {
+        if (headings.length === 0) return;
+
+        // Map pour stocker les ratios d'intersection de chaque heading
+        const headingObservers = new Map<string, number>();
+
+        const observer = new IntersectionObserver(
+            entries => {
+                // Mettre à jour le ratio d'intersection pour chaque heading observé
+                entries.forEach(entry => {
+                    const id = entry.target.id;
+                    if (entry.isIntersecting) {
+                        headingObservers.set(id, entry.intersectionRatio);
+                    } else {
+                        headingObservers.set(id, 0);
+                    }
+                });
+
+                // Trouver le heading avec le plus grand ratio d'intersection
+                let maxRatio = 0;
+                let activeHeadingId = "";
+
+                headingObservers.forEach((ratio, id) => {
+                    if (ratio > maxRatio) {
+                        maxRatio = ratio;
+                        activeHeadingId = id;
+                    }
+                });
+
+                // Ne mettre à jour que si on a trouvé un heading visible
+                // Sinon on garde l'état précédent
+                if (activeHeadingId && activeHeadingId !== activeId) {
+                    setActiveId(activeHeadingId);
+                } else if (!activeId && headings.length > 0) {
+                    // Cas initial : si aucun heading n'est actif encore, prendre le premier
+                    setActiveId(headings[0].id);
+                }
+            },
+            {
+                // rootMargin négatif = créer une zone "active" au centre du viewport
+                // "-20% 0px -35% 0px" = zone active entre 20% du haut et 65% du bas
+                rootMargin: "-20% 0px -35% 0px",
+                threshold: [0, 0.25, 0.5, 0.75, 1] // Observer à différents niveaux de visibilité
+            }
+        );
+
+        // Observer tous les headings
+        headings.forEach(heading => {
+            if (heading.id) {
+                observer.observe(heading);
+                headingObservers.set(heading.id, 0);
+            }
+        });
+
+        return () => {
+            observer.disconnect();
+        };
+    }, [headings, activeId]);
+
+    return activeId;
+}
+
+interface TableOfContentsCustomProps {
+    channel: Channel;
+}
+
+export const TableOfContentsCustom = ({ channel }: TableOfContentsCustomProps) => {
+    const [headingElements, setHeadingElements] = useState<HTMLHeadingElement[]>([]);
+
+    // Initialiser les headings une seule fois
+    useEffect(() => {
+        const contentElement = document.querySelector(".sbdocs-content");
+        const elements = Array.from(
+            contentElement?.querySelectorAll<HTMLHeadingElement>(
+                "h3:not(.docs-story *, .skip-toc)"
+            ) ?? []
+        );
+        setHeadingElements(elements);
+    }, []);
+
+    // Utiliser le hook pour tracker l'ID actif
+    const activeId = useActiveHeading(headingElements);
+
+    // Créer les items avec isActive
+    const headings = headingElements.map<SideMenuProps.Item>(heading => ({
+        text: (heading.innerText || heading.textContent).trim(),
+        isActive: heading.id === activeId,
+        linkProps: {
+            href: `#${heading.id}`,
+            onClick(e) {
+                e.preventDefault();
+                if (e.currentTarget instanceof HTMLAnchorElement) {
+                    const [, headerId] = e.currentTarget.href.split("#");
+                    if (headerId) {
+                        channel.emit(NAVIGATE_URL, { url: `#${headerId}` });
+                        document.querySelector(`#${heading.id}`)?.scrollIntoView({
+                            behavior: "smooth"
+                        });
+                    }
+                }
+            }
+        }
+    }));
+
+    return (
+        <Aside>
+            <SideMenu align="right" burgerMenuButtonText="Table des matières" items={headings} />
+        </Aside>
+    );
+};

.storybook/preview-head.html

@@ -46,4 +46,8 @@
     .sb-argstableBlock-body button {
         background-color: var(--background-alt-grey);
     }
+
+    .sbdocs-toc--custom {
+        display: none;
+    }
 </style>

package.json

@@ -23,6 +23,7 @@
         "format": "yarn _format --write",
         "format:check": "yarn _format --list-different",
         "storybook": "storybook dev -p 6006",
+        "storybook:dev": "storybook dev -p 6006",
         "build-storybook": "storybook build",
         "prestorybook": "yarn build && node dist/bin/react-dsfr update-icons",
         "prebuild-storybook": "yarn prestorybook"