Merge remote-tracking branch 'docs/main'

Author: CodeStix

docs/.babelrc

@@ -0,0 +1,4 @@
+{
+    "presets": ["next/babel"],
+    "plugins": [["styled-components", { "ssr": true }]]
+  }

docs/.gitignore

@@ -0,0 +1,34 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

docs/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 4,
+  "useTabs": false,
+  "printWidth": 120
+}

docs/README.md

@@ -0,0 +1,33 @@
+This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+yarn dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
+
+[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`.
+
+The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.

docs/articles/Array-fields.md

@@ -0,0 +1,223 @@
+# Array fields
+
+To create dynamic array fields, you should use the [`ArrayForm`](/docs/ArrayForm) component or [`useArrayForm`](/docs/useArrayForm) hook. These are wrappers around [`useChildForm`](/docs/useChildForm) which provide useful functions and optimizations for arrays.
+
+-   [ArrayForm](/docs/ArrayForm)
+-   [useArrayForm](/docs/useArrayForm)
+
+If you have an array field with a constant size, you should probably just use [`ChildForm`](/docs/ChildForm). (See bottom for examples)
+
+**Note on keys**: you **should** use the index as key, this seems against nature at first, but remember that this library does not rerender each time something in the array changes. When 2 array items get swapped, it does not rerender either, only when the array size changes, it rerenders. For this reason, it is not a problem (and it's recommended) to use index as the key. (This can change in the future)
+
+## Dynamic array examples
+
+✔️ **Dynamic string array field using `ArrayForm`**
+
+```tsx
+function NotesList() {
+    const form = useForm({
+        notes: ["Do the dishes", "Go outside", "Drink some water"],
+    });
+    return (
+        <form
+            onSubmit={(ev) => {
+                ev.preventDefault();
+                console.log("submit", form.values);
+            }}
+        >
+            <ArrayForm
+                form={form}
+                name="notes"
+                render={({ form, values, append, remove }) => (
+                    <>
+                        {/* You SHOULD use index as key. See top for info. */}
+                        {values.map((_, i) => (
+                            <div key={i}>
+                                <FormInput form={form} name={i} />
+                                <button type="button" onClick={() => remove(i)}>
+                                    Remove
+                                </button>
+                            </div>
+                        ))}
+                        <button type="button" onClick={() => append("New note")}>
+                            Add note
+                        </button>
+                    </>
+                )}
+            />
+            <button>Submit</button>
+        </form>
+    );
+}
+```
+
+✔️ **Dynamic object array field using `ArrayForm`**
+
+Remember: this is all type checked!
+
+```tsx
+function ShoppingListForm() {
+    const form = useForm({
+        title: "My shopping list",
+        items: [{ name: "Coffee", amount: 1 }],
+    });
+
+    return (
+        <form
+            onSubmit={(ev) => {
+                ev.preventDefault();
+                console.log("submit", form.values);
+            }}
+        >
+            <h2>Title</h2>
+            <FormInput form={form} type="text" name="title" />
+
+            {/* Create an array child form for the 'items' field */}
+            <h2>Items</h2>
+            <ArrayForm
+                form={form}
+                name="items"
+                render={({ form, values, append, remove }) => (
+                    <>
+                        {/* This only rerenders when the whole array changes. */}
+
+                        {values.map((_, i) => (
+                            // Create a child form for each item in the array, because each array item is an object.
+                            <ChildForm
+                                key={i} // You should index as key
+                                form={form} // Pass the parent form
+                                name={i} // Pass the current index as the name
+                                render={(form) => (
+                                    <div>
+                                        {/* Everything here is type-checked! */}
+                                        <FormInput form={form} type="text" name="name" />
+                                        <FormInput form={form} type="number" name="amount" />
+                                        <button type="button" onClick={() => remove(i)}>
+                                            Remove
+                                        </button>
+                                    </div>
+                                )}
+                            />
+                        ))}
+
+                        {/* Use the append helper function to add an item to the array */}
+                        <button type="button" onClick={() => append({ name: "", amount: 1 })}>
+                            Add item
+                        </button>
+                    </>
+                )}
+            />
+            <button>Submit</button>
+        </form>
+    );
+}
+```
+
+✔️ **Dynamic object array field with seperate component for each child form and using `useArrayForm`**
+
+```tsx
+interface ShoppingListItem {
+    name: string;
+    amount: number;
+}
+interface ShoppingList {
+    title: string;
+    items: ShoppingListItem[];
+}
+
+function ShoppingListForm() {
+    const form =
+        useForm <
+        ShoppingList >
+        {
+            title: "My shopping list",
+            items: [{ name: "Coffee", amount: 1 }],
+        };
+    return (
+        <form
+            onSubmit={(ev) => {
+                ev.preventDefault();
+                console.log("submit", form.values);
+            }}
+        >
+            <h2>Title</h2>
+            <FormInput form={form} type="text" name="title" />
+            <h2>Items</h2>
+            <ShoppingListItemsForm parent={form} />
+            <button>Submit</button>
+        </form>
+    );
+}
+
+function ShoppingListItemsForm(props: { parent: FormState<ShoppingList> }) {
+    const { form, values, append, remove } = useArrayForm(props.parent, "items");
+    // This component only rerenders when the whole array changes.
+    return (
+        <>
+            {values.map((_, i) => (
+                <ShoppingListItemForm parent={form} index={i} key={i} remove={remove} />
+            ))}
+            <button type="button" onClick={() => append({ name: "", amount: 1 })}>
+                Add item
+            </button>
+        </>
+    );
+}
+
+function ShoppingListItemForm(props: {
+    parent: FormState<ShoppingListItem[]>;
+    index: number;
+    remove: (i: number) => void;
+}) {
+    const form = useChildForm(props.parent, props.index);
+    return (
+        <div>
+            <FormInput form={form} type="text" name="name" />
+            <FormInput form={form} type="number" name="amount" />
+            <button type="button" onClick={() => props.remove(props.index)}>
+                Remove
+            </button>
+        </div>
+    );
+}
+```
+
+## Fixed array example
+
+A fixed array always has the same size, [`ChildForm`](/docs/ChildForm) is used, and the index into the array is given using the name prop.
+
+✔️ **Fixed array field containing strings**
+
+```tsx
+function AnswerForm() {
+    const form = useForm({
+        // Always 3 items in array
+        answers: ["", "", ""],
+    });
+    return (
+        <form
+            onSubmit={(ev) => {
+                ev.preventDefault();
+                console.log("submit", form.values);
+            }}
+        >
+            <ChildForm
+                parent={form}
+                name="answers"
+                render={(form) => (
+                    <div>
+                        {/* Use array index as field name */}
+                        <p>Answer 1</p>
+                        <FormInput form={form} name={0} type="text" />
+                        <p>Answer 2</p>
+                        <FormInput form={form} name={1} type="text" />
+                        <p>Answer 3</p>
+                        <FormInput form={form} name={2} type="text" />
+                    </div>
+                )}
+            />
+            <button>Submit</button>
+        </form>
+    );
+}
+```

docs/articles/ArrayForm.md

@@ -0,0 +1,35 @@
+# ArrayForm
+
+A component that provides array manipulation functions and optimizations. This is a wrapper around [`useArrayForm`](/docs/useArrayForm). The only difference is that this component does not render its content when the array is null/undefined ([is togglable](/docs/Toggling-a-field)).
+
+## Props
+
+#### `form` **(required)**
+
+The parent form which contains the array field to create a array child form for.
+
+#### `name` **(required)**
+
+The name of the array field in the parent form.
+
+#### `render` **(required)**
+
+A function that renders the array.
+
+The render function provides an object parameter, containing the following fields:
+
+-   `form`: The child form associated with this array. Pass this to this child forms and input elements.
+-   `values`: The array, you should `{map((e) => ...)}` this.
+-   `setValues(values)`: A function to update all the array values at once.
+
+**The object also contains helper functions to quickly manipulate the array field:**
+
+-   `remove(index)`: Function that removes a specific item at index in the array.
+-   `clear()`: Function that clears the array.
+-   `move(from, to)`: Function that moves an item in the array
+-   `swap(index, newIndex)`: Function that swaps 2 items in the array.
+-   `append(value)`: Function that appends an item to the end of the array.
+
+## Usage
+
+See [Array fields](/docs/Array-fields).

docs/articles/Auto-disable-submit-button.md

@@ -0,0 +1,30 @@
+## Example: Submit button that disables when unmodified/error
+
+![live updating form values](https://raw.githubusercontent.com/wiki/CodeStix/typed-react-form/images/submitbutton.gif)
+
+```tsx
+function FormExample() {
+    const form = useForm(
+        {
+            name: "John",
+        },
+        (values) => ({
+            // Example validator
+            name: values.name.length < 3 ? "Name must be longer" : undefined,
+        })
+    );
+    return (
+        <form
+            onSubmit={(ev) => {
+                ev.preventDefault();
+                console.log("save", form.values);
+                form.setDefaultValues(form.values);
+            }}
+        >
+            <FormInput form={form} name="name" />
+            {/* Listen for any change on the form */}
+            <AnyListener form={form} render={(form) => <button disabled={!form.dirty || form.error}>Save</button>} />
+        </form>
+    );
+}
+```

docs/articles/ChildForm.md

@@ -0,0 +1,23 @@
+# ChildForm
+
+Use the `ChildForm` component if you want to make fields inside an object field available to inputs. This is a wrapper around [`useChildForm`](/docs/useChildForm).
+
+## Props
+
+#### `form` (required)
+
+The parent form which contains the object field to create a child form for.
+
+#### `name` (required)
+
+The name of the field in the parent form to create
+
+#### `render` (required)
+
+A function that renders, and creates inputs for the child form, which is passed as a parameter.
+
+## Advanced
+
+You can also use this component on array fields (index as name), but [`ArrayForm`](/docs/ArrayForm) or [`useArrayForm`](/docs/useArrayForm) is preferred when you want to create [dynamic array fields](/docs/Array-fields). It provides useful array manipulation functions and optimizations.
+
+This component does not render its content when the form is empty (happens when its parent field has been assigned `null`, `undefined` or `{}`).