[RFC] Root components expose a `public state interface`

[KingSora]

Feature request

Good day! First of all I'm a huge fan of this project. I've build and used many UI libraries in the past and I'm impressed about the consistency and general effort put into BaseUI. That being said, I'm missing a (in my opinion) quite important feature which I think would elevate the quality and DX of BaseUI even more.

Every component has its Root which manages and holds the internal state of the whole component. I'll use the Dialog component as the main example going forward.

Currently the basic example for the dialog component is as follows:

<Dialog.Root>
  <Dialog.Trigger>
    Open Dialog
  </Dialog.Trigger>
  // ...
</Dialog.Root>

This markup is nice and clear, but it limits the developer to use the Dialog.Trigger as the element which opens the dialog. This limitation can be quite annoying in real world applications, because this limitation seems to have no benefit, because one could also do this:

const [open, setOpen] = useState(false);

<Dialog.Root open={open} onOpenChange={setOpen}>
  <button onClick={() => setOpen(true)}>
    Open Dialog
  </button>
  // ...
</Dialog.Root>

Image in this case the button element to be a custom element which should open the dialog. As you can see, for this approach you need quite a bit of additional code because in order to achieve that you have to make the dialog root controlled, so you can manage the state yourself. In this simple case this is quite annoying because the controlled state is essentially doing the exact same thing what the uncontrolled state is doing.

The idea is now to introduce a possibility to make this need of making this controlled state obsolete:

<Dialog.Root>
  {({ open, setOpen }) => <>
    <button onClick={() => setOpen(true)}>
      Open Dialog
    </button>
    // ...
  </>}
</Dialog.Root>

The Dialog.Root components children prop can be a function, which receives childrenProps. These children props contain internal state information and their setters. That children props object can be thought of a public state interface which represents the whole state of the component + its setters. It could (and should) not only be exposed via children props but also via a context which would even more increase DX in the case when components are nested over multiple layers.

Now you might think that all of this is pointless, because why not just use the render prop of the Dialog.Trigger component, and there are multiple reasons:

1. In real world application a single button can do different things depending on the application state. For example if the user is logged in the button should do actionA while when logged out the button should do actionB, where any action could be a modal to be opened or something entierly different.
2. BaseUI is an "abstraction" of a UI library and each adpoter can descide how to use the building blocks how every he / she sees fit. The addition of this feature would open up new patterns & lift restrictions which aren't needed.

Summary

• All Root components define a public state interface which consists of one or multiple state values + their setters if it makes sense and no harm. Those values should be picked carefully.
• The children prop of Root components accepts not only ReactNode as its value but also a function with the interface (publicStateInterface) => ReactNode, so the state can be accessed directly in the children.
• In nested components the public state interface can be accessed via a hook which behaves like useContext, this can be either something like const { open, setOpen } = Dialog.Root.useContext() or a separate export like const { open, setOpen } = useDialogRoot().
• Root components have a ref prop which exposes the public state interface as a way of controlling the component imperatively. (thats just a nice to have)

Examples in other libraries

I'm using this pattern in my own UI library, headlessUI and react-aria, are using this pattern as well (its a little bit inconsitent in headlessUI).

Motivation

In my opinion not having this feature is limiting DX greatly and BaseUI adopters are bound to restrictions which dont serve any benefit (please correct me if I'm wrong in this aspect).

If this is something BaseUI wants to implement, I would be ready to help with the implementation & make a PR.

[atomiks]

Some concerns with this API:

1. The render prop allows you to replace Dialog.Trigger with your own button, which seems to mostly address your concern here? You won't need controlled state if you can use your own button (<Dialog.Trigger render={<MyButton />} />)
2. If the button is rendered outside of the Dialog's React tree (in another component or far away, which could be common) this API doesn't work while controlled mode does. I think for consistency, even if it's a bit more verbose, controlled mode works in more scenarios and it's better to restrict this to one unified API

[KingSora]

@atomiks Thanks for the reply! :)

