From ea9197b8d95ec5e30026cc33d2fd8fc27d16a457 Mon Sep 17 00:00:00 2001
From: Iwan <mvalcke@hubspot.com>
Date: Mon, 4 Jan 2021 20:25:53 +0100
Subject: [PATCH] Add basic examples for new import syntax

---
 .../latest/import-from-export-to-js.mdx       | 75 ++++++++++++++++---
 1 file changed, 63 insertions(+), 12 deletions(-)

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 0d9938f06..a6739d0f6 100644
--- a/pages/docs/manual/latest/import-from-export-to-js.mdx
+++ b/pages/docs/manual/latest/import-from-export-to-js.mdx
@@ -10,15 +10,15 @@ You've seen how ReScript's idiomatic [Import & Export](import-export.md) works.
 
 ## Import From JavaScript
 
-### Import a JavaScript Module's Content
+### Import a single export from a JavaScript module
 
-Use the `bs.module` [external](external.md):
+Use [import](import.md):
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
 ```res example
 // Import nodejs' path.dirname
-@bs.module("path") external dirname: string => string = "dirname"
+import {dirname: string => string} from "path"
 let root = dirname("/User/github") // returns "User"
 ```
 ```js
@@ -28,22 +28,53 @@ var root = Path.dirname("/User/github");
 
 </CodeTab>
 
-Here's what the `external` does:
+Here's what happens:
 
-- `@bs.module("path")`: pass the name of the JS module as a string; in this case, `"path"`. The string can be anything: `"./src/myJsFile"`, `"@myNpmNamespace/myLib"`, etc.
-- `external`: the general keyword for declaring a value that exists on the JS side.
+- `import`: the general keyword for importing a value that exists on the JS side.
+- `{ ... }`: import a named export
 - `dirname`: the binding name you'll use on the ReScript side.
 - `string => string`: the type signature of `dirname`.
-- `= "dirname"`: the name of the variable inside the `path` JS module. There's repetition in writing the first and second `dirname`, because sometime the binding name you want to use on the ReScript side is different than the variable name the JS module exported.
+- `from "path"`: pass the name of the JS module as a string; in this case, `"path"`. The string can be anything: `"./src/myJsFile"`, `"@myNpmNamespace/myLib"`, etc.
 
-### Import a JavaScript Module Itself (CommonJS)
+### Import multiple exports from a JavaScript Module
 
-By omitting the string argument to `bs.module`, you bind to the whole JS module:
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+// Import nodejs' path.dirname
+import {isAbsolute: string => bool, dirname: string => string} from "path"
+let root = dirname("/User/github") // returns "User"
+let isAbsolutePath = isAbsolute("C:/foo/..") // true
+```
+```js
+var Path = require("path");
+var root = Path.dirname("/User/github");
+var isAbsolutePath = Path.isAbsolute("C:/foo/..");
+```
+</CodeTab>
+
+### Import an export with a more convenient alias
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
 ```res example
-@bs.module external leftPad: string => int => string = "./leftPad"
+import {sep as platformSeperator: string} from "path"
+Js.log(platformSeperator) // `\` on Windows, `/` on POSIX
+```
+```js
+var Path = require("path");
+console.log(Path.sep);
+```
+</CodeTab>
+
+### Import an entire JavaScript Module contents
+
+you bind to the whole JS module by writing: `* as myModule`
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+import * as leftPad: (string, int) => string from "./leftPad"
 let paddedResult = leftPad("hi", 5)
 ```
 ```js
@@ -53,14 +84,14 @@ var paddedResult = LeftPad("hi", 5);
 
 </CodeTab>
 
-### Import a JavaScript Module Itself (ES6 Module Format)
+### Import a JavaScript Module default (ES6 Module Format)
 
 If your JS project is using ES6, you're likely using Babel to compile it to regular JavaScript. Babel's ES6 default export actually exports the default value under the name `default`. You'd bind to it like this:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
 ```res example
-@bs.module("./student") external studentName: string = "default"
+import studentName: string from "./student"
 Js.log(studentName)
 ```
 ```js
@@ -70,6 +101,26 @@ console.log(Student.default);
 
 </CodeTab>
 
+### Import an export with variadic arguments
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+import {@variadic join: array<string> => string} from "path"
+let fullPath = join(["Users", "github"])
+```
+```js
+var Path = require("path");
+var fullPath = Path.join(["Users", "github"]);
+```
+</CodeTab>
+
+### Import an export with an illegal ReScript identifier
+
+```res example
+import {"Fragment" as make: component<{"children": element}>} from "react"
+```
+
 ## Export To JavaScript
 
 As mentioned in ReScript's idiomatic [Import & Export](import-export.md), every let binding and module is exported by default to other ReScript modules. If you open up the compiled JS file, you'll see that these values can also directly be used by another _JavaScript_ file too.