Improve arrays-and-keys, components-and-props, introduction and rendering-elements

Author: ryyppy

pages/docs/react/latest/arrays-and-keys.mdx

@@ -15,7 +15,7 @@ Whenever we are transforming data into an array of elements and put it in our Re
 
 ## Keys & Rendering Arrays
 
-Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside the array to give the elements a stable identity:
+Keys help React identify which elements have been changed, added, or removed throughout each render. Keys should be given to elements inside the array to give the elements a stable identity:
 
 ```res
 let numbers = [1, 2, 3, 4, 5];
@@ -40,7 +40,7 @@ let items = Belt.Array.map(todos, todo => {
 })
 ```
 
-When you don’t have stable IDs for rendered items, you may use the item index as a key as a last resort:
+If you don’t have stable IDs for rendered items, you may use the item index as a key as a last resort:
 
 ```res {2,3}
 let items = Belt.Array.mapWithIndex(todos, (todo, i) => {
@@ -119,5 +119,7 @@ let items =
 <div> {React.array(items)} </div>
 ```
 
-We used `Belt.List.toArray` to convert our list to an array before creating our `array<React.element>`. Please note that using `list` has a performance impact due to extra conversion costs.
+We use `Belt.List.toArray` to convert our list to an array before creating our `array<React.element>`. Please note that using `list` has performance impact due to extra conversion costs.
+
+In 99% you'll want to use arrays (seamless interop, faster JS code), but in some cases it might make sense to use a `list` to leverage advanced pattern matching features etc.
 

pages/docs/react/latest/components-and-props.mdx

@@ -143,7 +143,13 @@ var greeting = React.createElement(Playground$Greeting, tmp);
 
 </CodeTab>
 
-### Children Props
+### Special Props `key` and `ref`
+
+You can't define any props called `key` or `ref`. React treats those props differently and the compiler will will yield an error whenever you try to define a `~key` or `~ref` argument in your component function.
+
+Check out the corresponding [Arrays and Keys](./arrays-and-keys) and [Forwarding React Refs](./forwarding-refs) sections for more details.
+
+## Children Props
 
 In React `props.children` is a special attribute to represent the nested elements within a parent element:
 
@@ -250,17 +256,18 @@ module NoChildren = {
 <NoChildren> <div/> </NoChildren>
 ```
 
-Children props are really tempting to be abused as a way to model hierarchies, e.g. `<List> <ListHeader/> <Item/> </List>` (`List` should only allow `Item` / `ListHeader` elements), but this kind of constraint is hard to enforce because all components end up being `React.element`, so it would require notorious runtime checking within `List` to verify that all children are in fact of type `Item` or `ListHeader`.
+Children props are really tempting to be abused as a way to model hierarchies, e.g. `<List> <ListHeader/> <Item/> </List>` (`List` should only allow `Item` / `ListHeader` elements), but this kind of constraint is hard to enforce because all components end up being a `React.element`, so it would require notorious runtime checking within `List` to verify that all children are in fact of type `Item` or `ListHeader`.
 
-The best way to approach this kind of issue is by using props instead of children, e.g. `<List header="..." items=[{id: "...", text: "..."}]/>`. This way it's easy to type check the constraints, and also spares us many hours debugging and remembering component constraints.
+The best way to approach this kind of issue is by using props instead of children, e.g. `<List header="..." items=[{id: "...", text: "..."}]/>`. This way it's easy to type check the constraints, and it also spares component consumers from memorizing and remembering component constraints.
 
-**The best use-case for `children` is to pass down `React.element`s, no matter what kind of elements they are!**
+**The best use-case for `children` is to pass down `React.element`s without any semantic order or implementation details!**
 
 
+## Props & Type Inference
 
-### Type Inference
+The ReScript type system is really good at inferring the prop types just by looking at its prop usage. 
 
-The ReScript type system excels at computing the actual prop types through usage. We recommend to explicitly type your props (especially for exported components) to help your coworkers understand the types. For simple cases or experimentation, it's still fine to omit them:
+For simple cases, well-scoped usage, or experimentation, it's still fine to omit type annotations:
 
 
 ```res
@@ -275,8 +282,9 @@ let make = (~onClick, ~msg, ~children) => {
 }
 ```
 
-In the example above, `onClick` will be inferred as `ReactEvent.Mouse.t => unit`, `msg` as `string` and `children` as `React.element`. Type inference is very useful to ommit a lot of annoying type annotations, especially for private functions that pass around values to other functions.
+In the example above, `onClick` will be inferred as `ReactEvent.Mouse.t => unit`, `msg` as `string` and `children` as `React.element`. Type inference is especially useful when you just forward values to some smaller (privately scoped) functions.
 
+Even tough type inference spares us a lot of keyboard typing, we still recommend to explicitly type your props (just like with any public API) for better type visibility and to prevent confusing type errors.
 
 ## Using Components in JSX
 
@@ -309,6 +317,8 @@ var make = App;
 
 **Note:** React components are capitalized; primitive DOM elements like `div` or `button` are uncapitalized. More infos on the JSX specifics and code transformations can be found in our [JSX section](/docs/manual/latest/jsx#capitalized-tag) in our language manual.
 
+More details on the `@react.component` decorator and its generated interface can be found in our [Advanced React JSX Transformation](./react-jsx-transformation) page.
+
 
 ## Submodule Components
 

pages/docs/react/latest/introduction.mdx

@@ -11,6 +11,8 @@ ReScript offers first class bindings for [ReactJS](https://reactjs.org) and are
 
 The ReScript philosophy is to compile as closely to idiomatic JS code as possible; in case of ReactJS we made no exception, so it's not only easy to transfer all the React knowledge to the ReScript platform, but also straightorward to integrate with existing ReactJS codebases and libraries.
 
+All our documentated examples can be compiled in our [ReScript Playground](/try) as well.
+
 > **This documentation assumes basic knowledge about ReactJS.**
 >
 > Please note that even though we will cover many basic React concepts, it might still be necessary to have a look at the official [ReactJS](https://reactjs.org) resources, especially if you are a complete beginner with React.

pages/docs/react/latest/rendering-elements.mdx

@@ -123,28 +123,28 @@ React.createElement("div", undefined, element);
 
 </CodeTab>
 
-
-### Clone Elements
+## Cloning Elements
 
 **Note:** This is an escape hatch feature and will only be useful for interoping with existing JS code / libraries.
 
-Sometimes it's required to clone an existing element to set overwrite prop values or add props to a new instance. You can use `React.cloneElement` for that: 
+Sometimes it's required to clone an existing element to set, overwrite or add prop values to a new instance, or if you want to set invalid prop names such as `data-name`. You can use `React.cloneElement` for that: 
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
 ```res
 let original = <div className="hello"/>
 
 // Will return a new React.element with className set to "world"
-React.cloneElement(original, {"className": "world"});
+React.cloneElement(original, {"className": "world", "data-name": "some name"});
 ```
 ```js
 var original = React.createElement("div", {
       className: "hello"
     });
 
 React.cloneElement(original, {
-      className: "world"
+      className: "world",
+      "data-name": "some name"
     });
 ```
 
@@ -154,7 +154,6 @@ The feature mentioned above could also replicate `props spreading`, a practise c
 
 In ReScript, we rather pass down required props explicitly to leaf components or use a renderProp instead. We introduced [JSX punning](/docs/manual/latest/jsx#punning) syntax to make the process of passing down props more convenient.
 
-
 ## Using Elements within JSX
 
 You can compose elements into more complex structures by using JSX: