@mui/internal-docs-infra 0.2.1-canary.3 → 0.2.1

package/esm/pipeline/parseSource/addLineGutters.js

@@ -129,9 +129,9 @@ export function starryNightGutter(tree, sourceLines) {
       for (_iterator.s(); !(_step = _iterator.n()).done;) {
         var _frame$properties;
         var frame = _step.value;
-        if (frame.type === 'element' && frame.tagName === 'span' && ((_frame$properties = frame.properties) == null ? void 0 : _frame$properties.className) === 'frame' && typeof frame.properties.frameStartLine === 'number' && typeof frame.properties.frameEndLine === 'number') {
-          var startLine = frame.properties.frameStartLine - 1; // Convert to 0-based index
-          var endLine = frame.properties.frameEndLine; // This is already inclusive
+        if (frame.type === 'element' && frame.tagName === 'span' && ((_frame$properties = frame.properties) == null ? void 0 : _frame$properties.className) === 'frame' && typeof frame.properties.dataFrameStartLine === 'number' && typeof frame.properties.dataFrameEndLine === 'number') {
+          var startLine = frame.properties.dataFrameStartLine - 1; // Convert to 0-based index
+          var endLine = frame.properties.dataFrameEndLine; // This is already inclusive
           frame.properties.dataAsString = sourceLines.slice(startLine, endLine).join('\n');
         }
       }
@@ -169,8 +169,8 @@ function createFrame(frameChildren, sourceLines, startLine, endLine) {
 
   // Store line range information if provided (for dataAsString generation)
   if (sourceLines && startLine !== undefined && endLine !== undefined) {
-    properties.frameStartLine = startLine;
-    properties.frameEndLine = endLine;
+    properties.dataFrameStartLine = startLine;
+    properties.dataFrameEndLine = endLine;
   }
   return {
     type: 'element',

package/esm/useCode/useCode.d.ts

@@ -27,6 +27,11 @@ export interface UseCodeResult<T extends {} = {}> {
   selectedFileLines: number;
   selectedFileName: string | undefined;
   selectFileName: (fileName: string) => void;
+  allFilesSlugs: Array<{
+    fileName: string;
+    slug: string;
+    variantName: string;
+  }>;
   expanded: boolean;
   expand: () => void;
   setExpanded: React.Dispatch<React.SetStateAction<boolean>>;

package/esm/useCode/useCode.js

@@ -86,11 +86,13 @@ export function useCode(contentProps, opts) {
     transformedFiles: transformManagement.transformedFiles,
     mainSlug: userProps.slug,
     selectedVariantKey: variantSelection.selectedVariantKey,
+    selectVariant: variantSelection.selectVariantProgrammatic,
     variantKeys: variantSelection.variantKeys,
     initialVariant: initialVariant,
     shouldHighlight: shouldHighlight,
     preClassName: preClassName,
-    preRef: preRef
+    preRef: preRef,
+    effectiveCode: effectiveCode
   });
 
   // Sub-hook: Copy Functionality
@@ -115,6 +117,7 @@ export function useCode(contentProps, opts) {
     selectedFileLines: fileNavigation.selectedFileLines,
     selectedFileName: fileNavigation.selectedFileName,
     selectFileName: fileNavigation.selectFileName,
+    allFilesSlugs: fileNavigation.allFilesSlugs,
     expanded: uiState.expanded,
     expand: uiState.expand,
     setExpanded: uiState.setExpanded,

package/esm/useCode/useFileNavigation.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { VariantCode, VariantSource } from "../CodeHighlighter/types.js";
+import type { VariantCode, VariantSource, Code } from "../CodeHighlighter/types.js";
 import type { TransformedFiles } from "./useCodeUtils.js";
 interface UseFileNavigationProps {
   selectedVariant: VariantCode | null;
@@ -11,6 +11,8 @@ interface UseFileNavigationProps {
   initialVariant?: string;
   preClassName?: string;
   preRef?: React.Ref<HTMLPreElement>;
+  effectiveCode?: Code;
+  selectVariant?: React.Dispatch<React.SetStateAction<string>>;
 }
 export interface UseFileNavigationResult {
   selectedFileName: string | undefined;
@@ -23,6 +25,11 @@ export interface UseFileNavigationResult {
     component: React.ReactNode;
   }>;
   selectFileName: (fileName: string) => void;
+  allFilesSlugs: Array<{
+    fileName: string;
+    slug: string;
+    variantName: string;
+  }>;
 }
 /**
  * Hook for managing file selection and navigation within a code variant
@@ -36,6 +43,8 @@ export declare function useFileNavigation({
   initialVariant,
   shouldHighlight,
   preClassName,
-  preRef
+  preRef,
+  effectiveCode,
+  selectVariant
 }: UseFileNavigationProps): UseFileNavigationResult;
 export {};

package/esm/useCode/useFileNavigation.js

@@ -68,7 +68,9 @@ export function useFileNavigation(_ref) {
     initialVariant = _ref.initialVariant,
     shouldHighlight = _ref.shouldHighlight,
     preClassName = _ref.preClassName,
-    preRef = _ref.preRef;
+    preRef = _ref.preRef,
+    effectiveCode = _ref.effectiveCode,
+    selectVariant = _ref.selectVariant;
   // 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),
@@ -92,70 +94,151 @@ export function useFileNavigation(_ref) {
     hash = _useUrlHashState2[0],
     setHash = _useUrlHashState2[1];
 
+  // Track if we're waiting for a variant switch to complete, and which file to select after
+  var pendingFileSelection = React.useRef(null);
+  var justCompletedPendingSelection = React.useRef(false);
+
   // Helper function to check URL hash and switch to matching file
   var checkUrlHashAndSelectFile = React.useCallback(function () {
-    if (!selectedVariant || !hash) {
+    if (!hash) {
       return;
     }
 
-    // Check if hash matches any file slug
+    // Try to find matching file - check current variant first
     var matchingFileName;
+    var matchingVariantKey;
+
+    // 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);
+        if (hash === mainFileSlug) {
+          matchingFileName = selectedVariant.fileName;
+          matchingVariantKey = selectedVariantKey;
+        }
+      }
 
-    // Determine if this is the initial variant
-    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);
-      if (hash === mainFileSlug) {
-        matchingFileName = selectedVariant.fileName;
+      // Check extra files
+      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);
+          if (hash === fileSlug) {
+            matchingFileName = fileName;
+            matchingVariantKey = selectedVariantKey;
+            break;
+          }
+        }
       }
-    }
 
-    // Check extra files
-    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);
-        if (hash === fileSlug) {
-          matchingFileName = fileName;
-          break;
+      // Check transformed files
+      if (!matchingFileName && transformedFiles) {
+        var _iterator = _createForOfIteratorHelper(transformedFiles.files),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var file = _step.value;
+            var _fileSlug = generateFileSlug(mainSlug, file.originalName, selectedVariantKey, isInitialVariant);
+            if (hash === _fileSlug) {
+              matchingFileName = file.originalName;
+              matchingVariantKey = selectedVariantKey;
+              break;
+            }
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
         }
       }
     }
 
-    // Check transformed files if available
-    if (!matchingFileName && transformedFiles) {
-      var _iterator = _createForOfIteratorHelper(transformedFiles.files),
-        _step;
-      try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
-          var file = _step.value;
-          var _fileSlug = generateFileSlug(mainSlug, file.originalName, selectedVariantKey, isInitialVariant);
-          if (hash === _fileSlug) {
-            matchingFileName = file.originalName;
+    // Step 2: If no match and we can switch variants, search other variants
+    if (!matchingFileName && effectiveCode && selectVariant) {
+      for (var _i2 = 0, _Object$entries = Object.entries(effectiveCode); _i2 < _Object$entries.length; _i2++) {
+        var _Object$entries$_i = _slicedToArray(_Object$entries[_i2], 2),
+          variantKey = _Object$entries$_i[0],
+          variant = _Object$entries$_i[1];
+        // Skip current variant (already checked) and invalid variants
+        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);
+          if (hash === _mainFileSlug) {
+            matchingFileName = variant.fileName;
+            matchingVariantKey = variantKey;
             break;
           }
         }
-      } catch (err) {
-        _iterator.e(err);
-      } finally {
-        _iterator.f();
+
+        // Check extra files
+        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);
+            if (hash === _fileSlug2) {
+              matchingFileName = _fileName;
+              matchingVariantKey = variantKey;
+              break;
+            }
+          }
+        }
+        if (matchingFileName) {
+          break;
+        }
       }
     }
-    if (matchingFileName) {
+    if (matchingFileName && matchingVariantKey) {
+      // If the matching file is in a different variant, switch to that variant first
+      if (matchingVariantKey !== selectedVariantKey && selectVariant) {
+        // Remember which file to select after variant switch
+        pendingFileSelection.current = matchingFileName;
+        selectVariant(matchingVariantKey);
+        // Don't set the file here - it will be set after variant changes
+        return;
+      }
+
+      // Set the file if we're in the correct variant
+      pendingFileSelection.current = null;
       setSelectedFileNameInternal(matchingFileName);
-      markUserInteraction(); // Mark that user has made a selection via URL
+      markUserInteraction();
     }
-  }, [selectedVariant, hash, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, markUserInteraction]);
+  }, [hash, selectedVariant, selectedVariantKey, variantKeys, initialVariant, mainSlug, transformedFiles, effectiveCode, selectVariant, markUserInteraction]);
 
-  // On hydration/variant change, check URL hash and switch to matching file
+  // 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();
-  }, [checkUrlHashAndSelectFile]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hash]);
+
+  // When variant switches with a pending file selection, complete the file selection
+  React.useEffect(function () {
+    if (pendingFileSelection.current && selectedVariant) {
+      var fileToSelect = pendingFileSelection.current;
+      pendingFileSelection.current = null;
+      justCompletedPendingSelection.current = true;
+      setSelectedFileNameInternal(fileToSelect);
+      markUserInteraction();
+    } else {
+      justCompletedPendingSelection.current = false;
+    }
+  }, [selectedVariantKey, selectedVariant, markUserInteraction]);
 
   // Reset selectedFileName when variant changes
   React.useEffect(function () {
+    // Skip reset if we have a pending file selection from hash navigation
+    // OR if we just completed a pending file selection
+    if (pendingFileSelection.current || justCompletedPendingSelection.current) {
+      return;
+    }
     if (selectedVariant && selectedFileNameInternal !== selectedVariant.fileName) {
       // Only reset if current selectedFileName doesn't exist in the new variant
       var hasFile = selectedVariant.fileName === selectedFileNameInternal || selectedFileNameInternal && selectedVariant.extraFiles && selectedVariant.extraFiles[selectedFileNameInternal];
@@ -189,7 +272,13 @@ export function useFileNavigation(_ref) {
 
     // Only update the URL hash if it's different from current hash
     if (fileSlug && hash !== fileSlug) {
-      setHash(fileSlug); // Use the new URL hash hook
+      // 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
+      var expectedBaseSlug = toKebabCase(mainSlug);
+      if (hash && hash.startsWith("".concat(expectedBaseSlug, ":"))) {
+        setHash(fileSlug);
+      }
+      // Otherwise, don't update - either no hash exists or hash is for a different demo
     }
   }, [selectedVariant, selectedFileNameInternal, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, hasUserInteraction, setHash, hash]);
 
@@ -446,12 +535,67 @@ export function useFileNavigation(_ref) {
     markUserInteraction(); // Mark that user has made an explicit selection
     setSelectedFileNameInternal(targetFileName);
   }, [selectedVariant, transformedFiles, mainSlug, selectedVariantKey, variantKeys, initialVariant, setHash, markUserInteraction, hash]);
+
+  // Memoized array of all file slugs for all variants
+  var allFilesSlugs = React.useMemo(function () {
+    var result = [];
+    if (!effectiveCode || !variantKeys.length) {
+      return result;
+    }
+
+    // Iterate through all variants
+    var _iterator2 = _createForOfIteratorHelper(variantKeys),
+      _step2;
+    try {
+      var _loop = function _loop() {
+        var variantKey = _step2.value;
+        var variant = effectiveCode[variantKey];
+
+        // Skip invalid variants
+        if (!variant || typeof variant === 'string') {
+          return 1; // continue
+        }
+
+        // Determine if this is the initial variant
+        var isInitialVariant = initialVariant ? variantKey === initialVariant : variantKeys.length === 0 || variantKey === variantKeys[0];
+
+        // Add main file if it exists
+        if (variant.fileName) {
+          result.push({
+            fileName: variant.fileName,
+            slug: generateFileSlug(mainSlug, variant.fileName, variantKey, isInitialVariant),
+            variantName: variantKey
+          });
+        }
+
+        // Add extra files
+        if (variant.extraFiles) {
+          Object.keys(variant.extraFiles).forEach(function (fileName) {
+            result.push({
+              fileName: fileName,
+              slug: generateFileSlug(mainSlug, fileName, variantKey, isInitialVariant),
+              variantName: variantKey
+            });
+          });
+        }
+      };
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        if (_loop()) continue;
+      }
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    return result;
+  }, [effectiveCode, variantKeys, initialVariant, mainSlug]);
   return {
     selectedFileName: selectedFileName,
     selectedFile: selectedFile,
     selectedFileComponent: selectedFileComponent,
     selectedFileLines: selectedFileLines,
     files: files,
+    allFilesSlugs: allFilesSlugs,
     selectFileName: selectFileName
   };
 }

package/esm/useCode/useVariantSelection.d.ts

@@ -10,10 +10,11 @@ export interface UseVariantSelectionResult {
   selectedVariantKey: string;
   selectedVariant: VariantCode | null;
   selectVariant: React.Dispatch<React.SetStateAction<string>>;
+  selectVariantProgrammatic: React.Dispatch<React.SetStateAction<string>>;
 }
 /**
  * Hook for managing variant selection and providing variant-related data
- * Uses the useLocalStorage hook for local storage persistence of variant preferences
+ * Uses React state as source of truth, with localStorage for persistence
  */
 export declare function useVariantSelection({
   effectiveCode,

package/esm/useCode/useVariantSelection.js

@@ -4,7 +4,7 @@ import * as React from 'react';
 import { usePreference } from "../usePreference/index.js";
 /**
  * Hook for managing variant selection and providing variant-related data
- * Uses the useLocalStorage hook for local storage persistence of variant preferences
+ * Uses React state as source of truth, with localStorage for persistence
  */
 export function useVariantSelection(_ref) {
   var effectiveCode = _ref.effectiveCode,
@@ -18,38 +18,59 @@ export function useVariantSelection(_ref) {
     });
   }, [effectiveCode]);
 
-  // Use localStorage hook for variant persistence - this is our single source of truth
+  // Use localStorage hook for variant persistence
   var _usePreference = usePreference('variant', variantType || variantKeys, function () {
-      // Don't use initialVariant as the fallback - localStorage should take precedence
-      // We'll handle the initial variant separately in the selectedVariantKey logic
       return null;
     }),
     _usePreference2 = _slicedToArray(_usePreference, 2),
     storedValue = _usePreference2[0],
     setStoredValue = _usePreference2[1];
 
-  // Handle validation manually - localStorage should take precedence over initialVariant
-  var selectedVariantKey = React.useMemo(function () {
-    // First priority: use stored value if it exists and is valid
-    if (storedValue && variantKeys.includes(storedValue)) {
-      return storedValue;
-    }
+  // Initialize state from localStorage or initialVariant
+  var _React$useState = React.useState(function () {
+      // First priority: use stored value if it exists and is valid
+      if (storedValue && variantKeys.includes(storedValue)) {
+        return storedValue;
+      }
 
-    // Second priority: use initial variant if provided and valid (only when no localStorage value)
-    if (initialVariant && variantKeys.includes(initialVariant)) {
-      return initialVariant;
-    }
+      // Second priority: use initial variant if provided and valid
+      if (initialVariant && variantKeys.includes(initialVariant)) {
+        return initialVariant;
+      }
 
-    // Final fallback: use first available variant
-    return variantKeys[0] || '';
-  }, [storedValue, variantKeys, initialVariant]);
-  var setSelectedVariantKey = React.useCallback(function (value) {
-    setStoredValue(value);
-  }, [setStoredValue]);
+      // Final fallback: use first available variant
+      return variantKeys[0] || '';
+    }),
+    _React$useState2 = _slicedToArray(_React$useState, 2),
+    selectedVariantKey = _React$useState2[0],
+    setSelectedVariantKeyState = _React$useState2[1];
+
+  // Sync with localStorage changes (but don't override programmatic changes)
+  // Only sync when storedValue changes, not when selectedVariantKey changes
+  var prevStoredValue = React.useRef(storedValue);
+  React.useEffect(function () {
+    if (storedValue !== prevStoredValue.current) {
+      prevStoredValue.current = storedValue;
+      if (storedValue && variantKeys.includes(storedValue) && storedValue !== selectedVariantKey) {
+        setSelectedVariantKeyState(storedValue);
+      }
+    }
+  }, [storedValue, variantKeys, selectedVariantKey]);
+  var setSelectedVariantKeyProgrammatic = React.useCallback(function (value) {
+    var resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
+    if (variantKeys.includes(resolvedValue)) {
+      // Only update React state, not localStorage
+      // This prevents conflicts with hash-driven navigation
+      setSelectedVariantKeyState(resolvedValue);
+    }
+  }, [selectedVariantKey, variantKeys]);
   var setSelectedVariantKeyAsUser = React.useCallback(function (value) {
     var resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
-    setStoredValue(resolvedValue);
-  }, [setStoredValue, selectedVariantKey]);
+    if (variantKeys.includes(resolvedValue)) {
+      setSelectedVariantKeyState(resolvedValue);
+      setStoredValue(resolvedValue);
+    }
+  }, [setStoredValue, selectedVariantKey, variantKeys]);
   var selectedVariant = React.useMemo(function () {
     var variant = effectiveCode[selectedVariantKey];
     if (variant && _typeof(variant) === 'object' && 'source' in variant) {
@@ -62,14 +83,15 @@ export function useVariantSelection(_ref) {
   React.useEffect(function () {
     if (!selectedVariant && variantKeys.length > 0) {
       // Don't mark this as a user selection - it's just a fallback
-      // Use setValue instead of setValueAsUserSelection to avoid localStorage save
-      setSelectedVariantKey(variantKeys[0]);
+      // Use programmatic setter to avoid localStorage save
+      setSelectedVariantKeyProgrammatic(variantKeys[0]);
     }
-  }, [selectedVariant, variantKeys, setSelectedVariantKey]);
+  }, [selectedVariant, variantKeys, setSelectedVariantKeyProgrammatic]);
   return {
     variantKeys: variantKeys,
     selectedVariantKey: selectedVariantKey,
     selectedVariant: selectedVariant,
-    selectVariant: setSelectedVariantKeyAsUser
+    selectVariant: setSelectedVariantKeyAsUser,
+    selectVariantProgrammatic: setSelectedVariantKeyProgrammatic
   };
 }

package/esm/useDemo/useDemo.d.ts

@@ -65,6 +65,11 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   selectedFileLines: number;
   selectedFileName: string | undefined;
   selectFileName: (fileName: string) => void;
+  allFilesSlugs: Array<{
+    fileName: string;
+    slug: string;
+    variantName: string;
+  }>;
   expanded: boolean;
   expand: () => void;
   setExpanded: React.Dispatch<React.SetStateAction<boolean>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.2.1-canary.3",
+  "version": "0.2.1",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "keywords": [
@@ -53,7 +53,6 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "gitSha": "f5f45d690b092f240dc070cb49571fa2283e6508",
   "type": "commonjs",
   "exports": {
     "./package.json": "./package.json",