[docs] WIP: Fix HTML validation issues from link-check

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);

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',

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{' '}

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>;

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>

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,15 +47,15 @@ export function RowHeader({
       className={clsx('TableCell', className)}
       {...other}
     >
-      <span className="TableCellInner">{children}</span>
+      <div className="TableCellInner">{children}</div>
     </th>
   );
 }
 
 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>
   );
 }