[docs] POC: wire @mui/internal-docs-infra types pipeline into API pages by JCQuintas · Pull Request #22091 · mui/mui-x

JCQuintas · 2026-04-14T14:36:37Z

Summary

Proof-of-concept wiring of the new @mui/internal-docs-infra types pipeline into mui-x API docs pages. Ports the base-ui pattern (mui/base-ui#2932) to generate per-component API docs from TypeScript types at build time instead of from the legacy runtime propTypes walker.

Scope: 294 API pages across charts, data-grid, date-pickers, tree-view, chat, scheduler, chat-box. Each page is a thin <TypesPageShell> wrapper around a generated types.<slug>.ts that calls createTypes(import.meta.url, Component) — rewritten at build time by the loadPrecomputedTypes webpack loader.

What's in this branch:

docs/src/modules/api-docs/createTypes.tsx + ReferenceTable.tsx + TypesPageShell.tsx — mui-x-side factory and renderer.
294 generated types.*.ts / page .js pairs under docs/pages/x/api/**.
docs/src/modules/api-docs/typesRegistry.json — name → url map used to collapse additional types that have their own page into a compact "Related:" link row.
docs/next.config.ts — webpack rule matching types.*.ts, React dedupe aliases, @mui/internal-docs-infra in transpilePackages.
tsconfig.json — flattened (previously extended @mui/monorepo/tsconfig.json), since the loader's loadTypescriptConfig walk chokes on node_modules package specifiers.
pnpm-workspace.yaml / package.json — TS 6.0.2 bump + (when iterating locally) link: overrides for the upstream extractor / docs-infra packages.

Known limitations — POC, not ready to merge:

Prop list is filtered via an allowedProps allow-list baked from the existing curated .json files. The pipeline pulls every reachable prop from the TS type, so without the allow-list internal props (plugins, seriesConfig, …) leak through.
ReferenceTable is a minimal renderer — no section layout, no slots/classes sections, no toc.
type _ = prefix strip and large-payload IPC framing are fixed upstream in companion PRs:
Depends on the in-progress docs-infra canary channel until those PRs land.

What's verified:

294 pages render with the expected component / hook / function / class / raw layouts.
Props list matches the legacy builder output for every verified family (charts, data-grid, pickers, tree-view).
pnpm eslint is clean across the generated tree.

Experimental port of base-ui PR mui#2932's approach to mui-x: - Per-page `types.<slug>.ts` entry colocated with the API page. Calls `createTypes(import.meta.url, Gauge)` which the webpack loader `@mui/internal-docs-infra/pipeline/loadPrecomputedTypes` rewrites at build time with fully-resolved component type metadata. - `docs/src/modules/api-docs/createTypes.tsx` factory binds mui-x's placeholder `ReferenceTable` to the shared docs-infra pipeline via `createTypesFactory` / `createMultipleTypesFactory`. - `docs/src/modules/api-docs/ReferenceTable.tsx` — minimal POC renderer; not styled to match ApiPage yet, just dumps props to a `<table>`. - `docs/next.config.ts` — webpack rule matching `docs/pages/x/api/**/types.*.ts` and piping through `loadPrecomputedTypes` after the default babel loader. - `docs/pages/x/api/charts/gauge.js` — swapped out for a thin wrapper that renders `<TypesGauge />` instead of reading `gauge.json`. - `tsconfig.json` — `extends` changed from `@mui/monorepo/tsconfig.json` to `./node_modules/@mui/monorepo/tsconfig.json`. The docs-infra loader's extends resolver uses `path.resolve(projectPath, raw.extends)` and can't handle node_modules package specifiers (upstream bug). Results (local `pnpm dev`): - Gauge page compiles in ~8s on cold load, ~140ms on subsequent reloads. - `createMultipleTypes` form didn't populate `type.props` for a single non-namespace component — had to drop to `createTypes` (singular). - 22 Gauge props resolved (value, cornerRadius, startAngle, endAngle, width, height, sx, classes, etc.) and rendered in the POC table. Known limitations (POC scope, deliberately out of scope): - DataGrid is too large: extraction took ~99s before hitting a wasm RuntimeError / memory-access-out-of-bounds. TS Language Service can't handle its full inheritance chain at this size. - Events, selectors, interface pages, exports, grid-api: untouched. - ReferenceTable is a placeholder — no styling, no slot/class sections, no mdx/description rendering beyond raw ReactNode. - `types.*.md` sidecar files are generated by the loader and currently committed; should move to .gitignore once the approach is validated. - Translation JSON files are unused by the new page.

Inline the compilerOptions previously inherited via `extends: "@mui/monorepo/tsconfig.json"` so the root tsconfig is self-contained. Unblocks `@mui/internal-docs-infra/pipeline/loadPrecomputedTypes`, whose `loadTypescriptConfig` walk resolves `extends` as a literal relative path and can't handle node_modules package specifiers. Inlined from monorepo tsconfig: target, forceConsistentCasingInFileNames, noEmit, module, experimentalDecorators, allowSyntheticDefaultImports, noErrorTruncation. Not inlined (already explicitly set by mui-x): lib, jsx, strict, allowJs, moduleResolution. Dropped entirely: the monorepo's `paths` map for `@mui/material`, `@mui/lab`, `@mui/system`, etc. — mui-x installs those as real packages so TS resolves them via node_modules without mapping. Verified: `tsc` passes cleanly for x-charts, x-data-grid, x-date-pickers, x-tree-view. `pnpm docs:api`-equivalent Gauge POC still resolves 22 props via the new types pipeline in ~8s cold / ~140ms warm.

Adds a DataGrid `types.data-grid.ts` entry as a POC repro and a diagnosis writeup at `scripts/docs-infra-oom-repro.md`. Root cause: `formatInlineTypeAsHast` in `@mui/internal-docs-infra/pipeline/loadServerTypes/typeHighlighting.mjs` is not memoized. For DataGrid, instrumentation showed: - 1947 total calls - 5 unique input strings - each call re-runs Oniguruma's TextMate regex VM on the same text Oniguruma runs inside a fixed-size WASM linear memory buffer. Repeated allocations on identical inputs fragment the heap until it overruns with `RuntimeError: memory access out of bounds` at wasm://wasm/001ce0fe — which is the vscode-oniguruma wasm blob used by @wooorm/starry-night, not tsgo as first suspected. Upstream fix filed as mui-public branch `jcquintas/fix-highlightTypes-memoization` (commit e60dafa2). Wraps formatInlineTypeAsHast with a process-lifetime `Map` keyed on `(unionPrintWidth, typeText)` plus a structuredClone on read so downstream mutations don't poison the cache. Adds 4 regression tests under `typeHighlighting > memoization`. Verified end-to-end with the same patch applied locally to mui-x's installed node_modules copy: /x/api/data-grid/data-grid 63s (was: crash after ~100s) /x/api/charts/gauge 8s cold / 140ms warm (unchanged) Separate issues surfaced while investigating (filed/to-file separately): 1. typescript-api-extractor/dist/parsers/typeResolver.js:295 silently downgrades TypeFlag.TemplateLiteral types to `any`. Correctness bug. 2. DataGrid's extracted shape is wrong even with the OOM fixed. Only surfaces 1 prop (`pagination`) and ~40 `BasePropsOverrides` augmentation interfaces. The generic ForwardRefExoticComponent signature isn't being instantiated to its resolved prop type. 3. loadTypescriptConfig.mts `extends` resolver — already worked around in commit efe32b0 (root tsconfig flattening).

mui-bot · 2026-04-14T14:38:17Z

Deploy preview: https://deploy-preview-22091--material-ui-x.netlify.app/

Bundle size report

Bundle	Parsed size	Gzip size
@mui/x-data-grid	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-charts	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view-pro	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 319ba2b

github-actions · 2026-04-14T14:40:59Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

dav-is · 2026-04-14T15:23:15Z

+  DefaultCode: InlineCode,
+};
+
+export const createTypes = createTypesFactory(factoryOptions);


The JSDoc here is important because it doesn't inherit it from createTypesFactory

Suggested change

export const createTypes = createTypesFactory(factoryOptions);

/**

* Creates a type doc component that renders a reference table for the given component.

* @param url Depends on `import.meta.url` to determine the source file location.

* @param component The component to render a reference table for.

* @param [meta] Additional meta for the typedocs.

*/

export const createTypes = createTypesFactory(factoryOptions);

dav-is · 2026-04-14T15:24:09Z

+};
+
+export const createTypes = createTypesFactory(factoryOptions);
+export const createMultipleTypes = createMultipleTypesFactory(factoryOptions);


Same here:

Suggested change

export const createMultipleTypes = createMultipleTypesFactory(factoryOptions);

/**

* Creates a type doc component that renders a reference table for the given component.

* A variant is a different implementation style of the same component.

* @param url Depends on `import.meta.url` to determine the source file location.

* @param components The components to render reference tables for.

* @param [meta] Additional meta for the typedocs.

*/

export const createMultipleTypes = createMultipleTypesFactory(factoryOptions);

dav-is · 2026-04-14T15:25:54Z

+          // New types pipeline (POC) — intercept `types.*.ts` next to API pages and
+          // precompute props metadata at build time via the docs-infra loader.
+          {
+            test: /[/\\]docs[/\\]pages[/\\]x[/\\]api[/\\].+[/\\]types\..*\.ts$/,


So that the types.ts and types.md files sort properly, I would recommend this format data-grid.types.ts

Suggested change

test: /[/\\]docs[/\\]pages[/\\]x[/\\]api[/\\].+[/\\]types\..*\.ts$/,

test: /[/\\]docs[/\\]pages[/\\]x[/\\]api[/\\].+[/\\].*\.types\.ts$/,

dav-is · 2026-04-14T15:27:27Z

+          ),
+          docs: path.resolve(MONOREPO_PATH, './docs'),
          docsx: path.resolve(currentDirectory, '../docs'),
+          // TEMP: force React dedupe so linked @mui/internal-docs-infra doesn't


Usually I add file:../../mui-public/packages/docs-infra/build/ in the package.json instead of linking, the downside is you have to run pnpm i after every build of docs-infra to sync the built files

JCQuintas added 5 commits April 13, 2026 19:25

changes

23f19c1

chnages

319ba2b

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Apr 14, 2026

dav-is reviewed Apr 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[docs] POC: wire @mui/internal-docs-infra types pipeline into API pages#22091

[docs] POC: wire @mui/internal-docs-infra types pipeline into API pages#22091
JCQuintas wants to merge 5 commits intomui:masterfrom
JCQuintas:docs-apitest-infra

JCQuintas commented Apr 14, 2026

Uh oh!

mui-bot commented Apr 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

dav-is Apr 14, 2026

Uh oh!

dav-is Apr 14, 2026

Uh oh!

dav-is Apr 14, 2026

Uh oh!

dav-is Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-export const createTypes = createTypesFactory(factoryOptions);
+/**
+ * Creates a type doc component that renders a reference table for the given component.
+ * @param url Depends on `import.meta.url` to determine the source file location.
+ * @param component The component to render a reference table for.
+ * @param [meta] Additional meta for the typedocs.
+ */
+export const createTypes = createTypesFactory(factoryOptions);

	test: /[/\\]docs[/\\]pages[/\\]x[/\\]api[/\\].+[/\\]types\..*\.ts$/,
	test: /[/\\]docs[/\\]pages[/\\]x[/\\]api[/\\].+[/\\].*\.types\.ts$/,

Uh oh!

Conversation

JCQuintas commented Apr 14, 2026

Summary

Uh oh!

mui-bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

github-actions Bot commented Apr 14, 2026

Uh oh!

dav-is Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

dav-is Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

dav-is Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

dav-is Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mui-bot commented Apr 14, 2026 •

edited

Loading