From a68b1b242a0e8e4c59daf3218e787b86fa1d497e Mon Sep 17 00:00:00 2001
From: Ryan Christian <33403762+rschristian@users.noreply.github.com>
Date: Thu, 2 Jan 2025 14:22:03 -0600
Subject: [PATCH] refactor: Rewrite Forms doc (#1218)

---
 content/en/guide/v10/forms.md                 | 411 ++++++++++++++----
 .../controllers/repl/examples/style.css       |   6 +
 2 files changed, 331 insertions(+), 86 deletions(-)

diff --git a/content/en/guide/v10/forms.md b/content/en/guide/v10/forms.md
index bcb9b8012..6fdd02d6f 100755
--- a/content/en/guide/v10/forms.md
+++ b/content/en/guide/v10/forms.md
@@ -1,13 +1,11 @@
 ---
 name: Forms
-description: 'How to build awesome forms in Preact that work anywhere.'
+description: 'Forms and form controls allow you to collect user input in your application and is a fundamental building block of most web applications.'
 ---
 
 # Forms
 
-Forms in Preact work much the same as they do in HTML. You render a control, and attach an event listener to it.
-
-The main difference is that in most cases the `value` is not controlled by the DOM node, but by Preact.
+Forms in Preact work in the same way as they do in HTML & JS: you render controls, attach event listeners, and submit information.
 
 ---
 
@@ -15,100 +13,161 @@ The main difference is that in most cases the `value` is not controlled by the D
 
 ---
 
-## Controlled & Uncontrolled Components
+## Basic Form Controls
+
+Often you'll want to collect user input in your application, and this is where `<input>`, `<textarea>`, and `<select>` elements come in. These elements are the common building blocks of forms in HTML and Preact.
 
-When talking about form controls you'll often encounter the words "Controlled Component" and "Uncontrolled Component". The description refers to the way data flow is handled.
+### Input (text)
 
-The DOM has a bidirectional data flow, because every form control will manage the user input themselves. A simple text input will always update its value when a user typed into it. In contrast, a framework like Preact generally has a unidirectional data flow; the component doesn't manage the value itself there, but something else higher up in the component tree.
+To get started, we'll create a simple text input field that will update a state value as the user types. We'll use the `onInput` event to listen for changes to the input field's value and update the state per-keystroke. This state value is then rendered in a `<p>` element, so we can see the results.
 
-Generally, you should try to use _Uncontrolled_ Components whenever possible, the DOM is fully capable of handling `<input>`'s state:
+<tab-group tabstring="Classes, Hooks">
 
 ```jsx
-// Uncontrolled, because Preact doesn't set the value
-<input onInput={myEventHandler} />;
-```
+// --repl
+import { render, Component } from "preact";
+// --repl-before
+class BasicInput extends Component {
+  state = { name: '' };
 
-However, there are situations in which you might need to exert tighter control over the input value, in which case, _Controlled_ Components can be used.
+  onInput = e => this.setState({ name: e.currentTarget.value });
 
-To use controlled components in Preact, you will need to use [`refs`](/guide/v10/refs) to bridge the inherent gap between the DOM state and VDOM/Preact's state. Here's an example of how you might use a controlled component to limit the number of characters in an input field:
+  render(_, { name }) {
+    return (
+      <div class="form-example">
+        <label>
+          Name:{' '}
+          <input onInput={this.onInput} />
+        </label>
+        <p>Hello {name}</p>
+      </div>
+    );
+  }
+}
+// --repl-after
+render(<BasicInput />, document.getElementById("app"));
+```
 
 ```jsx
 // --repl
 import { render } from "preact";
-import { useState, useRef } from "preact/hooks";
+import { useState } from "preact/hooks";
 // --repl-before
-const Input = () => {
-  const [value, setValue] = useState('')
-  const inputRef = useRef()
-
-  const onInput = (e) => {
-    if (e.currentTarget.value.length <= 3) {
-      setValue(e.currentTarget.value)
-    } else {
-      const start = inputRef.current.selectionStart
-      const end = inputRef.current.selectionEnd
-      const diffLength = Math.abs(e.currentTarget.value.length - value.length)
-      inputRef.current.value = value
-      // Restore selection
-      inputRef.current.setSelectionRange(start - diffLength, end - diffLength)
-    }
-  }
+function BasicInput() {
+  const [name, setName] = useState('');
 
   return (
-	<>
-	  <label>This input is limited to 3 characters: </label>
-	  <input ref={inputRef} value={value} onInput={onInput} />
-	</>
+    <div class="form-example">
+      <label>
+        Name:{' '}
+        <input onInput={(e) => setName(e.currentTarget.value)} />
+      </label>
+      <p>Hello {name}</p>
+    </div>
   );
 }
 // --repl-after
-render(<Input />, document.getElementById("app"));
+render(<BasicInput />, document.getElementById("app"));
 ```
 
-> For more information on controlled components in Preact, see [Controlled Inputs](https://www.jovidecroock.com/blog/controlled-inputs) by Jovi De Croock.
+</tab-group>
 
-## Creating A Simple Form
+### Input (checkbox & radio)
 
-Let's create a simple form to submit todo items. For this we create a `<form>`-Element and bind an event handler that is called whenever the form is submitted. We do a similar thing for the text input field, but note that we are storing the value in our class ourselves. You guessed it, we're using a _controlled_ input here. In this example it's very useful, because we need to display the input's value in another element.
+<tab-group tabstring="Classes, Hooks">
 
 ```jsx
 // --repl
 import { render, Component } from "preact";
 // --repl-before
-class TodoForm extends Component {
-  state = { value: '' };
-
-  onSubmit = e => {
-    alert("Submitted a todo");
-    e.preventDefault();
-  }
+class BasicRadioButton extends Component {
+  state = {
+    allowContact: false,
+    contactMethod: ''
+  };
 
-  onInput = e => {
-    this.setState({ value: e.currentTarget.value })
-  }
+  toggleContact = () => this.setState({ allowContact: !this.state.allowContact });
+  setRadioValue = e => this.setState({ contactMethod: e.currentTarget.value });
 
-  render(_, { value }) {
+  render(_, { allowContact }) {
     return (
-      <form onSubmit={this.onSubmit}>
-        <input type="text" value={value} onInput={this.onInput} />
-        <p>You typed this value: {value}</p>
-        <button type="submit">Submit</button>
-      </form>
+      <div class="form-example">
+        <label>
+          Allow contact:{' '}
+          <input type="checkbox" onClick={this.toggleContact} />
+        </label>
+        <label>
+          Phone:{' '}
+          <input type="radio" name="contact" value="phone" onClick={this.setRadioValue} disabled={!allowContact} />
+        </label>
+        <label>
+          Email:{' '}
+          <input type="radio" name="contact" value="email" onClick={this.setRadioValue} disabled={!allowContact} />
+        </label>
+        <label>
+          Mail:{' '}
+          <input type="radio" name="contact" value="mail" onClick={this.setRadioValue} disabled={!allowContact} />
+        </label>
+        <p>
+          You {allowContact ? 'have allowed' : 'have not allowed'} contact {allowContact && ` via ${this.state.contactMethod}`}
+        </p>
+      </div>
     );
   }
 }
 // --repl-after
-render(<TodoForm />, document.getElementById("app"));
+render(<BasicRadioButton />, document.getElementById("app"));
 ```
 
-## Select Input
+```jsx
+// --repl
+import { render } from "preact";
+import { useState } from "preact/hooks";
+// --repl-before
+function BasicRadioButton() {
+  const [allowContact, setAllowContact] = useState(false);
+  const [contactMethod, setContactMethod] = useState('');
 
-A `<select>`-Element is a little more involved, but works similar to all other form controls:
+  const toggleContact = () => setAllowContact(!allowContact);
+  const setRadioValue = (e) => setContactMethod(e.currentTarget.value);
+
+  return (
+    <div class="form-example">
+      <label>
+        Allow contact:{' '}
+        <input type="checkbox" onClick={toggleContact} />
+      </label>
+      <label>
+        Phone:{' '}
+        <input type="radio" name="contact" value="phone" onClick={setRadioValue} disabled={!allowContact} />
+      </label>
+      <label>
+        Email:{' '}
+        <input type="radio" name="contact" value="email" onClick={setRadioValue} disabled={!allowContact} />
+      </label>
+      <label>
+        Mail:{' '}
+        <input type="radio" name="contact" value="mail" onClick={setRadioValue} disabled={!allowContact} />
+      </label>
+      <p>
+        You {allowContact ? 'have allowed' : 'have not allowed'} contact {allowContact && ` via ${contactMethod}`}
+      </p>
+    </div>
+  );
+}
+// --repl-after
+render(<BasicRadioButton />, document.getElementById("app"));
+```
+
+</tab-group>
+
+### Select
+
+<tab-group tabstring="Classes, Hooks">
 
 ```jsx
 // --repl
 import { render, Component } from "preact";
-
 // --repl-before
 class MySelect extends Component {
   state = { value: '' };
@@ -117,21 +176,16 @@ class MySelect extends Component {
     this.setState({ value: e.currentTarget.value });
   }
 
-  onSubmit = e => {
-    alert("Submitted " + this.state.value);
-    e.preventDefault();
-  }
-
   render(_, { value }) {
     return (
-      <form onSubmit={this.onSubmit}>
-        <select value={value} onChange={this.onChange}>
+      <div class="form-example">
+        <select onChange={this.onChange}>
           <option value="A">A</option>
           <option value="B">B</option>
           <option value="C">C</option>
         </select>
-        <button type="submit">Submit</button>
-      </form>
+        <p>You selected: {value}</p>
+      </div>
     );
   }
 }
@@ -139,39 +193,224 @@ class MySelect extends Component {
 render(<MySelect />, document.getElementById("app"));
 ```
 
-## Checkboxes & Radio Buttons
+```jsx
+// --repl
+import { render } from "preact";
+import { useState } from "preact/hooks";
+// --repl-before
+function MySelect() {
+  const [value, setValue] = useState('');
+
+  return (
+    <div class="form-example">
+      <select onChange={(e) => setValue(e.currentTarget.value)}>
+        <option value="A">A</option>
+        <option value="B">B</option>
+        <option value="C">C</option>
+      </select>
+      <p>You selected: {value}</p>
+    </form>
+  );
+}
+// --repl-after
+render(<MySelect />, document.getElementById("app"));
+```
+
+</tab-group>
 
-Checkboxes and radio buttons (`<input type="checkbox|radio">`) can initially cause confusion when building controlled forms. This is because in an uncontrolled environment, we would typically allow the browser to "toggle" or "check" a checkbox or radio button for us, listening for a change event and reacting to the new value.  However, this technique does not transition well into a world view where the UI is always updated automatically in response to state and prop changes.
+## Basic Forms
 
-> **Walk-Through:** Say we listen for a "change" event on a checkbox, which is fired when the checkbox is checked or unchecked by the user.  In our change event handler, we set a value in `state` to the new value received from the checkbox.  Doing so will trigger a re-render of our component, which will re-assign the value of the checkbox to the value from state.  This is unnecessary, because we just asked the DOM for a value but then told it to render again with whatever value we wanted.
+Whilst bare inputs are useful and you can get far with them, often we'll see our inputs grow into _forms_ that are capable of grouping multiple controls together. To help manage this, we turn to the `<form>` element.
 
-So, instead of listening for a `input` event we should listen for a `click` event, which is fired any time the user clicks on the checkbox _or an associated `<label>`_.  Checkboxes just toggle between Boolean `true` and `false`, so clicking the checkbox or the label, we'll just invert whatever value we have in state, triggering a re-render, setting the checkbox's displayed value to the one we want.
+To demonstrate, we'll create a new `<form>` element that contains two `<input>` fields: one for a user's first name and one for their last name. We'll use the `onSubmit` event to listen for the form submission and update the state with the user's full name.
 
-### Checkbox Example
+<tab-group tabstring="Classes, Hooks">
 
 ```jsx
 // --repl
 import { render, Component } from "preact";
 // --repl-before
-class MyForm extends Component {
-  toggle = e => {
-      let checked = !this.state.checked;
-      this.setState({ checked });
+class FullNameForm extends Component {
+  state = { fullName: '' };
+
+  onSubmit = e => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    this.setState({
+      fullName: formData.get("firstName") + " " + formData.get("lastName")
+    });
+    e.currentTarget.reset(); // Clear the inputs to prepare for the next submission
+  }
+
+  render(_, { fullName }) {
+    return (
+      <div class="form-example">
+        <form onSubmit={this.onSubmit}>
+          <label>
+            First Name:{' '}
+            <input name="firstName" />
+          </label>
+          <label>
+            Last Name:{' '}
+            <input name="lastName" />
+          </label>
+          <button>Submit</button>
+        </form>
+        {fullName && <p>Hello {fullName}</p>}
+      </div>
+    );
+  }
+}
+// --repl-after
+render(<FullNameForm />, document.getElementById("app"));
+```
+
+```jsx
+// --repl
+import { render } from "preact";
+import { useState } from "preact/hooks";
+// --repl-before
+function FullNameForm() {
+  const [fullName, setFullName] = useState("");
+
+  const onSubmit = (e) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    setFullName(formData.get("firstName") + " " + formData.get("lastName"));
+    e.currentTarget.reset(); // Clear the inputs to prepare for the next submission
   };
 
-  render(_, { checked }) {
+  return (
+    <div class="form-example">
+      <form onSubmit={onSubmit}>
+        <label>
+          First Name:{' '}
+          <input name="firstName" />
+        </label>
+        <label>
+          Last Name:{' '}
+          <input name="lastName" />
+        </label>
+        <button>Submit</button>
+      </form>
+      {fullName && <p>Hello {fullName}</p>}
+    </div>
+  );
+}
+
+// --repl-after
+render(<FullNameForm />, document.getElementById("app"));
+```
+
+</tab-group>
+
+> **Note**: Whilst it's quite common to see React & Preact forms that link every input field to component state, it's often unnecessary and can get unwieldy. As a very loose rule of thumb, you should prefer using `onSubmit` and the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API in most cases, using component state only when you need to. This reduces the complexity of your components and may skip unnecessary rerenders.
+
+## Controlled & Uncontrolled Components
+
+When talking about form controls you may encounter the terms "Controlled Component" and "Uncontrolled Component". These terms refer to whether or not the form control value is explicitly managed by the component. Generally, you should try to use _Uncontrolled_ Components whenever possible, the DOM is fully capable of handling `<input>`'s state:
+
+```jsx
+// Uncontrolled, because Preact doesn't set the value
+<input onInput={myEventHandler} />;
+```
+
+However, there are situations in which you might need to exert tighter control over the input value, in which case, _Controlled_ Components can be used.
+
+```jsx
+// Controlled, because Preact sets the value
+<input value={myValue} onInput={myEventHandler} />;
+```
+
+Preact has a known issue with controlled components: rerenders are required for Preact to exert control over input values. This means that if your event handler doesn't update state or trigger a rerender in some fashion, the input value will not be controlled, sometimes becoming out-of-sync with component state.
+
+An example of one of these problematic situations is as such: say you have an input field that should be limited to 3 characters. You may have an event handler like the following:
+
+```js
+const onInput = (e) => {
+  if (e.currentTarget.value.length <= 3) {
+    setValue(e.currentTarget.value);
+  }
+}
+```
+
+The problem with this is in the cases where the input fails that condition: because we don't run `setValue`, the component doesn't rerender, and because the component doesn't rerender, the input value is not correctly controlled. However, even if we did add a `else { setValue(value) }` to that handler, Preact is smart enough to detect when the value hasn't changed and so it will not rerender the component. This leaves us with [`refs`](/guide/v10/refs) to bridge the gap between the DOM state and Preact's state.
+
+> For more information on controlled components in Preact, see [Controlled Inputs](https://www.jovidecroock.com/blog/controlled-inputs) by Jovi De Croock.
+
+Here's an example of how you might use a controlled component to limit the number of characters in an input field:
+
+<tab-group tabstring="Classes, Hooks">
+
+```jsx
+// --repl
+import { render, Component, createRef } from "preact";
+// --repl-before
+class LimitedInput extends Component {
+  state = { value: '' }
+  inputRef = createRef(null)
+
+  onInput = (e) => {
+    if (e.currentTarget.value.length <= 3) {
+      this.setState({ value: e.currentTarget.value });
+    } else {
+      const start = this.inputRef.current.selectionStart;
+      const end = this.inputRef.current.selectionEnd;
+      const diffLength = Math.abs(e.currentTarget.value.length - this.state.value.length);
+      this.inputRef.current.value = this.state.value;
+      // Restore selection
+      this.inputRef.current.setSelectionRange(start - diffLength, end - diffLength);
+    }
+  }
+
+  render(_, { value }) {
     return (
-      <label>
-        <input
-          type="checkbox"
-          checked={checked}
-          onClick={this.toggle}
-        />
-        check this box
-      </label>
+      <div class="form-example">
+        <label>
+          This input is limited to 3 characters:{' '}
+          <input ref={this.inputRef} value={value} onInput={this.onInput} />
+        </label>
+      </div>
     );
   }
 }
 // --repl-after
-render(<MyForm />, document.getElementById("app"));
+render(<LimitedInput />, document.getElementById("app"));
+```
+
+```jsx
+// --repl
+import { render } from "preact";
+import { useState, useRef } from "preact/hooks";
+// --repl-before
+const LimitedInput = () => {
+  const [value, setValue] = useState('');
+  const inputRef = useRef();
+
+  const onInput = (e) => {
+    if (e.currentTarget.value.length <= 3) {
+      setValue(e.currentTarget.value);
+    } else {
+      const start = inputRef.current.selectionStart;
+      const end = inputRef.current.selectionEnd;
+      const diffLength = Math.abs(e.currentTarget.value.length - value.length);
+      inputRef.current.value = value;
+      // Restore selection
+      inputRef.current.setSelectionRange(start - diffLength, end - diffLength);
+    }
+  }
+
+  return (
+    <div class="form-example">
+      <label>
+        This input is limited to 3 characters:{' '}
+        <input ref={inputRef} value={value} onInput={onInput} />
+      </label>
+    </div>
+  );
+}
+// --repl-after
+render(<LimitedInput />, document.getElementById("app"));
 ```
+
+</tab-group>
diff --git a/src/components/controllers/repl/examples/style.css b/src/components/controllers/repl/examples/style.css
index 443e5ee0a..94fa673e4 100644
--- a/src/components/controllers/repl/examples/style.css
+++ b/src/components/controllers/repl/examples/style.css
@@ -68,3 +68,9 @@
 	left: 0;
 	top: 0;
 }
+
+/* Used in examples throughout our docs */
+.form-example label {
+	display: block;
+	margin: 0.5rem 0;
+}