asasvirtuais 2.5.1 → 4.0.0

package/README.md

@@ -1,894 +1,495 @@
 # asasvirtuais
 
-**A React framework for building maintainable web applications without the architectural debt.**
+A React framework for building full-stack apps where code is organized by feature, not by layer.
 
-After 7 years of wrestling with complex tech stacks, I built asasvirtuais to solve a problem nobody seems to talk about: the elephant under the carpet of modern web development. Every framework gives you components and state management, but none of them solve the fundamental challenge every project faces—connecting CRUD APIs to UI forms with clean, maintainable state management.
-
-This isn't about fancy animations or advanced performance optimization. This is about making codebases simple enough that you (or an AI) can focus on business logic instead of wrestling with architectural patterns.
+---
 
-## The Problem
+## Primitives
 
-Software development has convinced itself that complexity is inevitable. We've been taught that proper applications require:
+Three building blocks, each usable on its own.
 
-- State scattered across dozens of files
-- Design patterns that make simple things complicated
-- Dependencies injected through layers of abstraction
-- Code that's impossible to reason about without opening 10 files
+### `FieldsProvider` — field state
 
-But here's the thing: **complexity exists, but overengineering is a human tendency, not a technical requirement.**
+```tsx
+import { FieldsProvider } from 'asasvirtuais/fields'
 
-## The Solution
+<FieldsProvider defaults={{ title: '', done: false }}>
+  {({ fields, setField }) => (
+    <div>
+      <input value={fields.title} onChange={e => setField('title', e.target.value)} />
+      <input type="checkbox" checked={fields.done} onChange={e => setField('done', e.target.checked)} />
+    </div>
+  )}
+</FieldsProvider>
+```
 
-asasvirtuais is built on a simple foundation: **React + RESTful APIs**. No magic, no over-abstraction. Just a library that makes the right architectural decisions obvious.
+### `ActionProvider` — async action state
 
-The core insight: **developers and AI shouldn't need to think about state management—just focus on business logic.**
+```tsx
+import { ActionProvider } from 'asasvirtuais/action'
 
-### What Makes This Different
+<ActionProvider params={{ id: todo.id }} action={archiveTodo} onResult={() => router.push('/')}>
+  {({ submit, loading, error }) => (
+    <button onClick={submit} disabled={loading}>
+      {loading ? 'Archiving...' : 'Archive'}
+    </button>
+  )}
+</ActionProvider>
+```
 
-1. **Nested forms that actually make sense** - Build multi-step async validation workflows without the pain
-2. **CRUD operations as a solved problem** - Filter, create, update with zero boilerplate
-3. **Code in one place** - Business logic lives in readable, single files, not scattered across a dependency tree
-4. **AI-friendly patterns** - Simple enough that AI can generate complex forms correctly on the first try
+### `Form` — fields + action together
 
-## Installation
+```tsx
+import { Form } from 'asasvirtuais/form'
 
-### From npm
-```bash
-npm install asasvirtuais
+<Form defaults={{ email: '', password: '' }} action={login} onResult={handleResult}>
+  {({ fields, setField, submit, loading, error }) => (
+    <form onSubmit={submit}>
+      <input value={fields.email} onChange={e => setField('email', e.target.value)} />
+      <input type="password" value={fields.password} onChange={e => setField('password', e.target.value)} />
+      <button type="submit" disabled={loading}>Login</button>
+      {error && <p>{error.message}</p>}
+    </form>
+  )}
+</Form>
 ```
 
-### From esm.sh
-```typescript
-import { Form } from 'https://esm.sh/asasvirtuais@latest/form'
-import { useFields } from 'https://esm.sh/asasvirtuais@latest/fields'
-import { useAction } from 'https://esm.sh/asasvirtuais@latest/action'
-```
+---
 
-## Quick Start
+## Full-stack CRUD
 
-### Simple Form
+The framework provides a schema-first CRUD layer where create, update, and remove operations automatically keep the UI in sync through a reactive index — no manual state updates, no refetching.
 
-```tsx
-import { Form } from 'asasvirtuais/form'
+### Project structure
 
-type LoginFields = {
-  email: string
-  password: string
-}
+```
+app/
+├── schema.ts             # All table schemas in one place
+├── actions.ts            # Server actions — the backend
+├── providers.tsx         # App-level providers
+├── layout.tsx
+├── todos/
+│   ├── schema.ts          # Schema + types
+│   ├── fields.tsx        # Input components
+│   ├── forms.tsx         # Create / Update / Delete / Filter forms
+│   ├── components.tsx    # Display components
+│   └── provider.tsx      # TableProvider + hook
+```
 
-type LoginResult = {
-  token: string
-  user: { id: string; name: string }
-}
+---
 
-async function loginAction(fields: LoginFields): Promise<LoginResult> {
-  const response = await fetch('/api/login', {
-    method: 'POST',
-    body: JSON.stringify(fields)
-  })
-  return response.json()
-}
+### 1. Schema
 