The render prop allows you to replace Dialog.Trigger with your own button, which seems to mostly address your concern here? You won't need controlled state if you can use your own button (<Dialog.Trigger render={<MyButton />} />)

You are correct in that aspect, but I as a developer have to have the knowledge about the Dialog.Trigger (and Dialog.Close) component. Lets think about it that way: Why exactly is the Dialog.Trigger and Dialog.Close component really needed? - Whats the benefit of having it over having a function which does the same thing and is more versatile?

To me it seems like Dialog.Trigger and Dialog.Close are the same thing as the setOpen function just as components.

If the button is rendered outside of the Dialog's React tree (in another component or far away, which could be common) this API doesn't work while controlled mode does. I think for consistency, even if it's a bit more verbose, controlled mode works in more scenarios and it's better to restrict this to one unified API

Thats true, but this feature is about the exact opposite scenario. (making that case easier to implement while leaving all other options open)

Lets imagine MyDialog bellow is already a implementation of BaseUIs Dialog with styling etc. applied.

const [open, setOpen] = useState(false);
<>
  <MyDialog open={open} onClose={() => setOpen(false)}>
    This is my dialogs content
  </MyDialog>
  <button onClick={() => setOpen(true)}>open my dialog</button>
</>

I would say this code represents how modals are managed in many apps, even though this code is repetetive. Where would I use Dialog.Trigger in this case? I can't use it for the button because its outside of MyDialog, so I'm forced to make a controlled component here, every time.

Lets imagine a different implementation of a Dialog (again with styling applied):

const [open, setOpen] = useState(false);
<MyDialog open={open} onClose={() => setOpen(false)} content={<>This is my dialogs content</>}>
  <button>open my dialog</button>
</MyDialog>

This is a different pattern, but here I would be able to use the Dialog.Trigger component, since MyDialog doesn't directly represent the dialogs content, but a boundary which makes the dialog available to its children. The problem here is that in order to make this more convenient, I have to know about the Dialog.Trigger component which has to be imported or used somehow, which again limits me as a dev because I have to choose a component to make an action.

Lets imagine the last implementation:

<MyDialog content={<>This is my dialogs content</>}>
  {({ open, setOpen }) => <button onClick={() => setOpen(true)}>open my dialog</button>}
</MyDialog>

Here I don't need to know about anyhting special. I just have a Dialog, which exposes state which can be used. I can use my button or any other dom element without any special API, wrapping, props or anythign else.

If I need it, I still can make the dialog controlled, but in case I just want a dialog with a button, this is the smallest possible sufrace one can get.

---

I know that MyDialog internally could make the Dialog.Root controlled and expose all of that children state by itself, but thats the point I'm making. BaseUI currently makes certain implementation / style far easier to implement then another, but it doesn't and shouldn't have to do that.

[michaldudak]

Why exactly is the Dialog.Trigger and Dialog.Close component really needed? - Whats the benefit of having it over having a function which does the same thing and is more versatile?

The main reason these are components (besides convenience) is accessibility. For example, the Dialog.Trigger sets the aria-haspopup, aria-expanded and aria-controls attributes.

[KingSora]

@michaldudak I see, thanks for the insight! But if I'm getting this right you also would lose those a11y attributes if you would make the Dialog controlled and changing the open state via the setState function.

[michaldudak]

Yes, that's right. That's why we recommend to use the components we provide.

[KingSora]

Yes, that's right. That's why we recommend to use the components we provide.

I didn't find any mention about this recommendation in the docs for any of the components BaseUI provides. Many of the examples for components which can be "opened" just show the ever repeating pattern of controlled state: dialog, nested dialog, menu.

So I would say the usage of the Trigger and Close components is encouraged and preferred (for example if the button functionality is know up-front and doesn't change with the application state) but in real world applications a defined public state interface which would expose functions in addition to the components would enhance flexibility and DX.

[michaldudak]

FYI, we're exploring using standalone triggers (that don't have to be under the Root part). There's a POC for the Dialog: #2283, and we're going to work on other popups as well.
This should cover at least some of the concerns you voiced in this issue.