Components: Skip polymorphism prop typings on intersection

[aduth]

What?

Updates @wordpress/components shared components types to skip evaluating polymorphism when generating inner props types on WordPressComponent before defining its own intersecting as polymorphism.

Why?

Reduces memory consumption in a case where we don't meaningfully need the base typing.

This is an outcome of some research based on failing CI builds that may be related to memory usage (related Slack discussion), and so this could potentially improve reliability of tests.

How?

Passing false instead of forwarding IsPolymorphic prevents as type assignment in the base type. keyof React.JSX.IntrinsicElements creates a union of hundreds of element types that causes a non-insignificant amount of memory usage when resolving in the intersection type of WordPressComponent.

Very important to note that intersecting isn't the same as overriding, and it's not claimed that the typings behave in a way that { a: T } & { a: TT } is equivalent to { a: TT }. But in this case they provably reduce to the same result, and I don't believe it's the case that we intentionally want to inherit the base props at this typing layer. My understanding is that in WordPressComponent's typings, it infers what element type will be assigned on as, so we can skip the guess-work of saying that as can be any valid element tag name.

Provability comes from absorption law:

A ∧ (A ∨ B) = A

So in terms of types:

{ as: TT } & { as?: TT | keyof React.JSX.IntrinsicElements; }

Is equivalent to (in how we enforce assignability):

{ as: TT }

(optional intersected with required becomes required)

Impact:

The net result here is -6.6% memory used and -3.2% memory allocations when type-checking @wordpress/components, with @wordpress/components accounting for 90%+ of memory usage of type-checking the entire project.

Metric	Baseline (IsPolymorphic)	Changed (false)	Δ
Symbols	10,693,267	10,645,697	−0.4%
Instantiations	40,579,658	40,561,637	−0.04%
Memory used	7.55 GB	7.05 GB	−6.6%
Memory allocs	58,828,467	56,919,825	−3.2%

The reduction isn't huge, but with how much this polymorphism behavior contributes to overall memory usage across the entire project, it makes a meaningful dent. The polymorphism still remains a problematic source of significant memory consumption, but despite several attempts to explore broader improvements, I wasn't able to find a silver bullet solution, or at least one that doesn't involve losing benefits of the polymorphism (e.g. using as="label" on a polymorphic component makes TypeScript aware of additional label-specific props like htmlFor).

It also may carry over to build time; in a trial of 4-7 test runs compared between this branch and trunk, a full TypeScript build (tsc --build) reduced from 33.4s on average to 30.8s (~ -8%).

It's not entirely clear this will benefit the original problem with builds terminating, as it does appear that the peak memory usage of the build remains stable at around ~10.7GB.

Testing Instructions

Verify TypeScript build is unaffected:

npm run build

If you want to validate performance yourself, you can compare the following set of commands on this branch and trunk:

rm -f packages/components/tsconfig.tsbuildinfo
/usr/bin/time -l npx tsc -p packages/components/tsconfig.json --extendedDiagnostics 2>&1 \
  | grep -E '^(Symbols|Instantiations|Memory used|Memory allocs):|maximum resident'

Or full project timings and memory usage:

npx tsc --build --clean >/dev/null 2>&1
rm -rf packages/*/build-types
/usr/bin/time -l npx tsc --build 2>&1 | grep -E 'maximum resident|real'

Use of AI Tools

This was the result of a very long and involved conversation with Claude Code + Opus 4.8. So yes, a lot of the thinking and measuring here is AI-assisted, though with a lot of scrutiny, pushback, and idea exploration prompted by myself.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: 0 B

Total Size: 7.73 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in dfc1c71.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29532067397
📝 Reported issues:

• [Flaky Test] should paste block styles using keyboard #78759 in /test/e2e/specs/editor/various/list-view.spec.js
• [Flaky Test] should update the HTML only for the latest navigation #78835 in /test/e2e/specs/interactivity/router-navigate.spec.ts

[aduth]

As seen in the component descriptions in dfc1c71, one unfortunate side-effect / conflict of this is that the component documentation isn't able to decipher the types well enough to maintain that as is in-fact optional. This typing is quite complex but the way it's expected to work is to use one of the two signatures depending entirely if as is provided, but the documentation tool is not smart enough to decipher this. Previously it relied on the optional as in the intersection to detect it as optional, which (as argued in the original post) is not the actual behavior of the intersection anyways.

[mirka]

I'm open to considering a more drastic long term change, like adding a render prop to all the components that currently have an as prop, and deprecate the as.

Though, if I remember correctly, when I was trying to optimize this part of the type check performance before, removing the polymorphism entirely didn't have that much of a drastic effect on the whole. I might be misremembering what exactly I did though.

[aduth]

This unfortunately wasn't enough to help the build instability we've been seeing lately. I'm trying a more aggressive approach in #80705.

[mirka]

⚠️ These as props are definitely not required. Noticed when reviewing #82259, which will fix this particular readme.

Heads up that this is the second time I noticed unexpected type changes caused by this PR. The other was #82259 (a disabled prop was silently added to ToggleGroupControl).

There may be other irregularities.

[mirka]

I guess the disabled prop on ToggleGroupControl was technically added in #80705, which I'm assuming was an involuntary consequence of the type changes…? Not sure.

[aduth]

#80705 added disabled prop because DataViews was already passing the prop, by virtue of how the previous typings were more permissive in accepting any HTML prop, despite the fact that ToggleGroupControl never declared disabled as a prop and its use of WordPressComponent was as a non-polymorphic div element that also shouldn't have accepted disabled. The typings became more accurate, and revealed the type error on existing usage in DataViews. The expectation was that disabled was still valid because of how it's passed through to Ariakit (related discussion), but if I follow now based on #80705 and my own AI-assisted recollection of events, that may have only been true for one of the two paths that the control can take (i.e. the radio path).

As far as as being incorrectly documented as required: That's a valid issue to flag, though the typings are still correct; otherwise we'd have type errors all over the place. It's a problem of the documentation extraction. Given how Storybook is migrating away from the react-docgen-typescript tool we're using for that documentation extraction, I wonder if we'd be able to similarly use their new "meta" extraction tool for improved extraction accuracy.

[aduth]

Given how Storybook is migrating away from the react-docgen-typescript tool we're using for that documentation extraction, I wonder if we'd be able to similarly use their new "meta" extraction tool for improved extraction accuracy.

Judging by the components manifest that uses the new extractor, it would be better. I'm not sure if it's usable independently from Storybook though.