@mui/internal-docs-infra 0.13.1-canary.14 → 0.13.1-canary.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/ChunkProvider/types.d.mts +1 -1
  2. package/CodeControllerContext/CodeControllerContext.d.mts +1 -1
  3. package/CodeControllerContext/CodeControllerContext.mjs +1 -1
  4. package/CodeHighlighter/types.d.mts +3 -3
  5. package/CoordinatedLazy/CoordinatedContentContext.d.mts +1 -1
  6. package/CoordinatedLazy/CoordinatedContentContext.mjs +1 -1
  7. package/CoordinatedLazy/CoordinatedGateContext.d.mts +1 -1
  8. package/CoordinatedLazy/CoordinatedGateContext.mjs +1 -1
  9. package/CoordinatedLazy/createCoordinatedLazy.d.mts +1 -1
  10. package/CoordinatedLazy/createCoordinatedLazy.mjs +1 -1
  11. package/CoordinatedLazy/types.d.mts +5 -5
  12. package/abstractCreateStream/types.d.mts +1 -1
  13. package/createSitemap/createSitemap.d.mts +1 -1
  14. package/createSitemap/createSitemap.mjs +1 -1
  15. package/package.json +2 -2
  16. package/pipeline/enhanceCodeInline/enhanceCodeInline.d.mts +1 -1
  17. package/pipeline/enhanceCodeInline/enhanceCodeInline.mjs +1 -1
  18. package/pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.d.mts +1 -1
  19. package/pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs +1 -1
  20. package/pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.d.mts +3 -3
  21. package/pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs +3 -3
  22. package/pipeline/loadServerPageIndex/extractPrefixAndTitle.d.mts +2 -2
  23. package/pipeline/loadServerPageIndex/extractPrefixAndTitle.mjs +2 -2
  24. package/pipeline/loaderUtils/getLanguageFromExtension.d.mts +3 -3
  25. package/pipeline/loaderUtils/getLanguageFromExtension.mjs +3 -3
  26. package/pipeline/loaderUtils/processRelativeImports.d.mts +1 -1
  27. package/pipeline/loaderUtils/processRelativeImports.mjs +1 -1
  28. package/pipeline/loaderUtils/resolveModulePath.d.mts +1 -1
  29. package/pipeline/loaderUtils/resolveModulePath.mjs +1 -1
  30. package/pipeline/loaderUtils/stripRouteGroups.d.mts +5 -5
  31. package/pipeline/loaderUtils/stripRouteGroups.mjs +5 -5
  32. package/pipeline/parseSource/grammarMaps.d.mts +1 -1
  33. package/pipeline/parseSource/grammarMaps.mjs +1 -1
  34. package/pipeline/syncPageIndex/syncPageIndex.d.mts +2 -2
  35. package/pipeline/syncPageIndex/syncPageIndex.mjs +2 -2
  36. package/pipeline/syncTypes/generateTypesMarkdown.mjs +2 -2
  37. package/useCode/useCode.d.mts +1 -1
  38. package/useCoordinated/useCoordinated.d.mts +2 -2
  39. package/useCoordinated/useCoordinated.mjs +2 -2
  40. package/useCoordinated/useCoordinatedLazy.d.mts +1 -1
  41. package/useCoordinated/useCoordinatedLazy.mjs +1 -1
  42. package/useType/useType.d.mts +1 -1
  43. package/useType/useType.mjs +1 -1
  44. package/useType/useTypeProp.d.mts +2 -2
  45. package/useType/useTypeProp.mjs +2 -2
@@ -2,7 +2,7 @@ import type * as React from 'react';
2
2
  import type { StreamSource } from "../CoordinatedLazy/types.mjs";
3
3
  /**
4
4
  * Provided by a `ChunkProvider`: lazily resolve the client `StreamSource` for
5
- * descendant chunks. Called only when a chunk actually needs to load (i.e. it
5
+ * descendant chunks. Called only when a chunk actually needs to load (that is, it
6
6
  * was not preloaded), so the loader module stays out of the initial bundle and
7
7
  * is never imported when everything is precomputed.
8
8
  */
