chore(website): update docs

Author: TheEdoRan

website/docs/define-actions/action-utils.md

@@ -5,7 +5,7 @@ description: Action utils is an object with useful properties and callbacks func
 
 # Action utils
 
-Action utils is an object with some useful properties and callbacks passed as the second argument of the [`action`/`stateAction`](/docs/define-actions/instance-methods#action--stateaction) method.
+Action utils is an object with some useful properties and callbacks passed as the second argument of the [`action()`/`stateAction()`](/docs/define-actions/instance-methods#action--stateaction) method.
 
 ## Throw errors when they occur
 
@@ -14,11 +14,12 @@ Starting from v7.4.0, you can now pass optional `throwServerError` and `throwVal
 
 ## Action callbacks
 
-- `onSuccess`: called when action execution succeeds.
-- `onError`: called when action execution fails (validation errors or server error).
-- `onSettled`: called when action execution succeeds or fails.
+- `onSuccess()`: called when action execution succeeds.
+- `onError()`: called when action execution fails (validation errors or server error).
+- `onNavigation()`: called when a `next/navigation` function is called in a middleware function or in the action's server code function.
+- `onSettled()`: called when action execution succeeds or fails.
 
-With action callbacks you can perform custom logic after the action is executed, on the server side. You can pass them to [`action`/`stateAction`](/docs/define-actions/instance-methods#action--stateaction) method as the second argument, after the server code function. Their return value is not used and they **must** be async functions.
+With action callbacks you can perform custom logic after the action is executed, on the server side. You can pass them to [`action()`/`stateAction()`](/docs/define-actions/instance-methods#action--stateaction) method as the second argument, after the server code function. Their return value is not used and they **must** be async functions.
 
 ```tsx
 import { actionClient } from "@/lib/safe-action";
@@ -49,6 +50,13 @@ const action = actionClient
       clientInput,
       bindArgsClientInputs
     }) => {},
