Add real-time MEV and gas refund metrics to navbar

- Add comprehensive refund metrics widget showing MEV and gas refund totals
- Fetch live data from configurable Dune Analytics API with feature flag support
- Use navbar__item class for seamless Docusaurus framework integration
- Perfect typography: regular labels, semibold values (font-weight: 500) matching navbar links
- Display format: 'Refund | MEV: X.XX ETH | Gas: X.XX ETH' with separators
- Include click handler redirecting to Dune analytics dashboard
- Responsive design with mobile hide behavior
- Robust error handling with graceful degradation

Technical implementation:
- Multi-metric layout with proper flex alignment and baseline typography
- Custom navbar component following Docusaurus integration patterns
- Server-side rendering compatible with runtime feature flag control
- Minimal CSS leveraging framework styles for consistent appearance

Author: odysseus0

docusaurus.config.js

@@ -69,6 +69,10 @@ module.exports = async function createConfigAsync() {
               sidebarId: 'api',
               position: 'left',
             },
+            {
+              type: 'custom-mevMetrics',
+              position: 'right',
+            },
             {
               href: 'https://github.com/flashbots/docs',
               label: 'GitHub',
@@ -116,5 +120,9 @@ module.exports = async function createConfigAsync() {
       },
       'docusaurus-plugin-sass'
     ],
+    customFields: {
+      refundMetricsApiUrl: 'https://refund-metrics-dune-api.vercel.app',
+      refundMetricsRedirectUrl: 'https://protect.flashbots.net/',
+    },
   }
 }

src/components/MevMetrics.module.css

@@ -0,0 +1,44 @@
+.container {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: var(--ifm-navbar-link-color);
+}
+
+.metric {
+  display: flex;
+  align-items: baseline;
+  gap: 0.25rem;
+}
+
+.value {
+  font-weight: 500;
+}
+
+.loading {
+  opacity: 0.5;
+}
+
+.separator {
+  color: var(--ifm-navbar-link-color);
+  opacity: 0.3;
+}
+
+.clickable {
+  cursor: pointer;
+  transition: opacity 0.2s ease;
+}
+
+.clickable:hover {
+  opacity: 0.8;
+}
+
+.clickable:active {
+  opacity: 0.6;
+}
+
+@media (max-width: 996px) {
+  .container {
+    display: none !important;
+  }
+}

src/components/MevMetrics.tsx

@@ -0,0 +1,92 @@
+import React, { useEffect, useState } from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import styles from './MevMetrics.module.css';
+
+interface MetricsResponse {
+  totalMevRefund: number;
+  totalGasRefund: number;
+  fetchedAt: string;
+  stale: boolean;
+  showWidget?: boolean;
+}
+
+export default function MevMetrics(): JSX.Element | null {
+  const { siteConfig } = useDocusaurusContext();
+  const [data, setData] = useState<MetricsResponse | null>(null);
+  const [showWidget, setShowWidget] = useState(true);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const fetchMetrics = async () => {
+      try {
+        const apiUrl = siteConfig.customFields?.refundMetricsApiUrl as string;
+        const response = await fetch(`${apiUrl}/api/metrics`);
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        const metrics: MetricsResponse = await response.json();
+        
+        // Check feature flag
+        if (metrics.showWidget === false) {
+          setShowWidget(false);
+          setLoading(false);
+          return;
+        }
+        
+        setData(metrics);
+      } catch (error) {
+        console.error('Error fetching MEV metrics:', error);
+        // Don't show widget on error
+        setData(null);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchMetrics();
+  }, []);
+
+  const formatValue = (value: number): string => {
+    return `${value.toFixed(2)} ETH`;
+  };
+
+  const handleClick = () => {
+    const redirectUrl = siteConfig.customFields?.refundMetricsRedirectUrl as string;
+    window.open(redirectUrl, '_blank', 'noopener,noreferrer');
+  };
+
+  // Hide widget if flag says so or if no data
+  if (!showWidget || (!loading && !data)) {
+    return null;
+  }
+
+  return (
+    <div 
+      className={`navbar__item ${styles.container} ${styles.clickable}`}
+        onClick={handleClick}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            handleClick();
+          }
+        }}
+      >
+      <span className={styles.label}>Refund</span>
+      <span className={styles.separator}>|</span>
+      <div className={styles.metric}>
+        <span className={styles.label}>MEV:</span>
+        <span className={`${styles.value} ${loading ? styles.loading : ''}`}>
+          {loading ? '...' : data && formatValue(data.totalMevRefund)}
+        </span>
+      </div>
+      <span className={styles.separator}>|</span>
+      <div className={styles.metric}>
+        <span className={styles.label}>Gas:</span>
+        <span className={`${styles.value} ${loading ? styles.loading : ''}`}>
+          {loading ? '...' : data && formatValue(data.totalGasRefund)}
+        </span>
+      </div>
+    </div>
+  );
+}

src/theme/NavbarItem/ComponentTypes.tsx

@@ -0,0 +1,27 @@
+import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
+import LocaleDropdownNavbarItem from '@theme/NavbarItem/LocaleDropdownNavbarItem';
+import SearchNavbarItem from '@theme/NavbarItem/SearchNavbarItem';
+import HtmlNavbarItem from '@theme/NavbarItem/HtmlNavbarItem';
+import DocNavbarItem from '@theme/NavbarItem/DocNavbarItem';
+import DocSidebarNavbarItem from '@theme/NavbarItem/DocSidebarNavbarItem';
+import DocsVersionNavbarItem from '@theme/NavbarItem/DocsVersionNavbarItem';
+import DocsVersionDropdownNavbarItem from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
+import MevMetrics from '@site/src/components/MevMetrics';
+
+import type {ComponentTypesObject} from '@theme/NavbarItem/ComponentTypes';
+
+const ComponentTypes: ComponentTypesObject = {
+  default: DefaultNavbarItem,
+  localeDropdown: LocaleDropdownNavbarItem,
+  search: SearchNavbarItem,
+  dropdown: DropdownNavbarItem,
+  html: HtmlNavbarItem,
+  doc: DocNavbarItem,
+  docSidebar: DocSidebarNavbarItem,
+  docsVersion: DocsVersionNavbarItem,
+  docsVersionDropdown: DocsVersionDropdownNavbarItem,
+  'custom-mevMetrics': MevMetrics,
+};
+
+export default ComponentTypes;