@mui/internal-docs-infra 0.2.3-canary.9 → 0.3.1-canary.1

package/esm/useCode/useFileNavigation.js

@@ -37,13 +37,13 @@ export function isHashRelevantToDemo(urlHash, mainSlug) {
 
 /**
  * Generates a file slug based on main slug, file name, and variant name
+ * All variants except "Default" include the variant name in the hash
  * @param mainSlug - The main component/demo slug
  * @param fileName - The file name
  * @param variantName - The variant name
- * @param isInitialVariant - Whether this is the initial/default variant
  * @returns Generated file slug
  */
-function generateFileSlug(mainSlug, fileName, variantName, isInitialVariant) {
+function generateFileSlug(mainSlug, fileName, variantName) {
   // Extract base name from filename (strip extension)
   var lastDotIndex = fileName.lastIndexOf('.');
   var baseName = lastDotIndex !== -1 ? fileName.substring(0, lastDotIndex) : fileName;
@@ -62,8 +62,9 @@ function generateFileSlug(mainSlug, fileName, variantName, isInitialVariant) {
     return kebabFileName;
   }
 
-  // Format: mainSlug:fileName.ext (for initial variant) or mainSlug:variantName:fileName.ext
-  if (isInitialVariant) {
+  // Format: mainSlug:fileName.ext (for Default variant) or mainSlug:variantName:fileName.ext
+  // "Default" variant is treated specially and doesn't include variant name in hash
+  if (variantName === 'Default') {
     return "".concat(kebabMainSlug, ":").concat(kebabFileName);
   }
   return "".concat(kebabMainSlug, ":").concat(kebabVariantName, ":").concat(kebabFileName);
@@ -80,29 +81,23 @@ export function useFileNavigation(_ref) {
     selectedVariantKey = _ref$selectedVariantK === void 0 ? '' : _ref$selectedVariantK,
     _ref$variantKeys = _ref.variantKeys,
     variantKeys = _ref$variantKeys === void 0 ? [] : _ref$variantKeys,
-    initialVariant = _ref.initialVariant,
     shouldHighlight = _ref.shouldHighlight,
     preClassName = _ref.preClassName,
     preRef = _ref.preRef,
     effectiveCode = _ref.effectiveCode,
-    selectVariant = _ref.selectVariant;
+    selectVariant = _ref.selectVariant,
+    _ref$fileHashMode = _ref.fileHashMode,
+    fileHashMode = _ref$fileHashMode === void 0 ? 'remove-hash' : _ref$fileHashMode,
+    _ref$saveHashVariantT = _ref.saveHashVariantToLocalStorage,
+    saveHashVariantToLocalStorage = _ref$saveHashVariantT === void 0 ? 'on-interaction' : _ref$saveHashVariantT,
+    saveVariantToLocalStorage = _ref.saveVariantToLocalStorage,
+    hashVariant = _ref.hashVariant;
   // Keep selectedFileName as untransformed filename for internal tracking
   var _React$useState = React.useState(selectedVariant == null ? void 0 : selectedVariant.fileName),
     _React$useState2 = _slicedToArray(_React$useState, 2),
     selectedFileNameInternal = _React$useState2[0],
     setSelectedFileNameInternal = _React$useState2[1];
 
-  // Track user interaction locally
-  var _React$useState3 = React.useState(false),
-    _React$useState4 = _slicedToArray(_React$useState3, 2),
-    hasUserInteraction = _React$useState4[0],
-    setHasUserInteraction = _React$useState4[1];
-
-  // Helper to mark user interaction
-  var markUserInteraction = React.useCallback(function () {
-    setHasUserInteraction(true);
-  }, []);
-
   // Use the simplified URL hash hook
   var _useUrlHashState = useUrlHashState(),
     _useUrlHashState2 = _slicedToArray(_useUrlHashState, 2),
@@ -113,6 +108,37 @@ export function useFileNavigation(_ref) {
   var pendingFileSelection = React.useRef(null);
   var justCompletedPendingSelection = React.useRef(false);
 
+  // Track the previous variant key to detect user-initiated changes
+  var prevVariantKeyRef = React.useRef(selectedVariantKey);
+  var _React$useState3 = React.useState(selectedVariantKey),
+    _React$useState4 = _slicedToArray(_React$useState3, 2),
+    prevVariantKeyState = _React$useState4[0],
+    setPrevVariantKeyState = _React$useState4[1];
+  var isInitialMount = React.useRef(true);
+
+  // Detect if the current variant change was driven by a hash change
+  // A variant change is hash-driven if the hash has a variant that matches where we're going
+  // AND we weren't already on that variant (i.e., the hash is what triggered the change)
+  var _React$useState5 = React.useState(hashVariant || null),
+    _React$useState6 = _slicedToArray(_React$useState5, 2),
+    prevHashVariant = _React$useState6[0],
+    setPrevHashVariant = _React$useState6[1];
+  var isHashDrivenVariantChange = hashVariant === selectedVariantKey && prevVariantKeyState !== selectedVariantKey;
+
+  // Update prevHashVariant when hashVariant changes
+  React.useEffect(function () {
+    if (hashVariant !== prevHashVariant) {
+      setPrevHashVariant(hashVariant || null);
+    }
+  }, [hashVariant, prevHashVariant]);
+
+  // Update prevVariantKeyState when variant changes
+  React.useEffect(function () {
+    if (selectedVariantKey !== prevVariantKeyState) {
+      setPrevVariantKeyState(selectedVariantKey);
+    }
+  }, [selectedVariantKey, prevVariantKeyState]);
+
   // Helper function to check URL hash and switch to matching file
   var checkUrlHashAndSelectFile = React.useCallback(function () {
     if (!hash) {
@@ -125,11 +151,9 @@ export function useFileNavigation(_ref) {
 
     // Step 1: Check current variant (if we have one)
     if (selectedVariant) {
-      var isInitialVariant = initialVariant ? selectedVariantKey === initialVariant : variantKeys.length === 0 || selectedVariantKey === variantKeys[0];
-
       // Check main file
       if (selectedVariant.fileName) {
-        var mainFileSlug = generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey, isInitialVariant);
+        var mainFileSlug = generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey);
         if (hash === mainFileSlug) {
           matchingFileName = selectedVariant.fileName;
           matchingVariantKey = selectedVariantKey;
@@ -140,7 +164,7 @@ export function useFileNavigation(_ref) {
       if (!matchingFileName && selectedVariant.extraFiles) {
         for (var _i = 0, _Object$keys = Object.keys(selectedVariant.extraFiles); _i < _Object$keys.length; _i++) {
           var fileName = _Object$keys[_i];
-          var fileSlug = generateFileSlug(mainSlug, fileName, selectedVariantKey, isInitialVariant);
+          var fileSlug = generateFileSlug(mainSlug, fileName, selectedVariantKey);
           if (hash === fileSlug) {
             matchingFileName = fileName;
             matchingVariantKey = selectedVariantKey;
@@ -156,7 +180,7 @@ export function useFileNavigation(_ref) {
         try {
           for (_iterator.s(); !(_step = _iterator.n()).done;) {
             var file = _step.value;
-            var _fileSlug = generateFileSlug(mainSlug, file.originalName, selectedVariantKey, isInitialVariant);
+            var _fileSlug = generateFileSlug(mainSlug, file.originalName, selectedVariantKey);
             if (hash === _fileSlug) {
               matchingFileName = file.originalName;
               matchingVariantKey = selectedVariantKey;
@@ -181,11 +205,10 @@ export function useFileNavigation(_ref) {
         if (variantKey === selectedVariantKey || !variant || typeof variant === 'string') {
           continue;
         }
-        var _isInitialVariant = initialVariant ? variantKey === initialVariant : variantKeys.length === 0 || variantKey === variantKeys[0];
 
         // Check main file
         if (variant.fileName) {
-          var _mainFileSlug = generateFileSlug(mainSlug, variant.fileName, variantKey, _isInitialVariant);
+          var _mainFileSlug = generateFileSlug(mainSlug, variant.fileName, variantKey);
           if (hash === _mainFileSlug) {
             matchingFileName = variant.fileName;
             matchingVariantKey = variantKey;
@@ -197,7 +220,7 @@ export function useFileNavigation(_ref) {
         if (!matchingFileName && variant.extraFiles) {
           for (var _i3 = 0, _Object$keys2 = Object.keys(variant.extraFiles); _i3 < _Object$keys2.length; _i3++) {
             var _fileName = _Object$keys2[_i3];
-            var _fileSlug2 = generateFileSlug(mainSlug, _fileName, variantKey, _isInitialVariant);
+            var _fileSlug2 = generateFileSlug(mainSlug, _fileName, variantKey);
             if (hash === _fileSlug2) {
               matchingFileName = _fileName;
               matchingVariantKey = variantKey;
@@ -223,16 +246,13 @@ export function useFileNavigation(_ref) {
       // Set the file if we're in the correct variant
       pendingFileSelection.current = null;
       setSelectedFileNameInternal(matchingFileName);
-      markUserInteraction();
     }
-  }, [hash, selectedVariant, selectedVariantKey, variantKeys, initialVariant, mainSlug, transformedFiles, effectiveCode, selectVariant, markUserInteraction]);
+  }, [hash, selectedVariant, selectedVariantKey, mainSlug, transformedFiles, effectiveCode, selectVariant]);
 
   // Run hash check when URL hash changes to select the matching file
-  // Only depends on hash to avoid re-running when the callback recreates due to variant state changes
   React.useEffect(function () {
     checkUrlHashAndSelectFile();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [hash]);
+  }, [checkUrlHashAndSelectFile]);
 
   // When variant switches with a pending file selection, complete the file selection
   React.useEffect(function () {
@@ -241,11 +261,10 @@ export function useFileNavigation(_ref) {
       pendingFileSelection.current = null;
       justCompletedPendingSelection.current = true;
       setSelectedFileNameInternal(fileToSelect);
-      markUserInteraction();
     } else {
       justCompletedPendingSelection.current = false;
     }
-  }, [selectedVariantKey, selectedVariant, markUserInteraction]);
+  }, [selectedVariantKey, selectedVariant]);
 
   // Reset selectedFileName when variant changes
   React.useEffect(function () {
@@ -263,38 +282,49 @@ export function useFileNavigation(_ref) {
     }
   }, [selectedVariant, selectedFileNameInternal]);
 
-  // Update URL when variant changes (to reflect new slug for current file)
+  // Update hash when variant changes (user-initiated variant switch)
   React.useEffect(function () {
-    if (!selectedVariant || typeof window === 'undefined' || !selectedFileNameInternal || !hasUserInteraction) {
+    // Skip on initial mount - let hash-driven navigation handle it
+    if (isInitialMount.current) {
+      isInitialMount.current = false;
+      prevVariantKeyRef.current = selectedVariantKey;
       return;
     }
 
-    // Determine if this is the initial variant
-    var isInitialVariant = initialVariant ? selectedVariantKey === initialVariant : variantKeys.length === 0 || selectedVariantKey === variantKeys[0];
+    // Only update hash if there's already a relevant hash present
+    if (typeof window === 'undefined' || !isHashRelevantToDemo(hash, mainSlug)) {
+      prevVariantKeyRef.current = selectedVariantKey;
+      return;
+    }
 
-    // Generate the new slug for the currently selected file
-    var fileSlug = '';
-    if (transformedFiles) {
-      var file = transformedFiles.files.find(function (f) {
-        return f.originalName === selectedFileNameInternal;
-      });
-      if (file) {
-        fileSlug = generateFileSlug(mainSlug, file.originalName, selectedVariantKey, isInitialVariant);
-      }
-    } else {
-      fileSlug = generateFileSlug(mainSlug, selectedFileNameInternal, selectedVariantKey, isInitialVariant);
+    // Skip if variant hasn't actually changed
+    if (prevVariantKeyRef.current === selectedVariantKey) {
+      return;
     }
 
-    // Only update the URL hash if it's different from current hash
-    if (fileSlug && hash !== fileSlug) {
-      // Only update if current hash is for the same demo (starts with mainSlug)
-      // Don't set hash if there's no existing hash - variant changes shouldn't add hashes
-      if (isHashRelevantToDemo(hash, mainSlug)) {
-        setHash(fileSlug);
+    // Skip if this is a hash-driven variant change (hash is driving the variant selection)
+    if (pendingFileSelection.current || justCompletedPendingSelection.current || isHashDrivenVariantChange) {
+      prevVariantKeyRef.current = selectedVariantKey;
+      return;
+    }
+
+    // User switched variants, update hash based on fileHashMode
+    // Note: localStorage is already saved by setSelectedVariantKeyAsUser
+    if (fileHashMode === 'remove-filename') {
+      // Keep variant in hash: mainSlug or mainSlug:variant (for non-Default variants)
+      var kebabMainSlug = toKebabCase(mainSlug);
+      if (selectedVariantKey === 'Default') {
+        setHash(kebabMainSlug);
+      } else {
+        var kebabVariantName = toKebabCase(selectedVariantKey);
+        setHash("".concat(kebabMainSlug, ":").concat(kebabVariantName));
       }
-      // Otherwise, don't update - either no hash exists or hash is for a different demo
+    } else {
+      // Remove entire hash
+      setHash(null);
     }
-  }, [selectedVariant, selectedFileNameInternal, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, hasUserInteraction, setHash, hash]);
+    prevVariantKeyRef.current = selectedVariantKey;
+  }, [selectedVariantKey, hash, mainSlug, fileHashMode, setHash, isHashDrivenVariantChange]);
 
   // Compute the displayed filename (transformed if applicable)
   var selectedFileName = React.useMemo(function () {
@@ -446,15 +476,12 @@ export function useFileNavigation(_ref) {
       return [];
     }
 
-    // Determine if this is the initial variant
-    var isInitialVariant = initialVariant ? selectedVariantKey === initialVariant : variantKeys.length === 0 || selectedVariantKey === variantKeys[0];
-
     // If we have transformed files, use them
     if (transformedFiles) {
       return transformedFiles.files.map(function (f) {
         return {
           name: f.name,
-          slug: generateFileSlug(mainSlug, f.originalName, selectedVariantKey, isInitialVariant),
+          slug: generateFileSlug(mainSlug, f.originalName, selectedVariantKey),
           component: f.component
         };
       });
@@ -467,7 +494,7 @@ export function useFileNavigation(_ref) {
     if (selectedVariant.fileName && selectedVariant.source) {
       result.push({
         name: selectedVariant.fileName,
-        slug: generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey, isInitialVariant),
+        slug: generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey),
         component: /*#__PURE__*/_jsx(Pre, {
           className: preClassName,
           ref: preRef,
@@ -494,7 +521,7 @@ export function useFileNavigation(_ref) {
         }
         result.push({
           name: fileName,
-          slug: generateFileSlug(mainSlug, fileName, selectedVariantKey, isInitialVariant),
+          slug: generateFileSlug(mainSlug, fileName, selectedVariantKey),
           component: /*#__PURE__*/_jsx(Pre, {
             className: preClassName,
             ref: preRef,
@@ -505,7 +532,7 @@ export function useFileNavigation(_ref) {
       });
     }
     return result;
-  }, [selectedVariant, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, shouldHighlight, preClassName, preRef]);
+  }, [selectedVariant, transformedFiles, mainSlug, selectedVariantKey, shouldHighlight, preClassName, preRef]);
 
   // Create a wrapper for selectFileName that handles transformed filenames and URL updates
   var selectFileName = React.useCallback(function (fileName) {
@@ -513,10 +540,6 @@ export function useFileNavigation(_ref) {
       return;
     }
     var targetFileName = fileName;
-    var fileSlug = '';
-
-    // Determine if this is the initial variant
-    var isInitialVariant = initialVariant ? selectedVariantKey === initialVariant : variantKeys.length === 0 || selectedVariantKey === variantKeys[0];
 
     // If we have transformed files, we need to reverse-lookup the original filename
     if (transformedFiles) {
@@ -526,7 +549,6 @@ export function useFileNavigation(_ref) {
       });
       if (fileByTransformedName) {
         targetFileName = fileByTransformedName.originalName;
-        fileSlug = generateFileSlug(mainSlug, fileByTransformedName.originalName, selectedVariantKey, isInitialVariant);
       } else {
         // Check if the fileName is already an original name
         var fileByOriginalName = transformedFiles.files.find(function (f) {
@@ -534,21 +556,32 @@ export function useFileNavigation(_ref) {
         });
         if (fileByOriginalName) {
           targetFileName = fileName;
-          fileSlug = generateFileSlug(mainSlug, fileName, selectedVariantKey, isInitialVariant);
         }
       }
-    } else {
-      // No transformed files, generate slug directly
-      fileSlug = generateFileSlug(mainSlug, fileName, selectedVariantKey, isInitialVariant);
     }
 
-    // Update the URL hash without adding to history (replaceState)
-    if (typeof window !== 'undefined' && fileSlug && hash !== fileSlug) {
-      setHash(fileSlug); // Use the new URL hash hook
+    // Handle hash removal based on fileHashMode
+    if (typeof window !== 'undefined' && isHashRelevantToDemo(hash, mainSlug)) {
+      // Save variant to localStorage if on-interaction mode (clicking a tab counts as interaction)
+      if (saveVariantToLocalStorage && saveHashVariantToLocalStorage === 'on-interaction') {
+        saveVariantToLocalStorage(selectedVariantKey);
+      }
+      if (fileHashMode === 'remove-filename') {
+        // Keep variant in hash: mainSlug or mainSlug:variant (for non-Default variants)
+        var kebabMainSlug = toKebabCase(mainSlug);
+        if (selectedVariantKey === 'Default') {
+          setHash(kebabMainSlug);
+        } else {
+          var kebabVariantName = toKebabCase(selectedVariantKey);
+          setHash("".concat(kebabMainSlug, ":").concat(kebabVariantName));
+        }
+      } else {
+        // Remove entire hash
+        setHash(null);
+      }
     }
-    markUserInteraction(); // Mark that user has made an explicit selection
     setSelectedFileNameInternal(targetFileName);
-  }, [selectedVariant, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, setHash, markUserInteraction, hash]);
+  }, [selectedVariant, transformedFiles, mainSlug, selectedVariantKey, fileHashMode, hash, setHash, saveHashVariantToLocalStorage, saveVariantToLocalStorage]);
 
   // Memoized array of all file slugs for all variants
   var allFilesSlugs = React.useMemo(function () {
@@ -570,14 +603,24 @@ export function useFileNavigation(_ref) {
           return 1; // continue
         }
 
-        // Determine if this is the initial variant
-        var isInitialVariant = initialVariant ? variantKey === initialVariant : variantKeys.length === 0 || variantKey === variantKeys[0];
+        // Add variant-only slug (points to main file of the variant)
+        // Skip for Default variant since it doesn't have variant name in hash
+        if (variant.fileName && variantKey !== 'Default') {
+          var kebabMainSlug = toKebabCase(mainSlug);
+          var kebabVariantName = toKebabCase(variantKey);
+          var variantOnlySlug = "".concat(kebabMainSlug, ":").concat(kebabVariantName);
+          result.push({
+            fileName: variant.fileName,
+            slug: variantOnlySlug,
+            variantName: variantKey
+          });
+        }
 
         // Add main file if it exists
         if (variant.fileName) {
           result.push({
             fileName: variant.fileName,
-            slug: generateFileSlug(mainSlug, variant.fileName, variantKey, isInitialVariant),
+            slug: generateFileSlug(mainSlug, variant.fileName, variantKey),
             variantName: variantKey
           });
         }
@@ -587,7 +630,7 @@ export function useFileNavigation(_ref) {
           Object.keys(variant.extraFiles).forEach(function (fileName) {
             result.push({
               fileName: fileName,
-              slug: generateFileSlug(mainSlug, fileName, variantKey, isInitialVariant),
+              slug: generateFileSlug(mainSlug, fileName, variantKey),
               variantName: variantKey
             });
           });
@@ -602,7 +645,7 @@ export function useFileNavigation(_ref) {
       _iterator2.f();
     }
     return result;
-  }, [effectiveCode, variantKeys, initialVariant, mainSlug]);
+  }, [effectiveCode, variantKeys, mainSlug]);
   return {
     selectedFileName: selectedFileName,
     selectedFile: selectedFile,

package/esm/useCode/useUIState.d.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 interface UseUIStateProps {
   defaultOpen?: boolean;
+  mainSlug?: string;
 }
 export interface UseUIStateResult {
   expanded: boolean;
@@ -9,8 +10,10 @@ export interface UseUIStateResult {
 }
 /**
  * Hook for managing UI state like expansion and focus
+ * Auto-expands if there's a relevant hash for this demo
  */
 export declare function useUIState({
-  defaultOpen
+  defaultOpen,
+  mainSlug
 }: UseUIStateProps): UseUIStateResult;
 export {};

package/esm/useCode/useUIState.js

@@ -1,18 +1,33 @@
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import * as React from 'react';
+import { useUrlHashState } from "../useUrlHashState/index.js";
+import { isHashRelevantToDemo } from "./useFileNavigation.js";
 /**
  * Hook for managing UI state like expansion and focus
+ * Auto-expands if there's a relevant hash for this demo
  */
 export function useUIState(_ref) {
   var _ref$defaultOpen = _ref.defaultOpen,
-    defaultOpen = _ref$defaultOpen === void 0 ? false : _ref$defaultOpen;
-  var _React$useState = React.useState(defaultOpen),
+    defaultOpen = _ref$defaultOpen === void 0 ? false : _ref$defaultOpen,
+    mainSlug = _ref.mainSlug;
+  var _useUrlHashState = useUrlHashState(),
+    _useUrlHashState2 = _slicedToArray(_useUrlHashState, 1),
+    hash = _useUrlHashState2[0];
+  var hasRelevantHash = isHashRelevantToDemo(hash, mainSlug);
+  var _React$useState = React.useState(defaultOpen || hasRelevantHash),
     _React$useState2 = _slicedToArray(_React$useState, 2),
     expanded = _React$useState2[0],
     setExpanded = _React$useState2[1];
   var expand = React.useCallback(function () {
     return setExpanded(true);
   }, []);
+
+  // Auto-expand if hash becomes relevant
+  React.useEffect(function () {
+    if (hasRelevantHash && !expanded) {
+      setExpanded(true);
+    }
+  }, [hasRelevantHash, expanded]);
   return {
     expanded: expanded,
     expand: expand,

package/esm/useCode/useVariantSelection.d.ts

@@ -5,22 +5,27 @@ interface UseVariantSelectionProps {
   initialVariant?: string;
   variantType?: string;
   mainSlug?: string;
+  saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
 }
 export interface UseVariantSelectionResult {
   variantKeys: string[];
   selectedVariantKey: string;
   selectedVariant: VariantCode | null;
-  selectVariant: React.Dispatch<React.SetStateAction<string>>;
+  selectVariant: React.Dispatch<React.SetStateAction<string | null>>;
   selectVariantProgrammatic: React.Dispatch<React.SetStateAction<string>>;
+  saveVariantToLocalStorage: (variant: string) => void;
+  hashVariant: string | null;
 }
 /**
  * Hook for managing variant selection and providing variant-related data
- * Uses React state as source of truth, with localStorage for persistence
+ * Priority: URL hash > localStorage > initialVariant > first variant
+ * When hash has a variant, it overrides localStorage and is saved to localStorage
  */
 export declare function useVariantSelection({
   effectiveCode,
   initialVariant,
   variantType,
-  mainSlug
+  mainSlug,
+  saveHashVariantToLocalStorage
 }: UseVariantSelectionProps): UseVariantSelectionResult;
 export {};