From aad35d6c6ef96f7c9e9af8fb96cf4cc24a7fe9bc Mon Sep 17 00:00:00 2001
From: Travis Kaufman <traviskaufman@users.noreply.github.com>
Date: Thu, 25 Nov 2021 12:53:26 -0500
Subject: [PATCH] Add example of importing a react component from JS

There is currently no documentation showing how to import an external react component into ReScript. This commit adds one, adopting an example from https://forum.rescript-lang.org/t/use-reactjs-components-in-rescript-react-project/1992
---
 data/sidebar_react_latest.json                | 14 ++---
 .../latest/import-from-export-to-js.mdx       |  2 +
 .../docs/react/latest/javascript-interop.mdx  | 55 +++++++++++++++++++
 3 files changed, 61 insertions(+), 10 deletions(-)
 create mode 100644 pages/docs/react/latest/javascript-interop.mdx

diff --git a/data/sidebar_react_latest.json b/data/sidebar_react_latest.json
index 0439ddfc1..91f1ba9fd 100644
--- a/data/sidebar_react_latest.json
+++ b/data/sidebar_react_latest.json
@@ -1,9 +1,5 @@
 {
-  "Overview": [
-    "introduction",
-    "installation",
-    "migrate-from-reason-react"
-  ],
+  "Overview": ["introduction", "installation", "migrate-from-reason-react"],
   "Main Concepts": [
     "elements-and-jsx",
     "rendering-elements",
@@ -12,7 +8,8 @@
     "refs-and-the-dom",
     "context",
     "styling",
-    "router"
+    "router",
+    "javascript-interop"
   ],
   "Hooks & State Management": [
     "hooks-overview",
@@ -23,8 +20,5 @@
     "hooks-ref",
     "hooks-custom"
   ],
-  "Guides": [
-    "beyond-jsx",
-    "forwarding-refs"
-  ]
+  "Guides": ["beyond-jsx", "forwarding-refs"]
 }
diff --git a/pages/docs/manual/latest/import-from-export-to-js.mdx b/pages/docs/manual/latest/import-from-export-to-js.mdx
index 77c285929..3aa1e2e8b 100644
--- a/pages/docs/manual/latest/import-from-export-to-js.mdx
+++ b/pages/docs/manual/latest/import-from-export-to-js.mdx
@@ -8,6 +8,8 @@ canonical: "/docs/manual/latest/import-from-export-to-js"
 
 You've seen how ReScript's idiomatic [Import & Export](import-export.md) works. This section describes how we work with importing stuff from JavaScript and exporting stuff for JavaScript consumption.
 
+If you're looking for react-specific interop guidance, check out the [React JS Interop guide](../../react/latest/javascript-interop.mdx).
+
 **Note**: due to JS ecosystem's module compatibility issues, our advice of keeping your ReScript file's compiled JS output open in a tab applies here **more than ever**, as you don't want to subtly output the wrong JS module import/export code, on top of having to deal with Babel/Webpack/Jest/Node's CommonJS<->ES6 compatibility shims.
 
 In short: **make sure your bindings below output what you'd have manually written in JS**.
diff --git a/pages/docs/react/latest/javascript-interop.mdx b/pages/docs/react/latest/javascript-interop.mdx
new file mode 100644
index 000000000..847d7ad12
--- /dev/null
+++ b/pages/docs/react/latest/javascript-interop.mdx
@@ -0,0 +1,55 @@
+---
+title: "JavaScript Interop"
+description: "Working with React module content in ReScript"
+canonical: "/docs/react/latest/javascript-interop"
+---
+
+# JavaScript Interop
+
+This section complements the general [Import from / Export to JS](../../manual/latest/import-from-export-to-js.md)
+section with React-specific guidance.
+
+## Import from JavaScript
+
+### Importing a JS-based React Component
+
+This is especially useful for 3rd-party components.
+
+<CodeTab labels={["ReScript", "JS Output (ES6)"]}>
+
+```res example
+module DatePicker = {
+  @module("react-datepicker") @react.component
+  external make: (~date: Js.Date.t, ~onChange: (Js.Date.t) => unit) => React.element = "default"
+}
+
+@react.component
+let make = () => {
+  let (date, setDate) = React.useState(Js.Date.make)
+  <DatePicker date=date onChange={date => setDate(_ => date)} />
+}
+```
+```js
+import * as Curry from "./stdlib/curry.js";
+import * as React from "react";
+import ReactDatepicker from "react-datepicker";
+
+var DatePicker = {};
+
+function Playground(Props) {
+  var match = React.useState(function () {
+        return new Date();
+      });
+  var setDate = match[1];
+  return React.createElement(ReactDatepicker, {
+              date: match[0],
+              onChange: (function (date) {
+                  return Curry._1(setDate, (function (param) {
+                                return date;
+                              }));
+                })
+            });
+}
+```
+
+</CodeTab>