[data grid] Improve "Save and restore the state from external storage" demo about mui-x HOT 12 OPEN

@Janpot What do you think about moving the useStorageStateBrowser hook to @mui/utils?
I think we have many utility hooks we use internally that our users could use.
We can create a separate package and docs for these hooks - e.g. @mui/hooks.

This could also be an initiative under the MUI X product line - @mui/x-hooks with more advanced utility hooks like useStorageStateBrowser, useResizeObserver, useTimeout, useFirstRender, useOnMount, etc.

cc @joserodolfofreitas @oliviertassinari @mui/x

from mui-x.

For inspiration: In Toolpad we wrote a hook that handles initializing state from localstorage on the first render correctly (i.e. doesn't need an effect to run). It also syncs this state across tabs.

from mui-x.

Yes, I'll clean it up a bit and move to @mui/utils 👍

from mui-x.

To be noted that @mui/utils is a "private" npm package. Only MUI System and Base UI are supposed to import from it. This package exists so that MUI System doesn't have a dependency on Base UI but still able to use some of its logic to create components.

Just to note that this example is promoting @mui/utils as a public package. (This is why we have it as a dependency in Toolpad, I never knew it wasn't meant to be public)

Other places where @mui/utils seems to be endorsed in the docs as a public package:

• visuallyHidden https://mui.com/material-ui/icons/#semantic-icons
• visuallyHidden https://mui.com/material-ui/migration/v5-component-changes/#remove-sronly-variant
• unstable_useForkRef https://mui.com/base-ui/react-autocomplete/#using-a-portal (promoting an unstable_ export on an internal package 🙂 )

IMO, the @mui/utils package is already de facto public. It would make more sense to mark everything in the package as unstable_ to signal to consumers that it's not following semver guarantees. It's more effective than documenting it in the docs or README, at least you notice it when vscode autoimports something from the @mui/utils package.

from mui-x.

I don't think making it public is a good idea. The code in there is internal code that we need to share across our packages/repos, not code we want the public to consume. I think we should either clearly mark it as a private package or create a new one with a name like @mui/internals. Then there is no issue with removing the unstable_ prefix and making breaking changes to the code, because it's an internal-only package. There is also nothing that prevents us from uncoupling the version number from the core's versionning scheme if we introduce breaking changes.

What would prevent us from following semver?

Nothing prevents us, it just adds overhead. It needs to be properly maintained, backwards compatibility needs to be guaranteed more tightly, and it needs to be documented.

I don't think semver implies we need to do all that. If it's an internal package we can have a meaningful (semver) version number while also not documenting it. Following semver doesn't imply we make the package public. We could also just leave it at version 0.x, which semver defines as basically "do anything you want" (point 4 of semver).

from mui-x.

Other places where @mui/utils seems to be endorsed in the docs as a public package:

@Janpot Yes, it's not great, this work was never prioritized.

The shaping page that centralizes the discussions on this topic: https://www.notion.so/mui-org/mui-utils-purpose-9a9fc9da3a004864b6c4e1f4d1f24f95.

from mui-x.

I ported the hook to @mui/utils. For now with the purpose to only use it internally. If anyone has objections to this, please comment on the PR.

To build save/store grid state on top of this, it will need to be wrapped with parsing/serialization/validation logic. The hook doesn't mean to be opinionated about parsing, error handling and migrating stored values.

from mui-x.

To be noted that @mui/utils is a "private" npm package. Only MUI System and Base UI are supposed to import from it.

This package exists so that MUI System doesn't have a dependency on Base UI (would be weird, and isolate download npm stats) but still able to use some of its logic to create components.

from mui-x.

We did not close the discussion about MUI X using it

from mui-x.

To be noted that @mui/utils is a "private" npm package. Only MUI System and Base UI are supposed to import from it. This package exists so that MUI System doesn't have a dependency on Base UI but still able to use some of its logic to create components.

Just to note that this example is promoting @mui/utils as a public package. (This is why we have it as a dependency in Toolpad, I never knew it wasn't meant to be public)

Other places where @mui/utils seems to be endorsed in the docs as a public package:

• visuallyHidden https://mui.com/material-ui/icons/#semantic-icons
• visuallyHidden https://mui.com/material-ui/migration/v5-component-changes/#remove-sronly-variant
• unstable_useForkRef https://mui.com/base-ui/react-autocomplete/#using-a-portal (promoting an unstable_ export on an internal package 🙂 )

IMO, the @mui/utils package is already de facto public. It would make more sense to mark everything in the package as unstable_ to signal to consumers that it's not following semver guarantees. It's more effective than documenting it in the docs or README, at least you notice it when vscode autoimports something from the @mui/utils package.

What would prevent us from following semver? Couldn't we make this public and follow best practices as well?

from mui-x.

What would prevent us from following semver?

Nothing prevents us, it just adds overhead. It needs to be properly maintained, backwards compatibility needs to be guaranteed more tightly, and it needs to be documented.

edit: To be clear, I interpreted the question as "what prevents us from treating @mui/utils as an officially supported MUI product?".

from mui-x.

I think we should either clearly mark it as a private package or create a new one with a name like @mui/internals.

@romgrk this makes sense to me. Essentially have 2 packages,@mui/internals which is mostly what is currently in the utils, and @mui/utils which is public and contains things like useStorageStateBrowser from Toolpad. I can see us adding more relevant utils for our users there, we are probably going to encounter some cases when we ship the data grid server-side integration (transformers, adaptors, etc.)

from mui-x.