@mui/internal-docs-infra 0.12.1-canary.45 → 0.12.1-canary.47

package/createSitemap/index.d.mts

@@ -1 +1,2 @@
-export * from "./createSitemap.mjs";
+export * from "./createSitemap.mjs";
+export type * from "./types.mjs";

package/createSitemap/types.d.mts

@@ -41,11 +41,30 @@ export interface SitemapPage {
   skipDetailSection?: boolean;
   audience?: Audience;
   index?: boolean;
+  /**
+   * The title of the route-group section this page is listed under in a grouped index
+   * (e.g. `Components`), resolved from the page's route group. `null` for a page in a flat
+   * index or with no route group, so the field is always present. Useful for
+   * grouping/faceting search results.
+   */
+  section: string | null;
   image?: {
     url: string;
     alt?: string;
   };
 }
+/**
+ * A route-group section heading in a grouped index (see `SitemapSectionData.sections`).
+ * Maps a Next.js route group to the human-editable heading its pages are listed under.
+ */
+export interface PageIndexSection {
+  /** The route group this section collects (e.g. `(components)`). */
+  group: string;
+  /** The (human-editable) heading text shown for the section. */
+  title: string;
+  /** Heading depth for the section title. Defaults to 2 (`##`). */
+  depth?: number;
+}
 /**
  * Section data from sitemap
  */
@@ -53,6 +72,14 @@ export interface SitemapSectionData {
   title: string;
   prefix: string;
   pages: SitemapPage[];
+  /**
+   * Ordered route-group sections when the index is grouped (its `##` subtitles), so
+   * search can recover the sections a page belongs to. An empty array for a flat index,
+   * so the field is always present.
+   */
+  sections: PageIndexSection[];
+  /** Heading of the detail-region wrapper in a grouped index (defaults to `Details`). */
+  detailsSectionTitle?: string;
 }
 /**
  * Orama schema property types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.45",
+  "version": "0.12.1-canary.47",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -281,6 +281,26 @@
         "default": "./createSitemap/types.mjs"
       }
     },
+    "./resolvePageUrl": {
+      "import": {
+        "types": "./resolvePageUrl/index.d.mts",
+        "default": "./resolvePageUrl/index.mjs"
+      },
+      "default": {
+        "types": "./resolvePageUrl/index.d.mts",
+        "default": "./resolvePageUrl/index.mjs"
+      }
+    },
+    "./routeGroups": {
+      "import": {
+        "types": "./pipeline/loaderUtils/stripRouteGroups.d.mts",
+        "default": "./pipeline/loaderUtils/stripRouteGroups.mjs"
+      },
+      "default": {
+        "types": "./pipeline/loaderUtils/stripRouteGroups.d.mts",
+        "default": "./pipeline/loaderUtils/stripRouteGroups.mjs"
+      }
+    },
     "./useStream": {
       "import": {
         "types": "./useStream/index.d.mts",
@@ -795,5 +815,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "1c5627440adc8bc5990c9b1c95fb4b74d375345e"
+  "gitSha": "81765a8f621d2dc77469da42ae427c0b7e680e4f"
 }

package/pipeline/loadPrecomputedSitemap/loadPrecomputedSitemap.d.mts

@@ -8,7 +8,7 @@ export type LoaderOptions = {
   };
   /**
    * Directory for the sha256-validated JSON cache of parsed page indexes. When set,
-   * unchanged indexes are read from `{cacheDir}/pages-index/{route}.json` instead of
+   * unchanged indexes are read from `{cacheDir}/pages-index-v2/{route}.json` instead of
    * being re-parsed.
    */
   cacheDir?: string;

package/pipeline/loadServerPageIndex/enrichPageIndex.mjs

@@ -1,5 +1,5 @@
 import { extractPrefixAndTitle, stripTitleMarkdown } from "./extractPrefixAndTitle.mjs";
