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

package/esm/pipeline/syncPageIndex/mergeMetadataMarkdown.js

@@ -0,0 +1,214 @@
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+var _excluded = ["descriptionMarkdown"];
+import { markdownToMetadata, metadataToMarkdown } from "./metadataToMarkdown.js";
+
+/**
+ * Options for mergeMetadataMarkdown
+ */
+
+/**
+ * Merges new page metadata with existing markdown content, preserving the order
+ * of pages from the existing markdown when available, unless the file contains
+ * only the autogeneration marker (no editable section), in which case pages are
+ * sorted alphabetically by title.
+ *
+ * Pages are matched by their `path` property (e.g., './button/page.mdx'), not by slug.
+ * This allows multiple pages to have the same slug (anchor) while still being treated
+ * as distinct pages.
+ *
+ * @param existingMarkdown - The existing markdown content (or undefined if none exists)
+ * @param newMetadata - The new metadata to merge in
+ * @param options - Optional configuration
+ * @param options.preserveUnlisted - If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed.
+ * @param options.indexWrapperComponent - Optional component name to wrap the autogenerated content (e.g., 'PagesIndex')
+ * @returns The updated markdown content with merged metadata
+ *
+ * @example
+ * ```ts
+ * const existingMarkdown = `# Components
+ * - [Button](#button) - [Full Docs](./button/page.mdx) - A button
+ * - [Checkbox](#checkbox) - [Full Docs](./checkbox/page.mdx) - A checkbox
+ * `;
+ *
+ * const newMetadata = {
+ *   title: 'Components',
+ *   pages: [
+ *     { slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: 'Updated checkbox' },
+ *     { slug: 'button', path: './button/page.mdx', title: 'Button', description: 'Updated button' },
+ *     { slug: 'input', path: './input/page.mdx', title: 'Input', description: 'New input' },
+ *   ],
+ * };
+ *
+ * const result = await mergeMetadataMarkdown(existingMarkdown, newMetadata);
+ * // Result preserves Button, Checkbox order from existing markdown, adds Input at the end
+ * ```
+ */
+export function mergeMetadataMarkdown(_x, _x2) {
+  return _mergeMetadataMarkdown.apply(this, arguments);
+}
+function _mergeMetadataMarkdown() {
+  _mergeMetadataMarkdown = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(existingMarkdown, newMetadata) {
+    var options,
+      indexWrapperComponent,
+      path,
+      existingMetadata,
+      effectiveWrapper,
+      newPagesMap,
+      _iterator,
+      _step,
+      page,
+      pages,
+      addedPaths,
+      _iterator2,
+      _step2,
+      existingPage,
+      newPage,
+      _newPage$openGraph,
+      descriptionMarkdown,
+      existingPageWithoutDescriptionMarkdown,
+      merged,
+      _iterator3,
+      _step3,
+      _newPage,
+      pageWithTag,
+      alphabeticalSortMarker,
+      requestsAlphabeticalSort,
+      mergedMetadata,
+      _args = arguments;
+    return _regenerator().w(function (_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          options = _args.length > 2 && _args[2] !== undefined ? _args[2] : {};
+          indexWrapperComponent = options.indexWrapperComponent, path = options.path; // If no existing markdown, just convert the new metadata
+          // Use the provided wrapper unless it's null (which means remove)
+          if (existingMarkdown) {
+            _context.n = 1;
+            break;
+          }
+          return _context.a(2, metadataToMarkdown(newMetadata, {
+            indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent,
+            path: path
+          }));
+        case 1:
+          _context.n = 2;
+          return markdownToMetadata(existingMarkdown);
+        case 2:
+          existingMetadata = _context.v;
+          if (existingMetadata) {
+            _context.n = 3;
+            break;
+          }
+          return _context.a(2, metadataToMarkdown(newMetadata, {
+            indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent,
+            path: path
+          }));
+        case 3:
+          if (indexWrapperComponent === undefined) {
+            effectiveWrapper = existingMetadata.indexWrapperComponent;
+          } else if (indexWrapperComponent === null) {
+            effectiveWrapper = undefined;
+          } else {
+            effectiveWrapper = indexWrapperComponent;
+          }
+
+          // Create a map of new pages by path for quick lookup
+          newPagesMap = new Map();
+          _iterator = _createForOfIteratorHelper(newMetadata.pages);
+          try {
+            for (_iterator.s(); !(_step = _iterator.n()).done;) {
+              page = _step.value;
+              newPagesMap.set(page.path, page);
+            }
+
+            // Build the merged pages array, preserving order from existing markdown
+          } catch (err) {
+            _iterator.e(err);
+          } finally {
+            _iterator.f();
+          }
+          pages = [];
+          addedPaths = new Set(); // First, add all pages that exist in the existing markdown, in their original order
+          _iterator2 = _createForOfIteratorHelper(existingMetadata.pages);
+          try {
+            for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+              existingPage = _step2.value;
+              newPage = newPagesMap.get(existingPage.path);
+              if (newPage) {
+                // Page exists in both - merge the metadata, preferring new values
+                // Only exclude descriptionMarkdown if newPage provides a new description
+                descriptionMarkdown = existingPage.descriptionMarkdown, existingPageWithoutDescriptionMarkdown = _objectWithoutPropertiesLoose(existingPage, _excluded);
+                merged = _extends(_extends(_extends({}, newPage.description ? existingPageWithoutDescriptionMarkdown : existingPage), newPage), {}, {
+                  // Preserve tags from existing (user-managed, program should never delete tags)
+                  tags: existingPage.tags,
+                  // Preserve skipDetailSection from existing (user-managed for external links)
+                  skipDetailSection: existingPage.skipDetailSection,
+                  // Preserve sections from existing if new doesn't have them
+                  sections: newPage.sections || existingPage.sections,
+                  // Merge openGraph, but ensure description comes from newPage if it has one
+                  openGraph: (_newPage$openGraph = newPage.openGraph) != null ? _newPage$openGraph : newPage.description ? _extends(_extends({}, existingPage.openGraph), {}, {
+                    description: newPage.description
+                  }) : existingPage.openGraph
+                });
+                pages.push(merged);
+                addedPaths.add(newPage.path);
+              }
+              // If page doesn't exist in new metadata, it's been removed - don't include it
+            }
+
+            // Then, add any new pages that weren't in the existing markdown
+          } catch (err) {
+            _iterator2.e(err);
+          } finally {
+            _iterator2.f();
+          }
+          _iterator3 = _createForOfIteratorHelper(newMetadata.pages);
+          try {
+            for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+              _newPage = _step3.value;
+              if (!addedPaths.has(_newPage.path)) {
+                // This is a new page - automatically add the [New] tag
+                pageWithTag = _extends(_extends({}, _newPage), {}, {
+                  tags: _newPage.tags ? [].concat(_toConsumableArray(_newPage.tags), ['New']) : ['New']
+                });
+                pages.push(pageWithTag);
+                addedPaths.add(_newPage.path);
+              }
+            }
+
+            // If alphabetical sorting is requested, sort pages alphabetically by title
+          } catch (err) {
+            _iterator3.e(err);
+          } finally {
+            _iterator3.f();
+          }
+          alphabeticalSortMarker = "[//]: # 'This file is autogenerated, but the following list can be modified. Automatically sorted alphabetically.'";
+          requestsAlphabeticalSort = existingMarkdown.includes(alphabeticalSortMarker);
+          if (requestsAlphabeticalSort) {
+            pages = pages.sort(function (a, b) {
+              var titleA = a.title || a.slug;
+              var titleB = b.title || b.slug;
+              return titleA.localeCompare(titleB);
+            });
+          }
+
+          // Create the final metadata with merged pages
+          mergedMetadata = {
+            title: newMetadata.title,
+            // Always use the new title
+            pages: pages
+          }; // Preserve the alphabetical sorting marker if it was present
+          return _context.a(2, metadataToMarkdown(mergedMetadata, {
+            editableMarker: requestsAlphabeticalSort ? alphabeticalSortMarker : undefined,
+            indexWrapperComponent: effectiveWrapper,
+            path: path
+          }));
+      }
+    }, _callee);
+  }));
+  return _mergeMetadataMarkdown.apply(this, arguments);
+}

