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

package/esm/pipeline/transformMarkdownMetadata/types.d.ts

@@ -0,0 +1,110 @@
+import type { PhrasingContent } from 'mdast';
+/**
+ * Plugin options for transformMarkdownMetadata
+ */
+export interface TransformMarkdownMetadataOptions {
+  /**
+   * A suffix to append to the title when saving it to the `export const metadata` object.
+   * This suffix is not included in the metadata used for index extraction or returned metadata.
+   *
+   * Useful for adding site-wide title suffixes like " | My Site" to page metadata.
+   *
+   * @example
+   * ```ts
+   * transformMarkdownMetadata({ titleSuffix: ' | Base UI' })
+   * // Title "Button" becomes "Button | Base UI" in the export
+   * ```
+   */
+  titleSuffix?: string;
+  /**
+   * Controls automatic extraction of page metadata to parent directory index files.
+   *
+   * When enabled, the plugin extracts metadata (title, description, headings) from MDX files
+   * and maintains an index in the parent directory's page.mdx file.
+   *
+   * Index files themselves (e.g., pattern/page.mdx) are automatically excluded from extraction.
+   *
+   * Can be:
+   * - `false` - Disabled
+   * - `true` - Enabled with default filter: `{ include: ['app/'], exclude: [] }`
+   * - `{ include: string[], exclude: string[] }` - Enabled with custom path filters
+   *
+   * Path matching uses prefix matching - a file matches if it starts with any include path
+   * and doesn't start with any exclude path. Files that are index files themselves
+   * (matching pattern/page.mdx) are automatically skipped.
+   */
+  extractToIndex?: boolean | {
+    /** Path prefixes that files must match to have metadata extracted */
+    include: string[];
+    /** Path prefixes to exclude from metadata extraction */
+    exclude: string[];
+    /** Base directory to strip from file paths before matching (e.g., '/path/to/project/docs') */
+    baseDir?: string;
+    /** Only update existing indexes, don't create new ones */
+    onlyUpdateIndexes?: boolean;
+    /**
+     * Directory to write marker files when indexes are updated.
+     * Path is relative to baseDir.
+     * Set to false to disable marker file creation.
+     * @default false
+     */
+    markerDir?: string | false;
+    /**
+     * Throw an error if the index is out of date or missing.
+     * Useful for CI environments to ensure indexes are committed.
+     * @default false
+     */
+    errorIfOutOfDate?: boolean;
+    /**
+     * Use the first visible paragraph as the description in the extracted index,
+     * even if a meta tag description is present.
+     * This does not affect the `export const metadata` which will still use the meta tag.
+     * @default false
+     */
+    useVisibleDescription?: boolean;
+    /**
+     * Name of a React component to wrap around the autogenerated index content.
+     * If provided, the generated markdown will wrap the page list and detail sections
+     * in this component (e.g., `<PagesIndex>...</PagesIndex>`).
+     *
+     * When processing autogenerated index files, the plugin will also automatically
+     * inject `SitemapSectionData` as a `data` prop to this wrapper component,
+     * enabling dynamic rendering, search, or navigation features.
+     *
+     * @example 'PagesIndex'
+     */
+    indexWrapperComponent?: string;
+  };
+}
+/**
+ * Represents a hierarchical structure of headings.
+ * Each heading is keyed by its slug, with title and nested children.
+ */
+export type HeadingHierarchy = {
+  [slug: string]: {
+    title: string;
+    titleMarkdown: PhrasingContent[];
+    children: HeadingHierarchy;
+  };
+};
+/**
+ * Extracted metadata from markdown/MDX files
+ */
+export interface ExtractedMetadata {
+  title?: string;
+  description?: string;
+  descriptionMarkdown?: PhrasingContent[];
+  keywords?: string[];
+  sections?: HeadingHierarchy;
+  embeddings?: number[];
+  openGraph?: {
+    title?: string;
+    description?: string;
+    images?: Array<{
+      url: string;
+      width: number;
+      height: number;
+      alt: string;
+    }>;
+  };
+}

