Merge branch 'main' into rc-baremetal-mega

.yarnrc.yml

@@ -16,4 +16,4 @@ plugins:
 
 preferInteractive: true
 
-yarnPath: .yarn/releases/yarn-3.2.0.cjs
+yarnPath: .yarn/releases/yarn-3.2.1.cjs

README.md

@@ -653,6 +653,17 @@ And there you have it.
     <td align="center"><a href="https://github.com/zzyyxxww"><img src="https://avatars.githubusercontent.com/u/4072352?v=4" width="100px;" alt=""/><br /><sub><b>hello there</b></sub></a></td>
     <td align="center"><a href="https://github.com/llmaboi"><img src="https://avatars.githubusercontent.com/u/34942041?v=4" width="100px;" alt=""/><br /><sub><b>llmaboi</b></sub></a></td>
   </tr>
+  <tr>
+    <td align="center"><a href="http://www.finesoft.net/"><img src="https://avatars.githubusercontent.com/u/3767680?v=4" width="100px;" alt=""/><br /><sub><b>Changsoon Bok</b></sub></a></td>
+    <td align="center"><a href="https://github.com/merceyz"><img src="https://avatars.githubusercontent.com/u/3842800?v=4" width="100px;" alt=""/><br /><sub><b>Kristoffer K.</b></sub></a></td>
+    <td align="center"><a href="http://www.creativesoapbox.com/"><img src="https://avatars.githubusercontent.com/u/940266?v=4" width="100px;" alt=""/><br /><sub><b>Justin Kuntz</b></sub></a></td>
+    <td align="center"><a href="https://github.com/paineleffler"><img src="https://avatars.githubusercontent.com/u/9116535?v=4" width="100px;" alt=""/><br /><sub><b>Paine Leffler</b></sub></a></td>
+    <td align="center"><a href="https://github.com/pvenable"><img src="https://avatars.githubusercontent.com/u/590685?v=4" width="100px;" alt=""/><br /><sub><b>Paul Venable</b></sub></a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/PeterChen1997/MyBlog/issues"><img src="https://avatars.githubusercontent.com/u/21072589?v=4" width="100px;" alt=""/><br /><sub><b>Peter Chen</b></sub></a></td>
+    <td align="center"><a href="https://github.com/YannBirba"><img src="https://avatars.githubusercontent.com/u/66469030?v=4" width="100px;" alt=""/><br /><sub><b>Yann</b></sub></a></td>
+  </tr>
 </table>
 
 <!-- markdownlint-restore -->

__fixtures__/test-project/.yarnrc.yml

@@ -6,4 +6,4 @@ nmMode: hardlinks-local
 
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-3.2.0.cjs
+yarnPath: .yarn/releases/yarn-3.2.1.cjs

__fixtures__/test-project/api/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "dependencies": {
-    "@redwoodjs/api": "1.3.2",
-    "@redwoodjs/graphql-server": "1.3.2"
+    "@redwoodjs/api": "1.4.1",
+    "@redwoodjs/graphql-server": "1.4.1"
   }
 }

__fixtures__/test-project/package.json

@@ -8,7 +8,7 @@
     ]
   },
   "devDependencies": {
-    "@redwoodjs/core": "1.3.2",
+    "@redwoodjs/core": "1.4.1",
     "autoprefixer": "^10.4.4",
     "postcss": "^8.4.12",
     "postcss-loader": "^6.2.1",
@@ -28,5 +28,8 @@
   "scripts": {
     "postinstall": ""
   },
-  "packageManager": "[email protected]"
+  "packageManager": "[email protected]",
+  "resolutions": {
+    "glob": "7.2.3"
+  }
 }

__fixtures__/test-project/web/package.json