-import { collapseInlineWhitespace } from "../syncPageIndex/metadataToMarkdown.mjs";
+import { collapseInlineWhitespace, createPageSectionResolver } from "../syncPageIndex/metadataToMarkdown.mjs";
 /**
  * Converts parsed page-index metadata into the `SitemapSectionData` read-model.
  *
@@ -18,10 +18,15 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
     prefix,
     title
   } = extractPrefixAndTitle(absolutePath, rootContext);
+
+  // Resolve each page's section title from its route group (grouped indexes only).
+  const resolveSection = createPageSectionResolver(metadata.sections);
   return {
     ...metadata,
     prefix,
     title,
+    // Always present so consumers never branch on absence: an empty array for a flat index.
+    sections: metadata.sections ?? [],
     // Normalize the index's own (leaked) description like the parser. Spread instead of an explicit
     // key because SitemapSectionData does not declare `description`.
     ...(metadata.description !== undefined ? {
@@ -35,6 +40,7 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
       const {
         descriptionMarkdown,
         sections,
+        sectionGroup,
         ...pageWithoutMarkdown
       } = page;
       return {
@@ -43,7 +49,11 @@ export function enrichPageIndex(metadata, absolutePath, rootContext) {
         keywords: page.keywords?.map(collapseInlineWhitespace),
         types: page.types?.map(collapseInlineWhitespace),
         // Strip titleMarkdown from the sections hierarchy.
-        sections: sections ? stripTitleMarkdown(sections) : undefined
+        sections: sections ? stripTitleMarkdown(sections) : undefined,
+        // Resolve the route-group section title for grouped indexes (search faceting),
+        // honoring the header a human filed an otherwise-ungrouped page under. Always present
+        // (`null` when the page has no section) so consumers never branch on absence.
+        section: resolveSection(page.path, sectionGroup) ?? null
       };
     })
   };

package/pipeline/loadServerPageIndex/extractPrefixAndTitle.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { isRouteGroup } from "../loaderUtils/stripRouteGroups.mjs";
 /**
  * Converts a path segment to a title
  * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
@@ -58,7 +59,7 @@ export function extractPrefixAndTitle(absolutePath, rootContext) {
       return false;
     }
     // Filter out Next.js route groups (e.g., '(public)', '(content)')
-    if (seg.startsWith('(') && seg.endsWith(')')) {
+    if (isRouteGroup(seg)) {
       return false;
     }
     // Filter out current directory markers

package/pipeline/loadServerPageIndex/loadServerPageIndex.d.mts

@@ -11,7 +11,7 @@ export interface CreateLoadServerPageIndexOptions {
   /**
    * Directory for the sha256-validated JSON cache of parsed page indexes.
    *
-   * When set, a read first checks `{cacheDir}/pages-index/{route}.json`; on a hash
+   * When set, a read first checks `{cacheDir}/pages-index-v2/{route}.json`; on a hash
    * match it returns the cached data and skips the markdown parse, and on a miss it
    * parses, writes the cache, and returns. When unset, no cache is read or written.
    */

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.d.mts