-function LoginForm() {
-  return (
-    <Form<LoginFields, LoginResult>
-      defaults={{ email: '', password: '' }}
-      action={loginAction}
-      onResult={(result) => console.log('Logged in:', result.user.name)}
-    >
-      {({ fields, setField, submit, loading, error }) => (
-        <form onSubmit={submit}>
-          <input
-            type="email"
-            value={fields.email}
-            onChange={(e) => setField('email', e.target.value)}
-          />
-          <input
-            type="password"
-            value={fields.password}
-            onChange={(e) => setField('password', e.target.value)}
-          />
-          <button type="submit" disabled={loading}>
-            {loading ? 'Logging in...' : 'Login'}
-          </button>
-          {error && <p>Error: {error.message}</p>}
-        </form>
-      )}
-    </Form>
-  )
-}
-```
+Each model defines `readable` (what comes out of the database) and `writable` (what users can create or modify):
 
-## Core Concepts
+```ts
+// app/todos/schema.ts
+import z from 'zod'
 
-### 1. Forms: The N8N for React
+export const readable = z.object({
+  id: z.string(),
+  title: z.string(),
+  done: z.boolean(),
+  author: z.string(),
+  createdAt: z.string(),
+})
 
-Think of forms like nodes in a visual workflow builder. Each form is self-contained, knows its state, and can trigger actions. Nest them to create complex workflows without state management headaches.
+export const writable = readable.pick({
+  title: true,
+  done: true,
+})
 
-```tsx
-// Multi-step form with async validation between steps
-<Form<EmailFields, EmailResult>
-  defaults={{ email: '' }}
-  action={checkEmail}
->
-  {(emailForm) => (
-    <div>
-      <input
-        value={emailForm.fields.email}
-        onChange={(e) => emailForm.setField('email', e.target.value)}
-      />
-      <button onClick={emailForm.submit}>Next</button>
-
-      {emailForm.result?.exists && (
-        <Form<PasswordFields, PasswordResult>
-          defaults={{ userId: emailForm.result.userId, password: '' }}
-          action={verifyPassword}
-        >
-          {(passwordForm) => (
-            <input
-              type="password"
-              value={passwordForm.fields.password}
-              onChange={(e) => passwordForm.setField('password', e.target.value)}
-            />
-          )}
-        </Form>
-      )}
-    </div>
-  )}
-</Form>
-```
+export const schema = { readable, writable }
 
-### 2. Fields: State Without the Ceremony
+export type Readable = z.infer<typeof readable>
+export type Writable = z.infer<typeof writable>
+```
 
-Need just state management? Use `FieldsProvider`:
+All models are assembled into a single database schema file:
 
-```tsx
-import { FieldsProvider, useFields } from 'asasvirtuais/fields'
+```ts
+// app/schema.ts
+import { schema as todosSchema } from './todos/schema'
+import { schema as tagsSchema } from './tags/schema'
 
-function ProfileEditor() {
-  return (
-    <FieldsProvider<ProfileFields> defaults={{ name: '', bio: '' }}>
-      {({ fields, setField }) => (
-        <div>
-          <input
-            value={fields.name}
-            onChange={(e) => setField('name', e.target.value)}
-          />
-          <textarea
-            value={fields.bio}
-            onChange={(e) => setField('bio', e.target.value)}
-          />
-        </div>
-      )}
-    </FieldsProvider>
-  )
+export const schema = {
+  todos: todosSchema,
+  tags: tagsSchema,
 }
 ```
 
-### 3. Actions: Async Operations Made Simple
+---
 
-Need just action handling? Use `ActionProvider`:
+### 2. Server actions — the backend
 
-```tsx
-import { ActionProvider } from 'asasvirtuais/action'
+The backend is plain Next.js server actions. You pass them directly to the provider — no REST routes, no fetch client needed:
 
-function DeleteButton({ userId }: { userId: string }) {
-  return (
-    <ActionProvider
-      params={{ userId }}
-      action={deleteAccount}
-      onResult={() => alert('Account deleted')}
-    >
-      {({ submit, loading }) => (
-        <button onClick={submit} disabled={loading}>
-          {loading ? 'Deleting...' : 'Delete Account'}
-        </button>
-      )}
-    </ActionProvider>
-  )
+```ts
+// app/actions.ts
+'use server'
+
+import { firestoreInterface } from 'asasvirtuais-firebase/interface'
+import { auth0 } from '@/lib/auth0'
+
+const db = firestoreInterface()
+
+function clean(obj: any): any {
+  if (Array.isArray(obj)) return obj.map(clean)
+  if (obj !== null && typeof obj === 'object' && obj.constructor === Object) {
+    return Object.fromEntries(
+      Object.entries(obj)
+        .filter(([_, v]) => v !== undefined)
+        .map(([k, v]) => [k, clean(v)])
+    )
+  }
+  return obj
 }
