Merge pull request #269 from rescript-association/rr-style-docs

rescript-react style 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,205 @@
+---
+title: Styling
+description: "Styling in ReScript & React"
+canonical: "/docs/react/latest/styling"
+---
+
+# Styling
+
+React comes with builtin support for inline styles, but there are also a number of third party libraries for styling React components. You might be comfortable with a specific setup, like:
+
+- Global CSS / CSS modules
+- CSS utility libraries (`tailwindcss`, `tachyons`, `bootstrap` etc.)
+- CSS-in-JS (`styled-components`, `emotion`, etc.)
+
+If they work in JS then they almost certainly work in ReScript. In the next few sections, we've shared some ideas for working with popular libraries. If you're interested in working with one you don't see here, search the [package index](https://rescript-lang.org/packages) or post in [the forum](https://forum.rescript-lang.org).
+
+
+## Inline Styles
+
+This is the most basic form of styling, coming straight from the 90ies. You can apply a `style` attribute to any DOM element with our `ReactDOM.Style.make` API:
+
+```res
+<div style={ReactDOM.Style.make(~color="#444444", ~fontSize="68px", ())} />
+```
+
+It's a [labeled](/docs/manual/latest/function#labeled-arguments) (therefore typed) function call that maps to the familiar style object `{color: '#444444', fontSize: '68px'}`. For every CSS attribute in the CSS specfication, there is a camelCased label in our `make` function.
+
+**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:
+
+```res
+let style =
+  ReactDOM.Style.make(
+    ~color="red",
+    ~padding="10px",
+    (),
+  )->ReactDOM.Style.unsafeAddProp("-webkit-animation-name", "moveit")
+```
+
+## Global CSS
+
+Use a `%%raw` expression to import CSS files within your ReScript / React component code:
+
+```rescript
+// in a CommonJS setup
+%%raw("require('./styles/main.css')")
+
+// or with ES6
+%%raw("import './styles/main.css'")
+```
+
+## CSS Modules
+
+[CSS modules](https://github.com/css-modules/css-modules) can be imported like any other JS module. The imported value is a JS object, with attributes equivalent to each classname defined in the 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 as a JS object: 
+
+```res
+// {..} means we are handling a JS object with an unknown
+// set of attributes
+@module external styles: {..} = "./styles.module.css"
+
+// Use the obj["key"] syntax to access any classname within our object
+let app = <div className={styles["root"]} />
+```
+
+**Note:** `{..}` is an open [JS object type](/docs/manual/latest/object#type-declaration), 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 your 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
+
+There's no way we could recommend a definitive CSS-in-JS workflow, since there are many different approaches on how to bind to CSS-in-JS libraries (going from simple to very advanced).
+
+For demonstration purposes, let's create some 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 rawCss: string => 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 `emotion`'s apis. Here's how you'd use them in your app code:
+
+```res
+let container = Emotion.css({
+  "color": "#fff",
+  "backgroundColor": "red"
+})
+
+let app = <div className={container} />
+```
+
+You can also use submodules to organize your styles more easily:
+
+```res
+module Styles = {
+  open Emotion
+  let container = css({
+    "color": "#fff",
+    "backgroundColor": "red"
+  })
+  // your other declarations
+}
+
+let app = <div className={Styles.container} />
+```
+
+Please note that this approach will not check for invalid 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 container = ReactDOM.Style.make(~padding="20px", ())->css;
+
+let app = <div
+  className={container}
+/>
+```
+
+Here we used the already existing `React.Style.t` type to enforce valid CSS attribute names. 
+Last but not least, you can also bind to functions that let you use raw CSS directly:
+
+```res
+let container = Emotion.rawCss(`
+  color: #fff;
+  background-color: red;
+`)
+
+let app = <div className={container} />
+```
+
+Please keep in mind that there's a spectrum on how type-safe an API can be (while being more / less complex to handle), so choose a solution that fits to your team's needs.

src/common/App.js

@@ -9,6 +9,7 @@
 %%raw(`
   let hljs = require('highlight.js/lib/core');
   let js = require('highlight.js/lib/languages/javascript');
+  let css = require('highlight.js/lib/languages/css');
   let ocaml = require('highlight.js/lib/languages/ocaml');
   let reason = require('plugins/reason-highlightjs');
   let rescript = require('plugins/rescript-highlightjs');
@@ -21,6 +22,7 @@
   hljs.registerLanguage('reason', reason);
   hljs.registerLanguage('rescript', rescript);
   hljs.registerLanguage('javascript', js);
+  hljs.registerLanguage('css', css);
   hljs.registerLanguage('ts', js);
   hljs.registerLanguage('ocaml', ocaml);
   hljs.registerLanguage('sh', bash);