From ca035d8562708b4bab81d958bac839d7de3ed741 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= <slorber@users.noreply.github.com>
Date: Fri, 21 Feb 2025 19:03:49 +0100
Subject: [PATCH] feat(theme): add theme layout stable CSS classes (#10945)

---
 .../src/theme/AnnouncementBar/index.tsx       |  8 ++++--
 .../src/theme/Footer/Layout/index.tsx         |  3 ++-
 .../theme/Footer/Links/MultiColumn/index.tsx  |  8 +++++-
 .../src/theme/Layout/index.tsx                |  1 +
 .../src/theme/Navbar/Content/index.tsx        | 23 +++++++++++++---
 .../src/theme/Navbar/Layout/index.tsx         |  3 ++-
 .../Navbar/MobileSidebar/Layout/index.tsx     | 23 +++++++++++++---
 .../src/utils/ThemeClassNames.ts              | 27 +++++++++++++++++--
 8 files changed, 83 insertions(+), 13 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/AnnouncementBar/index.tsx b/packages/docusaurus-theme-classic/src/theme/AnnouncementBar/index.tsx
index ddea4e602c..d2f54e2525 100644
--- a/packages/docusaurus-theme-classic/src/theme/AnnouncementBar/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/AnnouncementBar/index.tsx
@@ -6,7 +6,8 @@
  */
 
 import React, {type ReactNode} from 'react';
-import {useThemeConfig} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+import {ThemeClassNames, useThemeConfig} from '@docusaurus/theme-common';
 import {useAnnouncementBar} from '@docusaurus/theme-common/internal';
 import AnnouncementBarCloseButton from '@theme/AnnouncementBar/CloseButton';
 import AnnouncementBarContent from '@theme/AnnouncementBar/Content';
@@ -22,7 +23,10 @@ export default function AnnouncementBar(): ReactNode {
   const {backgroundColor, textColor, isCloseable} = announcementBar!;
   return (
     <div
-      className={styles.announcementBar}
+      className={clsx(
+        ThemeClassNames.announcementBar.container,
+        styles.announcementBar,
+      )}
       style={{backgroundColor, color: textColor}}
       role="banner">
       {isCloseable && <div className={styles.announcementBarPlaceholder} />}
diff --git a/packages/docusaurus-theme-classic/src/theme/Footer/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Footer/Layout/index.tsx
index 01d337628e..ae9c42b606 100644
--- a/packages/docusaurus-theme-classic/src/theme/Footer/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Footer/Layout/index.tsx
@@ -7,6 +7,7 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Footer/Layout';
 
 export default function FooterLayout({
@@ -17,7 +18,7 @@ export default function FooterLayout({
 }: Props): ReactNode {
   return (
     <footer
-      className={clsx('footer', {
+      className={clsx(ThemeClassNames.layout.footer.container, 'footer', {
         'footer--dark': style === 'dark',
       })}>
       <div className="container container-fluid">
diff --git a/packages/docusaurus-theme-classic/src/theme/Footer/Links/MultiColumn/index.tsx b/packages/docusaurus-theme-classic/src/theme/Footer/Links/MultiColumn/index.tsx
index ebeb004e9d..570ec44554 100644
--- a/packages/docusaurus-theme-classic/src/theme/Footer/Links/MultiColumn/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Footer/Links/MultiColumn/index.tsx
@@ -7,6 +7,7 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import LinkItem from '@theme/Footer/LinkItem';
 import type {Props} from '@theme/Footer/Links/MultiColumn';
 
@@ -30,7 +31,12 @@ function ColumnLinkItem({item}: {item: ColumnItemType}) {
 
 function Column({column}: {column: ColumnType}) {
   return (
-    <div className={clsx('col footer__col', column.className)}>
+    <div
+      className={clsx(
+        ThemeClassNames.layout.footer.column,
+        'col footer__col',
+        column.className,
+      )}>
       <div className="footer__title">{column.title}</div>
       <ul className="footer__items clean-list">
         {column.items.map((item, i) => (
diff --git a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
index c51cbcc36d..44cc033e1c 100644
--- a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
@@ -48,6 +48,7 @@ export default function Layout(props: Props): ReactNode {
       <div
         id={SkipToContentFallbackId}
         className={clsx(
+          ThemeClassNames.layout.main,
           ThemeClassNames.wrapper.main,
           styles.mainWrapper,
           wrapperClassName,
diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/Content/index.tsx b/packages/docusaurus-theme-classic/src/theme/Navbar/Content/index.tsx
index b4fcc735ab..10c97a7632 100644
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/Content/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/Content/index.tsx
@@ -6,7 +6,12 @@
  */
 
 import React, {type ReactNode} from 'react';
-import {useThemeConfig, ErrorCauseBoundary} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+import {
+  useThemeConfig,
+  ErrorCauseBoundary,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
 import {
   splitNavbarItems,
   useNavbarMobileSidebar,
@@ -55,8 +60,20 @@ function NavbarContentLayout({
 }) {
   return (
     <div className="navbar__inner">
-      <div className="navbar__items">{left}</div>
-      <div className="navbar__items navbar__items--right">{right}</div>
+      <div
+        className={clsx(
+          ThemeClassNames.layout.navbar.containerLeft,
+          'navbar__items',
+        )}>
+        {left}
+      </div>
+      <div
+        className={clsx(
+          ThemeClassNames.layout.navbar.containerRight,
+          'navbar__items navbar__items--right',
+        )}>
+        {right}
+      </div>
     </div>
   );
 }
diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Navbar/Layout/index.tsx
index 7ec271d9df..bc05e51542 100644
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/Layout/index.tsx
@@ -7,7 +7,7 @@
 
 import React, {type ComponentProps, type ReactNode} from 'react';
 import clsx from 'clsx';
-import {useThemeConfig} from '@docusaurus/theme-common';
+import {ThemeClassNames, useThemeConfig} from '@docusaurus/theme-common';
 import {
   useHideableNavbar,
   useNavbarMobileSidebar,
@@ -43,6 +43,7 @@ export default function NavbarLayout({children}: Props): ReactNode {
         description: 'The ARIA label for the main navigation',
       })}
       className={clsx(
+        ThemeClassNames.layout.navbar.container,
         'navbar',
         'navbar--fixed-top',
         hideOnScroll && [
diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Layout/index.tsx
index 27627fdbd3..9d623fcd83 100644
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Layout/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Layout/index.tsx
@@ -8,8 +8,21 @@
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {useNavbarSecondaryMenu} from '@docusaurus/theme-common/internal';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Navbar/MobileSidebar/Layout';
 
+function NavbarMobileSidebarPanel({children}: {children: ReactNode}) {
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.layout.navbar.mobileSidebar.panel,
+        'navbar-sidebar__item menu',
+      )}>
+      {children}
+    </div>
+  );
+}
+
 export default function NavbarMobileSidebarLayout({
   header,
   primaryMenu,
@@ -17,14 +30,18 @@ export default function NavbarMobileSidebarLayout({
 }: Props): ReactNode {
   const {shown: secondaryMenuShown} = useNavbarSecondaryMenu();
   return (
-    <div className="navbar-sidebar">
+    <div
+      className={clsx(
+        ThemeClassNames.layout.navbar.mobileSidebar.container,
+        'navbar-sidebar',
+      )}>
       {header}
       <div
         className={clsx('navbar-sidebar__items', {
           'navbar-sidebar__items--show-secondary': secondaryMenuShown,
         })}>
-        <div className="navbar-sidebar__item menu">{primaryMenu}</div>
-        <div className="navbar-sidebar__item menu">{secondaryMenu}</div>
+        <NavbarMobileSidebarPanel>{primaryMenu}</NavbarMobileSidebarPanel>
+        <NavbarMobileSidebarPanel>{secondaryMenu}</NavbarMobileSidebarPanel>
       </div>
     </div>
   );
diff --git a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
index 78539578e6..a0a1834d1c 100644
--- a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
+++ b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
@@ -27,8 +27,10 @@ export const ThemeClassNames = {
 
     mdxPage: 'mdx-page',
   },
+
+  // TODO Docusaurus v4: remove old classes?
   wrapper: {
-    main: 'main-wrapper',
+    main: 'main-wrapper', // replaced by theme-layout-main
     // TODO these wrapper class names are now quite useless
     // TODO do breaking change later in 3.0
     // we already add plugin name/id class on <html>: that's enough
@@ -36,6 +38,7 @@ export const ThemeClassNames = {
     docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
+
   common: {
     editThisPage: 'theme-edit-this-page',
     lastUpdated: 'theme-last-updated',
@@ -47,8 +50,28 @@ export const ThemeClassNames = {
 
     admonitionType: (type: string) => `theme-admonition-${type}`,
   },
+
+  announcementBar: {
+    container: 'theme-announcement-bar',
+  },
+
   layout: {
-    // TODO add other stable classNames here
+    navbar: {
+      container: 'theme-layout-navbar',
+      containerLeft: 'theme-layout-navbar-left',
+      containerRight: 'theme-layout-navbar-right',
+      mobileSidebar: {
+        container: 'theme-layout-navbar-sidebar',
+        panel: 'theme-layout-navbar-sidebar-panel',
+      },
+    },
+    main: {
+      container: 'theme-layout-main',
+    },
+    footer: {
+      container: 'theme-layout-footer',
+      column: 'theme-layout-footer-column',
+    },
   },
 
   /**