@@ -1,5 +1,12 @@
-/** Cache namespace (subdirectory) for page-index entries. */
-export declare const PAGE_INDEX_CACHE_NAMESPACE = "pages-index";
+/**
+ * Cache namespace (subdirectory) for page-index entries. The `-v2` suffix is a schema version:
+ * grouped indexes added always-present `sections` and per-page `section` fields to the cached
+ * read-model, so a pre-existing `pages-index` entry (keyed only by content hash) could otherwise
+ * survive a docs-infra upgrade and serve the old shape for an unchanged index file. Bumping the
+ * namespace forces a clean miss the first time the new code runs. Bump again on any future
+ * breaking change to the cached page-index shape.
+ */
+export declare const PAGE_INDEX_CACHE_NAMESPACE = "pages-index-v2";
 /**
  * Derives the cache key for a page-index file from its path, reusing the same
  * route derivation as the loaded data so a writer and reader of the same index

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.mjs

@@ -1,7 +1,14 @@
 import { extractPrefixAndTitle } from "./extractPrefixAndTitle.mjs";
 
-/** Cache namespace (subdirectory) for page-index entries. */
-export const PAGE_INDEX_CACHE_NAMESPACE = 'pages-index';
+/**
+ * Cache namespace (subdirectory) for page-index entries. The `-v2` suffix is a schema version:
+ * grouped indexes added always-present `sections` and per-page `section` fields to the cached
+ * read-model, so a pre-existing `pages-index` entry (keyed only by content hash) could otherwise
+ * survive a docs-infra upgrade and serve the old shape for an unchanged index file. Bumping the
+ * namespace forces a clean miss the first time the new code runs. Bump again on any future
+ * breaking change to the cached page-index shape.
+ */
+export const PAGE_INDEX_CACHE_NAMESPACE = 'pages-index-v2';
 
 /**
  * Derives the cache key for a page-index file from its path, reusing the same

package/pipeline/loaderUtils/extractNameAndSlugFromUrl.mjs

@@ -1,4 +1,5 @@
 import { fileUrlToPortablePath } from "./fileUrlToPortablePath.mjs";
+import { kebabToTitleCase } from "./kebabToTitleCase.mjs";
 
 /**
  * Extracts and formats a name and slug from a URL path.
@@ -42,37 +43,6 @@ function camelToTitleCase(camelCase) {
   .replace(/^./, str => str.toUpperCase());
 }
 
-/**
- * Known brand names and acronyms that have a canonical capitalization.
- * Keys are lowercase, values are the canonical form to use in titles.
- */
-const BRAND_NAME_OVERRIDES = {
-  javascript: 'JavaScript',
-  typescript: 'TypeScript'
-};
-
-/**
- * Capitalizes a single word, applying brand-name overrides when applicable.
- */
-function capitalizeWord(word) {
-  const lower = word.toLowerCase();
-  const override = BRAND_NAME_OVERRIDES[lower];
-  if (override) {
-    return override;
-  }
-  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-}
-
-/**
- * Converts a kebab-case string to Title Case
- * @param kebabCase - The kebab-case string to convert
- * @returns Title case string
- */
-function kebabToTitleCase(kebabCase) {
-  return kebabCase.split(/[-_]/) // Split on both hyphens and underscores
-  .map(capitalizeWord).join(' ');
-}
-
 /**
  * Detects if a string is camelCase or PascalCase
  * @param str - The string to check

package/pipeline/loaderUtils/index.d.mts

@@ -7,4 +7,5 @@ export * from "./extractNameAndSlugFromUrl.mjs";
 export * from "./externalsToPackages.mjs";
 export * from "./fileUrlToPortablePath.mjs";
 export * from "./getLanguageFromExtension.mjs";
-export * from "./generateFileSlug.mjs";
+export * from "./generateFileSlug.mjs";
+export * from "./stripRouteGroups.mjs";

package/pipeline/loaderUtils/index.mjs

@@ -7,4 +7,5 @@ export * from "./extractNameAndSlugFromUrl.mjs";
 export * from "./externalsToPackages.mjs";
 export * from "./fileUrlToPortablePath.mjs";
 export * from "./getLanguageFromExtension.mjs";
-export * from "./generateFileSlug.mjs";
+export * from "./generateFileSlug.mjs";
+export * from "./stripRouteGroups.mjs";

package/pipeline/loaderUtils/kebabToTitleCase.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Converts a kebab-case (or snake_case) string to Title Case, honoring brand-name overrides
+ * (e.g. `javascript` -> `JavaScript`). This is the single title-casing rule shared by the
+ * producers that turn a slug/folder name into a display title — directory-derived index titles,
+ * URL-segment names, and route-group section headings — so those titles never diverge.
+ *
+ * @example kebabToTitleCase('alert-dialog') -> 'Alert Dialog'
+ * @example kebabToTitleCase('getting_started') -> 'Getting Started'
+ * @example kebabToTitleCase('typescript') -> 'TypeScript'
+ */
+export declare function kebabToTitleCase(kebabCase: string): string;

package/pipeline/loaderUtils/kebabToTitleCase.mjs

