@mui/internal-docs-infra 0.13.1-canary.31 → 0.13.1-canary.32

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.
@@ -1,7 +1,8 @@
1
1
  import * as React from 'react';
2
2
  import { createCoordinatedLazy } from "../CoordinatedLazy/createCoordinatedLazy.mjs";
3
- import { createClientProps } from "./createClientProps.mjs";
3
+ import { createClientProps, createContentFrame } from "./createClientProps.mjs";
4
4
  import { CodeHighlighterClient } from "./CodeHighlighterClient.mjs";
5
+ import { ContentFrameProvider } from "./useContentFrame.mjs";
5
6
 
6
7
  /**
7
8
  * The user props the CodeHighlighter chunk threads to its content + loaders. It
@@ -40,10 +41,18 @@ function CodeHighlighterChunkContent(props) {
40
41
  * The chunk's loading placeholder, used as the Suspense fallback while a server
41
42
  * loader streams. It renders the pre-prepared `<ContentLoading />` element threaded
42
43
  * through the user props (the actual loading UI is built up front by
43
- * `prepareInitialSource`).
44
+ * `prepareInitialSource`), inside the `ContentFrame` when one is configured.
44
45
  */
45
46
  function CodeHighlighterChunkLoading(props) {
46
- return /*#__PURE__*/_jsx(React.Fragment, {
47
+ const frame = createContentFrame(props, /*#__PURE__*/_jsx(ContentFrameProvider, {
48
+ framed: true,
49
+ children: props.fallback
50
+ }));
51
+ if (frame) {
52
+ return frame;
53
+ }
54
+ return /*#__PURE__*/_jsx(ContentFrameProvider, {
55
+ framed: false,
47
56
  children: props.fallback ?? null
48
57
  });
49
58
  }
@@ -27,6 +27,7 @@ import { CoordinatedContentContext } from "../CoordinatedLazy/CoordinatedContent
27
27
  import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
28
28
  import { scheduleDeferredPrecompute } from "./scheduleDeferredPrecompute.mjs";
29
29
  import * as Errors from "./errors.mjs";
30
+ import { ContentFrameProvider } from "./useContentFrame.mjs";
30
31
  import { jsx as _jsx } from "react/jsx-runtime";
31
32
  const DEBUG = false; // Set to true for debugging purposes
32
33
 
@@ -1446,7 +1447,10 @@ export function CodeHighlighterClient(props) {
1446
1447
  value: coordinatedFallbackContext,
1447
1448
  children: /*#__PURE__*/_jsx(CodeHighlighterFallbackContext.Provider, {
1448
1449
  value: fallbackContext,
1449
- children: props.fallback
1450
+ children: /*#__PURE__*/_jsx(ContentFrameProvider, {
1451
+ framed: false,
1452
+ children: props.fallback
1453
+ })
1450
1454
  })
1451
1455
  });
1452
1456
  const contentChildren = props.loadPrecompute && /*#__PURE__*/React.isValidElement(props.children) ? /*#__PURE__*/React.cloneElement(props.children, {
@@ -1461,10 +1465,40 @@ export function CodeHighlighterClient(props) {
1461
1465
  value: context,
1462
1466
  children: /*#__PURE__*/_jsx(CoordinatedContentContext.Provider, {
1463
1467
  value: contentContext,
1464
- children: contentChildren
1468
+ children: /*#__PURE__*/_jsx(ContentFrameProvider, {
1469
+ framed: false,
1470
+ children: contentChildren
1471
+ })
1465
1472
  })
1466
1473
  });
1467
1474
 
1475
+ // Changing provider ancestry here remounts stateful previews.
1476
+ if (props.frame) {
1477
+ // A Server Component frame reaches the client as its rendered output, so cloning
1478
+ // it would overwrite the preview it placed in its own children.
1479
+ if (typeof props.frame.type === 'string' || props.frame.type === React.Fragment) {
1480
+ throw new Errors.ErrorCodeHighlighterClientServerContentFrame();
1481
+ }
1482
+ return /*#__PURE__*/_jsx(CodeHighlighterContext.Provider, {
1483
+ value: context,
1484
+ children: /*#__PURE__*/_jsx(CoordinatedFallbackContext.Provider, {
1485
+ value: showFallback ? coordinatedFallbackContext : undefined,
1486
+ children: /*#__PURE__*/_jsx(CodeHighlighterFallbackContext.Provider, {
1487
+ value: fallbackContext,
1488
+ children: /*#__PURE__*/_jsx(CoordinatedContentContext.Provider, {
1489
+ value: contentContext,
1490
+ children: /*#__PURE__*/React.cloneElement(props.frame, {
1491
+ component: bridgedComponents?.[variantName]
1492
+ }, /*#__PURE__*/_jsx(ContentFrameProvider, {
1493
+ framed: true,
1494
+ children: showFallback ? props.fallback : contentChildren
1495
+ }))
1496
+ })
1497
+ })
1498
+ })
1499
+ });
1500
+ }
1501
+
1468
1502
  // Show the fallback OR the content (swap on data-readiness). The content loads
1469
1503
  // its own chunk after the swap, covered by the fallback it inherits via context.
1470
1504
  return showFallback ? fallbackNode : contentNode;
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import type { Code, CodeHighlighterBaseProps, CodeHighlighterClientProps } from "./types.mjs";
2
+ import type { Code, CodeHighlighterBaseProps, CodeHighlighterClientProps, ContentFrameProps } from "./types.mjs";
3
3
  import type { CompressedFallback } from "./fallbackFormat.mjs";
4
4
  export interface CreateClientPropsOptions<T extends {}> extends CodeHighlighterBaseProps<T> {
5
5
  code?: Code;
@@ -8,6 +8,11 @@ export interface CreateClientPropsOptions<T extends {}> extends CodeHighlighterB
8
8
  processedGlobalsCode?: Array<Code>;
9
9
  residualFallbacks?: CompressedFallback;
10
10
  }
11
+ /**
12
+ * Render the `ContentFrame` with the initial loading props, or `undefined` when no
13
+ * frame applies (no `ContentFrame`, a skipped fallback, or no prepared fallback).
14
+ */
15
+ export declare function createContentFrame<T extends {}>(props: Pick<CreateClientPropsOptions<T>, 'ContentFrame' | 'fallback' | 'skipFallback'>, children: React.ReactNode): React.ReactElement<ContentFrameProps<T>> | undefined;
11
16
  /**
12
17
  * Assemble the props for the `'use client'` `CodeHighlighterClient` from the
13
18
  * server/isomorphic props: rewrite the top-level URL to its hosted form, pre-render
@@ -2,6 +2,23 @@ import * as React from 'react';
2
2
  import { replaceUrlPrefix } from "../pipeline/loaderUtils/applyUrlPrefix.mjs";
3
3
  import { resolveFallbackCritical } from "./resolveFallbackCritical.mjs";
4
4
  import { jsx as _jsx } from "react/jsx-runtime";
5
+ /**
6
+ * Render the `ContentFrame` with the initial loading props, or `undefined` when no
7
+ * frame applies (no `ContentFrame`, a skipped fallback, or no prepared fallback).
8
+ */
9
+ export function createContentFrame(props, children) {
10
+ if (!props.ContentFrame || props.skipFallback) {
11
+ return undefined;
12
+ }
13
+ if (! /*#__PURE__*/React.isValidElement(props.fallback)) {
14
+ return undefined;
15
+ }
16
+ return /*#__PURE__*/_jsx(props.ContentFrame, {
17
+ ...props.fallback.props,
18
+ children: children
19
+ });
20
+ }
21
+
5
22
  /**
6
23
  * Assemble the props for the `'use client'` `CodeHighlighterClient` from the
7
24
  * server/isomorphic props: rewrite the top-level URL to its hosted form, pre-render
@@ -51,6 +68,7 @@ export function createClientProps(props) {
51
68
  } : undefined)
52
69
  };
53
70
  return {
71
+ frame: createContentFrame(props, null),
54
72
  url,
55
73
  code,
56
74
  precompute,
@@ -109,6 +109,9 @@ export declare class ErrorCodeHighlighterClientMissingData extends ErrorCodeHigh
109
109
  export declare class ErrorCodeHighlighterClientMissingFallbackHoist extends ErrorCodeHighlighterClientValidation {
110
110
  constructor();
111
111
  }
112
+ export declare class ErrorCodeHighlighterClientServerContentFrame extends ErrorCodeHighlighterClientValidation {
113
+ constructor();
114
+ }
112
115
  export declare class ErrorCodeHighlighterClientDynamicContentRequiresFallback extends ErrorCodeHighlighterClientValidation {
113
116
  constructor();
114
117
  }
@@ -224,6 +224,11 @@ export class ErrorCodeHighlighterClientMissingFallbackHoist extends ErrorCodeHig
224
224
  super(`Missing fallback data - A ContentLoading component was provided but did not hoist fallback data. ` + `Make sure your ContentLoading component calls \`useCodeFallback(props)\` and passes the component props.`);
225
225
  }
226
226
  }
227
+ export class ErrorCodeHighlighterClientServerContentFrame extends ErrorCodeHighlighterClientValidation {
228
+ constructor() {
229
+ super(`ContentFrame must be a Client Component - The frame arrived already rendered, so its ` + `children and preview cannot be replaced while content loads. Add \`'use client'\` to the ` + `module that defines the ContentFrame.`);
230
+ }
231
+ }
227
232
  export class ErrorCodeHighlighterClientDynamicContentRequiresFallback extends ErrorCodeHighlighterClientValidation {
228
233
  constructor() {
229
234
  super(`Dynamic content requires a ContentLoading - The Content component loads asynchronously ` + `(e.g. via \`LazyContent\`), but no \`ContentLoading\` was provided to show while it loads, ` + `so the slot would flash empty. Provide a \`ContentLoading\` component, or render the content synchronously.`);
@@ -1,4 +1,6 @@
1
1
  export * from "./CodeHighlighter.mjs";
2
2
  export { useCodeFallback } from "./useCodeFallback.mjs";
3
3
  export type { UseCodeFallbackResult } from "./useCodeFallback.mjs";
4
+ export { useContentFrame } from "./useContentFrame.mjs";
5
+ export type { UseContentFrameResult } from "./useContentFrame.mjs";
4
6
  export { mergeComments } from "./mergeComments.mjs";
@@ -1,3 +1,4 @@
1
1
  export * from "./CodeHighlighter.mjs";
2
2
  export { useCodeFallback } from "./useCodeFallback.mjs";
3
+ export { useContentFrame } from "./useContentFrame.mjs";
3
4
  export { mergeComments } from "./mergeComments.mjs";
@@ -605,9 +605,20 @@ export interface CodeFunctionProps {
605
605
  };
606
606
  }
607
607
  /**
608
- * Component and rendering props
608
+ * A persistent shell surrounding loading and interactive content. It must be a
609
+ * Client Component. `component` follows the selected variant and its live preview;
610
+ * every other prop is the initial loading snapshot and does not update on the client.
609
611
  */
612
+ export type ContentFrameProps<T extends {}> = ContentLoadingProps<T> & {
613
+ children: React.ReactNode;
614
+ };
615
+ /** Component and rendering props. */
610
616
  export interface CodeRenderingProps<T extends {}> {
617
+ /**
618
+ * Client Component that keeps the preview shell mounted while loading and
619
+ * interactive chrome change. Requires `ContentLoading`.
620
+ */
621
+ ContentFrame?: React.ComponentType<ContentFrameProps<T>>;
611
622
  /** Component to render the code content and preview */
612
623
  Content: React.ComponentType<ContentProps<T>>;
613
624
  /** Additional props passed to the Content component */
@@ -617,6 +628,8 @@ export interface CodeRenderingProps<T extends {}> {
617
628
  * Client-specific rendering props
618
629
  */
619
630
  export interface CodeClientRenderingProps {
631
+ /** Pre-rendered persistent shell, seeded from the initial loading metadata. */
632
+ frame?: React.ReactElement<Pick<ContentFrameProps<{}>, 'children' | 'component'>>;
620
633
  /** The CodeContent component that renders the code display and syntax highlighting */
621
634
  children: React.ReactNode;
622
635
  /** Loading placeholder shown while code is being processed */
@@ -165,38 +165,44 @@ export function useCodeFallback(props) {
165
165
  }
166
166
  }
167
167
  }, [setFallbackHasts, variantName, mainFile, source, extraSource, propsExtraVariants, ctxExtraVariants]);
168
- if (!props) {
169
- return {};
170
- }
171
- const collapseToEmpty = props.collapseToEmpty === true;
172
-
173
- // Resolve extraVariants: prefer props, fall back to context
174
- const allExtraVariants = propsExtraVariants || ctxExtraVariants;
175
- let resolvedExtraVariants;
176
- if (allExtraVariants) {
177
- resolvedExtraVariants = {};
168
+ const collapseToEmpty = props?.collapseToEmpty === true;
169
+ const fileNames = props?.fileNames;
170
+ const totalLines = props?.totalLines;
171
+ const focusedLines = props?.focusedLines;
172
+ const collapsible = props?.collapsible;
173
+ const language = props?.language;
174
+ const allExtraVariants = props ? propsExtraVariants || ctxExtraVariants : undefined;
175
+ const resolvedExtraVariants = React.useMemo(() => {
176
+ if (!allExtraVariants) {
177
+ return undefined;
178
+ }
179
+ const result = {};
178
180
  for (const [name, variant] of Object.entries(allExtraVariants)) {
179
- resolvedExtraVariants[name] = convertVariantSource(variant, collapseToEmpty);
181
+ result[name] = convertVariantSource(variant, collapseToEmpty);
180
182
  }
181
- }
182
- const converted = convertVariantSource(props, collapseToEmpty);
183
- const {
183
+ return result;
184
+ }, [allExtraVariants, collapseToEmpty]);
185
+
186
+ // Readiness updates must not rebuild unchanged fallback trees.
187
+ const converted = React.useMemo(() => convertVariantSource({
188
+ source,
189
+ extraSource,
190
+ fileNames,
184
191
  totalLines,
185
192
  focusedLines,
186
193
  collapsible
187
- } = converted;
188
- // Build the displayed file's `<code>` once, here, so every ContentLoading paints
189
- // identical attributes to `<Pre>`. `null` when there's nothing to paint. Extra files/variants
190
- // carry their own `source` + counts on `extraSource` / `extraVariants` for the
191
- // consumer to render the same way.
192
- const code = converted.source ? /*#__PURE__*/_jsx("code", {
193
- className: props.language ? `language-${props.language}` : undefined,
194
- "data-filename": props.fileNames?.[0],
195
- "data-collapsible": collapsible ? '' : undefined,
196
- "data-total-lines": totalLines,
197
- "data-focused-lines": focusedLines,
194
+ }, collapseToEmpty), [source, extraSource, fileNames, totalLines, focusedLines, collapsible, collapseToEmpty]);
195
+ const code = React.useMemo(() => converted.source ? /*#__PURE__*/_jsx("code", {
196
+ className: language ? `language-${language}` : undefined,
197
+ "data-filename": fileNames?.[0],
198
+ "data-collapsible": converted.collapsible ? '' : undefined,
199
+ "data-total-lines": converted.totalLines,
200
+ "data-focused-lines": converted.focusedLines,
198
201
  children: hastToJsx(converted.source)
199
- }) : null;
202
+ }) : null, [converted, language, fileNames]);
203
+ if (!props) {
204
+ return {};
205
+ }
200
206
  return {
201
207
  ...converted,
202
208
  extraVariants: resolvedExtraVariants,
@@ -0,0 +1,33 @@
1
+ import * as React from 'react';
2
+ export interface UseContentFrameResult {
3
+ /** Whether a `ContentFrame` surrounds this content and renders the preview. */
4
+ framed: boolean;
5
+ }
6
+ /**
7
+ * Marks the `Content` and `ContentLoading` of one `CodeHighlighter` as framed or not,
8
+ * so a nested `CodeHighlighter` never inherits the flag of the one around it.
9
+ */
10
+ export declare function ContentFrameProvider(props: {
11
+ framed: boolean;
12
+ children: React.ReactNode;
13
+ }): React.JSX.Element;
14
+ /**
15
+ * Hook for `Content` and `ContentLoading` components to detect a surrounding
16
+ * `ContentFrame`. When `framed` is `true`, the frame renders the preview, so the
17
+ * component should render only its chrome.
18
+ *
19
+ * @example
20
+ * ```tsx
21
+ * function MyContentLoading(props: ContentLoadingProps<{}>) {
22
+ * const fallback = useCodeFallback(props);
23
+ * const { framed } = useContentFrame();
24
+ * return (
25
+ * <div>
26
+ * {!framed && props.component}
27
+ * {fallback.code}
28
+ * </div>
29
+ * );
30
+ * }
31
+ * ```
32
+ */
33
+ export declare function useContentFrame(): UseContentFrameResult;
@@ -0,0 +1,46 @@
1
+ 'use client';
2
+
3
+ import * as React from 'react';
4
+ import { jsx as _jsx } from "react/jsx-runtime";
5
+ const UNFRAMED = {
6
+ framed: false
7
+ };
8
+ const FRAMED = {
9
+ framed: true
10
+ };
11
+ const ContentFrameContext = /*#__PURE__*/React.createContext(UNFRAMED);
12
+
13
+ /**
14
+ * Marks the `Content` and `ContentLoading` of one `CodeHighlighter` as framed or not,
15
+ * so a nested `CodeHighlighter` never inherits the flag of the one around it.
16
+ */
17
+ if (process.env.NODE_ENV !== "production") ContentFrameContext.displayName = "ContentFrameContext";
18
+ export function ContentFrameProvider(props) {
19
+ return /*#__PURE__*/_jsx(ContentFrameContext.Provider, {
20
+ value: props.framed ? FRAMED : UNFRAMED,
21
+ children: props.children
22
+ });
23
+ }
24
+
25
+ /**
26
+ * Hook for `Content` and `ContentLoading` components to detect a surrounding
27
+ * `ContentFrame`. When `framed` is `true`, the frame renders the preview, so the
28
+ * component should render only its chrome.
29
+ *
30
+ * @example
31
+ * ```tsx
32
+ * function MyContentLoading(props: ContentLoadingProps<{}>) {
33
+ * const fallback = useCodeFallback(props);
34
+ * const { framed } = useContentFrame();
35
+ * return (
36
+ * <div>
37
+ * {!framed && props.component}
38
+ * {fallback.code}
39
+ * </div>
40
+ * );
41
+ * }
42
+ * ```
43
+ */
44
+ export function useContentFrame() {
45
+ return React.useContext(ContentFrameContext);
46
+ }
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import type { Code, CodeHighlighterProps, ContentLoadingProps, ContentProps, LoadCodeMeta, LoadSource, LoadVariantMeta, ParseSource, SourceEnhancers } from "../CodeHighlighter/types.mjs";
2
+ import type { Code, CodeHighlighterProps, ContentLoadingProps, ContentFrameProps, ContentProps, LoadCodeMeta, LoadSource, LoadVariantMeta, ParseSource, SourceEnhancers } from "../CodeHighlighter/types.mjs";
3
3
  import type { DemoGlobalData } from "../createDemoData/types.mjs";
4
4
  type CreateDemoMeta = {
5
5
  name?: string;
@@ -49,6 +49,7 @@ type CreateDemoMeta = {
49
49
  type AbstractCreateDemoOptions<T extends {}> = {
50
50
  DemoContent: React.ComponentType<ContentProps<T>>;
51
51
  DemoContentLoading?: React.ComponentType<ContentLoadingProps<T>>;
52
+ DemoContentFrame?: React.ComponentType<ContentFrameProps<T>>;
52
53
  DemoTitle?: React.ComponentType<{
53
54
  slug?: string;
54
55
  children?: string;
@@ -92,6 +92,7 @@ export function abstractCreateDemo(options, url, variants, meta) {
92
92
  initialExpanded: initialExpanded,
93
93
  initialDisabled: initialDisabled,
94
94
  Content: options.DemoContent,
95
+ ContentFrame: options.DemoContentFrame,
95
96
  ContentLoading: options.DemoContentLoading,
96
97
  loadCodeMeta: options.loadCodeMeta,
97
98
  loadVariantMeta: options.loadVariantMeta,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mui/internal-docs-infra",
3
- "version": "0.13.1-canary.31",
3
+ "version": "0.13.1-canary.32",
4
4
  "author": "MUI Team",
5
5
  "description": "MUI Infra - internal documentation creation tools.",
6
6
  "license": "MIT",
@@ -814,5 +814,5 @@
814
814
  "bin": {
815
815
  "docs-infra": "./cli/index.mjs"
816
816
  },
817
- "gitSha": "fb999aabc9746b50f3cd915e236d646cf894eff4"
817
+ "gitSha": "ade666223d2e07ada27dbdedb646057819ab8f56"
818
818
  }
@@ -247,6 +247,8 @@ export class SocketClient {
247
247
  attemptConnect(socketPath) {
248
248
  return new Promise((resolve, reject) => {
249
249
  this.socket = connect(socketPath);
250
+ // Decoding each chunk separately corrupts characters split across chunks.
251
+ this.socket.setEncoding('utf8');
250
252
  this.socket.on('connect', () => {
251
253
  // Remove error listener after successful connection
252
254
  this.socket?.removeAllListeners('error');
@@ -272,8 +274,7 @@ export class SocketClient {
272
274
  * Optimized to avoid O(n²) behavior on large messages: only split the buffer
273
275
  * when the incoming chunk actually contains a newline delimiter.
274
276
  */
275
- handleData(data) {
276
- const chunk = data.toString();
277
+ handleData(chunk) {
277
278
  this.buffer += chunk;
278
279
 
279
280
  // Fast path: skip expensive split if this chunk has no message boundary
@@ -90,8 +90,10 @@ export class SocketServer {
90
90
  handleConnection(socket) {
91
91
  this.connections.add(socket);
92
92
  let buffer = '';
93
+ // Decoding each chunk separately corrupts characters split across chunks.
94
+ socket.setEncoding('utf8');
93
95
  socket.on('data', data => {
94
- buffer += data.toString();
96
+ buffer += data;
95
97
 
96
98
  // Process complete messages (delimited by newlines)
97
99
  const messages = buffer.split('\n');