[docs-infra] Type Prop Compression

[dav-is]

Downstream PR: mui/base-ui#4497

Adds new pattern document explaining the methodology: Prop Compression Pattern

Adds lazy loading to type highlighting and compresses the HAST to optimize uncompressed HTML parse and CSS paint time.

Results

30% (-789 KB) reduction of Base UI's Combobox uncompressed HTML, bringing it under the 2 MB limit (1886 KB). As a tradeoff, compressed props can't be further compressed, causing a 5% (+14 KB) increase in the compressed HTML size. The plain text is used as a shared dictionary when decompressing to minimize losses in compression effeciency. Improves first contentful paint and hydration time by 42 ms. Achieved by reducing HTML parse time by 34% (-19ms), scripting time (to parse the RSC props) by 31% (-15ms), and reducing render time by 20% (-8ms).

23% (-283 KB) reduction of docs-infra docs CodeHighlighter page which has many types. Compressed HTML increased by 5% (+6 KB).

Breaking Change

• TypeRef and TypePropRef must now be provided via a <CodeComponentProvider> so that they are aviable on the client. These are already client components, so there shouldn't be any meaningful difference in bundle size
• Removed typeText and shortTypeText as they can be derived from type and shortType hast on the client (see diff)
• Renamed hastGzip to hastCompressed (mostly an internal change)

See migration

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	0B(0.00%)	0B(0.00%)
@mui/x-charts-pro	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[code-infra-dashboard]

Bundle size

Bundle	Parsed size	Gzip size
@base-ui/react	0B(0.00%)	0B(0.00%)
@mui/x-charts-pro	0B(0.00%)	0B(0.00%)

Details of bundle changes

Deploy preview

• docs/app/docs-infra/factories/abstract-create-types/page.mdx
• docs/app/docs-infra/factories/page.mdx
• docs/app/docs-infra/hooks/page.mdx
• docs/app/docs-infra/patterns/page.mdx
• docs/app/docs-infra/patterns/prop-compression/page.mdx

Performance

Total duration: 17.18 ms ▼-5.31 ms^(-23.6%) | Renders: 4 ⁽⁺⁰⁾ | Paint: 71.70 ms ▼-27.30 ms^(-27.6%)

Test	Duration	Renders
HeavyList mount	10.48 ms ▼-4.90 ms(-31.9%)	1 (+0)
DataGrid mount with paint timing	2.51 ms ▼-0.40 ms(-13.7%)	1 (+0)
Counter click	4.19 ms ▼-0.01 ms(-0.3%)	2 (+0)

Details of benchmark changes

---

Check out the code infra dashboard for more information about this PR.

[Janpot]

parsing HTML strings back into something React can work with for interactivity

This is a strawman argument that probably has come up at every discussion so far. It's really not something I ever proposed. What I used to propose was to break out of React and use dangerouslySetInnerHtml (or show plain text and do it an effect) with event delegation. i.e. you put a click event handler on the parent element and read data- attributes and coordinates on the event target to show a popup. This goes at 0Kb extra bundle size.

[dav-is]

you put a click event handler on the parent element and read data- attributes and coordinates on the event target to show a popup

Then we would not be able to dogfood Base UI components. The complicated state and positioning logic of these components are likely already imported to use elsewhere on the page. We can also use next/link for cross page type linking.

Also, the highlighted code is generated at build time (e.g. rehype plugin), the enhancement API runs on server render which is how we can add links based on data from the sitemap (if a rehype plugin reads an external file, it breaks caching). To do that we need to traverse the HTML AST. It's also an extension point for users, they can create their own enhancers that are basically rehype plugins. Otherwise, we are left with a black box that can't be easily extended within a user's repo.

There are tradeoffs with the approach, but the main point is that the compression library is only 4KB + 3KB dictionary and results in a large savings in html size, even compared against html string rendering: https://deploy-preview-1269--mui-internal.netlify.app/docs-infra/patterns/prop-compression#medium-snippet

[Janpot]

Then we would not be able to dogfood Base UI components. The complicated state and positioning logic of these components are likely already imported to use elsewhere on the page.

dogfooding has two main goals:

1. Finding regression early
2. Finding missing features early (or missing documentation)