package/esm/pipeline/transformMarkdownMetadata/types.js

@@ -0,0 +1 @@
+export {};

package/esm/pipeline/transformMarkdownRelativePaths/index.d.ts

@@ -0,0 +1,2 @@
+import { transformMarkdownRelativePaths } from "./transformMarkdownRelativePaths.js";
+export default transformMarkdownRelativePaths;

package/esm/pipeline/transformMarkdownRelativePaths/index.js

@@ -0,0 +1,4 @@
+// This is the export format expected by a remark plugin.
+
+import { transformMarkdownRelativePaths } from "./transformMarkdownRelativePaths.js";
+export default transformMarkdownRelativePaths;

package/esm/pipeline/transformMarkdownRelativePaths/transformMarkdownRelativePaths.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from 'unified';
+/**
+ * Remark plugin that strips page file extensions from URLs.
+ * Removes /page.tsx, /page.jsx, /page.js, /page.mdx, /page.md from both absolute and relative URLs.
+ * For relative URLs (both ./ and ../), converts them to absolute paths based on the current file's location.
+ * Also removes Next.js route group segments (parenthesis) from URLs.
+ *
+ * Examples:
+ * - /components/page.tsx -> /components
+ * - ./code-highlighter/page.mdx -> /components/code-highlighter (when processed from /components/page.mdx)
+ * - ../code-highlighter/page.tsx -> /code-highlighter (when processed from /components/button/page.mdx)
+ * - /(public)/components/page.tsx -> /components
+ * This allows URLs to resolve when reading in VSCode and Github
+ */
+export declare const transformMarkdownRelativePaths: Plugin;

package/esm/pipeline/transformMarkdownRelativePaths/transformMarkdownRelativePaths.js