-```
 
-## React Interface: Data-Driven Applications
+export const find = async (props: any) => db.find(props)
 
-The `react-interface` package provides components and hooks for building data-driven React apps. Define your schema once, and use the components directly—no initialization needed.
+export const list = async (props: any) => db.list(props)
 
-### Complete Todo App Example
+export const create = async (props: any) => {
+  const session = await auth0.getSession()
+  if (!session?.user) throw new Error('Unauthorized')
 
-#### 1. Define Your Schema
+  const data = clean({ ...props.data })
 
-```typescript
-// app/database.ts
-import { z } from 'zod';
+  if (props.table === 'todos') {
+    data.author = session.user.id
+    data.done = false
+    data.createdAt = new Date().toISOString()
+  }
 
-export const todoSchema = {
-  readable: z.object({
-    id: z.string(),
-    text: z.string(),
-    completed: z.boolean(),
-    createdAt: z.date(),
-  }),
-  writable: z.object({
-    text: z.string(),
-    completed: z.boolean().optional(),
-  }),
+  return db.create({ ...props, data })
 }
 
-// You can export multiple schemas
-export const userSchema = {
-  readable: z.object({
-    id: z.string(),
-    name: z.string(),
-    email: z.string(),
-  }),
-  writable: z.object({
-    name: z.string(),
-    email: z.string(),
-  }),
+export const update = async (props: any) => {
+  const session = await auth0.getSession()
+  if (!session?.user) throw new Error('Unauthorized')
+
+  const data = clean({ ...props.data })
+
+  if (props.table === 'todos') {
+    const existing = await db.find({ table: 'todos', id: props.id })
+    if (existing.author !== session.user.id) throw new Error('Forbidden')
+  }
+
+  return db.update({ ...props, data })
+}
+
+export const remove = async (props: any) => {
+  const session = await auth0.getSession()
+  if (!session?.user) throw new Error('Unauthorized')
+
+  if (props.table === 'todos') {
+    const existing = await db.find({ table: 'todos', id: props.id })
+    if (existing.author !== session.user.id) throw new Error('Forbidden')
+  }
+
+  return db.remove(props)
 }
 ```
 
-#### 2. Provide the Interface Context
+This is where business logic lives: auth, default values, permission checks. All in one place, all readable top to bottom.
+
+---
+
+### 3. Providers
 
 ```tsx
-// app/layout.tsx
-import { InterfaceProvider } from 'asasvirtuais/fetch-interface'
-import { DatabaseProvider, TableProvider } from 'asasvirtuais/react-interface'
-import { todoSchema } from './database'
+// app/providers.tsx
+import { InterfaceProvider } from 'asasvirtuais/interface-provider'
+import { DatabaseProvider } from 'asasvirtuais/react-interface'
+import { TodosProvider } from '@/app/todos/provider'
+import * as db from '@/app/actions'
 
-export default function RootLayout({ children }) {
+export default function AppProviders({ children }: { children: React.ReactNode }) {
   return (
-    <DatabaseProvider>
-      <InterfaceProvider schema={todoSchema} baseUrl='/api/v1'>
+    <InterfaceProvider
+      find={db.find}
+      list={db.list}
+      create={db.create}
+      update={db.update}
+      remove={db.remove}
+    >
+      <DatabaseProvider>
         <TodosProvider>
           {children}
         </TodosProvider>
-      </InterfaceProvider>
-    </DatabaseProvider>
+      </DatabaseProvider>
+    </InterfaceProvider>
   )
 }
 ```
 
-#### 3. Create Your Table Provider
-
 ```tsx
-// app/todos/provider.tsx
-'use client'
-import { TableProvider } from 'asasvirtuais/react-interface'
-import { useInterface } from 'asasvirtuais/fetch-interface'
-import { todoSchema } from './database'
+// app/layout.tsx
+import AppProviders from './providers'
 
-export function TodosProvider({ children }) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <TableProvider
-      table='todos'
-      schema={todoSchema}
-      interface={useInterface()}
-    >
-      {children}
-    </TableProvider>
+    <html lang="en">
+      <body>
+        <AppProviders>
+          {children}
+        </AppProviders>
+      </body>
+    </html>
   )
 }
 ```
 
-#### 4. Build Your UI
+---
+
+### 4. Model provider
 
 ```tsx
-// app/todos/page.tsx
+// app/todos/provider.tsx
 'use client'
-import { useTable, CreateForm } from '@asasvirtuais/react-interface'
-import { todoSchema } from '@/app/database'
+import { TableProvider, useTable } from 'asasvirtuais/react-interface'
+import { useInterface } from 'asasvirtuais/interface-provider'
+import { schema } from '.'
 
