denwa-react-shared/skills/admin-table/SKILL.md

---
name: admin-table
description: >
  Implement complex data tables using AdminTable and useFetchTableData. 
  Covers columns configuration, server-side filtering, sorting, 
  and search state mapping.
type: framework
library: denwa-react-shared
framework: react
library_version: "1.0.88"
requires:
  - session-auth
sources:
  - "Denwa799/react-shared:src/shared/ui/admin-table/index.tsx"
  - "Denwa799/react-shared:src/shared/lib/hooks/use-fetch-table-data.ts"
---

# Admin Table & Data Fetching

The `AdminTable` component is the centerpiece for building resource lists. It works in conjunction with `useFetchTableData` to map UI states (search, sort, page) to API filters.

## Setup

```tsx
import { AdminTable, useFetchTableData } from 'denwa-react-shared';
import { ColumnsType } from 'antd/es/table';

const UsersPage = () => {
  // 1. Setup state setters (usually from nuqs or local state)
  const [order, setOrder] = useState('createdAtDesc');
  const [search, setSearch] = useState('');
  
  // 2. Use hook to get mapped filters/sort for API
  const { filter, sort, onChangeOrder, ...searchHandlers } = useFetchTableData({
    order,
    search,
    onSetOrder: setOrder,
    onSetSearch: setSearch,
    // ... other setters for pagination, radio, date search
    sortFields: [{ key: 'createdAtDesc', field: 'createdAt', order: 'desc' }],
    searchFields: ['name', 'email'],
    // ... field configuration
  });

  // 3. Render table
  return (
    <AdminTable
      tableData={data}
      columns={columns}
      order={order}
      onChangeOrder={onChangeOrder}
      searchProps={{
        ...searchHandlers,
        // ... text labels
      }}
      // ... actions and text props
    />
  );
};
```

## Core Patterns

### Configuring Search and Filters
`searchProps` expects a `TableSearchProps` object. Ensure you provide the `datePickerComponent` and all required handlers from `useFetchTableData`.

```tsx
<AdminTable
  searchProps={{
    datePickerComponent: BaseDatePicker,
    searchText: 'Поиск',
    noDateText: 'Нет даты',
    emptyText: 'Ничего не найдено',
    searchSelect: currentSearchField,
    radioOptions: [{ label: 'Все', value: 'all' }],
    searchOptions: [{ label: 'Имя', value: 'name' }],
    searchType: 'text',
    onChangeSearch: handleFieldChange,
    onChangeTextSearch: handleTextChange,
  }}
  // ...
/>
```

### Server-Side Pagination
The table expects `serverPagination` prop of type `IPaginate`.

```tsx
<AdminTable
  serverPagination={{
    total: totalItems,
    page: currentPage,
    limit: pageSize,
  }}
  onSetPaginate={(page, limit) => {
    setPage(page);
    setLimit(limit);
  }}
/>
```

## Common Mistakes

### HIGH Hallucinating internal state management
Wrong:
```tsx
// Trying to use useFetchTableData without passing external setters
const tableInfo = useFetchTableData({
  order: 'desc', // Static value
  // Missing onSetOrder, onSetSearch, etc.
});
```
Correct:
```tsx
const [order, setOrder] = useState('desc');
const tableInfo = useFetchTableData({
  order,
  onSetOrder: setOrder,
  // Must provide setters to allow the hook to update external state
});
```
The hook acts as a logic mapper and relies on external state (like `nuqs` or `useState`) to persist changes.

Source: maintainer interview

### HIGH Passings wrong pagination format
Wrong:
```tsx
// Using antd internal pagination object
<AdminTable serverPagination={{ current: 1, pageSize: 10 }} />
```
Correct:
```tsx
<AdminTable serverPagination={{ page: 1, limit: 10, total: 100 }} />
```
`AdminTable` expects a custom `IPaginate` shape, not the standard Ant Design pagination object.

Source: src/shared/ui/admin-table/types.ts

### MEDIUM Using raw antd Table
Wrong:
```tsx
import { Table } from 'antd';
return <Table dataSource={data} columns={columns} />;
```
Correct:
```tsx
import { AdminTable } from 'denwa-react-shared';
return <AdminTable tableData={data} columns={columns} ... />;
```
Using raw `Table` loses integrated search UI, standardized skeletons, and the "Drawer Form" orchestration.

Source: maintainer interview