@@ -0,0 +1,40 @@
+// webpack does not like node: imports
+// eslint-disable-next-line n/prefer-node-protocol
+import path from 'path';
+import { visit } from 'unist-util-visit';
+/**
+ * Remark plugin that strips page file extensions from URLs.
+ * Removes /page.tsx, /page.jsx, /page.js, /page.mdx, /page.md from both absolute and relative URLs.
+ * For relative URLs (both ./ and ../), converts them to absolute paths based on the current file's location.
+ * Also removes Next.js route group segments (parenthesis) from URLs.
+ *
+ * Examples:
+ * - /components/page.tsx -> /components
+ * - ./code-highlighter/page.mdx -> /components/code-highlighter (when processed from /components/page.mdx)
+ * - ../code-highlighter/page.tsx -> /code-highlighter (when processed from /components/button/page.mdx)
+ * - /(public)/components/page.tsx -> /components
+ * This allows URLs to resolve when reading in VSCode and Github
+ */
+export var transformMarkdownRelativePaths = function transformMarkdownRelativePaths() {
+  return function (tree, file) {
+    visit(tree, 'link', function (node) {
+      if (node.url) {
+        node.url = node.url.replace(/\/page\.(tsx|jsx|js|mdx|md)$/g, '');
+        node.url = node.url.replace(/\/page\.(tsx|jsx|js|mdx|md)(\?[^#]*)?(#.*)?$/g, '$2$3');
+        if ((node.url.startsWith('./') || node.url.startsWith('../')) && file.path) {
+          var currentDir = path.dirname(file.path);
+          var appIndex = currentDir.indexOf('/app/');
+          var baseDir = appIndex !== -1 ? currentDir.substring(appIndex + 4) : '/';
+
+          // Resolve the relative path from the current directory
+          var resolvedPath = path.resolve('/', baseDir, node.url);
+          node.url = resolvedPath;
+        }
+
+        // Remove Next.js route group segments (parenthesis)
+        node.url = node.url.replace(/\/\([^)]+\)/g, '');
+        node.url = node.url.replace(/\/$/, '');
+      }
+    });
+  };
+};

package/esm/useCode/Pre.js

@@ -105,10 +105,16 @@ export function Pre(_ref) {
     }, {
       rootMargin: hydrateMargin
     });
-    root.childNodes.forEach(function (node) {
+
+    // <pre><code><span class="frame" data-frame="0">...</span><span class="frame" data-frame="1">...</span>...</code></pre>
+    root.childNodes[0].childNodes.forEach(function (node) {
       if (node.nodeType === Node.ELEMENT_NODE) {
         var _observer$current;
         var element = node;
+        if (!element.hasAttribute('data-frame')) {
+          console.warn('Expected frame element in useCode <Pre>', element);
+          return;
+        }
         (_observer$current = observer.current) == null || _observer$current.observe(element);
       }
     });
@@ -128,6 +134,11 @@ export function Pre(_ref) {
   var frames = React.useMemo(function () {
     return hast == null ? void 0 : hast.children.map(function (child, index) {
       if (child.type !== 'element') {
+        if (child.type === 'text') {
+          return /*#__PURE__*/_jsx(React.Fragment, {
+            children: child.value
+          }, index);
+        }
         return null;
       }
       if (child.properties.className === 'frame') {
@@ -150,6 +161,8 @@ export function Pre(_ref) {
   return /*#__PURE__*/_jsx("pre", {
     ref: bindIntersectionObserver,
     className: className,
-    children: typeof children === 'string' ? children : frames
+    children: /*#__PURE__*/_jsx("code", {
+      children: typeof children === 'string' ? children : frames
+    })
   });
 }

package/esm/useCode/useCode.d.ts

@@ -9,6 +9,19 @@ export type UseCodeOpts = {
   githubUrlPrefix?: string;
   initialVariant?: string;
   initialTransform?: string;
+  /**
+   * Controls hash removal behavior when user interacts with file tabs:
+   * - 'remove-hash': Remove entire hash (default)
+   * - 'remove-filename': Remove only filename, keep variant in hash
+   */
+  fileHashMode?: 'remove-hash' | 'remove-filename';
+  /**
+   * Controls when to save hash variant to localStorage:
+   * - 'on-load': Save immediately when page loads with hash
+   * - 'on-interaction': Save only when user clicks a tab (default)
+   * - 'never': Never save hash variant to localStorage
+   */
+  saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
 };
 type UserProps<T extends {} = {}> = T & {
   name?: string;
@@ -17,7 +30,7 @@ type UserProps<T extends {} = {}> = T & {
 export interface UseCodeResult<T extends {} = {}> {
   variants: string[];
   selectedVariant: string;
-  selectVariant: React.Dispatch<React.SetStateAction<string>>;
+  selectVariant: (variant: string | null) => void;
   files: Array<{
     name: string;
     slug?: string;
@@ -34,7 +47,7 @@ export interface UseCodeResult<T extends {} = {}> {
   }>;
   expanded: boolean;
   expand: () => void;
-  setExpanded: React.Dispatch<React.SetStateAction<boolean>>;
+  setExpanded: (expanded: boolean) => void;
   copy: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void>;
   availableTransforms: string[];
   selectedTransform: string | null | undefined;

package/esm/useCode/useCode.js

@@ -18,7 +18,11 @@ export function useCode(contentProps, opts) {
     initialVariant = _ref.initialVariant,
     initialTransform = _ref.initialTransform,
     preClassName = _ref.preClassName,
-    preRef = _ref.preRef;
+    preRef = _ref.preRef,
+    _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;
 
   // Safely try to get context values - will be undefined if not in context
   var context = useCodeHighlighterContextOptional();
@@ -58,9 +62,10 @@ export function useCode(contentProps, opts) {
     });
   }, [contentProps, context == null ? void 0 : context.url]);
 
-  // Sub-hook: UI State Management
+  // Sub-hook: UI State Management (needs slug to check for relevant hash)
   var uiState = useUIState({
-    defaultOpen: defaultOpen
+    defaultOpen: defaultOpen,
+    mainSlug: userProps.slug
   });
 
   // Sub-hook: Variant Selection
@@ -68,7 +73,8 @@ export function useCode(contentProps, opts) {
     effectiveCode: effectiveCode,
     initialVariant: initialVariant,
     variantType: contentProps.variantType,
-    mainSlug: userProps.slug
+    mainSlug: userProps.slug,
+    saveHashVariantToLocalStorage: saveHashVariantToLocalStorage
   });
 
   // Sub-hook: Transform Management
@@ -89,11 +95,14 @@ export function useCode(contentProps, opts) {
     selectedVariantKey: variantSelection.selectedVariantKey,
     selectVariant: variantSelection.selectVariantProgrammatic,
     variantKeys: variantSelection.variantKeys,
-    initialVariant: initialVariant,
     shouldHighlight: shouldHighlight,
     preClassName: preClassName,
     preRef: preRef,
-    effectiveCode: effectiveCode
+    effectiveCode: effectiveCode,
+    fileHashMode: fileHashMode,
+    saveHashVariantToLocalStorage: saveHashVariantToLocalStorage,
+    saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
+    hashVariant: variantSelection.hashVariant
   });
 
   // Sub-hook: Copy Functionality

package/esm/useCode/useCodeUtils.js

@@ -1,7 +1,7 @@
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import _typeof from "@babel/runtime/helpers/esm/typeof";
 import { stringOrHastToJsx } from "../pipeline/hastUtils/index.js";
-import { applyTransform } from "../CodeHighlighter/applyTransform.js";
+import { applyCodeTransform } from "../pipeline/loadCodeVariant/applyCodeTransform.js";
 /**
  * Pure function to get available transforms from effective code data.
  * Only includes transforms that have actual deltas (file changes), not just filename changes.
@@ -94,7 +94,7 @@ export function applyTransformToSource(source, fileName, transforms, selectedTra
     }
 
     // Apply transform
-    var result = applyTransform(source, transforms, selectedTransform);
+    var result = applyCodeTransform(source, transforms, selectedTransform);
     var transformedName = transformData.fileName || fileName;
     return {
       transformedSource: result,
@@ -209,7 +209,7 @@ export function createTransformedFiles(selectedVariant, selectedTransform, shoul
             // Only apply transform if there's a meaningful delta
             var hasTransformDelta = transformData.delta && Object.keys(transformData.delta).length > 0;
             if (hasTransformDelta) {
-              transformedSource = applyTransform(source, transforms, selectedTransform);
+              transformedSource = applyCodeTransform(source, transforms, selectedTransform);
               transformedName = transformData.fileName || extraFileName;
             }
           }

package/esm/useCode/useFileNavigation.d.ts

@@ -22,11 +22,14 @@ interface UseFileNavigationProps {
   selectedVariantKey?: string;
   variantKeys?: string[];
   shouldHighlight: boolean;
-  initialVariant?: string;
   preClassName?: string;
   preRef?: React.Ref<HTMLPreElement>;
   effectiveCode?: Code;
   selectVariant?: React.Dispatch<React.SetStateAction<string>>;
+  fileHashMode?: 'remove-hash' | 'remove-filename';
+  saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
+  saveVariantToLocalStorage?: (variant: string) => void;
+  hashVariant?: string | null;
 }
 export interface UseFileNavigationResult {
   selectedFileName: string | undefined;
@@ -54,11 +57,14 @@ export declare function useFileNavigation({
   mainSlug,
   selectedVariantKey,
   variantKeys,
-  initialVariant,
   shouldHighlight,
   preClassName,
   preRef,
   effectiveCode,
-  selectVariant
+  selectVariant,
+  fileHashMode,
+  saveHashVariantToLocalStorage,
+  saveVariantToLocalStorage,
+  hashVariant
 }: UseFileNavigationProps): UseFileNavigationResult;
 export {};