docs/src/theme/Root.js - superset - Git at Google

 /**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
 import { useEffect } from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

 // File extensions to track as downloads
 const DOWNLOAD_EXTENSIONS = [
   'pdf',
   'zip',
   'tar',
   'gz',
   'tgz',
   'bz2',
   'exe',
   'dmg',
   'pkg',
   'deb',
   'rpm',
   'doc',
   'docx',
   'xls',
   'xlsx',
   'ppt',
   'pptx',
   'csv',
   'json',
   'yaml',
   'yml',
 ];

 // Scroll depth milestones to track
 const SCROLL_MILESTONES = [25, 50, 75, 100];

 export default function Root({ children }) {
   const { siteConfig } = useDocusaurusContext();
   const { customFields } = siteConfig;

   useEffect(() => {
     const { matomoUrl, matomoSiteId } = customFields;

     if (typeof window !== 'undefined') {
       const devMode = ['localhost', '127.0.0.1', '::1', '0.0.0.0'].includes(
         window.location.hostname,
       );

       // Initialize the _paq array
       window._paq = window._paq || [];

       // Configure the tracker before loading matomo.js
       window._paq.push(['enableHeartBeatTimer']);
       window._paq.push(['enableLinkTracking']);
       window._paq.push(['setTrackerUrl', `${matomoUrl}/matomo.php`]);
       window._paq.push(['setSiteId', matomoSiteId]);

       // Track downloads with custom extensions
       window._paq.push([
         'setDownloadExtensions',
         DOWNLOAD_EXTENSIONS.join('|'),
       ]);

       // Now load the matomo.js script
       const script = document.createElement('script');
       script.async = true;
       script.src = `${matomoUrl}/matomo.js`;
       document.head.appendChild(script);

       // Helper to track events
       const trackEvent = (category, action, name, value) => {
         if (devMode) {
           console.log('Matomo trackEvent:', { category, action, name, value });
         }
         window._paq.push(['trackEvent', category, action, name, value]);
       };

       // Helper to track site search
       const trackSiteSearch = (keyword, category, resultsCount) => {
         if (devMode) {
           console.log('Matomo trackSiteSearch:', {
             keyword,
             category,
             resultsCount,
           });
         }
         window._paq.push(['trackSiteSearch', keyword, category, resultsCount]);
       };

       // Helper to track page views
       const trackPageView = (url, title) => {
         if (devMode) {
           console.log('Matomo trackPageView:', { url, title });
         }
         window._paq.push(['trackPageView']);
       };

       // Track external link clicks using domain as category (vendor-agnostic)
       const handleLinkClick = event => {
         const link = event.target.closest('a');
         if (!link) return;

         const href = link.getAttribute('href');
         if (!href) return;

         try {
           const url = new URL(href, window.location.origin);

           // Skip internal links
           if (url.hostname === window.location.hostname) return;

           // Use hostname as category for vendor-agnostic tracking
           trackEvent('Outbound Link', url.hostname, href);
         } catch {
           // Invalid URL, skip tracking
         }
       };

       // Track Algolia search queries
       const setupAlgoliaTracking = () => {
         const observer = new MutationObserver(mutations => {
           mutations.forEach(mutation => {
             mutation.addedNodes.forEach(node => {
               if (node.nodeType === Node.ELEMENT_NODE) {
                 const searchInput =
                   node.querySelector?.('.DocSearch-Input') ||
                   (node.classList?.contains('DocSearch-Input') ? node : null);
                 if (searchInput) {
                   let debounceTimer;
                   searchInput.addEventListener('input', e => {
                     clearTimeout(debounceTimer);
                     debounceTimer = setTimeout(() => {
                       const query = e.target.value.trim();
                       if (query.length >= 3) {
                         const results =
                           document.querySelectorAll('.DocSearch-Hit');
                         trackSiteSearch(query, 'Documentation', results.length);
                       }
                     }, 1000);
                   });
                 }
               }
             });
           });
         });

         observer.observe(document.body, { childList: true, subtree: true });
         return observer;
       };

       // Track video plays
       const handleVideoPlay = event => {
         if (event.target.tagName === 'VIDEO') {
           const videoSrc =
             event.target.currentSrc || event.target.src || 'unknown';
           trackEvent('Video', 'Play', videoSrc);
         }
       };

       // Track CTA button clicks
       const handleCTAClick = event => {
         const button = event.target.closest(
           '.get-started-button, .default-button-theme',
         );
         if (button) {
           const buttonText = button.textContent?.trim() || 'Unknown';
           const clickedLink = event.target.closest?.('a');
           const href =
             clickedLink?.getAttribute('href') ||
             button.getAttribute('href') ||
             '';
           trackEvent('CTA', 'Click', `${buttonText} - ${href}`);
         }
       };

       // Track scroll depth
       let scrollMilestonesReached = new Set();
       const handleScroll = () => {
         const scrollTop = window.scrollY;
         const docHeight =
           document.documentElement.scrollHeight - window.innerHeight;
         if (docHeight <= 0) return;

         const scrollPercent = Math.round((scrollTop / docHeight) * 100);

         SCROLL_MILESTONES.forEach(milestone => {
           if (
             scrollPercent >= milestone &&
             !scrollMilestonesReached.has(milestone)
           ) {
             scrollMilestonesReached.add(milestone);
             trackEvent(
               'Scroll Depth',
               `${milestone}%`,
               window.location.pathname,
             );
           }
         });
       };

       // Reset scroll tracking on route change
       const resetScrollTracking = () => {
         scrollMilestonesReached = new Set();
       };

       // Track 404 pages
       const track404 = () => {
         const is404 =
           document.querySelector('.theme-doc-404') ||
           document.title.toLowerCase().includes('not found') ||
           document
             .querySelector('h1')
             ?.textContent?.toLowerCase()
             .includes('not found');
         if (is404) {
           trackEvent('Error', '404', window.location.pathname);
           if (devMode) {
             console.log('Matomo: 404 page detected', window.location.pathname);
           }
         }
       };

       // Track copy-to-clipboard events on code blocks
       const handleCopy = event => {
         const codeBlock = event.target.closest('pre, code, .prism-code');
         if (codeBlock) {
           const codeText = window.getSelection()?.toString() || '';
           const codeSnippet =
             codeText.substring(0, 100) + (codeText.length > 100 ? '...' : '');
           trackEvent(
             'Code',
             'Copy',
             `${window.location.pathname}: ${codeSnippet}`,
           );
         }
       };

       // Track color mode preference (as event, no admin config needed)
       const trackColorMode = () => {
         const colorMode =
           document.documentElement.getAttribute('data-theme') ||
           (window.matchMedia('(prefers-color-scheme: dark)').matches
             ? 'dark'
             : 'light');
         trackEvent('User Preference', 'Color Mode', colorMode);
       };

       // Track docs version from URL (as event, no admin config needed)
       const trackDocsVersion = () => {
         const pathMatch = window.location.pathname.match(/\/docs\/([\d.]+)\//);
         const version = pathMatch ? pathMatch[1] : 'latest';
         trackEvent('User Preference', 'Docs Version', version);
       };

       // Handle route changes for SPA
       const handleRouteChange = () => {
         if (devMode) {
           console.log('Route changed to:', window.location.pathname);
         }

         // Reset scroll tracking for new page
         resetScrollTracking();

         setTimeout(() => {
           const currentTitle = document.title;
           const currentPath = window.location.pathname;

           // Set custom dimensions before tracking page view
           trackColorMode();
           trackDocsVersion();

           if (devMode) {
             window._paq.push(['setDomains', ['superset.apache.org']]);
             window._paq.push([
               'setCustomUrl',
               'https://superset.apache.org' + currentPath,
             ]);
           } else {
             window._paq.push(['setCustomUrl', currentPath]);
           }

           window._paq.push(['setReferrerUrl', window.location.href]);
           window._paq.push(['setDocumentTitle', currentTitle]);
           trackPageView(currentPath, currentTitle);

           // Check for 404 after page renders
           setTimeout(track404, 500);
         }, 100);
       };

       // Set up Docusaurus route listeners
       const possibleEvents = [
         'docusaurus.routeDidUpdate',
         'docusaurusRouteDidUpdate',
         'routeDidUpdate',
       ];

       if (devMode) {
         console.log('Setting up Matomo tracking with enhanced features');
       }

       // Store handler references for proper cleanup
       const routeHandlers = possibleEvents.map(eventName => {
         const handler = () => {
           if (devMode) {
             console.log(`Docusaurus route update detected via ${eventName}`);
           }
           handleRouteChange();
         };
         document.addEventListener(eventName, handler);
         return { eventName, handler };
       });

       // Manual history tracking as fallback
       const originalPushState = window.history.pushState;
       window.history.pushState = function () {
         originalPushState.apply(this, arguments);
         handleRouteChange();
       };

       window.addEventListener('popstate', handleRouteChange);

       // Set up event listeners
       document.addEventListener('click', handleLinkClick);
       document.addEventListener('click', handleCTAClick);
       document.addEventListener('play', handleVideoPlay, true);
       document.addEventListener('copy', handleCopy);
       window.addEventListener('scroll', handleScroll, { passive: true });

       // Watch for color mode changes
       const colorModeObserver = new MutationObserver(mutations => {
         mutations.forEach(mutation => {
           if (mutation.attributeName === 'data-theme') {
             trackEvent(
               'User Preference',
               'Color Mode Change',
               document.documentElement.getAttribute('data-theme'),
             );
           }
         });
       });
       colorModeObserver.observe(document.documentElement, { attributes: true });

       // Set up Algolia tracking
       const algoliaObserver = setupAlgoliaTracking();

       // Initial page tracking
       handleRouteChange();

       // Cleanup
       return () => {
         routeHandlers.forEach(({ eventName, handler }) => {
           document.removeEventListener(eventName, handler);
         });

         if (originalPushState) {
           window.history.pushState = originalPushState;
           window.removeEventListener('popstate', handleRouteChange);
         }

         document.removeEventListener('click', handleLinkClick);
         document.removeEventListener('click', handleCTAClick);
         document.removeEventListener('play', handleVideoPlay, true);
         document.removeEventListener('copy', handleCopy);
         window.removeEventListener('scroll', handleScroll);

         if (algoliaObserver) {
           algoliaObserver.disconnect();
         }
         if (colorModeObserver) {
           colorModeObserver.disconnect();
         }
       };
     }
   }, []);

   return children;
 }
	/**
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/
	import { useEffect } from 'react';
	import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

	// File extensions to track as downloads
	const DOWNLOAD_EXTENSIONS = [
	'pdf',
	'zip',
	'tar',
	'gz',
	'tgz',
	'bz2',
	'exe',
	'dmg',
	'pkg',
	'deb',
	'rpm',
	'doc',
	'docx',
	'xls',
	'xlsx',
	'ppt',
	'pptx',
	'csv',
	'json',
	'yaml',
	'yml',
	];

	// Scroll depth milestones to track
	const SCROLL_MILESTONES = [25, 50, 75, 100];

	export default function Root({ children }) {
	const { siteConfig } = useDocusaurusContext();
	const { customFields } = siteConfig;

	useEffect(() => {
	const { matomoUrl, matomoSiteId } = customFields;

	if (typeof window !== 'undefined') {
	const devMode = ['localhost', '127.0.0.1', '::1', '0.0.0.0'].includes(
	window.location.hostname,
	);

	// Initialize the _paq array
	window._paq = window._paq \|\| [];

	// Configure the tracker before loading matomo.js
	window._paq.push(['enableHeartBeatTimer']);
	window._paq.push(['enableLinkTracking']);
	window._paq.push(['setTrackerUrl', `${matomoUrl}/matomo.php`]);
	window._paq.push(['setSiteId', matomoSiteId]);

	// Track downloads with custom extensions
	window._paq.push([
	'setDownloadExtensions',
	DOWNLOAD_EXTENSIONS.join('\|'),
	]);

	// Now load the matomo.js script
	const script = document.createElement('script');
	script.async = true;
	script.src = `${matomoUrl}/matomo.js`;
	document.head.appendChild(script);

	// Helper to track events
	const trackEvent = (category, action, name, value) => {
	if (devMode) {
	console.log('Matomo trackEvent:', { category, action, name, value });
	}
	window._paq.push(['trackEvent', category, action, name, value]);
	};

	// Helper to track site search
	const trackSiteSearch = (keyword, category, resultsCount) => {
	if (devMode) {
	console.log('Matomo trackSiteSearch:', {
	keyword,
	category,
	resultsCount,
	});
	}
	window._paq.push(['trackSiteSearch', keyword, category, resultsCount]);
	};

	// Helper to track page views
	const trackPageView = (url, title) => {
	if (devMode) {
	console.log('Matomo trackPageView:', { url, title });
	}
	window._paq.push(['trackPageView']);
	};

	// Track external link clicks using domain as category (vendor-agnostic)
	const handleLinkClick = event => {
	const link = event.target.closest('a');
	if (!link) return;

	const href = link.getAttribute('href');
	if (!href) return;

	try {
	const url = new URL(href, window.location.origin);

	// Skip internal links
	if (url.hostname === window.location.hostname) return;

	// Use hostname as category for vendor-agnostic tracking
	trackEvent('Outbound Link', url.hostname, href);
	} catch {
	// Invalid URL, skip tracking
	}
	};

	// Track Algolia search queries
	const setupAlgoliaTracking = () => {
	const observer = new MutationObserver(mutations => {
	mutations.forEach(mutation => {
	mutation.addedNodes.forEach(node => {
	if (node.nodeType === Node.ELEMENT_NODE) {
	const searchInput =
	node.querySelector?.('.DocSearch-Input') \|\|
	(node.classList?.contains('DocSearch-Input') ? node : null);
	if (searchInput) {
	let debounceTimer;
	searchInput.addEventListener('input', e => {
	clearTimeout(debounceTimer);
	debounceTimer = setTimeout(() => {
	const query = e.target.value.trim();
	if (query.length >= 3) {
	const results =
	document.querySelectorAll('.DocSearch-Hit');
	trackSiteSearch(query, 'Documentation', results.length);
	}
	}, 1000);
	});
	}
	}
	});
	});
	});

	observer.observe(document.body, { childList: true, subtree: true });
	return observer;
	};

	// Track video plays
	const handleVideoPlay = event => {
	if (event.target.tagName === 'VIDEO') {
	const videoSrc =
	event.target.currentSrc \|\| event.target.src \|\| 'unknown';
	trackEvent('Video', 'Play', videoSrc);
	}
	};

	// Track CTA button clicks
	const handleCTAClick = event => {
	const button = event.target.closest(
	'.get-started-button, .default-button-theme',
	);
	if (button) {
	const buttonText = button.textContent?.trim() \|\| 'Unknown';
	const clickedLink = event.target.closest?.('a');
	const href =
	clickedLink?.getAttribute('href') \|\|
	button.getAttribute('href') \|\|
	'';
	trackEvent('CTA', 'Click', `${buttonText} - ${href}`);
	}
	};

	// Track scroll depth
	let scrollMilestonesReached = new Set();
	const handleScroll = () => {
	const scrollTop = window.scrollY;
	const docHeight =
	document.documentElement.scrollHeight - window.innerHeight;
	if (docHeight <= 0) return;

	const scrollPercent = Math.round((scrollTop / docHeight) * 100);

	SCROLL_MILESTONES.forEach(milestone => {
	if (
	scrollPercent >= milestone &&
	!scrollMilestonesReached.has(milestone)
	) {
	scrollMilestonesReached.add(milestone);
	trackEvent(
	'Scroll Depth',
	`${milestone}%`,
	window.location.pathname,
	);
	}
	});
	};

	// Reset scroll tracking on route change
	const resetScrollTracking = () => {
	scrollMilestonesReached = new Set();
	};

	// Track 404 pages
	const track404 = () => {
	const is404 =
	document.querySelector('.theme-doc-404') \|\|
	document.title.toLowerCase().includes('not found') \|\|
	document
	.querySelector('h1')
	?.textContent?.toLowerCase()
	.includes('not found');
	if (is404) {
	trackEvent('Error', '404', window.location.pathname);
	if (devMode) {
	console.log('Matomo: 404 page detected', window.location.pathname);
	}
	}
	};

	// Track copy-to-clipboard events on code blocks
	const handleCopy = event => {
	const codeBlock = event.target.closest('pre, code, .prism-code');
	if (codeBlock) {
	const codeText = window.getSelection()?.toString() \|\| '';
	const codeSnippet =
	codeText.substring(0, 100) + (codeText.length > 100 ? '...' : '');
	trackEvent(
	'Code',
	'Copy',
	`${window.location.pathname}: ${codeSnippet}`,
	);
	}
	};

	// Track color mode preference (as event, no admin config needed)
	const trackColorMode = () => {
	const colorMode =
	document.documentElement.getAttribute('data-theme') \|\|
	(window.matchMedia('(prefers-color-scheme: dark)').matches
	? 'dark'
	: 'light');
	trackEvent('User Preference', 'Color Mode', colorMode);
	};

	// Track docs version from URL (as event, no admin config needed)
	const trackDocsVersion = () => {
	const pathMatch = window.location.pathname.match(/\/docs\/([\d.]+)\//);
	const version = pathMatch ? pathMatch[1] : 'latest';
	trackEvent('User Preference', 'Docs Version', version);
	};

	// Handle route changes for SPA
	const handleRouteChange = () => {
	if (devMode) {
	console.log('Route changed to:', window.location.pathname);
	}

	// Reset scroll tracking for new page
	resetScrollTracking();

	setTimeout(() => {
	const currentTitle = document.title;
	const currentPath = window.location.pathname;

	// Set custom dimensions before tracking page view
	trackColorMode();
	trackDocsVersion();

	if (devMode) {
	window._paq.push(['setDomains', ['superset.apache.org']]);
	window._paq.push([
	'setCustomUrl',
	'https://superset.apache.org' + currentPath,
	]);
	} else {
	window._paq.push(['setCustomUrl', currentPath]);
	}

	window._paq.push(['setReferrerUrl', window.location.href]);
	window._paq.push(['setDocumentTitle', currentTitle]);
	trackPageView(currentPath, currentTitle);

	// Check for 404 after page renders
	setTimeout(track404, 500);
	}, 100);
	};

	// Set up Docusaurus route listeners
	const possibleEvents = [
	'docusaurus.routeDidUpdate',
	'docusaurusRouteDidUpdate',
	'routeDidUpdate',
	];

	if (devMode) {
	console.log('Setting up Matomo tracking with enhanced features');
	}

	// Store handler references for proper cleanup
	const routeHandlers = possibleEvents.map(eventName => {
	const handler = () => {
	if (devMode) {
	console.log(`Docusaurus route update detected via ${eventName}`);
	}
	handleRouteChange();
	};
	document.addEventListener(eventName, handler);
	return { eventName, handler };
	});

	// Manual history tracking as fallback
	const originalPushState = window.history.pushState;
	window.history.pushState = function () {
	originalPushState.apply(this, arguments);
	handleRouteChange();
	};

	window.addEventListener('popstate', handleRouteChange);

	// Set up event listeners
	document.addEventListener('click', handleLinkClick);
	document.addEventListener('click', handleCTAClick);
	document.addEventListener('play', handleVideoPlay, true);
	document.addEventListener('copy', handleCopy);
	window.addEventListener('scroll', handleScroll, { passive: true });

	// Watch for color mode changes
	const colorModeObserver = new MutationObserver(mutations => {
	mutations.forEach(mutation => {
	if (mutation.attributeName === 'data-theme') {
	trackEvent(
	'User Preference',
	'Color Mode Change',
	document.documentElement.getAttribute('data-theme'),
	);
	}
	});
	});
	colorModeObserver.observe(document.documentElement, { attributes: true });

	// Set up Algolia tracking
	const algoliaObserver = setupAlgoliaTracking();

	// Initial page tracking
	handleRouteChange();

	// Cleanup
	return () => {
	routeHandlers.forEach(({ eventName, handler }) => {
	document.removeEventListener(eventName, handler);
	});

	if (originalPushState) {
	window.history.pushState = originalPushState;
	window.removeEventListener('popstate', handleRouteChange);
	}

	document.removeEventListener('click', handleLinkClick);
	document.removeEventListener('click', handleCTAClick);
	document.removeEventListener('play', handleVideoPlay, true);
	document.removeEventListener('copy', handleCopy);
	window.removeEventListener('scroll', handleScroll);

	if (algoliaObserver) {
	algoliaObserver.disconnect();
	}
	if (colorModeObserver) {
	colorModeObserver.disconnect();
	}
	};
	}
	}, []);

	return children;
	}