Merge pull request #177 from cca-io/version-3.0.0

Version 3.0.0
cca-io · Dec 6, 2021 · c134c33 · c134c33
2 parents 69874ec + 05d00a2
commit c134c33
Show file tree

Hide file tree

Showing 34 changed files with 2,620 additions and 1,935 deletions.
diff --git a/README.md b/README.md
@@ -19,4 +19,4 @@ Transition steps:
 
 1. ✅ Release `@jsiebern/bs-material-ui@2.1.0`
 2. ✅ Transition package name to `rescript-material-ui`
-3. Complete Reason -> ReScript transition and release `rescript-material-ui@3.0.0` with breaking changes
+3. ✅ Complete Reason -> ReScript transition and release `rescript-material-ui@3.0.0` with breaking changes
diff --git a/documentation/docs/changelog.md b/documentation/docs/changelog.md
@@ -14,6 +14,28 @@ title: Changelog
 (_Tags are copied from
 [babel](https://github.com/babel/babel/blob/master/CHANGELOG.md)_)
 
+## 3.0.0
+
+- :boom: Converted the main entry point `MaterialUi` to the `Mui` namespace.
+- :boom: Added `Any` module as a replacement for `MaterialUi.Types` and
+  `MaterialUi.any`.
+- :boom: Use stricter `React.element` type for children.
+- :boom: Simplified ThemeProvider and removed MuiThemeProvider.
+- :boom: `createTheme` replaces `createMuiTheme`.
+- :boom: Removed `WithStyles` HOC and added a simple `useStyles` binding
+  instead.
+- :rocket: Added some custom props for `Button`, `ButtonBase`,
+  `FormControlLabel`, `OutlinedInput`, `Radio`, `Switch`, `TableRow`,
+  `TextField`.
+- :rocket: Updated to material-ui 4.12.3 and material-ui-lab 4.0.0-alpha.60.
+- :memo: Updated all Documentation to current changes.
+- :memo: Added a migration guide for the transition to this version.
+- :memo: Added a bunch of examples.
+- :memo: ReScript syntax highlighting.
+- :house: Made most bindings zero cost
+- :house: Restructured the monorepo.
+- :nail_care: Finished Reason -> ReScript transition.
+
 ## 2.1.2
 
 - :boom: Republished 2.1.0 with the new package name `rescript-material-ui`.

diff --git a/documentation/docs/examples.md b/documentation/docs/examples.md
@@ -10,7 +10,8 @@ for more information.
 
 ```bash
 git clone https://github.com/cca-io/rescript-material-ui.git
-cd rescript-material-ui/public/rescript-material-ui
+cd rescript-material-ui/examples
 yarn install
-yarn examples
+yarn build
+yarn start
 ```
diff --git a/documentation/docs/installation.md b/documentation/docs/installation.md
@@ -2,7 +2,7 @@
 title: Installation
 ---
 
-First, add it to you dependencies using `npm` or `yarn`:
+First, add it to your dependencies using `npm` or `yarn`:
 
 ```bash
 yarn add rescript-material-ui

diff --git a/documentation/docs/introduction.md b/documentation/docs/introduction.md
@@ -3,7 +3,8 @@ title: Introduction
 ---
 
 `rescript-material-ui` provides [ReScript](https://rescript-lang.org/) bindings
-for the Javascript based UI library [MaterialUi](https://material-ui.com/).
+for the Javascript based UI library [MUI](https://mui.com/) (formerly
+[MaterialUi](https://material-ui.com/)).
 
 The bindings are automatically generated by utilizing the documentation
 generation scripts of the original package. These rely on a mix of code & code

diff --git a/documentation/docs/lab/installation.md b/documentation/docs/lab/installation.md
@@ -2,7 +2,7 @@
 title: Installation
 ---
 
-First, add it to you dependencies using `npm` or `yarn`:
+First, add it to your dependencies using `npm` or `yarn`:
 
 ```bash
 yarn add rescript-material-ui

diff --git a/documentation/docs/migration/2x-to-3.md b/documentation/docs/migration/2x-to-3.md
@@ -0,0 +1,60 @@
+---
+title: 2.x -> 3.0.0
+---
+
+# Migration Guide for v2.x -> v3.0.0
+
+## MaterialUi is now Mui
+
+We changed the namespace from `MaterialUi` to `Mui` in 3.0.0 for the following
+reasons:
+
+1. Nice and short 🙂
+2. Material-UI [rebranded to MUI](https://mui.com/blog/material-ui-is-now-mui/)
+3. Now that we are using the `namespace` feature, it is not possible anymore to
+   "alias" the `MaterialUi` module to `Mui` using `include MaterialUi`. This
+   gives the following error:
+   `Mui is compiled in script mode while its dependent is not`.
+4. 3.0.0 already has other breaking changes anyway.
+
+Furthermore, the lab bindings now have their own namespace under `MuiLab`.
+
+## Bindings changes
+
+These are mainly due to the stricter focus on zero-cost bindings.
+
+### Mangled names utilize the `\""`-syntax now
+
+e.g. `_InputProps` is now `\"InputProps"`, `_type="number"` is now
+`\"type"="number"`.
+
+### Polymorphic variants are now all lowercase
+
+e.g. `color=#Primary` is now `color=#primary`.
+
+### `any` and `anyUnpack` have been replaced
+
+These type helpers now reside under `Mui.Any`. Refer to
+[Any](../project-structure/any-type.md).
+
+### Children types are more specific
+
+Previously it was possible to put arbitrary types (such as strings) into
+children. Now the children type is `React.element`, which streamlines this
+library to the `rescript-react` bindings.
+
+Therefore, you now need to wrap strings with the `React.string` function, or
+pass arrays to `React.array`.
+
+## FAQ
+
+### Did we miss anything?
+
+If there are any problems with this new release, feel free to
+[open an issue](https://github.com/cca-io/rescript-material-ui/issues).
+
+### Will you upgrade to v5 as well?
+
+We are in no rush to do it, because we currently use v4 in most of our projects.
+If we ever feel the need to upgrade, we will upgrade this repository
+accordingly.
diff --git a/documentation/docs/project-structure/any-type.md b/documentation/docs/project-structure/any-type.md
@@ -3,7 +3,7 @@ title: Any Type
 ---
 
 If the type you need to pass cannot be determined you can usually insert the
-`Any` type. It lives under `Mui.Types`.
+`Any` type. It lives under `Mui.Any`.
 
 :::info
 

diff --git a/documentation/docs/project-structure/modules.md b/documentation/docs/project-structure/modules.md
@@ -23,30 +23,32 @@ section of the MUI documentation.
 
 ### Global module
 
-For convenience, `rescript-material-ui` offers the `MaterialUi` module as well.
-It includes all components and a few special ones, which will be discussed
-later. This modules primary purpose is not having to type out the `MaterialUi_`
-part of the component modules each time. Example:
+With version 3.0.0, this library switched to the
+[ReScript namespace](https://rescript-lang.org/docs/manual/latest/build-configuration#name-namespace)
+`Mui` which replaces the previous `MaterialUi` module.
+
+For convenience, the `Mui` module includes a few special modules, which will be
+discussed later. To avoid name clashes, we suggest you stick to typing out
+`Mui.[COMPONENT_NAME]` instead of using `open`.
 
 ```rescript
 @react.component
-let make = () => {
-  open Mui
+let make = () =>
   <div>
-    <Typography variant=#h4 gutterBottom=true>
+    <Mui.Typography variant=#h4 gutterBottom=true>
       {"Headline"->React.string}
-    </Typography>
-    <Typography>
+    </Mui.Typography>
+    <Mui.Typography>
       {"Some example text"->React.string}
-    </Typography>
+    </Mui.Typography>
   </div>
-}
 ```
 
 ### Special modules
 
-`Mui.res` contains the following special modules:
+The `Mui` namespace contains the following special modules:
 
+- [Any](any-type.md)
 - [Colors](module-colors.md)
 - [Core](module-core.md)
 - [Box](module-box.md)

diff --git a/documentation/docs/styles-ppx/installation.md b/documentation/docs/styles-ppx/installation.md
diff --git a/documentation/docs/styles-ppx/introduction.md b/documentation/docs/styles-ppx/introduction.md
diff --git a/documentation/docs/styles-ppx/usage.md b/documentation/docs/styles-ppx/usage.md
diff --git a/documentation/docs/styling/bs-css.md b/documentation/docs/styling/bs-css.md
@@ -0,0 +1,31 @@
+---
+title: bs-css
+---
+
+## Usage with bs-css or other CSS-in-ReScript libraries
+
+It is important to change the style precedence order with the help of the
+`StylesProvider` component, otherwise the internal MUI classes will overwrite
+your styles.
+
+### Example
+
+```rescript
+module Styles = {
+  open CssJs
+
+  let categoryButton = style(. [textTransform(#none), justifyContent(#flexStart)])
+  let icon = style(. [fontSize(px(24)), width(px(50))])
+}
+
+@react.component
+let make = () =>
+  <Mui.StylesProvider injectFirst=true>
+    <Mui.Button
+      color=#primary
+      classes={Mui.Button.Classes.make(~root=Styles.categoryButton, ())}
+      onClick=ignore>
+      {React.string("Hello, BS-CSS & MUI!")}
+    </Mui.Button>
+  </Mui.StylesProvider>
+```
diff --git a/documentation/docs/styling/css.md b/documentation/docs/styling/css.md
@@ -0,0 +1,24 @@
+---
+title: Plain CSS
+---
+
+## Usage with plain CSS
+
+It is important to change the style precedence order with the help of the
+`StylesProvider` component, otherwise the internal MUI classes will overwrite
+your styles.
+
+### Example
+
+```rescript
+@react.component
+let make = () =>
+  <Mui.StylesProvider injectFirst=true>
+    <Mui.Button
+      color=#primary
+      className="my-global-class-name"
+      onClick=ignore>
+      {React.string("Hello, plain CSS & MUI!")}
+    </Mui.Button>
+  </Mui.StylesProvider>
+```
diff --git a/documentation/docs/styling/introduction.md b/documentation/docs/styling/introduction.md
@@ -0,0 +1,12 @@
+---
+title: Introduction
+---
+
+For styling `rescript-material-ui` components, you need to pass CSS class names
+to them. We have documented the following popular options:
+
+- [`useStyles` hook](use-styles) (new in 3.0.0)
+- [CSS](css)
+- [Tailwind CSS](tailwind)
+- [a CSS-in-ReScript library like `bs-css`](bs-css)
+- [`Styles PPX`](styles-ppx) (not recommended)