asasvirtuais 0.7.17 → 0.8.2

package/README.md

@@ -1,421 +1,474 @@
-# Asas Virtuais Framework
-
-Asas Virtuais is a full-stack, schema-driven framework for Next.js designed for rapid, type-safe, and maintainable application development. It provides a powerful abstraction layer for data management, allowing you to define your data shape once with Zod and get automatically generated API endpoints, client-side hooks, and form components.
-
-## Core Principles
-
-- **Schema First**: Define your data models using Zod schemas. This provides a single source of truth for validation, type safety, and data shape across the entire stack.
-- **Interface-Driven**: Code against a standardized `TableInterface` on both the client and server. This decouples your application logic from the specific database implementation, allowing for easy swapping of backends.
-- **Convention over Configuration**: The framework automatically generates RESTful API endpoints and client-side hooks from your schema, minimizing boilerplate and accelerating development.
-- **Extensible by Design**: Every layer is built to be wrapped or replaced. You can easily add custom logic like authentication to API endpoints, create new database adapters, or build bespoke form field components.
-
-## Step-by-Step Guide
-
-This guide will walk you through building a feature using the Asas Virtuais framework.
-
-### Step 1: Define Your Schema
-
-Everything starts with your data schema. Use Zod to define `readable` (data sent to the client) and `writable` (data accepted from the client) shapes for each table.
-
-`app/database.ts`:
-```ts
-import { z } from 'zod'
-
-export const schema = {
-    // A generic 'users' table
-    users: {
-        readable: z.object({
-            id: z.string(),
-            name: z.string(),
-            email: z.string().email(),
-        }),
-        writable: z.object({
-            name: z.string().nonempty('Name is required'),
-            email: z.string().email(),
-        })
-    },
-    // A generic 'posts' table
-    posts: {
-        readable: z.object({
-            id: z.string(),
-            title: z.string(),
-            content: z.string().optional(),
-            authorId: z.string(),
-        }),
-        writable: z.object({
-            title: z.string().nonempty('Title is required'),
-            content: z.string().optional(),
-            authorId: z.string(),
-        })
-    },
-}
-```
-
-### Step 2: Create a Server-Side Adapter
-
-Implement the `TableInterface` for your chosen database. The framework is backend-agnostic. This project uses a Firestore adapter.
-
-`packages/firestore.ts`:
-```ts
-import { TableInterface } from './interface'
-import { firestore } from './firebase'
-
-// A generic Firestore adapter implementing the standard interface
-export function firestoreInterface<...>(defaultTable?: T): TableInterface<...> {
-  return {
-    async find({ table = defaultTable, id }) {
-      const docSnap = await firestore.collection(table).doc(id).get()
-      if (docSnap.exists) return { id: docSnap.id, ...docSnap.data() }
-      throw new Error(`Record not found`)
-    },
-    // ... list, create, update, remove implementations
-  }
-}
-```
-
-Then, instantiate the adapter for each of your tables.
-
-`app/server.ts`:
-```ts
-import { firestoreInterface } from '@/packages/firestore'
-import { schema } from './database'
-
-// Create a server-side data access object
-export const server = {
-    users: firestoreInterface<typeof schema, 'users'>('users'),
-    posts: firestoreInterface<typeof schema, 'posts'>('posts'),
-}
-```
-
-### Step 3: Expose API Endpoints
-
-With the server adapter ready, you can expose it as a RESTful API using `createDynamicRoute`. This automatically creates `GET`, `POST`, `PATCH`, and `DELETE` handlers. You can easily wrap the base implementation to add cross-cutting concerns like authentication.
-
-`app/api/v1/[...params]/route.ts`:
-```ts
-import { authenticate } from '@/packages/auth0' // Your authentication logic
-import { createDynamicRoute } from '@/packages/next-interface'
-import { firestoreInterface } from '@/packages/firestore'
-
-const dbInterface = firestoreInterface()
-
-// Wrap the base interface to enforce business logic and authentication
-const apiInterface = {
-    async create(props) {
-        const user = await authenticate()
-        // Example: Inject the authorId automatically
-        if (props.table === 'posts') {
-            props.data.authorId = user.id 
-        }
-        return dbInterface.create(props)
-    },
-    async find(props) {
-        const user = await authenticate()
-        const result = await dbInterface.find(props)
-        // Example: Check for ownership on 'posts'
-        if (result.authorId && result.authorId !== user.id) {
-            throw new Error('Unauthorized')
-        }
-        return result
-    },
-    // ... implementations for update, remove, and list with auth checks
-} as typeof dbInterface
-
-// Export the dynamic route handlers
-export const GET = createDynamicRoute(apiInterface)
-export const POST = createDynamicRoute(apiInterface)
-export const DELETE = createDynamicRoute(apiInterface)
-export const PATCH = createDynamicRoute(apiInterface)
-```
-
-### Step 4: Initialize the Client Interface
-
-On the client, initialize the React interface. This will provide all the hooks and components you need to interact with your API.
-
-`app/interface.tsx`:
-```tsx
-'use client'
-import { fetchInterface } from '@/packages/fetch-interface'
-import { schema } from './database'
-import { reactInterface } from '@/packages/react-interface'
-
-// Create the client-side fetcher
-const fetcher = fetchInterface({ schema, baseUrl: '/api/v1' })
-
-// Export all the React hooks and components for the app
-export const { 
-    DatabaseProvider, 
-    useTable, 
-    CreateForm, 
-    UpdateForm, 
-    SingleProvider, 
-    useSingle,
-    // ... and more
-} = reactInterface<typeof schema>(schema, fetcher)
-```
-
-### Step 5: Provide Data with `DatabaseProvider`
-
-In your layouts, use `DatabaseProvider` to fetch initial data and make it available to all components underneath it via React Context.
-
-`app/posts/[id]/layout.tsx`:
-```tsx
-import { DatabaseProvider, SingleProvider } from '@/app/interface'
-import { server } from '@/app/server'
-import { layout } from '@/packages/next'
-
-export default layout<{ id: string }>( async ({ id, children }) => {
-    // Fetch initial data on the server
-    const post = await server.posts.find({ id })
-
-    // Provide the fetched data to the client-side context
-    return (
-        <DatabaseProvider posts={{ [id]: post }} users={{}}>
-            <SingleProvider id={id} table='posts'>
-                {children}
-            </SingleProvider>
-        </DatabaseProvider>
-    )
-} )
-```
-
-### Step 6: Consume Data with Hooks
-
-Use the provided hooks to access and manipulate data in your components.
-
-#### `useTable`
-To work with a collection of records (list, create, update, delete).
-
-`app/posts/page.tsx`:
-```tsx
-'use client'
-import { useTable } from '@/app/interface'
-import Link from 'next/link'
-import { IconButton } from '@chakra-ui/react'
-import { LuTrash } from 'react-icons/lu'
-
-export default function PostsPage() {
-    const { array: posts, remove, list } = useTable('posts')
-
-    useEffect(() => {
-        list.trigger({}) // Fetch all posts
-    }, [])
-
-    return (
-        <VStack>
-            {posts.map((post) => (
-                <HStack key={post.id}>
-                    <Link href={`/posts/${post.id}`}>
-                        <Text>{post.title}</Text>
-                    </Link>
-                    <IconButton
-                        onClick={() => remove.trigger({id: post.id})}
-                        disabled={remove.loading}
-                        icon={<LuTrash />}
-                    />
-                </HStack>
-            ))}
-        </VStack>
-    )
-}
-```
-
-#### `useSingle`
-To work with a single record, often used within a `SingleProvider`.
-
-`app/posts/[id]/page.tsx`:
-```tsx
-'use client'
-import { useSingle } from '@/app/interface'
-
-export default function PostPage() {
-    // Get the current post from the context provided by SingleProvider
-    const { single: post } = useSingle('posts')
-
-    return (
-        <article>
-            <h1>{post.title}</h1>
-            <p>{post.content}</p>
-        </article>
-    )
-}
-```
-
-### Step 7: High-Level Abstracted Forms
-
-The framework provides `CreateForm` and `UpdateForm` components that handle form state, submission, and API calls for you.
-
-`app/posts/new/page.tsx`:
-```tsx
-'use client'
-import { CreateForm } from '@/app/interface'
-import { Input, Button, Textarea } from '@chakra-ui/react'
-
-export function NewPostPage() {
-    const { user } = useUser() // from @auth0/nextjs-auth0
-
-    return (
-        <CreateForm 
-            table='posts'
-            // Set default values for the form
-            defaults={{ authorId: user.id, title: 'New Post' }}
-            onSuccess={(post) => router.push(`/posts/${post.id}`)}
-        >
-            {/* The child is a render prop with form state and field state */}
-            {({ loading, fields, setField, submit }) => (
-                <form onSubmit={submit}>
-                    <Input 
-                        value={fields.title}
-                        onChange={(e) => setField('title', e.target.value)}
-                    />
-                    <Textarea
-                        value={fields.content}
-                        onChange={(e) => setField('content', e.target.value)}
-                    />
-                    <Button type='submit' disabled={loading}>
-                        {loading ? 'Saving...' : 'Create Post'}
-                    </Button>
-                </form>
-            )}
-        </CreateForm>
-    )
-}
-```
-
-#### `FilterForm`
-Use `FilterForm` to easily create search and filter functionality. It wraps the `list` method of a table and displays the results.
-
-`app/posts/SearchPosts.tsx`:
-```tsx
-'use client'
-import { FilterForm } from '@/app/interface'
-import { Input, Button, VStack, Text, Box } from '@chakra-ui/react'
-
-function SearchPosts() {
-    return (
-        <Box>
-            <FilterForm
-                table="posts"
-                // Set default filter values. The form will initially load with these.
-                defaults={{ title: '' }}
-            >
-                {({ loading, fields, setField, submit, result }) => (
-                    <VStack as="form" onSubmit={submit} align="stretch" spacing={4}>
-                        <Input
-                            placeholder="Search by title..."
-                            value={fields.title}
-                            onChange={(e) => setField('title', e.target.value)}
-                        />
-                        <Button type="submit" disabled={loading} alignSelf="flex-start">
-                            {loading ? 'Searching...' : 'Search'}
-                        </Button>
-
-                        {/* Display the results from the list call */}
-                        <VStack align="stretch" mt={4} spacing={2}>
-                            {result && result.length > 0 ? (
-                                result.map(post => (
-                                    <Text key={post.id}>- {post.title}</Text>
-                                ))
-                            ) : (
-                                <Text color="gray.500">No results found.</Text>
-                            )}
-                        </VStack>
-                    </VStack>
-                )}
-            </FilterForm>
-        </Box>
-    );
-}
-```
-
-## Form and Field Primitives
-
-The `CreateForm` and `UpdateForm` components are convenient abstractions. For more control, you can use the underlying `FormProvider` and `FieldsProvider` primitives directly.
-
-### `packages/form.tsx`
-
-`FormProvider` is a render-prop component that wraps your form submission logic. It manages the `loading`, `error`, and `result` state of an async callback.
-
-- **Props**:
-    - `callback`: An async function that takes the form data and performs the submission.
-    - `data`: The initial data for the form.
-    - `onSuccess`: An optional function to call with the result of a successful submission.
-- **Render Prop State**:
-    - `loading`: `boolean` - True while the callback is executing.
-    - `error`: `Error | null` - The error object if the submission fails.
-    - `result`: `Result | null` - The data returned from a successful submission.
-    - `submit`: `function` - The function to trigger the form submission.
-    - `values`: `Fields` - The current data object for the form.
-
-### `packages/fields.tsx`
-
-`FieldsProvider` manages the state of your form's input fields. It holds the `fields` object and provides `setField` and `setFields` methods to update it.
-
-- **Props**:
-    - `defaults`: The initial values for the form fields.
-- **Render Prop State**:
-    - `fields`: `T` - The object containing the current state of all form fields.
-    - `setField`: `(name, value)` - A function to update a single field's value.
-    - `setFields`: `(newFields)` - A function to replace the entire fields object.
-
-### Using `FormProvider` and `FieldsProvider` Together
-
-Here is how you can build a form from scratch using the low-level primitives. This pattern is what `CreateForm` uses internally.
-
-```tsx
-import { FormProvider } from 'asasvirtuais/form'
-import { FieldsProvider } from 'asasvirtuais/fields'
-import { Input, Button, Spinner, Text, Textarea, Stack } from '@chakra-ui/react'
-
-function NewPostForm({ onCreate }) {
-    // The function that will be called on form submission
-    const createPostCallback = async (fields) => {
-        // This would typically be an API call, e.g., from useTable()
-        const newPost = await api.posts.create({ data: fields });
-        return newPost;
-    };
-
-    return (
-        // 1. FormProvider handles the submission process
-        <FormProvider callback={createPostCallback} data={{}} onSuccess={onCreate}>
-            {({ loading, error, submit }) => (
-                // 2. FieldsProvider manages the state of the form's inputs
-                <FieldsProvider defaults={{ title: '', content: '', authorId: '1' }}>
-                    {({ fields, setField }) => (
-                        <form onSubmit={(e) => {
-                            e.preventDefault();
-                            // Pass the current field state to the submit function
-                            submit(fields);
-                        }}>
-                            <Stack>
-                                <label>Title</label>
-                                <Input
-                                    value={fields.title}
-                                    onChange={(e) => setField('title', e.target.value)}
-                                />
-
-                                <label>Content</label>
-                                <Textarea
-                                    value={fields.content}
-                                    onChange={(e) => setField('content', e.target.value)}
-                                />
-
-                                {error && <Text color="red.500">{error.message}</Text>}
-
-                                <Button type="submit" disabled={loading}>
-                                    {loading ? <Spinner /> : 'Create Post'}
-                                </Button>
-                            </Stack>
-                        </form>
-                    )}
-                </FieldsProvider>
-            )}
-        </FormProvider>
-    );
-}
-```
-
-## Roadmap
-
-- [ ] Relationships, linked records, TableLookup field
-- [ ] Realtime database with feathersjs
+# Asas Virtuais Framework
+
+Asas Virtuais is a full-stack, schema-driven framework for Next.js designed for rapid, type-safe, and maintainable application development. It provides a powerful abstraction layer for data management, allowing you to define your data shape once with Zod and get automatically generated API endpoints, client-side hooks, and form components.
+
+## Core Principles
+
+- **Schema First**: Define your data models using Zod schemas. This provides a single source of truth for validation, type safety, and data shape across the entire stack.
+- **Interface-Driven**: Code against a standardized `TableInterface` on both the client and server. This decouples your application logic from the specific database implementation, allowing for easy swapping of backends.
+- **Convention over Configuration**: The framework automatically generates RESTful API endpoints and client-side hooks from your schema, minimizing boilerplate and accelerating development.
+- **Extensible by Design**: Every layer is built to be wrapped or replaced. You can easily add custom logic like authentication to API endpoints, create new database adapters, or build bespoke form field components.
+
+## Step-by-Step Guide
+
+This guide will walk you through building a feature using the Asas Virtuais framework.
+
+### Step 1: Define Your Schema
+
+Everything starts with your data schema. Use Zod to define `readable` (data sent to the client) and `writable` (data accepted from the client) shapes for each table.
+
+`app/database.ts`:
+```ts
+import { z } from 'zod'
+
+export const schema = {
+    // A generic 'users' table
+    users: {
+        readable: z.object({
+            id: z.string(),
+            name: z.string(),
+            email: z.string().email(),
+        }),
+        writable: z.object({
+            name: z.string().nonempty('Name is required'),
+            email: z.string().email(),
+        })
+    },
+    // A generic 'posts' table
+    posts: {
+        readable: z.object({
+            id: z.string(),
+            title: z.string(),
+            content: z.string().optional(),
+            authorId: z.string(),
+        }),
+        writable: z.object({
+            title: z.string().nonempty('Title is required'),
+            content: z.string().optional(),
+            authorId: z.string(),
+        })
+    },
+}
+```
+
+### Step 2: Create a Server-Side Adapter
+
+Implement the `TableInterface` for your chosen database. The framework is backend-agnostic. This project uses a Firestore adapter.
+
+`packages/firestore.ts`:
+```ts
+import { TableInterface } from './interface'
+import { firestore } from './firebase'
+
+// A generic Firestore adapter implementing the standard interface
+export function firestoreInterface<...>(defaultTable?: T): TableInterface<...> {
+  return {
+    async find({ table = defaultTable, id }) {
+      const docSnap = await firestore.collection(table).doc(id).get()
+      if (docSnap.exists) return { id: docSnap.id, ...docSnap.data() }
+      throw new Error(`Record not found`)
+    },
+    // ... list, create, update, remove implementations
+  }
+}
+```
+
+Then, instantiate the adapter for each of your tables.
+
+`app/server.ts`:
+```ts
+import { firestoreInterface } from '@/packages/firestore'
+import { schema } from './database'
+
+// Create a server-side data access object
+export const server = {
+    users: firestoreInterface<typeof schema, 'users'>('users'),
+    posts: firestoreInterface<typeof schema, 'posts'>('posts'),
+}
+```
+
+### Step 3: Expose API Endpoints
+
+With the server adapter ready, you can expose it as a RESTful API using `createDynamicRoute`. This automatically creates `GET`, `POST`, `PATCH`, and `DELETE` handlers. You can easily wrap the base implementation to add cross-cutting concerns like authentication.
+
+`app/api/v1/[...params]/route.ts`:
+```ts
+import { authenticate } from '@/packages/auth0' // Your authentication logic
+import { createDynamicRoute } from '@/packages/next-interface'
+import { firestoreInterface } from '@/packages/firestore'
+
+const dbInterface = firestoreInterface()
+
+// Wrap the base interface to enforce business logic and authentication
+const apiInterface = {
+    async create(props) {
+        const user = await authenticate()
+        // Example: Inject the authorId automatically
+        if (props.table === 'posts') {
+            props.data.authorId = user.id 
+        }
+        return dbInterface.create(props)
+    },
+    async find(props) {
+        const user = await authenticate()
+        const result = await dbInterface.find(props)
+        // Example: Check for ownership on 'posts'
+        if (result.authorId && result.authorId !== user.id) {
+            throw new Error('Unauthorized')
+        }
+        return result
+    },
+    // ... implementations for update, remove, and list with auth checks
+} as typeof dbInterface
+
+// Export the dynamic route handlers
+export const GET = createDynamicRoute(apiInterface)
+export const POST = createDynamicRoute(apiInterface)
+export const DELETE = createDynamicRoute(apiInterface)
+export const PATCH = createDynamicRoute(apiInterface)
+```
+
+### Step 4: Initialize the Client Interface
+
+On the client, initialize the React interface. This will provide all the hooks and components you need to interact with your API.
+
+`app/interface.tsx`:
+```tsx
+'use client'
+import { fetchInterface } from '@/packages/fetch-interface'
+import { schema } from './database'
+import { reactInterface } from '@/packages/react-interface'
+
+// Create the client-side fetcher
+const fetcher = fetchInterface({ schema, baseUrl: '/api/v1' })
+
+// Export all the React hooks and components for the app
+export const { 
+    DatabaseProvider, 
+    useTable, 
+    CreateForm, 
+    UpdateForm, 
+    SingleProvider, 
+    useSingle,
+    // ... and more
+} = reactInterface<typeof schema>(schema, fetcher)
+```
+
+### Step 5: Provide Data with `DatabaseProvider`
+
+In your layouts, use `DatabaseProvider` to fetch initial data and make it available to all components underneath it via React Context.
+
+`app/posts/[id]/layout.tsx`:
+```tsx
+import { DatabaseProvider, SingleProvider } from '@/app/interface'
+import { server } from '@/app/server'
+import { layout } from '@/packages/next'
+
+export default layout<{ id: string }>( async ({ id, children }) => {
+    // Fetch initial data on the server
+    const post = await server.posts.find({ id })
+
+    // Provide the fetched data to the client-side context
+    return (
+        <DatabaseProvider posts={{ [id]: post }} users={{}}>
+            <SingleProvider id={id} table='posts'>
+                {children}
+            </SingleProvider>
+        </DatabaseProvider>
+    )
+} )
+```
+
+### Step 6: Consume Data with Hooks
+
+Use the provided hooks to access and manipulate data in your components.
+
+#### `useTable`
+To work with a collection of records (list, create, update, delete).
+
+`app/posts/page.tsx`:
+```tsx
+'use client'
+import { useTable } from '@/app/interface'
+import Link from 'next/link'
+import { IconButton } from '@chakra-ui/react'
+import { LuTrash } from 'react-icons/lu'
+
+export default function PostsPage() {
+    const { array: posts, remove, list } = useTable('posts')
+
+    useEffect(() => {
+        list.trigger({}) // Fetch all posts
+    }, [])
+
+    return (
+        <VStack>
+            {posts.map((post) => (
+                <HStack key={post.id}>
+                    <Link href={`/posts/${post.id}`}>
+                        <Text>{post.title}</Text>
+                    </Link>
+                    <IconButton
+                        onClick={() => remove.trigger({id: post.id})}
+                        disabled={remove.loading}
+                        icon={<LuTrash />}
+                    />
+                </HStack>
+            ))}
+        </VStack>
+    )
+}
+```
+
+#### `useSingle`
+To work with a single record, often used within a `SingleProvider`.
+
+`app/posts/[id]/page.tsx`:
+```tsx
+'use client'
+import { useSingle } from '@/app/interface'
+
+export default function PostPage() {
+    // Get the current post from the context provided by SingleProvider
+    const { single: post } = useSingle('posts')
+
+    return (
+        <article>
+            <h1>{post.title}</h1>
+            <p>{post.content}</p>
+        </article>
+    )
+}
+```
+
+### Step 7: High-Level Abstracted Forms
+
+The framework provides `CreateForm` and `UpdateForm` components that handle form state, submission, and API calls for you.
+
+`app/posts/new/page.tsx`:
+```tsx
+'use client'
+import { CreateForm } from '@/app/interface'
+import { Input, Button, Textarea } from '@chakra-ui/react'
+
+export function NewPostPage() {
+    const { user } = useUser() // from @auth0/nextjs-auth0
+
+    return (
+        <CreateForm 
+            table='posts'
+            // Set default values for the form
+            defaults={{ authorId: user.id, title: 'New Post' }}
+            onSuccess={(post) => router.push(`/posts/${post.id}`)}
+        >
+            {/* The child is a render prop with form state and field state */}
+            {({ loading, fields, setField, submit }) => (
+                <form onSubmit={submit}>
+                    <Input 
+                        value={fields.title}
+                        onChange={(e) => setField('title', e.target.value)}
+                    />
+                    <Textarea
+                        value={fields.content}
+                        onChange={(e) => setField('content', e.target.value)}
+                    />
+                    <Button type='submit' disabled={loading}>
+                        {loading ? 'Saving...' : 'Create Post'}
+                    </Button>
+                </form>
+            )}
+        </CreateForm>
+    )
+}
+```
+
+#### `FilterForm`
+Use `FilterForm` to easily create search and filter functionality. It wraps the `list` method of a table and displays the results.
+
+`app/posts/SearchPosts.tsx`:
+```tsx
+'use client'
+import { FilterForm } from '@/app/interface'
+import { Input, Button, VStack, Text, Box } from '@chakra-ui/react'
+
+function SearchPosts() {
+    return (
+        <Box>
+            <FilterForm
+                table="posts"
+                // Set default filter values. The form will initially load with these.
+                defaults={{ title: '' }}
+            >
+                {({ loading, fields, setField, submit, result }) => (
+                    <VStack as="form" onSubmit={submit} align="stretch" spacing={4}>
+                        <Input
+                            placeholder="Search by title..."
+                            value={fields.title}
+                            onChange={(e) => setField('title', e.target.value)}
+                        />
+                        <Button type="submit" disabled={loading} alignSelf="flex-start">
+                            {loading ? 'Searching...' : 'Search'}
+                        </Button>
+
+                        {/* Display the results from the list call */}
+                        <VStack align="stretch" mt={4} spacing={2}>
+                            {result && result.length > 0 ? (
+                                result.map(post => (
+                                    <Text key={post.id}>- {post.title}</Text>
+                                ))
+                            ) : (
+                                <Text color="gray.500">No results found.</Text>
+                            )}
+                        </VStack>
+                    </VStack>
+                )}
+            </FilterForm>
+        </Box>
+    );
+}
+```
+
+## Form and Field Primitives
+
+The `CreateForm` and `UpdateForm` components are convenient abstractions. For more control, you can use the underlying `Form`, `ActionProvider`, and `FieldsProvider` primitives directly.
+
+### `packages/action.tsx`
+
+`ActionProvider` is a render-prop component that wraps your form submission logic. It manages the `loading`, `error`, and `result` state of an async action.
+
+- **Props**:
+    - `action`: An async function that takes the form data and performs the submission.
+    - `params`: The data to pass to the action function.
+    - `onError`: An optional function to call when the action fails.
+    - `preload`: Optional boolean to trigger the action on mount.
+- **Render Prop State**:
+    - `loading`: `boolean` - True while the action is executing.
+    - `error`: `Error | null` - The error object if the submission fails.
+    - `result`: `Result | null` - The data returned from a successful submission.
+    - `submit`: `function` - The function to trigger the action.
+    - `data`: `Fields` - The current data object for the action.
+
+### `packages/fields.tsx`
+
+`FieldsProvider` manages the state of your form's input fields. It holds the `fields` object and provides `setField` and `setFields` methods to update it.
+
+- **Props**:
+    - `defaults`: The initial values for the form fields.
+- **Render Prop State**:
+    - `fields`: `T` - The object containing the current state of all form fields.
+    - `setField`: `(name, value)` - A function to update a single field's value.
+    - `setFields`: `(newFields)` - A function to replace the entire fields object.
+
+### `packages/form.tsx`
+
+`Form` is a convenience component that combines `FieldsProvider` and `ActionProvider` into a single component for simpler usage.
+
+- **Props**:
+    - `action`: An async function that takes the form data and performs the submission.
+    - `defaults`: The initial values for the form fields.
+    - `onError`: An optional function to call when the action fails.
+    - `preload`: Optional boolean to trigger the action on mount.
+- **Render Prop State**:
+    - Combines all state from both `FieldsProvider` and `ActionProvider`
+    - `fields`, `setField`, `setFields` (from FieldsProvider)
+    - `loading`, `error`, `result`, `submit`, `data` (from ActionProvider)
+
+### Using Form Primitives
+
+Here are different ways to build a form using the low-level primitives:
+
+**Option 1: Using `Form` (Recommended - Combines Fields + Action)**
+
+```tsx
+import { Form } from 'asasvirtuais/form'
+import { Input, Button, Spinner, Text, Textarea, Stack } from '@chakra-ui/react'
+
+function NewPostForm({ onCreate }) {
+    const createPostAction = async (fields) => {
+        const newPost = await api.posts.create({ data: fields });
+        return newPost;
+    };
+
+    return (
+        <Form action={createPostAction} defaults={{ title: '', content: '', authorId: '1' }}>
+            {({ fields, setField, loading, error, submit }) => (
+                <form onSubmit={submit}>
+                    <Stack>
+                        <label>Title</label>
+                        <Input
+                            value={fields.title}
+                            onChange={(e) => setField('title', e.target.value)}
+                        />
+
+                        <label>Content</label>
+                        <Textarea
+                            value={fields.content}
+                            onChange={(e) => setField('content', e.target.value)}
+                        />
+
+                        {error && <Text color="red.500">{error.message}</Text>}
+
+                        <Button type="submit" disabled={loading}>
+                            {loading ? <Spinner /> : 'Create Post'}
+                        </Button>
+                    </Stack>
+                </form>
+            )}
+        </Form>
+    );
+}
+```
+
+**Option 2: Using `ActionProvider` and `FieldsProvider` Separately (Maximum Control)**
+
+```tsx
+import { ActionProvider } from 'asasvirtuais/action'
+import { FieldsProvider } from 'asasvirtuais/fields'
+import { Input, Button, Spinner, Text, Textarea, Stack } from '@chakra-ui/react'
+
+function NewPostForm({ onCreate }) {
+    const createPostAction = async (fields) => {
+        const newPost = await api.posts.create({ data: fields });
+        return newPost;
+    };
+
+    return (
+        // 1. FieldsProvider manages the state of the form's inputs
+        <FieldsProvider defaults={{ title: '', content: '', authorId: '1' }}>
+            {({ fields, setField }) => (
+                // 2. ActionProvider handles the submission process
+                <ActionProvider action={createPostAction} params={fields}>
+                    {({ loading, error, submit }) => (
+                        <form onSubmit={submit}>
+                            <Stack>
+                                <label>Title</label>
+                                <Input
+                                    value={fields.title}
+                                    onChange={(e) => setField('title', e.target.value)}
+                                />
+
+                                <label>Content</label>
+                                <Textarea
+                                    value={fields.content}
+                                    onChange={(e) => setField('content', e.target.value)}
+                                />
+
+                                {error && <Text color="red.500">{error.message}</Text>}
+
+                                <Button type="submit" disabled={loading}>
+                                    {loading ? <Spinner /> : 'Create Post'}
+                                </Button>
+                            </Stack>
+                        </form>
+                    )}
+                </ActionProvider>
+            )}
+        </FieldsProvider>
+    );
+}
+```
+
+## Roadmap
+
+- [ ] Relationships, linked records, TableLookup field
+- [ ] Realtime database with feathersjs