Docs feedback

For components that have an onOpenChange() callback prop, that prop's types are inaccurate. The documentation site says that onOpenChange has this signature:

onOpenChange?: (
    open: boolean,
    event?: Event | undefined,
    reason?: PopoverOpenChangeReason | undefined,
) => void;

... but the exported type has this signature:

onOpenChange?: (
    open: boolean,
    event: Event | undefined,
    reason: PopoverOpenChangeReason | undefined,
) => void;

In the exported type, event and reason params are required; on the docs page, they are optional.

At the same time, a ~~legacy~~ typedef in the code looks like this:

 /**
   * Event handler called when the popover is opened or closed.
   * @type (open: boolean, event?: Event, reason?: Popover.Root.OpenChangeReason) => void
   */

How can we improve Base UI documentation?

Ensuring that onOpenChange's exported types match the documentation site would be a huge help! Based on my understanding, the documentation site is accurate, but the exported types are not.

I would be happy to implement a fix for this if maintainers are interested!

The @type isn't legacy but rather a workaround to get Popover.Root.OpenChangeReason to display with the namespace as the API extractor has troubles with it

Internally, we want onOpenChange to require those two types (so we explicitly pass undefined rather than accidentally omitting an event or reason), but externally (public-facing) they should have ?: since they're fully optional

Ah, I see. Thanks for explaining!

This feature will be available in the next npm release of Base UI.

In the meantime, you can try it out on our Canary release channel:

npm i https://pkg.pr.new/@base-ui-components/react@2104