Improve documentation and evaluate features for v0.12

[WorldSEnder]

Currently, we have quite a few macros that seem to do similar, but not quite the same thing. We should think about improving the documentation to make clear which ones to use with Yew, and which ones are meant to be used framework-independently.

As I see it, ::stylist::css! and ::stylist::style! should not ever have to be used with Yew. ::stylist::global_style! is currently the only way to mount a global style. global_style! is superseded by <stylist::yew::Global> and other framework specific solutions, imo. Like the global style! macro it's not context aware, so the current usage might be questionable, but okay for most cases.

The css! injected with styled_component seems to be more-or-less superseded with hooks and use_style!.

In any case, there should be documentation for using stylist specifically with Yew, since as of now, that's the only framework we have special in-crate support for.

[futursolo]

::stylist::global_style! is currently the only way to mount a global style, but like the global style! macro it's not context aware, so the current usage might be questionable, but okay for most cases.

The context-aware way of mounting global styles is stylist::yew::Global.

The css! injected with styled_component seems to be more-or-less superseded with hooks and use_style!.

use_style! is a hook inspired by the useStyles hook from jss and material-ui.

However, although there are some users that were in favour of this API (in certain cases, myself included), the useStyles hook never took off and was eventually removed in favour of the sx(css!-like) macro in material ui v5.

Unfortunately, IMHO, I think use_style! would eventually face the same destiny.
(Although, it would require a very good reason to remove it as it's just 2 lines of code.)

The main reason that stylist still promotes both use_style and styled_component is that there isn't a good way to implement a styled API for Yew yet, so use_style fills the gap of defining reusable styles across multiple components.

I think these 2 APIs are both useful and have different use cases.

The use_style! API is more useful with UI libraries where stylesheets are usually shared between multiple components and the style_component API is designed for end applications where stylesheets are more specialised and users need quick and simply ways to override existing styles.

[WorldSEnder]

However, although there are some users that were in favour of this API, the useStyles hook never took off and was eventually removed in favour of the sx(css!-like) macro in material ui v5.

One reason I see for this is that material-ui mixes the styling and styling props on components. Since there's no clear way to doing prop inheritance and prop mixins in yew, yet, I think the focus should be on the smallest possible building block that allows to build prop-based styling solutions from it. StyleSource is good in that regard, but a missing part is overrides/combining StyleSources together.

use_style! is fine as long as you're building a single component. For user-overrides, I'd say we need to find a way to combine StyleSources together, one could get along with use_style(combine(user_style, css!(r#" ... base style ... "))). That is to say, the use_style hook function will probably survive, even if it's at some point no longer used by most users, it will still be the lower building block that grabs the context and combines it with a style source.

Another thing about the sx approach, if I understand it correctly, is that it more or less abandons direct css and replaces it with a js-land dict-style "pre-css" that then gets compiled (at runtime!) to css in the last step. Fine for a framework, but I don't really like it, personally. In any case, we should stay more-or-less non-opinionated about such approaches, as long as they can construct their Sheet in the end and we mount it.

---

Anyway, back to the topic at hand: there should be one blessed guide on how to use the library for simple hacked-together apps (per framework focus, only yew for now?) and one guide on the internals for anybody wanting to write a styling solution on top. The current README gives 3 very similar approaches, where at most one of them is probably relevant to the average user.

Reading the docs is quite the cognitive overload, since there's so many seemingly similar macros and functions doing almost the same thing. I'd like the typical user to only have to use 2 macros tops.

[WorldSEnder]

I think the YieldStyle trait can be completely removed. Besides not really targeting struct components, if something like that exists at all, it should live in the yew module and make use of the Scope::context API to offer a tangible benefit over just calling Style::new(css!("styled { ... }")) inline in the view function.

[futursolo]

Anyway, back to the topic at hand: there should be one blessed guide on how to use the library for simple hacked-together apps (per framework focus, only yew for now?) and one guide on the internals for anybody wanting to write a styling solution on top. The current README gives 3 very similar approaches, where at most one of them is probably relevant to the average user.

Reading the docs is quite the cognitive overload, since there's so many seemingly similar macros and functions doing almost the same thing. I'd like the typical user to only have to use 2 macros tops.

I guess the question becomes: where should this guide live?

Currently, the only form of documentation is docs.rs.
If we put we put the guide in docs, then users will still need to read the docs.

If you want to host the guide in some other form, then I guess we need to move forward with this alongside #21?
If you have any good domain name in mind, I am happy to pay for the bill.

I think the YieldStyle trait can be completely removed.

I agree with this move. YieldStyle was a very simple wrapper that wraps Style and the experience of it was never as good as hooks or styled_component. If someone likes this API, it's also achievable with the public API.