Skip to content

Commit

Permalink
Make sure ReScript doesn't appear hardcoded in the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
davesnx committed Nov 21, 2024
1 parent db1ea7d commit 96a8f9e
Show file tree
Hide file tree
Showing 6 changed files with 29 additions and 12 deletions.
2 changes: 1 addition & 1 deletion packages/website/site/components/language-content.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,4 @@ export function Re({ children }) {

export function Res({ children }) {
return <LanguageContent language="rescript">{children}</LanguageContent>;
}
}
8 changes: 5 additions & 3 deletions packages/website/site/pages/about.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: About
---

import { Re, Res } from "../components/language-content";

# About

Author and maintainer: [David Sancho](https://sancho.dev)
Expand All @@ -13,11 +15,11 @@ Author and maintainer: [David Sancho](https://sancho.dev)
There are a few reasons why this project exists and why it came to live.

### There was a need
In my experience, writing React with a CSS-in-JS library is one of the best combos for writing scalable design systems, UI libraries and applications. When I discovered Reason back in the day (around 2018), it wasn't possible to bind to styled-components or emotion. Even ([a](https://reasonml.chat/t/idiomatic-way-to-bind-to-styled-components/886) [f](https://reasonml.chat/t/styled-components-possible/554)[e](https://reasonml.chat/t/styling-solutions-reasonreact-as-of-aug-18/958)[w](https://reasonml.chat/t/options-and-best-practices-for-styling-in-reasonreact/261) [p](https://twitter.com/lyovson/status/1233397294311100417)[e](https://discord.gg/byjdYFH)[o](https://discord.gg/byjdYFH)[p](https://discord.gg/byjdYFH)[l](https://discord.gg/byjdYFH)[e](https://forum.rescript-lang.org/t/how-to-create-bindings-for-emotion-styled/2995) were asking for it.
In my experience, writing React with a CSS-in-JS library is one of the best combos for writing scalable design systems, UI libraries and applications. When I discovered Reason back in the day (around 2018), it wasn't possible to bind to styled-components or emotion. Even [a](https://reasonml.chat/t/idiomatic-way-to-bind-to-styled-components/886) [f](https://reasonml.chat/t/styled-components-possible/554)[e](https://reasonml.chat/t/styling-solutions-reasonreact-as-of-aug-18/958)[w](https://reasonml.chat/t/options-and-best-practices-for-styling-in-reasonreact/261) [p](https://twitter.com/lyovson/status/1233397294311100417)[e](https://discord.gg/byjdYFH)[o](https://discord.gg/byjdYFH)[p](https://discord.gg/byjdYFH)[l](https://discord.gg/byjdYFH)[e](https://forum.rescript-lang.org/t/how-to-create-bindings-for-emotion-styled/2995) were asking for it.

During that time, there were a few efforts to bring type-safety to CSS with [bs-css](https://github.com/giraud/bs-css) and [bs-emotion](https://github.com/ahrefs/bs-emotion). Even though I liked that approach, it had a few drawbacks:
- The need for learning a new DSL on top of CSS was tedious. Very fancy for simple properties, but almost impossible for more complex ones (a classic example `width: calc(100% - 20px){:styled-ppx-css}` became `CSS.width(calc(min, percent(100.), px(20))){:rescript}` `CSS.width(calc(min, percent(100.), px(20)));{:reason}`). In real world usage I would end up using `CSS.unsafe`.
- The runtime was huge. The bundle-size of bs-css starts with 64kb and goes up considerably with the usage, even with ReScripts dead code elimination.
- The runtime was huge. The bundle-size of bs-css starts with 64kb and goes up considerably with the usage, even with the dead code elimination made by the compiler.
- The fact of having a runtime involved to only write safe CSS doesn't seem like a nice trade-off.

### It's possible and a good solution
Expand All @@ -26,7 +28,7 @@ Embedding CSS inside Reason/OCaml seemed like a bad idea at first, mostly since
After discovering what a ppx was (*"a mechanism to embed other languages inside Reason"*), and it could mimic the template literals, I jumped straight into hacking a prototype that became this project.

Embedding languages inside others isn't a new concept and has been happening for a long time. In fact, the most common case of an embedded language is usually CSS inside HTML.
Using CSS enables all sorts of integrations: Editors, DevTools, prototyping tools, Github Copilot, etc. Even for designers that don't want to understand or care about ReScript.
Using CSS enables all sorts of integrations: Editors, DevTools, prototyping tools, Github Copilot, etc. Even for designers that don't want to understand or care about <Res>ReScript</Res><Re>Reason</Re>.

### It can be more powerful than the JavaScript equivalents
Enabling type-safety in CSS is a nice to have, rather than a hard requirement, but nevertheless useful. styled-ppx brings an entire CSS compiler and type-chcker. This enables features from SASS (like supporting future CSS version features) with features from emotion to inline your styles and code together.
Expand Down
4 changes: 3 additions & 1 deletion packages/website/site/pages/editor-support.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@
title: Editor Support
---

import { Re, Res } from "../components/language-content";

# Editor Support

One of the downsides of embedding a language (CSS) into another language (ReScript/Reason/OCaml) is the limited editor support. Because of that, we provide an editor extension that brings syntax highlighting for the CSS inside the styled-ppx notation.
One of the downsides of embedding a language (CSS) into another language (<Res>ReScript</Res><Re>Reason</Re>) is the limited editor support. Because of that, we provide an editor extension that brings syntax highlighting for the CSS inside the styled-ppx notation.

## VSCode Extension

Expand Down
7 changes: 5 additions & 2 deletions packages/website/site/pages/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,14 @@ title: Frequently asked questions

# Frequently asked questions

## Does it support Reason and OCaml syntax?
## Does it support ReScript, Reason and OCaml syntax?

Yes, both are supported. Even though code snippets are written in ReScript (for the sake of simplicity), you can still use Reason and OCaml syntaxes. Since it is meant to be used in a browser, **styled-ppx** follows the same restrictions as ReScript.
Yes, all are supported. Since the ppx operates on the AST and all of those languages share the majority of the AST, we are able to support all of them. Note that, supporting ReScript has been challenging because they are exploring new patterns of the language that are not compatible with the OCaml AST.

Also, our [VSCode extension](https://marketplace.visualstudio.com/items?itemName=davesnx.vscode-styled-ppx) supports ReScript, Reason, and OCaml syntaxes.

The differences are around syntaxes are the string delimiters:

Reason and OCaml uses `"` and `{||}`, while ReScript uses ```. We recommend that you use `{||}` when it's a multi-line string.

You can use the language selector in the sidebar to switch between the different syntaxes. All snippets on this page are written in Reason and ReScript.
12 changes: 10 additions & 2 deletions packages/website/site/pages/reference/interpolation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: Interpolation
---

import { Re, Res } from "../../components/language-content";
import { Callout } from 'nextra/components'

# Interpolation
Expand Down Expand Up @@ -29,9 +30,16 @@ module Component = [%styled.div {|
|}];
```

<Res>
<Callout>
Don't confuse interpolation from [String Interpolation from ReScript](https://rescript-lang.org/docs/manual/latest/primitive-types#string-interpolation)
</Callout>
</Res>
<Re>
<Callout>
Don't confuse interpolation from [String Interpolation from Reason](https://reasonml.github.io/docs/en/primitives)
</Callout>
</Re>

## Features

Expand Down Expand Up @@ -64,7 +72,7 @@ module Component = [%styled.div {|

It's not allowed to interpolate on entire properties, neither any other interpolation. Which might be slightly different from other SASS/Less and JavaScript-based solutions (such as styled-components or emotion) as their interpolation is more dynamic and can be used everywhere.

**styled-ppx** forces you to be more rigid but with the promise of being always type-safe, which is the same way as ReScript does ❤️. The dynamism from JavaScript-based solutions comes with the cost of being unsafe.
**styled-ppx** forces you to be more rigid but with the promise of being always type-safe, which is the same way as <Res>ReScript</Res><Re>Reason</Re> does ❤️. The dynamism from JavaScript-based solutions comes with the cost of being unsafe.

Here's a valid JavaScript example `` `margin-${whatever}: 10px`{:js} `` from styled-components. Which isn't valid in **styled-ppx** with the same syntax. As explained above, this interpolation can't be applied to entire **properties** or half-properties.

Expand Down Expand Up @@ -178,7 +186,7 @@ background: #fff url(img.png); /* The background is white with an image */
background: url(img.png) no-repeat; /* The background is a non-repeating image */
```

In this case, to interpolate the background's value like: `background: $(variable1) $(variable2)` the type-checker can't know the type of `$(variable1)` and `(variable2)` ahead of time, because there are numerous possibilities for a valid `background` CSS property. This is called an [overload](https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html#overloaded-functions) in other languages and it's not available in ReScript due to it's nature of being a static typed language.
In this case, to interpolate the background's value like: `background: $(variable1) $(variable2)` the type-checker can't know the type of `$(variable1)` and `(variable2)` ahead of time, because there are numerous possibilities for a valid `background` CSS property. This is called an [overload](https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html#overloaded-functions) in other languages and it's not available in <Res>ReScript</Res><Re>Reason</Re> due to it's nature of being a static typed language.

## What if a property isn't supported

Expand Down
8 changes: 5 additions & 3 deletions packages/website/site/pages/reference/runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,18 @@
title: Runtime
---

import { Re, Res } from "../../components/language-content";

# CSS

> This page is a work in progress
Since v0.40.0 styled-ppx exposes a module called `CSS` that is used to construct values for CSS properties.

The library is available under:

- For ReScript users, as a rescript packages: `@davesnx/syled-ppx/css` and `@davesnx/syled-ppx/emotion`
The library is available<Res> as a rescript packages `@davesnx/syled-ppx/css` and `@davesnx/syled-ppx/emotion`.</Res><Re>:</Re>
<Re>
- For Melange users, as dune library with `(modes melange)`: `styled-ppx.melange`
- For native users, as dune library: `styled-ppx.native`
</Re>

Read more in the release notes for [v0.40](https://github.com/davesnx/styled-ppx/releases/tag/0.40.0)

0 comments on commit 96a8f9e

Please sign in to comment.