chore(website): improve documentation structure

website/docs/usage/direct-execution.md → website/docs/execution/direct-execution.md

@@ -57,6 +57,6 @@ export default function Login() {
 
 ### Action result object
 
-Every action you execute returns an object with the same structure. This is described in the [action result object](/docs/usage/action-result-object) section.
+Every action you execute returns an object with the same structure. This is described in the [action result object](/docs/execution/action-result-object) section.
 
 Explore a working example [here](<https://github.com/TheEdoRan/next-safe-action/tree/main/apps/playground/src/app/(examples)/direct>).

website/docs/usage/hooks/useaction.md → website/docs/execution/hooks/useaction.md

@@ -6,7 +6,7 @@ description: Learn how to use the useAction hook.
 # `useAction`
 
 :::info
-`useAction` **waits** for the action to finish execution before returning the result. If you need to perform optimistic updates, use [`useOptimisticAction`](/docs/usage/hooks/useoptimisticaction) instead.
+`useAction` **waits** for the action to finish execution before returning the result. If you need to perform optimistic updates, use [`useOptimisticAction`](/docs/execution/hooks/useoptimisticaction) instead.
 :::
 
 With this hook, you get full control of the action execution flow.
@@ -66,7 +66,7 @@ As you can see, here we display a greet message after the action is performed, i
 | Name           | Type                                       | Purpose                                                                                                |
 | -------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
 | `safeActionFn` | [HookSafeActionFn](/docs/types#hooksafeactionfn)   | This is the action that will be called when you use `execute` from hook's return object.               |
-| `utils?`   | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage/hooks/callbacks). |
+| `utils?`   | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/execution/hooks/callbacks). |
 
 ### `useAction` return object
 

website/docs/usage/hooks/useoptimisticaction.md → website/docs/execution/hooks/useoptimisticaction.md

@@ -6,7 +6,7 @@ description: Learn how to use the useOptimisticAction hook.
 # `useOptimisticAction`
 
 :::info
-`useOptimisticAction` **does not wait** for the action to finish execution before returning the optimistic data. It is then synced with the real result from server when the action has finished its execution. If you need to perform normal mutations, use [`useAction`](/docs/usage/hooks/useaction) instead.
+`useOptimisticAction` **does not wait** for the action to finish execution before returning the optimistic data. It is then synced with the real result from server when the action has finished its execution. If you need to perform normal mutations, use [`useAction`](/docs/execution/hooks/useaction) instead.
 :::
 
 Let's say you want to update the number of likes of a post in your application, mutating directly the database.
@@ -116,7 +116,7 @@ export default function AddLikes({ likesCount }: Props) {
 | ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `currentData` | `Data` (return type of the `safeActionFn` you passed as first argument) | An optimistic data setter. Usually this value comes from the parent Server Component.                                                                                                                                                  |
 | `updateFn`               | `(prevData: Data, input: InferIn<S>) => Data`                              | When you call the action via `execute`, this function determines how the optimistic data update is performed. Basically, here you define what happens **immediately** after `execute` is called, and before the actual result comes back from the server. |
-| `{ onExecute?, onSuccess?, onError?, onSettled? }`            | [`HookCallbacks`](/docs/types#hookcallbacks)                            | Optional callbacks. More information about them [here](/docs/usage/hooks/callbacks).                                                                                                                                               |
+| `{ onExecute?, onSuccess?, onError?, onSettled? }`            | [`HookCallbacks`](/docs/types#hookcallbacks)                            | Optional callbacks. More information about them [here](/docs/execution/hooks/callbacks).                                                                                                                                               |
 
 ### `useOptimisticAction` return object
 

website/docs/usage/hooks/usestateaction.md → website/docs/execution/hooks/usestateaction.md

@@ -82,7 +82,7 @@ export default function StatefulFormPage() {
 
 | Name                    | Type                                                                    | Purpose                                                                                                                                                                                                                                              |
 | ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `safeActionFn`          | [`HookStateSafeActionFn`](/docs/types#hookstatesafeactionfn)                              | This is the action that will be passed to React's `useActionState` hook. You can then all it with `execute` function from the hook's return object, that has the same signature as `safeActionFn`, minus the first argument (`prevResult`).                                                               |
+| `safeActionFn`          | [`HookSafeStateActionFn`](/docs/types#hooksafestateactionfn)                              | This is the action that will be passed to React's `useActionState` hook. You can then all it with `execute` function from the hook's return object, that has the same signature as `safeActionFn`, minus the first argument (`prevResult`).                                                               |
 | `utils`            | `{ initResult: Awaited<ReturnType<typeof safeActionFn>>; permalink?: string }` `&` [`HookCallbacks`](/docs/types#hookcallbacks)                            | Object with required `initResult` property and optional `permalink` and callbacks. Permalink usage is [explained in React docs](https://react.dev/reference/react/useActionState#parameters) for `useActionState` hook.                                                                                                                                            |
 
 You can pass an optional initial result to `useStateAction`, with the `initResult` argument. If not passed, the init result will default to `EMPTY_HOOK_RESULT` (every property typed `undefined`).

website/docs/execution/index.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 4
+description: Learn how to execute actions defined by the client.
+---
+
+# Execution

website/docs/getting-started.md

@@ -107,4 +107,4 @@ export default function Login() {
 }
 ```
 
-You also can execute Server Actions with hooks, which are a more powerful way to handle mutations. For more information about these, check out the [`useAction`](/docs/usage/hooks/useaction), [`useOptimisticAction`](/docs/usage/hooks/useoptimisticaction) and [`useStateAction`](/docs/usage/hooks/usestateaction) hooks sections.
+You also can execute Server Actions with hooks, which are a more powerful way to handle mutations. For more information about these, check out the [`useAction`](/docs/execution/hooks/useaction), [`useOptimisticAction`](/docs/execution/hooks/useoptimisticaction) and [`useStateAction`](/docs/execution/hooks/usestateaction) hooks sections.

website/docs/migrations/v3-to-v4.md

@@ -28,7 +28,7 @@ You can continue to use version 3 of the library if you want to. There are no se
 - Reorganized callbacks arguments for `onSuccess` and `onError`:
   - from `onSuccess(data, reset, input)` to `onSuccess(data, input, reset)`
   - from `onError(error, reset, input)` to `onError(error, input, reset)`
-- `useOptimisticAction` just required a safe action and an initial optimistic state before. Now it requires a `reducer` function too, that determines the behavior of the optimistic state update when the `execute` function is called. Also, now only one input argument is required by `execute`, instead of two. The same input passed to the actual safe action is now passed to the `reducer` function too, as the second argument (`input`). More information about this hook can be found [here](/docs/usage/hooks/useoptimisticaction).
+- `useOptimisticAction` just required a safe action and an initial optimistic state before. Now it requires a `reducer` function too, that determines the behavior of the optimistic state update when the `execute` function is called. Also, now only one input argument is required by `execute`, instead of two. The same input passed to the actual safe action is now passed to the `reducer` function too, as the second argument (`input`). More information about this hook can be found [here](/docs/execution/hooks/useoptimisticaction).
 
 ### Types
 

website/docs/recipes/customize-validation-errors-format.md

@@ -62,7 +62,7 @@ validationErrors = {
 };
 ```
 
-When passed to `formatValidationErrors`, the function will return a flattened version of it:
+When passed to `flattenValidationErrors`, the function will return a flattened version of it:
 
 ```typescript
 const flattenedErrors = flattenValidationErrors(validationErrors);
@@ -86,9 +86,11 @@ next-safe-action, by default, uses the formatted validation errors structure, so
 If you need or want to flatten validation errors often, though, you can define an utility function like this one (assuming you're using Zod, but you can adapt it to your needs):
 
 ```typescript title="src/lib/safe-action.ts"
-function fve<const S extends z.ZodTypeAny>(
-  schema: S
-): [
+import { flattenValidationErrors } from "next-safe-action";
+
+// ...
+
+export function fve<S extends z.ZodTypeAny>(schema: S): [
   S,
   {
     formatValidationErrors: FormatValidationErrorsFn<
@@ -117,9 +119,8 @@ const schema = z.object({
   username: z.string().min(3).max(30),
 });
 
-// Spread `fve` utility function in the `schema` method. Type safety is preserved.
-//                                     \\\\\\\\\\\\\\
 const loginUser = actionClient
+  // Spread `fve` utility function in the `schema` method. Type safety is preserved.
   .schema(...fve(schema))
   .action(async ({ parsedInput: { username } }) => {
     return {

website/docs/safe-action-client/index.md

@@ -1,17 +1,10 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 description: Safe action client is the instance that you can use to create typesafe actions.
 ---
 
 # Safe action client
 
 The safe action client instance is created by the `createSafeActionClient()` function. The instance is used to create safe actions, as you have already seen in previous sections of the documentation. You can create multiple clients too, for different purposes, as explained [in this section](/docs/recipes/extending-base-client).
 
-You can also provide functions to the client, to customize the behavior for every action you then create with it. We will explore them in detail in the following sections.
-
-Here's a reference of all the available optional functions:
-
-| Function name                | Purpose                                                                                                                                                                                                                                                                                         |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `handleReturnedServerError?` | When an error occurs on the server after executing the action on the client, it lets you define custom logic to returns a custom `serverError` instead of the default string. More information [here](/docs/safe-action-client/initialization-options#handlereturnedservererror).               |
-| `handleServerErrorLog?`      | When an error occurs on the server after executing the action on the client, it lets you define custom logic to log the error on the server. By default the error is logged via `console.error`. More information [here](/docs/safe-action-client/initialization-options#handleservererrorlog). |
+You can also provide functions to the client, to customize the behavior for every action you then create with it. We will explore them in detail in the next sections.