Add styling section to rescript-react docs

Author: ryyppy

data/sidebar_react_latest.json

@@ -11,6 +11,7 @@
     "arrays-and-keys",
     "refs-and-the-dom",
     "context",
+    "styling",
     "router"
   ],
   "Hooks & State Management": [

pages/docs/react/latest/styling.mdx

@@ -0,0 +1,170 @@
+---
+title: Styling
+description: "Styling in ReScript & React"
+canonical: "/docs/react/latest/styling"
+---
+
+# Styling
+
+There are many different approaches on how to do styling in React, such as:
+
+- Inline Styles (`style=...`)
+- Global CSS / CSS modules
+- CSS utility libraries (`tailwindcss`, `tachyons`, etc.)
+- CSS-in-JS (such as `styled-components`, `emotion`, etc.)
+
+## Inline Styles
+
+You can apply a `style` attribute to any DOM element with our `ReactDOM.Style.make` API:
+
+```rescript
+<div style=(
+  ReactDOM.Style.make(~color="#444444", ~fontSize="68px", ())
+)/>
+```
+
+It's a labeled (typed!) function call that maps to the familiar style object `{color: '#444444', fontSize: '68px'}`.
+
+**Note** that `make` returns an opaque `ReactDOM.Style.t` type that you can't read into. We also expose a `ReactDOM.Style.combine` that takes in two `style`s and combine them.
+
+### Escape Hatch: `unsafeAddProp`
+
+The above `Style.make` API will safely type check every style field! However, we might have missed some more esoteric fields. If that's the case, the type system will tell you that the field you're trying to add doesn't exist. To remediate this, we're exposing a `ReactDOM.Style.unsafeAddProp` to dangerously add a field to a style:
+
+```reason
+let myStyle = ReactDOM.Style.make(~color="#444444", ~fontSize="68px", ());
+
+## Global CSS
+
+Use a `%%raw()` expression to import CSS files within your ReScript / React component code:
+
+```rescript
+%%raw("require('./styles/main.css')")
+
+// or with ES6
+%%raw("import './styles/main.css'")
+```
+
+## CSS Modules
+
+CSS modules can be imported like any other JS module. The imported value is a JS object, with each key mapping to a classname within the imported CSS file.
+
+As an example, let's say we have a CSS module like this:
+
+```css
+/* styles.module.css */
+
+.root {
+  color: red
+}
+```
+
+We now need to create a module binding that imports our styles: 
+
+```res
+// {..} means we are handling a JS object with an unknown
+// set of attributes
+@module external styles: {..} = "./styles.module.css"
+
+let app = <div className={styles["root"]} />
+```
+
+**Note:** `{..}` is an open JS object type, which means the type checker will not type check correct classname usage. If you want to enforce compiler errors, replace `{..}` with a concrete JS object type, such as `{"root": string}`.
+
+
+## CSS Utility Libraries
+
+### Tailwind
+
+
+CSS utility libraries like [TailwindCSS](https://tailwindcss.com) usually require some globally imported CSS.
+
+First, create your TailwindCSS main entrypoint file:
+
+```css
+/* main.css */
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Then, import your `main.css` file in your ReScript / React application:
+
+```res
+// src/App.res
+
+%%raw("import './main.css'")
+```
+
+Utilize ReScript's pattern matching and string interpolations to combine different classnames:
+
+```res
+@react.component
+let make = (~active: bool) => {
+  let activeClass = if active {
+    "text-green-600"
+  }
+  else {
+    "text-red-600"
+  }
+
+  <div className={`border-1 border-black ${activeClass}`}>
+    {React.string("Hello World")}
+  </div>
+}
+```
+
+When using the [Tailwind VSCode plugin](https://tailwindcss.com/docs/intellisense), make sure to include ReScript as a target language to get autocompletion:
+
+- Open the VSCode settings
+- Search for `Tailwind CSS: Include Languages`
+- Add a new item with following settings:
+  - Item: `rescript`
+  - Value: `html`
+
+
+> **Hint:** `rescript-lang.org` actually uses TailwindCSS under the hood! Check out our [codebase](https://github.com/rescript-association/rescript-lang.org) to get some more inspiration on usage patterns.
+
+
+## CSS-in-JS
+
+Currently there are no official recommendations for CSS-in-JS yet due to the wildly different approaches on how to bind to CSS-in-JS (going from simple to very advanced).
+
+The most minimalistic approach is to create simple bindings to e.g. [`emotion`](https://emotion.sh/docs/introduction) (as described [here](https://github.com/bloodyowl/rescript-react-starter-kit/blob/eca7055c59ba578b2d1994fc928d8f541a423e74/src/shared/Emotion.res)):
+
+```res
+// src/Emotion.res
+
+@module("@emotion/css") external css: {..} => string = "css"
+@module("@emotion/css") external keyframes: {..} => string = "css"
+@module("@emotion/css") external cx: array<string> => string = "cx"
+
+@module("@emotion/css") external injectGlobal: string => unit = "injectGlobal"
+```
+
+This will give you straight-forward access to the `emotion` apis. Here's how you'd use them in your app code:
+
+```res
+let app = <div
+  className={Emotion.css({
+    "color": "#fff",
+    "backgroundColor": "red"
+  })}
+/>
+```
+
+Please note that this approach will not be type-checking for valid css attribute names. If you e.g. want to make sure that only valid CSS attributes are being passed, you could define your `css` function like this as well:
+
+```res
+@module("@emotion/css") external css: React.Style.t => string = "css"
+
+// Usage is slightly different (and probably less ergonomic)
+let app = <div
+  className={ReactDOM.Style.make(~padding="20px", ())->css}
+/>
+```
+
+In the example above we used the already existing `React.Style.t` type to enforce valid CSS attribute names. There's a spectrum on how type-safe an API might be, so choose a solution that fits your team's needs.
+
+For more CSS-in-JS ideas, you can also check out related discussions on our [forum](https://forum.rescript-lang.org), or start a new topic.