-function TodoList() {
-  const { index, remove, update } = useTable('todos', todoSchema)
-  const todos = Object.values(index.index)
+export function useTodos() {
+  return useTable('todos', schema)
+}
 
+export function TodosProvider({ children }: { children: React.ReactNode }) {
   return (
-    <>
-      <CreateForm
-        table="todos"
-        schema={todoSchema}
-        defaults={{ text: '' }}
-      >
-        {({ fields, setField, submit, loading }) => (
-          <form onSubmit={submit}>
-            <input
-              value={fields.text}
-              onChange={(e) => setField('text', e.target.value)}
-              placeholder="What needs to be done?"
-            />
-            <button type="submit" disabled={loading}>
-              {loading ? 'Adding...' : 'Add Todo'}
-            </button>
-          </form>
-        )}
-      </CreateForm>
-
-      <ul>
-        {todos.map(todo => (
-          <li key={todo.id}>
-            <span
-              style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}
-              onClick={() => update.trigger({ 
-                id: todo.id, 
-                data: { completed: !todo.completed } 
-              })}
-            >
-              {todo.text}
-            </span>
-            <button onClick={() => remove.trigger({ id: todo.id })}>
-              Delete
-            </button>
-          </li>
-        ))}
-      </ul>
-    </>
+    <TableProvider table="todos" schema={schema} interface={useInterface()}>
+      {children}
+    </TableProvider>
   )
 }
 ```
 
-#### 5. Multiple Tables with DatabaseProvider
+---
 
-For apps with multiple tables, wrap them all in a DatabaseProvider:
+### 5. UI
 
 ```tsx
-// app/layout.tsx
-import { DatabaseProvider, TableProvider } from '@asasvirtuais/react-interface'
-import { todoSchema, userSchema } from './database'
-import { todosInterface, usersInterface } from './interface'
-
-export default async function RootLayout({ children }) {
-  const [initialTodos, initialUsers] = await Promise.all([
-    fetchTodos(),
-    fetchUsers()
-  ])
-  
-  return (
-    <DatabaseProvider>
-      <TableProvider table="todos" schema={todoSchema} interface={todosInterface} asAbove={initialTodos}>
-        <TableProvider table="users" schema={userSchema} interface={usersInterface} asAbove={initialUsers}>
-          {children}
-        </TableProvider>
-      </TableProvider>
-    </DatabaseProvider>
-  )
-}
-
-// Now any component can access tables:
-function MyComponent() {
-  const todos = useTable('todos', todoSchema)
-  const users = useTable('users', userSchema)
-  // ...
-}
-```
+// app/todos/page.tsx
+'use client'
+import { useEffect } from 'react'
+import { useTodos } from './provider'
+import { SingleProvider } from 'asasvirtuais/react-interface'
+import { schema } from '.'
+import { TodoItem } from './components'
+import { CreateTodo } from './forms'
 
-## Advanced Examples
+export default function TodosPage() {
+  const { array, list } = useTodos()
 
-### Multi-Step Address Validation
+  useEffect(() => { list.trigger({}) }, [])
 
-```tsx
-// Complete checkout flow with async address lookup
-<Form<AddressLookupFields, AddressLookupResult>
-  defaults={{ zipCode: '' }}
-  action={lookupAddress}
->
-  {(zipForm) => (
+  return (
     <div>
-      <h3>Enter ZIP Code</h3>
-      <input
-        value={zipForm.fields.zipCode}
-        onChange={(e) => zipForm.setField('zipCode', e.target.value)}
-      />
-      <button onClick={zipForm.submit}>Lookup Address</button>
-
-      {zipForm.result && (
-        <Form<FullAddressFields, OrderResult>
-          defaults={{
-            zipCode: zipForm.fields.zipCode,
-            city: zipForm.result.city,
-            state: zipForm.result.state,
-            country: zipForm.result.country,
-            street: '',
-            number: ''
-          }}
-          action={createOrder}
-          onResult={(result) => alert(`Order created: ${result.orderId}`)}
-        >
-          {(addressForm) => (
-            <div>
-              <h3>Complete Address</h3>
-              <p>City: {addressForm.fields.city}</p>
-              <p>State: {addressForm.fields.state}</p>
-              <input
-                value={addressForm.fields.street}
-                onChange={(e) => addressForm.setField('street', e.target.value)}
-                placeholder="Street"
-              />
-              <input
-                value={addressForm.fields.number}
-                onChange={(e) => addressForm.setField('number', e.target.value)}
-                placeholder="Number"
-              />
-              <button onClick={addressForm.submit}>Place Order</button>
-            </div>
-          )}
-        </Form>
-      )}
+      <CreateTodo />
+      {array.map(todo => (
+        <SingleProvider key={todo.id} id={todo.id} table="todos" schema={schema}>
+          <TodoItem />
+        </SingleProvider>
+      ))}
     </div>
-  )}
-</Form>
+  )
+}
 ```
 
-## Effects and Side Effects
-
-One of asasvirtuais's core strengths is making effects simple. No middleware arrays, no lifecycle hooks—just write code where it belongs.
+When `create` resolves, the item appears in `array` immediately. Same for `update` and `remove`.
 
-### Frontend Effects (React)
+---
 
-In React, you control exactly when effects happen by writing code around form actions.
+## Listing vs. filtering
 
-#### Pre-flight Effects
+### `useTable().list` — reactive, global
 
-Run code before submission:
+Use this when you want all records in the reactive index. Results live in `array` and stay in sync with every create, update, and remove automatically:
 
 ```tsx