@@ -0,0 +1,34 @@
+/**
+ * Known brand names and acronyms that have a canonical capitalization.
+ * Keys are lowercase, values are the canonical form to use in titles.
+ */
+const BRAND_NAME_OVERRIDES = {
+  javascript: 'JavaScript',
+  typescript: 'TypeScript'
+};
+
+/**
+ * Capitalizes a single word, applying brand-name overrides when applicable.
+ */
+function capitalizeWord(word) {
+  const lower = word.toLowerCase();
+  const override = BRAND_NAME_OVERRIDES[lower];
+  if (override) {
+    return override;
+  }
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
+/**
+ * Converts a kebab-case (or snake_case) string to Title Case, honoring brand-name overrides
+ * (e.g. `javascript` -> `JavaScript`). This is the single title-casing rule shared by the
+ * producers that turn a slug/folder name into a display title — directory-derived index titles,
+ * URL-segment names, and route-group section headings — so those titles never diverge.
+ *
+ * @example kebabToTitleCase('alert-dialog') -> 'Alert Dialog'
+ * @example kebabToTitleCase('getting_started') -> 'Getting Started'
+ * @example kebabToTitleCase('typescript') -> 'TypeScript'
+ */
+export function kebabToTitleCase(kebabCase) {
+  return kebabCase.split(/[-_]/).map(capitalizeWord).join(' ');
+}

package/pipeline/loaderUtils/stripRouteGroups.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Whether a single path segment is a Next.js route group: a directory name wrapped in
+ * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
+ * URL. This is the one shared definition used by page grouping, parent-index resolution, and
+ * path-to-URL resolution.
+ *
+ * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
+ * `(draft)notes`) is not a route group and is kept.
+ *
+ * @example isRouteGroup('(overview)') -> true
+ * @example isRouteGroup('components') -> false
+ * @example isRouteGroup('(draft)notes') -> false
+ */
+export declare function isRouteGroup(segment: string): boolean;
+/**
+ * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
+ * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
+ * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
+ * mapping a route group back to a section (e.g. resolving a section's default landing page).
+ *
+ * @example routeGroupName('(overview)') -> 'overview'
+ * @example routeGroupName('components') -> undefined
+ * @example routeGroupName('(draft)notes') -> undefined
+ */
+export declare function routeGroupName(segment: string): string | undefined;
+/**
+ * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
+ * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
+ * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
+ * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
+ * rendered links, and search URL resolution all share.
+ *
+ * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
+ * @example stripRouteGroupSegments('/(draft)notes/guide') -> '/(draft)notes/guide'
+ */
+export declare function stripRouteGroupSegments(pathOrUrl: string): string;

package/pipeline/loaderUtils/stripRouteGroups.mjs

@@ -0,0 +1,44 @@
+/**
+ * Whether a single path segment is a Next.js route group: a directory name wrapped in
+ * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
+ * URL. This is the one shared definition used by page grouping, parent-index resolution, and
+ * path-to-URL resolution.
+ *
+ * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
+ * `(draft)notes`) is not a route group and is kept.
+ *
+ * @example isRouteGroup('(overview)') -> true
+ * @example isRouteGroup('components') -> false
+ * @example isRouteGroup('(draft)notes') -> false
+ */
+export function isRouteGroup(segment) {
+  return segment.startsWith('(') && segment.endsWith(')');
+}
+
+/**
+ * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
+ * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
+ * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
+ * mapping a route group back to a section (e.g. resolving a section's default landing page).
+ *
+ * @example routeGroupName('(overview)') -> 'overview'
+ * @example routeGroupName('components') -> undefined
+ * @example routeGroupName('(draft)notes') -> undefined
+ */
+export function routeGroupName(segment) {
+  return isRouteGroup(segment) ? segment.slice(1, -1) : undefined;
+}
+
+/**
+ * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
+ * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
+ * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
+ * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
+ * rendered links, and search URL resolution all share.
+ *
+ * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
+ * @example stripRouteGroupSegments('/(draft)notes/guide') -> '/(draft)notes/guide'
+ */
+export function stripRouteGroupSegments(pathOrUrl) {
+  return pathOrUrl.split('/').filter(segment => !isRouteGroup(segment)).join('/');
+}

