updates
This commit is contained in:
@@ -0,0 +1,304 @@
|
||||
---
|
||||
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"
|
||||
```
|
||||
Reference in New Issue
Block a user