In this case, the missing feature is an API to trigger popovers from DOM that is not react managed. I guess one could get somwhere with detached trigger handles but it's suboptimal a11y-wise. In general I'm not keen on having the dogfooding use-case dictate the architecture of something as foundational to docs infra as code highlighting.

We can also use next/link for cross page type linking.

next/link isn't much more than a component that renders an anchor tag and hands of its click event to the Next.js router, where the real complexity lies. If we're rendering anchors outside of react, it's trivial to delegate their clicks to the Next.js router ourselves. next/link isn't hiding complexity, it's just a convenience API.

Also, the highlighted code is generated at build time (e.g. rehype plugin), the enhancement API runs on server render which is how we can add links based on data from the sitemap (if a rehype plugin reads an external file, it breaks caching). To do that we need to traverse the HTML AST. It's also an extension point for users, they can create their own enhancers that are basically rehype plugins. Otherwise, we are left with a black box that can't be easily extended within a user's repo.

I don't understand this point, if your toolchain does code > hast > html, regardless of whether which step happens server side or client side, there is a point of extension.

[dav-is]

dangerouslySetInnerHtml is a viable method with its own set of tradeoffs, but this PR has nothing to do with it other than comparing the html weight from that solution. This PR is about deferring highlighting and the method for which we pass props across server client boundaries.

[Janpot]

I agree, I'm just reacting because you bring it up

...The alternative (parsing HTML strings back into something React can work with for interactivity)...

[dav-is]

I only mentioned it as a comparison, for numbers I could find, from the perspective of HAST vs HTML as a transfer data structure from server to client. For rendering, you could still transfer HAST from server to client, then render it with dangerouslySetInnerHtml. Sending a raw html string to the client makes having a code enhancer function on the client side (pages router can't have server side enhancers) not viable because it would increase the bundle by 60 KB.

Making code interactive with dangerouslySetInnerHtml and event bubbling has an unknown bundle size, certainly not zero. I would guess probably around the same 4 KB mark if it reused Base UI components somehow. The Base UI popover is 38 KB and might already be included in the page.

So far, the docs-infra package renders real react components in codeblocks with minimal performance impact. The TypeRef component even uses React Context to load type data. The API feels very similar to how MDX works.

[Janpot]

What is "full highlighting"? transforming a string containing code all the way to DOM?

idle and hydration feel largely redundant, are we really using them?

[dav-is]

Fallback:

Full Highlighting:

On the first render, the detailed type will likely be hidden within the collapsed accordion. Also note that the shortType (Union) is still highlighted on the first render before hydration.

[Janpot]

What I'm asking is: where is the parsing happening? serverside+transferred or browserside?

[dav-is]

starry-night runs on the server at build time

[Janpot]

then replace with fully-highlighted content on client mount.

Highlighting is fully done browser-side? from a string containing code to generating spans in the DOM?

[dav-is]

Highlighting is precomputed during build and passed to the client. All the client does is swap the fallback text with a rendered HAST. No highlighting lib on the client

[Janpot]

But won't we need a client-side highlighting mode for editable code?

[dav-is]

But won't we need a client-side highlighting mode for editable code?

Yes, for code blocks that is supported, but optional. For the actual type definitions, live editing isn't supported.

[Janpot]

Why is it called "fallback"? Is that the same "fallback" as in "links-only fallback"? Or are there multiple ways of transferring the HAST from server to client?

[dav-is]

This is intended to only be used to pass very simple HAST for .frame elements that wrap the plain text fallback code. For very large codeblocks, the fallback might need to be broken into mulitple frames, so that they can be enhanced in smaller chunks.

[['span', 'frame', "| boolean\n| React.RefObject<HTMLElement | null>\n| ((\n    openType: 'mouse' | 'touch' | 'pen' | 'keyboard' | '',\n  ) => boolean | void | HTMLElement | null)\n| undefined"]]

Renders as:

<pre class="CodeBlockPreInline"><code class="language-ts"><span class="frame">| boolean
| React.RefObject&lt;HTMLElement | null&gt;
| ((
    openType: 'mouse' | 'touch' | 'pen' | 'keyboard' | '',
  ) =&gt; boolean | void | HTMLElement | null)
| undefined</span></code></pre>

The fallback term mirrors that of suspense boundaries:

<Suspense fallback={<Loading />}>
  <SomeComponent />
</Suspense>