Skip to content

Beautiful Open-Source Form Builder

Update API documentation and enhance form integration with TanStack Query

JhumanJ6232bc89b9fa
diff --git a/.cursor/rules/api-query.mdc b/.cursor/rules/api-query.mdc
index 3af30c337..a7881deea 100644
--- a/.cursor/rules/api-query.mdc
+++ b/.cursor/rules/api-query.mdc
@@ -126,7 +126,73 @@ You normally **don’t** need to add headers manually.
---
-## 7. Checklist for New Composables
+## 7. Form Integration with TanStack Query
+
+Forms in OpnForm (`@/composables/lib/vForm/Form.js`) provide a higher-level abstraction for handling form state, validation, and submission. They integrate seamlessly with TanStack Query mutations:
+
+### When to Use Forms
+
+**Use `Form` class when:**
+
+- You need comprehensive form state management (busy, successful, recentlySuccessful)
+- Form has client-side or server-side validation
+- You need built-in error extraction and display
+- User needs visual feedback during submission (loading states, success messages)
+
+**Use direct TanStack Query when:**
+
+- Simple data operations without validation
+- No complex form state management needed
+- Direct server-state management is sufficient
+
+### Form + Mutation Integration
+
+Pass a TanStack Query mutation to `form.mutate()` or `form.mutateAsync()`:
+
+```js
+// Create mutation from a query composable
+const { update } = useWorkspaces();
+const updateMutation = update(workspaceId);
+
+// Use it with form
+const form = useForm({ name: "My Workspace" });
+
+const handleSubmit = () => {
+ form.mutate(updateMutation)
+ .then((response) => {
+ useAlert().success("Updated!");
+ // Handle success (redirect, cache invalidation, etc.)
+ })
+ .catch((error) => {
+ // Form automatically handles validation errors
+ // error.data contains extracted validation failures
+ if (error.response?.status !== 422) {
+ useAlert().error("Something went wrong");
+ }
+ });
+};
+```
+
+### Form State Lifecycle
+
+1. **`form.busy`** – True while mutation is pending
+2. **`form.successful`** – True after successful mutation
+3. **`form.recentlySuccessful`** – Auto-reverts to false after 2s (for UI feedback like "Saved!" messages)
+4. **`form.errors`** – Populated automatically from validation responses
+
+### Key Benefits of Form Class
+
+| Feature | Form Class | Direct Mutation |
+| ------------------ | ----------------------------------- | ------------------ |
+| Loading state | ✅ Automatic `form.busy` | Manual `isPending` |
+| Error extraction | ✅ Auto-extracts from response | Manual parsing |
+| Validation support | ✅ Built-in precognition | Via TanStack Query |
+| Success feedback | ✅ `form.recentlySuccessful` | Manual state |
+| File uploads | ✅ Automatic FormData serialization | Manual handling |
+
+---
+
+## 8. Checklist for New Composables
- [ ] Map 1-to-1 with an API module
- [ ] Provide `list`, `detail`, and the necessary mutations