turash/bugulma/frontend/components/admin/README.md

# Admin Feature Components

Reusable feature components for the admin panel, built based on the ADMIN_PANEL_CONCEPT.md specification.

## Components Overview

### Layout Components

#### `AdminLayout`
Main layout component with sidebar navigation, header, and content area.

**Features:**
- Collapsible sidebar with navigation items
- Expandable menu items with children
- User menu with dropdown
- Notifications indicator
- Responsive design (mobile-friendly)
- Breadcrumbs support

**Usage:**
```tsx
<AdminLayout title="Dashboard" breadcrumbs={[...]}>
  {/* Page content */}
</AdminLayout>
```

### Data Management Components

#### `DataTable`
Enhanced data table with built-in pagination, sorting, filtering, selection, and actions.

**Features:**
- Column-based rendering
- Sortable columns
- Row selection (single/multiple)
- Bulk actions
- Search integration
- Pagination
- Loading states
- Mobile card view
- Action menus per row

**Usage:**
```tsx
<DataTable
  data={organizations}
  columns={columns}
  getRowId={(org) => org.id}
  pagination={{ currentPage, totalPages, pageSize, totalItems, onPageChange }}
  sorting={{ column, direction, onSort }}
  search={{ value, onChange }}
  selection={{ selectedRows, onSelectionChange }}
  actions={[
    { label: 'Edit', icon: <Edit />, onClick: (org) => {} },
    { label: 'Delete', variant: 'destructive', onClick: (org) => {} },
  ]}
  bulkActions={[
    { label: 'Delete Selected', icon: <Trash2 />, onClick: (ids) => {} },
  ]}
/>
```

#### `FilterBar`
Advanced filtering component with multiple filter types.

**Features:**
- Multiple filter types (select, multiselect, text, number, date, daterange)
- Active filter indicators
- Clear all filters
- Filter tags display
- Popover-based UI

**Usage:**
```tsx
<FilterBar
  filters={[
    { id: 'status', label: 'Status', type: 'select', options: [...] },
    { id: 'sector', label: 'Sector', type: 'multiselect', options: [...] },
  ]}
  values={filterValues}
  onChange={setFilterValues}
/>
```

#### `SearchAndFilter`
Combined search and filter component.

**Usage:**
```tsx
<SearchAndFilter
  search={{ value, onChange, placeholder: 'Search...' }}
  filters={{ filters, values, onChange }}
/>
```

### Page Components

#### `PageHeader`
Enhanced page header with title, subtitle, breadcrumbs, and actions.

**Features:**
- Title and subtitle
- Breadcrumbs navigation
- Back button
- Action buttons (primary and secondary)
- Action menu dropdown

**Usage:**
```tsx
<PageHeader
  title="Organizations"
  subtitle="Manage all organizations"
  breadcrumbs={[{ label: 'Admin', href: '/admin' }, { label: 'Organizations' }]}
  actions={[
    { label: 'New Organization', icon: <Plus />, onClick: () => {} },
    { label: 'Export', variant: 'outline', onClick: () => {} },
  ]}
  onBack={() => navigate(-1)}
/>
```

#### `StatCard`
Enhanced stat card for dashboard metrics.

**Features:**
- Icon with color variants
- Value display
- Subtext
- Trend indicators (up/down with percentage)
- Clickable navigation
- Color variants (primary, success, warning, info)

**Usage:**
```tsx
<StatCard
  title="Total Organizations"
  value={1234}
  icon={<Building2 />}
  subtext="All time"
  trend={{ value: 12.5, label: 'vs last month', isPositive: true }}
  onClick={() => navigate('/admin/organizations')}
  color="primary"
/>
```

#### `FormSection`
Component for grouping related form fields.

**Features:**
- Title and description
- Collapsible option
- Actions in header
- Card-based layout

**Usage:**
```tsx
<FormSection
  title="Basic Information"
  description="Enter the basic details"
  collapsible
>
  {/* Form fields */}
</FormSection>
```

#### `SettingsSection`
Component for settings pages.

**Usage:**
```tsx
<SettingsSection
  title="General Settings"
  description="Configure general application settings"
  actions={<Button>Save</Button>}
>
  {/* Settings fields */}
</SettingsSection>
```

#### `ChartCard`
Wrapper component for charts with export and refresh.

**Features:**
- Title and description
- Export button
- Refresh button
- Loading state
- Custom actions

**Usage:**
```tsx
<ChartCard
  title="Economic Connections"
  description="Visualization of sector connections"
  onExport={() => {}}
  onRefresh={() => {}}
  isLoading={false}
>
  {/* Chart component */}
</ChartCard>
```

#### `ActivityFeed`
Component for displaying system activity logs.

**Features:**
- Activity items with user avatars
- Activity types (create, update, delete, verify, login)
- Timestamp formatting
- Loading states
- Load more functionality
- Empty states

**Usage:**
```tsx
<ActivityFeed
  activities={activities}
  isLoading={false}
  onLoadMore={() => {}}
  hasMore={true}
/>
```

## Component Relationships

```
AdminLayout
├── Sidebar Navigation
├── Header (with user menu, notifications)
└── Main Content
    ├── PageHeader
    │   ├── Breadcrumbs
    │   └── Actions
    ├── SearchAndFilter
    │   ├── SearchBar
    │   └── FilterBar
    ├── DataTable
    │   ├── ResponsiveTable (from ui primitives)
    │   ├── Pagination
    │   └── Bulk Actions
    ├── StatCard (for dashboard)
    ├── ChartCard (for analytics)
    ├── FormSection (for forms)
    ├── SettingsSection (for settings)
    └── ActivityFeed (for activity logs)
```

## Design Principles

All components follow:
- **Consistency**: Unified design system
- **Accessibility**: ARIA labels, keyboard navigation
- **Responsiveness**: Mobile-first design
- **Type Safety**: Full TypeScript support
- **Composability**: Components work together seamlessly
- **Performance**: Optimized rendering and state management

## Usage Examples

### Complete Admin Page Example

```tsx
import { AdminLayout, PageHeader, DataTable, SearchAndFilter } from '@/components/admin';

const OrganizationsPage = () => {
  const [search, setSearch] = useState('');
  const [filters, setFilters] = useState({});
  const [selectedRows, setSelectedRows] = useState(new Set());

  return (
    <AdminLayout title="Organizations">
      <PageHeader
        title="Organizations"
        subtitle="Manage all organizations in the system"
        actions={[
          { label: 'New Organization', onClick: () => {} },
          { label: 'Export', variant: 'outline', onClick: () => {} },
        ]}
      />

      <SearchAndFilter
        search={{ value: search, onChange: setSearch }}
        filters={{
          filters: filterOptions,
          values: filters,
          onChange: setFilters,
        }}
      />

      <DataTable
        data={organizations}
        columns={columns}
        getRowId={(org) => org.id}
        search={{ value: search, onChange: setSearch }}
        selection={{ selectedRows, onSelectionChange: setSelectedRows }}
        pagination={pagination}
        sorting={sorting}
        actions={tableActions}
        bulkActions={bulkActions}
      />
    </AdminLayout>
  );
};
```

## Next Steps

These components are ready to be used in admin pages. They provide:
- ✅ Complete layout structure
- ✅ Data management capabilities
- ✅ Form and settings organization
- ✅ Dashboard components
- ✅ Activity tracking

All components are production-ready and follow best practices for maintainability and scalability.