Add refs / forwardRefs / useRef docs

Author: ryyppy

pages/docs/react/latest/forwarding-refs.mdx

@@ -0,0 +1,136 @@
+---
+title: Forwarding Refs 
+description: "Forwarding Ref values in ReScript and React"
+canonical: "/docs/react/latest/forwarding-refs"
+category: "Guides"
+---
+
+# Forwarding Refs
+
+<Intro>
+
+Ref forwarding is a technique for automatically passing a [React.ref](./refs-and-the-dom) through a component to one of its children. This is typically not necessary for most components in the application. However, it can be useful for some kinds of components, especially in reusable component libraries. The most common scenarios are described below.
+
+</Intro>
+
+## Forwarding Refs to DOM Components
+
+Consider a FancyButton component that renders the native button DOM element:
+
+```res
+// FancyButton.res
+
+@react.component
+let make = (~children) => {
+  <button className="FancyButton">
+    children
+  </button>
+}
+```
+
+React components hide their implementation details, including their rendered output. Other components using FancyButton **usually will not need** to obtain a ref to the inner button DOM element. This is good because it prevents components from relying on each other’s DOM structure too much.
+
+Although such encapsulation is desirable for application-level components like `FeedStory` or `Comment`, it can be inconvenient for highly reusable “leaf” components like `FancyButton` or `MyTextInput`. These components tend to be used throughout the application in a similar manner as a regular DOM button and input, and accessing their DOM nodes may be unavoidable for managing focus, selection, or animations.
+
+**Ref forwarding is an opt-in feature that lets some components take a ref they receive, and pass it further down (in other words, “forward” it) to a child.**
+
+In the example below, `FancyInput` uses `React.forwardRef` to obtain the ref passed to it, and then forward it to the DOM input that it renders:
+
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+// App.res
+
+module FancyInput = {
+  @react.component
+  let make = React.forwardRef((~className=?, ~children, ref_) =>
+    <div>
+      <input
+        type_="text"
+        ?className
+        ref=?{Js.Nullable.toOption(ref_)->Belt.Option.map(
+          ReactDOMRe.Ref.domRef,
+        )}
+      />
+      children
+    </div>
+  )
+}
+
+@bs.send external focus: Dom.element => unit = "focus"
+
+@react.component
+let make = () => {
+  let input = React.useRef(Js.Nullable.null)
+
+  let focusInput = () =>
+    input.current
+    ->Js.Nullable.toOption
+    ->Belt.Option.forEach(input => input->focus)
+
+  let onClick = _ => focusInput()
+
+  <div>
+    <FancyInput className="fancy" ref=input>
+      <button onClick> {React.string("Click to focus")} </button>
+    </FancyInput>
+  </div>
+}
+```
+
+```js
+var React = require("react");
+var Belt_Option = require("./stdlib/belt_Option.js");
+var Caml_option = require("./stdlib/caml_option.js");
+
+var make = React.forwardRef(function (Props, ref_) {
+      var className = Props.className;
+      var children = Props.children;
+      var tmp = {
+        type: "text"
+      };
+      var tmp$1 = Belt_Option.map((ref_ == null) ? undefined : Caml_option.some(ref_), (function (prim) {
+              return prim;
+            }));
+      if (tmp$1 !== undefined) {
+        tmp.ref = Caml_option.valFromOption(tmp$1);
+      }
+      if (className !== undefined) {
+        tmp.className = Caml_option.valFromOption(className);
+      }
+      return React.createElement("div", undefined, React.createElement("input", tmp), children);
+    });
+
+var FancyInput = {
+  make: make
+};
+
+function App(Props) {
+  var input = React.useRef(null);
+  var onClick = function (param) {
+    return Belt_Option.forEach(Caml_option.nullable_to_opt(input.current), (function (input) {
+                  input.focus();
+                  
+                }));
+  };
+  return React.createElement("div", undefined, React.createElement(make, {
+                  className: "fancy",
+                  children: React.createElement("button", {
+                        onClick: onClick
+                      }, "Click to focus"),
+                  ref: input
+                }));
+}
+```
+
+</CodeTab>
+
+**Note:** Our `@react.component` decorator transforms our labeled argument props within our `React.forwardRef` function in the same manner as our classic `make` function.
+
+This way, components using `FancyInput` can get a ref to the underlying `input` DOM node and access it if necessary—just like if they used a DOM `input` directly.
+
+## Note for Component Library Maintainers
+
+
+**When you start using forwardRef in a component library, you should treat it as a breaking change and release a new major version of your library**. This is because your library likely has an observably different behavior (such as what refs get assigned to, and what types are exported), and this can break apps and other libraries that depend on the old behavior.

pages/docs/react/latest/hooks-ref.mdx

@@ -0,0 +1,152 @@
+---
+title: useRef Hook
+description: "Details about the useRef React hook in ReScript"
+canonical: "/docs/react/latest/hooks-ref"
+category: "Hooks & State Management"
+---
+
+# useRef
+
+<Intro>
+
+The `useRef` hooks creates and manages mutable containers inside your React component.
+
+</Intro>
+
+## Usage
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let refContainer = React.useRef(initialValue);
+```
+
+```js
+  var button = React.useRef(null);
+  React.useRef(0);
+```
+
+</CodeTab>
+
+`React.useRef` returns a mutable ref object whose `.current` record field is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component.
+
+Essentially, a `React.ref` is like a "box" that can hold a mutable value in its `.current` record field.
+
+You might be familiar with refs primarily as a way to access the DOM. If you pass a ref object to React with `<div ref={ReactDOM.Ref.domRef(myRef)} />`, React will set its `.current` property to the corresponding DOM node whenever that node changes.
+
+However, `useRef()` is useful for more than the ref attribute. It's handy for keeping any mutable value around similar to how you’d use instance fields in classes.
+
+This works because `useRef()` creates a plain JavaScript object. The only difference between `useRef()` and creating a `{current: ...}` object yourself is that useRef will give you the same ref object on every render.
+
+
+Keep in mind that `useRef` doesn’t notify you when its content changes. Mutating the `.current` record field doesn’t cause a re-render. If you want to run some code when React attaches or detaches a ref to a DOM node, you may want to use a [callback ref](./refs-and-the-dom#callback-refs) instead.
+
+More infos on direct DOM manipulation can be found in the [Refs and the DOM](./refs-and-the-dom) section.
+
+## Examples
+
+### Managing Focus for a Text Input
+
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+// TextInputWithFocusButton.re
+
+@bs.send external focus: Dom.element => unit = "focus"
+
+@react.component
+let make = () => {
+  let inputEl = React.useRef(Js.Nullable.null)
+
+  let onClick = _ => {
+    inputEl.current
+    ->Js.Nullable.toOption
+    ->Belt.Option.forEach(input => input->focus)
+  }
+
+  <>
+    <input ref={ReactDOM.Ref.domRef(inputEl)} type_="text" />
+    <button onClick> {React.string("Focus the input")} </button>
+  </>
+}
+```
+
+```js
+function TextInputWithFocusButton(Props) {
+  var inputEl = React.useRef(null);
+  var onClick = function (param) {
+    return Belt_Option.forEach(Caml_option.nullable_to_opt(inputEl.current), (function (input) {
+                  input.focus();
+                  
+                }));
+  };
+  return React.createElement(React.Fragment, undefined, React.createElement("input", {
+                  ref: inputEl,
+                  type: "text"
+                }), React.createElement("button", {
+                  onClick: onClick
+                }, "Focus the input"));
+}
+```
+
+</CodeTab>
+
+### Using a Callback Ref
+
+Reusing the example from our [Refs and the DOM](./refs-and-the-dom#callback-refs) section:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+// CustomTextInput.re
+
+@bs.send external focus: Dom.element => unit = "focus"
+
+@react.component
+let make = () => {
+  let textInput = React.useRef(Js.Nullable.null)
+  let setTextInputRef = element => {
+    textInput.current = element;
+  }
+
+  let focusTextInput = _ => {
+    textInput.current
+    ->Js.Nullable.toOption
+    ->Belt.Option.forEach(input => input->focus)
+  }
+
+  <div>
+    <input type_="text" ref={ReactDOM.Ref.callbackDomRef(setTextInputRef)} />
+    <input
+      type_="button" value="Focus the text input" onClick={focusTextInput}
+    />
+  </div>
+}
+```
+
+```js
+function CustomTextInput(Props) {
+  var textInput = React.useRef(null);
+  var setTextInputRef = function (element) {
+    textInput.current = element;
+    
+  };
+  var focusTextInput = function (param) {
+    return Belt_Option.forEach(Caml_option.nullable_to_opt(textInput.current), (function (input) {
+                  input.focus();
+                  
+                }));
+  };
+  return React.createElement("div", undefined, React.createElement("input", {
+                  ref: setTextInputRef,
+                  type: "text"
+                }), React.createElement("input", {
+                  type: "button",
+                  value: "Focus the text input",
+                  onClick: focusTextInput
+                }));
+}
+```
+
+</CodeTab>