---
name: crud-dialog
description: "Create CRUD dialogs for managing lookup/reference resources inline (inside a dialog) rather than a full page. Use when: adding a config/manage button next to a select field, building an inline CRUD for a simple lookup entity (e.g. insurance types, payment terms, categories), embedding list+create+edit+delete inside a modal. Uses the shared CrudDialog component and useCrudDialog hook."
---

# CRUD Dialog Generator

Create fully functional CRUD dialogs that embed list + create + edit + delete inside a modal dialog. This is the in-dialog counterpart of the page-level `ResourcePage` pattern. Ideal for managing simple lookup/reference entities without navigating away from the current form.

## When to Use

- User wants a config/settings button next to a select field to manage its options
- User wants to manage a simple lookup entity (e.g. insurance types, categories, tags) inline
- The resource is simple enough that a full page is overkill
- User says "CRUD in a dialog", "manage inside a modal", "config button", "inline CRUD"

## When NOT to Use

- The resource is complex with many fields, relations, or tabs → use **crud-page** skill instead
- The resource already has a dedicated page → link to it instead
- Only creation is needed (no listing/editing) → use `RhfAsyncSelectField` with `createForm` prop instead

## Architecture

The CRUD Dialog system has two layers:

| Layer | File | Purpose |
|-------|------|---------|
| **Hook** | `shared/components/crud-dialog/use-crud-dialog.ts` | Local state for pagination, sorting, form open/close, delete confirmation. No URL pollution. |
| **Component** | `shared/components/crud-dialog/crud-dialog.tsx` | Renders trigger button → Dialog with DataTable (list view) ↔ Form (create/edit view). Uses `useCrudDialog` internally. |

### Key Differences from ResourcePage

| Aspect | ResourcePage | CrudDialog |
|--------|-------------|------------|
| Renders in | Full page | Dialog modal |
| Pagination state | URL query params (`nuqs`) | Local `useState` (no URL pollution) |
| Form rendering | `FormDialog` component | Inline view swap (list ↔ form) |
| Trigger | Page navigation | Button click (settings icon by default) |
| Use case | Primary resource management | Lookup/reference entity management |

## Procedure

### Step 1: Ensure API Client Exists

The resource needs a client with `list`, `create`, `update`, `destroy` methods. Check `packages/api/src/clients/`. If missing, create one following the **crud-page** skill's Step 2.

### Step 2: Create the Resource Form

Create a simple form component for the resource. This is a lightweight form (no `useResourceForm` needed for simple entities).

**File**: `apps/dashboard/modules/<parent-module>/<resource>-form.tsx`

**Template**:

```tsx
"use client"

import { z } from "zod"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { Plus, Save } from "lucide-react"
import { Button } from "@/shared/components/ui/button"
import { FieldGroup } from "@/shared/components/ui/field"
import { Rhform, RhfTextField } from "@/shared/components/form"
import { toast } from "sonner"
import { useAuthApi } from "@/shared/useApi"
import { useEffect } from "react"

const schema = z.object({
    name: z.string().min(1, "Name is required"),
    // Add more fields as needed
})

type FormValues = z.infer<typeof schema>

type Props = {
    resourceId?: string | null
    initialData?: any
    onSuccess?: () => void
}

export function <Resource>Form({ resourceId, initialData, onSuccess }: Props) {
    const api = useAuthApi()
    const isEditing = !!resourceId

    const form = useForm<FormValues>({
        resolver: zodResolver(schema),
        defaultValues: { name: "" },
    })

    // Pre-fill when editing
    useEffect(() => {
        if (initialData) {
            const d = initialData?.data ?? initialData
            form.reset({ name: d.name ?? "" })
        }
    }, [initialData, form])

    const handleSubmit = async (values: FormValues) => {
        try {
            const promise = isEditing
                ? api.<resource>.update(resourceId!, { title: values.name } as any)
                : api.<resource>.create({ title: values.name } as any)

            toast.promise(promise, {
                loading: isEditing ? "Updating..." : "Creating...",
                success: isEditing ? "Updated successfully" : "Created successfully",
                error: isEditing ? "Failed to update" : "Failed to create",
            })

            await promise
            form.reset()
            onSuccess?.()
        } catch {
            // toast already shown
        }
    }

    return (
        <Rhform form={form} onSubmit={handleSubmit}>
            <FieldGroup>
                <RhfTextField name="name" label="Name" placeholder="e.g. My Item" required />
                <Button type="submit" disabled={form.formState.isSubmitting}>
                    {isEditing ? <Save className="h-4 w-4" /> : <Plus className="h-4 w-4" />}
                    {form.formState.isSubmitting
                        ? (isEditing ? "Updating..." : "Creating...")
                        : (isEditing ? "Update" : "Create")}
                </Button>
            </FieldGroup>
        </Rhform>
    )
}
```

### Step 3: Create the CrudDialog Instance

Wire the form into a `CrudDialog` component.

**File**: `apps/dashboard/modules/<parent-module>/<resource>-crud-dialog.tsx`

**Template**:

