[docs] Which package url is valid ?

loudjanilef commented 1 month ago

Kind of issue

Other

Issue description

If we look in the readme and click on the npm badge, we see that the npm package is @base_ui/react. The latest version for this package is v1.0.0-alpha3, which matches the release section of this project. But if we go on the website mui.com/base-ui/ tagged in the about section of the project, the displayed npm command is npm install @mui/base, same in the docs. Which one is the correct one ?

Context

I am trying to know which URL is the correct URL for and npm i command.

Search keywords: npm, url, link

flaviendelangle commented 1 month ago

I agree that this is confusing and that the current doc of @mui/base doc should be clearer on this @samuelsycamore

samuelsycamore commented 1 month ago

Thanks for raising this @loudjanilef. I agree that the current state is pretty confusing. The Overview page does include this warning callout:

Base UI's API is currently being revised; there will be no new features or components added to the current implementation. Learn more about plans for Base UI in this blog post.

But this could be a lot more prominent and a lot more clear now that there are two npm packages out there. And it should probably be repeated in the Quickstart guide.

What if we moved the callout to the top of both pages and revised it like this:

This documentation describes how to work with the @mui/base package. The Base UI API is currently being revised and will soon be released as @base_ui/react with a new set of docs. There will be no new features or components added to @mui/base, and we will announce when the new package is ready to migrate to. Learn more about plans for Base UI in this blog post.

Would that make things more clear? cc @colmtuite

samuelsycamore commented 1 month ago

Also, I just realized that the blog post linked in that callout doesn't exactly provide more details on the packages and such. Should we update that post to explain the latest state of things? (Could just be a few sentences at the end to address the confusion described here.)

flaviendelangle commented 1 month ago

One could say that the callout should even be on every single page of the @mui/base doc It's very easy to reach a component page like this one with Google and start using @mui/base without knowing the consequences:

michaldudak commented 1 month ago

We will add a callout once we have the new docs published. We currently don't have anything to point folks to from the old docs.

samuelsycamore commented 1 month ago

We currently don't have anything to point folks to from the old docs.

Still, it would be nice to at least provide more context for folks who may be confused by the two competing npm packages, don't you think?

colmtuite commented 1 month ago

Would that make things more clear? cc @colmtuite

I'm not sure, I don't think so? @flaviendelangle is correct that the callout should be on every page, and it will be. But right now, anything can change. For example, the new npm package can (and almost certainly will) change. We're too early to start mentioning the new package or linking people to new docs. So there's nothing to do here at this point.

@loudjanilef To answer your question, there is no "correct one", best to think of them as two different libs. This project is not released yet, and has no docs, so it's not ready to use just yet. Soon though!

cc @samuelsycamore

loudjanilef commented 1 month ago

Thank you for this information 🙏 Maybe you could write that the package is not ready yet on every documentation page until you have a link to the new package and docs ?

samuelsycamore commented 1 month ago

Maybe you could write that the package is not ready yet on every documentation page until you have a link to the new package and docs ?

Sounds like maybe there's still some confusion here:

The documentation at https://mui.com/base-ui/getting-started/ covers the @mui/base package, which is the older implementation of Base UI that lives in the mui/material repo. You can use this package right now if you'd like.
This repo (mui/base-ui) hosts the newer @base_ui/react package, which is still in the early days of development and has no published documentation. It is possible to tinker with this package today, but we wouldn't generally recommend it for use at this time.

Does that make sense?

I agree that the @mui/base docs should draw attention to the current state of things more prominently, but I'll defer to @colmtuite @michaldudak and the other Base UI maintainers to decide when it's time to proceed with that.

mui / base-ui