-import { CreateForm } from '@asasvirtuais/react-interface'
-import { messageSchema } from '@/app/database'
+const { array, list } = useTodos()
 
-<CreateForm
-  table="messages"
-  schema={messageSchema}
-  defaults={{ content: '' }}
->
-  {({ fields, setField, submit, loading }) => (
-    <form onSubmit={submit}>
-      <textarea
-        value={fields.content}
-        onChange={(e) => setField('content', e.target.value)}
-      />
-      <button
-        onClick={() => {
-          // Pre-flight effect - runs before submit
-          trackEvent('message_submit_clicked')
-          validateContent(fields.content)
-          submit()
-        }}
-        disabled={loading}
-      >
-        Send
-      </button>
-    </form>
-  )}
-</CreateForm>
-```
+useEffect(() => { list.trigger({}) }, [])
 
-#### Post-flight Effects
-
-Run code after successful submission:
-
-```tsx
-<CreateForm
-  table="messages"
-  schema={messageSchema}
-  defaults={{ content: '' }}
-  onSuccess={(message) => {
-    // Post-flight effects - run after success
-    notifyUser('Message sent!')
-    scrollToBottom()
-    trackAnalytics('message_created', { id: message.id })
-  }}
->
-  {({ fields, setField, submit }) => (
-    <form onSubmit={submit}>
-      {/* form fields */}
-    </form>
-  )}
-</CreateForm>
+// array updates automatically when any todo is created, updated, or removed
+return array.map(todo => (
+  <SingleProvider key={todo.id} id={todo.id} table="todos" schema={schema}>
+    <TodoItem />
+  </SingleProvider>
+))
 ```
 
-#### Using Field Values Without Submitting
+### `FilterForm` — local, paginated, or conditional
 
-Sometimes you want to use the form's field values without calling the server action:
+Use `FilterForm` when you need pagination, live search, or results that belong to the component rather than the global index. Results live in `form.result` and only update when `submit` is called:
 
 ```tsx