@@ -13,10 +13,10 @@
     ]
   },
   "dependencies": {
-    "@redwoodjs/auth": "1.3.2",
-    "@redwoodjs/forms": "1.3.2",
-    "@redwoodjs/router": "1.3.2",
-    "@redwoodjs/web": "1.3.2",
+    "@redwoodjs/auth": "1.4.1",
+    "@redwoodjs/forms": "1.4.1",
+    "@redwoodjs/router": "1.4.1",
+    "@redwoodjs/web": "1.4.1",
     "prop-types": "15.8.1",
     "react": "17.0.2",
     "react-dom": "17.0.2"

docs/docs/cli-commands.md

@@ -37,6 +37,29 @@ yarn redwood build [side..]
 
 The `..` operator indicates that the argument accepts an array of values. See [Variadic Positional Arguments](https://github.com/yargs/yargs/blob/master/docs/advanced.md#variadic-positional-arguments).
 
+## create redwood-app
+
+Create a Redwood project using the yarn create command:
+
+```
+yarn create redwood-app <project directory> [option]
+```
+
+| Arguments & Options    | Description                                                                                                             |
+| :--------------------- | :---------------------------------------------------------------------------------------------------------------------- |
+| `project directory`    | Specify the project directory [Required]                                                                                |
+| `--yarn-install`       | Enables the yarn install step and version-requirement checks. You can pass `--no-yarn-install` to disable this behavior |
+| `--typescript`, `--ts` | Generate a TypeScript project. JavaScript by default                                                                    |
+| `--overwrite`          | Create the project even if the specified project directory isn't empty                                                  |
+| `--no-telemetry`       | Disable sending telemetry events for this create command and all Redwood CLI commands: https://telemetry.redwoodjs.com  |
+| `--yarn1`              | Use yarn 1 instead of yarn 3                                                                                            |
+
+If you run into trouble during the yarn install step, which may happen if you're developing on an external drive and in other miscellaneous scenarios, try the `--yarn1` flag:
+
+```
+yarn create redwood-app my-redwood-project --yarn1
+```
+
 ## build
 
 Build for production.

docs/docs/graphql.md

@@ -585,6 +585,47 @@ type Mutation {
 }
 ```
 
+## Unions
+
+Unions are abstract GraphQL types that enable a schema field to return one of multiple object types.
+
+`union FavoriteTree = Redwood | Ginkgo | Oak`
+
+A field can have a union as its return type.
+
+```tsx
+type Query {
+  searchTrees: [FavoriteTree] // This list can include Redwood, Gingko or Oak objects
+}
+```
+
+All of a union's included types must be object types and do not need to share any fields.
+
+To query a union, you can take advantage on [inline fragments](https://graphql.org/learn/queries/#inline-fragments) to include subfields of multiple possible types.
+
+```tsx
+query GetFavoriteTrees {
+  __typename // typename is helpful when querying a field that returns one of multiple types
+  searchTrees {
+    ... on Redwood {
+      name
+      height
+    }
+    ... on Ginkgo {
+      name
+      medicalUse
+    }
+    ... on Oak {
+      name
+      acornType
+    }
+  }
+}
+```
+
+Redwood will automatically detect your union types in your `sdl` files and resolve *which* of your union's types is being returned. If the returned object does not match any of the valid types, the associated operation will produce a GraphQL error.
+
+
 ### GraphQL Handler Setup
 
 Redwood makes it easy to code, organize, and map your directives into the GraphQL schema.

docs/docs/testing.md

@@ -253,7 +253,118 @@ describe('Article', () => {
 
 This test (if it worked) would prove that you are indeed rendering an article. But it's also extremely brittle: any change to the component, even adding a `className` attribute for styling, will cause the test to break. That's not ideal, especially when you're just starting out building your components and will constantly be making changes as you improve them.
 
-> Why do we keep saying this test won't work? Because as far as we can tell there's no easy way to simply render to a string. `render` actually returns an object that has several functions for testing different parts of the output. Those are what we'll look into in the next section.
+:::info Why do we keep saying this test won't work?
+Because as far as we can tell there's no easy way to simply render to a string. `render` actually returns an object that has several functions for testing different parts of the output. Those are what we'll look into in the next section.
+
+Note that Redwood's `render` function is based on React Testing Library's. The only difference is that Redwood's wraps everything with mock providers for the various providers in Redwood, such as auth, the GraphQL client, the router, etc.
+
+If you were to use React Testing Library's `render` function, you'd need to provide your own wrapper function. In this case you probably want to compose the mock providers from `@redwoodjs/testing/web`:
+
+```jsx
+import { render, MockProviders } from '@redwoodjs/testing/web'
+
+// ...
+
+render(<Article article={ title: 'Foobar' } />, {
+  wrapper: ({ children }) => (
+    <MockProviders>
+      <MyCustomProvider>{children}</MyCustomProvider>
+    </MockProviders>
+  )
+})
+```
+:::
+
+## Testing Custom Hooks
+
+Custom hooks are a great way to encapsulate non-presentational code.
+To test custom hooks, we'll use the `renderHook` function from `@redwoodjs/testing/web`.
+
+:::info
+Note that Redwood's `renderHook` function is based on React Testing Library's. The only difference is that Redwood's wraps everything with mock providers for the various providers in Redwood, such as auth, the GraphQL client, the router, etc.
+
+If you were to use React Testing Library's `renderHook` function, you'd need to provide your own wrapper function. In this case you probably want to compose the mock providers from `@redwoodjs/testing/web`:
+
+```jsx
+import { renderHook, MockProviders } from '@redwoodjs/testing/web'
+
+// ...
+
+renderHook(() => myCustomHook(), {
+  wrapper: ({ children }) => (
+    <MockProviders>
+      <MyCustomProvider>{children}</MyCustomProvider>
+    </MockProviders>
+  )
+})
+```
+:::
+
+To use `renderHook`:
+1. Call your custom hook from an inline function passed to `renderHook`. For example:
+```js
+const { result } = renderHook(() => useAccumulator(0))
+```
+2. `renderHook` will return an object with the following properties:
+- `result`: holds the return value of the hook in its `current` property (so `result.current`). Think of `result` as a `ref` for the most recently returned value
+- `rerender`: a function to render the previously rendered hook with new props
+
+Let's go through an example. Given the following custom hook:
+
+```js title="web/src/hooks/useAccumulator/useAccumulator.js"
+const useAccumulator = (initialValue) => {
+  const [total, setTotal] = useState(initialValue)
+
+  const add = (value) => {
+    const newTotal = total + value
+    setTotal(newTotal)
+    return newTotal
+  }
+
+  return { total, add }
+}
+```
+
+The test could look as follows:
+
+```js title="web/src/hooks/useAccumulator/useAccumulator.test.js"
+import { renderHook } from '@redwoodjs/testing/web'
+import { useAccumulator } from './useAccumulator'
+
+describe('useAccumulator hook example in docs', () => {
+  it('has the correct initial state', () => {
+    const { result } = renderHook(() => useAccumulator(42))
+    expect(result.current.total).toBe(42)
+  })
+
+  it('adds a value', () => {
+    const { result } = renderHook(() => useAccumulator(1))
+    result.current.add(5)
+    expect(result.current.total).toBe(6)
+  })
+
+  it('adds multiple values', () => {
+    const { result } = renderHook(() => useAccumulator(0))
+    result.current.add(5)
+    result.current.add(10)
+    expect(result.current.total).toBe(15)
+  })
+
+  it('re-initializes the accumulator if passed a new initilizing value', () => {
+    const { result, rerender } = renderHook(
+      (initialValue) => useAccumulator(initialValue),
+      {
+        initialProps: 0,
+      }
+    )
+    result.current.add(5)
+    rerender(99)
+    expect(result.current.total).toBe(99)
+  })
+})
+```
+
+While `renderHook` lets you test a custom hook directly, there are cases where encapsulating the custom hook in a component is more robust. See https://kentcdodds.com/blog/how-to-test-custom-react-hooks.
 
 ### Queries
 

docs/docs/tutorial/chapter3/forms.md

@@ -1236,7 +1236,9 @@ And notice that if you fill in something in a field that's marked as an error, t
 
 ### Validating Input Format
 
-We should make sure the email field actually contains an email:
+We should make sure the email field actually contains an email, by providing a `pattern`.
+This is definitely not the end-all-be-all for email address validation, but for now let us pretend it's bulletproof.
+Let's also change the message on the email validation to be a little more friendly:
 
 <Tabs groupId="js-ts">
 <TabItem value="js" label="JavaScript">
@@ -1249,6 +1251,7 @@ We should make sure the email field actually contains an email:
     // highlight-start
     pattern: {
       value: /^[^@]+@[^.]+\..+$/,
+      message: 'Please enter a valid email address',
     },
     // highlight-end
   }}
@@ -1267,49 +1270,9 @@ We should make sure the email field actually contains an email:
     // highlight-start
     pattern: {
       value: /^[^@]+@[^.]+\..+$/,
-    },
-    // highlight-end
-  }}
-  errorClassName="error"
-/>
-```
-
-</TabItem>
-</Tabs>
-
-That is definitely not the end-all-be-all for email address validation, but pretend it's bulletproof. Let's also change the message on the email validation to be a little more friendly:
-
-<Tabs groupId="js-ts">
-<TabItem value="js" label="JavaScript">
-
-```jsx title="web/src/pages/ContactPage/ContactPage.js"
-<TextField
-  name="email"
-  validation={{
-    required: true,
-    pattern: {
-      value: /^[^@]+@[^.]+\..+$/,
-      // highlight-next-line
-      message: 'Please enter a valid email address',
-    },
-  }}
-  errorClassName="error"
-/>
-```
-
-</TabItem>
-<TabItem value="ts" label="TypeScript">
-
-```tsx title="web/src/pages/ContactPage/ContactPage.tsx"
-<TextField
-  name="email"
-  validation={{
-    required: true,
-    pattern: {
-      value: /^[^@]+@[^.]+\..+$/,
-      // highlight-next-line
       message: 'Please enter a valid email address',
     },
+    // highlight-end
   }}
   errorClassName="error"
 />

docs/docusaurus.config.js

@@ -45,6 +45,10 @@ const config = {
           target: '_self',
         },
         items: [
+          {
+            type: 'docsVersionDropdown',
+            position: 'left',
+          },
           {
             href: 'https://github.com/redwoodjs/redwood',
             position: 'right',
@@ -112,6 +116,13 @@ const config = {
           // ? — blob? tree?
           editUrl: 'https://github.com/redwoodjs/redwood/blob/main/docs', // base path for repo edit pages
           remarkPlugins: [autoImportTabs, fileExtSwitcher],
+          versions: {
+            current: {
+              label: 'Canary',
+              path: 'canary',
+              banner: 'unreleased',
+            },
+          },
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),