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:

<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:

<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:

<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:

<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:

<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:

<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:

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

SettingsSection

Component for settings pages.

Usage:

<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:

<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:

<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

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.