Expose `@material-ui/core/utils` from top-level `@material-ui/core`

[NMinhNguyen]

• I have searched the issues of this repository and believe that this is not a duplicate.

Summary 💡

// packages/material-ui/src/index.js
+ export * from './utils';

Examples 🌈

import { useForkRef } from '@material-ui/core'

Motivation 🔦

I may be mistaken, but from what I gather, @material-ui/core/utils is probably safe to import since it has typings, is a 2nd level import, and is imported by another package, @material-ui/lab, although strictly speaking there's no docs. There's also mention of making setRef private, which suggests that utils are currently public.

The main motivation to export it from the top-level @material-ui/core is UMD bundles - we have a design system where we'd like to externalise @material-ui/core but we're currently importing a few things from utils and thus we can't just do e.g. import { useForkRef } from '@material-ui/core'. There are a few userland workarounds like copying and pasting the utils, or somehow still bundling in nested imports like @material-ui/core/utils (as in, not externalising), but we'd like to avoid that if possible. Another module we're currently relying on is @material-ui/core/styles/zIndex but that one we should be able to retrieve by calling createMuiTheme and extracting it from there instead, so not that much of a problem.

Presumably, if @material-ui/lab was to provide a UMD bundle, it would run into this constraint as well.

[eps1lon]

Sounds reasonable. @oliviertassinari did we reach a conclusion how we want to consolidate utils or do we stick with the current "put utils as low as possible" approach?

[NMinhNguyen]

"put utils as low as possible" approach

What does this mean? For someone not too familiar with the approach 🙂

[eps1lon]

We have @material-ui/utils as well as each package as its own utils module. We usually start out with having utils even lower e.g. in @material-ui/core/SomeComponent/helpers (or utils). If we need it somewhere else we move it up (here @material-ui/core/utils. Once a lab component (or @material-ui/styles) needs it we move it to @material-ui/utils.

Basically to prevent exposing potentially poor abstractions too early. But I wouldn't be surprised if it's totally random in the end.

Edit: State in react is a good analogy. You don't put state directly into your redux store at first. You start out low until that doesn't work anymore.

[NMinhNguyen]

I think that's fair! And very sane. Would you say @material-ui/core/utils are currently public though?

[eps1lon]

Would you say @material-ui/core/utils are currently public though?

Yes. Any first and second level path import.

Be aware that we only support first and second level imports. Anything deeper is considered private and can cause issues, such as module duplication in your bundle.

-- https://material-ui.com/guides/minimizing-bundle-size/#option-1

[NMinhNguyen]

Shall I raise a PR to re-export them then?

[eps1lon]

Sure, Olivier can chime in if I missed something.

[oliviertassinari]

I think that the only public modules are the ones exported in the barrel index, so as we are speaking @material-ui/core/utils is private. I think that we can put @material-ui/utils in the same category: private (because not documented).

[NMinhNguyen]

@oliviertassinari would your suggestion be to copy & paste the utils in my project then?

[eps1lon]

I think that we can put @material-ui/utils in the same category: private (because not documented).

That one is definitely not private. Though breaking changes aren't a problem there since we can be more liberal with version bumps.

[oliviertassinari]

That one is definitely not private.

@eps1lon I think that it's up to us to decide what's public and what's private. We could very say it's private, as long as we didn't document it. The only exception would be the barrel index of @material-ui/core that we have repeatedly committed, in the past, to considering public if exported.

---

@NMinhNguyen Ok, so that was for the current state of affair, regarding the target we should have. I think that we should make modules public based on the value it can potentially bring to users. We have on the verge of a v5, so we will be able to make plenty of BCs anyway.

I would propose the following public modules

• capitalize
• createSvgIcon
• deprecatedPropType
• unsupportedProp
• useForkRef
• useEventCallback
• useControlled
• isMuiElement
• @material-ui/utils
• ownerWindow
• debounce
• ownerDocument

Which leaves us with these modules private

• useIsFocusVisible
• setRef
• scrollLeft
• createChainedFunction
• getScrollbarSize