[docs] Create more hooks demos

[michaldudak]

Base UI hooks are not described well in the docs. Most of the demos showcase components.
We need to demonstrate how hooks' parameters affect their functionality.

We need to figure out the best way to display them - either show both component and hook demos one above the other or add a toggle that would allow readers to switch between component and hook demos. @danilo-leal, @samuelsycamore, what do you think?

[danilo-leal]

It'd be awesome if there was a way to do that visually! I initially thought about something similar to Joy UI's playground ⎯ would that work? Or @zanivan & I could come up with custom images to demonstrate this somehow?! Let us know once there's an example to kick it off with!

[mnajdova]

We could likely improve the props preview, to show the most important part of the demo - the usage of the prop. cc @siriwatknp

[samuelsycamore]

I would be hesitant to introduce any more toggles/options to the existing demos—between CSS flavors, JS/TS, and all the different ways to view and edit the source, it would get overwhelming. But in general I agree that the hooks need to be documented better. Most of the hook content is just generic boilerplate text explaining why you'd want to use it.

The Switch has nice "basic" and "customized" examples in its Hook section, and it'd be nice to have comparable examples for all of the other hooks. (The Badge has no such demos.) That might be a good place to start.

But we also need to figure out how to share both component and hook demos in the Customization sections of the docs. That part is tricky and I'm not sure what the best solution would be! It seems to me that a toggle (as I mentioned) would just be adding too many options, but having two demos back-to-back in each section doesn't sound great either.

[danilo-leal]

For what it's worth, I was thinking of something similar to the Playground demos on Joy UI, which do not display the demo toolbar controls. But, assuming the component vs. hook implementation doesn't have any visual diff, something similar to that wouldn't be as useful. Then, it'd indeed make sense to have a toggle on the demo toolbar for toggling the code snippet with component and hook options (and definitely wouldn't have the CSS menu in this case).

[michaldudak]

Now that hooks are more of an escape hatch, I think we don't need separate demos for them. Perhaps one page explaining the concept and showing a few examples would be enough?

cc @colmtuite

[colmtuite]

Now that hooks are more of an escape hatch, I think we don't need separate demos for them.

Agreed @michaldudak . Demos would be nice eventually, but not at all a priority right now. I don't think we should even focus on creating a hooks page yet. The components should be the entry point for 95%+ of users, so we can just focus on those for now.

[michaldudak]

We decided not to expose (and document) hooks for now and focus solely on components, as the component-per-node pattern offers a higher degree of customizability. We may get back to it in a future release.