VDOM properties documentation

[natevw]

This is a rough (but potentially publishable??) start on documenting Preact's props handling. (some background/context)

For the most part I think this documentation is non-controversial, I struggled in many cases speaking "on Preact's behalf" while writing this out:

• what's officially considered "public API" vs. implementation detail
• what's technically the domain of Preact core vs. compat vs. JSX/htm/VDOM
• and what Preact claims for itself vs. simply will always try to follow "same as whatever React documents"

…in the end though, I mostly just stuck to a bit higher level in general which left room for handwavey summaries anyway.

I also struggled a bit just with general terminology. Are these really "VDOM" properties, or are they "component" properties? (React sort of documents "built-in components" as if it had simply entirely subsumed them into its own framework….) Again, handwavey was my friend but would like to avoid any egregious discrepancies to how the rest of the docs tend to discuss the various distinctions.

How close is this to a "good enough" starting point that could be published?

[rschristian]

This is brilliant, and something a few users have been asking about for a long while! Thank you so much for writing it! We really appreciate it.

One thing that's missing is perhaps the preference for properties, as Jason mentioned (if (name in domElement), etc). That's something we should probably note, maybe with a little asterisk for the handful of exceptions (you don't have to explicitly list them out).

I'm also a bit apprehensive about having a doc filled with so many links to PRs. I love backing references, that's great, but as you've probably noted things are moving re:v11 and generally we try to contain all information here rather than having users piece it together from external sources. Will have a think on it though.