```tsx
"use client"

import { CrudDialog } from "@/shared/components/crud-dialog"
import { ColumnHeader } from "@/shared/data-view/table-view"
import { useAuthApi } from "@/shared/useApi"
import { <RESOURCE>_ROUTES } from "@garage/api"
import { <Resource>Form } from "./<resource>-form"

export function <Resource>CrudDialog() {
    const api = useAuthApi()

    return (
        <CrudDialog
            title="<Resource Label>"
            queryKey={[<RESOURCE>_ROUTES.INDEX]}
            getClient={() => api.<resource>}
            resourceLabel="<resource label>"
            columns={() => [
                {
                    accessorKey: "name",
                    header: ({ column }) => <ColumnHeader column={column} title="Name" />,
                },
                // Add more columns as needed
            ]}
            renderForm={({ resourceId, initialData, onSuccess }) => (
                <<Resource>Form
                    resourceId={resourceId}
                    initialData={initialData}
                    onSuccess={onSuccess}
                />
            )}
        />
    )
}
```

### Step 4: Wire into the Parent Form

Place the CrudDialog trigger next to the corresponding select field. The pattern is to add a custom label row with the config button:

```tsx
import { <Resource>CrudDialog } from "./<resource>-crud-dialog"

// Inside the form JSX:
<div>
    <div className="flex items-center justify-between mb-1">
        <span className="text-sm font-medium"><Field Label></span>
        <<Resource>CrudDialog />
    </div>
    <RhfAsyncSelectField
        name="<field_name>"
        label=""
        placeholder="Select..."
        queryKey={[<RESOURCE>_ROUTES.INDEX]}
        listFn={() => api.<resource>.list()}
        mapOption={mapLookupOption}
        {...STORE_OBJECT}
    />
</div>
```

**Key**: Set `label=""` on the `RhfAsyncSelectField` since the label is rendered manually above with the config button.

## CrudDialog Props Reference

```typescript
type CrudDialogProps<TClient> = {
    /** Dialog title shown in the header */
    title: string
    /** React Query cache key */
    queryKey: string[]
    /** Function returning the API client instance */
    getClient: () => TClient
    /** Human-readable name for toast messages (e.g. "insurance type") */
    resourceLabel?: string
    /** Table columns definition */
    columns: (helpers: {
        openEdit: (row: any) => void
        handleDelete: (row: any) => Promise<void>
    }) => ColumnDef<any>[]
    /** Render create/edit form */
    renderForm: (props: {
        resourceId: string | null
        initialData: any
        onSuccess: () => void
    }) => React.ReactNode
    /** Optional custom trigger element (defaults to Settings2 icon) */
    trigger?: React.ReactNode
    /** CSS class for the default trigger button */
    triggerClassName?: string
}
```

## useCrudDialog Hook API

For advanced use cases where you need more control, use the hook directly:

```typescript
const crud = useCrudDialog({
    queryKey: [ROUTES.INDEX],
    getClient: () => api.resource,
    resourceLabel: "item",
})

// Returns:
crud.items          // Current page data
crud.isLoading      // Query loading state
crud.pagination     // { page, pageSize, pageCount, total }
crud.sorting        // SortingState
crud.handleChange   // DataViewChangeEvent handler
crud.isFormOpen     // Whether form view is active
crud.editingId      // ID being edited (null for create)
crud.editingItem    // Full item data being edited
crud.openCreate()   // Switch to create form
crud.openEdit(row)  // Switch to edit form
crud.closeForm()    // Back to list view
crud.handleDelete(row) // Confirm + delete
crud.handleFormSuccess() // Invalidate + close form
crud.invalidateQuery()  // Refresh list data
```

## Real Example: Insurance Type

See the implementation in `apps/dashboard/modules/job-cards/`:

- [insurance-type-form.tsx](../../apps/dashboard/modules/job-cards/insurance-type-form.tsx) — Simple form with one "name" field
- [insurance-type-crud-dialog.tsx](../../apps/dashboard/modules/job-cards/insurance-type-crud-dialog.tsx) — CrudDialog wiring
- [job-card-form.tsx](../../apps/dashboard/modules/job-cards/job-card-form.tsx) — Usage next to the insurance type select field

## Naming Conventions

| Item | Pattern | Example |
|------|---------|---------|
| Form file | `modules/<parent>/<resource>-form.tsx` | `job-cards/insurance-type-form.tsx` |
| CrudDialog file | `modules/<parent>/<resource>-crud-dialog.tsx` | `job-cards/insurance-type-crud-dialog.tsx` |
| Form component | `<Resource>Form` | `InsuranceTypeForm` |
| CrudDialog component | `<Resource>CrudDialog` | `InsuranceTypeCrudDialog` |

## Imports Cheat Sheet

```tsx
// CrudDialog component
import { CrudDialog } from "@/shared/components/crud-dialog"

// Table column header
import { ColumnHeader } from "@/shared/data-view/table-view"

// API
import { useAuthApi } from "@/shared/useApi"
import { <RESOURCE>_ROUTES } from "@garage/api"

// Form components (for the resource form)
import { Rhform, RhfTextField } from "@/shared/components/form"
import { Button } from "@/shared/components/ui/button"
import { FieldGroup } from "@/shared/components/ui/field"
import { z } from "zod"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { toast } from "sonner"
```