SelectNext: Refine documentation

[acelaya]

Originally posted in #1330 (review)

• At the top the component is described as a presentational component. I don't think that's really accurate any more. It isn't just styling around a native <select>.
• There is an example near the top that shows what it looks like, but there is no code view
• Underneath that is a "Working with SelectNext" section that references SelectNext.Option but at this point of reading through the page, there has been no explanation or demonstration of what an Option is or what the code structure looks like.
• explain how it differs from a <select>, as well as linking to the accessibility patterns it implements, specifically the Select-only Combobox Add props to SelectNext to granularly pass classess #1369 (comment)

[robertknight]

Related to this, the switches to toggle between UI preview and code are missing from all the examples, as we have for other components.

Docs: https://patterns.hypothes.is/input-select-next

SelectNext example:

Compare with the old Select (note switch button on the right):

[acelaya]

Related to this, the switches to toggle between UI preview and code are missing from all the examples, as we have for other components.

Yeah, I skipped those intentionally, because of the way <Library.Demo /> generates the preview based on its actual children.

If you use a helper wrapper components that allow you to use local state handling, the preview ends up looking like this, which is not very useful:

with-source-2024-05-08_14.00.09.mp4

We have a way to kind-of work around that, by using a helper component which has the same name as the one documented, but with an underscore, but I reckon I was not able to put something useful enough together here, as the state management itself is important and cannot be documented this way.

We could manually write code snippets using <Library.Code />, but they can quickly get outdated, and they cannot be linted, type-checked and formatted, risking human mistakes.

Some time ago we discussed the possibility of using individual source files that could be "embedded" in the docs with syntax highlight, while being type-checked and linted like the rest of the code. Maybe we can go back to that at some point.