@@ -87,7 +87,7 @@ export type CodeControllerProps<T extends {} = {}> = {
87
87
  * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
88
88
  * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
89
89
  * such as `useDemoController`. Parameterize with `T` for the controller's own props
90
- * (e.g. `CodeController<UseDemoControllerOptions>`).
90
+ * (for example, `CodeController<UseDemoControllerOptions>`).
91
91
  */
92
92
  export type CodeController<T extends {} = {}> = React.ComponentType<CodeControllerProps<T>>;
93
93
  export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
@@ -20,7 +20,7 @@ import * as React from 'react';
20
20
  * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
21
21
  * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
22
22
  * such as `useDemoController`. Parameterize with `T` for the controller's own props
23
- * (e.g. `CodeController<UseDemoControllerOptions>`).
23
+ * (for example, `CodeController<UseDemoControllerOptions>`).
24
24
  */
25
25
 
26
26
  export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
@@ -504,7 +504,7 @@ export interface CodeContentProps {
504
504
  code?: Code;
505
505
  /** React components for live preview alongside code */
506
506
  components?: Components;
507
- /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
507
+ /** What type of variants are available (for example, a type `packageManager` when variants `npm` and `yarn` are available) */
508
508
  variantType?: string;
509
509
  /** Static variant names that should be fetched at runtime */
510
510
  variants?: string[];
@@ -512,7 +512,7 @@ export interface CodeContentProps {
512
512
  variant?: string;
513
513
  /** Currently selected file name */
514
514
  fileName?: string;
515
- /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
515
+ /** Language for syntax highlighting (for example, 'tsx', 'css'). When provided, fileName is not required for parsing. */
516
516
  language?: string;
517
517
  /** Default variant to show on first load */
518
518
  initialVariant?: string;
@@ -588,7 +588,7 @@ export interface CodeFunctionProps {
588
588
  loadVariantMeta?: LoadVariantMeta;
589
589
  /** Function to load raw source code and dependencies */
590
590
  loadSource?: LoadSource;
591
- /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
591
+ /** Array of source transformers for code processing (for example, TypeScript to JavaScript) */
592
592
  sourceTransformers?: SourceTransformers;
593
593
  /** Promise resolving to a source parser for syntax highlighting */
594
594
  sourceParser?: Promise<ParseSource>;
@@ -8,7 +8,7 @@ import type { CoordinatedContentContextValue } from "./types.mjs";
8
8
  export declare const CoordinatedContentContext: React.Context<CoordinatedContentContextValue>;
9
9
  /**
10
10
  * Read the data the fallback hoisted, from inside the full content. Lets the
11
- * content use what the fallback fetched (e.g. a decompression dictionary)
11
+ * content use what the fallback fetched (for example, a decompression dictionary)
12
12
  * without the consumer threading it through props. Returns an empty map when
13
13
  * rendered outside a `CoordinatedLazy`.
14
14
  */
@@ -12,7 +12,7 @@ export const CoordinatedContentContext = /*#__PURE__*/React.createContext({
12
12
 
13
13
  /**
14
14
  * Read the data the fallback hoisted, from inside the full content. Lets the
15
- * content use what the fallback fetched (e.g. a decompression dictionary)
15
+ * content use what the fallback fetched (for example, a decompression dictionary)
16
16
  * without the consumer threading it through props. Returns an empty map when
17
17
  * rendered outside a `CoordinatedLazy`.
18
18
  */
@@ -2,7 +2,7 @@ import * as React from 'react';
2
2
  import type { SettleGate } from "../useCoordinated/createSettleGate.mjs";
3
3
  /**
4
4
  * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
5
- * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
5
+ * when it isn't given an explicit `gate` prop. A coordinator (for example, the
6
6
  * `useStream` controller) provides its gate here so every swap rendered beneath
7
7
  * it reports into the same gate - that is how a group's `loading` reflects each
8
8
  * piece's swap without threading a `gate` prop through every one. `null` outside
@@ -3,7 +3,7 @@
3
3
  import * as React from 'react';
4
4
  /**
5
5
  * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
6
- * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
6
+ * when it isn't given an explicit `gate` prop. A coordinator (for example, the
7
7
  * `useStream` controller) provides its gate here so every swap rendered beneath
8
8
  * it reports into the same gate - that is how a group's `loading` reflects each
9
9
  * piece's swap without threading a `gate` prop through every one. `null` outside
@@ -20,7 +20,7 @@ import type { ChunkComponentProps, CreateChunkConfig } from "./types.mjs";
20
20
  * The client-mode branch hands the (function-bearing) `config` to a `'use client'`
21
21
  * component, so a client-loaded chunk must render inside a client subtree - call
22
22
  * `createCoordinatedLazy` from a client module, or wrap it in a client provider
23
- * (e.g. `abstractCreateStream`'s `ClientProvider`). Server-loaded and
23
+ * (for example, `abstractCreateStream`'s `ClientProvider`). Server-loaded and
24
24
  * preloaded/precomputed chunks have no such constraint - they render entirely on
25
25
  * the server path.
26
26
  *
@@ -28,7 +28,7 @@ function RenderNull() {
28
28
  * The client-mode branch hands the (function-bearing) `config` to a `'use client'`
29
29
  * component, so a client-loaded chunk must render inside a client subtree - call
30
30
  * `createCoordinatedLazy` from a client module, or wrap it in a client provider
31
- * (e.g. `abstractCreateStream`'s `ClientProvider`). Server-loaded and
31
+ * (for example, `abstractCreateStream`'s `ClientProvider`). Server-loaded and
32
32
  * preloaded/precomputed chunks have no such constraint - they render entirely on
33
33
  * the server path.
34
34
  *
@@ -32,7 +32,7 @@ export interface CoordinatedFallbackContextValue {
32
32
  }
33
33
  /**
34
34
  * The data the fallback hoisted, handed down to the full content so it can use
35
- * what the fallback fetched (e.g. a DEFLATE dictionary). Read via
35
+ * what the fallback fetched (for example, a DEFLATE dictionary). Read via
36
36
  * {@link useCoordinatedContent}.
37
37
  */
38
38
  export interface CoordinatedContentContextValue {
@@ -88,7 +88,7 @@ export interface UseCoordinatedSwapOptions {
88
88
  awaitContent?: boolean;
89
89
  /**
90
90
  * Settle gate to register this swap with. When omitted, the ambient gate from
91
- * a surrounding coordinator (e.g. the `useStream` controller, via
91
+ * a surrounding coordinator (for example, the `useStream` controller, via
92
92
  * {@link CoordinatedGateContext}) is used instead. The page-global gate is
93
93
  * always registered on top of either, so a page-wide coordinated commit waits
94
94
  * for the swap regardless.
@@ -149,14 +149,14 @@ export interface CoordinatedLazyProps {
149
149
  requireHoist?: boolean;
150
150
  /**
151
151
  * Hold the swap until the content reports it has loaded, mounting the content
152
- * behind the fallback so a code-split (e.g. `LazyContent`) content can load in
152
+ * behind the fallback so a code-split (for example, `LazyContent`) content can load in
153
153
  * the background and reveal only once its chunk has arrived. See
154
154
  * {@link UseCoordinatedSwapOptions.awaitContent}.
155
155
  */
156
156
  awaitContent?: boolean;
157
157
  /**
158
158
  * Settle gate to register this swap with. When omitted, the ambient gate from
159
- * a surrounding coordinator (e.g. the `useStream` controller, via
159
+ * a surrounding coordinator (for example, the `useStream` controller, via
160
160
  * {@link CoordinatedGateContext}) is used instead. The page-global gate is
161
161
  * always registered on top of either, so a page-wide coordinated commit waits
162
162
  * for the swap regardless.
@@ -400,7 +400,7 @@ export interface LazyContentProps<T extends {} = {}> {
400
400
  fallback?: React.ReactNode;
401
401
  /**
402
402
  * Additional settle gate to report readiness to once the component has loaded
403
- * and mounted (e.g. a `useStream` controller gate). The page-global gate is
403
+ * and mounted (for example, a `useStream` controller gate). The page-global gate is
404
404
  * always registered too. Client path only - the server path streams via
405
405
  * Suspense and has no client gate to report to.
406
406
  */
@@ -2,7 +2,7 @@ import type * as React from 'react';
2
2
  import type { CreateChunkConfig } from "../CoordinatedLazy/types.mjs";
3
3
  /**
4
4
  * Options bound by {@link createStreamFactory}. Extends the chunk config with
5
- * an optional client provider (e.g. a `ChunkProvider` supplying client loaders,
5
+ * an optional client provider (for example, a `ChunkProvider` supplying client loaders,
6
6
  * or a `PreloadProvider`) wrapped around the chunk.
7
7
  *
8
8
  * All loader functions on the config are expected to be dynamically imported by
@@ -13,7 +13,7 @@ type CreateSitemapMeta = {
13
13
  * Returns a sitemap data object containing schema and page data.
14
14
  *
15
15
  * In Next.js builds, the webpack loader precomputes the sitemap data.
16
- * Outside Next.js (e.g., tests or scripts), use `loadServerSitemap()` for runtime loading.
16
+ * Outside Next.js (for example, tests or scripts), use `loadServerSitemap()` for runtime loading.
17
17
  *
18
18
  * @param sourceUrl Depends on `import.meta.url` to determine the source file location.
19
19
  * @param pages Record of page components indexed by path.
@@ -17,7 +17,7 @@ function isNextJsContext() {
17
17
  * Returns a sitemap data object containing schema and page data.
18
18
  *
19
19
  * In Next.js builds, the webpack loader precomputes the sitemap data.
20
- * Outside Next.js (e.g., tests or scripts), use `loadServerSitemap()` for runtime loading.
20
+ * Outside Next.js (for example, tests or scripts), use `loadServerSitemap()` for runtime loading.
21
21
  *
22
22
  * @param sourceUrl Depends on `import.meta.url` to determine the source file location.
23
23
  * @param pages Record of page components indexed by path.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mui/internal-docs-infra",
3
- "version": "0.13.1-canary.14",
3
+ "version": "0.13.1-canary.16",
4
4
  "author": "MUI Team",
5
5
  "description": "MUI Infra - internal documentation creation tools.",
6
6
  "license": "MIT",
@@ -813,5 +813,5 @@
813
813
  "bin": {
814
814
  "docs-infra": "./cli/index.mjs"
815
815
  },
816
- "gitSha": "ad35b856293897756fb224998f295a8edb4a8f94"
816
+ "gitSha": "4ee02d8d0a78249ef9aadb30f919489c56b89ebe"
817
817
  }
@@ -9,7 +9,7 @@ import type { Root as HastRoot } from 'hast';
9
9
  * inside — no semantic information is destroyed.
10
10
  *
11
11
  * 2. **Token reclassification**: Corrects misidentified token classes,
12
- * e.g., `function` marked as `pl-en` is changed to `pl-k` (keyword).
12
+ * for example, `function` marked as `pl-en` is changed to `pl-k` (keyword).
13
13
  *
14
14
  * 3. **Built-in type enhancement** (TypeScript only): Reclassifies standalone
15
15
  * type keywords (`string`, `number`, `void`, etc.) from `pl-smi`/`pl-k`
@@ -350,7 +350,7 @@ function enhanceBuiltInTypes(children) {
350
350
  * inside — no semantic information is destroyed.
351
351
  *
352
352
  * 2. **Token reclassification**: Corrects misidentified token classes,
353
- * e.g., `function` marked as `pl-en` is changed to `pl-k` (keyword).
353
+ * for example, `function` marked as `pl-en` is changed to `pl-k` (keyword).
354
354
  *
355
355
  * 3. **Built-in type enhancement** (TypeScript only): Reclassifies standalone
356
356
  * type keywords (`string`, `number`, `void`, etc.) from `pl-smi`/`pl-k`
@@ -8,7 +8,7 @@ import type { Code } from "../../CodeHighlighter/types.mjs";
8
8
  * Used primarily to determine when to show the full Content component instead of ContentLoading
9
9
  * fallback, ensuring a smooth user experience without rendering errors.
10
10
  *
11
- * @param variants - Array of variant names that must all be ready (e.g., ['javascript', 'typescript'])
11
+ * @param variants - Array of variant names that must all be ready (for example, `['javascript', 'typescript']`)
12
12
  * @param code - The code object containing variant data
13
13
  * @param needsHighlight - Whether all sources need to be syntax highlighted (hast nodes, not strings)
14
14
  * @returns True if all variants and their files are loaded and ready for full rendering
@@ -26,7 +26,7 @@ function isSourceLoaded(code, needsHighlight) {
26
26
  * Used primarily to determine when to show the full Content component instead of ContentLoading
27
27
  * fallback, ensuring a smooth user experience without rendering errors.
28
28
  *
29
- * @param variants - Array of variant names that must all be ready (e.g., ['javascript', 'typescript'])
29
+ * @param variants - Array of variant names that must all be ready (for example, `['javascript', 'typescript']`)
30
30
  * @param code - The code object containing variant data
31
31
  * @param needsHighlight - Whether all sources need to be syntax highlighted (hast nodes, not strings)
32
32
  * @returns True if all variants and their files are loaded and ready for full rendering
@@ -32,15 +32,15 @@ import type { Code, VariantExtraFiles, VariantSource } from "../../CodeHighlight
32
32
  * any loading operations. This design is crucial for performance and rendering strategies:
33
33
  *
34
34
  * - **Synchronous validation** allows immediate decisions about rendering paths without async overhead
35
- * - **Enables build-time optimization**: When code is precomputed (e.g., via build-time processing),
35
+ * - **Enables build-time optimization**: When code is precomputed (for example, via build-time processing),
36
36
  * this function can immediately return `initialData`, avoiding async components entirely
37
37
  * - **Separates concerns**: Data validation is separate from data loading, making the codebase
38
38
  * more predictable and easier to reason about
39
39
  *
40
40
  * When `initialData: false` is returned, the calling component is responsible for initiating
41
- * asynchronous loading operations (e.g., `loadCodeFallback`, `CodeInitialSourceLoader`).
41
+ * asynchronous loading operations (for example, `loadCodeFallback`, `CodeInitialSourceLoader`).
42
42
  *
43
- * @param variants - Array of all available variant names for this code block (e.g., ['javascript', 'typescript'])
43
+ * @param variants - Array of all available variant names for this code block (for example, `['javascript', 'typescript']`)
44
44
  * @param variant - The specific variant we want to display (must exist in variants array)
45
45
  * @param code - The code object containing all variant data (may be undefined if not loaded)
46
46
  * @param fileName - Optional specific file to display. Resolution logic:
@@ -32,15 +32,15 @@ import { hasAllVariants } from "./hasAllCodeVariants.mjs";
32
32
  * any loading operations. This design is crucial for performance and rendering strategies:
33
33
  *
34
34
  * - **Synchronous validation** allows immediate decisions about rendering paths without async overhead
35
- * - **Enables build-time optimization**: When code is precomputed (e.g., via build-time processing),
35
+ * - **Enables build-time optimization**: When code is precomputed (for example, via build-time processing),
36
36
  * this function can immediately return `initialData`, avoiding async components entirely
37
37
  * - **Separates concerns**: Data validation is separate from data loading, making the codebase
38
38
  * more predictable and easier to reason about
39
39
  *
40
40
  * When `initialData: false` is returned, the calling component is responsible for initiating
41
- * asynchronous loading operations (e.g., `loadCodeFallback`, `CodeInitialSourceLoader`).
41
+ * asynchronous loading operations (for example, `loadCodeFallback`, `CodeInitialSourceLoader`).
42
42
  *
43
- * @param variants - Array of all available variant names for this code block (e.g., ['javascript', 'typescript'])
43
+ * @param variants - Array of all available variant names for this code block (for example, `['javascript', 'typescript']`)
44
44
  * @param variant - The specific variant we want to display (must exist in variants array)
45
45
  * @param code - The code object containing all variant data (may be undefined if not loaded)
46
46
  * @param fileName - Optional specific file to display. Resolution logic:
@@ -2,7 +2,7 @@ import type { HeadingHierarchy } from "../transformMarkdownMetadata/types.mjs";
2
2
  import type { SitemapSection } from "../../createSitemap/types.mjs";
3
3
  /**
4
4
  * Converts a path segment to a title
5
- * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
5
+ * for example, "docs-infra" -> "Docs Infra", "components" -> "Components"
6
6
  */
7
7
  export declare function pathSegmentToTitle(segment: string): string;
8
8
  /**
@@ -11,7 +11,7 @@ export declare function pathSegmentToTitle(segment: string): string;
11
11
  export declare function stripTitleMarkdown(hierarchy: HeadingHierarchy): Record<string, SitemapSection>;
12
12
  /**
13
13
  * Extracts prefix and title from an import path
14
- * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
14
+ * for example, "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
15
15
  */
16
16
  export declare function extractPrefixAndTitle(absolutePath: string, rootContext: string): {
17
17
  prefix: string;
@@ -2,7 +2,7 @@ import path from 'node:path';
2
2
  import { isRouteGroup } from "../loaderUtils/stripRouteGroups.mjs";
3
3
  /**
4
4
  * Converts a path segment to a title
5
- * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
5
+ * for example, "docs-infra" -> "Docs Infra", "components" -> "Components"
6
6
  */
7
7
  export function pathSegmentToTitle(segment) {
8
8
  return segment.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
@@ -33,7 +33,7 @@ export function stripTitleMarkdown(hierarchy) {
33
33
 
34
34
  /**
35
35
  * Extracts prefix and title from an import path
36
- * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
36
+ * for example, "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
37
37
  */
38
38
  export function extractPrefixAndTitle(absolutePath, rootContext) {
39
39
  // Get the relative path from the root context
@@ -5,19 +5,19 @@
5
5
  export declare const languageMap: Record<string, string>;
6
6
  /**
7
7
  * Maps language aliases to canonical language names.
8
- * Used to normalize short language names (e.g., from className like 'language-js')
8
+ * Used to normalize short language names (for example, from className like 'language-js')
9
9
  * to their full names.
10
10
  */
11
11
  export declare const languageAliasMap: Record<string, string>;
12
12
  /**
13
13
  * Gets the language name from a file extension.
14
- * @param extension - The file extension (e.g., '.tsx', '.css')
14
+ * @param extension - The file extension (for example, '.tsx', '.css')
15
15
  * @returns The language name or undefined if not recognized
16
16
  */
17
17
  export declare function getLanguageFromExtension(extension: string): string | undefined;
18
18
  /**
19
19
  * Normalizes a language name to its canonical form.
20
- * This handles aliases like 'js' -> 'javascript', 'ts' -> 'typescript'.
20
+ * This handles aliases like `'js'` -> `'javascript'`, `'ts'` -> `'typescript'`.
21
21
  * @param language - The language name or alias
22
22
  * @returns The canonical language name, or the input if not a known alias
23
23
  */
@@ -19,7 +19,7 @@ export const languageMap = {
19
19
 
20
20
  /**
21
21
  * Maps language aliases to canonical language names.
22
- * Used to normalize short language names (e.g., from className like 'language-js')
22
+ * Used to normalize short language names (for example, from className like 'language-js')
23
23
  * to their full names.
24
24
  */
25
25
  export const languageAliasMap = {
@@ -44,7 +44,7 @@ export const languageAliasMap = {
44
44
 
45
45
  /**
46
46
  * Gets the language name from a file extension.
47
- * @param extension - The file extension (e.g., '.tsx', '.css')
47
+ * @param extension - The file extension (for example, '.tsx', '.css')
48
48
  * @returns The language name or undefined if not recognized
49
49
  */
50
50
  export function getLanguageFromExtension(extension) {
@@ -53,7 +53,7 @@ export function getLanguageFromExtension(extension) {
53
53
 
54
54
  /**
55
55
  * Normalizes a language name to its canonical form.
56
- * This handles aliases like 'js' -> 'javascript', 'ts' -> 'typescript'.
56
+ * This handles aliases like `'js'` -> `'javascript'`, `'ts'` -> `'typescript'`.
57
57
  * @param language - The language name or alias
58
58
  * @returns The canonical language name, or the input if not a known alias
59
59
  */
@@ -5,7 +5,7 @@ export interface ProcessImportsResult {
5
5
  }
6
6
  /**
7
7
  * Processes imports based on the specified storage mode, automatically handling
8
- * source rewriting when needed (e.g., for 'flat' mode). Works for both JavaScript and simple file types.
8
+ * source rewriting when needed (for example, for 'flat' mode). Works for both JavaScript and simple file types.
9
9
  *
10
10
  * @param source - The original source code
11
11
  * @param importResult - The result from parseImports
@@ -379,7 +379,7 @@ function processJsImports(source, importResult, storeAt, resolvedPathsMap) {
379
379
 
380
380
  /**
381
381
  * Processes imports based on the specified storage mode, automatically handling
382
- * source rewriting when needed (e.g., for 'flat' mode). Works for both JavaScript and simple file types.
382
+ * source rewriting when needed (for example, for 'flat' mode). Works for both JavaScript and simple file types.
383
383
  *
384
384
  * @param source - The original source code
385
385
  * @param importResult - The result from parseImports
@@ -13,7 +13,7 @@ export declare const VALUE_IMPORT_EXTENSIONS: readonly ['.ts', '.tsx', '.js', '.
13
13
  /**
14
14
  * Checks if a file path or import path represents a JavaScript/TypeScript module
15
15
  * @param path - The file path or import path to check
16
- * @returns true if it's a JS/TS module, false otherwise
16
+ * @returns true if it's a JavaScript or TypeScript module, false otherwise
17
17
  */
18
18
  export declare function isJavaScriptModule(path: string): boolean;
19
19
  export interface DirectoryEntry {
@@ -77,7 +77,7 @@ function isStaticAsset(path) {
77
77
  /**
78
78
  * Checks if a file path or import path represents a JavaScript/TypeScript module
79
79
  * @param path - The file path or import path to check
80
- * @returns true if it's a JS/TS module, false otherwise
80
+ * @returns true if it's a JavaScript or TypeScript module, false otherwise
81
81
  */
82
82
  export function isJavaScriptModule(path) {
83
83
  // If the path has an extension, check if it's one of the JS/TS extensions
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * Whether a single path segment is a Next.js route group: a directory name wrapped in
3
- * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
3
+ * parentheses (for example, `(overview)`). Route groups organize files without appearing in the public
4
4
  * URL. This is the one shared definition used by page grouping, parent-index resolution, and
5
5
  * path-to-URL resolution.
6
6
  *
7
- * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
7
+ * Because it tests a whole segment, a segment that merely contains parentheses (for example,
8
8
  * `(draft)notes`) is not a route group and is kept.
9
9
  *
10
10
  * @example isRouteGroup('(overview)') -> true
@@ -13,10 +13,10 @@
13
13
  */
14
14
  export declare function isRouteGroup(segment: string): boolean;
15
15
  /**
16
- * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
16
+ * The name inside a route-group segment (for example, `(overview)` -> `overview`), or `undefined` when the
17
17
  * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
18
18
  * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
19
- * mapping a route group back to a section (e.g. resolving a section's default landing page).
19
+ * mapping a route group back to a section (for example, resolving a section's default landing page).
20
20
  *
21
21
  * @example routeGroupName('(overview)') -> 'overview'
22
22
  * @example routeGroupName('components') -> undefined
@@ -27,7 +27,7 @@ export declare function routeGroupName(segment: string): string | undefined;
27
27
  * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
28
28
  * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
29
29
  * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
30
- * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
30
+ * (for example, `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
31
31
  * rendered links, and search URL resolution all share.
32
32
  *
33
33
  * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * Whether a single path segment is a Next.js route group: a directory name wrapped in
3
- * parentheses (e.g. `(overview)`). Route groups organize files without appearing in the public
3
+ * parentheses (for example, `(overview)`). Route groups organize files without appearing in the public
4
4
  * URL. This is the one shared definition used by page grouping, parent-index resolution, and
5
5
  * path-to-URL resolution.
6
6
  *
7
- * Because it tests a whole segment, a segment that merely contains parentheses (e.g.
7
+ * Because it tests a whole segment, a segment that merely contains parentheses (for example,
8
8
  * `(draft)notes`) is not a route group and is kept.
9
9
  *
10
10
  * @example isRouteGroup('(overview)') -> true
@@ -16,10 +16,10 @@ export function isRouteGroup(segment) {
16
16
  }
17
17
 
18
18
  /**
19
- * The name inside a route-group segment (e.g. `(overview)` -> `overview`), or `undefined` when the
19
+ * The name inside a route-group segment (for example, `(overview)` -> `overview`), or `undefined` when the
20
20
  * segment is not a whole route group. Uses the same whole-segment rule as {@link isRouteGroup}, so
21
21
  * callers get one definition of the parenthesis convention instead of re-deriving it. Useful for
22
- * mapping a route group back to a section (e.g. resolving a section's default landing page).
22
+ * mapping a route group back to a section (for example, resolving a section's default landing page).
23
23
  *
24
24
  * @example routeGroupName('(overview)') -> 'overview'
25
25
  * @example routeGroupName('components') -> undefined
@@ -33,7 +33,7 @@ export function routeGroupName(segment) {
33
33
  * Removes whole Next.js route-group segments (`(group)`) from a `/`-separated path or URL, since
34
34
  * they do not appear in the public URL, keeping every other segment intact. It splits on `/` and
35
35
  * filters whole segments with {@link isRouteGroup}, so a folder that merely contains parentheses
36
- * (e.g. `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
36
+ * (for example, `(draft)notes`) stays in the path. This is the one whole-segment rule the grouped index,
37
37
  * rendered links, and search URL resolution all share.
38
38
  *
39
39
  * @example stripRouteGroupSegments('/components/(inputs)/checkbox') -> '/components/checkbox'
@@ -12,7 +12,7 @@ export declare const extensionMap: Record<string, string>;
12
12
  export declare const languageToGrammarMap: Record<string, string>;
13
13
  /**
14
14
  * Gets the grammar scope from a language name.
15
- * @param language - The language name (e.g., 'tsx', 'css', 'typescript')
15
+ * @param language - The language name (for example, 'tsx', 'css', 'typescript')
16
16
  * @returns The grammar scope or undefined if not recognized
17
17
  */
18
18
  export declare function getGrammarFromLanguage(language: string): string | undefined;
@@ -46,7 +46,7 @@ export const languageToGrammarMap = {
46
46
 
47
47
  /**
48
48
  * Gets the grammar scope from a language name.
49
- * @param language - The language name (e.g., 'tsx', 'css', 'typescript')
49
+ * @param language - The language name (for example, 'tsx', 'css', 'typescript')
50
50
  * @returns The grammar scope or undefined if not recognized
51
51
  */
52
52
  export function getGrammarFromLanguage(language) {
@@ -2,7 +2,7 @@ import * as lockfile from 'proper-lockfile';
2
2
  import type { PageMetadata } from "./metadataToMarkdown.mjs";
3
3
  /**
4
4
  * Builds the route-group-preserving relative path that identifies a page within its
5
- * parent index (e.g. `./(components)/accordion/page.mdx`). The parent directory is
5
+ * parent index (for example, `./(components)/accordion/page.mdx`). The parent directory is
6
6
  * resolved by skipping route groups, but the route-group segment is retained in the
7
7
  * returned path so the index can be grouped into `## Section` headings.
8
8
  *
@@ -10,7 +10,7 @@ import type { PageMetadata } from "./metadataToMarkdown.mjs";
10
10
  * and the types loader (`syncTypes`) — must build a page's path this way so they agree
11
11
  * on its identity and the grouping is derivable from the stored path.
12
12
  * @param pageDir Absolute directory of the page whose index entry is being built.
13
- * @param pageFileName File name of the page within that directory (e.g. `page.mdx`).
13
+ * @param pageFileName File name of the page within that directory (for example, `page.mdx`).
14
14
  */
15
15
  export declare function indexRelativePagePath(pageDir: string, pageFileName: string): string;
16
16
  export interface SyncPageIndexOptions {
@@ -27,7 +27,7 @@ function getParentDir(path, skipRouteGroups = false) {
27
27
 
28
28
  /**
29
29
  * Builds the route-group-preserving relative path that identifies a page within its
30
- * parent index (e.g. `./(components)/accordion/page.mdx`). The parent directory is
30
+ * parent index (for example, `./(components)/accordion/page.mdx`). The parent directory is
31
31
  * resolved by skipping route groups, but the route-group segment is retained in the
32
32
  * returned path so the index can be grouped into `## Section` headings.
33
33
  *
@@ -35,7 +35,7 @@ function getParentDir(path, skipRouteGroups = false) {
35
35
  * and the types loader (`syncTypes`) — must build a page's path this way so they agree
36
36
  * on its identity and the grouping is derivable from the stored path.
37
37
  * @param pageDir Absolute directory of the page whose index entry is being built.
38
- * @param pageFileName File name of the page within that directory (e.g. `page.mdx`).
38
+ * @param pageFileName File name of the page within that directory (for example, `page.mdx`).
39
39
  */
40
40
  export function indexRelativePagePath(pageDir, pageFileName) {
41
41
  const parentDir = getParentDir(pageDir, true);
@@ -393,7 +393,7 @@ export async function generateTypesMarkdown(options) {
393
393
  }
394
394
  }
395
395
  } else if (typeMeta.type === 'function') {
396
- const part = typeMeta.data.name;
396
+ const part = typeMeta.name;
397
397
  const data = typeMeta.data;
398
398
  const displayName = getDisplayName(part);
399
399
  addHeading(3, displayName);
@@ -490,7 +490,7 @@ export async function generateTypesMarkdown(options) {
490
490
  }
491
491
  } else if (typeMeta.type === 'class') {
492
492
  // For 'class' types (ClassTypeMeta)
493
- const part = typeMeta.data.name;
493
+ const part = typeMeta.name;
494
494
  const data = typeMeta.data;
495
495
  const displayName = getDisplayName(part);
496
496
  addHeading(3, displayName);
@@ -93,7 +93,7 @@ export interface UseCodeResult<T extends {} = {}> {
93
93
  /**
94
94
  * Slug for the currently selected file. Always derived from the canonical
95
95
  * (original) file name — transforms are a view preference and do not
96
- * produce separate slugs. Useful for building permalinks (e.g. `#${slug}`)
96
+ * produce separate slugs. Useful for building permalinks (for example, `#${slug}`)
97
97
  * that survive transform changes.
98
98
  */
99
99
  selectedFileSlug: string | undefined;
@@ -168,7 +168,7 @@ export interface UseCoordinatedExtras<TValue> {
168
168
  * Coordinate a piece of state across sibling component instances on
169
169
  * the same channel, so that visually disruptive value changes commit
170
170
  * in a single layout pass rather than independently. Designed as a
171
- * thin wrapper around any `useState`-shaped primitive (e.g.
171
+ * thin wrapper around any `useState`-shaped primitive (for example,
172
172
  * `useLocalStorageState`, `usePreference`, plain `useState`).
173
173
  *
174
174
  * **Originator flow** — calling the returned `setValue`:
@@ -180,7 +180,7 @@ export interface UseCoordinatedExtras<TValue> {
180
180
  * consistent with the optional `onCommit` side-effect
181
181
  *
182
182
  * **Receiver flow** — when the underlying `value` changes from outside
183
- * (e.g. a storage event from another tab):
183
+ * (for example, a storage event from another tab):
184
184
  * 1. `pendingValue` updates to match
185
185
  * 2. Coordination runs locally (this tab's peers run their own
186
186
  * phase-1 barrier)
@@ -20,7 +20,7 @@ function generatePeerId() {
20
20
  * Coordinate a piece of state across sibling component instances on
21
21
  * the same channel, so that visually disruptive value changes commit
22
22
  * in a single layout pass rather than independently. Designed as a
23
- * thin wrapper around any `useState`-shaped primitive (e.g.
23
+ * thin wrapper around any `useState`-shaped primitive (for example,
24
24
  * `useLocalStorageState`, `usePreference`, plain `useState`).
25
25
  *
26
26
  * **Originator flow** — calling the returned `setValue`:
@@ -32,7 +32,7 @@ function generatePeerId() {
32
32
  * consistent with the optional `onCommit` side-effect
33
33
  *
34
34
  * **Receiver flow** — when the underlying `value` changes from outside
35
- * (e.g. a storage event from another tab):
35
+ * (for example, a storage event from another tab):
36
36
  * 1. `pendingValue` updates to match
37
37
  * 2. Coordination runs locally (this tab's peers run their own
38
38
  * phase-1 barrier)
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Declares the calling component as a source of an initial, post-hydration
3
- * layout shift — e.g. a code block that swaps from its plain fallback to
3
+ * layout shift — for example, a code block that swaps from its plain fallback to
4
4
  * highlighted (and focus-collapsed) output once it hydrates.
5
5
  *
6
6
  * While any registered source is unsettled, {@link useCoordinated} holds its
@@ -5,7 +5,7 @@ import { registerLayoutShiftSource } from "./layoutShiftGate.mjs";
5
5
 
6
6
  /**
7
7
  * Declares the calling component as a source of an initial, post-hydration
8
- * layout shift — e.g. a code block that swaps from its plain fallback to
8
+ * layout shift — for example, a code block that swaps from its plain fallback to
9
9
  * highlighted (and focus-collapsed) output once it hydrates.
10
10
  *
11
11
  * While any registered source is unsettled, {@link useCoordinated} holds its
@@ -20,6 +20,6 @@ export interface TypeRefProps {
20
20
  * - No `TypesDataProvider` is present in the tree
21
21
  * - The type name has not been registered
22
22
  *
23
- * @param name - The type name to look up (e.g., "Root", "Trigger", "AccordionTrigger")
23
+ * @param name - The type name to look up (for example, "Root", "Trigger", "AccordionTrigger")
24
24
  */
25
25
  export declare function useType(name: string): TypeData | undefined;
@@ -13,7 +13,7 @@ import { useTypesDataContext } from "./TypesDataContext.mjs";
13
13
  * - No `TypesDataProvider` is present in the tree
14
14
  * - The type name has not been registered
15
15
  *
16
- * @param name - The type name to look up (e.g., "Root", "Trigger", "AccordionTrigger")
16
+ * @param name - The type name to look up (for example, "Root", "Trigger", "AccordionTrigger")
17
17
  */
18
18
  export function useType(name) {
19
19
  const context = useTypesDataContext();
@@ -24,7 +24,7 @@ export interface TypePropRefProps {
24
24
  * - No `TypesDataProvider` is present in the tree
25
25
  * - The type or property has not been registered
26
26
  *
27
- * @param typeName - The type name (e.g., "Root", "Trigger")
28
- * @param propName - The property name (e.g., "className", "defaultOpen")
27
+ * @param typeName - The type name (for example, "Root", "Trigger")
28
+ * @param propName - The property name (for example, "className", "defaultOpen")
29
29
  */
30
30
  export declare function useTypeProp(typeName: string, propName: string): TypePropData | undefined;
@@ -13,8 +13,8 @@ import { useTypesDataContext } from "./TypesDataContext.mjs";
13
13
  * - No `TypesDataProvider` is present in the tree
14
14
  * - The type or property has not been registered
15
15
  *
16
- * @param typeName - The type name (e.g., "Root", "Trigger")
17
- * @param propName - The property name (e.g., "className", "defaultOpen")
16
+ * @param typeName - The type name (for example, "Root", "Trigger")
17
+ * @param propName - The property name (for example, "className", "defaultOpen")
18
18
  */
19
19
  export function useTypeProp(typeName, propName) {
20
20
  const context = useTypesDataContext();