@patternfly/documentation-framework 6.10.33 → 6.11.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 6.11.0 (2025-06-16)
+
+
+### Features
+
+* **ThemeSwitcher:** Enhanced theme switcher with system preference detection and tri-state selection ([#4639](https://github.com/patternfly/patternfly-org/issues/4639)) ([1b05742](https://github.com/patternfly/patternfly-org/commit/1b057425216a484dda1f46ba37842c22b77c7b87))
+
+
+
+
+
 ## 6.10.33 (2025-06-16)
 
 **Note:** Version bump only for package @patternfly/documentation-framework

package/components/example/example.js

@@ -1,4 +1,4 @@
-import React, { useContext, useEffect } from 'react';
+import React, { useContext, useEffect, useState, useCallback } from 'react';
 import { useLocation } from '@reach/router';
 import {
   Button,
@@ -8,6 +8,10 @@ import {
   debounce,
   Label,
   Switch,
+  Select,
+  SelectOption,
+  SelectList,
+  MenuToggle,
   Tooltip,
   Stack,
   StackItem
@@ -19,6 +23,9 @@ import * as reactTableModule from '@patternfly/react-table';
 import * as reactTableDeprecatedModule from '@patternfly/react-table/deprecated';
 import { css } from '@patternfly/react-styles';
 import { getParameters } from 'codesandbox/lib/api/define';
+import SunIcon from '@patternfly/react-icons/dist/esm/icons/sun-icon';
+import MoonIcon from '@patternfly/react-icons/dist/esm/icons/moon-icon';
+import DesktopIcon from '@patternfly/react-icons/dist/esm/icons/desktop-icon';
 import { ExampleToolbar } from './exampleToolbar.jsx';
 import { AutoLinkHeader } from '../autoLinkHeader/autoLinkHeader';
 import {
@@ -32,9 +39,89 @@ import {
 import { convertToReactComponent } from '@patternfly/ast-helpers';
 import missingThumbnail from './missing-thumbnail.jpg';
 import { RtlContext } from '../../layouts';
+import { useTheme } from '../../hooks/useTheme';
 
 const errorComponent = (err) => <pre>{err.toString()}</pre>;
 
+// Full-screen theme selector component using shared theme hook
+const FullScreenThemeSelector = () => {
+  const { themeMode, setThemeMode, THEME_MODES } = useTheme();
+  const [isThemeSelectOpen, setIsThemeSelectOpen] = useState(false);
+
+  const handleThemeChange = (_event, selectedMode) => {
+    setThemeMode(selectedMode);
+    setIsThemeSelectOpen(false);
+  };
+
+  const getThemeDisplayText = (mode) => {
+    switch (mode) {
+      case THEME_MODES.LIGHT:
+        return 'Light';
+      case THEME_MODES.DARK:
+        return 'Dark';
+      default:
+        return 'System';
+    }
+  };
+
+  const getThemeIcon = (mode) => {
+    switch (mode) {
+      case THEME_MODES.LIGHT:
+        return <SunIcon />;
+      case THEME_MODES.DARK:
+        return <MoonIcon />;
+      default:
+        return <DesktopIcon />;
+    }
+  };
+
+  return (
+    <Select
+      id="ws-example-theme-select"
+      isOpen={isThemeSelectOpen}
+      selected={themeMode}
+      onSelect={handleThemeChange}
+      onOpenChange={(isOpen) => setIsThemeSelectOpen(isOpen)}
+      toggle={(toggleRef) => (
+        <MenuToggle
+          ref={toggleRef}
+          onClick={() => setIsThemeSelectOpen(!isThemeSelectOpen)}
+          isExpanded={isThemeSelectOpen}
+          icon={getThemeIcon(themeMode)}
+          aria-label={`Theme selection, current: ${getThemeDisplayText(themeMode)}`}
+        >
+          {getThemeDisplayText(themeMode)}
+        </MenuToggle>
+      )}
+      shouldFocusToggleOnSelect
+    >
+      <SelectList>
+        <SelectOption 
+          value={THEME_MODES.SYSTEM}
+          icon={<DesktopIcon />}
+          description="Follow system preference"
+        >
+          System
+        </SelectOption>
+        <SelectOption 
+          value={THEME_MODES.LIGHT}
+          icon={<SunIcon />}
+          description="Always use light mode"
+        >
+          Light
+        </SelectOption>
+        <SelectOption 
+          value={THEME_MODES.DARK}
+          icon={<MoonIcon />}
+          description="Always use dark mode"
+        >
+          Dark
+        </SelectOption>
+      </SelectList>
+    </Select>
+  );
+};
+
 class ErrorBoundary extends React.Component {
   constructor(props) {
     super(props);
@@ -199,21 +286,10 @@ export const Example = ({
         {(hasDarkThemeSwitcher || hasRTLSwitcher) && (
           <Flex
             direction={{ default: 'column' }}
-            gap={{ default: 'gapLg' }}
-            className="ws-full-page-utils pf-v6-m-dir-ltr "
+            gap={{ default: 'gapMd' }}
+            className="ws-full-page-utils pf-v6-m-dir-ltr"
           >
-            {hasDarkThemeSwitcher && (
-              <Switch
-                id="ws-example-theme-switch"
-                label="Dark theme"
-                defaultChecked={false}
-                onChange={() =>
-                  document
-                    .querySelector('html')
-                    .classList.toggle('pf-v6-theme-dark')
-                }
-              />
-            )}
+            {hasDarkThemeSwitcher && <FullScreenThemeSelector />}
             {hasRTLSwitcher && (
               <Switch
                 id="ws-example-rtl-switch"

package/hooks/useTheme.js

@@ -0,0 +1,137 @@
+import { useState, useEffect, useCallback } from 'react';
+
+const THEME_MODES = {
+  SYSTEM: 'system',
+  LIGHT: 'light',
+  DARK: 'dark'
+};
+
+const THEME_STORAGE_KEY = 'theme-preference';
+const DARK_MODE_CLASS = 'pf-v6-theme-dark';
+
+/**
+ * Custom hook for managing theme state with system preference detection
+ * @returns {Object} Theme state and controls
+ * @returns {string} themeMode - Current theme mode ('system'|'light'|'dark')
+ * @returns {Function} setThemeMode - Function to change theme mode
+ * @returns {string} resolvedTheme - The actual applied theme ('light'|'dark')
+ * @returns {Object} THEME_MODES - Available theme mode constants
+ */
+export const useTheme = () => {
+  const getStoredThemeMode = () => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return null;
+    }
+    return localStorage.getItem(THEME_STORAGE_KEY);
+  };
+
+  const setStoredThemeMode = (mode) => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return;
+    }
+    localStorage.setItem(THEME_STORAGE_KEY, mode);
+  };
+
+  const getResolvedTheme = (mode) => {
+    // SSR-safe check for window and matchMedia
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return 'light';
+    }
+    
+    if (mode === THEME_MODES.SYSTEM) {
+      try {
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      } catch (error) {
+        // Fallback if matchMedia fails
+        console.warn('matchMedia not supported, defaulting to light theme');
+        return 'light';
+      }
+    }
+    return mode;
+  };
+
+  const updateThemeClass = (resolvedTheme) => {
+    if (typeof window === 'undefined' || !document) {
+      return;
+    }
+    
+    const htmlElement = document.querySelector('html');
+    if (!htmlElement) {
+      return;
+    }
+    
+    if (resolvedTheme === 'dark') {
+      htmlElement.classList.add(DARK_MODE_CLASS);
+    } else {
+      htmlElement.classList.remove(DARK_MODE_CLASS);
+    }
+  };
+
+  const [themeMode, setThemeModeState] = useState(() => {
+    const stored = getStoredThemeMode();
+    return stored && Object.values(THEME_MODES).includes(stored) ? stored : THEME_MODES.SYSTEM;
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState(() => getResolvedTheme(themeMode));
+
+  const setThemeMode = useCallback((newMode) => {
+    setThemeModeState(newMode);
+    setStoredThemeMode(newMode);
+    
+    const newResolvedTheme = getResolvedTheme(newMode);
+    setResolvedTheme(newResolvedTheme);
+    updateThemeClass(newResolvedTheme);
+  }, []);
+
+  // Listen for system preference changes
+  useEffect(() => {
+    // Enhanced SSR-safe check
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return;
+    }
+
+    let mediaQuery;
+    try {
+      mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    } catch (error) {
+      console.warn('matchMedia not supported, skipping system theme detection');
+      return;
+    }
+    
+    const handleSystemThemeChange = (e) => {
+      if (themeMode === THEME_MODES.SYSTEM) {
+        const newSystemTheme = e.matches ? 'dark' : 'light';
+        setResolvedTheme(newSystemTheme);
+        updateThemeClass(newSystemTheme);
+      }
+    };
+
+    // Check if addEventListener is available (some older browsers might not support it)
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener('change', handleSystemThemeChange);
+      return () => {
+        mediaQuery.removeEventListener('change', handleSystemThemeChange);
+      };
+    } else if (mediaQuery.addListener) {
+      // Fallback for older browsers
+      mediaQuery.addListener(handleSystemThemeChange);
+      return () => {
+        mediaQuery.removeListener(handleSystemThemeChange);
+      };
+    }
+  }, [themeMode]);
+
+  // Initial theme application
+  useEffect(() => {
+    const initialResolvedTheme = getResolvedTheme(themeMode);
+    setResolvedTheme(initialResolvedTheme);
+    updateThemeClass(initialResolvedTheme);
+  }, [themeMode]);
+
+  return {
+    themeMode,
+    setThemeMode,
+    resolvedTheme,
+    THEME_MODES
+  };
+}; 

package/layouts/sideNavLayout/sideNavLayout.js

@@ -23,17 +23,20 @@ import {
   SkipToContent,
   Switch,
   SearchInput,
-  ToggleGroup,
-  ToggleGroupItem,
+  Select,
+  SelectOption,
+  SelectList,
   MastheadLogo
 } from '@patternfly/react-core';
 import BarsIcon from '@patternfly/react-icons/dist/esm/icons/bars-icon';
 import GithubIcon from '@patternfly/react-icons/dist/esm/icons/github-icon';
 import MoonIcon from '@patternfly/react-icons/dist/esm/icons/moon-icon';
 import SunIcon from '@patternfly/react-icons/dist/esm/icons/sun-icon';
+import DesktopIcon from '@patternfly/react-icons/dist/esm/icons/desktop-icon';
 import { SideNav, TopNav, GdprBanner } from '../../components';
 import staticVersions from '../../versions.json';
 import { Footer } from '@patternfly/documentation-framework/components';
+import { useTheme } from '../../hooks/useTheme';
 
 export const RtlContext = createContext(false);
 
@@ -46,8 +49,9 @@ const HeaderTools = ({
   topNavItems,
   isRTL,
   setIsRTL,
-  isDarkTheme,
-  setIsDarkTheme
+  themeMode,
+  setThemeMode,
+  THEME_MODES
 }) => {
   const latestVersion = versions.Releases.find((version) => version.latest);
   const previousReleases = Object.values(versions.Releases).filter((version) => !version.hidden && !version.latest);
@@ -55,6 +59,7 @@ const HeaderTools = ({
   const [isDropdownOpen, setDropdownOpen] = useState(false);
   const [searchValue, setSearchValue] = React.useState('');
   const [isSearchExpanded, setIsSearchExpanded] = React.useState(false);
+  const [isThemeSelectOpen, setIsThemeSelectOpen] = useState(false);
 
   const getDropdownItem = (version, isLatest = false) => (
     <DropdownItem itemId={version.name} key={version.name} to={isLatest ? '/' : `/${version.name}`}>
@@ -70,10 +75,31 @@ const HeaderTools = ({
     setIsSearchExpanded(!isSearchExpanded);
   };
 
-  const toggleDarkTheme = (_evt, selected) => {
-    const darkThemeToggleClicked = !selected === isDarkTheme;
-    document.querySelector('html').classList.toggle('pf-v6-theme-dark', darkThemeToggleClicked);
-    setIsDarkTheme(darkThemeToggleClicked);
+  const handleThemeChange = (_event, selectedMode) => {
+    setThemeMode(selectedMode);
+    setIsThemeSelectOpen(false);
+  };
+
+  const getThemeDisplayText = (mode) => {
+    switch (mode) {
+      case THEME_MODES.LIGHT:
+        return 'Light';
+      case THEME_MODES.DARK:
+        return 'Dark';
+      default:
+        return 'System';
+    }
+  };
+
+  const getThemeIcon = (mode) => {
+    switch (mode) {
+      case THEME_MODES.LIGHT:
+        return <SunIcon />;
+      case THEME_MODES.DARK:
+        return <MoonIcon />;
+      default:
+        return <DesktopIcon />;
+    }
   };
 
   useEffect(() => {
@@ -92,24 +118,6 @@ const HeaderTools = ({
           </ToolbarItem>
         )}
         <ToolbarGroup align={{ default: 'alignEnd' }}>
-          {hasDarkThemeSwitcher && (
-            <ToolbarItem>
-              <ToggleGroup aria-label="Dark theme toggle group">
-                <ToggleGroupItem
-                  aria-label="light theme toggle"
-                  icon={<SunIcon />}
-                  isSelected={!isDarkTheme}
-                  onChange={toggleDarkTheme}
-                />
-                <ToggleGroupItem
-                  aria-label="dark theme toggle"
-                  icon={<MoonIcon />}
-                  isSelected={isDarkTheme}
-                  onChange={toggleDarkTheme}
-                />
-              </ToggleGroup>
-            </ToolbarItem>
-          )}
           {hasRTLSwitcher && (
             <ToolbarItem>
               <Switch
@@ -147,6 +155,53 @@ const HeaderTools = ({
               <GithubIcon />
             </Button>
           </ToolbarItem>
+          {hasDarkThemeSwitcher && (
+            <ToolbarItem>
+              <Select
+                id="ws-theme-select"
+                isOpen={isThemeSelectOpen}
+                selected={themeMode}
+                onSelect={handleThemeChange}
+                onOpenChange={(isOpen) => setIsThemeSelectOpen(isOpen)}
+                toggle={(toggleRef) => (
+                  <MenuToggle
+                    ref={toggleRef}
+                    onClick={() => setIsThemeSelectOpen(!isThemeSelectOpen)}
+                    isExpanded={isThemeSelectOpen}
+                    icon={getThemeIcon(themeMode)}
+                    aria-label={`Theme selection, current: ${getThemeDisplayText(themeMode)}`}
+                  >
+                    {getThemeDisplayText(themeMode)}
+                  </MenuToggle>
+                )}
+                shouldFocusToggleOnSelect
+              >
+                <SelectList>
+                  <SelectOption 
+                    value={THEME_MODES.SYSTEM}
+                    icon={<DesktopIcon />}
+                    description="Follow system preference"
+                  >
+                    System
+                  </SelectOption>
+                  <SelectOption 
+                    value={THEME_MODES.LIGHT}
+                    icon={<SunIcon />}
+                    description="Always use light mode"
+                  >
+                    Light
+                  </SelectOption>
+                  <SelectOption 
+                    value={THEME_MODES.DARK}
+                    icon={<MoonIcon />}
+                    description="Always use dark mode"
+                  >
+                    Dark
+                  </SelectOption>
+                </SelectList>
+              </Select>
+            </ToolbarItem>
+          )}
           {hasVersionSwitcher && (
             <ToolbarItem>
               <Dropdown
@@ -245,7 +300,8 @@ export const SideNavLayout = ({ children, groupedRoutes, navOpen: navOpenProp })
 
   const [versions, setVersions] = useState({ ...staticVersions });
   const [isRTL, setIsRTL] = useState(false);
-  const [isDarkTheme, setIsDarkTheme] = React.useState(false);
+  
+  const { themeMode, setThemeMode, resolvedTheme, THEME_MODES } = useTheme();
 
   useEffect(() => {
     if (typeof window === 'undefined') {
@@ -338,8 +394,9 @@ export const SideNavLayout = ({ children, groupedRoutes, navOpen: navOpenProp })
             topNavItems={topNavItems}
             isRTL={isRTL}
             setIsRTL={setIsRTL}
-            isDarkTheme={isDarkTheme}
-            setIsDarkTheme={setIsDarkTheme}
+            themeMode={themeMode}
+            setThemeMode={setThemeMode}
+            THEME_MODES={THEME_MODES}
           />
         )}
       </MastheadContent>
@@ -360,7 +417,7 @@ export const SideNavLayout = ({ children, groupedRoutes, navOpen: navOpenProp })
           defaultManagedSidebarIsOpen={navOpenProp}
         >
           {children}
-          {process.env.hasFooter && <Footer isDarkTheme={isDarkTheme} />}
+          {process.env.hasFooter && <Footer isDarkTheme={resolvedTheme === 'dark'} />}
         </Page>
         <div id="ws-page-banners">{hasGdprBanner && <GdprBanner />}</div>
       </RtlContext.Provider>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patternfly/documentation-framework",
   "description": "A framework to build documentation for PatternFly.",
-  "version": "6.10.33",
+  "version": "6.11.0",
   "author": "Red Hat",
   "license": "MIT",
   "bin": {
@@ -12,7 +12,7 @@
     "@babel/preset-env": "^7.24.3",
     "@babel/preset-react": "^7.24.1",
     "@mdx-js/util": "1.6.16",
-    "@patternfly/ast-helpers": "^1.4.0-alpha.219",
+    "@patternfly/ast-helpers": "^1.4.0-alpha.220",
     "@reach/router": "npm:@gatsbyjs/reach-router@1.3.9",
     "autoprefixer": "9.8.6",
     "babel-loader": "^9.1.3",
@@ -79,5 +79,5 @@
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0"
   },
-  "gitHead": "66abf030387237d3d41d14bb98bdae886b03e7a0"
+  "gitHead": "3481a949f8c8f17ed8d74faba651b339acae54df"
 }