From 509c759c3feb54c8e4e18e7d5ef9f9603a908e02 Mon Sep 17 00:00:00 2001
From: Janpot <2109932+Janpot@users.noreply.github.com>
Date: Mon, 4 May 2026 14:35:21 +0200
Subject: [PATCH] [docs] WIP: Fix HTML validation issues from link-check

---
 docs/scripts/reportBrokenLinks.mts                     |  9 +++++++++
 docs/src/components/CodeBlock/CodeBlock.tsx            | 10 +++++++---
 docs/src/components/ReferenceTable/AdditionalTypes.tsx |  4 ++--
 docs/src/components/ReferenceTable/ReferenceTable.tsx  |  2 +-
 docs/src/components/Search/SearchBar.tsx               |  4 ++--
 docs/src/components/Table.tsx                          |  6 +++---
 6 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/scripts/reportBrokenLinks.mts b/docs/scripts/reportBrokenLinks.mts
index 48c1cb89506..e2124265246 100644
--- a/docs/scripts/reportBrokenLinks.mts
+++ b/docs/scripts/reportBrokenLinks.mts
@@ -8,6 +8,15 @@ async function main() {
     ignoredPaths: [],
     // CSS selectors for content to ignore during link checking
     ignoredContent: [],
+    htmlValidate: {
+      extends: ['mui:recommended'],
+      rules: {
+        // Portaled elements (Menu, Select, Autocomplete listbox) and Base UI
+        // components render aria-controls/aria-labelledby targets only after
+        // client hydration, so they're missing from the static HTML.
+        'no-missing-references': 'off',
+      },
+    },
   });
 
   process.exit(issues.length);
diff --git a/docs/src/components/CodeBlock/CodeBlock.tsx b/docs/src/components/CodeBlock/CodeBlock.tsx
index 84a8542c237..1eadc7eeb7e 100644
--- a/docs/src/components/CodeBlock/CodeBlock.tsx
+++ b/docs/src/components/CodeBlock/CodeBlock.tsx
@@ -10,7 +10,10 @@ import { CheckIcon } from '../../icons/CheckIcon';
 import { GhostButton } from '../GhostButton';
 import './CodeBlock.css';
 
-const CodeBlockContext = React.createContext({ codeId: '', titleId: '' });
+const CodeBlockContext = React.createContext<{
+  codeId: string | undefined;
+  titleId: string | undefined;
+}>({ codeId: undefined, titleId: undefined });
 
 export function Root(props: React.ComponentPropsWithoutRef<'div'>) {
   const titleId = React.useId();
@@ -56,12 +59,13 @@ export function Panel({ className, title, children, ...other }: CodeBlockPanelPr
       <GhostButton
         aria-label="Copy code"
         onClick={async () => {
-          const codeRoot = document.getElementById(codeId);
+          const codeRoot = codeId ? document.getElementById(codeId) : null;
           const code = codeRoot?.querySelector('pre code')?.textContent ?? codeRoot?.textContent;
 
           if (code) {
             await copy(code);
-            const titleText = document.getElementById(titleId)?.textContent ?? undefined;
+            const titleText =
+              (titleId ? document.getElementById(titleId)?.textContent : undefined) ?? undefined;
             const codeBlockId = titleText ? `${pathname}#${titleText}` : pathname;
             ga?.trackEvent({
               category: 'code_block',
diff --git a/docs/src/components/ReferenceTable/AdditionalTypes.tsx b/docs/src/components/ReferenceTable/AdditionalTypes.tsx
index 63589cc372e..7924f0bdd4c 100644
--- a/docs/src/components/ReferenceTable/AdditionalTypes.tsx
+++ b/docs/src/components/ReferenceTable/AdditionalTypes.tsx
@@ -41,7 +41,7 @@ export function AdditionalTypes({
             additionalType.slug && show?.includes(additionalType.slug) ? 'true' : undefined
           }
         >
-          <h4 className="ReferenceSectionHeading AdditionalTypeHeading">
+          <h3 className="ReferenceSectionHeading AdditionalTypeHeading">
             {additionalType.name}
             <a
               href="#"
@@ -53,7 +53,7 @@ export function AdditionalTypes({
             >
               {hydrated && canGoBack ? 'Back' : 'Hide'}
             </a>
-          </h4>
+          </h3>
           {additionalType.data.reExportOf ? (
             <p className="AdditionalTypeReExport">
               Re-Export of{' '}
diff --git a/docs/src/components/ReferenceTable/ReferenceTable.tsx b/docs/src/components/ReferenceTable/ReferenceTable.tsx
index 42ab1ec99cb..2f6532c5776 100644
--- a/docs/src/components/ReferenceTable/ReferenceTable.tsx
+++ b/docs/src/components/ReferenceTable/ReferenceTable.tsx
@@ -12,7 +12,7 @@ import { AdditionalTypes } from './AdditionalTypes';
 import * as CodeBlock from '../CodeBlock';
 
 function SectionHeading({ children }: { children: React.ReactNode }) {
-  return <h4 className="ReferenceSectionHeading">{children}</h4>;
+  return <h3 className="ReferenceSectionHeading">{children}</h3>;
 }
 
 type UseTypesResult = ReturnType<typeof useTypes>;
diff --git a/docs/src/components/Search/SearchBar.tsx b/docs/src/components/Search/SearchBar.tsx
index c0bea0adf87..cd792c7ceb5 100644
--- a/docs/src/components/Search/SearchBar.tsx
+++ b/docs/src/components/Search/SearchBar.tsx
@@ -372,7 +372,7 @@ export function SearchBar({
     <React.Fragment>
       <Button onClick={handleOpenDialog} aria-label="Search" className={`SearchTrigger`}>
         <Search className="SearchTriggerIcon" />
-        <div className="SearchTriggerKbd">
+        <span className="SearchTriggerKbd">
           {showCmdSymbol ? (
             <kbd className="SearchTriggerCmd">⌘</kbd>
           ) : (
@@ -382,7 +382,7 @@ export function SearchBar({
             </React.Fragment>
           )}
           <kbd className="SearchTriggerK">K</kbd>
-        </div>
+        </span>
       </Button>
       <Dialog.Root open={dialogOpen} onOpenChange={handleCloseDialog}>
         <Dialog.Portal>
diff --git a/docs/src/components/Table.tsx b/docs/src/components/Table.tsx
index e6fc434f4ff..7f84d5f640a 100644
--- a/docs/src/components/Table.tsx
+++ b/docs/src/components/Table.tsx
@@ -30,7 +30,7 @@ export function ColumnHeader({
 }: Omit<React.ComponentProps<'th'>, 'scope'>) {
   return (
     <th scope="col" className={clsx('TableColumnHeader', className)} {...other}>
-      <span className="TableCellInner">{children}</span>
+      <div className="TableCellInner">{children}</div>
     </th>
   );
 }
@@ -47,7 +47,7 @@ export function RowHeader({
       className={clsx('TableCell', className)}
       {...other}
     >
-      <span className="TableCellInner">{children}</span>
+      <div className="TableCellInner">{children}</div>
     </th>
   );
 }
@@ -55,7 +55,7 @@ export function RowHeader({
 export function Cell({ children, className, ...other }: React.ComponentProps<'td'>) {
   return (
     <td ref={observeScrollableInner} className={clsx('TableCell', className)} {...other}>
-      <span className="TableCellInner">{children}</span>
+      <div className="TableCellInner">{children}</div>
     </td>
   );
 }