+    onNavigation: async ({
+      navigationKind,
+      ctx,
+      metadata,
+      clientInput,
+      bindArgsClientInputs,
+    }) => {},
     onSettled: async ({
       result,
       ctx,

website/docs/define-actions/extend-previous-schemas.md

@@ -1,30 +1,30 @@
 ---
 sidebar_position: 6
-description: Learn how to use next-safe-action with a i18n solution.
+description: Learn how to extend previous schema(s)
 ---
 
 # Extend previous schema(s)
 
-Sometimes it's useful to define an action "template" with a base schema and then extend it with additional properties. This can be done inside the [`schema`](/docs/define-actions/instance-methods#schema) method by passing an async function that has the previous schema as its argument. See the example below:
+Sometimes it's useful to define an action "template" with a base input schema and then extend it with additional properties. This can be done inside the [`inputSchema`](/docs/define-actions/instance-methods#inputschema) method by passing an async function that has the previous schema as its argument. See the example below:
 
 ```typescript
 "use server";
 
 import { actionClient } from "@/lib/safe-action";
 import { z } from "zod";
 
-const schema = z.object({
+const inputSchema = z.object({
   username: z.string(),
 });
 
 const myAction = actionClient
-  .schema(schema)
+  .inputSchema(inputSchema)
   // highlight-start
-  .schema(async (prevSchema) => {
+  .inputSchema(async (prevSchema) => {
     // Here we extend the previous schema with `password` property.
     return prevSchema.extend({ password: z.string() });
   })
-  .schema(async (prevSchema) => {
+  .inputSchema(async (prevSchema) => {
     // Here with `age` property.
     return prevSchema.extend({ age: z.number().positive() });
   })
@@ -35,4 +35,4 @@ const myAction = actionClient
   });
 ```
 
-Note that if you don't use `prevSchema` inside the `schema` method, the previous schema(s) will be overwritten.
+Note that if you don't use `prevSchema` inside the `inputSchema` method, the previous schema(s) will be overwritten.

website/docs/define-actions/validation-errors.md

@@ -10,7 +10,7 @@ description: Learn how to customize or manually creating validation errors.
 next-safe-action, by default, emulates Zod's [`format()`](https://zod.dev/ERROR_HANDLING?id=formatting-errors) method for building both validation and bind args validation errors and return them to the client.
 
 This can be customized both at the safe action client level and at the action level by:
-- using [`defaultValidationErrorsShape`](/docs/define-actions/create-the-client#defaultvalidationerrorsshape) optional property in `createSafeActionClient`;
+- using [`defaultValidationErrorsShape`](/docs/define-actions/create-the-client#defaultvalidationerrorsshape) optional property in `createSafeActionClient()`;
 - using `handleValidationErrorsShape()` optional async function in [`inputSchema()`](/docs/define-actions/instance-methods#inputschema) method.
 
 The second way overrides the shape set at the instance level, per action.
@@ -90,7 +90,7 @@ When input data fails schema validation, a `validationErrors` object is returned
 
 It's often useful to also define custom logic to set additional validation errors by ourselves, for example when a user is signing up and password/confirm password fields don't match, and/or when the email is already in use.
 
-Let's see how to implement this specific case in the optimal way, using both schema refinements and errors set in action's server code function, thanks to `returnValidationErrors`.
+Let's see how to implement this specific case in the optimal way, using both schema refinements and errors set in action's server code function, thanks to `returnValidationErrors()`.
 
 ### Schema refinements
 
@@ -144,7 +144,7 @@ const signupAction = actionClient
 
 Note that:
 
-- You're required to pass a schema as the first argument of `returnValidationErrors`. This is used to infer the type of the validation errors set via the second argument.
-- Errors set using `returnValidationErrors` will not be merged with the schema ones. If schema validation fails, the execution stops before reaching action's server code function. Otherwise, the action's backend code would receive invalid parsed input.
+- You're required to pass a schema as the first argument of `returnValidationErrors()`. This is used to infer the type of the validation errors set via the second argument.
+- Errors set using `returnValidationErrors()` will not be merged with the schema ones. If schema validation fails, the execution stops before reaching action's server code function. Otherwise, the action's backend code would receive invalid parsed input.
 - `returnValidationErrors()` returns `never`. This means that internally it throws an error that gets caught and processed by next-safe-action, so code declared below the `returnValidationErrors()` invocation will not be executed.
 - Since it returns `never`, you don't need to use `return` before this function call, and you can call it only once per execution path (it works the same way as Next.js `redirect()` and `notFound()` functions).

website/docs/migrations/v7-to-v8.md

@@ -11,8 +11,8 @@ Version 8 introduces significant changes to the validation system, improves type
 Legend:
 - ⚠️ Breaking change
 - 🆕 New feature
-- ⏳ Deprecation
 - ✨ Improvement
+- 🔄 Refactor
 
 ## What's new?
 
@@ -41,7 +41,8 @@ The behavior when using functions from `next/navigation` was very unclear and co
 
 This behavior has been changed in v8. Now, when you're using functions imported from `next/navigation` in an action:
 - the hooks `status` value will be `"hasNavigated"` instead of `"hasSucceeded"`;
-- a new `onNavigation` callback will be triggered, both for actions and hooks, instead of `onSuccess`. This callback receives a `navigationKind` value, that indicates the type of navigation that occurred.
+- a new `onNavigation` callback will be triggered, both for actions and hooks, instead of `onSuccess`. This callback receives a `navigationKind` value, that indicates the type of navigation that occurred;
+- the `success` property of the middleware result will now be `false`, instead of `true`, if a navigation function was called in a middleware function or in the action's server code function.
 
 ```typescript
 import { useAction } from "next-safe-action/hooks";
@@ -91,24 +92,6 @@ const result = await boundAction(input);
 
 The deprecated `executeOnMount` hook functionality has been removed in v8. Server Actions should be used only for mutations, so it doesn't make sense to execute them on mount. Or at least, it shouldn't be a common case and, above all, a library job. If you still need to do it, just use `useEffect` to trigger the execution, however you want.
 
-### ⏳ `schema` method renamed to `inputSchema`
-
-The library, since version 7.8.0, supports both input and output validation, respectively using the `schema` and `outputSchema` methods. In v8, the `schema` method has been renamed to `inputSchema` to better reflect its purpose, and avoid potential confusion.
-
-The `schema` method is deprecated and will be removed in a future version, but it's still available for backward compatibility. It's now just an alias for `inputSchema`:
-
-```typescript title="v7"
-actionClient.schema(/* ... */)
-```
-
-```typescript title="v8"
-actionClient.inputSchema(/* ... */)
-```
-
-:::info UPDATE EXISTING ACTIONS
-To update your actions, you can just use the search and replace feature of your editor to replace all occurrences of `.schema` with `.inputSchema`.
-:::
-
 ### ✨ Type-checked metadata
 
 This is a big improvement in type safety over v7. Metadata is now statically type-checked when passed to actions. So, now if you forget to pass the expected metadata shape, as defined by the `defineMetadataSchema` init option, you will get a type error immediately:
@@ -144,7 +127,7 @@ const action = actionClient
 );
 ```
 
-### ✨ Safe action result always defined
+### 🔄 Safe action result always defined
 
 The action result object is now always defined. This allows you to destructure it without the need to check if it's defined or not first:
 
@@ -164,7 +147,26 @@ if (result?.data) {
 const { data } = await action(input);
 ```
 
-### Deprecated `useStateAction` hook
+### 🔄 `schema` method renamed to `inputSchema`
+
+The library, since version 7.8.0, supports both input and output validation, respectively using the `schema` and `outputSchema` methods. In v8, the `schema` method has been renamed to `inputSchema` to better reflect its purpose, and avoid potential confusion.
+
+The `schema` method is deprecated and will be removed in a future version, but it's still available for backward compatibility. It's now just an alias for `inputSchema`:
+
+```typescript title="v7"
+actionClient.schema(/* ... */)
+```
+
+```typescript title="v8"
+actionClient.inputSchema(/* ... */)
+```
+
+:::info UPDATE EXISTING ACTIONS
+To update your actions, you can just use the search and replace feature of your editor to replace all occurrences of `.schema` with `.inputSchema`.
+:::
+
+
+### 🔄 Deprecation of `useStateAction` hook
 
 The `useStateAction` hook has been deprecated. It's always been kind of a hack to begin with, and it doesn't support progressive enhancement, since it tries to do what the `useAction` and `useOptimisticAction` hooks do.