Data Table Page

Quick Reference

Page Structure (Reference: Users Page)

app/(pages)/{feature}/
├── page.tsx                    # Server component - data fetching
├── _components/
│   ├── table/
│   │   ├── {feature}-table.tsx        # SWR setup + context provider
│   │   ├── {feature}-table-body.tsx   # DataTable + toolbars
│   │   ├── {feature}-table-columns.tsx # Column definitions
│   │   ├── {feature}-table-header.tsx  # Search, export, print
│   │   └── {feature}-table-controller.tsx # Bulk actions
│   ├── actions/
│   │   ├── actions-menu.tsx           # Row action buttons
│   │   └── add-{item}-button.tsx      # Add button
│   ├── filters/                       # Filter components
│   ├── sidebar/
│   │   └── status-panel.tsx           # Summary + filters sidebar
│   └── modal/
│       ├── add-{item}-sheet.tsx       # Create form
│       ├── edit-{item}-sheet.tsx      # Update form
│       └── view-{item}-sheet.tsx      # Read-only view
└── context/
    └── {feature}-actions-context.tsx  # CRUD actions context

Shared Components

API Layer Files

Core Data Flow

1. page.tsx (Server)
   ↓ Fetch initial data with server actions
   ↓ Pass to client component as initialData

2. {feature}-table.tsx (Client)
   ↓ SWR hook with fallbackData: initialData
   ↓ Define updateItems() for cache mutations
   ↓ Wrap children in ContextProvider

3. Column definitions
   ↓ Receive callbacks: updateItems, markUpdating, clearUpdating
   ↓ Call API → Update cache → Show toast

4. User interaction
   ↓ markUpdating([id]) → API call → updateItems([result]) → clearUpdating()

Key Patterns Summary

1. Server-Side Fetching (page.tsx)

export default async function Page({ searchParams }) {
  const data = await getData(limit, skip, filters);
  return <Table initialData={data} />;
}

2. SWR Setup (table.tsx)

const { data, mutate } = useSWR(apiUrl, fetcher, {
  fallbackData: initialData,
  keepPreviousData: true,
  revalidateOnMount: false,
});

3. Cache Update Function

const updateItems = async (updatedItems) => {
  await mutate((current) => ({
    ...current,
    items: current.items.map(item =>
      updatedMap.has(item.id) ? updatedMap.get(item.id) : item
    ),
  }), { revalidate: false });
};

4. Mutation Pattern

markUpdating([id]);
try {
  const result = await apiCall(id, data);
  await updateItems([result]);
  toast.success(message);
} finally {
  clearUpdating([id]);
}

For complete patterns, see PATTERNS.md.

Allowed Operations

DO:

• Create new table pages following the users page structure
• Add CRUD operations with optimistic updates
• Extend shared components for feature-specific needs
• Add new column definitions with callbacks
• Create context providers for actions
• Add server actions and client API functions

DON'T:

• Bypass SWR for data fetching
• Use useState for server data (use SWR)
• Call APIs directly from column cells without proper error handling
• Skip the context pattern for shared actions
• Create new pagination components (use shared Pagination)

Validation Checklist

Before completing data table work:

• Server component fetches initial data
• SWR uses fallbackData from server
• updateItems function updates cache correctly
• Mutations follow markUpdating → API → updateItems → clearUpdating
• Toast notifications on success/error
• Loading states show during operations
• URL state works for pagination/filters
• Context provides actions to nested components
• Types defined in types/{feature}.ts

Additional Resources

• REFERENCE.md - Complete API and component reference
• EXAMPLES.md - Full code examples for all patterns
• PATTERNS.md - Critical implementation patterns
• MODULES.md - Complete file inventory

Trigger Phrases

• "data table", "table page", "CRUD page"
• "server-side fetching", "SWR", "useSWR"
• "mutations", "updateUsers", "updateItems"
• "optimistic update", "cache invalidation"
• "column definitions", "createColumns"
• "row actions", "bulk operations"
• "pagination", "filters", "search"
• "add sheet", "edit sheet", "view sheet"
• "context provider", "actions context"