package/pipeline/parseSource/index.d.mts

@@ -1,2 +1,2 @@
-export * from "./parseSource.mjs";
+export { createParseSource, parsePlainText, parseSource, registerAllGrammars, registerGrammars, resetStarryNight } from "./parseSource.mjs";
 export { getGrammarFromLanguage, languageToGrammarMap, extensionMap } from "./grammarMaps.mjs";

package/pipeline/parseSource/index.mjs

@@ -1,2 +1,2 @@
-export * from "./parseSource.mjs";
+export { createParseSource, parsePlainText, parseSource, registerAllGrammars, registerGrammars, resetStarryNight } from "./parseSource.mjs";
 export { getGrammarFromLanguage, languageToGrammarMap, extensionMap } from "./grammarMaps.mjs";

package/pipeline/parseSource/parseSource.d.mts

@@ -1,4 +1,6 @@
+import { createStarryNight } from '@wooorm/starry-night';
 import type { ParseSource } from "../../CodeHighlighter/types.mjs";
+type StarryNight = Awaited<ReturnType<typeof createStarryNight>>;
 /**
  * Parses source into a line-guttered HAST **without** syntax highlighting — the
  * raw text wrapped in the same `.line`/`.frame` structure `parseSource` produces,
@@ -51,8 +53,16 @@ export declare function registerAllGrammars(): Promise<void>;
  * @returns A Promise that resolves to the initialized `parseSource` function
  */
 export declare const createParseSource: (initialScopes?: string[]) => Promise<ParseSource>;
+/**
+ * Returns the shared Starry Night instance after registering every grammar.
+ *
+ * Inline highlighting can follow code that initialized a lazy subset, so it must
+ * initialize the complete registry before using the shared instance.
+ */
+export declare function getStarryNightInstance(): Promise<StarryNight>;
 /**
  * Clears the global Starry Night singleton and registration state. Intended for
  * tests exercising lazy registration from a known-empty registry.
  */
-export declare function resetStarryNight(): void;
+export declare function resetStarryNight(): void;
+export {};

package/pipeline/parseSource/parseSource.mjs

@@ -232,6 +232,21 @@ export const createParseSource = async initialScopes => {
   return parseSource;
 };
 
+/**
+ * Returns the shared Starry Night instance after registering every grammar.
+ *
+ * Inline highlighting can follow code that initialized a lazy subset, so it must
+ * initialize the complete registry before using the shared instance.
+ */
+export async function getStarryNightInstance() {
+  await createParseSource();
+  const instance = getInstance();
+  if (!instance) {
+    throw new Error('Starry Night failed to initialize.');
+  }
+  return instance;
+}
+
 /**
  * Clears the global Starry Night singleton and registration state. Intended for
  * tests exercising lazy registration from a known-empty registry.

package/pipeline/syncPageIndex/mergeMetadataMarkdown.d.mts

@@ -59,6 +59,13 @@ export declare function mergeMetadataPages(existingMarkdown: string | undefined,
  * This allows multiple pages to have the same slug (anchor) while still being treated
  * as distinct pages.
  *
+ * Known limitation: matching is by exact path, so a page whose stored path changes format —
+ * notably an index first regenerated after route groups became path-preserving, where an old
+ * entry `./accordion/page.mdx` no longer matches the new `./(components)/accordion/page.mdx` —
+ * is not reconciled with its old entry and can briefly duplicate. This is accepted rather than
+ * matched by route-group-stripped path (two distinct pages `./(a)/x` and `./(b)/x` share one
+ * stripped path), since grouped indexes are net-new; a stale entry clears once removed by hand.
+ *
  * @param existingMarkdown - The existing markdown content (or undefined if none exists)
  * @param newMetadata - The new metadata to merge in
  * @param options - Optional configuration