-<CreateForm
-  table="messages"
-  schema={messageSchema}
-  defaults={{ content: '' }}
->
-  {(form) => (
+import { FilterForm } from 'asasvirtuais/form'
+import { schema } from '.'
+
+<FilterForm table="todos" schema={schema} defaults={{ query: { done: false } }} autoTrigger>
+  {({ result, loading, fields, setField, submit }) => (
     <div>
-      <textarea
-        value={form.fields.content}
-        onChange={(e) => form.setField('content', e.target.value)}
+      <input
+        placeholder="Search..."
+        value={fields.query?.title ?? ''}
+        onChange={e => {
+          setField('query', { title: e.target.value })
+          submit()
+        }}
       />
-      
-      {/* This button calls the server action */}
-      <button onClick={form.submit}>Send to Server</button>
-      
-      {/* This button uses field values without calling the action */}
-      <button onClick={() => {
-        // Just use the field values directly for local operations
-        saveToLocalStorage(form.fields)
-        showPreview(form.fields)
-      }}>
-        Save Draft Locally
-      </button>
+      {loading && <p>Loading...</p>}
+      {result?.map(todo => <p key={todo.id}>{todo.title}</p>)}
     </div>
   )}
-</CreateForm>
-```
-
-### Backend Effects (API Routes)
-
-On the backend, effects are just functions wrapping other functions. No framework magic.
-
-#### Using tableInterface for Business Logic
-
-```typescript
-// app/api/v1/[...params]/route.ts
-import { tableInterface } from '@asasvirtuais/interface'
-import { firestoreInterface } from '@/lib/firestore'
-import { messageSchema } from '@/app/database'
-
-// Wrap your base interface with business logic
-const messagesInterface = tableInterface(messageSchema, 'messages', {
-  async create(props) {
-    // Pre-flight validation
-    await checkUserQuota(props.data.userId)
-    await moderateContent(props.data.content)
-    
-    // The actual database operation
-    const message = await firestoreInterface.create(props)
-    
-    // Post-flight side effects
-    await updateConversationTimestamp(message.conversationId)
-    await notifyParticipants(message.conversationId, message.id)
-    await trackMessageCreated(message)
-    
-    return message
-  },
-  
-  async update(props) {
-    const existing = await firestoreInterface.find(props)
-    
-    // Business rule enforcement
-    if (existing.role === 'assistant') {
-      throw new Error("Cannot edit assistant messages")
-    }
-    
-    if (existing.userId !== getCurrentUserId()) {
-      throw new Error("Cannot edit other users' messages")
-    }
-    
-    return firestoreInterface.update(props)
-  },
-  
-  async remove(props) {
-    const message = await firestoreInterface.find(props)
-    
-    // Cascade deletion
-    await deleteMessageAttachments(message.id)
-    await updateConversationCount(message.conversationId, -1)
-    
-    return firestoreInterface.remove(props)
-  },
-  
-  // Pass through operations that don't need custom logic
-  find: firestoreInterface.find,
-  list: firestoreInterface.list,
-})
-```
-
-### Key Principles
-
-1. **Effects are just code** - No special lifecycle methods or middleware patterns
-2. **Control flow is visible** - Reading the code tells you exactly what runs and when
-3. **Composition over configuration** - Wrap functions to add behavior, don't configure hooks
-4. **Backend and frontend mirror each other** - The same compositional patterns work everywhere
-
-## API Reference
-
-### `Form<Fields, Result>`
-
-Combined fields and action management.
-
-**Props:**
-- `defaults?: Partial<Fields>` - Initial field values
-- `action: (fields: Fields) => Promise<Result>` - Async action to perform
-- `onResult?: (result: Result) => void` - Success callback
-- `onError?: (error: Error) => void` - Error callback
-- `autoTrigger?: boolean` - Auto-trigger action on mount
-- `children: ReactNode | (props) => ReactNode` - Render prop or children
-
-**Render Props:**
-- `fields: Fields` - Current field values
-- `setField: (name, value) => void` - Update single field
-- `setFields: (fields) => void` - Update multiple fields
-- `submit: (e?) => Promise<void>` - Trigger action
-- `loading: boolean` - Action loading state
-- `result: Result | null` - Action result
-- `error: Error | null` - Action error
-
-### `FieldsProvider<T>`
-
-Field state management only.
-
-**Props:**
-- `defaults?: Partial<T>` - Initial field values
-- `children: ReactNode | (props) => ReactNode` - Render prop or children
-
-**Hook: `useFields<T>()`**
-- `fields: T` - Current field values
-- `setField: (name, value) => void` - Update single field
-- `setFields: (fields) => void` - Update multiple fields
-
-### `ActionProvider<Params, Result>`
-
-Action management only.
-
-**Props:**
-- `params: Partial<Params>` - Action parameters
-- `action: (params) => Promise<Result>` - Async action
-- `onResult?: (result: Result) => void` - Success callback
-- `onError?: (error: Error) => void` - Error callback
-- `autoTrigger?: boolean` - Auto-trigger on mount
-- `children: ReactNode | (props) => ReactNode` - Render prop or children
-
-**Hook: `useAction<Params, Result>()`**
-- `params: Partial<Params>` - Current parameters
-- `submit: (e?) => Promise<void>` - Trigger action
-- `loading: boolean` - Loading state
-- `result: Result | null` - Action result
-- `error: Error | null` - Action error
-
-## Philosophy
-
-### Code Maintainability Over Everything
-
-The industry has normalized spreading code across dozens of files with dependency injection, decorators, and "clean architecture" patterns that make simple things complicated. asasvirtuais takes the opposite approach:
-
-**Keep business logic in single, readable files.**
-
-When you can see all the logic in one place, you can reason about it. When logic is scattered, every change becomes archaeology.
-
-### Made for Humans and AI
-
-The patterns in asasvirtuais are simple enough that:
-- Junior developers can understand them in minutes
-- Senior developers appreciate the lack of ceremony
-- AI assistants can generate correct implementations on the first try
-
-This isn't about dumbing down—it's about removing accidental complexity.
-
-### Against "Babel Towering"
-
-The AI trend seems focused on generating massive codebases quickly, stacking abstraction on abstraction. That's how you build towers that fall.
-
-asasvirtuais is designed for the opposite: codebases that stay maintainable even as they grow.
-
-## Real-World Use
-
-I've used asasvirtuais with Airtable for data modeling on production projects. The combination of a simple frontend framework and a flexible backend lets you focus on solving actual problems instead of fighting your tools.
-
-## AI Integration
-
-Give AI the asasvirtuais documentation and watch it generate multi-step forms with async validation in a single file—something that would normally require multiple files, complex state management, and careful coordination.
-
-Try it with [Google AI Studio](https://ai.studio/apps/drive/1-MwQzpbgMZhRqSbpqQYX1IRpvj61F_l8).
-
-
-# Model Package Instructions
-
-A model package is a self-contained module that defines a data model and provides React components for interacting with that data. Based on the chat example, here's how to structure a model package:
-
-## File Structure
-
-```
-app/[model-name]/
-├── index.ts          # Schema definitions and types
-├── fields.tsx        # Individual form field components
-├── forms.tsx         # Complete form components
-└── table.tsx         # Provider and hooks for data access
+</FilterForm>
 ```
 
-## 1. Schema Definition (`index.ts`)
-
-Define your data model using Zod schemas:
-
-```typescript
-import z from 'zod'
-
-// Define the complete object structure (what comes from the database)
-export const readable = z.object({
-    id: z.string(),
-    // ... other fields that can be read
-})
-
-// Define which fields can be written/modified
-export const writable = readable.pick({
-    // ... fields that can be created/updated
-})
-
-// Export the schema object
-export const schema = { readable, writable }
-
-// Export TypeScript types
-export type Readable = z.infer<typeof readable>
-export type Writable = z.infer<typeof writable>
-```
+---
 
-**Key Points:**
-- `readable`: Full object schema including `id` and all readable fields
-- `writable`: Subset of fields that users can create/modify (typically excludes `id`)
-- Use `.pick()` to select fields from readable for writable
-- Export both the schema object and TypeScript types
+## Async selector fields
 
-## 2. Field Components (`fields.tsx`)
+When a form needs the user to pick a record from another table, `FilterForm` composes naturally inside a field component. The field reads and writes to the parent form's context via `useFields()` — no props needed to bridge them.
 
-Create reusable field components for individual form inputs:
+Say a todo can be tagged, and the user needs to search and select a tag while creating the todo:
 
-```typescript
-import { Input, InputProps } from '@chakra-ui/react'
+```tsx
+// app/todos/fields.tsx
 import { useFields } from 'asasvirtuais/fields'
+import { FilterForm } from 'asasvirtuais/form'
+import { schema as tagsSchema } from '@/app/tags'
 
-export function [FieldName]Field(props: InputProps) {
-    const { fields, setField } = useFields<{fieldName: type}>()
-    
-    return (
-        <Input 
-            name='fieldName' 
-            value={fields.fieldName} 
-            onChange={e => setField('fieldName', e.target.value)} 
-            {...props} 
-        />
-    )
+export function TagSelectorField() {
+  // reads/writes to whatever Form or FieldsProvider this is rendered inside
+  const { fields, setField } = useFields<{ tagId: string }>()
+
+  return (
+    <FilterForm table="tags" schema={tagsSchema} defaults={{ query: {} }}>
+      {({ fields: search, setField: setSearch, submit, result }) => (
+        <div>
+          <input
+            placeholder="Search tags..."
+            onChange={e => {
+              setSearch('query', { name: e.target.value })
+              submit()
+            }}
+          />
+          <ul>
+            {result?.map(tag => (
+              <li
+                key={tag.id}
+                onClick={() => setField('tagId', tag.id)}
+                style={{ fontWeight: fields.tagId === tag.id ? 'bold' : 'normal' }}
+              >
+                {tag.name}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </FilterForm>
+  )
 }
 ```
 
-**Key Points:**
-- Use `useFields` hook with type annotation matching your field
-- Pass through additional props using spread operator
-- Set appropriate `name` attribute
-- Handle `onChange` with `setField`
-
-## 3. Form Components (`forms.tsx`)
+Use it inside any form — it just works:
 
-Create complete forms for creating and filtering data:
-
-```typescript
-import { CreateForm, FilterForm, useTableInterface } from 'asasvirtuais/react-interface'
+```tsx
+// app/todos/forms.tsx
+import { CreateForm } from 'asasvirtuais/form'
 import { schema } from '.'
-import { [Field]Field } from './fields'
-import { Stack, Button } from '@chakra-ui/react'
-
-// Create form
-export function Create[Model]() {
-    return (
-        <CreateForm table='tableName' schema={schema}>
-            {form => (
-                <Stack as='form' onSubmit={form.submit}>
-                    <[Field]Field />
-                    <Button type='submit'>Create [Model]</Button>
-                </Stack>
-            )}
-        </CreateForm>
-    )
-}
+import { TitleField, TagSelectorField } from './fields'
 
-// Filter/List form
-export function Filter[Models]() {
-    const { remove } = useTableInterface('tableName', schema)
-    
-    return (
-        <FilterForm table='tableName' schema={schema}>
-            {form => (
-                <Stack>
-                    {form.result?.map(item => (
-                        <div key={item.id}>
-                            {/* Display item data */}
-                            <Button onClick={() => remove.trigger({id: item.id})}>
-                                Delete
-                            </Button>
-                        </div>
-                    ))}
-                </Stack>
-            )}
-        </FilterForm>
-    )
+export function CreateTodo({ onSuccess }: { onSuccess?: () => void }) {
+  return (
+    <CreateForm table="todos" schema={schema} defaults={{ title: '', tagId: '' }} onSuccess={onSuccess}>
+      {({ submit, loading }) => (
+        <div>
+          <TitleField />
+          <TagSelectorField />
+          <button onClick={submit} disabled={loading}>
+            {loading ? 'Creating...' : 'Create Todo'}
+          </button>
+        </div>
+      )}
+    </CreateForm>
+  )
 }
 ```
 
-**Key Points:**
-- `CreateForm` handles creation logic, provides `form.submit`
-- `FilterForm` provides `form.result` with filtered data
-- Use `useTableInterface` for operations like `remove`
-- Always provide `table` name and `schema` to forms
-
-## 4. Provider and Hooks (`table.tsx`)
+The `FilterForm` queries the `tags` table asynchronously. The `CreateForm` owns the selected `tagId`. Neither knows about the other.
 
-Set up the data provider and custom hooks using `InterfaceProvider` and `useInterface`:
-
-```typescript
-'use client'
-import { TableProvider, useTableInterface } from 'asasvirtuais/react-interface'
-import { useInterface } from 'asasvirtuais/fetch-interface'
-import { schema } from '.'
+---
 
-export function use[Models]() {
-    return useTableInterface('tableName', schema)
-}
+## The single record pattern
 
-export function [Models]Provider({ children }: { children: React.ReactNode }) {
-    return (
-        <TableProvider
-            table='tableName'
-            schema={schema}
-            interface={useInterface()}
-        >
-            {children}
-        </TableProvider>
-    )
-}
-```
-
-Then in your layout, wrap with `InterfaceProvider` to set up the context:
+`SingleProvider` makes a record available to all its descendants without prop drilling. When multiple components share one record, wrap them all in one provider:
 
 ```tsx
-import { InterfaceProvider } from 'asasvirtuais/fetch-interface'
-import { DatabaseProvider } from 'asasvirtuais/react-interface'
-import { [Models]Provider } from './table'
-import { schema } from '.'
-
-<DatabaseProvider>
-  <InterfaceProvider schema={schema} baseUrl='/api/v1'>
-    <[Models]Provider>
-      {children}
-    </[Models]Provider>
-  </InterfaceProvider>
-</DatabaseProvider>
-```
-
-**Key Points:**
-- Mark table.tsx as `'use client'` for Next.js
-- `InterfaceProvider` creates the fetch interface and provides it via context
-- `useInterface()` retrieves the interface from context inside `TableProvider`
-- Create a custom hook for easy access to table interface
-
-## Naming Conventions
-
-- **Model name**: Singular (e.g., `chat`, `user`, `product`)
-- **Table name**: Plural (e.g., `chats`, `users`, `products`)
-- **Field components**: `[Field]Field` (e.g., `TitleField`, `EmailField`)
-- **Form components**: `Create[Model]`, `Filter[Models]` (e.g., `CreateChat`, `FilterChats`)
-- **Provider**: `[Models]Provider` (e.g., `ChatsProvider`)
-- **Hook**: `use[Models]` (e.g., `useChats`)
-
-## Usage Example
-
-```typescript
-import { ChatsProvider } from './chat/table'
-import { CreateChat, FilterChats } from './chat/forms'
-
-function App() {
-    return (
-        <ChatsProvider>
-            <CreateChat />
-            <FilterChats />
-        </ChatsProvider>
-    )
+import { SingleProvider, useSingle } from 'asasvirtuais/react-interface'
+
+// Detail page
+<SingleProvider id={params.id} table="todos" schema={schema}>
+  <TodoDetail />
+  <UpdateTodoForm />
+  <DeleteTodoButton />
+</SingleProvider>
+
+// Inside any of those:
+function TodoDetail() {
+  const { single } = useSingle(schema, 'todos')
+  return <h1>{single.title}</h1>
 }
 ```
 
+If the record isn't in the reactive index yet, `SingleProvider` fetches it automatically.
 
-## Contributing
+---
+
+## Effects
 
-This is the result of years of meditation on overengineering. If you see ways to make it simpler (not more feature-rich, simpler), I'm interested.
+There is no middleware or lifecycle configuration. Effects are code written around the action:
 
-## License
+```tsx
+// Before submit
+<button onClick={() => {
+  validateForm(form.fields)
+  form.submit()
+}}>
+  Save
+</button>
+
+// After success
+<CreateForm
+  table="todos"
+  schema={schema}
+  onSuccess={todo => {
+    router.push(`/todos/${todo.id}`)
+    showNotification('Todo created!')
+  }}
+>
+  {/* ... */}
+</CreateForm>
 
-MIT
+// Using field values without submitting
+<button onClick={() => saveDraftLocally(form.fields)}>
+  Save Draft
+</button>
+```
 
 ---
 
-*Built by someone who spent 7 years learning that the hard way is usually the wrong way.*
+## Naming pattern examples
+
+| Concept | Pattern | Example |
+|---|---|---|
+| Table name | lowercase plural | `'todos'` |
+| Schema types | `Readable`, `Writable` | `type Readable = z.infer<...>` |
+| Field components | `{Field}Field` | `TitleField`, `DoneField` |
+| Provider | `{Model}sProvider` | `TodosProvider` |
+| Hook | `use{Model}s()` | `useTodos()` |
+| Create form | `Create{Model}` | `CreateTodo` |
+| Update form | `Update{Model}` | `UpdateTodo` |
+| Delete action | `Delete{Model}` | `DeleteTodo` |
+| Item component | `{Model}Item` | `TodoItem` |
+| Detail component | `Single{Model}` | `SingleTodo` |