feat: add docs for validation and flash messages (#30)

docs/.vitepress/config.js

@@ -332,7 +332,8 @@ function boringStackGuide() {
         { text: 'Routing', link: 'boring-stack/routing' },
         { text: 'Navigation', link: 'boring-stack/navigation' },
         { text: 'Redirects', link: 'boring-stack/redirects' },
-        { text: 'Error handling', link: 'boring-stack/error-handling' },
+        { text: 'Validation', link: 'boring-stack/validation' },
+        { text: 'Flash messages', link: 'boring-stack/flash-messages' },
         { text: 'Sharing data', link: 'boring-stack/sharing-data' }
       ]
     },

docs/boring-stack/flash-messages.md

@@ -0,0 +1,74 @@
+---
+head:
+  - - meta
+    - property: 'og:image'
+      content: https://docs.sailscasts.com/boring-stack-social.png
+title: Flash messages
+titleTemplate: The Boring JavaScript Stack 🥱
+description: Flash messages in The Boring JavaScript Stack
+prev:
+  text: Validation
+  link: '/boring-stack/validation'
+next:
+  text: Sharing data
+  link: '/boring-stack/sharing-data'
+editLink: true
+---
+
+# Flash messages
+
+Flash messages are stable and boring mechanisms for sharing messages between requests.
+
+In fact, The Boring Stack leverages flash messages for sending [server-side validation error messages](/boring-stack/validation).
+
+## Sending flash messages
+
+You can send a flash message in your action using `req.flash()`.
+
+```js
+module.exports = {
+  exits: {
+    success: {
+      responseType: 'redirect'
+    }
+  }
+  fn: async function () {
+    req.flash('message', 'Look like your timezone has changed')
+    req.flash('success', 'Billing details updated successfully')
+    req.flash('error', 'Your subscription could not be renewed')
+
+    return '/dashboard'
+  }
+}
+```
+
+## Reading flash messages
+
+Flash messages sent in your actions are made available in a `flash` page prop object with `3` properties like so.
+
+- `success`: Use this for indicating successful operations.
+- `error`: Use this to communicate errors or failures.
+- `message`: Use this for generic messages.
+
+::: code-group
+
+```js [Vue]
+import { usePage } from '@inertiajs/vue3'
+const messages = usePage().props.flash.success // can be flash.message, flash.error
+```
+
+```js [React]
+import { usePage } from '@inertiajs/react'
+const messages = usePage().props.flash.success // can be flash.message, flash.error
+```
+
+```js [Svelte]
+import { page } from '@inertiajs/svelte'
+const messages = page.props.flash.success // can be flash.message, flash.error
+```
+
+:::
+
+::: tip
+The properties of the flash prop are always an array
+:::

docs/boring-stack/validation.md

@@ -0,0 +1,66 @@
+---
+head:
+  - - meta
+    - property: 'og:image'
+      content: https://docs.sailscasts.com/boring-stack-social.png
+title: Validation
+titleTemplate: The Boring JavaScript Stack 🥱
+description: Validation errors handling in The Boring JavaScript Stack
+prev:
+  text: Redirects
+  link: '/boring-stack/redirects'
+next:
+  text: Flash messages
+  link: '/boring-stack/flash-messages'
+editLink: true
+---
+
+# Validation
+
+The Boring Stack leverages sessions and flash messages for handling server-side validation errors.
+
+## How it works
+
+When a validation error occurs while a form is submitted using Inertia, The Boring Stack will automatically detect that this is an Inertia request and then flash the error to the session using [Sails Flash](https://github.com/sailscastshq/sails-flash) and the error will be made available in both `usePage().props.errors` and `form.errors` if you are using the [form helper](https://inertiajs.com/forms#form-helper) provided by Inertia.
+
+## Sharing errors
+
+By default, when any input fails a Sails validation, the error will be flashed to the session and made available to you automatically.
+
+You can also share errors in your action by throwing an exit with the `responseType` of `badRequest`. For example, in a login form you want to display the message "Email/Password is wrong", you can do so in your `login.js` action:
+
+```js
+module.exports = {
+  exits: {
+    badCombo: {
+      responseType: 'badRequest'
+    }
+  },
+  fn: async function () {
+    const user = await User.findOne({ email })
+    if (!user) {
+      throw {
+        badCombo: {
+          problems: [{ login: 'Email/Password is wrong' }]
+        }
+      }
+    }
+  }
+}
+```
+
+## Displaying errors
+
+Then in your login page, you can access the `login` errror via `form.errors.login` if you are using the [form helper](https://inertiajs.com/forms#form-helper) or `usPage().props.errors.login`.
+
+::: info
+Learn more about [displaying errors](https://inertiajs.com/validation#displaying-errors) in the Inertia docs.
+:::
+
+## Error bags
+
+If you are using the form helper, you don't need error bags because validatioin errors are scoped to the form object making the request.
+
+::: info
+Learn more about [error bags](https://inertiajs.com/validation#error-bags) in the Inertia docs.
+:::