Merge branch 'master' into update-docs-api-29-06

Author: aspeddro

data/sidebar_react_latest.json

@@ -12,9 +12,11 @@
     "events",
     "refs-and-the-dom",
     "context",
+    "memo",
     "styling",
     "router",
-    "lazy-components"
+    "lazy-components",
+    "import-export-reactjs"
   ],
   "Hooks & State Management": [
     "hooks-overview",

misc_docs/syntax/decorator_send_pipe.mdx

@@ -4,6 +4,7 @@ keywords: ["send", "pipe", "decorator"]
 name: "@bs.send.pipe"
 summary: "This is the `@bs.send.pipe` decorator."
 category: "decorators"
+status: "deprecated"
 ---
 
 > Removed since compiler version 10.0. Use the [@send](https://rescript-lang.org/docs/manual/latest/bind-to-js-function) decorator instead.

misc_docs/syntax/language_labeled_argument.mdx

@@ -0,0 +1,69 @@
+---
+id: "labeled-argument"
+keywords: ["labeled", "argument"]
+name: "~arg"
+summary: "This is a `labeled argument`."
+category: "languageconstructs"
+---
+
+When declaring a function, arguments can be prefixed with `~` which means that they can and need to be called by their name, not the argument position. This is especially useful to differentiate them more easily if they are of the same type.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res prelude
+let calculateDistance = (~x1, ~y1, ~x2, ~y2) => {
+  Math.sqrt((x1 -. x2) ** 2. +. (y1 -. y2) ** 2.)
+}
+
+calculateDistance(~x1=6., ~y1=8., ~x2=3., ~y2=4.) 
+```
+
+```js
+function calculateDistance(x1, y1, x2, y2) {
+  return Math.sqrt(Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2));
+}
+
+calculateDistance(6, 8, 3, 4);
+```
+
+</CodeTab>
+
+Labeled arguments can be provided in any order:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+calculateDistance(~x1=6., ~x2=3., ~y1=8., ~y2=4.) 
+```
+
+```js
+calculateDistance(6, 8, 3, 4);
+```
+
+</CodeTab>
+
+This also works together with partial application:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let calcY = calculateDistance(~x1=6., ~x2=3., ...)
+calcY(~y1=8., ~y2=4.)
+```
+
+```js
+function calcY(none, extra) {
+  return calculateDistance(6, none, 3, extra);
+}
+
+calcY(8, 4);
+```
+
+</CodeTab>
+
+### References
+
+* [Labeled Arguments](/docs/manual/latest/function#labeled-arguments)
+* [Function Syntax Cheatsheet](/docs/manual/latest/function#tips--tricks)

misc_docs/syntax/language_optional_labeled_argument.mdx

@@ -0,0 +1,85 @@
+---
+id: "optional-labeled-argument"
+keywords: ["optional", "labeled", "argument"]
+name: "~arg=?"
+summary: "This is an `optional labeled argument`."
+category: "languageconstructs"
+---
+
+Labeled arguments, i.e. arguments that are prefixed with `~`, can be suffixed with `=?` to denote that they are optional. Thus, they can be
+omitted when calling the function.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let print = (text, ~logLevel=?) => {
+  switch logLevel {
+  | Some(#error) => Console.error(text)
+  | _ => Console.log(text)
+  }
+}
+
+print("An info")
+print("An error", ~logLevel=#error)
+```
+
+```js
+function print(text, logLevel) {
+  if (logLevel === "error") {
+    console.error(text);
+  } else {
+    console.log(text);
+  }
+}
+
+print("An info", undefined);
+
+print("An error", "error");
+```
+
+</CodeTab>
+
+Optional labeled arguments can also hold a default value.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let print = (text, ~logLevel=#info) => {
+  switch logLevel {
+  | #error => Console.error(text)
+  | #warn => Console.warn(text)
+  | #info => Console.log(text)
+  }
+}
+
+print("An info")
+print("A warning", ~logLevel=#warn)
+```
+
+```js
+function print(text, logLevelOpt) {
+  var logLevel = logLevelOpt !== undefined ? logLevelOpt : "info";
+  if (logLevel === "warn") {
+    console.warn(text);
+  } else if (logLevel === "error") {
+    console.error(text);
+  } else {
+    console.log(text);
+  }
+}
+
+print("An info", undefined);
+
+print("A warning", "warn");
+```
+
+</CodeTab>
+
+### References
+
+* [Labeled Arguments](/docs/manual/latest/function#labeled-arguments)
+* [Optional Labeled Arguments](/docs/manual/latest/function#optional-labeled-arguments)
+* [Labeled Argument with Default Value](/docs/manual/latest/function#optional-with-default-value)
+* [Function Syntax Cheatsheet](/docs/manual/latest/function#tips--tricks)

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/import-export-reactjs.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 \<-> JavaScript module compatibility shims.
 
 In short: **make sure your bindings below output what you'd have manually written in JS**.

pages/docs/manual/latest/let-binding.mdx

@@ -181,5 +181,5 @@ Still, `%%private` is useful in the following scenarios:
 
 - **Code generators.** Some code generators want to hide some values but it is sometimes very hard or time consuming for code generators to synthesize the types for public fields.
 
-- **Quick prototyping.** During prototyping, we still want to hide some values, but the interface file is not stable yet, `%%private` provide you such convenience.
+- **Quick prototyping.** During prototyping, we still want to hide some values, but the interface file is not stable yet. `%%private` provides you such convenience.
 

pages/docs/manual/latest/overview.mdx

@@ -127,7 +127,7 @@ canonical: "/docs/manual/latest/overview"
       const myFun = (x, y) => {
         const doubleX = x + x;
         const doubleY = y + y;
-        return doubleX + doubleY
+        return doubleX + doubleY;
       };
       ```
       </td>

pages/docs/manual/v10.0.0/let-binding.mdx

@@ -181,5 +181,5 @@ Still, `%%private` is useful in the following scenarios:
 
 - **Code generators.** Some code generators want to hide some values but it is sometimes very hard or time consuming for code generators to synthesize the types for public fields.
 
-- **Quick prototyping.** During prototyping, we still want to hide some values, but the interface file is not stable yet, `%%private` provides you such convenience.
+- **Quick prototyping.** During prototyping, we still want to hide some values, but the interface file is not stable yet. `%%private` provides you such convenience.
 

pages/docs/manual/v10.0.0/overview.mdx

@@ -125,7 +125,7 @@ canonical: "/docs/manual/latest/overview"
   <pre><code>{`const myFun = (x, y) => {
   const doubleX = x + x;
   const doubleY = y + y;
-  return doubleX + doubleY
+  return doubleX + doubleY;
 };`}</code></pre>
       </td>
       <td>

pages/docs/manual/v8.0.0/let-binding.mdx

@@ -217,5 +217,5 @@ Still, `%private` is useful in the following scenarios:
 
 - Code generators. Some code generators want to hide some values but it is sometimes very hard or time consuming for code generators to synthesize the types for public fields.
 
-- Quick prototyping. During prototyping, we still want to hide some values, but the interface file is not stable yet, `%private` provide you such convenience.
+- Quick prototyping. During prototyping, we still want to hide some values, but the interface file is not stable yet. `%private` provides you such convenience.
 

pages/docs/manual/v8.0.0/overview.mdx

@@ -117,7 +117,7 @@ canonical: "/docs/manual/latest/overview"
       const myFun = (x, y) => {
         const doubleX = x + x;
         const doubleY = y + y;
-        return doubleX + doubleY
+        return doubleX + doubleY;
       };
       ```
       </td>

pages/docs/manual/v9.0.0/let-binding.mdx

@@ -181,5 +181,5 @@ Still, `%private` is useful in the following scenarios:
 
 - Code generators. Some code generators want to hide some values but it is sometimes very hard or time consuming for code generators to synthesize the types for public fields.
 
-- Quick prototyping. During prototyping, we still want to hide some values, but the interface file is not stable yet, `%private` provide you such convenience.
+- Quick prototyping. During prototyping, we still want to hide some values, but the interface file is not stable yet. `%private` provides you such convenience.
 

pages/docs/manual/v9.0.0/overview.mdx

@@ -115,7 +115,7 @@ canonical: "/docs/manual/latest/overview"
       const myFun = (x, y) => {
         const doubleX = x + x;
         const doubleY = y + y;
-        return doubleX + doubleY
+        return doubleX + doubleY;
       };
       ```
       </td>

pages/docs/react/latest/import-export-reactjs.mdx

@@ -0,0 +1,189 @@
+---
+title: Import / Export ReactJS
+description: "Reusing existing React components"
+canonical: "/docs/react/latest/import-export-reactjs"
+---
+
+# Import / Export ReactJS
+
+Reusing existing React components in ReScript is straightforward. 
+This guide will walk you through the steps required to import and use React components within ReScript,
+including defining component props and handling various import scenarios.
+
+## Basic Example
+
+To reuse a React component in ReScript, create a new module, specify the component's location, and define its props.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+module Confetti = {
+  @module("react-confetti") @react.component
+  external make: (~width: int, ~height: int) => React.element = "default"
+}
+
+// Assuming we are in App.res
+@react.component
+let make = () => {
+  <Confetti width={300} height={300} />
+}
+```
+
+```js
+import ReactConfetti from "react-confetti";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var Confetti = {};
+
+function Playground(props) {
+  return JsxRuntime.jsx(ReactConfetti, {
+              width: 300,
+              height: 300
+            });
+}
+```
+
+</CodeTab>
+
+## Importing from Relative Paths
+
+You can import components from relative file paths using the `@module` attribute.  
+Use "default" to indicate the default export, or specify a named export if needed.
+
+### Named Export Example 
+
+<CodeTab labels={["ReScript"]}>
+
+```res
+// Equivalent of import { Foo } from "bar"
+module Foo = {
+  @module("bar") @react.component
+  external make: unit => React.element = "Foo"
+}
+```
+
+</CodeTab>
+
+## Defining Props Types
+
+You can define a separate type for your component's props within the module.
+
+### Props Type Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+module Confetti = {
+  type confettiProps = {
+    width: int,
+    height: int,
+  }
+
+  @module("react-confetti") @react.component(: confettiProps)
+  external make: confettiProps => React.element = "default"
+}
+
+@react.component
+let make = () => {
+  <Confetti width={300} height={300} />
+}
+```
+
+```js
+import ReactConfetti from "react-confetti";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var Confetti = {};
+
+function Playground(props) {
+  return JsxRuntime.jsx(ReactConfetti, {
+              width: 300,
+              height: 300
+            });
+}
+```
+
+</CodeTab>
+
+## Optional Props
+
+To define optional props, use the `?` symbol.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+module Confetti = {
+  type confettiProps = {
+    width: int,
+    height: int,
+    initialVelocityX?: int,
+    initialVelocityY?: int,
+  }
+
+  @module("react-confetti") @react.component(: confettiProps)
+  external make: confettiProps => React.element = "default"
+}
+
+@react.component
+let make = () => {
+  <Confetti width={300} height={300} />
+}
+```
+
+```js
+import ReactConfetti from "react-confetti";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var Confetti = {};
+
+function Playground(props) {
+  return JsxRuntime.jsx(ReactConfetti, {
+              width: 300,
+              height: 300
+            });
+}
+```
+
+</CodeTab>
+
+## Extending Built-in DOM Nodes
+
+To accept existing DOM props for a component, extend the `JsxDOM.domProps` type.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+module Foo = {
+  type fooProps = {
+    ...JsxDOM.domProps,
+    customProp: string,
+  }
+
+  @module("foo") @react.component(: fooProps)
+  external make: fooProps => React.element = "default"
+}
+
+@react.component
+let make = () => {
+  <Foo width={"300px"} height={"300px"} customProp="bar" />
+}
+```
+
+```js
+import Foo from "foo";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var Foo$1 = {};
+
+function Playground(props) {
+  return JsxRuntime.jsx(Foo, {
+              height: "300px",
+              width: "300px",
+              customProp: "bar"
+            });
+}
+```
+
+</CodeTab>
+
+In this example `width` and `height` can be set because `JsxDOM.domProps` was spread into `fooProps`.

pages/docs/react/latest/memo.mdx

@@ -0,0 +1,133 @@
+---
+title: memo
+description: "Using React.memo"
+canonical: "/docs/react/latest/memo"
+---
+
+# memo
+
+`React.memo` lets you skip re-rendering a component when its props are unchanged.
+
+Wrap a component in memo to get a memoized version of that component.
+This memoized version of your component will usually not be re-rendered when its parent component is re-rendered as long as its props have not changed.
+
+<small>But React may still re-render it: memoization is a performance optimization, not a guarantee.</small>
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+@react.component
+let make = React.memo((~a: int, ~b: string) => {
+  <div>
+    {React.int(a)}
+    <br />
+    {React.string(b)}
+  </div>
+})
+```
+
+```js
+import * as React from "react";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var make = React.memo(function (props) {
+      return JsxRuntime.jsxs("div", {
+                  children: [
+                    props.a,
+                    JsxRuntime.jsx("br", {}),
+                    props.b
+                  ]
+                });
+    });
+```
+
+</CodeTab>
+
+## arePropsEqual
+
+In React, memo can accept an optional argument called "arePropsEqual". This function takes two arguments: the previous props and the new props of the component.
+It should return true if the old and new props are the same, meaning the component will produce the same output and behavior with the new props as it did with the old ones.
+
+In ReScript, you can use the `arePropsEqual` function with the `React.memoCustomCompareProps` binding. However, `React.memoCustomCompareProps` cannot be combined with `@react.component`.
+
+To work around this, you can redefine the make binding:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+@react.component
+let make = (~disabled, ~onClick) => {
+  <button
+    disabled={disabled}
+    onClick={ev => ev->JsxEvent.Mouse.preventDefault->onClick}>
+    {React.string("My button")}
+  </button>
+}
+
+let make = React.memoCustomCompareProps(make, (p1, p2) =>
+  p1.disabled == p2.disabled
+)
+```
+
+```js
+import * as React from "react";
+import * as JsxRuntime from "react/jsx-runtime";
+
+function Playground(props) {
+  var onClick = props.onClick;
+  return JsxRuntime.jsx("button", {
+              children: "My button",
+              disabled: props.disabled,
+              onClick: (function (ev) {
+                  onClick((ev.preventDefault(), undefined));
+                })
+            });
+}
+
+var make = React.memo(Playground, (function (p1, p2) {
+        return p1.disabled === p2.disabled;
+      }));
+```
+
+</CodeTab>
+
+
+Another approach is to use a custom prop type and remove the `@react.component` annotation.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type props = {
+  disabled: bool,
+  onClick: JsxEvent.Mouse.t => unit,
+}
+
+let make = React.memoCustomCompareProps(
+  ({disabled, onClick}) => {
+    <button disabled={disabled} onClick={ev => ev->onClick}>
+      {React.string("My button")}
+    </button>
+  },
+  (p1, p2) => p1.disabled == p2.disabled,
+)
+```
+
+```js
+import * as React from "react";
+import * as JsxRuntime from "react/jsx-runtime";
+
+var make = React.memo((function (param) {
+        var onClick = param.onClick;
+        return JsxRuntime.jsx("button", {
+                    children: "My button",
+                    disabled: param.disabled,
+                    onClick: (function (ev) {
+                        onClick(ev);
+                      })
+                  });
+      }), (function (p1, p2) {
+        return p1.disabled === p2.disabled;
+      }));
+```
+
+</CodeTab>