update

Author: amirhhashemi

src/routes/solid-router/concepts/actions.mdx

@@ -7,7 +7,6 @@ They are designed to simplify your application's data flow, ensure a consistent
 
 Actions provide several key benefits:
 
-- **Centralized Logic**: Encapsulate the logic for data modifications in a single, reusable function.
 - **Integrated State Management**: Solid Router automatically tracks the execution state of an action (whether it's pending, successful, or has encountered an error), making it easy to build reactive UI feedback.
 - **Automatic Data Revalidation**: By default, after an action successfully completes, Solid Router revalidates any queries on the same page.
   This ensures your UI reflects the latest data without manual intervention.
@@ -34,10 +33,10 @@ const addPostAction = action(async (title: string) => {
 
 	if (!response.ok) {
 		const errorData = await response.json();
-		throw new Error(errorData.message || "Failed to add post");
+		return { success: false, message: errorData.message };
 	}
 
-	return await response.json();
+	return { success: true, data: await response.json() };
 });
 ```
 
@@ -50,7 +49,7 @@ This is crucial for Solid Router to correctly identify and re-run actions on the
 We'll explore this in more detail in the Handling Form Submissions section.
 :::
 
-## How to Use Actions
+## Using actions
 
 Solid Router offers two primary ways to invoke an action:
 
@@ -76,7 +75,7 @@ const addPostAction = action(async (formData: FormData) => {
 	const title = formData.get("title")?.toString();
 
 	if (!title || title.trim() === "") {
-		throw new Error("Post title cannot be empty.");
+		return { success: false, message: "Post title cannot be empty." };
 	}
 
 	const response = await fetch("https://api.com/posts", {
@@ -89,9 +88,11 @@ const addPostAction = action(async (formData: FormData) => {
 
 	if (!response.ok) {
 		const errorData = await response.json();
-		throw new Error(errorData.message || "Failed to add post");
+		return { success: false, message: errorData.message };
 	}
-}, "add-post");
+
+	return { success: true };
+}, "addPost");
 
 function AddPostForm() {
 	return (
@@ -108,7 +109,7 @@ When this form is submitted, `addPostFormAction` will be invoked with the `FormD
 
 :::tip[File Uploads]
 
-If your form includes file inputs, ensure your <form> element has enctype="multipart/form-data" to correctly send the file data.
+If your form includes file inputs, ensure your `<form>` element has `enctype="multipart/form-data"` to correctly send the file data.
 
 ```tsx
 <form action={uploadFileAction} method="post" enctype="multipart/form-data">
@@ -133,7 +134,7 @@ const updatePostAction = action(async (postId: string, formData: FormData) => {
 	const newTitle = formData.get("title")?.toString();
 
 	if (!newTitle || newTitle.trim() === "") {
-		throw new Error("Post title cannot be empty.");
+		return { success: false, message: "Post title cannot be empty." };
 	}
 
 	const response = await fetch(
@@ -149,8 +150,10 @@ const updatePostAction = action(async (postId: string, formData: FormData) => {
 
 	if (!response.ok) {
 		const errorData = await response.json();
-		throw new Error(errorData.message || "Failed to update post");
+		return { success: false, message: errorData.message };
 	}
+
+	return { success: true };
 });
 
 function PostEditForm(props: { postId: string }) {
@@ -165,3 +168,180 @@ function PostEditForm(props: { postId: string }) {
 ```
 
 Here, `updatePostAction` receives `postId` (passed via `with`), and then the `formData` from the form.
+
+### Invoking Actions Programmatically with `useAction`
+
+While forms are highly recommended for progressive enhancement, there are scenarios where you might need to trigger an action directly from a Solid component, outside of a `<form>` element.
+The `useAction` primitive allows you to do this.
+
+`useAction` takes an action as an argument and returns a function that, when called, will invoke the action with the provided parameters.
+
+```tsx
+import { action, useAction } from "@solidjs/router";
+
+const likePostAction = action(async (postId: string) => {
+	await fetch(`https://api.com/posts/${encodeURIComponent(postId)}/likes`, {
+		method: "POST",
+	});
+});
+
+function LikePostButton(props: { postId: string }) {
+	const likePost = useAction();
+
+	return <button onClick={() => likePost(postId)}>Like</button>;
+}
+```
+
+In this example, `likePost` is a function that can be called with arguments matching `likePostAction`.
+When the button is clicked, `likePostAction` invokes for the specific post ID.
+
+## Query revalidation
+
+By default, when an action successfully finishes its execution, Solid Router will automatically revalidate all queries on the same page.
+This means you typically don't have to manually refetch data after a mutation.
+For example, if you add a new post using an action, any query on that page fetching a list of posts will automatically re-run and update your UI.
+
+```tsx
+import { query, action, createAsync } from "@solidjs/router";
+
+const getPostsQuery = query(async () => {
+	const response = await fetch("https://api.com/posts");
+	return await response.json();
+}, "getPosts");
+
+const addPostAction = action(async (formData: FormData) => {
+	const title = formData.get("title")?.toString();
+	await fetch("https://api.com/posts", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ title }),
+	});
+}, "addPost");
+
+function PostsPage() {
+	// This query will automatically revalidate after addPostAction completes.
+	const posts = createAsync(() => getPostsQuery());
+
+	return (
+		<div>
+			<h2>All Posts</h2>
+			<For each={posts()}>{(post) => <p>{post.title}</p>}</For>
+
+			<h3>Add New Post</h3>
+			<form action={addPostAction} method="post">
+				<input name="title" placeholder="Post title" />
+				<button type="submit">Add Post</button>
+			</form>
+		</div>
+	);
+}
+```
+
+While automatic revalidation is convenient, there are times you need more control.
+Solid Router's response helpers allow you to precisely manage which queries are revalidated, or even disable revalidation entirely for a specific action.
+You'll learn more about these helpers in the next section.
+
+## Response helpers
+
+Solid Router provides special response helpers that enable your actions to explicitly dictate routing and query revalidation:
+
+- [`json`](/solid-router/reference/response-helpers/json): Allows customizing query revalidation behavior when the action returns something.
+  While it's not necessary to use this helper to return a value from an action (a plain JavaScript value also works), the `json` helper can be used when you want to return data **and** customize query revalidation.
+- [`redirect`](/solid-router/reference/response-helpers/redirect): Performs a redirect.
+- [`reload`](/solid-router/reference/response-helpers/reload): Revalidates queries.
+
+You can either `return` or `throw` the result of a response helper in order for Solid Router to handle it.
+Throwing might be preferable in TypeScript environemnts since it doesn't conflict with TypeScript's type system.
+
+```tsx
+import { action, redirect, json, reload } from "@solidjs/router";
+
+// Example 1: Redirecting after a successful login
+const loginAction = action(async (formData: FormData) => {
+	// ...Login logic
+
+	throw redirect("/dashboard");
+});
+
+// Example 2: Returning data with specific revalidation control
+const savePreferencesAction = action(async (formData: FormData) => {
+	// ...Save preferences logic
+
+	return json(
+		{ success: true, message: "Preferences saved!" },
+		{ revalidate: ["userPreferences"] }
+	);
+});
+
+// Example 3: Disabling revalidation
+const logActivityAction = action(async (activityData: FormData) => {
+	// ...Log activity to server
+
+	// Don't revalidate any queries on the current page for this action
+	throw reload({ revalidate: [] });
+});
+```
+
+## Tracking action state
+
+When an action is executing, your UI often needs to reflect its current state.
+Solid Router provides the `useSubmission` and `useSubmissions` primitives to track the lifecycle of your actions.
+
+The `useSubmission` hook returns an object with reactive values that represent the state of the _most recent_ submission for a given action.
+This is perfect for displaying pending states on buttons, showing the latest error, or displaying the outcome of the action.
+
+```tsx
+import { Show } from "solid-js";
+import { action, useSubmission } from "@solidjs/router";
+
+const saveSettingsAction = action(async (formData: FormData) => {
+	const email = formData.get("email")?.toString();
+
+	if (!email || !email.includes("@")) {
+		throw new Error("Please enter a valid email address.");
+	}
+
+	await new Promise((res) => setTimeout(res, 2000)); // Simulate API call
+
+	return { success: true, message: "Settings saved successfully!" };
+}, "save-settings");
+
+function UserSettingsForm() {
+	const submission = useSubmission(saveSettingsAction);
+
+	return (
+		<form action={saveSettingsAction} method="post">
+			<label for="email">Email:</label>
+			<input id="email" name="email" type="email" />
+
+			<button type="submit" disabled={submission.pending}>
+				{submission.pending ? "Saving..." : "Save Settings"}
+			</button>
+
+			<Show when={submission.error}>
+				{(error) => (
+					<div style="color: red; margin-top: 10px;">
+						<p>Error: {error().message}</p>
+						<button onClick={() => submission.clear()}>Clear Error</button>
+						<button onClick={() => submission.retry()}>Retry</button>
+					</div>
+				)}
+			</Show>
+			<Show when={submission.result}>
+				{(result) => (
+					<p style="color: green; margin-top: 10px;">{result().message}</p>
+				)}
+			</Show>
+		</form>
+	);
+}
+```
+
+In this example, the form's submit button is disabled during `submission.pending`, and appropriate messages are shown based on `submission.error` or `submission.result`.
+The `clear` method resets the submission state, and `retry` re-executes the last submission with its original input.
+
+For more details, see the [`useSubmission` API reference](/solid-router/reference/data-apis/use-submission).
+
+:::tip
+If you need to track multiple concurrent or recent submissions for an action (e.g., a list of file uploads, a queue of items being processed), the [`useSubmissions` primitive](/solid-router/reference/data-apis/use-submissions) can be used.
+:::