package/esm/pipeline/syncPageIndex/metadataToMarkdown.d.ts

@@ -0,0 +1,67 @@
+import type { Root } from 'mdast';
+import type { ExtractedMetadata } from "../transformMarkdownMetadata/types.js";
+export interface PageMetadata extends ExtractedMetadata {
+  /** The slug/path for this page (e.g., 'button', 'checkbox') */
+  slug: string;
+  /** The relative path to the page's MDX file */
+  path: string;
+  /** Tags for this entry (e.g., 'New', 'Hot', 'Beta') */
+  tags?: string[];
+  /** Skip generating detail section for this entry (for external links) */
+  skipDetailSection?: boolean;
+  /** Component parts with their API metadata (for multi-part components) */
+  parts?: Record<string, {
+    props?: string[];
+    dataAttributes?: string[];
+    cssVariables?: string[];
+  }>;
+  /** Component exports with their API metadata (used for both single and multi-part components) */
+  exports?: Record<string, {
+    props?: string[];
+    dataAttributes?: string[];
+    cssVariables?: string[];
+  }>;
+}
+export interface PagesMetadata {
+  /** The main title for the pages index */
+  title: string;
+  /** Description below the title (editable, persisted) */
+  description?: string;
+  /** Array of page metadata */
+  pages: PageMetadata[];
+  /** Page-level metadata for export (e.g., robots, etc.) */
+  pageMetadata?: Record<string, unknown>;
+  /** Name of a React component that wraps the autogenerated index content */
+  indexWrapperComponent?: string;
+}
+/**
+ * Options for metadataToMarkdown and metadataToMarkdownAst functions
+ */
+export interface MetadataToMarkdownOptions {
+  /**
+   * Custom editable section marker comment.
+   * If not provided, uses the default marker.
+   */
+  editableMarker?: string;
+  /**
+   * 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>`).
+   * @example 'PagesIndex'
+   */
+  indexWrapperComponent?: string;
+  /**
+   * The path to the file being generated. Used in autogenerated comments to help
+   * users validate the file.
+   */
+  path?: string;
+}
+export declare function metadataToMarkdownAst(data: PagesMetadata, options?: MetadataToMarkdownOptions): Root;
+/**
+ * Converts an array of page metadata into the markdown format (string)
+ */
+export declare function metadataToMarkdown(data: PagesMetadata, options?: MetadataToMarkdownOptions | string): string;
+/**
+ * Parses markdown content and extracts page metadata using unified
+ */
+export declare function markdownToMetadata(markdown: string): Promise<PagesMetadata | null>;