From 3a312d964d7b2f67149c8d4abf8390e6d26b5c8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= <slorber@users.noreply.github.com>
Date: Tue, 31 Aug 2021 11:00:46 +0200
Subject: [PATCH]  feat: Add docs-related stable classnames (#5445)

---
 .../src/theme/DocItem/index.tsx               | 20 +++++++++---
 .../src/theme/DocItemFooter/index.tsx         | 12 +++++--
 .../src/theme/DocPage/index.tsx               |  2 +-
 .../src/theme/DocSidebar/index.tsx            |  5 +--
 .../src/theme/DocSidebarItem/index.tsx        | 18 ++++++++---
 .../src/theme/DocTagDocListPage/index.tsx     |  2 +-
 .../src/theme/DocTagsListPage/index.tsx       |  2 +-
 .../src/theme/DocVersionBanner/index.tsx      | 13 ++++++--
 .../src/theme/EditThisPage/index.tsx          |  7 ++++-
 .../src/theme/LastUpdated/index.tsx           |  5 +--
 .../docusaurus-theme-classic/src/types.d.ts   |  1 +
 .../src/utils/ThemeClassNames.ts              | 31 ++++++++++++++++++-
 12 files changed, 96 insertions(+), 22 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx
index d63d254c50..3a93804f52 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx
@@ -20,6 +20,7 @@ import TOCCollapsible from '@theme/TOCCollapsible';
 import {MainHeading} from '@theme/Heading';
 
 import styles from './styles.module.css';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function DocItem(props: Props): JSX.Element {
   const {content: DocContent, versionMetadata} = props;
@@ -67,7 +68,11 @@ export default function DocItem(props: Props): JSX.Element {
           <div className={styles.docItemContainer}>
             <article>
               {showVersionBadge && (
-                <span className="badge badge--secondary">
+                <span
+                  className={clsx(
+                    ThemeClassNames.docs.docVersionBadge,
+                    'badge badge--secondary',
+                  )}>
                   Version: {versionMetadata.label}
                 </span>
               )}
@@ -75,11 +80,15 @@ export default function DocItem(props: Props): JSX.Element {
               {canRenderTOC && (
                 <TOCCollapsible
                   toc={DocContent.toc}
-                  className={styles.tocMobile}
+                  className={clsx(
+                    ThemeClassNames.docs.docTocMobile,
+                    styles.tocMobile,
+                  )}
                 />
               )}
 
-              <div className="markdown">
+              <div
+                className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
                 Title can be declared inside md content or declared through frontmatter and added manually
                 To make both cases consistent, the added title is added under the same div.markdown block
@@ -98,7 +107,10 @@ export default function DocItem(props: Props): JSX.Element {
         </div>
         {renderTocDesktop && (
           <div className="col col--3">
-            <TOC toc={DocContent.toc} />
+            <TOC
+              toc={DocContent.toc}
+              className={ThemeClassNames.docs.docTocDesktop}
+            />
           </div>
         )}
       </div>
diff --git a/packages/docusaurus-theme-classic/src/theme/DocItemFooter/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItemFooter/index.tsx
index 7f7fd01594..86f70ee722 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocItemFooter/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocItemFooter/index.tsx
@@ -16,10 +16,15 @@ import TagsListInline, {
 } from '@theme/TagsListInline';
 
 import styles from './styles.module.css';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function TagsRow(props: TagsListInlineProps) {
   return (
-    <div className="row margin-bottom--sm">
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        'row margin-bottom--sm',
+      )}>
       <div className="col">
         <TagsListInline {...props} />
       </div>
@@ -38,7 +43,7 @@ function EditMetaRow({
   formattedLastUpdatedAt,
 }: EditMetaRowProps) {
   return (
-    <div className="row">
+    <div className={clsx(ThemeClassNames.docs.docFooterEditMetaRow, 'row')}>
       <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
 
       <div className={clsx('col', styles.lastUpdated)}>
@@ -75,7 +80,8 @@ export default function DocItemFooter(props: Props): JSX.Element {
   }
 
   return (
-    <footer className="docusaurus-mt-lg">
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}>
       {canDisplayTagsRow && <TagsRow tags={tags} />}
       {canDisplayEditMetaRow && (
         <EditMetaRow
diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
index d255baad53..8acd5d4dc0 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
@@ -55,7 +55,7 @@ function DocPageContent({
 
   return (
     <Layout
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsDocPage}
       searchMetadatas={{
         version,
diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx
index 82f0b48ba1..702e7a54ca 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx
@@ -12,6 +12,7 @@ import {
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
   MobileSecondaryMenuComponent,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import useScrollPosition from '@theme/hooks/useScrollPosition';
@@ -78,7 +79,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
           [styles.menuWithAnnouncementBar]:
             !isAnnouncementBarClosed && showAnnouncementBar,
         })}>
-        <ul className="menu__list">
+        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
           <DocSidebarItems items={sidebar} activePath={path} />
         </ul>
       </nav>
@@ -93,7 +94,7 @@ const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
   path,
 }) => {
   return (
-    <ul className="menu__list">
+    <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
       <DocSidebarItems
         items={sidebar}
         activePath={path}
diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx
index 4a907aaaf2..98e109eceb 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx
@@ -12,6 +12,7 @@ import {
   usePrevious,
   Collapsible,
   useCollapsible,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
@@ -117,9 +118,13 @@ function DocSidebarItemCategory({
 
   return (
     <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+      )}>
       {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
       <a
         className={clsx('menu__link', {
@@ -161,7 +166,12 @@ function DocSidebarItemLink({
   const {href, label} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   return (
-    <li className="menu__list-item" key={label}>
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        'menu__list-item',
+      )}
+      key={label}>
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
index 7c1985bea4..b72e39ab01 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
@@ -63,7 +63,7 @@ export default function DocTagDocListPage({tag}: Props): JSX.Element {
   return (
     <Layout
       title={title}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagDocListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
index 780faa8911..7c5348f12a 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
@@ -20,7 +20,7 @@ function DocTagsListPage({tags}: Props): JSX.Element {
   return (
     <Layout
       title={title}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagsListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
diff --git a/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx
index 751bae67ff..eebbe862bd 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx
@@ -14,9 +14,13 @@ import {
   useDocVersionSuggestions,
   GlobalVersion,
 } from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+} from '@docusaurus/theme-common';
 
 import type {Props} from '@theme/DocVersionBanner';
+import clsx from 'clsx';
 
 type BannerLabelComponentProps = {
   siteTitle: string;
@@ -131,7 +135,12 @@ function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
 
   return (
-    <div className="alert alert--warning margin-bottom--md" role="alert">
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docVersionBanner,
+        'alert alert--warning margin-bottom--md',
+      )}
+      role="alert">
       <div>
         <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
diff --git a/packages/docusaurus-theme-classic/src/theme/EditThisPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/EditThisPage/index.tsx
index 8b02281ca4..5fda42f876 100644
--- a/packages/docusaurus-theme-classic/src/theme/EditThisPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/EditThisPage/index.tsx
@@ -10,10 +10,15 @@ import Translate from '@docusaurus/Translate';
 
 import type {Props} from '@theme/EditThisPage';
 import IconEdit from '@theme/IconEdit';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   return (
-    <a href={editUrl} target="_blank" rel="noreferrer noopener">
+    <a
+      href={editUrl}
+      target="_blank"
+      rel="noreferrer noopener"
+      className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"
diff --git a/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx b/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx
index 7ed0de65eb..42e6d478fb 100644
--- a/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx
@@ -8,6 +8,7 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/LastUpdated';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function LastUpdatedAtDate({
   lastUpdatedAt,
@@ -57,7 +58,7 @@ export default function LastUpdated({
   lastUpdatedBy,
 }: Props): JSX.Element {
   return (
-    <>
+    <span className={ThemeClassNames.common.lastUpdated}>
       <Translate
         id="theme.lastUpdated.lastUpdatedAtBy"
         description="The sentence used to display when a page has been last updated, and by who"
@@ -84,6 +85,6 @@ export default function LastUpdated({
           <small> (Simulated during dev for better perf)</small>
         </div>
       )}
-    </>
+    </span>
   );
 }
diff --git a/packages/docusaurus-theme-classic/src/types.d.ts b/packages/docusaurus-theme-classic/src/types.d.ts
index a39d5af3bb..94a74419ed 100644
--- a/packages/docusaurus-theme-classic/src/types.d.ts
+++ b/packages/docusaurus-theme-classic/src/types.d.ts
@@ -579,6 +579,7 @@ declare module '@theme/TOC' {
 
   export type TOCProps = {
     readonly toc: readonly TOCItem[];
+    readonly className?: string;
   };
 
   export type TOCHeadingsProps = {
diff --git a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
index 700bd66398..b33c249372 100644
--- a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
+++ b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
@@ -6,6 +6,8 @@
  */
 
 // These class names are used to style page layouts in Docusaurus
+// Those are meant to be targeted by user-provided custom CSS selectors
+// /!\ Please do not modify the classnames! This is a breaking change, and annoying for users!
 export const ThemeClassNames = {
   page: {
     blogListPage: 'blog-list-page',
@@ -22,7 +24,34 @@ export const ThemeClassNames = {
   wrapper: {
     main: 'main-wrapper',
     blogPages: 'blog-wrapper',
-    docPages: 'docs-wrapper',
+    docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
+
+  // /!\ Please keep the naming convention consistent!
+  // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+  common: {
+    editThisPage: 'theme-edit-this-page',
+    lastUpdated: 'theme-last-updated',
+  },
+  layout: {
+    // TODO add other stable classNames here
+  },
+  docs: {
+    docVersionBanner: 'theme-doc-version-banner',
+    docVersionBadge: 'theme-doc-version-badge',
+    docMarkdown: 'theme-doc-markdown',
+    docTocMobile: 'theme-doc-toc-mobile',
+    docTocDesktop: 'theme-doc-toc-desktop',
+    docFooter: 'theme-doc-footer',
+    docFooterTagsRow: 'theme-doc-footer-tags-row',
+    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+    docSidebarMenu: 'theme-doc-sidebar-menu',
+    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+    docSidebarItemLink: 'theme-doc-sidebar-item-link',
+    // TODO add other stable classNames here
+  },
+  blog: {
+    // TODO add other stable classNames here
+  },
 };